macro instructions to do so.
AS in other CICS/VS macro instruction operands, if only one entry is given in the TYPE operand, no parentheses are necessary. For example, the
Chapter 6. Service Invocation 61
Page of SH20-9003-2 Revised May 22, 1975 By TNL SN20-9086
DFHTC TYPE=READ
macro instruction is used to request that data be read from a terminal.
The application programmer must determine the combination of keywords that follows TYPE=, depending on the terminal (and sometimes, access method) used and the operation(s) to be performed. Additional operands may be required or desired, again depending on the terminal and access method used. Some common input/output requests are discussed below.
(For full details of DFHTC, see Chapter 7; for specific terminals, see Chapter 11; for further VTAM considerations, see the CICS/VS Advanced Communication Guide, SH20-9049.)
Before terminal services can be requested by means of the DFHTC macro instruction, the application programmer must provide instructions that do the following:
1. Symbolically define the TCTTE and TIOA by copying the appropriate storage definitions (DFHTCTTE and DFHTIOA) provided by CICS/VS.
(It is assumed that the storage definitions for the CSA and TCA have already been copied, as described in Chapters 2 through 5.)
2. Establish addressability for the TCTTE and TIOA by specifying a symbolic base address for the TCTTE and TIOA, respectively.
The Assembler-language or American National Standard (ANS) COBOL application programmer must obtain the base address of the TCTTE from TCAFCAAA and place i t in TCTTEAR; with PL/I, addressability for the TCTTE is established automatically. After addressability to the TCTTE has been established, the application programmer must obtain the base address of the TIOA from TCTTEDA and place i t at TIOABAR. Any field in the TCTTE or TIOA can then be accessed by field name.
CICS/VS allows one or more TIOAs to be associated with a terminal at a given time. If a TIOA is obtained through the DFHSC
TYPE=GETMAIN,CLASS=TERMINAL macro instruction, the address of the ~IOA
is automatically placed in TCASCSA. The application programmer must set up a base register for this TIOA and place the address at TCASCSA into the base register.
The length of the data to be read or written into a given TIOA is found in TIOATDL. On a read operation, this two-byte binary value is placed in TIOATDL by terminal control and represents the number of bytes actually read. On a write operation, the application programmer must place the number of bytes to be written in TIOATDL prior to issuing
th~ DFHTC TYPE=WRITE macro instruction.
TIOAs and terminal control macro instructions are used by CICS/VS basic mapping support (BMS) in response to application-program requests for BMS services. However, for BMS operations that use mapping, the application programmer need not be concerned with providing the length of the data in TIOATDL prior to output; note that this does not apply to the DFHBMS TYPE=TEXTBLD macro instruction, because i t does not involve mapping. After a BMS input operation, TIOATDL contains zeros.
Note: All TIOAs have a 12-byte prefix for storage accounting and terminal control and a one-byte terminating suffix. The value at TIOATDL does not include these 13 bytes.
WRITE DATA TO A TERMINAL (WRITE)
The application programmer can request that data be written to a terminal by issuing the
DFHTC TYPE=WRITE
macro instruction. Before issuing this macro instruction, the address of the TIOA from which data is to be written must be placed into TCTTEDA and the length of the data to be written into TIOATDL. (Of course, the CSA, TCA, and TCTTE must also be symbolically defined and, with Assembler language orANS COBOL, addressability established for the TCTTE. )
When the write is completed by terminal control, the TIOA is released to a dynamic storage pool (unless SAVE is specified). Any subsequent reference to this TIOA by the application program is logically in error and produces unpredictable results.
A TIOA can be reusedc by the application program after a write i t the request to write data to a terminal is made through the
DFHTC TYPE=(WRI~E,SAVE,WAIT)
macro instruction. In this case the TIOA is not released by terminal control. The WAIT parameter is needed to ensure that the write of the TIOA is complete before the area is reused.
Note: To ensure a dump of the TIOA following a terminal control write, the application programmer must issue a SAVE and WAIT with the DFHTC TYPE=WRITE macro ins1::,ruction that precedes the DFHDC macro
instruction.-As pointed out earlier, the application programmer can specify a write followed by a read operation in a single request by issuing the
DFHTC TYPE=(WRITE,REAC)
macro instruction. A typical use for this macro instruction occurs in a conversational environment in which the application program writes a question to the terminal, waits for a response, and then reads the response. Since the SAVE parameter is not specified, terminal control may reuse the TIOA from which data is written as a TIOA for the input data. However, a new TIOA is obtained for the read operation and its address placed in TCTTEDA when certain devices are involved or when certain conditions exist. For example:
• Local 3270 terminals.
• PSEUDOBIN is specified with READ,WRITE.
• The TIOA length for the WRITE instruction is less than that specified in the DFHTCT TYPE=TERMINAL,TIOAL=length specification
(binary synchronous terminals) or in the DFHTCT TYPE=LINE,
INAREAIFlength specification (all other terminals) by the system programmer.
• certain error conditions.
• A 3270 terminal is used in 2260 compatibility mode.
Thus the user shouldaJ.ways reload TIOABAR from TCTTEDA following the (WRITE, READ) macro instruction.
Note: In the case of a terminal connected to the 7770 Audio Response Unit, a read request that does not include the WRITE parameter causes the "ready" message defined in the terminal control table by the system programmer to be written to the terminal before the read operation occurs.
Chapter 6. Service Invocation 63