Introduction to Emulator APIs

The IBM® Z and I Emulator for Windows 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:

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"       // ZIEWin 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.

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, Z and I Emulator for Windows does not install the following libraries.

Sample Programs

Several sample programs are provided, each of which illustrates the use of one of the Z and I Emulator for Windows 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 Z and I Emulator for Windows APIs:

The following files are installed in the \SAMPLES directory.

Table 1. Sample Program Files
File Name Description
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

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
PCSMAIN Illustrates the use of PCSAPI to start and stop sessions, query the session status, and query the profile for the session
VBHLLAPI VBHLLAPI sample files
VBPCSAPI VBPCSAPI sample files