The AscApi shared library (libascapi.sl) is developped to provide an Ascii based interface to the device server API. This Ascii interface will be used to interfece the HP VEETEST software with the ESRF control system.
Table of Contents:
1Data type used for input and output arguments3
2Conversion of types to and from string3
3The functions of the library5
3.1Examples for "dev_get_ascii" function6
3.2Examples for "dev_put_ascii" function6
3.3Examples for "dev_putget_ascii" function8
4Library locations8
1 Data type used for input and output arguments
The type used to send or to get data to or from AscApi library is "string". The strings are used as defined in C programming language.
Therefore all the necessary information to execute a command on a device server should be sent in string format. This means that the device name, command name, input argument for that command (if needed) and output argument are all strings.
There are a lot of data types defined and used by the components of the ESRF control system to perform an action on a device or to get the information from a device. So to be able to send and to receive the information in a unique data type and format the type conversions are performed in two directions : from control system data types to string , from string to the control system data types.
It has been decided that all these conversion functions are developped in a separate shared library so it can easily be extended to new types, and also adaptable to other software (applications) needs.
In a first step, only the kernel data types have conversion functions to and from string. The other conversion functions (for other data types) can easily be added in the type conversion shared library "libtcapi.sl".
For the moment the following types are converted in the so-called "type conversion (libtcapi.sl)" library :
There will be three main functions in the library :
dev_get_acsii
long dev_get_ascii(char *dev_name, char *cmd_name, char **out_arg, char **str_err)
This function is used for all the device server commands which do not require any input argument. The first two parameters are the input parameters which give the indication on the device name and the command name to be executed on that device. The last two parameters are the output parameters which contain respectively the result returned by the device server command and an error string if any error occured. The output parameters : out_arg and str_err should be allocated by the caller of the function. The dev_get_ascii function does not do ANY allocation for these strings and supposes that enough memory space has been allocated for them.
dev_put_ascii
long dev_put_ascii(char *dev_name, char *cmd_name, char *in_arg, char **str_err)
This function is used for all the device server commands which do not return any output argument. The first two parameters are the input parameters which give the indication on the device name and the command name to be executed on that device. The third parameter is the input data required by the device server command.The last parameter is the output parameter which contain the error occured during the execution of the device server command. The output parameter : str_err should be allocated by the caller of the function. The dev_put_ascii function does not do ANY allocation for this string and supposes that enough memory space has been allocated for it.
As explained before, the "in_arg" parameter is the input argument required by the device server command in string format. This string must repect a strict format so that dev_put_ascii can convert it to the data type expected by the device command. To know which format should be used, refer to the following section where an example is given for each data type.
dev_putget_ascii
long dev_putget_ascii(char *dev_name, char *cmd_name, char *in_arg, char **out_arg, char **str_err)
This function is used for all the device server commands which do require an input argument as well as an output argument. The first two parameters are the input parameters which give the indication on the device name and the command name to be executed on that device. The third parameter is the input data required by the device server command.The last two parameters are the output parameters which contain respectively the result of the device server command and an error string if any. The output parameters : out_arg and str_err should be allocated by the caller of the function. The dev_putget_ascii function does not do ANY allocation for these strings and supposes that enough memory space has been allocated for them.
3.1
Examples for "dev_get_ascii" function
Since this function is called when no input argument is required for the device server command, it is very simple to use. There is no particular format to be followed. The dev_name parameter should contain a string which is the name of a device exported in the static data base. The cmd_name parameter should contain a string which is the name of a command defined for this device and which does not require any input argument.
This function is used for all device server commands which require an input argument and do not return any output argument. The input argument (in_arg) passed through this function is a string. But according to the type of the input argument expected by the device server command this string must follow a precise format.
Here are the string formats for each of the control system data types :
This function is used for all device server commands which need an input argument and which also return an output argument. The input argument is passed through this function under the form of a string. But according to the type of the input argument expected by the device server command this string must follow a precise format. These formats are already defined in the previous section (3.2).
To know how to define the first two parameters (dev_name and cmd_name) refer to the examples in the sections 3.1 or 3.2.
To know how to define the third parameter (in_arg) refer to the examples in the section 3.2.
The two libraries are called respectively "libtcapi.sl" for the type conversion library and "libascapi.sl" for the acii interface to device server api. Note that "libascapi.sl" dynamically loads "libtcapi.sl" and references it.
The root of the developpement directory for the type conversion library is : "
The root of the developpement directory for the ascii devapi library is : "
The header files for these libraries are installed in :
/users/d/dserver/dev/include and /users/d/dserver/include
The libraries themselves are installed in :
/users/d/dserver/dev/lib/shared/s700 and /users/d/dserver/lib/shared/s700