Changes to the system programming interface

The EXTRACT STATISTICS command

The EXTRACT STATISTICS is added to CICS® to supplement the function of the COLLECT STATISTICS command.

For the PIPELINE, URIMAP, and WEBSERVICE resources, use EXTRACT STATISTICS to retrieve the current statistics for a single resource, or global statistics for a class of resources. EXTRACT STATISTICS only deals with these three resources. To COLLECT STATISTICS for other resources, continue to use the COLLECT STATISTICS command.

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

Read syntax diagramSkip visual syntax diagram
Extract STATISTICS

>>-EXTRACT STATISTICS--RESTYPE(cvda)---------------------------->

>--+--------------------------------------------+--------------->
   '-RESID(data-area)--+----------------------+-'   
                       '-RESIDLEN(data-value)-'     

>--SET(ptr-ref)-+---------------------------------------------------------------------------+-><
                +-LASTRESET(data-area)------------------------------------------------------+   
                '-LASTRESETHRS(data-area)--LASTRESETMIN(data-area)--LASTRESETSEC(data-area)-'   

Conditions: INVREQ, IOERR, LENGERR, NOTAUTH, NOTFND

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.

Not all resource types provide both global and specific statistics. Table 1 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 1. 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 -- DFHPIWDS

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.

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).
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 1.
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.
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 1.
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).