Application programming for a user-maintained shared data table or coupling facility data table

CICS® handles a user-maintained shared data table, or a coupling facility data table, and its source data set as separate entities. iWhen loading is complete, all file control commands that access the filename are performed only on the data table. If a request cannot be satisfied from a user-maintained shared data table, or a coupling facility data table, CICS does not access the source data set (as it would for a CICS-maintained shared data table). CICS returns an exception condition response instead.

You can use the user exits in data table services to put only the records that you need to access in the data table; there is no possibility of the source data set being accessed for those that you do not load. You can also use the user exit XDTRD to modify each record (by selecting, for example, only a subset of its fields) when it is loaded.

Records that were in the source data set when the data table was opened might be absent from the data table because they were not copied during loading. This could be because of suppression by the user exit XDTRD, or an abnormal event such as the data table becoming full.

Some application programming requests are not supported for a user-maintained shared data table or a coupling facility data table. For example, read requests that use the UPDATE option with an imprecise key are not supported. Also, some exception conditions are unique to user-maintained shared data tables or coupling facility data tables. You might need to change existing applications to comply with the restrictions on which commands and options can be used, or to handle the exception conditions that CICS returns.

The following commands are not supported; they return the INVREQ condition and a value of 44 in the EIBRESP2 field:
  • Commands with the RBA option
  • WRITE commands with the MASSINSERT option
The following commands are supported for shared data tables (using cross-memory services for remote access):
  • READ commands without the RBA option or the UPDATE option. If the record does not exist in the data table, the NOTFND condition is returned.
  • STARTBR, RESETBR, READNEXT, and READPREV commands without the RBA option.
  • ENDBR commands.
The following commands are supported for shared data tables (using function shipping for remote requests):
  • WRITE commands without the RBA or MASSINSERT options. The record is added to the data table (if it is not suppressed by the XDTAD user exit).
    The NOSPACE condition is returned in the following situations:
    • There is not enough data space storage to add the record to a shared data table.
    • There is insufficient space in the coupling facility data table pool to store the record.
    • The data table already contains the maximum number of records that is specified in the file definition.
    CICS issues message DFHFC0432 if a write is attempted but insufficient space is available.

    The SUPPRESSED condition is returned if the user exit XDTAD suppresses the addition of the record to the data table.

  • REWRITE commands without the RBA option. The record is updated in the data table. The NOSPACE condition is returned if there is insufficient storage for the updated record. CICS issues message DFHFC0432 if insufficient space is available.
  • DELETE commands without the RBA option. The record is deleted from the data table. The NOTFND condition is returned if the record does not exist in the data table. The NOSPACE condition is returned if the data table is recoverable and there is insufficient virtual storage for the information that CICS writes about the deleted record.

Using a user-maintained shared data table or coupling facility data table during loading

While a user-maintained shared data table is being loaded, you can use only non-update read requests with precise keys. If the record has already been loaded, processing the request is handled in the normal way. If the record has not yet been loaded, the record is read from the source data set and submitted to the user exit XDTRD (if activated):
  • If it is not suppressed by XDTRD, the record is added to the data table and returned to the application program.
  • If it is suppressed by XDTRD, the NOTFND condition is returned.

The LOADING condition is returned for other requests that would have been valid had loading been complete.