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.
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:
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:
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,
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.
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
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
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.
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.
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.
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.
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.
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.
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.
Storage Alloc gives the number of Kilobytes that have been allocated to the data table. This includes both address space and data space storage.
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.
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.
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.
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.