Transient data control

Transient data control

The CICS transient data control program provides a generalized queuing facility. Data can be queued (stored) for subsequent internal or external processing. Selected data, specified in the application program, can be routed to or from predefined symbolic destinations, either intra partition or extra partition.

Destinations are intra partition if associated with a facility allocated to the CICS region, and extra partition if the data is directed to a destination that is external to the CICS region. The destinations must be defined in the destination control table (the DCT) by the system programmer when the CICS system is generated.

Transient data control commands are provided to:

* Write data to a transient data queue (WRITEQ TD).
* Read data from a transient data queue (READQ TD).
* Delete an intra partition transient data queue (DELETEQ TD).
* Write data to transient data queue (WRITEQ TD)

WRITEQ TD
QUEUE(name)
FROM(data-area)
[LENGTH(data-value)]
[SYSID(name)]

Conditions: DISABLED, IOERR,
ISCINVREQ, LENGERR, NOSPACE,
NOTAUTH, NOTOPEN, QIDERR, SYSIDERR

This command is used to write transient data to a predefined symbolic destination. The destination (queue) is identified in the QUEUE option.

The FROM option specifies the data to be written to the queue, and the LENGTH option specifies the record length. The LENGTH option need not be specified for extra partition queues of fixed-length records if the length is known and a data area of the correct size is available. If SYSID is specified, LENGTH must be specified as well.

The following example shows how to write data to a predefined symbolic destination; in this case, the control system messages log (CSML):

EXEC CICS WRITEQ TD
QUEUE('CSML')
FROM(MESSAGE)
LENGTH(LENG)

Read data from transient data queue (READQ TD)

READQ TD
QUEUE(name)
{INTO(data-area)|SET(ptr-ref)}
[LENGTH(data-area)]
[SYSID(name)]
[NOSUSPEND]

Conditions: DISABLED, IOERR,
ISCINVREQ, LENGERR, NOTAUTH,
NOTOPEN, QBUSY, QIDERR, QZERO,
SYSIDERR

This command is used to read transient data from a predefined symbolic source. The source (queue) is identified in the QUEUE option.

Reading a record from an intra partition transient data queue defined as reusable is destructive; it can only be read once.

The INTO option specifies the area into which the data is to be placed. The LENGTH option must specify a data area that contains the maximum length of record that the program will accept. If the record exceeds this value, it is truncated and the LENGERR condition occurs. After the retrieval operation, the data area
specified in the LENGTH option is set to the record length (before any truncation occurred). The LENGTH option need not be specified for extra partition queues of fixed-length records if the length is known and a data area of the correct size is available. If SYSID is specified, LENGTH must be specified as well.

Alternatively, a pointer reference can be specified in the SET option. CICS then acquires an area large enough to hold the record and sets the pointer reference to the address of that area. The area is retained until another transient data command is executed. After the retrieval operation, the data area specified in the LENGTH option is set to the record length.

If automatic task initiation is being used(the HANDLE CONDITION QZERO command should be included to ensure that termination of an automatically initiated task only occurs when the queue is empty.

The following example shows how to read a record from an intra partition data set (queue), which in this case is the control system message log (CSML), into a data area specified in the request:

EXEC CICS READQ TD
QUEUE('CSML')
INTO(DATA)
LENGTH(LENG)

The following example shows how to read a record from an extra partition data set (queue) having fixed-length records into a data area provided by CICS; the pointer reference specified by the SET option is set to the address of the storage area reserved for the data record. It is assumed that the record length is known.

EXEC CICS READQ TD
QUEUE(EX1)
SET(PREF)

Delete an intra partition transient data queue (DELETEQ TD)

DELETEQ TD
QUEUE(name)
[SYSID(name)]

Conditions: DISABLED, ISCINVREQ,
NOTAUTH, QIDERR, SYSIDERR

This command is used to delete all of the transient data associated with a particular intra partition destination (queue). All storage associated with the destination is released (reallocated).

This command must be used to release the storage associated with a destination specified as no reusable in the DCT. Otherwise, the storage remains allocated to the destination; the data and the amount of storage associated with the destination continue to grow whenever a WRITEQ TD command refers to the destination.