IMS Connectivity in an On Demand Environment: A Practical Guide to IMS Connectivity

116 IMS Connectivity in an On Demand Environment: A Practical Guide to IMS Connectivity

9.1 IMS Connect components and user exits

IMS Connect itself has many functions to perform and is broken down into various

components (see Figure 9-1). The compartmentalization of the different functions provides

the platform to divide IMS Connect into the different components and keep the functions

isolated and modular. Because IMS Connect performs several distinct communication

functions, TCP/IP client communication, IMS OTMA communication, and IMSplex

communication, the exits are involved in all instances, because message manipulation is a

factor in both directions.

Figure 9-1 User exits are invoked on incoming and outgoing messages

9.2 IMS Connect communication with user exits

The purpose of the user exits in IMS Connect is to format and possibly modify the incoming or

outgoing messages.

Commonalities among all user exits

Any user exit that is associated with an input message and needs to be invoked by IMS

Connect to process the message must be defined in the EXIT= parameter in the HWSCFG

configuration file. A maximum of 254 exits can be defined here.

USER MESSAGE EXITS

Chapter 9. IMS Connect user exit support 117

With the exception of HWSCSLO0 and HWSCSLO1, which are used to support the IMS

Control Center, IMS Connect invokes the defined user exits in the following instances:

 During IMS Connect initialization time.

 After receiving the complete message from the client and prior to passing it to OTMA.

 After receiving control back from the user exit during the input phase and if IMS Connect

detects an error in the output buffer setup by the user exit.

 After receiving the IMS response from OTMA and prior to passing the output message to

the client.

 During IMS Connect termination.

IMS Connect does

not invoke a different exit for each of the previous instances, but expects

an exit to be able to process each of these phases. This is dictated by an option specified in

the parameter list passed to the exit. These options are:

 INIT (initialization)

 READ (input phase)

 EXER (error on input phase)

 XMIT (output phase)

 TERM (termination)

HWSCSLO0 and HWSCSLO1 are a bit different, because they deal with IMSplex

communication. These two exits are provided by IBM as object code only (OCO) and cannot

be customized, so we do not provide more information about these exits in this chapter.

All exits are expected to function in a reentered environment and are given control in key 7

and in the addressing mode with which the exit was linked. The parameter list passed to the

exit is always in storage located above the 16 MB virtual storage line, so all exits should be

able to perform 31-bit addressing at the minimum, even if the author of such an exit wants to

restrict the exits location to RMODE 24.

IMS Connect provides a 1 KB buffer work area with each invocation of an exit. The purpose of

the work buffer is to ensure that the reentered environment is maintained and to provide a

unique storage area where registers can be saved. Although the general purpose register 13

points to an IMS Connect save area at entry to an exit, an automatically pre-allocated

follow-on save area is not provided. This means that the exit must provide its own save area

in the 1 KB work buffer and backchain this unique save area to the IMS Connect save area.

The exit can, on entry to the exit, save the status of the general purpose registers in the IMS

Connect save area, as pointed to by general purpose register 13, and subsequently restore

them from there when the exit returns control to IMS Connect. IMS Connect supports

assembler-written user exits only. Table 9-1 shows the common register contents on entry to

all user exits.

Table 9-1 Register contents on entry to user exits (all options)

Restriction: Do not define the IBM-supplied exits (HWSUINIT and HWSJAVA0) in the

HWSCFG configuration file. IMS Connect automatically loads the HWSJAVA0 exit, and

HWSUINIT is an IMS Connect exit but is not a user message exit.

Register Contents on entry

1 Pointer to parmlist, as mapped by HWSEXPRM.

13 IMS Connect save area.

14 Return address of IMS Connect.