The Dataset Contention Reporting System

Introduction

DCS reporting facilities include:

• Facilities in JAL to request contention data recording.
• Generation of data and recording in the CMF file.
• A snap-shot facility to capture the data recorded in the CMF file. The output file created by the snap-shot utility is used as input to the reporting program.
• Selective reporting by type of job, duration of contention, data set name, and other criteria.
• A reporting program that generates two reports that allow you to quickly correlate “causes and effects”. The reports are:

–The Job Analysis report.

–The Data set Analysis report.

An example of each one and an explanation of their contents is shown below.

The Job Analysis Report

Its purpose is to show:

• The jobs that were affected.
• The total duration of the contention situation.
• The data sets that were involved.
• How much time each data set contributed to the problem.

A sample is shown below.

Let’s take a look at job PAY01300:

• Since the report is organized alphabetically by job name, we can locate the entry quickly by looking at the left side of the report.
• The second column shows the JES2 job number, in this case 3221.
• The third column shows the submission date.
• The next column shows the submission time.
• The RECORD ID column shows the optional identification field. The value in this field is assigned at JAL time and can be used for reporting selection purposes. In this case the job is identified as ‘PAYROLL’.

The ‘OCCURRENCE FROM’ shows you the time that the job ran into data set contention. For this job there are two entries, indicating that contention occurred twice before the job executed

–The first delay occurred at 12:55:42. The FOR column tells us that it lasted 26 minutes 22 seconds.

–The second delay occurred at 13:48:17. The FOR column tells us that it lasted 8 minutes 22 seconds.

• The JESID column shows the 4-byte JES2 system identification.
• The F column is a flag that indicates how the job contention terminated. The possible values are:

• The data set column shows one or more data sets per contention occurrence. In this example, two data sets were involved in the first occurrence:

–PAY900.DETAIL.BRANCH

–PAY900.INPUT.EDIT

–The data set PAY900.DETAIL.BRANCH became available after 6 minutes and 13 seconds.

–The data set PAY900.INPUT.EDIT took 26 minutes and 20 seconds to become available, so it was this data set that caused the long delay.

• In the second delay, only one data set was not available:

–PAY900.INPUT EDIT

–It became available after 8 minutes 22 seconds.

• The S column shows the data set service level requested:

–S for STANDBY.

–C for CLAIM.

–Q for CONTEND.

–R for REPOSSESS.

• The C column indicates how the reporting program detected that a data set became available:

–A P indicates that a data set “popped-up” record was encountered, this represents the normal case.

–A J indicates that the data set “popped-up” record is missing. In that situation the reporting program considers the data set to be available when the job contention situation ended. Occasionally, you might see a J in this column. If J becomes prevalent, it is an indication that you might not be recording from all systems in your DCS complex.

• Note: You might see an asterisk next to a field under the following conditions:

–The contention occurrence time is earlier than the job’s reader-on time.

–The contention occurrence time is earlier than the end of the previous contention occurrence for the job.

–The interval time associated with one of the data sets is longer than the contention interval for the job.

This situation can occur in multisystem environments as a result of the differences in clock values.

The Dataset Analysis Report

The purpose of this report is to show:

• The data sets that were involved in contention situations.
• The jobs that were delayed.
• The “holders” of the data set.

This report complements the Job Analysis report. We can show this by continuing with the example used to describe the Job Analysis report. From the previous report, we might be interested in determining the holders of the following two data sets:

• PAY900.DETAIL.BRANCH
• PAY900.INPUT.EDIT

Since the report is organized as “mini-reports” per data set, in alphabetic order, we can quickly locate the information:

• The first column under the DATASET NAME represents the JES2 node name.
• The INTERVAL DATE/TIME shows the initial date and time that DCS detected this data set causing contention.
• The INTERVAL FOR shows the total duration of the contention. Several jobs could have been affected during this period.
• The next subsection of the report, JOB OCCURRENCES, shows the job or jobs that were affected for the interval.
• The job name, JES2 number, submission date and time, the JES2 identification, and when the contention occurred for this job are all shown. This allows you to relate the entry to the Job Analysis report.
• Three columns containing flags are included here.

–The F column is the same as the F column in the Job Analysis report. It indicates how the job contention terminated. The possible values are documented with the Job Analysis report.

–The S column is the same as the S column in the Job Analysis report. It shows the data set service level requested by this job:

• S for STANDBY.
• C for CLAIM.
• Q for CONTEND.
• R for REPOSSESS.

–The C column is the same as in the Job Analysis report. It indicates how the reporting program detected that a data set became available. Normally a data set “popped-up” record is encountered, this is indicated with a P. In cases where the data set “popped-up” record is missing, the data set is considered to be available when the job contention situation ended. This is indicated with a J. Occasionally, you might see a J in this column. If J becomes prevalent, it is an indication that you might not be recording from all systems in your DCS complex.

• The next subsection of the report, HOLDERS, shows “who” was holding the data set. The name of the holder is shown. It could be a batch job, a started task, or a TSO user. This is indicated in the T column:

–J for batch job.

–T for TSO user.

–S for started task.

• The next column, JESID, shows the id of the system where the holder is executing.
• The H column shows the data set status:

–S for shared.

–E for exclusive.

• The AT column shows the first time that the holder was detected.
• Note: You might see an asterisk next to a field under the following conditions:

–The contention occurrence time is earlier than the job’s reader-on time.

–Where the HOLDER time reported under the heading “AT” is not within the boundaries of the data set contention.

These situations can occur in multisystem environments as a result of the differences in clock values.

Implementation Summary

The steps to implement the data collection and reporting system are as follows:

• Activate the CMF file. DCS uses this file for the data collection.
• Update the JAL to request recording for the particular job, or jobs, for which you want contention data to be collected. This is done with the DCS RECORD statement. If you want data collection for all the jobs processed by ThruPut Manager, code an unconditional DCS RECORD statement.
• Decide what kind of reporting cycle you want.
• Put in place the procedures to run the snap-shot utility at the appropriate intervals to reflect the cycle you have chosen. For information, refer to the heading “The Snap-Shot Utility” later in this topic.
• Decide the selection criteria you want for the reporting system. For information, refer to the heading “The Report Selection Options” later in this topic.
• If the reports are to generated at regular intervals, put in place the procedures to ensure that the reporting program is run.

Dependencies

The CMF File

This file must be active in all the systems participating in the DCS complex.

TMSS Initialization Statements

A FILE CMF initialization statement is required.

JAL

When contention occurs, DCS determines if recording was requested in JAL with the DCS RECORD action statement. If no request was made contention records are not generated.

The CMF File Considerations

The mechanism to record contention data is similar to SMF recording. The records are written to a file called CMF. A wrap-around technique is used to ensure that the traditional problems resulting from out-of-space conditions are eliminated. The CMF file is shared by all the systems participating in the DCS complex.

A diagram showing the relationships among the systems running DCS, the CMF file, and the reporting system is shown:

The space needed for this file depends:

• On your reporting cycle (daily, weekly, on demand, or any other interval you may choose).
• The frequency of data set conflicts.

One cylinder of a 3380/3390 device accommodates the records generated by 700 contention situations.

Recording

Recording is done by the Contention Management Facility (CMF). This facility records contention-related data designed to be input to the contention management reporting program.

CMF has a number of similarities with SMF. Variable length records are generated to collect all the necessary information. It is unlikely that you will have to be concerned with these records, but for your information here is a list of the different record types:

• Type 1—Job Contention Record: This is generated whenever a job encounters data set contention during initiation.
• Type 2—Job Release Record: This is generated whenever a job is released from DCS HOLD.
• Type 3—Dataset Popup Record: This is generated whenever a data set becomes available.
• Type 4—Dataset Holder Record: This is generated whenever a holder of a contention data set is observed for the first time.
• Type 5—Job Status Change Record: This is generated whenever a data set service is modified.

Unlike SMF, the CMF facility records all its data in a single shared file, so merging records from different systems is not required. DCS ensures that the integrity of the CMF file is maintained.

The Snap-Shot Utility

The DCS Snap-Shot utility, DTMDCSUn (where n represents the current ThruPut Manager release number) creates a copy of selected data in your CMF file to use as input to the reporting program. Sample JCL is shown here:

//jobname JOB ...
//stepname EXEC PGM=DTMDCSUn,PARM=’start-date start-time end-date end-time’
//SYSPRINT DD SYSOUT=A
//SYSUT1 DD DSN=the-CMF-file,DISP=SHR
//SYSUT2 DD DSN=the-output-file-name,DISP=(,CATLG),
// UNIT=unitname,SPACE=(CYL,(n)),
// DCB=(RECFM=VB,BLKSIZE=4096) start-dateis the Julian date at which to begin copying the file, in the form yyyyddd or -nnn indicating the relative number of days. See the discussion below.

start-timeis the time at which to begin copying the file, in the form hh: or hh:mm or hh:mm:ss.

end-dateis the Julian date at which to stop copying the file, in the form yyyyddd or -nnn indicating the relative number of days. See the discussion below.

end-timeis the time at which to stop copying the file, in the form hh: or hh:mm or hh:mm:ss.

the-CMF-fileis the data set name for the CMF file.

the-output-file-nameis the name of the file to be created for input to the reporting program.

nIs the size, in cylinders, of the output file that will contain the selected data.

All parameters for specifying start and stop dates and times are optional:

• If no parameters are specified, the entire CMF file is copied.
• If the end date and time are omitted, the current date and time are assumed.
• If either start or end time is omitted, the entire day’s data is copied.

Formats for Start and End Dates

The start and end date parameters can be specified in two ways:

• As a Julian date, expressed as yyyyddd.
• As a count of days relative to the current date, indicated by specifying a 1-3 digit number prefixed with a minus sign (-). Using this method, the numeral 0 (zero) is a special case specifying the current date. It does not require the leading minus sign.

The specification for both start and end dates must use the same format.

Format for Start and End Times

Both start and end times are optional. If present, you can specify times as one of:

• hh:, where hh is a 1-2 digit number from the range 0-23 representing the hour using a 24-hour clock. The trailing colon (:) is required to distinguish a time from the special relative date 0, as described above.
• hh:mm, where hh is as described above, and mm is a two digit number from the range 00 to 59, indicating the number of minutes after the hour.
• hh:mm:ss, where hh:mm is as described above, and ss is a two digit number from the range 00-59, indicating the number of seconds after the minute.

Examples

Consider these examples:

• PARM=”0” selects today.
• PARM=”-1 -1” selects yesterday.
• PARM=”-1” selects yesterday and today.
• PARM=”96250” selects from September 6, 1996, up to today.
• PARM=”96250 15: 96257 17:30” selects from 3 PM September 6, 1996, up to 5:30 PM September 13, 1996.

Notes

• DTMDCSUn can be run as a separate job prior to running the reporting program, or as the first step of the reporting job.
• Please note that this utility does not remove data from the CMF file. Because of the wrap-around technique used to do the recording, this is not necessary. The data is simply copied to the output file.
• At the end of the run, the utility prints a summary of the records copied to the output file.

The Reporting Program Reporting Program

The DCS Reporting Program is DTMDCSRn (where n represents the current ThruPut Manager release number). It produces two reports:

• The Job Analysis Report.
• The Dataset Analysis Report.

This section of the topic explains the input data requirements and considerations. It also documents the selection capabilities available with this program.

The Input File

The input data file for the reporting program is created with the Snap-Shot utility that was discussed in the previous section. The file must be sorted before it can be processed by the reporting program. Before a sample of the job stream is shown, some considerations are discussed.

Depending on how you collect the data, it is possible to end up with duplicate records in your input. The reporting program recognizes the situation and discards any record for which an identical copy has already been read. That is, duplicate input records do not cause problems for the reporting program.

Duplication of records can occur when you use the following techniques:

• You choose to do multiple runs of the Snap-shot utility, each run creating an independent output file. You then concatenate all these files as input to the sort.
• You choose to do multiple runs of the Snap-shot utility to the same output file with a disposition of MOD. This file is then used as the input to the sort program.

Both techniques are valid, and the reporting program takes care of any duplicate records.

The Reporting Program JCL

An example of the JCL needed to run the reporting program is as follows:

The Report Selection Options

Report Selection

The first level of selection is the Report Selection. You can select which one of the two reports you want the reporting program to print by including or excluding its corresponding DD statement in the JCL:

• If a //DCSRJRPT DD is included, the Job Analysis Report is produced.
• If a //DCSRDRPT DD is included, the Dataset Analysis Report is produced.

You can include both in a single run.

Job Analysis Report Selection Options

The following selection options are available with this report:

• The number of lines per page.
• Minimum contention duration. For example, you might not want to clutter your report with any contention occurrence that did not last at least 10 minutes.
• The beginning date for data to be considered.
• The beginning time for data to be considered.
• The end date for data to be considered.
• The end time for data to be considered.
• The job name.
• The job identification pattern. An identification character string can be assigned to each job in JAL to be used here for selection. This is discussed later.

These selection criteria are specified as SYSIN input records, one selection parameter per record. Their syntax and effects are now discussed in detail.

JOB_LINES=nSpecifies the number of lines per page.

n must be greater than 10. The default value is 60.

If you do not want page breaks specify 0.

JOB_NAME_PATTERN=patternSpecifies a job name pattern to be used in the selection of jobs to be included in the report.

JOB_RECORD_PATTERN=patternThe key to the reporting selection capabilities is provided by the job record id facility. At JAL time, you can assign a record id to each individual job when you request DCS RECORDING. The record id is an arbitrary character string containing up to 16 characters of your choosing. The character string substitution capabilities of JAL are available to you. This allows you to insert Job Descriptors, such as account, or any hard coded string.

For example, you might want to insert string identifying categories such as ‘PRODUCTION’ or ‘PAYROLL’ and/or the type of service requested. At report selection time you could code:

JOB_RECORD_PATTERN=PAYROLL*
 or
JOB_RECORD_PATTERN=*CLAIM*Only the jobs that contain a matching string are included in the report. This represents the highest selection level. That is, before any other criteria are applied, the job must satisfy the record id pattern specified with this parameter.

JOB_MIN_TIME=hh:mm:ssSpecifies the minimum contention duration for a job to be included in the report. This represents the sum of the values in the OCCURRENCE/FOR column in your report.

hh:mm:ss represents the total time interval below which you do not want the job included in your report. The default value is 1 minute.

When specifying the time, you can omit lower-order components that are not required.

JOB_DATE_LO=yymmmddThis represents the earliest date for data to qualify. Any data that was generated earlier than this date is not reported.

You can omit the year, month, or day component. This results in a wildcard effect. For example, if you code 94FEB, any record created in 1994 during the month of February is included in the report. If only two digits are included, they are assumed to be the day.

JOB_DATE_LO=-nnnThis is an alternate form for specifying the earliest date for data to qualify. You can specify up to three digits indicating a relative date. For example, -3 indicates three days prior to the current date. To specify the current day’s data, you can use -0.

JOB_DATE_HI=yymmmddThis represents the latest date for data to qualify. Any data that was generated later than this date is not reported.

You can omit the year, month, or day component. This results in a wildcard effect. If only two digits are included, they are assumed to be the day.

JOB_DATE_HI=-nnnThis is an alternate form for specifying the latest date for data to qualify. You can specify up to three digits indicating a relative date. For example, -3 indicates three days prior to the current date. To specify the current day’s data, you can use -0.

{{id name="TheDatasetContentionReportingSystem-XREF_bookmark67"/}}

{{id name="TheDatasetContentionReportingSystem-XREF_Dataset_Analysis_Report"/}}

JOB_TIME_LO=hh:mm:ssThe time specification operates within the date boundaries specified with the JOB_ DATE parameters. It represents the earliest time for data to qualify. It is expressed as a 24-hour time specification. You can omit lower-order components that are not required.

Any data that was generated at an earlier time is not reported.

JOB_TIME_HI=hh:mm:ssThe time specification operates within the date boundaries specified with the JOB_ DATE parameters. It represents the latest time for data to qualify. It is expressed as a 24-hour time specification. You can omit lower-order components that are not required.

Any data that was generated at a later time is not reported.

Dataset Analysis Report Selection Options

The following selection options are available with this report:

• The number of lines per page.
• Minimum contention duration. For example, you might not want to clutter your report with any contention occurrence that did not last at least 10 minutes.
• The beginning date for data to be considered.
• The beginning time for data to be considered.
• The end date for data to be considered.
• The end time for data to be considered.
• Data set name matching.

These selection criteria are specified as SYSIN input records, one selection parameter per record. Their syntax and effects are now discussed in detail.

DATASET_LINES=nSpecifies the number of lines per page.

n must be greater than 10. The default value is 10.

If you do not want page breaks specify 0.

DATASET_NAME_PATTERN=patternAllows you to select the data sets you want the report to include. The standard data set matching capabilities of ThruPut Manager are allowed here.

DATASET_MIN_TIME=hh:mm:ssSpecifies the minimum contention duration for a data set to be included in the report. This represents the INTERVAL FOR column in your report.

hh:mm:ss represents the time interval below which you do not want the job included in your report. The default value is 1 minute. You can omit lower-order components that are not required.

DATASET_DATE_LO=yymmmddIt represents the earliest date for data to qualify. Any data that was generated earlier than this date is not reported.

You can omit the year, month, or day component. This results in a wildcard effect. For example, if you code 94FEB, any record created in 1994 during the month of February is included in the report. If only two digits are included, they are assumed to be the day.

DATASET_DATE_LO=-nnnThis is an alternate form for specifying the earliest date for data to qualify. You can specify up to three digits indicating a relative date. For example, -3 indicates three days prior to the current date. To specify the current day’s data, you can use -0.

DATASET_DATE_HI=yymmmddIt represents the latest date for data to qualify. Any data that was generated later than this date is not reported.

You can omit the year, month, or day component. This results in a wildcard effect. If only two digits are included, they are assumed to be the day.

DATASET_DATE_HI=-nnnThis is an alternate form for specifying the latest date for data to qualify. You can specify up to three digits indicating a relative date. For example, -3 indicates three days prior to the current date. To specify the current day’s data, you can use -0.

DATASET_TIME_LO=hh:mm:ssThe time specification operates within the date boundaries specified with the DATASET_DATE parameters. It represents the earliest time for data to qualify. It is expressed as a 24-hour time specification. You can omit lower-order components that are not required.

Any data that was generated at an earlier time is not reported.

DATASET_TIME_HI=hh:mm:ssThe time specification operates within the date boundaries specified with the DATASET_DATE parameters. It represents the latest time for data to qualify. It is expressed as a 24-hour time specification. You can omit lower-order components that are not required.

Any data that was generated at a later time is not reported.

MAX_DATASETS=nnnnnSpecifies the maximum number of data sets for this report. This can be a number in the range 1-99999. The default value is 4096.

MAX_HOLDERS=nnnnnSpecifies the maximum number of data set holders for this report. This can be a number in the range 1-99999. The default value is 4096.

MAX_JOBS=nnnnnSpecifies the maximum number of jobs for this report. This can be a number in the range 1-99999. The default value is 4096.

Facilities Summary