STAT call

This topic contains Product-sensitive Programming Interface information.

Format

Parameters

db pcb

Specifies the DB PCB used to pass status information to the application program. The VSAM statistics used by the data sets associated with this PCB are not related to the type of statistics that is returned from the STAT call. This PCB must reference a full-function database. This parameter is an input and output parameter.

aib

Specifies the AIB for the call. This parameter is an input and output parameter. These fields must be initialized in the AIB:

AIBID

Eye catcher. This 8-byte field must contain DFSAIBbb.

AIBLEN

AIB lengths. This field must contain the actual length of the AIB that the application program obtained.

AIBRSNM1

Resource name. This 8-byte, left-justified field must contain the name of a full-function DB PCB.

AIBOALEN

I/O area length. This field must contain the length of the I/O area specified in the call list.

i/o area

Specifies an area in the application program that is large enough to hold the requested statistics. This parameter is an output parameter. In PL/I, this parameter should be specified as a pointer to a major structure, array, or character string.

stat function

Specifies a 9-byte area whose content describes the type and format of the statistics required. The first 4 bytes define the type of statistics requested and byte 5 defines the format to be provided. The remaining 4 bytes contain EBCDIC blanks. If the stat function that is provided is not one of the defined functions, an AC status code is returned. This parameter is an input parameter. The 9-byte field contains:

• 4 bytes that define the type of statistics you want:

  DBAS

  OSAM database buffer pool statistics

  DBES

  OSAM database buffer pool statistics, enhanced or extended

  VBAS

  VSAM database subpool statistics

  VBES

  VSAM database subpool statistics, enhanced or extended

• 1 byte that gives the format of the statistics:

  F

  Full statistics to be formatted. If you specify F, your I/O area must be at least 360 bytes for DBAS or VBAS and 600 bytes for DBES or VBES.

  O

  Full OSAM database subpool statistics in a formatted form. If you specify O, your I/O area must be at least 360 bytes.

  S

  Summary of the statistics to be formatted. If you specify S, your I/O area must be at least 120 bytes for DBAS or VBAS and 360 bytes for DBES or VBES.

  U

  Full statistics to be unformatted. If you specify U, your I/O area must be at least 72 bytes.

• 4 bytes of EBCDIC blanks for normal or enhanced STAT call, or bE1b

  Restriction: The extended format parameter is supported by the DBESO, DBESU, and DBESF functions only.

  Extended OSAM buffer pool statistics can be retrieved by including the parameter bE1b following the enhanced call function. The extended STAT call returns all of the statistics returned with the enhanced call, plus the statistics on the coupling facility buffer invalidates, OSAM caching, and sequential buffering IMMED and SYNC read counts.

Usage

The STAT call can be helpful in debugging because it retrieves IMS database statistics. It is also helpful in monitoring and tuning for performance. The STAT call retrieves OSAM database buffer pool statistics and VSAM database buffer supports.

When you request VSAM statistics, each issued STAT call retrieves the statistics for a subpool. Statistics are retrieved for all VSAM local shared resource pools in the order in which they are defined. For each local shared resource pool, statistics are retrieved in ascending order based on buffer size. Statistics for index subpools always follow those for data subpools if any index subpool exists in the shared resource pool. The index subpools are also retrieved in ascending order based on buffer size.

For more information on the STAT call, see IMS Version 15.5 Application Programming.

Restrictions

For function shipping in the CICS environment, the local and remote CICS must both be DBCTL.