HP 3000 Manuals HP 3000 Manuals
RECV3270
RECV3270
allows your program to receive the screen after the host has modified it.
Syntax
_______________________________________
| |
| I I |
| RECV3270 (terminalid, result)|
_______________________________________
Parameters
terminalid (input)
Integer identifying the terminal. The terminalid is returned in a call
to the OPEN3270 intrinsic.
result (output)
The following values can be generated by the REVC3270 intrinsic:
0 = Successful completion.
1 = Device not open.
22 = BASIC calling sequence error has occurred.
23 = Keyboard enable timeout has occurred.
24 = Response timeout 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)
91 = LU.T1 bind received.
92 = Unbind received.
93 = LU.T3 bind received.
94 = HOLD PRINT timer has expired (10 minutes).
95 = Host application requests PA key entry.
301 = Illegal DB register.
302 = Invalid session.
305 = Parameter bounds violation.
306 = Invalid flag parameter.
308 = Session is inactive.
315 = Internal error.
319 = LU-SSCP message pending.
325 = Request pending.
332 = Privilege mode required.
336 = Link shutdown occurred.
337 = Protocol shutdown requested.
338 = Quiesce shutdown requested.
340 = No stack space.
351 = Link failure occurred .
352 = Transport internal error shutdown.
353 = Hierarchical shutdown.
Description
The RECV3270 intrinsic performs 3 functions:
1. It allows your program to suspend processing and wait for new
data, and then it informs your program when data has arrived from
the host.
2. It tells SNA IMF whether your program has received the host data
since the last time the host updated the screen.
3. It allows a program emulating a printer (LU.T1 or LU.T3) to
control host transmissions so that data in the internal screen
image is not overwritten before your program has a chance to
process it.
With standard (wait) MPE I/O, the RECV3270 intrinsic suspends your
program until data arrives from the host or until the timeout interval
specified in the OPEN3270 intrinsic has expired.
If your program calls the RECV3270 intrinsic without having set the
receive timeout, and the host does not send any data, your program will
be suspended indefinitely. Therefore, you should always set the receive
timer portion of the timeout parameter of the OPEN3270 intrinsic to
ensure that your program can regain control after an unresolved RECV3270
call.
If your program is emulating an IBM 3278 display station (LU.T2) with
standard I/O, a call to RECV3270 suspends processing until a transmission
arrives from the host. Then, RECV3270 updates a counter telling SNA IMF
that your program has seen the most recent internal screen image.
SNA IMF/XL and SNA IMF/V handle LU.T2 emulation differently. When a new
transmission arrives from the host, SNA IMF/XL does not update the
internal screen image unless your program has called RECV3270 and is
waiting for data from the host. If your program has not called RECV3270,
SNA IMF/XL waits for a RECV3270 call before it updates the internal
screen image. SNA IMF/V updates the internal screen image whether or not
your program has called RECV3270.
NOTE With no-wait I/O, you must follow each call to RECV3270 with a call
to IOWAIT, IOWAIT3270, IODONTWAIT, or IODONTWAIT3270.
If SNA IMF/V receives host data and updates the internal screen image
before your program calls RECV3270, it can tell from the counter that
your program has not read the internal screen image since the last host
transmission. If your program then calls, for example, READFIELD (or any
intrinsic that accesses the internal screen image), SNA IMF/V will return
a result code of 9, indicating that the host has updated the internal
screen image since the last time your program received it.
Result code 9 tells your program that the field it just attempted to read
belongs to a different screen image from the data it read previously.
Whenever your program receives result code 9, it should call RECV3270.
SNA IMF/V then updates the counter and allows your program to access the
most recent screen image.
SNA IMF/XL does not return a result code of 9, so you must check the
result parameter after a call to RECV3270 to determine whether the host
has sent new data. If result = 0, the host has sent new data, and the
internal screen image has been updated. If result = 24, the receive
timer has expired, and the internal screen image has not been updated.
If your program is emulating a printer (LU.T1 or LU.T3), the RECV3270
intrinsic can prevent the IBM host from sending new data before your
program has a chance to process the current screen image.
Ordinarily, SNA IMF sends a positive response to the IBM host after it
receives a transmission, whether or not your program has called RECV3270.
However, during printer emulation, SNA IMF delays sending its positive
response until your program processes the new data and calls RECV3270
again.
During printer emulation (with standard I/O), the first call to RECV3270
suspends your program until data has arrived for it, then it informs your
program that the host has updated the internal screen image. Your
program can then call other SNA IMF intrinsics to check the screen,
locate field attributes, read data, and so on, while the host is still
waiting for a positive response. When your program has finished
processing the current screen image, it must call RECV3270 again. This
RECV3270 call tells SNA IMF that your program is finished processing and
is ready for more data. SNA IMF then sends a positive response to the
IBM host, and the host can continue transmitting.
After your program calls the OPEN3270 intrinsic, it must immediately call
the RECV3270 intrinsic. This first RECV3270 call receives the SNA IMF
banner screen from the OPEN3270 intrinsic. This first internal screen
image can be discarded, and you can continue with your processing.
In most cases, you should follow a call to TRAN3270 with a call to
RECV3270 to receive any data that the host sends in response to your
transmission. However, if you know that the host will not respond to
your transmission, you can call RESET3270 to reenable the keyboard.
(Successful calls to TRAN3270 disable the keyboard.)
The host might update the screen in more than one transmission.To ensure
that you always receive a complete screen from the host, you might need
to write your program to issue a variable number of RECV3270 intrinsic
calls.
If the host system always sends a keyboard enable in the last
transmission, you can set the keyboard enable timer in your call to the
OPEN3270 intrinsic. Then you need to call RECV3270 only once to receive
a complete screen image. The RECV3270 intrinsic will not complete until
the keyboard enable has been received or the timer has run out.
NOTE Be aware of any changes in your host system software. For example,
TSOalways sends the keyboard enable timer in the last transmission,
but other applications might not. Also be aware of changes in
protocol. If you migrate from BSC to SDLC, more host transmissions
are involved in starting your SNA session. You may need to modify
the logon routine in your program to issue more RECV3270 intrinsic
calls when an SNA session is initiated.
The RECV3270 intrinsic can be called in either transparent or
non-transparent mode.
With no-wait I/O, your program can call RECV3270 for several different
devices. It can then call IOWAIT or IOWAIT3270, and it will suspend
processing until data has arrived for one of the devices.
After calling RECV3270 with no-wait I/O, your program can call IODONTWAIT
or IODONTWAIT3270, instead of IOWAIT or IOWAIT3270, and it will not be
suspended. Each time your program calls IODONTWAIT or IODONTWAIT3270,
SNA IMF checks to see if data has arrived for a device and informs your
program. If no data has arrived, your program continues processing, and
it must call IODONTWAIT or IODONTWAIT3270 again later to see if data has
arrived.
With no-wait I/O, every call to RECV3270 must be followed by a call to
IOWAIT, IOWAIT3270, IODONTWAIT, or IODONTWAIT3270. Result codes that
would be returned through the RECV3270 intrinsic with standard wait I/O
are returned through the IOWAIT, IOWAIT3270, IODONTWAIT, and
IODONTWAIT3270 intrinsics with no-wait I/O.
For more information on using the RECV3270 intrinsic with no-wait I/O,
see chapter 4, "Intrinsics Used with No-Wait I/O."
COBOL Calling Sequence
CALL "CRECV3270" USING TERMINALID RESULT. (on MPE V and in compatibility
mode on MPE XL)
CALL INTRINSIC "RECV3270" USING TERMINALID RESULT. (in native mode on MPE
XL)
Both parameters are numeric data items.
FORTRAN Calling Sequence
CALL RECV3270 (TERMINALID, RESULT)
Both parameters are integer variables.
BASIC Calling Sequence
CALL BRECV3270(T, R) (on MPE V and in compatibility mode on MPE XL)
CALL RECV3270(T, R) (in native mode on MPE XL)
Both parameters are integer variables.
SPL Calling Sequence
RECV3270 (TERMINALID, RESULT)
Both parameters are integer variables.
Pascal Calling Sequence
RECV3270 (TERMINALID, RESULT);
Both parameters are short integer variables.
C/XL Calling Sequence
RECV3270 (&TERMINALID, &RESULT);
Both parameters are of type short.
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 RECV3270; intrinsic;
.
.
.
{************************** Intrinsic Call **************************}
RECV3270 (terminalid, result);