Enterprise Server supports the use of MFS input message field and segment exits in COBOL, and enables you to edit MFS segment and field data from a COBOL program. This is an emulation of a mainframe feature.
- Invocation
- MFS input message exits are invoked automatically at run time.
- Coding Requirements
- 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 runtime 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.
- Run-time Requirements
- 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.
- Run-time Behavior
- The following describes the run-time behavior for IMS segment and field exits.
- Examples
- 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
(Windows) or
$COBDIR/demo/ims/examples
(UNIX)
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.
- 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.
- Troubleshooting
- 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:
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
