Defining coupling facility structures

If you use a coupling facility for your CICS® log streams, define the coupling facility structures you require 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 policy using the IXCMIAPU utility. See Figure 1 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 2 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.

Figure 1. 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(002097)
        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)

     STRUCTURE NAME(LOG_CICSVR)            /* CICS VR logs */
       INITSIZE(10000) SIZE(16000)
       PREFLIST(cfname) REBUILDPERCENT(1)
/*
//

Multiple log streams can write data to a single coupling facility structure. The log data is not 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, you might define a structure 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.

You must 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 2 defines log stream coupling facility structures to the MVS system logger. It is meant for guidance only and you must substitute values appropriate to your requirements.
Figure 2. 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 Guide for information on planning coupling facility configurations.