Temporary Storage Control Introduction Temporary Storage provides a scratchpad area for applications to store data for short term use. One ...
Introduction
Temporary Storage provides a scratchpad area for applications to store data for short term use. One example of usage is passing data between executions of a pseudo conversational program.
Temporary Storage, also called TS is divided into TS queues and records, which are also known as items. It is incorrect to relate the term record to a file based record. A TS record or item size can be different for the record size of the underlying data set. The underlying data set over which TS is implemented is pointed to by DFHTEMP dd name in the CICS startup. This is a VSAM ESDS file, set up by the systems programmer. All CICS instance wide TS queues use this one file and the application programmer need not be bothered about setting this file up.
You do not need to define TS queues to CICS if you do not want them to be recoverable, or under syncpoint control. Be aware though that if you do need to define them, online CEDA does not support TS queue definitions. You have to code assembler macros and assemble and Link edit the definition into the CICS libraries. This is a system programmer / CICS administrators job.
System Considerations
The temporary storage table (TST) is a list of generic names (or prefixes) used to identify sets of temporary storage queues. Generic names are formed from the leading characters of the appropriate queue names, and can be up to seven characters long.
The generic names coded on a DFHTST TYPE=RECOVERY macro identify queues for which CICS provides backout of changes in the event of transaction failure or protection against system failure.
The generic name coded on a DFHTST TYPE=REMOTE macro identifies queues for which CICS routes the temporary storage request to a remote CICS region or TS server, unless the remote system name (SYSIDNT) is the same as that of the local CICS. If SYSIDNT is the same name as the local CICS, the queues specified by the DATAID option are treated by CICS as local queues.
The generic name coded on a DFHTST TYPE=LOCAL macro identifies queues as local queues that reside in the CICS region in which the TST is installed.
The generic name coded on a DFHTST TYPE=SECURITY macro identifies queues for which resource security checking is required.
CICS searches the TST for the first prefix that satisfies the particular search criteria. For example, if CICS searches for temporary storage queue ABCDEFGH, and the TST contains prefix A followed by prefix AB, A is selected. To avoid this, define the less-generic entries to the TST before any more-generic entries, so that the first to be found is the least generic of all possible matches.
Note that when CICS is looking for DATAIDs to match against a TS queue name, it searches only the types of entry in which it is interested for that particular search. CICS searches:
- Local and remote entries when determining whether a queue is remote. Thus, local and remote entries are regarded as one search category when CICS is matching a queue name against generic names.
- Recovery and remote entries when determining whether a queue is recoverable. However, if the leading characters of a queue name match both TYPE=RECOVERY and TYPE=REMOTE generic names, TYPE=REMOTE takes precedence, and the recovery option must be redefined in the local region in which the queue resides. (Queues in a shared TS pool cannot be recoverable.)
- Security entries only when determining whether a queue is subject to security.
DFHTST TYPE=INITIAL, LIST OF GENERIC NAMES OF QUEUE *
SUFFIX=01 THAT ARE RECOVERABLE, REMOTE,
* SHARED, LOCAL, OR REQUIRE
* SECURITY CHECKING.
* The following macro specifies that all LOCAL queues with
* names beginning with the letter 'R' are RECOVERABLE:
*
DFHTST TYPE=RECOVERY, *
DATAID=R
* The following macro specifies that queues with names
* beginning with C,D,E, and X are local queues:
*
DFHTST TYPE=LOCAL, *
DATAID=(C,D,E,X)
* The following macro specifies that queues with names
* beginning with AB,L,M,N are remote queues on system RSYS:
*
DFHTST TYPE=REMOTE, *
DATAID=(AB,L,M,N), *
SYSIDNT=RSYS, Queue names on remote system *
RMTNAME=LC begin with letters LC
* The following macro specifies that queues with names
* beginning with SAQ require security checking.
* Note that the full TS queue name is passed to the ESM.
*
DFHTST TYPE=SECURITY, *
DATAID=SAQ
*
DFHTST TYPE=FINAL
END
Sample Source For TS Queue Definitions.
Note that the link edited module will have the name DFHTST01. This must be pointed to in DFHSIT, the System Initialization Table by TST=01. The creation of the table and the DFHSIT change is the CICS administrator/ systems programmer work.
Application Programming Consideration:
As mentioned earlier the items in the queue represent data records from the application perspective. They are numbered 1 through n, although most usage will typically have only one record.Applications can fetch the item either sequentially or randomly (by specifying the item number).
TS control lets you choose between main storage and DFHTEMP ESDS for hosting your queue. Long life temporary data, typically data between pseudo conversational executions are better stored on disk to avoid stress on main storage. Short life data, where operator interaction does not determine the lifetime of the data, is better stored in main storage. However CICS does not pose any restrictions. Depending on the response times and other CICS conditions, an application programmer is free to choose between the methods. Note though that main storage implemented queues are not recoverable as they cannot be defined in the TST.
The WRITEQ TS command
EXEC CICS
WRITEQ TS QUEUE(name)
FROM(data-area)
[ LENGTH(data-value) ]
[ ITEM(data-area) [ REWRITE ] ]
[ NUMITEMS(data-area) ]
[ SYSID(name) ]
[ MAIN | AUXILIARY ]
[ NOSUSPEND ]
END-EXEC
options
QUEUE One to eight character queue name.
FROM The data area from where the data is to be written to the queue.
LENGTH A binary half word PIC S9(4) COMP field that specifies the length of the record to be written.
ITEM A half word PIC S9(4) COMP field which specifies the item to be rewritten when REWRITE is specified. If REWRITE is not specified, CICS ignores this field on input and sets it with the item number of the newly written item on return.
REWRITE specifies that the item should be rewritten.
NUMITEMS A binary half word field that CICS sets with the number of items (including this one just written) in the queue. Not valid if ITEM is coded.
SYSID Connection name of the remote system where this queue is defined.
MAIN Specifies that the item should be held in main storage.
AUXILIARY Specifies that the item should be held in auxiliary storage.
NOSUSPEND If sufficient space does not exist for the record, don’t suspend the calling task. Return with the NOSPACE response.
Exceptions:
INVREQ The queue name is invalid, or the queue was created for CICS internal use and cant be written into by a user program.
IOERR An IOERR occurred.
ITEMERR No record exists for the item number specified.
NOSPACE There is insufficient space to hold the TS record.
QIDERR The specified queue does not exist.(conceivably possible only when you attempt rewrite)
SYSIDERR The system defined by SYSID could not be located or accessed.
ISCINVREQ An indeterminate error occurred on the remote system.
Notes:
- TS queues are automatically created when you write a record to a queue that does not exist.
- Main or auxiliary lets you choose between the queue being on main or auxiliary storage.
- If the data being passed between applications is small use the commarea. If more than say 4k use a queue instead.
- If you want the queue name to be unique, use the terminal ID in the EIBTRMID field as the queue name.
- If you code NOSUSPEND, control is returned immediately to your program if sufficient space does not exist for the record. You can detect it by the NOSPACE condition.
The READQ TS command
EXEC CICS
READQ TS QUEUE(name)
{ INTO(data-area) | SET(pointer-ref) }
[ LENGTH(data-value) ]
[ NUMITEMS(data-value) ]
[ ITEM(data-area) | NEXT ]
[ SYSID(name) ]
END-EXEC
options:
QUEUE One to eight character queue name.INTO The data area into where the data from the queue is to be written.
SET Specifies the data area that will contain the address of the retrieved record.
LENGTH A binary half word PIC S9(4) COMP field that on input specifies the length of the data area and on return from the call has the length of the record that has been read.
ITEM A half word PIC S9(4) COMP field which specifies the item to be read from the queue.
NUMITEMS A binary half word field that CICS sets with the number of items in the queue.
SYSID Connection name of the remote system where this queue is defined.
Exceptions:
INVREQ The queue was created for CICS internal use and cannot be written into by a user program.
IOERR An IOERR occurred.
ISCINVREQ An undeterminable error occurred on the remote system that has the queue.
ITEMERR No record exists for the item number specified.
LENGERR The length of the record exceeds the length of the buffer specified.
QIDERR The specified queue does not exist.
SYSIDERR The system defined by SYSID could not be located or accessed.
Notes:
The access to TS queues can be sequential or direct. For direct access specify the item number. Note however that CICS maintains one and only one position in the queue for all tasks that access the queue. If multiple tasks access the queue sequentially, tasks may not get the next record due to intervening access by another task. If tasks want to reserve the queue for exclusive use they must use CICS ENQ and DEQ specifying the same resource name.Since temporary storage queues are created and deleted dynamically, always check for the QIDERR. If you specify ITEM check for the ITEMERR condition.
The DELETQ TS command
EXEC CICS
DELETQ TS QUEUE(name)
[ SYSID(name) ]
END-EXEC
SYSID Connection name of the remote system where this queue is defined.
Exceptions:
INVREQ The queue was created for CICS internal use and cannot be written into by a user program.
ISCINVREQ An undeterminable error occurred on the remote system that has the queue.
QIDERR The specified queue does not exist.
SYSIDERR The system defined by SYSID could not be located or accessed.
Notes:
- TS queues are automatically created when you write a record to a queue that does not exist. Once created they have to be explicitly deleted using the DELETQ command.
- Queues can be created in virtual storage or via DFHTEMP in a vsam ESDS file.
- You can create a unique queue name by using the value in EIBTRMID field of the EIB.
- Another way to delete a queue is to issue CEBR and issue a purge command. Since queues can be deleted so easily, checking of QIDERR is a must.
A sample Program using TS queues:
This is a variant of the CUSTOMER maintenance program presented earlier. Since the program is pseudo conversational, special considerations need to be given to the update program function. Between the time the record to be updated is read and thrown on the terminal screen for user change, some other transaction may change the record in the data set. Another version of the maintenance program defended itself against this possibility by maintaining a copy of the original record in the commarea which is preserved across pseudo conversational executions. The contents of the original record in the commarea are always checked against the contents after a READ with UPDATE option. The REWRITE is done only if the just read copy and the commarea copy match.
This version achieves the same result by storing a copy of the original record in a TS queue rather than in the commarea. This is a good idea if the record size is large.
This program and artifacts are described in the section SAMPLE APPLICATION.
General TS queue considerations
- Temporary storage queues remain intact until they are deleted by the originating task, by any other task, or by an initial or cold start;
- Before 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.
- The temporary storage queues can be defined as local, remote, or shared.
No comments
Post a Comment