INPUT SCREEN

General Form:

     INPUT SCREEN alpha_receiver [ , AT(row, column) ] [ , BOX(depth, width) ]

Where:

     row, column, height, width      = numeric expressions

The INPUT SCREEN statement is used to copy the specified portion of the screen currently being displayed into an alpha variable. The alpha variable can then later be used by the PRINT SCREEN statement to re-display the specified portion of the screen. This cycle has the same effect as the WINDOW OPEN/CLOSE statements.

This statement is not relevant in a graphical forms environment and can therefore only be used within text only applications. It is not supported for systems using DBCS code pages or UTF-8 encoded Unicode.

The screen is read row by row starting at the specified co-ordinates for the specified number of rows and columns.

If the AT values are omitted, the following defaults are assumed:

If the BOX values are omitted, the following defaults are assumed:

where MaxRow is the number of rows on the screen and MaxCol is the number of columns as defined in the TERMINFO description for the terminal. Thus for a normal 24x80 screen

INPUT SCREEN a$()
INPUT SCREEN a$(), AT(0,0),BOX(24,79)

are equivalent. Note that depth + 1 rows and width + 1 columns are copied. The depth and width are defined in this curious way for compatibility with BASIC-2C.

The information returned to the alpha variable from the INPUT SCREEN statement, consists of an 80-byte string containing header information about the display (see table 1.8), followed by three sections containing the actual characters, attribute and box graphic information, and color attribute information respectively. Each of these sections should be (( depth + 1 ) * ( width + 1 )) bytes. Characters are read from the screen row by row for the depth + 1 rows and column by column within each row for width + 1 columns. If the specified alpha variable is too small to store the required information, the contents of the alpha variable are truncated at the last complete section. For example:

INPUT SCREEN screen_1$, AT(5,5), BOX(5,5)

would enter rows 5 - 10 inclusive, columns 5 - 10 into the variable screen_1$ . For all of the required information to be correctly stored, the alpha variable screen_1$ must be dimensioned as follows:

To use INPUT SCREEN to store the entire contents of a standard 24x80 screen requires 6080 bytes

DIM screen$(80 + 25 * 80 * 3 )
INPUT SCREEN screen$()

Though it is not possible to write on the 25th row of a screen it must still be recorded as PRINT BOX(24,80) requires overscore box attributes on the 25th row.

A copy of a partitions screen can be saved to disk in INPUT SCREEN format either by pressing a special key or on receipt of a SIGUSR2* signal. The screen is written to a file named scrndxxx in the current directory where xxx is the partition. This file can then be loaded from disk by another user and displayed on their screen with the PRINT SCREEN statement. This facility is intended for remote support. The special screen dumping key is identified by the ScreenDump TERMINFO clause.

*      SIGUSR2 is a signal that can be sent to a process by issuing the Unix kill command.

Character information - Section 1

The next set of bytes, after the 80 bytes of header information, contains the characters present within the range specified by AT and BOX. Characters are read from the specified area row by row for the specified range, and column by column within each row for the specified range.

Video attribute and box graphic information - Section 2

The second section contains a one byte attribute for each character. The code represents the video attribute mode, and information about box graphics if present. The code is structured as follows:

Color attribute information - Section 3

This section stores a one byte code for each character. The code represents the background and foreground color attribute for the character. The background attribute is stored in the high order nibble and ranges from HEX(0x) to HEX(7x), while the foreground attribute is stored in the low order nibble and may have a value ranging from HEX(x0) to HEX(x7).

INPUT SCREEN will only record color information that is set with the special color sequence, HEX(020204 aa bb cc dd ee 0F) The BASIC-2C sequence HEX(02000605 aa bb cc dd ee 0F) is also supported though this sequence will only work if byte 22 of $OPTIONS is set to a non-zero value. Such sequences are only supported on certain terminal types, refer to the Terminal support chapter for more information.

If color attributes are not in use each byte in section 3 is set to HEX(07) for black background and a white foreground.

Syntax examples:

INPUT SCREEN screen$()
INPUT SCREEN test$,AT(row,col)
INPUT SCREEN new$, AT(2,4), BOX(7,7)
INPUT SCREEN FLD(window$.window_2$),AT(4,4)

See also:

PRINT SCREEN, WINDOW OPEN/CLOSE