Register form: The register that contains the parameters. When the R format is specified, this operand must be in one of the general registers 1–12, and that register must be specified within parentheses.

Register form: The register that contains the parameters. When the R format is specified, this operand must be in one of the general registers 0 or 2–12, and that register must be specified within parentheses.

If the registers you specify as the first and second operands are registers 1 and 0 respectively, the TPUT macro instruction uses those registers. However, if you use registers 2–12, the macro expansion loads registers 1 and 0, respectively, from the registers you specify as the buffer address and buffer size. Therefore, you might find it advantageous to use registers 1 and 0. The expansion of the register form of the TPUT macro instruction destroys the contents of registers 1 and 0.

The R operand and all other optional operands are mutually exclusive. If both R and any other optional operands are coded, the macro will not expand.

L

specifies the list form.

(E,ctrl addr)

specifies the execute form and the address of the list form.

1. All trailing blanks are removed before the line is written to the terminal. If a blank line is sent, the terminal vertically spaces one line.
2. Control characters are added to the end of the output line to position the cursor to the beginning of the next line.
3. All terminal control characters, except backspace, are replaced with a printable character.
4. Only those characters that appear in USA EBCDIC keyboard layout and code charts are supported. All others are replaced with a printable character. The replacement of characters includes the representation of the keyboard features and the special characters $, #, @ without hexadecimal equivalents of the USA EBCDIC code. For more information about keyboard features character sets, see IBM 3270 Information Display System: Character Set Reference.

EDIT is the default value for the EDIT, ASIS, CONTROL, FULLSCR, and NOEDIT operands.

TSO/VTAM supports 3270 extended data stream functions with the TPUT NOEDIT and NOEDIT modes of input. For information about specifying the NOEDIT mode of input, refer to STFSMODE - Set Full-Screen Mode.

1. The line of output is translated from EBCDIC to terminal code. Not valid characters are converted to a printable character to prevent program caused I/O errors. This does not mean that all unprintable characters are eliminated. For example, restore, uppercase, lower case, bypass, and bell ring might be valid but unprintable characters at some terminals. (See CONTROL.)
2. Transmission control characters are added.
3. An EBCDIC NL, placed at the end of the message, indicates to TPUT that the cursor is to be returned at the end of the line. NL is replaced with whatever is necessary to cause the cursor to return for that particular terminal type. This NL processing occurs only if you specify ASIS, and if the NL is the last character in your message.

   If you specify EDIT, NL is handled as described in item 3 under EDIT.

   If the NL is embedded in your message, a semicolon or colon may be substituted for NL and sent to the terminal. No idle characters are added (see item 6 below). This can cause overprinting, particularly on terminals that require a line-feed character to position the carrier on a new line.

4. If you have used backspace in your output message, but the backspace character does not exist on the terminal type to which the message is being routed, the backspace character is removed from the output message.
5. If the output line is longer than the terminal line size, control characters are added as needed to cause the message to display on several lines.
6. A sufficient number of idle characters is added to the end of each output line to prevent the transmission of output to the terminal while the cursor is being returned to the left-hand margin.
7. Including a bypass character, bypass carriage return, or bypass new-line character in the TPUT macro data suppresses printing of the next input entered by the user at the 3270 terminal. VTAM® moves the cursor to the next available line, unlocking the keyboard. No more data is sent to the terminal until the terminal user enters data or presses the Enter key. The data entered by the user is not printed at the terminal.

1. If the first character in your message is an escape control character (X'27'), the two characters following it are treated as a command code and as a write control character by the 3270. Note that the command code should always be for a remote 3270. If necessary, TPUT will convert the code to that for a local 3270. If the first character is not an escape character, a default write command and a write control character are added to the beginning of the message. Any attachment-dependent characters required for correct transmission of the data stream are provided by the access method.
2. Transmission control characters (SOH, STX, ETX, ETB, EOT, and NAK) and characters having no 3270 equivalent (X'04', X'06', X'14' through X'17', and X'24') are converted to printable colons to prevent program-caused I/O errors.

Lines are not counted when you use this option.

If the OWAITHI value specified in your TSO/E parameters is not large enough to contain your entire message, or if the BUFFERS and BUFFERSIZE parameters are specified so that your message does not fit into all of the system's buffers, the TPUT operation does not proceed, and code X'10' is returned. For a description of OWAITHI, see z/OS MVS Initialization and Tuning Reference. Without the FULLSCR option, your TPUT proceeds buffer-by-buffer as buffers become available.

If FULLSCR is specified for a message destined for another terminal, ASIS will be used instead.

WAIT

specifies that control is not returned to the program that issues the TPUT macro instruction until the output line is placed into a terminal output buffer. If no buffers are available for the same ASID TPUT (TPUT without any ASID, ASIDLOC, or USERIDL option - not a cross-memory TPUT), the issuing program is placed into a wait state until buffers become available, and the output line is placed into them. WAIT is the default value for the WAIT and NOWAIT operands.

Note: A cross-memory TPUT with WAIT operand will be rejected with a return code of 20 (X'14') when the buffers are not available. A cross-memory (ASID) TPUT is allowed to exceed the storage value coded for the high buffer threshold. The limit is calculated as:

     high buffer threshold * 3

where high buffer threshold is specified by parameter HIBFREXT in the member TSOKEY00 of SYS1.PARMLIB.

NOWAIT

specifies that control is returned to the program that issues the TPUT macro instruction, whether or not a terminal output buffer is available for the output line. If no buffer is available, TPUT returns a code of 4 in register 15.

NOHOLD

indicates that control is returned to the program that issues the TPUT macro instruction as soon as the output line is placed in terminal output buffers.

NOHOLD is the default value for the NOHOLD and HOLD operands.

HOLD

specifies that the program that issues the TPUT macro instruction cannot continue its processing until this output line is written to the terminal or deleted. The TPUT macro with the HOLD option is not discarded during RESHOW processing.

NOBREAK

specifies that if the user starts to enter input, the user is not interrupted. The output message is placed on the output queue and displayed after the user completes the line.

NOBREAK is the default value for the NOBREAK and BREAKIN operands.

BREAKIN

specifies that output has precedence over input. If the user starts to enter input, input is interrupted, and this output line is displayed. Data received before the interruption is displayed following this output line. However, the amount of data that is displayed is unpredictable.

HIGHP

specifies that this message must be sent to the terminal, even though the destination terminal does not display messages from other terminals. This operand counters the effect of the interterminal communication bit when the bit is set by the PROFILE command.

The operand is recognized only if your program is authorized (either by system key, supervisor state, or APF). The ASID keyword must also be specified. HIGHP is the default if neither HIGHP nor LOWP is specified, and if the issuing program is authorized.

LOWP

specifies that, if the user of the destination terminal allows interterminal messages, this TPUT will be sent to the terminal. If such messages are not allowed, the message is not displayed, and a code of X'0C' is returned, indicating that the message was not displayed. The LOWP operand is recognized only when ASID is specified. To use this operand, your program must be authorized (either by system key, supervisor state, or APF).

If you specify LOWP, your program should have an alternate method of transmitting the message to the terminal user. For example, a message data set could be used.

ASID, ASIDLOC, and USERIDL are not valid when you specify them with FULLSCR or ASIS parameters.

If the TPUT specifies an ASID or user ID, the message is sent to the target terminal. ASID and USERID TPUTs from programs not in supervisor state or not authorized under APF are prefixed with a plus sign (+) to prevent possible counterfeiting of system messages to an operator console.

The operand is recognized only if your program is authorized (either by system key 0 - 7, supervisor state, or APF-authorized).

You may specify the TOKNIN operand only with the execute form of the TPUT macro.

If you specify TOKNIN= with no value, the entire TOKNIN operand is ignored.