READFIELD

READFIELD reads 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 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 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);