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.
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).
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.
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.
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.
//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.
//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.
Bear in mind the following points when planning the definition of your coupling facility structures:
Recovery would, otherwise, be delayed until the next time that a system attempts to connect to a log stream in the affected structures, or until the logger address space of the failing system is restarted.
For example, in a 4-way sysplex comprising MVSA, MVSB, MVSC, and MVSD, you might have the CICS regions that normally run on MVSA and MVSB use structure LOG_DFHLOG_001, and 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. Also, if you have more than one coupling facility, allocate the system log structures to different coupling facilities. See Figure 14 for an illustration of this example.
There is no significant advantage in setting MAXBUFSIZE lower than 64000 as far as the utilization of storage is concerned.
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:
See also the section "Develop a naming convention for system logger resources" in the z/OS MVS Setting Up a Sysplex manual.
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.
//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)
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.
//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:
This section discusses how to size the following types of coupling facility log stream:
For the CICS primary system log stream (DFHLOG), it is important to:
The MVS system logger begins the offload process when the high offload threshold (HIGHOFFLOAD) of the log stream is reached. The offload process consists of two steps:
To minimize the amount of data offloaded from the CICS primary system log:
A structure-full event occurs when a log stream’s structure space becomes full before the offloading of data has completed.
For advice on monitoring and avoiding structure-full events, see the CICS Performance Guide .
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.
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.
Table 11 summarizes how you should decide on the values for various attributes on the structure definition, log stream definition, and system definition.
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 |
It can be reduced by avoiding the use of unnecessarily large staging data sets.
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:
You define this attribute in your DEFINE STRUCTURE job.
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 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.
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:
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:
akpintvl = AKPFREQ / ((N1 * R1) + (N2 * R2) + (Nn * Rn) )
where:
If this duration is longer than akpintvl value, you can either:
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:
You can calculate the amount of data (Dn) written to the system log for each transaction:
Dn = Ns * syncreclen +
Nfc * (fcrechdr + fcreclen) +
Nts * (tsrechdr + tsreclen) +
Ntd * (tdrechdr + tdreclen) +
Nur * (urrechdr + urreclen)
where:
Count only READ UPDATE and WRITE ADD records. fcrechdr is 144 (136 bytes of record header plus 8 bytes of file name).
Similarly:
Count only TS PUT and TS UPDATE records.
For TS PUT records, tsrechdr is 108, and tsreclen is 88.
For TS UPDATE records, tsrechdr is 108, and tsreclen is 52.
tdrechdr is 108, and tdreclen is 380.
urrechdr is 125.
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:
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:
If this duration is longer than akpintvl value, you can either:
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)
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)
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.
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:
AOR_akpintvl = ( AKPFREQ * intvlen ) / ( AOR_recs + (FOR_recs / no. of AORs) )
where:
If this is longer than AOR_akpintvl, use AOR_akpintvl as the duration or consider increasing AKPFREQ.
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.
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:
A connection to a log stream contains a single point of failure if the coupling facility is volatile or it resides on the same CPC as the MVS system connecting to it. For example, if you have two CPCs, CPC1 and CPC2, and CPC1 has an MVS LPAR and a coupling facility, while CPC2 has only MVS LPARs, the connections from the MVS LPAR in CPC1 to the coupling facility are failure dependent--if you lose CPC1 you lose both MVS and its local buffers and the coupling facility. On the other hand, the connections from CPC2 are failure independent, because the system logger local storage and buffers are in a physically separate CPC from the coupling facility, and you would have to lose both to lose data. With DUPLEXMODE(COND), failure dependent connections result in staging sets, while failure independent connections are not allocated staging data sets.
For example, the staging data set size corresponding to the basic coupling facility space requirement for each CICS system log stream (DFHLOG) can be calculated by the following formula:
staging data set size = entries * rnd-avg-buf / 4096
where:
rnd-avg-buf = avgbufsize (rounded up to 4K)
See topic number of entries calculation for the formula to calculate no. entries.