HLLAPI Terminal Emulation

PASSPORT HLLAPI Interface

The HLLAPI (High Level Language Application Programming Interface) Interface was originally developed by IBM in the mid 1980's and first used with the MS DOS-based IBM PC 3270 Emulation Program. It has evolved over two decades to become the most widely used API to link thousands of desktop-based applications to IBM mainframe applications.

A library file (.LIB) is provided that may be linked into an application in order to use the HLLAPI interface. Only C++ applications need an explicit link to the .LIB file. HLLAPI is not an ActiveX COM object and isn't object oriented. HLLAPI provides a single function that has four parameters. The first parameter indicates which HLLAPI function to perform. PASSPORT uses either hllapi() or winhllapi () as the function name entry point.

The IBM HLLAPI DLL name is PCSHLL.DLL whereas PASSPORT uses the PASSHLL.DLL file name. When migrating an HLLAPI application to PASSPORT it's important to check:

1. The name of the HLLAPI DLL being loaded is correct (normally needs to be changed)
2. The HHLAPI application can find the HLLAPI DLL by adding the PASSPORT installation directory to the PATH environment variable
3. The HLLAPI function entry point is correct, either hllapi() or winhllapi () or something else (normally does not need to be changed).

The IBM HLLAPI DLL name is PCSHLL.DLL whereas PASSPORT uses the PASSHLL.DLL file name. When migrating an HLLAPI application to PASSPORT it's important to check that (1) the name of the HLLAPI DLL being loaded is correct (normally needs to be changed) and (2) the HLLAPI function entry point is correct, either hllapi() or winhllapi () or something else (normally does not need to be changed).

The HLLAPI short name, which ranges from the letter 'A' to the letter 'Z', is used to identify which host session is being used.

When to Use: The HLLAPI Interface is recommended when PASSPORT is being used to replace an existing terminal emulator and an existing PC HLLAPI application. Also, third party applications may require HLLAPI for host access.

What is HLLAPI?

HLLAPI (High Level Language Application Program Interface) is the industry standard method to interface Windows PC applications with host applications via terminal emulation. A typical HLLAPI application could present users with a graphical interface to a host application or be used to automate routine functions such as common file transfers.

PASSPORT supports 32-bit WinHLLAPI and is compatible with the HLLAPI support found in the IBM® Personal Communications/TN3270 terminal emulation software.

If you want to use a commercially distributed desktop application that interfaces with a TN3270 emulator via HLLAPI, configure the application as you would for use with the IBM® PC/3270 package and proceed as normal.

HLLAPI is automatically available in every terminal emulator session of PASSPORT. By default, each PASSPORT terminal emulator session that is opened, is assigned an alphabet character, ranging sequentially from A through Z. However, to manually change the HLLAPI information, select the HLLAPI tab from the Communication Setup dialog box. From here, select Manually Specify to specify a different short or long name.

WinHLLAPI defines a standard style API for the 32-bit versions of Windows. This encompasses both familiar IBM® HLLAPI style routines and a set of Windows-specific extensions.

• WinHLLAPI support is provided by the file Passhll.dll
• PASSPORT does not support DOS EHLLAPI applications running in a DOS window. If you have a DOS EHLLAPI application you will need to contact the supplier of the EHLLAPI program and obtain their 16-bit or 32-bit Windows based version of the product.

Accessing Host Applications

HLLAPI applications can be accessed using one of two different levels of API calls:

• Basic Function Calls (Consist of 4 parameters)

1. Function number
2. Data Strings
3. Flags, etc. . .
4. Values/Return Codes

• Simplified HLLAPI Interface (See HLLAPI.H)

1. Easier to use than Basic HLLAPI calls
2. HLLAPI.H file contains listing of the simplified HLLAPI calls

Supported HLLAPI Functions

The following functions are supported in PASSPORT:

• (1) Connect Presentation Space
• (2) Disconnect Presentation Space
• (3) Send Key
• (4) Wait
• (5) Copy Presentation Space
• (6) Search Presentation Space
• (7) Query Cursor Location
• (8) Copy Presentation Space To String
• (9) Set Session Parameters
• (10) Query Sessions
• (11) Reserve
• (12) Release
• (13) Copy OIA
• (14) Query Field Attribute
• (15) Copy String To Presentation Space
• (18) Pause
• (20) Query System
• (21) Reset System
• (22) Query Session Status
• (23) Start Host Notification
• (24) Query Host Update
• (25) Stop Host Notification
• (30) Search Field
• (31) Find Field Position
• (32) Find Field Length
• (33) Copy String To Field
• (34) Copy Field To String
• (40) Set Cursor
• (50) Start Keystroke Intercept
• (51) Get Key
• (52) Post Intercept Status
• (53) Stop Keystroke Intercept
• (90) Send File
• (91) Receive File
• (99) Convert Position Row/Col
• (101) Connect Window Services
• (102) Disconnect Window Services
• (104) Windows Status

• (4112) Run Profile
• (4113) Run Profile and Connect
• (4114) Close and Disconnect

• WinHLLAPICleanup( )
• WinHLLAPIStartup ( )

HLLAPI Extensions for Rumba Applications

The following three functions have been added as extensions to Zephyr's HLLAPI implementation. These functions provide compatibility with Wall Data's"RUMBA® Tools for PowerBuilder®":

Run Profile: This function launches the specified PASSPORT PC TO HOST® session profile from your WinHLLAPI application.

Run Connect: This function launches the specified PASSPORT PC TO HOST® session profile and connects to the specified presentation space from your WinHLLAPI application.

Close Disconnect: This function disconnects the specified host session and closes the application from your WinHLLAPI session.

Simplified Function Calls

• hllapi_ConnectPS (LPSTR strSessID)
• hllapi_DisconnectPS ()
• hllapi_SendKey (LPSTR strKeyString)
• hllapi_Wait ()
• hllapi_CopyPS (LPSTR pstrPS)
• hllapi_SearchPS (LPSTR strString, int& iPos, int& iFoundPos)
• hllapi_QueryCursorLocation (int& nCurLoc)
• hllapi_CopyPSToString (LPSTR strPS, int& iLen, int& iPos)
• hllapi_SetSessionParameters (LPSTR strParameters, int& iParams)
• hllapi_QuerySessions (LPSTR strSessions, int& iSessions)
• hllapi_Reserve () hllapi_Release ()
• hllapi_CopyOIA (LPSTR strOIA)
• hllapi_QueryFieldAttribute (int& iPos, int& iAttrib)
• hllapi_CopyStringToPS (LPSTR strString, int& iPos)
• hllapi_Pause (int& iHalfSeconds)
• hllapi_QuerySystem (LPSTR strSystem)
• hllapi_ResetSystem ()
• hllapi_QuerySessionStatus (LPSTR strSessID, LPSTR strStatus)
• hllapi_StartHostNotification (LPSTR strNotify)
• hllapi_QueryHostUpdate (LPSTR strSessID)
• hllapi_StopHostNotification (LPSTR strSessID)
• hllapi_SearchField (LPSTR strString, int& iPos, int& iFoundPos)
• hllapi_FindFieldPosition (LPSTR strString, int& iPos, int& iFieldPos)
• hllapi_FindFieldLength (LPSTR strString, int& iPos, int& iFieldLen)
• hllapi_CopyStringToField (LPSTR strString, int& iPos)
• hllapi_CopyFieldToString (LPSTR strString, int& iLen, int& iPos)
• hllapi_SetCursor (int& nCurLoc)
• hllapi_SendFile (LPSTR strCmd)
• hllapi_ReceiveFile (LPSTR strCmd)
• hllapi_ConvertPositionToRowCol (LPSTR strSessID, int& iPos, int& iRow, int& iColumn)
• hllapi_ConvertRowColToPosition (LPSTR strSessID, int& iRow, int& iColumn, int& iPos)