5.1 Function description

< Day Day Up >

CICS started using System Logger in the first release of CICS Transaction Server. The services of the System Logger are used to record information required for transaction back out and recovery on the CICS system log. The CICS system log is comprised of two log streams (DFHLOG and DFHSHUNT). In addition, data required for forward recovery may be written to a forward recovery log stream, and application data may be written to a user journal which is also stored in a log stream.

The period between the start of a particular set of changes and the point at which they are complete is called a unit of work (UOW). A UOW is a sequence of actions which must complete before any of the individual actions can be regarded as complete. A UOW is terminated by a syncpoint. The syncpoint may be issued implicitly at task end, or explicitly when the task issues an EXEC CICS SYNCPOINT. In the absence of user syncpoints being explicitly issued within the transaction, the entire transaction is one UOW. After changes are committed (by successful completion of the UOW and recording of the syncpoint on the system log), they become durable, and are not backed out in the event of a subsequent failure of the task or system. If a transaction consisting of multiple UOWs fails, or the CICS region fails, committed UOWs are not backed out.

The log records on the system log stream that are associated with a given UOW are "chained" together. In the context of the System Logger function, the term chain refers to the grouping of records for a particular UOW.

The interface to the System Logger is via the CICS Log Manager domain, referred to as the logger domain. CICS resource managers, such as file control, communicate with the recovery manager (RM) component of CICS. The recovery manager associates the request with the unit of work (UOW) and passes the request to the logger domain. The logger domain places the data into a buffer and then calls the System Logger using an IXGWRITE call to pass the data to be written to the log stream. When the UOW completes (that is, issues a syncpoint), CICS can then delete all log records associated with the UOW.

An application may also request user-defined data to be recorded in a user journal using an EXEC CICS WRITE JOURNALNAME command. The application execution interface will pass the request to the logger domain, where an IXGWRITE call is issued for the log stream associated with the journal name.

In order for CICS to connect to a log stream, the log stream must be defined in the System Logger policy. From a CICS point of view, the System Logger policy is a resource respository much like the CICS System Definition (CSD) file.

The log stream definition must exist in the System Logger policy before CICS can connect (think of a connect as an OPEN) and use it. If the log stream resources have not been pre-defined, CICS will attempt to dynamically define them as needed.

CICS provides support for the dynamic installation of many of its resources. Following in that tradition, log streams can be dynamically defined to the System Logger. To facilitate the dynamic definition of log streams, the names and characteristics must be supplied via models.

In the CICS System Logger environment, two types of models may be required.

The first is a journal model defined in CICS which provides a linkage between the journal name and the log stream to be used. The STREAMNAME parm in the JOURNALMODEL identifies the log stream to be used by CICS. The CICS journal models replace the journal control table used in CICS/ESA® V4.1 and earlier.

For DFHLOG and DFHSHUNT, if the JOURNALMODEL is not defined, CICS will attempt to connect to a log stream named &userid..&applid..DFHLOG (or &userid..&applid..DFHSHUNT).

For non-system logs (user journals, forward recovery logs, and auto journals), if a JOURNALMODEL has not been defined, the name used would be &userid..&applid..DFHJ0xx, where xx is the journal number.

The second type is referred to as an MVS model. MVS log stream models are defined in the System Logger policy using the IXCMIAPU utility. The model contains the log stream characteristics to be assigned when the log stream is dynamically created. MVS models sysname.DFHLOG.MODEL and sysname.DFHSHUNT.MODEL are required entries in the System Logger policy if CICS is to dynamically create the DFHLOG and/or DFHSHUNT log streams. "sysname" is the name of the z/OS image as specified in the IEASYSxx in SYS1.PARMLIB. Figure 5-1 shows how CICS decides on the name of the log stream to be used for DFHLOG (as an example).

click to expand
Figure 5-1: How CICS decides which log stream name to use

When CICS requests a log stream to be dynamically created for DFHLOG or DFHSHUNT, an IXGINVNT DEFINE request will be issued, pointing to an MVS model named sysname.DFHLOG.MODEL or sysname.DFHSHUNT.MODEL respectively. The name of the MVS model used for the log stream create may be changed in the CICS XLGSTRM exit. A sample exit is provided with CICS Transaction Server V2.2 in member DFH$LGLS of SDFHSAMP. For earlier releases, a sample exit is available via a ServerPac which can be downloaded from:

http://www.ibm.com/software/ts/cics/txppacs/csle.html

All characteristics of the log stream to be defined may be changed in the XLGSTRM exit except the log stream name. Prior to calling the exit, CICS will have already cataloged the Log Stream Name in the CICS catalog..

Tip

All log streams defined using a given MVS model will have the same attributes, unless altered in the XLGSTRM exit. Having the same attributes for all log streams could result in incorrect definitions for the type and volume of data written, or it could result in all log streams being placed in the same structure.

The log stream names for DFHLOG and DFHSHUNT can only be changed when CICS is initial started. For other types of starts (cold, warm, and emergency) the log stream name is obtained from the CICS catalog.

During CICS startup, an IXGCONN call will be issued to connect to the DFHLOG and DFHSHUNT log streams. CICS will connect to user journals and forward recovery logs at first reference.

Note that CICS allocates two buffers for each log stream: this enables CICS to write while an IXGWRITE is in progress for the alternate buffer.

During a normal shutdown, CICS will flush the log buffers and issue a disconnect call (IXGDISC) for the log streams. However, it's important to note during an immediate shutdown (CEMT P SHUT,I) the buffers are not flushed for user journals.

To avoid loss of user journal records, use a normal shutdown with the shutdown assist program (DFHCESD) active. Add a program to the Program List Table for ShutDown (PLTSD) to issue a SET JOURNAL FLUSH for each user journal. Even though the shutdown assist program may force an immediate shutdown, it will happen after the PLTSD programs have run.

Another method is to add the wait option on writes to user journals; however, use of the wait option could lead to performance and response time issues.

5.1.1 Log stream usage

Figure 5-2 shows the relationship of the resource managers, the logger domain, and the System Logger function.

click to expand
Figure 5-2: Overview of CICS logging

Log streams used by the CICS address space can be categorized into four basic types:

System
Forward recovery
User
Autojournal

In addition, the log of logs is a special form of a user journal.

The system log is comprised of two log streams, DFHLOG and DFHSHUNT.

The system log is used to hold information required to perform backout of in-flight activity in the event of a transaction, region, or system failure.

Recovery information, such as the "before" image of the data when an update is made to a recoverable VSAM file, is written to DFHLOG prior to the update. A transaction does not cause a log record to be written until it accesses a recoverable resource for update. There are many tasks, such as CEMT which does not update recoverable resources and therefore does not cause log records to be written.

DFHSHUNT is a dual purpose log stream. In the case where a task has caused a log record to be written to DFHLOG and it does not cause another record to be written to the log within one activity keypoint, its records are moved to DFHSHUNT. This means the chain of log records (known as a log chain) written on behalf of the task since the last syncpoint, or start of task, is moved to DFHSHUNT. By moving the records for tasks which are inactive for one activity keypoint to DFHSHUNT, CICS is better able to manage the tail (oldest records required for backout) on DFHLOG.

The second use of DFHSHUNT is to hold the log chain for a UOW which is in INDOUBT status. A UOW is INDOUBT in the resource manager region if it has been invoked for the first phase of syncpoint (prepare), but not for the second (commit). A failure in the resource manager, CICS, or the communication link in the period between Phase 1 and Phase 2 leaves the resource manager in doubt as to whether the UOW should commit or backout. In those cases the log chain associated with the UOW is moved from DFHLOG to DFHSHUNT to await resynchronization.

The only records written to DFHSHUNT are those which have been moved from DFHLOG for one of these two reasons.

When a transaction completes, or issues a user SYNCPOINT, the records for the UOW have been committed and are no longer required for backout.

Log tail management is the process of removing records from the DFHLOG and DFHSHUNT log streams which are no longer required. The oldest record of interest to CICS on the log stream is defined as the history point. During the activity keypoint process, CICS will determine the history point for DFHLOG and DFHSHUNT. An IXGDELET call will be issued to inform the System Logger all records older than the history point may be logically deleted. The records are physically deleted during the next offload process for that log stream.

Performance of DFHLOG has a major impact on transaction throughput and response time. For a description of CICS parameters which can affect log stream performance, refer to "AKPFREQ" on page 143 and "LGDFINT" on page 144.

Log tail management is only performed for DFHLOG and DFHSHUNT.
Forward recovery log

CICS supports forward recovery of VSAM data sets updated by CICS file control. If a forward recovery log is defined in either the file definition or the ICF catalog entry for the data set, the "after" image of changes will be logged.

Data written to the forward recovery log is appended to the exiting data in the buffers for the log stream. The buffers are written (an IXGWRITE issued) to the log stream during syncpoint processing.

CICS itself does not use the data from a forward recovery log. The data is used by products designed to provide forward recovery, such as IBM's CICS/VR.

Log tail management is not performed on forward recovery logs.
User journals

User journals contain data written as a result of an EXEC CICS WRITE JOURNALNAME or EXEC CICS WRITE JOURNALNUM command from an application program.

If the wait option is specified on the write command, the log write (IXGWRITE) will be issued immediately to cause the buffer to be written to the log stream. Otherwise, the buffer is written when it fills.

Data written to a user journal is not synchronized with the UOW.

CICS does not reference the data written to user journals.

Log tail management is not performed on user journals. The program used to process the log stream could delete the data using IXGDELET calls, or you could define the log stream with a RETPD>0 and AUTODELETE(Y).
Auto journal

CICS supports the use of an auto journal for file control data and terminal control messages. Auto journals are generally used for audit trails.

When a file is defined to CICS, auto journaling may be specified. Data for the operations selected is recorded on the journal specified in the CICS file definitions. For example, JNLUPDATE(YES) indicates rewrite and delete operations are to be recorded on the log stream.

For operations defined as synchronous (JNLSYNCREAD or JNLSYNCWRITE) the log write operation is issued immediately, otherwise the buffer is written when it fills.

Auto Journal of terminal messages is defined in the communications profile.

The data written to an auto journal is not referenced by CICS. You must provide your own programs to process the data.

Log tail management is not performed on auto journals. The program used to process the data could delete the data using IXGDELET calls, or the log stream could be defined with a RETPD>0 and AUTODELETE(Y).
Log of Logs

The log of logs is a form of a user journal written to provide information to forward recovery programs such as CICS VSAM Recovery (CICS/VR). The log contains copies of the tie-up records, which provide a summary of VSAM recoverable data sets used and the log stream to which the forward recovery information was written.

CICS does not perform log tail management on the log of logs log stream. The program used for forward recovery would normally be used to delete the data using IXGDELET calls, or the log stream could be defined with a RETPD>0 and AUTODELETE(Y).

5.1.2 Criticality/persistence of data

The data written to DFHLOG and DFHSHUNT persists only for the time period it might be required for recovery, in the event of a transaction, region, or system failure. For general logs (forward recovery, auto journals, or user logs), the data persists for the duration of the retention period specified in the log stream definition, or until the data has been deleted. Refer to Figure 5-15 on page 162 for information concerning offload data set deletion.

< Day Day Up >