5.2 Definitions

< Day Day Up >

To implement the System Logger in a CICS environment, a number of definitions are required as shown in Figure 5-3 on page 141. The figure is organized by task on the left with the related policy listed on the right. Each of the z/OS policies can be considered similar in concept to the CICS System Definition (CSD) file.

click to expand
Figure 5-3: System Logger-related definitions

The utility used to define resources in the System Logger and CFRM policies is IXCMIAPU, which is similar in function to DFHCSDUP for CICS.

5.2.1 Subsystem definitions

As shown in Figure 5-3, there are many parts which must be in place prior to a log stream being used by CICS. The log streams can be pre-defined, or dynamically installed. In either case, if a specific log stream name (other than the default generated by CICS) is to be used when CICS connects to the log stream, it must be supplied in a CICS journal model.

When a CICS region is started, it connects to the DFHLOG and DFHSHUNT log streams which make up the system log. If journal models have been defined for DFHLOG and DFHSHUNT, CICS uses the log stream name (LSN) found in the model for the connect.

If a JOURNALMODEL has not been defined, &USERID..&APPLID..DFHLOG (or DFHSHUNT) is used as the LSN.

For non-system logs, CICS searches for a journal model, for example DFHJ07 for user journal 7. If a journal model is found, the LSN provided is used. If a journal model is not found, a log stream name of &userid..&applid..&jnam, for example GRAUEL.IYOT1.DFHJ07, is used.

CICS Journal Models

Figure 5-4 provides a sample job for defining a CICS journal model. The important parameters are JOURNALNAME, TYPE, and STREAMNAME. The JOURNALNAME is the name used in the CICS environment such as DFHLOG, or DFHJ07. The TYPE must be "MVS" and streamname identifies the log stream name (LSN).

  //DFHCSDUP JOB CLASS=A,MSGCLASS=A  //UPGRCSD   EXEC PGM=DFHCSDUP  //STEPLIB   DD DSN=CICSTS22.CICS.SDFHLOAD,DISP=SHR  //SYSPRINT DD SYSOUT=*  //SYSIN DD *   DEFINE JOURNALMODEL(CICSLOG)       The name of the model is CICSLOG             GROUP(TEST)              The CICS group name is TEST             DESCRIPTION('DFHLOG LOGSTREAM USING A TEMPLATE DEFINITION')             JOURNALNAME(DFHLOG)             TYPE(MVS)                Records to be written to the MVS log stream                                      specified.             STREAMNAME(&USERID..&APPLID..DFHLOG) The CICS logger issues an IXGCONN                                      to connect to the streamname derived from the                                      template or the name explicitly specified. DEFINE JOURNALMODEL(SYSSHUNT)           TYPE(MVS) GROUP(TEST) JOURNALNAME(DFHSHUNT)           DESCRIPTION('DFHSHUNT LOGSTREAM EXPLICIT DEFINITION')           STREAMNAME(TCOM.IYCLZCCA.DFHSHUNT)

Figure 5-4: Sample CICS JOURNALMODEL

JOURNALMODEL

The JOURNALMODEL may contain an explicit log stream name (for example, JIMG.JIMSAOR.DFHLOG) or a TEMPLATE value (for example, &applid..DFHLOG), in which case the symbolic qualifiers are used to build the actual log stream name.

Valid symbolic qualifiers are:

&USERID	The symbolic name for the CICS region userid, which can be up to eight characters. If the region does not have a userid, the string "CICS" will be used.
&APPLID	The symbolic name for the CICS region APPLID, as specified in the APPLID system initialization parameter, and can be up to eight characters.
&JNAM	The symbolic name for a journal name which references, either by a specific or generic match, this journal model definition. &JNAME can be up to eight characters in length.
&SYSID	The symbolic name for the CICS region SYSID as specified in the SYSIDNT system initialization parameter. If SYSID is not specified, the string "CICS" will be used.

Tip

Log stream names (LSN) can only have a maximum of 26 characters. The reason for the restriction is in the offload (log) data set names. Offload data sets contain the LSN with a prefix of the High Level Qualifier (HLQ) as specified on the System Logger policy definition, plus an 8-character sequence number.

For example, if the Log Stream Name (LSN) is IYOT1.DFHLOG, and the HLQ is CICSLVL2, the offload data set name would be CICSLVL2.IYOT1.DFHLOG.Axxxxxxx

When the log stream is defined, the first offload data set will be allocated. If the LSN is greater than 26 characters and the HLQ is 8 characters (the sequence number will always be 8 characters), the allocation will fail.

The failure is fairly easy to spot when the log stream is being defined with IXCMIAPU. When the log stream is being dynamically defined during a CICS initial start, the failure is not so easy to spot. CICS will terminate with a DFHLGxxx message with an IXC251I message is written to the console.

Once the log stream name is defined, CICS will issue an IXGCONN request to connect to the log stream. If the log stream has not been defined in the System Logger policy, the System Logger returns IXGRSNCODENOSTREAM (RC 8 reason code 080B).

During a CICS initial start, if the log stream for DFHLOG (or DFHSHUNT) is not found, upon receiving an 080B, CICS attempts to create the log stream via an IXGINVNT DEFINE request using the MVS model sysname.DFHLOG.MODEL. The model used for DFHSHUNT is sysname.DFHSHUNT.MODEL. In all cases the log stream name remains the same — the one used for the original IXGCONN call.

For a non-system log (user journal, forward recovery log, or auto journal), the name of the logger model used consists of the first two qualifiers of the log stream name with MODEL appended (for example, if the log stream name is JIM.JON.HARRY - the model name will be JIM.JON.MODEL). The MVS models must exist in the System Logger policy (that is, a DEFINE LOGSTREAM has been issued for a log stream called JIM.JON.MODEL with MODEL(YES) specified).

If the create request for either DFHLOG or DFHSHUNT fails, CICS will abend, with a message in the range of DFHLG0503 through 0511 being issued.

DFHSIT Parameters

The CICS System Initialization parameters which affect the interaction with the System Logger are AKPFREQ (Activity Key Point Frequency) and LGDFINT (Log Defer Interval).

AKPFREQ

The activity keypoint frequency value (AKPFREQ) specifies the number of times CICS appends log records to the buffer associated with the DFHLOG log stream before an activity keypoint is initiated. It does not reflect how much data is held in the buffer prior to it being written to the log stream. The data is written as required (based on the buffer filling, or the force option being specified on the call to the CICS logger domain). A keypoint is a snapshot of in-flight tasks in the system at the time. The activity keypoint interval is defined as the interval of time between two consecutive activity keypoints.

During the activity keypoint, CICS initiates the tail trimming process for DFHLOG and DFHSHUNT. CICS determines the history point (the oldest record required for transaction backout) for DFHLOG and DFHSHUNT and issue an IXGDELET call to the System Logger to logically delete blocks of data older than the history point. Logically deleted data will be discarded by the System Logger during the next offload process for the log stream. It's important to note the oldest record required defines the new tail of the log. No data is deleted which is newer than the history point.

CEMT I SYS may be used to view and dynamically change the value for AKPFREQ.

LGDFINT

LGDFINT specifies the "log defer" interval. The log defer interval is the length of time CICS delays a forced journal write (a write which is considered immediate) before issuing the IXGWRITE call. The intent is to allow additional records to be placed in the buffer and reduce the number of IXGWRITE calls to the System Logger.

The LGDFINT mechanism applies only to DFHLOG and DFHSHUNT log streams.

However, when a buffer fills it is written without waiting for the log defer interval.

When a journal write call is passed to the logger domain with the wait option, the record is simply appended to the current buffer. The buffer is written either when it fills and the application will wait for the completion of the IXGWRITE.

When a journal write call is passed to the logger domain with the force option, the logger domain is synchronously issuing an IXGWRITE and the record is immediately written to the log stream.

The LGDFINT default value in releases prior to CICS Transaction Server V2.2 was 30 milliseconds (ms). In V2.2 the default was changed to 5 ms. The recommendation is LGDFINT be set to 5 for all releases.

CEMT I SYS may be used to view and dynamically change the value for LGDFINT.

5.2.2 System Logger definitions

As shown in Figure 5-3 on page 141, most of the actual set up is for resources required from the z/OS point of view.

CICS provides several sample jobs (DFHILG1-7) in the SDFHINST library to assist with log stream definitions. However, the jobs do not contain installation-specific information. The jobs should be used as JCL examples. The following samples are provided to show parameters which affect performance and suggested settings in a CICS environment. However, note that the sizes shown must be replaced with values which match the needs of the log stream being defined.

Log streams

CICS can use CF-Structure log streams and/or DASD-only log streams. The definition and recommendations differ depending on the type being used. Definitions for a CF-Structure based log stream will be discussed first, and then the DASD-only log streams in "DASD-only log stream" on page 153.

CF-Structure log stream

The following are sample JCL and IXCMIAPU statements to define CF-Structure log streams. The parameters and values used are discussed in each of the following sections.

Define a Structure for CICS log streams in the CFRM Policy

Figure 5-5 on page 145 illustrates defining the LOG_JG structure in the CFRM policy.

  //DEFSTR JOB CLASS=A,MSGCLASS=A  //POLICY EXEC PGM=IXCMIAPU  //SYSPRINT DD SYSOUT=A  //SYSIN DD *  DATA TYPE(CFRM) REPORT(YES)  DEFINE STRUCTURE NAME(LOG_JG)          LOG_JG is the structure name     INITSIZE(20000)                     INITIAL structure size, in 1K units     SIZE(30000)                         Structure can be ALTERed up to this size     PREFLIST(CF01,CF02)                 Specifies CF preference selection order     ALLOWAUTOALT(NO)                    XES can not automatically alter this structure     FULLTHRESHOLD(90)                   Issues messages if structure reaches 90% full

Figure 5-5: Defining structure in CFRM policy

FULLTHRESHOLD

FULLTHRESHOLD (added in OS/390 2.9) specifies a percentage value used by automatic alter processing and structure full monitoring. If the structure exceeds this percent utilization, auto alter may adjust the structure (if you specified ALLOWAUTOALT(YES)) and issue messages to the console. The value specified on this keyword should be larger than the HIGHOFFLOAD for the log streams in this structure.

If you disable structure full monitoring by specifying FULLTHRESHOLD(0), no messages are displayed and information from the SMF Type 88 records should be used to tune the log streams.

ALLOWAUTOALT

If ALLOWAUTOALT(YES) (added in OS/390 R10) is specified, when the FULLTHRESHOLD value is reached, XCF will issue message IXC585E and automatically start an ALTER against the structure to relieve the storage shortage. XCF will issue message IXC588I to the system log to externalize the ALTER request. Refer to Figure 5-6 on page 146 for an example of the XCF messages.

 MV2C     01145 03:51:49.50          00000080 *IXC585E STRUCTURE LOG_JG2 IN COUPLING FACILITY SVCF04, 979                                 979 00000080  PHYSICAL STRUCTURE VERSION B5E2748F D0885E02,                                 979 00000080  IS AT OR ABOVE STRUCTURE FULL MONITORING THRESHOLD OF 80%.                                 979 00000080  ENTRIES:  IN-USE:        930 TOTAL:       1105,  84% FULL                                 979 00000080  ELEMENTS: IN-USE:       2401 TOTAL:       8841,  27% FULL MV2C     01145 03:51:49.52          00000280  IXC588I AUTOMATIC ALTER PROCESSING INITIATED 980                                 980 00000080  FOR STRUCTURE LOG_JG2.                                 980 00000080  CURRENT SIZE:       3072 K                                 980 00000080  TARGET SIZE:        3072 K                                 980 00000080  TARGET ENTRY TO ELEMENT RATIO:       1192 :       3078                                 980 00000080  TARGET EMC STORAGE PERCENTAGE: 0.00 MV2C     01145 03:51:58.30          00000280  IXC590I AUTOMATIC ALTER PROCESSING FOR STRUCTURE LOG_JG2 982                                 982 00000080  COMPLETED. TARGET ATTAINED.                                 982 00000080  CURRENT SIZE:                3072 K  TARGET:       3072 K                                 982 00000080  CURRENT ENTRY COUNT:         2921    TARGET:       2921                                 982 00000080  CURRENT ELEMENT COUNT:       7542    TARGET:       7542                                 982 00000080  CURRENT EMC COUNT:              0    TARGET:          0 MV2C     01145 03:52:53.33          00000080  IXC586I STRUCTURE LOG_JG2 IN COUPLING FACILITY SVCF04, 998                                 998 00000080 PHYSICAL STRUCTURE VERSION B5E2748F D0885E02,                                 998 00000080 IS NOW BELOW STRUCTURE FULL MONITORING THRESHOLD.

Figure 5-6: Example of Auto Alter messages

Because the offload capability provided by System Logger is threshold driven, you do not want XES adjusting the structure size at the same time System Logger is trying to manage the log streams within the existing structure space. Similarly, because System Logger provides its own function for dynamically adjusting the entry-to-element ratios, you do not want XES making similar adjustments independently of System Logger. Therefore, you should always specify ALLOWAUTOALT(NO) for any System Logger structure.

Additional information can be found in the topic "Define the Coupling Facility Structures Attributes in the CFRM Policy Couple Data Set" in z/OS MVS Setting Up a Sysplex, SA22-7625.

SIZE

SIZE(nnnn) Specifies the maximum amount of space to be allocated for the structure in the CF. The number is specified in units of 1K (1024 bytes). The maximum structure size is the largest size to which the structure can be dynamically altered. Specifying too large a maximum structure size can waste CF resources.

INITSIZE

INITSIZE(nnnn) Specifies the initial amount of space to be allocated for the structure in the CF. The number is specified in units of 1K (1024 bytes). The INITSIZE value must be less than or equal to the SIZE value.

MINSIZE

MINSIZE(nnnn) MINSIZE specifies the smallest size in units of 1K (1024 bytes) to which the structure can be altered.

Define a Structure for CICS log streams in the System Logger Policy

If you plan to use CF-Structure log streams, the structure each log stream is associated with must be defined in the System Logger policy. In addition, it must also be defined in the CFRM policy. Figure 5-7 contains a sample job to define the LOG_JG structure in the System Logger policy.

 //DEFSTR JOB CLASS=A,MSGCLASS=A  //POLICY EXEC PGM=IXCMIAPU  //SYSPRINT DD SYSOUT=A  //SYSIN DD *  DATA TYPE(LOGR) REPORT(YES)  DEFINE STRUCTURE NAME(LOG_JG)        LOG_JG is the structure name  LOGSNUM(10)   *                      up to 10 logstreams can connect  AVGBUFSIZE(400)  *                   size of the starting 'average' buffer - monitor                                       the 'effective average buffer' using IXCMIAPU  MAXBUFSIZE(64000)  *                 determines the size of each log buffer - also                                       defines the CF element size                                       > 65276 - element size is 512                                       =<65276 - element size is 256 *  parms which affect performance

Figure 5-7: Defining a structure for CF-Structure log streams in the System Logger policy

The structure used for the log stream can affect performance. Key factors include the number and characteristics of the log streams which share the structure. We recommend limiting the number of log streams which can reside in the structure (LOGSNUM specified on the structure definition) to ten. All log streams in a structure should have similar characteristics. For example, TORs, AORs, and FORs typically have different log stream record size and volumes, so their DFHLOG and DFHSHUNT log streams should typically be in different structures.

SIZE

The size of a structure is specified in the CFRM policy. Each structure is divided into entries and elements. Each IXGWRITE uses one entry and one or more elements, depending on the length of data written.

The entries in the structure are shared between all connected log streams on an as-needed basis, while the elements are divided equally across the number of connected log streams in the structure. When another log stream connects to the structure, the elements are dynamically redistributed. Similarly, when a log stream disconnects from the structure, the elements previously allocated to that log stream are redistributed equally across all remaining log streams in the structure.

MAXBUFSIZE

The MAXBUFSIZE value you specify is returned to CICS when it connects to a log stream in that structure. CICS sets up its internal log buffers to be the same size as MAXBUFSIZE. For user journals, where the application does not use the wait option, it may be advantageous to specify a smaller size, as the buffer only gets written to the log stream when it fills. As a general rule, we recommend a MAXBUFSIZE of 64000.

MAXBUFSIZE in conjunction with AVGBUFSIZE is used to determine the entry-to-element ratio for that structure. When data is written to the CF, it's written in increments equal to the element size. A MAXBUFSIZE greater than 65276 gives an element size of 512; a MAXBUFSIZE equal to or less than 65276 results in an element size of 256. For example, the definition would result in a CF element size of 512 bytes:

      MAXBUFSIZE(65532)   AVGBUFSIZE(1100)

Three elements will be used for an average write (1100/512 and round up). The entry-to-element ratio is therefore 1:3. Beginning with OS/390 1.3, System Logger will dynamically adjust the entry-to-element ratio.

System Logger samples the structure use prior to adjusting the entry-to-element ratio. If the log streams using a given structure have very dissimilar characteristics, the sample may not reflect the data which will be written in the next interval. This would lead System Logger to adjust the ratio to a value which could result in a shortage of entries. For example, imagine an FOR which normally writes 1000 800 byte records per second, and an AOR which averages 500 100 byte records per second are sharing the same structure. One entry is required for each IXGWRITE. Further assume the structure is allocated to hold 2000 800 byte writes, with a MAXBUFSIZE of 64000. If System Logger finds the FOR had dominated the last interval (normally about 30 minutes) it will bias the ratio towards the needs of the FOR—in this case 1:4 (800/256 and round up).

Now, if during the next interval, the AOR dominates, writing 5000 100 byte records, it is possible to exhaust the entry pool without hitting HIGHOFFLOAD.

When the total number of entries in the structure become 90% full, all log streams in the structure are completely offloaded (that is, offload processing is initiated and completes when LOWOFFLOAD threshold is reached)

The effective average buffer size (the current average amount of data written per IXGWRITE call), is included in an IXCMIAPU report, as shown in Figure 5-8. Note this is the average across all the log streams in the structure—some log streams may have far smaller log blocks and others may have larger ones. Ideally all the log streams sharing a given structure would have similar average log block sizes.

 STRUCTURE NAME(LOG_JG_20M) LOGSNUM(10)           MAXBUFSIZE(64000) AVGBUFSIZE(400)           EFFECTIVE AVERAGE BUFFER SIZE(1024)           log stream NAME                     CONNECTION           --------------                     ----------           IYOT3.DFHSHUNT                     NO           IYOT2.DFHSHUNT                     NO           log streams CURRENTLY DEFINED TO THIS STRUCTURE(2)

Figure 5-8: Using IXCMIAPU report to get Effective Average Buffer Size

The current entry-to-element ratio can also be calculated from data available in the Coupling Facility Activity report produced from the SMF 74 records using the RMF Post Processor utility, ERBRMFPP. A sample Coupling Facility Activity Report is shown in Figure 8-2 on page 277.

Define the log stream in the LOGR policy

Figure 5-9 on page 149 shows sample JCL and IXCMIAPU statements to define a CF-Structure log stream. The parameters and values used are discussed in the following sections.

 //DEFSTR JOB CLASS=A,MSGCLASS=A //POLICY EXEC PGM=IXCMIAPU //SYSPRINT DD SYSOUT=A //SYSIN DD * DATA TYPE(LOGR) REPORT(YES) DEFINE LOGSTREAM NAME(IYOT1.DFHLOG)   Matches name in CICS Journal Model AUTODELETE(NO) *                      Always NO for DFHLOG and DFHSHUNT DIAG(YES)                             If an 804 (IXGRSNCODENOBLOCK) reason code will be                                       given, a dump of the logger is taken before                                       returning to CICS EHLQ(NO_EHLQ)                         Allows specification of 33 characters for a high                                       level qualifier - mutually exclusive with HLQ HIGHOFFLOAD(80) *                     Threshold, expressed as a percent of the                                       logstream space, when offloading is to take place HLQ(GRAUEL)                           HLQ for the offload and staging data set names LOGGERDUPLEX(COND) *                  Specifies whether Logger will continue to provide                                       its own log data duplexing, regardless of other                                       duplexing (such as system-managed duplexing). LOWOFFLOAD(40) *                      Value, expressed as a % of the space used by the                                       logstream, which defines the offload target LS_DATACLAS(LS10MEG) *                SMS data class used for DASD offload LS_SIZE(500) *                        The number of 4K control intervals to be                                       allocated for each offload data set MODEL(NO) OFFLOADRECALL(NO) *                   Always set to NO for CICS logstreams RETPD(0) *                            Retention period, zero for DFHLOG and DFHSHUNT STG_DUPLEX(YES) * DUPLEXMODE=(COND) *                   Log writes are to be duplexed to the Staging                                       Data set if the CF becomes volatile or failure                                       dependent (CF and z/OS in same CPC) STG_SIZE(9000)                        No. of 4K control intervals in Staging data set STRUCTNAME(LOG_JG)                    Structure which will contain the data * indicates parameters that affect performance

Figure 5-9: CF-Structure log stream definition

AUTODELETE and RETPD

AUTODELETE and RETPD can have a disastrous effect on DFHLOG and DFHSHUNT if specified other than AUTODELETE(NO) and RETPD(0). With AUTODELETE(YES) and RETPD>0, even though CICS attempts log tail management, all data will be off-loaded to the offload data sets and held for the number of days specified for RETPD. AUTODELETE(YES) allows the System Logger (rather than CICS) to decide when to delete the data. When a new offload data set is allocated and AUTODELETE(YES) is specified with RETPD(0), the System Logger will delete the old offload data set (and the data). If CICS needs the data for backout, the result will be an 804 return code and CICS will terminate with a DFHLG0772.

For the forward recovery log stream and log 0f logs, the recommended values are AUTODELETE(NO) and RETPD(xx) where is xx is the number of days the data needs to be kept before allowing any deletion. This value is based on installation business needs. If you are planning to keep this data for a long period, be prepared to manage offload data sets.

DIAG(YES)

DIAG(YES) should always be specified for DFHLOG and DFHSHUNT. In a case where the System Logger is unable to locate data requested by CICS, a response of return code 8 with reason code IXGRSNCODENOBLOCK (804) is given. This means backout data is not available and CICS treats it as a fatal error, terminating the region with a DFHLG0772. In many cases, information from the System Logger address space is needed to resolve the problem. When DIAG(YES) is specified in the log stream definition, a dump of the System Logger address space is provided (by the System Logger) in addition to the DFHLG0772 dump provided by CICS. There is no overhead associated with this parameter unless a dump is requested. This error is normally seen when CICS issues an IXGBRWSE for backout data or during activity keypoint processing when CICS issues the IXGDELET command to trim the tail of the log. It can also be returned during region startup when an IXGCONN (connect) is issued to connect to the log stream.

HIGHOFFLOAD

The HIGHOFFLOAD parameter, in conjunction with the size of the log stream structure, has a major impact on the amount of virtual storage used by the System Logger. For a CF-Structure log stream, if staging data sets are not being used, all the data in the CF portion of the log stream is duplexed to the System Logger-owned dataspace. If staging data sets are used with a CF-Structure log stream, the data is written to the staging data set rather than the dataspace.

If the HIGHOFFLOAD value is too high, the log stream may fill before offload processing can free sufficient space in the log stream. CICS is not aware the offload process is taking place, and will continue writing to the log stream. This can lead to an entry or structure full condition, which causes log writes to be suspended for 3 seconds.

We recommend setting HIGHOFFLOAD to 80 - 85% for all CICS log streams.

LOWOFFLOAD

The LOWOFFLOAD value defines the amount of data which may be retained in the log stream interim storage following an offload process. In the CICS environment, the LOWOFFLOAD value should be high enough to retain the data required for backout but low enough to keep the number of offloads to a reasonable number.

LOWOFFLOAD should be set between 40 and 60% for DFHLOG and DFHSHUNT. It should be set to 0 for user journals, forward recovery logs, and auto journals.

In tests setting LOWOFFLOAD closer to HIGHOFFLOAD (for example, 75 with a HIGHOFFLOAD of 80) some improvement was noted in transaction throughput at a cost of an increase in the storage frames and CPU in the System Logger address space. The storage frames used will normally increase as the size of the structure increases. Each region should be evaluated based on its workload.

It should also be noted setting the LOWOFFLOAD to a higher value may mask poorly behaving transactions. It may appear the log stream is working properly (for example little or no data is offloaded) when in fact large amounts of storage are being consumed to retain records which would be offloaded with a lower setting. Remember the goal is to contain the data needed for recovery using a minimum of interim storage, with no data being moved to the offload data sets.

LS_SIZE

LS_SIZE defines the allocation size, in 4 KB blocks, for the offload data sets. It should be specified large enough to contain several offloads, possibly up to a day's worth. DFHLOG and DFHSHUNT should only offload a minimal amount of data, if any. For user journals, all data is offloaded.

If you have log streams which offload large volumes of data, find a balance between a size small enough so the system can always find free space, while at the same time, minimizing the number of times new offload data sets need to be allocated.

It's very important to specify LS_SIZE large enough to limit the number of times an additional data set is allocated, to reduce the exposure to delays during the allocation process. The size to be specified is based on the amount of data written during the prime processing window of the day. The amount of data written can be determined using the SMF Type 88 records produced for the log stream by the System Logger.

If the extent size of the SMS data class specified on the LS_DATACLAS (or the value specified in LS_SIZE) is too small, frequent DASD shifts (allocation of a new offload data set) can occur. Frequent DASD shifts have a negative effect on performance and expose the system to a depletion of DASD space. The number of offload data sets is limited by the DSEXTENT value specified when you format the LOGR Couple Data Set. The DSEXTENT value defines the number of System Logger directory entries. Each directory entry can point to a maximum of 168 offload data sets. Prior to OS/390 1.3, the number of extents was limited to one; with OS/390 1.3 and later, the number is limited only by the amount of DASD available.

Attention:

If LS_SIZE is not specified in the log stream definition, and an extent size is not specified in the data class pointed to by LS_DATACLAS, the value is taken from the ALLOCxx Parmlib member. The default value in ALLOCxx is 2 tracks. Refer to the z/OS MVS Initialization and Tuning Reference, SA22-7592 for more information about this member.

LS_DATACLAS

It is very important to remember log stream staging and offload data sets are single extent VSAM linear data sets, and the SHAREOPTIONS must be specified as "3,3". If the SHAREOPTIONS are anything other than "3,3" there is a risk the System Logger will be unable to read offloaded data and post CICS with return code 8, reason code 804 (IxgRsnCodeNoBlock). This will cause CICS to abend with a DFHLG0772. Therefore, you should make sure the SMS Data Class specified on the LS_DATACLAS parameter is set to use SHAREOPTIONS 3,3.

The following messages are additional symptoms of the incorrect SHAREOPTIONS:

DFHLG0772 MVS System Logger codes: X'00000004', X'00000403' or
DFHLG0772 MVS System Logger codes: X'00000008', X'0000084A'.

With either of the above messages, an associated IEC161I message will be produced.

IEC161I 052(009)-084 error opening a SHAREOPTIONS 1,x data set or
IEC161I 052(015)-084 error opening a SHAREOPTIONS 2,x data set.

In all cases, the log stream will be considered broken and CICS will terminate.

Following application of OW54863, the System Logger will check the SHAREOPTIONS of the staging and offload data sets at connect time. If the SHAREOPTIONS are not set to (3,3), message IXG267I will be issued. If the System Logger is unable to open the data set, message IXG288I will be issued.

Either an IDCAMS LISTCAT or ISMF display may be used to verify the SHAREOPTIONS are set to 3,3.

LOGGERDUPLEX

LOGGERDUPLEX specifies whether System Logger will continue to perform its own log data duplexing, or conditionally not provide its own duplexing based on an alternative duplexing configuration. An "alternate duplexing configuration" means System-Managed Duplexing is being used for the associated structure.

LOGGERDUPLEX(COND) indicates the System Logger will provide its own duplexing of the log data unless the log stream is being duplexed with System-Managed Duplexing and the duplexing is providing the required level of failure independence.

For a more detailed discussion, refer to "Duplexing log data for CF-Structure based log streams" on page 42.

STG_SIZE

For a CF-Structure log stream, STG_SIZE defines the size of the staging data set to be allocated if STG_DUPLEX and DUPLEX_MODE(YES) are specified. If STG_DUPLEX(UNCOND) is specified, the data in the CF-Structure log stream will always be duplexed to the staging data set. If STG_DUPLEX(COND) is specified, the data in the CF-Structure log stream is duplexed to the staging data set only if the CF becomes volatile or becomes failure dependent.

The size of the staging data set (STG_SIZE) must be at least large enough to hold as much data as the log stream storage in the CF.

The rule of thumb is STG_SIZE must be large enough to hold the data written during an activity keypoint interval, plus the length of time of the longest running unit of work.

If you are migrating to CICS TS and starting to use System Logger with CICS for the first time, DFHLSCU should be run against the CICS/ESA 4.1 system log and the output used as a starting point for STG_SIZE and the size used for the CF structure definition.

Space within the staging data set is allocated to log blocks in 4096 byte increments, regardless of the buffer size. So, for example, if the average log block size is 2000 bytes, the effective space in the staging data set is reduced by about 50%. Bear this in mind when setting the size of the staging data set.

Attention:

When staging data sets are used with a CF-Structure log stream, STG_SIZE must be specified large enough to hold at least as much data as the CF-Structure log stream.

The structure storage is divided equally among the active log streams. If the number of log streams connected to the structure will vary, the STG_SIZE value should be chosen based on the least number of log streams which will normally be connected.

Offload processing is triggered based on the smaller capacity of either the structure log stream storage or the staging data set.

STG_DUPLEX

STG_DUPLEX(YES) with DUPLEXMODE(COND) means if the CF becomes volatile, or resides in the same failure domain as the System Logger, the log stream data will be duplexed to the staging data set; otherwise it is duplexed to buffers in the System Logger dataspace. A CF is in the same failure domain when the CF LPAR and the z/OS LPAR reside in the same physical hardware box, or if the CF is volatile regardless of where it is. Duplexing to the staging data set means the cost of an I/O will be incurred for each write. Therefore we strongly recommend you provide a configuration where the structure containing the log stream for a CICS region is not in the same failure domain as the system where CICS is executing. To determine if System Logger is using staging data sets for a log stream, use the D LOGGER,LOGSTREAM,LSN= command as shown in Figure 5-10 on page 153. In the figure, DUPLEXING: LOCAL BUFFERS indicates that the duplex copy of log stream IYOT1.CICS22.DFHLOG resides in System Logger's dataspace.

 IXG601I   18.55.09  LOGGER DISPLAY 779 INVENTORY INFORMATION BY LOGSTREAM LOGSTREAM                  STRUCTURE         #CONN  STATUS ---------                  ---------         ------ ------ IYOT1.CICS22.DFHLOG        LOG_JG2_5M        000001 IN USE   SYSNAME: SYSD     DUPLEXING: LOCAL BUFFERS

Figure 5-10: Displaying if staging data sets are in use

OFFLOADRECALL

OFFLOADRECALL should be set to NO for CICS log streams. This option was added via APAR OW48404. This parameter applies in the situation where the System Logger is to perform an offload of data and the target data set has been migrated by DFSMShsm. Specifying NO indicates to the System Logger a new offload data set is to be allocated rather than attempting a recall. This prevents the System Logger from waiting for the recall and avoids the risk of CICS being unable to write to a log stream which has filled waiting for the offload to proceed.

DASD-only log stream

Figure 5-11 shows an example of a DASD-only log stream definition. The DASDONLY and MAXBUFSIZE parameters are applicable only for a DASD-only log stream (MAXBUFSIZE is specified at the structure level for CF-Structure log streams).

 //DEFSTR JOB CLASS=A,MSGCLASS=A //POLICY EXEC PGM=IXCMIAPU //SYSPRINT DD SYSOUT=A //SYSIN DD * DATA TYPE(LOGR) REPORT(YES) DEFINE LOGSTREAM NAME(IYOT2.DFHLOG)   Matches name defined in Journal Model AUTODELETE(NO) *                      Always NO for DFHLOG and DFHSHUNT DASDONLY(YES)                         CF structures will not be used DIAG(YES)                             If an 804 (IXGRSNCODENOBLOCK) reason code will be                                       given, a dump of the logger is taken before                                       returning to CICS EHLQ(NO_EHLQ)                         Allows specification of 33 characters for a high                                       level qualifier - mutually exclusive with HLQ HIGHOFFLOAD(80) *                     Threshold, expressed as a percent of the                                       logstream space, when offloading is to take place HLQ(GRAUEL)                           HLQ of the offload data set name LOWOFFLOAD(40) *                      Value, expressed as a % of the space used by the                                       logstream, which defines the offload target LS_DATACLAS(LS10MEG) *                SMS class used for DASD offload LS_SIZE(4500) *                       The number of 4K control intervals to be                                       allocated for each offload data set MAXBUFSIZE(65532) *                   Max buffer size of blocks written to the log MODEL(NO) OFFLOADRECALL(NO) *                   Always set to NO for CICS logstreams RETPD(0) *                            Retention period, zero for DFHLOG and DFHSHUNT STG_SIZE(9000) *                      The number of 4K control intervals in the Staging                                       data set * parms which affect performance

Figure 5-11: Defining a DASD-only log stream

The following discussion presents the parameters which affect DASD-only log stream performance in a CICS Transaction Server environment.

AUTODELETE and RETPD

AUTODELETE and RETPD can have a disastrous effect on the DFHLOG and DFHSHUNT if specified other than AUTODELETE(NO) and RETPD(0). With AUTODELETE(YES) and RETPD>0, even though CICS will attempt log tail management, all data will be offloaded to the offload data sets and held for the number of days specified for RETPD.

AUTODELETE(YES) lets the System Logger (rather than CICS) decide when to delete the data. When a new offload data set is allocated and AUTODELETE(YES) is specified, the System Logger will delete the data in the old offload data set. If CICS needs the data for backout, the result will be an 804 return code and CICS will terminate with a DFHLG0772.

For the forward recovery log stream and log of logs, the recommended values are AUTODELETE(NO) and RETPD(xx) where is xx is the number of days the data needs to be kept before allowing any deletion. This value is mainly based on the installation business needs. If you are planning to keep this data for a long period, be prepare to manage offload data sets.

DIAG

DIAG(YES) should always be specified for DFHLOG and DFHSHUNT. In a case where the System Logger is unable to locate data requested by CICS, a return code 8 with reason code IXGRSNCODENOBLOCK (804) is presented to CICS. This means backout data is not available and CICS treats it as a fatal error, terminating the region with a DFHLG0772. In many cases, information from the System Logger address space is needed to resolve the problem. When DIAG(YES) is specified in the log stream definition, a dump of the System Logger address is provided (by the System Logger) in addition to the DFHLG0772 dump provided by CICS. There is no overhead associated with this parm unless a dump is requested. This error is normally seen when CICS issues an IXGBRWSE for backout data or during activity keypoint processing when CICS issues the IXGDELET command to trim the tail of the log. It can also be returned during region startup when an IXGCONN (connect) is issued to connect to the log stream.

HIGHOFFLOAD

The HIGHOFFLOAD parameter, in conjunction with the size of the log stream, has a major effect on the amount of storage used by the System Logger. Before data is written to the staging data set, it is written to the System Logger dataspace.

If the HIGHOFFLOAD value is too high, there can be insufficient space to accommodate data written to the log stream during offload processing. This can lead to a staging data set full condition which causes log writes to be suspended. Also, for DASD-only log streams, space in the staging data set is not freed until the offload completes. Therefore, it is very important to factor in the peak times when calculating the staging data set size and HIGHOFFLOAD values.

We recommend setting HIGHOFFLOAD to 80–85% for all CICS log streams.

LOWOFFLOAD

LOWOFFLOAD should be set between 40 and 60% for DFHLOG and DFHSHUNT, and to 0 for user journals, forward recovery logs, and auto journals.

In tests setting LOWOFFLOAD closer to HIGHOFFLOAD (for example, 75 with a HIGHOFFLOAD of 80) some improvement was noted in transaction throughput at a cost of an increase in the storage frames and CPU in the System Logger address space. The storage frames used will normally increase as the size of the staging data set increases. Each region should be evaluated based on its workload.

It should also be noted setting the LOWOFFLOAD to a higher value may mask poorly behaving transactions. It may appear the logstream is working properly (for example little or no data is offloaded) when in fact large amounts of storage are being consumed to retain records which would be offloaded with a lower setting. Remember the goal is to contain the data needed for recovery using a minimum of interim storage, with no data being moved to the offload data sets.

LS_SIZE

LS_SIZE defines the allocation size for the offload data sets. It should be specified large enough to contain several offloads, possibly as much as a day's worth. DFHLOG and DFHSHUNT should only offload a minimal amount of data. For user journals, all data is offloaded.

If you have log streams which offload large volumes of data, find a balance between a size small enough so the system can always find space, while at the same time, minimizing the number of times new offload data sets need to be allocated.

If the extent size of the LS_DATACLAS (or the value specified in LS_SIZE) is too small, frequent DASD shifts (allocation of a new offload data set) will occur. Frequent DASD shifts have a negative impact on performance and expose the system to a depletion of DASD space. The number of offload data sets is limited by the DSEXTENT value specified in the LOGR Couple Data Set. The DSEXTENT value defines the number of System Logger directory entries. Each directory entry can point to a maximum of 168 offload data sets. Prior to OS/390 1.3, the number of extents was limited to 1; with OS/390 1.3 and above, the number is limited only by the amount of DASD available.

Attention:

If LS_SIZE is not specified in the log stream definition, and a size is not specified in the data class pointed to by LS_DATACLAS, the value is taken from the ALLOCxx Parmlib member. The default value in ALLOCxx is 2 tracks. Refer to the z/OS MVS Initialization and Tuning Reference, SA22-7592.

LS_DATACLAS

It is very important to remember log stream staging and offload data sets are single extent VSAM linear data sets, and the SHAREOPTIONS must be specified as "3,3". If the SHAREOPTIONS are anything other than "3,3" there is a risk the System Logger will be unable to read offloaded data and post CICS with return code 8, reason code 804 (IxgRsnCodeNoBlock). This will cause CICS to abend with a DFHLG0772. Therefore, you should ensure the SMS Data Class specified on the LS_DATACLAS parameter is set to use SHAREOPTIONS 3,3.

The following messages are additional symptoms of the incorrect SHAREOPTIONS:

DFHLG0772 MVS System Logger codes: X'00000004', X'00000403' or
DFHLG0772 MVS System Logger codes: X'00000008', X'0000084A'.

With either of the above messages, an associated IEC161I message will be produced.

IEC161I 052(009)-084 error opening a SHAREOPTIONS 1,x data set or
IEC161I 052(015)-084 error opening a SHAREOPTIONS 2,x data set.

In all cases, the log stream will be considered broken and CICS will terminate.

Following application of OW54863, the System Logger will check the SHAREOPTIONS of the staging and offload data sets. If the SHAREOPTIONS are not set to (3,3), message IXG267I will be issued. If the System Logger is unable to open the data set, message IXG288I will be issued.

Either an IDCAMS LISTCAT or ISMF display may be used to verify the SHAREOPTIONS are set to 3,3.

STG_SIZE

STG_SIZE is specified based on the amount of data to be contained in the log stream. The rule of thumb is it must be large enough to hold the data written during a peak activity keypoint interval, plus the length of time of the longest running unit of work, plus a buffer to allow for higher than normal transaction rates.

Attention:

If STG_SIZE is not specified in the log stream definition and a size is not specified in the SMS data class referred to by STG_DATACLAS, the value is taken from the ALLOCxx parmlib member. The default value in ALLOCxx is 2 tracks, which would result in very frequent offloads for that log stream. Refer to the z/OS MVS Initialization and Tuning Reference, SA22-7592.

MAXBUFSIZE

MAXBUFSIZE may be specified for a DASD-only log stream, it defines the largest block which can be written to the log stream. The default value is 65532 and should be used in a CICS environment.

MAXBUFSIZE is returned to CICS at connect time and CICS in turn uses this value as the size of its internal log buffers. For user journals, where the application does not use the wait option, it may be advantageous to specify a smaller size, as the buffer is only written to the log stream when it fills.

STG_DUPLEX

STG_DUPLEX(YES) with DUPLEXMODE(COND) are not applicable to DASD-only log streams.

OFFLOADRECALL

OFFLOADRECALL should be set to NO for CICS log streams. This option was added via z/OS APAR OW48404. Specifying NO indicates to System Logger if a required offload data set has been migrated by DFSMShsm, then a new offload data set is to be allocated. This prevents System Logger from waiting for the recall, which could result in the staging data set filling before the offload completes.

Attention:

With the exception of DFHLOG and DFHSHUNT, DASD-only log streams can be shared within the z/OS image. User journals and forward recovery logs fall into this category. Please note, this could have an impact on IOSQ time to the related staging data sets.

Another important point, if you have a DASD-only user journal shared between multiple CICS regions in the same image, then you must ensure all the CICS regions sharing the journal always run on the same z/OS image. If one CICS is moved to another image, only the CICS regions on the first z/OS image to connect to the log stream will be successful.

MVS Model log streams - DFHLOG

Figure 5-12 illustrates definitions for a CF-Structure log stream model for DFHLOG. If the log stream is to be a DASD-only log stream, the CF-specific parms would be replaced by those which pertain to DASD-only.

  //DEFMODEL JOB CLASS=A,MSGCLASS=A  //MODDEF EXEC PGM=IXCMIAPU  //SYSPRINT DD SYSOUT=*  //SYSIN DD *   DATA TYPE(LOGR) REPORT(YES)   DEFINE LOGSTREAM NAME(sysname.DFHLOG.MODEL)  sysname - name of the z/OS image   STRUCTNAME(LOG_DFHLOG_001)                   Structure which will contain the data   DIAG(YES)                                    If an 804 (IXGRSNCODENOBLOCK) reason code                                                will be given, a dump of the logger is                                                taken before returning to CICS   HIGHOFFLOAD(80)                              Threshold, expressed as a % of logstream                                                space, when offloading is to take place   LOWOFFLOAD(40)                               Value, expressed as a % of the space used                                                by the logstream, of the offload target LS_DATACLAS(LS10MEG)                           SMS dataclass used for offload data sets   OFFLOADRECALL(NO)                            Always set to NO for CICS logstreams STG_DUPLEX(YES) DUPLEXMODE=(COND)              Log writes to be duplexed to the CF and                                                Staging data sets if CF becomes volatile STG_SIZE(9000)                                 Number of 4K CIs in the Staging data set MODEL(YES)                                     A model only, connection is not permitted LS_SIZE(100000)                                The number of 4K blocks for offload                                                data sets allocation MSG IXG256I is                                                issued if the value is less than 64K

Figure 5-12: Defining a MODEL log stream for DFHLOG

The MVS model associates a log stream with the desired characteristics. Model usage makes it easier to dynamically define CICS log streams. The disadvantage is all log streams using the model have the same characteristics.

MVS Model log streams - User journals

Figure 5-13 illustrates definitions for an MVS model for a user journal log stream.

 //DEFMODEL JOB CLASS=A,MSGCLASS=A   //MODDEF  EXEC  PGM=IXCMIAPU   //SYSPRINT DD SYSOUT=*   //SYSIN DD *    DATA TYPE(LOGR) REPORT(YES)    DEFINE LOGSTREAM NAME(IYOY1.IYO1.MODEL)    DASDONLY(YES)    AUTODELETE(Y)                             Logger will delete the data when the                                              retention period (RETPD) has elapsed.    RETPD(15)                                 Retain the data for 15 days    DIAG(YES)                                 If an 804 (IXGRSNCODENOBLOCK) reason code                                              will be given, a dump of the logger is                                              taken before returning to CICS    HIGHOFFLOAD(85)                           Threshold, expressed as a % of logstream                                              space, when offloading is to take place    LOWOFFLOAD(00)                            Value, expressed as a % of the space used                                              by the logstream, of the offload target    LS_DATACLAS(LS10MEG)                      SMS dataclass used for offload data sets    OFFLOADRECALL(NO)                         Always set to NO for CICS logstreams    MODEL(YES)                                A model only, connection is not permitted    STG_SIZE(5000)                            Number of 4K CIs in the staging data set

Figure 5-13: Defining a MODEL log stream for a user journal

Models for user journals are named based on the first two qualifiers in the log stream name. For example, the model in Figure 5-13 would be used for user journals such as IYOT1.IYO1.DFHJ03.

The example shows a DASD-only log stream; if a Coupling Facility log stream is required, replace the DASD-only parameters with those for a CF-Structure log stream.

< Day Day Up >