Der Event-Exit HTTP dient dazu bestehende Teilprogramme für die Aufrufe von HTTP-Clients zu ertüchtigen, ohne dass dafür die Teilprogramme selbst geändert werden müssen.
Nachrichten von und an HTTP-Clients sind normalerweise in einem anderen Format aufgebaut, als sie von bestehenden Teilprogrammen erwartet und verarbeitet werden können. Aufgabe des HTTP-Exits ist es, die Eingabenachrichten von HTTP-Clients in die von einem Teilprogramm erwartete Datenstruktur umzusetzen und in gleicher Weise Ausgabenachrichten eines Teilprogramms so umzuformatieren, dass diese für einen HTTP-Client lesbar sind.
Um die Verarbeitungslogik eines HTTP-Exit-Programms einfach halten zu können, kann über die Generierung jedem TAC ein eigenes HTTP-Exit-Programm zugeordnet werden.
Der Event-Exit HTTP wird beim Lesen der Eingabe-Nachricht von einem sowie vor dem Senden der HTTP-Response an einen HTTP-Client aufgerufen.
Der HTTP-Exit wird für eine Eingabenachricht nur einmal, zum Zeitpunkt des ersten MGET-Aufrufs aufgerufen und muss dabei die gesamte Eingabenachricht bearbeiten und die Nachrichtenteile für den ersten und alle folgenden MGET-Aufrufe des Teilprogramms erzeugen. Dazu kann der Exit mit den kcHttpGet-Funktionen auf alle Bestandteile eines HTTP-Requests zugreifen z.B. mit der Funktion kcHttpGetReqMsgBody auf den Message Body des HTTP Requests. Mit der Funktion kcHttpPutMgetMsg kann die für das Teilprogramm umformatierte Nachricht bereitgestellt werden. Der Exit hat darüberhinaus die Möglichkeit mittels der Struktur kcHttpExitMsgInfo die Aufteilung der Eingabenachricht in Nachrichtenteile festzulegen. D.h. der Exit bestimmt damit die Anzahl und die Länge der Nachrichtenteile, die das Teilprogramm mit MGET lesen kann.
Vor dem Senden einer HTTP-Response wird der HTTP-Exit zur Bearbeitung der Ausgabenachricht aufgerufen. Der Exit hat dann die Möglichkeit mit der Funktion kcHttpGetMputMsg die vom Teilprogramm mit MPUT-Aufrufen an UTM übergebene(n) Nachricht(enteile) zu lesen und mit der Funktion kcHttpPutRspMsgBody den Message Body der HTTP-Response festzulegen. Dazu wird dem Exit in der Struktur kcHttpExitMsgInfo die Aufteilung der vom Teilprogramm mit MPUT-Aufrufen erzeugten Ausgabenachricht übergeben, d.h. er erhält Information über die Anzahl und die Länge der Nachrichtenteile.
Weiterhin kann der HTTP-Exit mit der Funktion kcHttpPutStatus die HTTP-Status Line und mit der Funktion kcHttpPutHeader HTTP-Header-Felder für die HTTP-Response versorgen. Im folgenden Bild ist der Ablauf skizziert.
Bild: Ablauf der Nachrichtenbehandlung durch einen Event-Exit HTTP
Programmierhinweise
- Der Event-Exit HTTP muss in der Programmiersprache C implementiert werden.
- Der Event-Exit HTTP darf keine KDCS-Aufrufe verwenden.
Generierungshinweise
- Für jeden Event-Exit HTTP ist eine PROGRAM-Anweisung nötig.
- Mit der Anweisung HTTP-DESCRIPTOR wird eine Verknüpfung von der URL eines HTTP-Requests zu einem HTTP-Exit-Programm, sowie zu einem TAC der Anwendung und damit einem Teilprogramm festgelegt.
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;
Die Felder der Datenstruktur kcHttpExitMsgInfo haben folgende Bedeutung:
nrMsgParts | Anzahl der Nachrichtenteile |
lthMsgParts[254] | Feld mit den Längen der maximal 254 Nachrichtenteilen |
Die Felder der Datenstruktur kcHttpExitPar haben folgende Bedeutung:
utmHttpVersion | Version der UTM-HTTP-Schnittstelle |
ioIndicator | Indikator, ob der Event-Exit HTTP für die Behandlung der Eingabe-Nachricht oder der Ausgabe-Nachricht aufgerufen wurde:'I' Input 'O' Output |
retcode | In diesem Feld gibt der Event-Exit HTTP einen Returncode zurück. Hat das Feld einen Wert ungleich 0, so wird der Vorgang mit PEND ER beendet, wobei der Wert des Feldes in den sekundären KDCS-Returncode umgesetzt wird (der Wert 26 würde z.B. den sekundären KDCS-Returncode HX1A ergeben). |
httpInfo | In dieser Struktur übergibt UTM die HTTP-Information, die einem Teilprogramm beim KDCS-Aufruf INIT PU zurückgegeben wird, an den Event-Exit HTTP. |
pCa | Adresse des KB |
pStructureInfo
| Adresse der Strukturinformation der Nachricht. Beim Aufruf des Event-Exit HTTP beim Lesen der Nachricht mit MGET muss der Exit die Datenstruktur versorgen. Beim Aufruf vor dem Senden der HTTP Response stellt UTM dem Exit in der Datenstruktur die Anzahl und Länge der vom Teilprogramm mit MPUT an UTM übergebenen Nachrichtenteile zur Verfügung.
|