READ

Purpose

Use the READ subcommand to place information from the terminal in the console stack (LIFO). The READ subcommand is designed to be issued from a macro. After a READ subcommand is executed, a REXX macro has access to the stacked information through the REXX PULL instruction. (In an EXEC 2 macro, access can be gained through the &READ control statement.)

Operands

Cmdline

indicates stacking only the command input area in the console stack. This is the default.

All

indicates stacking all lines changed on the screen in the console stack, and stacking the command input area as the last line. The corresponding changes are also made to the copy of the file that is in virtual storage.

Nochange

is similar to the ALL option except the changes made on the screen are not made to the file being edited but are available from the console stack.

Number

indicates the file lines changed on the screen are to be prefixed by their file line numbers. Prefix area changes will be prefixed by their associated file line numbers only if the TAG option is specified.

Tag

indicates you want to insert a tag identifying the origin of the line at the beginning of each line stacked. (The tags are described in Note 3).

Notag

specifies no tags are inserted in the stacked lines.

Notes for Macro Writers

1. If a READ is issued from a typewriter terminal, only the command line is placed in the stack.
2. Pressing ENTER, a PF key, or a PA key terminates a READ subcommand; however, a key assigned to COPYKEY, NULLKEY, TABKEY, or the CP BRKKEY does not terminate a READ. Pressing CLEAR clears any data typed since the last time the ENTER key, a PF key, or a PA key was pressed, but this also does not terminate a READ. The operand specified for the READ subcommand (CMDLINE, ALL, or NOCHANGE) determines which lines are placed in the console stack. The same number of lines are stacked whether TAG or NOTAG is specified. The TAG operand causes each line in the stack to be preceded by a tag. The various tags are described in Note 3.

   Using READ CMDLINE

   The key pressed to terminate the READ command (a PF key, a PA key, or the ENTER key) and how that key is defined (BEFORE, AFTER, ONLY, or IGNORE) determine which lines are placed in the console stack.

   If something was entered on the command line, the console stack contains the following line(s), as determined by the definition of the key that was pressed:

   If the key was defined as BEFORE, the console stack contains:

   1. ENTER, PF, or PA key value (depending on which key was pressed)
   2. Command line

   If the key was defined as AFTER, the console stack contains:

   1. Command line
   2. ENTER, PF, or PA key value (depending on which key was pressed)

   If the key was defined as IGNORE, the console stack contains the command line.

   If the key was defined as ONLY, the console stack contains the ENTER, PF, or PA key value (depending on which key was pressed).

   If nothing was entered on the command line (or ERASE EOF was used to clear the command line), the console stack contains the definition of the key (ENTER, PF, or PA key) that was pressed.

   Using READ ALL or READ NOCHANGE

   The editor scans the screen (from top to bottom, left to right) and stacks all modified fields. Each modified field is stacked as a separate line. With either the ALL or the NOCHANGE operand, the console stack contains:

   1. ENTER, PF, or PA key value (depending on which key was pressed)
   2. Lines and prefix areas changed on the screen (if any)
   3. Command line (if something was entered on the command line)

   If nothing was changed on the screen, the console stack contains the ENTER, PF, or PA key value (depending on which key was pressed).

   Using CTLCHARs in non-RESERVED lines with READ NOCHANGE, may cause unpredictable results.

3. With the TAG operand specified, a tag that identifies the field precedes each line in the stack. The tags and their meanings are as follows:
   • CMD - command line
   • ETK - ENTER key
   • FIL - file line
   • PAK - PA key
   • PFK - PF key
   • PRF - prefix area
   • RES - reserved line

   The tag is followed by additional information and the modified field itself:

   • CMD string

     where string is whatever was typed in the command line.

     The string can be empty if an undefined key is pressed. In this case, only the tag (CMD) is stacked (or a null line if READ NOTAG is specified).

   • ETK string

     where string is the ENTER key definition.

   • FIL n1 n2 n3 string
     where:

     n1 n2

     are the line number and column number of the beginning of the line on the screen.

     n3

     is the corresponding file line number. This is returned ONLY if the READ subcommand was issued with the NUMBER option, otherwise it is omitted.

     string

     is the changed file line. (String can be empty if the ERASE EOF key was pressed.)

   • PAK n string
     where:

     n

     is the number of the PA key pressed to terminate the READ.

     string

     is the PA key definition.

     PAK lines are stacked LIFO.
   • PFK n string
     where:

     n

     is the number of the PF key pressed to terminate the READ.

     string

     is the PF key definition.

     PFK lines are stacked LIFO.
   • PRF n1 n2 n3 string
     where:

     n1 n2

     are the line number and column number of the prefix area on the screen.

     n3

     is the corresponding file line number associated with the prefix area. The file line number is returned only if the READ subcommand was issued with the NUMBER option, otherwise it is omitted.

     string

     is whatever was typed in the prefix area. (The string can be empty if the ERASE EOF key was pressed.) The string is whatever the user typed in the prefix area, as determined by XEDIT. For example, with SET NUMBER OFF, typing a in the prefix area returns a and not a====.

   • RES n1 n2 string
     where:

     n1 n2

     are the line number and column number of the reserved field on the screen.

     string

     is the reserved field that was changed. (The string can be empty if the ERASE EOF key was pressed.)

4. If a command is entered on a screen in MORE or HOLDING status, the command is placed in the CMS input queue (which is the same as the terminal input buffer). For more information on the program stack and terminal input buffer, see z/VM: REXX/VM User's Guide.
5. When a READ subcommand is issued from a REXX application, use both the QUEUED() and EXTERNALS() functions to determine if there is anything in the program stack or the terminal input buffer. For information on the QUEUED and EXTERNALS functions, see z/VM: REXX/VM Reference.

Responses

The message Macro-read n File(s) is displayed in the status area.

Messages and Return Codes

509E

Subcommand subcommand not valid from a prefix macro [RC=4]

520E

Invalid operand: operand [RC=5]

where return codes are: