READSCREEN

READSCREEN reads all or a specified part of the internal screen image.

Syntax

                      I         I          I         CA

READSCREEN       (terminalid, offset, maxinbuflen, inbuf,

                      I         I

                  actinbuflen, result)

Parameters

terminalid (input)

Integer identifying the terminal. The terminalid is returned in a call to the OPEN3270 intrinsic.

offset (input)

Integer specifying the offset, in characters, into the internal screen image. The first character position on the screen has an offset value of zero. Reading begins at the location you specify in offset. The offset parameter must be zero when the DBCS option to the OPEN3270 intrinsic is enabled.

maxinbuflen (input)

Integer specifying the maximum number of characters to return in inbuf.

inbuf (output)

Character array containing the contents of the field that was read. Trailing nulls are removed. Embedded and leading nulls are returned.

actinbuflen (output)

Integer indicating the number of characters actually returned in inbuf.

result (output)

The following values can be generated by the READSCREEN intrinsic:

0 = Successful completion.

1 = Device not open.

9 = Host modified screen since the last receive request. (MPE V only)

21 = Field offset specified is out of range.

22 = BASIC calling sequence error has occurred.

25 = Intrinsic call made while in split stack mode.

26 = Intrinsic call made with the parameter value out of bounds.

29 = Called intrinsic with a request already outstanding. (No-wait I/O only)

30 = Internal error occurred in IMF intrinsic.

42 = Specified MAXINBUFLEN parameter is too large.

53 = Invalid intrinsic called for data stream mode device.

100 = A bad (non-zero) offset was specified in the intrinsic call.

Description

The READSCREEN intrinsic returns any portion or all of the internal screen image. Portions of the returned screen that are non-display fields will be filled with nulls.

READSCREEN is a position-oriented intrinsic; it reads a section of the screen beginning at a specified character position. READFIELD is a field-oriented intrinsic; it reads a specified field of the screen and selects the field by number rather than by offset into the internal screen image.

The image returned by READSCREEN begins at a location determined from the value of the offset parameter and extends across all columns and down each row, terminating at the last position in the last row and column. Therefore, if the last field on the screen wraps around to the top of the screen, and you ask for less than a full internal screen image, READSCREEN will not return all of the last field.

By calling SCREENATTR before calling READSCREEN, you can determine whether the screen is formatted, and if so, how many fields there are in the screen. If you call READSCREEN when the screen is formatted, field attributes will be interspersed with data in your inbuf string.

Field attribute characters can be located by calling the ATTRLIST intrinsic. The ATTRLIST intrinsic will return all the attribute character locations within all or part of the internal screen image. If the values you choose for the ATTRLIST parameters offset and subscreensize are the same as those used in the READSCREEN parameters offset and maxinbuflen, you will access the same screen subsection. If the offsetlist array in your call to ATTRLIST is too small, the array will be filled, and the actual number of attribute characters within the specified screen subsection will be returned in actlistlen.

Field attribute characters can also be located by calling the FIELDATTR intrinsic. FIELDATTR returns the location of a specified field and the information about that field, which is coded in its attribute character. If a field is non-display, the displayattr parameter of the FIELDATTR intrinsic will be 3.

During LU.T3 printer emulation, you should routinely call RECV3270 after you have finished reading the current internal screen image. Calling RECV3270 will cause SNA IMF to inform the host that your "printer" is ready to receive more data. The host must wait for a printer to finish before sending more data; so, your program, using a device configured as a printer, can control host transmissions through the RECV3270 intrinsic.

If your device is configured on the host as a printer, your internal screen image may contain printer orders embedded in the data. Examples of printer orders are CR (Carriage Return) and NL (New Line). IBM 3287 printer models differ, so consult the IBM Information Display System Data Stream Programmer's Reference Manual (IBM part number GA23-0059) for further information about printer orders.




	NOTE: When checking for LU.T3 printer orders in your screen data, remember that the internal screen image is in ASCII.

Call the READSCREEN intrinsic in non-transparent mode.

COBOL Calling Sequence

CALL "CREADSCREEN" USING TERMINALID OFFSET MAXINBUFLEN INBUF ACTINBUFLEN RESULT. (on MPE V and in compatibility mode on MPE XL)

CALL INTRINSIC "READSCREEN" USING TERMINALID OFFSET MAXINBUFLEN INBUF ACTINBUFLEN RESULT. (in native mode on MPE XL)

All parameters are numeric data items except INBUF, which is an alphanumeric data item.

FORTRAN Calling Sequence

CALL READSCREEN (TERMINALID, OFFSET, MAXINBUFLEN, INBUF, ACTINBUFLEN, RESULT)

All parameters are integer variables except INBUF, which is a character array.

BASIC Calling Sequence

CALL BREADSCREEN (T, O1, L7, I$, L8, R) (on MPE V and in compatibility mode on MPE XL)

CALL READSCREEN (T, O1, L7, I$, L8, R) (in native mode on MPE XL)

All parameters are integer variables except I$, which is a string variable.




	NOTE: Because BASIC cannot read a string of more than 255 characters, and because the length of a screen will exceed 255 characters, you can use the `maxinbuflen` parameter to prevent the BASIC string variable from overflowing. `offset` allows you to begin reading at the location you specify. Multiple calls to `READSCREEN` with different `offset` values can give BASIC programs the entire screen.

SPL Calling Sequence

READSCREEN (TERMINALID, OFFSET, MAXINBUFLEN, INBUF, ACTINBUFLEN, RESULT)

All parameters are integer data items except INBUF, which is a byte array.

Pascal Calling Sequence

READSCREEN (TERMINALID, OFFSET, MAXINBUFLEN, INBUF, ACTINBUFLEN, RESULT);

All parameters are short integers except for INBUF, which is a packed array of char.

C/XL Calling Sequence

READSCREEN (&TERMINALID, &OFFSET, &MAXINBUFLEN, INBUF, &ACTINBUFLEN, &RESULT);

All parameters are of type short, except INBUF, which is a character array (a pointer to a char).

Pascal Program Excerpts

Following are excerpts from a Pascal program that calls SNA IMF intrinsics. For examples of complete Pascal programs in non-transparent and transparent modes, see Appendix F “Sample Programs”

{************************** Global Declarations **************************}typeshortint      = -32768..32767;       { global type, two bytes (half word) }...var   terminalid    : shortint;          { value returned by OPEN3270 intrinsic }   result        : shortint;...procedure READSCREEN;  intrinsic;...{************************** Local Declarations **************************}var   offset        : shortint;   { All READSCREEN variables except }   maxinbuflen   : shortint;   { terminalid and result are local. }   inbuf         : packed array[1..1920] of char;   actinbuflen   : shortint;...{************** Variable Initialization and Intrinsic Call **************}offset := 0;maxinbuflen := 1920;inbuf := ' ';READSCREEN (terminalid, offset, maxinbuflen, inbuf, actinbuflen, result);