Requirements planning and checklist for the logger environment

The requirements and the procedure to set up the CICS® logging environment are outlined.

The procedure includes tasks for MVS™ system programmers, CICS system programmers, and security administrators, and close cooperation between all groups is required.

  • Plan the logger environment.
    Consider the possible storage options, and choose which of the three available hardware options to use:
    • Nonvolatile coupling facility, where log stream data is duplexed in the MVS logger data space. Nonvolatile storage involves the use of battery backup or an uninterruptible power supply (UPS):
      • When using a UPS, you use a hardware console command to update coupling facility status.
      • When using battery backup, batteries must be online and charged.
    • Volatile coupling facility, where log stream data is duplexed to a staging data set.
    • DASD-only, where log stream data is duplexed in the MVS logger data space.
    See Coupling facility or DASD-only?, to help you decide on one of these or a combination of both.
    Make the following planning decisions:
    • Determine the number CICS regions that require logger support and hence system log streams.
    • Determine the number of user journals and autojournals that your regions use.
    • Determine the number of forward recovery logs required for VSAM data sets.
    • Determine whether any user journal or forward recovery log streams are to be shared between regions (to create merged data automatically). The system log streams, DFHLOG and DFHSHUNT, cannot be shared.

      DASD-only log streams can be shared only in the same MVS image.

    • Decide on the number and sizes of the coupling facilities to be used.

      For information about types of coupling facility, see z/OS MVS Setting Up a Sysplex. The minimum level of coupling facility supported by the MVS system logger is CFLEVEL=1, with the appropriate service level of the coupling facility control code that supports CFLEVEL=1.

    • Determine the log stream sizes:
  • Apply any maintenance updates.
    Ensure that all maintenance affecting the MVS system logger, and the CICS log manager and its utilities, is applied.
    • Logger serviceability APARs that relate to the MVS system logger are identified with the LOGRSERVICE keyword.
    • APARs that relate to the CICS log manager are identified with the CICSLOGR keyword.
  • Create and format the LOGR couple data sets.
    You need to know the number of log streams and, for coupling facility log streams, the number of structures. Each CICS region requires two system log streams and the following optional log streams:
    • A log stream for the log of logs.
    • One or more log streams for forward recovery logs.
    • One or more log streams for autojournals.
    • One or more log streams for user journals.
    In consultation with your MVS system programmer, complete the following steps:
    • Use MVS utility IXCL1DSU to create and format the primary and alternate LOGR couple data sets.
    • Identify the LOGR couple data sets to the sysplex in the COUPLExx member in SYS1.PARMLIB.
    • Make the LOGR couple data set available to the sysplex.
    For more information, see Format the LOGR Couple Data Set and Make it Available to the Sysplex in z/OS MVS Setting Up a Sysplex.
  • Define the coupling facility structures.

    If you are using the coupling facility for some or all of your log streams, update your CFRM policy and your LOGR couple data set with the required structure definitions. See Defining coupling facility structures for details, including a sample job.

  • Establish the required security authorizations
    Ensure that all the user IDs that are involved with running the system logger, or defining or accessing logger resources, are authorized, and that the required profiles are defined in the LOGSTRM general resource class.
    • If the MVS system logger address space (IXGLOGR) is not given SAF privileged or trusted status, ensure that you give the required authorization to the user ID that runs IXGLOGR. For example, if the user ID that runs IXGLOGR (defined in the RACF® started procedures table (ICHRIN03), or defined in the RACF STARTED class profile) is SYSTASK:
      • SYSTASK requires ALTER access to IXLSTR structure profiles in the FACILITY general resource class for access to log stream coupling facility structures.
      • SYSTASK requires ALTER access to the data set profiles (hlq.data_set_name) in the DATASET general resource class, for each DASD log stream and staging data set.
    • To use the MVS system logger IXCMIAPU utility to define, update and delete entries in the LOGR couple data set, you must have appropriate authorizations to the relevant RACF profiles in the LOGSTRM and FACILITY general resource classes. See Authorizing users of IXCMIAPU for information and examples of how to do this.
    • To enable CICS to create log streams dynamically, and to write to log streams, ensure that the CICS region user ID has the required authorizations. See Authorizations for CICS regions for information and examples of how to do this.

    Ensure that all the user IDs that are involved with running the system logger, or defining or accessing logger resources, are authorized, and that the required profiles are defined in the LOGSTRM general resource class. For more information about authorizations for the system logger, see z/OS MVS Setting Up a Sysplex.

  • Check the sysplex definition in PARMLIB.

    To use the MVS system logger, each MVS image must be a member of a sysplex. Ensure your sysplex definition, in PARMLIB member IEASYSxx, specifies either PLEXCFG(MONOPLEX), for a single-member sysplex, or PLEXCFG(MULTISYSTEM), for a multi-member sysplex. Also ensure that you define a COUPLExx, member in PARMLIB. The value specified on the SYSPLEX parameter in COUPLExx, forms part of DASD-only and staging data set names.

  • Activate the LOGR subsystem.
    Ensure that the LOGR subsystem is active so that the CICS log manager batch utility, DFHJUP, can format and print log data. The LOGR susbsystem is defined by the following entry in IEFSSNxx PARMLIB member: 
    SUBSYS SUBNAME(LOGR) INITRTN(IXGSSINT)
  • Plan staging data set requirements.
    Staging data sets are used for both DASD-only and coupling facility log streams, and if specified are dynamically allocated by the MVS system logger:
    • For DASD-only log streams, staging data sets are the primary (interim) storage.
    • For coupling facility log streams, staging data sets are allocated by the system logger to safeguard log data in the event of the log data being in a volatile configuration; that is:
      • There is a loss of the coupling facility battery backup
      • A structure failure that results in the only copy of log data being in MVS local storage buffers.
    Review the following parameters:
    • STG_DUPLEX(YES) and DUPLEXMODE(COND) to cause the system logger to use staging data sets if the coupling facility is not failure independent (see Staging data sets for coupling facility logstreams for more information).
    • STG_MGMTCLAS to specify the System Managed Storage (SMS) management class to be used for staging data set allocation (valid only when STG_DUPLEX(YES) or DASDONLY(YES) is specified)
    • STG_STORCLAS to specify the SMS storage class to be used for staging data set allocation (valid only when STG_DUPLEX(YES) or DASDONLY(YES) is specified).
    • STG_SIZE to specify the size of staging data sets.
    • SHAREOPTIONS(3,3) for log stream data sets and staging data sets (see VSAM Share Options for System Logger in z/OS MVS Setting Up a Sysplex).
  • Plan DASD space and SMS environment for logger auxiliary storage.

    System logger auxiliary storage comprises all log stream (offload) data sets. See Managing auxiliary storage for information about size parameters and other attributes that relate to auxiliary storage.

  • Define log streams and log stream models.
    Define the specific log streams, and log stream models for dynamic creation of log streams, in the LOGR policy. Ensure that you complete the following steps:
    • Set HIGHOFFLOAD no higher than 80% so that the offload function can be activated before structures reach the 90% level and to provide a buffer so that CICS can continue to write records without filling the logstream before offload completes.
    • Set LOWOFFLOAD for DFHLOG and DFHSHUNT in the range 40–60%. For user journals and the log of logs, specify LOWOFFLOAD as 0.
    • Specify HLQ for the high level qualifier for offload data sets. It is not part of the CICS log stream name. The default is IXGLOGR.
    • Specify STG_DUPLEX(YES) and DUPLEXMODE(COND) for log streams in the coupling facility to ensure that staging data sets are used automatically if the coupling facility is volatile or failure dependent.
    • Set STG_SIZE to control the size, in 4KB blocks, of staging data sets allocated by the system logger. For coupling facility log streams, the staging data set must hold at least as much data as the log stream in the structure, so that offloads are not triggered by the staging data sets. See Sizing coupling facility log streams and Sizing for DASD-only log streams.
    • Specify LS_DATACLAS and LS_SIZE, for the SMS data class and the number of 4KB allocation blocks respectively for log stream off load data sets. See Managing auxiliary storage.
    • Specify MODEL(YES) to indicate that a log stream definition is a model only and not an actual log stream. See SDFHINST members DFHILG2 (coupling facility) and DFHILG5 (DASD-only) for samples of model log streams.

    Use AUTODELETE(YES) with a suitable retention period (RETPD) for general logs but not for CICS system logs (DFHLOG and DFHSHUNT). See Defining coupling facility log streams for some sample IXCMIAPU jobs, and z/OS MVS Setting Up a Sysplex for general information about updating LOGR policies.

  • Define JOURNALMODEL resource definitions.

    Define JOURNALMODEL resource definitions in the CICS CSD to enable CICS to map CICS journal names to MVS system logger log stream names. See JOURNALMODEL resources.

    The MVS system logger log stream names must match the streamnames that are used in the JOURNALMODEL resource definitions, otherwise the following error messages might occur at CICS region startup:
    • IXG231I IXGCONN REQUEST=CONNECT TO LOG STREAM stream_name DID NOT SUCCEED
    • DFHLG0508 Log stream stream_name not defined to MVS
    • DFHLG0731 A failure has occurred while opening the system log (DFHLOG).
  • Review the AKPFREQ system initialization parameter.

    This parameter represents the number of write operations (log records) by CICS log manager to the log stream buffer before an activity keypoint is taken, whereas under the old journal control program it specifies the number of consecutive blocks written to the system log data set.

    The parameter has a significant effect on the size of system logger primary (interim) storage, affecting the log tail management that takes place during activity keypoint (AKP) processing. The system logger acts as follows:
    • It deletes records that are no longer of interest to CICS
    • It moves records to DFHSHUNT for those tasks that wrote log records in the last ACP.
  • Evaluate the results after implementation.
    After you implemented the procedure to use the MVS system logger for CICS log streams and journals, evaluate the results on a continual basis. You can use the following:
    • CICS interval statistics. You can collect these at specified intervals and end-of-day to obtain CICS log manager statistics. You can also collect statistics using the DFH0STAT sample program.
    • SMF Type 88 records. These are produced by the MVS system logger, and can be printed using IXGRPT1, which is supplied in SYS1.SAMPLIB. You can also print these records using IXGRPT1J and IXGRPT1L.