This document describes how information about Natural sessions can be logged in a file which can be processed and evaluated in batch mode.
It covers the following topics:
Optionally, information about Natural sessions can be logged in a file which can be processed and evaluated in batch mode.
In contrast to the online SYSTP Utility, which just gives a snap shot of the current system usage, this logging facility can be used to keep track of the Natural CICS system usage over a longer period of time.
It is possible that several Natural CICS environments (that is, several system directories with unique threads, roll facilities, swap and buffer pools) share the same Natural log destination. When an SCP environment is initialized, a "system ID" is written into the system directory. This system ID is part of an evaluation program to "sort" log records by Natural CICS system environment.
You are recommended to define the Natural log file in the Natural application CICS, as logging to a "remote" log file would degrade performance.
When running the log file evaluation program (see SYSTP in Batch Mode in the Natural Utilities documentation), the log file should be closed in CICS, otherwise unpredictable results may happen due to the last buffer being still in storage or the EOF record missing on file.
Sufficient disk space should be reserved for the Natural log file;
preferably the log file should be defined using secondary allocation (if the
file runs full in z/VSE, the z/VSE message NO MORE AVAILABLE
EXTENTS is issued and the operator is asked to enter new extents or
cancel CICS).
The Natural log file is a sequential disk file; that is, an
"extra partition destination" in terms of CICS. By default, the
internal (logical) name of the log file is NLOG; this name can be
changed by specifying the LOGDEST parameter in the
NCMPRM macro.
The log file has to be defined in a
CICS DCT as
TYPE=EXTRA with associated dataset control information
(TYPE=SDSCI entry in DCT). This file must also be defined in the
CICS start-up JCL (DD statement in z/OS, DLBL statement in z/VSE).
The following records are logged in the Natural log file:
Length=96
After successful SCP system initialization, a record that holds the initialization date and time as well as other system data like the common system prefix, the number of RCBs or the number of thread groups, is written to the log file.
When this first log request fails, the Natural log file is flagged in the system directory as not available and no further logging takes place.
System restart records are written whenever the system highwater marks
are reset by the corresponding system administration function of the
SYSTP utility. In addition to the system start information, these
records contain the terminal ID and the user ID of the SYSTP
user.
Length=216
On (normal or abnormal) termination of a Natural session, a session log record is written to the log file. This record is internally split into six parts:
The record control part which holds the actual session statistics:
the current date and time (that is, the date and time when the session terminated),
the system ID which indicates the Natural CICS environment in which the session was active,
the record type = session record.
The record control part is common to all Natural log records to distinguish the different record types. Macro NCMLOG holds the record layouts.
The user session part which holds the actual session statistics:
the terminal ID,
the (last) user ID,
the session start date and time,
the maximum storage allocated by the session,
the number of session resumes/swap ins/roll ins,
the maximum number of records rolled by the session (if any).
The thread group part which holds the current data of the thread group associated with the session:
the thread group number,
the number of TCB slots in the group (if any),
the common thread size of the group,
the maximum storage allocated in the group by any session,
the maximum number of sessions active in the group,
the maximum wait queue size of the group (with
TYPE=SHR thread groups) and the maximum number of sessions
concurrently active in the group (with TYPE=GETM thread
groups),
the number of times this maximum wait queue size was reached.
The thread part which holds the data of the TYPE=SHR
thread used as last thread by the session (if used at all):
the thread name,
the thread use count,
the highest thread storage used by any session,
the number of session resumes/roll-ins into this thread,
the maximum wait queue size of this thread,
the number of times this maximum wait queue size was reached.
The roll facility part which holds information about the roll facility to which the session was assigned (if it was at all):
the roll facility name,
the maximum number of sessions assigned to this roll facility,
the record size of the roll facility,
the slot size of the roll facility,
the number of slots in this roll facility,
the maximum number of roll-outs to / roll-ins from this roll facility.
The system directory part which holds statistics about the global system usage:
the maximum number of UCB block extensions,
the maximum number of sessions active in the system,
the maximum number of sessions concurrently active in SCP,
the number of SCP system recoveries.
By design, session termination records are stored by session date and time. This means that parts 3 to 6 of a later session record always hold more current information than those of a previous one. Parts 3 to 6 of the record are used by the log file evaluation program to refresh the corresponding information provided; that is, information on the thread group, thread, roll facility and SCB.
This technique is used to keep up-to-date information about the Natural CICS system resources in case CICS terminates in an uncontrolled manner.
The session termination log records, of course, reflect only resources
which have been used by the corresponding sessions. Therefore, these records
may not reflect the full SCP environment. Reports of a full SCP environment can
be obtained by making a snapshot of the whole environment by either using the
SYSTP
System
Administration Facilities or placing Natural under CICS
into the CICS PLTSD (as described in the section Special Natural CICS
Functionality).
System snapshot records in the Natural log file represent session termination records without session-specific information as listed under part 2.
