Start of change

EXTRACT STATISTICS

Retrieve the current statistics for a single resource, or global statistics for a class of resources.

EXTRACT STATISTICS only deals with the URIMAP, PIPELINE, and WEBSERVICE resources, to COLLECT STATISTICS for other resources see COLLECT STATISTICS.

EXTRACT STATISTICS performs a function equivalent to COLLECT STATISTICS for the resources URIMAP, PIPELINE, and WEBSERVICE. These could not be provided by extending COLLECT STATISTICS due to a design limitation of that command. The syntax of EXTRACT STATISTICS is different and provides for unlimited future expansion.

Read syntax diagramSkip visual syntax diagramExtract STATISTICS
 
>>-EXTRACT STATISTICS--RESTYPE--(--cvda--)---------------------->
 
>--+----------------------------------------------------------+-->
   '-RESID--(--data-area--)--+------------------------------+-'
                             '-RESIDLEN--(--data-value--)---'
 
>--SET--(--ptr-ref--)--+---------------+-----------------------><
                       '-| last time |-'
 

Conditions: INVREQ, IOERR, LENGERR, NOTAUTH, NOTFND

Read syntax diagramSkip visual syntax diagramlast time:
 
|--+-LASTRESET(data-area)----------------+----------------------|
   '-| hours |--| minutes |--| seconds |-'
 
hours:
 
|--LASTRESETHRS(data-area)--------------------------------------|
 
minutes:
 
|--LASTRESETMIN(data-area)--------------------------------------|
 
seconds:
 
|--LASTRESETSEC(data-area)--------------------------------------|
 

Description

The EXTRACT STATISTICS command returns to the invoking application the current statistics for a particular resource, or overall statistics for the resources of a given type.

The statistics that CICS gives you are those that have been accumulated after the expiry of the last statistics extraction interval, end-of-day expiry, or requested reset. (Statistics already written to the SMF data set cannot be accessed.) The EXTRACT STATISTICS command does not cause the statistics counters to be reset.

CICS obtains enough storage for the data returned from this command, and returns a pointer to this area. The first two bytes of the area contain its length. This storage can be reused by subsequent EXTRACT STATISTICS commands, so you should store elsewhere any data that is required beyond the next issue of the command. CICS releases this storage at task termination.

Table 2 contains Product-sensitive Programming Interface information. See Programming interface information for an explanation of Programming Interface information.

Not all resource types provide both global and specific statistics. Table 2 tells you which statistics are available for each resource type, and gives the copybook name for each set of available statistics. The copybooks define the format of the returned statistics. Where no copybook name is given in the global statistics column, global statistics are not available for the resource type; similarly, where there is no entry in the specific statistics column, you cannot get statistics for an individual resource.

Table 2. Resource types and statistics
Resource type CVDA RESIDLEN Statistic type Global statistics Specific statistics
PIPELINE 1124 Char(8) PIPELINE -- DFHPIRDS
URIMAP 1173 Char(8) URIMAP DFHWBGDS DFHWBRDS
WEBSERVICE 1174 Char(32) WEBSERVICE -- DFHPIW DS

Copybooks are provided in ASSEMBLER, COBOL, and PL/I. (There is no copybook for C.) The names of the copybooks are the same in each language. You can find them in the following libraries:

ASSEMBLER CICSTS31.CICS.SDFHMAC
COBOL CICSTS31.CICS.SDFHCOB
PL/I CICSTS31.CICS.SDFHPL1
Note:
Some of the copybooks contain packed fields. Before these fields are used, they should be checked for hexadecimal zeros. The COBOL versions of the fields have been redefined as numeric with a suffix of -R for this purpose.

For further information about these copybooks, see the CICS® Performance Guide.

Options

LASTRESET(data-area)
returns a 4-byte packed decimal field giving the time at which the counters for the requested statistics were last reset. This is usually the time of the expiry of the last interval. The last reset time is always returned in local time.

There are two formats for the reset time:

  • A composite (packed decimal format 0hhmmss+), which you obtain by using the LASTRESET option.
  • Separate hours, minutes, and seconds, which you obtain by specifying the LASTRESETHRS, LASTRESETMIN, and LASTRESETSEC options respectively.
LASTRESETHRS(data-area)
returns a fullword binary field giving the hours component of the time at which the counters for the requested statistics were last reset (see the LASTRESET option).
LASTRESETMIN(data-area)
returns a fullword binary field giving the minutes component of the time at which the counters for the requested statistics were last reset (see the LASTRESET option).
LASTRESETSEC(data-area)
returns a fullword binary field giving the seconds component of the time at which the counters for the requested statistics were last reset (see the LASTRESET option).
RESTYPE(cvda)
requests statistics for a particular resource type depending on the cvda supplied. Valid CVDA values are:
PIPELINE
requests statistics for a PIPELINE; RESID identifies the particular PIPELINE.
URIMAP
requests statistics for a URIMAP; RESID identifies the particular URIMAP.
WEBSERVICE
requests statistics for a WEBSERVICE; RESID identifies the particular WEBSERVICE.
RESID(data-area)
specifies the name of the resource for which statistics are being extracted. The absence of this keyword means that global statistics are to be extracted.
RESIDLEN(data-value)
specifies the length of the RESID data area. If omitted, the default value is the length given in Table 2.
SET(ptr-ref)
specifies a pointer reference to be set to the address of the data area containing the returned statistics. The first 2 bytes of the data area contain the length of the data area in halfword binary form.

Conditions

INVREQ
RESP2 values:
5
An invalid RESTYPE has been specified. Valid types are the cvda values listed in Table 2.
6
A mandatory RESID has NOT been specified for the requested RESTYPE.
IOERR
RESP2 values:
3
The requested statistics area was not functioning. This happens if, for instance, statistics control blocks are overwritten.
LENGERR
RESP2 values:
7
An invalid RESIDLEN was supplied for the requested RESID.
NOTAUTH
RESP2 values:
100
The user associated with the issuing task is not authorized to use this command.
101
The user associated with the issuing task is not authorized to access this particular resource in the way required by this command.
NOTFND
RESP2 values:
1
The requested resource cannot be found (for example, if the WEBSERVICE you specify is not known to CICS).

Examples

e.g.

EXEC CICS EXTRACT STATISTICS URIMAP
or
EXEC CICS EXTRACT STATISTICS RESTYPE(1173) 
or
EXEC CICS EXTRACT STATISTICS RESTYPE(DFHVALUE(URIMAP))

CICS provides a sample EXTRACT STATISTICS application (DFH0STAT) that makes use of virtually all the options described in this section. This set of programs illustrates ways of using the EXTRACT STATISTICS and INQUIRE commands of CICS Transaction Server for z/OS® to produce information about a CICS system. The reports include a CICS and MVS storage analysis that can be used as an aid to specifying the DSA LIMIT parameters.

See the CICS Performance Guide for information on installing and operating the DFH0STAT application. The source code for the application can be found in CICSTS31.CICS.SDFHSAMP.

End of change [[ Contents Previous Page | Next Page Index ]]