MFS Input Message Exits

MFS input message exits are invoked automatically at run time.

MFS input message exits are specified using standard MFS syntax. To include MFS input message segment and field exits in IMS applications, follow these coding standards:

Write all input message segment and field exits in COBOL. This is different from IMS/ESA, where segment and field exits are written in Assembler.
Use the IMS/ESA naming convention as follows:
```
DFSMEnnn
```
Where nnn is the exit number expressed as a three-digit decimal number from 000 through 127. For example, for field exit number zero, use the name DFSME000.
Segment and field exits receive ASCII data. If the exit program is written for EBCDIC, it must also convert the IMS data it receives in ASCII from ASCII into EBCDIC, and convert the data from EBCDIC back to ASCII before exiting.
Be sure that segments are not modified such that they are rendered invalid. Invalid segments can cause run-time errors.
Do not use an exit to invoke IMS callable services, including storage services and control block services.

Note: If an MFS source references an exit that does not exist, the program behaves as if there were no exit coded in the MFS. Exception conditions returned by the exit are written to the server console log.

The following are run-time requirements for IMS segment and field exits:

Compile all segment and field exits.
Place the compiled code in the directory specified by the ES_IMS_EXITPATH environment variable or, alternatively, in the directory specified by the COBPATH environment variable. Enterprise Server searches for segment and field exits in that order and uses the first matching exit found.

The following describes the run-time behavior for IMS segment and field exits.

As the enterprise server is started, the names of the exits found are written to the server console log. For example, the following represents a typical server console log entry:
```
120131 13172725 4684 IMSTEST CASTM5044I IMS TM exit programs loaded: 
DFSME000.dll, DFSME127.dll 13:17:27
```
For input message field exits, the parameter list format passed to the exit has the same format as that passed by IMS/ESA.
For input message segment exits, the parameter list format passed to the exit has the same format as that passed by IMS/ESA with the exception of an extra field, DFSME-R1-RETURN, at the end of the control block. DFSME-R1-RETURN contains a user-defined error message number when the segment exit issues a return code of 12, canceling the message.
We do not support segment exit return code 16. A segment that returns a value of 16 does not send a message to the input device.

The sample segment and field exits provided are supported only for MFS source that uses the option 1 and 2 formats. All sample files are located in %PUBLIC%\Documents\Micro Focus\Enterprise Developer\Samples\Mainframe\IMS\Classic\Examples by default.

Field Exit Routine

We provide a sample program, DFSME000.cbl, containing a field exit routine. It is a COBOL implementation of the DFSME000 Assembler MFS field edit exit routine provided with the IMS/ESA product. This program contains comments further describing the use of input message field exits. The following is an excerpt from the Linkage Section of DFSME000.cbl, showing the parameter list format:

       01  FIELDEXIT-PARMS.
           05  FLDFLAG             PIC  X(01).
           05  FILLER              PIC  X(01).
           05  FLDELTH             PIC  X(01) COMP-X.
           05  FLDVECT             PIC  X(01) COMP-X.
           05  FLDLTH              PIC  X(04) COMP-X.
           05  FLDADDR             USAGE POINTER.
           05  FLDUSERID           PIC  X(08).
           05  FLDGROUPID          PIC X(08).[2]

Segment Exit Routine

We provide a sample program, DFSME127.cbl containing a segment exit routine. It is a COBOL implementation of the DFSME127 Assembler MFS segment edit exit routine provided with the IMS/ESA product. The following is an excerpt from the Linkage Section of DFSME127.cbl, showing the parameter list format:

       01  DFSME-PARM.
           05  DFSME-FLAG              PIC X(01).
           05  FILLER                  PIC X(01).
           05  FILLER                  PIC X(01).
           05  DFSME-VECTOR            PIC X(01)   COMP-X.
           05  DFSME-LTH               PIC X(04)   COMP-X.
           05  DFSME-ADDR              POINTER.
           05  DFSME-FLDEXIT-RC        PIC X(04)   COMP-X.
           05  DFSME-NEXT-MODNAME      PIC X(08).
           *>  NEXT FIELD IS IN COBOL PARM BLOCK ONLY
           05  DFSME-R1-RETURN         PIC X(04)   COMP-X.

Segment and field exits can generate trace entries that are useful for troubleshooting.

Enabling Trace

You enable the generation of segment and field exit trace entries from Enterprise Server Administration as follows:

From the Enterprise Server Administration Home page, start the enterprise server that runs your application.
Click Edit for the started enterprise server.
Click Server > Control > ES Monitor & Control.
Click Control.
Under Trace Points > Server, check exits.

Viewing Trace Entries

MSS writes trace information for Trace diagnostics A and B datasets to the files casauxta.rec and casauxtb.rec respectively. By default, both are located in the System directory, %USERPROFILE%\Documents\Micro Focus User\Enterprise Developer\WORKAREA\es-name (where es-name is the name of the enterprise server). However, you can view trace entries in real time, including C/x trace information, by clicking Display.

Trace IDs

Trace entries are generated in entry and exit pairs using six-digit hexadecimal IDs as follows:

Digits one and two are 39. These indicate that the entry is for MFS.
Digits three and four are unique to the emitting source module.
Digit five is a 0 (zero).

Digit six indicates the type of trace entry, as follows:

3	entry
4	exit
9	error

The following lists MFS trace IDs along with their significance and the variable content of each.

x'390103', Segment exit entry, exit number, vector
x'390204', Segment exit exit, return code, segment number
x'390303', Field exit entry, exit number, vector
x'390404', Field exit exit, return code, max return code
x'390509', Segment exit missing, exit number, intended vector
x'390609', Field exit missing, exit number, intended vector

Example

In this example, the first field exit is for exit number 100 and vector 100. However, Enterprise Server has failed to load the module. In this case, the error is simply recorded and processing continues. The second trace entry reveals that exit 5 was given control for vector 5. The third trace entry records the return code and the running maximum return code for the field exits at the return of exit 5. Processing continues on to the next to the last trace entry where segment exit 126 is called with vector 14. The return from the segment exit is 0 (zero) and the current segment is 1.

Note: In trace output, the trace ID includes a prepended "39 " indicating that the entry is from casmfs.dll, and digit five is shown as 8 instead of 0 (zero).

                                  Seq  Task-Nbr  ProcessID +---ID--+ hhmmsshh
mfsFldExitER(  100 )v(   100 )    654      6652      12312 39 390689 22105958
mfsFldExit(      5 )v(     5 )    655      6652      12312 39 390383 22105958
mfsFldExitRC(    0 )max(   0 )    656      6652      12312 39 390484 22105958
mfsFldExit(      5 )v(     1 )    657      6652      12312 39 390383 22105958
mfsFldExitRC(    8 )max(   0 )    658      6652      12312 39 390484 22105958
mfsFldExit(      5 )v(     1 )    659      6652      12312 39 390383 22105958
mfsFldExitRC(    0 )max(   8 )    660      6652      12312 39 390484 22105958
mfsFldExit(      5 )v(     1 )    661      6652      12312 39 390383 22105958
mfsFldExitRC(    0 )max(   8 )    662      6652      12312 39 390484 22105958
mfsSegExit(    126 )v(    14 )    663      6652      12312 39 390183 22105958
mfsSegExitRC(    0 )seg(   1 )    664      6652      12312 39 390284 22105958