NAME
    *Glb.pm* -- common data structures and procedures.

DESCRIPTION
    Module *Glb.pm* includes the definitions of the common data structures
    for the representation of Qios operations, error messages and datafile
    configuration records. Further, module *Glb.pm* implements the
    mechanisms for error handling and system logging.

  Operations

    The operations of Qios are represented in the associative array %op by
    which the integer numbers are assigned to the keywords representing
    operations. The keywords are used to symbolically identify the
    operations in the code. For the purpose of fast implementation, Qios
    manipulates internally the integer codes of operations.

  Errors

    The error messages are represented using the associative array %error
    with the keywords identifying errors and the corresponding error
    messages as strings.

    The state of a module describes the position in which the module is in a
    given timepoint. The state can be one of the following: *Ok*, *Info*,
    *Warn*, *Error* and *Fatal*. The state of the particular module is
    recorded using the variable *$state*. The state of the system is
    recorded in the module *Glb.pm*. (Note: only system wide state is
    currently used.)

    The errors are gathered on the stack *@error* to be able to make a
    precise diagnose of the error possibly from more than one modules. The
    main function for checking the errors in the system examines only the
    size of stack *@error*.

  Logging

    Two log streams are realized. The standard log stream is used to record
    system events during normal operation. The debug log stream is used for
    debugging.

    Log level of the log record denotes the importance (or severity) of the
    log record. The log level thresholds (parameters of system) are used to
    filter the standard and debug log streams: only log records which levels
    are smaller than or equal to the threshold log level are channeled to
    the stream. The log level of the log record is controlled by using the
    appropriate procedure to report the log record.

    The log level thresholds are specified in the datafile configuration:
    *loglvl* variable records the level of standard logging and the variable
    *dbglvl* filters debug log stream. Furthermore, the log streams can be
    turned off and on using the configuration parameters: *logon* and
    *debug*.

    The procedures for reporting the log records can report various types of
    events: all types of errors, info messages, descriptions, announcements,
    printing various debug info, etc. The procedures are: *log_sayX*,
    *log_heyX*, *log_warn*, *log_error*, *log_fatal*, *log_enterX*,
    *log_exitX* and *log_infoX*. The variable 'X' in the procedure names
    denotes the reporting log level (0..2) of the log record.

COMMENTS
    This module is part of the *qios* programming environment.