The SPNBOX functions are used for supervisory control. For descriptions of the purpose of individual functions see the original Matlab manual. For descriptions of the C interfaces, see the spnbox header file.

There are common patterns in the way parameters are used. In general, matrices as defined in matrix.h in the pntool directory are used to represent Petri net matrices, marking and other types of constraint matrices, and some vectors and are passed to SPNBOX functions by pointer. In general, vectors are represented as integer arrays and are passed to SPNBOX functions as pointers to ints. The size of an array is sometimes determined by context, as from the number of rows in matrix, and sometimes explicitly via an integer parameter.

Return types use similar patterns. Matrices and vectors are represented in similar manners. In addition, some functions returns strings as status indications. The various status messages are defined in spnbox.h. These messages are the same ones used in the original Matlab code.

There are a few coding conventions used in the SPNBOX function implementations.

• Most functions have been divided into subroutines, even where the functionality is only used once, to improve the readability of the code. In most files the subroutine division is a fairly natural division of the functionlity, but in a few places the Matlab functions did not lend themselves to obvious logical division. Here, the division into subroutines are somewhat arbitrary.
• Almost every function has at least one subroutine, CheckParams, which checks the function parameters for validity and sometimes sets up defaults. It is typically this function that is responsible for raising an error (via merror defined in pnheaders/general.h) and terminating.
• The functions use a great deal of dynamic memory. Where numerous allocations or an unpredictable number of allocations are made, dynamic memory management routines defined in the support files are used to record the allocations as they are made and free them all at the end of the function. Sometimes, however, the number of allocations is small enough that the management functions are not used.
• All allocation is done via the safe wrappers tcalloc and tmalloc defined in general.h.

Some functions can print status messages to stdout during execution. How many of these messages will be printed is determined by a function int is_verbose(), declared but not implemented in general.h. Verbosity is set by a custom implementation of the is_verbose() fuction. The integer returned by the function is the verbosity level. A higher level indicates a request to print more detail. The minimum, 0, means no message except those absolutely necessary should be printed. The maximum is 10. In the SPNBOX functions, each function has a verbosity threshold. It will print its messages only if the verbosity is at its threshold. Thresholds are defined in the main header file. Functions that are called by other functions should have a higher verbosity threshold so that their messages are displayed less readily.

spnbox.h is the primary header file for the SPNBOX functions. It defines all the SPNBOX functions and all the necessary option macros, message strings, return type structures, and a few specialized parameter structures.

To build SPNBOX for use with ACTS, move to the pntool/spnbox/ directory and run make with the default target. This will build all object files for all the SPNBOX functions, as well as the support files used by them.

Note that this will also check to make sure that the support file liblpsolve55.a, the compiled linear programming library, is present. If it is not, the makefile will change directories to the third-party directory where the lpsolve files reside and run its linux-targeted makefile.