You must define a system log if you want to preserve data integrity in the event of unit of work failures and CICS® failures (see Unit of work recovery and abend processing). A system log is mandatory for:
CICS log manager connects to its log stream automatically during system initialization, unless it is defined as TYPE(DUMMY) in a CICS JOURNALMODEL resource definition.
During a cold start, and a warm and emergency restart, CICS retrieves the names of its system log streams from the global catalog, ensuring that it reconnects to the same log streams that were used on the previous run.
During an initial start, CICS uses default log stream names, unless you specify otherwise on a JOURNALMODEL resource definition. The process of selecting and connecting to a system log stream is as follows:
If you use these default log stream names, ensure that
If you define JOURNALMODEL resource definitions for your system logs, ensure that:
If you don’t want to use a system log (for example, in a CICS test region), specify JOURNALMODEL resource definitions for DFHLOG and DFHSHUNT with TYPE(DUMMY). Note that running CICS with the system log defined as TYPE(DUMMY) forces you to perform an initial start, and CICS does not support dynamic transaction backout.
If CICS fails to connect to its system log streams because they have not been defined, CICS attempts to have them created dynamically using model log streams. To create a log stream dynamically, CICS must specify to the MVS system logger all the log stream attributes needed for a new log stream. To determine these otherwise unknown attributes, CICS requests the MVS system logger to create the log stream using attributes of an existing model log stream definition. If you decide to allow CICS to create log streams dynamically, you are responsible for creating the required model log stream definitions to ensure that dynamic creation succeeds.
It is generally worthwhile setting up model log streams only if:
Otherwise, it is probably less work to define the log streams explicitly using IXCMIAPU. Generally, dynamic creation using model log streams is best suited for test and development purposes, and explicit definition for production regions.
The model log stream names that CICS uses for dynamic creation of its system log streams are of the form &sysname.LSN_last_qualifier.MODEL, where:
If you do not provide a JOURNALMODEL resource definition for DFHLOG and DFHSHUNT, or if you use the CICS-supplied definitions in group DFHLGMOD, the model names default to &sysname.DFHLOG.MODEL and &sysname.DFHSHUNT.MODEL.
Example: If a CICS region issues a request to create a log stream for its primary system log, and CICS is running in an MVS image with a sysid of MV10 and using the default JOURNALMODEL definition, the system logger expects to find a model log stream named MV10.DFHLOG.MODEL.
CICS invokes the XLGSTRM global user exit immediately before calling the MVS system logger to create a log stream. If you don't want to use CICS default values for the creation of a log stream, you can write an XLGSTRM global user exit program to modify the request details, including the model log stream name (in parameter UEPMLSN).
If you are using coupling facility log streams, sharing structures between MVS images provides some recovery advantages. If an MVS image or logger address space fails, another surviving MVS image using the same log stream structures (not necessarily the same log streams) is notified of the failure and can start immediate log stream recovery for the log streams used by the failing MVS. Otherwise, recovery is delayed until the next time a system connects to a log stream in the affected structures, or until the failed system logger address space restarts.
However, using model log streams defined with the CICS default name are always assigned to the same structure within an MVS image. This may not give you the best allocation in terms of recovery considerations if you are using structures defined across two or more coupling facilities.
For example, consider a two-way sysplex that uses two coupling facilities, each with one log structure defined for use by CICS system logs, structures LOG_DFHLOG_001 and LOG_DFHLOG_002. In this situation, it is better from a recovery point of view for the CICS regions in each MVS to balance log stream allocations across both log structures. This scenario is illustrated in Figure 8, which shows a 2-way sysplex comprising MVSA and MVSB, with four CICS regions in each MVS. CICSA1 through CICSA4 reside in MVSA, and CICSB1 through CICSB4 reside in MVSB. Each MVS is using two coupling facilities, CF1 and CF2, each of which has one log structure referenced by model log streams. The first and second CICS regions in each MVS use log streams defined in the first log structure, and the third and fourth CICS regions in each MVS use log streams defined in the second log structure. In this scenario, each MVS image has a partner to recover its log streams in the event of an MVS failure.
Another example, shown in Figure 9, is based on a 4-way sysplex comprising MVSA, MVSB, MVSC, and MVSD. In this case, ensure that the CICS regions that normally run on MVSA and MVSB use structure LOG_DFHLOG_001, and that the regions that run on MVSC and MVSD use structure LOG_DFHLOG_002. Thus each MVS image has a partner to recover its log streams in the event of an MVS failure. If a structure fails, the two MVS images using the other structure can take over the workload.
To balance log streams across log structures, as shown in Figure 8, using model log streams means customizing the model log stream names. You cannot achieve the distribution of log streams shown in this scenario using the CICS default model name.
You can use an XLGSTRM global user exit program to vary, in a number of ways, the model log stream name to be passed to the system logger. One such way is to store appropriate values in the exit's global work area. For example, you can use the INITPARM system initialization parameter to specify a parameter string for use by the exit. This can be retrieved, using the EXEC CICS ASSIGN INITPARM command, in the first-phase PLT program that you use to enable the XLGSTRM global user exit program. Having obtained the relevant model log stream information from the INITPARM command, you can store this in the global work area for later use by your XLGSTRM global exit program. Varying the model log stream details in this way enables you to balance log streams across different log structures in a coupling facility.
See the CICS Customization Guide for information about writing an XLGSTRM global user exit program, and for information about PLT initialization programs.
During a restart, the CICS log manager scans the log backwards to recover unit of work information. The log is scanned backwards as follows:
This process means that completed units of work, including shunted backout-failed and commit-failed units of work, are ignored in this part of the log scan. This is significant for the retrieval of user-written log records. User-written records cannot be presented at the XRCINPT global user exit program (see Writing user-recovery data) if they are part of units of work that CICS skips in this part of the log scan process.
Figure 10 illustrates the way CICS performs log processing during a CICS restart.
Here are some steps you can take to ensure that system log stream sizes, and thus restart times, are kept to a minimum:
For information about calculating system log stream structure sizes, see the CICS Transaction Server for z/OS® Installation Guide.
The rest of this topic expands on these points.
CICS log manager controls the size of the system log stream by regularly deleting the oldest completed unit of work records (log-tail deletion).
This operation is associated with activity keypoints. It is important, therefore, that you choose the correct activity keypoint frequency (AKPFREQ)--that is, one that allows CICS to keep the system log down to a reasonable size and to keep it within the coupling facility (if one is used):
The log tail is the oldest end of the log. At each activity keypoint, the CICS recovery manager requests the log manager to delete the tail of the system log by establishing a point on the system log before which all older data blocks can be deleted. Thus, if the oldest "live" unit of work is in data block x, the CICS log manager requests the system logger to delete all data blocks older than x (x-1 and older).
In a system with an activity keypoint frequency configured for optimum effect, all units of work execute in a short enough time to enable the log-tail deletion process to keep the primary log stream within its primary storage space allocation. However, in most systems, some units of work will last longer. This could be due to application design, or the unit of work suffering an indoubt failure, a commit-failure or backout-failure. To prevent these few units of work affecting the whole region, CICS detects that a unit of work has become long-running and makes copies of its log records on the secondary log stream. This allows more of the primary log stream to be trimmed and hence increases the probability of keeping the system log within its primary space allocation. CICS decides that a unit of work is long-running if the UOW does not write to the system log for two complete activity keypoint intervals.
All log records for units of work are initially written on the primary log stream. From this, they are either deleted by the log-tail deletion mechanism, or copied to the secondary log stream. The copy is made during activity keypointing.
After they have been moved to the secondary logstream, the log records for a unit of work remain there until the unit of work is completed. Note that subsequent writes to the system log by the unit of work are directed to the primary log.
You should write only recovery-related records to the system log stream. You can do this using the commands provided by the application programming interface (API) or the exit programming interfaces (XPI). This is important because user recovery records are presented to a global user exit program enabled at the XRCINPT exit point.
User-written recovery records are managed in the same way as recovery manager records, and do not prevent CICS from performing log-tail deletion:
During warm and emergency restarts, CICS scans the system log backwards. If, during this backwards scan, CICS finds active user records, they are presented to a global user exit program enabled at the XRCINPT exit point.
Active user log records are those that are:
These user records, which form part of a unit of work chain, are deemed to be active only if:
These records are presented to your XRCINPT global user exit program, regardless of the state of the unit of work, provided the unit of work lies within the scope of the backward scan of the system during restart. This category includes units of work that are in a backout-failed or commit-failed state.
These user records are always presented to your XRCINPT global user exit program, regardless of the state of the high-order bit in the JTYPEID field.
If CICS completes its scan of the system log and finds there are no active user records, it issues message DFHER5731.
CICS log tail deletion, which ensures that completed log records are retained for two complete activity key points only, is inhibited if you specify a retention period (RETPD=dddd) when you define the system log to MVS. The dddd value specifies the minimum number of days for which data is to be retained on the log.
You are strongly recommended not to use the system log for records that need to be kept. Any log and journal data that needs to be preserved should be written to a general log stream. See the CICS System Definition Guide for advice on how to manage log stream data sets.
Do not design long-running transactions in such a way that they write frequently to the system log stream, in a single unit of work, across multiple activity keypoints.
If a long-running transaction does not take regular syncpoints while regularly initiating writes to the system log, CICS is prevented from purging units of work that completed after the long-running task started.
In Figure 11, the long-running transaction is updating recoverable resources, causing writes to the system log. All the updates are in the same unit of work because it does not take explicit syncpoints. The oldest deletion point is earlier than activity keypoint number 5, preventing CICS from deleting any completed units of work that lie between activity keypoints 5 and 8. In this example, the long-running transaction will eventually cause the system log stream to spill onto secondary storage.
[[ Contents Previous Page | Next Page Index ]]