COLLECT STATISTICS

Obtains either the current statistics for a single named resource or the global statistics for a named resource type.

Syntax


COLLECT STATISTICS

>>-COLLECT STATISTICS--SET(ptr-ref)----------------------------->

>--+-LASTRESET(hhmmss)---------------------------------------------------------+-->
   '-LASTRESETHRS(data-area)--LASTRESETMIN(data-area)--LASTRESETSEC(data-area)-'   

>--+-DUMP----------------------+-------------------------------><
   +-FILE(data-value)----------+   
   +-INTERSYSTEM(data-value)---+   
   +-JOURNAL-------------------+   
   +-PROGRAM--+--------------+-+   
   |          '-(data-value)-' |   
   +-RUNTIMEDB-----------------+   
   +-STORAGE-------------------+   
   +-TASK----------------------+   
   +-TDQUEUE--+--------------+-+   
   |          '-(data-value)-' |   
   +-TERMINAL(data-value)------+   
   +-TRANSACTION(data-value)---+   
   +-TSQUEUE-------------------+   
   '-UNITOFWORK----------------'

Conditions: NOTFND

Note:

FILE has eight characters.
INTERSYSTEM has four characters.
LASTRESET is not supported in C or C++ programs.
PROGRAM has eight characters.
STORAGE provides statistics for all storage subpools.
TDQUEUE has four characters.
TERMINAL has four characters.
TRANSACTION has four characters.

Description

COLLECT STATISTICS returns to the calling application the current statistics for a single named resource, or the global statistics for a named resource type. For example, you can get the summary statistics that relate to all the programs in your region, or you can specify a single global statistic in which you are interested. However, not all the resource types provide both global and specific statistics; for further information about this, see Options.

On each COLLECT STATISTICS command, you can request the statistics that are associated with only one resource or resource type.

The statistics that CICS® returns to you are those that have been accumulated since the statistics counters were last reset by the expiry of an interval, by an end-of-day collection, or by a PERFORM STATISTICS RECORD ALL RESETNOW command. CICS writes statistics to an operating system byte stream file; after the statistics have been written to a file, you cannot access them with the COLLECT STATISTICS command. The COLLECT STATISTICS command does not cause CICS to reset the statistics counters.

CICS obtains enough storage for the data that is returned from this command, and returns a pointer to this area.

This storage can be reused by subsequent COLLECT STATISTICS commands, so you must store elsewhere any data that can be required beyond the next issue of the command. CICS releases storage at task termination.

Options

resource

The syntax that is given for the COLLECT STATISTICS command shows the various resource types for which you can request statistics and, where applicable, the format of the associated data-value argument that is to be used when you request the statistics for a specific resource. The following restrictions apply:

You can request only global statistics for the following resource types: DUMP, JOURNAL, RUNTIMEDB, STORAGE, TASK, TSQUEUE, and UNITOFWORK.
You can request either global statistics or specific statistics for the following resource types: PROGRAM and TDQUEUE.
You can request only specific statistics for the following resource types: FILE, INTERSYSTEM, TERMINAL, and TRANSACTION.

LASTRESET(hhmmss)

(This option is for COBOL only.) The option specifies a packed decimal field, declared as PIC S9(7) COMP-3, to receive the time at which the statistics counters for this resource or resource type were last reset. This is usually the time of the expiry of the last interval. See Replaced arguments when programming with COBOL.

C or C++ programs must use the separate LASTRESETHRS, LASTRESETMIN, and LASTRESETSEC options instead.

LASTRESETHRS(data-area)

Specifies a 32-bit binary field that is to receive the time in hours at which CICS last reset the statistics counters for this resource or resource type.

LASTRESETMIN(data-area)

Specifies a 32-bit binary field that is to receive the time in minutes at which CICS last reset the statistics counters for this resource or resource type.

LASTRESETSEC(data-area)

Specifies a 32-bit binary field that is to receive the time in seconds at which CICS last reset the statistics counters for this resource or resource type.

SET(ptr-ref)

Specifies a pointer reference that is to be set to the address of the data area that contains the returned statistics. The number of statistics records that are contained in the data area is given at the start of the area. COBOL copybooks and C or C++ include files are provided to allow you to map the returned statistics. You can find these copybooks in the installed include directory in CICS-STAT for MicroFocus COBOL, and in CICS-STAT1 (for the working-storage section) and CICS-STAT2 (for the linkage section) for IBM® COBOL programs. You can find the include files in cics_stat.h, in the installed include directory. See INTO and SET for more information about using this option.

Conditions

NOTFND: Occurs if CICS cannot find the named resource.
Default action: Terminates the task abnormally.