HP 3000 Manuals HP 3000 Manuals
READFIELD
READFIELDreads a field of data from the internal screen image.
Syntax
_______________________________________________________________
| |
| I I I I |
| READFIELD (terminalid, fieldnum, offset, maxinbuflen,|
| |
| CA I I |
| inbuf, actinbuflen, result |
_______________________________________________________________
Parameters
terminalid (input)
Integer identifying the terminal. The terminalid is returned in a call
to the OPEN3270 intrinsic.
fieldnum (input)
Integer indicating the relative field number. Field number 1 is the
field following the first attribute character in the internal screen
image. Field numbers start at 1 and continue through numfields (returned
by the SCREENATTR intrinsic), unless the screen is unformatted, which
means that numfields and fieldnum are both zero. Put a zero in fieldnum
if the screen is unformatted. (An unformatted screen has no attribute
characters.)
offset (input)
Integer specifying the offset value, in characters, of the first
character position read from 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 actual number of characters returned in inbuf.
result (output)
The following values can be generated by the READFIELD intrinsic:
0 = Successful completion.
1 = Device not open.
9 = Host modified screen since the last receive
request. (MPE V only)
11 = Non-existent field number was specified.
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.
53 = Invalid intrinsic called for data stream mode
device.
100 = A bad (non-zero) offset was specified in the
intrinsic call.
Description
The READFIELD intrinsic returns the contents of a specified field in the
internal screen image. You pass the terminal ID, a field number, an
offset within the field, and the maximum number of characters to
transfer. The READFIELD intrinsic returns the contents of the field
(unless it is non-display) and the actual length of the data returned.
If the specified field is non-display, the inbuf parameter is filled with
a number of nulls equal to the value in the maxinbuflen parameter.
By calling SCREENATTR before calling READFIELD, you can determine whether
the screen is formatted, and if so, the number of fields in the screen.
If the screen is unformatted (the SCREENATTR intrinsic has returned a
numfields value of zero), you can read the screen by calling READFIELD
with the fieldnum parameter set to zero.
If you specify a maxinbuflen of more characters than a field actually
contains, READFIELD will return a number of characters equal to the
number of characters in the field.
During printer emulation, you should routinely follow your last call to
READFIELD (or to READSCREEN) with a call to RECV3270. The host cannot
interrupt READFIELD with a data transmission during printer emulation,
and you must call RECV3270 to indicate to the host that you are finished
with the previous screen of data.
If your device is configured as an LU.T3 printer on the host side, 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 3270
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.
Use the READFIELD intrinsic in non-transparent mode.
COBOL Calling Sequence
CALL "CREADFIELD" USING TERMINALID FIELDNUM OFFSET MAXINBUFLEN INBUF
ACTINBUFLEN RESULT. (on MPE V and in compatibility mode on MPE XL)
CALL INTRINSIC "READFIELD" USING TERMINALID FIELDNUM 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 READFIELD (TERMINALID, FIELDNUM, OFFSET, MAXINBUFLEN, INBUF,
ACTINBUFLEN, RESULT)
All parameters are integer variables except INBUF, which is a character
array.
BASIC Calling Sequence
CALL BREADFIELD (T, N, O1, L7, I$, L8, R) (on MPE V and in compatibility
mode on MPE XL)
CALL READFIELD (T, N, O1, L7, I$, L8, R) (in native mode on MPE XL)
All parameters are integer variables except I$, which is a string
variable.
NOTE Since BASIC cannot read a string of more than 255 characters, and
since the length of a field on the internal screen may exceed 255
characters,the maxinbuflen parameter is provided to prevent the
BASIC string variable from overflowing. The offset parameter
permits you to choose which portion of the field to read. Multiple
calls to READFIELD with different offset values can permit programs
written in BASIC to read all of a field that is longer than 255
characters.
SPL Calling Sequence
READFIELD (TERMINALID, FIELDNUM, OFFSET, MAXINBUFLEN, INBUF, ACTINBUFLEN,
RESULT)
All parameters are integer variables except INBUF, which is a byte array.
Pascal Calling Sequence
READFIELD (TERMINALID, FIELDNUM, OFFSET, MAXINBUFLEN, INBUF, ACTINBUFLEN,
RESULT);
All parameters are short integer variables except INBUF, which is a
packed array of char.
C/XL Calling Sequence
READFIELD (&TERMINALID, &FIELDNUM, &OFFSET, &MAXINBUFLEN, INBUF,
&ACTINBUFLEN, &RESULT);
All parameters are of type short, except INBUF, which is an array of
characters (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 READFIELD; intrinsic;
.
.
.
{************************** Local Declarations **************************}
var
fieldnum : shortint; { All READFIELD variables }
offset : shortint; { except terminalid and result }
maxinbuflen : shortint; { are local. }
inbuf : packed array[1..1920] of char;
actinbuflen : shortint;
.
.
.
{************** Variable Initialization and Intrinsic Call **************}
fieldnum := 2;
offset := 0;
maxinbuflen := 80;
inbuf := ' ';
READFIELD (terminalid, fieldnum, offset, maxinbuflen, inbuf,
actinbuflen, result);