Writing Device Servers

Anyone planning to write a device server should be in possession of or have access to two basic documents - Device Server Programmer's Manual, the Automatic Class Generator and the Local Guide (this document). Together these documents describe everything about writing device servers without going into site specific details. Although these documents are fairly uptodate they were not written at the same time and therefore the first one (the programmer's manual) does not refer to the second one (automatic class generator). Do not be put off by this, simply read them in their chronological order.

Whatever you do READ BOTH THESE DOCUMENTS before starting to write your first device server !

Once you have read these two documents return to this document and read on. The seven stages in writing a device server are explained in chapter 5 of the DSPM (cf. figure 4). Follow these stages and you should arrive at a device server.

Code is best produced by using the automatic class generator. This means that once you have decided on what will constitute a device and defined the device commands (action, input and output parameters) the next step is to prepare an input file for the class generator e.g. class.dat. The format of this file is described in the class generator document. Although the class generator is a very useful (I would almost say indispensable) tool neither it nor the document are perfect. Some things to be aware of are :

• the class name as it appears after the classname keyword is used as is in the code and is therefore case sensitive i.e. start all new words and/or abbreviations with a capital letter.
• all object fields entries need all keywords to be specified for correct code to be generated (e.g. even if the field in question does not require a resource it must be specified).
• some types are not correctly supported e.g. the generator does not know how to generate code for a variable length array of doubles (D_VAR_DOUBLEARR) neither for an unsigned long type (D_ULONG_TYPE), and the code has to be modified manually or specify the real type (DevVarDoubleArray and DevULong).

At HartRAO we only have the ascii version of the code generator for SunOS. It can found in the directory /usr/local/bin under the name classgen. Before running it make sure that the environment variable TEMPLATEPATH is pointing to the directory where the template files are stored -

/usr/local/src/dserver/classgen/classes/template

To run classgen type classgen file-name on apus or bootes.

The root directory of the output file to be generated should be

/usr/local/src/nccs/dservers/classes/myclass (where myclass is the name of the new class).

The class generator will generate the following files :

1.

Makefile - the multi-platform GNU make compatible makefile for making the server and client.

2.

Class.c - the source file for implementing the class, this file needs to be edited to add the source code for the individual commands.

3.

ClassP.h - the private include file.

4.

Class.h - the public include file, this file will require editing to add any public symbols or constants which are required by client and server alike.

5.

Class_menu.c - a simple test menu program to test all the commands, this file will require editing if the server uses any ``exotic'' types and to pretty format the menu.

6.

startup.c - a standard startup routine (which will be called by main() for creating, initialising and exporting a list of devices of this class, this file will need editing if any non-standard features are required by the server e.g. creating devices of different classes, special hardware support.

7.

Class.res - an example resource file.

8.

Class.tex - a user's guide in Latex format which can be Latex'ed and distributed to application programmer's, this file will require editing if the input file descriptive text was kept terse.

All these files are generated from a set of template files which can be found in $TEMPLATEPATH/simple in the different subdirectories (src, include, ug and res). These files can be modified (by a device server guru) if necessary to generate different code if a bug is detected or HartRAO wants to simply customize the code to their liking.