The DFHSTUP extract statistics reporting function

The extract reporting facility provides a method of sending CICS® statistics data to a user program that can process statistics records to create tailored reports. These reports should be easy to review on a daily basis; avoiding the need to work through large amounts of data to determine if some corrective or preventative tuning action is required. It should also be possible to identify the specific CICS regions, the time of day, and the type of CICS resources that may require further specific in-depth performance analysis. DFH0STXR is a sample program designed to exploit the extract reporting function. You can use the sample program as supplied, or as a model on which to base your own programs.

The DFH0STXR sample program

The DFH0STXR sample program produces an event type of statistics report that highlights each event in a single print line providing a convenient method of analyzing CICS statistics records.

There are three types of event:

These events are predefined within the DFH0STXR sample program but can be customized (see Using the extract statistics reporting function for guidance). In order to facilitate customization, events are documented in the prolog along with the statistics fields queried for each.

The existing statistics utility program record selection capabilities, such as, applid, date and time, apply automatically to the DFH0STXR reports, in addition to any other statistics reports that may be created at the same time. However, the COLLECTION TYPE and UPPERCASE control parameters are ignored.

You have the option in the design of the user program to write the statistics data to a data set to be used as input to a database, such as DB2®, or to a reporting tool such as ICETOOL.

The source code for DFH0STXR is supplied in the CICSTS31.CICS.SDFHSAMP library. It is also supplied in compiled form in CICSTS31.CICS.SDFHLOAD. See the CICS Application Programming Guide for guidance on installing application programs.

As well as the DFH0STXR sample, two skeleton exits are provided; an assembler extract exit called DFH£STXA, and a COBOL extract exit called DFH0STXC. These show the format and structure of the interface between DFHSTUP and the extract exit. The source for these skeletons is in SDFHSAMP, and the compiled programs in SDFHLOAD. Extract exits must be written using a Language Environment® enabled assembler or a CICS Language Environment supported high level language.

Figure 22 contains sample output from the DFHSTUP statistics utility program including output from the extract exit. Other statistics reports have been suppressed, as reported in message DFHST0233I.

Figure 22. Sample output from DFHSTUP using the DFH0STXR sample extract program
CICS 6.3.0 Statistics Utility Program                                    Report Date 08/30/2002   Report Time 15:51:18   Page     4
Report Abstract
___________________________________________________________________________________________________________________________________
REPORT ABSTRACT
_______________
  Total SMF records read . . . . . . . . . . . :                   1315
  Total SMF/CICS records read. . . . . . . . . :                   1313
  Total SMF/CICS/Statistics records read . . . :                   1313
  Total SMF/CICS/Statistics records processed. :                     35
  Applid: IYK2Z2G1  Jobname: CI13JTD5
  ___________________________________
  Number of Statistics Intervals processed . . :                      0
  Number of EOD records processed. . . . . . . :                      0
  Number of INT records processed. . . . . . . :                      0
  Number of REQ records processed. . . . . . . :                   2456
  Number of RRT records processed. . . . . . . :                      0
  Number of USS records processed. . . . . . . :                     15
  Date/Time of first SMF record processed. . . : 08/30/2002 at 15:40:25     CICS Start Date/Time. . : 08/30/2002 at 15:40:23
  Date/Time of last SMF record processed . . . : 08/30/2002 at 15:42:43
DFHST0233 I DFHSTUP report suppressed. Report options requested only an EXTRACT userprogram to be invoked.
CICS 6.3.0 Statistics Utility Program                                    Report Date 08/30/2002   Report Time 15:51:18   Page     5
Report Abstract
___________________________________________________________________________________________________________________________________
CICS 6.3.0 Statistics Exception Event Reporter                      Report Date: 08/30/2002   Report Time: 15:51:18      Page      1
____________________________________________________________________________________________________________________________________
EXCEPTION
WARN
INFO
CICS 6.3.0 Statistics Exception Event Reporter                      Report Date: 08/30/2002   Report Time: 15:51:18      Page      2
____________________________________________________________________________________________________________________________________
        Record     Record  Stats           Event
Type     Date       Time    Type  Applid    id    Event Description
____________________________________________________________________________________________________________________________________
  I   08/30/2002  15:42:43  REQ  IYK2Z2G1  XM001  MXT Limit =  30. Current Tasks =   1. Peak Tasks =   6.
  I   08/30/2002  15:42:43  REQ  IYK2Z2G1  SM001  DSA Limit =      4,096K. Allocated =      2,048K. Peak =      2,048K.
  I   08/30/2002  15:42:43  REQ  IYK2Z2G1  SM002  EDSA Limit =    204,800K. Allocated =     22,528K. Peak =     22,528K.
  I   08/30/2002  15:42:43  REQ  IYK2Z2G1  TS001  DFHTEMP CIs =        507. Peak Used =          2. Peak TSMain =          0K.
  W   08/30/2002  15:42:43  REQ  IYK2Z2G1  LD001  Program Load to Use Ratio for Program 'IBMRLIB1' = 100%. Location = 'RDSA    '.
  W   08/30/2002  15:42:43  REQ  IYK2Z2G1  LD001  Program Load to Use Ratio for Program 'IBMRSAP ' = 100%. Location = 'RDSA    '.
  W   08/30/2002  15:42:43  REQ  IYK2Z2G1  LD001  Program Load to Use Ratio for Program 'IGZCPAC ' = 100%. Location = 'ERDSA   '.
  W   08/30/2002  15:42:43  REQ  IYK2Z2G1  LD001  Program Load to Use Ratio for Program 'IGZCPCC ' = 100%. Location = 'ERDSA   '.
  I   08/30/2002  15:42:43  REQ  IYK2Z2G1  D2001  DB2 Conn 'RCTJT   '. TCB Limit =    12. Peak TCBs =     1. TCB Readyq HWM =   0.
CICS 6.3.0 Statistics Exception Event Reporter                      Report Date: 08/30/2002   Report Time: 15:51:18      Page      3
____________________________________________________________________________________________________________________________________
                                    Statistics Exception Event Report Totals for Applid IYK2Z2G1
                                    ____________________________________________________________
Statistics Records Processed . . . . . . . . . . :       2,471
Statistics Exception Events Reported . . . . . . :           0
Statistics Warning Events Reported . . . . . . . :           4
Statistics Information Events Reported . . . . . :           5
                                                    __________
Total Events Reported  . . . . . . . . . . . . . :           9
____________________________________________________________________________________________________________________________________
Total Statistics Records Processed .................:      2,471
Statistics Event Report Processing Complete.
Note:
The date and time do not indicate when an event occurs.The statistics record may be written out some time after the actual event has occurred.

Using the extract statistics reporting function

To use the extract reporting function, you specify the EXTRACT control statement to control the output from DFHSTUP. The EXTRACT control statement takes all the statistics data from the input SMF data set and passes it to a user program for processing. The EXTRACT control statement has the following syntax:

EXTRACT USERPROGRAM=progname

where USERPROGRAM is the name of the user-written program that is to process the data. You must supply a USERPROGRAM value.

The existing statistics utility program record selection capabilities, such as, applid, date and time apply automatically to extract reports as well as to any other statistics reports that may be created at the same time. However, the COLLECTION TYPE control parameter of DFHSTUP is ignored in an EXTRACT report.

Specifying the EXTRACT control statement changes the default DFHSTUP report settings. If you specify only the EXTRACT control statement, only the extract exit is driven; other DFHSTUP reports are suppressed. If EXTRACT is specified, other statistics report control statements, such as SUMMARY, must also be specified to ensure that the appropriate reports are produced.

The STXRINPT DD control statement specifies the event types to be reported. The possible event types are:

[EXCEPTION] [WARNING] [INFORMATION]

Exception is the default.You can abbreviate these parameters to EXC, WARN and INFO.

For example, if you want just an event-type report using the CICS supplied sample exit program, you could specify the following:

//xxxxxxxx JOB (job accounting)
//stepname EXEC PGM=DFHSTUP,REGION=0M
//STEPLIB  DD DSN=....
//         DD DSN=....
//         DD DSN=PP.CEE.SCEERUN,DISP=SHR
//DFHSTATS DD DSN=...
//DFHSTWRK DD ....
//SYSPRINT DD SYSOUT=x
//STXRRPT  DD SYSOUT=x
//STXRINPT DD *
INFO                          <- Optional input
/*
//SYSIN DD *
EXTRACT USERPROGRAM=DFH0STXR
/*
//

If you wish to print all types of statistics reports, including a summary and an event report, you could specify the following:

//xxxxxxxx JOB (job accounting)
//stepname EXEC PGM=DFHSTUP,REGION=0M
//STEPLIB  DD DSN=....
//         DD DSN=....
//         DD DSN=PP.CEE.SCEERUN,DISP=SHR
//DFHSTATS DD DSN=...
//DFHSTWRK DD ....
//SYSPRINT DD SYSOUT=x
//STXRRPT  DD SYSOUT=x
//STXRINPT DD *
INFO
/*
//SYSIN DD *
COLLECTION TYPE=ALL
SUMMARY
EXTRACT USERPROGRAM=DFH0STXR
/*
//

You must assemble (or compile) and link edit DFHSTUP user programs as batch programs, not as CICS applications, and you need link-edit control statements appropriate to the language in which they are written. When you link-edit the programs, you need to specify the following link-edit control statements:

These requirements are illustrated in the following sample job stream.

//DFHxxxxx JOB (),CLASS=A,MSGCLASS=A,NOTIFY=userid
//*
//* Compile job step here
//*
//LINK     EXEC PGM=IEWL,PARM='XREF,LIST,LET'
//SYSLIB   DD DSN=PP.CEE.SCEELKED,DISP=SHR
//CICSLIB  DD DSN=CICSTS31.CICS.SDFHLOAD,DISP=SHR
//OBJLIB   DD DSN=object.module.library,DISP=SHR
//SYSLMOD  DD DSN=user.library,DISP=SHR
//SYSUT1   DD UNIT=SYSDA,SPACE=(1024,(100,10)) 
//SYSPRINT DD SYSOUT=x
//SYSLIN   DD *
 ENTRY   DFHEXTRA
 CHANGE  EXITEP(program name)
 INCLUDE CICSLIB(DFHSTXLE)
 INCLUDE OBJLIB(obj-prog)
 MODE AMODE(31),RMODE(24)
 NAME    progname(R) 
/*
//
Notes:
  1. The entry name, DFHEXTRA, is the entry name in the CICS-supplied stub, DFHSTXLE.
  2. The CICS-supplied stub, DFHSTXLE, is generated with a link to the user program using a dummy CSECT name (EXITEP).
  3. Use the link edit CHANGE statement to change the CSECT name from EXITEP to the name specified as the program ID or CSECT name in the user program.
  4. Include DFHSTXLE in any Language Environment-conforming user program that you write for use with the DFHSTUP EXTRACT command. DFHSTXLE is the interface stub between DFHSTOT, a module in DFHSTUP, and the Language Environment user program.
  5. obj-prog is the name of the object program.
  6. progname is the name for the load module; this is the name that you specify on the USERPROGRAM parameter of the EXTRACT command.
  7. You must link edit user programs AMODE(31) and RMODE(24).

Related reference
Statistics utility program (DFHSTUP)
Setting the statistics recording status, end-of-day time and recording interval
Control parameters of the DFHSTUP program
CICS Application Programming Guide
[[ Contents Previous Page | Next Page Index ]]