Interpreting data table statistics

This section describes the statistics information that is produced by CICS® to help you monitor the activity on your data tables.

You can use the information contained in a CICS statistics report to evaluate the benefits of using data table services. The information that is recorded for a data table under "Data Table Requests Information" is shown in Table 6.

Table 6. Data table statistics
Heading Description
Close Type Type of data table close (only appears in the statistics collected when a data table is closed).
Read Requests Number of attempts to read records from the data table or, in the AOR statistics, the number of read requests that had to be function shipped.
Recs ¬ in Table Number of attempts to read records from a source data set because the record was not found in the data table. (For a user-maintained data table, this happens only during loading.)
Adds from Reads Number of attempts to copy records from a source data set to the data table during loading process (including read requests from applications during loading).
Add Requests Number of attempts to write records to the data table.
Adds rejected - Exit Number of records suppressed by XDTRD and XDTAD user exits.
Adds rejected -
   Table Full
Number of records that were not included because the table was full.
Rewrite Requests Number of attempts to rewrite records in the data table.
Delete Requests Number of attempts to delete records from the data table.
Highest Table Size Peak number of records held in the data table.
Storage Alloc(K) Number of KB allocated to the data table.

The statistics for data tables are included in the FILES section of the statistics report. Four sections of FILE information are produced:

A request to a data table that is owned by another region is recorded in the statistics report for both the requesting and file-owning regions.

The DT Indicator is a single character that can have the values:

T
The statistics report contains data table information because the file has been opened as a data table.
R
The statistics report contains information for a remote file that has accessed a data table via shared data tables cross-memory services.
S
The statistics report contains data table information for the accesses made by this file to an associated data table (that has the same source data set).
X
The statistics report contains information for an alternate index file, and reports data table information for the update of the data table associated with a file in the same upgrade set.

The field is blank if data table statistics are not present for the file.

The Close Type is a single character that appears in the statistics only for the closing of a data table. The possible values indicate the type of close:

C
Close of a CICS-maintained data table.
P
Partial close of a CICS-maintained data table. There are still other files using the data table, so the data table itself has not been closed, only the file.
S
Close of the source data set for a user-maintained data table. This happens at the end of the loading of the data table.
U
Close of a user-maintained data table.

A total value for the storage allocated is not included in the TOTALS line.

The CICS Operations and Utilities Guide tells you how to obtain a statistics report using the statistics utility program DFHSTUP. Using CICS statistics and CICS statistics tables in the CICS Performance Guide describe the data contained in a statistics report,

Sample data table statistics

Figure 7, Figure 8, and Figure 9 show extracts from the file statistics for a hypothetical configuration similar to that discussed in Using statistics to select data tables, following conversion of the files into data tables. These figures are used to discuss how to interpret the information about data tables which is provided by the CICS statistics.

Figure 7. CICFOR requested file statistics
Requested Statistics Report        Collection Date-Time 12/25/99-23:55:41  Last Reset 21:00:00  Applid CICFOR    Jobname SDTGSTF1
_________________________________________________________________________________________________________________________________
FILES - Resource Information
____________________________
  File      Dataset Name                               Dataset  RLS      DT      Time     Time     Remote    Remote   Lsrpool
  Name          Base Dataset Name (If Applicable)       Type    File  Indicator Opened   Closed     Name     Sysid      ID
  ____________________________________________________________________________________________________________________________
  APPLE     CIC01.CICOWN.APPLES                          K      NO         T    22:12:04  OPEN                           1
  BANANA    CIC01.CICOWN.BANANAS                         K      NO         T    22:53:56  OPEN                           1
  ORANGE    CIC01.CICOWN.CITRUS                          K      NO         T    20:51:25  OPEN                           2
  PLUM      CIC01.CICOWN.PLUMS                           K      NO         T    21:30:10  OPEN                           4
  POTATO    CIC01.CICOWN.POTATOES                        K      NO         T    20:30:10  OPEN                           8
  VICTORIA  CIC01.CICOWN.PLUMS                           K      NO         S    21:56:23  OPEN                           4
  ____________________________________________________________________________________________________________________________
Requested Statistics Report        Collection Date-Time 12/25/99-23:55:41  Last Reset 21:00:00  Applid CICFOR    Jobname SDTGSTF1
_________________________________________________________________________________________________________________________________
FILES - Requests Information
____________________________
  File     Get      Get Upd  Browse   Update   Add      Delete   Brws Upd VSAM EXCP Requests RLS req
  Name     Requests Requests Requests Requests Requests Requests Requests   Data    Index    Timeouts
  ____________________________________________________________________________________________________
  APPLE           1      495   760001      495       12        0        0     14560     1321        0
  BANANA          0     1803    48603     1803      951        0        0      8212      481        0
  ORANGE       1087   102677      104   107897     4709     1880        0     25180     1947        0
  PLUM            0       10     2001        0       20       10        0       580        3        0
  POTATO          0        0    24173        0        0        0        0      4513        2        0
  VICTORIA        0        3        0        0        5        3        0         5        1        0
  ____________________________________________________________________________________________________
  *TOTALS*     1088   104988   834882   110195     5697     1893
Requested Statistics Report        Collection Date-Time 12/25/99-23:55:41  Last Reset 21:00:00  Applid CICFOR    Jobname SDTGSTF1
_________________________________________________________________________________________________________________________________
FILES - Data Table Requests Information
_______________________________________
  File     Close    Read       Recs ¬   Adds from Add      Adds rejected Adds rejected Rewrite  Delete   Highest    Storage
  Name     Type     Requests   in Table   Reads   Requests    - Exit     - Table Full  Requests Requests Table Size Alloc(K)
  ___________________________________________________________________________________________________________________________
  APPLE              1105241          1   760000        12          0             0         495        0   760012      95104
  BANANA              652195          0    48602       951          2             0        1803        0    49551      11200
  ORANGE                1473       1191        0      4709          0             0      107897     1880   604167     266658
  PLUM                   227          1     2000        20          0             0           0       10     2025        256
  POTATO                9670      24173    24165         0          0         24165           0        0     1000       1760
  VICTORIA              3063          1        0         5          0             0           0        3     2025        256
  ___________________________________________________________________________________________________________________________
  *TOTALS*           1771869      25367   834767      5697          2         24165      110195     1893   760012

Figure 8. CICAOR1 requested file statistics
Requested Statistics Report        Collection Date-Time 12/25/99-23:56:58  Last Reset 21:00:00  Applid CICAOR1   Jobname SDTGSTA1
_________________________________________________________________________________________________________________________________
FILES - Resource Information
____________________________
  File      Dataset Name                               Dataset  RLS      DT      Time     Time     Remote    Remote   Lsrpool
  Name          Base Dataset Name (If Applicable)       Type    File  Indicator Opened   Closed     Name     Sysid      ID
  ____________________________________________________________________________________________________________________________
  APPLE     REMOTE                                                NO       R     CLOSED   CLOSED   APPLE     CIF1        N
  BANANA    REMOTE                                                NO       R     CLOSED   CLOSED   BANANA    CIF1        N
  ORANGE    REMOTE                                                NO       R     CLOSED   CLOSED   ORANGE    CIF1        N
  POTATO    REMOTE                                                NO       R     CLOSED   CLOSED   POTATO    CIF1        N
  ZUCCHINI  REMOTE                                                NO       R     CLOSED   CLOSED   COURGETT  CIA2        N
  ____________________________________________________________________________________________________________________
Requested Statistics Report        Collection Date-Time 12/25/99-23:56:58  Last Reset 21:00:00  Applid CICAOR1   Jobname SDTGSTA1
_________________________________________________________________________________________________________________________________
FILES - Requests Information
____________________________
  File     Get      Get Upd  Browse   Update   Add      Delete   Brws Upd VSAM EXCP Requests RLS req
  Name     Requests Requests Requests Requests Requests Requests Requests   Data    Index    Timeouts
  ____________________________________________________________________________________________________
  APPLE           1      520        0      520        5        0        0         0        0        0
  BANANA          0        0        0        0        0        0        0         0        0        0
  ORANGE        214    38735       14    37105     1311      630        0         0        0        0
  POTATO          0        0    24173        0        0        0        0         0        0        0
  ZUCCHINI        0        0        0        0        0        0        0         0        0        0
  ____________________________________________________________________________________________________
  *TOTALS*      215    39255    24187    38625     1316      630        0                           0
Requested Statistics Report        Collection Date-Time 12/25/99-23:56:58  Last Reset 21:00:00  Applid CICAOR1   Jobname SDTGSTA1
_________________________________________________________________________________________________________________________________
FILES - Data Table Requests Information
_______________________________________
  File     Close    Read       Recs ¬   Adds from Add      Adds rejected Adds rejected Rewrite  Delete   Highest    Storage
  Name     Type     Requests   in Table   Reads   Requests    - Exit     - Table Full  Requests Requests Table Size Alloc(K)
  ___________________________________________________________________________________________________________________________
  APPLE              1304214          0        0         0          0             0           0        0        0
  BANANA              441349          0        0         0          0             0           0        0        0
  ORANGE               63384        228        0         0          0             0           0        0        0
  POTATO                4835      24173        0         0          0             0           0        0        0
  ZUCCHINI             97867          0        0         0          0             0           0        0        0
  ___________________________________________________________________________________________________________________________
  *TOTALS*           1911649      24401        0         0          0             0           0        0        0

Figure 9. CICAOR2 requested file statistics
Requested Statistics Report        Collection Date-Time 12/25/99-23:59:59  Last Reset 21:00:00  Applid CICAOR2   Jobname SDTGSTA2
_________________________________________________________________________________________________________________________________
FILES - Resource Information
____________________________
  File      Dataset Name                               Dataset  RLS      DT      Time     Time     Remote    Remote   Lsrpool
  Name          Base Dataset Name (If Applicable)       Type    File  Indicator Opened   Closed     Name     Sysid      ID
  ____________________________________________________________________________________________________________________________
  COURGETT  CIC02.CICOWN.COURGETT                        K        NO       T    22:35:02  OPEN                           1
  LEMON     REMOTE                                                NO       R     CLOSED   CLOSED   ORANGE    CIF1        N
  ____________________________________________________________________________________________________________________
Requested Statistics Report        Collection Date-Time 12/25/99-23:59:59  Last Reset 21:00:00  Applid CICAOR2   Jobname SDTGSTA2
_________________________________________________________________________________________________________________________________
FILES - Requests Information
____________________________
  File     Get      Get Upd  Browse   Update   Add      Delete   Brws Upd VSAM EXCP Requests RLS req
  Name     Requests Requests Requests Requests Requests Requests Requests   Data    Index    Timeouts
  ____________________________________________________________________________________________________
  COURGETT        0        0        0        0        0        0        0         0        0        0
  LEMON         946    63942      299    70792     3398     1250        0         0        0        0
  ____________________________________________________________________________________________________
  *TOTALS*      946    63942      299    70792     3398     1250        0                           0
Requested Statistics Report        Collection Date-Time 12/25/99-23:59:59  Last Reset 21:00:00  Applid CICAOR2   Jobname SDTGSTA2
_________________________________________________________________________________________________________________________________
FILES - Data Table Requests Information
_______________________________________
  File     Close    Read       Recs ¬   Adds from Add      Adds rejected Adds rejected Rewrite  Delete   Highest    Storage
  Name     Type     Requests   in Table   Reads   Requests    - Exit     - Table Full  Requests Requests Table Size Alloc(K)
  ___________________________________________________________________________________________________________________________
  COURGETT             27656          0        0    386590          0             0       27656        0   101232      16160
  LEMON              3240872       1245        0         0          0             0           0        0        0
  ___________________________________________________________________________________________________________________________
  *TOTALS*           3268528       1245        0    386590          0             0       27656        0   101232

The main changes that are seen in the statistics when a file is redefined as a data table are:

You should use the statistics to get an overall feel for the behavior of your data tables, rather than attempt to explain the individual values.

The examples demonstrate a number of points about the statistics. These points are discussed in the rest of this section.

Normal loading

Adds from Reads usually shows the number of attempts to add a record during loading2. Because the loading process involves browsing the source data set until the end of the file, the number of Browse Requests (in the "FILES - Requests Information") equals Adds from Reads + 1 if loading completed successfully and there have been no other browses on the source data set. The statistics for APPLE in Figure 7 illustrate this point.

In the CICFOR statistics shown, APPLE, BANANA, and PLUM were opened after the last statistics reset, but ORANGE and POTATO were opened before, so the latter do not display the load-time statistics. It is generally better to assess statistics from a time interval that has not been distorted by loading, but you should remember that the loading process incurs an overhead that has to be recovered by the number of data table accesses.

Optimization of loading

The statistics for BANANA in the example in Figure 7 indicate that only a range of key values, from the middle of the source data set, is required in the data table. Here, the XDTRD exit (described in XDTRD user exit) has been used to skip over any keys that are not in this range.

Adds rejected - Exit shows the number of times the exit returned a non-zero return code, and is 2 in this case: 1 for when the first record in the source data set was presented, and the exit requested the load to skip on to the first key in the desired range, and 1 for when the first key beyond this range was presented, and the exit requested the load to skip over all remaining records to the end of the source data set.

In a case like this, you would usually use the XDTAD exit to reject any records that are written with keys outside the desired range. Then the number of Adds rejected - Exit would include the number of such records that had been written to the file.

The number of Adds from Reads contains the number of records that were loaded into the data table plus the two that were rejected. As for all the file and data table statistics, this figure shows the number of attempted, rather than the number of successful, writes.

Loading a user-maintained data table

When the loading of a user-maintained data table completes, the source data set is closed and an unsolicited statistics record is written that reports the number of records that are browsed from the source and written to the data table (or rejected by the XDTRD exit). Therefore, these figures do not appear in any later statistics reports such as that for COURGETT in Figure 9. A Close Type of S identifies such statistics.

Implicit open from the requesting region

If the file is not open in the FOR when the AOR issues the first read to it, no connection exists and the read is function shipped. This appears as one file Get Request in the AOR statistics. The implicit open and subsequent loading of the data table is triggered in the FOR.

This first read attempt from the new data table is counted in the Read Requests in the FOR data table statistics, but as the record is not found in the data table at this stage, it is added to the count of Recs ¬ in Table (which records the number of times a record could not be obtained from the data table). The record is fetched from VSAM, so the number of file Get Requests is incremented by 1. The statistics from CICAOR1 and CICFOR for APPLE illustrate this point.

Update requests

All update requests (writes, rewrites, and deletes) are processed by the owning region, which also controls loading and other maintenance of the data table. Because of this, the data table statistics of Adds from Reads, Add Requests, Adds rejected, Rewrite Requests, Delete Requests, Highest Table Size, and Storage Alloc are always zero on the remote requesting regions.

Updates are always reflected in both the data table and the source data set for a CICS-maintained data table, so matching numbers are often seen in the file statistics and the data table statistics for Add Requests and Delete Requests, and also for Update Requests in the file statistics compared with Rewrite Requests in the data table statistics. The statistics for APPLE and ORANGE illustrate this point.

These numbers might not match if not all records in the source data set are loaded into the data table, or if some error occurs when the source data set is updated. For example, an attempt to write a record with a duplicate key to the source data set is counted in the file Add Requests but no attempt is made to write the record to the data table, so the count of data table Add Requests is less.

In the case of a user-maintained data table, access after loading is complete is always to the data table, so the line of file statistics always contains zeros. The statistics for COURGETT in Figure 9 illustrate this point.

Data table high water mark

The Highest Table Size shows the largest number of records that was present in the data table at any one time. For APPLE, from which no records have been deleted, this is the number of records originally loaded, plus the number of data table Add Requests. For BANANA, the XDTRD user exit accepts only records that are of interest during loading, and XDTAD performs the same task when records are written; so the number is given by Adds from Reads plus Add Requests minus Adds rejected - Exit.

Total storage allocated

Storage Alloc gives the number of Kilobytes that have been allocated to the data table. This includes both address space and data space storage.

Reading and browsing

The number of data table Read Requests includes browses that are satisfied by the data table. Thus for ORANGE in Figure 8 and LEMON in Figure 9 file Browse Requests are very small (and in most cases they would be zero). But the number of data table Read Requests is of a similar magnitude to the total number of Get and Browse requests that were made before conversion of the file to a data table.

Failure to access records via the data table

The set of figures for ORANGE and LEMON show an effect that is sometimes seen when there is much update activity on a CICS-maintained data table. In this case, some of the read requests from remote regions might find that the record in the data table is being updated, so these requests are function shipped to the FOR.

For example, LEMON shows 1245 Recs ¬ in Table, of which 946 are Get Requests and 299 are Browse Requests. The function-shipped reads and browses attempt to access the data table in CICFOR (as shown by the 1473 Read Requests for ORANGE), by which time some of the reads can be satisfied from the data table, but the remainder use the source data set (as shown by the number under Recs ¬ in Table).

POTATO shows what can happen if an unsuitable choice of candidate is made. Because the data table size specified in the file definition is much less than the number of records in the source data set, only a small part of the file is loaded. However, the file is accessed remotely by an application that browses many records that lie beyond those that were loaded.

All those browse requests have to be function shipped to CICFOR (as shown by the high number of Recs ¬ in Table seen in Figure 8 for that file) and then, on CICFOR, the source data set has to be accessed (as shown by the number of Browse Requests in Figure 7) is made to add the records to the data table (see count of Adds from Reads) but as the data table is still at its maximum number of records, they have to be rejected (see Adds rejected - Table Full). Incidentally, the statistics record that contains the loading figures for the file includes 1 under Adds rejected - Table Full for the record that caused the load to terminate because the data table had reached its maximum size.

The values of Read Requests, Recs ¬ in Table, Browse Requests, Adds from Reads, and Adds rejected - Table Full are not all equal (as might have been expected) because some browses reach the end of the source data set (in which case there is no record to attempt to add to the data table) and also because often no attempt is made to access the data table when browsing over a range of records that is known to be missing from the data table.

Although this is an extreme example, it does illustrate the importance in certain situations of having a good understanding of the applications. A user exit should have been used to select the range of records on which most of the browsing occurs.

Multiple files with a single source

The file VICTORIA in CICFOR is included to show that when a second file is defined with the same source data set as a file that is open as a data table (PLUM), it can take advantage of the data table for non-update reads and browses (regardless of which file is opened first). In the Resource Information for VICTORIA, a DT Indicator of S means that the line of data table statistics shows how the data table has been used by this associated file; for example, 3063 reads or browses have been satisfied from the data table.

The same Storage Alloc and Highest Table Size statistics are reported for both PLUM and VICTORIA because the data table is associated with both files. Therefore the data table TOTALS line does not include a value for the total storage allocated. The load-time statistics are reported only for the file that initiated the data table; that is the file whose open caused the current instance of the data table to be built.

Additional statistics fields

Some additional statistics about shared data tables are collected when file statistics are gathered, but they are not formatted in a statistics report. You can write a program to extract these additional statistics from the statistics record. For programming information about CICS statistics, see the CICS Customization Guide.

This section describes the fields that are related to shared data tables and are part of the DFHA17 statistics record but are not displayed in a statistics report.

A17_DT_SIZE_CURRENT

This is a fullword at offset 160 (X'A0'). It contains the current count of records in the data table.

A17_DT_IN_USE_TOTAL

This is a fullword at offset 168 (X'A8'). It contains the total amount of storage (in KB) currently in use for the data table.

A17_DT_ALLOC_ENTRY

This is a fullword at offset 172 (X'AC'). It contains the amount of storage (in KB) currently allocated from the server’s address space to hold table entries for this data table.

A17_DT_IN_USE_ENTRY

This is a fullword at offset 176 (X'B0'). It contains the amount of storage (in KB) in the server’s address space currently being used by table entries for this data table.

A17_DT_ALLOC_INDEX

This is a fullword at offset 180 (X'B4'). It contains the amount of storage (in KB) currently allocated from the server’s address space to hold the index for this data table.

A17_DT_IN_USE_INDEX

This is a fullword at offset 184 (X'B8'). It contains the amount of storage (in KB) in the server’s address space currently being used by the index for this data table.

A17_DT_ALLOC_DATA

This is a fullword at offset 188 (X'BC'). It contains the amount of storage (in KB) currently allocated from the data space for the data portion of the records in this data table.

A17_DT_IN_USE_DATA

This is a fullword at offset 192 (X'C0'). It contains the amount of storage (in KB) in the data space currently being used to hold record data for this data table.

A17_DT_REREADS

This is a fullword at offset 196 (X'C4'). It contains a count of the number of times a read from a requesting region has retried a part of the data table section of the request processing because the data table changed in some way after the start of that section.

These fields are also displayed in the X'0B22' exit trace for a statistics call amongst the fourteen statistics fullwords, which are (in the order they appear in the trace):

Adds from Reads  during load
Adds rejected - Exit  during load
Adds rejected - Table Full  during load
Highest Table Size
Current record count
Storage Alloc (K)  or Total storage allocated
Total storage in-use
Entry storage allocated
Entry storage in-use
Index storage allocated
Index storage in-use
Data storage allocated
Data storage in-use
Rereads

Because these are internal fields, the traced values do not always correspond exactly to those in a statistics record.

Related concepts
Using statistics to select data tables
Statistics utility program -- DFHSTUP
Using CICS statistics
CICS statistics tables
Operations with data tables
Opening a data table
Closing a data table
MVS JCL requirements when using shared data tables
Activating user exits for data tables

2.
If loading has completed, but the load failed to read to the end of the source data set, the count for a CICS-maintained data table might also show attempts to add records that have been read from the source data set because they were not originally loaded.

[[ Contents Previous Page | Next Page Index ]]