HP 3000 Manuals HP 3000 Manuals
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 SCREENATTRbefore 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 ordersembedded in the data. Examples of
printer orders are CR (Carriage Return)and NL (New Line). IBM 3287
printer models differ, so consult chapter 6 of the IBM Information
Display System Data Stream Programmer's Reference (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 **************************}
type
shortint = -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);