VSCREEN WAITREAD

Read syntax diagramSkip visual syntax diagram VSCreen WAITRead vname

Authorization

General User

Purpose

Use the VSCREEN WAITREAD command from an exec to update the virtual screen with data in the virtual screen queue, refresh the physical screen, and wait for the next attention interrupt.

Operands

vname
is the name of the virtual screen that is to wait for input.

Usage Notes

  1. All windows showing virtual screens other than the virtual screen specified in the VSCREEN WAITREAD command are protected. The windows showing the specified virtual screen are either protected or unprotected, depending on how the data being displayed is defined in the virtual screen.
  2. VSCREEN WAITREAD executes in the following manner:
    • Each virtual screen is updated with data from the virtual screen queue.
    • The screen image is rebuilt based on the ordered list of windows and displayed on the physical screen.
    • The next interrupt is awaited. (The virtual screen specified in the VSCREEN WAITREAD command is now active.)
    • When the interrupt is received, the screen is read.
    • Information regarding the key pressed, the cursor, and modified fields are passed back to the exec in variables.

    The virtual screen can then be updated with the variables by using the VSCREEN WRITE command.

    The exec variables contain:
    WAITREAD.0
    the number of variables returned (excluding WAITREAD.0)
    WAITREAD.1
    the key that caused the attention interrupt (such as PAKEY n, PFKEY n,CLEAR, or ENTER)
    Note:
    a.
    WAITREAD.1 is set to UNKNOWN when the System Request key is used to generate the attention interrupt and no other system. For example, VM/VTAM session managers, and so forth traps the System Request key interrupt.
    b.
    The changed areas (WAITREAD.3, and so forth) may be set when UNKNOWN is returned in WAITREAD.1.
    c.
    The UNKNOWN value can also be set due to an interrupt by CP. For example, a warning message.
    WAITREAD.2
    the word CURSOR followed by the line number and column number of the cursor in the virtual screen, followed by the word DATA or RESERVED indicating the area the cursor was located. If the cursor was in a DATA or RESERVED area, the following line and column number pairs may be returned: 
          LINE     COLUMN
a.     n          n
b.     0          n
c.     0          2
    Where:
    a.
    specifies the cursor was positioned between the top and bottom of the virtual screen. The line number may range from one (1) to the number of scrollable data lines in the virtual screen. The column number may range from one (1) to the number of columns in the virtual screen.
    b.
    specifies the cursor was positioned on the line immediately following the bottom of the virtual screen. The line number will be zero (0), and the column number may range from one (1) to the number of columns in the virtual screen.
    c.
    specifies the cursor was positioned on a line following the bottom of the virtual screen, but the line was not necessarily the one immediately following the virtual screen bottom. The line number will be zero (0), and the column number will be two (2).

    If the cursor was not in a DATA or RESERVED area, the line and column numbers will both be -1.

    WAITREAD.3
     
    WAITREAD.n
    where each variable contains the word DATA or RESERVED indicating the type of text updated, followed by the line number and column number of the field that was modified, followed by the modified text.
    Note: The keyword values returned in WAITREAD.0, WAITREAD.1, and WAITREAD.2, as well as the EXEC variables WAITREAD.n, are always in American English (AMENG).
  3. VSCREEN WAITREAD is an important command for execs that read from and write to windows. A typical sequence for such an exec would be:
    • Define a window and virtual screen (WINDOW DEFINE and VSCREEN DEFINE commands)
    • Connect the window to the virtual screen (WINDOW SHOW command)
    • Write data to the virtual screen (VSCREEN WRITE command)
    • Issue the VSCREEN WAITREAD command.

    When an interrupt is received, the exec can process the WAITREAD.n variables and update the virtual screen using the VSCREEN WRITE command.

  4. A field definition character is placed at the start of each row if:
    • A window is not connected to a virtual screen at column 1, or
    • The number of columns in the window, virtual screen, and physical screen are not the same

    As a result, data is shifted one character to the right in each row so data in column one is not lost. Lines may be truncated on the right, and the location information indicates the window is showing one less character from the virtual screen.

  5. When windows overlap on the physical screen, a field definition character is placed at each window boundary.
  6. If only part of a field from a virtual screen is displayed on the physical screen and the field is modified, the entire field is returned as a modified field in a variable WAITREAD.n.
  7. The same field can be modified in different windows. These modifications are processed from the top of the screen to the bottom, moving from left to right.
  8. The lines in a window that are not top reserved lines, bottom reserved, or data lines from the virtual screen are called pad lines. When a window is connected to the active virtual screen, the pad lines are unprotected. If there are multiple windows connected to the same active virtual screen, only the pad lines of the top-most window are unprotected.
  9. Any part of a window that does not map to the virtual screen is protected. For example, suppose you have defined a window that is 24 rows by 80 columns and a virtual screen that is 20 rows by 60 columns. When you connect the window to the virtual screen at row 1 column 1, the 4 rows and 20 columns in the window that do not map to the virtual screen are protected.
  10. If the window or windows showing the active virtual screen are not visible on the screen, the WM window is automatically displayed. See Things You Should Know about Full-Screen CMS under SET FULLSCREEN for more information.

Messages and Return Codes

  • DMS329W Warning: APL/TEXT option not in effect
  • DMS386E Missing operand(s) [RC=24]
  • DMS388E Invalid keyword: keyword [RC=24]
  • DMS391E Unexpected operand(s): operand [RC=24]
  • DMS494W FULLREAD set off.
  • DMS614E Screen modifications lost. See ‘SET FULLREAD’ to use PAkeys safely.
  • DMS622E Insufficient free storage [RC=104]
  • DMS629W Screen modifications may be lost. Press ENTER key to process screen changes.
  • DMS631E WAITREAD can only be executed from an EXEC-2 or REXX exec [RC=4]
  • DMS696W Invalid data received from the display
  • DMS917E No windows are showing virtual screen vname [RC=4]
  • DMS921E Virtual screen vname is not defined [RC=28]
  • DMS925E I/O error on screen [RC=100]
  • DMS926E Command is only valid on a display terminal [RC=88]
  • DMS928E Command is not valid for virtual screen vname [RC=12]

Additional system messages may be issued by this command. The reasons for these messages and their location are:

Reason Location
Errors in command syntax Command Syntax Error Messages