TINE EZ client documentation. More...

#include "listener.h"

Data Structures
struct	ezDblArray
	Defines the double array type returned by ezGetDblValues() More...
struct	ezIntArray
	Defines the double array type returned by ezGetIntValues() More...
struct	ezResult
	Defines the 'Result' Object for the EZ TINE interface. More...
struct	ezStrArray
	Defines the double array type returned by ezGetStrValues() and ezGetChannels() More...
Functions
int	ezAddMonitor (ezResult res, void(nf)(int), int nid)
	attaches a monitor 'notifier' function to the given result object
int	ezFreeResult (ezResult *res)
	Frees an EZ result object.
ezResult *	ezGet (char *fullNameAndProperty,...)
	Gets the resulting data and status according the target parameter(s) given.
ezStrArray	ezGetChannels (ezResult *res)
	Get the channel names associated with an EZ result object.
ezDblArray	ezGetDblValues (ezResult *res)
	Returns an ezDblArray according to the EZ result object passed.
ezIntArray	ezGetIntValues (ezResult *res)
	Returns an ezIntArray according to the EZ result object passed.
ezStrArray	ezGetStrValues (ezResult *res)
	Returns an ezStrArray according to the EZ result object passed.
ezResult *	ezSet (char *fullNameAndProperty,...)
	Sets the input data on the target given.
char *	ezToString (ezResult *res)
	Returns a character string containing the returned data values.

Detailed Description

TINE EZ client documentation.

Function Documentation

int ezAddMonitor	(	ezResult *	res,
		void(*)(int)	nf,
		int	nid
	)

attaches a monitor 'notifier' function to the given result object

Calls to ezGet() or ezSet() will create an EZ Result object (if one does not already exist). This routine will attach a notifier funtion of the caller's chosing to the internal data listener attached to the result object. The listener will call the supplied notifier function when new data have arrived, which could server a signal to make a fresh call to ezGet() (as opposed to polling from within the application).

Parameters:

res	is EZ Result object to which the notifier should be attached.
nf	is the caller supplied notifier function, which must have the prototype 'void function(int id)'.
nid	is the caller supplied notification 'id' which will be returned in the call to the monitor notifier.

example:

Returns:: 0 upon success otherwise a TINE error code.

References ezResult::idListener, and ezResult::key.

int ezFreeResult ( ezResult * res )

Frees an EZ result object.

Calls to ezGet() or ezSet() will create an EZ Result object (if one does not already exist). The result object will reserve memory and occupy a spot in a hash table until it is explicity freed via this call or until the application program ends. A result object is specifically tied to the input parameter(s) provided in the call to ezGet() or ezSet() and is therefore created only once for a given set of parameters.

Parameters:

res	is EZ Result object to be freed.

Returns:: 0 upon success or a TINE error code.

References ezResult::devLst, ezResult::dout, ezResult::idListener, ezResult::key, ezResult::nxt, ezResult::prv, ezResult::scratch, and ezResult::scratchNames.

ezResult* ezGet	(	char *	fullNameAndProperty,
			...
	)

Gets the resulting data and status according the target parameter(s) given.

The returned 'result' object contains the data returned from the call according to the target's default registered information (concerning data lengths and types).

Parameters:

fullNameAndProperty is a single string containing the fully specified context, server name, device name, and property of the the desired target. This can be either of the form '/context/server/device/property' (i.e. 'property' included in the hierarchy) or '/context/server/device[property]') (i.e. 'property' distinguished via '[]'). The latter is occasionally easier to view and parse when the 'device' name itself contains '/' characters (so as to extend the hierarchy).

input can be optionally provided in analogy with the printf() family of C functions. If input is provided, the 'fullNameAndProperty' text should be extended to include an input'pipe' character '<' followed by 'd' or 'g' to indicate either integer or float values as further input. A 'D' can also be supplied, indicating that a pointer to a tine DTYPE object will be input (which can then provide any complex data input required).

Note:: Most 'get' calls do not require input, so this function can be used in its most simple form in the vast majority of cases. Those 'get' calls which do take input typically require one or two integer or float values, making simple 'printf' style input a viable option.

example:

#include "tine.h"
#include "eztine.h"

void myEzTask(void)
{
  ezResult *ezr;
  ezStrArray ezs;
  ezDblArray orbx;
  int i;

  //
  // get the petra horizontal orbit (start at 1st device)
  //
  ezr = ezGet("/PETRA/BPM/#0[Orbit.X]");
  if (ezr == NULL || ezr->status != 0) 
  { // jump out with error message:
    printf("error getting orbit: <%d>\n",ezr ? ezr->status : -1);
    goto err;
  }
  // get the channels:
  ezs = ezGetChannels(ezr);    
  // get the channel values as double array:
  orbx = ezGetDblValues(ezr);
  // dump to screen:
  if (ezs.length != orbx.length)
  { // jump out with error message:
    printf("unexpected : %d channel names vs. %d channel positions\n",ezs.length,orbx.length);
    goto err;
  }
  printf("horizontal positions:\n");
  for (i=0; i<orbx.length && i<20; i++)
  {
    printf("%.64s : %g\n",ezs.values[i],orbx.values[i]);
  }

  // ...

  //
  // get an echo from a test server (READ property with input):
  //
  ezr = ezGet("/TEST/SineServer/SineGen0[Echo] <%d %d",33,66);
  if (ezr == NULL || ezr->status != 0) 
  { // jump out with error message:
    printf("error getting echo: <%d>\n",ezr ? ezr->status : -1);
    goto err;
  }
  printf("Echo:\n%s\n",ezToString(ezr));

  // ...

  //
  // accomplish the same Echo call another way:
  //
  {
    DTYPE din;
    int i, ivals[2] = { 55, 77 };
    memset(&din,0,sizeof(DTYPE));
    din.dFormat = CF_INT32;
    din.dArrayLength = 2;
    din.data.lptr = ivals;
    ezr = ezGet("/TEST/SineServer/SineGen0[Echo] <%D",&din);
    if (ezr == NULL || ezr->status != 0) 
    { // jump out with error message:
      printf("error getting echo: <%d>\n",ezr ? ezr->status : -1);
      goto err;
    }
  }

  // ...

err:
 return;
}

Returns:: an ezResult object containing the results

See also:: ezGetDblValues(), ezGetIntValues(), ezGetStrValues()

References ezResult::din, ezResult::dout, ezResult::idListener, ezResult::lengthUpdate, ezResult::status, and ezResult::timeUpdate.

ezStrArray ezGetChannels ( ezResult * res )

Get the channel names associated with an EZ result object.

If the result object is associated with a known multi-channel array, then the channel names are returned. Otherwise the 'device' name used to establish the result object is returned;

Parameters:

res	is EZ Result object for which the channel names should be returned.

Note:: The array returned within the ezStrArray object is 'volatile' in the sense that it points to a 'scratch' buffer within the result object. This array should consequently be either used or copied prior to any futher call to ezGetDblValues(), ezGetIntValues(), ezGetStrValues(), or ezGetChannels(), which also make use of the scratch buffer.

Returns:: an ezStrArray containing the channel names

References ezResult::devLst, ezResult::dout, ezResult::key, ezStrArray::length, ezResult::scratchNames, ezResult::status, ezStrArray::status, ezStrArray::timeValid, and ezStrArray::values.

ezDblArray ezGetDblValues ( ezResult * res )

Returns an ezDblArray according to the EZ result object passed.

Calls to ezGet() or ezSet() will create an EZ Result object (if one does not already exist). The result object contains the returned data (in the 'dout' field) which may or may not refer to a double array. The 'dout' object can be examined to determine the data type returned if necessary. Otherwise a call to ezGetDblValues() will attempt to convert the returned data to a double array. If this is not possible then an empty array is returned and the 'status' field of the result object passed is set to indicate the problem as well as the 'status' field of the ezDblArray.

Note:: compound data types such as 'DBLDBL' or 'USTRING', etc. which do contain at least one data field which can be converted to a double result in the first (or primary) number field being used to establish the double array. In such cases, the ezDblArray returned contains an array of doubles but with the 'status' field set to 'ambiguous'.

Parameters:

res	is EZ Result object whose data should be used to form an ezDblArray.

Note:: The array returned within the ezDblArray object is 'volatile' in the sense that it points to a 'scratch' buffer within the result object. This array should consequently be either used or copied prior to any futher call to ezGetDblValues(), ezGetIntValues(), or ezGetStrValues(), which also make use of the scratch buffer. On the other hand, repeated calls to ezGetDblValues() using the same result object will only overwrite the contents of the existing double array, which might be the desired result.

Returns:: ezDblArray (which could be zero length if there is a problem)

See also:: ezGetIntValues(), ezGetStrValues(), ezGetChannels()

References ezResult::dout, ezResult::idListener, ezDblArray::length, ezResult::lengthUpdate, ezResult::scratch, ezResult::scratchCapacity, ezResult::status, ezDblArray::status, ezResult::timeUpdate, ezDblArray::timeValid, and ezDblArray::values.

ezIntArray ezGetIntValues ( ezResult * res )

Returns an ezIntArray according to the EZ result object passed.

Calls to ezGet() or ezSet() will create an EZ Result object (if one does not already exist). The result object contains the returned data (in the 'dout' field) which may or may not refer to an integer array. The 'dout' object can be examined to determine the data type returned if necessary. Otherwise a call to ezGetIntValues() will attempt to convert the returned data to an integer array. If this is not possible then an empty array is returned and the 'status' field of the result object passed is set to indicate the problem as well as the 'status' field of the ezIntArray.

Note:: compound data types such as 'DBLDBL' or 'USTRING', etc. which do contain at least one data field which can be converted to an integer result in the first (or primary) number field being used to establish the double array. In such cases, the ezIntArray returned contains an array of doubles but with the 'status' field set to 'ambiguous'.

Parameters:

res	is EZ Result object whose data should be used to form an ezIntArray.

Note:: The array returned within the ezIntArray object is 'volatile' in the sense that it points to a 'scratch' buffer within the result object. This array should consequently be either used or copied prior to any futher call to ezGetDblValues(), ezGetIntValues(), or ezGetStrValues(), which also make use of the scratch buffer. On the other hand, repeated calls to ezGetIntValues() using the same result object will only overwrite the contents of the existing double array, which might be the desired result.

Returns:: ezIntArray (which could be zero length if there is a problem)

See also:: ezGetDblValues(), ezGetStrValues(), ezGetChannels()

References ezResult::dout, ezResult::idListener, ezIntArray::length, ezResult::lengthUpdate, ezResult::scratch, ezResult::scratchCapacity, ezResult::status, ezIntArray::status, ezResult::timeUpdate, ezIntArray::timeValid, and ezIntArray::values.

ezStrArray ezGetStrValues ( ezResult * res )

Returns an ezStrArray according to the EZ result object passed.

Calls to ezGet() or ezSet() will create an EZ Result object (if one does not already exist). The result object contains the returned data (in the 'dout' field) which may or may not refer to a string-type array. The 'dout' object can be examined to determine the data type returned if necessary. Otherwise a call to ezGetStrValues() will attempt to convert the returned data to a string array. If this is not possible then an empty array is returned and the 'status' field of the result object passed is set to indicate the problem as well as the 'status' field of the ezStrArray.

Parameters:

res	is EZ Result object whose data should be used to form an ezStrArray.

Note:: The array returned within the ezStrArray object is 'volatile' in the sense that it points to a 'scratch' buffer within the result object. This array should consequently be either used or copied prior to any futher call to ezGetDblValues(), ezGetIntValues(), or ezGetStrValues(), which also make use of the scratch buffer. On the other hand, repeated calls to ezGetStrValues() using the same result object will only overwrite the contents of the existing double array, which might be the desired result.

Returns:: ezStrArray (which could be zero length if there is a problem)

See also:: ezGetIntValues(), ezGetDblValues(), ezGetChannels()

References ezResult::dout, ezResult::idListener, ezStrArray::length, ezResult::lengthUpdate, ezResult::scratch, ezResult::scratchCapacity, ezResult::status, ezStrArray::status, ezResult::timeUpdate, ezStrArray::timeValid, and ezStrArray::values.

ezResult* ezSet	(	char *	fullNameAndProperty,
			...
	)

Sets the input data on the target given.

The returned 'result' object contains any data returned from the call according to the target's default registered information (concerning data lengths and types). Thus this call is also a 'set/get' operation if the target support this. The user is free to ignore any returned data if the purpose of the operation was only a 'set'. This call will apply 'WRITE' access to the 'set' operation (as opposed to a call to ezGet() with the same parameters as ezSet().

Parameters:

fullNameAndProperty is a single string containing the fully specified context, server name, device name, and property of the the desired target. This can be either of the form '/context/server/device/property' (i.e. 'property' included in the hierarchy) or '/context/server/device[property]') (i.e. 'property' distinguished via '[]'). The latter is occasionally easier to view and parse when the 'device' name itself contains '/' characters (so as to extend the hierarchy).

input can be optionally provided in analogy with the printf() family of C functions. If input is provided, the 'fullNameAndProperty' text should be extended to include an input'pipe' character '<' followed by 'd' or 'g' to indicate either integer or float values as further input. A 'D' can also be supplied, indicating that a pointer to a tine DTYPE object will be input (which can then provide any complex data input required).

example:

Returns:: an ezResult object containing the results

References ezResult::din, ezResult::dout, ezResult::lengthUpdate, ezResult::status, and ezResult::timeUpdate.

char* ezToString ( ezResult * res )

Returns a character string containing the returned data values.

Calls to ezGet() or ezSet() will create an EZ Result object (if one does not already exist). This routine returns a string containing the returned data (one element per line of output).

Parameters:

res	is EZ Result object whose data should be dumped to a string.

Returns:: a string representation of the data.

References ezResult::dout, ezResult::lengthUpdate, and ezResult::status.

Data Structures

Functions

Detailed Description

Function Documentation