NAME

cxDataCheckingSet - create a vector of the given type.
#include <cx/DataOps.h>

typedef enum { cx_check_magic cx_check_mem_bounds } cxDataCheckLevel;
typedef enum { cx_check_ignore cx_check_warning cx_check_halt cx_check_abort cx_check_callback } cxDataCheckAction;
typedef void (*cxDataCheckCallback)( cxDataCheckErrorInfo*, void* );
void cxDataCheckingSet( cxDataCheckLevel level, cxDataCheckAction action, cxDataCheckCallback callback );
integer cx_check_magic
integer cx_check_mem_bounds

parameter (cx_check_magic = 0) parameter (cx_check_mem_bounds = 1)
integer cx_check_ignore integer cx_check_warning integer cx_check_halt integer cx_check_abort integer cx_check_callback
parameter (cx_check_ignore = 0) parameter (cx_check_warning = 1) parameter (cx_check_halt = 2) parameter (cx_check_abort = 3) parameter (cx_check_callback = 4)
typedef void (*cxDataCheckCallback)( cxDataCheckError, void* );
subroutine cxDataCheckingSet( level, action, callback ) integer level integer action integer callback
level
The level of detail of checking to be performed on data.
action
The action to be performed when an error in the data is detected.
callback
An optional routine that will be called when an error in the data is detected.
All data objects are checked for errors as they are handled and any errors are reported to the user. Data that is known to be bad is not transmitted to other modules, and its reference count is not changed.

cxDataCheckingSet defines the level of detail of the checking and what action is to be performed when an error is detected. Data is checked when it is stored in input or output ports, and whenever it is extracted from an input port by cxInputDataGet. The level parameter defines the amount of checking that is to be done.

cx_check_magic
the "magic number" field in the data is checked for validity. This helps detect operations on data that has already been reclaimed.
cx_check_mem_bounds
every array within a data type (e.g. the dims array in a cxLattice) is allocated with extra boundary "fenceposts" at the beginning and the end. Special byte sequences, and the size of the array in bytes are stored in the fenceposts. This helps detect memory indexing and allocation errors.

The action parameter defines the action to be taken when an error is detected.

cx_check_ignore
operations which might cause the module to fail are avoided, but the error is not reported.
cx_check_warning
the error is reported to the user by a simple text message.
cx_check_halt
the error is reported to the user and the module sleeps, allowing the user to examine the process with a debugger. The module sleeps as long as the external integer cxDataErrorRelease is false, so the halted module can be released by using the debugger to set this variable to a non-zero value.
cx_check_abort
the error is reported to the user and the module aborts. Any data referenced by the module is not reclaimed, and will be leaked.
cx_check_callback
the user supplied callback routine, callback is called, with the cxDataCheckErrorInfo structure and the pointer to the data containing the error. This allows the user to customize handling and reporting of errors.

The default action is for magic numbers to be checked on all data reference count changes and a warning to be issued. Magic number checking is always performed to prevent a module from attempting to lock a the reference count of data that has been damaged, which would inadvertently (and permanently) lock all modules out of the data arena. The level parameter values are listed in order of strictness, and each subsequent value implies that the lower level test is also done. That is, the magic number is always checked before the memory bounds.

The cxDataCheckCallback routines cxDataWarning, cxDataHalt, and cxDataAbort implement the cx_check_warning, cx_check_halt, and cx_check_abort actions. They are defined publicly so the user may access them directly. For example, the default actions can be restored by the following call:

cxDataCheckingSet( cx_check_magic,
cx_check_ref, cxDataCheckCallback, cxDataWarning );

cxDataCheck(3E), cxDataMagicCheck(3E), cxDataMemBoundsCheck(3E), cxMemBoundsCheck(3E)
Last modified: Mon Nov 6 16:33:03 GMT 2000
[ Documentation Home ]
© The Numerical Algorithms Group Ltd, Oxford UK. 1996