Buffered Server API File Reference

---

Detailed Description

TINE Buffered Server DLL documentation.

Functions
short	AttachServer (char *srvExportName, char *srvEQPName, int ndevices)
	Attaches the TINE server DLL according to the input given.
short	RegisterDeviceName (char *devName, short devNumber)
	Device name registration call.
short	RegisterBufferedProperty (char *prpName, long prpInSiz, short prpInFmt, long prpOutSiz, short prpOutFmt, float prpMax, float prpMin, char *prpEgu, short access, char *prpDsc)
	Buffered Property registration call.
short	pushBufferedData (char *prpName, char *devName, BYTE *prpData, long prpSiz, int prpSchedule)
	Refreshes the contents of the data buffer associated with the given property.
short	pullBufferedData (char *prpName, char *devName, BYTE *prpData, long prpSiz)
	Retrieves the contents of the input data buffer associated with the given property.
short	hasInputChanged (char *prpName)
	Checks whether there are new input data for the given property.
short	GetInputDeviceNumber (void)
	Returns the device number associated with the WRITE call.
short	RegisterServerCallback (char *prpName, void(*cb)(void))
	Registers a callback routine to be called when a WRITE access property is called.
short	RegisterServerNotifier (char *prpName, void(*nf)(int))
	Registers a Notifier routine to be called when a WRITE access property is called.

---

Function Documentation

short AttachServer	(	char *	srvExportName,
		char *	srvEQPName,
		int	ndevices
	)

Attaches the TINE server DLL according to the input given.

Visual Basic :
Declare Function AttachServer Lib "TBufferedSrv.dll" (ByVal srvExportName As String,ByVal srvEQPName As String,ByVal ndevices As Long) As Integer

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

short GetInputDeviceNumber

(

void

)

Returns the device number associated with the WRITE call.

Visual Basic:
Declare Function GetInputDeviceNumber Lib "TBufferedSrv.dll" () As Integer

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:

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

short hasInputChanged

(

char *

prpName

)

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

Visual Basic:
Declare Function hasInputChanged Lib "TBufferedSrv.dll" (ByVal prpName As String) As Integer

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

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

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

Visual Basic:
Declare Function pushBufferedData Lib "TBufferedSrv.dll" _
(ByVal prpName As String, ByVal devName As String, prpData As Any, ByVal prpSiz As Long) As Integer

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

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

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

Visual Basic:
Declare Function pushBufferedData Lib "TBufferedSrv.dll" _
(ByVal prpName As String, ByVal devName As String, _
prpData As Any, ByVal prpSiz As Long, ByVal prpSchedule As Integer) As Integer

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.

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

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

Buffered Property registration call.

Visual Basic:
Declare Function RegisterBufferedProperty Lib "TBufferedSrv.dll" _
(ByVal prpName As String, ByVal prpInSiz As Long, ByVal prpInFmt As Integer _
ByVal prpOutSiz As Long, ByVal prpOutFmt As Integer, ByVal prpMax As Single, _
ByVal prpMin As Single, ByVal prpEgu As String, ByVal access As Integer, _
ByVal prpDesc As String) As Integer

Servers can also register their 'buffered' properties through the 'exports.csv' file. If the FEC Name can be unambiguously determined at startup time (e.g. there's only one entry in the fecid.csv, or the RegisterFecName() API call is used) then a startup file with the name '<FECNAME>-exports.csv' is first accessed for registration information, where '<FECNAME>' refers the the registered FEC name. If this file does not exist then 'exports.csv' is accessed. In cases where it is not practical to register property names in this manner, a call to RegisterBufferedProperty() can be made. RegisterBufferedProperty() can be called at any time after the AttachServer() has been called.

Parameters:

	prpName	is the property name to be exported and buffered
	prpInSiz	is the number of elements to be associated with the property when input data is sent to the server.
	prpInFmt	is the TINE data type associated with input data for this property
	prpOutSiz	is the number of elements to be associated with the property when output data is requested from the server.
	prpOutFmt	is the TINE data type associated with output data for this property
	prpMax	is the maximum valid value the property is allowed to contain.
	prpMin	is the minimum valid value the property is allowed to contain.
	prpEgu	is the engineering units associated with the propery
	access	is the bit-wise combination of TINE access codes (i.e. CA_READ and CA_WRITE) which determine the read/write access characteristics of the property.
	prpDesc	is a description of the property (up to 64 characters).

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)

id = RegisterBufferedProperty("SINE", 0, CF_NULL, 100, CF_FLOAT, 1000, 0, "bozos", CA_READ, "Another Sine property")
id = RegisterBufferedProperty("TEST", 0, CF_NULL, 100, CF_INTEGER, 1000, 0, "vals", CA_READ, "Another Test property")
id = RegisterBufferedProperty("MODE", 1, CF_INTEGER, 1, CF_INTEGER, 1, 0, "", CA_READ + CA_WRITE, "Sine Mode")

For i = 0 To 99
  dn = "DEVICE" + Trim$(str$(i))
  id = RegisterDeviceName(dn, i)
Next

i = RegisterServerCallback("MODE", AddressOf cb)

Timer1.Enabled = True
End Sub

short RegisterDeviceName	(	char *	devName,
		short	devNumber
	)

Device name registration call.

Visual Basic:
Declare Function RegisterDeviceName Lib "TBufferedSrv.dll" (ByVal devName As String,ByVal devNumber As Integer) As Integer

Servers can also register their device names through a startup file. If used, the startup file is specified by the 6-char local (internal) equipment module name concatenated with "-device.csv" (e.g. "eqm1-devices.csv"). In cases where this is not practical, a call to RegisterDeviceName() can be made. RegisterDeviceName() can be called at any time after the AttachServer() has been called.

Parameters:

	devName	is the device name to be assigned to the device number passed
	devNumber	is the device number whose name is being assigned.

Note:

the devNumber passed in this call must lie between (or equal to) 0 and the number of devices set via the EqpNumberModules ActiveX control property.

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)

For i = 0 To 99
  dn = "DEVICE" + Trim$(str$(i))
  id = RegisterDeviceName(dn, i)
Next

i = RegisterServerCallback("MODE", AddressOf cb)

Timer1.Enabled = True
End Sub

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

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

Visual Basic:
Declare Function RegisterServerCallback Lib "TBufferedSrv.dll" (ByVal prpName As String, cb As Any) As Integer

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

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

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

Visual Basic:
Declare Function RegisterServerNotifier Lib "TBufferedSrv.dll" (ByVal prpName As String, cb As Any) As Integer

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:

---