SUBJECT "On XClassGen"
	XClassGen was developed by Laurent Claustre at the 
		European synchrotron Radiation Facility,
			Grenoble, France 1993.


The Control Group has written roughly 90 high level device classes for  
equipment interfaced to the accelerators and it seems obvious that we
should make the implementation of the future device servers easier. 
This is possible with an automatic class generation tool.

The Generator should, starting from a set of input specifications, 
automatically produce all the files necessary to implement a device
class. It is not possible to automatically generate the device specific,
only skeleton files which require editing in order to implement the
full functionality.

The main goal of a such generator is to prepare the work for the device
class programmer in the most efficient way and to provide a standard
representation for all the classes (e.g. source, includes, user's guide,
directory structure ...).

The generator can provide two kinds of classes. One class type contains
one process; the other class contains two processes.

SEE ALSO "On Template"
SEE ALSO "On Two Process Device Server"

SUBJECT "On Header"
The header serves to specify the name of the class and some informations
which will allow to identify the device server (the project, the author
(s), etc ...).

The Class Name:
A divice class start with a capital letter and use uppercase for 
compound words. an example:
	- AGPowerSupply

The Root Directory:
	This information defines where you want to generate the target 
	files. This director should be created before using the 
	generator. The generator will create all the subdirectories 
	(src, include, RCS, ...). An Example: 
	- /users/a/dserver/dev/TeslaHall

The Project:
	To describe the project where the device server will be used.A

The Initial Date:
	Give the original starting date.

The Author(s):
	The name of the developer(s).

The Class Description:
	Here you can describe your device server (if you want), this 
	description will be inserted in the header of the file class.c, 
	and in the chapter `Description' in the user's guide.

SUBJECT "On Superclass"
If you want to use superclass, you will give its name. Remember you that
a divice class start with a capital letter and use uppercase for 
compound words. an example:
	- AGPowerSupply

SUBJECT "On State"
All the data which are given  to the state machine will be used to 
generate the state_handler method and the chapter State machine of 
the user's guide.

The State Name:
	You can only use the defined states found in the file
	$DSHOME/include/DevStates.h. Example:
	- DEVSTANDBY

The State Description:
	This description will be inserted as comment in the 
	state_handler() routine and in the users's guide of the device
	server (section State machine).


SUBJECT "On Allowed Command"
It's the allowed command for the current state. You must 
only specify the command which modifies the state.

The Allowed Command Name:
	You can only use  commands names defined in the 
	$DSHOME/include/DevCmds.h file. Example:
	- DevSetValue

The New State:
	You can only use the defined states found in the file
	$DSHOME/include/DevStates.h. Example:
	- DEVOFF
	

SUBJECT "On Forbidden Command"
It's the forbidden command for the current state.You can only use  
commands names defined in the $DSHOME/include/DevCmds.h 
file.



SUBJECT "On Classfield"
This part allows you to define the fields of the class (i.e. the typedef
structure classClassPart). The generator will use this information
to make the classP.h file, the class.c file (to implement the resource
table, the class_initialize method) and the class.res file (to 
implement the resource value of the class fields).

N.B.: The generator will automatically generate a state resource called
state with the value DEVON. The field ds->devserver.state is set with
this value by the class_initialize method.

The Classfield Name:
	This is the name of the classfield, it will be used in the 
	classP.h and class.c files.

The Classfield Type:
	This is the type of the class field. If a resource is not 
	specified for this field you can directly use C types or types
	defined in the $DSHOME/include/dev_xdr.h
	file. Examples:
	- long
	- Devstring

	If you define a resource,you must use only the types defined 
	in the $DSHOME/include/dev_xdr.h file.
	Example:
	-D_LONG_TYPE

The Default Value:
	A hardwired default value for class fields used in the 
	class_initialize method.

The Classfield Description:
	you can give a description of classfields. It will be inserted
	in the classP.h file.

The Resource Name:
	If you want to define a resource for this field you must give
	a name for this resource; if possible, use the same name for 
	the classfield and the resource.

The Resource Value:
	Defined the resource value (useful only if a resource name been
	previously defined).



SUBJECT "On Objectfield"
Here, you must describe the object fields of your class. The data
provided will allow implemention of the classP.h (to code the typedef
structure classPart) and the class.c (to code the resource table for 
objects and to code the object_initialize method) files.

The Objectfield Name:
	This is the name of the object field, it will be use in the 
	classP.h and class.c files.

The Objectfield Type:
	See Classfield Type section in the help on Classfield.

The Default Value:
	You must state default values, if you want the object_initialize
	method initialize the object fields before to get the database 
	resources.

The Objectfield Description:
	You can give a description of object fields. It will be 
	inserted in the classP.h file.

The Resource Name:
	If you want to provide a resource for this field you must give
	a name for this resource. If possible, use the same name for the
	object field and the resource.

	

SUBJECT "On Command"
All the required commands should be described in the command list. The
information given for each command will allow generation of the command
headers, the commandlist structure and so on.

The Command name:
	You can only use  commands names defined in the 
	$DSHOME/DevCmds.h file. Example:
	- DevSetValue

The Command Description:
	Give a description of the command. This description will be
	used to generate the command header and the user's guide.

The Argument In Type:
	You can only use the types available in the 
	$DSHOME/include/xdr_typelist.h file. Example:
	- D_STRING_TYPE

The Argument In Description:
	Give a description of the argin. This description will be used
	to generate the command header and the user's guide.

The Argument Out Type:
	You can only use the types defined in the file 
	$DSHOME/include/xdr_typelist.h file. Example:
	- D_VAR_STRINGARR

The Argument Out Description:
	As argin description.

The Error Code List:
	You can give the error codes that the command return in case of
	failure. These errors  are defined in the file 
	$DSHOME/include/DevErrors.h. This list will be
	inserted in the command header and in the user's guide. Example:
	- DevErr_DeviceWrite DevErr_DeviceRead


SUBJECT "On Template"
xclassgen generates the target files from a set of template files. 
The notion of template files is important for maintenance of the 
generator. By modifying the template files evolutionary changes to
the device classes can be incorporated any modifications to the 
generator.



SUBJECT "On Two Process Device Server"
The generator can provide two kinds of classes. One class contains
a single process and another class contains two processes the server
process and the subprocess. The server process and the subprocess 
communicate via Dataports (shared memory), and the subprocess works
continiously tp update the shared memory. We use the interprocess 
communication model provided by David carron. He has made a library of 
five routines (dataport library) to use this model. For more 
details see the MCSN040 (The Data Port) document.

The main goal of a two processes Device Server is to make the subprocess
perform a continious task and communicate directly with the device.
The server process communicates with the client and always waits for a 
command from clients. The subprocess is a infinite loop. 

The source code of the subprocess should be contained in the Class_sub.c
file. The shared structure will be defined in the ClassP.h header file.
The reader could consult the template files (on $DSHOME/classes/
template/subproc) to get a better understanding. 

The subprocess will be created and the Dataport opened by the 
class_initialize() routine. All the necessary source code has been
added to check if the sunprocess already exists and if the shared 
memory is allocated.

When a Device Server is generated, the reader should complete the shared
structure with variables shared by the two processes to make it possible
for the user to use the dataport and implement the commands which will
use the shared memory.
