Performance Data extract

A Performance Data Extract is created as a file in delimited text format or JSON Lines format for the purpose of importing the CMF performance class data into external programs such as DB2®, PC spreadsheet tools, or other analytics platforms for further detailed analysis and reporting.

A Recap report containing processing statistics is always printed at the end of extract processing.

To request the extract, enter line action S against the Performance Extract on the Report Set panel. If extracts have been previously specified, the list of Performance Extracts is displayed. Otherwise, the Performance Extract panel is displayed for you to define your first one.
Figure 1. Performance Extracts
File  Filter  Edit  Systems  Options  Help
 ------------------------------------------------------------------------------
                     SAMPLE - Performance Extracts                 Row 1 from 2
 Command ===> ________________________________________________ Scroll ===> ____
 
         ---- System Selection -----                                     Selection
 /  Exc  APPLID +  Image +  Group +     Recap      Form +     Alert +    Criteria
 _       CICSP001  ________ ________    EXPT0001   ________   ________     YES
         Output Data Set . .  'CICSP001.EXTRACT'____________________________
 ------------------------------------------------------------------------------
 _       DEVT____  MVS1____ ________    EXPT0002   ________   ________     NO
         Output Data Set . .  'DEVTMVS1.EXTRACT'____________________________
 ------------------------------------------------------------------------------
 ********************************* End of list ********************************
 

This panel displays the list of Performance Data Extracts in this Report Set. You can select (edit), delete, or include/exclude any extract, insert new ones, or rearrange them (move/copy).

The options and line actions are the same as on the Cross-System Work Extracts panel (see Cross-System Work extract), except for the addition of the Form and Alert columns.

When generating the JCL, CICS® PA assigns a default DDname CPAOEXnn where nn is a sequential number 01-99 to ensure uniqueness.

To display the Performance Extract panel, enter line action S against the Performance Extract on the Report Set panel, then if the list of previously specified extracts is displayed, enter line action S against a particular extract in the list.
Figure 2. Performance Extract

File  Systems  Options  Help
 ------------------------------------------------------------------------------
                          SAMPLE - Performance Extract
 Command ===> _________________________________________________________________
 
 System Selection:                       Extract Recap:
  APPLID . . CICSP001  +                  DDname  . . . EXPT0001
  Image  . . ________  +
  Group  . . ________  +
 
 Data Output:
  Data Set Name  . . 'CICSP001.EXTRACT'____________________________
  Disposition  . . . 1  1. OLD   2. MOD    (If cataloged)
  z/OS UNIX File . .                                                      + 
 
 Extract Focus:                          Summary Processing Options:          
  Form  . . . . ________  +               Interval  . . . 00:01:00  (hh:mm:ss)
  Alert . . . . ________  +               Override Form   ________  +         
   Severity . . ________  +               Timestamp . . . ________  +         
                                                                             
 Extract Format:
     1. CSV   2. JSON                        Options
                                                                             
 Selection Criteria:                     Execution Options:                   
  _  Performance  *                       /  Use External Sort    
                                                                             
 Repository  . . : CPA.XYX.REPOSTRY                                          
 
  F1=Help      F3=Exit      F4=Prompt    F7=Backward  F8=Forward  F10=Actions
 F12=Cancel

Use this panel to specify extract options and record selection criteria for the Performance Data extract. The mandatory options are the name and disposition of the Extract data set, the extract format, and the DDname for the Recap report. You can let the other options take their default values.

The Extract record has a default format which includes all the Clock fields. Report Forms (LIST, LISTX, or SUMMARY) can be used to tailor the format and content of the records.

The options are:

System Selection
Identifies the CICS APPLIDs whose data you want to select for processing.

You can specify any combination of APPLID, Image, or Group, but these must be defined in your System Definitions. If you do not specify System Selection here or in the Global Options, then you are prompted at run time to specify the System Selection. This will apply globally to all reports and extracts without their own System Selection. This is recommended as it allows you to run your Report Sets against any of your defined Systems. Press the Prompt key (F4) to select from a list of defined Systems, Images, or Groups. To modify your System Definitions, select Systems in the action bar.

Specify one of the following:
  • A CICS APPLID. An APPLID that matches a defined System's name pattern is also allowed. For example, CICSP1 can be specified if CICSP* is a defined system.
  • An APPLID and an MVS™ Image. This identifies the MVS Image where your CICS system runs.
  • An MVS Image. All CICS systems executing on this MVS Image is selected.
  • An APPLID and Image combination plus a Group. This is useful for uniquely identifying a CICS system when there are multiple CICS systems with the same name defined.
  • A Group alone. CICS PA will select all CICS APPLIDs defined to the Group. For example, for transaction grouping, or for systems that connect via IRC/MRO, ISC/APPC, or IPIC.

CICS PA uses the System Selection in JCL generation to build the APPLID(applid1,applid2,applid3,...) and INput(SMFIN001,SMFIN002,SMFIN003,...) operands, and corresponding //SMFINnnn DD statements.

System Selection can also be specified either:
  • In Global Options. The report-level specification takes precedence over the global.
  • At run time. The run-time System Selection overrides the Global Options and optionally the report-level specification.
Data Set Name
The name of the data set where the extract records are written. If CICS PA is to create the data set at run time, the default allocation attributes specified on the Reporting Allocation Settings panel are used in generating the JCL. If the data set is already cataloged, then CICS PA will use DISP=OLD or DISP=MOD according to your request to overwrite or append to the existing data set.

When generating the JCL, CICS PA assigns a default DDname CPAOEXnn where nn is a sequential number 01-99 to ensure uniqueness.

When specifying the data set name, standard TSO conventions apply.

If you want to output to a data set, make sure the z/OS Unix File field is blank.

Disposition
The DISP value that you want the generated JCL to use for the output data set if it is already cataloged:
OLD
Overwrites the data set contents with the new extract data.
MOD
Appends the new extract data.

You must specify one of these dispositions regardless of whether the output data set is cataloged. If the output data set is not cataloged when CICS PA generates the JCL, then CICS PA generates the JCL using DISP=(NEW,CATLG) to catalog it.

z/OS Unix File
The absolute path of the z/OS® UNIX file that is the destination of the extract. If you want to output to a z/OS UNIX File, ensure the Data Set Name field is blank. That is, you can specify a data set name or a z/OS UNIX file, but not both.
Form
The name of a Report Form to be used to tailor the type of extract and the format of the extract records. The Report Form can be a LIST, LISTX, or SUMMARY Form:
  • LIST and LISTX Forms produce an extracted data file like the Performance List Report. There is no restriction on the number of fields. Note that in contrast to the report, LISTX does not produce a sorted extract. Specifying a Form of this type generates the LIST report operand.
  • SUMMARY produces an extracted data file equivalent to the Performance Summary report, sorting and summarizing on specified fields, but with no restriction on the number of fields. Specifying a Form of this type generates the SUMMARY report operand.
  • If a Report Form is not specified, the default extract is produced using the EXTRACTPERFORMANCE report operand.

To select the name from a list of compatible Report Forms, position the cursor on the Form field and press Prompt (F4).

CICS PA JCL generation translates the Report Form specification into the LIST(FIELDS or SUMMARY(FIELDS operand.

Alert
The name of a Performance Alert Definition. To select from a list of predefined names, position the cursor on the Alert field and press Prompt (F4). CICS PA JCL generation translates the Alert specification into the ALERTDEF operand.

This option only applies when a Form is specified, otherwise, it is ignored.

Severity
When an Alert name is specified, this suboption allows you to specify the minimum severity level to be reported and type of transactions reported.

For the List extract, the minimum severity level selected for reporting is used to report transactions that have at least that level of reporting in any of the severity fields. This could result in transactions being reported with severity lower than the specified severity when the transaction also has one or more severity fields that meets the specified severity criteria. For example, if you specify SEVERITY(CRITICAL), only transactions with Critical severity are reported, however, if a transaction also exceeds Warning or Info thresholds, the lower severity will be also reported.

Press Prompt (F4) to select from the list of available options which are:
For a List extract (ignored for Summary):
The following options only apply to a List report or extract. If specified for a Summary extract, SEVERITY(ALL) is assumed.
CRITICAL
Only Critical transactions are reported.
WARNING
Only Critical and Warning transactions are reported.
INFO
All alerts are reported: Critical, Warning and Informational transactions.
For a List or Summary extract:
The following options apply to both List and Summary.
ELIGIBLE
Only eligible transactions are processed and reported. Eligible transactions are those that have resource values that match resource values specified in the alert definition.

This option provides the means to filter out transactions that would never generate an alert because their resource values do not match resource values specified in the alert definition.

ALL or blank
All transactions are reported regardless of whether they are eligible or whether they generate an alert. This is the default value.
CICS PA JCL generation translates the Severity specification into the following operands:
List extract
SEVERITY(CRITICAL|WARNING|INFO|ELIGIBLE|ALL)
Summary extract
SEVERITY(ELIGIBLE|ALL)
Interval
The time interval applies when you want to summarize transaction activity over time. It is used when you specify a SUMMARY Report Form which has any of the key fields OSTART, START, or STOP included. When reporting, CICS PA accumulates the data for each interval in the report period and writes a report line for each.

Specify a value in the range 00:00:01 (1 second) to 24:00:00 (24 hours). The default is 00:01:00 (1 minute).

A time interval of less than one hour must fit evenly into the hour. CICS PA will round it down to the nearest interval that aligns to the hour. For example, 1.35 is reduced to 00:01:30 minutes which will produce 40 interval report lines for each hour of data.

A time interval of more than one hour must fit evenly into the day. CICS PA will round it down to the nearest interval that aligns to the day. For example, 10.30.23 is reduced to 08:00:00 hours which will produce 3 interval report lines for each day of data.

Minutes take precedence for an abbreviated entry. For example:
1
becomes 00:01:00
1.1
becomes 00:01:00 (rounded down from 00:01:01)
1.1.1
becomes 01:00:00 (rounded down from 01:01:01)

This option generates the INTERVAL(hh:mm:ss) operand.

Override Form
For the Summary extract, this option specifies whether to PREFIX, APPEND or REPLACE the key fields specified in the Form. Based on the action in this option, JCL generation will generate the required Form key using the override option and field specified in Timestamp. Ensure that the resulting key will conform to the Summary key rules. No action will be taken if this field is blank. The Form itself is not affected, only the generated FIELDS key fields.
Timestamp
Specifies the field name to override the Form key fields. Valid timestamp fields are START, STOP, and OSTART.
Extract Format
This option specifies whether to output the extract in delimited text format (CSV) or in JSON Lines format (JSON).
Options
When this option is selected and you press Enter, the Options panel is displayed, which enables you to alter the formatting of the extract.
Performance Selection Criteria
You can specify Selection Criteria to filter the CMF records on time period and field values to restrict the extract to the data that is of interest to you. CICS PA JCL generation translates Selection Criteria to the SELECT(PERFORMANCE operand.

If you specify a Report Form that also has Selection Criteria specified, CICS PA JCL generation translates the Form's Selection Criteria to the SELECT2(PERFORMANCE operand. If both the report and the Form specify Selection Criteria, then a record must pass selection by both specifications to be included in the extract.

Line Actions:
⁄
Display the menu of line actions.
S
Display the subpanel where Selection Criteria can be specified for this report. For details, see Specifying Selection Criteria.
A
Activate the Selection Criteria so they are generated for this report when the Report Set is submitted. Selection Criteria can only be activated if one or more Select Statements are specified and not all are excluded. An asterisk (*) indicates they are active.
D
Deactivate the Selection Criteria. Any you have specified here will not be used.
Use External Sort

Select / to use an external sort utility to process Summary records. This is the default. It generates the EXTERNAL(ddname) operand. This provides the DDname of the work data set used by the external sort utility. CICS PA assigns an External Work File from a pool of External Work Files with default DDnames in the format CPAXWnnn where nnn is a sequential number 001-999 to uniquely identify the work file.

An external sort should be used when processing records that would generate a very large number of unique key values.

If not selected, an internal sort is used.

Repository
The data set name of the Repository that contains the Performance Alert Definitions.