IBM Personal Communications 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 increases in transaction and becomes repetitive, this over a long term would have issues:
- Inefficient
- Redundant and hence error prone
- Time consuming and thus expensive
IBM Personal Communications 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 interface 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 PCOMM and their functions:
A.
Personal Communications Session API (PCSAPI): PCOMM sessions management.
B.
Emulator High Level Language API (EHLLAPI): Workstation application <> Host management once session is established.
C.
IBM Personal Communications Host Access Class Library (HACL): Workstation application <> Host management once session is established.
D.
Dynamic Data Exchange (DDE): Host-Client data exchange management.
E.
Server-Requestor Programming Interface (SRPI): Provides access to IBM Enhanced Connectivity Facility (ECF) providing the tools to write SRPI requester programs
In this blog we will explore more about PCS APIs.PCS Session APIs have the capability to launch, open session, close, connect, disconnect the PCOMM 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. PCOMM Session APIs also provide functions to setup printer, page, 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 conventionPCOMM Session APIs follow a simple prototype for all functions to keep the programming straightforward. As mentioned above these API’s 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 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.
Macro Execution Block Diagram:
Following diagram depicts the High-level view of the PCOMM’s API-Macro Engine-IBM Host flow.
Code Snipped VBA code (in Excel Application):
A. Declaration
'Declaration for PCSAPI functions and defining their prototype to VBA engine
Declare Function pcsStartSession Lib "PCSAPI32.DLL" (ByVal buffer As String, ByVal SessionID As Integer, ByVal CmdShow As Integer) As Integer
Declare 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 Function PCOMM_SendKey& Lib "PCSHLL32.DLL" Alias "hllapi" (HllFunctionNo&, ByVal HllData$, HllLength&, HllReturnCode&)
Declare Function PCOMM_SetCursor& Lib "PCSHLL32.DLL" Alias "hllapi" (HllFunctionNo&, ByVal HllData$, HllLength&, HllReturnCode&)
Declare Function PCOMM_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 to establish connection to a PCOMM session
Public Function ConnectPCOMMSession()
HllFunctionNo = 1
HllData = "A"
HllLength = 4
HllReturnCode = 0
RC = PCOMM_ConnectPS(HllFunctionNo, HllData, HllLength, HllReturnCode)
If RC = 0 Then
MsgBox "Connection Established"
Else
MsgBox "Connection Failed"
End If
End Function
C.ConnectPCOMMSession
'Function to establish connection to a PCOMM session
Public Function ConnectPCOMMSession()
HllFunctionNo = 1
HllData = "A"
HllLength = 4
HllReturnCode = 0
RC = PCOMM_ConnectPS(HllFunctionNo, HllData, HllLength, HllReturnCode)
If RC = 0 Then
MsgBox "Connection Established"
Else
MsgBox "Connection Failed"
End If
End Function
D. LaunchPCOMM Function
'Function to launch the PCOMM session
Public Function LaunchPCOMMSession(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 "PCOMM Launched Successfully"
Else
MsgBox "PCOMM Launched failed"
End If
End Function
E. Stop PCOMM Session
'Function to disconnect and stop the PCOMM session
Public Function StopPCOMMSession()
On Error Resume Next
Dim pcommStop As Boolean
'PCSStopSession takes Session ID and save mode as input
pcommStop = pcsStopSession(SessionID, 2)
If (pcommStop = True) Then
MsgBox "PCOMM Closed Successfully"
End If
End Function
Download the Sample code:
Attached is an excel sample that can be used to test PCSAPI calls.
pcsapi_excel_sample.zip
Contact: For further information on Automation, Services Offerings or Technical details in IBM HACP/HATS please connect with HCL mainframe Lab Services.
Avinash Sable
Lead - Lab Services, IBM HACP & HATS