File control statistics

There are four sections in the DFHSTUP report for file statistics, dealing with resource information, requests information, data table requests information, and performance information.

Unsolicited file statistics are printed in a statistics report separate from other types of CICS® statistics.

These statistics can be accessed online using the EXEC CICS COLLECT STATISTICS FILE command, and are mapped by the DFHA17DS DSECT. For programming information about the EXEC CICS COLLECT STATISTICS command, see the CICS System Programming Reference manual.

This section contains the following statistics:

Files: Resource statistics - resource information

Table 61. Files: Resource statistics - resource information
DFHSTUP name Field name Description
File name A17FNAM is the name you specified in the DEFINE FILE command of resource definition online.

Reset characteristic: not reset

 

Dataset name A17DSNAM is the 44-character name defining the physical data set to the system. You may have specified this in:
  • The DSNAME operand specified in the DEFINE FILE command of resource definition online
  • The operand specified in the DD DSN= operand of the CICS JCL
  • By dynamic allocation of a data set to a file through the use of CEMT SET FILE DSNAME or EXEC CICS SET FILE DSNAME commands.
If no data set is currently allocated to the file, this field is blank.

If the file is remote, no data set name is printed but the word "remote" is substituted for the data set name.

Reset characteristic: not reset

 

Base dataset name (if applicable) A17BDSNM In the instance that the file is a VSAM PATH, this field gives the base data set name.

Reset characteristic: not reset.

 

Dataset type A17DSTYP is the data set type, which can be BDAM, ESDS, KSDS, RRDS or PATH. If the file is remote or not open, this field is blank.

Reset characteristic: not reset.

 

RLS A17DSRLS is an indicator of whether the file is RLS or not.
  • 'R' =RLS accessed file
  • ' ' =Non-RLS
These are shown as "Yes" and "No" respectively in the DFHSTUP report.

Reset characteristic: not reset.

 

DataTable indicator A17DT is a one-byte field that contains the value "R", or "S" or "T", or "L" or "K", or "X", if data table statistics fields are present in the record.
  • "R" indicates that this is a remote file for which table read and source read statistics are present.
  • "S" indicates that the resource was not opened as a table but was able to access data from a table associated with the same data set.
  • "T" indicates that the resource is a shared data table.
  • "L" indicates that the resource is a coupling facility data table (locking model).
  • "K" indicates that the resource is a coupling facility data table (contention model).
  • "X" indicates that the resource has been opened with a source data set which has an associated CICS maintained data table and the resource has been updated which has caused the data table to also be updated.

Reset characteristic: not reset

 

Time opened A17LOPNT is the time at which this file was opened. If this field is not set, A17LOPNT contains the hexadecimal value X'00000000 00000000', shown in the report as "CLOSED". If the field is set, it contains a time expressed as a store clock (STCK) value in local time.

This field contains a valid time if:

  • The file was open at the time the statistics were taken.
  • This is an unsolicited statistics request due to the file being closed.

Reset characteristic: not reset

 

Time closed A17LCLST is the time at which this file was closed. If this field is not set, A17LCLST contains the hexadecimal value X'00000000 00000000', shown in the report as "OPEN". If the field is set, it contains a time expressed as a store clock (STCK) value in local time.

Reset characteristic: not reset

 

Remote Name A17RNAME The name by which this file is known in the system or region in which it is resident.

Reset characteristic: not reset.

 

Remote Sysid A17RSYS When operating in an ISC or MRO environment, and the file is held by a remote system, this field specifies the system upon which the file is resident.

Reset characteristic: not reset.

 

LSR A17POOL

The identity of the local shared resource pool. This value is that specified by:

  • The LSRPOOLID operand of the resource definition online DEFINE FILE command.

"N" means that it is not defined in an LSR pool. Reset characteristic: not reset.

 

CFDT PoolName A17DTCFP The name of the coupling facility data table pool defined for the data table associated with the file

Reset characteristic: not reset

 

NOT IN THE DFHSTUP REPORT A17FLOC states whether the file is defined as being local to this CICS system, or resides on a remote CICS system. The field is one byte long, and is set to "R" if remote.

Reset characteristic: not reset

 

Note:
When the source data set of a user-maintained table is closed, the "time opened" is reset to the time at which the source was closed.

Files: Resource statistics - requests information

The following eight items are service request statistics. They do not tell you directly how many I/O accesses are being carried out for each transaction (a single-transaction measurement is required for this). Nevertheless, by regularly totaling the service requests against individual data sets, they can enable you to anticipate data set problems when I/O activity increases.

They list the number of service requests processed against the data set. These are dependent on the type of requests that are allowed on the data set.

Table 62. Files: Resource statistics - requests information
DFHSTUP name Field name Description
File name A17FNAM is the name you specified in:
  • The DEFINE FILE command of resource definition online
  • (for BDAM files only) The TYPE=FILE, FILE operand of the DFHFCT macro.

Reset characteristic: not reset

 

GET requests A17DSRD is the number of GET requests attempted against this file.

Reset characteristic: reset to zero

 

GET upd requests A17DSGU is the number of GET UPDATE requests attempted against this file.

Reset characteristic: reset to zero

 

Browse requests A17DSBR is the number of GETNEXT and GETPREV requests attempted against this file.

Reset characteristic: reset to zero

 

Update requests A17DSWRU is the number of PUT UPDATE requests attempted against this file.

Reset characteristic: reset to zero

 

Add requests A17DSWRA is the number of PUT requests attempted against this file.

Reset characteristic: reset to zero

 

Delete requests A17DSDEL is the number of DELETE requests attempted against this file.

Reset characteristic: reset to zero

 

Brws upd requests A17DSBRU is the number of browse READNEXT UPDATE and READPREV UPDATE requests issued against this file.

Note that this field is only applicable to RLS accessed files.

Reset characteristic: reset to zero

 

VSAM EXCP requests
-Data A17DSXCP A value is printed if the file has been opened and used as a VSAM KSDS during the CICS run, even if the file is not being used as a KSDS at the time of taking statistics. See notes 1, 2 and 3.

 

-Index A17DSIXP See notes 1, 2 and 3.

Reset characteristic: reset to zero

 

RLS req timeouts A17RLSWT is the number of RLS requests made to this file that were not serviced in the specified time limit, and therefore the requests were terminated.

Reset characteristic: reset to zero

 

Notes:
The "VSAM EXCP requests" fields indicate the number of I/O operations on the file for data and index records respectively. Also, note the following points:
  1. The values printed for both items relate to the file. If dynamic allocation has been used to change the physical data sets associated with a file, the value shown is an accumulation for all the data sets.
  2. Take care when using these values for files participating in data set name sharing, because VSAM maintains only one count of EXCPs for all access method control blocks (ACBs) thus connected. In this situation, the value reported against each file represents the total accesses for all sharing ACBs during the period for which the file was open. (Therefore, if all files in the data set name sharing group were open for the same period, each file would have the same EXCP values reported against it, which would be the total for all the files in the group.)
  3. For RLS, this value is a count of the number of calls to the system buffer manager. It includes calls that result in either a coupling facility cache access or an I/O.
  4. The EXCP count for RLS files is the count of all EXCPs for all tasks accessing the RLS file within that CICS region. It should be noted as stated in note 2, EXCP counts are stored in the file's corresponding ACB within that CICS region.

 

Files: Resource statistics - data table requests information

If the file is a data table, further fields are present in the statistics record. The presence of these additional fields is indicated by the value R, S, T, L, K, or X in the field A17DT. Their names and meanings are as follows:

Table 63. Files: Resource statistics - data table requests information
DFHSTUP name Field name Description
File Name A17FNAM is the name you specified in the DEFINE FILE command of resource definition online.

Reset characteristic: not reset

 

Close type A17DTTYP This one-byte field is set to:
  • "C" when a CICS maintained table is closed
  • "P" when a file which has been accessing a CICS-maintained table is closed but the table remains open because there are other files still open which are using the table
  • "S" when the source data set for a user-maintained table is being closed
  • "U" when a user maintained table is closed
  • "L" when a locking model coupling facility data table is closed
  • "K" when a contention model coupling facility data table is closed.

Reset characteristic: not reset

 

Read requests A17DTRDS is the number of attempts to retrieve records from the table.

Reset characteristic: reset to zero

 

Recs [not] in table A17DTRNF is the number of reads where the record was not found in the data table, so CICS retrieved the record from the source file.

Reset characteristic: reset to zero

 

Adds from reads A17DTAVR is the number of records placed in the table by the loading process or as a result of API READ requests issued while loading was in progress.

Reset characteristic: reset to zero

 

Add requests A17DTADS is the number of attempts to add records to the table as a result of WRITE requests.

Reset characteristic: reset to zero

 

Adds rejected - exit A17DTARJ is the number of records CICS attempted to add to the table which were rejected by the global user exit.

Reset characteristic: reset to zero

 

Adds rejected - table full A17DTATF is the number of records CICS attempted to add to the table but was unable to do so because the table already contained the maximum number of records specified.

Reset characteristic: reset to zero

 

Rewrite requests A17DTRWS is the number of attempts to update records in the table as a result of REWRITE requests.

Reset characteristic: reset to zero

 

Delete requests A17DTDLS is the number of attempts to delete records from the table as a result of DELETE requests.

Reset characteristic: reset to zero

 

Highest table size A17DTSHI is the peak number of records present in the table.

Reset characteristic: reset at close

 

Storage alloc(K) A17DTALT is the total amount of storage allocated to the data table. The DFHSTUP report expresses the storage in kilobytes. DFHSTUP does not total the storage allocated for all data tables because multiple files may share the same data table.

Reset characteristic: not reset

 

Chng Resp/Lock Waits A17DTCON For a CFDT that is using the locking model, records are locked down when they are read for update. This count is the number of times it was necessary to WAIT for an already locked record.

For a CFDT that is using the contention model, records are not locked when they are read for update. If a subsequent rewrite or delete request finds that the record has already changed, a CHANGED response is returned. This count is the number of times that a CHANGED response was issued.

Reset characteristic: reset to zero

 

NOT IN THE DFHSTUP REPORT A17DTLDS is the number of times that a LOADING response was issued. When a CFDT is in the process of being loaded, and requests issued for records beyond the range of those already loaded will get a LOADING response.

Reset characteristic. reset to zero

 

Note:
The request information statistics output for a data table represents the activity of the source data set, and the data table request information represents the activity of the data table. Thus, for a CICS-maintained table, you would expect to find similar counts in both sections of the statistics output for requests which modify the table, because both the source data set and the table must be updated. For a user-maintained table, updating activity is not shown in the data table resource information.

When using the shared data tables feature, the statistics records will contain the additional information as follows:

Table 64. Files: shared data table statistics
DFHSTUP name Field name Description
NOT IN THE DFHSTUP REPORT A17DTSIZ is the current number of records in the data table.

Reset characteristic: not reset

 

NOT IN THE DFHSTUP REPORT A17DTUST is the total amount of storage (kilobytes) in use for the data table.

Reset characteristic: not reset

 

NOT IN THE DFHSTUP REPORT A17DTALE is the total amount of storage (kilobytes) allocated for the record entry blocks.

Reset characteristic: not reset

 

NOT IN THE DFHSTUP REPORT A17DTUSE is the total amount of storage (kilobytes) in use for the record entry blocks.

Reset characteristic: not reset

 

NOT IN THE DFHSTUP REPORT A17DTALI is the total amount of storage (kilobytes) allocated for the index.

Reset characteristic: not reset

 

NOT IN THE DFHSTUP REPORT A17DTUSI is the total amount of storage (kilobytes) in use for the index.

Reset characteristic: not reset

 

NOT IN THE DFHSTUP REPORT A17DTALD is the total amount of storage (kilobytes) allocated for the record data.

Reset characteristic: not reset

 

NOT IN THE DFHSTUP REPORT A17DTUSD is the total amount of storage (kilobytes) in use for the record data.

Reset characteristic: not reset

 

NOT IN THE DFHSTUP REPORT A17DTRRS is the total number of read retries, that is the number of times reads in an AOR had to be retried because the FOR changed the table during the read.

A17DTRRS is not a count of accesses which failed because a file owning region (FOR) was updating the specific record that the AOR wished to read. In such cases, the request is function shipped and is counted in the "source reads".

Reset characteristic: not reset

 

Note:
Data table fields are present in the statistics records but contain zeros if shared data tables are not installed or the resource is not a data table.

Files: Resource statistics - performance information

These statistics are available online, and are mapped by the DFHA17DS DSECT.

Table 65. Files: Resource statistics - performance information
DFHSTUP name Field name Description
File name A17FNAM is the name you specified in the DEFINE FILE command of resource definition online.

Reset characteristic: not reset

 

Strings A17STRNO The maximum permissible number of concurrent updates. For RLS, the value specified in the ACB macro is ignored. After OPEN a value of 1024 is returned, indicating the maximum number of strings allowed.

Reset characteristic: not reset.

 

Active strings A17DSASC The current number of updates against the file.

Reset characteristic: not reset.

 

Wait on Strings: Current A17DSCWC The current number of 'waits' for strings against the file.

Reset characteristic: not reset

 

Wait on Strings: Total A17DSTSW The total number of 'waits' for strings against the file.

Reset characteristic: reset to zero

 

Wait on Strings: Highest A17DSHSW The highest number of 'waits' for strings against the file.

Reset characteristic: reset to current value

 

Buffers: Data A17DSDNB is the number of buffers to be used for data. For RLS, BUFND is ignored and the value specified in the ACB is returned. This parameter has no effect for hierarchical file systems (HFS) files.

Reset characteristic: not reset.

 

Buffers: Index A17DSINB is the number of buffers to be used for index. For RLS, BUFNI is ignored and the value specified in the ACB is returned. This parameter has no effect for hierarchical file systems (HFS) files.

Reset characteristic: not reset.

 

Excl Cntl Conflicts A17FCXCC is the number of exclusive control conflicts that have occurred against VSAM control intervals in this file.

Reset characteristic: reset to zero

 

Files: Summary statistics - resource information

Summary statistics are not available online.

Table 66. Files: Summary statistics - resource information
DFHSTUP name Description
File Name is the name you specified in the DEFINE FILE command of resource definition online.

 

Dataset name is the 44-character name defining the physical data set to the system. For remote files the data set name will be shown as REMOTE.

 

Base dataset name (If applicable) In the instance that the file is a VSAM PATH, this field gives the base data set name.

 

Dataset type is the data set type, which can be BDAM, ESDS, KSDS, RRDS or PATH. If the file is remote or not open, this field is blank.

 

RLS is an indicator of whether the file is RLS accessed or not. "Yes" = RLS-accessed file, "No" = non-RLS.

 

Data Table indicator is a one-byte field that contains the value "R", or "S" or "T", or "L" or "K" or "X", if data table statistics fields are present in the record.
  • "R" indicates that this is a remote file for which table read and source read statistics are present.
  • "S" indicates that the resource was not opened as a table but was able to access data from a table associated with the same data set.
  • "T" indicates that the resource is a data table.
  • "L" indicates that the resource is a coupling facility data table using the locking model.
  • "K" indicates that the resource is a coupling facility data table using the contention model.
  • "X" indicates that the resource has been opened with a source data set which has an associated CICS maintained data table and the resource has been updated which has caused the data table to also be updated.

 

Remote name The name by which this file is known in the system or region in which it is resident.

 

Remote sysid When operating in an ISC or MRO environment, and the file is held by a remote system, this field specifies the system upon which the file is resident.

 

LSR

The identity of the local shared resource pool. This value is that specified via the LSRPOOLID operand of the resource definition online DEFINE FILE command."N" means that it is not defined in an LSR pool.

 

CFDT PoolName The name of the coupling facility data table pool defined for the data table associated with the file.

 

Files: Summary statistics - requests information

Summary statistics are not available online.

Table 67. Files: Summary statistics - requests information
DFHSTUP name Description
File name is the name you specified in:
  • The DEFINE FILE command of resource definition online
  • (for BDAM files only) The TYPE=FILE, FILE operand of the DFHFCT macro.

 

Get requests is the total number of GET requests issued against this file.

 

Get upd requests is the total number of GET UPDATE requests issued against this file.

 

Browse requests is the total number of GETNEXT and GETPREV requests issued against this file.

 

Update requests is the total number of PUT UPDATE requests issued against this file.

 

Add requests is the total number of PUT requests issued against this file.

 

Delete requests is the total number of DELETE requests issued against this file.

 

Brws upd requests is the total number of READNEXT UPDATE and READPREV UPDATE requests issued against this file (RLS only).

 

VSAM EXCP request: Data A value is printed if the file has been opened and used as a VSAM KSDS during the CICS run. See notes 1, 2 and 3.

 

VSAM EXCP request: Index See notes 1, 2 and 3.

 

VSAM EXCP request: RLS req timeouts is the total number of RLS requests made to this file that were not serviced in the specified time limit, and therefore the requests were terminated.

 

Notes:
The "VSAM EXCP requests" fields indicate the number of I/O operations on the file for data and index records respectively. Also, note the following points:
  1. The values printed for both items relate to the file. If dynamic allocation has been used to change the physical data sets associated with a file, the value shown is an accumulation for all the data sets.
  2. Take care when using these values for files participating in data set name sharing, because VSAM maintains only one count of EXCPs for all ACBs thus connected. In this situation, the value reported against each file represents the total accesses for all sharing ACBs during the period for which the file was open. (Therefore, if all files in the data set name sharing group were open for the same period, each file would have the same EXCP values reported against it, which would be the total for all the files in the group.)
  3. For RLS, this value is a count of the number of calls to the system buffer manager. It includes calls that result in either a coupling facility cache access or an I/O.
  4. The EXCP count for RLS files is the count of all EXCPs for all tasks accessing the RLS file within that CICS region. It should be noted as stated in note 2, EXCP counts are stored in the file's corresponding ACB within that CICS region.

Files: Summary statistics - data table requests information

Summary statistics are not available online.

Table 68. Files: Summary statistics - data table requests information
DFHSTUP name Description
File Name is the name you specified in the DEFINE FILE command of resource definition online.

 

Table type This one-byte field is set to:
  • "C" when a CICS maintained table is closed.
  • "P" when a file which has been accessing a CICS maintained table is closed but the table remains open because there are other files still open which are using the table,
  • "S" when the source data set for a user maintained table is being closed,
  • "U" when a user maintained table is closed,
  • "L" when a locking model coupling facility data table is closed,
  • "K" when a contention model coupling facility data table is closed.

 

Successful reads is the total number of reads from the data table.

 

Recs in table is the number of reads where the record was not found in the data table, so CICS retrieved the record from the source file.

 

Adds from reads is the total number of records placed in the table by the loading process or as a result of API READ requests issued while loading was in progress.

 

Add requests is the total number of attempts to add records to the table as a result of WRITE requests.

 

Adds rejected - exit is the total number of records CICS attempted to add to the table which were rejected by the global user exit.

 

Adds rejected -table full is the total number of records CICS attempted to add to the table but was unable to do so because the table already contained the maximum number of records specified.

 

Rewrite requests is the total number of attempts to update records in the table as a result of REWRITE requests.

 

Delete requests is the total number of attempts to delete records from the table as a result of DELETE requests.

 

Highest table size is the peak number of records present in the table.

 

Chng Resp/Lock Waits For a CFDT that is using the locking model, records are locked down when they are read for update. This count is the number of times it was necessary to WAIT for an already locked record.

For a CFDT that is using the contention model, records are not locked when they are read for update. If a subsequent rewrite or delete request finds that the record has already changed, a CHANGED response is returned. This count is the number of times that a CHANGED response was issued.

 

Files: Summary statistics - performance information

Summary statistics are not available online.

Table 69. Files: Summary statistics - performance information
DFHSTUP name Description
File name is the name you specified in the DEFINE FILE command of resource definition online.

 

Strings The maximum permissible number of concurrent updates. For RLS, the value specified in the ACB macro is ignored. After OPEN a value of 1024 is returned, indicating the maximum number of strings allowed.

 

Wait on strings: Total The total number of ‘waits’ for strings against the file.

 

Wait on strings: HWM The highest number of 'waits' for strings against the file.

 

Buffers: Data is the number of buffers to be used for data. For RLS, BUFND is ignored and the value specified in the ACB is returned. This parameter has no effect for hierarchical file systems (HFS) files.

 

Buffers: Index is the number of buffers to be used for index. For RLS, BUFNI is ignored and the value specified in the ACB is returned. This parameter has no effect for hierarchical file systems (HFS) files.

 

Excl Cntl Conflicts is the total number of exclusive control conflicts that have occurred against VSAM control intervals in this file.

 

Related reference
Back to full list of statistics and DFHSTUP reports
Appendix A. CICS statistics tables
Interpreting these statistics
Interpreting file statistics
DFH0STAT reports for these statistics
Files Report
File Requests Report
Data Set Name Report
Data Tables Reports
Coupling Facility Data Table Pools Report
[[ Contents Previous Page | Next Page Index ]]