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 WebAppSupport library.
Syntax
INTEGER PROCEDURE INITHTTPLIBRARY (VERSION, TIME-OUT, LOG-LEVEL, ASYNC-MODE)
Input Parameters
VERSION is used for supporting future changes to the APIs. It accepts the interface version at which the application program is running as a parameter. The minimum interface version at which the application program is running and the interface version supported by the WEBAPPSUPPORT library is returned as the value. The lowest value returned is 1. The application program must assume functionality corresponding to the returned interface version of WEBAPPSUPPORT. Each version is inclusive of a lower version. The supported versions are as follows:
4: The application can receive a –33 (Invalid Character) error result instead of –3 (Software Error) when setting a response header that contains an invalid character in the header value.
3: The HTML_ESCAPE and htmlEscape procedures also escape the three characters #,), and (.
2: The application might receive the new error results –18 (Buffer Too Small), –19 (Merge Syntax Error), and –20 (Max len Too Small) instead of –3 (Fault).
1: The original and default level.
TIME-OUT specifies the timeout value for the request to return. This option specifies the number of seconds to wait for a response from the HTTP server.
LOG-LEVEL indicates the log level tracing for this stack only. Following are the log levels:
0 = no calls traced
1 = trace all calls
2 = trace errors only
ASYNC-MODE controls whether or not requests are made synchronously or asynchronously. If OPTION_VALUE is 0, requests are made synchronously. This value is the default value. If the OPTION_VALUE is 1, requests are made asynchronously.
Output Parameter
RESULT is the return value of the method. Returns 1 if there are no internal errors. Returns other values in case of timeouts and internal errors. For information on internal error codes, refer to the WEBAPPSUPPORT Application Programming Guide (3826 5286).
This method creates a new connection to the host and returns the host and client handle depending upon the parameters SERVER, PORT-NUMBER, and BASE-PATH.
Syntax
The CREATEHTTPSESSION uses the following syntax:
INTEGER PROCEDURE CREATEHTTPSESSION (CLIENT-HANDLE, HOST-HANDLE, SERVER, PORT-NUM,
BASE-PATH, KEEP-ALIVE, AUTH-TYPE, CREDENTIALS)
Input Parameters
SERVER identifies the host name, which 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, "/Api/AirportsAPIv2/" is the base path.
KEEP-ALIVE is the keep alive timeout value in seconds.
AUTH-TYPE is the authentication used between the ClearPath system and ePortal Web Cluster running ePortal service proxy. The default value is 0. For more information on the value of the parameter AUTH-TYPE, refer to the WEBAPPSUPPORT Application Programming Guide (3826 5286).
CREDENTIALS value must be kept empty if AUTH-TYPE value is 0. For information on the value of the parameter ATTR_STRING, refer to the WEBAPPSUPPORT Application Programming Guide (3826 5286).
Output Parameters
CLIENT-HANDLE is a handle of the client object in the WEBAPPSUPPORT library.
HOST-HANDLE is a handle of the host object in the WEBAPPSUPPORT library.
RESULT is the return value of the method. Returns 1 if there are no internal errors. Returns other values in case of timeouts and internal errors. For information on internal error codes, refer to the WEBAPPSUPPORT Application Programming Guide (3826 5286).
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
INTEGER PROCEDURE SENDHTTPREQUEST (SOCKET-HANDLE, CLIENT-HANDLE,
HOST-HANDLE, REQUEST-HANDLE, OPERATION-ID, REQ-CONTENT, REQ-CONTENT-LEN)Input Parameters
CLIENT-HANDLE is a handle of the client object in the WEBAPPSUPPORT library.
HOST-HANDLE is a handle of the host object in the WEBAPPSUPPORT library.
OPERATION-ID is the route of the HTTP method in the ePortal service proxy.
REQ-CONTENT contains the request payload sent to the ePortal service proxy.
REQ-CONTENT-LEN is the length of the request payload.
Output Parameters
SOCKET-HANDLE is a handle of the socket object in the WEBAPPSUPPORT library.
REQUEST-HANDLE is a handle of the request object in the WEBAPPSUPPORT library.
RESULT is the return value of the method. Returns 1 if there are no internal errors. Returns other values in case of timeouts and internal errors. For information on internal error codes, refer to the WEBAPPSUPPORT Application Programming Guide (3826 5286).
Send HTTPS Request
This method is used to send the COBOL payload data to the ePortal service proxy running on the Web Cluster in a secure way.
Syntax
INTEGER PROCEDURE SENDHTTPSREQUEST (SOCKET-HANDLE, CLIENT-HANDLE,
HOST-HANDLE, REQUEST-HANDLE, OPERATION-ID, REQ-CONTENT, REQ-CONTENT-LEN,
CLIENT-CERT, CLIENT-KEY-CONTAINER, CLIENT-KYE-LEN, OPTION-RESULT) Input Parameters
CLIENT-HANDLE is a handle of the client object in the WEBAPPSUPPORT library.
HOST-HANDLE is a handle of the host object in the WEBAPPSUPPORT library.
OPERATION-ID is the route of the HTTP method in the ePortal service proxy.
REQ-CONTENT contains the request payload sent to ePortal service proxy.
REQ-CONTENT-LEN is the length of the request payload.
CLIENT-CER is used to set the key container value if the value is 1. It enables the key container. The default value is 0 to use the server certificate.
CLIENT-KEY-CONTAINER holds the client container key name if the client side value is 1.
CLIENT-KYE-LEN holds the client container key name length.
Output Parameters
SOCKET-HANDLE is a handle of the socket object in the WEBAPPSUPPORT library.
REQUEST-HANDLE is a handle of the request object in the WEBAPPSUPPORT library.
OPTION-RESULT is the result returned from the SockLib_SetSockOpt function.
RESULT is the return value of the method. Returns 1 if there are no internal errors. Returns other values in case of timeouts and internal errors.
For information on the internal error codes, refer to the WEBAPPSUPPORT Application Programming Guide (3826 5286).
Receive HTTP Response
This method is used to read the HTTP response. If the library is initialized to send and receive the message in an asynchronous mode of communication, call this message in a loop until the message returns a result other than -83.
Syntax
INTEGER PROCEDURE RECEIVEHTTPRESPONSE (SOCKET-HANDLE, REQUEST-HANDLE, RES-CONTENT,
RES-CONTENT-LEN, STATUS-CODE, REASON)
Input Parameters
SOCKET-HANDLE is a handle of the socket object in the WEBAPPSUPPORT library.
REQUEST-HANDLE is a handle of the request object in the WEBAPPSUPPORT library.
Output Parameters
RES-CONTENT contains the COBOL payload, which is part of the HTTP response from ePortal service proxy.
RES-CONTENT-LEN contains the response content length.
STATUS-CODE is the HTTP status response code returns from the ePortal service proxy.
REASON is the reason phrase of the HTTP status code.
RESULT is the return value of the method. Returns 1 if there are no internal errors. Returns other values in case of timeouts and internal errors. For information on internal error codes, refer to the WEBAPPSUPPORT Application Programming Guide (3826 5286).
Destroy HTTP Session
This method releases the socket and request objects in the WEBAPPSUPPORT library.
Syntax
INTEGER DESTROYHTTPSESSION (SOCKET-HANDLE, REQUEST-HANDLE)Input Parameters
SOCKET-HANDLE is a handle of the socket object in the WEBAPPSUPPORT library.
REQUEST-HANDLE is a handle of the request object in the WEBAPPSUPPORT library.
Output Parameter
RESULT is the return value of the method. Returns 1 if there are no internal errors. Returns other values in case of timeouts and internal errors. For information on internal error codes, refer to the WEBAPPSUPPORT Application Programming Guide (3826 5286).
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 host and client objects created as a part of initialization.
Syntax
INTEGER CLOSEHTTPLIBRARY (CLIENT-HANDLE, HOST-HANDLE)Input Parameters
CLIENT-HANDLE is a handle of the client object in the WEBAPPSUPPORT library.
HOST-HANDLE is a handle of the host object in the WEBAPPSUPPORT library.
Output Parameter
RESULT is the return value of the method. Returns 1 if there are no internal errors. Returns other values in case of timeouts and internal errors. For information on internal error codes, refer to the WEBAPPSUPPORT Application Programming Guide (3826 5286).
Note: The CLOSEHTTPLITRARY method must be called before you terminate the COBOL program to avoid resource leak in the ClearPath system.