Host Access Solutions: Terminal Emulation Software and Host Integration

PASSPORT APIs Provide Desktop Based Host Application Integration

Host Application Integration Using Screen Information is Low Cost and Low Risk

With it's low cost and low risk approach to host application integration, client-based TN3270, TN5250, VT100, VT220, VT420, SCO ANSI or Wyse 60 terminal emulation for Microsoft Windows can be an ideal platform for lightweight and modest integration solutions requiring host access.

The Zephyr PASSPORT PC TO HOST® and PASSPORT WEB TO HOST® terminal emulation products offer 2 APIs to assist developers with options for client-based host integration. PASSPORT PC TO HOST® is Certified for Windows Vista® and PASSPORT WEB TO HOST® Works with Windows Vista.

Zephyr also offers the PASSPORT Object Toolkit to ease programmatic application integration efforts. The toolkit can be used in conjunction with the Zephyr PASSPORT terminal emulation and is available free of charge to customers who license at least 500 units of PASSPORT via an annual subscription license.

For more robust integration projects, Zephyr offers PASSPORT Host Integration Objects, an advanced, programmatic communications module and API that can be used for .NET host integration on either a Windows desktop or server.

Client Based Host Integration APIs

• Object Interface
• HLLAPI Interface

Using the host application screen display as an API, developers can quickly navigate through TN3270, TN5250, VT, SCO ANSI and Wyse 60 applications to locate specific screens, fields and text, as well as cut and paste data to and from the host session. The APIs listed above can be used with either PASSPORT PC TO HOST® or PASSPORT WEB TO HOST®.

Sample Client Based Integration Projects

• Microsoft Access macros can be written to update information in a host application using data from an Access database with PASSPORT terminal emulation for host access

• A PowerBuilder HLLAPI application originally written for the NetManage Rumba desktop based terminal emulator can be ported to the PASSPORT WEB TO HOST® web-based terminal emulation program

• Complex Attachmate EXTRA!® macros and applications written specifically for Attachmate EXTRA!® can be easily ported for use with PASSPORT terminal emulation

• A corporate desktop-based application that integrates multiple applications can embed and interface a complete terminal emulation program

Object Interface

The PASSPORT Object Interface is an ideal API for new, client-side integration projects that require access to IBM mainframe, AS/400 or UNIX host applications. The PASSPORT Object API can also used to support converted Attachmate EXTRA!® macros, as well as existing screen scraping applications designed for the Attachmate EXTRA!® Objects API.

The PASSPORT Object interface is an ActiveX COM object called PASSOBJ.DLL. There is an hierarchy of objects used for host access that includes Sessions, Session, Screen, OIA, Area, Toolbars, Toolbar, QuickPads and QuickPad (see diagram below).

The COM object can be used with any programming language that can use ActiveX COM objects, including C++, Visual Basic, VB Script and Java Script. The PASSPORT Object Toolkit provides a sample VB Script application and source code.

When migrating an existing Attachmate EXTRA!® application to PASSPORT, the only change necessary is to change the name of the object used in the CreateObject () method. An Attachmate EXTRA!® application uses CreateObject ("EXTRA.SYSTEM"). For PASSPORT you would use CreateObject ("PASSPORT.SYSTEM").

When to Use: The PASSPORT Object Interface is recommended for new, client-side integration projects that require access to IBM mainframe, AS/400 or UNIX host applications. It can also be used to support existing Attachmate OLE automation applications and to run converted Attachmate EXTRA! macros with the PASSPORT terminal emulation.

Object Hierarchy

PASSPORT System Object

This is the top-level object providing access to all PASSPORT objects.

Properties
ActiveSession	Returns the currently active Session object
Application	Returns the System object
DefaultFilePath	Sets or returns the default path specification as a string
FullName	Returns a string specifying the path and filename
Name	Returns the name of the object as a string
Parent	Returns the parent of the specified object
Path	Returns the path of the PASSPORT executable file
Sessions	Returns a collection of Session objects that are currently open
TimeoutValue	Sets or returns the number of milliseconds used by Wait operations
Version	Returns a string identifying the version of PASSPORT

 

Methods
Quit	Closes all PASSPORT sessions
ViewStatus	Starts the Status program

Sessions Object

This object is a collection object consisting of individual Session objects.

Properties
Application	Returns the System object
Count	Returns the number of items in the collection of objects
Parent	Returns the parent of the specified object

 

Methods
CloseAll	Closes all active sessions
Item	Returns an element in the collection
JumpNext	Returns the next open session and gives it the focus
Open	Opens and returns a session, adds it to the Sessions collection

Session Object

This object is a collection object consisting of individual Session objects.

Properties
Application	Returns the System object
Connected	Returns the connection status, also connects/disconnects a session
FullName	Returns a string specifying the path and filename
Height	Returns or sets the height of the session window in pixels
KeyboardLocked	Returns or sets the keyboard input state for the Left Returns or sets the horizontal position of the session in pixels
Name	Returns the name of the object as a string
Parent	Returns the parent of the specified object
Path	Returns the path of the session file
Saved	Returns the save status of the session
Screen	Returns the Screen object associated with the session
Top	Returns or sets the vertical position of the session in pixels
Type	Returns a value indicating the session type
Visible	Returns visibility status, or sets visibility on/off
Width	Returns or sets the width of the session window in pixels
WindowState	Returns or sets the state of the session window - normal, max, min

 

Methods
Activate	Makes the specified session the active window
Close	Closes the session
NavigateTo	Execute a PASSPORT macro
ReceiveFile	Receives a file from the host
Save	Saves the current settings of the session
SaveAs	Saves a copy of the specified session to a new file
SendFile	Sends a file from the PC to the host

Screen Object

This object provides access to the contents of the host screen presentation space.

Properties
Application	Returns the System object
Col	Returns the System object
Cols	Returns the number of columns in the presentation space
Name	Returns the name of the object as a string
OIA	Returns an OIA object
Parent	Returns the parent of the specified object
Row	Returns or sets the row position of the cursor
Rows	Returns the number of rows in the presentation space
Selection	Returns an Area object representing the currently selected area
Updated	Returns is the Screen object has been updated

Area Object

This object provides access to a defined area of the screen.

Properties
Application	Returns the System object
Bottom	Returns or sets the ending row of the Area object
Left	Returns or sets the screen column where the area begins
Parent	Returns the parent of the specified object
Right	Returns or sets the column, specified as an integer, where the Area ends
Top	Returns or sets the row where the area begins
Type	Returns or sets type of Area coordinates - top, left, bottom, right
Value	Returns or sets the text in the Area

Methods
Copy	Copies the select text to the Clipboard
Cut	Removes selected text from the session and stores it in the Clipboard
Delete	Deletes the current selection
Paste	Pastes Clipboard text into the object
Select	Selects the object

OIA Object

This object provides host connection and status information that is contained in the Operator Information Area (OIA) of the host screen.

Methods
ConnectionStatus	Indicates the status of the host connection
ErrorStatus	Returns an integer indicating any error condition
Updated	Returns if the OIA object has been updated
Value	Returns the text in the OIA Area
Xstatus	Returns an integer indicating the status of the XClock

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 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.

What is HLLAPI?

HLLAPI (High Level Language Application Program Interface) is the industry standard method to interface Windows PC applications with host applications via TN3270, TN5250, VT100, VT220, VT420, SCO ANSI or Wyse 60 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 or 16-bit EHLLAPI application you will need to contact the supplier of the EHLLAPI program and obtain their 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

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 ( )

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)

Download a Copy

Download a fully functional trial copy of PASSPORT PC TO HOST® Terminal Emulation. The evaluation copy can be downloaded and running in minutes, and offers fully functional terminal emulation with a built-in expiration date. Once your evaluation is complete, you can convert the trial copy of the software into a production version with a simple license code.