IOERROR XI 80 1 (Error not
Chapter 4.2. Terminal Control (DFHTC Macro Instruction)
CICS/VS terminal control uses the standard access methods available with the host operating system. The basic telecommunications access method
~TAM) is used by CICS/VS'for most start-stop and BSC terminals. As an option for OSjVS, the telecommunications access method (TCAM) can be specified. The sequential access method (SA~) is used where keyboard terminals are simulated by sequential devices such as card readers and
line printers. The virtual telecommunications access method (ACF/VTAM) or the telecommunications access method (TCA~) is used for systems network architecture (SNA) terminal systems.
Terminal control polls terminals to see if they have any data to transmit, and addresses terminals by having the computer check whether terminals are ready to receive data. Terminal control is responsible for code translation, transaction initiation, synchronization of input and output operations, and the line control necessary to read from or write to a terminal. Thus, the application program is freed from having to physically control terminals~ During processing, an application program is connected to one terminal for one task and terminal control monitors which task is associated with which terminal. The algorithm used by terminal control to determine which task should be initiated is described later in this chapter under the heading "Terminal-oriented Task Identification." Terminal control detects and logs errors, and also, where appropriate, inserts a default.
Terminal control can, as its name suggests, be used for communication with terminals. In SNA systems, however, i t is used to control
communication with logical units. A logical unit (LU) represents either a terminal directly, or a program stored in a subsystem controller which in turn controls one or more terminals. The CICS/VS application program communicates, by means of the logical unit, either with a terminal or with the stored program. For example, a 3161 terminal is represented by a single logical unit without any associated user-vritten application program. In contrast, a 3190 SUbsystem is represented by a 3191
controller, user-written 3190 application programs, and one or more 3190 terminals; when the subsystem is configured, one or more logical units are designated by the user.
Facilities that apply specifically to logical units are described later in this chapter under "Facilities for Logical units".
To request terminal control services, the application programmer uses the CICS/VS DFHTC (terminal control) macro instruction.
Among the services that can be requested by the DFHTC macro
instruction are some that are of interest to most, if not all, terminal types supported by CICS/VS such as:
• Write data to a terminal.
• Read data from a terminal.
• Synchronize te~minal input/output for a transaction.
• Converse with a terminal.
Chapter 4.2. Terminal Control (DFHTC Macro Instruction) 161
• Read or write records to a card reader, disk data set, magnetic tape unit, or a line printer defined by the system programmer as a card-reader-in/line-printer-out (CRLP) terminal. This facility allows transactions to be tested when normal communications terminals are not available.
For additional information concerning the last of these services, see
"Sequential Terminal Support" in Chapter'7.2.
Other services available in response to DFHTC macro instructions apply to specific types of terminal. Because many types of terminal are supported by CICS/VS, many special services are provided. (For a list of terminals supported by CICSjVS, see the publication CICS/VS General Information.) The following list is representative of the terminal-oriented input/output services available:
• Read the entire contents of a buffer (3270 Information Display System) •
• Read a message containing both uppercase and lowercase data (3270 Information Display System).
• Print out the contents of an information display buffer on a printer (3270 Information Display System) •
• Transmit a message to a common buffer (2980 General Banking System) •
• Read or write data in transparent mode, that is, without translation (System/?, System/370, System/3, 2770 Data
Communication System, 2780 Data Transmission Terminal, 3600 Finance Communication System ~TAM), 3740 Data Entry System, 3780 Data Communications Terminal) •
• Use the attention key to interrupt a write operation or signal a read attention request (for example, on the 2741 Communication Terminal) •
The general form of the terminal control macro instruction (DFHTC) resembles that of other CICS/VS macro instructions. Keyword operands are specified separated by commas. Although most CICS/VS macro
instructions use only one entry following the keyword TYPE, the DFHTC macro instruction can contain several. The
DFHTC TIPE=(WRITE,READ)
macro instruction, for example, causes a write to the terminal, a wait for that write to be completed (an implied wait), and a read from the terminal to which data has just been written.
Another example is the
DFHTC TIPE=(ERASE,WRITE,READ,WAIT)
macro instruction, which causes an erase and then a write to a terminal, followed by an implied wait, followed by a read and a requested wait.
The latter wait ensures that the read is complete before control is returned to the application program.
Two separate DFBTC macros must be used when two options that would be incompatible for the same macro are needed. Examples of incompatible options are:
162 CICS/VS APRM (ML)
DFHTC TYPE=(READ,WRITE) DFHTC TYPE=(WRITE,PRINT) DFHTC TYPE=(WRITE,READB) DFHTC TYPE=(PRINT,READ)
In such cases, the first macro should include the WAIT option; for example:
DFHTC TYPE=(WRITE,WAIT) DPHTC TYPE=READB
As in other CICS/VS macro instruction operands, if only one entry is given in the TYPE operand, no parentheses are necessary.
The application programmer must determine the combination of keywords that follow TYPE=, depending on the terminal (and sometimes, access method) used and the operations required. Additional operands may be required or desired, again depending upon the terminal and access method used. Some common input/output requests are discussed later in this chapter ..
Before using the DFHTC macro instruction to request terminal services, the application program must include instructions that:
1. Symbolically define the TCTTE and TIOA by copying the appropriate storage definitions (DPHTCTTE 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 Part 2.)
2. Establish addressability for the TCTTE by specifying a symbolic base address. If using the Assembler-language or COBOL, the application programmer must obtain the base address of the TCTTE from TCAPCAAA and place i t in TCTTEAR; with PL/I, addressability
for the TCTTE is established automatically. Any field in the TCTTE can then be accessed by field name. Addressability for the TIOA must be established each time a DFHTC TYPE=READ or TYPE=WRITE macro is issued. The ways of doing this are described in the following section.
Facilities for all Terminals and Logical Units
The facilities described in this section apply to all terminals and logical units. There may, however, be additional facilities that apply to specific devices. If this is so, details are given later in this chapter under headings for the relevant device types.
READ DATA FROM A TERMINAL OR LU
The application programmer can request that data be read from a terminal or logical unit by issuing the
DPHTC TYPE=READ
macro instruction. This causes a read to be issued to the terminal and the transaction to be placed in a wait state until the read completes.
Chapter ij. 2. Terminal Control (DPHTC Macro Instruction) 163
The incoming data is placed in a 'rIOA acquired by terminal control, which places the address of the TIOA in TCTTEDA. On completion of the read operation, the application program must copy the address from TCTTEDA to the TIOA base address register (TIOABAR): any field in the TIOA can then be accessed by field name.
The length of the data read into the TIOA is stored in TIOATDL.
Terminal control attempts to reuse TIOAs that have been used in previous operations. For this purpose, it maintains a chain of TIOA addresses anchored in the TCTTE. If no TIOA is attached to the chain, or if the existing TIOAs are too short or are otherwise unsuitable, terminal control acquires a new TIOA. The current TIOA, as addressed by TCTTEDA, may be freed by terminal control unless the SAVE operand is specified.
A new TIOA is also acquired by terminal control for the read when the DFHTC TYPE=(READ,SAVE)
macro instruction is issued. All TIOAs currently chained off the TCTTB are retained and may subsequently be reused; a new TIOA is dynamically acquired for this read and is added to the chain.
A write, followed by a read operation, can be specified in a single request. See "Write DATA and READ Response", later in this chapter.
When a TIOA which was previously obtained as a line input-output area (LIOA) by the terminal control program (TCP) is passed to a user task, the contents of the data part cannot be guaranteed beyond the data length supplied in TIOATDL. Therefore users should not attempt to interrogate the contents of a TIOA beyond this supplied length.
When the contents of a 3210 buffer are read (by using DFHTC TYPE=READB), the programmer should be aware that the attention
identifier byte and the cursor address are made available at TCTTEAID and TCTTECAD respectively_ A set of standard symbolic names for testing the 3210 attention identifier is provided in a copy book called DFHAID.
For further details refer to "Standard Attention Identifier List (DFHAID)" in Chapter q.3. "Basic Mapping Support".
WRITE DATA TO A TERMINAL OR LU
A request for data to be written to a terminal or logical unit can be issued using the
DFHTC TYPE=WRITE
macro instruction. Before issuing this macro instruction, the
application program must acquire a TIOA in which to build the data to be transmitted, and must place the address of the TIOA in TCTTEDA and the length of the data to be written in TIOATDL. The maximum data length is 32,761 bytes which includes the length of the function management header
~MH) when writing to a logical unit.
The required TIOA is acquired by a DFHSC TYPE=GETMAIN,CLASS=TEBKIHAL macro instruction. CICS/VS places the address of the TIOA in TCASCS!, from where it must be copied into the TIOA base address register
(TIOABAR) •
164 CICS/VS APRM(ML)
The application program must not change the contents of TCTTEDA until after the I/O operation has completed. The operation will only be
complete when another terminal control request has been issued (that is, TYPE=WAIT or TYPE=READ) •
If WAIT is not specified on a terminal control TYPE=WRITE operation, the operation may be deferred until the next terminal control request.
When the next terminal control request is issued, the SNA flows are optimized before the actual I/O is issued. For example, a terminal control write followed by a terminal control read could cause two flo~s
to be sent, whereas only one flow is sent if it can be determined that the next operation is a read request.
When writing data to a 3600 (non-pipeline) or 3790 inquiry logical unit, the CICS/VS application program must not put data into the first three bytes of the TIOA, unless it is building its own FMH (see
ItFunction Management Header" later in this chapter). The FMH is built either by CICS/VS or by the CICS/VS application program.
When the write operation is completed by terminal control, the TIOA is released to a dynamic storage pool (unless SAVE is specified) • Subsequent reference to this TIOA by the application program will produce unpredictable results.
However, a TIO! can be reused by the application program after a write if the request to write data to a terminal uses the
DFHTC TYPE=(WRITE,SAVE,WAIT)
macro instruction~ In this case, the TIOA is not released by terminal control. The WAIT parameter ensures that the write of the TIOA is
complete before the area is reused. Note that the SAVE operand does not guarantee that the field TCTTEDA addresses the TIOA saved, but only that the TIOA is not freed.
If a dump of the TIOA is required following a terminal control write, the SAVE and WAIT operands should be included with the DFHTC TYPE=WRITE macro instruction that precedes the DFHDC macro instruction.
WRITE DATA AND READ REPLY
As stated earlier, a write followed by a read operation can be specified in a single request by issuing the
DFHTC TYPE=(WRITE,READ)
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 reply, and subsequently reads the reply. Because the SAVE parameter is not specified, terminal control can reuse the TIOA (from which data is written) as a TIOA for the input data. Under certain conditions, however, a new TIOA is obtained for the read operation, for example:
• Local 3270 terminals.
• PSEUDOBIN specified with READ, WRITE.
Chapter 4.2. Terminal Control (DFHTC Macro Instruction) 165
• The TIOA length for the WRITE instruction less than that specified by the system programmer in the DFHTCT TYPE=TERMINAL,TIOAL=length specification (binary synchronous terminals) or in the DFHTCT TYPE=LINE,INAREAL=length specification (all other terminals).
• Certain error conditions.
• A 3270 terminal used in 2260 compatibility mode.
The user should alway§ reload TIOABAR from TCTTEDA following the (WRITE,READ) macro instruction.
For 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.
If both a write and a read operation are specified in a single request by issuing
DFHTC TYPE=(WRITE,READ,SAVE)
the TIOA used for writing is saved; a new TIOA is then acquired by terminal control for the read. The size of the TIOA is determined by the system programmer when specifying the TCTTE for the terminal (rather than by the size of the TIOA used for the write). If the saved TIOA is reused later for either writing or reading, the application program must place the address of the TIOA into TCTTEDA prior to issuing the request to use the area.
The manner in which the address of a TIOA is "remembered" is the application programmer's responsibility.
Upon completion of a (WRITE,READ,SAVE) , place the value at TCTTEDA into TIOABAR to establish addressability for the newly-acquired TIOA.
SYNCHRONIZE TERMINAL I/O (WAIT)
In a task under which more than one terminal or logical unit operation is performed, the application programmer must ensure that a current terminal operation is complete before another begins. Therefore, after a terminal control write has been issued, but before another terminal control write can be issued, a terminal control wait must be issued.
TcrTEDA can be changed to point to the new TIOA for output, and the next terminal control write can be issued. For SNA logical units, after a terminal control write has been issued, the next operation may be either a terminal control wait, or a terminal control read, according to
whether a subsequent write, or terminal control read is to be issued.
To do this the
DFHTC TYPE=W AIT
macro instruction is issued, where the WAIT parameter is coded
separately, as shown, or in combination with READ or WRITE. A PUT can be coded in place of a (WRITE,WAIT); a GET can be coded in place of a
(READ ,WAIT) • A terminal control read operation forces a wait to occur before the transaction is resumed, that is, the data will be available in the TIOA addressed by TCTTEDA at completion of the terminal control read operation.
166 CICS/VS APRM(ML)
A wait may cause execution of a task to be suspended. If suspension is necessary, control is returned to CICS/VS. Execution of the task is resumed when the write is posted complete~
A wait need not be coded for a write if the write is the last
terminal operation of the transaction~ The TIOA is retained until the data is written, even if the transaction and its associated storage are deleted from the system before the write occurs.
CONVERSE WITH A TERMINAL OR LU
To request a conversational mode of communication with a terminal or loqical unit, issue the
DFHTC TYPE=CONVERSE
macro instruction, where CONVERSB (or CONV) is the same as
(WRITE,READ,WAIT). This instruction is always executed in the sequence:
WRITE, implied wait, READ, WAIT.
It is possible, for most devices, to use this macro instruction rather than TYPE=READ, but it must not be used for the 3600 or 3650 pipeline logical units. However, its use is recommended for all other logical units.
DISCONNECT A SWITCHED LINE
To break a line connection between a terminal or logical unit and a host CPU, the
DFHTC TYPE=DISCONNECT
macro instruction is used. This applies only to devices operating on switched lines or to logical units. When used with logical units, DISCONNECT, which does not become effective until the task has been terminated, terminates the session, without causing a physical disconnection.
Note: CICS/OS/VS implements DISCONNECT for World Trade Teletype Terminals by writing a message to the terminal indicating that the terminal operator should manually disconnect.
Examples
The following examples show the coding required to:
1. Acquire storage for use as a terminal input/output area through the DPHSC macro instruction.
2. Place the address of the acquired area into TCTTEDA.
3. Place the length of the data to be written into TIOATDL.
Chapter 4.2. Terminal Control ~PHTC Macro Instruction) 167
i j . Issue a terminal control macro instruction to a 3270 terminal, thus
ESTABLISH ADDRESSABILITY FOR TCTTE OBTAIN TIOA FOR OUTPUT DATA
ESTABLISH ADDRESSABILITY FOR TIOA
NOTE EST ADDRESSABILITY FOR TCTTE. READ,WAIT) TERMINAL, THEN READ
MOVE TCTTEDA TO TIOABAR. NOTE EST ADDRESSABILITY FOR TIOl.
/*EST ADDRESSABILITY FOR TCTTE*/
OBTAIN TIOA FOR OUTPUT DATA
/*EST ADDRESSABILITY FOR TIOA*/
* *
*
...,
Facilities for Logical Units
A CICS/VS application program communicates with a TCAM, VTAM, or EXTM logical unit in much the same way that i t does with BTAM or TCAM terminals (that is, by using the various forms of the DFHTC macro
instruction described above). However, communication with logical units is governed by the conventions (protocols) that apply to each type of logical unit. This section describes the additional facilities provided by CICS/VS to enable the application programmer to comply with these protocols.
The types of logical units and the related protocols for each of the SNA subsystems supported by CICS/VS are described in the CICS/VS
subsystem guides for the IBM 3270, IBM 3600/3630, IBM 3650, IBM 3767/3770 and the IBM 3790 (see Bibliography).
SEND/RECEIVE MODE
Por SNA logical units, a transaction conversing with such a logical unit must conform to the send/receive protocols of SNA, unless the read-ahead queueing feature has been specified.
However, a transaction is normally in send mode and can issue any terminal control request. For displays (for example, the 3270), the send/receive mode is transparent to the application program, but for logical units that perform chaining, or make use of the full SNA . protocols (for example, the 3767), the send/receive mode should be taken into account.
If the application program is in receive mode, flag TCTEURCV in field TCTERCVI is set on, and the application program must continue to issue terminal control READ requests.
For compatibility, the read-ahead queueing feature (RAQ=YES specified in the DFHSG PROGRAM=TCP system macro) is provided so that the
application program is independent of the send/receive mode. However, it is recommended that application programs be changed to use SNA
send/receive protocols and that, wherever possible, they specify RAQ=NO.
OVERLAPPING LOGICAL-UNIT OUTPUT
Write operations are not initiated until a subsequent terminal control operation to the logical unit is issued, a syncpoint is taken, or the task terminates.
If a terminal control write operation is awaiting completion, a
If a terminal control write operation is awaiting completion, a