Error Logging

QM includes an error logging system that records brief details of errors that may require investigation by system administrators or application developers. These include:

•Run time program errors (e.g. unassigned variables)

•User authentication errors (failed logins)

•Forced logout

•Internal file system errors

The error log is maintained in a text file named errlog in the QMSYS directory. This file will be created automatically when the first message is logged. On Linux and Unix systems, the file permissions will be set to allow all users full access to the file.

Although the errlog file can be written directly by programs using the sequential file processing statements, this should be avoided as the buffering used by these statements may result in lost messages. Application developers should use the QMBasic LOGMSG statement or the LOGMSG command if they wish to add their own messages to the log file.

On ECS mode systems, the log file is maintained in UTF-8 encoding.

To avoid faulty programs generating very large log files and to remove the need for file maintenance, the ERRLOG configuration parameter sets the maximum size in kilobytes to which the error log file may grow. When this size is reached, the first half of the data in the file is discarded. The minimum acceptable non-zero value of the ERRLOG configuration parameter is 10. A smaller value will be treated as 10. Setting the ERRLOG parameter to zero disables error logging.

Each log message consists of two or more lines of text. The first gives the date and time in the time zone of the user that started QM, the QM user number, process id, login name and account name of the user generating the error. The second line gives the actual message, indented by three spaces to make the file more readable. Further lines may be present, also indented by three columns. This format is easy to process using user written tools if required.

Log Filtering

Prior to logging the first message from a QM session, the system checks for the presence of a catalogued subroutine named !ERRLOG.FILTER and, if this is present, calls it for each logged message from that point onwards. The subroutine can be used to filter messages such that certain messages are not logged or to trigger other application events such as emailing run time error messages to support staff.

The subroutine must be declared as

SUBROUTINE ERRLOG.FILTER(RESULT, MSG, STATUS, ERR)

where

RESULT

should be returned as a Boolean value indicating whether the message is to be written to the error log. This defaults to true if not changed by the subroutine.

MSG	is the text of the log message. Modifying this text has no effect.

STATUS

is the value of the STATUS() function at the point when the log action was initiated. This is only meaningful for some messages.

ERRNO

is the value of the OS.ERROR() function at the point when the log action was initiated. This is only meaningful for some messages.

The subroutine must be catalogued with the ! prefix on its name. A log message generated from the filter subroutine such as a run time error is always logged without calling the filter subroutine recursively. Also, log messages from other QM processes such as the replication server (qmrpl) or the network monitor (qmsvc or qmlnxd) are not filtered.

The !ERRLOG.FILTER subroutine must abide by some rules:

•Must not use STOP or ABORT

•Must not use transactions or related QMBasic operations

•Must use the NON.TRANSACTIONAL option when opening files

•Must not throw exceptions unless caught in the same subroutine

•Must not request input from the user's terminal

•Must not write to files that are published for replication

•Must not start a phantom process

•Must not execute a shell command