EXTRACT STATISTICS

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

The EXTRACT STATISTICS command can be used to obtain statistics for all CICS® resource types except AUTOINSTALL, CONNECTION, FEPI CONNECTION, FEPI POOL, FEPI TARGET, JOURNALNUM, TABLEMGR, TCLASS, TERMINAL and VTAM® for which the COLLECT STATISTICS command must be used.

Extract STATISTICS

subrestype

applcontext

last time

hours

minutes

seconds

Conditions: APPNOTFOUND, INVREQ, IOERR, LENGERR, NOTAUTH, NOTFND

This command is threadsafe.

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 request resource statistics for a specific resource of a resource type that is supported as a private resource, the command operates according to the context in which the task is running.

If the command is issued from a public program, statistics are returned for the named public resource.
If the command is issued from a program that is part of an application deployed on a platform, so is running with an application context, the private resources for the application are searched first for the named resource. If a private resource is not found, statistics are returned for the named public resource.
For the EXEC CICS EXTRACT STATISTICS command only, you can specify a different application context to be searched for private resources. When you request statistics for a different application, if a private resource is not found for that application, no statistics are returned.

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.

Table 1 contains Product-sensitive Programming Interface information.

Table 1. Resource types and statistics
Resource type	CVDA	RESIDLEN	Statistic type	Global statistics	Specific statistics
ATOMSERVICE	1179	8	ATOMSERVICE	—	DFHW2RDS
BUNDLE	1180	8	BUNDLE	—	DFHRLRDS
DB2CONN	1142	—	DB2CONN	DFHD2GDS	—
DB2ENTRY	1143	8	DB2ENTRY	—	DFHD2RDS
DISPATCHER	1144	—	DISPATCHER	DFHDSGDS	—
DOCTEMPLATE	1145	8	DOCTEMPLATE	—	DFHDHDDS
EPADAPTER	1196	32	EPADAPTER	—	DFHEPRDS
ENQUEUE	1146	—	ENQUEUE	DFHNQGDS	—
EVENTBINDING	1191	32	EVENTBINDING	DFHECGDS	DFHECRDS
CAPTURESPEC subresource type	1195	32	EVENTBINDING	—	DFHECCDS
EVENTPROCESS	1192	—	EVENTPROCESS	DFHEPGDS	—
FILE	238	8	FILE	—	DFHA17DS
IPCONN	1176	8	IPCONN	—	DFHISRDS
JOURNALNAME	1147	8	JOURNALNAME	—	DFHLGRDS
JVMPROGRAM	1151	8	JVMPROGRAM	—	DFHPGRDS (public) DFHPGPDS (private
JVMSERVER	1193	8	JVMSERVER	—	DFHSJSDS
LIBRARY	1177	8	LIBRARY	—	DFHLDBDS (public) DFHLDYDS (private
LSRPOOL	1152	4	LSRPOOL	—	DFHA08DS
MONITOR	1153	4	MONITOR	DFHMNGDS	DFHMNTDS
MQCONN	1175	—	MQCONN	DFHMQGDS	—
MVSTCB	1154	4	MVSTCB	DFHDSTDS	DFHDSRDS
PIPELINE	1124	8	PIPELINE	—	DFHPIRDS
PROGAUTO	1072	—	PROGAUTO	DFHPGGDS	—
PROGRAM	154	8	PROGRAM	DFHLDGDS	DFHLDRDS (public) DFHLDPDS (private
PROGRAMDEF	1178	8	PROGRAMDEF	—	DFHPGDDS (public) DFHPGEDS (private
RECOVERY	1156	—	RECOVERY	DFHRMGDS	—
STATS	1158	—	STATS	DFHSTGDS	—
STORAGE	1159	8	STORAGE	DFHSMSDS	DFHSMDDS
STREAMNAME	1160	26	STREAMNAME	DFHLGGDS	DFHLGSDS
SUBPOOL	1161	8	SUBPOOL	—	DFHSMDDS
SYSDUMPCODE	1162	8	SYSDUMPCODE	DFHSDGDS	DFHSDRDS
TASKSUBPOOL	1164	—	TASKSUBPOOL	DFHSMTDS	—
TCPIP	802	—	TCPIP	DFHSOGDS	—
TCPIPSERVICE	1166	8	TCPIPSERVICE	—	DFHSORDS
TDQUEUE	767	4	TDQUEUE	DFHTQGDS	DFHTQRDS
TRANCLASS	1169	8	TRANCLASS	—	DFHXMCDS
TRANDUMPCODE	1170	4	TRANDUMPCODE	DFHTDGDS	DFHTDRDS
TRANSACTION	1171	4	TRANSACTION	DFHXMGDS	DFHXMRDS
TSQUEUE	768	—	TSQUEUE	DFHTSGDS	—
URIMAP	1173	8	URIMAP	DFHWBGDS	DFHWBRDS
WEBSERVICE	1174	32	WEBSERVICE	—	DFHPIWDS
XMLTRANSFORM	1194	32	XMLTRANSFORM	—	DFHMLRDS

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:

Language	Library
ASSEMBLER	CICSTS53.CICS.SDFHMAC
C	CICSTS53.CICS.SDFHC370
COBOL	CICSTS53.CICS.SDFHCOB
PL/I	CICSTS53.CICS.SDFHPL1

Note: Some of the copybooks contain packed fields. Before these fields are used, check them 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 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.

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:

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 WebSphere® MQ connection.
MVSTCB: Request statistics for MVS™ TCBs. RESID identifies the address of a particular TCB.
PIPELINE: Request statistics for a PIPELINE resource; RESID identifies the particular PIPELINE resource definition.
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.
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 subpools.
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 is 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.
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. The subrestype parameter is optional; for usage see Table 1. Valid CVDA values are as follows:

CAPTURESPEC: Request statistics for a capture specification.

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.

Examples

EXEC CICS EXTRACT STATISTICS URIMAP
or
EXEC CICS EXTRACT STATISTICS RESTYPE(1173) 
or
EXEC CICS EXTRACT STATISTICS RESTYPE(DFHVALUE(URIMAP))

CICS provides a sample EXTRACT STATISTICS application, DFH0STAT, that uses the options described in this topic. This set of programs illustrates ways of using the EXTRACT STATISTICS and INQUIRE commands 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 sample statistics program, DFH0STAT for information about installing and operating the DFH0STAT application. The source code for the application is in CICSTS53.CICS.SDFHSAMP.