Transient Data Control Introduction and Usage Transient Data control is used for simple sequential processing. You can store data sequenti...
Introduction and Usage
Transient Data control is used for simple sequential processing. You can store data sequentially and retrieve it in the same sequence.
Transient Data means data that passes quickly into and out of existence. A record passes into a transient data queue when you write it to the queue. It passes out of the queue and out of existence when you read it. This is also called a destructive read.
When you write a record to a TD queue, it is always added at the end. When you read the queue, the first record from the queue is returned to you as well as removed from the queue. As such you cannot read the same record twice.
Transient data queues are often called destinations. Unlike the TS queues where defining them to CICS is optional and dependent on usage, TD queues must be defined to the system. In earlier versions of CICS you had to code the DCT (destination control table)using macros and then assemble and link edit the table into a CICS loadlib. You then had to point to this table via the SIT. Today CICS uses RDO to define TD queues.
- Intrapartition queue, that can be accessed from only within the CICS region.
- Extrapartition queues can be accessed both by the CICS region as well as by a batch program running in another address space.
- Indirect queue is one which points to another queue.
- Remote queue is one hosted on another CICS image either on this or a remote system.
An extrapartition destination can reside on any device that is valid for QSAM. CICS stores intrapartition queues in a VSAM file pointed to by DFHNTRA.
You use the TDQUEUE definition to describe the physical and operational characteristics of a transient data queue.
Intrapartition definitions contain attributes that provide information about recovery characteristics, trigger levels, associated transactions, facilities, and userids.
Extrapartition definitions contain information about the associated QSAM data set, and the number of buffers that are to be used.
Indirect definitions identify the underlying queue name.
Remote definitions contain the name of the remote system and the name by which the queue is known on that remote system.
A transient data queue is always installed in an enabled state. Any queues that were disabled when a CICS system terminated, will still be enabled when the system is restored using a warm start or emergency restart.
You can use the following transactions and commands to inquire about, set, and discard transient data definitions after they have been installed:
- CEMT INQUIRE TDQUEUE (or EXEC CICS INQUIRE TDQUEUE)
- CEMT SET TDQUEUE (or EXEC CICS SET TDQUEUE)
- CEMT DISCARD TDQUEUE (or EXEC CICS DISCARD TDQUEUE)
- The CECI transaction
Automatic Transaction Initiation
ATI provides a way of automatically starting a task when the number of entries in the queue reach a level specified in the queue definition. You define the transaction to be initiated as part of the queue definition.Indirect Destinations
This feature lets a single transient data queue be identified by different names. The physical queue can be either an intrapartition or an extrapartition queue. You do this when you want to shield a program from changes in the actual destination name. Typical example is where the destination is a terminal.
Reserving destinations for exclusive use
CICS does not automatically prevent multiple tasks to access the same TD queue. For this reason the applications that share a common queue must employ their own enqueue mechanisms, typically using CICS ENQ and CICS DEQ.
The WRITEQ TD command
EXEC CICS
WRITEQ TD QUEUE(name)
FROM(data-area)
[ LENGTH(data-value) ]
[ SYSID(name) ]
END-EXEC.
options
QUEUE Specifies the one to four character name of the transient data queue where the data is to be written.
FROM Specifies the data area from where the record is to be written.
LENGTH Specifies a half word PIC S9(4) COMP field that indicates the length of the record that is to be written.
SYSID Specifies the one to four character connection name that points to a remote system.
Exception Conditions
DISABLED The destination is disabled
INVREQ Another task has the extrapartition queue open for input.
IOERR An I/O error occurred
ISCINVREQ An undeterminable error occurred at the remote system.
LENGERR The length specified exceeds the maximum record length allowed for the destination.
NOSPACE There is not enough space allocated to the destination to contain the record.
NOTOPEN The destination is not open
QIDERR The destination specified in the call is not defined to CICS (either via RDO or DCT).
SYSIDERR The remote system could not be located or accessed.
Notes
- There are two types of queues. One is intrapartition and implemented on VSAM ESDS pointed to by DFHNTRA. The other is a QSAM and is an extrapartition queue.
- An intrapartition queue can have ATI with a specified trigger level. One common use of ATI is for printing applications.
- To have exclusive use of the queue use CICS ENQ and DEQ.
The READQ TD command
EXEC CICS
READQ TD QUEUE(name)
{ INTO(data-area) | SET(pointer-ref) }
[ LENGTH(data-value) ]
[ SYSID(name) ]
[ NOSUSPEND ]
END-EXEC.
options
QUEUE Specifies the one to four character name of the transient data queue from where the data is to be retrieved.
INTO Specifies the data area to where the record from the queue is to be written.
SET Specifies the data area that will contain the address of the retrieved record.
LENGTH Specifies a half word PIC S9(4) COMP field that indicates on input the length of the buffer. On return from the call CICS sets it with the length of the record fetched.
SYSID Specifies the one to four character connection name that points to a remote system.
NOSUSPEND Specifies that if the queue is busy, control is to return immediately to the program at the point following the READQ TD command.
Exception Conditions
DISABLED The destination is disabled
INVREQ The extrapartition queue has been opened for output.
IOERR An I/O error occurred
ISCINVREQ An undeterminable error occurred at the remote system.
LENGERR The length of the record exceeds the length of the buffer specified in the LENGTH option.
NOTOPEN The destination is not open
QBUSY Another task is writing or deleting a record in the queue.
QZERO There are no more records in the destination.
QIDERR The destination specified in the call is not defined to CICS (either via RDO or DCT).
SYSIDERR The remote system could not be located or accessed.
Notes
- There are two types of queues. One is intrapartition and implemented on VSAM ESDS pointed to by DFHNTRA. The other is a QSAM and is an extrapartition queue.
- An intrapartition queue can have ATI with a specified trigger level. One common use of ATI is for printing applications.
- Records are always fetched from the queue in the order in which they were written. Also the read is destructive, the record is deleted.
- To have exclusive use of the queue use CICS ENQ and DEQ.
- You should expect QZERO condition to arise if the queue is empty.
- You can get a QBUSY condition only if you specified NOSUSPEND. If you had not specified NOSUSPEND, your task blocks until the queue is no longer busy and your request completes.
The DELETEQ TD command
EXEC CICS
DELETEQ TD QUEUE(name)
[ SYSID(name) ]
END-EXEC
options
QUEUE One to four character queue name.SYSID Connection name of the remote system where this queue is defined.
Exceptions
DISABLED The queue has been disabled
INVREQ The queue is an extrapartition queue.
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
- Although the reads to a TD queue are destructive, the space occupied by the deleted records is not released until you issue a DELETEQ TD.
- The DELETEQ TD just deletes any unread records and reclaims space from deleted records. The destination itself is not deleted.
- You can issue a DELETEQ TD only against an intrapartition TD queue.
The ENQ command
EXEC CICS
ENQ RESOURCE(data-area)
[ LENGTH(data-value) ]
END-EXEC
RESOURCE Specifies a 1 to 255 character resource name.
LENGTH A half word PIC S9(4) COMP field that indicates the length of the resource name in the data-area. If you omit this CICS takes the address of the data-area as the resource that you want to ENQ.
The DEQ command
EXEC CICS
DEQ RESOURCE(data-area)
[ LENGTH(data-value) ]
END-EXEC
RESOURCE Specifies a 1 to 255 character resource name.
LENGTH A half word PIC S9(4) COMP field that indicates the length of the resource name in the data-area. If you omit this CICS takes the address of the data-area as the resource that you want to DEQ
The SPOOLOPEN command
EXEC CICS
SPOOLOPEN OUTPUT TOKEN(data-area)
USERID(data-value)
NODE(data-value)
CLASS(data-value)
ASA
PRINT
RECORDLENGTH(data-value)
RESP(data-area)
END-EXEC
Options
ASA specifies that the report has each record prefixed with an ASA carriage-control character, and this character must be used by the operating system to control formatting when the report is printed.
CLASS (data-value).specifies a 1-character class designation. If it is omitted, class A is assumed.
PRINT allows large records (maximum 32760 bytes) to be written to the spool. This is the default setting.
RECORDLENGTH(data-value).specifies, as a halfword binary variable, the maximum length of record to
write to a print data set. The default value is 32760.
TOKEN (data-area) specifies the 8-character CICS-allocated token used to identify a report.
USERID (data-value)specifies the 8-character identifier of the destination userid that processes the report. The report carries this identifier, which is used to select the report at its destination. It is a sender field and must be declared with a length of 8 characters.
NODE specifies the 8-character identifier of a destination node that the system spooler uses to route the file.It is a sender field.
Conditions
ALLOCERR, ILLOGIC, INVREQ, LENGERR, NODEIDERR, NOSPOOL,NOSTG, NOTFND, NOTOPEN, OPENERR, OUTDESCERR, SPOLBUSY, STRELERR. See CICS Application Programming Reference for details.
The SPOOLCLOSE command.
EXEC CICS
SPOOLCLOSE TOKEN(data-area)
KEEP
END-EXEC.
Options
KEEP For an INPUT report, KEEP specifies that the report is to be read again when SPOOLOPEN
INPUT is next issued.
For an OUTPUT report, KEEP specifies that the report is to be sent to its destination node.
TOKEN (data-area)specifies the 8-character CICS-allocated token used to identify a report.
Conditions
ALLOCERR, INVREQ, NOSPOOL, NOSTG, NOTFND, NOTOPEN, STRELERR
The SPOOLWRITE command
The SPOOLWRITE command writes data to a spool report.
EXEC CICS
SPOOLWRITE TOKEN(data-area)
FROM(data-area)
FLENGTH(data-value)
END-EXEC
Options:
FLENGTH (data-value) specifies the fullword binary variable that is to be set to the length of the data that is transferred. This is set by the user on output. It is optional and, if it is omitted, CICS uses the length of the data area.
FROM (data-area)specifies the data area from which to take the variable length data. The data itself is not altered in any way by CICS. FROM is a sender field.
TOKEN (data-area) specifies the 8-character CICS-allocated token used to identify a report. It is a receiver on SPOOLOPEN and a sender on all other commands.
No comments
Post a Comment