EXTRACT STATISTICS
Retrieve the current statistics for a single resource, or global statistics for a class of resources.
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.
- 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.
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 | 1144 | 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 | 1165 | — | TCPIP | DFHSOGDS | — |
TCPIPSERVICE | 1166 | 8 | TCPIPSERVICE | — | DFHSORDS |
TDQUEUE | 1167 | 4 | TDQUEUE | DFHTQGDS | DFHTQRDS |
TRANCLASS | 1169 | 8 | TRANCLASS | — | DFHXMCDS |
TRANDUMPCODE | 1170 | 4 | TRANDUMPCODE | DFHTDGDS | DFHTDRDS |
TRANSACTION | 1171 | 4 | TRANSACTION | DFHXMGDS | DFHXMRDS |
TSQUEUE | 1172 | — | 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 | CICSTS52.CICS.SDFHMAC |
C | CICSTS52.CICS.SDFHC370 |
COBOL | CICSTS52.CICS.SDFHCOB |
PL/I | CICSTS52.CICS.SDFHPL1 |
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.
- A composite format (packed decimal format
- 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 specfied 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 CICSTS52.CICS.SDFHSAMP.