Chapter 7 - Application Programming Interfaces

The Advanced 3270/SNA option has two programming interfaces:

	LLAPI (Low-level Language Application Programming Interface)
	HLLAPI (High-Level Language Application Programming Interface)

This chapter describes these programming interfaces and provides additional programming information.

LLAPI

Advanced 3270 LLAPI is compatible with IBM API Version 2.0. LLAPI.EXE is a memory-resident program that translates LLAPI program calls into the Banyan PI2 (Programming Interface 2) functions automatically and transparently. This allows you to run IBM LLAPI applications on Banyan software without modification. LLAPI programs can coexist with one or more PI2 applications. Only one LLAPI application can be run at a time, however.

Configuration

When a LLAPI application runs in a purely IBM software environment, display LU initialization is automatic. When a LLAPI application runs in a Banyan environment, E3270 looks in the specified configuration file for the first LU defined as a standard Type 2 display, and assigns it to LLAPI.

Make sure that the configuration file includes at least one LU configured as a standard 3270 display. (See Chapter 2 for a complete procedure for setting up a workstation as a display.)

Installing LLAPI

Before you run an LLAPI application with Advanced 3270/SNA, load the LLAPI program layer into memory between the RA3270 and E3270 layers. To do this, you must run three programs in this order:

RA3270
LLAPI
E3270 configfile

The easiest way to run these three programs is to create a batch file that loads the product software. The exact format of the batch file depends on the options you are using. Once you have run the batch file, you must press the Hotkey to return to DOS. Once you are at the DOS prompt, you are ready to run your LLAPI program.

LLAPI Application Startup

To start up a LLAPI application, follow these steps:

1. Load the Advanced 3270 software. If you are using a batch file, be sure that the LLAPI command is loaded between RA3270 and E3270 of your emulator software.

2. Once the emulator software is running, use the Hotkey to switch to DOS.

3. Run the LLAPI application by entering the name of the application at the DOS prompt.

Runtime Option

The LLAPI program supports the following runtime parameter:

LLAPI -NOMSG

The -NOMSG parameter suppresses all program load error messages directed to the display.

LLAPI Supported Calls

Table 7-1 lists all the calls supported by the Banyan LLAPI interface. Standard LLAPI uses Interrupt 7A.

Buffer Code-to-ASCII Translation Support

The LLAPI calls Write Keystroke and Copy String support the use of either ASCII characters or 3270 device buffer code. If a LLAPI application makes a call using 3270 device buffer code, the codes are translated into ASCII automatically. You can customize this translation by generating a translation table through the BLDTABLE program.

To generate the LLAPI Buffer Code-to-ASCII table, enter a command in the following format at the DOS prompt:

BLDTABLE inputfile outputfile

If you are loading a code page other than US ASCII code page 437, you must customize this table to account for the different character set you are using. To do this, run BLDTABLE to generate a file with a .SCN extension. This file must have the same filename as the ASCII-to-EBCDIC translation table you are loading. For example, if you are loading an ASCII-to-EBCDIC translation table called TABLE.TBL, then you must name the Buffer Code-to-ASCII translation table for LLAPI TABLE.SCN.

Once the table name has been entered into ACONFIG, you can make your LLAPI calls using 3270 device buffer code and they will be automatically translated.

LLAPI Error Messages

LLAPI does not become resident in memory if there is an error while the program is loading. In this event, LLAPI does not release any emulator layer from memory that is already loaded at that time. If a load error occurs, correct the problem and run the batch file again. Since the load sequence is order dependent, any emulator modules already in memory should not prevent the batch file from executing successfully.

You can build various degrees of error level checking into the batch file to control execution in the event of an error. (Refer to your DOS documentation for details on using error-level checking to control batch file execution.)

LLAPI returns the completion codes and messages shown in Table 7-2. You can use these values for error level checking.

HLLAPI

HLLAPI is compatible with IBM EEHLLAPI (Entry Emulator High Level Language Application Programming Interface) version 1.2, which is a subset of IBM HLLAPI 3.0.

The HLLAPI module is a memory-resident program that translates HLLAPI program calls into the Banyan PI2 (Programming Interface - 2) function calls automatically and transparently. This allows you to run many HLLAPI applications on Banyan software without modification.

EEHLLAPI functions supported by the Banyan HLLAPI appear in Table 7-3. For information about these functions, please refer to the Programming Guide, IBM PC 3270 Emulation Program, Entry Level Version 1.2, IBM Part # 84x0609.

Configuration

When a HLLAPI application runs in a purely IBM software environment, display LU initialization is automatic. When a HLLAPI application runs in a Banyan environment, E3270 looks in the Banyan configuration file for the first two LUs defined as display Type 2, and assigns them to HLLAPI.

Make sure that the configuration file includes the necessary LU definitions for the HLLAPI application, and any other logical units that you require for the Advanced 3270 emulator.

Installing HLLAPI

Before you run an HLLAPI application with Advanced 3270, load the HLLAPI program layer into memory between the E3270 and RA3270 layers. The easiest way to do this is to edit the batch file that loads the product software.

When you have edited the batch file properly, the contents should look like this:

RA3270
HLLAPI
E3270 %1

The exact format of the batch file depends on the options you are using.

The important thing is to edit the file so that HLLAPI loads between RA3270 and E3270.

HLLAPI Application Startup

To start a HLLAPI application, follow these steps:

1. Load the Advanced 3270 software. If you are using a batch file, be sure that the HLLAPI command is loaded in the proper sequence.

2. Once the emulator software is running, use the Hotkey to switch to DOS.

3. Run the HLLAPI application by entering its name at the DOS prompt. If you choose to assign Session Short Names, follow the instructions in the following section.

Note: Banyan does not support HLLAPI multitasking either through the /R command line switch or through the <ALT-R> keyboard key sequence.

Session Short Names

HLLAPI uses session short names to tell the HLLAPI application which sessions are available for it to use.

In Advanced 3270/SNA, default session short names are as follows:

You can override the session short names of the first two display sessions from the HLLAPI command line. Short names can be any single upper-case or lower-case character, and are specified as runtime parameters in the batch file. For example:

HLLAPI /1:letter /2:letter

/1 is the first session, and /2 is the second. If you need only one session for HLLAPI, enter the following parameter in the batch file:

HLLAPI /1:letter

where letter is a letter from A to Z.

A typical batch file that specifies short names might look something like this:

RA3270
HLLAPI /1:Z /2:Y
E3270 %1

In this example, the first two sessions configured on the workstation are named Z and Y respectively. If you do not define short names in the batch file, HLLAPI chooses /1:E by default, with no second session specified.

HLLAPI Error Messages

HLLAPI does not become resident in memory if there is an error while the program is loading. In this event, HLLAPI does not release any emulator layer from memory that is already loaded. If a load error occurs, correct the problem and run the batch file again. Since the load sequence is order dependent, any emulator modules already in memory should not prevent the batch file from executing successfully.

HLLAPI returns the following error messages:

RA3270 not resident. No action taken.

You must load RA3270 before loading HLLAPI.EXE.

HLLAPI already running. No action taken.

You tried to run the HLLAPI module when it was already present in memory.

Error in specifying session short names. Program terminated.

Check your command line syntax. The proper syntax for specifying session short names is given in this chapter in the section entitled "Session Short Names".

Must use PC-DOS version 3.XX or higher.

HLLAPI.EXE requires DOS versions 3.00 or higher. If you get this error message, you must upgrade your version of DOS before you can run your HLLAPI application.

INDHL001 HLLAPI is loaded. INDHLL002 HLLAPI is ready.

This message occurs when HLLAPI loads successfully.

HLLAPI Supported Calls

Table 7-3 lists all the calls supported by the Banyan HLLAPI interface. Standard HLLAPI uses Interrupt 7F.

Programming Considerations

The following notes are to be kept in mind when you are writing HLLAPI applications for Advanced 3270/SNA.

HLLAPI LIM Support

Many high level programming languages require a Language Interface Module (LIM) in order to make HLLAPI calls. The IBM PC 3270 Emulation Program Entry Level Programmer's Guide, Version 1.21 has an appendix that explains what functions the LIM performs. The appendix also gives example LIMs for a number of different languages.

There is a LIM distributed on the Advanced 3270/SNA distribution diskettes called HLLC.ASM. This LIM is compatible with Microsoft C, Version 5.1, for small, medium and large memory models.

Developers who are writing applications in 8086 assembler or interpreted basic do not require a LIM.

Storage Manager Calls (Function 17)

If you are writing your HLLAPI application in BASIC, implement the Storage Manager calls exactly as described in the IBM PC 3270 Emulation Program Entry Level Programmer's Guide, Version 1.21.

Customizing HLLAPI SendKey

The HLLAPI SendKey function (function 3) sends a keystroke or string of keystrokes to the host presentation space. These ASCII characters undergo an ASCII-to-ASCII translation inside HLLAPI before the characters are displayed in presentation space. The ASCII codes are then translated into EBCDIC, then translated back to ASCII. (This is to account for three characters that appear on the 3270 keyboard, but not on the PC keyboard. See Table 4-7 for a list of these characters.)

EEHLLAPI dynamically detects the code page that is loaded (either 437 or 850) and makes character translations accordingly. HLLAPI.EXE does not dynamically detect differences in code pages. However, you can run the GENX program to customize the ASCII-to-ASCII table for the code page you are running.

The ASCII-to-ASCII table inside HLLAPI.EXE as shipped is configured to support US ASCII, code page 437.

A Long Example

The following translations are made by both EEHLLAPI and the Banyan HLLAPI.EXE when US ASCII, Code Page 437 is loaded on the PC.

Figure 7-1. EEHLLAPI Translations for Code Page 437

Character requested by Send Key (EBCDIC) 6C EBCDIC to ASCII translation DD ASCII to ASCII translation 7C Description of Character Split Bar

Character requested by Send Key (EBCDIC) 4F EBCDIC to ASCII translation 7C ASCII to ASCII translation B3 Description of Character Long Vertical Bar

Note that with Code Page 437 loaded, the closest character in the code set to the short vertical bar (EBCDIC 4F) is the long vertical bar (ASCII B3). The short verticle bar character is not supported in Code Page 437.

Now suppose that you are running a PC in Great Britain that is configured to use US ASCII, Code Page 850. EEHLLAPI detects the existence of Code Page 850, and make the following translations.

Figure 7-2. EEHLLAPI Translations for Code Page 850

To effect these translations with the Advanced 3270/SNA HLLAPI module, you must follow these steps:

1. Run GENX.

2. At the Program to be Customized prompt, enter HLLAPI.EXE.

3. At the Symbol Table Name prompt, enter HLLAPI.MAP.

4. At the Customization Menu Name prompt, enter HLLAPI.LAN.

5. At the New Program Name prompt, enter HLLAPI.EXE.

6. Press <ENTER> after specifying the New Program Name. The screen in Figure 7-3 appears:

Figure 7-3. HLLAPI SendKey Customization Menu

7. Enter either 1 or 2 to select the Code Set that is loaded on your PC. The message "Language (1 or 2) Selected" appears on the screen.

8. Enter 98 to modify the HLLAPI.EXE ASCII-to-ASCII table with your chosen table.

9. Press 99 to exit to DOS.

Unsupported Keyboard Mnemonics

The following keyboard mnemonics are not supported by the Banyan HLLAPI interface.

@A@C - Test @A@f - Change Format A
@D - Word Delete @A@m - Cursor Position A
@I - Alt + Insert A
@d - Doc Mode A
@e - Wrap

Unloading APIs from Memory

When you have finished running your application, exit from the program.

When you have exited from the program, follow these steps to terminate the emulator and remove all related program modules from memory, including HLLAPI and LLAPI.

1. Press the Hotkey to switch back to the emulator.

2. Log off from any host sessions that are still active.

3. Press <F10>, then press <F9>.