Introduction to Emulator APIs

The IBM® Personal Communications product supplies several application programming interfaces (APIs). Each interface has a specific set of functions and may be used for different purposes. Choose the programming interface that best matches the functional requirements of your application. Some applications may use more than one interface to achieve the desired results. The programming interfaces are:

Emulator High Level Language API (EHLLAPI): This interface provides functions to access emulator "presentation space" data such as characters on the host screen. It also provides functions for sending keystrokes to the host, intercepting user-entered keystrokes, querying the status of the host session, uploading and downloading files, and other functions. This interface is often used for automated operator applications which read host screens and enter keystrokes without direct user intervention. See EHLLAPI Functions.
- IBM Standard HLLAPI Support: This is a standard programming interface which allows programmatic access to a host emulator session. See Introduction to IBM Standard EHLLAPI, IBM Enhanced EHLLAPI and WinHLLAPI Programming.
- IBM Enhanced HLLAPI Support: This interface is based on the IBM Standard HLLAPI interface. It provides all of the existing functionality but uses modified data structures. See Introduction to IBM Standard EHLLAPI, IBM Enhanced EHLLAPI and WinHLLAPI Programming.
- Windows High Level Language API (WinHLLAPI): This interface provides much of the same functionality of IBM Standard EHLLAPI and adds some extensions that take advantage of the Windows environment. See Introduction to IBM Standard EHLLAPI, IBM Enhanced EHLLAPI and WinHLLAPI Programming.
Dynamic Data Exchange (DDE): This interface is similar to the EHLLAPI interface in that it provides a programmable means to read the host screen, send keystrokes, and perform related functions. It has some additional functions for access to the emulator clipping rectangle, intercepting mouse events, and adding/removing commands on the emulator menu bar. See DDE Functions in a 32-bit Environment.
Personal Communications Session API (PCSAPI): This interface is used to start, stop, and control emulator sessions and settings. See PCSAPI Functions.
For Personal Communications Version 13.0, functions have been added to allow control and retrieval of page and printer settings. See Page Setup Functions and Printer Setup Functions.
Server-Requestor Programming Interface (SRPI): This interface is used in cooperation with an IBM Enhanced Connectivity Facility (ECF) application running on a host system. This API provides functions for writing synchronous call-return interfaces to remote server programs. See Server-Requester Programming Interface (SRPI) Support.
IBM Personal Communications Host Access Class Library (ECL): ECL is a set of objects that allow application programmers and scripting language writers to access host applications easily and quickly. Personal Communications supports three different ECL layers (C++ objects, ActiveAutomation (OLE), and LotusScript Extension (LSX)). Refer to Host Access Class Library (HACL) for more details.

Using API Header Files

The application program should include operating system header files before including API header files. For example:

  #include <windows.h>      // Windows main header
  #include "pcsapi.h"       // PComm PCSAPI header
  ...

Critical Sections

Use critical sections (EnterCriticalSection function) carefully when your program calls emulator APIs. Do not make emulator API calls within a critical section. If one thread of an application establishes a critical section and another thread is within an emulator API call, the call is suspended until you exit from the critical section.

During processing of an API call, all signals (except numeric coprocessor signals) are delayed until the call completes or until the call needs to wait for incoming data. Also, TerminateProcess issued from another process is held until the application completes an API call it might be processing.

Stack Size

Emulator APIs use the calling program's stack when they are executed. The operating system, the application, and the API all require stack space for dynamic variables and function parameters. At least 8196 bytes (8K) of stack space should be available at the time of an API call. It is the responsibility of the application program to ensure sufficient stack space is available for the API.

Running 16-bit Windows EHLLAPI programs

If you are running multiple 16-bit Windows EHLLAPI tasks that use any of the 16-bit EHLLAPI DLLs, each 16-bit EHLLAPI task must run under a separate NTVDM. You can use any of the following methods to accomplish this:

Shortcuts used to start 16-bit EHLLAPI applications must specify that the program run in a separate memory space (NTVDM).
To start a 16-bit EHLLAPI application such as hllapi16.exe from a command prompt or batch program, type the following command:
```
start /separate hllapi16.exe
```
If a Win32 application spawns a 16-bit EHLLAPI application using the Windows API CreateProcess, it must use the Process creation flag named CREATE_SEPARATE_WOW_VDM.

Windows x64 Platform Support

The x64-based versions of Microsoft Windows Server 2008 and Microsoft Windows 8/8.1/10 x64 Edition are optimized to run native 64-bit programs, but do not support 32-bit drivers or 16-bit applications.

For these platforms, Personal Communications does not install the following libraries.

DOS EHLLAPI
16-bit API support:
- Standard EHLLAPI 16-bit interface
- WinHLLAPI 16-bit interface
- PCSAPI 16-bit interface
- SRPI 16-bit interface

Sample Programs

Several sample programs are provided, each of which illustrates the use of one of the Personal Communications APIs. If you choose to install the sample programs, they will be installed in the \SAMPLES directory.

Note:

International Business Machines Corporation provides these files as is, without warranty of any kind, either express or implied, including, but not limited to, the implied warranties of merchantability or fitness for a particular purpose.

The sample program files include source and supporting files for the following Personal Communications APIs:

Emulator High-Level Language Programming Interface (EHLLAPI)
Dynamic Data Exchange (DDE)
Server-Requester Programming Interface (SRPI)
PCSAPI Functions

The following files are installed in the \SAMPLES directory.

Table 1. Sample Program Files
File Name	Description
DDE_C.H	DDE include file
EHLAPI32.H	IBM standard 32-bit EHLLAPI include file
WHLLAPI.H	WinHLLAPI 16-bit include file
HAPI_C.H	EHLLAPI include file
PCSAPI.H	PCSAPI include file
PCSCALLS.LIB	Import library for standard interface
PCSCAL32.LIB	Import library for enhanced interface
EHLAPI32.LIB	Import library for IBM Standard 32-bit EHLLAPI interface
WHLLAPI.LIB	Import library for WinHLLAPI 16-bit interface
WHLAPI32.LIB	Import library for WinHLLAPI 32-bit interface
UUCCPRB.H	SRPI include file

The following subdirectories are created in the \SAMPLES directory.

Table 2. Sample Program Subdirectories
File Name	Description
DDXFER	Shows how EHLLAPI can be used to create a "Drag and Drop" application; in this case, for file transfer
ECL	HACL sample files
HLLSMP	Shows how to use EHLLAPI to request a keystroke and log on to a VM system
LISTFILE	Illustrates how DDE can make use of the LOAD button to transfer files from the host
PCSMAIN	Illustrates the use of PCSAPI to start and stop sessions, query the session status, and query the profile for the session
SPL2FILE	A program that uses DDE to save an iSeries®, eServer™ i5, or System i5® spool file as an ASCII file on the PC
SRPSMP	Illustrates the use of the Server Requester Programming Interface (SRPI)
VBDDE	VBDDE sample files
VBHLLAPI	VBHLLAPI sample files
VBPCSAPI	VBPCSAPI sample files

Displaying Arabic data in the VBHLLAPI sample program

For proper display of Arabic data in the VBHLLAPI sample program, you should do the following:

Edit the VBHLLAPI sample program source code. For each form, change the default font property to a Windows True Type font that supports Arabic script (for example, Courier New).
Recompile the VBHLLAPI sample program.