# An ASCII interface to device server API

## Table of Contents

1 Data type used for input and output arguments
2 Conversion of types to and from string
3 The functions of the library

3.1 Examples for "dev_get_ascii" function
3.2 Examples for "dev_put_ascii" function
3.3 Examples for "dev_putget_ascii" function

4 Library locations

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.

## 2 Conversion of types to and from string

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 :

- D_VOID_TYPE

- D_USHORT_TYPE

- D_SHORT_TYPE

- D_ULONG_TYPE

- D_LONG_TYPE

- D_FLOAT_TYPE

- D_DOUBLE_TYPE

- D_STRING_TYPE

- D_INT_FLOAT_TYPE

- D_FLOAT_READPOINT

- D_STATE_FLOAT_READPOINT

- D_LONG_READPOINT

- D_DOUBLE_READPOINT

- D_VAR_CHARARR

- D_VAR_STRINGARR

- D_VAR_USHORTARR

- D_VAR_SHORTARR

- D_VAR_ULONGARR

- D_VAR_LONGARR

- D_VAR_FLOATARR

- D_VAR_DOUBLEARR

## 3 The functions of the 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.

- dev_get_ascii("tl1/ps-d/d", "DevState", &my_out_string, &my_error_string) this call will return the following values :

  my_out_string = "DevShort.\n2\n"
  my_error_string = "dev_get_ascii succeeded.\n"

- dev_get_ascii("tl1/ps-d/d", "DevStatus", &my_out_string, &my_error_string) this call will return the following values :

  my_out_string = "DevString.\nOn\n"
  my_error_string = "dev_get_ascii succeeded.\n"

### 3.2 Examples for "dev_put_ascii" function

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 :

- DevUShort,DevShort,DevULong and DevLong : the string must contain a numeric data (composed of numeric characters only) eventually preceded and followed by authorized white characters (space, tabs, return).

  example :
  " 345 " or " -99 "
  dev_put_ascii("tt/pp/1", "DevSet", " +345 ", &my_error_string)

- DevFloat and DevDouble : the string must contain a floating point data (composed of numeric characters and dot "." only) eventually preceded and followed by authorized white characters (space, tabs, return).

  example :
  "3.00678" or " -98.7746 "
  dev_put_ascii("tt/pp/1", "DevSet", " 12.39876 ", &my_error_string)

- DevString : the string must contain the DevString data to be passed to the device server command inside two (starting and ending) double quotes.

  example :
  "\"This is the DevString to be passed to the command.\""
  note that the first character and the last character of the string should be the double quotes.
  dev_put_ascii("tt/pp/1", "DevSet", "\"Coucou\"", &my_error_string)

- DevIntFloat : the string contains two items. The first one is a DevLong data so it should respect the format defined above and the second item is a DevFloat data respecting the corresponding format defined above. These two items are separated by at least one authorized white characters (space, tabs, return). Each of them can eventually be preceded and / or followed by one or more authorized white characters (space, tabs, return).

  example :
  "6454 765.0987" or " 64747 464.8747 "
  dev_put_ascii("tt/pp/1", "DevSet", " 64747 464.8747 ", &my_error_string)

- DevFloatReadPoint, DevDoubleReadPoint and DevLongReadPoint : The string is composed of two items. Both of them are either float data (respecting the format described above DevFloat, DevDouble) or long decimal data (respecting the format described above DevUShort,DevShort,DevULong and DevLong). These two items are separated by at least one authorized white characters (space, tabs, return). Each of them can eventually be preceded and / or followed by one or more authorized white characters (space, tabs, return).

  example :
  "6454 765" or " 987 64 " or "765.09 464.87 "
  dev_put_ascii("tt/pp/1", "DevSet", " 987 64 ", &my_error_string)
  dev_put_ascii("tt/pp/1", "DevSet", " 765.09 464.87 ", &my_error_string)

- DevStateFloatReadPoint : The string is composed of three items. The first one is a DevShort data respecting the corresponding format described above. The next two items are the DevFloat data respecting the corresponding format described above. These three items are separated by at least one authorized white characters (space, tabs, return). Each of them can eventually be preceded and / or followed by one or more authorized white characters (space, tabs, return).

  example :
  "454 765.09 464.87" or " 454 765.09 464.87 "
  dev_put_ascii("tt/pp/1", "DevSet", " 454 765.09 464.87 ", &my_error_string)

- DevVarCharArray : The string for this data type can be any string.

  example :
  "Here is an example for a DevVarCharArray data."
  Note that the first character and the last character are not double quotes in this case.
  dev_put_ascii("tt/pp/1", "DevSet", " This is a CharArray", &my_error_string)

- DevVarStringArray : The string contains N items. N is the number of DevString data to be put into the array. Each DevString item should start with a double quotes and end with the double quotes also. Two consecutive DevString items can be separated by zero or more characters which can be ANY character including white characters, commas, and all other characters.

  example :
  " \"first DevString!\" , \"Second DevString data.\"\"Last DevString.\" "
  Note that the number of DevString read from the input string is the number of double quotes divided by 2. The most important characteristic of this string format is that each DevString item should be between two double quotes.
  dev_put_ascii("tt/pp/1", "DevSet", "\"first DevString!\" , \"Second DevString data.\"\"Last DevString.\"", &my_error_string)

- DevVarUShortArray, DevVarShortArray, DevVarULongArray, DevVarLongArray, DevVarFloatArray, DevVarDoubleArray : The string contains a sequence of either decimal numeric items or float data items. Each item respects the corresponding format described above. Each item MUST be followed by a comma (,) even the last item. The characters authorized for this string are : all numeric characters, `-', space, tabs, return, dot `.', and comma (,). The number of items read from the string is determined by the number of commas in that string.

  example :
  " 45,465 , 665, 645,78, " or " 3.4, 8.9 , 576.098, "
  dev_put_ascii("tt/pp/1", "DevSet", "45,465 , 665, 645,78,", &my_error_string)
  dev_put_ascii("tt/pp/1", "DevSet", "3.4, 8.9 , 576.098, ", &my_error_string)

### 3.3 Examples for "dev_putget_ascii" function

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.

## 4 Library locations

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 : "

/users/d/dserver/system/type_conv

The root of the developpement directory for the ascii devapi library is : "

/users/d/dserver/system/ascii_dev

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