The Model Railway
Software
libRailControl
Constants/Functions
Process Comm.
trainctrl
db/dbplan
railctrl
| |
libRailControl
The library libRailControl consists of two files. The header file
"/home/railway/inc/RailControl.h" contains the prototypes of the
library functions along with the definitions of symbolic constants used to specify
block sections, points, and signals. In order to use the library, the files of your
application must contain the pre-processor directive
#include "RailControl.h"
The archive file "/home/railway/lib/libRailControl.a" contains the
object code of the libray functions. Application programs using the library must
therefore be linked with this archive file. This can be done by the additional
command line argument -lRailControl when starting the C compiler or
linker respectively.
By using libRailControl, an application becomes mutli-threaded. This has two major
consequences for an application programmer. First, he must be sure to call only
thread-safe functions from other libraries, including libc. Second, all files of
an application program must be compiled with the switch _REENTRANT
defined. This can most easily be accomplished by calling the C compiler with the
additional argument -D_REENTRANT .
In the case of a runtime error, each function returns the symbolic value
FAILURE . Otherwise a value different from FAILURE
is returned.
7 substitutes for the archive file are provided in order to simplify application
programming.
-
"/home/railway/lib/libRailControl.DUMMY.a"
"/home/railway/lib/libRailControl.DUMMY.PRINT.a"
-
When linking with this archive file, a dummy application is generated. The resulting
program is single-threaded and runs without the model railway.
Instead of really controlling the model railway, the library tries to simulate it.
This means, that all get_... functions will return the value last
set for the specific component and that even the read_M? functions
return values similar to those one would get by controlling the real thing.
Obviously this version is extremly useful during the process of application program
development.
But of course this simulation is not perfect, so by trying to control the model
railway, a control program might have to deal with situations not being
produced by this library.
By using the PRINT version of this library, every get_... ,
set_... and both read_M? functions echo their parameters
and results to stderr before returning.
-
"/home/railway/lib/libRailControl.PERMISSION.a"
"/home/railway/lib/libRailControl.DUMMY.PERMISSION.a"
"/home/railway/lib/libRailControl.DUMMY.PERMISSION.PRINT.a"
-
For using one of these versions of the library, an application has to follow
the process communication concept, outlined by the files
"/home/railway/inc/process.h" ,
"/home/railway/template/pstate.h" and
"/home/railway/template/main.c" .
See Process Comm. for a description of these
files and the underlying idea.
As for the "normal" version of the library, there are again two DUMMY
versions to ease application program development.
-
"/home/railway/lib/libRailControl.ERROR.a"
-
When linking with this archive file, the library functions produce error messages
upon runtime errors in addition to returnung the value
FAILURE .
-
"/home/railway/lib/libRailControl.PROTO.a"
-
When linking with this archive file, a protocol is produced regarding the data
exchange with the electronic interface via the work station's parallel interface.
This feature is primarily intended for debugging libRailControl itself.
Clemens Grelck
generated on: Tue Jul 13 13:31:00 MET DST 1999
|