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.
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.
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.
int	CloseGlobalLink (int linkId)
	Closes an active globals data link.
int	CloseLink (int linkId)
	Cancels an active data link.
int	CloseNetGlobal (const char *keyword)
	Closes an active globals data link according to the globals Keyword.
int	ExecLink (const char devName, const char devProperty, DTYPE dout, DTYPE din, short access)
	Executes a synchronous link.
int	ExecLinkEx (const char devName, const char devProperty, DTYPE dout, DTYPE din, short access, UINT16 timeout)
	Executes a synchronous link (Extended call).
int	FreeAccessLock (char context, char server)
	Frees an access lock on the server specified.
int	GetAccessLockInformation (char context, char server, NAME32 callerName, NAME32 callerIp, NAME32 *timeLeft)
	Acquires access lock information from the server specified.
int	GetAccessLockStatus (char context, char server)
	Acquires the current access lock status on a client's access lock.
int	GetAllowDependentLinks (void)
	returns the setting for this value
int	GetAlwaysRetry (void)
	Gets the current setting of the 'Always Retry' flag.
int	GetAutoLinkErrorAlarms (void)
	Gets the current setting of the autoLinkErrorAlarms flag.
GrpTblEntry *	GetCallbackGroup (size_t id)
	Returns a reference to the callback Group Table Entry associated with the identifier supplied.
int	GetClnRecvQueueDepth (void)
	Gets the default client-side receive queue depth for all client links.
int	GetCompletionDataSize (int i)
	Returns the most recent data size of the link index supplied.
int	GetCompletionDataSizeFromCallbackId (int id)
	Returns the most recent data size of the link associated with the callback id supplied.
int	GetCompletionDataType (int i)
	Returns the most recent data type of the link index supplied.
int	GetCompletionDataTypeFromCallbackId (int id)
	Returns the most recent data type of the link associated with the callback id supplied.
short	GetCompletionSource (int i)
	Returns the error source associated with the input link index.
short	GetCompletionSourceFromCallbackId (int id)
	Returns the error source associated with the callback identifier supplied.
char *	GetCompletionStatus (int i)
	Returns the error string associated with the input link index.
char *	GetCompletionStatusFromCallbackId (int id)
	Returns the error string associated with the callback identifier supplied.
int	GetConnectionTable (ConTblInfo tbl, int tblSize)
	Gets the current connection table.
int	GetConnectionTableCapacity (void)
	Gets the maximum number of entries allowed in the connection table.
int	GetCurrentDataStatus (int i)
	Returns the data status code associated with the input link index.
int	GetCurrentDataStatusFromCallbackId (int id)
	Returns the data status code associated with the callback identifier supplied.
double	GetCurrentDataTimeStamp (int i)
	Returns the data timestamp associated with the input link index.
double	GetCurrentDataTimeStampFromCallbackId (int id)
	Returns the data timestamp associated with the callback identifier supplied.
int	GetCurrentLinkStatus (int i)
	Returns the completion code associated with the input link index.
int	GetCurrentLinkStatusFromCallbackId (int id)
	Returns the completion code associated with the callback identifier supplied.
int	GetDataFromCallbackId (int id, DTYPE dout, UINT16 status)
	Supplies the DTYPE data object and call status for the callback ID in question.
int	GetDataFromLinkId (int linkId, DTYPE dout, UINT16 status)
	Supplies the DTYPE data object and call status for the link ID in question.
int	GetDataStamp (int linkId)
	Gets the data stamp with which the incoming data set has been tagged.
int	GetDataStampFromCallbackId (int id)
	Gets the global system data stamp with which the incoming data set has been tagged.
int	GetDefaultTransportMode (void)
	Gets the default TINE transport mode used in client-side links.
int	GetGlobalLinkId (char *keyword)
	retrieves the link ID for a globals link
int	GetGlobalLinkIdFromCallbackId (int cbId)
	retrieves the link ID for a globals link
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	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.
GrpMember *	GetGroupMemberList (GrpTblEntry *grp)
	Returns a linked list of the group members for the callback group supplied.
int	GetLastGlobalDataSize (int id)
	Returns the most recent data size of the global link index supplied.
int	GetLastGlobalDataSizeFromCallbackId (int id)
	Returns the most recent data size of the global link callback id supplied.
char *	GetLastLinkError (short cc, char *errstr)
	The error string associated with the input error number.
void *	GetLinkCallbackReference (int id)
	Returns the supplied callback reference for the link ID in question.
char *	GetLinkName (int i)
	Returns the full link name associated with the input link index.
char *	GetLinkNameFromCallbackId (int id)
	Returns the full link name associated with the callback identifier supplied.
int	GetLinkQueueDepth (int linkId)
	Gets the client-side receive queue depth for the link in question.
double	GetSynchronizationTolerance (void)
	Gets the tolerance used in deciding whether to apply a timestamp offset or not.
int	GetSystemDataStamp (int linkId)
	Gets the global system data stamp with which the incoming data set has been tagged.
int	GetSystemDataStampFromCallbackId (int id)
	Gets the global system data stamp with which the incoming data set has been tagged.
int	GetSystemStampDelay (void)
	Returns the registered system cycle delay.
int	GetSystemStampOffset (void)
	Returns the registered system cycle offset.
UINT16	GetTransferFlag (int linkId)
	Gets the data transfer flag for the given link ID.
UINT16	GetTransferFlagFromCallbackId (int id)
	Gets the data transfer flag for the give callback identifier.
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.
int	recvNetGlobal (const char keyword, DTYPE dout, void(*cbFcn)(int, int))
	Initiates a net globals data link.
int	recvNetGlobalEx (const char keyword, DTYPE dout, void(*cbFcn)(int, int), UINT32 cbId)
	Initiates a net globals data link (extended call).
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).
int	RegisterCycleTriggerFunction (CYCBFCNP fcn, char eqm, char prpLst, void *reference)
	Registers a cycle trigger callback dispatch function.
int	SetAccessLock (char context, char server, int lockType, int lockDuration)
	Acquires an access lock to the server specified.
void	SetAllowDependentLinks (int value)
	turns the ability to manage identical (dependent) links ON or OFF
void	SetAlwaysRetry (int value)
	Sets the 'Always Retry' flag to the value given.
void	SetAutoLinkErrorAlarms (int value)
	Sets the autoLinkErrorAlarms flag.
void	SetAutoLinkWatchdogs (int value)
	Enables/Disables automatic link watchdogs.
void	SetClnRecvQueueDepth (int depth)
	Sets the default client-side receive queue depth for all client links.
void	SetConnectionTableCapacity (int value)
	Sets the maximum number of entries in the connection table.
void	SetDefaultTransportMode (int value)
	Sets the default TINE transport mode used in client-side links.
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)
void	SetGlobalsTableCapacity (int value)
	sets the globals table capacity
void	SetLinkQueueDepth (int linkId, int depth)
	Sets the client-side receive queue depth for the link in question.
int	SetLinkWatchdogPollingInterval (int value)
	Sets the link watchdog polling interval to the value given.
int	SetNotificationTolerance (int linkId, float toleranceAbsolute, float tolerancePercent)
	Allows the caller to apply a tolerance pertaining to link notification.
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.
void	SetSynchronizationTolerance (double toleranceInSeconds)
	Sets the tolerance used in deciding whether to apply a timestamp offset or not.
void	SetSystemStampDelay (int cycleDelay)
	Establishes the system cycle delay.
void	SetSystemStampOffset (int cycleOffset)
	Establishes a system cycle offset.
int	UnregisterCycleTriggerFunction (CYCBFCNP fcn, void *reference)
	Unregisters a previously registered cycle trigger callback dispatch function.
Variables
UINT32	LastCompletionDataSize = 0
	Supplies the data size of the most recent link.
int	LastCompletionDataType = CF_NULL
	Supplies the data type of the most recent link.
short	lastLnkErrSrc = 0
	Gives the signature of the last Link Error.
int	MaxNumConnections = CONTBL_CAPACITY
	Determines the maximum number of entries in the connection table.

Detailed Description

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.

Function Documentation

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.

Parameters:

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).

Returns:: A positive link handle if successful, otherwise the negative of a TINE completion code which can be interpreted by a call to GetLastLinkError().

See also:: AttachLinkEx(), DTYPE

Example:

    // global variables:
    short TRCchannel[100];
    float TRCvoltage[100];
    int idTRC;

    // callback routine:
    void TRCcallback(int id, int cc)
    {
      char errstr[256];
      if (cc)
      {
        printf("TRC error : %s\n",GetLastLinkError(cc,errstr));
        return;
      }
      if (id == idTRC)
      {
        // the data are here, do something with them
      }
    }
    //...
    int MyInitRoutine(void)
    {
      char errstr[256];
      DTYPE din, dout;
      dout.dFormat = CF_FLOAT;
      dout.dArrayLength = 100;
      dout.data.fptr = TRCvoltage;
      din.dFormat = CF_SHORT;
      din.dArrayLength = 100;
      din.data.sptr = TRCchannel;
      // fill in TRCchannel with the channels of interest and send to server:
      idTRC = AttachLink("/HERA/TRC/WL167", "VOLTAGE", &dout, &din, CA_READ, 1000, TRCcallback, CM_REFRESH);
      if (idTRC < 0) // something is wrong
      {
        printf("Can’t AttachLink to /HERA/TRC/WL167 : %s\n",GetLastLinkError(-idTRC,errstr));
        exit(1);
      }
    }
    // ...

Referenced by clslog(), and ExecLinkEx().

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.

Parameters:

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 funtion

Returns:: A positive link handle if successful, otherwise the negative of a TINE completion code which can be interpreted by a call to GetLastLinkError().

See also:: AttachLink(), DTYPE

Example:

    // global variables:
    short TRCchannel[100];
    float TRCvoltage[100];
    int myId = 10;

    // callback routine:
    void TRCcallback(int id, int cc)
    {
      char errstr[256];
      if (cc)
      {
        printf("TRC error : %s\n",GetLastLinkError(cc,errstr));
        return;
      }
      if (id == myId)
      {
        // the data are here, do something with them
      }
    }
    //...
    int MyInitRoutine(void)
    {
      char errstr[256];
      DTYPE din, dout;
      dout.dFormat = CF_FLOAT;
      dout.dArrayLength = 100;
      dout.data.fptr = TRCvoltage;
      din.dFormat = CF_SHORT;
      din.dArrayLength = 100;
      din.data.sptr = TRCchannel;
      // fill in TRCchannel with the channels of interest and send to server:
      idTRC = AttachLinkEx("/HERA/TRC/WL167", "VOLTAGE", &dout, &din, CA_READ, 1000, TRCcallback, CM_REFRESH,myId);
      if (idTRC < 0) // something is wrong
      {
        printf("Can’t AttachLink to /HERA/TRC/WL167 : %s\n",GetLastLinkError(-idTRC,errstr));
        exit(1);
      }
    }
    // ...

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.

Parameters:

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 funtion
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.

Returns:: A positive link handle if successful, otherwise the negative of a TINE completion code which can be interpreted by a call to GetLastLinkError().

See also:: AttachLink(), AttachLinkEx(),DTYPE

Example:

   typedef void (*REFFCN)(void);
    // global variables:
    short TRCchannel[100];
    float TRCvoltage[100];
    int myId = 10;

    // callback routine:
    void TRCcallback(int id, int cc, void *ref)
    {
      char errstr[256];
      if (cc)
      {
        printf("TRC error : %s\n",GetLastLinkError(cc,errstr));
        return;
      }
      if (id == myId)
      {
        // the data are here, do something with them
      }
      if (cc == 0)
      { // now call another routine that this callback is supposed to call
        ((REFFCN)ref)();
      }
    }
    void forwardVoltage(void)
    {
      // do something special here
    }
    //...
    int MyInitRoutine(void)
    {
      char errstr[256];
      DTYPE din, dout;
      dout.dFormat = CF_FLOAT;
      dout.dArrayLength = 100;
      dout.data.fptr = TRCvoltage;
      din.dFormat = CF_SHORT;
      din.dArrayLength = 100;
      din.data.sptr = TRCchannel;
      // fill in TRCchannel with the channels of interest and send to server:
      idTRC = AttachLinkEx2("/HERA/TRC/WL167", "VOLTAGE", &dout, &din, CA_READ, 1000, TRCcallback, CM_REFRESH,myId,(void *)forwardVoltage);
      if (idTRC < 0) // something is wrong
      {
        printf("Can’t AttachLink to /HERA/TRC/WL167 : %s\n",GetLastLinkError(-idTRC,errstr));
        exit(1);
      }
    }
    // ...

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.

Parameters:

linkId the globals link index to be canceled

See also:: recvNetGlobal() or recvNetGlobalEx() and CloseNetGlobal()

References glbClnSck.

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.

Parameters:

i	the link index to be canceled

Returns:: 0 upon success or a TINE error code

See also:: AttachLink(), AttachLinkEx()

Example:

   CloseLink(idEnergyLink);

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.

Parameters:

keyword the globals keyword used to establish the link.

See also:: recvNetGlobal() or recvNetGlobalEx() and CloseGlobalLink()

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

Parameters:

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.)

Returns:: 0 if successful, otherwise a TINE completion code which can be interpreted by a call to GetLastLinkError().

See also:: ExecLocalLink(), ExecLinkEx(), DTYPE

Example:

#include "tine.h"
...

char errstr[256];
float bpm_positions[131];
DTYPE dout;

...

dout.dFormat = CF_FLOAT;
dout.dArrayLength = 131;
dout.data.fptr = bpm_positions;

// start at WL167 and get 131 consecutive positions
if ((cc=ExecLink(“/HERA/BPM/WL167”, ”POSITIONS", &dout, NULL, CA_READ)) != 0)
{
   printf(“BPM POSITIONS: %s\n”,GetLastLinkError(cc,errstr));

...

References ExecLinkEx(), and ExecLocalLink().

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.

Parameters:

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.

Returns:: 0 if successful, otherwise a TINE completion code which can be interpreted by a call to GetLastLinkError().

See also:: ExecLocalLink(), ExecLink(), DTYPE

Example:

#include "tine.h"

...

char errstr[256];
float bpm_postions[131];
DTYPE dout;

...

dout.dFormat = CF_FLOAT;
dout.dArrayLength = 131;
dout.data.fptr = bpm_positions;

// start at WL167 and get 131 consecutive positions
if ((cc=ExecLinkEx“/HERA/BPM/WL167”, ”POSITIONS", &dout, NULL, CA_READ,3000)) != 0)
{
   printf(“BPM POSITIONS: %s\n”,GetLastLinkError(cc,errstr));

...

References AttachLink(), DTYPE::dArrayLength, DTYPE::data, DTYPE::dFormat, DTYPE::dStamp, DTYPE::dTag, DTYPE::dTimeStamp, lastLnkErrSrc, PutDataTimeStamp(), DTYPE::sysStamp, DUNION::vptr, and DTYPE::xferReason.

Referenced by ExecLink(), FindServerOnNetwork(), GetAccessLockInformation(), GetArchivedData(), GetArchivedDataAsAny(), GetArchivedDataAsFloat(), GetArchivedDataAsSnapshot(), GetArchivedDataAsText(), GetArchivedTraceDataAsFloat(), GetDeviceNamesEx(), GetDeviceProperties(), GetDevicePropertyEGU(), GetDevicePropertyInformation(), GetSystemDevices(), GetSystemProperties(), GetSystemPropertyInformation(), and GetTargetPropertyInformation().

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.

Parameters:

context	is the targeted context of the server
server	is the targeted device server

Returns:: a tine return code.

Example:

  
  /* acquire a persistent lock (persistent lock will ignore the duration parameter) */
  cc = SetAccessLock("DESY2","PiControls",LOCK_PERSISTENT,0);
  if (cc != 0) dbglog("SetAccessLock : %s",erlst[cc]);
  
  /* do something important ... */

  /* release the lock */
  FreeAccessLock("DESY2","PiControls");

See also:: SetAccessLock(), GetAccessLockInformation(), GetAccessLockStatus()

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".

Parameters:

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.

Returns:: a tine return code.

Example:

  int cc;
  NAME32 callerName,callerIp,timeLeft;

  cc = GetAccessLockInformation("TEST","LxSineServer",&callerName,&callerIp,&timeLeft);
  if (cc == 0)
  {
    dbglog("LxSineServer locked by %s at address %s (%s)",callerName.name,callerIp.name,timeLeft.name);
  }

See also:: SetAccessLock(), FreeAccessLock(), GetAccessLockStatus()

References DTYPE::dArrayLength, DTYPE::data, DTYPE::dFormat, ExecLinkEx(), 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.

Parameters:

context	is the targeted context of the server
server	is the targeted device server

Returns:: a tine return code indicating the status of the access lock.

See also:: SetAccessLock(), FreeAccessLock(), GetAccessLockInformation()

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.

Returns:: the current setting of this feature. (default: TRUE)

See also:: GetAllowDependentLinks()

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.

Returns:: the current value of the retry flag.

See also:: SetAlwaysRetry()

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).

Returns:: the current setting of the autoLinkErrorAlarms flag.

See also:: SetAutoLinkErrorAlarms

GrpTblEntry * GetCallbackGroup ( size_t id )

Returns a reference to the callback Group Table Entry associated with the identifier supplied.

Parameters:

id	is the group callback id (effectively the reference pointer to the callback function associated with the group.

Returns:: a reference to the group table entry (GrpTblEntry *) if the given id corresponds to a registered callback group, or NULL if not found.

See also:: GetGroupMemberList(), GrpTblEntry, GrpMember

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.

Returns:: the current setting for the default receive queue depth or a negative TINE return code upon error.

int GetCompletionDataSize ( int i )

Returns the most recent data size of the link index supplied.

Parameters:

i	is the link index for which the completed data size is desired

Returns:: The most recent data size of the link index supplied

See also:: GetCompletionDataSizeFromCallbackId()

Example:

#include "tine.h"

...
char errstr[256];

if  ((cc=ExecLink(“/HERA/HEPBPM/WL167”,” POSITIONS.X”,&dout,NULL,CA_READ)) != 0)
{
  printf(“link failed : %s\n”,GetLastLinkError(cc,errstr));
}
else
  printf(“%d values returned\n”,GetCompletionDataSize(-1));

...

References LastCompletionDataSize.

int GetCompletionDataSizeFromCallbackId ( int id )

Returns the most recent data size of the link associated with the callback id supplied.

Parameters:

id	is the callback id of the link for which the completed data size is desired

Returns:: The most recent data size of the link associated with the callback id supplied

See also:: GetCompletionDataSize()

Example:

#include "tine.h"
...

void PostSystemInit()
{
  char errstr[256];
  if  ((id=AttachLinkEx(“/HERA/HEPBPM/WL167”,” ORBIT.X”,&dout,NULL,CA_READ,1000,bpmcback,CM_POLL,bpmcbackID)) < 0)
  {
    printf(“link failed : %s\n”,GetLastLinkError(-id,errstr));
  }
}
...
void bpmcback(int id, int cc)
{
//...
  printf(“%d values returned\n”, GetCompletionDataSizeFromCallbackId(bpmcbackID));
// ...
}

int GetCompletionDataType ( int i )

Returns the most recent data type of the link index supplied.

Parameters:

i	is the link index for which the data type is desired

Returns:: The most recent data type of the link index supplied

See also:: GetCompletionDataTypeFromCallbackId()

Example:

#include "tine.h"

...

char errstr[256];

dout.dFormat = CF_DEFAULT;
dout.dArraySize = 4000;  // bytes assumed for type CF_DEFAULT
dout.data.vptr = buffer;    // buffer had better be able to hold the data which is returned!

if  ((cc=ExecLink(“/HERA/HEPBPM/WL167”,” POSITIONS.X”,&dout,NULL,CA_DEFAULT)) != 0)
{
  printf(“link failed : %s\n”,GetLastLinkError(cc,errstr));
}
else
{
  siz = GetCompletionDataSize(-1);
  fmt = GetCompletionDataType (-1);
  switch (fmt)
  {
     case CF_FLOAT:
         for (i=0; i<siz; i++) printf(“bpm #%d : %g\n”,i,((float *)buffer)[i]);
     case CF_DOUBLE:
        // etc. ...
   }
}

References LastCompletionDataType.

Referenced by GetCompletionDataTypeFromCallbackId().

int GetCompletionDataTypeFromCallbackId ( int id )

Returns the most recent data type of the link associated with the callback id supplied.

Parameters:

id	is the callback id of the link for which the completed data type is desired

Returns:: The most recent data type of the link associated with the callback id supplied

See also:: GetCompletionDataType()

Example:

#include "tine.h"

...

void doinit()
{
  char errstr[256];
  dout.dFormat = CF_DEFAULT;
  dout.dArraySize = 4000;  // bytes assumed for type CF_DEFAULT
  dout.data.vptr = buffer;    // buffer had better be able to hold the data which is returned!

  if  ((id=AttachLinkEx(“/HERA/HEPBPM/WL167”,” POSITIONS.X”,&dout,NULL,CA_READ,1000,bpmcback,CM_POLL,bpmcbackID)) < 0)
  {
    printf(“link failed : %s\n”,GetLastLinkError(-id,errstr));
  }
 }
// ...

void bpmcback(int id, int cc)
{
// ...
  siz = GetCompletionDataSizeFromCallbackId(bpmcbackID);
  fmt = GetCompletionDataTypeFromCallbackId(bpmcbackID);
  switch (fmt)
  {
     case CF_FLOAT:
         for (i=0; i<siz; i++) printf(“bpm #%d : %g\n”,i,((float *)buffer)[i]);
     case CF_DOUBLE:
        // etc. ...
   }
//...
}

References GetCompletionDataType().

short GetCompletionSource ( int i )

Returns the error source associated with the input link index.

Parameters:

i	is the link index of the link for which the current status string is desired.

Returns:: The error source associated with the input link index as one of LNK_ERROR_LCL or LNK_ERROR_RMT, or -1 if the link index is invalid.

See also:: GetCompletionSourceFromCallbackId()

References lastLnkErrSrc.

short GetCompletionSourceFromCallbackId ( int id )

Returns the error source associated with the callback identifier supplied.

Parameters:

id	is the callback id of the link for which the current status string is desired.

Returns:: The error source associated with the callback identifier supplied as one of LNK_ERROR_LCL or LNK_ERROR_RMT, or -1 if the callback identifier is invalid.

char* GetCompletionStatus ( int i )

Returns the error string associated with the input link index.

Parameters:

i	is the link index of the link for which the current status string is desired.

Returns:: The error string associated with the input link index, or NULL if the the link index is invalid.

See also:: GetCompletionStatusFromCallbackId()

Example:

char* GetCompletionStatusFromCallbackId ( int id )

Returns the error string associated with the callback identifier supplied.

Parameters:

id	is the callback id of the link for which the current status string is desired.

Returns:: The error string associated with the callback identifier supplied, or NULL if the callback id is invalid.

See also:: GetCompletionStatus()

Example:

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

Parameters:

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.

Returns:: 0 upon success or a TINE return code.

See also:: GetConnectionTableCapacity(), SetConnectionTableCapacity()

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.

See also:: SetConnectionTableCapacity()

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'.

Parameters:

i	is the link index of the link for which the current completion code is desired.

Returns:: The status code associated with the input link index

See also:: GetCurrentLinkStatus()

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'.

Parameters:

id	is the callback id of the link for which the current completion code is desired.

Returns:: The data status code associated with the callback identifier supplied

See also:: GetCurrentLinkStatusFromCallbackId().

double GetCurrentDataTimeStamp ( int i )

Returns the data timestamp associated with the input link index.

Parameters:

i	is the link index of the link for which the current data timestamp is desired.

Returns:: The data timestamp associated with the input link index

See also:: GetDataTimeStampAsTimeval, GetDataTimeStamp, GetCurrentDataTimeStampFromCallbackId

References PutDataTimeStamp().

double GetCurrentDataTimeStampFromCallbackId ( int id )

Returns the data timestamp associated with the callback identifier supplied.

Parameters:

i	is the callback identifier of the link for which the current data timestamp is desired.

Returns:: The data timestamp associated with the input callback identifier

See also:: GetDataTimeStampAsTimeval, GetDataTimeStamp, GetCurrentDataTimeStamp

References PutDataTimeStamp().

int GetCurrentLinkStatus ( int i )

Returns the completion code associated with the input link index.

Parameters:

i	is the link index of the link for which the current completion code is desired.

Returns:: The completion code associated with the input link index

Example:

#include "tine.h"

...
  char errstr[256];

  dout.dFormat = CF_FLOAT;
  dout.dArraySize = 300; 
  dout.data.vptr = buffer;    // buffer had better be able to hold the data which is returned!
 

  if  ((id=AttachLink(“/HERA/HEPBPM/WL167”,” ORBIT.X”,&dout,NULL,CA_READ, linkCbk,CM_POLL)) != 0)
  {
    printf(“link failed : %s\n”,GetLastLinkError(-id,errstr));
    exit(1);

  }

 

 ...

  cc = GetCurrentLinkStatus(id);

  if (cc) // uh-oh !
  {
     printf(“Can’t take action ! : %s\n”,GetLastLinkError(cc,errstr));
     return;
  }
  takeAction();

int GetCurrentLinkStatusFromCallbackId ( int id )

Returns the completion code associated with the callback identifier supplied.

Parameters:

id	is the callback id of the link for which the current completion code is desired.

Returns:: The completion code associated with the callback identifier supplied

Example:

#include "tine.h"

 ...
  char errstr[256];

  dout.dFormat = CF_FLOAT;
  dout.dArraySize = 300;
  dout.data.vptr = buffer;    // buffer had better be able to hold the data which is returned!

  if  ((id=AttachLinkEx(“/HERA/HEPBPM/WL167”,” ORBIT.X”,&dout,NULL,CA_READ,1000,linkCbk,CM_POLL,bpmId)) != 0)
  {
    printf(“link failed : %s\n”,GetLastLinkError(-id,errstr));
    exit(1);
  }

  ...

  cc = GetCurrentLinkStatusFromCallbackId(bpmId);

  if (cc) // uh-oh !
  {
     printf(“Can’t take action ! : %s\n”,GetLastLinkError(cc,errstr));
     return;
  }
  takeAction();

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.

Parameters:

id	(input) is the callback id of the link for which the current completion code is desired.
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.

Returns:: 0 or a TINE error code.

See also:: GetDataFromLinkId()

References GetDataFromLinkId().

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.

Parameters:

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.

Returns:: 0 or a TINE error code.

See also:: GetDataFromCallbackId()

References DTYPE::dArrayLength, DTYPE::data, DTYPE::dFormat, DTYPE::dStamp, DTYPE::dTag, DTYPE::dTimeStamp, DTYPE::sysStamp, DUNION::vptr, and DTYPE::xferReason.

Referenced by GetDataFromCallbackId().

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.

Parameters:

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.

Returns:: The data stamp if the call succeeds or -1.

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.

Parameters:

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.

Returns:: The data stamp if the call succeeds or -1.

int GetDefaultTransportMode ( void )

Gets the default TINE transport mode used in client-side links.

Returns:: the default TINE transport mode (either 'TCP' or 'UDP').

See also:: SetDefaultTransportMode()

int GetGlobalLinkId ( char * keyword )

retrieves the link ID for a globals link

Parameters:

keyword is the globals keyword passed as an argument to recvNetGlobal().

Returns:: the link table ID for the globals link or a negative TINE error code.

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().

Parameters:

cbId	is the callback ID passed as an argument to recvNetGlobalEx().

Returns:: the link table ID for the globals link or a negative TINE error code.

int GetGlobalsHeartbeat ( void )

gets the heartbeat (in seconds) during which time no 'timeout' messages will be sent to a globals dispatch routine (client-side)

See also:: SetGlobalsHeartbeat(), recvNetGlobal().

int GetGlobalsTableCapacity ( void )

gets the globals table capacity (client-side)

See also:: SetGlobalsTableCapacity(), recvNetGlobal().

double GetGlobalsTimeStamp ( int linkId )

Returns the timestamp of the globals keyword with the given link ID.

Parameters:

linkId the globals link index for which the timestamp is desired.

See also:: recvNetGlobal() or recvNetGlobalEx() and CloseNetGlobal()

GrpMember * GetGroupMemberList ( GrpTblEntry * grp )

Returns a linked list of the group members for the callback group supplied.

Parameters:

grp	is a reference to the group table entry (GrpTblEntry *) whose member list is desired.

Returns:: a reference to a linked list of the group members for the callback group supplied

See also:: GetCallbackGroup(), GrpTblEntry, GrpMember

References feclog(), and PutDataTimeStamp().

int GetLastGlobalDataSize ( int id )

Returns the most recent data size of the global link index supplied.

Parameters:

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).

Returns:: The most recent data size of the global link index supplied

See also:: GetLastGlobalDataSizeFromCallbackId()

int GetLastGlobalDataSizeFromCallbackId ( int id )

Returns the most recent data size of the global link callback id supplied.

Parameters:

i	is the global link callback id for which the data size is desired.

Returns:: The most recent data size of the global link callback id supplied

Note:: This is a best effort to determine the propery entry table for the callback id supplied as an argument. It is the duty of the caller to manage a unique set of callback ids for his application.

See also:: GetLastGlobalDataSize()

char* GetLastLinkError	(	short	cc,
		char *	errstr
	)

The error string associated with the input error number.

Parameters:

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]").

Returns:: The error string associated with the input error number.

See also:: GetCompletionStatus()

Example:

char errstr[256];

if ((cc=ExecLink(devname,"ECHO",&dout,&din,CA_READ)) != 0) 
{
  printf(“ExecLink : %s\n”,GetLastLinkError(cc,errstr));
}

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.

Parameters:

id	(input) is the callback id of the link for which the current completion code is desired.

Returns:: NULL or the reference pointer supplied in the call to AttachLinkEx2().

See also:: AttachLinkEx2()

char* GetLinkName ( int i )

Returns the full link name associated with the input link index.

Parameters:

idis	the link index of the link for which the link name is desired.

Returns:: The full link name as "/<Context>/<Server>/<Device>[<Property>]", or "link not found" if the callback id is invalid.

char* GetLinkNameFromCallbackId ( int id )

Returns the full link name associated with the callback identifier supplied.

Parameters:

id	is the callback id of the link for which the link name is desired.

Returns:: The full link name as "/<Context>/<Server>/<Device>[<Property>]", or "link not found" if the callback id is invalid.

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.

Parameters:

linkId is the connection table link id (returned from a call to AttachLink()).

Returns:: the current queue depth setting for the link in question.

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.

Returns:: toleranceInSeconds is the maximum time difference allowed before setting the data timestamp offset.

See also:: setSynchronizationTolerance()

int GetSystemDataStamp ( int linkId )

Gets the global 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.

Parameters:

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.

Returns:: The data stamp if the call succeeds or -1.

int GetSystemDataStampFromCallbackId ( int id )

Gets the global 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.

Parameters:

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.

Returns:: The data stamp if the call succeeds or -1.

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).

Returns:: The currently registered system cycle delay (default = 0 msec).

See also:: SetSystemStampDelay

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.

Returns:: The currently registered system cycle offset (default = 0).

See also:: SetSystemStampOffset

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.

Parameters:

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.

Returns:: The data transfer flag.

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.

Parameters:

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.

Returns:: The data transfer flag.

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.

Parameters:

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

Returns:: 0 if successful, otherwise a TINE completion code which can be interpreted by a call to GetLastLinkError().

See also:: AttachLink(), AttachLinkEx(), DTYPE

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.

Parameters:

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().

Returns:: A positive link handle if successful, otherwise the negative of a TINE completion code which can be interpreted by a call to GetLastLinkError().

See also:: recvNetGlobalEx(), sendNetGlobal(), DTYPE

Example:

#include "tine.h"

...
char errstr[256];

NGenergyID = recvNetGlobal("HPENERGY",&dout,showenergy);
if (NGenergyID < 0)
{
  printf("NETGLOBAL : %s\n",GetLastLinkError(-NgenergyID,errstr));
}

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.

Parameters:

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

Returns:: A positive link handle if successful, otherwise the negative of a TINE completion code which can be interpreted by a call to GetLastLinkError().

See also:: recvNetGlobal(), sendNetGlobal(), DTYPE

Example:

#include "tine.h"

#define ENERGY_ID 1
#define CURRENT_ID 2
void globalsCallback(int id,int cc)
{
  switch (id)
  {
    case ENERGY_ID:
      // do something with the incoming energy
      break;
    case CURRENT_ID:
      // do something with the incoming beam current
      break;
    ...
  }
}
...

char errstr[256];
NGenergyID = recvNetGlobalEx("HPENERGY",&dout,globalsCallback,ENERGY_ID);
if (NGenergyID < 0)
{
  printf("NETGLOBAL : %s\n",GetLastLinkError(-NgenergyID,errstr));
}

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.

Parameters:

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.

Returns:: A positive link handle if successful, otherwise the negative of a TINE completion code which can be interpreted by a call to GetLastLinkError().

See also:: recvNetGlobal(), sendNetGlobal(), DTYPE

Example:

#include "tine.h"

#define ENERGY_ID 1
#define CURRENT_ID 2
typedef void (*REFFCN)(void);
void globalsCallback(int id,int cc,void *ref)
{
  switch (id)
  {
    case ENERGY_ID:
      // do something with the incoming energy
      break;
    case CURRENT_ID:
      // do something with the incoming beam current
      break;
    ...
  }
  if (cc == 0)
  { // link status is okay -> forward the info down the line
    ((REFFCN)ref)();
  }
}
...

void forwardLink(void)
{
  // do something special here
}
int startGlobalsLink(void)
{
  char errstr[256];
  NGenergyID = recvNetGlobalEx2("HPENERGY",&dout,globalsCallback,ENERGY_ID,(void *)forwardLink);
  if (NGenergyID < 0) 
  {
    printf("NETGLOBAL : %s\n",GetLastLinkError(-NgenergyID,errstr));  
  }
}

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'.

Parameters:

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.

Returns:: 0 if successful, otherwise a TINE completion code

Example:

#define EQMTAG "TSTEQM"
#define PRP_CYCLE      1
int cycleNumber = 0;
int tsteqm(char *devName,char *devProperty,DTYPE *dout, DTYPE *din,short access);
void tstinit(void);
void tstbkg(void);

typedef void (*HDWIOFCNP)(int);
void hdwIoCycle(int cycle)
{
  /* read relevant hardware (here we just print something out) */
  printf("read hardware for cycle %d\n",cycle);
}
void onCycleTrigger1(int cycle,int cc,void *ref)
{
  printf("received cycle %d <%d>\n",cycle,cc);
  cycleNumber = cycle;
}
void onCycleTrigger2(int cycle,int cc,void *ref)
{ /* call the referenced function */
  if (cc == 0) ((HDWIOFCNP)ref)(cycle);
}
void PreSystemInit(void)
{
  SetSystemUseDataProtection(TRUE);
  SetPacketMTU(64000);
  RegisterFecInformation("CYCCATCH.8","TST","TEST","Cycle catcher tester","My Office","none","me",8);
}
void PostSystemInit(void)
{
  /* register the equipment module: */
  RegisterEquipmentModule("CycleCatcher",EQMTAG,1,tsteqm,tstinit,tstbkg,100,NULL);
  /* register a cycle trigger function with no scheduling and no reference */
  RegisterCycleTriggerFunction(onCycleTrigger1,EQMTAG,NULL,NULL);
  /* register another cycle trigger function with a scheduled property and a reference to another function */
  RegisterCycleTriggerFunction(onCycleTrigger2,EQMTAG,"CycleNumber",(void *)hdwIoCycle);
}
void tstbkg(void)
{
}
void tstinit(void)
{
  int cc = 0;
  DTYPE dout;

  memset(&dout,0,sizeof(DTYPE));
  dout.dFormat = CF_INT32;
  dout.dArrayLength = 1;
  RegisterPropertyInformation(EQMTAG,"CycleNumber",&dout,NULL,CA_READ,AT_SCALAR,0,"current system cycle number",PRP_CYCLE,NULL);
  RegisterDeviceName(EQMTAG,"keyword",0);
}
int tsteqm(char *devName,char *devProperty,DTYPE *dout, DTYPE *din,short access)
{
  int devnr,prpid,cc;

  devnr = GetDeviceNumber(EQMTAG,devName);
  prpid = GetPropertyId(EQMTAG,devProperty);

  switch (prpid)
  {
    case PRP_CYCLE:
      if (access&CA_WRITE) return illegal_read_write;
      if ((cc=putValuesFromLong(dout,&cycleNumber,1)) != 0) return cc;
      return 0;
    default:
      break;
  }
  return illegal_property;
}

See also:: UnregisterCycleTriggerFunction

References feclog().

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.

Parameters:

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).

Returns:: a tine return code.

Example:

  
  /* acquire a persistent lock (persistent lock will ignore the duration parameter) */
  cc = SetAccessLock("DESY2","PiControls",LOCK_PERSISTENT,0);
  if (cc != 0) dbglog("SetAccessLock : %s",erlst[cc]);
  
  /* do something important ... */

  /* release the lock */
  FreeAccessLock("DESY2","PiControls");

See also:: FreeAccessLock(), GetAccessLockInformation(), GetAccessLockStatus()

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.

Note:: A contract is deemed 'identical' if the device name and property parameters are identical and the input and output data objects have identical characteristics (including the data tag, format, and size). The link acquisition mode will be adjusted to the proper hierarchy level according to link dependencies. Likewise, the link polling rate will also be adjusted according to the link dependencies.; The default setting is 'TRUE'. Under some circumstances it could be desireable to set the value to FALSE (e.g. the central archiver sets this to FALSE).

Parameters:

value is the desired setting. (default = TRUE).

See also:: GetAllowDependentLinks()

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.

Parameters:

value is the value of the retry flag.

See also:: GetAlwaysRetry()

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).

Parameters:

value is the desired setting of this flag (default = TRUE)

See also:: GetAutoLinkErrorAlarms

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.

Parameters:

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.

Parameters:

depth is the requested queue depth (values less than zero are ignored). A value of zero implies no queue will be maintained.

void SetConnectionTableCapacity ( int value )

Sets 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.

Parameters:

value is the requested Client API Callsonnection table size

Default: 1000 (Or #define CLIENTLIST_CAPACITY in project.def)

See also:: GetConnectionTableCapacity()

void SetDefaultTransportMode ( int value )

Sets the default TINE transport mode used in client-side links.

Parameters:

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.

See also:: GetDefaultTransportMode()

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)

Parameters:

value is the desired heartbeat in seconds (default: 60 seconds)

See also:: GetGlobalsHeartbeat(), recvNetGlobal().

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).

Parameters:

value is the desired table size.

Note:: this call must be made prior to the client-side registration for any network global in order to have any effect.

See also:: GetGlobalsTableCapacity(), recvNetGlobal().

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.

Parameters:

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.

Parameters:

value is the desired link watchdog polling interval in milliseconds.

References feclog().

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.

Parameters:

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.

Returns:: 0 if successful, otherwise a TINE completion code which can be interpreted by a call to GetLastLinkError().

See also:: AttachLink(), AttachLinkEx()

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.

Parameters:

value determines whether heartbeat notification will be suppressed or not Default: FALSE

See also:: SetNotificationTolerance()

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.

Parameters:

toleranceInSeconds is the maximum time difference allowed before setting the data timestamp offset. (Default: 0.5 seconds)

See also:: getSynchronizationTolerance()

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).

Parameters:

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).

See also:: GetSystemStampDelay

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.

Parameters:

cycleOffset is the desired cycle offset (counts) to be applied to the incoming cycle number from the registered CYCLER. (Default = 0).

See also:: GetSystemStampOffset

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.

Parameters:

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.

Returns:: 0 if successful, otherwise a TINE completion code

See also:: RegisterCycleTriggerFunction

References feclog().

Variable Documentation

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.

Note:: This is not thread safe. In multithreaded applications, use GetCompletionDataSize() or GetCompletionDataSizeFromCallbackId()

See also:: GetCompletionDataSize(), GetCompletionDataSizeFromCallbackId()

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.

Note:: This is not thread safe. In multithreaded applications, use GetCompletionDataType() or GetCompletionDataTypeFromCallbackId()

See also:: GetCompletionDataType(), GetCompletionDataTypeFromCallbackId()

Referenced by GetCompletionDataType().

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 ExecLinkEx(), and GetCompletionSource().

int MaxNumConnections = 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)

See also:: SetConnectionTableCapacity(), GetConnectionTableCapacity()

Functions

Variables

Detailed Description

Function Documentation

Variable Documentation