Coupling facility log streams

If you use a coupling facility, the ideal environment is provided by two or more non-volatile coupling facilities that are failure-independent from any of the exploiting MVS™ images, using dedicated processor resources.

Should one coupling facility fail, or require maintenance, in such an environment, the system logger can rebuild its data in another coupling facility and continue. Running CICS® systems would experience only minimal impact.

If you are unable to devote two coupling facilities for the purposes of the MVS system logger, the next most robust environment is provided by one dedicated coupling facility for normal logger and lock structure use, plus a coupling facility LPAR. This environment has the same advantages of rebuilding with minimal impact to running CICS systems. Furthermore, MVS detects that the LPAR coupling facility is not in a failure-independent domain, and causes the system logger to write log stream data to staging data sets for extra security.

Running with a single coupling facility is not recommended since its failure would cause the MVS system logger, and any other users of the coupling facility, to suspend normal operation until access to the coupling facility were restored. CICS would, effectively, be unusable in such a situation.

Unless you specify that the system logger is to use staging data sets, the recovery of log stream data depends on the MVS images remaining active so that the system loggers can use copies of log records held in storage to repopulate the coupling facility when it is again available. If you must run with a single coupling facility, you are recommended to specify DUPLEXMODE(UNCOND) to force the use of staging data sets.

Defining coupling facility structures

If you use a coupling facility for your CICS log streams, define the coupling facility structures needed for the log streams in your CFRM policy (in the CFRM data set), and in the LOGR policy (in the LOGR data set).

Updating the CFRM policy

Coupling facility space is divided into structures using the coupling facility resource management (CFRM) policy defined in the CFRM data set. The CFRM policy allows you to define how MVS is to manage coupling facility resources, and you update this using the IXCMIAPU utility. See Figure 12 for a sample job to define coupling facility structures in the CFRM policy data set.

Updating the LOGR policy

You define structures in the MVS system logger LOGR policy in the system logger couple data sets using the DEFINE STRUCTURE specification of the ICXMIAPU utility. See Figure 13 for a sample job to define coupling facility structures in the LOGR policy data set.

Remember

Before attempting to run any of the IXCMIAPU jobs, ensure that the MVS system logger (IXGLOGR) is running. If IXGLOGR is not running (for example if MVS is running in LOCAL mode), logstream definition jobs fail with rc=0814.

Figure 12. Sample policy job to define logger structures to CFRM 1/2
//CFRM     JOB (accounting-information),CLASS=A,MSGCLASS=A
//POLICY   EXEC PGM=IXCMIAPU
//STEPLIB  DD DSN=SYS1.MIGLIB,DISP=SHR
//SYSPRINT DD SYSOUT=*
//*********************************************************************
//*                                                                   *
//*  System logger structure definitions should be merged with        *
//*  definitions for other structures required by the sysplex.        *
//*                                                                   *
//* Space values are for illustration only -- substitute values       *
//* appropriate to your number of logs and expected activity.         *
//*                                                                   *
//* NOTE:  The values in this job are not matched with the other      *
//         sample jobs.                                               *
//*********************************************************************
//SYSIN    DD *
   DATA TYPE(CFRM) REPORT(YES)
   DELETE POLICY NAME(POL1)
   DEFINE POLICY NAME(POL1)
       PREFLIST(cfname) REBUILDPERCENT(1) 
   /* Define coupling facilities */
     CF NAME(cfname)
        TYPE(009674)
        MFG(IBM)
        PLANT(00)
        SEQUENCE(000000040032)
        PARTITION(3)
        CPCID(00)
        DUMPSPACE(8192)
   /* Define other structures required by sysplex here . . .      */
 ... 
   /* Define logger structures for CICS log streams.              */
   /* - If a choice of facilities is available, use non-volatile  */
   /*     facilities if possible                                  */
   /* - Specify low REBUILDPERCENT so that structures are rebuilt */
   /*     in the event of connectivity failure                    */
   /* - INITSIZE gives initial coupling facility size (based on sizing calcs)    */
   /* - SIZE should be larger to allow for rebuild to a larger    */
   /*     size if INITSIZE proves to be too small                 */
   /*   SIZE and INITSIZE values are for illustration only -      */
   /*   substitute values appropriate for your intended usage.    */
 
     STRUCTURE NAME(LOG_DFHLOG_001)        /* CICS system logs    */
       INITSIZE(10000) SIZE(16000)
       PREFLIST(cfname) REBUILDPERCENT(1)
 
     STRUCTURE NAME(LOG_DFHSHUNT_001)      /* CICS secondary logs */
       INITSIZE(10000) SIZE(16000)
       PREFLIST(cfname) REBUILDPERCENT(1)
 
     STRUCTURE NAME(LOG_USERJNL_001)       /* CICS user journals  */
       INITSIZE(10000) SIZE(16000)
       PREFLIST(cfname) REBUILDPERCENT(1)
 
     STRUCTURE NAME(LOG_GENERAL_001)     /* Forward recovery logs */
       INITSIZE(10000) SIZE(16000)
       PREFLIST(cfname) REBUILDPERCENT(1)
/*
//

Multiple log streams can write data to a single coupling facility structure. This does not mean that the log data is merged; the log data stays segregated according to log stream. You can specify the number of log streams that use the resources of a single coupling facility structure using the LOGSNUM parameter on the IXCMIAPU service to define a structure.

Each log stream is allocated a proportion of the structure space based on the number of currently connected log streams (up to the limit specified in LOGSNUM).

For example, a structure may be defined to contain a maximum of, say, 30 log streams. If only 10 log streams are connected, each log stream can use one tenth of the space in the structure. As other log streams are connected and disconnected, the MVS system logger adjusts the proportion of space to be used by each log stream.

It is important to plan carefully before specifying a value for LOGSNUM, because this parameter determines how much storage space in the structure is available to each log stream. A number in the range 10 to 20 is optimum in many environments.

The JCL in Figure 13 defines log stream coupling facility structures to the MVS system logger. It is meant for guidance only and you should substitute values appropriate to your requirements.

Figure 13. Sample JCL to define coupling facility structures to MVS system logger
//DEFSTRUC JOB ...
//POLICY   EXEC PGM=IXCMIAPU
//STEPLIB  DD DSN=SYS1.MIGLIB,DISP=SHR
//SYSPRINT DD SYSOUT=*
//*********************************************************************
//*                                                                   *
//* Define log stream coupling facility structures to the MVS logger  *
//*                                                                   *
//* AVGBUFSIZE and LOGSNUM values are just for illustration,          *
//* substitute values appropriate to your intended usage              *
//*                                                                   *
//*********************************************************************
//SYSIN    DD *
  DATA TYPE(LOGR) REPORT(YES)
 
  /* System logs            */
  DEFINE STRUCTURE NAME(LOG_DFHLOG_001) LOGSNUM(10)
             MAXBUFSIZE(64000) AVGBUFSIZE(500)
 
  /* Secondary system logs  */
  DEFINE STRUCTURE NAME(LOG_DFHSHUNT_001) LOGSNUM(10)
             MAXBUFSIZE(64000) AVGBUFSIZE(4096)
 
  /* User journals with unforced writes  */
  DEFINE STRUCTURE NAME(LOG_USERJRNL_001) LOGSNUM(10)
             MAXBUFSIZE(64000) AVGBUFSIZE(64000)
 
  /* Fwd recovery logs and user jnls that are forced */
  DEFINE STRUCTURE NAME(LOG_GENERAL_001) LOGSNUM(10)
             MAXBUFSIZE(64000) AVGBUFSIZE(2048)
 
/*
//

See the z/OS MVS Programming: Assembler Services Guidez/OS MVS Programming: Assembler Services Guide for information on planning coupling facility configurations.

Planning considerations for the number of log structures

Bear in mind the following points when planning the definition of your coupling facility structures:

Log structure naming conventions

It is sensible to adopt a naming convention for your coupling facility structures that help to identify the purpose of the structure. A format such as LOG_purpose_nnn is recommended, where:

Some examples are:

LOG_DFHLOG_001
For the CICS primary system log. The structure should be large to avoid the need to write data to DASD. The average buffer size would be small. See the sizing calculations in Structure size for system log usage.
LOG_DFHSHUNT_001
For the CICS secondary system log. The structure should be small but requires a large buffer size. A structure of 150K per log stream may well be sufficient.
LOG_USERJRNL_001
For user journals where block writes are not forced. The average and maximum buffer sizes of these structures should be the same.
LOG_GENERAL_001
For forward recovery logs and user journals where block writes are forced periodically.

See also the section "Develop a naming convention for system logger resources" in the z/OS MVS Setting Up a Sysplex manual.

Defining coupling facility log streams

Use the MVS IXCMIAPU utility to define coupling facility log streams to the LOGR couple data set. The basic syntax to define a coupling facility log stream is as follows:

DEFINE LOGSTREAM NAME(log_stream_name)
             STRUCTNAME(structure_name)
             LOWOFFLOAD(low_offload) HIGHOFFLOAD(high_offload)
             STG_DUPLEX(YES|NO) DUPLEXMODE(COND|UNCOND)

For detailed information about the full range of log stream attributes, see the OS/390 Setting Up a Sysplex manual. Figure 15 shows example definitions for a pair of coupling facility log streams associated with a CICS system log.

Figure 15. Example definitions of coupling facility log streams. The definitions are for the CICS primary and secondary system log streams. The value region_userid is the RACF® userid under which the CICS address space is running; applid is the CICS region’s VTAM® APPL name (taken from the APPLID system initialization parameter).
//DEFLOGS  JOB ...
//LOGDEFN  EXEC PGM=IXCMIAPU
//STEPLIB  DD DSN=SYS1.MIGLIB,DISP=SHR
//SYSPRINT DD SYSOUT=*
//******************************************************************
//*                                                                *
//* Define coupling facility log streams for CICS system log.      *
//*                                                                *
//* The LOWOFFLOAD value is for illustration only --               *
//* substitute a value appropriate for your environment.           *
//*                                                                *
//******************************************************************
//SYSIN    DD *
  DATA TYPE(LOGR) REPORT(NO)
  DEFINE LOGSTREAM NAME(region_userid.applid.DFHLOG)
                   STRUCTNAME(LOG_DFHLOG_001)
                   LOWOFFLOAD(40) HIGHOFFLOAD(80)
                   STG_DUPLEX(YES) DUPLEXMODE(COND)
  DEFINE LOGSTREAM NAME(region_userid.applid.DFHSHUNT)
                   STRUCTNAME(LOG_DFHSHUNT_001)
                   LOWOFFLOAD(40) HIGHOFFLOAD(80)
                   STG_DUPLEX(YES) DUPLEXMODE(COND)

Using model log streams

To avoid having to define explicitly each log stream used by each of your CICS regions, you can use model log stream definitions. Using models, log streams are defined to MVS dynamically, on their first usage. Figure 16 shows an example of coupling facility model definitions for CICS primary and secondary system log streams.

Figure 16. Example model definitions for coupling facility system log streams. The value sysname is the sysid of the MVS image in which the CICS region or regions are running.
//DEFLOGS  JOB ...
//LOGDEFN  EXEC PGM=IXCMIAPU
//STEPLIB  DD DSN=SYS1.MIGLIB,DISP=SHR
//SYSPRINT DD SYSOUT=*
//******************************************************************
//*                                                                *
//* Define coupling facility model log streams for CICS system log.*
//*                                                                *
//* The LOWOFFLOAD value is for illustration only --               *
//* substitute a value appropriate for your environment.           *
//*                                                                *
//******************************************************************
//SYSIN    DD *
  DATA TYPE(LOGR) REPORT(NO)
  DEFINE LOGSTREAM NAME(sysname.DFHLOG.MODEL)
                   MODEL(YES)
                   STRUCTNAME(LOG_DFHLOG_001)
                   LOWOFFLOAD(40) HIGHOFFLOAD(80)
                   STG_DUPLEX(YES) DUPLEXMODE(COND)
  DEFINE LOGSTREAM NAME(sysname.DFHSHUNT.MODEL)
                   MODEL(YES)
                   STRUCTNAME(LOG_DFHSHUNT_001)
                   LOWOFFLOAD(40) HIGHOFFLOAD(80)
                   STG_DUPLEX(YES) DUPLEXMODE(COND)

For detailed information about using model log streams, see the CICS Recovery and Restart Guide. For information about the mapping of CICS journal definitions to log stream names, see the CICS System Definition Guide .

When using model log streams, you need to bear the following in mind:

Sizing considerations for coupling facility log streams

This section discusses how to size the following types of coupling facility log stream:

Sizing DFHLOG

For the CICS primary system log stream (DFHLOG), it is important to:

Sizing DFHSHUNT

It is important to size the secondary system log stream (DFHSHUNT) to avoid structure-full events. However, it is normal for some data to be offloaded from DFHSHUNT to secondary storage.

Sizing general logs

It is important to size forward recovery logs, user journals, and autojournals to avoid structure-full events. However, because CICS does not delete data from these log streams, it is normal for data to be offloaded to secondary storage.

Recommendations

Table 11 summarizes how you should decide on the values for various attributes on the structure definition, log stream definition, and system definition.

Table 11. How to decide on the values of attributes
Facility Attribute Recommendation
Structure INITSIZE Use the DFHLSCU utility program or the formula in topic INITSIZE calculation.
Structure SIZE Use DFHLSCU or the formula in topic SIZE calculation.
Structure AVGBUFSIZE Use DFHLSCU or the formula in topic AVGBUFSIZE calculation. Underestimate rather than overestimate.
Structure MAXBUFSIZE 64000
Primary system log stream (DFHLOG) HIGHOFFLOAD 80
Primary system log stream (DFHLOG) LOWOFFLOAD Use DFHLSCU or the formula in topic LOWOFFLOAD calculation.
Secondary system log stream (DFHSHUNT) HIGHOFFLOAD 80
Secondary system log stream (DFHSHUNT) LOWOFFLOAD 40 - 60
General log stream HIGHOFFLOAD 80
General log stream LOWOFFLOAD 0
Log stream STG_SIZE Use DFHLSCU or the formula in topic Staging data set size calculation.
Overestimate rather than underestimate.
CICS system AKPFREQ 4000
Note:
Startup may take longer than you experienced when using earlier releases. This is due in part to the allocation and formatting of the staging data sets. The increased time that startup takes is dependent on such things as:

It can be reduced by avoiding the use of unnecessarily large staging data sets.

The log stream sizing utility, DFHLSCU

If you are migrating from CICS/ESA 3.3 or CICS/ESA 4.1, you are strongly recommended to use the CICS-supplied utility program, DFHLSCU, to help you calculate your space requirements. DFHLSCU takes as input "old-style" (pre-CICS Transaction Server for OS/390, Version 1 Release 1-format) journal records, and analyzes them to establish values for:

AVGBUFSIZE
The average buffer size, in bytes, of a log stream structure in the coupling facility. Although it is important, that the value you specify for AVGBUFSIZE reflects as accurately as possible the real size of most log blocks written to the structure. This leads to efficient use of the space in the coupling facility and minimum DASD offloading frequency. However OS/390 (since release 3) performs some dynamic tuning, reducing the importance of the value you specify for AVGBUFSIZE.

You define this attribute in your DEFINE STRUCTURE job.

INITSIZE
The initial amount of space, in kilobytes, to be allocated for the log stream structure in the coupling facility. You define this attribute in your CFRM policy.
HIGHOFFLOAD
The point in primary storage (that is, in either the coupling facility structure or the staging data set), as a percentage of space consumed, where the MVS system logger starts its offload process. You define this attribute in your DEFINE LOGSTREAM job.
LOWOFFLOAD
The point in primary storage, as a percentage of space consumed, where the MVS system logger stops offloading data from primary storage to log stream DASD data sets. You define this attribute in your DEFINE LOGSTREAM job.
SIZE
The maximum size, in kilobytes, of the log stream structure in the coupling facility. You define this attribute in your CFRM policy. The value of the SIZE attribute is approximately 50% greater than the value of the INITSIZE attribute. You can dynamically increase the log stream structure size up to the value of the SIZE attribute.
STG_SIZE
The size, as a number of 4K blocks, of the staging data set for the log stream. A coupling facility log stream may or may not use a staging data set. For advice on the use of staging data sets with coupling facility log streams, see Staging data sets for coupling facility log streams.

You define this attribute in the DEFINE LOGSTREAM statements of your IXCMIAPU job. If you are using a staging data set and do not specify STG_SIZE, the MVS logger determines the size from

For details on how to use DFHLSCU, see the CICS Operations and Utilities Guide .

If DFHLSCU is inappropriate for use in your environment

If it is inappropriate for you to use DFHLSCU to help you size your coupling facility structures and log streams (perhaps you have no CICS Version 4 or Version 3 journal records to use as input to DFHLSCU, or you are capacity planning for new applications), the following sections help you to calculate your space requirements.

The formulae provided help you to calculate values for:

You must base your calculations on the journaling requirements of your applications. This provides the starting point for the following formulae.

Structure size for system log usage

You are recommended not to place the primary and secondary log streams in the same structure due to the large disparity in data volumes written to the primary and secondary system logs.

Generally, the volume of data that CICS keeps in the primary system log at any one time is slightly greater than the amount written during one activity keypoint interval. This volume is determined by the activity keypoint frequency, which is measured in the number of write requests to the CICS system log stream output buffer, and defined on the AKPFREQ system initialization parameter. Review the value specified on the AKPFREQ system initialization parameter when planning coupling facility structure sizes.

The INITSIZE value to be supplied in the CFRM policy can be calculated as follows:

Figure 17. INITSIZE calculation
		INITSIZE = 310 + ( LOGSNUM * A * B / 1024)    
	where  	 A = 2000 + (no. entries + 5)
	and   	 B = (AVGBUFSIZE * 1.1289) + 195

The value for the number of entries (no. entries) can be calculated as follows:

               no. entries =  ((akpintvl + trandur) * writespersec) / 0.9

where:

You can calculate AVGBUFSIZE for DFHLOG from the weighted average of the data logged by the most frequently executed transactions in the system:

AVGBUFSIZE = (bytespersec / writespersec) + 48

where:

If the result of the calculation shows a value for AVGBUFSIZE that is greater than the value defined for MAXBUFSIZE, then the value defined for MAXBUFSIZE is taken as the value for AVGBUFSIZE, and writespersec is calculated as follows:

writespersec = bytespersec / (MAXBUFSIZE - 48)

Round the final result of the INITSIZE formula up to the next multiple of 256.

The SIZE value to be supplied in the CFRM policy can be calculated as follows:

Figure 18. SIZE calculation
			SIZE = 480 + ( LOGSNUM * A * B / 1024) 
		where  	 A = 2500 + (no. entries + 5)
		and   	 B = (AVGBUFSIZE * 1.6821) + 289

Calculate the value for the number of entries as in the INITSIZE formula.

Round the final result of the SIZE formula up to the next multiple of 256. The formula for SIZE gives a result that is approximately fifty percent greater that the INITSIZE value.

Generally, the secondary system log stream needs to be only a fraction of the size of the primary log stream. Use the following formulae to calculate coupling facility space for DFHSHUNT:

INITSIZE = (150 * LOGSNUM) + 310
SIZE = (230 * LOGSNUM) + 480

You can calculate a suitable value for LOWOFFLOAD for DFHLOG using the following formula:

LOWOFFLOAD = (trandur * 90) / (akpintvl + trandur) + 10  (where RETPD=0 specified)

or

LOWOFFLOAD = (trandur * 90) / (akpintvl + trandur)    (where RETPD=dddd specified)            

where:

Structure size for forward recovery log usage

You can merge the forward recovery logs written by many CICS regions onto the same log stream. You can also use the same log stream for forward recovery data for multiple data sets.

See Figure 17 and Figure 18 for the formulae to calculate values for the INITSIZE and SIZE attributes.

Calculate a value for number of entries as follows:

no. entries = writespersec * 12.5

where:

writespersec = lesser of 25 or (N1 + ... + Nn)

where N1 .... Nn is the number of transactions per second writing to each data set.

You can calculate AVGBUFSIZE as follows:

AVGBUFSIZE = (bytespersec / writespersec) + 36

where:

If the records are WRITE ADD, WRITE ADD COMPLETE, or WRITE ADD DELETE records, rechdr is 84 and is followed by the record key, and the record data (including its key).

If the result of the calculation shows a value for AVGBUFSIZE that is greater than the value defined for MAXBUFSIZE, then the value defined for MAXBUFSIZE is taken as the value for AVGBUFSIZE, and writespersec is calculated as follows:

writespersec = bytespersec / (MAXBUFSIZE - 36)
Structure size for user journal and autojournal usage

See Figure 17 and Figure 18 for the formulae to calculate values for the INITSIZE and SIZE attributes.

Calculate a value for number of entries as follows:

no. entries = writespersec * 12.5

See the explanation of writespersec below.

For journals where the log blocks are not forced to the log stream, the average block size tends to be slightly less than the MAXBUFSIZE value defined for the coupling facility structure.

For journals where the log blocks are forced to the log, (via the EXEC CICS WAIT JOURNALNAME or EXEC CICS WAIT JOURNALNUM commands, or via the WAIT option of the EXEC CICS WRITE JOURNALNAME or EXEC CICS WRITE JOURNALNUM commands), you can calculate AVGBUFSIZE from the weighted average of the data logged for each journal logging to the same log stream for a given CICS system.

AVGBUFSIZE = (bytespersec / (writespersec) + 36

where:

Autojournal records are issued from file control. They may be DATA SET NAME records which consist of a 204-byte record header, and no further data. Alternatively, they may be READ ONLY, READ UPDATE, WRITE UPDATE, WRITE ADD, or WRITE ADD COMPLETE records In this case, rechdr is 84 and is followed by the file control record itself.

User journal records consist of a 68-byte record header, followed by the user prefix, and the user data.

If the result of the calculation shows a value for AVGBUFSIZE that is greater than the value defined for MAXBUFSIZE, then the value defined for MAXBUFSIZE is taken as the value for AVGBUFSIZE, and writespersec is calculated as follows:

writespersec = bytespersec / (MAXBUFSIZE - 36)

Coupling facility requirements in an RLS environment

When you move to an RLS environment from an environment in which multiple AORs have been accessing data sets in an FOR, the logging activity of the FOR is distributed across the AORs. As a consequence, the coupling facility structure size required by each AOR increases.

You can use the formulae for INITSIZE and SIZE, given in Figure 17 and Figure 18. However, you need to calculate values for:

using formulae which are different to those already described.

Use either reports produced by DFHLSCU for the CICS/ESA 4.1 AOR and FOR system logs, or log stream statistics from CICS Transaction Server for z/OS®, to calculate

in a reporting interval for the AORs and the FOR.

Calculating increased AOR coupling facility storage requirements

Use the following formulae to calculate:

for the AORs in the new RLS environment.

Calculate the AOR AVGBUFSIZE value required by the INITSIZE and SIZE formulae as follows:

AOR AVGBUFSIZE = ( AOR_bytes + (FOR_bytes / no. of AORs) ) / (intvlen * 25)                    

where:

Calculate the AOR 'number of entries' value required by the INITSIZE and SIZE formulae as follows:

AOR no. entries = ((AOR_akpintvl + trandur) * 25) / 0.9

where:

Once you have calculated the values for AOR AVGBUFSIZE and AOR no. entries, use the formulae for INITSIZE and SIZE, as described in Figure 17 and Figure 18.

Staging data sets for coupling facility log streams

MVS normally keeps a second copy of the data written to the coupling facility in a data space, for use when rebuilding a coupling facility log in the event of an error. This is satisfactory as long as the coupling facility is failure-independent (in a separate CPC and non-volatile) from MVS.

Where the coupling facility is in the same CPC, or uses volatile storage, the MVS system logger supports staging data sets for copies of log stream data that would otherwise be vulnerable to failures that impact both the coupling facility and the MVS images.

The following recommendations are for guidance when defining log streams:

[[ Contents Previous Page | Next Page Index ]]