TINE buffered server documentation. More...

#include "tine.h"
#include "listener.h"

Functions
int	AttachServer (char srvExportName, char srvEQPName, int ndevices)
	Attaches the TINE server according to the input given.
int	AttachServerEx (char srvExportName, char srvEQPName, int ndevices, void(*tmr)(void), int tmrInterval)
	Attaches the TINE server according to the input given.
int	GetInputDeviceNumber (void)
	Returns the device number associated with the WRITE call.
int	getNotifiedProperty (char *prpName)
	Retrieves the property which caused the notifier to be called.
int	getNotifiedPropertyAndDevice (char prpName, char devName)
	Retrieves the property which caused the notifier to be called.
int	hasInputChanged (char *prpName)
	Checks whether there are new input data for the given property.
int	pullBufferedData (char prpName, char devName, BYTE *prpData, long prpSiz)
	Retrieves the contents of the input data buffer associated with the given property.
int	pushBufferedData (char prpName, char devName, BYTE *prpData, long prpSiz, int prpSchedule)
	Refreshes the contents of the data buffer associated with the given property.
int	RegisterBufferedDeviceName (char devName, int devNr, char devRdr, char *devDesc)
	Registers a device with the current device server.
int	RegisterBufferedDeviceNameEx (char devName, int devNr, int devMask, float zPos, char devRdr, char devDesc, char devLocation)
	Registers a device with the current device server. (extended call).
int	RegisterBufferedProperty (char prpName, long prpInSiz, short prpInFmt, long prpOutSiz, short prpOutFmt, float prpMax, float prpMin, char prpEgu, short access, char *prpDsc)
	Registers a property with the current device server.
int	RegisterBufferedPropertyEx (char prpName, long prpInSiz, short prpInFmt, long prpOutSiz, short prpOutFmt, float prpMax, float prpMin, char prpEgu, short access, char *prpDsc, int prpId)
	Registers a property with the current device server. (extended call).
int	RegisterBufferedPropertyEx2 (char prpName, long prpInSiz, short prpInFmt, char prpInTag, long prpOutSiz, short prpOutFmt, char prpOutTag, float prpMax, float prpMin, char prpEgu, short access, char *prpDsc, int prpId, int arrayType, int rowLength)
	Registers a property with the current device server. (doubly extended call).
int	RegisterServerCallback (char prpName, int(cb)(void))
	Registers a callback routine to be called when a WRITE access property is called.
int	RegisterServerNotifier (char prpName, void(nf)(int))
	Registers a Notifier routine to be called when a WRITE access property is called.
int	RegisterServerNotifierEx (char prpName, void(nf)(int), int nid)
	Registers a Notifier routine to be called when a WRITE access property is called (extended call).
int	SetBufferedDataSize (char *prpName, int dataSiz)
	Establishes the maximum returned array length for the target property.

Detailed Description

TINE buffered server documentation.

Function Documentation

int AttachServer	(	char *	srvExportName,
		char *	srvEqmName,
		int	ndevices
	)

Attaches the TINE server according to the input given.

Parameters:

srvExportName	is the desired export name. If this is omitted (i.e. a zero-length string is passed, then the export name must be obtained from an associated 'exports.csv' in the local FEC database repository.
srvEqmName	is the desired local equipment module name. If this is omitted (i.e. a zero-length string is passed, then the local equipment module name is extracted from an associated 'exports.csv' in the local FEC database repository.
ndevices	is the number of devices (instances) associated with this device server. If this is omitted (i.e. 0 is passed), then the number of devices is extracted from an associated 'exports.csv' in the local FEC database repository.

A call to AttachServerEx() or AttachServer() serves to initialize the device server. It is analogous to setting the server ActiveX control's enabled property to 'true', where the ActiveX interface is concerned. Theoretically, you can call AttachServer() with all 'NULL' parameters, in which case all registration information is obtained from the 'exports.csv' file (see Server Startup csv-Files. Note however, that if you take this strategy, you should take care to avoid a lock-out situation regarding the name resolution. Namely, if all initialization names are to reside in 'fecid.csv' (FEC name) and 'exports.csv' (device server name, local equipment module name, and properties) then the fecid.csv should not make use of an 'Export_Name' column or a 'Local_Name' column. That is, the fecid.csv file should only contain one entry, referring to the server process in question. In cases where more than one FEC process are running on the same computer, each process should have its own fecid.csv in its working directory when the export.csv file cannot make use of an 'Export_Name' column in order to latch the appropriate device server. Of course, if AttachServer() provides an 'Export Name' in the first parameter, then there is no ambiguity.

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

Example: Attach to server and set the server's export name (requires exports.csv file to set the local equipment module name and number of modules):

int modeCb(void)
{
  if (hasInputChanged("MODE"))
  {
    int cc, val;
    int nr = GetInputDeviceNumber();
    char dev[DEVICE_NAME_SIZE];
    sprintf(dev,"#%d",nr);
    if ((cc = pullBufferedData("MODE", dev, &val, 1)) != 0) return cc;
    // maybe do some range checking, etc. and decide to accept or reject ...
    // push the value back if accepted ...
    if ((cc = pushBufferedData("MODE", dev, &val, 1, FALSE)) != 0) return cc;
  }
}

void init(void)
{
  int cc;

  if ((cc = AttachServer("BUFSINE","",0)) != 0) 
    printf("could not attach to server database: %d\n",cc);

  if ((cc=RegisterServerCallback("MODE", modeCb)) != 0)
    printf("could not attach to handler to property MODE: %d\n",cc);

  // ...

}

Example: Attach to server and set the server's export name, local equipment module name and number of modules (does not read exports.csv file!):

int modeCb(void)
{
  if (hasInputChanged("MODE"))
  {
    int cc, val;
    int nr = GetInputDeviceNumber();
    char dev[DEVICE_NAME_SIZE];
    sprintf(dev,"#%d",nr);
    if ((cc = pullBufferedData("MODE", dev, &val, 1)) != 0) return cc;
    // maybe do some range checking, etc. and decide to accept or reject ...
    // push the value back if accepted ...
    if ((cc = pushBufferedData("MODE", dev, &val, 1, FALSE)) != 0) return cc;
  }
}

void init(void)
{
  int cc;

  if ((cc = AttachServer("BUFSINE","BUFEQM",100)) != 0) 
    printf("could not attach to server database: %d\n",cc);

  if ((cc=RegisterServerCallback("MODE", modeCb)) != 0)
    printf("could not attach to handler to property MODE: %d\n",cc);

  // ...

}

int AttachServerEx	(	char *	srvExportName,
		char *	srvEqmName,
		int	ndevices,
		void(*)(void)	tmr,
		int	tmrInterval
	)

Attaches the TINE server according to the input given.

Parameters:

srvExportName	is the desired export name. If this is omitted (i.e. a zero-length string is passed, then the export name must be obtained from an associated 'exports.csv' in the local FEC database repository.
srvEqmName	is the desired local equipment module name. If this is omitted (i.e. a zero-length string is passed, then the local equipment module name is extracted from an associated 'exports.csv' in the local FEC database repository.
ndevices	is the number of devices (instances) associated with this device server. If this is omitted (i.e. 0 is passed), then the number of devices is extracted from an associated 'exports.csv' in the local FEC database repository.
tmr	is a backgound task which should be called by the TINE engine on a regular basis (timer interval determined by the 5th input parameter). The task function should have the prototype void (*tmr)(void);
tmrInterval	is the timer interval in milliseconds which determines how often the timer backgound task will be called.

A call to AttachServerEx() or AttachServer() serves to initialize the device server. It is analogous to setting the server ActiveX control's enabled property to 'true', where the ActiveX interface is concerned. Theoretically, you can call AttachServer() with all 'NULL' parameters, in which case all registration information is obtained from the 'exports.csv' file (see Server Startup csv-Files. Note however, that if you take this strategy, you should take care to avoid a lock-out situation regarding the name resolution. Namely, if all initialization names are to reside in 'fecid.csv' (FEC name) and 'exports.csv' (device server name, local equipment module name, and properties) then the fecid.csv should not make use of an 'Export_Name' column or a 'Local_Name' column. That is, the fecid.csv file should only contain one entry, referring to the server process in question. In cases where more than one FEC process are running on the same computer, each process should have its own fecid.csv in its working directory when the export.csv file cannot make use of an 'Export_Name' column in order to latch the appropriate device server. Of course, if AttachServer() provides an 'Export Name' in the first parameter, then there is no ambiguity.

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

Example: Attach to server and set the server's export name (requires exports.csv file to set the local equipment module name and number of modules):

int modeCb(void)
{
  if (hasInputChanged("MODE"))
  {
    int cc, val;
    int nr = GetInputDeviceNumber();
    char dev[DEVICE_NAME_SIZE];
    sprintf(dev,"#%d",nr);
    if ((cc = pullBufferedData("MODE", dev, &val, 1)) != 0) return cc;
    // maybe do some range checking, etc. and decide to accept or reject ...
    // push the value back if accepted ...
    if ((cc = pushBufferedData("MODE", dev, &val, 1, FALSE)) != 0) return cc;
  }
}

void init(void)
{
  int cc;

  if ((cc = AttachServer("BUFSINE","",0)) != 0) 
    printf("could not attach to server database: %d\n",cc);

  if ((cc=RegisterServerCallback("MODE", modeCb)) != 0)
    printf("could not attach to handler to property MODE: %d\n",cc);

  // ...

}

Example: Attach to server and set the server's export name, local equipment module name and number of modules (does not read exports.csv file!):

int modeCb(void)
{
  if (hasInputChanged("MODE"))
  {
    int cc, val;
    int nr = GetInputDeviceNumber();
    char dev[DEVICE_NAME_SIZE];
    sprintf(dev,"#%d",nr);
    if ((cc = pullBufferedData("MODE", dev, &val, 1)) != 0) return cc;
    // maybe do some range checking, etc. and decide to accept or reject ...
    // push the value back if accepted ...
    if ((cc = pushBufferedData("MODE", dev, &val, 1, FALSE)) != 0) return cc;
  }
}

void init(void)
{
  int cc;

  if ((cc = AttachServer("BUFSINE","BUFEQM",100)) != 0) 
    printf("could not attach to server database: %d\n",cc);

  if ((cc=RegisterServerCallback("MODE", modeCb)) != 0)
    printf("could not attach to handler to property MODE: %d\n",cc);

  // ...

}

int GetInputDeviceNumber ( void )

Returns the device number associated with the WRITE call.

This call can be made inside the server's callback routine along with 'hasInputChanged' in order to ascertain which device was 'set'.

Returns:: The device number (obtained from the registered device name) used in the call.

Example:

int getNotifiedProperty ( char * prpName )

Retrieves the property which caused the notifier to be called.

Parameters:

prpName (output) is the property name which caused the notifer to be called

Returns:: 0 upon success otherwise a TINE return code

int getNotifiedPropertyAndDevice	(	char *	prpName,
		char *	devName
	)

Retrieves the property which caused the notifier to be called.

Parameters:

prpName (output) is the property name which caused the notifer to be called

Returns:: 0 upon success otherwise a TINE return code

int hasInputChanged ( char * prpName )

Checks whether there are new input data for the given property.

Parameters:

prpName is the property name whose input data buffer is to be checked for changes.

Returns:: 0 (False) if the input data have not changed or -1 (True) if there are new input data to be acquired by calling PullBufferedData().

Example:

int modeCb(void)
{
  if (hasInputChanged("MODE"))
  {
    int cc, val;
    int nr = GetInputDeviceNumber();
    char dev[DEVICE_NAME_SIZE];
    sprintf(dev,"#%d",nr);
    if ((cc = pullBufferedData("MODE", dev, &val, 1)) != 0) return cc;
    // maybe do some range checking, etc. and decide to accept or reject ...
    // push the value back if accepted ...
    if ((cc = pushBufferedData("MODE", dev, &val, 1, FALSE)) != 0) return cc;
  }
}

void init(void)
{
  int cc;

  if ((cc = AttachServer("BUFSINE","",0)) != 0) 
    printf("could not attach to server database: %d\n",cc);

  if ((cc=RegisterServerCallback("MODE", modeCb)) != 0)
    printf("could not attach to handler to property MODE: %d\n",cc);

  // ...

}

int pullBufferedData	(	char *	prpName,
		char *	devName,
		BYTE *	prpData,
		long	prpSiz
	)

Retrieves the contents of the input data buffer associated with the given property.

Parameters:

prpName	is the property name from whose input buffer the associated data are to be read.
devName	is the device name giving the starting address i.e. entry point into the property's buffer from which the associated data are to be read.
prpData	is a reference to the data buffer into which the incoming data should be read (pulled).
prpSiz	is the number of elements to be read into the property's data buffer.

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

Example:

int modeCb(void)
{
  if (hasInputChanged("MODE"))
  {
    int cc, val;
    int nr = GetInputDeviceNumber();
    char dev[DEVICE_NAME_SIZE];
    sprintf(dev,"#%d",nr);
    if ((cc = pullBufferedData("MODE", dev, &val, 1)) != 0) return cc;
    // maybe do some range checking, etc. and decide to accept or reject ...
    // push the value back if accepted ...
    if ((cc = pushBufferedData("MODE", dev, &val, 1, FALSE)) != 0) return cc;
  }
}

void init(void)
{
  int cc;

  if ((cc = AttachServer("BUFSINE","",0)) != 0) 
    printf("could not attach to server database: %d\n",cc);

  if ((cc=RegisterServerCallback("MODE", modeCb)) != 0)
    printf("could not attach to handler to property MODE: %d\n",cc);

  // ...

}

int pushBufferedData	(	char *	prpName,
		char *	devName,
		BYTE *	prpData,
		long	prpSiz,
		int	prpSchedule
	)

Refreshes the contents of the data buffer associated with the given property.

Parameters:

prpName	is the property name into whose buffer the associated data are to be written
devName	is the device name giving the starting address i.e. entry point into the property's buffer into which the associated data are to be written
prpData	is a reference to the data to be written (pushed) into the property's data buffer.
prpSiz	is the number of elements to be written into the property's data buffer.
prpSchedule	is the schedule 'flag' determining whether the property is to be scheduled immediately ('true') or not. If prpSchedule is >= 0x10 (16) and < 0x1000 then it is assumed to provide the specific scheduling 'scope' (some combination of CA_ALARM - 0x10, CA_HIST - 0x20, CA_NETWORK - 0x200). If prpSchedule < 0x10 then it treated as a simple boolean which schedules the property(ies) for all subsystems. If prpSchedule > 0x1000 it is assumed to provide a user-assigned UTC timestamp to the data in question (and the property is not scheduled in this case).

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

Example:

// call routine tmr regularly in the background ...
int tmr(void)
{
  int i, n;
  float vals[100];
  
  for (n=0; n<10; n++)
  { // push a sine curve with noise into each of the 10 registered devices ...
    for (i=0; i<100; i++) vals[i] = 500.0 + 300 * sin(i*6.2832/50) + 20.0 * (float)rand()/RAND_MAX;
    sprintf(dev,"#%d",n);
    pushBufferedData("Sine", dev, vals, 100, FALSE);
  }
}

int RegisterBufferedDeviceName	(	char *	devName,
		int	devNr,
		char *	devRdr,
		char *	devDesc
	)

Registers a device with the current device server.

It many cases it is easiest to supply local configuration files with all of the property and device information relevant for a buffered server. In such cases there are remarkably few API calls necessary to provide a fully functioning device server.

On the other hand, if it is necessary to register additional devices this registration call can be used.

Parameters:

devName	is the device name (up to 64 characters)
devNr	is the associated device number
devRdr	is an optional redirection string (if the device is to be redirected to another server
devDesc	is an optional description of the device.

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

int RegisterBufferedDeviceNameEx	(	char *	devName,
		int	devNr,
		int	devMask,
		float	zPos,
		char *	devRdr,
		char *	devDesc,
		char *	devLocation
	)

Registers a device with the current device server. (extended call).

It many cases it is easiest to supply local configuration files with all of the property and device information relevant for a buffered server. In such cases there are remarkably few API calls necessary to provide a fully functioning device server.

On the other hand, if it is necessary to register additional devices this registration call can be used.

Parameters:

devName	is the device name (up to 64 characters)
devNr	is the associated device number
devMask	is the associated device mask
zPos	is the associated Z or longitudinal position of the device
devRdr	is an optional redirection string (if the device is to be redirected to another server
devDesc	is an optional description of the device.
devLocation	is an optional text specifying the physical locatio of the device.

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

int RegisterBufferedProperty	(	char *	prpName,
		long	prpInSiz,
		short	prpInFmt,
		long	prpOutSiz,
		short	prpOutFmt,
		float	prpMax,
		float	prpMin,
		char *	prpEgu,
		short	access,
		char *	prpDsc
	)

Registers a property with the current device server.

It many cases it is easiest to supply local configuration files with all of the property and device information relevant for a buffered server. In such cases there are remarkably few API calls necessary to provide a fully functioning device server.

On the other hand, if it is necessary to register additional properties this registration call can be used.

Parameters:

prpName	is the propery name (up to 64 characters, but try to use 32 or less).
prpInSiz	is the maximum input data size accepted by the property
prpInFmt	is the data format of the input data
prpOutSiz	is the maximum output data size accepted by the property
prpOutFmt	is the data format of the output data
prpMax	is the nominal maximum value of the property data
prpMin	is the nominal minimum value of the property data
prpEgu	is the engineering unit of the property data
access	is the access accepted by the property (e.g. CA_READ and/or CA_WRITE).
prpDsc	is the description of the property.

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

int RegisterBufferedPropertyEx	(	char *	prpName,
		long	prpInSiz,
		short	prpInFmt,
		long	prpOutSiz,
		short	prpOutFmt,
		float	prpMax,
		float	prpMin,
		char *	prpEgu,
		short	access,
		char *	prpDsc,
		int	prpId
	)

Registers a property with the current device server. (extended call).

It many cases it is easiest to supply local configuration files with all of the property and device information relevant for a buffered server. In such cases there are remarkably few API calls necessary to provide a fully functioning device server.

On the other hand, if it is necessary to register additional properties this registration call can be used.

Parameters:

prpName	is the propery name (up to 64 characters, but try to use 32 or less).
prpInSiz	is the maximum input data size accepted by the property
prpInFmt	is the data format of the input data
prpOutSiz	is the maximum output data size accepted by the property
prpOutFmt	is the data format of the output data
prpMax	is the nominal maximum value of the property data
prpMin	is the nominal minimum value of the property data
prpEgu	is the engineering unit of the property data
access	is the access accepted by the property (e.g. CA_READ and/or CA_WRITE).
prpDsc	is the description of the property.
prpId	is the desired property ID (returned in a call to GetPropertyId()).

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

int RegisterBufferedPropertyEx2	(	char *	prpName,
		long	prpInSiz,
		short	prpInFmt,
		char *	prpInTag,
		long	prpOutSiz,
		short	prpOutFmt,
		char *	prpOutTag,
		float	prpMax,
		float	prpMin,
		char *	prpEgu,
		short	access,
		char *	prpDsc,
		int	prpId,
		int	arrayType,
		int	rowLength
	)

Registers a property with the current device server. (doubly extended call).

It many cases it is easiest to supply local configuration files with all of the property and device information relevant for a buffered server. In such cases there are remarkably few API calls necessary to provide a fully functioning device server.

On the other hand, if it is necessary to register additional properties this registration call can be used.

Parameters:

prpName	is the propery name (up to 64 characters, but try to use 32 or less).
prpInSiz	is the maximum input data size accepted by the property
prpInFmt	is the data format of the input data
prpOutSiz	is the maximum output data size accepted by the property
prpOutFmt	is the data format of the output data
prpMax	is the nominal maximum value of the property data
prpMin	is the nominal minimum value of the property data
prpEgu	is the engineering unit of the property data
access	is the access accepted by the property (e.g. CA_READ and/or CA_WRITE).
prpDsc	is the description of the property.
prpId	is the desired property ID (returned in a call to GetPropertyId()).
arrayType	is the array type (e.g. AT_CHANNEL, AT_TRACE) of the property
rowLength	is the row length of the property (relevant if the property delivers a double array).

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

int RegisterServerCallback	(	char *	prpName,
		int(*)(void)	cb
	)

Registers a callback routine to be called when a WRITE access property is called.

Parameters:

prpName
cb

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

Example:

int modeCb(void)
{
  if (hasInputChanged("MODE"))
  {
    int cc, val;
    int nr = GetInputDeviceNumber();
    char dev[DEVICE_NAME_SIZE];
    sprintf(dev,"#%d",nr);
    if ((cc = pullBufferedData("MODE", dev, &val, 1)) != 0) return cc;
    // maybe do some range checking, etc. and decide to accept or reject ...
    // push the value back if accepted ...
    if ((cc = pushBufferedData("MODE", dev, &val, 1, FALSE)) != 0) return cc;
  }
}

void init(void)
{
  int cc;

  if ((cc = AttachServer("BUFSINE","",0)) != 0) 
    printf("could not attach to server database: %d\n",cc);

  if ((cc=RegisterServerCallback("MODE", modeCb)) != 0)
    printf("could not attach to handler to property MODE: %d\n",cc);

  // ...

}

int RegisterServerNotifier	(	char *	prpName,
		void(*)(int)	nf
	)

Registers a Notifier routine to be called when a WRITE access property is called.

The difference between a callback and a notifier is that it is assumed that the callback completes all activity associated with the transaction while inside the callback routine. A notififier will call the notifier routine and expect the caller to call the SetBufferedCompletion() routine when the transaction is complete. This scenario is useful for development platforms such as LabView.

Parameters:

prpName	the Property name for which the notifier is in effect
nf	the notifier routine

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

Example:

int RegisterServerNotifierEx	(	char *	prpName,
		void(*)(int)	nf,
		int	nid
	)

Registers a Notifier routine to be called when a WRITE access property is called (extended call).

The difference between a callback and a notifier is that it is assumed that the callback completes all activity associated with the transaction while inside the callback routine. A notififier will call the notifier routine and expect the caller to call the SetBufferedCompletion() routine when the transaction is complete. This scenario is useful for development platforms such as LabView.

Parameters:

prpName	the Property name for which the notifier is in effect
nf	the notifier routine
nid	is the desired notifier id to be returned in the notifier supplied notifier routine.

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

int SetBufferedDataSize	(	char *	prpName,
		int	dataSiz
	)

Establishes the maximum returned array length for the target property.

A called property will return up to the registered array length of array elements, regardless of the number of values actually 'pushed' into the array. This call can be used to influence the actual number of elements returned to the caller.

A caller can always ask for an receiver fewer data elements than registered. However asking for more elements will result in a truncated call, where the number of elements returned is given by either by the registered output data length for the designated property or the buffered data size registered with this call.

Subsequent calls to PushBufferedData will automatically adjust the buffered data size according to the property size given IF the property size is greater than 1 AND there is already an existing buffered data size registered.

Setting the buffered data size to '0' will revert to the initial conditions where the registered property size determines the maximum data size to be returned.

Note:: This call can only by applied to properties which are registered to return an array of type AT_SPECTRUM.

Parameters:

prpName	is the property name into whose buffer size is to be adjusted.
dataSiz	is the maximum number of elements to be returned to a caller.

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

Functions

Detailed Description

Function Documentation