READSTREAM

READSTREAM reads all or part of the untranslated host data stream.

Syntax

                      I         I          I        CA

READSTREAM       (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 indicating the offset, in characters, into the data stream. The first character in the data stream has an offset of zero. The data transfer 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 data stream.

actinbuflen (output

Integer indicating the number of characters actually returned in inbuf.

result (output)

The following values can be generated by the READSTREAM 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.

49 = Value specified for the INBUF parameter is too small to hold the entire data stream.

50 = Called READSTREAM without calling RECV3270 first.

52 = Data stream is too long.

54 = Device not opened in transparent mode.

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

Description

To use the READSTREAM intrinsic, open a device in transparent mode by calling the OPEN3270 intrinsic with bit 14 of the flags parameter set to 1.

With SDLC protocol, data received from the host is contained in the Request Unit (RU). The RU is preceded by some header bytes known as the Request Header (RH). The RU contains the data stream commands and the data. Each LU.T2 and LU.T3 RU (or each RU chain, if RU chaining is used) from the host contains a 3270 data stream command. LU.T1 RUs contain SCS control codes instead of 3270 data stream commands.

SNA IMF removes the RH bytes and stores the rest of the RU in the internal screen image. For LU.T2 and LU.T3 sessions, the first byte in the internal screen image is the 3270 data stream write command.

To obtain host data, first call the RECV3270 intrinsic, and then call the READSTREAM intrinsic. After calling RECV3270, the stream of data received from the host is buffered in the internal screen image. Calling READSTREAM retrieves the data from the internal screen image. You can access all or any part of the RU through the READSTREAM intrinsic.

If the host attempts to write more data to your internal screen image before you have called RECV3270 to retrieve the data already stored there, SNA IMF rejects the command with sense code X'0820', "device busy." This rejection prevents the host from writing over a data stream that you have not received. You should call RECV3270 and READSTREAM for every RU received.

The READSTREAM intrinsic can be called only in transparent mode. See Chapter 2 “Using SNA IMF Intrinsics” for more information about transparent mode.

COBOL Calling Sequence

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

CALL INTRINSIC "READSTREAM" 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 READSTREAM (TERMINALID, OFFSET, MAXINBUFLEN, INBUF, ACTINBUFLEN, RESULT)

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

BASIC Calling Sequence

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

CALL READSTREAM (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 choose the portion of the screen to read. Multiple calls to `READSTREAM` with different `offset` values can give BASIC programs the entire screen.

SPL Calling Sequence

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

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

Pascal Calling Sequence

READSTREAM (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

READSTREAM (&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 READSTREAM;  intrinsic;...{************************** Local Declarations **************************}var   offset        : shortint;   { All READSTREAM 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 := 100;inbuf := ' ';READSTREAM (terminalid, offset, maxinbuflen, inbuf, actinbuflen, result);