LIST Report Form

The LIST Report Form can be used to tailor the format and content of the following reports and extracts:

The Report Form defines the fields to be included, the order of the columns, and a title for the report.

The Report Form panel has two views as there are too many columns of information to display in a single screen view. Scroll Right (F11) to toggle between the views.

When you select a Report Form to Edit or View, the first view shown in Figure 1 is displayed by default.
Figure 1. LIST Report Form (with Default Form)
   File  Edit  Confirm  Upgrade  Options  Help
 ------------------------------------------------------------------------------
                     EDIT LIST Report Form - SAMPLIST                   More: >
 Command ===> ________________________________________________ Scroll ===> PAGE
 
 Description  . . . . List Report Form________________  Version (VRM): 670
 
 Selection Criteria:
  _  Performance  *                                     Page width . . 132_ 
 
     Field
 /   Name +     Type      Fn   Description
 __  TRAN____   _______   ___  Transaction identifier
 __  STYPE___   _______   ___  Transaction start type
 __  TERM____   _______   ___  Terminal ID
 __  USERID__   _______   ___  User ID
 __  RSYSID__   _______   ___  Remote System ID
 __  PROGRAM_   _______   ___  Program name
 __  TASKNO__   _______   ___  Transaction identification number
 __  STOP____   TIMET__   ___  Task stop time
 __  RESPONSE   _______   SEV  Transaction response time
 __  DISPATCH   TIME___   ___  Dispatch time
 __  CPU_____   TIME___   SEV  CPU time
 __  SUSPEND_   TIME___   ___  Suspend time
 __  DISPWAIT   TIME___   ___  Redispatch wait time
 __  FCWAIT__   TIME___   ___  File I/O wait time
 __  FCAMCT__   _______   ___  File access-method requests
 __  IRWAIT__   TIME___   ___  MRO link wait time
 __  EOR_____   _______   ___  ---------------- End of Report ----------------
 __  EOX_____   _______   ___  ---------------- End of Extract ---------------
 __  ABCODEC_   _______   ___  Current ABEND code
  F1=Help      F3=Exit      F4=Prompt    F5=Rfind     F7=Backward  F8=Forward
 F10=Actions  F11=Right    F12=Cancel                                        
   File  Edit  Confirm  Upgrade Options  Help
 ------------------------------------------------------------------------------
                     EDIT LIST Report Form - SAMPLIST                   More: >
 Command ===> ________________________________________________ Scroll ===> PAGE
 
 Description  . . . . List Report Form________________
 
 Title  . . First half title__________________________________________________
            Second half title_________________________________________________
 
     Field                                               - User Field -
 /   Name       Type      Length  Dictionary Definition  Offset  Length
 __  TRAN____   _______        4  TRAN     DFHTASK C001   ___     ___
 __  STYPE___   _______        2  TTYPE    DFHTASK C004   ___     ___
 __  TERM____   _______        4  TERM     DFHTERM C002   ___     ___
 __  USERID__   _______        8  USERID   DFHCICS C089   ___     ___
 __  RSYSID__   _______        4  RSYSID   DFHCICS C130   ___     ___
 __  PROGRAM_   _______        8  PGMNAME  DFHPROG C071   ___     ___
 __  TASKNO__   _______        8  TRANNUM  DFHTASK P031   ___     ___
 __  STOP____   TIMET__       12  STOP     DFHCICS T006   ___     ___
 __  RESPONSE   _______        8  RESP     CICSPA  D901   ___     ___
 __  DISPATCH   TIME___        8  USRDISPT DFHTASK S007   ___     ___
 __  CPU_____   TIME___        8  USRCPUT  DFHTASK S008   ___     ___
 __  SUSPEND_   TIME___        8  SUSPTIME DFHTASK S014   ___     ___
 __  DISPWAIT   TIME___        8  DISPWTT  DFHTASK S102   ___     ___
 __  FCWAIT__   TIME___        8  FCIOWTT  DFHFILE S063   ___     ___
 __  FCAMCT__   _______        8  FCAMCT   DFHFILE A070   ___     ___
 __  IRWAIT__   TIME___        8  IRIOWTT  DFHTERM S100   ___     ___
 __  EOR_____   _______                                   ___     ___
 __  EOX_____   _______                                   ___     ___
 __  ABCODEC_   _______        4  ABCODEC  DFHPROG C114   ___     ___
  F1=Help      F3=Exit      F4=Prompt    F5=Rfind     F7=Backward  F8=Forward
 F10=Actions  F11=Right    F12=Cancel                                        
The LIST Report Form consists of the following:
Form Description
Up to 32 characters of text to describe the purpose of the Report Form. This description is shown on the Report Forms panel to help you identify the Forms in the list. It is initially set to List Report Form.
Version (VRM)
This identifies the CICS® release that this Report Form was created for. It determines which CMF fields are available for selection in this Report Form.
Selection Criteria
Optionally, you can specify Selection Criteria to filter the data on time periods and field values to restrict the reporting to only the data that is of interest to you.

When a report specifies a Report Form and both have Selection Criteria specified, records must match both criteria to be included in the report.

Line Actions: The available line actions are:
/
Display the selection list of line actions.
S
Select (edit) the Selection Criteria. See Specifying Selection Criteria for information on specifying Selection Criteria.
A
Activate the Selection Criteria so they are included for reporting. Selection Criteria can only be activated if you have specified at least one Select Statement and it is not excluded. An asterisk * indicates they are active.
D
Deactivate the Selection Criteria. Any you might have specified here will not be used in reporting.
Page Width
Page width of the report, in the range 80 to 8000. The default is 132.

When you increase the page width, you can include more fields in the report. Move EOR down the list or move fields above EOR to include the fields of interest. CICS PA automatically adjusts the EOR marker when the fields overflow the page width.

When you view the report output (using SDSF), scroll right to see the additional fields. Note that when you print the report, data that exceeds the maximum printer page width is truncated.

Title
Title of the report. Specify up to 128 characters of text to describe the report. CICS PA concatenates the two lines of 64 exactly as entered to make one line which prints at the top of each page of the report below the heading. The default is blank (no title).

If the report uses a Report Form, and a title is specified on both, the title on the report takes precedence.

This option generates the TITLE1('left-half') and TITLE2('right-half') operands.

The title is ignored for extracts.

Field rows
One row for each field. The order of the fields in the Report Form dictates the order of the columns in the report or extract. The fields have the following attributes: Field Name, Type (clock and time stamp fields only), Description, Length, Dictionary Definition, User Field Offset and Length (character user fields only).
Field Name
One of the following:
  • The CICS PA field name. For CICS CMF fields, this is usually the Informal name or similar. The names for user fields are derived from the MCT. Use line action S or Prompt (F4) to select from a list of fields applicable to this Form type and CICS version.
  • The Application Group name. For details, see Application Grouping.

    Type an Application Group name in the Field Name column and APG in the Type column, and then press Enter. Otherwise, if you press Enter without APG in the Type column, the panel attempts to interpret the Application Group name as a CMF data field.

    When you add an Application Group to a Report Form, CICS PA adjusts the EOR marker to allow for the maximum width of an Application name (32 characters). However, when producing a report, CICS PA adjusts the Application Group column width to fit the longest Application name in the report.

    Application Groups are stored in an HDB register. Report Forms are independent of HDB registers, so the panel does not validate the Application Group name.

  • The special entry EOR.

    EOR is managed by CICS PA. It signals the end of the report line. The fields listed above EOR fit on the report line and are included in the report in the same order as they appear in the list. Those below EOR will not be reported and are ignored.

    CICS PA automatically sets EOR when the Report Form is created and resets it if necessary when the Form is changed to ensure that the maximum page width of 132 is not exceeded. In positioning EOR, CICS PA allows for one blank separator between each field.

    To produce a report line shorter than 132, either move EOR towards the top of the Form, delete unwanted fields, or move them below EOR.

  • The special entry EOX.

    EOX signals the end of the extract record. There are no restrictions on record length so EOX can be positioned anywhere in the list. EOX is initially positioned just below EOR. Fields above EOX are included in the extract, those below EOX are ignored. If EOX is not specified, EOR is used.

Format Type
Either:
  • The value APG, indicating that the Field Name refers to the name of an Application Group

    or

  • The presentation format of the field.
    For numeric (A) fields, optionally specify one of the following:
    K
    Divide value by 1000, typically for count fields.
    M
    Divide value by 1000000, typically for count fields.
    KB
    Kilobytes (divide by 1024), typically for storage fields.
    MB
    Megabytes (divide by 1024x1024), typically for storage fields.
    For clock (S) fields, you must specify either:
    TIME
    Accumulation of elapsed time in seconds with requested precision of 0.0001 to 0.000001. Default: TIME with PRECISION(4).
    COUNT
    Number of occurrences of the condition.
    For time (T) fields START and STOP, you must specify one of:
    TIMET
    Time in the format hh:mm:ss.thm (default)
    TIMEM
    Time in the format hh:mm
    TIMES
    Time in the format hh:mm:ss
    TIMEP
    Time in one of the following formats, according to the requested precision:
    4 (default)
    hh:mm:ss.thmi
    5
    hh:mm:ss.thmij
    6
    hh:mm:ss.thmiju
    DATE
    Date in the format mm/dd/yyyy
    DATEISO
    Date in the format yyyy-mm-dd
    DATEM
    Date in the format mm/dd
    DATEYR
    Date in the format mm/dd/yy
Fn (Function)
Field function. Specify SEV to indicate that the field is an alert reporting field. That is, the report column will contain the alert severity level when an alert is detected in this transaction field, otherwise this column will contain blanks.
Note:
  1. SEV is only valid for CMF Clock (type S), Count (type A), and CICS PA derived (type D) fields.
  2. If a SEV field is defined in the Form but not in the alert definition, it will always be blank in the report.
  3. If an alert field is defined in the alert definition but there is no equivalent SEV field in the Form, no threshold checking will be performed for that field.
  4. Report Forms created before the introduction of Performance Alerts are automatically upgraded to include Fn (function). This occurs automatically when the Form is edited using the CICS PA dialog.
The example above shows that alerts for fields RESPONSE and CPU(TIME) will be reported in the respective columns in the report.
Field Description
This is a short description of the field. Enter line action H (Help) to see a more detailed description. See Figure 1 for an example of the help details displayed in a pop-up window.
Length
The length of the field in the report or extract. This is used to calculate the width of the print line.
Dictionary Definition
The description of the CMF data field in the format informalname owner xnnn where:
  • informalname is the CMF field name
  • owner is the CICS component that 'owns' the field
  • x indicates the data type:
    • A - 32- or 64-bit count
    • C - character string
    • D - CICS PA derived time
    • P - packed decimal number
    • S - clock (time-count)
    • T - STCK time stamp
    • X - CICS PA calculated count
  • nnn is the field identifier

Some special fields, such as APPLID and RESPONSE, are not defined in the CMF Dictionary and are given an owner of 'CICSPA'. They are either derived from the fixed section of the CMF record (for example, APPLID), or calculated from two or more other CMF fields (for example, RESPONSE).

User Field Offset and Length
This is used for character user fields when only part of the field is to be reported. Offset is the position of the first character and Length is the number of characters from this position to be reported. For example, if the user field contains the value ABCDEFG, then specifying offset 1 and length 4 gives the output ABCD. Both values are required for character user fields and default to the entire field (offset 1 and maximum length).

CICS PA JCL generation translates these values to FIELDS(CHARACTER(SUBSTR(offset,length),...

Line Actions: The following line actions are valid on this panel:
Display the menu of line actions.
S
Select a field name from a list of all CMF fields appropriate to the type of Report Form and CICS release. See Performance field selection for an example of the field selection panel.
I
Insert a blank row after this row for entry or selection of another field.
R
Repeat this row.
RR
Repeat a block of rows bounded by two RRs.
C
Copy this row.
CC
Copy a block of rows bounded by two CCs.
M
Move this row.
MM
Move a block of rows bounded by two MMs.
A
Move⁄Copy after this row.
B
Move⁄Copy before this row.
D
Delete this row.
DD
Delete a block of rows bounded by two DDs.
H
Field Help. Display a detailed explanation of the field. This is the same field selection panel displayed by line action S: see the example in Figure 1.
Note:
  1. Line operations can span the EOR and EOX rows. CICS PA will reset EOR after the operation has completed to ensure the page width is not exceeded. Only one EOR and one EOX is retained, that closest to the top of the list. If EOX is deleted, EOR is assumed to define the length of the extract.
  2. Fields can appear more than once in a Report Form with different types specified. For example: FCWAIT(TIME), FCWAIT(COUNT).
  3. Deleted user fields (LIST and SUMMARY Forms) cannot be recovered.
Primary Commands: The following primary commands are valid for the LIST, LISTX, and SUMMARY Report Form panels:
FIND string
This command (or F) looks for the specified character string in all columns of displayed data. The string is not case sensitive. The display scrolls to the row where the string is found and positions the cursor on the matching data.

To find more occurrences, use F5 or the RFIND command repeatedly.

If there is no match but the search did not begin at the top of the list, the screen does not change and the message *Bottom of data reached* is displayed. Use F5 or RFIND to search from the top. If there is no match in the entire list, the screen does not change and a String not found message is displayed.

Start of changeRUN or JCLEnd of change
Start of changeSpecify run-time options before submitting the Report Form JCL. End of change
SAVE
This command is only available from Edit mode and saves any changes you have made. To save any changes made in View mode, use SAVEAS.

Also available from File in the action bar.

SAVEAS formname|datasetname(formname)
This command is available from both Edit and View mode to save the contents of this Report Form under another name, either in the current data set (assumed if no data set name is provided) or in another suitable data set (if the name of a valid PDS is provided).

Also available from File in the action bar.

RESET
This command (or RES) removes all outstanding line actions and deletes any blank rows.

Also available from Edit in the action bar.

CONFIRM ON|OFF
CONFIRM ON (or CONFIRM) instructs CICS PA to prompt for confirmation when you request to Cancel from the Report Form panel when there have been updates.

With CONFIRM OFF, Cancel requests are actioned immediately, discarding any changes.

This command changes the setting only for the current Edit/View session. On exit, it reverts to the value set by Cancel Confirmation in CICS PA Settings.

Also available from Confirm in the action bar.

UPGRADE vrm
This command is used to upgrade the Report Form to the specified CICS version (vrm) provided it is a later release. CMF Fields for all CICS releases after the current release and up to the specified release are added to the bottom of the Form.

Also available from Upgrade in the action bar.