TYPIO - Write message to console

General

Application areas:	Data terminal communication; see "Data terminal communication" Message system; see "Messages" Communication; see "Communication (programs, users, system)"
Macro type:	Type S, MF format 1: standard/E/L form; see "S-type macros"

For a detailed description of physical and logical consoles and their use in BS2000 refer to the “Introduction to System Administration” [10 (Related publications)].

Macro description

The TYPIO macro is used to output a message on the console and to receive a message from the console.

Macro format and description of operands

TYPIO

MSG={addr1 / (r1) / (base1,[index1],[disp1])}

[,REPLY=(length, )]{addr2 / (r2) / (base2,[index2],[disp2}])

,SHORT=NO / YES

[,UCDEST={’destcode’ / addr3 / (r3) / (base3,[index3].[disp3])} ]

,MF={S / L / (E,{addr4 / (1) / (r4)})

MSG=
Specifies the address of an output area for the output message (variable-length record). Message length <= 230 bytes; messages of a length between 231 and 251 bytes are truncated; messages even longer than that are not transferred (length error).

addr1
Symbolic address (name) of the output area.

(r1)
Register containing the address value “addr1”.

(...)
Indirect address for addr1.
base1 = base register 1; index1 = index register 1; disp1 = displacement 1

REPLY=

Specifies that a reply is expected. This operand defines the address of the input area for the reply (variable-length record).
Reply length <= 72 bytes.

length
Length of input area (anticipated reply length + 4); 4 <= length <= 76.

• Longer replies are truncated.

• Shorter replies are entered left-justified and a byte with value X'00' is appended.

• length < 4 and length > 251 both result in a length error (RC = X'0C').

• 77 <= length <= 251 results in a length error (RC = X'04') and is treated as length = 76.

=addr2
Symbolic address (name) of the input area.

=(r2)
Register containing the address value “addr2”.

(...)
Indirect address for addr2.
base2 = base register 2; index2 = index register 2; disp2 = displacement 2

SHORT=
Specifies whether the message is to be output with an abbreviated or unabbreviated header (only effective for output to physical consoles).

NO
Default setting: specifies that the message is output in unabbreviated form.

YES
The message header is output in the form %xxxx_ where:% = message without reply
xxxx = source code/name/TSN and

SHORT=YES is permitted only if REPLY has not been specified.

UCDEST=
UCON output destination.

The destination of the message may be specified as follows:

• mnemonic name for a specific physical console

• routing code for consoles and user tasks to which a specific job area has been assigned

• authorization name for an authorized user task.

If UCDEST is not specified, the output is directed to the target specified in system parameter MSGDEST. In case of an invalid specification of UCDEST the output is directed to the main console.

'destcode'
The following specifications are possible (Entries must be enclosed in single quotes):

• destcode = (mn)where mn = 2-character mnemonic console name

• destcode = <xwhere x = routing code (be sure to specify the < character)

• destcode = name of the user task (4 characters)

addr3
Symbolic address (name) of a field (word) containing the entry for “destcode”.

(r3)
Register containing the entry for “destcode”.

(...)
Indirect address for addr3.
base3 = base register 3; index3 = index register 3; disp3 = displacement 3

Note

All entries must be entered left-justified.

MF=
For a general description of the MF operand, its operand values and any subsequent operands (e.g. for a prefix), see section “S-type macros”. The valid MF values are given at the start of the macro description under “Macro type” and are included in the macro format.

In the E form of the macro, the address of the parameter list is written to register R1 during macro execution.

Notes on the macro call

• When using indirect addressing (operands MSG, REPLY, UCDEST) the commas must always be entered.

• Format of the output or input area (operand MSG or REPLY):

  Byte 0-1:	Record length field (length of the message/reply + 4); when REPLY is specified, this field is supplied with values by TYPIO.
  Byte 2-3:	reserved
  Byte 4-n:	Text of message/reply

  Example for an output area:
  message      DC    Y(mend-message)
               DS    CL2
               DC    C'message-text'
  mend         EQU   *
  Example for an input area:
  reply        DS    0CL54
  lenfield     DS    CL2
               DS    CL2
  rtext        DS    CL50
  

• The macro can be used in reentrant programs, provided that only register entries are used and the L form and E form are called individually.

• During execution of the TYPIO macro, the contents of registers R0 and R1 are overwritten. The contents of register R0 are overwritten with binary zeros. The start address of the parameter list is written to register R1 (in the E form of the macro).For this reason, neither of these registers should be used for storing other values.

Return information and error flags

R15:

+---------------+
|   |   |   |   |
| | | | | | |a|a|
+---------------+

A return code relating to the execution of the TYPIO macro (format 2) is transferred in the rightmost byte of register R15. The remaining bytes are deleted.

X'aa'	Meaning
X'00'	Normal execution.
X'04'	TYPIO completed. Message or reply length truncated Message: length 230 to 251specified Reply: length 77 to 251 specified
X'08'	Address error: address was given via register R0 or R1, or an address (addr1 - addr3) is at least partially not in the user area.
X'0C'	Length error: message length <= 0 or greater than 251 bytes.
X'10'	Message output not possible (can occur, for example, during generation or termination of the calling task).