EXTRACT STATISTICS

Description

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

The statistics that CICS returns 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 must store elsewhere any data that is required beyond the next issue of the command. CICS releases this storage at task termination.

For resource types that are supported as private resources for applications deployed on platforms, different statistics records are written for public resources and for private resources, each mapped by a different copybook, or DSECT. LIBRARY, JVMPROGRAM, PROGRAM, and PROGRAMDEF resource types are supported as private resources. If a resource is a public resource, the public copybook is used to map its data, and if a resource is a private resource, the private copybook is used to map its data.

When you use the EXEC CICS EXTRACT STATISTICS or EXEC CICS COLLECT STATISTICS command to return statistics for a specified program that is declared as an application entry point, only one statistics record is returned. If the command is issued in or for an application context, and the program was defined as a private resource for the application, the DSECT for private resources is used to format the data, even if the program has currently been promoted to a public program in order to make the application entry point available.

Copybooks are provided in ASSEMBLER, C, COBOL, and PL/I.

The names of the copybooks are the same in each language. You can find them in the following libraries. Note that in the following table, CICSTSnn is your CICS release.

For further information about these copybooks, see Introduction to CICS statistics.

Options

APPLICATION(data-value)

Specifies the application name element of the application context. The application name can be up to 64 characters in length.

Specify the application context to return statistics for a private resource that is part of an application deployed on a platform. Statistics for private resources can only be returned as specific, or resource, statistics for a named resource of the JVMPROGRAM, LIBRARY, PROGRAM, or PROGRAMDEF resource types, which are supported as private resources. You must specify a complete application context, including the platform name, application name, and full application version number. If the private resource that you name on the RESID option is not found in the specified application context, no statistics are returned.

You do not need to specify an application context if the command is issued from a program that is part of the relevant application. By default, CICS returns statistics for a private resource from the application where the command is issued, or statistics for a public resource if no private resource can be found.

APPLMAJORVER(data-value)

Specifies the application major version element of the application context, in fullword binary form.

APPLMINORVER(data-value)

Specifies the application minor version element of the application context, in fullword binary form.

APPLMICROVER(data-value)

Specifies the application micro version element of the application context, in fullword binary form.

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 time is usually when the last interval expired. The last reset time is always returned in local time.

The reset time has two formats:

• A composite format (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.

LASTRESETABS(data-area)

Returns an 8-byte packed decimal field giving the time at which the counters for the requested statistics were last reset. The returned value is in ABSTIME format. ABSTIME specifies the number of milliseconds since 00:00 on 1 January 1900, which is known as absolute time.

You can use FORMATTIME to change the data into other familiar formats.

The format of data-area is:

COBOL:  PIC S9(15) COMP-3
C:      char data_area[8];
PL/I:   FIXED DEC(15)
ASM:    PL8

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

PLATFORM(data-value)

Specifies the platform name element of the application context. The platform name can be up to 64 characters in length.

RESTYPE(cvda)

Requests statistics for a particular resource type depending on the CVDA value supplied. Valid CVDA values are as follows:

ASYNCSERVICE

Request global statistics for the asynchronous services domain.

ATOMSERVICE

Request statistics for an ATOMSERVICE resource; RESID identifies the particular ATOMSERVICE resource definition.

BUNDLE

Request statistics for a BUNDLE resource; RESID identifies the particular BUNDLE resource definition.

DB2CONN

Request statistics for the CICS-Db2® connection including information for pool threads and command threads.

DB2ENTRY

Request statistics for a DB2ENTRY; RESID identifies the particular DB2ENTRY.

DISPATCHER

Request statistics for the dispatcher domain.

DOCTEMPLATE

Request statistics for a document template; RESID identifies the particular DOCTEMPLATE resource definition.

ENQUEUE

Request statistics for enqueue requests.

EPADAPTER

Request statistics for an EPADAPTER resource; RESID identifies the particular EPADAPTER resource definition.

EVENTBINDING

Request statistics for a particular EVENTBINDING resource; RESID identifies the particular EVENTBINDING resource definition.

EVENTPROCESS

Request global statistics on the event processing domain.

FILE

Request statistics for a file. RESID identifies the particular file definition.

IPCONN

Request statistics for an IPCONN resource; RESID identifies the particular IPCONN resource definition.

JOURNALNAME

Request statistics for a CICS journal. RESID identifies the particular journal. To collect statistics for journals defined using the journal numbering convention (for example, for the auto journals defined in file resource definitions), specify the name as DFHJnn, where nn is the journal number in the range 01 - 99.

Note: Specifying DFHJ01 returns statistics written to a user journal of that name, not the system log.

JVMPROGRAM

Request statistics for a Java™ program. RESID identifies the particular PROGRAM resource definition.

JVMSERVER

Request statistics for a JVMSERVER resource; RESID identifies the particular JVMSERVER resource definition.

LIBRARY

Request statistics for a LIBRARY resource; RESID identifies the particular LIBRARY resource definition.

LSRPOOL

Request statistics on a VSAM LSR pool; RESID identifies the particular pool, in the range 1–255, in fullword binary form.

MONITOR

Request statistics for the monitoring domain. RESID identifies a particular task, in 4-byte packed decimal format, for which performance class statistics are to be returned.

MQCONN

Request statistics for a IBM® MQ connection.

MQMONITOR

Request statistics for an MQ monitor. RESID identifies a particular MQ monitor.

MVSTCB

Request statistics for z/OS® TCBs. RESID identifies the address of a particular TCB.

PIPELINE

Request statistics for a PIPELINE resource; RESID identifies the particular PIPELINE resource definition.

POLICY

Combined with POLICYRULE, request statistics for a policy rule. RESID identifies the particular POLICY resource definition that contains the policy rule.

Note: Both POLICY and POLICYRULE must be specified in your request; if either is missing, your request will fail with INVREQ condition.

PROGAUTO

Request statistics on the auto-installed program definitions.

PROGRAM

Request statistics for non-Java programs. RESID identifies a particular program.

PROGRAMDEF

Request statistics on a program definition. RESID identifies a particular program.

RECOVERY

Request statistics for the recovery manager domain.

SECURITY

Request statistics for the security domain.

STATS

Request statistics on the statistics domain.

STORAGE

Request statistics for a storage domain. A RESID specifies statistics to be returned for a particular storage domain subpool. A complete list of the possible subpool names is documented in CICS subpools in the ECDSA.

SUBPOOL

Request statistics for a storage manager domain subpool. The RESID specifies the particular storage domain subpool. A complete list of the possible subpool names is documented in CICS subpools in the ECDSA.

STREAMNAME

Request statistics for the CICS log manager domain, or if RESID is specified a particular log stream.

SYSDUMPCODE

Request statistics on system dumps, or if RESID is specified a particular system dump code.

TASKSUBPOOL

Request statistics for a storage manager task subpool.

TCPIP

Request statistics for IP sockets.

TCPIPSERVICE

Request statistics for a TCP/IP service; RESID identifies the particular TCP/IP service.

TASKSUBPOOL

Request statistics for a storage manager task subpools.

TDQUEUE

Requests statistics for transient data, or if a RESID is specified, a particular transient data queue.

TRANCLASS

Request statistics for a transaction class. RESID identifies the particular TRANCLASS definition.

TRANDUMPCODE

Request statistics on transaction dumps, or if RESID is specified, a particular transaction dump code.

TRANSACTION

Request statistics on transactions, or if RESID is specified, a particular transaction.

TSQUEUE

Request statistics on temporary storage.

URIMAP

Request statistics for a URIMAP resource; RESID identifies the particular URIMAP resource definition.

USER

Request statistics for the user domain.

WEBSERVICE

Request statistics for a WEBSERVICE resource; RESID identifies the particular WEBSERVICE resource definition.

XMLTRANSFORM

Request statistics for an XMLTRANSFORM resource; RESID identifies the particular XMLTRANSFORM resource definition.

RESID(data-area)

Specifies the name of a particular resource for which statistics are to be returned. The absence of this keyword means that global statistics are to be extracted. RESID is a character field.

If RESID is specified, resource security check will be performed on the CICS resource. Therefore, the user issuing EXTRACT STATISTICS needs READ access to the resource.

RESIDLEN(data-value)

Specifies the length of the RESID data area. If omitted, the default value is the length given in Table 1.

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.

SUBRESTYPE(cvda)

Requests statistics for a particular resource type depending on the CVDA value supplied. For usage, see Table 1. Valid CVDA values are as follows:

CAPTURESPEC

Request statistics for a capture specification. This subrestype parameter is optional.

POLICYRULE

Request statistics for a policy rule that is contained in a particular POLICY resource. This subrestype parameter is required. See Note.

SUBRESID(data-area)

Specifies the name of the particular resource for which statistics are being extracted. The absence of this keyword means that statistics for the specified RESTYPE are to be extracted. SUBRESID is a character field.

If SUBRESID is specified, resource security check will be performed on the CICS resource. Therefore, the user issuing EXTRACT STATISTICS needs READ access to the resource.

SUBRESIDLEN(data-value)

Specifies the length of the SUBRESID data area. If omitted, the default value is the length given in Table 1.

Conditions

APPNOTFOUND

RESP2 values:

1

The command has been issued specifying an application context, but the named application is not found.

INVREQ

RESP2 values:

5

An invalid RESTYPE has been specified. Valid types are listed in Table 1.

6

A mandatory RESID has not been specified for the requested RESTYPE.

8

An invalid SUBRESTYPE has been specified. Valid types are listed in Table 1.

9

A mandatory SUBRESID has not been specified for the requested SUBRESTYPE.

11

An invalid RESTYPE and SUBRESTYPE combination has been specified. Valid types are listed in Table 1.

IOERR

RESP2 values:

3

The requested statistics area was not functioning. This problem occurs if, for example, statistics control blocks are overwritten.

LENGERR

RESP2 values:

7

An invalid RESIDLEN was supplied for the requested RESID.

10

An invalid SUBRESIDLEN was supplied for the requested SUBRESID.

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.

2

The type of resource is not defined in the CICS system; for example, if FEPI statistics are requested with POOL or NODE when the FEPI system initialization parameter specifies NO.

6.2beta 3

Performance class data for the task is not available. At the time the task is initialized, monitoring is switched off; or the monitoring performance class is not active.