News
Abstract
Send user-defined payloads using new client APIs
Content
What is it?
You may already be using integrated web services client for ILE to send SOAP requests. New support has been added to integrated web services client support that allows you send any user-defined payloads over the HTTP transport.
The new support is the transport APIs, and is made up of the following APIs:
| Function | Description |
| axiscTransportCreate() |
Create a transport object. |
| axiscTransportDestroy() |
Destroy a transport object. |
| axiscTransportReset() |
Resets the transport object to its initial state. This includes closing the connection to server, and clearing out all properties that have been set. |
| axiscTransportSetProperty() | Sets a transport property. |
| axiscTransportGetProperty() | Gets a transport property. |
| axiscTransportSend() | Send bytes over transport. The function buffers the data until the axiscTransportFlush() function is called. |
| axiscTransportFlush() | Flush the transport of any buffered data. |
| axiscTransportReceive() |
Receive data from the transport. |
| axiscTransportGetLastErrorCode() | Get transport error code from last unsuccessful transport operation. |
| axiscTransportGetLastError() | Get transport error string from last unsuccessful transport operation. |
The C prototypes for the functions are in the file /QIBM/ProdData/OS/WebServices/V1/client/include/axis/ITransport.h. The RPG prototypes for the functions are in the file /QIBM/ProdData/OS/WebServices/V1/client/include/Axis.rpgleinc.
The typical flow of events when using the transport APIs is as follows:
- Use the axiscTransportCreate() API to create a transport object. The URL to web service is specified on the call to the function.
- Set any transport properties (e.g. connect timeout, HTTP method, HTTP headers, whether payload needs to be converted to UTF-8, etc.) using the axiscTransportSetProperty() function.
- Send data (if any) using the axiscTransportSend() function. Data is buffered until the axiscTransportFlush() is called. The data is automatically converted to UTF-8 unless the AXISC_PROPERTY_CONVERT_PAYLOAD transport property is set to "false". In which case the data is sent as-is.
- Send the request to the client by invoking the axiscTransportFlush() function.
- Receive the response to the request by calling the axiscTransportReceive() function. This API must be called even if no data is returned in order to consume the HTTP response to the request, which includes the HTTP response headers and status code. The data is automatically converted from UTF-8 to the job CCSID unless the AXISC_PROPERTY_CONVERT_PAYLOAD transport property is set to "false". In which case the data is returned as-is.
- If no errors were detected on the call to axiscTransportReceive(), retrieve the HTTP status code to determine what to do with received data using the axiscTransportGetProperty() API with property to be retrieved set to AXISC_PROPERTY_HTTP_STATUS_CODE.
- Destroy the transport object by calling the axiscTransportDestroy() function.
The attachments at the bottom of page point to simple programs that sends a REST request to retrieve student registrations in various programming languages. One is written in RPG (restRS.rpgle_.src), one is written in COBOL (restRS.CBLLE_.src), and one is written in C (restCS.c.src).
Why use it?
The new APIs allow you to send user-defined payloads over the HTTP transport. This will enable users to send REST requests or even SOAP requests while controlling exactly what is sent. The APIs will handle the details of the HTTP protocol while allowing users to handle the important details, which is the payload sent and received.
Availability
The new client APIs are available in releases IBM i 7.1, 7.2, and 7.3. You must load the following PTFs in order to be able to use the APIs:
IBM i 7.1: SI61773, SI59019
IBM i 7.2: SI61774, SI59020
IBM i 7.3: SI61775, SI60359
Was this topic helpful?
Document Information
Modified date:
31 December 2019
UID
ibm11138654