94 CICS/VS Application Programmer's Reference Manual
File Services
For Assembler language:
DFHFC TYPE=GET,
NORMAL RESPONSE I/O ERROR
CLI BE CLI BE CLI BE
DAT AS EI'=MASTER, RDIDADR=KEYF TCAFCTR,X' 00' GOOD
TCAF'CTR,X' SO' ERROR
TCAFCTR,X'OS' ERROR
INVALID REQUEST
GOOD DS OH
ERROR DS OH
DFHPC TYPE=ABEND For ANS COBOL:
GOOD.
ERROR.
DFHFC TYPE=GET,
DATASET=MASTER, RDI CADR=KEYF
IF TCAFCRC=' , THEN GO TO GOOD.
IF TCAFCRC=' , THEN GO TO ERROR.
IF TCAFCRC=' , THEN GO TO ERROR.
DFHPC TYPE=ABEND
NOTE 12-0-1-S-9 NORESP.
NOTE 12-0-1-8 IOERROR.
NOTE 12-S-9 INVREQ.
where the value specified wi thin single quotation marks is an
unprintable multipunch code for the required hexadecimal value. For example, a hexadecimal 00 has a multipunch code of 12-0-1-S-9.
The alternative approach to response code checking, which is
available to ANS COBOL programmers as described earlier, is generally a coding convenience and provides concise code documentation. When this approach is used, the IF statements above are replaced by statements of the form shown below:
IF FCNORESP THEN GO TO GOOD.
IF FCIOERROR THEN GO TO ERROR.
IF FCINVREQ THEN GO TO ERROR.
For PL/I:
* *
* *
DFHFC TYPE=GET,
*
DATASEI'=MASTER,
*
RDIDADR=KEYF
IF TCAFCTR='OOOOOOOO'E THEN GO TO GOOD; /* NORMAL RESPONSE */
IF TCAFCTR='10000000'B THEN GO TO ERROR; /* I/O ERROR */
' - - - - -
- - - - - - - - --- --- - - - - - - - - - - - - -
. - ' - - -- -
-96 CICS/VS Application Programmer's Reference Manual
IF TCAFCTR='00001000'B THEN GO TO ERROR; /* INVALID REQUEST */
GOOD:
ERROR:
DFHPC TYPE=ABEND TRANSIENT DATA SERVICES
Transient data management provides, through transient data control, a generalized queuing facility. Data can be queued (stored) for
subsequent internal or external processing. Selected units of
information, as specified by the application programmer, can be routed to or from predefined symbolic destinations, either intra~artition or extrapartition. The definitions for the destinations must be contained in a destination control table (nCT) established by the system
programmer at system generation.
Intrapartition destinations are queues of data on direct access storage devices developed for input to one or more programs running asynchronously (concurrently) as separate tasks; they are internal to the CICS/VS partition/region. nata directed to or from these internal destinations is called intrapartition data and must consist of
variable-length records. Intrapartition destinations can be associated with either a terminal or an out~ut data set. Intrapartition data may be ultimately transmitted upon request to a destination terminal or retrieved sequentially from the output data set. Typical uses of this facility involve message switching, broadcasting, data base access and routing of output to multiple terminals (for example, for order
distribution), queuing of data (for example, for assignment of order numbers or priority by arrival), and data collection (for example, for
hatched input from 2780 Data Transmission Terminals). If generated within the system, the CICS/VS asynchronous transaction processing
(ATP) facility can be used to transfer data to or frcm an intrapartition destination. (See "Asynchronous Transaction Processing" in Chapter
11. )
An intrapartition queue is reusable. The systerr programmer can indicate, by symbolic destination, whether (1) transient data space management is to control the reuse of tracks associated with a
particular destination identification (DESTID), or (2) the releasing of track space is to be controlled through use of the transient data PURGE macro instruction. If transient data space rranagement is not used, an intrapartition queue continues to grow, irrespective of whether the data has been read, until the application programmer purges i t .
Extrapartition destinations are queues (data sets) external to the CICS/VS partition/region, residing on any sequential device (DASD, tape, printer, and so on). In general, sequential extrapartition destinations are used for storing data external to the CICS/VS partition/region or for retrieving data from outside the
partition/region. For example, one task may read data from a remote terminal, edit the data, and write the results to a data set for subsequent processing in another partition/region. Logging data, statistics, and transaction error messages are examples of data that can be written to extrapartition destinations. In general,
extrapartition data created by CICS/VS is intended for subsequent batched input to non-CICS/VS programs. Data can also be routed to an output device such as a line printer. The CICS/VS asynchronous
TRANSIENT DATA
transaction processing (ATP) facility can be used when reading or writing extrapartition data sets.
Data directed to or from an external destination is called
extrapartition data and consists of sequential records that are fixed-or variable-length, blocked fixed-or unblocked. The record format for a particularextrapartition destination must be described by the system programmer when setting up the destination control table (see the CICS/VS system Programmer's Reference Manual).
Intrapartition and extrapartition destinations can be used as indirect destinations, which are symbolic references to still other destinations. This facility provides some flexibility in program maintenance in that data can be routed to a destination known by a different symbolic name, without. t.he necessity of recompiling existing programs that use the original name. only the destination control table need be changed. The application programs can route data to the destination using the previous symbolic name; however, the previ0us name is now an indirect destination that refers to the new symbolic name. Since indirect destinations are established by means of
destination control table entries, the application programmer usually need not be concerned with how this is done. Further information is available in the CICS/VS System Programmer's Reference Manual.
For intrapartition destinations, CICS/VS provides the option of automatic task initiation. A basis for automatic task initiation is established by the system programmer by specifying a nonzero trigger level for a particular intrapartition destination in the DCT. (See discussion of the CFHDCT TYPE=INTRA macro instruction in the CICS/VS system Programmer's Reference Manual.) When the number of entries
(PUTs from one or more programs) in the queue (destination) reaches the specified level, a transaction specified in the definition of the destination is automatically initiated. Control is passed to a program that processes the data in the queue; the prograrr RUst issue repetitive GETs to deplete the queue.
Once the queue has been depleted, a new automatic task initiation cycle begins. That is, a new task is scheduled for initiation when the specified trigger level is again reached, whether or not execution of the prior task has terminated.
If an automatically initiated task does not deplete the queue, access to the queue is not inhibited. The task may be normally or abnormally terminated before the queue is emptied (that is, before a QUE ZERO
response is returned in response to a DFHTD TYPE=GET macro instruction).
If the destination is a terminal, the same task is reinitiated regardless of the trigger level. If the destination is a data set, the task is not reinitiated until the specified trigger level is reached. If the trigger level of a queue is zero, no task is
automatically initiated. To ensure that termination of an automatically initiated task occurs when the queue is empty, the application program should test for a QUEZERO condition rather than for some
application-dependent factor such as an anticipated number of records.
I t is the QUEZERO condition only that indicates a depleted queue.
Requests for transient data services are communicated to transient data control through CICS/VS macro instructions. Transient data control then executes as a service program under control of the TCA of the
requesting program. It runs at the priority of the requesting program and saves and restores registers from its TCA. After the requested transient data service has been provided (or attemFted), control is returned to the next executable instruction in the requesting program.
The transient data managerrent macro instruction (~FHTD) is used to request any of the following services:
98 CICS/VS Application Programmer's Reference Manual
1. Direct data to a predefined symbolic destination which references a data set or a terminal
2. Acquire data from a predefined symbolic source which references a data set or a terminal
3. Control the processing of an extrapartition data set 4. Purge data associated with an intrapartition data set
5. Check the response to a request for transient data services The application programmer must specify the parameters required when requesting transient data services. Parameters can be specified in two ways: (1) by including the parameters in operands of the DFHTD macro instruction by which the service is requested, or (2) by coding instructions that move the required parameters to fields of the TCA prior to issuing the DFHTD macro instruction. The latter approach provides some degree of flexibility in that a single DFHTD macro instruction can be tailored according to current logic needs within the application program.
The application programmer can check the CICS/VS response to a request for transient data services as described under "Test Response to a Request for Transient Data services." The operands that can be specified in DFHTD macro instructions are explained in detail under
"DFHTD Macro Instruction" in Chapter 7.
CICS/VS routes a variety of messages generated by CICS/VS programs or tasks to transient data control. For example, terminal control detects a line or terminal problem (not related to a user-provided task) and routes control to the CICS/vS terminal abnormal condition program (DFHTACP). DFHTACP then generates a message to the control system terminal log (CSTL) and/or to the control system master terminal
(CSMT) •
Destination definitions for all user and CICS/VS destinations must be included in the destinaticn control table (DCT). Lack of a
destination definition leads to an IDERROR (identification error) response to a DFHTD macro instruction.
DISPOSE OF DATA (PUT)
The application programmer can direct transient data to a predefined symbolic destination by issuing the
DFHTD TYPE=PUT,
macro instruction. Destinations are intrapartition if associated with a facility allocated to the CICS/vS partition/region and extrapartition if the data is directed to same destination that is external to ~e
CICS/vS partition/region. If intrapartition data is to be placed in the transient data output area, the symbolic storage definition for this area (DFHTDOA) should be copied in the application program. All references to the output area should be made through the use of a register (TDOABAR) which points to the beginning of the area.
*
The application programmer must specify the address of the output area containing data to be written, either by specifying the symbolic label of the area in the DFHTD TYPE=PUT macro instruction, or by placing the address in TCATDAA prior to issuing the macro instruction. For
variable-length records and intrapartition data, the first four bytes
Macro Destination Pointer Output Record Acquired Released
Type (see note 1) Area Format by by
-100 CICS/vS Application Progra·mmer's Reference Manual
- - -
- - - - - - -- - - -
- - -- - - -
- - - -- - - -
-MVC DATA, MESSAGEMVC TCATDDI,=C'CSML' DFHTD TYPE=PUT,
TDADDR=TDOAVRL
01 DFHTDOA COpy DFHTDOA.
02 DATA X ( 10) •
02 TDOABAR PICTURE S 9 (8) USAGE IS COMPUTATIONAL.
MOVE LENGTH TO TDOAVRI.
MOVE MESSAGE TO DATA.
MOVE 'CSML' TO TCATDDI.
DFHTD TYPE=PUT,
For PL/I:
%INCLUDE DFHTDOA;
TDADDR=TDOA \iRL
2 DATA CHAR (10) ;
TDOAVRL=LENGTH;
DATA=MESSAGE;
TCATDDI= , CSML' ; DFHTD TYPE=PUT,
TDACDR=TDOAVRL
ACQUIRE QUEUED DATA (GET)
The application programmer can acquire transient data from a predefined symbolic source by coding the
DFHTD TYPE=GET,
macro instruction. The address of the data acquired is returned at TCATDAA.
If the data is extrapartition, TCATDAA points to the first word of the data area. For variable-length records, the first four bytes of this area contain the length (LLbb) as specified for variable-length data sets.
If the data is intrapartition, the symbolic storage definition for the transient data input area (DFHTDIA) must have been copied in the application program. TCATDAA points to a CICS/VS input area defined by DFHTDIA. TDIAIRL contains the length (data length plus the length of the length field) of the area.