Useful API Calls File Reference

TINE API tools. More...

Functions
int	AcquireAndRegisterStruct (char *devName, char *tag, int num)
	Acquires the structure specified by the structure tag from the specified device server.
void	AppendHistoryLog (char *text,...)
	Appends a line of text to a server's secondary log file.
int	AssertRangeValid (const char *eqmName, const char *prpName, DTYPE *din, int enforceLimits)
	Helper routine to check input data against registered range limits.
int	GetArchivedData (char *devsrv, int index, time_t start, time_t stop, FLTINT *fiDataArray, short *num)
	Retrieves archive data from the 'Central Archiver'.
int	GetArchivedDataAsAny (char *devsrv, time_t start, time_t stop, HstHdr *dataHdr, BYTE *data, int dataFmt, char *dataTag, int *num)
	Retrieves archive data as requested in the call.
int	GetArchivedDataAsFloat (char *devsrv, time_t start, time_t stop, FLTINT *fiDataArray, int *num)
	Retrieves archive data from the 'Central Archiver' requested in the call.
int	GetArchivedDataAsSnapshot (char *devsrv, time_t *target, float *fDataArray, int size)
	Retrieves archive data array from the 'Central Archiver' as a snapshot at a given time.
int	GetArchivedDataAsText (char *devsrv, time_t start, time_t stop, NAME32I *niDataArray, int *num)
	Retrieves archive data as text from the 'Central Archiver'.
int	GetArchivedTraceDataAsFloat (char *devsrv, time_t start, time_t stop, float *fDataArray, int num)
	Retrieves archive data from the 'Central Archiver' requested in the call.
int	GetDeviceContexts (NAME16 *clist, int *num)
	Retrieves a list of server contexts via query to the Equipment Name Server.
int	GetDeviceContextsFromFile (NAME16 *clist, int *num)
	Retrieves a list of server contexts via query to the local static database.
int	GetDeviceNames (char *srv, NAME16 *devs, int *num)
	Retrieves a list of device names via query to the server given.
int	GetDeviceNamesEx (char *srv, char *prp, NAME16 *devs, int *num)
	Retrieves a list of device names associated with a given property via query to the server specified.
int	GetDeviceProperties (char *srv, NAME32 *props, int *num)
	Retrieves a list of properties via query to the server given.
int	GetDevicePropertyEGU (char *srv, char *prp, float *max, float *min, char *egu)
	Retrieves the maximum, minimum values and engineering units for the property specified.
int	GetDevicePropertyInformation (char *srv, PropertyQueryStruct *srvProps, int *num)
	Retrieves a list of property query structures for the device server specified.
int	GetDeviceServers (NAME16 *dslist, int *num)
	Retrieves a list of servers via query to the Equipment Name Server.
int	GetDeviceServersEx (char *context, NAME16 *dslist, int *num)
	Retrieves a list of servers via query to the Equipment Name Server.
int	GetDeviceServersFromFile (char *context, NAME16 *dslist, int *num)
int	GetMyServerAddress (char *eqmName, char *expName, char *ctxName, char *fecName, int *port)
	Obtains FEC and Device server information from the Equipment Name Server based on the address and (optional) local equipment module name of the caller.
int	GetServers (NAME16 *slist, int *num)
	Retrieves a list of servers via query to the Equipment Name Server.
int	GetServersEx (char *context, NAME16 *slist, int *num)
	Retrieves a list of FECs via query to the Equipment Name Server.
int	GetSystemContexts (NAME32 *clist, int *num)
	Retrieves a list of server contexts via query to the Equipment Name Server.
int	GetSystemDevices (char *srv, char *prp, NAME64 *dlist, int *num)
	Retrieves a list of device names associated with a given property via query to the server specified.
int	GetSystemFecs (char *context, NAME16 *slist, int *num)
	Retrieves a list of FECs associated with a given context.
int	GetSystemProperties (char *srv, NAME64 *plist, int *num)
	Retrieves a list of properties via query to the server given.
int	GetSystemPropertyInformation (char *srv, char *prp, PrpQueryStruct **pqs, int *num)
	Retrieves a list of extended property query structures for the device server and target property specified.
int	GetSystemServers (char *context, NAME32 *dslist, int *num)
	Retrieves a list of FECs via query to the Equipment Name Server.
int	GetTargetPropertyInformation (char *srv, char *prp, int *fmt, int *siz, char *dsc)
	Retrieves the default set of property information parameters for the property specified.
int	GetValuesAsAny (DTYPE *d, void *val, short fmt, int objectSizeInBytes, int num, int offset)
	Retrieves incoming data as an array of the format type given.
int	GetValuesAsByte (DTYPE *d, BYTE *bval, int num)
	Retrieves incoming data as an array of bytes.
int	GetValuesAsDBLDBL (DTYPE *d, DBLDBL *ddval, int num)
	Retrieves incoming data as an array of DBLDBL values.
int	GetValuesAsDouble (DTYPE *d, double *dval, int num)
	Retrieves incoming data as an array of doubles.
int	GetValuesAsFloat (DTYPE *d, float *fval, int num)
	Retrieves incoming data as an array of floats.
int	GetValuesAsLong (DTYPE *d, SINT32 *lval, int num)
	Retrieves incoming data as an array of long integers.
int	GetValuesAsNAME64DBL (DTYPE *d, NAME64DBL *ndval, int num)
	Retrieves incoming data as an array of NAME64DBL values.
int	GetValuesAsNAME64DBLDBL (DTYPE *d, NAME64DBLDBL *nddval, int num)
	Retrieves incoming data as an array of NAME64DBLDBL values.
int	GetValuesAsShort (DTYPE *d, short *sval, int num)
	Retrieves incoming data as an array of short integers.
int	GetValuesAsString (DTYPE *d, char *str, UINT32 *dsiz)
	Retrieves incoming data as a string buffer.
int	GetValuesAsStringEx (DTYPE *d, char *str, int fmt, int num, int offset)
	Prepares incoming data to a string type.
int	PutValuesFromAny (DTYPE *d, void *val, short fmt, int sgn, int objectSizeInBytes, int num, int offset)
	Submits outgoing data from an array of the given format data type.
int	PutValuesFromByteEx (DTYPE *d, BYTE *bval, int num, int offset)
	Submits outgoing data from an array of bytes.
int	PutValuesFromDoubleEx (DTYPE *d, double *dval, int num, int offset)
	Submits outgoing data from an array of doubles.
int	PutValuesFromFloatEx (DTYPE *d, float *fval, int num, int offset)
	Submits outgoing data from an array of floats.
int	PutValuesFromLongEx (DTYPE *d, SINT32 *lval, int num, int offset)
	Submits outgoing data from an array of long integers.
int	PutValuesFromShortEx (DTYPE *d, short *sval, int num, int offset)
	Submits outgoing data from an array of short integers.
int	PutValuesFromString (DTYPE *d, char *str, int fmt, int num, int offset)
	Prepares outgoing data as a string type.
int	PutValuesFromUnsignedLongEx (DTYPE *d, UINT32 *lval, int num, int offset)
	Submits outgoing data from an array of unsigned long (32-bit) integers.
int	PutValuesFromUnsignedShortEx (DTYPE *d, UINT16 *sval, int num, int offset)
	Submits outgoing data from an array of unsigned short integers.
int	RestorePropertyValues (const char *eqmName, const char *prpName, void *values, short format, int size)
	Retrieves the value settings of the property name given from disk.
int	SavePropertyValues (const char *eqmName, const char *prpName, void *values, short format, int size)
	Saves value settings of the property name given onto disk.
int	SavePropertyValuesEx (const char *eqmName, const char *devName, const char *prpName, void *values, short format, int size)
	Saves value settings of the property name given onto disk (extended version).
int	SendEventTrigger (char *dev, char *cmt, short triggerLevel)
	Sends a Post-Mortem (i.e. event) Trigger to the designated Post-Mortem Server.
Variables
int	fecLogFileDepth = 500
	Sets the depth in lines of a server's secondary log file (if utilized).

---

Detailed Description

TINE API tools.

Many optional routines are offered to make programming easier. Below are API routines which are useful both for client-side programming and server-side programming. Some query calls such as GetDeviceNames(), etc. are clearly suitable for information gathering. The set of of data manipulation routines such at GetValuesAsFloat() or PutValuesFromLongEx() are designed for easy integration into server code, where format conversion, array-wrapping, array segmenting, etc. are automatically provided. Helper routines such as sendPMTrigger() are also provided.

---

Function Documentation

int AcquireAndRegisterStruct	(	char *	devName,
		char *	tag,
		int	num
	)

Acquires the structure specified by the structure tag from the specified device server.

This routine is largly useful for generic applications which need to display results. Logic which requires knowing 'which field does what' will in general also require knowing a priori the structure fields.

Parameters:

devName	is the targeted device server where the structure is registered.
tag	is the structure tag
num	is the maximum number of structure objects of this type which can be stord locally. Note that due to alignment, byte-swapping and memory issues, the TINE kernel needs to reserve enough space to prepare incoming structures for the caller.

Returns:

a tine return code.

See also:

SealTaggedStruct(), AddFieldToStruct()

void AppendHistoryLog	(	char *	str,
			...
	)

Appends a line of text to a server's secondary log file.

For most cases the system log file "fec.log" is sufficient for logging server activities. Furthermore, "fec.log" is retrievable via a systematic TINE call so that it can be viewed from a remote location without requiring a mount to a file system. However, for more detailing logging you may want to make use of a secondary log file whose name is given by <fecName>.log. This log file resides only on the local file system.

Parameters:

str	is a 'printf'-like variable argument list string containing the text to be appended

Returns:

none

See also:

fecLogFileDepth

int AssertRangeValid	(	const char *	eqmName,
		const char *	prpName,
		DTYPE *	din,
		int	enforceLimits
	)

Helper routine to check input data against registered range limits.

This routine returns TRUE if the given input does not violate the registered range settings for the property given. Any errors in input will result in a 'TRUE' being returned. If the 'enforceLimits' parameter is 'TRUE' then the routine will always return TRUE but will mutate the DTYPE object so that any range exceptions are set to the registered maximum or minimum values.

This helper routine will only consider input data objects supplying a single valued 'primitive' numerical format type.

Parameters:

eqmName	is the local equipment module name.
prpName	is the name of the property whose values are to be restored
din	is a reference to input data to be checked against the registered range settings.
enforceLimits	will insert the corresponding maximum or minimum value into the din object reference should any range exception be detected.

Returns:

TRUE if no range violation is detected.

References DUNION::bptr, DTYPE::dArrayLength, DTYPE::data, DTYPE::dFormat, DUNION::dptr, DUNION::fptr, GetRegisteredPropertyListStruct(), DUNION::lptr, and DUNION::sptr.

int GetArchivedData	(	char *	keyword,
		int	keyindex,
		time_t	start,
		time_t	stop,
		FLTINT *	fiDataArray,
		short *	num
	)

Retrieves archive data from the 'Central Archiver'.

This call retrieves archive data from either the default 'Central Archive' or the archiver requested in the call.

Parameters:

keyword	[in] is either the keyword-appended full device server name for which the archive data is desired or simply the keyword, in which case the default central archiver is called (registered with export name "HISTORY").
keyindex	[in] is an optional index (if non-zero) into a keyword array (for instance if the keyword is a trace.
start	[in] is the start time input (expressed as a UNIX timestamp) for which the archive data are desired.
stop	[in] is the end time input (expressed as a UNIX timestamp) for which the archive data are desired.
fiDataArray	[out] is a pointer to array of FLTINT objects to receive the archive data.
num	[in/out] is a pointer to an integer giving (as input) the size of the FLTINT buffer which is to receive the archive data, and (as ouput) which contains the amount of archive data actually returned by the call.

Returns:

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

Note:

It is in general best to use the keyword-appended full device name in this call. For instance, if the horizontal orbit has been archived as keyword "ORBIT.X", a call to get the orbit position for a BPM with device name "MONITOR3" could be made by specifying "ORBIT.X" as the keyword and "3" as the keyindex and assume that this keyword is available at a central archive server named "HISTORY". Otherwise, if the name of the relevant archive server is known (either "HISTORY" or something else), then the call can be made by specifying "/<context>/<archive server>/MONITOR3/ORBIT.X" as the keyword and "0" as the keyindex. The latter although longer is a much more general way to obtain archive data via this call.

The data in this call are returned as an array of FLTINT objects, containing a data-point + timestamp pair.

If you desire the an entire trace or spectrum of data at a particular timestamp, you should make a call to GetArchivedTraceDataAsFloat() in which case an array of floats is returned at the first timestamp encountered while scanning from start to stop.

See also:

GetArchivedDataAsText(), GetArchivedDataAsFloat(), GetArchivedTraceDataAsFloat()

References DTYPE::dArrayLength, DTYPE::data, DTYPE::dFormat, ExecLinkEx(), DUNION::ulptr, and DUNION::vptr.

int GetArchivedDataAsAny	(	char *	devsrv,
		time_t	start,
		time_t	stop,
		HstHdr *	dataHdr,
		BYTE *	data,
		int	dataFmt,
		char *	dataTag,
		int *	num
	)

Retrieves archive data as requested in the call.

This call retrieves archive data from the archiver requested in the call. This call retrieves an archived data set according to the data format given.

Parameters:

devsrv	[in] must be the keyword-appended full device server name for which the archive data is desired.
start	[in] is the start time input (expressed as a UNIX timestamp) for which the archive data are desired.
stop	[in] is the end time input (expressed as a UNIX timestamp) for which the archive data are desired.
dataHdr	[out] is a pointer to an array to hold the history header information. This is an array of HstHdr objects containing a TINE timestamp (UTC double), a system data stamp (32-bit integer) and the user data stamp (32-bit integer) in one-to-one correspondence with the data array returned.
data	[out] is a pointer to an array of data objects to receive the archive data. This should an array of the desired data format (and large enough to hold the requested data).
dataFmt	[in] is the TINE data format code of the requested data. If this doesn't match the stored format, an attempt will be made to reformat the data. However this will not always be possible and could lead to an error.
dataTag	[in] is the TINE tagged structure tag to be used if the stored data is a TINE tagged structure. If the stored data is not a structure, this parameter is ignored.
num	[in/out] is a pointer to an integer giving (as input) the size of the data buffer which is to receive the archive data, and (as ouput) which contains the amount of archive data actually returned by the call.

Returns:

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

See also:

GetArchivedDataAsFloat(), GetArchivedData(), GetArchivedDataAsText()

References DTYPE::dArrayLength, DTYPE::data, DTYPE::dFormat, DTYPE::dTag, ExecLinkEx(), DUNION::ulptr, and DUNION::vptr.

int GetArchivedDataAsFloat	(	char *	devsrv,
		time_t	start,
		time_t	stop,
		FLTINT *	fiDataArray,
		int *	num
	)

Retrieves archive data from the 'Central Archiver' requested in the call.

This call retrieves archive data from the archiver requested in the call. This call supercedes GetArchivedData(), which still allows a simple call into the 'default central archiver'.

Parameters:

devsrv	[in] must be the keyword-appended full device server name for which the archive data is desired.
start	[in] is the start time input (expressed as a UNIX timestamp) for which the archive data are desired.
stop	[in] is the end time input (expressed as a UNIX timestamp) for which the archive data are desired.
fiDataArray	[out] is a pointer to array of FLTINT objects to receive the archive data.
num	[in/out] is a pointer to an integer giving (as input) the size of the FLTINT buffer which is to receive the archive data, and (as ouput) which contains the amount of archive data actually returned by the call.

Returns:

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

Note:

You must use the keyword-appended full device name in this call. For instance, if the horizontal orbit has been archived as keyword "ORBIT.X", a call to get the orbit position for a BPM with device name "MONITOR3" is to be made by specifying "/<context>/<archive server>/MONITOR3/ORBIT.X" as the keyword.

The data in this call are returned as an array of FLTINT objects, containing a data-point + timestamp pair.

If you desire the an entire trace or spectrum of data at a particular timestamp, you should make a call to GetArchivedTraceDataAsFloat() in which case an array of floats is returned at the first timestamp encountered while scanning from start to stop.

See also:

GetArchivedDataAsText(), GetArchivedData(), GetArchivedTraceDataAsFloat()

References DTYPE::dArrayLength, DTYPE::data, DTYPE::dFormat, ExecLinkEx(), DUNION::ulptr, and DUNION::vptr.

int GetArchivedDataAsSnapshot	(	char *	devsrv,
		time_t *	target,
		float *	fDataArray,
		int	size
	)

Retrieves archive data array from the 'Central Archiver' as a snapshot at a given time.

This call retrieves an archive data array from either the default 'Central Archive' or the archiver requested in the call.

Parameters:

devsrv	[in] must be the keyword-appended full device server name for which the archive data is desired.
target	[in] is the target time input (expressed as a UNIX timestamp) for which the archive data are desired.
fDataArray	[out] is a pointer to array of floats to receive the archive data.
size	[in] gives the size of the float buffer which is to receive the archive data, and is likewise used to specify the size of the trace, waveform or spectrum which has been archived.

Returns:

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

See also:

GetArchivedDataAsText(), GetArchivedDataAsFloat(), GetArchivedTraceDataAsFloat()

References DTYPE::dArrayLength, DTYPE::data, DTYPE::dFormat, ExecLinkEx(), DUNION::ulptr, and DUNION::vptr.

int GetArchivedDataAsText	(	char *	devsrv,
		time_t	start,
		time_t	stop,
		NAME32I *	niDataArray,
		int *	num
	)

Retrieves archive data as text from the 'Central Archiver'.

This call retrieves archive data as text from the archiver requested in the call.

Parameters:

devsrv	[in] is the keyword-appended full device server name for which the archive data is desired.
start	[in] is the start time input (expressed as a UNIX timestamp) for which the archive data are desired.
stop	[in] is the end time input (expressed as a UNIX timestamp) for which the archive data are desired.
niDataArray	[out] is a pointer to array of NAME32I objects to receive the archive data.
num	[in/out] is a pointer to an integer giving (as input) the size of the FLTINT buffer which is to receive the archive data, and (as ouput) which contains the amount of archive data actually returned by the call.

Returns:

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

Note:

This calls uses only the keyword-appended full device name in this call. If the name of the relevant archive server is known (either "HISTORY" or something else), then the call can be made by specifying "/<context>/<archive server>/MONITOR3/ORBIT.X" as the keyword. The archived data will be converted to a text string and entered into the "NAME32" part of the array of NAME32I doublets returned. This call must be used in order to retrieve data stored as strings, such as machine states, etc.

See also:

GetArchivedData(), GetArchivedDataAsFloat(), GetArchivedTraceDataAsFloat()

References DTYPE::dArrayLength, DTYPE::data, DTYPE::dFormat, ExecLinkEx(), DUNION::ulptr, and DUNION::vptr.

int GetArchivedTraceDataAsFloat	(	char *	devsrv,
		time_t	start,
		time_t	stop,
		float *	fDataArray,
		int	num
	)

Retrieves archive data from the 'Central Archiver' requested in the call.

This call retrieves archive data from the archiver requested in the call, and will deliver the contents of an archived keyword at a particular timestamp, which is particularly useful when the keyword represents a trace, waveform, or spectrum.

Parameters:

devsrv	[in] must be the keyword-appended full device server name for which the archive data is desired.
start	[in] is the start time input (expressed as a UNIX timestamp) for which the archive data are desired.
stop	[in] is the end time input (expressed as a UNIX timestamp) for which the archive data are desired.
fDataArray	[out] is a pointer to array of floats to receive the archive data.
num	[in] gives the size of the float buffer which is to receive the archive data, and is likewise used to specify the size of the trace, waveform or spectrum which has been archived. To this end, this must indeed match the size of the record archived or the call will fail.

Returns:

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

Note:

You must use the keyword-appended full device name in this call. For instance, if the horizontal orbit has been archived as keyword "ORBIT.X", a call to get the entire orbit at a given timestamp is to be made by specifying "/<context>/<archive server>/#0/ORBIT.X" as the keyword.

The archiver will start searching for a record beginning with the start time specified. It will stop scanning and return the record found as soon as it encounters a timestamp equal to or greater than than the start time and not exceeding the stop time.

See also:

GetArchivedDataAsText(), GetArchivedData(), GetArchivedDataAsFloat()

References DTYPE::dArrayLength, DTYPE::data, DTYPE::dFormat, ExecLinkEx(), DUNION::ulptr, and DUNION::vptr.

int GetDeviceContexts	(	NAME16 *	clist,
		int *	num
	)

Retrieves a list of server contexts via query to the Equipment Name Server.

Deprecated:

This call retrieves a list of all server context managed by the Equipment Name Server

Parameters:

clist	is a pointer to a NAME16 buffer to receive the name list.
num	is the size of the buffer pointed to by the first parameter. Note that this buffer space must be pre-allocated, otherwise a system crash will ensue.

Returns:

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

See also:

GetSystemContexts()

int GetDeviceContextsFromFile	(	NAME16 *	clist,
		int *	num
	)

Retrieves a list of server contexts via query to the local static database.

Deprecated:

This call retrieves a list of all server context managed by the local static database.

Parameters:

clist	is a pointer to a NAME16 buffer to receive the name list.
num	is the size of the buffer pointed to by the first parameter. Note that this buffer space must be pre-allocated, otherwise a system crash will ensue.

Returns:

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

See also:

GetSystemContexts()

int GetDeviceNames	(	char *	srv,
		NAME16 *	dlist,
		int *	num
	)

Retrieves a list of device names via query to the server given.

Deprecated:

This call retrieves a list of all device names registered on the server. A classic device server will export its behavior through its properties, and export its "instances" through its "device names", according to the motto "All devices found on this server have the same set of properties, and all properties apply to any device found on this server". Under some circumstances this is not true, in which case a more generalized query GetDeviceNamesEx() is required to retrieve a device list associated with a given property.

Parameters:

srv	is the full device server name for which the property query is to be made
dlist	is a pointer to a NAME16 buffer to receive the name list.
num	is the size of the buffer pointed to by the first parameter. Note that this buffer space must be pre-allocated, otherwise a system crash will ensue.

Returns:

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

See also:

GetDeviceNamesEx()

References GetDeviceNamesEx().

int GetDeviceNamesEx	(	char *	srv,
		char *	prp,
		NAME16 *	dlist,
		int *	num
	)

Retrieves a list of device names associated with a given property via query to the server specified.

Deprecated:

This call retrieves a list of all device names registered on the server associated with the property specified in the call. A classic device server will export its behavior through its properties, and export its "instances" through its "device names", according to the motto "All devices found on this server have the same set of properties, and all properties apply to any device found on this server". For certain classes of server (in particular middle layer servers) the properties exported might refer to 'apples' and 'oranges' simply because the server is archiving them. Or there might be other reasons why the device list associated with a particular property has little or nothing to do with that associated with some other property. Use this call to obtain the device list associated with a particular property.

Parameters:

srv	is the full device server name for which the property query is to be made
prp	is the property for which the device list is desired.
dlist	is a pointer to a NAME16 buffer to receive the name list.
num	is the size of the buffer pointed to by the first parameter. Note that this buffer space must be pre-allocated, otherwise a system crash will ensue.

Returns:

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

See also:

GetSystemDevices()

References DTYPE::dArrayLength, DTYPE::data, DTYPE::dFormat, ExecLinkEx(), GetExportedDeviceList(), and DUNION::vptr.

Referenced by GetDeviceNames().

int GetDeviceProperties	(	char *	srv,
		NAME32 *	plist,
		int *	num
	)

Retrieves a list of properties via query to the server given.

This call retrieves a list of all properties registered on the server associated with full device server name specified. A classic device server will export its behavior through its properties, and export its "instances" through its "device names", according to the motto "All devices found on this server have the same set of properties, and all properties apply to any device found on this server". In this case, simply specifying the device server name as the first input parameter will return the set of properties valid for all devices registered on the server. Under some circumstances, however, the set of properties associated with a particular device might be different from device to device. If this is the case, the full device server name should be used as the first parameter, where the target device name is also sent as part of the query.

Parameters:

srv	is the full device server name for which the property query is to be made
plist	is a pointer to a NAME32 buffer to receive the name list.
num	is the size of the buffer pointed to by the first parameter. Note that this buffer space must be pre-allocated, otherwise a system crash will ensue.

Returns:

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

See also:

GetDevicePropertyInformation(), GetTargetPropertyInformation(), GetDevicePropertyEGU()

References DUNION::cptr, DTYPE::dArrayLength, DTYPE::data, DTYPE::dFormat, and ExecLinkEx().

int GetDevicePropertyEGU	(	char *	srv,
		char *	prp,
		float *	max,
		float *	min,
		char *	egu
	)

Retrieves the maximum, minimum values and engineering units for the property specified.

This call retrieves the maximum, minimum values and engineering units for the property specified.

Parameters:

srv	[in] is the full device server name for which the property query is to be made
prp	[in] is the property for which the information is desired.
max	[out] is a pointer to receive maximum property value (if non-NULL) as registered.
min	[out] is a pointer to receive minimum property value (if non-NULL) as registered.
egu	[out] is a string buffer to receive the property engineering unit (if non-NULL). Note that buffer space must be pre-allocated, otherwise a system crash will ensue.

Returns:

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

Note:

It is always assumed thar regardless of property format overloading, the maximum and minimum values as well as the engineering units remain the same.

See also:

GetDevicePropertyInformation(), GetDeviceProperties(), GetTargetPropertyInformation()

References DTYPE::dArrayLength, DTYPE::data, DTYPE::dFormat, ExecLinkEx(), DUSTRING::f1val, DUSTRING::f2val, DUSTRING::str, and DUNION::vptr.

int GetDevicePropertyInformation	(	char *	srv,
		PropertyQueryStruct *	srvProps,
		int *	num
	)

Retrieves a list of property query structures for the device server specified.

This call retrieves a list of property information parameters in the form of PropertyQueryStruct structures for the device server specified.

Parameters:

srv	[in] is the full device server name for which the property query is to be made
srvProps	[out] is a pointer to an array of PropertyQueryStruct objects. Note that buffer space must be pre-allocated, otherwise a system crash will ensue.
num	[in/out] as input is a pointer to the maximum number of PropertyQueryStruct objects which srvProps can hold. As output it contains the total number of properties.

Returns:

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

See also:

GetTargetPropertyInformation(), GetDeviceProperties(), GetDevicePropertyInformationX()

References DTYPE::dArrayLength, DTYPE::data, DTYPE::dFormat, ExecLinkEx(), and DUNION::vptr.

int GetDeviceServers	(	NAME16 *	dslist,
		int *	num
	)

Retrieves a list of servers via query to the Equipment Name Server.

This call simply retrieves a list of all devices servers irrespective of server context. For a context specific list, please use the extended call GetDeviceServersEx().

Parameters:

dslist	is a pointer to a NAME16 buffer to receive the name list.
num	is the size of the buffer pointed to by the first parameter. Note that this buffer space must be pre-allocated, otherwise a system crash will ensue.

Returns:

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

See also:

GetDeviceServersEx()

int GetDeviceServersEx	(	char *	context,
		NAME16 *	dslist,
		int *	num
	)

Retrieves a list of servers via query to the Equipment Name Server.

This call retrieves a list of all devices servers associated with the context given.

Parameters:

context	is the context for which the query is to be made
dslist	is a pointer to a NAME16 buffer to receive the name list.
num	is the size of the buffer pointed to by the first parameter. Note that this buffer space must be pre-allocated, otherwise a system crash will ensue.

Returns:

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

See also:

GetDeviceServers()

int GetDeviceServersFromFile	(	char *	context,
		NAME16 *	dslist,
		int *	num
	)

This call retrieves a list of all devices servers associated with the context given, as obtained from the local static database.

Parameters:

context	is the context for which the query is to be made
dslist	is a pointer to a NAME16 buffer to receive the name list.
num	is the size of the buffer pointed to by the first parameter. Note that this buffer space must be pre-allocated, otherwise a system crash will ensue.

Returns:

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

See also:

GetDeviceServers()

int GetMyServerAddress	(	char *	eqmName,
		char *	expName,
		char *	ctxName,
		char *	fecName,
		int *	port
	)

Obtains FEC and Device server information from the Equipment Name Server based on the address and (optional) local equipment module name of the caller.

A diskless (or otherwise 'in-a-box') server which does not know its address parameters such as fec name, export name, context, port offset, etc. can make this call prior to initializing. Upon success, a call to RegisterFecInformation() can then be made to fix these parameters within the server process.

Parameters:

ctxName	(output optional) the Context of local server.
eqmName	(input/output optional)the local equipment module name of local server.
expName	(output optional) the exported device server name of the local server.
fecName	(output optional) is the FEC name of the local server.
port	(output optional) is the port offset of the local server. to the call.

Returns:

0 if successful, otherwise a TINE completion code

References DUNION::cptr, DTYPE::dArrayLength, DTYPE::data, DTYPE::dFormat, DTYPE::dTag, NAME16::name, and NAME32::name.

int GetServers	(	NAME16 *	slist,
		int *	num
	)

Retrieves a list of servers via query to the Equipment Name Server.

This call simply retrieves a list of all Front End Computer Names (FECs) irrespective of server context. For a context specific list, please use the extended call GetServersEx().

Parameters:

slist	is a pointer to a NAME16 buffer to receive the name list.
num	is the size of the buffer pointed to by the first parameter. Note that this buffer space must be pre-allocated, otherwise a system crash will ensue.

Returns:

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

See also:

GetServersEx()

int GetServersEx	(	char *	context,
		NAME16 *	slist,
		int *	num
	)

Retrieves a list of FECs via query to the Equipment Name Server.

Deprecated:

This call retrieves a list of all Front End Computer Names (FECs) associated with the server context given.

Parameters:

context	is the context for which the query is to be made
slist	is a pointer to a NAME16 buffer to receive the name list.
num	is the size of the buffer pointed to by the first parameter. Note that this buffer space must be pre-allocated, otherwise a system crash will ensue.

Returns:

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

See also:

GetSystemServers()

int GetSystemContexts	(	NAME32 *	clist,
		int *	num
	)

Retrieves a list of server contexts via query to the Equipment Name Server.

This call retrieves a list of all server context managed by the Equipment Name Server

Parameters:

clist	is a pointer to a NAME32 buffer to receive the name list.
num	is the size of the buffer pointed to by the first parameter. Note that this buffer space must be pre-allocated, otherwise a system crash will ensue.

Returns:

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

int GetSystemDevices	(	char *	srv,
		char *	prp,
		NAME64 *	dlist,
		int *	num
	)

Retrieves a list of device names associated with a given property via query to the server specified.

This call retrieves a list of all device names registered on the server associated with the property specified in the call. A classic device server will export its behavior through its properties, and export its "instances" through its "device names", according to the motto "All devices found on this server have the same set of properties, and all properties apply to any device found on this server". For certain classes of server (in particular middle layer servers) the properties exported might refer to 'apples' and 'oranges' simply because the server is archiving them. Or there might be other reasons why the device list associated with a particular property has little or nothing to do with that associated with some other property. Use this call to obtain the device list associated with a particular property.

Parameters:

srv	is the full device server name for which the property query is to be made
prp	is the property for which the device list is desired.
dlist	is a pointer to a NAME64 buffer to receive the name list.
num	is the size of the buffer pointed to by the first parameter. Note that this buffer space must be pre-allocated, otherwise a system crash will ensue.

Returns:

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

References DTYPE::dArrayLength, DTYPE::data, DTYPE::dFormat, ExecLinkEx(), GetExportedDeviceList(), and DUNION::vptr.

int GetSystemFecs	(	char *	context,
		NAME16 *	slist,
		int *	num
	)

Retrieves a list of FECs associated with a given context.

This call retrieves a list of all FEC names associated with the context specified in the call. The call is made the equipment name server.

Parameters:

context	(input) is the context for which the FEC list is desired. If NULL or an empty string, a list of all known FECS is returned.
slist	is a pointer to a NAME16 buffer to receive the FEC name list.
num	is the size of the buffer pointed to by the first parameter. Note that this buffer space must be pre-allocated, otherwise a system crash will ensue.

Returns:

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

int GetSystemProperties	(	char *	srv,
		NAME64 *	plist,
		int *	num
	)

Retrieves a list of properties via query to the server given.

This call retrieves a list of all properties registered on the server associated with full device server name specified. A classic device server will export its behavior through its properties, and export its "instances" through its "device names", according to the motto "All devices found on this server have the same set of properties, and all properties apply to any device found on this server". In this case, simply specifying the device server name as the first input parameter will return the set of properties valid for all devices registered on the server. Under some circumstances, however, the set of properties associated with a particular device might be different from device to device. If this is the case, the full device server name should be used as the first parameter, where the target device name is also sent as part of the query.

Parameters:

srv	is the full device server name for which the property query is to be made
plist	is a pointer to a NAME64 buffer to receive the name list.
num	is the size of the buffer pointed to by the first parameter. Note that this buffer space must be pre-allocated, otherwise a system crash will ensue.

Returns:

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

See also:

GetDevicePropertyInformation(), GetTargetPropertyInformation(), GetDevicePropertyEGU()

References DUNION::cptr, DTYPE::dArrayLength, DTYPE::data, DTYPE::dFormat, and ExecLinkEx().

int GetSystemPropertyInformation	(	char *	srv,
		char *	prp,
		PrpQueryStruct **	srvProps,
		int *	num
	)

Retrieves a list of extended property query structures for the device server and target property specified.

This call retrieves a list of all relevant property information parameters in the form of PrpQueryStruct structures for the device server and target property specified.

Parameters:

srv	[in] is the full device server name for which the property query is to be made
prp	[in] is the property name for which the extended property query is to be made. Passing a NULL for this parameter will result in the query returning information for all properties until the buffer space (given by 'num') is exhausted. Passing a wildcard character '*' will return information for those properties matching the pattern given.
srvProps	[in/out] is a pointer to a pointer to an array of PrpQueryStruct objects. The property query objects contain all detailed information concerning the queried property. If this pointer points to a NULL pointer (unallocated), the buffer space will be allocated by the call and assigned to the pointer given, in which case it is the caller's duty to free the memory when no longer needed. If this pointer points to a non-NULL pointer (pre-allocated), the the buffer space pointed to must be sufficient to handle the number of structures given by the num parameter.
num	[in/out] as input is a pointer to the maximum number of PrpQueryStruct objects which srvProps can hold. As output it contains the total number of properties found. If the number pointed to is 0, then the number of properties is ascertained from the target server. In this case, the srvProps parameter usually points to a NULL (unassigned) pointer.

Returns:

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

See also:

GetTargetPropertyInformation(), GetDeviceProperties(), GetDevicePropertyInformation()

References DUNION::cptr, DTYPE::dArrayLength, DTYPE::data, DTYPE::dFormat, DTYPE::dTag, ExecLinkEx(), and DUNION::vptr.

int GetSystemServers	(	char *	context,
		NAME32 *	dslist,
		int *	num
	)

Retrieves a list of FECs via query to the Equipment Name Server.

This call retrieves a list of all Front End Computer Names (FECs) associated with the server context given.

Parameters:

context	is the context for which the query is to be made
dslist	is a pointer to a NAME32 buffer to receive the name list.
num	is the size of the buffer pointed to by the first parameter. Note that this buffer space must be pre-allocated, otherwise a system crash will ensue.

Returns:

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

See also:

GetServers()

int GetTargetPropertyInformation	(	char *	srv,
		char *	prp,
		int *	fmt,
		int *	siz,
		char *	dsc
	)

Retrieves the default set of property information parameters for the property specified.

This call retrieves the default set of property information parameters for the property specified.

Parameters:

srv	[in] is the full device server name for which the property query is to be made
prp	[in] is the property for which the information is desired.
fmt	[out] is a pointer to receive the TINE format data type (if non-NULL).
siz	[out] is a pointer to receive the data size (if non-NULL)
dsc	[out] is a string buffer (minimum 64 characters) to receive the property description (if non-NULL). Note that buffer space must be pre-allocated, otherwise a system crash will ensue.

Returns:

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

Note:

In cases where property behavior has been overloaded, this call will only retrieve the properties "default" behavior, i.e. the information pertaining to the last registered property.

See also:

GetDevicePropertyInformation(), GetDeviceProperties(), GetDevicePropertyEGU()

References DTYPE::dArrayLength, DTYPE::data, DTYPE::dFormat, DTYPE::dTag, ExecLinkEx(), NAME64::name, PrpQueryStruct::prpDescription, PropertyQueryStruct::prpDescription, PrpQueryStruct::prpFormat, PropertyQueryStruct::prpFormat, PrpQueryStruct::prpSize, PropertyQueryStruct::prpSize, and DUNION::vptr.

int GetValuesAsAny	(	DTYPE *	d,
		void *	val,
		short	fmt,
		int	objectSizeInBytes,
		int	num,
		int	offset
	)

Retrieves incoming data as an array of the format type given.

This routine will convert incoming data if possible to an array of the given format

Parameters:

d	is a TINE DTYPE data object from which the incoming data is to be used.
val	is a pointer to the destination data
fmt	is the TINE format data type of the destination data. This should be one of CF_BYTE, CF_INT16, CF_INT32, CF_FLOAT, CF_DOUBLE, etc. (any valid TINE format)
objectSizeInBytes	is the size in bytes of the containing object. For instance, 'val' might point to a float value embedded in a structure, so objectSizeInBytes should be the size of the structure in this case. If objectSizeInBytes is smaller than the size of 'fmt' then an error is returned.
num	is the number of array elements contained in the destination array
offset	is the starting point in the destination data array

Returns:

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

See also:

PutValuesFromAny()

References DUNION::bptr, DTYPE::dArrayLength, DTYPE::data, DTYPE::dFormat, GetValuesAsByte(), GetValuesAsDouble(), GetValuesAsFloat(), GetValuesAsLong(), and GetValuesAsShort().

int GetValuesAsByte	(	DTYPE *	d,
		BYTE *	bval,
		int	num
	)

Retrieves incoming data as an array of bytes.

This routine will convert incoming data if possible to an array of bytes (unsigned chars). If it is not possible to convert to an array of bytes an error is returned.

Parameters:

d	is a TINE DTYPE data object containing the incoming data.
bval	is a pointer to the byte array to receive the converted input data is the maximum number of array elements which the byte array can hold

Returns:

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

See also:

GetValuesAsShort(), GetValuesAsLong(), GetValuesAsFloat(), GetValuesAsDouble()

References DUNION::bptr, DTYPE::dArrayLength, DTYPE::data, DTYPE::dFormat, DUNION::dptr, DUNION::fptr, DUNION::lptr, DUNION::sptr, and DUNION::vptr.

Referenced by GetValuesAsAny().

int GetValuesAsDBLDBL	(	DTYPE *	d,
		DBLDBL *	ddval,
		int	num
	)

Retrieves incoming data as an array of DBLDBL values.

This routine will convert incoming data if possible to an array of DBLDBL doublets. For instance, FLTINT values or INTINT values will be cast into doubles. If it is not possible to convert to a string an error is returned.

Parameters:

d	is a TINE DTYPE data object containing the incoming data.
ddva	is a pointer to the buffer to receive the converted input data
num	is the maximum size of the string buffer

Returns:

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

See also:

GetValuesAsShort(), GetValuesAsLong(), GetValuesAsFloat(), GetValuesAsDouble()

References DBLDBL::d1val, DBLDBL::d2val, DTYPE::dArrayLength, DTYPE::data, DTYPE::dFormat, and DUNION::vptr.

int GetValuesAsDouble	(	DTYPE *	d,
		double *	dval,
		int	num
	)

Retrieves incoming data as an array of doubles.

This routine will convert incoming data if possible to an array of doubles. If it is not possible to convert to an array of doubles an error is returned.

Parameters:

d	is a TINE DTYPE data object containing the incoming data.
dval	is a pointer to the double array to receive the converted input data
num	is the maximum number of array elements which the double array can hold

Returns:

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

See also:

GetValuesAsShort(), GetValuesAsLong(), GetValuesAsFloat()

Alias: GetValuesAsDouble()

Example: (see GetValuesAsShort() for example)

References DUNION::bptr, DTYPE::dArrayLength, DTYPE::data, DTYPE::dFormat, DUNION::dptr, DUNION::fptr, DUNION::lptr, DUNION::sptr, and DUNION::vptr.

Referenced by GetValuesAsAny().

int GetValuesAsFloat	(	DTYPE *	d,
		float *	fval,
		int	num
	)

Retrieves incoming data as an array of floats.

This routine will convert incoming data if possible to an array of floats. If it is not possible to convert to an array of floats an error is returned.

Parameters:

d	is a TINE DTYPE data object containing the incoming data.
fval	is a pointer to the float array to receive the converted input data
num	is the maximum number of array elements which the float array can hold

Returns:

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

See also:

GetValuesAsShort(), GetValuesAsLong(), GetValuesAsDouble()

Alias: GetValuesAsFloat()

Example: (see GetValuesAsShort() for example)

References DUNION::bptr, DTYPE::dArrayLength, DTYPE::data, DTYPE::dFormat, DUNION::dptr, DUNION::fptr, DUNION::lptr, DUNION::sptr, and DUNION::vptr.

Referenced by GetValuesAsAny().

int GetValuesAsLong	(	DTYPE *	d,
		SINT32 *	lval,
		int	num
	)

Retrieves incoming data as an array of long integers.

This routine will convert incoming data if possible to an array of long integers. If it is not possible to convert to an array of long integers an error is returned.

Parameters:

d	is a TINE DTYPE data object containing the incoming data.
lval	is a pointer to the long 32-bit integer array to receive the converted input data
num	is the maximum number of array elements which the long integer array can hold

Returns:

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

See also:

GetValuesAsShort(), GetValuesAsFloat(), GetValuesAsDouble()

Alias: GetValuesAsLong()

Example: (see getValuesAsShort() for example)

References DUNION::bptr, DTYPE::dArrayLength, DTYPE::data, DTYPE::dFormat, DUNION::dptr, DUNION::fptr, DUNION::lptr, DUNION::sptr, and DUNION::vptr.

Referenced by GetValuesAsAny().

int GetValuesAsNAME64DBL	(	DTYPE *	d,
		NAME64DBL *	ndval,
		int	num
	)

Retrieves incoming data as an array of NAME64DBL values.

This routine will convert incoming data if possible to an array of NAME64DBL doublets. For instance, NAME8INT values or NAME32INT values will be cast into NAME64DBL values. If it is not possible to convert to a string an error is returned.

Parameters:

d	is a TINE DTYPE data object containing the incoming data.
ddva	is a pointer to the buffer to receive the converted input data
num	is the maximum size of the string buffer

Returns:

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

See also:

GetValuesAsShort(), GetValuesAsLong(), GetValuesAsFloat(), GetValuesAsDouble()

References DUNION::cptr, DTYPE::dArrayLength, DTYPE::data, DTYPE::dFormat, NAME64DBL::dval, and DUNION::vptr.

int GetValuesAsNAME64DBLDBL	(	DTYPE *	d,
		NAME64DBLDBL *	nddval,
		int	num
	)

Retrieves incoming data as an array of NAME64DBLDBL values.

This routine will convert incoming data if possible to an array of NAME64DBLDBL triplets. For instance, NAME16FLTINT values or NAME32DBLDBL values will be cast into NAME64DBLDBL values. If it is not possible to convert to a string an error is returned.

Parameters:

d	is a TINE DTYPE data object containing the incoming data.
ddva	is a pointer to the buffer to receive the converted input data
num	is the maximum size of the string buffer

Returns:

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

See also:

GetValuesAsShort(), GetValuesAsLong(), GetValuesAsFloat(), GetValuesAsDouble()

References NAME64DBLDBL::d1val, NAME64DBLDBL::d2val, DTYPE::dArrayLength, DTYPE::data, DTYPE::dFormat, NAME64DBLDBL::name, and DUNION::vptr.

int GetValuesAsShort	(	DTYPE *	d,
		short *	sval,
		int	num
	)

Retrieves incoming data as an array of short integers.

This routine will convert incoming data if possible to an array of short integers. If it is not possible to convert to an array of short integers an error is returned.

Parameters:

d	is a TINE DTYPE data object containing the incoming data.
sval	is a pointer to the short integer array to receive the converted input data is the maximum number of array elements which the short integer array can hold

Returns:

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

See also:

GetValuesAsLong(), GetValuesAsFloat(), GetValuesAsDouble()

Alias: GetValuesAsShort

Example:

#include "toolkit.h"
#include "bpmeqm.h"

...

int bpmeqm(char *devName,char *devProperty,DTYPE *dout, DTYPE *din,short access)
{
  int devnr,prpid,i,cc;
  short l_online;

  devnr = GetDeviceNumber(BPMEQM_TAG,devName);
  if (devnr < 0) return illegal_equipment_number;
  prpid = GetPropertyId(BPMEQM_TAG,devProperty);

  switch (prpid)
  {
    case PRP_ONLINE:
        if (access&CA_WRITE) 
        {
          if (din->dArrayLength == PRP_ONLINE_SIZE)
          {
            /* get the set value sent to us : */
            if ((cc=getValuesAsShort(din,&l_online,1)) != 0) return cc;
            /* do range checking : */
            if (l_online < PRP_ONLINE_LOW || l_online > PRP_ONLINE_HIGH) return out_of_range;
            /* apply the setting to the targetted BPM :*/
            bpm[devnr].online = l_online;
          }
          else 
          {
            return dimension_error;
          }
        }
        if (dout->dArrayLength > 0)
        {
          if (dout->dArrayLength > PRP_ONLINE_SIZE) return dimension_error;
          if ((cc=putValuesFromShort(dout,&bpm[devnr].online,1)) != 0) return cc;
        }
        return 0;
    case PRP_STATUS:

  ...

References DUNION::bptr, DTYPE::dArrayLength, DTYPE::data, DTYPE::dFormat, DUNION::dptr, DUNION::fptr, DUNION::lptr, DUNION::sptr, and DUNION::vptr.

Referenced by GetValuesAsAny().

int GetValuesAsString	(	DTYPE *	d,
		char *	str,
		UINT32 *	strBufferSize
	)

Retrieves incoming data as a string buffer.

This routine will convert incoming data if possible to a string representation.

If it is not possible to convert to a string an error is returned.

Parameters:

d	is a TINE DTYPE data object containing the incoming data.
str	is a pointer to the string buffer to receive the converted input data
strBufferSize	is the maximum size of the string buffer [input] and contains the number of characters written into the buffer on completion [output]

Returns:

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

Note:

this routine is suitable for 'dumping' the data as a string output. The elements of a string array will be separated by a carriage-return line-feed. For data conversion, it is perhaps more advisable to use GetValuesAsStringEx() (the counter part to PutValuesFromString()).

See also:

GetValuesAsStringEx()

Alias: getValuesAsString()

References DUNION::bptr, DUNION::cptr, DTYPE::dArrayLength, DTYPE::data, DTYPE::dFormat, DUNION::dptr, DUNION::fptr, DUNION::lptr, DUNION::sptr, and DUNION::vptr.

Referenced by PutValuesFromByteEx(), PutValuesFromDoubleEx(), PutValuesFromFloatEx(), PutValuesFromLongEx(), PutValuesFromShortEx(), PutValuesFromUnsignedLongEx(), and PutValuesFromUnsignedShortEx().

int GetValuesAsStringEx	(	DTYPE *	d,
		char *	str,
		int	fmt,
		int	num,
		int	offset
	)

Prepares incoming data to a string type.

This routine will convert incoming string type data into other string type data if possible. If it is not possible to convert to a string an error is returned.

Parameters:

d	is a TINE DTYPE data object containing the incoming data.
str	is a pointer to the string type which is to hold the converted data.
fmt	is the TINE format specifier for the destination string type (i.e. one of CF_TEXT, CF_NAME16, etc.) of the converted data.
num	is the maximum size of the destination string buffer holding the converted data.
offset	is the entry point of the destination string array (if an array is passed)

Returns:

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

See also:

GetValuesAsShort(), GetValuesAsLong(), GetValuesAsFloat(), GetValuesAsDouble()

References DUNION::bptr, DUNION::cptr, DTYPE::dArrayLength, DTYPE::data, and DTYPE::dFormat.

int PutValuesFromAny	(	DTYPE *	d,
		void *	val,
		short	fmt,
		int	sgn,
		int	objectSizeInBytes,
		int	num,
		int	offset
	)

Submits outgoing data from an array of the given format data type.

This routine will convert outgoing data if possible from an array of the type specified. If it is not possible to convert to an array of unsigned short integers an error is returned.

Parameters:

d	is a TINE DTYPE data object into which the outgoing data is to be copied.
val	is a pointer to the source data
fmt	is the TINE format data type of the source data. This should be one of CF_BYTE, CF_INT16, CF_INT32, CF_FLOAT, or CF_DOUBLE
sgn	is a boolean flag specifying whether format conversion should treat the source data as signed (TRUE) or unsgined (FALSE). This flag applies only to fmt == CF_INT16 or CF_INT32.
objectSizeInBytes	is the size in bytes of the containing object. For instance, 'val' might point to a float value embedded in a structure, so objectSizeInBytes should be the size of the structure in this case. If objectSizeInBytes is smaller than the size of 'fmt' then an error is returned.
num	is the number of array elements contained in the source array
offset	is the starting point in the source data array

Returns:

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

See also:

GetValuesAsAny()

Example:

typedef struct
{
  NAME16 units; 
  double spm; 
  double spr; 
  double tgtPosition; 
  double position; 
  double positionMaximum; 
  double positionMinimum; 
  double positionOffset; 
  double positionScale; 
  double limits[3]; 
  double acceleration; 
  double velocity; 
  double current; 
  UINT32 msps; 
  UINT32 tgtMicroPosition; 
  UINT32 rotationmoveallowed; 
  UINT32 stepcounter; 
  UINT32 microstepcounter; 
  short status; 
  short online; 
  MonitorScan monScan; 
} Motor;

Motor mstTbl[NUM_MSTEQM_DEVICES];


// equipment module dispatch routine
int msteqm(char *devName,char *devProperty,DTYPE *dout, DTYPE *din,short access)
{
  // declarations omitted ...

  switch (prpId)
  {
    // ...

    case PRP_ACCELERATION:
        if (isGroupedCall) return illegal_device;
        if (access&CA_WRITE)
        {
          if (din->dArrayLength > 0)
          {
            if (din->dArrayLength > 1) return dimension_error;
            if ((cc=GetValuesAsDouble(din,&dval,1)) != 0) return cc;
            if (dval > mstTbl[devnr].limits[ACC_UPR_IDX]) return out_of_range;
            if (dval < 0) return out_of_range;
            cc = setMotorAcceleration(devnr,dval);
            if (cc == 0) mstTbl[devnr].acceleration = dval; else return cc;
          }
        }
        if (dout->dArrayLength > 0)
        {
          if (dout->dArrayLength > (UINT32)gNumMotors) return dimension_error;
          // information kept in structure array :
          if ((cc=PutValuesFromAny(dout,&mstTbl[0].acceleration,CF_DOUBLE,TRUE,sizeof(Motor),gNumMotors,devnr)) != 0) return cc;
        }
        return 0;
     
     // ...

  }

References DUNION::bptr, DTYPE::dArrayLength, DTYPE::data, DTYPE::dFormat, PutValuesFromByteEx(), PutValuesFromDoubleEx(), PutValuesFromFloatEx(), PutValuesFromLongEx(), PutValuesFromShortEx(), PutValuesFromString(), PutValuesFromUnsignedLongEx(), and PutValuesFromUnsignedShortEx().

int PutValuesFromByteEx	(	DTYPE *	d,
		BYTE *	bval,
		int	num,
		int	offset
	)

Submits outgoing data from an array of bytes.

This routine will convert outgoing data if possible from an array of bytes. If it is not possible to convert to an array of bytes an error is returned.

Parameters:

d	is a TINE DTYPE data object into which the outgoing data is to be copied.
bval	is a pointer to the byte (unsigned char) array containing the source data
num	is the number of array elements contained in the source array
offset	is the starting point in the source data array

Note:

This is the extended version of PutValuesFromByte(), the difference being that PutValuesFromByteEx() takes a pointer to the entire source array, will begin copying at the offset given, and will wrap the source array if necessary. This feature allows a caller to receive an entire array of data (an orbit for instance) but have the initial element begin at a location of his choosing.

The macro PutValuesFromByte is a call to PutValuesFromByteEx() with offset 0

Returns:

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

See also:

PutValuesFromUnsignedShortEx(), PutValuesFromLongEx(), PutValuesFromFloatEx(), PutValuesFromDoubleEx()

References DUNION::bptr, DUNION::cptr, DTYPE::dArrayLength, DTYPE::data, DTYPE::dFormat, DUNION::dptr, DUNION::fptr, GetValuesAsString(), DUNION::lptr, DUNION::sptr, and DUNION::vptr.

Referenced by PutValuesFromAny().

int PutValuesFromDoubleEx	(	DTYPE *	d,
		double *	dval,
		int	num,
		int	offset
	)

Submits outgoing data from an array of doubles.

This routine will convert outgoing data if possible from an array of doubles. If it is not possible to convert to an array of doubles an error is returned.

Parameters:

d	is a TINE DTYPE data object into which the outgoing data is to be copied.
fval	is a pointer to the double array containing the source data
num	is the number of array elements contained in the source array
offset	is the starting point in the source data array

Note:

This is the extended version of PutValuesFromDouble(), the difference being that PutValuesFromDoubleEx() takes a pointer to the entire source array, will begin copying at the offset given, and will wrap the source array if necessary. This feature allows a caller to receive an entire array of data (an orbit for instance) but have the initial element begin at a location of his choosing.

The macro PutValuesFromDouble is a call to PutValuesFromDoubleEx() with offset 0

Returns:

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

See also:

PutValuesFromShortEx(), PutValuesFromLongEx(), PutValuesFromFloatEx()

Alias: PutValuesFromDoubleEx

Example: (see PutValuesFromFloatEx() for example)

References DUNION::bptr, DUNION::cptr, DTYPE::dArrayLength, DTYPE::data, DTYPE::dFormat, DUNION::dptr, DUNION::fptr, GetValuesAsString(), DUNION::lptr, DUNION::sptr, and DUNION::vptr.

Referenced by PutValuesFromAny().

int PutValuesFromFloatEx	(	DTYPE *	d,
		float *	fval,
		int	num,
		int	offset
	)

Submits outgoing data from an array of floats.

This routine will convert outgoing data if possible from an array of floats. If it is not possible to convert to an array of floats an error is returned.

Parameters:

d	is a TINE DTYPE data object into which the outgoing data is to be copied.
fval	is a pointer to the float array containing the source data
num	is the number of array elements contained in the source array
offset	is the starting point in the source data array

Note:

This is the extended version of PutValuesFromFloat(), the difference being that PutValuesFromFloatEx() takes a pointer to the entire source array, will begin copying at the offset given, and will wrap the source array if necessary. This feature allows a caller to receive an entire array of data (an orbit for instance) but have the initial element begin at a location of his choosing.

The macro PutValuesFromFloat is a call to PutValuesFromFloatEx() with offset 0

Returns:

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

See also:

PutValuesFromUnsignedShortEx(), PutValues(), PutValuesFromLongEx(), PutValuesFromDoubleEx()

Alias: PutValuesFromFloatEx

Example:

#include "toolkit.h"
#include "bpmeqm.h"

int bpmeqm(char *devName,char *devProperty,DTYPE *dout, DTYPE *din,short access)
{
  int devnr,prpid,i,cc;
  short l_online;

  devnr = GetDeviceNumber(BPMEQM_TAG,devName);
  if (devnr < 0) return illegal_equipment_number;
  prpid = GetPropertyId(BPMEQM_TAG,devProperty);

  switch (prpid)
  {
    case PRP_ONLINE:
        ...
        return 0;
    case PRP_STATUS:
        ...
        return 0;
    case PRP_ORBIT_Y:
        if (access&CA_WRITE) return illegal_read_write;
        if (dout->dArrayLength > 0)
        {
          if (dout->dArrayLength > PRP_ORBIT_Y_SIZE) return dimension_error;
          /* return the portion of the vertical orbit requested : */
          if ((cc=putValuesFromFloatEx(dout,g_orbit_yBuffer,PRP_ORBIT_Y_SIZE,devnr)) != 0) return cc;
        }
        return 0;
    case PRP_ORBIT_X:
  ...

References DUNION::bptr, DUNION::cptr, DTYPE::dArrayLength, DTYPE::data, DTYPE::dFormat, DUNION::dptr, DUNION::fptr, GetValuesAsString(), DUNION::lptr, DUNION::sptr, and DUNION::vptr.

Referenced by PutValuesFromAny().

int PutValuesFromLongEx	(	DTYPE *	d,
		SINT32 *	lval,
		int	num,
		int	offset
	)

Submits outgoing data from an array of long integers.

This routine will convert outgoing data if possible from an array of long integers. If it is not possible to convert to an array of long integers an error is returned.

Parameters:

d	is a TINE DTYPE data object into which the outgoing data is to be copied.
lval	is a pointer to the long integer array containing the source data
num	is the number of array elements contained in the source array
offset	is the starting point in the source data array

Note:

This is the extended version of PutValuesFromLong(), the difference being that PutValuesFromLongEx() takes a pointer to the entire source array, will begin copying at the offset given, and will wrap the source array if necessary. This feature allows a caller to receive an entire array of data (an orbit for instance) but have the initial element begin at a location of his choosing.

The macro PutValuesFromLong is a call to PutValuesFromLongEx() with offset 0

Returns:

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

See also:

PutValuesFromUnsignedLongEx(), PutValuesFromShortEx(), PutValuesFromFloatEx(), PutValuesFromDoubleEx()

Alias: PutValuesFromLongEx

Example: (see PutValuesFromFloatEx() for example)

References DUNION::bptr, DUNION::cptr, DTYPE::dArrayLength, DTYPE::data, DTYPE::dFormat, DUNION::dptr, DUNION::fptr, GetValuesAsString(), DUNION::lptr, DUNION::sptr, and DUNION::vptr.

Referenced by PutValuesFromAny().

int PutValuesFromShortEx	(	DTYPE *	d,
		short *	sval,
		int	num,
		int	offset
	)

Submits outgoing data from an array of short integers.

This routine will convert outgoing data if possible from an array of short integers. If it is not possible to convert to an array of short integers an error is returned.

Parameters:

d	is a TINE DTYPE data object into which the outgoing data is to be copied.
sval	is a pointer to the short 16-bit integer array containing the source data
num	is the number of array elements contained in the source array
offset	is the starting point in the source data array

Note:

This is the extended version of PutValuesFromShort(), the difference being that PutValuesFromShortEx() takes a pointer to the entire source array, will begin copying at the offset given, and will wrap the source array if necessary. This feature allows a caller to receive an entire array of data (an orbit for instance) but have the initial element begin at a location of his choosing.

The macro PutValuesFromShort is a call to PutValuesFromShortEx() with offset 0

Returns:

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

See also:

PutValuesFromUnsignedShortEx(), PutValuesFromLongEx(), PutValuesFromFloatEx(), PutValuesFromDoubleEx()

Alias: putValuesFromShortEx

Example:

#include "toolkit.h"
#include "bpmeqm.h"

int bpmeqm(char *devName,char *devProperty,DTYPE *dout, DTYPE *din,short access)
{
  int devnr,prpid,i,cc;
  short l_online;

  devnr = GetDeviceNumber(BPMEQM_TAG,devName);
  if (devnr < 0) return illegal_equipment_number;
  prpid = GetPropertyId(BPMEQM_TAG,devProperty);

  switch (prpid)
  {
    case PRP_ONLINE:
        ...
        return 0;
    case PRP_STATUS:
        if (access&CA_WRITE) return illegal_read_write;
        if (dout->dArrayLength > 0)
        {
          if (dout->dArrayLength > PRP_STATUS_SIZE) return dimension_error;
          /* return the portion of the global status array buffer requested : */
          if ((cc=putValuesFromShortEx(dout,g_statusBuffer,PRP_STATUS_SIZE,devnr)) != 0) return cc;
        }
        return 0;
    case PRP_ORBIT_Y:
   ...

References DUNION::bptr, DUNION::cptr, DTYPE::dArrayLength, DTYPE::data, DTYPE::dFormat, DUNION::dptr, DUNION::fptr, GetValuesAsString(), DUNION::lptr, DUNION::sptr, DUNION::usptr, and DUNION::vptr.

Referenced by PutValuesFromAny().

int PutValuesFromString	(	DTYPE *	d,
		char *	str,
		int	fmt,
		int	num,
		int	offset
	)

Prepares outgoing data as a string type.

This routine will convert output string type data into other string type data if possible. If it is not possible to convert to a string an error is returned.

Parameters:

d	is a TINE DTYPE data object to contain the outgoing data.
str	is a pointer to the string type containing the data to be converted.
fmt	is the TINE format specifier for the string type (i.e. one of CF_TEXT, CF_NAME16, etc.; CF_STRING is also supported here).
num	is the number of array elements contained in the source array
offset	is the starting point in the source data array

Returns:

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

See also:

PutValuesAsShort(), PutValuesAsLong(), PutValuesAsFloat(), PutValuesAsDouble()

Example:

// equipment module dispatch routine
int myeqm(char *devName,char *devProperty,DTYPE *dout, DTYPE *din,short access)
{
  char str[256];
  static int scount = 0;
  // other declarations omitted ...

  switch (prpId)
  {
    // ...

    case PRP_TESTSTRING:
        if (dout->dArrayLength > 0)
        { 
          if (dout->dFormat != CF_TEXT) return illegal_format;
          sprintf(str,"call %d",scount++);
          PutValuesFromString(dout,str,CF_TEXT,256,0);
        }
        return 0;
     
     // ...

  }
  return illegal_property;
}

References DUNION::bptr, DUNION::cptr, DTYPE::dArrayLength, DTYPE::data, and DTYPE::dFormat.

Referenced by PutValuesFromAny().

int PutValuesFromUnsignedLongEx	(	DTYPE *	d,
		UINT32 *	lval,
		int	num,
		int	offset
	)

Submits outgoing data from an array of unsigned long (32-bit) integers.

This routine will convert outgoing data if possible from an array of unsigned long integers. If it is not possible to convert to an array of long integers an error is returned.

Parameters:

d	is a TINE DTYPE data object into which the outgoing data is to be copied.
lval	is a pointer to the long integer array containing the source data
num	is the number of array elements contained in the source array
offset	is the starting point in the source data array

Note:

This is the extended version of PutValuesFromUnsignedLong(), the difference being that PutValuesFromUnsignedLongEx() takes a pointer to the entire source array, will begin copying at the offset given, and will wrap the source array if necessary. This feature allows a caller to receive an entire array of data (an orbit for instance) but have the initial element begin at a location of his choosing.

The macro PutValuesFromLong is a call to PutValuesFromLongEx() with offset 0

Returns:

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

See also:

PutValuesFromUnsignedLongEx(), PutValuesFromShortEx(), PutValuesFromFloatEx(), PutValuesFromDoubleEx()

Alias: PutValuesFromLongEx

Example: (see PutValuesFromFloatEx() for example)

References DUNION::bptr, DUNION::cptr, DTYPE::dArrayLength, DTYPE::data, DTYPE::dFormat, DUNION::dptr, DUNION::fptr, GetValuesAsString(), DUNION::lptr, DUNION::sptr, DUNION::ulptr, and DUNION::vptr.

Referenced by PutValuesFromAny().

int PutValuesFromUnsignedShortEx	(	DTYPE *	d,
		UINT16 *	sval,
		int	num,
		int	offset
	)

Submits outgoing data from an array of unsigned short integers.

This routine will convert outgoing data if possible from an array of unsigned short integers. If it is not possible to convert to an array of unsigned short integers an error is returned.

Parameters:

d	is a TINE DTYPE data object into which the outgoing data is to be copied.
fval	is a pointer to the unsigned short integer array containing the source data
num	is the number of array elements contained in the source array
offset	is the starting point in the source data array

Note:

This is the extended version of PutValuesFromUnsignedShort(), the difference being that PutValuesFromUnsignedShortEx() takes a pointer to the entire source array, will begin copying at the offset given, and will wrap the source array if necessary. This feature allows a caller to receive an entire array of data (an orbit for instance) but have the initial element begin at a location of his choosing.

The macro PutValuesFromUnsignedShort is a call to PutValuesFromUnsignedShortEx() with offset 0

Returns:

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

See also:

PutValuesFromShortEx(), PutValuesFromFloatEx(), PutValuesFromDoubleEx()

Alias: PutValuesFromUnsignedShortEx

Example: (see PutValuesFromFloatEx() for example)

References DUNION::bptr, DUNION::cptr, DTYPE::dArrayLength, DTYPE::data, DTYPE::dFormat, DUNION::dptr, DUNION::fptr, GetValuesAsString(), DUNION::lptr, DUNION::sptr, DUNION::usptr, and DUNION::vptr.

Referenced by PutValuesFromAny().

int RestorePropertyValues	(	const char *	eqmName,
		const char *	prpName,
		void *	values,
		short	format,
		int	size
	)

Retrieves the value settings of the property name given from disk.

Using this routine will restore the given values of the named property from the disk file named <prpName>-settings.csv.

Parameters:

eqmName	is the local equipment module name.
prpName	is the name of the property whose values are to be restored
values	is a reference to the values to be restored
format	is the format of the values to be restored (simple format type)
size	is the array size (not the size in bytes) of the values to be restored.

Returns:

0 if successful, otherwise a TINE completion code

References GetDeviceNumberEx().

Referenced by RegisterPropertyInformation().

int SavePropertyValues	(	const char *	eqmName,
		const char *	prpName,
		void *	values,
		short	format,
		int	size
	)

Saves value settings of the property name given onto disk.

Using this routine will back out the given values of the named property to a disk file named <prpName>-settings.csv.

Parameters:

eqmName	is the local equipment module name.
prpName	is the name of the property whose values are to be stored
values	is a reference to the values to be stored
format	is the format of the values to be stored (simple format type)
size	is the array size (not the size in bytes) of the values to be stored.

Returns:

0 if successful, otherwise a TINE completion code

References SavePropertyValuesEx().

int SavePropertyValuesEx	(	const char *	eqmName,
		const char *	devName,
		const char *	prpName,
		void *	values,
		short	format,
		int	size
	)

Saves value settings of the property name given onto disk (extended version).

Using this routine will back out the given values of the named property to a disk file named <prpName>-settings.csv. The extended version allows passing a device name which is then assumed relevant for locating the targeted property.

Parameters:

eqmName	is the local equipment module name.
devName	is the name of the device whose property prpName is being referred to
prpName	is the name of the property whose values are to be stored
values	is a reference to the values to be stored
format	is the format of the values to be stored (simple format type)
size	is the array size (not the size in bytes) of the values to be stored.

Returns:

0 if successful, otherwise a TINE completion code

References GetDeviceNumberEx().

Referenced by SavePropertyValues().

int SendEventTrigger	(	char *	devname,
		char *	cmt,
		short	triggerLevel
	)

Sends a Post-Mortem (i.e. event) Trigger to the designated Post-Mortem Server.

By making this call, a configured Post-Mortem Server can be sent a trigger initializing the collection of data for the data set specified.

Parameters:

devname	specifies, at a minimum, the event trigger to be acquired. If given in this manner (typically from a server process), the standard event server for the registered context of the server process is assumed. e.g. "bpm-intlk" specifies the trigger "bpm-intlk" for the standard event server for the registered context of the server issuing the event trigger. Otherwise an event-trigger appending full device name is assumed, e.g. "/PETRA/EVENTSTORE/bpm-intlk".
cmt	is any accompanying comment text which should be associated with the post-mortem event. This is typically the reason for the event archive (which modules signalled the alarm, or tripped the interlock, etc.).
triggerLevel	is the level at which the post-mortem event is initialized. Typically a value of "1" should be used to signify beginning at the first step. If a value of "-1" is passed, the post-mortem event will forward the trigger to all other post-mortem servers indentifying itself as the initialized. Other post-mortem servers which may or may not have missed the event can then either react or not according to some pre-coded event critiera. A value of "0" has no effect, and values greater than "1" will step the data recording sequence at a higher (usually unknown) level.

Returns:

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

See also:

GetDeviceServersEx()

---

Variable Documentation

int fecLogFileDepth = 500

Sets the depth in lines of a server's secondary log file (if utilized).

For most cases the system log file "fec.log" is sufficient for logging server activities. Furthermore, "fec.log" is retrievable via a systematic TINE call so that it can be viewed from a remote location without requiring a mount to a file system. However, for more detailing logging you may want to make use of a secondary log file whose name is given by <fecName>.log. This log file resides only on the local file system. You can fix the depth of the this log file by setting this parameter.

See also:

AppendHistoryLog()