General
Application areas: | Input/output of files and records; see "Input/output" |
Macro type: | Type S, MF format 1: 24-bit interface: standard/E/L form |
This macro description applies to TIAM V13.2A.
The following applies when using the 31-bit interface:
With MF=C/D, no symbolic names and equates are generated for the standard header. In the event of the operand list being supplied dynamically, the initialization values for the standard header should be taken from an operand list generated with MF=L.
No return code is transferred in the standard header.
The CUPAB macro generates a DSECT for the operand list of the WROUT macro for 24-bit addressing mode.
Macro description
WROUT sends a message to the SYSOUT file. SYSOUT can be assigned to a PLAM library element, an S variable, a cataloged SAM or ISAM file or typically - to the user's terminal.
If the LOGGING=PARAMETERS (LISTING=YES) operand is specified in the SET-LOGON-PARAMETERS or MODIFY-JOB-OPTIONS command, output to SYSOUT is also routed to SYSLST.
Macro format 1 and description of operands
WROUT |
record,error[,edit] [{,MODE=COMP ,OTRSUP= {NO / YES},OLINEND={NO / YES} ,OHCOPY= {NO / YES},OHDR= {NO / YES} / ,MODE=LINE ,OHCOPY= {NO / YES},OHOM= {NO / YES} ,OINFO= {NO / YES},ONOPOSN= {NO / YES} ,OBELL= {NO / YES},ONOLOGC= {NO / YES} ,EXTEND= {NO / YES} / ,MODE=PHYS ,OHDR= {NO / YES},OETB= {NO / YES} ,OTRANS= {NO / YES} / ,MODE=FORM}] ,RC=OLD / NEW [,VTSUCBA=addr] [,ASSIGN=NO /YES] ,PARMOD=24 / 31 [,MF=L / C / (C,pre) / (D,pre) / D / (E,...)] |
record
Symbolic address of the record to be output. The record starts with the record length field, followed by the print control character and the message to be output.
Record format and example:
Byte 0-1: | Length of the message + 4-byte record length field, the length must be > 5. |
Byte 2-3: | reserved |
Byte 4: | Print control character; analyzed for printer output only |
Byte 5-n: | Message |
record DC Y (recend-record)
DS CL2 reserved bytes
DC X'nm' print control character
DC C'message' message to be output
recend EQU *
Note
If SYSOUT is a cataloged file, any records of more than 2044 or 2032 bytes are truncated (register R15=X'0C'), only the first part of the record being written to the file. The different maximum output length depends on the use of the PAM key (FORMAT=NONKEY/KEY).
error
Symbolic address of an error routine in the user program to be branched to in the event of an error.
In the event of an error, register R14 contains the address of the next instruction after the WROUT macro call. The error code is transferred in register R15.
31-bit interface: If error = 0 (address X'00..0') is specified, the program is continued with the instruction following the WROUT call.
edit
Specifies the edit option for a message to be written to the terminal. The edit option is ignored if SYSOUT is not a terminal. This operand is not necessary if standard functions (all edit bits = 0) are used, if the MODE= operand is specified or if the VTSU control block is used. By direct specification (X'xx') only the first edit byte for output can be set to the meaning described under the CUPAB macro.
Notes
This operand continues to be supported for reasons of compatibility only. The edit bytes should be defined via MODE specifications (see the MODE operand) or via the VTSU control block (see the VTSUCBA operand).
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.
A prefix (pre = 1..3 letters) can be specified in the C form and D form of the macro, as shown in the macro format. Default value: pre = CUW
PARMOD=
Controls macro expansion. Either the 24-bit or the 31-bit interface is generated.
If PARMOD is not specified here, macro expansion is performed according to the specification for the GPARMOD macro or according to the default setting for the assembler (= 24-bit addressing).
24
The 24-bit interface is generated. Data lists and instructions use 24-bit addresses (address space <= 16 Mb).
31
The 31-bit interface is generated. Data lists and instructions use 31-bit addresses (address space <= 2 Gb). Data lists start with the standard header.
The MODE specifications and edit options continue to be supported for compatibility reasons only. They are now summarized in the VTSU control block (VTSUCB, see the VTSUCB macro).
MODE=
This operand is not evaluated unless SYSDTA is assigned to the data display terminal.
COMP
Specifies compatible mode. The symbolic operands OTRSUP through OHDR (see below) enable the user program to use all the edit options. Any specifications made directly in the “edit” operand are ignored. Control characters may appear in the output message but these are not checked by the system. This mode is compatible with previous versions of the operating system.
This mode is treated as MODE=LINE for the 8160, 8162, 9749, 975x, 9763, 3270 and X.29 devices. The edit option OLINEND is ignored.
Edit options OTRSUP and OHDR are rejected (RC: X'08').
LINE
Specifies that the current terminal is to be treated as a logical line or page terminal. The message may be structured through the use of logical control characters (see the VTCSET macro). If SYSOUT is not a terminal, only logical control characters NL and NP are evaluated, e.g. in the case of output to printer in batch mode.
Any other control characters are invalid and are converted by the system to a userdefined substitute (see the command MODIFY-TERMINAL-OPTIONS SUBSTITUTE-CHARACTER=).
FORM
Specifies format mode. The user program works with the “Terminal Mapping Support” software component (FHS), which edits the message in a form suitable for output to a particular terminal.
PHYS
Specifies that the message is to be output physically at the terminal, i.e. without editing by the system. This permits special device functions to be executed for which the LINE or FORM mode is insufficient. If none of the valid edit options is specified, the system prefixes the message by a standard device message header.
EXTEND=
Determines whether the fields for output texts are to be protected or unprotected.
NO
The operator is guided through the system. Only the input request made by the system or the user program is protected against being overwritten.
Output is unprotected and at reduced brightness.
NIL characters in the output text are converted to the substitute characters; in the case of input they are removed.
Depending on the operating mode, the screen may be cleared starting at the cursor when output commences.
YES
(Only for 9749, 975x, 9763, 816x, and 3270 Data Display Terminals)
This entry supports the use of protected and unprotected fields with the aid of logical control characters EPA, NUM and SPA (see the VTCSET macro).
Text output is protected and at reduced brightness unless specified otherwise. The message can be structured by means of logical control characters (see VTCSET). When using 3270 terminals, note that logical control characters occupy space on the screen. A series of logical control characters, however, requires only one screen position. Areas which the terminal operator can use for input start with EPA or NUM and end with SPA.
During input and output, NIL is treated as a permissible character; it is sent to the data display terminal by the program, and vice versa. When using 3270 terminals, note that the NIL character is not transferred to the processor. Fields that are returned in truncated form are filled with NIL characters up to their original length. This ensures that the fields are always returned to the user in their original (output) length.
The beginning of an output message is displayed at the beginning of the next line following the cursor. If the message does not begin with VPA, the screen is cleared, starting at the cursor and before the first text character.
If the end of the screen is reached during output, output is continued at the top of the screen. This continuation is always unprotected. Overflow control is ineffective here.Keys RU, EFZ, AFZ and LSP are locked.
Except for OBELL, ILCASE and IGETFC, all other edit options are ignored. See programming notes.
OBELL=
Determines whether an audible signal is provided for output.
NO
No audible signal is provided for output.
YES
An audible signal is heard on output at the end of the message (applies only to 9749, 975x, 9763, 816x and 3270 Data Display Terminals with special hardware feature).
OETB=
Determines the final control character of the output message.
NO
Specifies that the message output at the terminal is to be concluded with the control character ETX.
YES
Specifies that the message output at the terminal is to be concluded with the control character ETB.
OHCOPY=
Determines whether the message output to a data display terminal is also output on a hardcopy device (printer) connected to the terminal.
NO
The message is output via the data display terminal only.
YES
The message output to a data display terminal is also output on a hardcopy device (printer) connected to the terminal. The hardcopy device must be generated or assigned using TCHNG.
For 3270 Terminals:
The entire screen contents are output via the hardcopy device. This means that the output may also include previous I/O's. In the event of a series of outputs directly following one another, the hardcopy function is activated for the last output only. Hardcopy output is performed only if a hardcopy device was generated for the terminal when the connection was set up.
There is no hardcopy output if OINFO=YES or EXTEND=YES was specified.
If OHCOPY=YES is used and the message contains one of the logical control characters SPA, EPA, CHS or NUM, only the last unprotected part of the message is output and not the whole message.
If, at the same time, OVERFLOW-CONTROL=NO (MODIFY-TERMINAL-OPTIONS command) was specified, it may be the case that only part of the output is printed on the hardcopy device.
OHDR=
Specifies how the system is to handle the message header.
NO
The message header (in US ASCII code) is prefixed to the output text by the system.
YES
Indicates that the message contains a user-specific header (message header is to be specified in US ASCII code) which the system prefixes to the output text. The length of the message header + 1 must be specified in binary form in byte 5 of the message.
For 3270 Terminals:
The message header is specified in EBCDIC code and consists of the CMD byte and the WCC byte. This message header must be preceded by a byte containing X'01' (length of the TRANSDATA message header + 1).
Note
When output is to the 8160, 975x and 9763 Data Display Terminals and printers locally attached to them, neither the system (MODE=LINE or COMP) nor the terminal mapping support (MODE=FORM) employs any message header
(PARAM0, PARAM1). Instead, they work with parameter specifications (PAG). The differences between these two modes are described in the manuals for the data display terminals or printers.
OHOM=
Specifies whether message output is to be structured or homogeneous.
NO
Specifies that the message is to be output, not homogeneously, but in structured form, i.e. one logical line is regarded as the output unit. The message length is unrestricted, provided the logical lines do not exceed 255 characters.
Effect when using mode 1:
Individual logical lines can be separately modified and thus selectively retransferred.
YES
This operand can only be used in conjunction with 816x, 9749, 975x and 9763 Data Display Terminals.
It specifies that the message is to be output homogeneously, in unstructured form, i.e. the entire message is regarded as one output unit. The message length is restricted by the size of the output buffer in the system.
Effect when using mode 1:
By modifying one character in an output message, the entire message can be retransferred, provided the message contains no logical display control characters.
Note
If SYSOUT is assigned to a file, the WROUT macro is not executed and SYSLST logging is suppressed.
OINFO=
Determines whether the message is to be output in a special information line.
NO
The message is not output in the special information line.
YES
The message can be mapped to a special information line without destroying important data at the terminal.
The entry is intended particularly for user programs sending messages to terminals “asynchronously” without knowing the current terminal display. Mapping is performed:
protected, in a hardware display line (e.g. 9749, 9750, 9752 Data Display Terminals), or
protected, in the last line on the screen (e.g. 816x, 9751, 9753, 3270 Data Display Terminals) if specified in the user program (see the TCHNG macro, INFOLIN operand), after previous output with MODE=FORM or MODE=PHYS.
in all other cases, as a normal line mode message.
If the message length exceeds one screen line, the message is split up and output line by line. The system observes the waiting time specified in the MODIFY-TERMINAL-OPTIONS OVERFLOW-CONTROL=TIME() command.
If OINFO=YES, the OHCOPY=YES entry is ignored, i.e. neither the information line nor the screen contents are printed.
The hardware display line is only reset after the next input followed by an output.
OLINEND=
Specifies how carriage return/line feed characters are to be handled.
NO
Each message output to a terminal always starts on a new line. The necessary control characters are either prefixed to the message by the system or inserted into the message when the physical end-of-line is reached, if the type of terminal requires this to be done.
YES
The message is output to the terminal without the carriage return/line feed control characters supplied by the system. Control must be assumed by the user program.
ONOLOGC=
Specifies whether logical control characters are to be evaluated.
NO
All logical characters are evaluated and special physical control characters are permitted (see the VTCSET macro, e.g. ESC, DC4). Any other characters < X'40' are replaced by SUB. Characters >= X'40' are accepted.
YES
Logical control characters are not evaluated. All characters < X'40' in EBCDIC code are replaced by SUB. Only characters >= X'40' are accepted.
ONOPOSN=
Determines where the message is to start.
NO
The message starts at the beginning of the next line.
YES
The message starts at the beginning of the current line (applies only to printer terminals).
OTRANS=
Specifies whether the output data is to be transmitted in standardized or transparent form.
NO
Output data is to be transmitted in standardized form, i.e. code conversion takes place.
YES
Output data is to be transmitted in transparent form, i.e. consisting of arbitrary binary characters (5, 7 or 8 bits per character depending on the device code) which are not converted during transmission. If the transmission path was not generated “potentially transparent”, output is rejected with return code X'04'.
OTRSUP=
Specifies whether translation from EBCDIC to device code is suppressed.
NO
Translation of the message from EBCDIC to device code is not suppressed, i.e. the program provides the message in EBCDIC and the system translates it into device code.
YES
Translation of the message is suppressed. In this case the program must provide the message in device code.
RC=
Determines where the return code is to be stored.
This operand may be specified only if the 31-bit interface is used.
OLD
The return code is stored in the rightmost byte of register R15.
NEW
The return code is stored in both register R15 and the standard header. All 4 bytes of register R15 are allocated for evaluation.
A 4-byte return code is issued only if SYSDTA reads from the data display terminal. In all other cases only a 1-byte return code is issued, irrespective of the return code value.
VTSUCBA=addr
Defines the address of a VTSUCB generated with MF=L.
When using the VTSUCBA operand, the MODE operand and the following edit options are ignored (their value is set to X'FF' in the parameter list). This means that all desired edit options must be specified in the VTSUCB.
This operand may be specified only if the 31-bit interface is used and is not evaluated unless SYSDTA is assigned to a data display terminal. By default, the VTSUCB is not used.
ASSIGN=
Defines whether changes in the SYSOUT assignment are to be displayed.
The user program is notified of the initial default assignment and of each subsequent change to the SYSOUT assignment via the error routine in the user program. When a change to the SYSOUT assignment is detected, the record is not written.
This operand value is permissible only for the 31-bit interface.
NO
Changes to the SYSOUT assignment are not to be displayed.
YES
Changes to the SYSOUT assignment are to be displayed.
Note
The SYSOUT assignment is entered in an output field of the parameter list.
This permits the user program to react to changed general conditions, perform any conversion of the output record which may be required, and then to repeat writing with the corrected record.
Programming notes
for use of the MODE=LINE operand with EXTEND=YES
(for 3270 Data Display Terminals see appendix)
When EXTEND=YES is specified in LINE mode, the user can work with formats without requiring a terminal mapping support component.
If the user wishes to work with formats, the first output must begin with NP in order to clear the screen and start with text in position 1.1.
NL positions to the beginning of the next line and clears the remainder of the screen; VPAn positions to the beginning of line n, in which case the remainder of the screen is retained.
Positioning within a line is only possible with text, spaces or NIL characters.
After VPAn, NL and CHS, text is protected and displayed with reduced brightness.
Unprotected fields are output using 'EPA text SPA'.
Numeric fields are output using 'NUM text SPA'.VPAn at the end of the message can be used to place the cursor at the start of the first unprotected field of line n, in which case the screen contents are retained. If no unprotected field starts in line n, the cursor is positioned to the first unprotected field following line n.
If no VPAn is specified at the end of the message, the cursor is placed in the first unprotected field on the screen.Continuation of output/screen update
NP generates a new screen.
VPAn at the start of the output changes line n of the screen. VPAn can be used to skip one or more lines. In the current line, a dark area is produced starting at the cursor and extending to the end of the line or a field preceding end-of-line. This is followed by positioning to line n. After completion of the update, the cursor is repositioned using VPAn, otherwise the screen would be cleared starting at the cursor (see above). When NL is used within an updating procedure, the screen is likewise cleared starting at the cursor. If this is to be avoided, VPAn must always be used to jump to a new line.
Macro format 2 and description of operands
WROUT |
(1) [,PARMOD=24 / 31 |
(1)
Register R1 contains the operand list address. The list must be aligned on a word boundary.
PARMOD=
Controls macro expansion; generated as a 24-bit or 31-bit interface.
If PARMOD is omitted, macro expansion corresponds to the specification for the GPARMOD macro or to the default value for the assembler (= 24-bit interface).
24
The 24-bit interface is generated. Data lists and instructions use 24-bit addresses (address space <= 16 Mb).
31
The 31-bit interface is generated. Data lists and instructions use 31-bit addresses (address space <= 2 Gb). Data lists start with the standard header.
Layout of the data area
Addressing | Byte | Contents |
24-bit mode | 0 | Output edit byte 1 |
1-3 | Address of the record to be output (operand “record”) | |
4 | Output edit byte 2 | |
5-7 | Address to be branched to if an error occurs (operand “error”). | |
31-bit mode | 0-7 | Standard header. For details of the structure, see section “Standardheader”. |
8-11 | Address to be branched to if an error occurs (operand “error”). | |
12-15 | Address of the record to be output (operand “record”) | |
16 | Output edit byte 1 | |
17 | Output edit byte 2 | |
18 | Reserved (X'00' ) | |
19 | Flag indicating use of VTSUCB and handling of return codes. | |
20-23 | Address of the VTSUCB | |
24-25 | Reserved (X'0000' ) | |
26 | Notification of a change to the SYSOUT assignment is to be provided | |
27 | Change to the SYSOUT assignment (output value) |
When using the 24-bit interface, the values for output edit byte 1/2 should be taken from the table specified with the CUPAB macro.
When using the 31-bit interface, they should be taken from a list generated with MF=C/D. This also applies for controlling whether a change to the SYSOUT assignment should be displayed (byte 26) and for the values of the SYSOUT assignment (byte 27).
Values for changing the SYSOUT assignment
Value | Meaning |
X'00' | Assignment for SYSOUT not changed |
X'01' | SYSOUT is assigned to a file |
X'02' | SYSOUT is assigned to a terminal |
X'03' | SYSOUT is assigned to an S-variable |
X'04' | SYSOUT is assigned to an element of a PLAM library |
Note
If SYSOUT is a cataloged file, any records of more than 2044 or 2032 bytes are truncated (RC:X'0C'), only the first part of the record being written to the file.
The different maximum output length depends on the use of the PAM key (FORMAT=NONKEY/KEY).
In the case of EAM files, records of more than 2040 bytes are also truncated (return code:X'0C').
Return information and error flags
During macro processing, register R1 contains the operand list address.
if PARMOD=24:
R15:
+---------------+ | | | | | |0|0|0|0|0|0|a|a| +---------------+
A return code relating to the execution of the WROUT macro is transferred in register R15.
X'aa' | Meaning |
X'04' | Unrecoverable error. |
X'08' | Operand error. |
X'0C' | Output record truncated. Record contents (without record length field) exceed size of I/O |
X'10' | During execution of the macro, BREAK was issued on the terminal. |
X'20' | Invalid edit option byte: error corrected by the system. |
X'38' | Error in connection with POSIX. |
if PARMOD=31:
if RC=OLD:
Return codes that can occur in addition to those described under PARMOD=24 are
X'aa' | Meaning |
X'00' | Normal termination. |
X'24' | Error in VTSUCB. |
and the return codes which, in accordance with conventions, apply to all macros (see the table “Standard return codes” (Standard header)).
if RC=NEW:
The return codes are entered in both the standard header and register R15.
Standard header:
+---------------+ | | | | | |c|c|b|b|a|a|a|a| +---------------+
The following return code relating to the execution of the WROUT macro is transferred in the standard header (cc=Subcode2, bb=Subcode1, aaaa=Maincode):
X'cc' | X'bb' | X'aaaa' | Meaning |
X'00' | X'00' | X'0000' | Function processed successfully. |
X'00' | X'00' | X'0020' | Function processed successfully; an operand error was corrected by |
X'00' | X'01' | X'0008' | Operand error not corrected. |
X'07' | X'01' | X'0008' | Operand error not corrected: the RESERVED fields are not 0 |
X'00' | X'20' | X'0004' | Internal error. |
X'02' | X'20' | X'0004' | Internal error: BCAM message lost. |
X'06' | X'20' | X'0004' | Internal error: negative transport acknowledgment. |
X'00' | X'20' | X'0028' | Internal error: problems with memory allocation. |
X'00' | X'40' | X'000C' | Output record truncated. |
X'00' | X'40' | X'0010' | BREAK during execution. |
X'00' | X'40' | X'0030' | Input/output aborted. |
X'01' | X'80' | X'0004' | Internal BCAM bottleneck. |
X'09' | X'80' | X'0038' | Error in connection with POSIX: Input/output serialization error. |
X'0A' | X'40' | X'0038' | Error in connection with POSIX: |
X'24' | VTSU error. In addition to Maincode (rightmost byte), see error |
Example 1
WROUT1 START
PRINT NOGEN
WROUT1 AMODE 31
WROUT1 RMODE 24
BALR 3,0
USING *,3
WROUT MESSAGE,ERROR,PARMOD=31
2 *,@DCEO 999 921011 53531004
TERM
ERROR TERM DUMP=Y
*
MESSAGE DC Y(ENDMESS-MESSAGE) Record length
DS CL2 Reserved
DC X'01' Print feed control character
DC 'EXAMPLE WROUT 1' Text
ENDMESS EQU *
END
Runtime log:
/start-assembh % BLS0500 PROGRAM 'ASSEMBH', VERSION '<ver>' OF '<date>' LOADED % ASS6010 <ver> OF BS2000 ASSEMBH READY //compile source=*library-element(macexmp.lib,wrout1), - // compiler-action=module-generation(module-format=llm), - // module-library=macexmp.lib, - // listing=parameters(output=*library-element(macexmp.lib,wrout1)) % ASS6011 ASSEMBLY TIME: 293 MSEC % ASS6018 0 FLAGS, 0 PRIVILEGED FLAGS, 0 MNOTES % ASS6019 HIGHEST ERROR-WEIGHT: NO ERRORS % ASS6006 LISTING GENERATOR TIME: 79 MSEC //end % ASS6012 END OF ASSEMBH /start-executable-program library=macexmp.lib,element-or-symbol=wrout1, - / prog-mode=*any % BLS0523 ELEMENT 'WROUT1', VERSION '@' FROM LIBRARY ':2OSG:$QM212.MACEXMP.LIB' IN PROCESS % BLS0524 LLM 'WROUT1', VERSION ' ' OF '<date> <time>' LOADED EXAMPLE WROUT 1
Example 2
WROUT2 START
PRINT NOGEN
BALR 10,0
USING *,10
WROUT MESSAGE,ERROR,PARMOD=31,MODE=LINE,OBELL=Y
2 *,@DCEO 999 921011 53531004
ERROR NOP 0
TERM
*
MESSAGE DC Y(ENDMESS-MESSAGE)
DS 3X
DC C'Output WROUT 2'
ENDMESS EQU *
END
Example 3
Use of VTSUCB
WROUT3 START
PRINT NOGEN
BALR 10,0
USING *,10
WROUT MESSAGE,ERROR,PARMOD=31,VTSUCBA=VTSUPAR
ERROR NOP 0
TERM
*
VTSUPAR VTSUCB MODE=LINE,BELL=YES
1 *,VTSUCB 350 980309
MESSAGE DC Y(ENDMESS-MESSAGE)
DS 3X
DC C'Output WROUT 3'
ENDMESS EQU *
END
Example 4
Use of format 2
WROUT4 START
PRINT NOGEN
BALR 10,0
USING *,10
LA 1,PARAM
WROUT (1),PARMOD=31
ERROR NOP 0
TERM
*
PARAM WROUT MESSAGE,ERROR,MF=L,PARMOD=31,MODE=LINE,OBELL=Y
2 *,@DCEO 999 921011 53531004
MESSAGE DC Y(ENDMESS-MESSAGE)
DS 3X
DC C'Output WROUT 4'
ENDMESS EQU *
END