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:
- 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:
- Z and I Emulator for Windows Session API (PCSAPI):ZIEWin sessions management.
- Emulator High Level Language API (EHLLAPI): Manage interaction between workstation
application and host system once the session is established.
- 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):
|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:
BOOL WINAPI pcsConnectSession(char cShortSessionID)
BOOL WINAPI pcsDisconnectSession(char cShortSessionID)
BOOL WINAPI pcsQueryConnectionInfo(char cShortSessionID, CONNECTIONINFO
ULONG WINAPI pcsStartSession(PSZ lpProfile, char cShortSessionID, USHORT fuCmdShow)
BOOL WINAPI pcsStopSession(char cShortSessionID, USHORT fuSaveProfile)
ULONG WINAPI pcsQuerySessionList(ULONG Count, SESSINFO *SessionList)
For more information about these API, please click here.
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):
'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
'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.
For further information on Organizing Web Applications in HCL ZIE, automation capabilities and Lab services offerings, please write to:
Sudhir Ranjan Rout
Developer, Lab Services
I have this code in my VB to connect the IBM-i but not able to get connected.
The VB code is used to connect IBM – i is below.
Private Declare Function hllapi Lib “pcshll32” (pFunctionNumber As Long, ByVal pData As String, _
pDataLength As Long, pReturnCode As Long) As Long
its returning the error of 76 path not found. I am using IACS – Client emulator to connect the AS400
I am trying to automate IBM ACS which is java based 5250 emulator.
I started with trying the sample you provided on your blog, but once hllapi function is called, it does not go any further.
Could you pls help with any suggestions?