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.