TINE Client-side API Routines. More...
Functions | |
| int | AttachLink (const char *devName, const char *devProperty, DTYPE *dout, DTYPE *din, short access, int pollingRate, void(*cbFcn)(int, int), int mode) |
| Initiates an asynchronous link. More... | |
| int | AttachLinkEx (const char *devName, const char *devProperty, DTYPE *dout, DTYPE *din, short access, int pollingRate, void(*cbFcn)(int, int), int mode, UINT32 cbId) |
| Initiates an asynchronous link. More... | |
| int | AttachLinkEx2 (const char *devName, const char *devProperty, DTYPE *dout, DTYPE *din, short access, int pollingRate, void(*cbFcn)(int, int, void *), int mode, UINT32 cbId, void *reference) |
| Initiates an asynchronous link. More... | |
| int | CloseGlobalLink (int linkId) |
| Closes an active globals data link. More... | |
| int | CloseLink (int linkId) |
| Cancels an active data link. More... | |
| int | CloseNetGlobal (const char *keyword) |
| Closes an active globals data link according to the globals Keyword. More... | |
| int | ExecLink (const char *devName, const char *devProperty, DTYPE *dout, DTYPE *din, short access) |
| Executes a synchronous link. More... | |
| int | ExecLinkEx (const char *devName, const char *devProperty, DTYPE *dout, DTYPE *din, short access, UINT16 timeout) |
| Executes a synchronous link (Extended call). More... | |
| int | FreeAccessLock (char *context, char *server) |
| Frees an access lock on the server specified. More... | |
| int | GetAccessLockInformation (char *context, char *server, NAME32 *callerName, NAME32 *callerIp, NAME32 *timeLeft) |
| Acquires access lock information from the server specified. More... | |
| int | GetAccessLockStatus (char *context, char *server) |
| Acquires the current access lock status on a client's access lock. More... | |
| int | GetAllowDependentLinks (void) |
| returns the setting for this value More... | |
| int | GetAlwaysRetry (void) |
| Gets the current setting of the 'Always Retry' flag. More... | |
| int | GetAutoLinkErrorAlarms (void) |
| Gets the current setting of the autoLinkErrorAlarms flag. More... | |
| GrpTblEntry * | GetCallbackGroup (size_t id) |
| Returns a reference to the callback Group Table Entry associated with the identifier supplied. More... | |
| int | GetClnRecvQueueDepth (void) |
| Gets the default client-side receive queue depth for all client links. More... | |
| int | GetCompletionDataSize (int i) |
| Returns the most recent data size of the link index supplied. More... | |
| int | GetCompletionDataSizeFromCallbackId (int id) |
| Returns the most recent data size of the link associated with the callback id supplied. More... | |
| int | GetCompletionDataType (int i) |
| Returns the most recent data type of the link index supplied. More... | |
| int | GetCompletionDataTypeFromCallbackId (int id) |
| Returns the most recent data type of the link associated with the callback id supplied. More... | |
| short | GetCompletionSource (int i) |
| Returns the error source associated with the input link index. More... | |
| short | GetCompletionSourceFromCallbackId (int id) |
| Returns the error source associated with the callback identifier supplied. More... | |
| char * | GetCompletionStatus (int i) |
| Returns the error string associated with the input link index. More... | |
| char * | GetCompletionStatusFromCallbackId (int id) |
| Returns the error string associated with the callback identifier supplied. More... | |
| int | GetConnectionList (char *lstbuf, int bufsize) |
| Gets the current connection table. More... | |
| int | GetConnectionTable (ConTblInfo *tbl, int *tblSize) |
| Gets the current connection table. More... | |
| int | GetConnectionTableCapacity (void) |
| Gets the maximum number of entries allowed in the connection table. More... | |
| int | GetCurrentDataStatus (int i) |
| Returns the data status code associated with the input link index. More... | |
| int | GetCurrentDataStatusFromCallbackId (int id) |
| Returns the data status code associated with the callback identifier supplied. More... | |
| double | GetCurrentDataTimeStamp (int i) |
| Returns the data timestamp associated with the input link index. More... | |
| double | GetCurrentDataTimeStampFromCallbackId (int id) |
| Returns the data timestamp associated with the callback identifier supplied. More... | |
| int | GetCurrentLinkStatus (int i) |
| Returns the completion code associated with the input link index. More... | |
| int | GetCurrentLinkStatusFromCallbackId (int id) |
| Returns the completion code associated with the callback identifier supplied. More... | |
| int | GetDataFromCallbackId (int id, DTYPE *dout, UINT16 *status) |
| Supplies the DTYPE data object and call status for the callback ID in question. More... | |
| int | GetDataFromLinkId (int linkId, DTYPE *dout, UINT16 *status) |
| Supplies the DTYPE data object and call status for the link ID in question. More... | |
| int | GetDataStamp (int linkId) |
| Gets the data stamp with which the incoming data set has been tagged. More... | |
| int | GetDataStampFromCallbackId (int id) |
| Gets the global system data stamp with which the incoming data set has been tagged. More... | |
| int | GetDefaultTransportMode (void) |
| Gets the default TINE transport mode used in client-side links. More... | |
| int | GetGlobalDataType (int id) |
| Returns the data type of global link index supplied. More... | |
| int | GetGlobalDataTypeFromCallbackId (int id) |
| Returns the data type of global link callback id supplied. More... | |
| int | GetGlobalLinkId (char *keyword) |
| retrieves the link ID for a globals link More... | |
| int | GetGlobalLinkIdFromCallbackId (int cbId) |
| retrieves the link ID for a globals link More... | |
| int | GetGlobalsDataStamp (int glbId) |
| Gets the data stamp with which the incoming globals data set has been tagged. More... | |
| int | GetGlobalsHeartbeat (void) |
| gets the heartbeat (in seconds) during which time no 'timeout' messages will be sent to a globals dispatch routine (client-side) More... | |
| int | GetGlobalsSystemStamp (int glbId) |
| Gets the system data stamp with which the incoming globals data set has been tagged. More... | |
| int | GetGlobalsTableCapacity (void) |
| gets the globals table capacity (client-side) More... | |
| double | GetGlobalsTimeStamp (int linkId) |
| Returns the timestamp of the globals keyword with the given link ID. More... | |
| double | GetGlobalsTimeStampFromCallbackId (int id) |
| Returns the timestamp of the globals keyword with the given link callback ID. More... | |
| GrpMember * | GetGroupMemberList (GrpTblEntry *grp) |
| Returns a linked list of the group members for the callback group supplied. More... | |
| int | GetLastGlobalDataSize (int id) |
| Returns the most recent data size of the global link index supplied. More... | |
| int | GetLastGlobalDataSizeFromCallbackId (int id) |
| Returns the most recent data size of the global link callback id supplied. More... | |
| char * | GetLastLinkError (short cc, char *errstr) |
| The error string associated with the input error number. More... | |
| int | GetLinkCallbackDelay (int linkId) |
| Gets the client-side callback notification. More... | |
| void * | GetLinkCallbackReference (int id) |
| Returns the supplied callback reference for the link ID in question. More... | |
| char * | GetLinkName (int i) |
| Returns the full link name associated with the input link index. More... | |
| char * | GetLinkNameFromCallbackId (int id) |
| Returns the full link name associated with the callback identifier supplied. More... | |
| int | getLinkOutputStatus (int lnkId, char *strSts, int maxKeyLength, int splitlines) |
| int | GetLinkQueueDepth (int linkId) |
| Gets the client-side receive queue depth for the link in question. More... | |
| int | GetSubscriptionRenewalThreshold (int linkId, int *thresholdInPercent) |
| Gets the current client-side subscription threshold for the link in question. More... | |
| int | GetSuspendCallbacks (void) |
| returns the suspends asynchronous callback notification setting More... | |
| double | GetSynchronizationTolerance (void) |
| Gets the tolerance used in deciding whether to apply a timestamp offset or not. More... | |
| int | GetSystemDataStamp (int linkId) |
| Gets the system data stamp with which the incoming data set has been tagged. More... | |
| int | GetSystemDataStampFromCallbackId (int id) |
| Gets the system data stamp with which the incoming data set has been tagged. More... | |
| int | GetSystemStampDelay (void) |
| Returns the registered system cycle delay. More... | |
| int | GetSystemStampOffset (void) |
| Returns the registered system cycle offset. More... | |
| UINT16 | GetTransferFlag (int linkId) |
| Gets the data transfer flag for the given link ID. More... | |
| UINT16 | GetTransferFlagFromCallbackId (int id) |
| Gets the data transfer flag for the give callback identifier. More... | |
| int | ModifyLinkAttributes (int i, short access, int pollingRate, void(*cbFcn)(int, int), int mode, UINT32 cbId) |
| Allows the caller to assign new link attributes to an active link. More... | |
| int | PutLnkErrorValue (int i, void *errValue) |
| Flags a link so that the given error value is used as the data value in case of any link error. More... | |
| int | PutLnkTimeStamp (int i) |
| Flags a link so that the local timestamp is used for all incoming data sets. More... | |
| int | ReassignLinkData (int id, void *buffer, UINT32 length) |
| Reassigns the bound data buffer for the link table id given. More... | |
| int | recvNetGlobal (const char *keyword, DTYPE *dout, void(*cbFcn)(int, int)) |
| Initiates a net globals data link. More... | |
| int | recvNetGlobalEx (const char *keyword, DTYPE *dout, void(*cbFcn)(int, int), UINT32 cbId) |
| Initiates a net globals data link (extended call). More... | |
| int | recvNetGlobalEx2 (const char *keyword, DTYPE *dout, void(*cbFcn)(int, int, void *), UINT32 cbId, void *reference) |
| Initiates a net globals data link (doubly extended call). More... | |
| int | RegisterCycleTriggerFunction (CYCBFCNP fcn, char *eqm, char *prpLst, void *reference) |
| Registers a cycle trigger callback dispatch function. More... | |
| void | ResetSuspendCallbacks (void) |
| stops suspending callbacks and resets the reference counter More... | |
| int | ResubmitDataLink (int id) |
| Resubmits a (CM_SINGLE) data link. More... | |
| int | SetAccessLock (char *context, char *server, int lockType, int lockDuration) |
| Acquires an access lock to the server specified. More... | |
| void | SetAllowDependentLinks (int value) |
| turns the ability to manage identical (dependent) links ON or OFF More... | |
| void | SetAlwaysRetry (int value) |
| Sets the 'Always Retry' flag to the value given. More... | |
| void | SetAutoLinkErrorAlarms (int value) |
| Sets the autoLinkErrorAlarms flag. More... | |
| void | SetAutoLinkWatchdogs (int value) |
| Enables/Disables automatic link watchdogs. More... | |
| void | SetClnRecvQueueDepth (int depth) |
| Sets the default client-side receive queue depth for all client links. More... | |
| int | SetConnectionTableCapacity (int value) |
| Sets the maximum number of entries in the connection table. More... | |
| void | SetDefaultTransportMode (int value) |
| Sets the default TINE transport mode used in client-side links. More... | |
| void | SetGlobalsHeartbeat (int value) |
| sets the heartbeat (in seconds) during which time no 'timeout' messages will be sent to a globals dispatch routine (client-side) More... | |
| void | SetGlobalsTableCapacity (int value) |
| sets the globals table capacity More... | |
| void | SetLinkCallbackDelay (int linkId, int cyclesToDelay) |
| Sets a client-side callback notification. More... | |
| void | SetLinkQueueDepth (int linkId, int depth) |
| Sets the client-side receive queue depth for the link in question. More... | |
| int | SetLinkWatchdogPollingInterval (int value) |
| Sets the link watchdog polling interval to the value given. More... | |
| int | SetNotificationTolerance (int linkId, float toleranceAbsolute, float tolerancePercent) |
| Allows the caller to apply a tolerance pertaining to link notification. More... | |
| int | SetNotificationToleranceEx (int linkId, float toleranceAbsolute, float tolerancePercent, int offset, int length, int flags) |
| Allows the caller to apply a tolerance pertaining to link notification (extended call). More... | |
| int | SetSubscriptionRenewalThreshold (int linkId, int thresholdInPercent) |
| Gets the current client-side subscription threshold for the link in question. More... | |
| void | SetSuppressHeartbeatNotification (int value) |
| Determines whether CM_DATACHANGE data links signal incoming data by calling the corresonding callback routine even when the incoming data is a HEARTBEAT notification. More... | |
| void | SetSuspendCallbacks (int value) |
| set suspends asynchronous callback notification ON or OFF More... | |
| void | SetSynchronizationTolerance (double toleranceInSeconds) |
| Sets the tolerance used in deciding whether to apply a timestamp offset or not. More... | |
| void | SetSystemStampDelay (int cycleDelay) |
| Establishes the system cycle delay. More... | |
| void | SetSystemStampOffset (int cycleOffset) |
| Establishes a system cycle offset. More... | |
| int | UnregisterCycleTriggerFunction (CYCBFCNP fcn, void *reference) |
| Unregisters a previously registered cycle trigger callback dispatch function. More... | |
| int | UpdateDataStampsFromCallbackId (int id, DTYPE *dout) |
| Fills in the given DTYPE data object with all data stamp information. More... | |
| int | UpdateDataStampsFromLinkId (int linkId, DTYPE *dout) |
| Fills in the given DTYPE data object with all data stamp information. More... | |
Variables | |
| int | gConTblCapacity = CONTBL_CAPACITY |
| Determines the maximum number of entries in the connection table. More... | |
| UINT32 | LastCompletionDataSize = 0 |
| Supplies the data size of the most recent link. More... | |
| int | LastCompletionDataType = CF_NULL |
| Supplies the data type of the most recent link. More... | |
| short | lastLnkErrSrc = 0 |
| Gives the signature of the last Link Error. More... | |
TINE Client-side API Routines.
Below are the principal client-side API routines which allow the user to obtain data from elements in the control system. Data acquistion can either be synchronous (e.g. ExecLink()) where execution is blocked until a call completes, or asynchronous (e.g. AttachLink()) where the results of a call are given to a callback routine upon completion. Data can also be 'monitored' asynchronously either at a supplied polling rate or upon data change.
| int AttachLink | ( | const char * | devName, |
| const char * | devProperty, | ||
| DTYPE * | dout, | ||
| DTYPE * | din, | ||
| short | access, | ||
| int | pollingRate, | ||
| void(*)(int, int) | callback, | ||
| int | mode | ||
| ) |
Initiates an asynchronous link.
Asynchronous data exchange. AttachLink() returns immediately with a positive link index if the device name can be resolved and there are sufficient resources on the client side. Otherwise, a call to AttachLink() returns a negative completion code which can be interpreted with GetLastLinkError().
AttachLink() differs from AttachLinkEx() in that the callback will always return the link identifier as the callback id parameter in the callback routine.
| devName | is the full device name (/<Context>/<Server>/<Device>) of the device to contact. For example: "/HERA/BPM/WL167". Note that, if devName references a locally registered equipment module, an internal call to ExecLocalLink() is made. For instance: "/LOCAL/BPMEQM/WL167" sets the context to "LOCAL", and "BPMEQM" must be a locally registered equipment module. In such a case, the call can only be successful when the client and server are running together in the same process). |
| devProperty | is the device property requested, for example "ORBIT.X" |
| dout | is a pointer to the output data set, that is, the data set to be returned from the server to the client. The structure element ‘dout->data’ should be a pointer to a pre-allocated data buffer, which is to receive the returned data. If dout is a NULL pointer, it is assumed that no data are to be returned. |
| din | is a pointer to the input data set, that is, the data set to be sent to the server from the client. If din is a NULL pointer, it is assumed that no data are to be sent to the server Note that the input data set is used to specify the contract! This means that the data values (in addition to the data array length and data format) will be cached at the server side in the case of persistent links with input data. |
| access | is the data access mode. This can be any of the TINE access codes ORed together (CA_READ, CA_WRITE, etc.) |
| pollingRate | is the polling rate in milliseconds as seen at the server. For SINGLE transfers, this value also serves as a timeout parameter. |
| callback | is the address of the user-supplied callback routine to be called when data arrive from the server. The prototype of this routine must be as shown, where the first argument (id) gives the id of the link which is calling the callback, and the second argument (cc) gives the completion code. For successful data transmission, cc will always be 0, otherwise it can be interpreted with GetLastLinkError(). |
| mode | is the transfer mode (see discussion on Data Transfer Modes). |
Example:
| int AttachLinkEx | ( | const char * | devName, |
| const char * | devProperty, | ||
| DTYPE * | dout, | ||
| DTYPE * | din, | ||
| short | access, | ||
| int | pollingRate, | ||
| void(*)(int, int) | callback, | ||
| int | mode, | ||
| UINT32 | callbackID | ||
| ) |
Initiates an asynchronous link.
Asynchronous data exchange. AttachLinkEx() returns immediately with a positive link index if the device name can be resolved and there are sufficient resources on the client side. Otherwise, a call to AttachLinkEx() returns a negative completion code which can be interpreted with GetLastLinkError().
AttachLinkEx() differs from AttachLink() in that the caller can supply a callback identifier to be returned in the callback function. In lieu of this, the callback will return the link identifier.
| devName | is the full device name (/<Context>/<Server>/<Device>) of the device to contact. For example: "/HERA/BPM/WL167". Note that, if devName references a locally registered equipment module, an internal call to ExecLocalLink() is made. For instance: "/LOCAL/BPMEQM/WL167" sets the context to "LOCAL", and "BPMEQM" must be a locally registered equipment module. In such a case, the call can only be successful when the client and server are running together in the same process). |
| devProperty | is the device property requested, for example "ORBIT.X" |
| dout | is a pointer to the output data set, that is, the data set to be returned from the server to the client. The structure element ‘dout->data’ should be a pointer to a pre-allocated data buffer, which is to receive the returned data. If dout is a NULL pointer, it is assumed that no data are to be returned. |
| din | is a pointer to the input data set, that is, the data set to be sent to the server from the client. If din is a NULL pointer, it is assumed that no data are to be sent to the server Note that the input data set is used to specify the contract! This means that the data values (in addition to the data array length and data format) will be cached at the server side in the case of persistent links with input data. |
| access | is the data access mode. This can be any of the TINE access codes ORed together (CA_READ, CA_WRITE, etc.). |
| pollingRate | is the polling rate in milliseconds as seen at the server. For SINGLE transfers, this value also serves as a timeout parameter. |
| callback | is the address of the user-supplied callback routine to be called when data arrive from the server. The prototype of this routine must be as shown, where the first argument (id) gives the id of the link which is calling the callback, and the second argument (cc) gives the completion code. For successful data transmission, cc will always be 0, otherwise it can be interpreted with GetLastLinkError(). |
| mode | is the transfer mode (see discussion on Data Transfer Modes). |
| callbackID | is supplied by the caller as an identifier to be returned in the callback function. Pass UNASSIGNED_CALLBACKID in order to receive the link ID in the supplied callback function. |
Example:
| int AttachLinkEx2 | ( | const char * | devName, |
| const char * | devProperty, | ||
| DTYPE * | dout, | ||
| DTYPE * | din, | ||
| short | access, | ||
| int | pollingRate, | ||
| void(*)(int, int, void *) | callback, | ||
| int | mode, | ||
| UINT32 | callbackID, | ||
| void * | reference | ||
| ) |
Initiates an asynchronous link.
Asynchronous data exchange. AttachLinkEx2() returns immediately with a positive link index if the device name can be resolved and there are sufficient resources on the client side. Otherwise, a call to AttachLinkEx() returns a negative completion code which can be interpreted with GetLastLinkError().
AttachLinkEx2() differs from AttachLinkEx() and AttachLink() in that the caller can supply a callback identifier and a reference pointer to be returned in the callback function.
| devName | is the full device name (/<Context>/<Server>/<Device>) of the device to contact. For example: "/HERA/BPM/WL167". Note that, if devName references a locally registered equipment module, an internal call to ExecLocalLink() is made. For instance: "/LOCAL/BPMEQM/WL167" sets the context to "LOCAL", and "BPMEQM" must be a locally registered equipment module. In such a case, the call can only be successful when the client and server are running together in the same process). |
| devProperty | is the device property requested, for example "ORBIT.X" |
| dout | is a pointer to the output data set, that is, the data set to be returned from the server to the client. The structure element ‘dout->data’ should be a pointer to a pre-allocated data buffer, which is to receive the returned data. If dout is a NULL pointer, it is assumed that no data are to be returned. |
| din | is a pointer to the input data set, that is, the data set to be sent to the server from the client. If din is a NULL pointer, it is assumed that no data are to be sent to the server Note that the input data set is used to specify the contract! This means that the data values (in addition to the data array length and data format) will be cached at the server side in the case of persistent links with input data. |
| access | is the data access mode. This can be any of the TINE access codes ORed together (CA_READ, CA_WRITE, etc.). |
| pollingRate | is the polling rate in milliseconds as seen at the server. For SINGLE transfers, this value also serves as a timeout parameter. |
| callback | is the address of the user-supplied callback routine to be called when data arrive from the server. The prototype of this routine must be as shown, where the first argument (id) gives the id of the link which is calling the callback, the second argument (cc) gives the completion code, and the third argument is the user supplied reference pointer. For successful data transmission, cc will always be 0, otherwise it can be interpreted with GetLastLinkError(). |
| mode | is the transfer mode (see discussion on Data Transfer Modes). |
| callbackID | is supplied by the caller as an identifier to be returned in the callback function. Pass UNASSIGNED_CALLBACKID in order to receive the link ID in the supplied callback function. |
| reference | is a user-supplied pointer which will be returned in the callback routine. This can be a very useful means for de-referencing the callback. |
Example:
| int CloseGlobalLink | ( | int | linkId | ) |
Closes an active globals data link.
Use this call to close an active data link. Note that the parameter passed must be the returned link id when the original call to recvNetGlobal() was made. If the call is successful, and the link is the last globals link on a context's multicast group, the application will detach from the group.
| linkId | the globals link index to be canceled |
| int CloseLink | ( | int | i | ) |
Cancels an active data link.
Use this call to cancel an active data link (alias: CloseLink()). Note that the parameter passed must be the returned link id when the original call to AttachLink() or AttachLinkEx() was made.
| i | the link index to be canceled |
Example:
| int CloseNetGlobal | ( | const char * | keyword | ) |
Closes an active globals data link according to the globals Keyword.
Use this call to close an active data link. If the call is successful, and the link is the last globals link on a context's multicast group, the application will detach from the group.
| keyword | the globals keyword used to establish the link. |
| int ExecLink | ( | const char * | devName, |
| const char * | devProperty, | ||
| DTYPE * | dout, | ||
| DTYPE * | din, | ||
| short | access | ||
| ) |
Executes a synchronous link.
Synchronous data exchange. ExecLink() does not complete until the data transfer has completed or a timeout has ensued. ExecLink() differs from ExecLinkEx() in that the default timeout of 1000 msec is assumed
| devName | is the full device name (/<Context>/<Server>/<Device>) of the device to contact. For example: "/HERA/BPM/WL167". Note that, if devName references a locally registered equipment module, an internal call to ExecLocalLink() is made. For instance: "/LOCAL/BPMEQM/WL167" sets the context to "LOCAL", and "BPMEQM" must be a locally registered equipment module. In such a case, the call can only be successful when the client and server are running together in the same process). |
| devProperty | is the device property requested, for example "ORBIT.X" |
| dout | is a pointer to the output data set, that is, the data set to be returned from the server to the client. The structure element ‘dout->data’ should be a pointer to a pre-allocated data buffer, which is to receive the returned data. If dout is a NULL pointer, it is assumed that no data are to be returned. |
| din | is a pointer to the input data set, that is, the data set to be sent to the server from the client. If din is a NULL pointer, it is assumed that no data are to be sent to the server |
| access | is the data access mode. This can be any set of access codes ORed together (CA_READ, CA_WRITE, CA_CONNECT, etc.) |
Example:
| int ExecLinkEx | ( | const char * | devName, |
| const char * | devProperty, | ||
| DTYPE * | dout, | ||
| DTYPE * | din, | ||
| short | access, | ||
| UINT16 | timeout | ||
| ) |
Executes a synchronous link (Extended call).
Synchronous data exchange. ExecLinkEx() does not complete until the data transfer has completed or a timeout has ensued. ExecLinkEx() differs from ExecLink() in that the user may specify a timeout period for the call to complete.
| devName | is the full device name (/<Context>/<Server>/<Device>) of the device to contact. For example: "/HERA/BPM/WL167". Note that, if devName references a locally registered equipment module, an internal call to ExecLocalLink() is made. For instance: "/LOCAL/BPMEQM/WL167" sets the context to "LOCAL", and "BPMEQM" must be a locally registered equipment module. In such a case, the call can only be successful when the client and server are running together in the same process). |
| devProperty | is the device property requested, for example "ORBIT.X" |
| dout | is a pointer to the output data set, that is, the data set to be returned from the server to the client. The structure element ‘dout->data’ should be a pointer to a pre-allocated data buffer, which is to receive the returned data. If dout is a NULL pointer, it is assumed that no data are to be returned. |
| din | is a pointer to the input data set, that is, the data set to be sent to the server from the client. If din is a NULL pointer, it is assumed that no data are to be sent to the server |
| access | is the data access mode. This can be any combination of access codes ORed together (CA_READ, CA_WRITE, CA_CONNECT, etc.). |
| timeout | the timeout period in milliseconds for the call to complete. When it is known a priori that a call takes a long time to complete than you can set this value accordingly. ExecLink() makes a call to ExecLinkEx() with the timeout parameter set to 1000 msec. Note that by default, a 'retry' will automatically be attempted in case the call does not complete in the time specified. This 'retry' can add significantly to the total call completion time. For instance if the target is simply not running, the call will take approximately two times the timeout specified (plus an additional 100 msec) before returning. If this behavior is NOT desired, then the 'access' parameter should be ORed with the CA_NORETRY flag. Also note that lossy networks can easily lead to packet loss in the case of a (default) UDP transaction. In a similar sense, a busy server might also cause a TCP transaction to fail to complete within the time specified. |
Example:
References argument_list_error.
Referenced by FindServerOnNetwork(), GetAccessLockInformation(), GetDeviceProperties(), GetDevicePropertyEGU(), GetDevicePropertyInformation(), GetSystemPropertiesEx(), and GetSystemPropertyInformation().
| int FreeAccessLock | ( | char * | context, |
| char * | server | ||
| ) |
Frees an access lock on the server specified.
A client application can obtain an access lock to the given server provided the caller has WRITE privilileges himself. Once the lock is obtained, no other process will be allowed WRITE access regardless of any other access control lists. A lock may be preemptive (LOCK_PREEMTIVE) or persistent (LOCK_PERSISTENT). Preemptive locks may be aborted (LOCK_ABORT) by other callers with WRITE privilileges. Persistent locks may not. A Client API Callsan free a lock he has obtained by calling this method (nominally equivalent to SetAccessLock() + LOCK_CANCEL.
| context | is the targeted context of the server |
| server | is the targeted device server |
Example:
References invalid_parameter.
| int GetAccessLockInformation | ( | char * | context, |
| char * | server, | ||
| NAME32 * | callerName, | ||
| NAME32 * | callerIp, | ||
| NAME32 * | timeLeft | ||
| ) |
Acquires access lock information from the server specified.
A client application can obtain an access lock to the given server provided the caller has WRITE privilileges himself. Once the lock is obtained, no other process will be allowed WRITE access regardless of any other access control lists. A lock may be preemptive (LOCK_PREEMTIVE) or persistent (LOCK_PERSISTENT). Preemptive locks may be aborted (LOCK_ABORT) by other callers with WRITE privilileges. Persistent locks may not. A Client API Callsan obtain the current access lock information via this call. This will provide information as to the caller's user name, network address, and time remaining. If there is no access lock on the server specified, then the caller's name will be empty, the network address will be "0.0.0.0" and the time remaining will be "0 seconds remaining".
| context | is the targeted context of the server |
| server | is the targeted device server |
| callerName | is a NAME32 object to hold the user name of the holder of the access lock. |
| callerIp | is a NAME32 object to hold the network address of the holder of the access lock. |
| timeLeft | is a NAME32 object to hold a string given the seconds remaining on the access lock. |
Example:
References DTYPE::dArrayLength, DTYPE::data, DTYPE::dFormat, ExecLinkEx(), invalid_parameter, NAME32::name, and DUNION::vptr.
| int GetAccessLockStatus | ( | char * | context, |
| char * | server | ||
| ) |
Acquires the current access lock status on a client's access lock.
A client application can obtain an access lock to the given server provided the caller has WRITE privilileges himself. Once the lock is obtained, no other process will be allowed WRITE access regardless of any other access control lists. A lock may be preemptive (LOCK_PREEMTIVE) or persistent (LOCK_PERSISTENT). Preemptive locks may be aborted (LOCK_ABORT) by other callers with WRITE privilileges. Persistent locks may not. A Client API Callsan of course hold different access locks to different servers, and can obtain the current lock status for any of them by using this function.
| context | is the targeted context of the server |
| server | is the targeted device server |
References invalid_parameter.
| int GetAllowDependentLinks | ( | void | ) |
returns the setting for this value
When set to TRUE, attempts to establish (multiply) identical links to the same target are allowed. In this case the original link is desigated the 'parent link' and constitutes the actual link (client to server). Other client-side links to the same target (have the same contract) will then obtain their results from the parent link.
| int GetAlwaysRetry | ( | void | ) |
Gets the current setting of the 'Always Retry' flag.
Client Links can be instructed to always apply the CA_RETRY flag upon initialization by setting this flag to TRUE. If TRUE all link timeouts will be retried up to three times before issuing a link timeout notification. The default value is TRUE.
| int GetAutoLinkErrorAlarms | ( | void | ) |
Gets the current setting of the autoLinkErrorAlarms flag.
A server can set automatic 'link_error' alarms when a link to another server goes down. This call retrieves the current value of this setting, (default = TRUE).
| GrpTblEntry * GetCallbackGroup | ( | size_t | id | ) |
Returns a reference to the callback Group Table Entry associated with the identifier supplied.
| id | is the group callback id (effectively the reference pointer to the callback function associated with the group. |
| int GetClnRecvQueueDepth | ( | void | ) |
Gets the default client-side receive queue depth for all client links.
Asynchronous data acquisition implies a callback handler which accepts and processes incoming data. Under most circumstances the callback handler should process the incoming data quickly and return prior to the next data acquisition (otherwise the data rate is set too high to be useful for the client). However circumstances arrive where either bursts of data arrive or the client side is otherwise busy processing an atypical event, etc. In these cases queueing the incoming data can be beneficial. You can get the default queue depth for initializing links with this routine.
| int GetCompletionDataSize | ( | int | i | ) |
Returns the most recent data size of the link index supplied.
| i | is the link index for which the completed data size is desired |
Example:
References LastCompletionDataSize.
| int GetCompletionDataSizeFromCallbackId | ( | int | id | ) |
Returns the most recent data size of the link associated with the callback id supplied.
| id | is the callback id of the link for which the completed data size is desired |
Example:
| int GetCompletionDataType | ( | int | i | ) |
Returns the most recent data type of the link index supplied.
| i | is the link index for which the data type is desired |
Example:
| int GetCompletionDataTypeFromCallbackId | ( | int | id | ) |
Returns the most recent data type of the link associated with the callback id supplied.
| id | is the callback id of the link for which the completed data type is desired |
Example:
| short GetCompletionSource | ( | int | i | ) |
Returns the error source associated with the input link index.
| i | is the link index of the link for which the current status string is desired. |
References lastLnkErrSrc.
| short GetCompletionSourceFromCallbackId | ( | int | id | ) |
Returns the error source associated with the callback identifier supplied.
| id | is the callback id of the link for which the current status string is desired. |
| char* GetCompletionStatus | ( | int | i | ) |
Returns the error string associated with the input link index.
| i | is the link index of the link for which the current status string is desired. |
Example:
| char* GetCompletionStatusFromCallbackId | ( | int | id | ) |
Returns the error string associated with the callback identifier supplied.
| id | is the callback id of the link for which the current status string is desired. |
Example:
| int GetConnectionList | ( | char * | lstbuf, |
| int | bufsize | ||
| ) |
Gets the current connection table.
A client's connections are managed and maintained in a connection table. You can retrieve the current connection table by using this call
| lstbuf | is a reference to a string buffer which will hold the connection table list |
| bufsize | gives the size in bytes of the string buffer passed in the first argument. |
References argument_list_error, and buffer_too_small.
| int GetConnectionTable | ( | ConTblInfo * | tbl, |
| int * | tblSize | ||
| ) |
Gets the current connection table.
A client's connections are managed and maintained in a connection table. You can retrieve the current connection table by using this call
| tbl | is a reference to block of memory which will hold the ConTblInfo array giving the current Client API Callsonnection table. |
| tblSize | (input) is a pointer to an integer value containing the maximum size (number of entries) the the tbl reference can hold. (output) will contain the size of the current connection table. |
References argument_list_error.
| int GetConnectionTableCapacity | ( | void | ) |
Gets the maximum number of entries allowed in the connection table.
A client's connections are managed and maintained in a connection table. The size of this table is pre-allocated at initialization time. This allows for fast lookups, since a connection ID is simply an entry into the table. If it is known that the client will need a large number of simultaneous links then this value should be set accordingly at initialization time.
References gConTblCapacity.
| int GetCurrentDataStatus | ( | int | i | ) |
Returns the data status code associated with the input link index.
If the remote equipment module is called, this is the return code delivered. If the link returns or notifies the caller and the equipment module has not been called (e.g. in case of time out) this value will be 'not posted'.
| i | is the link index of the link for which the current completion code is desired. |
| int GetCurrentDataStatusFromCallbackId | ( | int | id | ) |
Returns the data status code associated with the callback identifier supplied.
If the remote equipment module is called, this is the return code delivered. If the link returns or notifies the caller and the equipment module has not been called (e.g. in case of time out) this value will be 'not posted'.
| id | is the callback id of the link for which the current completion code is desired. |
| double GetCurrentDataTimeStamp | ( | int | i | ) |
Returns the data timestamp associated with the input link index.
| i | is the link index of the link for which the current data timestamp is desired. |
| double GetCurrentDataTimeStampFromCallbackId | ( | int | id | ) |
Returns the data timestamp associated with the callback identifier supplied.
| i | is the callback identifier of the link for which the current data timestamp is desired. |
| int GetCurrentLinkStatus | ( | int | i | ) |
Returns the completion code associated with the input link index.
| i | is the link index of the link for which the current completion code is desired. |
Example:
| int GetCurrentLinkStatusFromCallbackId | ( | int | id | ) |
Returns the completion code associated with the callback identifier supplied.
| id | is the callback id of the link for which the current completion code is desired. |
Example:
| int GetDataFromCallbackId | ( | int | id, |
| DTYPE * | dout, | ||
| UINT16 * | status | ||
| ) |
Supplies the DTYPE data object and call status for the callback ID in question.
If the user-supplied callback identifier is unambiguous, the output data information pertaining the the link can be obtained via this call. A reference to a DTYPE object will be filled with the current data parameters, including all time and data stamps, transfer reason, data format, etc.
| id | (input) is the callback id of the link supplied with the data link. |
| dout | (output) is a reference to the DTYPE data object to be filled in. |
| status | (output) is a reference to an unsigned short integer to receive the call's return code. |
| int GetDataFromLinkId | ( | int | linkId, |
| DTYPE * | dout, | ||
| UINT16 * | status | ||
| ) |
Supplies the DTYPE data object and call status for the link ID in question.
If the link ID is known, the output data information pertaining the the link can be obtained via this call. A reference to a DTYPE object will be filled with the current data parameters, including all time and data stamps, transfer reason, data format, etc.
| linkId | (input) is the link ID (see AttachLink()) of the data link. |
| dout | (output) is a reference to the DTYPE data object to be filled in. |
| status | (output) is a reference to an unsigned short integer to receive the call's return code. |
References argument_list_error.
| int GetDataStamp | ( | int | linkId | ) |
Gets the data stamp with which the incoming data set has been tagged.
A server can set an integer data stamp with any transaction which will accompany all data transactions. The caller can retrieve this value with this call.
| linkId | is the connection table link id (returned from a call to AttachLink()). If -1 is passed, then the currently active value for the data stamp is returned. |
| int GetDataStampFromCallbackId | ( | int | id | ) |
Gets the global system data stamp with which the incoming data set has been tagged.
A server can set an integer data stamp with any transaction which will accompany all data transactions. The caller can retrieve this value with this call.
| id | is the callback id (supplied with a call to AttachLinkEx()). If -1 is passed, then the currently active value for the data stamp is returned. |
| int GetDefaultTransportMode | ( | void | ) |
Gets the default TINE transport mode used in client-side links.
| int GetGlobalDataType | ( | int | id | ) |
Returns the data type of global link index supplied.
This call is useful if a globals link was started with the target data format = CF_DEFAULT (and a sufficient buffer size was provided). In such cases the global data size can be obtained by calling GetLastGlobalDataSize().
| i | is the global link index for which the data type is desired. |
| int GetGlobalDataTypeFromCallbackId | ( | int | id | ) |
Returns the data type of global link callback id supplied.
This call is useful if a globals link was started with the target data format = CF_DEFAULT (and a sufficient buffer size was provided). In such cases the global data size can be obtained by calling GetLastGlobalDataSize().
| id | is the global link callback id passed in the initial call to recvNetGlobalEx() or recvNetGlobalEx2(). |
References invalid_index.
| int GetGlobalLinkId | ( | char * | keyword | ) |
retrieves the link ID for a globals link
| keyword | is the globals keyword passed as an argument to recvNetGlobal(). |
| int GetGlobalLinkIdFromCallbackId | ( | int | cbId | ) |
retrieves the link ID for a globals link
The ID supplied as argument is the requested callback ID from the original link registration. This link ID is needed as argument to CloseLink().
| cbId | is the callback ID passed as an argument to recvNetGlobalEx(). |
| int GetGlobalsDataStamp | ( | int | glbId | ) |
Gets the data stamp with which the incoming globals data set has been tagged.
A server can set an integer data stamp with any transaction which will accompany all data transactions. The caller can retrieve this value with this call.
| glbId | is the connection table link id (returned from a call to recvNetGlobal()). If -1 is passed, then the 0 is returned. |
| int GetGlobalsHeartbeat | ( | void | ) |
gets the heartbeat (in seconds) during which time no 'timeout' messages will be sent to a globals dispatch routine (client-side)
| int GetGlobalsSystemStamp | ( | int | glbId | ) |
Gets the system data stamp with which the incoming globals data set has been tagged.
A server can set a global data stamp value (e.g. cycle id or run number, etc.) which will accompany all data transactions. The caller can retrieve this value with this call.
| glbId | is the globals table link id (returned from a call to recvNetGlobal()). If -1 is passed, then the currently active value for the data stamp is returned. |
| int GetGlobalsTableCapacity | ( | void | ) |
gets the globals table capacity (client-side)
| double GetGlobalsTimeStamp | ( | int | linkId | ) |
Returns the timestamp of the globals keyword with the given link ID.
| linkId | the globals link index for which the timestamp is desired. |
Referenced by GetGlobalsTimeStampFromCallbackId().
| double GetGlobalsTimeStampFromCallbackId | ( | int | id | ) |
Returns the timestamp of the globals keyword with the given link callback ID.
| id | the callback ID passed to the intial call to recvNetGlobalEx(). |
References GetGlobalsTimeStamp().
| GrpMember * GetGroupMemberList | ( | GrpTblEntry * | grp | ) |
Returns a linked list of the group members for the callback group supplied.
| grp | is a reference to the group table entry (GrpTblEntry *) whose member list is desired. |
| int GetLastGlobalDataSize | ( | int | id | ) |
Returns the most recent data size of the global link index supplied.
| i | is the global link index for which the data size is desired. If i is -1 the last recorded incoming global data size (not a thread-safe thing to do). |
| int GetLastGlobalDataSizeFromCallbackId | ( | int | id | ) |
Returns the most recent data size of the global link callback id supplied.
| id | is the global link callback id for which the data size is desired. |
| char* GetLastLinkError | ( | short | cc, |
| char * | errstr | ||
| ) |
The error string associated with the input error number.
| cc | is the completion code for which the error string is desired. If cc is in fact the last Link Error then the returned error string is used, otherwise the system error string for the completion code in question is returned |
| errstr | is the error string buffer which is to contain the string description of the the cc parameter. A pointer to the same string buffer is returned (A null pointer returns "[null error string]"). |
Example:
| int GetLinkCallbackDelay | ( | int | linkId | ) |
Gets the client-side callback notification.
Asynchronous data acquisition implies a callback handler which accepts and processes incoming data. In some exotic circumstances it might be desireable to delay a callback notification for some specified number of TINE kernel cycles. For instance a 'master link' should needs to fire its callback prior to examining data in other link callbacks. One can use this call to examine the current setting.
| linkId | is the connection table link id (returned from a call to AttachLink()). |
| void* GetLinkCallbackReference | ( | int | id | ) |
Returns the supplied callback reference for the link ID in question.
If the user-supplied callback reference is given in the doubly extended AttachLink call to AttachLinkEx2(), this reference pointer can be retrieved by using this routine.
| id | (input) is the callback id of the link for which the current completion code is desired. |
| char* GetLinkName | ( | int | i | ) |
Returns the full link name associated with the input link index.
| idis | the link index of the link for which the link name is desired. |
| char* GetLinkNameFromCallbackId | ( | int | id | ) |
Returns the full link name associated with the callback identifier supplied.
| id | is the callback id of the link for which the link name is desired. |
| int getLinkOutputStatus | ( | int | lnkId, |
| char * | strSts, | ||
| int | maxKeyLength, | ||
| int | splitlines | ||
| ) |
\intern used internally: no pointer checking ...
| lnkId | is the link id |
| strSts | should be at least 256 char |
| int GetLinkQueueDepth | ( | int | linkId | ) |
Gets the client-side receive queue depth for the link in question.
Asynchronous data acquisition implies a callback handler which accepts and processes incoming data. Under most circumstances the callback handler should process the incoming data quickly and return prior to the next data acquisition (otherwise the data rate is set too high to be useful for the client). However circumstances arrive where either bursts of data arrive or the client side is otherwise busy processing an atypical event, etc. In these cases queueing the incoming data can be beneficial. You can get the current queue depth for a specific link using this routine.
| linkId | is the connection table link id (returned from a call to AttachLink()). |
| int GetSubscriptionRenewalThreshold | ( | int | linkId, |
| int * | thresholdInPercent | ||
| ) |
Gets the current client-side subscription threshold for the link in question.
Persistent contracts established by a Client API Callsalling one of the AttachLink() family 'subscribe' for the contract on the server. A subscription is only valid for a number of responses and must be renewed by the client. This of course happens automatically in the TINE kernel and is a guarantee that clients which 'disappear' ungracefully do not persist indefinitely. The 'number of responses' is known as the subscription renewal length. This value is adjusted according to a client's desired polling interval (i.e. the default value at 1 Hz, 60, is augmented to higher values when polling for instance at 10 Hz). The default value might under some circumstance be deemed to be too small. e.g. a server knows that properties are being 'scheduled' (see _SystemScheduleProperty()) at many Hz, which would cause the subscription counter to descrease more rapidly than the client's polling interval would otherwise dictate. In such cases the subscription 'renewals' would be far more frequently than an efficient data transmission would warrant.
| linkId | is the link id for the link in question (returned from the original call to AttachLink(). |
| thesholdInPercent | is a reference to hold the current setting. |
| int GetSuspendCallbacks | ( | void | ) |
returns the suspends asynchronous callback notification setting
When set to TRUE, all asynchronous callbacks will be suspended until the call is reissued changing the setting to FALSE.
| double GetSynchronizationTolerance | ( | void | ) |
Gets the tolerance used in deciding whether to apply a timestamp offset or not.
If a TINE time server is running and supplying a system time stamp, and this server is accepting this to synchronize its local clock when applying data time stamps, the tolerance used in applying this offset can be read by this routine.
| int GetSystemDataStamp | ( | int | linkId | ) |
Gets the system data stamp with which the incoming data set has been tagged.
A server can set a global data stamp value (e.g. cycle id or run number, etc.) which will accompany all data transactions. The caller can retrieve this value with this call.
| linkId | is the connection table link id (returned from a call to AttachLink()). If -1 is passed, then the currently active value for the data stamp is returned. |
| int GetSystemDataStampFromCallbackId | ( | int | id | ) |
Gets the system data stamp with which the incoming data set has been tagged.
A server can set a global data stamp value (e.g. cycle id or run number, etc.) which will accompany all data transactions. The caller can retrieve this value with this call.
| id | is the callback id (supplied with a call to AttachLinkEx()). If -1 is passed, then the currently active value for the data stamp is returned. |
| int GetSystemStampDelay | ( | void | ) |
Returns the registered system cycle delay.
If a server's context has a registered 'CYCLER' then all read data will be tagged with the incoming system cycle number. If it is known a priori that due to hard i/o latency the application of the cycle tag needs to be delayed by some value, then this routine may be used to obtain the currently registered cycle delay value (in milliseconds).
| int GetSystemStampOffset | ( | void | ) |
Returns the registered system cycle offset.
If a server's context has a registered 'CYCLER' then all read data will be tagged with the incoming system cycle number. If it is known a priori that due to hard i/o latency the cycle tag needs to be offset by some value, then this routine may be used to obtain the currently registered cycle offset.
| UINT16 GetTransferFlag | ( | int | linkId | ) |
Gets the data transfer flag for the given link ID.
The caller can obtain an examine the data transfer reason associated with the last data transfer for the link ID given.
| linkId | is the connection table link id (returned from a call to AttachLink()). If -1 is passed, then the current value of the transfer flag is returned. |
| UINT16 GetTransferFlagFromCallbackId | ( | int | id | ) |
Gets the data transfer flag for the give callback identifier.
The caller can obtain an examine the data transfer reason associated with the last data transfer for the callback identifier given.
| id | is the callback id (supplied with a call to AttachLinkEx()). If -1 is passed, then the current value of the transfer flag is returned. |
| int ModifyLinkAttributes | ( | int | i, |
| short | access, | ||
| int | pollingRate, | ||
| void(*)(int, int) | callback, | ||
| int | mode, | ||
| UINT32 | callbackID | ||
| ) |
Allows the caller to assign new link attributes to an active link.
A TINE client by making this call can re-assign a callback function, access mode or polling rate currently in place for an active link.
| i | is the link identifier for the link in question (the returned identifier when the call to AttachLink() or AttachLinkEx() was originally made |
| access | is the data access mode. This can be any combination of TINE access code ORed together (e.g. CA_READ|CA_WRITE). |
| pollingRate | is the polling rate in milliseconds as seen at the server. For SINGLE transfers, this value also serves as a timeout parameter. |
| callback | is the address of the user-supplied callback routine to be called when data arrive from the server. The prototype of this routine must be as shown, where the first argument (id) gives the id of the link which is calling the callback, and the second argument (cc) gives the completion code. For successful data transmission, cc will always be 0, otherwise it can be interpreted with GetLastLinkError(). |
| mode | is the transfer mode (see discussion on Data Transfer Modes). |
| callbackID | is supplied by the caller as an identifier to be returned in the callback funtion |
| int PutLnkErrorValue | ( | int | linkId, |
| void * | errValue | ||
| ) |
Flags a link so that the given error value is used as the data value in case of any link error.
| linkId | is a valid link table id of the link for which the local timestamp should be applied. |
| errValue | is a reference to the error value data set which should be applied in case of a link error. |
| int PutLnkTimeStamp | ( | int | linkId | ) |
Flags a link so that the local timestamp is used for all incoming data sets.
| linkId | is a valid link table id of the link for which the local timestamp should be applied. |
| int ReassignLinkData | ( | int | id, |
| void * | buffer, | ||
| UINT32 | length | ||
| ) |
Reassigns the bound data buffer for the link table id given.
A monitored link is often 'bound' to a specified buffer which is to maintain a representation of the corresponding data (i.e. if the output DTYPE object passed in the call references a non-null data pointer). The caller can reassign this buffer by using this call.
| id | is the link table id (e.g. returned from the original call to AttachLink()). |
| buffer | is a pointer to the new buffer; |
| length | is the length in bytes of the new buffer. This is only used as a 'control'. The call is only successful if the length passed is at least as big as the number of bytes required in the original link. |
| int recvNetGlobal | ( | const char * | keyword, |
| DTYPE * | dout, | ||
| void(*)(int, int) | callback | ||
| ) |
Initiates a net globals data link.
A TINE client requests to receive network global parameters via this routine. Note that the client must reside on a network which itself is receiving broadcast data or onto which multicasts are being routed in order for this call to take effect.
recvNetGlobal() differs from recvNetGlobalEx() in that the callback will return the link identifier in the callback function.
| keyword | is the name of the network global which is desired. If the globals keyword exists on a specific context, then the keyword given should be prefixed with the context. For example "/PETRA/Energy". If the keyword is entered without a prefix then the 'SITE' globals are assumed (e.g. "PEENERGY"). |
| dout | is a pointer to the output data set, that is, the data set to be returned from the server to the client. The structure element ‘dout->data’ should be a pointer to a pre-allocated data buffer, which is to receive the returned data. If dout is a NULL pointer, it is assumed that no data are to be returned. |
| callback | is the address of the user-supplied callback routine to be called when data arrive from the server. The prototype of this routine must be as shown, where the first argument (id) gives the id of the link which is calling the callback, and the second argument (cc) gives the completion code. For successful data transmission, cc will always be 0, otherwise it can be interpreted with GetLastLinkError(). |
Example:
| int recvNetGlobalEx | ( | const char * | keyword, |
| DTYPE * | dout, | ||
| void(*)(int, int) | callback, | ||
| UINT32 | callbackID | ||
| ) |
Initiates a net globals data link (extended call).
A TINE client requests to receive network global parameters via this routine. Note that the client must reside on a network which itself is receiving broadcast data or onto which multicasts are being routed in order for this call to take effect.
recvNetGlobalEx() differs from recvNetGlobal() in that the caller can supply a callback identify to be returned in the callback function. In lieu of this, the callback will return the link identifier.
| keyword | is the name of the network global which is desired. If the globals keyword exists on a specific context, then the keyword given should be prefixed with the context. For example "/PETRA/Energy". If the keyword is entered without a prefix then the 'SITE' globals are assumed (e.g. "PEENERGY"). |
| dout | is a pointer to the output data set, that is, the data set to be returned from the server to the client. The structure element ‘dout->data’ should be a pointer to a pre-allocated data buffer, which is to receive the returned data. If dout is a NULL pointer, it is assumed that no data are to be returned. |
| callback | is the address of the user-supplied callback routine to be called when data arrive from the server. The prototype of this routine must be as shown, where the first argument (id) gives the id of the link which is calling the callback, and the second argument (cc) gives the completion code. For successful data transmission, cc will always be 0, otherwise it can be interpreted with GetLastLinkError(). |
| callbackID | is supplied by the caller as an identifier to be returned in the callback funtion |
Example:
| int recvNetGlobalEx2 | ( | const char * | keyword, |
| DTYPE * | dout, | ||
| void(*)(int, int, void *) | callback, | ||
| UINT32 | callbackID, | ||
| void * | reference | ||
| ) |
Initiates a net globals data link (doubly extended call).
A TINE client requests to receive network global parameters via this routine. Note that the client must reside on a network which itself is receiving broadcast data or onto which multicasts are being routed in order for this call to take effect.
recvNetGlobalEx2() differs from recvNetGlobal() and recvNetGlobalEx() in that the caller can supply a callback identify and a reference pointer to be returned in the callback function. In lieu of this, the callback will return the link identifier and a null pointer.
| keyword | is the name of the network global which is desired. If the globals keyword exists on a specific context, then the keyword given should be prefixed with the context. For example "/PETRA/Energy". If the keyword is entered without a prefix then the 'SITE' globals are assumed (e.g. "PEENERGY"). |
| dout | is a pointer to the output data set, that is, the data set to be returned from the server to the client. The structure element ‘dout->data’ should be a pointer to a pre-allocated data buffer, which is to receive the returned data. If dout is a NULL pointer, it is assumed that no data are to be returned. |
| callback | is the address of the user-supplied callback routine to be called when data arrive from the server. The prototype of this routine must be as shown, where the first argument (id) gives the id of the link which is calling the callback, and the second argument (cc) gives the completion code. For successful data transmission, cc will always be 0, otherwise it can be interpreted with GetLastLinkError(). |
| callbackID | is supplied by the caller as an identifier to be returned in the callback funtion. |
| reference | is supplied by the caller as a reference to be returned in the callback function. In this way, the callback can then de-reference the originating source of the callback. |
Example:
| int RegisterCycleTriggerFunction | ( | CYCBFCNP | fcn, |
| char * | eqm, | ||
| char * | prpLst, | ||
| void * | reference | ||
| ) |
Registers a cycle trigger callback dispatch function.
If a CYCLER is running in a server's context, then the server will receive 'Cycle Number' events scheduled by the designated CYCLER server. The cycle number will make use of the 'System Data Stamp' to tag all data sets obtained from the server. A server can also register a trigger function dispatch routine (or routines) to be called when a 'Cycle Number' event occurs. The dispatch routines will be called prior to setting the 'System Stamp' to the new Cycle Number, which will be set following the execution of all dispatch routines. Optionally, the server can provide a property (or list of properties) to be scheduled following the dispatch execution. This will ensure that such properties will be called immediately following dispatch execution AND contain the most recent Cycle Number as the 'System Data Stamp'.
| fcn | is a reference to the cycle trigger dispatch routine to be called following the reception of a new Cycle Number. This must have the prototype: void (*fcn)(int cycleNumber,int cycleStatus,void *reference). Thus, the dispatch routine will be called with the current cycle number, the cycle status (possibly 'link_timeout' if no cycle is received within the assigned globals heartbeat (see SetGlobalsHeartbeat)), and an optional 'reference', which is a void pointer of the caller's choosing (and will be returned to the caller in the dispatch routine). |
| eqm | the local equipment module name of the desired central server (e.g. "BPMEQM") |
| prpLst | is the property or properties which are to be 'scheduled' following the execution of the dispatch routine. If more than a single property is to be scheduled, this should be a string containing a comma separated list. |
| reference | is a caller supplied void pointer which will be returned to the called in the dispatch routine. |
Example:
| void ResetSuspendCallbacks | ( | void | ) |
stops suspending callbacks and resets the reference counter
When set to TRUE, all asynchronous callbacks will be suspended until the call is reissued changing the setting to FALSE.
| int ResubmitDataLink | ( | int | id | ) |
Resubmits a (CM_SINGLE) data link.
This routine is useful for asynchronous single links which should be 'retried' following a link timeout notification in the callback.
| id | is the link index for the link which is to be resubmitted |
| int SetAccessLock | ( | char * | context, |
| char * | server, | ||
| int | lockType, | ||
| int | lockDuration | ||
| ) |
Acquires an access lock to the server specified.
A client application can obtain an access lock to the given server provided the caller has WRITE privileges himself. Once the lock is obtained, no other process will be allowed WRITE access regardless of any other access control lists. A lock may be preemptive (LOCK_PREEMTIVE) or persistent (LOCK_PERSISTENT). Preemptive locks may be aborted (LOCK_ABORT) by other callers with WRITE privileges. Persistent locks may not.
| context | is the targeted context of the server |
| server | is the targeted device server |
| lockType | is the desired lock type: one of LOCK_CANCEL, LOCK_PREEPMTIVE, LOCK_PERSISTENT or LOCK_ABORT. |
| lockDuration | is the requested duration of the lock in seconds. This applies only to preemptive locks. Persistent locks will ignore this parameter and continue to renew the lock until the caller cancels the lock (graceful) or disappears (maximum 60 second wait). |
Example:
| void SetAllowDependentLinks | ( | int | value | ) |
turns the ability to manage identical (dependent) links ON or OFF
When set to TRUE, attempts to establish (multiply) identical links to the same target are allowed. In this case the original link is desigated the 'parent link' and constitutes the actual link (client to server). Other client-side links to the same target (have the same contract) will then obtain their results from the parent link.
| value | is the desired setting. (default = TRUE). |
| void SetAlwaysRetry | ( | int | value | ) |
Sets the 'Always Retry' flag to the value given.
Client Links can be instructed to always apply the CA_RETRY flag upon initialization by setting this flag to TRUE. If TRUE all link timeouts will be retried up to three times before issuing a link timeout notification. The default value is TRUE.
| value | is the value of the retry flag. |
| void SetAutoLinkErrorAlarms | ( | int | value | ) |
Sets the autoLinkErrorAlarms flag.
A server can set automatic 'link_error' alarms when a link to another server goes down. This call sets the value of this flag, (default = TRUE).
| value | is the desired setting of this flag (default = TRUE) |
| void SetAutoLinkWatchdogs | ( | int | value | ) |
Enables/Disables automatic link watchdogs.
On-Data-Change or Event monitor links can sometimes fail to notice a missing server for up to the system heartbeat of 60 seconds. With this flag enabled (the default) all such links to a given server are coupled to a watchdog link which will fire the appropriate link notifications when a server goes down. If this feature is not desireable, it can be turned off with this call.
| value | is either TRUE to turn this feature on (the default) or FALSE to turn it off |
| void SetClnRecvQueueDepth | ( | int | depth | ) |
Sets the default client-side receive queue depth for all client links.
Asynchronous data acquisition implies a callback handler which accepts and processes incoming data. Under most circumstances the callback handler should process the incoming data quickly and return prior to the next data acquisition (otherwise the data rate is set too high to be useful for the client). However circumstances arrive where either bursts of data arrive or the client side is otherwise busy processing an atypical event, etc. In these cases queueing the incoming data can be beneficial. You can set the default queue depth for initializing links with this routine.
| depth | is the requested queue depth (values less than zero are ignored). A value of zero implies no queue will be maintained. |
| int SetConnectionTableCapacity | ( | int | value | ) |
Sets the maximum number of entries in the connection table.
References invalid_data.
| void SetDefaultTransportMode | ( | int | value | ) |
Sets the default TINE transport mode used in client-side links.
| value | is the desired default transport mode. This can be either 'TCP' or 'UDP' (the default). Indeed, if value does not equal 'TCP' then the default transport mode will be taken as UDP. |
| void SetGlobalsHeartbeat | ( | int | value | ) |
sets the heartbeat (in seconds) during which time no 'timeout' messages will be sent to a globals dispatch routine (client-side)
| value | is the desired heartbeat in seconds (default: 60 seconds) |
| void SetGlobalsTableCapacity | ( | int | value | ) |
sets the globals table capacity
This establishes the maximum size of the (client-side) table which is to receive network globals. (Default : 50).
| value | is the desired table size. |
| void SetLinkCallbackDelay | ( | int | linkId, |
| int | cyclesToDelay | ||
| ) |
Sets a client-side callback notification.
Asynchronous data acquisition implies a callback handler which accepts and processes incoming data. In some exotic circumstances it might be desireable to delay a callback notification for some specified number of TINE kernel cycles. For instance a 'master link' should needs to fire its callback prior to examining data in other link callbacks. One can use this call to accomplish this.
| linkId | is the connection table link id (returned from a call to AttachLink()). |
| cyclesToDelay | is the number of cycles to delay prior to firing the link callback. A value of zero (DEFAULT) implies no delay. |
| void SetLinkQueueDepth | ( | int | linkId, |
| int | depth | ||
| ) |
Sets the client-side receive queue depth for the link in question.
Asynchronous data acquisition implies a callback handler which accepts and processes incoming data. Under most circumstances the callback handler should process the incoming data quickly and return prior to the next data acquisition (otherwise the data rate is set too high to be useful for the client). However circumstances arrive where either bursts of data arrive or the client side is otherwise busy processing an atypical event, etc. In these cases queueing the incoming data can be beneficial. You can set the queue depth for a specific link using this routine.
| linkId | is the connection table link id (returned from a call to AttachLink()). |
| depth | is the requested queue depth (values less than zero are ignored). A value of zero implies no queue will be maintained. |
| int SetLinkWatchdogPollingInterval | ( | int | value | ) |
Sets the link watchdog polling interval to the value given.
Data-change or event style monitor links will receive data updates only when the examined data have changed or an event has been declared. In addition a systematic heartbeat is received at approximately once per minute per monitor link and a systematic watch dog link per target server is established (if enabled) at the minimum of the desired remote polling interval and the value given by this call (default = 1000 msec). Thus a link timeout notification will be sent to the link callback with minimum latency. The default link watchog polling interval can be set with this function call.
| value | is the desired link watchdog polling interval in milliseconds. |
References feclog(), and out_of_range.
| int SetNotificationTolerance | ( | int | linkId, |
| float | toleranceAbsolute, | ||
| float | tolerancePercent | ||
| ) |
Allows the caller to apply a tolerance pertaining to link notification.
When a TINE client subscribes to data using CM_DATACHANGE mode, the data is sent from server to client when the data change without regard to any applied tolerance (zero tolerance). The client application may nonetheless wish to be notified only when the data have changed outside a given tolerance. This can be achieved by calling this routine. The same applies to CM_TIMER mode, where the data are sent server-to-client according to the schedule. In the latter case, all data comparisons are made entirely at the client side. Note that if this feature is desired in CM_TIMER mode, the CM_NODUPLICATES switch must be applied to the mode parameter in the call to AttachLink() or AttachLinkEx(). This switch will be appended automatically if SetSuppressHeartbeatNotification(TRUE) is called.
| linkId | is the link identifier for the link in question (the returned identifier when the call to AttachLink() or AttachLinkEx() was originally made |
| toleranceAbsolute | if non-zero is a tolerance in the data units of the in-coming data. It is checked against irrespective of the current data values. |
| tolerancePercent | if non-zero is a tolerance expressed as a percent, and refers to the previous data set. |
If both an absolute tolerance and a percent tolerance are used, the absolute value of both contributions are added together to define the total tolerance which should be checked against.
References SetNotificationToleranceEx().
| int SetNotificationToleranceEx | ( | int | linkId, |
| float | toleranceAbsolute, | ||
| float | tolerancePercent, | ||
| int | offset, | ||
| int | length, | ||
| int | flags | ||
| ) |
Allows the caller to apply a tolerance pertaining to link notification (extended call).
When a TINE client subscribes to data using CM_DATACHANGE mode, the data is sent from server to client when the data change without regard to any applied tolerance (zero tolerance). The client application may nonetheless wish to be notified only when the data have changed outside a given tolerance. This can be achieved by calling this routine. The same applies to CM_TIMER mode, where the data are sent server-to-client according to the schedule. In the latter case, all data comparisons are made entirely at the client side. Note that if this feature is desired in CM_TIMER mode, the CM_NODUPLICATES switch must be applied to the mode parameter in the call to AttachLink() or AttachLinkEx(). This switch will be appended automatically if SetSuppressHeartbeatNotification(TRUE) is called.
| linkId | is the link identifier for the link in question (the returned identifier when the call to AttachLink() or AttachLinkEx() was originally made |
| toleranceAbsolute | if non-zero is a tolerance in the data units of the in-coming data. It is checked against irrespective of the current data values. |
| tolerancePercent | if non-zero is a tolerance expressed as a percent, and refers to the previous data set. |
| offset | specifies the array offset to be used in data comparison (DEFAULT: 0). If the given offset is less then 0 or greater than the length of the acquired data array (i.e. > 1 if a single value is acquired) it will be automatically set to 0. |
| length | specifes the length of the data array (beginning at the given offset) to be used in data comparison (DEFAULT: length of the acquire data array, or 1 if a single value is acquired). If the given value exceeds the array bounds, then it will be adjusted. |
| flags | is one of DTF_SUPPRESS or DTF_NOTIFY and specifies the desired form of the the 'out of tolerance' notification (DEFAULT: DTF_SUPPRESS). If DTF_SUPPRESS is specified, then callbacks will be suppressed unless there is an error or the most recent data set is out of tolerance. If DTF_NOTIFY is specified, then callbacks will not be suppressed. However, if the most recent data set is out of tolerance, then an otherwise successful callback completion code will be flagged as CE_SENDDATA + out_of_tolerance. The caller can then make use of this form of 'out of tolerance' signal to suit his needs. |
If both an absolute tolerance and a percent tolerance are used, the absolute value of both contributions are added together to define the total tolerance which should be checked against.
Referenced by SetNotificationTolerance().
| int SetSubscriptionRenewalThreshold | ( | int | linkId, |
| int | thresholdInPercent | ||
| ) |
Gets the current client-side subscription threshold for the link in question.
Persistent contracts established by a Client API Callsalling one of the AttachLink() family 'subscribe' for the contract on the server. A subscription is only valid for a number of responses and must be renewed by the client. This of course happens automatically in the TINE kernel and is a guarantee that clients which 'disappear' ungracefully do not persist indefinitely. The 'number of responses' is known as the subscription renewal length. This value is adjusted according to a client's desired polling interval (i.e. the default value at 1 Hz, 60, is augmented to higher values when polling for instance at 10 Hz). The default value might under some circumstance be deemed to be too small. e.g. a server knows that properties are being 'scheduled' (see _SystemScheduleProperty()) at many Hz, which would cause the subscription counter to descrease more rapidly than the client's polling interval would otherwise dictate. In such cases the subscription 'renewals' would be far more frequently than an efficient data transmission would warrant. The client side link can establish a higher renewal threshold value by making use of this call.
| linkId | is the link id for the link in question (returned from the original call to AttachLink(). |
| thresholdInPercent | is the desired threshold given as a percent of the total number of subscription transfers. This should be positive integer. Accepted values range between 10 and 90 (percent). |
| void SetSuppressHeartbeatNotification | ( | int | value | ) |
Determines whether CM_DATACHANGE data links signal incoming data by calling the corresonding callback routine even when the incoming data is a HEARTBEAT notification.
A client may wish to receive data notification events only when the incoming data have changed or the data link has an error, and not receive and respond to heartbeat notifications. Setting this global variable to TRUE will archieve this aim.
| value | determines whether heartbeat notification will be suppressed or not Default: FALSE |
| void SetSuspendCallbacks | ( | int | value | ) |
set suspends asynchronous callback notification ON or OFF
When set to TRUE, all asynchronous callbacks will be suspended until the call is reissued changing the setting to FALSE.
| value | is the desired setting |
| void SetSynchronizationTolerance | ( | double | toleranceInSeconds | ) |
Sets the tolerance used in deciding whether to apply a timestamp offset or not.
If a TINE time server is running and supplying a system time stamp, and this server is accepting this to synchronize its local clock when applying data time stamps, the tolerance used in applying this offset can be set by this routine.
| toleranceInSeconds | is the maximum time difference allowed before setting the data timestamp offset. (Default: 0.5 seconds) |
| void SetSystemStampDelay | ( | int | cycleDelay | ) |
Establishes the system cycle delay.
If a server's context has a registered 'CYCLER' then all read data will be tagged with the incoming system cycle number. If it is known a priori that due to hard i/o latency the application of the cycle tag needs to be delayed by some value, then this routine may be used to establish such a cycle delay value (in milliseconds).
| cycleDelay | is the desired cycle delay (milliseconds), which will must elapse before the incoming cycle number from the registered CYCLER is to be applied to all readback data. (default = 0). |
| void SetSystemStampOffset | ( | int | cycleOffset | ) |
Establishes a system cycle offset.
If a server's context has a registered 'CYCLER' then all read data will be tagged with the incoming system cycle number. If it is known a priori that due to hard i/o latency the cycle tag needs to be offset by some value, then this routine may be used to establish such an offset.
| cycleOffset | is the desired cycle offset (counts) to be applied to the incoming cycle number from the registered CYCLER. (Default = 0). |
| int UnregisterCycleTriggerFunction | ( | CYCBFCNP | fcn, |
| void * | reference | ||
| ) |
Unregisters a previously registered cycle trigger callback dispatch function.
If a cycle trigger event dispatch routine is no longer required, it can be unregistered using this routine.
| fcn | is a reference to the previously registered cycle trigger dispatch routine which is to be removed. |
| reference | is a caller supplied void pointer which will be returned to the called in the dispatch routine. |
| int UpdateDataStampsFromCallbackId | ( | int | id, |
| DTYPE * | dout | ||
| ) |
Fills in the given DTYPE data object with all data stamp information.
If the user-supplied callback identifier is unambiguous, a reference to a DTYPE object will be filled with the current time and data stamps as well as the transfer reason. The remaining elements of the given DTYPE object are not touched.
| id | (input) is the callback id supplied with the data link. |
| dout | (output) is a reference to the DTYPE data object to be filled in. |
| int UpdateDataStampsFromLinkId | ( | int | linkId, |
| DTYPE * | dout | ||
| ) |
Fills in the given DTYPE data object with all data stamp information.
If the link ID is known, a reference to a DTYPE object will be filled with the current time and data stamps as well as the transfer reason. The remaining elements of the given DTYPE object are not touched.
| linkId | (input) is the link ID (see AttachLink()) of the data link. |
| dout | (output) is a reference to the DTYPE data object to be filled in. |
References argument_list_error.
| int gConTblCapacity = CONTBL_CAPACITY |
Determines the maximum number of entries in the connection table.
A client's connections are managed and maintained in a connection table. The size of this table is pre-allocated at initialization time. This allows for fast lookups, since a connection ID is simply an entry into the table. If it is known that the client will need a large number of simultaneous links then this value should be set accordingly at initialization time.
Default: 1000 (Or #define CONTBL_CAPACITY in project.def)
Referenced by GetConnectionTableCapacity().
| UINT32 LastCompletionDataSize = 0 |
Supplies the data size of the most recent link.
A global variable which supplies the data size of the most recent link.
Referenced by GetCompletionDataSize().
| int LastCompletionDataType = CF_NULL |
Supplies the data type of the most recent link.
A global variable which supplies the data type of the most recent link.
| short lastLnkErrSrc = 0 |
Gives the signature of the last Link Error.
If a call to ExecLink() or ExecLinkEx() fails it will return a non-zero TINE error code, which can be interpreted by GetLastLinkError(). It is sometime useful to know whether the return code was locally generated (for instance a time out) or remotely generated (for instance 'illegal property'). To this end you can examine the value of lastLnkErrSrc and check it against LNK_ERROR_LCL or LNK_ERROR_RMT
Referenced by GetCompletionSource().
1.5.8