TINE static listener documentation. More...

#include "project.def"

Functions
int	alsnExecLink (char devName, char devProperty, DTYPE dout, DTYPE din, short access, long timeout)
	Executes a synchronous call within an asynchronous static listener.
int	alsnExecLinkEx (char devName, char devProperty, DTYPE dout, DTYPE din, short access, long timeout, double *dTimeStamp)
	Executes a synchronous call within an asynchronous static listener.
char *	alsnGetLastLinkError (short cc, char *errstr)
	The error string associated with the input error number.
int	GetListenerTableCapacity (void)
	Gets the current setting for the maximum listener table capacity.
void	SetAllowedIdleTime (int idleTime)
	Sets the maximum time a listening link is allowed to be idle (un-read).
int	SetDefaultListenerMode (int mode)
	Sets the polling mode for any static listeners created via a call to alsnExecLink().
void	SetListenerTableCapacity (int capacity)
	Sets the maximum listener table capacity.
short	tgetDoubleArray (char fullDeviceNameAndProperty, double dataout, int buffersiz)
	Executes a synchronous call within an asynchronous static listener.
short	tgetLongArray (char fullDeviceNameAndProperty, long dataout, int buffersiz)
	Executes a synchronous call within an asynchronous static listener.
short	tgetShortArray (char fullDeviceNameAndProperty, short dataout, int buffersiz)
	Executes a synchronous call within an asynchronous static listener.
short	tgetSingleArray (char fullDeviceNameAndProperty, float dataout, int buffersiz)
	Executes a synchronous call within an asynchronous static listener.
short	tgetStringArray (char fullDeviceNameAndProperty, char dataout, int buffersiz)
	Executes a synchronous call within an asynchronous static listener.
short	tputgetAnyArray (char fullDeviceNameAndProperty, short access, short putdatafmt, void putdata, int putsiz, char puttag, short getdatafmt, void getdata, int getsiz, char gettag, double dTimeStamp)
	Executes a synchronous call within an asynchronous static listener for any type of array input/output.
short	tputgetArrayEx (char fullDeviceNameAndProperty, short access, short putdatafmt, void putdata, int putsiz, short getdatafmt, void getdata, int getsiz, double dTimeStamp)
	Executes a synchronous call within an asynchronous static listener for array input/output (extended call).

Detailed Description

TINE static listener documentation.

Function Documentation

int alsnExecLink	(	char *	devName,
		char *	devProperty,
		DTYPE *	dout,
		DTYPE *	din,
		short	access,
		long	timeout
	)

Executes a synchronous call within an asynchronous static listener.

Asynchronous/Synchronous data exchange. For query calls (for instance to obtain a property list), calls to the local history server, or calls with a timeout parameter less than 50 milliseconds, the call reverts to ExecLinkEx(), i.e. synchronous data transfer. Otherwise, the initial call starts an asynchronous static listener for the selected device name and property, polling at the rate determined by the timeout parameter. The initial call waits for the first data set to be returned before it completes. Subsequent calls retrieve data from the listener's buffer and complete immediately. If no subsequent calls are made within a 5 minute interval, the asynchronous link is cancelled.

Parameters:

devName	is the full device name (/<Context>/<Server>/<Device>) of the device to contact. For example: "/HERA/BPM/WL167".
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. This should refer to a DTYPE object giving the data size, format, and tag (if any) and reference to the data of the output data set.
din	is a pointer to the input data set, that is, the data set to be sent to the server from the client. This should refer to a DTYPE object giving the data size, format, and tag (if any) and reference to the data of the input data set.
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. This parameter has a particular meaning when used in the static listener routines. Namely, it is also used to determine the polling interval for the asynchronous listener which is attached to the call. You can force the call to execute synchronously without starting a listener by passing a value less than 50 for this parameter.

Returns:: 0 if successful, otherwise a TINE completion code which can be interpreted by examining RPCLastErrorString.

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

Asynchronous/Synchronous data exchange. For query calls (for instance to obtain a property list), calls to the local history server, or calls with a timeout parameter less than 50 milliseconds, the call reverts to ExecLinkEx(), i.e. synchronous data transfer. Otherwise, the initial call starts an asynchronous static listener for the selected device name and property, polling at the rate determined by the timeout parameter. The initial call waits for the first data set to be returned before it completes. Subsequent calls retrieve data from the listener's buffer and complete immediately. If no subsequent calls are made within a 5 minute interval, the asynchronous link is cancelled.

Parameters:

devName	is the full device name (/<Context>/<Server>/<Device>) of the device to contact. For example: "/HERA/BPM/WL167".
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. This should refer to a DTYPE object giving the data size, format, and tag (if any) and reference to the data of the output data set.
din	is a pointer to the input data set, that is, the data set to be sent to the server from the client. This should refer to a DTYPE object giving the data size, format, and tag (if any) and reference to the data of the input data set.
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. This parameter has a particular meaning when used in the static listener routines. Namely, it is also used to determine the polling interval for the asynchronous listener which is attached to the call. You can force the call to execute synchronously without starting a listener by passing a value less than 50 for this parameter.

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

See also:: DTYPE

References alsnExecLinkEx().

int alsnExecLinkEx	(	char *	devName,
		char *	devProperty,
		DTYPE *	dout,
		DTYPE *	din,
		short	access,
		long	timeout,
		double *	dTimeStamp
	)

Executes a synchronous call within an asynchronous static listener.

Asynchronous/Synchronous data exchange. For query calls (for instance to obtain a property list), calls to the local history server, or calls with a timeout parameter less than 50 milliseconds, the call reverts to ExecLinkEx(), i.e. synchronous data transfer. Otherwise, the initial call starts an asynchronous static listener for the selected device name and property, polling at the rate determined by the timeout parameter. The initial call waits for the first data set to be returned before it completes. Subsequent calls retrieve data from the listener's buffer and complete immediately. If no subsequent calls are made within a 5 minute interval, the asynchronous link is cancelled.

Parameters:

devName	is the full device name (/<Context>/<Server>/<Device>) of the device to contact. For example: "/HERA/BPM/WL167".
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. This should refer to a DTYPE object giving the data size, format, and tag (if any) and reference to the data of the output data set.
din	is a pointer to the input data set, that is, the data set to be sent to the server from the client. This should refer to a DTYPE object giving the data size, format, and tag (if any) and reference to the data of the input data set.
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. This parameter has a particular meaning when used in the static listener routines. Namely, it is also used to determine the polling interval for the asynchronous listener which is attached to the call. You can force the call to execute synchronously without starting a listener by passing a value less than 50 for this parameter.
dTimeStamp	will be filled with the data time stamp corresponding to the requested data.

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

See also:: DTYPE

Referenced by alsnExecLink().

char* alsnGetLastLinkError	(	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.

int GetListenerTableCapacity ( void )

Gets the current setting for the maximum listener table capacity.

The table of active static listeners has a maximum capacity determined by the given input parameter (default = 5000). New (READ) link targets will acquire an available 'slot' in the table and remain in an 'active' listening state so long as the desired link target is read out within the alloted 'deadband' of 5 minutes. If no readout by the application has occured within 5 minutes of the assignment within the listener table, then the link is closed and the table entry is marked as available. An application needing 'many' simultaneous active links should weigh this variable's setting with the needs of the application.

Returns:: the current setting for the maximum listener table capacity.

See also:: SetListenerTableCapacity()

void SetAllowedIdleTime ( int idleTime )

Sets the maximum time a listening link is allowed to be idle (un-read).

Parameters:

idleTime is the allowed time in seconds a listening link can be active but un-read (un-used) by the application (default = 300 seconds).

Note:: the environment variable TINE_LISTENER_IDLE_TIME can also be used to set the value.

int SetDefaultListenerMode ( int mode )

Sets the polling mode for any static listeners created via a call to alsnExecLink().

The polling mode to be used in establishing an asynchronous static listener is not a input parameter to the api call alsnExecLink(). Instead the polling mode which is applied is determined by the current value of the default listener mode. (CM_POLL upon startup). In any case the CM_WAIT flag is applied the the poll mode so that the synchronous call alsnExecLink() does not return until the initial call has completed.

Parameters:

mode	is the desired default polling mode, i.e. one of CM_POLL or CM_REFRESH (possibly ORed with CM_CONNECT or CM_NETWORK for instance). Setting the default mode to CM_SINGLE or CM_CANCEL makes no sense in the context of a static listener.

Returns:: The current default polling mode to be applied to a static listener.

void SetListenerTableCapacity ( int capacity )

Sets the maximum listener table capacity.

The table of active static listeners has a maximum capacity determined by the given input parameter (default = 5000). New (READ) link targets will acquire an available 'slot' in the table and remain in an 'active' listening state so long as the desired link target is read out within the alloted 'deadband' of 5 minutes. If no readout by the application has occured within 5 minutes of the assignment within the listener table, then the link is closed and the table entry is marked as available. An application needing 'many' simultaneous active links should weigh this variable's setting with the needs of the application.

SetListenerTableCapacity() should be called prior to the initial call of any static listener routine (such as alsnExecLink(), alsnCall(), or calls which might use them: tgetArray(), etc.)

Parameters:

capacity is the desired listener table capacity (default = 5000).

Note:: One should also assure consistency within the TINE kernel settings for the total allowed number of connection table entries given by SetConnectionTableCapacity() (default = 1000). An attempt is made to coordinate these settings upon the initial use of a static listener. However if 'normal' TINE client links have been initialized prior to a listener call, then then this 'late attempt' will fail and the link table capacity will be given by the conditions in play when the 'normal' TINE links were established.

See also:: GetListenerTableCapacity()

short tgetDoubleArray	(	char *	fullDeviceNameAndProperty,
		double *	dataout,
		int	buffersiz
	)

Executes a synchronous call within an asynchronous static listener.

Asynchronous/Synchronous data exchange. This is a convenience routine which accesses alsnExecLink() explicitly for an array of double data type without data input.

Parameters:

fullDeviceNameAndProperty	is the full device name appended with the requested property parsed according to '/<Context>/<Server>/<Device>[<Property>]\<rate>'. For example: "/HERA/BPM/WL167[ORBIT.X]@500". If the '\<rate>' is omitted, a polling rate of 1000 milliseconds is assumed.
dataout	is a reference to the double array to receive the output data.
buffersiz	is the size of (i.e. number of elements in) the array.

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

See also:: alsnExecLink()

short tgetLongArray	(	char *	fullDeviceNameAndProperty,
		long *	dataout,
		int	buffersiz
	)

Executes a synchronous call within an asynchronous static listener.

Asynchronous/Synchronous data exchange. This is a convenience routine which accesses alsnExecLink() explicitly for an array of long data type without data input.

Parameters:

fullDeviceNameAndProperty	is the full device name appended with the requested property parsed according to '/<Context>/<Server>/<Device>[<Property>]\<rate>'. For example: "/HERA/BPM/WL167[ORBIT.X]@500". If the '\<rate>' is omitted, a polling rate of 1000 milliseconds is assumed.
dataout	is a reference to the long integer array to receive the output data.
buffersiz	is the size of (i.e. number of elements in) the array.

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

See also:: alsnExecLink().

short tgetShortArray	(	char *	fullDeviceNameAndProperty,
		short *	dataout,
		int	buffersiz
	)

Executes a synchronous call within an asynchronous static listener.

Asynchronous/Synchronous data exchange. This is a convenience routine which accesses alsnExecLink() explicitly for an array of short integer data type without data input.

Parameters:

fullDeviceNameAndProperty	is the full device name appended with the requested property parsed according to '/<Context>/<Server>/<Device>[<Property>]\<rate>'. For example: "/HERA/BPM/WL167[ORBIT.X]@500". If the '\<rate>' is omitted, a polling rate of 1000 milliseconds is assumed.
dataout	is a reference to the short integer array to receive the output data.
buffersiz	is the size of (i.e. number of elements in) the array.

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

See also:: alsnExecLink()

short tgetSingleArray	(	char *	fullDeviceNameAndProperty,
		float *	dataout,
		int	buffersiz
	)

Executes a synchronous call within an asynchronous static listener.

Asynchronous/Synchronous data exchange. This is a convenience routine which accesses alsnExecLink() explicitly for an array of Single (float) data type without data input.

Parameters:

fullDeviceNameAndProperty	is the full device name appended with the requested property parsed according to '/<Context>/<Server>/<Device>[<Property>]\<rate>'. For example: "/HERA/BPM/WL167[ORBIT.X]@500". If the '\<rate>' is omitted, a polling rate of 1000 milliseconds is assumed.
dataout	is a reference to the float array to receive the output data.
buffersiz	is the size of (i.e. number of elements in) the float array.

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

See also:: alsnExecLink()

short tgetStringArray	(	char *	fullDeviceNameAndProperty,
		char *	dataout,
		int	buffersiz
	)

Executes a synchronous call within an asynchronous static listener.

Synchronous data exchange. This is a convenience routine which accesses ExecLink() explicitly for an array of NAME32 data type without data input. This is useful for retrieving a list of properties or devices from a server for instance.

Parameters:

fullDeviceNameAndProperty	is the full device name appended with the requested property parsed according to '/<Context>/<Server>/<Device>[<Property>]'. For example: "/HERA/BPM/WL167[PROPERTIES]".
dataout	is a reference to the NAME32 array to receive the output data.
buffersiz	is the size of (i.e. number of elements in) the NAME32 array.

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

See also:: alsnExecLink()

short tputgetAnyArray	(	char *	fullDeviceNameAndProperty,
		short	access,
		short	putdatafmt,
		void *	putdata,
		int	putsiz,
		char *	puttag,
		short	getdatafmt,
		void *	getdata,
		int	getsiz,
		char *	gettag,
		double *	dTimeStamp
	)

Executes a synchronous call within an asynchronous static listener for any type of array input/output.

Asynchronous/Synchronous data exchange with input and output data of the data size, type, and tag specified.

Parameters:

fullDeviceNameAndProperty	is the full device name appended with the requested property parsed according to '/<Context>/<Server>/<Device>[<Property>]\<rate>'. For example: "/HERA/BPM/WL167[ORBIT.X]@500". If the '\<rate>' is omitted, a polling rate of 1000 milliseconds is assumed.
access	is the requested data access (e.g. CA_READ and/or CA_WRITE).
putdatafmt	is the input data format
putdata	is a reference to the input data
putsiz	is the input data size
puttag	is the input data tag (relevant if the input data is a tagged structure or bitfield).
getdatafmt	is the output data format
getdata	is a reference to the buffer which is to receive the output data
getsiz	is the output data size
gettag	is the output data tag (relevant if the input data is a tagged structure or bitfield).
dTimeStamp	is a reference to a double value to receive the data timestamp.

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

See also:: alsnExecLink()

short tputgetArrayEx	(	char *	fullDeviceNameAndProperty,
		short	access,
		short	putdatafmt,
		void *	putdata,
		int	putsiz,
		short	getdatafmt,
		void *	getdata,
		int	getsiz,
		double *	dTimeStamp
	)

Executes a synchronous call within an asynchronous static listener for array input/output (extended call).

Asynchronous/Synchronous data exchange with input and output data of the data size and type specified.

Parameters:

fullDeviceNameAndProperty	is the full device name appended with the requested property parsed according to '/<Context>/<Server>/<Device>[<Property>]\<rate>'. For example: "/HERA/BPM/WL167[ORBIT.X]@500". If the '\<rate>' is omitted, a polling rate of 1000 milliseconds is assumed.
access	is the requested data access (e.g. CA_READ and/or CA_WRITE).
putdatafmt	is the input data format
putdata	is a reference to the input data
putsiz	is the input data size
getdatafmt	is the output data format
getdata	is a reference to the buffer which is to receive the output data
getsiz	is the output data size
dTimeStamp	is a reference to a double value to receive the data timestamp.

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

See also:: alsnExecLink()

Functions

Detailed Description

Function Documentation