Client API Calls File Reference

---

Detailed Description

TINE Client DLL documentation.

Functions
short	GETRPCDATA (short linkId, void *databuf, time_t *timestamp)
	Use with Visual Basic 3.0 or 6.0. Retrieves data associated with the given link index into the calling process.
short	GETRPCDATAEx (short linkId, void *databuf, time_t *timestamp, long *datasize)
	Use with Visual Basic 3.0 or 6.0. Retrieves data associated with the given link index into the calling process.
short	GetRPCDataAndTime (short linkId, void *databuf, double *dtimestamp, long *datasize)
	Use with Visual Basic 6.0. Retrieves data associated with the given link index into the calling process.
short	T_ATTACHLINK (char *devName, char *devprop, DTYPE *dout, DTYPE *din, short access, int pollrate, cbTLink callback, int mode)
	Use with Visual Basic 6.0. Establishes an asynchronous link with the given calling parameters.
int	AttachLink (char *devName, char *devprop, DTYPE *dout, DTYPE *din, short access, int pollrate, void(*callback)(int, int), int mode)
	Non-Pascal version (Win32 Only). Establishes an asynchronous link with the given calling parameters.
int	AttachLinkEx (char *devName, char *devProperty, DTYPE *dout, DTYPE *din, short access, int pollrate, void(*callback)(int, int), int pollmode, UINT32 callbackID)
	Non-Pascal version (Win32 Only). Establishes an asynchronous link with the given calling parameters.
short	GetRPCLastError (short cc, char *ErrString)
	Retrieves the TINE status string for the given completion code for the most recent data link if cc < 0.
void	CloseLink (int linkId)
	Non-Pascal version (Win32 Only). Closes an asynchronous link with the given link id.
short	EXECLINK (char *devName, char *devProperty, DBLK *dout, void *dataout, DBLK *din, void *datain, short access)
	Use with Visual Basic 3.0 or 6.0. Executes a synchronous link.
short	EXECLINKEx (char *devName, char *devProperty, DBLK *dout, void *dataout, DBLK *din, void *datain, short access, long timeout)
	Use with Visual Basic 3.0 or 6.0. Extended call. Executes a synchronous link with timeout parameter.
short	ExecLinkEx (char *devName, char *devProperty, DTYPE *dout, DTYPE *din, short access, long pollrate)
	Non-Pascal version (Win32 Only). Executes a synchronous link with timeout parameter.
short	ExecLink (char *devname, char *devprop, DTYPE *dout, DTYPE *din, short access)
	Non-Pascal version (Win32 Only). Executes a synchronous link.

---

Function Documentation

int AttachLink	(	char *	devName,
		char *	devprop,
		DTYPE *	dout,
		DTYPE *	din,
		short	access,
		int	pollrate,
		void(*)(int, int)	callback,
		int	mode
	)

Non-Pascal version (Win32 Only). Establishes an asynchronous link with the given calling parameters.

Asynchronous data exchange. Calls in the AttachLink() family attempt to establish the requested data link with the given calling parameters and complete immediately. If the address of the requested server can be resolved and the calling parameters are otherwise okay, the call will complete successfully and return a valid (positive) link handle. This does not mean that the requested server will respond to the request. The data and status information from the server will be returned asynchronously inside the callback routine passed in the call. In Visual Basic 3.0, there is no equivalent to this call. In the Win32 world, use T_ATTACHLINK() with Visual Basic. Use AttachLink() with interfaces which do not require the Pascal calling convention (e.g. VC++, LabView, MatLab, etc.).

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.).
	pollrate	is the polling interval in milliseconds at which the server is requested to acquire data. This value also signals a timeout if there is no notification within this amount of time plus the system heartbeat (1000 msec for POLLing links). One can use AttachLink() for asynchronous single READ and WRITE requests by specifying a pollmode of CM_SINGLE.
	callback	is a reference to the a callback function which is to be called by the TINE engine when either incoming data have arrived or an error condition has arised. This should be a pointer to a funtion with prototype void callback(int linkId, int statusCode)
	pollmode	is the TINE poll mode, i.e. one of CM_CANCEL, CM_SINGLE, CM_REFRESH, CM_POLL, which can be ORed with one of CM_BCAST, CM_NETWORK, CM_MCAST, CM_USE_ON_ERROR, CM_RETRY, CM_GROUPED, CM_CONNECT, CM_WAIT, or CM_SYNCNOTIFY. (see the discussion of Data Access Modes).

Returns:

A positive link handle ID if successful, otherwise the negative of a TINE completion code which can be interpreted by a call to GetRPCLastError(). If the TINE engine can resolve the address of the requested server and all of the calling parameters are otherwise correct the call should complete successfully. Possible errors might be 'non existent element' or 'non existent fec', etc.

Note:

This form of the call cannot be used with Visual Basic. Use T_ATTACHLINK() instead.

See also:

AttachLinkEx(), T_ATTACHLINK(), DTYPE, EXECLINK(), EXECLINKEx()

int AttachLinkEx	(	char *	devName,
		char *	devProperty,
		DTYPE *	dout,
		DTYPE *	din,
		short	access,
		int	pollrate,
		void(*)(int, int)	callback,
		int	pollmode,
		UINT32	callbackID
	)

Non-Pascal version (Win32 Only). Establishes an asynchronous link with the given calling parameters.

Asynchronous data exchange. Calls in the AttachLink() family attempt to establish the requested data link with the given calling parameters and complete immediately. If the address of the requested server can be resolved and the calling parameters are otherwise okay, the call will complete successfully and return a valid (positive) link handle. This does not mean that the requested server will respond to the request. The data and status information from the server will be returned asynchronously inside the callback routine passed in the call. This call differs from AttachLink() in that it offers an additional parameter, callbackID, whereby the caller can specify which callback identifier he would like to be passed when the callback routine is called. In Visual Basic 3.0, there is no equivalent to this call. In the Win32 world, use T_ATTACHLINK() with Visual Basic. Use AttachLinkEx() with interfaces which do not require the Pascal calling convention (e.g. VC++, LabView, MatLab, etc.).

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.).
	pollrate	is the polling interval in milliseconds at which the server is requested to acquire data. This value also signals a timeout if there is no notification within this amount of time plus the system heartbeat (1000 msec for POLLing links). One can use AttachLink() for asynchronous single READ and WRITE requests by specifying a pollmode of CM_SINGLE.
	callback	is a reference to the a callback function which is to be called by the TINE engine when either incoming data have arrived or an error condition has arised. This should be a pointer to a funtion with prototype void callback(int linkId, int statusCode)
	pollmode	is the TINE poll mode, i.e. one of CM_CANCEL, CM_SINGLE, CM_REFRESH, CM_POLL, which can be ORed with one of CM_BCAST, CM_NETWORK, CM_MCAST, CM_USE_ON_ERROR, CM_RETRY, CM_GROUPED, CM_CONNECT, CM_WAIT, or CM_SYNCNOTIFY. (see the discussion of Data Access Modes).
	callbackID	is a user-specified callback identifier, which will passed to the callback routine when it is called. Passing a '-1' for this parameter has the result of defaulting to a call to AttachLink() where the returned link identifier is used.

Returns:

A positive link handle ID if successful, otherwise the negative of a TINE completion code which can be interpreted by a call to GetRPCLastError(). If the TINE engine can resolve the address of the requested server and all of the calling parameters are otherwise correct the call should complete successfully. Possible errors might be 'non existent element' or 'non existent fec', etc.

Note:

This form of the call cannot be used with Visual Basic. Use T_ATTACHLINK() instead.

See also:

AttachLink(), T_ATTACHLINK(), DTYPE, EXECLINK(), EXECLINKEx()

void CloseLink

(

int

linkId

)

Non-Pascal version (Win32 Only). Closes an asynchronous link with the given link id.

Asynchronous data exchange. Calls in the AttachLink() family attempt to establish the requested data link with the given calling parameters and complete immediately. If the address of the requested server can be resolved and the calling parameters are otherwise okay, the call will complete successfully and return a valid (positive) link handle. The link will remain active until the client application quits or until it explicitly closes the active link using this call. In Visual Basic 3.0, there is no equivalent to this call. In the Win32 world, use CLOSERPC() with Visual Basic. Use CloseLink() with interfaces which do not require the Pascal calling convention (e.g. VC++, LabView, MatLab, etc.).

Parameters:

linkId

is the link identifier originally returned by a call to AttachLink() or AttachLinkEx().

See also:

AttachLinkEx(), AttachLink()

short ExecLink	(	char *	devname,
		char *	devprop,
		DTYPE *	dout,
		DTYPE *	din,
		short	access
	)

Non-Pascal version (Win32 Only). Executes a synchronous link.

Synchronous data exchange. Calls in the ExecLink() family do not complete until the data transfer has completed or a timeout has ensued. In the Win32 world, use EXECLINK() or T_EXECLINK() with Visual Basic. Use ExecLinkEx() with interfaces which do not require the Pascal calling convention (e.g. VC++, LabView, MatLab, etc.).

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

Returns:

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

Note:

This form of the call cannot be used with Visual Basic. ExecLink() has the same prototype as the console API call, namely it makes use of the DTYPE object (which is cumbersome to use in Visual Basic) instead of the DBLK object + data reference used in EXECLINK().

See also:

ExecLinkEx(), DTYPE

short EXECLINK	(	char *	devName,
		char *	devProperty,
		DBLK *	dout,
		void *	dataout,
		DBLK *	din,
		void *	datain,
		short	access
	)

Use with Visual Basic 3.0 or 6.0. Executes a synchronous link.

Synchronous data exchange. Calls in the ExecLink() family do 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. Use ExecLink() with interfaces which do not require the Pascal calling convention.

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 reference to the output data block, that is, the data set to be returned from the server to the client. This parameter must be present and should specifiy a format data type of CF_NULL and data size of 0 if no return data are requested.
	dataout	is a reference to the array into which the server's output data should be copied. This must be consistent with the data block parameters passed in the dout parameter, otherwise the call will fail.
	din	is a pointer to the input data block, that is, the data set to be sent to the server from the client. This parameter is required and should contain a format data type of CF_NULL and data size of 0 if no data are to be sent to the server.
	datain	is a reference to the array from which the input data should be copied prior to sending to the server. If a 0 is passed as this parameter, no data are submitted to the server. This must be consistent with the data block parameters passed in the din parameter, otherwise the call will fail.
	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 GetRPCLastError().

See also:

EXECLINKEx(), DBLK

Example:

' Inside a command button put ....

Private Sub Command1_Click()
  Dim ndevs As Integer
  Dim dout As DBLK, din As DBLK

  dout.dArrayLength = 1
  dout.dFormat = CF_SHORT
  din.dArrayLength = 0
  din.dFormat = CF_NULL
  rc = EXECLINK("/TEST/SINE/#0", "NDEVICES", dout, ndevs, din, 0, CA_READ)
  If rc <> 0 Then
    Label1.Caption = " Error : " + RPCERROR(rc)
  Else
    Label1.Caption = " There are " + Str(ndevs) + " devices"
  End If
Exit Sub

short ExecLinkEx	(	char *	devName,
		char *	devProperty,
		DTYPE *	dout,
		DTYPE *	din,
		short	access,
		long	pollrate
	)

Non-Pascal version (Win32 Only). Executes a synchronous link with timeout parameter.

Synchronous data exchange. Calls in the ExecLink() family do not complete until the data transfer has completed or a timeout has ensued. In the Win32 world, use EXECLINK() or T_EXECLINK() with Visual Basic. Use ExecLinkEx() with interfaces which do not require the Pascal calling convention (e.g. VC++, LabView, MatLab, etc.).

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

Returns:

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

Note:

This form of the call cannot be used with Visual Basic. ExecLinkEx() has the same prototype as the console API call, namely it makes use of the DTYPE object (which is cumbersome to use in Visual Basic) instead of the DBLK object + data reference used in EXECLINK().

See also:

ExecLink(), DTYPE

short EXECLINKEx	(	char *	devName,
		char *	devProperty,
		DBLK *	dout,
		void *	dataout,
		DBLK *	din,
		void *	datain,
		short	access,
		long	timeout
	)

Use with Visual Basic 3.0 or 6.0. Extended call. Executes a synchronous link with timeout parameter.

Synchronous data exchange. Calls in the ExecLink() family do 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. Use ExecLinkEx() with interfaces which do not require the Pascal calling convention.

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 reference to the output data block, that is, the data set to be returned from the server to the client. This parameter must be present and should specifiy a format data type of CF_NULL and data size of 0 if no return data are requested.
	dataout	is a reference to the array into which the server's output data should be copied. This must be consistent with the data block parameters passed in the dout parameter, otherwise the call will fail.
	din	is a pointer to the input data block, that is, the data set to be sent to the server from the client. This parameter is required and should contain a format data type of CF_NULL and data size of 0 if no data are to be sent to the server.
	datain	is a reference to the array from which the input data should be copied prior to sending to the server. If a 0 is passed as this parameter, no data are submitted to the server. This must be consistent with the data block parameters passed in the din parameter, otherwise the call will fail.
	access	is the data access mode. This can be any set 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

Returns:

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

See also:

EXECLINK(), DBLK, ExecLinkEx()

Alias: T_EXECLINK()

Example:

' Inside a command button put ....

Private Sub Command1_Click()
  Dim ndevs As Integer
  Dim dout As DBLK, din As DBLK

  dout.dArrayLength = 1
  dout.dFormat = CF_SHORT
  din.dArrayLength = 0
  din.dFormat = CF_NULL
  rc = EXECLINKEx("/TEST/SINE/#0", "NDEVICES", dout, ndevs, din, 0, CA_READ, 100)
  If rc <> 0 Then
    Label1.Caption = " Error : " + RPCERROR(rc)
  Else
    Label1.Caption = " There are " + Str(ndevs) + " devices"
  End If
Exit Sub

short GETRPCDATA	(	short	linkId,
		void *	databuf,
		time_t *	timestamp
	)

Use with Visual Basic 3.0 or 6.0. Retrieves data associated with the given link index into the calling process.

Visual Basic :
Declare Function GETRPCDATA Lib "tinecln32.dll" (ByVal linkId As Integer, databuf As Any, timestamp As Long) As Integer
Declare Function GETRPCSTRDATA Lib "tinecln32.dll" Alias "GETRPCDATA" (ByVal linkId As Integer, ByVal sdatabuf As String, timestamp As Long) As Integer

Parameters:

	linkId	is the link identifier for which the data is desired
	databuf	is a reference to the data buffer into which the link data are to be copied. This buffer must be pre-alloced with enough room to store the data.
	timestamp	is the data timestamp as UTC (seconds since Jan 1, 1970)

It is only necessary to call this routine directly when using the 'Simple TINE Client ActiveX interface.

Returns:

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

See also:

GETRPCDATAEx(), GetRPCDataAndTime()

Example:

Dim DataBuffer(300) As Single
Dim DataTime As Long

Private Sub Eqp1_Receive()
  Dim errString As String * 64
  Dim rc As Integer

  If Eqp1.EqpStatus Then
    GetRPCLastError -1, errString
    EqpStatusLabel.Caption = errString
    Exit Sub
  Else
    EqpStatusLabel.Caption = ""
  End If

  rc = GETRPCDATA(Eqp1.EqpIndex, DataBuffer(0), DataTime)

  ...

End Sub

short GetRPCDataAndTime	(	short	linkId,
		void *	databuf,
		double *	dtimestamp,
		long *	datasize
	)

Use with Visual Basic 6.0. Retrieves data associated with the given link index into the calling process.

Visual Basic :
Declare Function GetRPCDataAndTime Lib "tinecln32.dll" (ByVal linkId As Integer, databuf As Any, timestamp As Long, datasize As Long) As Integer
Declare Function GetRPCStrDataAndTime Lib "tinecln32.dll" Alias "GetRPCDataAndTime" (ByVal linkId As Integer, ByVal sdatabuf As String, timestamp As Long, datasize As Long) As Integer

Parameters:

	linkId	is the link identifier for which the data is desired
	databuf	is a reference to the data buffer into which the link data are to be copied. This buffer must be pre-alloced with enough room to store the data.
	dtimestamp	is the TINE data timestamp as UTC + fractional seconds.
	datasize	contains the data size (as array dimension) of the data set returned from the server. It is assumed that the size of the data buffer can hold the data returned. The data returned will never be greater than the size demanded by the initial link parameters as given for example in AttachLink().

It is only necessary to call this routine directly when using the 'Simple TINE Client ActiveX interface. This call differs from GETRPCDATA() in that it returns the full TINE timestamp (UTC + millisecons as fractional part) as well as the size of the data set actually returned from the server (possibly less than what was asked for.).

Note:

This call is unavailable in Visual Basic 3.0 (use GETRPCDATAEx()).

Returns:

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

See also:

GETRPCDATA(), GETRPCDATAEx()

short GETRPCDATAEx	(	short	linkId,
		void *	databuf,
		time_t *	timestamp,
		long *	datasize
	)

Use with Visual Basic 3.0 or 6.0. Retrieves data associated with the given link index into the calling process.

Visual Basic :
Declare Function GETRPCDATAEx Lib "tinecln32.dll" (ByVal linkId As Integer, databuf As Any, timestamp As Long, datasize As Long) As Integer
Declare Function GETRPCSTRDATAEx Lib "tinecln32.dll" Alias "GETRPCDATA" (ByVal linkId As Integer, ByVal sdatabuf As String, timestamp As Long, datasize As Long) As Integer

Parameters:

	linkId	is the link identifier for which the data is desired
	databuf	is a reference to the data buffer into which the link data are to be copied. This buffer must be pre-alloced with enough room to store the data.
	timestamp	is the data timestamp as UTC (seconds since Jan 1, 1970)
	datasize	contains the data size (as array dimension) of the data set returned from the server. It is assumed that the size of the data buffer can hold the data returned. The data returned will never be greater than the size demanded by the initial link parameters as given for example in AttachLink().

It is only necessary to call this routine directly when using the 'Simple TINE Client ActiveX interface. This call differs from GETRPCDATA() in that it returns in the fourth parameter the size of the data set actually returned from the server (possibly less than what was asked for.). This call differs from GetRPCDataAndTime(), in that only the 'seconds' part of the data timestamp is returned in the third parameter.

Returns:

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

See also:

GETRPCDATA(), GetRPCDataAndTime()

short GetRPCLastError	(	short	cc,
		char *	ErrString
	)

Retrieves the TINE status string for the given completion code for the most recent data link if cc < 0.

Visual Basic :
Declare Function GetRPCLastError Lib "tinecln32.dll" (ByVal cc As Integer, ByVal ErrString As String) As Integer

Parameters:

	cc	is the TINE completion code (i.e. status code) for which the string representation is desired.
	errString	is a (pre-allocated!) string buffer into which the most recent completion status will be copied. This must point to a string buffer with enough room to hold the completion status (at least 48 characters).

It is only necessary to call this routine directly when using the 'Simple TINE Client ActiveX interface. If this the routine is called passing a negative number as the first parameter, then this routine should be called immediately following any synchronous link or asynchronous Receive event. Used in this manner, the call is clearly not thread-safe, but as Visual Basic builds single-threaded applications, this will most likely give reasonable results. As a synchronous call will return the completion code directly as a return code, you can safely use this call by passing the returned completion code as the first parameter.

Returns:

0 if successful, otherwise a TINE completion code.

Example:

Dim DataBuffer(300) As Single
Dim DataTime As Long

Private Sub Eqp1_Receive()
  Dim errString As String * 64
  Dim rc As Integer

  If Eqp1.EqpStatus Then
    GetRPCLastError -1, errString
    EqpStatusLabel.Caption = errString
    Exit Sub
  Else
    EqpStatusLabel.Caption = ""
  End If

  rc = GETRPCDATA(Eqp1.EqpIndex, DataBuffer(0), DataTime)

  ...

End Sub

short T_ATTACHLINK	(	char *	devName,
		char *	devprop,
		DTYPE *	dout,
		DTYPE *	din,
		short	access,
		int	pollrate,
		cbTLink	callback,
		int	mode
	)

Use with Visual Basic 6.0. Establishes an asynchronous link with the given calling parameters.

Asynchronous data exchange. Calls in the AttachLink() family attempt to establish the requested data link with the given calling parameters and complete immediately. If the address of the requested server can be resolved and the calling parameters are otherwise okay, the call will complete successfully and return a valid (positive) link handle. This does not mean that the requested server will respond to the request. The data and status information from the server will be returned asynchronously inside the callback routine passed in the call. In Visual Basic 3.0, there is no equivalent to this call. In Visual Basic 6.0, you must declare the callback routine as a Subroutine (not a Function) inside a .BAS module and make use of the AddressOf routine to pass the address of the this subroutine to T_ATTACHLINK(). This works in Visual Basic only to the extent that no debug break points are set inside 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
	access	is the data access mode. This can be any combination of access codes ORed together (CA_READ, CA_WRITE, CA_CONNECT, etc.).
	pollrate	is the polling interval in milliseconds at which the server is requested to acquire data. This value also signals a timeout if there is no notification within this amount of time plus the system heartbeat (1000 msec for POLLing links). One can use AttachLink() for asynchronous single READ and WRITE requests by specifying a pollmode of CM_SINGLE.
	callback	is a reference to the a callback function which is to be called by the TINE engine when either incoming data have arrived or an error condition has arised. This should be a pointer to a funtion with prototype Sub sinCallback(ByVal id As Long, ByVal cc As Long)
	pollmode	is the TINE poll mode, i.e. one of CM_CANCEL, CM_SINGLE, CM_REFRESH, CM_POLL, which can be ORed with one of CM_BCAST, CM_NETWORK, CM_MCAST, CM_USE_ON_ERROR, CM_RETRY, CM_GROUPED, CM_CONNECT, CM_WAIT, or CM_SYNCNOTIFY. (see the discussion of Data Access Modes).

Returns:

A positive link handle ID if successful, otherwise the negative of a TINE completion code which can be interpreted by a call to GetRPCLastError(). If the TINE engine can resolve the address of the requested server and all of the calling parameters are otherwise correct the call should complete successfully. Possible errors might be 'non existent element' or 'non existent fec', etc.

Note:

Unless you have a good reason to use this routine, it is better to make use of the ACOP Receive Event for asynchronous data links.

See also:

AttachLink(), DTYPE, EXECLINK(), EXECLINKEx()

Example:

' Inside a command button put ....

Private Sub Command1_Click()
  Dim dout As DTYPE, din As DTYPE

  dout.dArrayLength = 100
  dout.dFormat = CF_FLOAT
  dout.ddata = CADDR(s(0))

  din.dArrayLength = 0
  din.dFormat = CF_NULL
  din.ddata = 0

  idSine = T_ATTACHLINK("/TEST/SINE/#0", "SINE", dout, din, CA_READ, 1000, AddressOf sinCallback, CM_POLL)

Exit Sub


' In Module1.bas put the following ...

Global DataBuffer(300) As Single
Global idSine As Long

Sub sinCallback(ByVal id As Long, ByVal cc As Long)
  Form1.Label1.Caption = "[" + str(id) + "] : " + RPCERROR(cc)
  If cc Then Exit Sub
  Form1.Label2.Caption = " New Data have arrived !"
End Sub

---