The syntax of the interface methods, and the input and output parameters of the syntax are as follows:
For information about the sequence of calls, see Interface Methods and Sequence of Calls.
Initialization
The initialization function is used to initialize the HTTP Client Library.
Syntax
void INITHTTPLIBRARY(int *version, int *max_sessions, int *time_out, int *log_level,
char *log_file, int *sync_mode, char *comapiMode, int *result)Input Parameters
version is the HTTP client library API version. The current version is 1.0.
max_sessions is the maximum number of sessions that is open by this HTTP client. Pass the value 1 or more to create number a of sessions throughout the UCS COBOL application lifetime.
time_out specifies the timeout (in seconds) for the request to return.
log_level specifies if the implementation is on
Log Level | Description |
0 | None |
1 | Error |
2 | Warning |
3 | Information |
4 | Verbose |
log_file is the name of the log file. The default log file is http$*log$eportal. You cannot overwrite the default file.
sync_mode specifies whether the API interface supports HTTP or HTTPS. The value is set to “0” that indicates HTTP support only. HTTPS support will be considered in future releases.
comapiMode, specifies the COMAPI mode. It returns 1 on success and other values on failure.
Output Parameter
result represents failure or success of the API interface. Returns 1 in case of success. Returns other values in case of errors. For more information on error codes, see “ Error Codes of Result Parameter” in this topic.
Create HTTP Session
This method creates a new HTTP session and returns a session handle that must be passed to the subsequent API calls.
Syntax
void CREATEHTTPSESSION (HTTP_SESSION_HANDLE *sessionHandle, char *server, int *port_num,
char *base_path, int *keep_live, int *auth_type, char *credentials, int *result)Input Parameters
sessionHandle is the session handle returned by the CREATEHTTPSESSION API interface.
server is the host name that can be a domain name or an IP address.
port_num is the port number on which the ePortal service proxy listens.
base_path is the path for the Outbound Service. For example, in the Outbound Service path, the following is the base path. The rest of the path will be passed in the SENDHTTPREQUEST API.
/Api/AirportsAPIv2/U_58D8BCB7A9E6240E200CFF25,
"/Api/AirportsAPIv2/"
auth_type is for future use, and it is the authentication used between the ClearPath system and ePortal Web Cluster running ePortal service proxy on Windows. Supported type is 0 for basic.
credentials is the user name and password to authenticate with the ePortal proxy server. You can set it to a null or blank value. This will be supported in future releases.
Output Parameter
result value represents failure or success of the API interface. It returns 1 on success and 0 on failure.
Send HTTP Request
This method is used to send the COBOL payload data to the ePortal service proxy running on the Web Cluster as an HTTP request.
Syntax
void SENDHTTPREQUEST(HTTP_SESSION_HANDLE *session_handle, char *operation_id, char *req_content, int *req_content_len, int *status_code, int *result)Input Parameters
session_handle is the handle returned by the createHTTPSession().
operation_id is the openAPI operation ID.
req_content_len is the length of the request.
req_content is the buffer containing the request payload.
status_code is the error code returned as a result of failure in the HTTP client send request. It has a predefined HTTP client error values. The following are the possible error codes returned by statusCode:
Error Code | Description |
|---|---|
1 | Unknown error. |
2 | An invalid handle or possible bad pointer was passed to a function. |
3 | Buffer too small or a failure while in memory allocation. |
4 | An attempt to use an invalid socket handle was made. |
5 | Cannot send socket parameters. |
6 | Error while resolving host name. |
7 | Error while connecting to the remote server. |
8 | Socket time out error. |
9 | Error while receiving data. |
10 | Error while sending data. |
11 | Error while receiving the remote HTTP headers. |
12 | Could not find element within the header. |
13 | The headers search clue was too large for the internal API buffer. |
14 | No content length was specified for the outgoing data. The caller should specify chunking mode in the session creation. |
15 | The HTTP chunk token that was received from the server was too big and possibly wrong. |
16 | Could not authenticate with the remote host. |
17 | Could not authenticate with the remote proxy |
18 | Bad or not supported HTTP verb was passed to a function. |
19 | A function received a parameter that was too large. |
20 | The session state prevents the current function from proceeding. |
21 | Could not parse the chunk length while in chunked transfer. |
22 | Could not parse curtail elements from the URL such as the host name, HTTP prefix act. |
23 | Could not detect key elements in the received headers. |
24 | Error while attempting to resize a buffer. |
25 | Authentication schema is not supported. |
26 | The selected authentication schema does not match the server response. |
27 | An element was missing while parsing the digest authentication challenge. |
28 | Digest algorithm could be MD5 or MD5-sess. Other types are not supported. |
29 | Binding error. |
30 | TLS negotiation error. |
64 | Feature is not (yet) implemented. |
1000 | HTTP end of stream message. |
Output Parameter
result represents failure or success of the API interface. Returns 1 in case of success. Returns other values in case of errors. For more information on error codes, see “ Error Codes of Result Parameter” in this topic.
Receive HTTP Response
This method is used to read the HTTP response. The call blocks until the response is received. If there is no response until timeout, then an error is returned. The error occurs in case the send or receive fails because of network issues or other internal issues.
Syntax
void RECEIVEHTTPRESPONSE(HTTP_SESSION_HANDLE *session_handle, char *res_content,
int *res_content_len, int *status_code, char *reason, int *result)Input Parameters
session_handle is the handle returned by createHTTPSession().
res_content is the output field containing the response buffer.
res_content_len is the output field containing the length of the response buffer.
status_code is the HTTP status response code.
reason is the phrase that describes the failure of the HTTP response.
Output Parameter
result represents failure or success of the API interface. Returns 1 in case of success. Returns other values in case of errors. For more information on error codes, see “ Error Codes of Result Parameter” in this topic.
Destroy HTTP Session
This method closes the HTTP session, and frees all resources associated with this HTTP session.
Syntax
void DESTROYHTTPSESSION(HTTP_SESSION_HANDLE *session_handle, int *result)Input Parameter
session_handle is the handle returned by the createHTTPSession().
The session returns a non-zero value on success, and 0 on failure.
Output Parameter
result represents failure or success of the API interface. Returns 1 in case of success. Returns other values in case of errors. For more information on error codes, see “ Error Codes of Result Parameter” in this topic.
Note: Ensure to call the DESTROYHTTPSESSION method for each CREATEHTTPSESSION method call to avoid resource leak in the ClearPath system.
Close HTTP Library
This method closes all objects created as a part of initialization.
Syntax
void CLOSEHTTPLIBRARY (int *result)
Output Parameter
result represents failure or success of the API interface. Returns 1 in case of success. Returns other values in case of errors. For more information on error codes, see “ Error Codes of Result Parameter” in this topic.
Note: The CLOSEHTTPLITRARY method must be called before you terminate the COBOL program to avoid resource leak in the ClearPath system.
Error Codes of Result Parameter
The following are the error codes of the Result parameter.
Error Code | Description |
|---|---|
–13 | HTTP library is already initialized. Call the CLOSEHTTPLIBRARY API to close all the sessions. |
–12 | HTTP library is not initialized. Call the INITHTTPLIBRARY API to initialize the library. |
–11 | Reached maximum session allowed. |
–10 | Failed to initialize the HTTP library because the log is not created. |
–9 | Failed to set the COMPAPI mode. |
–8 | Failed to set the COMPAPI mode because a null value is passed. |
–7 | Failed to allocate max session. |
–6 | Failed to create a session handle for the session handle key. |
–5 | Failed to set verbs. |
–4 | Failed to send request. |
–3 | Failed to receive response. |
–2 | Failed to receive a status code. |
–1 | Failed to set the maximum session requested. |
0 | Failed to close the request. |
1 | Successfully initiated the library. |