Overview of FOCLOG

In this section:

FOCLOG is a facility for logging FOCUS usage that was designed to have a negligible impact on FOCUS applications and to make it easy to analyze the collected data.

The cost of logging has been made so low as to be insignificant, so FOCUS usage can now be monitored continually, not just for selected periods. This is because the log is a simple sequential file to which usage data gathered during the FOCUS session or batch job is only appended when the FOCUS session ends.

Updates to the log from concurrently executing FOCUS sessions or batch jobs are serialized through a standard systems-wide z/OS Enqueue macro. The systems-wide scope allows a single log to gather usage data from users in different LPARS on the same machine.

The log is a physical sequential file with multiple record types that is easily read by FOCUS using a distributed Master File. Multiple logs can be logically concatenated so they are viewed as a single entity, and analyzed right where they are. Alternatively, since all the data is in character format, it can easily be moved to another platform—for example a laptop—where a more graphical analysis can be done using WebFOCUS.

How Logging Is Implemented

The FOCLOG facility is incorporated into FOCUS. However, logging is only triggered if at the start of execution, FOCUS detects the presence of member FOCUSLOG in any of the data sets allocated to DDNAME ERRORS. This file in turn names the log data set itself. The ERRORS DDNAME is already allocated through JCL in all production FOCUS environments—FOCUS will not execute without it.

To inhibit logging, you can delete or rename the FOCUSLOG file or delete or rename the reference to the log file within the FOCUSLOG file.

When logging is triggered, usage data is collected and kept in memory as the application proceeds. The log itself is not opened until the FOCUS session or batch job ends. If FOCUS abends in the course of execution, or if it is stopped by the operator, the usage data will not be logged for those user sessions active at the time of the stoppage.

Extreme precautions have been taken to ensure that logging difficulties will not affect the application. If the log cannot be written for whatever reason (for example, it is full, the user has no write privilege to it, there has been an I/O error), the only effect on the application will be that the usage data will not be logged. This is true even if the logging difficulty results in an abend: FOCUS will recover and terminate normally.

Failures to log are not signaled through FOCUS-generated error messages.

If the logging failure caused an abend from which FOCUS recovered—for example a B37 abend caused by a log full condition—the occurrence of the abend will be recorded in the batch job step statistics or in your TSO log, but logging failures which do not cause an abend will not be recorded in any way.

The z/OS ISPF utility can be used to examine the date and time of the last update of the log.

The Log Data Set

The first 44 bytes of the first record of the FOCUSLOG member in the concatenation of data sets allocated to DDNAME ERRORS contains the fully qualified data set name of the current log file.

Other records in the FOCUSLOG file are ignored, so they can safely be used to retain the names of prior logs. The default is to create short logs; long logs are created by following the log file name with the keyword DETAIL. This keyword gives you everything recorded in the short log and adds the data set or file names for the FOCEXEC, Master File, and Access File used in each request.

The site administrator must ensure that the LOG file is write-accessible to all FOCUS users and protected against archiving—FOCUS will not wait until an archived log is restored, rather it will skip logging instead. Therefore, the log file should not be managed by DFSMS.

The log consists of four types of records:

Type of record

Size in bytes

Number of Occurrences

Session

168

One per FOCUS session or batch job

Command

129 or 173

One per FOCUS command that accesses data

File

28 or 116

One per MASTER file referenced by the command

Dataset

68

One per data set still allocated at the end of the job

The detailed description of each record is in the distributed FOCLOG Master File and in Information Captured in the FOCLOG File. Long and short logs have identical Master Files; in the short log the Master File, Access File, and FOCEXEC data set names will appear blank.

Sample FOCLOG Configuration Scenarios

In the following diagram of a single LPAR configuration, one FOCLOG file records the usage of all FOCUS users in that LPAR:

In a site configuration where FOCUS resides in several LPARS, even with different OS levels, a single FOCLOG file can reside in any one of the LPARs.


Information Builders