This C/370 sub-program can be used to invoke a remote Web Service or POJO from a CICS program.
Provided that a LegStar Proxy has been installed in an HTTP server, the API uses HTTP connectivity to the proxy which will in turn call a target Web Service, POJO, etc....
The messaging protocol used between the API and the proxy is identical to the one used for inbound calls to CICS programs by csokrt or chttprt. This means that data flowing between CICS and the proxy is raw EBCDIC relieving CICS from code page conversions and XML processing.
The API itself uses an HTTP library, called LSHTTLIB, also written in C/370. LSHTTLIB is a simple HTTP 1.0 library with support for basic authentication whose focus is on performance rather than functionality. Please note that this library connects CICS programs to the proxies, not to the target web service or POJO.
LSHTTLIB uses CICS Sockets. Please refer to z/os Communication Server documentation on how to setup IP CICS Sockets in the target CICS region.
When writing your client program you will need data descriptions of the input and output structures produced by the target web service. The COBOL Structures Generator module generates such data descriptions.
- CICS TS 2.3 (6.3.0 Command language translator)
- C/370 for OS/390 V2 R10
The first step is to create and deploy a proxy in an HTTP engine. The Mainframe Service Generator module helps you generate such a proxy.
Once LSHTTAPI and LSHTTLIB have been compiled in a library available to your CICS region in the RPL list, you might need to define LSHTTLIB using RDO (unless programs get autoinstalled).
Then you can write a client application using using LSHTTAPI.
There are 2 structures that form the parameters passed to the API. Because these structures are shared with a C/370 program, all fields must be synchronized on fullword boundaries and character fields must be null terminated. The API offers 2 methods (strC2Cob and strCob2C) to help with formatting.
The first structure is used for tracing and error reporting. It must be passed on the very first call to the init API method:
| Field name | Size | Description | |
| TRACE-ID | 17 | in | A correlation ID for end to end tracing |
| TRACE-MODE | 4 | in | 0= traces off, 1= traces on |
| ERROR-MESSAGE | 266 | out | Human readable error message |
The second structure is passed on every call to the invoke API method:
| Field name | Size | Description | |
| URI | 513 | in | The c2wsrt gateway locator |
| SERVICE-NAME | 33 | in | Logical name of the target web service |
| REQUEST-DATA | 4 | in | A pointer to the request host data |
| REQUEST-DATA-LEN | 4 | in | length (in bytes) of the request host data |
| REPLY-DATA | 4 | out | A pointer to the reply host data |
| REPLY-DATA-LEN | 4 | out | length (in bytes) of the request host data |
| CONNECT-TIMEOUT | 4 | in | Max wait time for a gateway connection (seconds) |
| RECV-TIMEOUT | 4 | in | Max wait time for a reply (seconds) |
| PROXY-URI | 513 | in | If gateway is behind a proxy |
| USERID | 33 | in | If gateway requires authentication (basic) |
| PASSWORD | 33 | in | If gateway requires authentication (basic) |
Any error will be signaled back with a negative return code. HTTP standard error codes such as 404 or 500 becomes -404 and -500. In addition to these standard error codes, you may also get: