Temporary storage control

Temporary storage control

The CICS temporary storage control program provides the application programmer with the ability to store data in temporary storage queues, either in main storage, or in auxiliary storage on a direct-access storage device. Data stored in a temporary storage queue is known as temporary data. Temporary storage control commands are provided to:

* Write data to a temporary storage queue (WRITEQ TS).
* Update data in a temporary storage queue (WRITEQ TS REWRITE).
* Read data from a temporary storage queue (READQ TS).
* Delete a temporary storage queue (DELETEQ TS).

If TS is omitted, the command is assumed to be for temporary storage, not for transient data which has similar commands.

Temporary storage queues

Temporary storage queues are identified by symbolic names which must be eight characters assigned by the originating task. Temporary data can be retrieved by the originating task or by any other task using the symbolic name assigned to it. Specific items (logical records) within a queue are referred to by relative position numbers. To avoid conflicts caused by duplicate names, a naming convention should be established, for example, the operator identifier, terminal identifier, or transaction identifier could be used as a prefix or suffix to each programmer-supplied symbolic name.

Temporary storage queues remain intact until they are deleted by the originating task or by any other task; prior to deletion, they can be accessed any number of times. Even after the originating task is terminated, temporary data can be accessed by other tasks through references to the symbolic name under which it is stored.

Temporary data can be stored either in main storage or in auxiliary storage. Generally, main storage should be used if the data is needed for short periods of time; auxiliary storage should be used if the data is to be kept for long periods of time. Data stored in auxiliary storage is retained after CICS termination and can be recovered in a subsequent restart, but data in main storage cannot be recovered. Main storage might be used to pass data from task to task, or for unique storage that allows programs to meet the requirement of CICS that they be quasi-reentrant (that is, serially reusable between entry and exit points of the program).

Typical uses of temporary storage control

A temporary storage queue having only one record can be treated as a single unit of data that can be accessed using its symbolic name. Using temporary storage control in this way provides a typical "scratch pad" capability. This type of storage should be accessed using the READQ TS command with the ITEM(1) option; failure to do so may cause the ITEMERR condition to be raised.

In general, temporary storage queues of more than one record should be used only when direct access or repeated access to records is necessary; transient data control provides facilities for efficient handling of sequential data sets.

Some uses of temporary storage queues follow:

Terminal paging. A task could retrieve a large master record from a direct-access data set, format it into several screen images (using basic mapping support), store the screen images temporarily in auxiliary storage, and then ask the terminal operator which "page" (screen image) is desired. The application programmer can provide a program (as a generalized routine or unique to a single application) to advance page by page, advance or back up a relative number of pages, and so on.

A suspend data set. Assume a data collection task is in progress at a terminal. The task reads one or more units of input and then allows the terminal operator to interrupt the process by some kind of coded input. If not interrupted, the task repeats the data collection process. If interrupted, the task writes its "incomplete" data to temporary storage and terminates. The terminal is now free to process a different transaction (perhaps a high-priority inquiry). When the terminal is available to continue data collection, the operator initiates the task in a "resume" mode, causing the task to recall its suspended data from temporary storage and continue as though it had not been interrupted.

Preprinted forms. An application program can accept data to be written as output on a preprinted form. This data can be stored in temporary storage as it arrives. When all the data has been stored, it can first be validated and then transmitted in the order required by the format of the preprinted form.

Write data to a temporary storage queue (WRITEQ TS)

WRITEQ TS
QUEUE(name)
FROM(data-area)
[LENGTH(data-value)]
[ITEM(data-area)[REWRITE]]
[SYSID(name)]
[MAIN|AUXILIARY]
[NOSUSPEND]

Conditions: INVREQ, IOERR,
ISCINVREQ, ITEMERR, LENGERR,
NOSPACE, NOTAUTH, QIDERR, SYSIDERR

This command is used to store temporary data (records) in a temporary storage queue in main or auxiliary storage.

If you use the MAIN option on this command to write data to a temporary storage queue on a remote system, the data is stored in main storage provided that the remote system is accessed by the CICS multi region operation (MRO) facility and that the remote system is at the same release level as the requesting system. If these conditions are not met, the data is stored in auxiliary storage.

The queue is identified in the QUEUE option. The FROM and LENGTH options are used to specify the record that is to be written to the queue, and its length.

If the ITEM option is specified, CICS assigns an item number to the record in the queue, and sets the data area supplied in that option to the item number. If the record starts a new queue, the item number assigned is 1; subsequent item numbers follow on sequentially.

The REWRITE option specifies that records are to be updated, in which case the ITEM option must also be specified to identify the item (record) that is to be replaced by the data identified in the FROM option. If the specified queue exists, but the specified item cannot be found, the ITEMERR condition occurs. If the
specified queue does not exist, the QIDERR condition occurs.

The following example shows how to write a record to a temporary storage queue in auxiliary storage:

EXEC CICS WRITEQ TS
QUEUE(UNIQNAME)
FROM(MESSAGE)
LENGTH(LENGTH)
ITEM(DREF)

The following example shows how to update a record in a temporary storage queue in main storage:

EXEC CICS WRITEQ TS
QUEUE('TEMPQ1')
FROM(DATAFLD)
LENGTH(40)
ITEM(ITEMFLD)
REWRITE
MAIN

Read data from temporary storage queue (READQ TS)

READQ TS
QUEUE(name)
{INTO(data-area)|SET(ptr-ref)}
[LENGTH(data-area)]
[NUMITEMS(data-area)]
[ITEM(data-area)|NEXT]
[SYSID(name)]

Conditions: INVREQ, IOERR,
ISCINVREQ, ITEMERR, LENGERR,
NOTAUTH, QIDERR, SYSIDERR

This command is used to retrieve data from a temporary storage queue in main or auxiliary storage. The queue is identified in the QUEUE option.

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 length exceeds the specified maximum length, 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).

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 the record. The area is retained until another READQ TS command is executed. After the retrieval operation, the data area specified in the LENGTH option is set to the record length.

The ITEM and NEXT options are used to specify which record (item) within a queue is to be read. If the ITEM option is specified, the record with the specified item number is retrieved. If the NEXT option is in effect (either explicitly or by default), the next record after the last record to be retrieved (by any task) is retrieved. Therefore, if different tasks are to access the same queue and each task is to start at the beginning of the queue, the ITEM option must be used.

The following example shows how to read the first (or only) record from a temporary storage queue into a data area specified in the request:

EXEC CICS READQ TS
QUEUE(UNIQNAME)
INTO(DATA)
LENGTH(LDATA)
ITEM(1)

The following example shows how to read the next record from a temporary storage queue 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.

EXEC CICS READQ TS
QUEUE(DESCRQ)
SET(PREF)
LENGTH(LENG)
NEXT


Delete temporary storage queue (DELETEQ TS)

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

Conditions: ISCINVREQ, NOTAUTH,
QIDERR, SYSIDERR

This command is used to delete all the temporary data associated with a temporary storage queue. All storage associated with the queue is freed.

Temporary data should be deleted at the earliest possible time to avoid using excessive amounts of storage.

Temporary storage control options

AUXILIARY
Specifies that the temporary storage queue is on a direct-access storage device in auxiliary storage.

FROM (data-area)
Specifies the data that is to be written to temporary storage.

INTO (data-area)
Specifies the data area into which the data is to be written. The data area may be any variable, array, or structure. If this option is specified, move-mode access is implied.

ITEM (parameter)
Specifies a half word binary value to be used with WRITEQ TS and READQ TS commands.

When used with a WRITEQ TS command in which the REWRITE option is not specified, 'parameter' must be a data area that is to be set to the item (record) number assigned to this record in the queue. If the REWRITE option is specified, the data area specifies the item in the queue that is to be replaced.

When used with a READQ TS command, 'parameter' specifies the item number of the logical record to be retrieved from the queue. The parameter must be a data value that is to be taken as the relative number of the logical record to be retrieved. This number may be the number of any item that has been written to the Temporary storage queue.

LENGTH (parameter)
Specifies the length (as a half word binary value) of the data to be used with WRITEQ TS and READQ TS commands.

For a WRITEQ TS command, the parameter must be a data value that is the length of the data that is to be written.

For a READQ TS command with the INTO option, the parameter must be a data area that specifies the maximum length of data that the program is prepared to handle. If the value specified is less than zero, zero is assumed. If the length of the data exceeds the value specified, the data is truncated to that value and the LENGERR condition occurs. On completion of the retrieval operation, the data area is set to the original length of the data.

For a READQ TS command with the SET option, the parameter must be a data area. On completion of the retrieval operation, the data area is set to the length of the data.

MAIN
Specifies that the temporary storage queue is in main storage.

NEXT
Specifies that the next sequential logical record following the last record to be retrieved (by any task) is to be retrieved.

NOSUSPEND
Specifies that application program suspension for the NOSPACE condition is to be inhibited.

NUMITEMS
Specifies a half word binary field into which CICS stores a number indicating how many items there are in the queue.

QUEUE (name)
Specifies the symbolic name of the queue to be written to, read from, or deleted.
If the queue name appears in the TST, and the entry is marked as remote, the request is shipped to a remote system.
The name must be alphanumeric, must be eight characters in length, must be unique within the CICS system, and must not be solely binary zeros.
Do not use the characters X'DF' as a queue name prefix; these characters are reserved for CICS use. Also, using any of the following in queue name prefixes can have unpredictable consequences:

1. Embedded blanks
2. Hexadecimal X'AA' through X'AF'
3. Hexadecimal X'BA' through X'BF'
4. Hexadecimal X'CA' through X'CF'
5. Hexadecimal X'DA' through X'DF'
6. Hexadecimal X'EA' through X'EF'
7. Hexadecimal X'FA' through X'FF'

REWRITE
Specifies that the existing record in the queue is to be overwritten with the data provided. If the REWRITE option is specified, the ITEM option must also be specified. If the specified queue does not exist, the QIDERR condition occurs. If the correct item within an existing queue cannot be found, the ITEMERR condition occurs but the data is not stored.

SET (ptr-ref)
Specifies the pointer reference that is to be set to the address of the retrieved data. If this option is specified, locate-mode access is implied.

SYSID (name) (remote systems only)
Specifies the name of the system whose resources are to be used for intercommunication facilities. The name can be up to four characters in length.

Temporary storage control exceptional conditions

INVREQ

Occurs when a WRITEQ TS command specifies a queue:
That is locked and awaiting ISC session recovery (see the CICS/MVS Installation Guide for details.), or
With a symbolic name that is all binary zeros.

This condition also occurs for a READQ TS or DELETEQ TS command when the record to be retrieved has been created by a DFHTS TYPE=PUT macro.

Default action: terminate the task abnormally.

IOERR
Occurs when there is an unrecoverable input/output error.

Default action: terminate the task abnormally.

ISCINVREQ
Occurs when the remote system indicates a failure which does not correspond to a known condition.

Default action: terminate the task abnormally.

ITEMERR
Occurs when:

The item number specified or implied by a READQ TS command,
Or a WRITEQ TS command with the REWRITE option, is invalid (that is, outside the range of entry numbers assigned for the queue).

The maximum number of items (32767) is exceeded.

Default action: terminate the task abnormally.

LENGERR
Occurs if:
The length of the stored data is greater than the value specified by
the LENGTH option for move-mode input operations, or
The length of the stored data specified by the WRITEQ TS command is zero or negative.

Default action: terminate the task abnormally.

NOSPACE
Occurs when insufficient space is available in the temporary storage data set to contain the data.

Default action: suspend the task until space becomes available as it is released by other tasks; then return normally.

NOTAUTH
Occurs when a resource security check has failed. Use of SYSID will always raise the NOTAUTH condition when resource security level checking is in effect (RSLC=YES in the PCT). The reasons for the failure are the same as for abend code AEY7, as described in the CICS/MVS Messages and Codes manual.

Default action: terminate the task abnormally.

QIDERR
Occurs when the queue specified by a READQ TS command, or by a WRITEQ TS command with the REWRITE option cannot be found, either in main storage or in auxiliary storage.

Default action: terminate the task abnormally.

SYSIDERR
Occurs when the SYSID option specifies either a name which is not defined in the intersystem table, or a system to which the link is closed.

Default action: terminate the task abnormally.