For an introduction to API’s and emulator programming in HCL ZIEWin, refer to the link below:

https://blog.hcltechsw.com/hclsoftware/automation-using-pcsapi/

 In this blog, we will explore more about EHLLAPI APIs.

ZIEWin provides functions to access emulator “presentation space” data (such as characters on the host screen), sending keystrokes to the host, intercepting user-entered keystrokes, querying the status of the host session and uploading and downloading files, etc. The different EHLLAPI programming interfaces are listed below:

  • IBM Standard HLLAPI Support (HLLAPI): This is a standard programming interface that allows programmatic access to a host emulator session.
  • IBM Enhanced HLLAPI Support (EHLLAPI): This interface is based on the IBM Standard HLLAPI interface. It provides all the existing functionality but uses modified data structures.
  • 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.

The figure below illustrates different EHLLAPI layers:

Figure 1: EHLLAPI Layers

Languages
Any programming language which can invoke an entry point in a DLL with the “Pascal” calling convention can be used to execute EHLLAPI functions. The EHLLAPI toolkit supports the following compilers:
•       C/C++
•       Visual Basic for Automation
•       Visual Basic Scripting


EHLLAPI C/C++ applications must include the EHLLAPI header file (HAPI_C.H).

EHLLAPI CallFormat
The EHLLAPI entry point is always called with the following four parameters:
Function Name (EHLLAPI Function Number, Data Buffer, Buffer Length, Position/Return Code).

EHLLAPI Function Number Input
Data Buffer Input/output
Buffer Length Input/output
Position/Return Code Input/output

Compiling and linking
Applications using EHLLAPI functions must include the appropriate header file to obtain the proper function prototypes, constants, and data structure definitions. These header files may be used with any of the supported C/C++ compilers.

Note: If a different compiler or language is used, then you must provide your equivalent definitions and structures. There are two possible ways to link the application program, depending on how the entry point is to be resolved.

The following table shows which header files to use for different flavor of EHLLAPI.

Interface ​ Entry Point ​ Header File ​ DLL
IBM Standard (64-bit)  hllapi ​ ehlapi32.h  EHLAPI32.DLL
IBM Enhanced (64-bit) ​ hllapi  hapi_c32.h PCSHLL32.DLL
WinHLLAPI (64-bit) ​ winhllapi ​ whllapi.h ​ WHLAPI32.DLL

Function Calling convention
ZIEWin Session APIs follow a simple prototype for all functions to keep the programming straightforward. As mentioned above these APIs can be accessed and programmed using multiple programming languages (VBA, C/C++, C#, etc.).

Function Type Function Name (Arguments)

Where:

Function Type The return type of the API
Function Name The function to be called
Arguments Input argument to be passed to the function and can vary from 1 to 3

EHLLAPI Functions and their opcodes:

The below table shows different EHLLAPI functions and their Opcodes. Details about these functions, Operations, Data type, Length, and Return values can be found here

A Simple EHLLAPI ‘C’ Sample Program

The following sample windows application enters the character string “Hello World!” in the first input field of host session ‘A’.

A.      Includes

//Include standard library functions
#include <stdlib.h>
#include <stdio.h>
#include <windows.h>
//EHLLAPI header file
#include "hapi_c32.h"

B.      Main Function body and reset connection (if any)

int main(char **argv, int argc) 
{
    int HFunc, HLen, HRc;
    char HBuff[1];
    struct HLDConnectPS ConnBuff;
    // Send Key string for HOME+string+ENTER:
    char SendString[] = "@0Hello World!@E";
    //Reset the automation system
    HFunc = HA_RESET_SYSTEM;
    HLen = 0;
    HRc = 0;
    hllapi(&HFunc, HBuff, &HLen, &HRc); //standard EHLLAPI Calling format
    if (HRc != HARC_SUCCESS) 
    {
        printf("Unable to access EHLLAPI.\n");
        return 1;
    }

C.  Establish a connection between program and emulator (Step A must be
performed before any other steps)

HFunc = HA_CONNECT_PS;
    HLen = sizeof(ConnBuff);
    HRc = 0;
    memset(&ConnBuff, 0x00, sizeof(ConnBuff));
    ConnBuff.stps_shortname = 'A';
    hllapi(&HFunc, (char *)&ConnBuff, &HLen, &HRc);
    switch (HRc) {
        case HARC_SUCCESS:
        case HARC_BUSY:
        case HARC_LOCKED:
            //If here, we are good with connection
            break;
        case HARC_INVALID_PS:
            printf("Host session A does not exist.\n");
            return 1;
        case HARC_UNAVAILABLE:
            printf("Host session A is in use by another EHLLAPI application.\n");
            return 1;
        case HARC_SYSTEM_ERROR:
            printf("System error connecting to session A.\n");
            return 1;
        default:
            printf("Error connecting to session A.\n");
            return 1;
    }

D.      Write “HelloWorld” on the Emulator Screen

//Send the Keystroke as recorded in SendString Buffer
    HFunc = HA_SENDKEY;
    HLen = strlen(SendString);
    HRc = 0;
    hllapi(&HFunc, SendString, &HLen, &HRc);
    switch (HRc) {
        case HARC_SUCCESS:
            break;
        case HARC_BUSY:
        case HARC_LOCKED:
            printf("Send failed, host session locked or busy.\n");
            break;
        default:
            printf("Send failed.\n");
            break;
    }

E.    Disconnect from the ZIEWin Engine (Clean disconnect)

HFunc = HA_DISCONNECT_PS;
    HLen = 0;
    HRc = 0;
    hllapi(&HFunc, HBuff, &HLen, &HRc);
    printf("EHLLAPI program ended.\n");
    
    return 0;

Refer to below files for a complete sample code

Ehllapi_ZIEWin_Sample

Contact us

For further information on Organizing Web Applications in HCL ZIE, automation capabilities and Lab services offerings, please write to:

ZIO@hcl.com

Comment wrap
Further Reading
article-img
Mainframes | September 17, 2020
HCL ZIE for Windows Hardware and Software Pre-requisites
HCL ZIE for Windows, a native Windows 64-bit application is a proven emulator solution that supports 3270 and 5250 systems adhering to the latest security standards. Read the blog to know more details.
article-img
Mainframes | September 3, 2020
Installing Z and I Emulator for Windows (ZIEWin)
Z and I Emulator for Windows provides 3270, 5250, and VT emulation, connecting to z/OS®, z/VM®, eServer™ i5, iSeries®, System i5®, zSeries, and ASCII systems.
article-img
Mainframes | September 3, 2020
Configuring session on Z and I Emulator for Windows (ZIEWin)
Z and I Emulator for Windows saves emulator configuration information to a workstation profile (.WS). Depending on your Z and I Emulator for Windows configuration, you might have a workstation profile only or both workstation profile and a configuration file.
Close
Filters result by
Sort:
|