The event exit HTTP is used to enhance existing program units for the calls of HTTP clients, without having to change the program units themselves.
Messages from and to HTTP clients are usually built in a different format than expected and processed by existing program units. The task of the HTTP exit is to convert the input messages from HTTP clients into the data structure expected of a program unit and to reformat output messages of a program unit in such a way that they are readable by an HTTP client.
In order to be able to keep the processing logic of an HTTP exit program simple, a separate HTTP exit program can be assigned to each TAC via the generation.
The HTTP event exit is called when the input message is read from and before the HTTP response is sent to an HTTP client.
The HTTP exit is invoked for an input message only once, at the time of the first MGET call, and must process the entire input message and build the message segments for the first and all subsequent MGET calls of the program unit. For this purpose, the exit can use the kcHttpGet functions to access all components of an HTTP request, for example, the message body of the HTTP request using the function kcHttpGetReqMsgBody. The function kcHttpPutMgetMsg can be used to provide the message reformatted for the program unit. The exit also has the option of using the structure kcHttpExitMsgInfo to split the input message into message segments. This means that the exit determines the number and length of the message segments that the program unit can read with MGET.
Before sending an HTTP response, the HTTP exit is called to process the output message. The exit then can use the function kcHttpGetMputMsg to read the message (parts) passed to UTM by the program unit with MPUT calls and use the function kcHttpPutRspMsgBody to specify the message body of the HTTP response. The splitting of the output message created by the program unit with MPUT calls is passed to the exit in the structure kcHttpExitMsgInfo, that is, it receives information about the number and length of the message parts.
The HTTP exit can also supply the HTTP status line with the function kcHttpPutStatus and HTTP header fields for the HTTP response with the function kcHttpPutHeader. The process flow is outlined in the following figure.
Figure: Message handling flow through an HTTP event exit
Programming notes
- The HTTP event exit must be implemented in the C programming language.
- The event exit HTTP must not use KDCS calls.
Generation notes
- Each event exit HTTP requires a PROGRAM statement.
- The statement HTTP-DESCRIPTOR defines a link from the URL of an HTTP request to an HTTP exit program as well as to a TAC of the application and thus a program unit.
HTTP-DESCRIPTOR <http-descriptor-name>
[, BCAMAPPL = <bcamappl> | *ALL]
[, CONVERT-TEXT = *YES | *NO]
[, HTTP-EXIT = <program-name> | *NONE | *SYSTEM]
[, PATH = C'<path>' | C'/*']
, TAC = <tac>
[, USER-AUTH = *NONE | *BASIC]
extern void <program-name>(kcHttpExitPar *);
typedef enum
{ KC_UTM_HTTP_VERSION = 1 /* current version of UTM HTTP interface */
, KC_UTM_HTTP_VERSION_1 = 1 /* UTM HTTP interface version of UTM V07.0A */
, KC_UTM_HTTP_VERSION_MAX = INT_MAX
} kc_http_version;
typedef struct { /* structure for message */
int nrMsgParts; /* number of message parts */
short lthMsgParts[254]; /* length of message parts */
} kcHttpExitMsgInfo;
typedef struct { /* parameter structure for HTTP exit */
kc_http_version utmHttpVersion; /* version of UTM-HTTP interface */
char ioIndicator; /* 'I' Input; 'O' Output */
unsigned char retcode; /* ok: 0; nok: 1-255 */
struct kcHttpInfo httpInfo; /* http info from INIT PU */
void * pCa; /* ptr to communication area */
kcHttpExitMsgInfo * pStructureInfo; /* ptr to message structure info */
} kcHttpExitPar;
The fields of the data structure kcHttpExitMsgInfo have the following meaning:
nrMsgParts | Number of message segments |
lthMsgParts[254] | Array with lengths of maximun 254 message segments |
The fields of the data structure kcHttpExitPar have the following meaning:
utmHttpVersion | Version of the UTM-HTTP interface |
ioIndicator | Indicator whether the event exit HTTP was called to handle the input message or the output message:'I' Input'O' Output |
retcode | In this field, the event exit HTTP returns a return code. If the field has a value other than 0, the service is terminated with PEND ER, whereby the value of the field is converted into the secondary KDCS return code (the value 26 would result, for example, in the secondary KDCS return code HX1A). |
httpInfo | In this structure, UTM passes the HTTP information that is returned to a program unit in the KDCS call INIT PU to the event exit HTTP. |
pCa | Pointer to KB |
pStructureInfo | Pointer to the structure information of the message. When calling the event exit HTTP while reading the message with MGET, the exit must supply the data structure. When calling before sending the HTTP response, UTM provides the exit in the data structure with the number and length of message segements passed to UTM by the program unit with MPUT:
|