Introduction

ZIEWin provides an emulator interface to communicate with IBM Mainframe/AS400/VT sessions. This is used for reading & updating host data and interfacing host with other applications. Performing manual tasks on emulator screen increase in transaction and becomes repetitive, and over the long term would have below issues:

  • Inefficient
  • Redundant and hence error-prone
  • Time-consuming and thus expensive

ZIEWin exposes many Application Programming Interfaces (APIs) to empower the user to automate commonly performed tasks. Different APIs are provided with a specific set of functions, which can be used for different purposes and provide different programming interfaces based on the user’s requirement. Different APIs support programming languages such as Visual Basic for Applications (and thus supports MS Office applications), C/C++, C#, Java, LotusScript, REXX, etc.

The list of API set provided by ZIEWin and their functions:

  1. Z and I Emulator for Windows Session API (PCSAPI):ZIEWin sessions management.
  2. Emulator High Level Language API (EHLLAPI): Manage interaction between workstation
    application and host system once the session is established.
  3. Z and I Emulator for Windows Host Access Class Library (HACL): Set of objects that allow application programmers to access host applications easily and quickly.
    Enhanced Connectivity Facility (ECF) providing the tools to write SRPI requester programs

In this blog, we will explore more about PCSAPIs.

PCS Session APIs can launch, open session, close, connect, and disconnect the ZIEWin session. As the EHLLAPI APIs are tightly coupled with IBM EHLLAPI communication standard (TN3270 and TN5250 protocol), they do not have session management API’s. ZIEWin Session APIs also provide functions to setup printer, page and query workstation profile/session list/Emulator Status. These API’s can be used in conjunction with EHLLAPI/HACL API’s to complete the automation cycle.

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

Listed below are the most commonly used PCS APIs and their prototype:
1.      pcsConnectSession
         BOOL WINAPI pcsConnectSession(char cShortSessionID)
2.      pcsDisconnectSession
         BOOL WINAPI pcsDisconnectSession(char cShortSessionID)
3.      pcsQueryConnectionInfo
         BOOL WINAPI pcsQueryConnectionInfo(char cShortSessionID, CONNECTIONINFO
*ConnectionInfo)
4.      pcsStartSession
         ULONG WINAPI pcsStartSession(PSZ lpProfile, char cShortSessionID, USHORT fuCmdShow)
5.      pcsStopSession
         BOOL WINAPI pcsStopSession(char cShortSessionID, USHORT fuSaveProfile)
6.      pcsQuerySessionList
         ULONG WINAPI pcsQuerySessionList(ULONG Count, SESSINFO *SessionList)

For more information about these API, please click here.

MacroExecutionBlockDiagram:
​The following diagram depicts the High-level view of the ZIEWin’s API-Macro Engine-IBM Host flow.

Code Snipped VBA code (in Excel Application):

A.     Declarations

'Declaration for PCSAPI functions and defining their prototype to VBA engine
Declare PtrSafe Function pcsStartSession Lib "PCSAPI32.DLL" (ByVal buffer As String, ByVal SessionID As Integer, ByVal CmdShow As Integer) As Integer
Declare PtrSafe Function pcsStopSession Lib "PCSAPI32.DLL" (ByVal SessionID As Integer, ByVal SaveProfile As Integer) As Integer
'Declaration for EHLLAPI functions and defining their prototype to VBA engine
Declare PtrSafe Function ZIEWin_SendKey& Lib "PCSHLL32.DLL" Alias "hllapi" (HllFunctionNo&, ByVal HllData$, HllLength&, HllReturnCode&)
Declare PtrSafe Function ZIEWin_SetCursor& Lib "PCSHLL32.DLL" Alias "hllapi" (HllFunctionNo&, ByVal HllData$, HllLength&, HllReturnCode&)
Declare PtrSafe Function ZIEWin_ConnectPS & Lib "PCSHLL32.DLL" Alias "hllapi" (HllFunctionNo&, ByVal HllData$, HllLength&, HllReturnCode&)
'Defining Global Variable
Dim SessionID As Integer
Dim ProfileName As String

B.      Entry Function

'Function entry point which drives the automation
Sub PCSAPISample()
SessionID = 65 'Session A
ProfileName = "Iseriesdemos.WS" 'change it session name of your preference
'call the LaunchZIEWinSession Sub
LaunchZIEWinSession ProfileName, SessionID
'Create a EHLLAPI connection with ZIEWin
ConnectZIEWinSession
'Move the cursor to desired location on the ZIEWin Screen
moveCursor 8, 53, 10
'Send a string to ZIEWin Screen
sendString "HelloWorld"
'Disconnect and close the ZIEWin Session
StopZIEWinSession SessionID
End Sub

C.      ConnectZIEWinSession

'Function to establish connection to a ZIEWin session
Public Function ConnectZIEWinSession()
    HllFunctionNo = 1
    HllData = "A"
    HllLength = 4
    HllReturnCode = 0
    RC = ZIEWin_ConnectPS(HllFunctionNo, HllData, HllLength, HllReturnCode)
    If RC = 0 Then
        MsgBox "Connection Established"
    Else
        MsgBox "Connection Failed"
    End If
    
End Function

D.     LaunchZIEWin Function

'Function to launch the ZIEWin session
Public Function LaunchZIEWinSession(ProfileName As String, SessionID As Integer)
        
    On Error Resume Next
    Dim RC As Integer
    
    'PCSStartsession take 'session profile file' and the session ID (65->ASCII->'A')
    RC = pcsStartSession(ProfileName, SessionID, 2)
    
    If RC = 0 Then
        MsgBox "ZIEWin Launched Successfully"
    Else
        MsgBox "ZIEWin Launched failed"
    End If
End Function

E.     Stop ZIEWin Session

'Function to disconnect and stop the ZIEWin session
Public Function StopZIEWinSession()
        
    On Error Resume Next
    Dim ziewinStop As Boolean
   
    'PCSStopSession takes Session ID and save mode as input
    ziewinStop = pcsStopSession(SessionID, 2)
    If (ziewinStop = True) Then
        MsgBox "ZIEWin Closed Successfully"
    End If
End Function

 

Download the sample code:

Attached is an excel sample that can be used to test PCSAPI calls.

PCSAPI_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

Sudhir Ranjan Rout

Developer, Lab Services

Comment wrap
Further Reading
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.
article-img
Mainframes | August 12, 2020
Automation using EHLLAPI
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.
Close
Filters result by
Sort:
|