HP 3000 Manuals HP 3000 Manuals
OPEN3270
OPEN3270emulates turning onthe power to a 3278 display station or 3287
printer.
Syntax
______________________________________________________________________
| |
| I CA I I I |
| OPEN3270 (devicenum, snalnkinfo, flags, terminalid, devtype,|
| |
| I I IA I |
| ffindex, screensize, timeout, result) |
______________________________________________________________________
Parameters
devicenum (input)
Integer identifying the device to be emulated. The devicenum parameter
must be -2 for a terminal, -1 for an LU.T1 printer, or -3 for an LU.T3
printer.
snalnkinfo (input)
Character array that represents the name of the SNA node and the
SNA class. For SNA IMF/V, the format of snalnkinfo is snanode#
snaclassname.For SNA IMF/XL, the format of snalnkinfo is snanode#
security classname. A pound sign (#) must separate the array items. The
snalnkinfo parameter identifies the section of the Node Management
Services configuration file (NMCONFIG.PUB.SYS) used by the SNA link
product. The snalnkinfo parameter must end with a non-alphanumeric
character. The following characters cannot be used as terminators:
# / [ ] . , :
flags (input)
A word whose bit groups specify the following options: wait or no-wait
I/O, transparent or non-transparent mode, internal tracing, LU support,
UNBIND option, and DBCS option. Bit groups are listed using the standard
SPL notation: (15:1) indicates bit 15, and (10:3) indicates bits 10, 11,
and 12. See table 3-2, following the flags parameter description, for
OPEN3270 configuration options for setting up LU.T1 or LU.T3 emulation.
Bit (15:1)
Input/Output (I/O) mode. (See chapter 2 for
information on wait and no-wait I/O.)
0 = Standard (wait) I/O. Your program will
be suspended during I/O processing.
1 = No-wait I/O. I/O requests are
overlapped, and your program continues
to execute while I/O requests are
outstanding.
Bit (14:1)
Transparent/Non-Transparent mode. (See chapter 2
for information on transparent and non-transparent
modes.)
0 = Non-transparent mode. The data stream
is translated into an image of the terminal
screen.
1 = Transparent mode. Your program has
access to the untranslated data stream.
Bit (13:1)
Internal tracing.
0 = Internal tracing is off.
1 = Internal tracing is on. SNA IMF internal
tracing should be used only at the request
of your HP representative to collect data
for problem determination. Enabling the
tracing facility degrades performance.
The trace file is named IMFnnTxx, where
nn is the NAU number and xx is a unique
two-digit identifier.
Bit (12:1) LU.T1/LU.T3 support for IBM 3287 printer emulation.
The effect of this option depends on the value in
bit 14 and the value in the devicenum parameter.
See table 3-2 for more information.
0 = This option supports either LU.T1 or
LU.T3 emulation but not both.
Which LU type is emulated depends on
the value of the devicenum parameter.
If devicenum = -1, bit 14 of the flags
parameter must also be set to 1. When in
LU.T1 sessions, the PA1, PA2, and CANCEL keys
are accepted
by TRAN3270.
1 = This option allows a printer to accept
both LU.T1 and LU.T3 sessions. LU.T1
sessions are in transparent mode, and
LU.T3 sessions are in non-transparent
mode. If devicenum = -1, bit 14 of the
flags parameter must also be set to 1.
When in LU.T1 sessions, the PA1, PA2,
CANCEL, HOLD, and ENABLE keys are
accepted by TRAN3270, and additional
RECV3270 result codes 91 through 95
may be returned. When in LU.T3
sessions, the printer keys cannot be used
and the additional RECV3270 result codes
will not be returned.
Bit (11:1) UNBIND option.
0 = UNBIND option is disabled. SNA IMF
will send the LUSTAT X'0831' if closing
while an LU-LU session is active.
1 = UNBIND option is enabled. SNA IMF
will send UNBIND instead of LUSTAT
if closing while an LU-LU session is
active.
Bit (10:1) DBCS option.
0 = Double-Byte Character Set option is
disabled. SNA IMF/XL will process 8-bit
data only.
1 = Double-Byte Character Set option is
enabled. SNA IMF/XL will process 8-bit
and 16-bit data.
Bits (0:10) Reserved.
Table 3-2 shows how bits 12 and 14 of the flags parameter work with the
value in the devicenum parameter to set up SNA IMF for printer emulation.
Table 3-2. Setting Up LU.T1 or LU.T3 Emulation
--------------------------------------------------------------------------------------------
| |
| LU.T1/LU.T3 devicenum Transparent Effect |
| (bit 12) parameter Mode (bit 14) |
| |
| 0 -1 1 LU.T1 is the initial setup. Only LU.T1 |
| sessions are accepted. Uses transparent |
| mode intrinsics. PA1, PA2, and CANCEL keys |
| accepted. |
| |
| 1 -1 1 LU.T1 is the initial setup. Both LU.T1 and |
| LU.T3 sessions are accepted. LU.T1 |
| sessions are in transparent mode, LU.T3 |
| sessions are in non-transparent mode. All |
| printer keys are accepted for LU.T1. New |
| result codes returned ( RECV3270). |
| |
| 0 -3 1 LU.T3 is the initial setup. Only LU.T3 |
| sessions are accepted. Uses transparent |
| mode intrinsics. (No printer keys accepted |
| for LU.T3.) |
| |
| 1 -3 1 LU.T3 is the initial setup. Both LU.T1 and |
| LU.T3 sessions are accepted. LU.T1 |
| sessions are in transparent mode, LU.T3 |
| sessions are in non-transparent mode. All |
| printer keys are accepted for LU.T1. New |
| result codes returned ( RECV3270). |
| |
| 0 -1 0 Error: |
| Non-transparent mode with LU.T1 was |
| specified. |
| |
| 1 -1 0 Error: |
| Non-transparent mode with LU.T1 was |
| specified. |
| |
| 0 -3 0 LU.T3 is the initial setup. Only LU.T3 |
| sessions are accepted. Uses |
| non-transparent mode intrinsics. (No |
| printer keys accepted for LU.T3.) |
| |
| 1 -3 0 LU.T3 is the initial setup. Both LU.T1 and |
| LU.T3 sessions are accepted. LU.T1 |
| sessions are in transparent mode, LU.T3 |
| sessions are in non-transparent mode. All |
| printer keys are accepted for LU.T1. New |
| result codes returned ( RECV3270). |
| |
--------------------------------------------------------------------------------------------
terminalid (output)
Integer identifying the terminal. This terminal identifier returned by
OPEN3270 is used by other SNA IMF intrinsics to identify a device. The
terminalid parameter is also used by IOWAIT and IODONTWAIT when doing
no-wait I/O (terminalid=filenum).
devtype (output)
Integer identifying the device type. Possible values are as follows:
2 = 3278 display station/keyboard
8 = 3287 printer with 3274/3276 attachment
ffindex (input)
This parameter is not used by SNA IMF, but it is included for backward
compatibility. The application calling OPEN3270 is responsible for
managing the number of lines per page for printers.
screensize (output)
This parameter is always defined as 1920 characters until the BINDis
received from the host. The BIND may specify a buffer size of 480 or
3440 characters.
timeout (input)
An integer array of 2 words that contains timeout values. The first word
is the keyboard enable timeout value, and the second word is the
transmit/receive timeout value. The keyboard enable timer controls the
RECV3270 intrinsic. The transmit/receive value controls both the
TRAN3270 and RECV3270 intrinsics. Each integer in the array specifies a
timeout value in seconds, from zero through 28800 (0 seconds to 8 hours).
Any numbers greater than 28800 and any negative numbers are treated as
28800. A value of zero in a word disables the timer.
The values used in timeout usually are treated as unsigned logical 16-bit
positive integers. For COBOL and BASIC, the values are treated as signed
integers.
If you specify a value for the transmit/receive timeout, SNA IMF sets two
timers: a receive timer and a transmit timer. The receive timeout is
the maximum time interval that a RECV3270 request may remain outstanding.
By specifying a maximum time interval, you can prevent an SNA IMF
application from suspending indefinitely (hanging) when the host does not
send any data to your device. The transmit timeout is the maximum time
interval that a TRAN3270 intrinsic request may remain outstanding. By
specifying a maximum time interval, you can prevent an SNA IMF
application from hanging when the host system does not allow your device
to send data, or when the host goes down before you can send your data to
the host.
If new data is not waiting for you (that is, the host has not yet
modified your screen), the receive timer is started as soon as the
RECV3270 intrinsic starts executing. The timer is turned off when SNA
IMF receives data for your device. Likewise, the transmit timer is
started when the TRAN3270 intrinsic begins execution. The transmit timer
is turned off when SNA IMF successfully completes sending data to the
host. If either timer expires, your I/O request (your call to TRAN3270
or RECV3270) is cancelled, and result code 24 is returned.
The keyboard enable timer simplifies writing SNA IMF applications when
the keyboard enable sent by the host is always in the last block of data.
The keyboard enable timer signals SNA IMF to wait for the keyboard enable
before completing your RECV3270 intrinsic call. This timer is especially
useful if the host sends a variable number of blocks to update your
screen. A single RECV3270 intrinsic call lets the keyboard enable signal
when the screen update is complete. If your device is expecting a
variable number of blocks, issue a RECV3270 intrinsic call and then check
the screen contents to see if the host has finished sending data. If it
has not, then you must issue another RECV3270 intrinsic call and check
the screen again.
You may use the keyboard enable timer either alone or with the receive
timer to control the RECV3270 intrinsic. When you use the keyboard
enable timer alone, the timer starts when the first block is received and
restarts after each block without a keyboard enable. When you use the
keyboard enable timer with the receive timer, the receive timer starts
when the RECV3270 intrinsic begins executing. The receive timer is
turned off when your device receives the first block of data. The
keyboard timer, on the other hand, starts operating and continues to
operate until your device receives a block of data that includes the
keyboard enable, or until the timeout expires. If the keyboard enable
timer expires, your RECV3270 I/O request is cancelled and result code 23
is returned in the result parameter of the RECV3270 intrinsic.
result (output)
The following values can be generated by the OPEN3270 intrinsic:
0 = Successful completion.
2 = Invalid devicenum parameter specified.
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.
27 = Could not open device. Insufficient virtual
memory was available.
28 = Could not open device. Insufficient real memory was
available.
30 = Internal error occurred in IMF intrinsic.
43 = Transparent mode not requested for LU.T1 emulation.
251 = Could not open NMCONFIG.PUB.SYS. ( MPE XL only)
252 = Could not read from NMCONFIG.PUB.SYS. ( MPE XL only)
253 = Could not close NMCONFIG.PUB.SYS. ( MPE XL only)
254 = Invalid SNAnode name. ( MPE XL only)
255 = Invalid security class name. ( MPE XL only)
256 = Security class not properly configured. ( MPE XL only)
257 = Program not authorized to use this security class.
( MPE XL only)
258 = User is not authorized to use this security class.
( MPE XL only)
301 = Illegal DB register.
304 = Security violation. ( MPE V only)
305 = Parameter bounds violation.
308 = Session is inactive.
309 = No available AFT entry. 315 = Internal Error.
317 = NAU is inactive.
321 = Invalid class name. ( MPE V only)
322 = Invalid session type.
324 = Invalid configuration access. ( MPE V only)
326 = No available NAU.
329 = Inactive node or invalid node name.
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
Calling the OPEN3270 intrinsic is equivalent to turning on an IBM display
station or printer.
The terminalid number, returned by the intrinsic, must be used to
reference the device in subsequent SNA IMF intrinsics.
When you call the OPEN3270 intrinsic in non-transparent mode, an internal
screen image is created that contains a description of all the fields on
terminal screen. In non-transparent mode, the internal screen imagecan
be accessed only through the following intrinsics:
ATTRLIST
SCREENATTR
FIELDATTR
READFIELD
READSCREEN
STREAM3270
WRITEFIELD
In transparent mode, the internal screen image contains the untranslated
data stream, so you cannot use any of the intrinsics that access specific
fields or field attributes. In transparent mode, the internal screen
imagecan be accessed only through the following intrinsics:
READSTREAM
WRITESTREAM
NOTE The WRITESTREAM intrinsicis used only for LU.T2 sessions. LU.T1
sessions use the TRAN3270 intrinsic to transmit printer keys and do
not use the WRITESTREAM intrinsic. LU.T3 emulated devices cannot
send data to the host.
After you call OPEN3270, your internal screen image initially contains
the SNA IMF unowned screen. This screen is equivalent to the IBM unowned
screen. When an IBM 3278 display station displays the unowned screen, a
question mark (?) appears on the screen in the operator information
area. An unowned screen image on an HP terminal contains the SNA IMF
bannerand is made up of one protected field.
Immediately after issuing the OPEN3270 intrinsic, your program should
call the RECV3270 intrinsic to obtain this initial screen with the banner
message. If the host sends data to the device before you call RECV3270,
the internal screen image sent by the host replaces the unowned screen
and is the first screen you see.
You can customize the unowned screen with your own message. To customize
this screen, use an editor to modify the unowned screen portion of the
CATIMF.PUB.SYS file(message set 11) on your HP 3000. After you have
designed your customized screen, run the HP 3000 MAKECATor GENCAT
utilityto incorporate your changes into the catalog. The MAKECAT utility
is only on MPE V and on MPE XL releases prior to 2.1; the GENCAT utility
is only on MPE XL release 2.1 and later releases.
Each time you call the OPEN3270 intrinsic after you run MAKECAT or
GENCAT, your HP terminal will display your customized screen. However,
if data is received immediately from the host, that data will replace the
unowned screen, perhaps before you even see it.
After you receive the first unowned screen, call TRAN3270 to send the SYS
REQ key to acquire the SSCP-LU screen. See appendix D for more
information on display screen ownership.
The OPEN3270 intrinsic can be called in transparent or non-transparent
mode.
Although similar to the IMF/3000 OPEN3270 intrinsic, the SNA IMF OPEN3270
intrinsic has a different interface. For example, the SNA IMF snalnkinfo
parameter replaces the IMF/3000 confile parameter and the SNA IMF
devicenum parameter replaces the IMF/3000 deviceid parameter. See
appendix D for details.
When using the SNA Server/Access product, the netinfo parameter replaces
the SNA IMF snalnkinfo parameter. See the HP SNA Server/Access User's
Guide for more specific information.
COBOL Calling Sequence
CALL "COPEN3270" USING DEVICENUM SNALNKINFO FLAGS TERMINALID DEVICETYPE
FFINDEX SCREENSIZE TIMEOUT RESULT. (on MPE V and in compatibility mode on
MPE XL)
CALL INTRINSIC "OPEN3270" USING DEVICENUM SNALNKINFO FLAGS TERMINALID
DEVICETYPE FFINDEX SCREENSIZE TIMEOUT RESULT. (in native mode on MPE XL)
All parameters are numeric data items except SNALNKINFO and TIMEOUT.
SNALNKINFO is an alphanumeric data item. TIMEOUT is a two-element
numeric table.
FORTRAN Calling Sequence
CALL OPEN3270 (DEVICENUM, SNALNKINFO, FLAGS, TERMINALID, DEVTYPE,
FFINDEX, SCREENSIZE, TIMEOUT, RESULT)
All parameters are integer variables except SNALNKINFO and TIMEOUT.
SNALNKINFO is a character array. TIMEOUT is an integer array of two
elements.
BASIC Calling Sequence
CALL BOPEN3270 (D1, C$, F, T, D2, F1, B, T2(*), R) (on MPE V and in
compatibility mode on MPE XL)
CALL OPEN3270 (D1, C$, F, T, D2, F1, B, T2(*), R) (in native mode on MPE
XL)
All parameters are integer variables except C$ and T2(*). C$ is a string
variable. T2(*) is a numeric array of two integers.
SPL Calling Sequence
OPEN3270 (DEVICENUM, SNALNKINFO, FLAGS, TERMINALID, DEVTYPE, FFINDEX,
SCREENSIZE, TIMEOUT, RESULT)
All parameters are integers except SNALNKINFO and TIMEOUT. SNALNKINFO is
a byte array. TIMEOUT is an integer array of two elements.
Pascal Calling Sequence
OPEN3270 (DEVICENUM, SNALNKINFO, FLAGS, TERMINALID, DEVTYPE, FFINDEX,
SCREENSIZE, TIMEOUT, RESULT);
All parameters are short integer variables except SNALNKINFO and TIMEOUT.
SNALNKINFO is a packed array of char. TIMEOUT is an array of two short
integer variables.
C/XL Calling Sequence
OPEN3270 (&DEVICENUM, SNALNKINFO, &FLAGS, &TERMINALID, &DEVTYPE,
&FFINDEX, &SCREENSIZE, TIMEOUT, &RESULT);
All parameters are of type short except SNALINKINFO and TIMEOUT.
SNALINKINFO is a character array (a pointer to a char), and TIMEOUT is a
short integer array (a pointer to a 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) }
flags_type = packed record { flags may be global or local. }
filler : 0..1023; { It's global in this example. }
dbcs : 0..1; { Two bytes (half word). }
unbind_op : 0..1;
LU1_3sup : 0..1;
int_trace : 0..1;
trans_mode : 0..1;
IO_mode : 0..1;
end;
.
.
.
var
terminalid : shortint;
result : shortint;
.
.
.
procedure OPEN3270; intrinsic;
.
.
.
{************************** Local Declarations **************************}
var
snalnkinfo : packed array[1..18] of char; { All OPEN3270 variables }
devicenum : shortint; { except terminalid and }
flags : flags_type; { result are local. }
devtype : shortint;
ffindex : shortint;
screensize : shortint;
timeout : packed array[1..2] of shortint;
.
.
.
{************** Variable Initialization and Intrinsic Call **************}
snalnkinfo := 'SNANODE#SNACLASS ';
devicenum := -2;
with flags do
begin
IO_mode := 0;
trans_mode := 1;
int_trace := 0;
LU1_3sup := 0;
unbind_op := 1;
dbcs := 0;
filler := 0;
end;
ffindex := 0;
timeout[1] := 30;
timeout[2] := 30;
OPEN3270 (devicenum, snalnkinfo, flags, terminalid, devtype, ffindex,
screensize, timeout, result);