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
Mainframes | September 17, 2020
Organizing Web Application Deployment in HCL ZIETrans
HCL ZIETrans allows you to transform your user experience by extending 3270 and 5250 terminal applications to the web, portlet, rich client, or as standard SOAP or RESTful web services. By default, all HCL ZIETrans Web applications are stored in one enterprise archive file. HCL ZIETrans Toolkit is an HCL ZIE component that enables you to develop new applications and allows previewing and saving each change. We can streamline the HCL ZIETrans application in such a way that it becomes easier to use the host applications whose data and functions it presents. The supported servers for multiple HCL ZIETrans applications in an ear are ‘WebSphere Application Server’ and ‘WebSphere Liberty’. This blog describes the ways to manage the HCL ZIETrans web applications that have multiple .ear and multiple .war in the projects, using HCL ZIETrans Toolkit and the best practices. When you export your applications as HCL ZIETrans EAR file and deploy them on WebSphere Application Server, the .ear file contains a Web archive (.war) file with the resources to run each application. An EAR may also combine multiple web projects (WAR), Enterprise JavaBeans projects (JAR), standard JARs, etc. into a single application. Each individual .ear consumes around 25MB (minimum) of disk space during runtime. So, if you have multiple HCL ZIETrans projects you may end up having multiple HCL ZIETrans EAR of varying size depending on the complexity of the application. Based on different deployment or development scenarios may lead to developers/administrators opting for single EAR or multiple EAR’s deployment solutions. The below table illustrates salient points of the ‘Individual’ Vs ‘Multiple wars in single’ EAR deployment method, based on these customers can decide their HCL ZIETrans application deployment architecture. Table 1: Individual Vs Multiple wars in one EAR deployment Ways to organize the HCL ZIETrans Web Applications: Associating...
Mainframes | September 3, 2020
Installing Z and I Emulator for Windows (ZIEWin)
Introduction: 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. Z and I Emulator for Windows uses Microsoft Windows Installer technology for all installation procedures. When the Z and I Emulator for Windows installation image is first run, it examines the target system and, if necessary, automatically installs the proper version of the Windows Installer service. Setup.exe is the bootstrap loader that calls the Windows Installer service (msiexec.exe) and launches the installation dialogs. The following should be taken into account when installing Z and I Emulator for Windows: In some cases, installation of Windows Installer triggers a reboot of the system. If you are required to reboot, upon subsequent startup you are taken immediately back to Windows Installer to continue installation of Z and I Emulator for Windows. After Windows Installer has been successfully installed, if the installation of Z and I Emulator for Windows fails or is cancelled by the user, Windows Installer rolls back all partially installed Z and I Emulator for Windows files and returns the system to its original state. You must be a member of the Administrator's group to perform these installations. Before you begin installation, make sure all other applications are stopped. If you are reinstalling Z and I Emulator for Windows or are upgrading Z and I Emulator for Windows, make sure that Z and I Emulator for Windows is not running before you start setup. For more details, see the video on ‘ZIEWin Installation’ : https://youtu.be/alXvflupxps Contact us For further information on Organizing Web Applications in HCL ZIE, automation capabilities and Lab services offerings, please write to: ZIO@hcl.com Mahua Chanda Developer, Lab Services, HCL ZIE
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. The workstation profile can be used later by other Z and I Emulator for Windows sessions, or to restart this session. Configuring Session To create a new session, follow the steps given below: From the Start menu, click Programs -> HCL Z and I Emulator for Windows -> Start or Configure Sessions. In the Session Manager dialog box , click New Session. The Customize Communication window appears. Select the type of host from the Type of Host drop-down list box. Select the interface you will use from the Interface drop-down list box. Select the attachment type you want to use from the Attachment drop-down list box. Click Session Parameters to modify the session type (display or printer), host code page, and display/graphics options. The Session Parameters - 3270, 5250, or ASCII - Host window appears (depending on the host you selected in step 3). Click OK. Click Link Parameters. Enter the appropriate information for each page and click Next to continue and click Finish when you are done. Click the Host Definition tab to configure the Connection Options. Select Auto-reconnect to reestablish an interrupted connection. The Connection Timeout value tells Z and I Emulator for Windows how long it should wait to connect to the host. The Try connecting to last configured host infinitely option is enabled by default. Clear this box if you do not want Z and I Emulator for Windows to automatically and indefinitely wait for acknowledgement for a connect request from the last correctly configured server/host. After configuring the session options, click OK in the Telnet tab panel. Click OK on the Customize Communication window. The session is displayed automatically. For more details, see the video on ‘Configuring Display and Printer Session’ : https://youtu.be/x6dg9kEpwDk Contact us...
a/icon/common/search Created with Sketch.