Monitoring shared data tables
CICS® produces statistics information to help you monitor the activity on your shared data tables. You can use the information contained in a CICS statistics report to evaluate the benefits of using shared data table services.
What shared data table statistics are available
A request to a shared data table that is owned by another region is recorded in the statistics report for both the requesting and file-owning regions.
- The FILES - Resource Information shows information such as the filename,
source data set name, data set type (which is always
Kfor a data table, because the source must be a VSAM KSDS) and a DT indicator. If data table statistics are present for the file, the DT Indicator is a single character that can have one of the following values; the field is blank if data table statistics are not present for the file:- T - The statistics report contains data table information because the file has been opened as a shared 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 shared data table (that has the same source data set).
- X - The statistics report contains information for an alternate index file, and reports shared data table information for the update of the shared data table associated with a file in the same upgrade set.
- The FILES - Requests Information shows the statistics for accesses to the source data set. For a loaded user-maintained shared data table, this contains only zeros.
- The FILES - Data Table Requests Information shows statistics for accesses to the shared data table. See Table 1 for the meanings of the column headings and the information that is recorded for a data table.
- The FILES - Performance Information shows the use of VSAM strings and buffers, and is only of interest for a data table in that it relates to the source data set.
| Heading | Description |
|---|---|
| Close Type | Type of data table close (only appears in the statistics collected when a data
table is closed). The Close Type is a single character and can have one of
the following values:
|
| 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. A total value for the storage allocated is not included in the TOTALS line. |
You can obtain a statistics report using the statistics utility program DFHSTUP. See Statistics utility program (DFHSTUP).
Introduction to CICS statistics describes the data contained in a statistics report.
Sample shared data table statistics
Figure 1, Figure 2, and Figure 3 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 samples are provided 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 Data Set Name Data Set RLS DT Time Time Remote Remote Lsrpool
Name Base Data Set 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 760012Requested Statistics Report Collection Date-Time 12/25/99-23:56:58 Last Reset 21:00:00 Applid CICAOR1 Jobname SDTGSTA1
_________________________________________________________________________________________________________________________________
FILES - Resource Information
____________________________
File Data Set Name Data Set RLS DT Time Time Remote Remote Lsrpool
Name Base Data Set 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 0Requested Statistics Report Collection Date-Time 12/25/99-23:59:59 Last Reset 21:00:00 Applid CICAOR2 Jobname SDTGSTA2
_________________________________________________________________________________________________________________________________
FILES - Resource Information
____________________________
File Data Set Name Data Set RLS DT Time Time Remote Remote Lsrpool
Name Base Data Set 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- Values appear in the owning region showing the activity of loading the data table.
- Except during loading, the counts of Get Requests and Browse Requests in the FILES - Requests Information statistics for the owning region are much reduced (often to zero), because such requests can now be satisfied from the data table using cross memory services, so they appear in only the requesting regions.
- After the initial load, data table statistics for update requests appear in both the owning and requesting regions showing the use of the shared data table.
- The Recs ¬ in Table figure indicates the degree to which benefit from shared data tables support has been prevented. In an AOR it shows how many retrieval requests have had to be function shipped. In an FOR it shows how many records have had to be fetched from the source data set.
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.
Interpreting the statistics
An explanation of the sample data table statistics follows.
- What can you know about a normal loading
-
Adds from Reads usually shows the number of attempts to add a record during loading. 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.
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 1 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.
- Where optimization of loading helps
-
The statistics for BANANA in the example indicate that only a range of key values, from the middle of the source data set, is required in the data table. These statistics are shown in Figure 1. Here, the XDTRD exit (described in Exit XDTRD) 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 intended 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 intended 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.
- How the statistics tell you about loading of a user-maintained shared 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 3. A Close Type of S identifies such statistics.
- How an implicit open from the requesting region is recorded in the 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.
- How can you know about update requests from the statistics
-
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 3 illustrate this point.
- How do you know about the shared data table high watermark
- The Highest Table Size shows the greatest 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.
- How are reading and browsing operations counted
- The number of data table Read Requests includes browses that are satisfied by the data table. Thus for ORANGE in Figure 2 and LEMON in Figure 3 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.
- How can you know about the failure to access records via the shared 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 2 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 1) 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.
- How can you know about multiple files with a single source from the statistics
-
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.