COLLECT STATISTICS

Description

The COLLECT STATISTICS 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 collection interval, end-of-day expiry, or requested reset. Statistics already written to the SMF data set cannot be accessed. The COLLECT 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 2 bytes of the area contain its length. This storage can be reused by subsequent COLLECT STATISTICS commands, so 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. JVMPROGRAM and PROGRAM resource types are available on the COLLECT STATISTICS command and are supported as private resources. To extract statistics for private LIBRARY or PROGRAMDEF resource types, use the EXTRACT STATISTICS command. 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.

Not all resource types provide both global and specific, or resource, statistics. Table 1 tells you which statistics are available for each resource type, and gives the copybook, or DSECT, 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 unavailable for the resource type. Where the specific, or resource, statistics column contains no entry, you cannot get statistics for an individual resource.

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:

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

Options

AUTOINSTALL

Requests global statistics on autoinstall.

CONNECTION(data-value)

Requests statistics for a connection to a remote system or region; data-value is the 4-character identifier (from its CONNECTION definition) of the system or region.

DB2CONN

Requests statistics for the CICS DB2 connection including information for pool threads and command threads.

DB2ENTRY(data-value)

Requests statistics for a DB2ENTRY; data-value is the 8-character identifier of the DB2ENTRY (from its DB2ENTRY definition).

DISPATCHER

Requests global statistics on the dispatcher domain.

ENQUEUE

Requests global statistics for enqueue requests.

FILE(data-value)

Requests statistics for a file; data-value is the 8-character identifier of the file (from its FILE definition).

JOURNALNAME(data-value)

Requests statistics for a CICS journal; data-value is an 8-character journal name. CICS returns the address of the area of storage that contains the requested statistics.

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 DFHnn, 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.

JOURNALNUM(data-value)

Requests statistics for a journal; data-value is the number of the journal, in halfword binary format. Journal numbers range from 1 to 99. CICS returns the address of the area of storage that contains the requested statistics.

Specifying JOURNALNUM(1) returns statistics for journal DFHJ01. This journal is not the system log.

Specifying identifiers in the range 1—99 returns statistics for journals DFHJ01 - DFHJ99.

Note: JOURNALNUM continues to be supported for compatibility with earlier releases of CICS. However, the statistics returned are CICS log manager statistics, not journal control statistics. You can map the data at the address returned only by using the DFHLGRDS DSECT which replaces the DFHA13DS DSECT supported at earlier releases.

When you change an application program that use JOURNALNUM, use the JOURNALNAME option instead.

JVMPROGRAM(data-value)

Requests statistics for a Java™ program that runs in a JVM. The data-value is the name of the PROGRAM resource definition.

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.

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

LSRPOOL(data-value)

Requests statistics on a VSAM LSR pool; data-value is the pool number, in the range 1–8, in fullword binary form.

MONITOR(data-value)

Requests performance class statistics for a task when a data-value is supplied. The data-value is the task number, in 4-byte packed decimal format. Without a data-value, MONITOR requests global performance class statistics.

The monitoring performance class must be active for any statistics to be returned. If performance class is not active, the NOTFND condition is returned. For background information about monitoring, see CICS monitoring facility: Performance and tuning.

MVSTCB(data-value)

Requests statistics for an MVS TCB when a data-value is supplied. The data-value is the address of an MVS TCB. Without a data-value, MVSTCB requests global statistics for MVS TCBs in the CICS address space.

POOL(data-value)

Requests statistics for a FEPI pool; data-value is the 8-character name of the pool.

POOL(data-value) TARGET(data-value)

Requests statistics for a FEPI target within a FEPI pool. The POOL data-value identifies the pool, and the TARGET data-value identifies the system within the pool for which statistics are requested.

PROGAUTO

Requests global statistics on the autoinstalled program definitions.

PROGRAM(data-value)

Requests statistics for a program when a data-value is supplied. The data-value is the 8-character name of the PROGRAM definition. Without a data-value, PROGRAM requests the global program statistics. CICS does not collect statistics for programs that run in a JVM when a COLLECT STATISTICS PROGRAM command is issued; you must use the COLLECT STATISTICS JVMPROGRAM command to obtain these statistics.

RECOVERY

Requests global statistics on the recovery manager.

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.

STATS

Requests global statistics on the statistics domain.

STORAGE(data-value)

Requests statistics for a storage domain subpool when a data-value is present. The data-value is the 8-character name of a storage domain subpool. A complete list of the possible subpool names is documented in CICS subpools in the ECDSA. Without a data-value, this option requests the global statistics for the CICS dynamic storage areas.

STREAMNAME(data-value)

Requests statistics for a log stream when a data-value is supplied. The data-value is the 26-character name of the log stream. Without a data-value, STREAMNAME requests the global statistics for the CICS log manager.

SUBPOOLdata-value)

Requests statistics for a storage manager domain subpool. The data-value is the 8-character name of a domain subpool. For tables of the CICS storage manager domain subpools, see CICS subpools in the ECDSA.

SYSDUMPCODE(data-value)

Requests statistics for a system dump code when a data-value is supplied. The data-value is the 8-character dump code. Without a data-value, SYSDUMPCODE requests global statistics on system dumps.

TABLEMGR

Requests global statistics on the table manager.

TARGET (data-value) NODE(data-value)

Requests statistics for a FEPI connection. The NODE data-value is the 8-character name of the terminal which FEPI simulates, and the TARGET data-value is the 8-character name of the system to which FEPI appears as a secondary logical unit.

TASKSUBPOOL

Requests global statistics for the storage manager task subpools.

TCLASS(data-value)

Requests statistics for a transaction class; data-value is the class number, in the range 1-10, in fullword binary form. Transaction classes are no longer identified by number, but instead by an 8-character identifier.

When you use the TCLASS option to request statistics for a class (as opposed to TRANCLASS), a conversion from fullword binary number to 8-character value is made on your behalf (for example, TCLASS(01) becomes the equivalent of TRANCLASS(‘DFHTCL01')).

TCPIP

Requests global statistics for IP sockets.

TCPIPSERVICE(data-value)

Requests the statistics for a TCP/IP service; data-value is the 8-character name of the TCP/IP service.

TDQUEUE(data-value)

Requests statistics for a transient data queue when data-value is supplied. The data-value is the 4-character name of the queue. Without a data-value, TDQUEUE requests the global statistics for transient data.

TERMINAL(data-value)

Requests statistics for a terminal; data-value is the 4-character terminal identifier (from the TERMINAL definition).

TRANCLASS(data-value)

Requests statistics for a transaction class; data-value is the 8-character name of the class from the TRANCLASS definition.

TRANDUMPCODE(data-value)

Requests statistics for a transaction dump code when a data-value is supplied. The data-value is the 4-character dump code. Without a data-value, TRANDUMPCODE requests global statistics on transaction dumps.

TRANSACTION(data-value)

Requests statistics for a transaction when a data-value is supplied. The data-value is the 4-character transaction identifier (from the TRANSACTION definition). Without a data-value, TRANSACTION requests global statistics on transactions.

TSQUEUE

Requests global statistics on temporary storage.

VTAM

Requests global statistics on z/OS Communications Server. VTAM is the previous name for z/OS Communications Server.

Conditions

INVREQ

RESP2 values:

4

The TCLASS value was not in the range 1-10, or the LSRPOOL value was not in the range 1-8.

IOERR

RESP2 values:

3

The requested statistics area was not functioning. This happens if, for instance, statistics control blocks are overwritten.

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:

0

The resource type is obsolete.

1

The requested resource cannot be found. This response is returned if the resource name that you specify is not known to CICS.

2

The resource type is valid but is not defined in the CICS system (for example, FEPI statistics are requested with POOL or NODE when the FEPI system initialization parameter specifies NO).