COLLECT STATISTICS

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

Start of changeFor statistics relating to the resources URIMAP, PIPELINE, and WEBSERVICE, see EXTRACT STATISTICS.End of change

Read syntax diagramSkip visual syntax diagramCOLLECT STATISTICS
 
>>-COLLECT STATISTICS SET(ptr-ref)--+---------------+----------->
                                    '-| last time |-'
 
>--| resource types |------------------------------------------><
 

Conditions: INVREQ, IOERR, 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)--------------------------------------|
 
Read syntax diagramSkip visual syntax diagramresource types:
 
|--+-AUTOINSTALL-----------------------------------+------------|
   +-CONNECTION(data-value)------------------------+
   +-CORBASERVER(data-value)--+------------------+-+
   |                          '-BEAN(data-value)-' |
   +-DB2CONN---------------------------------------+
   +-DB2ENTRY(data-value)--------------------------+
   +-DISPATCHER------------------------------------+
   +-ENQUEUE---------------------------------------+
   +-FILE(data-value)------------------------------+
   +-JOURNALNAME(data-value)-----------------------+
   +-JOURNALNUM(data-value)------------------------+
   +-JVMPOOL---------------------------------------+
   +-JVMPROFILE(data-value)------------------------+
   +-JVMPROGRAM(data-value)------------------------+
   +-LSRPOOL(data-value)---------------------------+
   +-MONITOR-+--------------+----------------------+
   |         '-(data-value)-'                      |
   +-MVSTCB-+--------------+-----------------------+
   |        '-(data-value)-'                       |
   +-POOL(data-value)--+--------------------+------+
   |                   '-TARGET(data-value)-'      |
   +-PROGAUTO--------------------------------------+
   +-PROGRAM-+--------------+----------------------+
   |         '-(data-value)-'                      |
   +-RECOVERY--------------------------------------+
   +-REQUESTMODEL(data-value)----------------------+
   +-STATS-----------------------------------------+
   +-STORAGE-+--------------+----------------------+
   |         '-(data-value)-'                      |
   +-STREAMNAME-+--------------+-------------------+
   |            '-(data-value)-'                   |
   +-SUBPOOL(data-value)---------------------------+
   +-SYSDUMPCODE-+--------------+------------------+
   |             '-(data-value)-'                  |
   +-TABLEMGR--------------------------------------+
   +-TARGET(data-value)--NODE(data-value)----------+
   +-TASKSUBPOOL-----------------------------------+
   +-TCLASS(data-value)----------------------------+
   +-TCPIP-----------------------------------------+
   +-TCPIPSERVICE(data-value)----------------------+
   +-TDQUEUE-+--------------+----------------------+
   |         '-(data-value)-'                      |
   +-TERMINAL(data-value)--------------------------+
   +-TRANCLASS(data-value)-------------------------+
   +-TRANDUMPCODE-+--------------+-----------------+
   |              '-(data-value)-'                 |
   +-TRANSACTION-+--------------+------------------+
   |             '-(data-value)-'                  |
   +-TSQUEUE---------------------------------------+
   '-VTAM------------------------------------------'
 

Description

The COLLECT STATISTICS command returns to the invoking application the current statistics for a particular resource, or overall statistics for the resources of a given type. For example, you can get the statistics for global transaction activity in your CICS system (such as the total number of transactions attached), or you can specify a single transaction that you are interested in (such as CEMT).

The statistics that CICS gives you 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 two bytes of the area contain its length. This storage can be reused by subsequent COLLECT 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 1 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 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 Statistic type Global statistics Specific statistics
AUTOINSTALL Terminal autoinstall DFHA04DS -
BEAN Enterprise beans - DFHEJBDS
CONNECTION ISC/IRC system and mode entries - DFHA14DS
CORBASERVER CorbaServer entries - DFHEJRDS
DB2CONN DB2 Connection DFHD2GDS -
DB2ENTRY DB2 Entry - DFHD2RDS
DISPATCHER Dispatcher DFHDSGDS -
ENQUEUE Enqueue DFHNQGDS -
FEPI CONNECTION FEPI Connection - DFHA23DS
FEPI POOL FEPI Pool - DFHA22DS
FEPI TARGET FEPI Target - DFHA24DS
FILE File control - DFHA17DS
JOURNALNAME Journalname - DFHLGRDS
JOURNALNUM Journalname - DFHLGRDS
JVMPOOL JVM pool DFHSJGDS -
JVMPROFILE JVM profiles - DFHSJRDS
JVMPROGRAM JVM programs - DFHPGRDS
LSRPOOL LSR pools - DFHA08DS
MONITOR Monitor DFHMNGDS DFHMNTDS
MVSTCB MVS TCB DFHDSTDS DFHDSRDS
PROGAUTO Program autoinstall DFHPGGDS -
PROGRAM Program DFHLDGDS DFHLDRDS
RECOVERY Recovery manager DFHRMGDS -
REQUESTMODEL Request models - DFHIIRDS
STATS Statistics DFHSTGDS -
STORAGE Storage manager (SM) DFHSMSDS DFHSMDDS
STREAMNAME Log stream DFHLGGDS DFHLGSDS
SUBPOOL SM domain subpool - DFHSMDDS
SYSDUMPCODE Dump (system) DFHSDGDS DFHSDRDS
TABLEMGR Table manager DFHA16DS -
TASKSUBPOOL SM task subpool DFHSMTDS -
TCLASS Transaction class - DFHXMCDS
TCPIP Sockets domain DFHSOGDS -
TCPIPSERVICE TCP/IP service - DFHSORDS
TDQUEUE Transient data DFHTQGDS DFHTQRDS
TERMINAL Terminals - DFHA06DS
TRANCLASS Transaction class - DFHXMCDS
TRANDUMPCODE Dump (transaction) DFHTDGDS DFHTDRDS
TRANSACTION Transaction manager DFHXMGDS DFHXMRDS
TSQUEUE Temporary storage DFHTSGDS
VTAM VTAM DFHA03DS -

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

AUTOINSTALL
requests global statistics on autoinstall.
BEAN(data-value)
requests statistics for an enterprise bean; data-value is the 1-240 character name of the bean.

Because a bean of the same name may exist in multiple CorbaServers, if you specify this option you must also specify CORBASERVER.

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.
CORBASERVER(data-value)
requests statistics for a CorbaServer; data-value is the 4-character name of the CorbaServer.
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 to 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 half-word 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. Note that this 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 releases of CICS earlier than CICS Transaction Server for z/OS®. 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 make changes to application programs that use JOURNALNUM, you are recommended to use the JOURNALNAME option.

JVMPOOL
requests statistics for the JVM pool, if one exists. (There is no identifier on JVMPOOL: a CICS region can have only one JVM pool.) CICS returns the address of the area of storage that contains the requested statistics.
JVMPROFILE(data-value)
requests statistics for a JVM profile. The data-value is the 8-character name of the JVM profile.

When you use the name of a JVM profile anywhere in CICS, you must enter it using the same combination of upper and lower case characters that is present in the HFS file name.

JVMPROGRAM(data-value)
requests statistics for a Java program that runs in a JVM. The data-value is the name of the program's 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 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).
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. (For programming information, see EIBTASKN in Appendix A of the CICS Application Programming Reference manual.) 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 on monitoring, see the CICS Performance Guide.

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 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 need to use the COLLECT STATISTICS JVMPROGRAM command to obtain these statistics.
RECOVERY
requests global statistics on the recovery manager.
REQUESTMODEL(data-value)
requests statistics for a request model; data-value is the 8-character name of the request model resource definition.
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 the CICS Performance Guide. Without a data-value, this option requests the global statistics for the CICS dynamic storage areas.
STREAMNAME(data-value)
requests statistics for a logstream when a data-value is supplied. The data-value is the 26-character name of the logstream. 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 the CICS Performance Guide
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 VTAM.

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:
1
The requested resource cannot be found (for example, if the JOURNALNAME you specify is not known to CICS).
2
The type of resource 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).
Note:
Start of change
NOTFND is also returned if you attempt to use COLLECT STATISTICS PROGRAM when you should use COLLECT STATISTICS JVMPROGRAM. See Collecting statistics for Java programs that run in a JVM for additional information.
End of change

Examples

CICS provides a sample COLLECT STATISTICS application (DFH0STAT) that makes use of virtually all the options described in this section. This set of programs illustrates ways of using the COLLECT 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.

Start of changeRestrictionsEnd of change

Start of change

Collecting statistics for Java programs that run in a JVM

Statistics for Java programs that run in a JVM are collected separately from statistics for other programs, because the JVM programs are not loaded by CICS. CICS does not collect statistics for JVM programs when a COLLECT or PERFORM STATISTICS PROGRAM command is issued; to see them, you need to use the COLLECT or PERFORM STATISTICS JVMPROGRAM command instead.

However, when you browse program names using the INQUIRE PROGRAM command, JVM programs are found. If you have an application that collects statistics for programs by browsing with the INQUIRE PROGRAM command, and then issuing the COLLECT STATISTICS PROGRAM command for the program names that it finds, the application will now receive a "not found" response when it attempts to collect statistics for any JVM programs. (Previously, zeros would have been returned as statistics values for these programs.)

To avoid receiving this response, make the application check the RUNTIME value for each program name that it finds. If the RUNTIME value is JVM, the application should not issue the COLLECT STATISTICS PROGRAM command for that program name. If you want to see the statistics for programs with a RUNTIME value of JVM, you can make the application issue the COLLECT STATISTICS JVMPROGRAM command for those programs. Note that the statistics information that is collected for JVM programs is not the same as that collected for other programs.

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