The HTTP Server User Exit

The single HTTP server user exit is given control at strategic points in the processing of each HTTP request to enable an installation to control and manipulate the processing of HTTP requests.

This document covers the following topics:

• Installation

• General Interface

• Exit Points

Installation

The HTTP server user exit must be a load module called HAANUXIT and must be available for loading by the HTTP server.

It is loaded when the HTTP server is initialized and becomes part of the HTTP server nucleus. It must be reentrant and may reside above the 16-megabyte line.

The member HAANUXIT on the HTPvrs.SRCE dataset is a sample user exit that implements each of the user exit points currently taken but simply returns normally to the user exit point. Thus, the user exit as delivered may be compiled and will not affect the normal operation of the HTTP server.

A message is issued during the server initialization process when the module is found and loaded. If this message is not issued, the exit is not operational.

General Interface

The exit is called with the following registers:

Exit Parameter List

On entry to the user exit, register 1 points to a parameter list that varies depending on the call.

The parameters passed to each exit point are documented in the appropriate section; however, the first parameter is always a pointer to the UXIT control block, which contains information about the HTTP server itself and the exit point for which the user exit has been called.

A DSECT to map this control block may be generated by the following statement in the Assembler program:

MYUXIT   HMANUXIT DSECT=YES

The parameter list may be addressed using the following statements assuming R1 contains what it contained when the module was entered:

      L      Rx,0(,R1)             Rx -> UXIT control block
      USING  UXIT,Rx               Address UXIT area

The following table describes the field names and their contents, which are relevant for all exit points. The UXIT control block may also contain data relevant only to specific exit calls. Any fields of additional significance are documented in the description of the exit point itself.

The HAANUXIT source member on the HTPvrs.SRCE dataset shows how the UXIT parameter list may be addressed and processed. It should be used as the basis for any exit written at an installation.

Entry/Exit Processing

The HTTP server has been written using a standard entry/exit mechanism to provide consistent standards within the server and to centralize much of the common coding used during entry/exit processing.

Two macros are used:

• HMANENT for entry processing; and

• HMANEXIT for exit processing.

HMANENT Macro for Entry Processing

The HMANENT macro takes a number of parameters; however, the important ones from the exit's point of view are the WRKL and WRKD parameters.

• WRKL specifies the length of the savearea and work area that should be allocated for the exit.

• WRKD specifies the name of the working storage DSECT that will be used to address the area.

  When control is passed to the code following the HMANENT macro expansion, the following registers are set:

WORK     DSECT
WORKSAVE DS    18F

         Exit work fields here

WORKL    EQU   *-WORK

HMANEXIT Macro for Exit Processing

The HMANEXIT macro returns control to the calling program, optionally returning values in registers 15, 0, and 1. For HAANUXIT, the only relevant register in this case is 15, which is used as a return code.

Note that the HMANEXIT macro must get control with registers 12 and 13 containing the same values as were set up by the HMANENT macro.

Exit Points

For each exit point, the following subsections will be documented:

Initialization

Purpose

The initialization exit point is designed to provide an opportunity for the exit to initialize its own environment prior to any subsequent calls.

Parameters

Return Codes / Return Values

Termination

Purpose

The termination entry point has been designed to provide the exit with a point at which it should clean up after any given request.

Parameters

Return Codes / Return Values

URL Processing

Purpose

The URL processing exit point is taken immediately before the URL as provided by the user is processed. The installation can then

• modify or replace the URL all together and cause the HTTP server to use a different URL to service the request. This may be useful when URL names change and a cut-over period is required to handle old and new requests.

• reject access to the URL, which causes the HTTP server to return a 'permission denied' response to the request.

Parameters

Return Codes / Return Values

Output Processing

Purpose

The output processing exit point that is taken one or more times as output is built to be sent in response to the request. How often the exit is taken depends totally on what the URL represents and how large the output object is.

This exit point may be used to

• control translation of the output data if the basic facilities provided by the HTTP server are not adequate. This exit can effectively replace the HTTP server translation processing and do the translation itself.

• insert data into the output data stream. This is useful for inserting HTTP headers for any given request; however, users must be careful that the resulting output is still a valid HTTP request. The HTTP server does not control what is being sent in this case and therefore the user is responsible for ensuring that it is correct.

• prevent certain data from being sent.

Parameters

Return Codes / Return Values

Input Processing

Purpose

Called when input is being processed for an incoming HTTP request, the input processing exit point may be used to

• translate incoming content in a way different from the basic translation services provided by the HTTP server.

• track or report identified HTTP headers or requests identified by certain requests.

Parameters

Return Codes / Return Values

Accept Processing

Purpose

The accept processing exit point is taken immediately after a client has connected to the HTTP server. It may be used to control which IP addresses may connect with the HTTP server

Parameters

Return Codes / Return Values