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

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

3/8/2020 04:13:33 pm

As of your post, VBA for Excel 64-bit is incompatible with EHLLAPI 32-bit. Examples given here are for Excel 32-bit only. VB.Net programs will work but not VBA.

Raiders52(Al)

2/17/2020 09:55:15 pm

I am looking for someone who has experience integrating Excel VBA calls (and passing Variables) to the AS400 Macros which has been recorded in the new Windows 10 iAccess Client scripting language "HAScript". I have been searching for weeks and have not found anyone with this experience. I have built many Excel VBA automation scripts making calls to the old iAccess Client Ver. 7.1 AS400 macros recorded in vbscript. Any help would be greatly appreciated.

Many thanks
Raiders52(Al)

StefanoP

3/5/2020 04:14:41 pm

Hello Raider52,
I have a problem like your. I developed powerful program with Visual Basic and now I need to convert them for Windows 10 iAccess Client for JAVA. For this purpose I am analyzing XML macro language deeply.
The main lack is for instructions to realize a loop like for - next (in VB). I can try to realize loop with the instruction:
<recolimit value="1" goto="RecoveryScreen1" />.

At the moment I am not sure it's possible to realize a powerful macro.

Until now no one answer to my help request.

Please, stay in touch with me, let's help each other.

Thank you
StefanoP

3/8/2020 05:36:24 am

Hi Stefano,

You can indeed create powerful interfaces to AS400 (i Series) using the EHLLAPI interface via VBA / VB.Net. I wrote a VB.Net desktop app to update iSeries applications via Excel input transactions. It interfaces with the new Java-based IBM emulator. Here's a link to a HowTo demo for an idea of what can be accomplished. It's a zip of an MP4 video.

http://www.plug-and-chug.com/2footputt/AppMapperV2/AppMapper_HowTo.zip

Saravanan

8/29/2020 04:26:41 pm

Hi Raiders,

Have you found any solution to connect the AS400 new emulator which is on Windows 10.
iACS client : acshod-B20200829_190244(32-bit)11.0.8-B20130530 Version: 1.1.8.5

I am trying to connect the API like this but failed please give me if you get some idea on how to connect.

API i used to connect the AS400 from VB-Excel Macro.

Private Declare Function hllapi Lib "pcshll32" (pFunctionNumber As Long, ByVal pData As String, _
pDataLength As Long, pReturnCode As Long) As Long

Raider52

8/29/2020 06:10:27 pm

Hello Saravanan:

No I have not yet found a solution to my Windows 10 AS400 emulator, which runs the old VBA connection to PCCOM. Fortunately, we can continue using the pre-Windows 10 iClient Access emulator without a problem... There is quite an investment of time in the old Excel/VBA scripts, and we need to find a solid solution before spending lot of effort/cost on the conversion.

Let's keep in touch
Raider52

9/2/2020 04:11:21 am

Hi Saravanan,
I agree with Raider52: if it’s possible, it’s better to continue with the pre-Windows10 iClient Access.
In my case it wasn’t possible and I had to convert the VB code in XML instructions. It was not easy because XML is not well-documented in IBM sites and no real examples are available in internet.
I worked a lot during lockdown and in May I completed the conversion of two complex VB programs.
Customer users are now working with the new XML program on the new emulator (JAVA based).
Now I have a good experience in XML emulator API and I can help someone which need to convert the VB program realized for the previous emulator.
Don’t hesitate to ask me more details of conversion if you need.

StefanoP

Raiders52

9/7/2020 11:16:06 pm

Hello StefanoP

Could you share the part of your code where VBA accesses the AS400 and launches the pre-recorded AS400 macros... This is the part which confuses me.

Thanks,
Raiders52

3/5/2020 08:51:41 pm

Hello StefanoP

I am not a Java or XML developer. I have developed good skill in VBA. I will certainly like to keep in touch, as I have developed good Excel VBA/AS400 vbs macro integration, and need to convert the same to accommodate Excel VBA to work with IBM HAScript (java) coding.

If you have any VBA code that works with Windows 10 iAccess Client for JAVA, I would love to see if I could simulate the same.

Thanks again for your reply.

Raider52(Al)

3/8/2020 05:46:00 am

Don't struggle. Make sure you've got the prerequisites covered. Here's a link to a Zip that contains a working Excel Macro Workbook and a PDF outlining the prerequisites required to run VB.Net and VBA in the new Java-based IBM Access Client.

www.plug-and-chug.com/2footputt/AppMapperV2/VBA_EHLLAPI.zip

3/8/2020 04:16:24 pm

My previous comment is for 32-bit Excel. We're still researching how to make it work with Excel 64-bit.

3/9/2020 07:23:09 pm

Hi Rich Little,
I appreciated your develop and your suggestion to install HOD EHLLAPI Bridge in order to reuse the already VB developed code.
Is HOD EHLLAPI Bridge free for AS400 customer ?
Anyway I am not sure to convince the customer to install Windows 10 iAccess Client for JAVA 32-bit version because they centrally installed 64-bit version in order to meet better Windows 10 architecture.
I'll try to convince the customer and I'll continue to investigate how to substitute the some parts of VB programs with XML macro.
I didn't find anyone with some knowledge and experience about the XML macro; the only one available with Windows 10 iAccess Client for JAVA.

Best Regards
StefanoP

4/14/2020 10:03:58 am

Hello
I finished to convert my VB.net programs, just the portion which interface the AS400 emulator, in XML language.
Indeed new VB.net code realizes the XML macro to be launched from the emulator interface.
With the help of covid 19 seclusion, this job takes few days.
For the moment I could not tested it ; I hope to do it asap on a customer PC of a remote user. Otherwise I'll will have to wait the customer site reopening.
The only thing I did't find is a command line to launch the XML macro; it could be similar to
C:\IBMiAccess_v1r1\Start_Programs\Windows_x86-64\acslaunch_win-64.exe \PLUGIN= ....
but I didn't find the right Plugin to launch the XML (.mac) macro.

saha

6/29/2020 11:54:11 am

Hi,

How to read string in HOD 3270, while i'm run the CopyPStoString fun=8 HllData value showing 0.its not changing. Kindly help on this

sending keystrok and moving cuursor are working but ican't able to read string in HOD 3270

below is code:
Declare Function PCOMM_CopyPStoString& Lib "PCSHLL32.DLL" Alias "hllapi" (HllFunctionNo&, HllData$, HllLength&, HllReturnCode&)

'EHLLAPI function implementation of CopyString
Function CopyString(targetRow As Integer, targetCol As Integer, lngth As Integer) As String 'confirmed

Dim tempPos As Integer

tempPos = calculateAbsPos(targetRow, targetCol)
HllFunctionNo = 8
HllData = vbNullString
HllLength = lngth
HllReturnCode = tempPos
retVal = PCOMM_CopyPStoString(HllFunctionNo, HllData, HllLength, HllReturnCode)
CopyString = HllData

If retVal <> 0 Then
MsgBox "Copy string could not be set"
Else
MsgBox "Copied to string"
End If
End Function

9/19/2020 11:34:01 am

Hello Raiders52,
I used Visual Basic to write the real macro in XML language; the name of xml macro file is code_generation.mac (mac extension is required).
For security reason the users login in AS400 independently, than he executes my Visual Basic program. The program writes the file code_generation.mac and launch an Ctrl-i (I used a simple autoit program). In the As400 java based emulator, Ctrl-i was previously associated with the execution of the macro code_generation.mac.

Here the first instructions of code_generation.mac (it is a sequence of screens):

<HAScript name="macro_codici_200322_192748" description="" timeout="3600000" pausetime="300" promptall="true" blockinput="false" author="AAA" creationdate="22-mar-2020 19.27.48" supressclearevents="false" usevars="false" ignorepauseforenhancedtn="true" delayifnotenhancedtn="0" ignorepausetimeforenhancedtn="true" continueontimeout="false">
<screen name="Schermo1" entryscreen="true" exitscreen="false" transient="false">
<description >
<oia status="NOTINHIBITED" optional="false" invertmatch="false"/>
</description >
<actions>
<input value="AN 1[enter]" row="0" col="0" movecursor="true" xlatehostkeys="true" encrypted="false"/>
</actions>
<nextscreens timeout="0">
<nextscreen name="Schermo2"/>
</nextscreens>
<\screen>
<screen name="Schermo2" entryscreen="true" exitscreen="false" transient="false">
<description >
<oia status="NOTINHIBITED" optional="false" invertmatch="false"/>
</description >
<actions>
<input value="5194538 19[enter]" row="0" col="0" movecursor="true" xlatehostkeys="true" encrypted="false"/>
</actions>
<nextscreens timeout="0">
<nextscreen name="Schermo3"/>
</nextscreens>
<\screen>
<screen name="Schermo3" entryscreen="true" exitscreen="false" transient="false">
<description >
<oia status="NOTINHIBITED" optional="false" invertmatch="false"/>
</description >
<actions>
<input value="[pf15]" row="0" col="0" movecursor="true" xlatehostkeys="true" encrypted="false"/>
</actions>
<nextscreens timeout="0">
<nextscreen name="Schermo4"/>
</nextscreens>
<\screen>
<screen name="Schermo4" entryscreen="true" exitscreen="false" transient="false">
<description >
<oia status="NOTINHIBITED" optional="false" invertmatch="false"/>
</description >
<actions>
<mouseclick row="4" col="60"/>
<input value="5194538 11[enter]" row="0" col="0" movecursor="true" xlatehostkeys="true" encrypted="false"/>
</actions>
<nextscreens timeout="0">
<nextscreen name="Schermo5"/>
</nextscreens>
<\screen>
<screen name="Schermo5" entryscreen="true" exitscreen="false" transient="false">
<description >
<oia status="NOTINHIBITED" optional="false" invertmatch="false"/>
</description >
<actions>
<input value="[enter]" row="0" col="0" movecursor="true" xlatehostkeys="true" encrypted="false"/>
</actions>
<nextscreens timeout="0">
<nextscreen name="Schermo6"/>
</nextscreens>
<\screen>
<screen name="Schermo6" entryscreen="true" exitscreen="false" transient="false">
<description >
<oia status="NOTINHIBITED" optional="false" invertmatch="false"/>
</description >
<actions>
<mouseclick row="7" col="79"/>
<input value="C" row="0" col="0" movecursor="true" xlatehostkeys="true" encrypted="false"/>
<mouseclick row="10" col="72"/>
<input value="07102019" row="0" col="0" movecursor="true" xlatehostkeys="true" encrypted="false"/>
<mouseclick row="20" col="13"/>
<input value="02440 " row="0" col="0" movecursor="true" xlatehostkeys="true" encrypted="false"/>
<mouseclick row="17" col="68"/>
<input value="9D[enter]" row="0" col="0" movecursor="true" xlatehostkeys="true" encrypted="false"/>
</actions>
<nextscreens timeout="0">
<nextscreen name="Schermo7"/>
</nextscreens>
<\screen>
........................
.......................
...........................

Dan Ortiz link

12/7/2020 10:10:00 pm

Nice article, I found this sample very handy I wonder know how to implement a couple things:

a. sendString Method calls PCOMM_SendKey; how to send Mnemonics as [enter] key?

b. Let's talk how could we retrieve data from our IBM host screen, after we have reached the screen position at Row, Col we wonder read N chars to the right.

12/8/2020 09:33:37 am

Hello Dan, I agree with you. It was very hard to substitute the PCOMM with xml instructions for a complex program realized in Visual Basic. Especially because of the poor IBM documentation and lack of examples.

Anyway for your requests:

Answer a. :

<actions>
<input value="'[enter]'" row="0" col="0" movecursor="true" xlatehostkeys="true" encrypted="false" />
</actions>

Answer b. :

<actions>
<mouseclick row="$indice_riga$" col="3" />
<extract name="'Dat05'" planetype="TEXT_PLANE" srow="$indice_riga$" scol="7" erow="$indice_riga$" ecol="14" assigntovar="$nome_spool$" />
<actions>

Where indice_riga is the row of the screen and the the variable nome_spool retrieve the characters from column 7 to column 14 (8 characters).

Personal Communications Session API (PCSAPI) in IBM Personal Communications

Leave a Reply.

Archives

Categories