The Execute Form of the PUTLINE macro instruction

Use the execute form of the PUTLINE macro instruction to put a line or lines out to the terminal, to chain second-level messages, and to format a line and return the address of the formatted line to the code that issued the PUTLINE macro instruction. Use the execute form of the PUTLINE macro instruction to perform the following functions:

Set up the input/output parameter list (IOPL).
Initialize those fields of the PUTLINE parameter block (PTPB) not initialized by the list form of the macro instruction, or to modify those fields already initialized.
Pass control to the PUTLINE service routine.

The operands you specify in the execute form of the PUTLINE macro instruction set up control information used by the PUTLINE service routine. You can use the PARM, UPT, ECT, and ECB operands of the PUTLINE macro instruction to build, complete or modify an IOPL. The OUTPUT and TERMPUT operands and their sublist operands initialize the PUTLINE parameter block. The PUTLINE parameter block is referred to by the PUTLINE service routine to determine which functions you want PUTLINE to perform. The PUTLINE service routine makes use of the IOPL and the PTPB to determine which of the PUTLINE functions you want performed.

In the execute form of the PUTLINE macro instruction only the following is required:

PUTLINE      MF=(E,{list address})
                   {    (1)     }

The PARM, UPT, ECT, and ECB operands are not required if you have built your IOPL in your own code.

The output line address is required for each issuance of the PUTLINE macro instruction, but you can supply it in the list form of the macro instruction.

The other operands and sublists are optional because you can supply them in the list form of the macro instruction or in a previous execute form, or because you might want to use the default values which are automatically supplied by the macro expansion itself.

Figure 1 shows the execute form of the PUTLINE macro instruction; each of the operands is explained following the figure.

Figure 1. The Execute Form of the PUTLINE macro instruction

 [symbol]   PUTLINE      [PARM=parameter address] [,UPT=upt address)
                         [,ECT=ect address ] [,ECB=ecb address]

                         [OUTPUT=(output address {,TERM } {+
,SINGLE } {,INFOR} {,NOTRANS})]
                         [                       {FORMAT} {+
,MULTLVL} {,DATA } {,TRANS  } ]
                         [                                {,MULTLIN}                     ]

                         [             {EDIT   +
}                                ]
                         [ ,TERMPUT=(  {ASIS   } {,WAIT  } {+
,NOHOLD} {,NOBREAK})]
                         [             {CONTROL} {,NOWAIT} {+
,HOLD  } {,BREAKIN} ]

                         [ ,ENTRY={entry address}]+
  ,MF=(E {,list address})
                         [        {    (15)     }]+
         {     (1)     }

PARM=parameter address

specifies the address of the 3-word PUTLINE parameter block (PTPB). It can be the address of a list form of the PUTLINE macro instruction. The address can be any address valid in an RX instruction, or the number of one of the general registers 2–12 enclosed in parentheses. This address will be placed into the IOPL.

UPT=upt address

specifies the address of the user profile table (UPT). You can obtain this address from the Command Processor parameter list (CPPL) pointed to by register 1 when a Command Processor is attached by the terminal monitor program. The address can be any address valid in an RX instruction or it can be placed in one of the general registers 2–12 and the register number enclosed in parentheses. This address will be placed into the IOPL.

ECT=ect address

specifies the address of the environment control table (ECT). You can obtain this address from the CPPL pointed to by register 1 when a Command Processor is attached by the terminal monitor program. The address can be any address valid in an RX instruction or it can be placed in one of the general registers 2–12 and the register number enclosed in parentheses. This address will be placed into the IOPL.

ECB=ecb address

specifies the address of the event control block (ECB). You must provide a one-word event control block and pass its address to the PUTLINE service routine. This address will be placed into the IOPL. The address can be any address valid in an RX instruction or it can be placed in one of the general registers 2–12 and the register number enclosed in parentheses.

OUTPUT=output address

indicates that an output line is provided. The type of line provided and the processing to be performed on that line by the PUTLINE service routine are described by the OUTPUT sublist operands TERM, FORMAT, SINGLE MULTLVL, MULTLIN, INFOR, DATA, NOTRANS, and TRANS. The default values are TERM, SINGLE, INFOR, and NOTRANS.

The output address differs depending upon whether the output line is an informational message or a data line. For DATA requests, it is the address of the beginning (the fullword header) of a data record to be put out to the terminal. For informational message requests (INFOR), it is the address of the output line descriptor. The output line descriptor (OLD) describes the message to be put out, and contains the address of the beginning (the fullword header) of the message or messages to be written to the terminal by the PUTLINE service routine.

When a barrier element is the top stack element, and PUTLINE is operating in the foreground, PUTLINE displays the output at the terminal; if PUTLINE is operating in the background, it places the output in the SYSTSOUT data set.

TERM | FORMAT

TERM: Write the line out to the terminal.
FORMAT: The output request is only to format a single message and not to put the messages out to the terminal. The PUTLINE service routine returns the address of the formatted line by placing it in the third word of the PUTLINE parameter block.

SINGLE | MULTLVL | MULTLIN

SINGLE: The output line is a single line.
MULTLVL: The output message consists of multiple levels. INFOR must be specified.
MULTLIN: The output data consists of multiple lines. DATA must be specified.

INFOR | DATA

INFOR: The output line is an informational message.
DATA: The output line is a data line.

NOTRANS | TRANS

NOTRANS: specifies that the output line is not to be translated.
TRANS: specifies that the output line is to be written in the language specified in the user profile table (UPT). INFOR must be specified if TRANS is specified.
Note: For more information about providing translated messages, see PUTLINE Message Line Processing.

TERMPUT=

specifies the options requested. The options are EDIT, ASIS, or CONTROL; WAIT or NOWAIT; NOHOLD or HOLD; and NOBREAK or BREAKIN. The default values are EDIT, WAIT, NOHOLD, and NOBREAK.

EDIT | ASIS | CONTROL

EDIT

specifies that in addition to minimal editing (see ASIS), the following functions are requested:

Any trailing blanks are removed before the line is written to the terminal. If a blank line is sent, the terminal vertically spaces one line.
Control characters are added to the end of the output line to position the cursor to the beginning of the next line.
All terminal control characters (for example: bypass, restore, horizontal tab, new line) are replaced with a printable character. Backspace is an exception; see item 4 under ASIS.

ASIS

specifies that minimal editing is to be performed as follows:

The line of output is translated from EBCDIC to terminal code. Incorrect characters are converted to a printable character to prevent program-caused I/O errors. This does not mean that all unprintable characters are eliminated. Restore, uppercase, lowercase, bypass, and bell ring, for example, might be valid but nonprinting characters at some terminals. (See CONTROL.)
Transmission control characters are added.
EBCDIC NL, placed at the end of the message, indicates that the cursor is to be returned at the end of the line. NL is replaced with whatever is necessary for that particular terminal type to cause the cursor to return. This NL processing occurs only if you specify ASIS, and the NL is the last character in your message.
If you specify EDIT, NL is handled as described in 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 cursor on a new line.
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 PUTLINE service routine attempts alternate methods to accomplish the backspace.
Control characters are added as needed to cause the message to occur on several lines if the output line is longer than the terminal line size.
Idle characters are sent at the end of each line to prevent typing as the carrier returns.

CONTROL

specifies that the output line is composed of terminal control characters and will not display or move the cursor on the terminal. This option should be used for transmission of characters such as bypass, restore, or bell ring.

WAIT | NOWAIT

WAIT: specifies that control will not be returned until the output line has been placed into a terminal output buffer.
NOWAIT: specifies that control should be returned whether or not a terminal output buffer is available. If no buffer is available, a return code of 8 is returned in register 15.

NOHOLD | HOLD

NOHOLD: specifies that control is returned to the routine that issued the PUTLINE macro instruction, and it can continue processing, as soon as the output line has been placed on the output queue.
HOLD: specifies that the module that issued the PUTLINE macro instruction is not to resume processing until the output line has been put out to the terminal or deleted.

NOBREAK | BREAKIN

NOBREAK: specifies that if the terminal user has started to enter input, the user is not to be interrupted. The output message is placed on the output queue to be displayed after the terminal user has completed the line.
BREAKIN: specifies that output has precedence over input. If the user at the terminal is transmitting, the user is interrupted, and the output line is sent. Any data that was received before the interruption is kept and displayed at the terminal following the output line.

ENTRY=entry address | (15)

specifies the entry point of the PUTLINE service routine. If ENTRY is omitted, the PUTLINE macro expansion will generate a LINK macro instruction to invoke the PUTLINE service routine. The address can be any address valid in an RX instruction or (15) if the entry point address has been loaded into general register 15.

MF=E

indicates that this is the execute form of the PUTLINE macro instruction.

list address | (1)

The address of the four-word input/output parameter list (IOPL). This can be a completed IOPL that you have built, or 4 words of declared storage to be filled from the PARM, UPT, ECT, and ECB operands of this execute form of the PUTLINE macro instruction. The address is any address valid in an RX instruction or (1) if the parameter list address has been loaded into general register 1.