Using zOS-Web Enablement toolkit from CICS

[nk2164]

Hello,

I am wondering if i can use the zos web toolkit from a CICS application ? Are there any environment considerations . Would appreciate any pointers to documentation.

Thanks.

[CexyChris]

Hi,

good question. I was asking mysef the same - well, actually I asked @ian-burnett and got a very wholesome answer. In short: No, you cannot use the toolkit within CICS, because it requires the LE-Option POSIX(ON), which is not available in CICS-LE. As far as I understood, CICS could provide the correct environment, if all modules were linked with the option XPLINK, but that Option is only applicable to C and C++ language modules. Here is the bit of documentation, see "Runtime options ignored under CICS" https://www.ibm.com/support/knowledgecenter/en/SSGMCP_5.5.0/applications/developing/le/dfhp3_langenv_runopts.html With Ian's permission I could post our little Q&A here - it's a good read! What I still don't know, though, is why the POSIX(ON)-Option is required by the toolkit...

Kind regards

[ian-burnett]

Thanks @CexyChris - feel free to add that conversation here if you wish.

I still have the original email somewhere if you would rather I posted.

Ian.

[gorelikg]

Hi Everyone,

@ian-burnett thank you for handling the email! i saw you replied and explained the CICS situation and then i dropped the ball @CexyChris Q&A would be a welcomed addition!

My overdue answer for why HTTP/HTTPS Enabler requires POSIX(ON): HTTP/HTTPS Enabler takes advantage of the POSIX signal handling semantics to ignore SIGPIPEs while it's interacting with the socket on behalf of the user.

[nk2164]

@CexyChris @ian-burnett @gorelikg Thank you for your responses. It saved me a bunch of time :) My colleague, who has tried the toolkit from batch and REXX was curious if this would work in CICS. In fact, he did mention reading the documentation about the toolkit needing POSIX(ON) and it not being available in CICS. But we both were not really sure and wanted to code up something quick to try out. Glad I checked here before spending too much time.

[CexyChris]

These were the emails: Q: Hi Galina, Hi Ian,

we are currently working towards adapting the toolkit in to our traditional z/OS batch jobs to enable them to use software functions written in JEE, which are provided as web services. This works out rather smoothly so far. Now, the question was raised wether it'd be possible for COBOL programs, which use the toolkit and are primarilly written for batch, to be run in CICS. From a CICS point of view this seems a little odd, because there are inevitable differences between online and batch programs (OPEN and READ come to mind first, when talking about batch programs), but from the application developer's point of view this makes a lot of sense. Being able to write code which runs in batch as well as in CICS is very desirable. So even though it might make more sense to use the CICS-provided WEB API, there is still a good reason for developers to ask for their program to be agnostic of wether it is batch or online. When I tried out running a test program, I got an error message from the HWTHCONN callable interface with ReturnCode: 000003845 and description:The required POSIX(ON) run-time option is not set.
I then statically linked a CEEUOPT module into my program to set POSIX(ON), but this still doesn't work as CICS ignores the POSIX-Option as is stated in the documentation here: https://www.ibm.com/support/knowledgecenter/en/SSGMCP_5.5.0/applications/developing/le/dfhp3_langenv_runopts.html But the documentation also states, the option would take effect if the running program was linked with option XPLINK. So I was wondering: If the callable interfaces of the toolkit were linked with option XPLINK they might be running under CICS, right? I do not have an understainding of what implications come with using this option, though... Also I do not understand why POSIX(ON) is even needed. Would you please be so kind as to explain to me the need for POSIX and whether it is possible to link the callable interfaces with XPLINK. I would also like to hear your opinion about using the toolkit in CICS instead of the CICS-provided APIs.

Thank you very much for your time!

Kind regards Christoph

Answer: Hi Christoph,

I cannot speak as to why the z/OS Client Web Enablement Toolkit (CWET) requires POSIX: I'll leave Galina to answer that question.

While I understand the desire to keep source code common across both batch and CICS, there are some limitations which will prevent you from doing so if you are using COBOL. It is possible to run POSIX-enabled programs in CICS, however there are some caveats. The first is that, as you have found out, you need to compile and link with the XPLINK option enabled in order for CICS to provide the correct environment. The second is that only the z/OS C and C++ languages support the XPLINK convention.

https://www.ibm.com/support/knowledgecenter/SSLTBW_2.4.0/com.ibm.zos.v2r4.ceea200/ceea20029.htm

You mentioned your batch programs are written in COBOL so unless you write the applications in C or C++, you will not be able to obtain a POSIX environment inside CICS.

This is related to the implementation of Language Environment (LE) used within CICS. COBOL in CICS runs with CICS-LE, but you need to use batch-LE to run with POSIX enabled. Only the JVM and C applications compiled XPLINK run with batch-LE inside CICS.

Using the supplied CICS API services for network I/O, rather than the CWET functions has many advantages.

System administration is easier, because various aspects of the CICS web APIs can be configured using resource definitions, without the requirement to recompile the application. For example, changing cipher suites or target endpoints can be accomplished by modifying a URIMAP definition, whereas a caller of the CWET needs to alter the parameters passed to the API. The CICS web support provides timeout management via external configuration, both on a per-request basis and on a whole-transaction basis.

Diagnostic data is easier to obtain and use when using the CICS web APIs, because the CICS trace points can highlight the flow of data from the application, into the CICS subsystem, out to the network, then back in and back to the application. This trace can be dynamically controlled while the CICS region is running, with numerous diagnostic aids available should deeper investigation be required.

There are several monitoring benefits that can be gained by using the CICS APIs too. There are many CICS statistics fields which allow the system programmer to track the number of calls made to remote services at a global level, plus the CICS monitoring data allows the tracking of the number of calls made, elapsed time in remote calls, SSL ciphers used, amount of data transmitted etc. on a per-transaction basis.

https://www.ibm.com/support/knowledgecenter/en/SSGMCP_5.5.0/reference/monitoring/dfht3_mon_perfclass_dfhsock.html

If using the CWET within CICS, any calls to the CWET API will just appear as part of the application and CICS will not be able offer any diagnostic information as to why a transaction suffered a slowdown without instrumentation of the application code.

When using the CICS web implementation, clients can take advantage of socket pooling and SSL session caching - improving performance especially where many transactions are targeting the same endpoints.

Let me know if you need any further information.

Regards, Ian Burnett

[ian-burnett]

Thanks for that @CexyChris

While we have this discussion open, can I ask @nk2164 what your use-case was? Were you looking to use the HTTP/HTTPS handler or was it for the JSON processing?

As above, Christoph's requirement was to allow COBOL source to be shared between batch and CICS. If you only want to use some functionality in CICS and are willing to code in C, then it should be possible. CICS will allow you to EXEC CICS LINK from any language to an XPLINK C module which could then call the toolkit. I've never tried it myself, but that doesn't mean it's impossible.

If you have a use-case and are willing to keep this CICS-specific and use C (rather than shared source with batch), then I may be able to code up a sample.

Some considerations ahead of time:

1. Calling an XPLINK module in CICS from COBOL is relatively expensive in terms of CPU. We need to switch from the standard COBOL stack frame to the XPLINK stack frame, plus switch to a new TCB (X8 or X9). Then switch back when we return to COBOL (presumably that's your base application language).
2. As above, I cannot guarantee this will work - I will need to see what happens if/when I code this. There may be some hidden curiosities if we start calling the toolkit from multiple TCBs within the same address space. Using the JSON processing more likely to work (hence asking for the use-case).
3. None of this processing will be zIIP-eligible. If you are happy to switch languages from COBOL to Java, then Java is zIIP-eligible and there are plenty standard libraries which perform both HTTP outbound requests and JSON parsing / generation.
4. As per the email in the comment above, this won't offer the same configuration flexibility or RAS options as you get with the native CICS services.

Regards,

Ian

[nk2164]

@ian-burnett , Our Use-case was to try calling REST API's from cics application and process the json response . C might not work for us. We mostly use PLI. Reading all the considerations you documented here makes me think we need to pursue something different. Maybe explore native cics provided services or z/OS Connect EE.

I thank you all for your detailed responses.

[gorelikg]

@nk2164 From an HTTP/HTTPS Enabler + CICS perspective, agreed, until CICS supports POSIX(ON), HTTP/HTTPS enabler is not your ideal option. Regarding, z/OS Connect EE, under the covers for batch they do use the HTTP/HTTPS enabler and for CICS they use the native CICS support, so they're definitely a good option if you don't want to deal with dual path coding.

From a JSON Parser perspective, there are no restrictions/requirements for POSIX(ON), you should have no issues invoking from a CICS application.

Just keep in mind only AMODE(31) is supported at the moment for both entities.

[nk2164]

Sure . Thank you @gorelikg .