Personal Communications Session API (PCSAPI) in IBM Personal Communications

2/15/2018

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 convention

PCOMM 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):

Download the Sample code:

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

pcsapi_excel_sample.zip
File Size:	18 kb
File Type:	zip

Download File

Contact:

For further information on automation in IBM PCOMM/HOD, contact zServices@hcl.com

Or write to HCL-HI-LabServices@hcl.com to get more information on Services offerings or Technical details.

Avinash Sable
Lead - Lab Services, IBM HACP & HATS
avinash.sable@hcl.com

6 Comments

Rich Little

4/16/2018 05:22:27 pm

Does this work with the new (ish) Java-based ACS emulator?

Avinash Sable

4/18/2018 02:37:52 am

Hi Rich,

There are couple of IBM System i Emulators flavours based on Host On-Demand (HOD) and Personal Communications (PCOMM).

1. The windows based IBM iAW (i-series access for windows) Emulator supports PCS API’s as it consumes PCOMM binaries. However, support for IBM iAW for Windows is no longer supported beyond windows 8.1 (IBM reference here: http://www-01.ibm.com/support/docview.wss?uid=isg3T1026807).

2. The new Java based ACS emulator uses HOD binaries, which does not provide PCSAPI support (directly).
o However, If you are still looking to use PCSAPI’s in conjunction with, ( & may be EHLLAPI) then you may consider using HOD EHLLAPI Bridge. Read my blog here (https://www.tetcommunity.com/blogs/ibm-host-on-demand-ehllapi-bridge) to know how to use existing PCOMM PCSAPI/EHLLAPI automation code in HOD.
o You may also consider using HOD’s Session API’s (which by the way are equally or more powerful than PCSAPIs). You can find more IBM reference here (https://www.ibm.com/support/knowledgecenter/en/SSS9FA_13.0.0/com.ibm.hod.doc/doc/SessionManager/SessionManagerAPI.html). We are working on a blog to cover that base as well.

Rich

4/18/2018 12:22:32 pm

So it looks like I need to have HOD installed if I want to go with either the Bridge or HOD Session API's. Is that correct?

4/19/2018 05:02:36 am

Hello Rich,

Though we deal with HACP (PCOMM & HOD) and not expert on ACS, but we do know that HOD libraries are used as is. Which also means that if configured properly, Technically ACS should work/behave the same way HOD does.
1. HOD EHLLAPI bridge is an installer (right now supported only on windows) available to download from IBM Fix Central (needs HACP entitlement) and is a must! Without this installers PCSAPI/EHLLAPI code will not work with ACS (or HOD).
o Once you have that installed, you can open launch the ACS with the selected (.hod) session
o On your ACS client, ‘Select Communication->Configure’.
o Select ‘Preferences->Start Options’ on the left pane.
o Click ‘Yes’ radio button on the ‘Auto-Start HLLAPI Enabler’ option.
2. HOD Session API: looking at the way ACS bundle is (a single executable jar), no other jar is exposed to the user (even the HOD jars). So, looks like to use HOD Session API’s you will need HOD Installed.
3. If installing HOD is not what you want to do, you may also consider installing Host Access Toolkit (IBM Passport Advantage: needs HACP entitlement), which ships the HOD libraries. This Allows you to completely customize the Emulator Display and Automation using HOD API’s. A Blog on that is also underway.

Hope this helps.
Feel free to ask more clarification.

http://www.resumeformat2017.com/teacher-resume-format-2017/ link

9/28/2018 06:44:04 am

An online MBA degree is an uncommon chance to encourage your livelihood and land the position you require. In any case, such countless today experience issues with gaining the egree and visit website to get more data. Swing to capable article forming destinations if you need a specialist and apt support and would lean toward not to get wonderfully left.

Budi Setiawan

8/23/2019 07:51:36 am

I was trying to run it under Excel for Office 365 on Windows 10. Changed the code as below
Declare PtrSafe Function PCOMM_ConnectPS& Lib "PCSHLL32.DLL" Alias "hllapi" (HllFunctionNo&, ByVal HllData$, HllLength&, HllReturnCode&)

However, it keeps complaining as Run-time error '48': File not found PCSHLL32.DLL

I confirmed that the file PCSHLL32.DLL exist and it's in the search path list.

Another thing is seemed the following code :
RC = pcsStartSession(ProfileName, SessionID, 2)
is not working although there is no error message.

Could you please give us a piece of advice ?

Thank You :-)

Personal Communications Session API (PCSAPI) in IBM Personal Communications

Leave a Reply.

Archives

Categories