General
Application areas: | Input/output of files and records; see "Input/output"Data terminal communication; see "Data terminal communication" |
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:
Neither symbolic names nor equates are generated for the standard header when MF=C/D is used. 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.
A user dump is produced if the UNIT field is supplied with an incorrect value.No return code is transferred in the standard header.
The CUPAB macro generates a DSECT of the RDATA operand list for the 24-bit interface format.
Macro description
RDATA enables the next data record to be read from SYSDTA.
SYSDTA can be assigned to a PLAM library element, a cataloged SAM or ISAM file or - typically - the user's terminal.
The record (or, in the case of the terminal, the message) is placed in an area of the user program as a variable-length record.
The keyboard is locked for the 8160, 9749 and 975x Data Display Terminals after an input with RDATA. This means that no further inputs are possible before the next output; only short codes are permitted.
If a “BREAK” is detected during the read operation, the program counter is reset to the start of the macro expansion, with the result that the macro is repeated after the interrupt has been processed.
On execution of the macro (in the case of format 1), the specified operands are stored in an operand table and the start address of this table is loaded into register R1. In the case of format 2, the table specified in the user program is used.
Macro format 1 and description of operands
RDATA |
record,error[,length][,edit][,A] ,KEYOUT=N / Y ,KEYPOS=N / Y ,KEYLEN=N / Y [{ MODE=COMP ,ITRSUP={NO / YES},ILINEND={NO / YES} ,ILCASE={NO / YES},IHDR={NO / YES} ,IGETBS={NO / YES} / ,MODE=LINE ,ILCASE={NO / YES},IGETBS={NO / YES} ,IGETFC={NO / YES},IGETIC={NO / YES} ,ICFD={NO / YES} }] ,RC=OLD / NEW [,VTSUCBA=addr] [,TIMER=value] ,PARMOD=24 / 31 [,MF=C / (C,pre) / (E,...) / (D,pre) / D / L] |
record
Symbolic address of the field to which the data record to be read is transferred. The field starts with a record length field. Record format:
Byte 0-1: record length + 4-byte record length field
Byte 2-3: reserved
Byte 4-n: data record.
Example
RECORD DS 0CL74 LENGTH DS CL2 RESERV DS CL2 DATA DS CL70
error
Symbolic address (name) in the user program to which a branch is made:
when an error occurs (read error, end of file,...)
if operand A is set.
If an error occurs, register R14 contains the address of the next instruction after the RDATA macro call. The error code is transferred in register R15.
31-bit interface: if error = 0 (address X'00..0') is specified, the program continues with the next instruction after the RDATA macro call.
length
Specifies the size of the read input area (“record”) including 4 bytes for the record length field. The maximum size permitted is 32767 bytes. If this operand is omitted, the length attribute of “record” is assumed.
edit
Specifies the edit option for a message input from the terminal. This operand is not necessary when standard functions (all edit bits = 0) are used, when a MODE specification is made or when the VTSU control block is used. Direct specification (X'xx') enables only the first edit byte for input to be set to the same meaning as specified in the CUPAB macro description.
Notes
This parameter only continues to be supported for reasons of compatibility.
The edit options should be controlled via MODE specifications (see the MODE operand) or via the VTSU control block (see the VTSUCBA operand).
A
The user program is notified of the initial standard assignment and each subsequent assignment to SYSDTA. This notification occurs via the error address (“erraddr”) as soon as the read operation has been completed. The assignment code is stored as follows:
24-Bit interface: | in the leftmost byte of register R15. |
31-Bit interface: | in the CURAIND field of the operand list. |
KEYLEN=
Determines whether or not the ISAM key length is to be stored. This operand is evaluated only if SYSDTA is assigned to an ISAM file.
N
The length of the ISAM key is not stored.
Y
The length of the ISAM key decremented by 1 is stored as follows:
24-bit interface: in the rightmost byte of register R0.
31-bit interface: in the CURKEYL field of the operand list.
KEYOUT=
Determines whether the record is to be transferred with or without the ISAM key. This operand is evaluated only if SYSDTA is assigned to an ISAM file.
N
The ISAM key is not to be removed.
Y
The ISAM key is removed.
KEYPOS=
Determines whether or not the ISAM key position is to be stored. This operand is evaluated only if SYSDTA is assigned to an ISAM file.
N
The ISAM key position is not stored.
Y
The ISAM key position decremented by 1 is stored as follows:
24-bit interface:
in the middle two bytes of register R0 if KEYLEN=Y is specified
in the two rightmost bytes of register R0 if KEYLEN=N is specified.
31-bit interface: in the CURKEYP field of the operand list.
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 = CUR
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 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.
Note
Any character string beginning with “Y” has the same meaning as the “Y” entry. Any character other than “Y” is interpreted as “N”; similarly any character string beginning with a character other than “Y” has the same effect as an “N” entry and gives rise to an MNOTE message.
The following operands are interpreted only if SYSDTA is assigned to the terminal. The MODE specifications together with the 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=COMP
Specifies compatible mode. Symbolic operands enable the user program to use all the edit options as defined in the edit option table (see the CUPAB macro). Any specifications made in the “edit” operand are ignored. Control characters in the text are passed unchecked to the user program. This operating mode is compatible with previous versions (compatible terminals supported: 8103, 8110, 8150, 8152, 8161).
This mode is interpreted as MODE=LINE for the devices 3270, 8160, 8162, 9749, 975x. All edit options other than ILCASE, IGETBS are rejected (RC: X'08').
MODE=LINE
If SYSDTA is a terminal, it is treated as a logical line terminal. The message may be structured with logical control characters (see the VTCSET macro). A device-specific message header is not provided. The operands for message editing are interpreted.
If SYSDTA is a cataloged file, i.e. not a terminal, the operands for message editing are not interpreted. For example, lowercase letters are not converted into uppercase letters if SYSDTA is a cataloged file and ILCASE has the NO value (default value). Logical control characters in the message are also not interpreted.
ICFD=
Specifies whether confidential data is to be protected.
NO
No precautions are to be taken to protect confidential data.
YES
The input data is confidential and is to be invisible at the terminal. Depending on the terminal used, this is implemented by blanking or clearing the screen or by overwriting the input line in the case of printer terminals.
IGETBS=
Determines whether underline characters (X'6D') are passed to the user program. This operand should be specified only for 8103 Data Display Terminals.
NO
Underline characters are not passed to the user program. Instead, the system performs the correction function.
YES
The underline characters (X'6D') are passed to the user program without being evaluated by the system.
IGETFC
Determines whether a function key code is to be transferred.
NO
No function key code is to be transferred.
YES
The 5th byte of the input area is to contain the standardized function key code. This code identifies the terminal key used to initiate data transfer (for standardized function key codes see the appendix).
IGETIC=
Determines whether the input source is to be changed.
NO
The input source is not to be changed.
YES
Input is to be from the connected ID card reader. The input data can consist only of ID card information or of the short code K14. This entry is permitted only for 8160, 9749, 975x and 3270 Terminals with a defined ID card reader (see also the TSTAT macro, TYPE=TCHAR). The IGETIC operand is ignored if ICFD=YES is also specified or if no ID card reader is connected.
IHDR=
Specifies how the message header is to be handled.
NO
The message header is not transferred to the user program.
YES
The entire message header is transferred to the user program. In the case of 3270 Terminals, the message header consists of the application ID (AID byte) and the 2-byte cursor position.
ILCASE=
Determines whether a distinction is to be made between uppercase and lowercase letters.
NO
All lowercase letters are transferred to the user program in uppercase format.
YES
Lowercase letters are also transferred to the user program.
ILINEND=
Specifies how carriage return and line feed characters are to be handled.
NO
The carriage return and line feed characters are not passed to the user program.
YES
The carriage return and line feed characters are passed to the user program.
ITRSUP=
Specifies whether or not the translation from device code to EBCDIC is to be suppressed.
NO
Translation from device code to EBCDIC is not suppressed. The user program receives the message in EBCDIC.
Exception
In the case of the 8161 Data Display Terminal, the message header is always supplied in the device code.
YES
Translation from device code to EBCDIC is suppressed. The user program receives the message in the device code. This entry is not valid for the 8161 Data Display Terminal.
RC=
Determines where the return code is to be stored.
This operand is permitted only for a 31-bit interface.
OLD
The return code is stored in the rightmost byte of register R15.
NEW
The return code is stored both in register R15 and in the standard header. All 4 bytes of register R15 are allocated for evaluation. A 4-byte return code is supplied only if SYSDTA reads from the data display terminal. In all other cases, only a 1-byte return code is supplied, irrespective of the return code value.
TIMER=value
Defines a maximum wait time for input. If no input is received within the defined wait time, a return code is issued. This operand may be specified only for the 31-bit interface.
value
Wait time of 10 to 3600 seconds. The default value is UNLIMITED, i.e. no timer is used.
VTSUCBA=addr
Defines the address of a VTSUCB generated with MF=L. This When the VTSUCBA operand is used, the MODE operand and the following EDIT options are ignored (the operand 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 for the 31-bit interface.
The VTSUCB is not used by default.
addr
Symbolic address (name) of the VTSUCB.
Macro format 2 and description of operands
RDATA |
(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. 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 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
Interface | Byte | Contents |
31-bit interface | 0 - 7 | Standard header. For structure see section “Standard header”The initialization values should be taken from an operand list generated |
8 - 11 | Address to be branched to if an error occurs (operand “error”). | |
12 - 15 | Address of the field to which the data record read is transferred | |
16 | Input edit byte 1 | |
17 | Input edit byte 2 | |
18 | Assignment code for SYSDTA | |
19 | Flag indicating use of VTSUCB and return code handling | |
20 - 21 | Maximum length of the data record to be read (operand “length”) | |
23 | SYSDTA assignment indicator (Bit 20 | |
24 - 25 | Position of the ISAM key | |
26 - 27 | Length of the ISAM key | |
28 - 31 | Address of the VTSUCB | |
32 - 33 | Timer values | |
34 - 35 | Reserved (X'00000000') | |
24-bit interface | 0 | Input edit byte 1 |
1 - 3 | Address of the field to which the data record read is transferred | |
4 | Flag | |
5 | Input edit byte 2 | |
6 - 7 | Maximum length of the data record to be read (operand “length”). | |
8 | SYSDTA assignment indicator (Bit 20 | |
9 - 11 | Address to be branched to if an error occurs (operand “error”). |
When using the 24-bit interface, the values for input 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 data list generated with MF=C/D.
Assignment code for SYSDTA
24-bit interface:
The assignment code is transferred in the leftmost byte of register
R1531-bit interface:
The assignment code is transferred in the CURAIND field of the
RDATA operand list.Code values and their meaning
Value
Meaning
X'00'
Assignment for SYSDTA is unchanged
X'04'
SYSDTA is assigned to a SAM file
X'08'
SYSDTA is assigned to an ISAM file
X'14'
SYSDTA is assigned to a terminal
X'18'
SYSDTA is assigned to an S variable
X'20'
SYSDTA is assigned to a PLAM library element
Flag byte and its meaning:
Bit 27 = 1/0 corresponds to KEYOUT=Y/N.Bit 26 = 1/0 corresponds to KEYPOS=Y/N.Bit 25 = 1/0 corresponds to KEYLEN=Y/N.
Return information and error flags
Where possible, the system corrects any edit options that are invalid for a particular device or for the operating mode MODE=.
During macro processing, register R1 contains the operand list address.
if PARMOD=24:
R15:
+---------------+ | | | | | |b|b|0|0|0|0|a|a| +---------------+
A return code relating to the execution of the RDATA macro is transferred in register R15, where: aa = Maincode; bb = assignment code if operand A is specified in conjunction with the 24-bit interface;
in all other cases bb = X'00'.
X'aa' | Meaning |
X'00' | Normal termination |
X'04' | Unrecoverable error |
X'08' | Operand error |
X'0C' | Record truncated. Record length > specified length |
X'10' | End of file (EOF) |
X'14' | SYSDTA not assigned |
X'18' | Error during volume access |
X'20' | Invalid edit option byte: error corrected by the system |
X'38' | Problem in connection with POSIX |
if PARMOD=31, RC=OLD:
Return codes that may occur in addition to those described under PARMOD=24 are 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 PARMOD=31, RC=NEW:
The return codes are entered both in the standard header and in register R15.
Standard header:
+---------------+ | | | | | |c|c|b|b|a|a|a|a| +---------------+
A return code relating to execution of the RDATA macro is transferred in the standard header:
aaaa=Maincode; bb=SUBCODe1, cc=Subcode2
X'cc' | X'bb' | X'aaaa' | Meaning |
X'00' | X'00' | X'0000' | Function processed successfully |
X'00' | X'00' | X'0014' | Function processed successfully, but SYSDTA not assigned |
X'00' | X'00' | X'0018' | Function processed successfully, but error occurred when accessing |
X'00' | X'00' | X'0020' | Function processed successfully. Operand error corrected via |
X'00' | X'01' | X'0008' | Operand error not corrected |
X'07' | X'01' | X'0008' | Operand error not corrected: |
X'08' | X'01' | X'0008' | Operand error not corrected: |
X'00' | X'20' | X'0004' | Internal error |
X'02' | X'20' | X'0004' | Internal error: BCAM message lost |
X'05' | X'20' | X'0004' | Internal error: input message too long |
X'06' | X'20' | X'0004' | Internal error: negative transport acknowledgment |
X'00' | X'40' | X'0004' | Input/output aborted |
X'00' | X'40' | X'000C' | Input record length > specified length: |
X'00' | X'40' | X'0010' | End of file (EOF) |
X'00' | X'40' | X'0034' | Timeout (no input received within specified wait time) |
X'01' | X'80' | X'0004' | Internal BCAM bottleneck |
X'09' | X'80' | X'0038' | Error in connection with POSIX: |
X'0A' | X'40' | X'0038' | Error in connection with POSIX: |
X'24' | VTSU error. In addition to main code (rightmost byte), see error |
Notes on the macro call
Truncation occurs if the record to be transferred is longer than specified in the length operand. The record is only transferred to the read input area in accordance with the length specified in the length operand; the remainder of the record is lost. If the record is shorter than the read input area, it is entered left-justified and the remainder is not filled with blanks. The program continues without an error flag.
The end-of-file condition (EOF) can occur in the following ways:
Interactive mode:
Activate the ESCAPE function (K2 key). Job processing switches over to command mode. Then issue the EOF command followed by RESUME-PROGRAM.Procedure or batch mode:
The (system) files SYSDTA and SYSCMD are assigned to each other and a data record starting with a slash is read.
Exceptions:
the slash has been replaced by symbolic operands.
the record starts with two consecutive slashes
(e.g. SDF statement).
The (system) files SYSDTA and SYSCMD are not assigned to each other:The EOF command is detected in columns 1-4 of the record.
For examples, see section “S-type macros”.