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

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

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

Private Sub init()
Dim cc As Integer, ID As Integer
Dim i As Integer, n As Integer
Dim dn As String

cc = AttachServer("BUFSINE", "", 0)

i = RegisterServerCallback("MODE", AddressOf cb)

Timer1.Enabled = True
End Sub

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!):

Private Sub init()
Dim cc As Integer, ID As Integer
Dim i As Integer, n As Integer
Dim dn As String

cc = AttachServer("BUFSINE", "BUFEQM", 100)

i = RegisterServerCallback("MODE", AddressOf cb)

Timer1.Enabled = True
End Sub

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

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

Private Sub init()
Dim cc As Integer, ID As Integer
Dim i As Integer, n As Integer
Dim dn As String

cc = AttachServer("BUFSINE", "", 0)

i = RegisterServerCallback("MODE", AddressOf cb)

Timer1.Enabled = True
End Sub

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!):

Private Sub init()
Dim cc As Integer, ID As Integer
Dim i As Integer, n As Integer
Dim dn As String

cc = AttachServer("BUFSINE", "BUFEQM", 100)

i = RegisterServerCallback("MODE", AddressOf cb)

Timer1.Enabled = True
End Sub

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:

Sub cb()
Form1.Label1.Caption = "callback was called"
If hasInputChanged("MODE") Then
  pullBufferedData "MODE", "#0", sineMode, 1
  pushBufferedData "MODE", "#0", sineMode, 1, 0
End If
End Sub

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

Example:

Sub cb()
Form1.Label1.Caption = "callback was called"
If hasInputChanged("MODE") Then
  pullBufferedData "MODE", "#0", sineMode, 1
  pushBufferedData "MODE", "#0", sineMode, 1, 0
End If
End Sub

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

Example:

Private Sub Timer1_Timer()
Dim i As Integer
Dim S(99) As Single
Static delta As Single
For i = 0 To 99
 S(i) = 500 + 300 * Sin((sineMode * delta + i * 6.2832) / 50) + 20 * Rnd
Next

pushBufferedData "SINE", "#0", S(0), 100, 0

delta = delta + 5
End Sub

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

Example:

Private Sub init()
Dim cc As Integer, ID As Integer
Dim i As Integer, n As Integer
Dim dn As String

cc = AttachServer("BUFSINE", "BUFEQM", 100)

i = RegisterServerCallback("MODE", AddressOf cb)

Timer1.Enabled = True
End Sub

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

Example:

Functions

Detailed Description

Function Documentation