ACQUIRE3270

ACQUIRE3270 on a terminal or printer that is not under MPE control.

Syntax (for SNA IMF/V)

                   CA          I        I      I         I

ACQUIRE3270   (snalnkinfo, devicenum, ldev, enhance, priority,

                 I       I       I      I

               blanks, format, flags, result

Syntax (for SNA IMF/XL)

                   CA          I        I      I         I

ACQUIRE3270   (snalnkinfo, devicenum, ldev, enhance, priority,

                 I       I       I      I      CA     I

               blanks, format, flags, options, pfn, result

Parameters

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:# / [ ] . , :
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.
ldev (input): Integer specifying the MPE logical device number of an HP 3000 terminal or printer to be used to run Pass Thru.
enhance (input): Integer specifying the terminal screen display enhancements to be used. Table 3-1 “Display Enhancement Options”lists the values of the enhance parameter and their effects.

Table 3-1 Display Enhancement Options

Value	3278 normal intensity converted to	3278 high intensity converted to
0	264x half-bright or 23xx/262x normal (full-bright)	23xx/262x/264x normal (full-bright)
1	23xx/262x/264x normal (full-bright)	23xx/262x/264x underline
2	23xx/262x/264x normal (full-bright)	23xx/262x/264x inverse video
3	23xx/262x/264x inverse video	23xx/262x/264x normal (full-bright)

If you are using an HP 264x terminal, you must have the Display Enhancements option installed, because half-bright and underline are not standard features. Without the Display Enhancements option, if you specify 0 in the enhance parameter, all characters appear at normal intensity. Half-bright is not available on the 23xx or 262x terminals.

You cannot turn off inverse video for part of a field on an HP terminal. Therefore, if you choose inverse video, the white strip of the inverse video occupies the entire field, regardless of where the end of your data falls in the field.

priority (input)

Integer specifying the output priority for Pass Thru. priority must be from 1 through 13. This parameter will be used by Pass Thru to determine the priority of the LOGIMF file, which contains the output of the PRINT softkey used to print the internal screen image. The default value is 7.

For more information about priority, see the description of the FOPEN intrinsic in the MPE V Intrinsic Reference Manual. This priority parameter is passed to an FOPEN intrinsic call as the output priority value in the numbuffers parameter. You may override priority by specifying a file equa3ion before starting your program. The name of the output file is LOGIMF.

blanks (input)

Integer that determines whether leading blank input characters in an unprotected field are converted to nulls before being transmitted to the host. For more information, see Using SNA IMF Pass Thru manual.

0: Pass Thru converts leading blank input characters in an unprotected field to null characters. This option performs the same function as specifying LB = NO in the PTCONFIG file for Pass Thru sessions.
1: If leading blanks exist in fields read from the HP terminal screen, Pass Thru transmits the leading blanks to the host. This option performs the same function as specifying LB = YES in the PTCONFIG file for Pass Thru sessions.

format (input)

Integer that tells Pass Thru which form of screen printing to use and when to print the internal screen (not used for LU.T1 emulation):

1: Print the internal screen image and the location and characteristic of each attribute character.
2: Print the internal screen image the way it appears on the terminal, with attribute and null characters appearing as blanks.
3: Automatically print the internal screen image and the location and characteristic of each attribute character whenever Pass Thru calls the TRAN3270 or RECV3270 intrinsic.
4: Print the internal screen image the same way it appears on the terminal with attribute and null characters appearing as blanks, whenever Pass Thru calls the TRAN3270 or RECV3270 intrinsic.

flags (input)

Integer indicating one of the following:

0: The Pass Thru session is started as a child process of your program, and your program continues to execute. With this option, your program can start Pass Thru sessions on multiple devices. Be careful: all Pass Thru sessions started by your program will be aborted if your program should terminate, either normally or abnormally.
1: The Pass Thru session is activated as the child process of your program, and your program is suspended until the Pass Thru session ends. Your program is reactivated when the Pass Thru session ends.
3: The Pass Thru session activated by your program becomes the child process of the Node Management Monitor (NMMON). Your program continues to execute after Pass Thru has started. With this option, your program can start Pass Thru sessions on multiple devices, and these Pass Thru sessions can remain active after your program has terminated.

options (input)

SNA IMF/XL only. A 16-bit word that indicates the trace, spooler priority, read timeout, and LaserJet II options. The bit groups are listed using the standard SPL notation: (15:1) indicates bit 15, and (10:3) indicates bits 10, 11, and 12.

Bit (15:1)

LaserJet II mode:

0 = LaserJet II option is off. Printer output files will go to the spooled printer.

1 = LaserJet II option is on. Printer output files will be redirected to an HP LaserJet Series II or Series III printer. The LaserJet II option can be used only in an LU.T1 or LU.T3 printer session.

Bits (6:9)

Read timeout value:

Terminal timeout value in seconds. The value must be an integer between 10 and 255. The default value for Pass Thru is 10 seconds. You may have to increase this value if your terminal's response time is longer than 10 seconds.

Bits (2:4)

Spooler priority:

This value must be an integer between 1 and 13.

Bit (1:1)

Trace mode:

0 = SNA IMF internal tracing is off.

1 = SNA IMF internal tracing is on. Tracing should be turned on only at the request of your HP representative, to collect data for problem determination. A trace file with the name IMFnnTxx, where nn is the NAU number and xx is a unique two-digit identifier, will be created during the Pass Thru session. Note that tracing degrades performance.

Bit (0:1): Reserved.

pfn (input)

SNA IMF/XL only. Optional character array specifying a name for the spooler file. A legal filename is an alphanumeric string of up to 8 characters. The first character must be alphabetic. If pfn is not specified, the default file name is a field of blanks.




	NOTE: If an illegal spooler file name is passed as the `pfn` parameter, no error will be generated. Illegal filenames will be treated as follows: A file name of more than 8 characters will be truncated after the eighth character. If the first character of an illegal file name is alphabetic, but the filename contains a non-alphanumeric character, the filename will be truncated at the illegal character. If the illegal file name begins with a non-alphabetic character, the default printer file name (a field of blanks) will be used.

result (output)

The following values can be generated by the ACQUIRE3270 intrinsic:

0 = Successful completion.

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.

69 = Unable to find snaclassname.

70 = Invalid LDEV specified or LDEV is already in use.

71 = The ENHANCE parameter must be an integer between 0 and 3.

72 = The PRIORITY parameter must be an integer between 1 and 13.

73 = The BLANKS parameter must be either 0 or 1.

74 = The FORMAT parameter must be an integer between 1 and 4.

75 = Invalid flags parameter.

76 = TTSSON.PUB.SYS is missing.

77 = An HP LAN nodename must begin with an alphabetic character.

78 = The SNA Server must be installed properly to use this feature.

79 = Fewer than three characters were specified for snanode#snaclassname.

83 = Unable to find HP LAN nodename.

84 = An HP LAN nodename must contain between one and eight alphanumeric characters.

85 = Unable to find end of user and account string(]).

86 = SNA nodename must begin with an alphabetic character.

87 = An SNA classname must begin with an alphabetic character.

88 = A user.account is required for 3287 printer emulation over a LAN.

89 = Fewer than three characters were specified for user.account.

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)

304 = Security violation. (MPE V only)

308 = Session is inactive.

315 = Internal Error.

321 = Invalid class name. (MPE V only)

324 = Invalid configuration access. (MPE V only)

326 = No available NAU.

329 = Inactive node or invalid node name.

Description

The ACQUIRE3270 intrinsic allows you to start Pass Thru programmatically on a terminal or printer attached to an HP 3000. The parameters of the ACQUIRE3270 intrinsic correspond to the info string parameters in the RUN command that starts Pass Thru. For more information, see Using SNA IMF Pass Thru.

In most cases, ACQUIRE3270 may start Pass Thru on any free terminal or printer not under MPE control. However, you can call ACQUIRE3270 to gain control over a device that is already in use if you specify a value of 1 in the flags parameter. You must exit Pass Thru before the device can again be used for normal MPE activity. An error occurs, and a result code of 70 is returned, if you specify a flags parameter value of 0 and attempt to start Pass Thru on a device that is in use.

If Pass Thru detects an error condition (for example, a line to the host system has not been established), an error message is displayed on both the HP 3000 terminal being acquired and the system console, and the error number is returned in the ACQUIRE3270 result parameter. You can call the ERR3270 intrinsic to get the message associated with the result code.




	NOTE: If you are using the HP SNA Server/Access products on a LAN, some of the `ACQUIRE3270` parameters are different from those described here. See the HP SNA Server/Access User's Guide for more specific information.

Although similar to the IMF/3000 ACQUIRE3270 intrinsic, the SNA IMF ACQUIRE3270 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 A “Intrinsic Result Codes” for details.

Call ACQUIRE3270 in non-transparent mode.

COBOL Calling Sequence

CALL "CACQUIRE3270" USING SNALNKINFO DEVICENUM LDEV ENHANCE PRIORITY BLANKS FORMAT FLAGS RESULT. (on MPE V)

CALL "CACQUIRE3270" USING SNALNKINFO DEVICENUM LDEV ENHANCE PRIORITY BLANKS FORMAT FLAGS OPTIONS PFN RESULT. (on MPE XL in compatibility mode)

CALL INTRINSIC "ACQUIRE3270" USING SNALNKINFO DEVICENUM LDEV ENHANCE PRIORITY BLANKS FORMAT FLAGS OPTIONS PFN RESULT. (on MPE XL in native mode)

All parameters are numeric data items except SNALNKINFO and PFN, which are alphanumeric data items.

FORTRAN Calling Sequence

CALL ACQUIRE3270 (SNALNKINFO, DEVICENUM, LDEV, ENHANCE, PRIORITY, BLANKS, FORMAT, FLAGS, RESULT) (on MPE V)

CALL ACQUIRE3270 (SNALNKINFO, DEVICENUM, LDEV, ENHANCE, PRIORITY, BLANKS, FORMAT, FLAGS, OPTIONS, PFN, RESULT) (on MPE XL)

All parameters are integer variables except SNALNKINFO and PFN, which are character variables.

BASIC Calling Sequence

CALL BACQUIRE3270 (C$, D1, L0, E1, P2, B1, F3, F, R) (on MPE V)

CALL BACQUIRE3270 (C$, D1, L0, E1, P2, B1, F3, F, O4, P$, R) (on MPE XL in compatibility mode)

CALL ACQUIRE3270 (C$, D1, L0, E1, P2, B1, F3, F, O4, P$, R) (on MPE XL in native mode)

All parameters are integer variables except C$and P$, which are string variables.

SPL Calling Sequence

ACQUIRE3270 (SNALNKINFO, DEVICENUM, LDEV, ENHANCE, PRIORITY, BLANKS, FORMAT, FLAGS, RESULT) (on MPE V)

ACQUIRE3270 (SNALNKINFO, DEVICENUM, LDEV, ENHANCE, PRIORITY, BLANKS, FORMAT, FLAGS, OPTIONS, PFN, RESULT) (on MPE XL)

All parameters are integer variables except SNALNKINFO and PFN, which are byte arrays.

Pascal Calling Sequence

ACQUIRE3270 (SNALNKINFO, DEVICENUM, LDEV, ENHANCE, PRIORITY, BLANKS, FORMAT, FLAGS, RESULT); (on MPE V)

ACQUIRE3270 (SNALNKINFO, DEVICENUM, LDEV, ENHANCE, PRIORITY, BLANKS, FORMAT, FLAGS, OPTIONS, PFN, RESULT); (on MPE XL)

All parameters are short integer variables except SNALNKINFO and PFN, which are packed arrays of char.

C/XL Calling Sequence

ACQUIRE3270 (SNALINKINFO, &DEVICENUM, &LDEV, &ENHANCE, &PRIORITY, &BLANKS, &FORMAT, &FLAGS, &OPTIONS, PFN, &RESULT);

All parameters are of type short, except SNALINKINFO and PFN, which are character arrays (pointers to characters).

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”

{*** NOTE: This example is for SNA IMF/XL only, because it uses the    ***}{*** 'options' and 'pfn' parameters, which SNA IMF/V does not support. ***}{************************** Global Declarations **************************}type   shortint = -32768..32767; { global type, two bytes (half word) }   options_type  = packed record        { options_type may be global }      filler     : 0..1;                { or local. It's global in this }      int_trace  : 0..1;                { example. Two bytes (half word) }      spriority  : 0..13;               { Note: readto is defined as a }      readto   : 10..256;               { value from 10 through 256, but }      LJ2        : 0..1;                { the highest bit is reserved and }   end;                                 { must be zero, so 255 is the }                                        { highest allowable value for readto. }...var   result        : shortint;...procedure ACQUIRE3270;  intrinsic;...

{************************** Local Declarations **************************}var   snalnkinfo  : packed array[1..18] of char;   { All ACQUIRE3270 variables }   devicenum   : shortint;                      { except result are }   ldev        : shortint;                      { declared as local. }   enhance     : shortint;   priority    : shortint;   blanks      : shortint;   format      : shortint;   flags       : shortint;   options     : options_type;   pfn         : packed array[1..9] of char;...{************** Variable Initialization and Intrinsic Call **************}snalnkinfo := 'SNANODE#SNACLASS ';devicenum := -3;ldev := 6;enhance := 0;priority := 6;blanks := 0;format := 3;flags := 2;with options dobegin   filler := 0;   int_trace := 0;   spriority := 8;   readto := 10;   LJ2 := 1;end;ACQUIRE3270 (snalnkinfo, devicenum, ldev, enhance, priority, blanks,             format, flags, options, pfn, result);