Automation using PCSAPI

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:

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