Chapter 13: User Exits for Request Handlers

This chapter describes how to write user exit programs that allow you to customize the behavior of the Micro Focus MFRHSOAP request handler.

Introduction

The Micro Focus MFRHSOAP request handler provides a number of user exit points, enabling you to supply a user exit program that can perform additional processing of input and output parameters.

You can also provide a user exit program for use with a custom request handler, if you find this approach offers advantages over including all the code you need in the request handler itself.

You specify a user exit program and the exit points at which it is to be invoked by the request handler at run time as part of the interface mapping process, described in the chapter COBOL Web Services with the Interface Mapping Toolkit in your Web Services and COBOL book. This information is built into the interface definition table (IDT) associated with the mapped service.

User Exit Points Provided

Figure 13-1 shows the interaction between request handlers, the application container and the run-time interface mapper.

Figure 13-1: Request Handler Exit Points

The user exit points are indicated by squares numbered from 1 through 9. The table below gives the name and purpose of the exit points.

Number	Name	Description
1	External data value modification – input parameter	Enables you to modify the external data value specified in a client request before the request handler’s default mapping for the parameter occurs. This exit point is invoked for each external-to-internal input parameter mapping that is specified in the IDT.
2	Internal data value modification – input parameter	Enables you to override the internal data value created by the request handler’s default mapping for a parameter. This exit point is invoked for each external-to-internal input parameter mapping that is specified in the IDT.
3	Unmapped named external input parameter	Enables you to provide processing of any input parameters that do not have associated input parameter mappings defined in the IDT. This exit point is invoked for each unmapped named input parameter.
4	End of input request processing	Enables you to set up parameter values other than the external parameters specified in the client request. It also provides the opportunity for any resources allocated in exit points 1 through 3 to be released.
5	Start of response processing	Enables you to bypass completely the default mapping used to build a client response. The exit program is responsible for the creation of the response that will be sent back to the client by the application container.
6	Internal data value modification – output parameter	Enables you to modify the internal data value as created by the user application before the request handler’s default mapping for the parameter occurs. This exit point is invoked for each internal-to-external output parameter mapping that is specified in the IDT.
7	External data value modification – output parameter	Enables you to override the external data value created by the request handler’s default mapping for a parameter. This exit point is invoked for each internal-to-external output parameter mapping that is specified in the IDT.
8	End of response processing	Enables you to modify the response generated by the default mapping.
9	End of request processing	Enables you to release any resources that were allocated in exit points 1 through 8.

Structure Definitions and Type Definitions

To help COBOL and C programmers, we provide a COBOL copybook (cbltypes.cpy) and a C header file (svext.h) with Enterprise Server. These files contain definitions of the structures and interfaces that you will require to write user exits and custom request handlers.

One of these is the IDP_EXIT_INFO structure, which is used for passing the information required by the exit routines for processing at each exit point. A pointer to this structure, together with the exit point identifier, is passed to each exit routine. The information passed and returned depends on the exit point.

For definitions of the information passed at each exit point see the reference Help topics Exit Points.

For definitions of support functions see the reference Help topics Functions.

For structure definitions see the reference Help topics Structures.

Linkage Section Field Names

Several of the exit points are provided so that you can manipulate an input or output field. The way you pass a field name in the exit interface depends on how it is defined in the Linkage Section of the program providing the service. There are two possibilities:

The item is defined at level 01. In this case, the field name passed in the exit interface is the same as the field name in the Linkage Section
The item is defined at a level subordinate to level 01. In this case, the field name passed in the exit interface is composed of the field name prefixed by a concatenation of the names of the group items that it belongs to. The individual names are separated by "." characters. For example: field "e" in the record below would be uniquely identified as "a.b.c.e".
```
01 a.
   03 b.
      05 c.
         07 d     pic x(4).
         07 e     pic x(4).
         07 f     pic x(4).
      05 g        pic x(4).
   03 h           pic x(4).
```
If the field itself, or any of the group items that it belongs to, are tables, the required table index is specified by appending “(n)” to the name, where n indicates the position of the field or item in the table. For example, field “f” of the fourth element of “c” in the record below would be uniquely identified as “a.b.c(4).f”:
```
01 a.
   03 b.
      05 c occurs 10.
         07 d     pic x(4).
         07 e     pic x(4).
         07 f     pic x(4).
      05 g        pic x(4).
   03 h           pic x(4).
```

Deploying a User Exit Program

To deploy a user exit program, copy it into the Enterprise Server bin directory, at install-dir\base\bin if Enterprise Server is installed as part of Net Express, or install-dir\bin if Enterprise Server is installed standalone.