Using two message log (MLOG) data sets

All the major components and tasks of HCL Workload Automation for Z log messages to either SYSOUT or to a data set, based on your configuration choice.

When the messages are logged to a data set (EQQMLOG), the message log data set remains under the control of the HCL Workload Automation for Z controller for as long as the controller is active. If you want to save, or clear, the contents of the data set, you must first stop the controller. Also, if the controller is not stopped for a long period of time, and EQQMLOG runs out of space, the messages are written into the system log.

To avoid these problems, including the increased amount of time required to find specific records in an oversized data set, you can configure HCL Workload Automation for Z to use two message log data sets, EQQMLOG and EQQMLOG2.

The two MLOGs are used alternatively: while one logs messages, the other remains inactive. Then, when the active data set reaches a pre-set level of completion, its contents are copied into a GDG data set and it goes idle, while the other data set starts logging. When the same level of completion is reached in the now active data set, the switch is repeated. Every time the data sets are shifted, message: 
EQQZ402I SWITCH FROM ddn1 TO ddn2
is issued on SYSLOG and written in the just switched MLOG.

The messages copied from EQQMLOG and EQQMLOG2 are available in the GDG data set.

To configure HCL Workload Automation for Z to use two MLOGS, specify Y in the MLOG SWITCH field of the EQQJOBSC installation aid panel. To activate this feature, you must also specify in the Switchlimit field the number of records written in the MLOG file that you want to trigger the switch mechanism. When the file reaches this level of capacity, its contents are saved in the GDG file, and the oncoming messages are written on the alternate file.

The number of records in Switchlimit must be greater than 0 for the feature to be activated.

Specifying Y in MLOG SWITCH results in the creation of sample JCLs that:
  • Add DD EQQMLOG2 in the controller started task JCL (samples EQQCONO and EQQCON) and initial parameters (samples EQQCONOP and EQQCONP)
  • Add DD EQQMLOG2 in the tracker started task JCL and initial parameters (samples EQQTRA and EQQTRAP)
  • Allocate the EQQMLOG2 data set like EQQMLOG (sample EQQPCS02)
  • Create the GDG data set where the outgoing MLOG file is archived (samples EQQSMLOG and EQQREPRO)
  • Allocate the GDG root to archive the MLOGS (sample EQQPCS12)

You must then make the EQQSMLOG procedure (copied from the EQQJOBS customized samples) accessible to the controller, for example by adding it in the user.proclib.

After the product is installed, you can configure the MLOGPROCNAME and SWITCHMLOGLIM keywords of the OPCOPTS initialization statement to set or change the feature.

Particular attention should be paid to calibrating the number of records specified in Switchlimit (or SWITCHMLOGLIM), the point being that an exceedingly low value triggers the switching function with unnecessary frequency while at the other end you risk filling the MLOG to its capacity and generate a B37 abend. As a best practice, you enter a number that at least doubles the number of records logged at the controller startup or during the workload peak (when many ETT add messages are sent).

For example, if you use a 3390 disk, a track is 56664 bytes. One cylinder includes 15 tracks, which are 849960 bytes. If you allocate an MLOG of 1 cylinder with 1 extent, the number of available bytes is 1699920. Since the MLOG record length is 125 bytes, the maximum number of available records is 13599 (1699920/125). Under these conditions, the appropriate number of records for Switchlimit or SWITCHMLOGLIM should be a little lower, perhaps 13000. If you then find that a greater number of messages is issued at short intervals during peak workload or at controller startup, this implies that you should increase the value and allocate more space for EQQMLOG.

Another advantage of using the MLOG switching function is that it prevents the loss of the messages that are written to EQQMLOG when abend B37 occurs as the MLOG file becomes full. In fact with the switching function on, if the current MLOG file fills up due to an inadequate number of records defined in Switchlimit or SWITCHMLOGLIM, when B37 is issued, a switch MLOG action is forced, all records are copied to the GDG data set, and control is passed to the alternate MLOG.

When this feature is installed, you can:
  • Run the modify command, /F subsys, SWITCHMLOG, to force the switch to the alternate data set (EQQMLOG or EQQMLOG1), regardless of the number of currently logged messages, and starts the record counter from 0 again.
  • See which of the two MLOG data sets is in current use on the BROWSING GENERAL CURRENT PLAN INFORMATION dialog (EQQSGCPP; fast path 6.6).

See also Message log data set (EQQMLOG).