The Log File

If LOGGING is set to ON or ALL, every incoming message that the programmable operator facility receives is put into a CMS file referred to as the log file. The log file can reside on either a minidisk or an SFS directory. If LOGGING is set to ALL, all error messages and command responses generated by the programmable operator facility are also put in the log file. If LOGGING is set ON, responses from CP, CMS, and programmable operator facility commands are not logged; messages are.

When the log file resides in an SFS directory, it can be shared with other users. You should, however, ensure that no one will be writing to the file and that no one has the file locked when the programmable operator is running. If other users have write authority to the log file, consider locking the file before starting the programmable operator. See the CREATE LOCK command in the z/VM: CMS Commands and Utilities Reference.

Each message is identified by the date and time received. The user ID and node ID appear only if the text was sent by a CP MSG, SMSG, WNG, or sent using SCIF (Single Console Image Facility). The user ID and node ID are blank for a message sent by CP. A message sent by a remote RSCS network virtual machine has a node ID, but no user ID. A message sent from an NCCF or NetView operator console has *NCCF as the node ID.

Log entries generated and logged by the programmable operator have a user ID of PROP. The log file has the following format:

col 1    col 10   col 19   col 28     col 39
|        |        |        |          |
yy/mm/dd hh:mm:ss{userid   nodeid}:   text

The log file contains variable length records. The maximum record length that the programmable operator facility can place in the log file is 132 characters. Because the prefix uses 38 of the 132 characters, the text can be only 94 characters long. Therefore if the text of a message exceeds the maximum length of 94 characters the overflow is continued on the next record. This continued record has the same prefix as the preceding record, with no colon (:) preceding the text in column 37.

A separate log file is started for each day. The name of the file is:

LGyymmdd nodeid A5

yy: is the current year
mm: is the current month
dd: is the current day
nodeid: is the current RSCS node ID of the system on which the programmable operator facility is running. (If the node ID is not available, then the file type for the logfile will default to PROPFILE.

When the programmable operator facility is started, stopped, or debug mode is changed, a record is written to the log file. The messages written to the file have the normal log prefix and a text corresponding to the changed function. Generally, responses to the programmable operator console commands are written to the log file when LOGGING is set to ON or ALL. It is also possible to have responses from the programmable operator commands written to the log file. See the LOGGING statement of the routing table or the programmable operator SET command for more information. The log file may be used as an alternative to spooling the virtual console when LOGGING is set to ALL and LOWCASE. When node-checking is in effect, by having PROPCHK or HOSTCHK statements in the RTABLE, if a node changes status from UP to DOWN or from DOWN to UP, a message is also written to the log file.

If a virtual machine resource limit is reached, such as disk full or file space full, it may not be possible to write another record to the programmable operator facility log file. If this happens, the programmable operator facility invokes the PROPLGER EXEC for recovery. IBM supplies a sample PROPLGER EXEC. See Log Error Exit (PROPLGER). You can use the sample PROPLGER EXEC, modify it, or replace it with a user-written exec.

When using an SFS directory accessed as file mode A, PROPLGER EXEC is invoked whenever the file space threshold limit is exceeded. However, if the threshold is set too high or other users are writing to this storage group, the programmable operator facility may not detect certain resource limits until it tries to close the log file. At that point the programmable operator will not be able to invoke the PROPLGER EXEC, and some log data could be lost. If it is important for you to minimize the potential loss of log data, consider using a minidisk for the log file instead of an SFS directory.

Any z/VM user authorized in the active routing table^¹ can obtain the log file as a reader spool file by using the programmable operator GET LOG command (this does not include NCCF or NetView users). Messages can be placed in the log file by authorized users by using the programmable operator LOG command with no other action being taken.

An old log file can be purged by any user authorized in the active routing table to use the programmable operator CMD command by issuing the CMS ERASE command.

¹ An NCCF or NetView operator cannot use the GET command to obtain the log file. Use CMS commands (and the programmable operator CMD command) to type the file or portions of the file or to send the file to a user ID where you can process it.