Accessing Log Files from Programs

The following sections include information that you need to access log files programmatically.

Creating and naming log files

When system logging is first enabled, MPE/iX creates and opens the first log file and begins recording events as they occur. When this log file is full, or when the system is shut down and restarted, MPE/iX creates and opens a new log file.

Log file names always take the form LOGxxxx.PUB.SYS, where xxxx is the log file number, ranging from 0000 to 9999. The first log file is LOG000; when it is closed and a new log file opened, MPE/iX increments the file number by one. Each time a new log file is created, a console message, similar to the following, displays the new log file number:

   LOG FILE NUMBER xxxx ON

Log file commands

Three MPE/iX commands, SHOWLOG, SWITCHLOG, and RESUMELOG, are available to control system logging. The SHOWLOG command displays the number of the current log files and the percentage of file space already used to record logging events. For example:

   LOG FILE LOG9675 IS 16% FULL

The SWITCHLOG command closes the current log file, and creates and opens a new one.

The third command, RESUMELOG, restarts the logging process after it is suspended because of an error.




	NOTE: You must have system supervisor (OP) capability to use these three commands. For more information, refer to the MPE/iX Commands Reference Manual Volumes 1 and 2 (32650-90003 and 32650-90364).

File security

Log files are created by, and therefore belong to, the system logging process. By default, their creator is MANAGER.SYS. They are assigned the MPE/iX default security provisions typically assigned to files within the PUB group of the SYS account. The current log file can be modified only by users assigned Account Librarian (AL) capability for the SYS account, or by PUB group users (GU capability) of the SYS account.

Once the log file is closed, MPE/iX changes the file access restrictions on the file from ANY to CR (the file creator) only. The result is that only the system manager controls access to current and closed log files.

Log file structure

All log files are created as files containing variable-length records. They should always be treated as files containing variable-length records, accessed sequentially.

For a log file, the end-of-file pointer can point at the last record (block) written to the file (if the file is closed normally), or at any point beyond the last record written (if the file has not been closed). In the latter case, all space following the last record is padded with zeros.

The general format of a log file is shown in Figure 7-1 “Log File Format”. The log file record size is 2048 bytes with a maximum of 1024 records per file.

Figure 7-1 Log File Format

Console messages for log files

Log file status and error messages are reported to the system console. They conform to the format hh/mm/PIN/message, where:

`hh`	= the hour of the day
`mm`	= the minute of the hour
`PIN`	= the process identification number
`message`	= the message text

The log file status message text may consist of any of the following:

LOG FILE NUMBER xxxx ON indicates that a new log file has been created. This message always appears prior to the welcome message after a restart. If displayed while the system is running, it indicates that the previous current log file has been closed.
LOG FILE NUMBER xxxx IS 50% FULL indicates that logging data fills up half of the log file's allotted file space.
LOG FILE NUMBER xxxx IS 75% FULL indicates that logging data fills up three-quarters of the log file's allotted file space.
LOG FILE NUMBER xxxx LOGGING RESUMED indicates that a RESUMELOG command was successfully executed.

Log file errors are reported in one of the following messages. Refer to Table 7-1 “Log File Errors” for a summary of log file error numbers, their meaning, and whether they are recoverable or irrecoverable errors.

LOG FILE NUMBER xxxx ERROR #nn, LOGGING STOPPED indicates that an irrecoverable error occurred; system logging is disabled until the next system startup.
LOG FILE NUMBER xxxx ERROR #nn. LOGGING SUSPENDED indicates that a recoverable error occurred. A recoverable error temporarily suspends logging until the system supervisor issues the RESUMELOG command, discussed previously.

File error handling

Two types of errors prevent the system logging facility from maintaining the log file:

Catastrophic errors. Caused by physical I/O errors or unit failures. These errors are not recoverable and will disable logging until the next restart.
Managerial errors. Encountered during creation and management of the log file. These are usually recoverable, and they cause logging to be temporarily suspended. Logging resumes when the problem is resolved and a RESUMELOG command is issued.

When logging resumes, a special log record is created, denoting the total number of records missed, the number of job/session initiation records missed, the number of job/session termination records missed, and the number of I/O records missed. To analyze this or any other entry in the log file, run the LOGTOOL utility program.The following table shows the various file errors that are logged:

Table 7-1 Log File Errors

Error #	Error	Recover?
1	Input/output error in accessing the system disk.	No
2	Input/output error in accessing disk log file.	No
21	Data parity error.	No
26	Transmission error.	No
27	Input/output timeout.	No
28	Data overrun.	No
29	SIO failure.	No
30	Unit failure.	No
46	Insufficient disk space to create log file.	Yes
47	Input/output error on file label.	No
57	Virtual memory not sufficient.	No
61	Group (`PUB`) disk space exceeded in creating log file.	Yes
62	Account (`SYS`) disk space exceeded in creating log file.	Yes
63	Group disk, space exceeded in allocating new extent to the log file.
64	Account disk space exceeded in creating log file.	Yes
100	A file of the same name as the current log file already exists in the system file directory.	Yes
102	Directory input/output error.	No
103	System directory overflow.	No
105	Illegal variable block structure.	No