In response to excellent feedback and suggestions from new and existing CICS Performance Analyzer for z/OS (CICS PA) clients, IBM is adding new capabilities to this flagship CICS Tools product. The new functions are delivered with a PTF for APAR PI64606.

Summary of new functionality

  • Create extracts using Statistics Summary forms and Statistics List forms – RFE 82551
  • Export statistics data from multiple CICS Transaction Server for z/OS (CICS TS) and CICS Transaction Gateway (CICS TG) releases into the same DB2 table – RFE 89215
  • Symbolic variable representing week for cyclic data sets – RFE 89308
  • Enhancements to sample report sets
  • Convert CICS Statistics Domain Subpools records in a pre-V530 HDB to the correct format
  • Documentation enhancements

Extracts for CICS PA Statistics Summary and List reports – RFE 82551

Performance and Statistics extracts provide a means of extracting CICS PA-formatted data into a file for import into PC spreadsheet tools or databases. The data can then be used for further analysis and visualizing using tables and charts.

CICS PA V5.3 introduced form-based statistics reporting. This APAR extends this feature to allow the form-based statistics records to be written to a file instead of to the usual report. Form-based statistics extract is supported for SMF data with Reports Sets and the Statistics HDB Extract option.

Many CICS TS systems and performance programmers need to provide CICS TS and CICS TG statistics for people who do not have access to z/OS. They need an easy way to create a CSV file of Statistics Summary and List reports containing CICS TS and CICS TG data.

CICS PA V5.3 introduced form-based Statistics List and Statistics Summary reporting. APAR PI64606 extends this functionality to enable users to create extracts using a form. The Statistics form-based extract provides equivalent functionality to the Performance form-based extract.

Using this new function, it is easy to extract the Statistics data the end user wants. The end users can import an extracted CSV into spreadsheet or database tools for detailed analysis and reporting.

The Statistics form-based extract feature is available in both Report Sets->Extracts>Statistics definition and in the HDB->Extract feature. Here I illustrate creating a form-based Statistics Extract using a Report Set:

pict-1

  • In the Extract Focus section, you specify which Statistics data you want in the extract. You can use either the “Statistics Reports” option or the “Form” option.
  • Statistics Reports lets you select from a list of existing CICS statistics reports.
  • Form is the name of a Statistics List or Summary form that specifies the fields you want in the extract. Press Prompt (F4) to choose from a list of existing eligible forms.

You can extract from a STATS historical database in a similar way:

pict-2

Here I will show how you can extract statistics data loaded into a HDB.

  • HDB form-based statistics extract is available under 5.6 Historical Database > Extract > [select a STATS HDB]
  • Again you can select any STATLST or STATSUM form
  • If you choose Request form-based extract, a panel is displayed that enables you to enter run options for the extract, including selection criteria and statistics type
  • If you choose Request full reports extract, the list of statistics reports is displayed. Enter line action S beside the reports you want to extract, and then press Enter. A panel is displayed that enables you to enter run options for the extract.
  • Choose additional extract options to generate a file in your desired format including:
    • the delimiter( for example, comma or semi-colon)
    • whether to include field labels

As before, you can import the extract file into PC spreadsheet or database tools for further detailed analysis and reporting.

pict-3 pict-4 pict-5

Multiple-release statistics data to single DB2 table – RFE 89215

Prior to this enhancement, you could not load certain CICS TS and TG statistics records from multiple releases into DB2 because of changes to the fields defined in the records. The DB2 table load would fail because the CICS PA-generated DB2 LOAD command was based on the CICS release specified in the dialog. If you are processing records from multiple releases of CICS, the generated fields in the LOAD command might not match some releases, causing the DB2 load to fail.

To overcome this limitation, this enhancement allows you to specify the multiple CICS releases for both CICS TS and CICS TG. When you do this, CICS PA will generate multiple DB2 LOAD commands, one for each of the specified releases.

To match the HDB record with the LOAD command, CICS PA appends a release identifier to the STID specified in the LOAD command’s WHEN clause. This ensures the appropriate LOAD command, with the correct list of fields, is used to load each HDB record into the DB2 table. Since the DB2 table definition will probably be based on a specific CICS release, some record fields might not exist in the table, which would normally cause the DB2 load to fail. In order to ensure it does not fail, CICS PA also generates the IGNOREFIELDS YES operand. This operand allows the DB2 load to continue when fields specified in the LOAD command are not defined in the DB2 table.

NOTE: The release identifier and IGNOREFIELDS YES are not generated if only one CICS release is specified in the dialog.

In summary, the HDB export function generates JCL that tolerates additional or missing fields because of CICS TS or CICS TG version differences.

You can use this functionality from these panels:

  • 5.5 Historical Database > Export > [select a STATS HDB] > … > select 2 Load data into table
  • 5.3 Historical Database > Load (because you can select Load DB2 Table option to load to DB2 as well as to HDB)
  • 2 Report Sets > [select report set] > Extracts > HDB Load (again because of the Load DB2 Table option)

This graphic shows the HDB Load panel option for specifying the required version, release, and modification levels (VRMs).

In this example, it is assumed that data from only one VRM is loaded into the HDB and exported to DB2:

pict-6

This graphic shows the DB2 LOAD command that is generated when only one CICS VRM is specified:

pict-7

pict-8

Note that the command does not include the IGNOREFIELDS YES operand, nor the release identifier in the STID value in the WHEN clause. They are not required since only one version of that statistics record is loaded in the HDB and therefore the record definition should match the DB2 table definition.

The graphic below shows the DB2 LOAD commands generated when multiple VRMs are specified.

For example, on the load form, you can specify TS 690 and 680, in addition to 700 as below.

pict-9

The JCL that is created specifies two LOAD INTO TABLE statements, one for VRM 700 and 690 which had the same fields, and one for VRM 680 which had a different set of fields.

pict-10

  • Although three VRMs are specified for TS, only two DB2 LOAD commands are generated. This is because the Dispatcher Overview statistics records (STID 062A) changed between VRM 680 and 690, but it is the same in VRM 690 and 700.
  • In order to match the correct DB2 LOAD command field list with the record being processed, CICS PA appends the release identifier to the STID in the WHEN clause, ‘7’ for VRM 680, ‘8’ for VRM 690 and 700.
  • The DB2 LOAD IGNOREFIELDS YES operand is generated to ensure that the load does not fail if the field list in the DB2 load command does not match the DB2 table definition.
  • IGNOREFIELDS YES and release identifier are generated only for STIDs that have changed in the specified VRMs. The DB2 LOAD command for a STID that has not changed is the standard command without these two new attributes.

Symbolic variable week for Cyclic dataset name – RFE 89308

Some client sites include a relative week number for weekly SMF datasets. For example CICSPROD.Y16W09 where 16 is year 2016 and 09 is the week of the year. Using symbolics, the cyclic dataset name is defined as CICSPROD.Y&YY..W&WW.SMF.

  • Primary Menu Option 1.2 Shared Systems > [1 Define Systems and their SMF Files] > [select a system] > [select 2 Cyclic SMF Files], the name of the SMF file can include &WW to represent the week number

This graphic shows how to define a Shared Systems Definition Cyclic data set whose name contains year and week:

pict-11

  • The new week variable is specified as &WW in the name of the cyclic data set.
  • The Origin date will determine the start of the cycle for weeks, for example week 01.
  • There are 53 week cycles in the year; the 53rd cycle contains the remaining days after the 52nd cycle to the start of the new week cycle. This is based on 365 days / 7 days = 52.1 weeks, for example 1 extra day, and 2 in leap years.

Symbolic variable for week

With this APAR, you can use symbolic variable &WW to represent the week.

The list of valid variables is now:

pict-12

Enhancements to sample reports sets

Sample reports sets were introduced in CICS PA V5.3. This enhancement augments the samples with the addition of new reports to the THRDSAFE report set. This report set can be used to analyze the performance of threadsafe transactions and to identify transactions that would benefit from being made threadsafe.

Use sample member CPARSSJC in the SCPASAMP library to install the sample report sets. See Installing Report Set samples in the CICS PA documentation for details.

New reports for THRDSAFE report set to help analyze the level of TCB switching:

  • CHMDSLST: EXEC CICS commands and change CICS TCB Modes analysis – List
  • CHMDSSUM: EXEC CICS commands and change CICS TCB Modes analysis – Summary
  • CPU5SUMC: Transaction CPU count analysis (V5)

The VIRTSTG and STGOVRV statistics forms are used in several sample report sets.

This enhancement has modified the previous versions of these forms to refine their content and improve their focus in order to report the most relevant statistics.

You can further customize any of the forms provided in the sample report sets to report the statistics you want.

  • VIRTSTG: Virtual storage usage summary report
    • DSA Name and DSA Index fields added
    • some redundant fields removed
    • the fields are now presented in a better order
  • STGOVRV: Storage overview summary report
    • Collection Time field added
    • STGOVRV report is now added to report set CONSOLDT

pict-13

The MONTORNG and TRANMNGR statistics forms are used in a number of sample report sets.

This enhancement has modified the previous versions of these forms to refine their content and improve their focus in order to report the most relevant statistics.

You can further customize any of the forms provided in the sample report sets to report the statistics you want.

  • MONTORNG: Monitoring Global statistics report
    • fields reordered and redundant fields removed
  • TRANMNGR: Transaction Manager statistics analysis report
    • Collection time and Current MAXTASK fields added

pict-14

Convert pre-V530 Statistics HDB records

Versions of CICS PA prior to V5.3 loaded Domain Subpools statistics record field Initial Free Area with an incorrect length into the HDB. CICS PA V5.3 corrected this problem causing records loaded into the HDB prior to V5.3 to report incorrect values.

This enhancement provides a new HDB command that converts records loaded with the incorrect length to the correct format. This ensure that all the fields in the Domain Subpools are reported correctly by CICS PA.

The Convert command will generate JCL to execute the conversion routine

pict-15

The above graphic shows how to convert a statistics HDB container containing Domain Subpools records loaded using a pre-V5.3 version of CICS PA.

  1. From the Primary Option Menu select 5 – Historical Database
  2. Select 7 – Maintenance
  3. Select the statistics HDB you wish to convert
  4. Select View 2 – Data Sets
  5. Enter line action “C” next to one or more containers you wish to convert. This will generate JCL similar to the sample shown on the next slide.
  6. Submit the JCL to perform the conversion
  7. Review the JOB SYSPRINT files for conversion completion status

This graphic below shows an example of the JCL to convert a statistics HDB container:

pict-16

The conversion JCL has several steps:

  1. HKEEP1 performs housekeeping to ensure that the job runs successfully by explicitly deleting the TMP data set used to contain the copied records.
  2. CICSPA1 runs the conversion routine.
    • DD HDBIN identifies the statistics HDB container to be converted
    • DD HDBOUT identifies the data set to write the HDB records to. All records from the HDB container are written to this data set regardless of whether they are reformatted or not. This data set will replace the HDB container if one or more records are reformatted. Note: you should review the SPACE parameter in this DD card to ensure that sufficient space will be allocated to hold all the records in the HDB container.
  3. When step CICSPA1 completes with return code 0, indicating that records were reformatted, step HDREN1 is executed to delete the original statistics HDB container and rename the TMP container to HDB replacing the original.
  4. When step CICSPA1 completes with return code 4, indicating that no records were reformatted, step HDREN1 is bypassed and step TMPDEL1 is executed. This step simply deletes the TMP data sets as it is a exact copy of the HDB container and is therefore not required. Step TMPDEL1 is bypassed if step HDREN1 is executed.

Documentation enhancements

The CICS PA User’s Guide now shows a brief example of each report in the report set samples, including a description and the most important columns.

The topic for the PLUGIN scenario includes a table of tasks to help you successfully display the data in CICS PA plug-in for CICS Explorer.

pict-17

The PLUGIN topic is useful when you want to export data from CICS PA to DB2 so you can view the data with CICS Explorer.


Documentation is available in the IBM Knowledge Center:
CICS PA V5.3 documentation

See Summary of Changes for what’s new.
CICS PA V5.3 Summary of changes

The new Components used by the CICS PA plug-in topic has diagrams explaining the relationship between HDBs, DB2, CICS Explorer, and the CICS PA plug-in. Examples below:
pict-18

pict-19

Join The Discussion

Your email address will not be published. Required fields are marked *