TINE Data Access and Flags

Below is a list of the available data access flags

A TINE data request is accompanied by an access code. At the client-side, the request might be made by specifying any combination of CA_READ access and CA_WRITE access. Note that by default, any data exchange will automatically carry the CA_READ access bit. TINE servers are also open to CA_READ access from any client on the network. Data requests specifying CA_WRITE access must pass through the TINE security mechanism (see the discussion concerning users.csv, ipnets.csv, and ipxnets.csv). It is generally suggested that those data-exchange requests which involve commands to change hardware settings or otherwise directly access front-end hardware always require CA_WRITE access. The server equipment module can then examine the access code in the data request. At the server-side, the following access bits can be checked against the data access list shown below.

The scope bits CA_FIRST and CA_LAST can be quite useful, as the initial data access for a particular contract (which is being polled) might trigger some activity which is not needed in subsequent requests. Likewise, the final data request (when the contract is being canceled) might also be used to terminate related background activities. Of course, single commands will always carry both the CA_FIRST and the CA_LAST bits, as the request is merely transient and is coming into scope and going out of scope at the same time.

The access bit CA_CONNECT is entirely analogous to the transfer mode bit CM_CONNECT (please see the discussion there). It is offered as an access bit in the case of synchronous calls using ExecLink(), in which case there is no possibility to otherwise modify the transfer mode (de-facto CM_SINGLE).

List of data acquisition access flags

• CA_NULL
  • Used internally
• CA_READ
  • The call is requesting read access.
  • This access flag will be applied by default.
  • visible to both client and server
• CA_WRITE
  • The call is requesting write access. Calls which change settings should always request write access and servers which accept such requests should always demand that write access is applied to the call before allowing a setting to be changed.
  • Write access is always checked against a server's allowed users list (users.csv) and against a server's allowed networks list (ipnets.csv and/or ipxnets.csv). If no users.csv file exists, then all users have write access. If no ipnets.csv file exists, the all ip addresses and subnets have write access.
  • visible to both client and server
• CA_XREAD
  • At server property registration, applying this access flag instructs the server to apply exclusive READ logic to the designated property when it is accessed. If used in conjunction with CA_READ then an exclusive read will be enforced whenever an ACCESSLOCK is in play. If used by itself (without CA_READ) then an exclusive READ is always in effect when the property is accessed. This means that the server's access lists are consulted (as if the call were a WRITE access) in order to determine it the call can be forwarded to the property's dispatch routine.
  • visible to server only during property registration.
• CA_REPEAT
  • Set by the server prior to calling the equipment module.
  • The call was previously instructed to retry the link via the return code not_ready.
  • visible to server only
• CA_SYNC
  • Set by the server prior to calling the equipment module.
  • The call is being made on behalf of a non-peristent synchronous data link.
  • visible to server only
• CA_ALARM
  • Set by the server prior to calling the equipment module.
  • The call is being made on behalf of the local alarm server (due to the Alarm Watch Table).
  • visible to server only
• CA_HIST
  • Set by the server prior to calling the equipment module.
  • The call is being made on behalf of the local history server.
  • visible to server only
• CA_FIRST
  • Set by the server prior to calling the equipment module.
  • The call is coming into scope. For instance a persistent data link for a particular contract has just been established.
  • visible to server only
• CA_LAST
  • Set by the server prior to calling the equipment module.
  • The call is going out of scope. For instance a persistent data link for a particular contract has just been canceled.
  • Synchronous calls will set the CA_FIRST bit along with the CA_LAST bit as well as the CA_SYNC bit.
  • visible to server only
• CA_RETRY
  • Used in conjunction with access mode CM_SINGLE only. It instructs the subsystem to retry the data acquistion in case of connection timeout or link error.
  • visible to client only
• CA_NETWORK
  • At server property registration, applying this access flag instructs the server to enforce 'network' access to the designated property. This means that any attempt to access the propery's data asynchronously will (after a bit of handshaking) be converted to a network (i.e. multicast) access. This can be an extremely useful attribute regarding 'popular' properties with large payloads.
  • visible to server only during property registration.
• CA_QUERY
  • Is set prior to calling an equipment module if the call is a query call coming from the TINE kernel.
  • visible to server only
• CA_LOCKED
  • This access bit is set if a client has an access lock token on the server and issues a WRITE request (command). The equipment module can check to see if this bit set when processing a WRITE command and (for instance) refuse the command if there is no access lock token.
  • visible to server only
• CA_NORETRY
  • Applies only to client side calls and instructs the subsystem not to re-issue the link upon timeout error, regardless of the 'gAlwaysRetry' setting.
  • visible to client only
• CA_CONNECT
  • Has the same effect as the mode flag CM_CONNECT. Is useful for API interfaces such as ExecLinkEx() which does not take a 'mode' parameter.
  • visible to client only
• CA_STREAM
  • Has the same effect as the mode flag CM_STREAM. Is useful for API interfaces such as ExecLinkEx() which does not take a 'mode' parameter.
  • visible to client only

  • Note:

    Formally this is the same bit value as CA_LOCK (which is visible on at the server)

• CA_MUTABLE
  • Applies only to synchronous calls ExecLink() or ExecLinkEx(). This allows the subsystem to adjust the output data object to account for the amount of data actually returned by the server. This is the only thread-safe way of obtaining this information with a sychronous call. Note that calling GetCompletionDataSize(-1) is not thread-safe.
  • visible to client only
• CA_SAVERESTORE
  • At server property registration, applying this access flag instructs the server to flag the designated property as a 'save-and-restore' property. Thus upon initialization the property's previous settings (for all devices) will be sent to the property's dispatch handler (restored). Likewise any successful change of the property's value for any device will be saved to a file on the local disk.

    Note:

    Only 'attribute' style properties can participate in this systematic save-and-restore. This includes only those properties whose WRITE and READ data types are the same and whose registered data size is either 1 for both READ and WRITE or if the property is a registered multi-channel array. Currently only 'simple' data types are allowed.

  • visible to server only during property registration.
• CA_SYNCNOTIFY
  • Has the same effect as the mode flag CM_SYNCNOTIFY.
  • visible to client only