The XBMIN exit allows you to intercept a RECEIVE MAP request after BMS has successfully processed the request. The XBMOUT exit allows you to intercept a SEND MAP request after BMS has successfully processed the request; or, if cumulative mapping is in progress, on completion of each page of output.
The XBMIN exit is called, if enabled, when all the following are true:
Using XBMIN, you can:
The XBMOUT exit is called, if enabled, when all the following are true:
Using XBMOUT, you can:
Both exits are passed four exit-specific parameters:
CICS® supplies a sample program, DFH$BMXT, that shows how mapped input and output data can be modified with reference to the information provided in the "field element" table. A copybook, DFHXBMDS, is also supplied. This copybook is a DSECT which defines the structure of the field element.
The field element table contains one or more elements which provide information about each "field of interest" passed to the exit. A "field of interest" is a field which has been defined as VALIDN=USEREXIT in the map source file used to create the mapset referenced in the mapping operation.
Each field element has the following structure:
In the XBMIN exit, BMXDATA points into a work area which BMS has obtained for input mapping purposes. When the exit returns control, this work area is copied to the application data structure associated with this map.
In the XBMOUT exit, BMXDATA points into a terminal input/output area (TIOA) in which BMS has generated an output datastream. When the exit returns control, the TIOA is disposed of in accordance with the disposition of the TERMINAL (the default), SET, or PAGING option specified on the SEND MAP request.
MYMAP DFHMDI SIZE=(12,40)
and a field in this map is defined
as
FLDA DFHMDF POS=(5,1)
the offset of this field (relative to
zero) is 160 in decimal notation. In this example, BMXMAPOF would contain
the value X'00A0'.
This section contains some considerations specific to the XBMIN exit.
The actual data length (in BMXACTLN) may be less than the length defined in the map (in BMXMAPLN). This could happen, for example, if a terminal operator does not completely fill a data entry field. In this case, BMS will have right- or left-justified the data in the field and padded the field with blank or zero characters. This justification and padding occurs before the exit is invoked. Your exit program can, by checking the bit settings in the BMXFDFB field, determine how BMS performed justification and padding for the field.
The actual data length (in BMXACTLN) may be greater than the length defined in the map (in BMXMAPLN). This could happen, for example, if a map contains an unprotected field which is not immediately followed by another field. This allows the terminal operator to enter data past the end of the field. When this occurs, the data field is truncated by BMS according to the length defined for the field in the map. However, BMXACTLN contains the length of data found in the inbound datastream.
When modifying data in the XBMIN exit, the safest method is to use the length provided in BMXMAPLN, but to ensure that any pad characters added by BMS are preserved.
BMXATTR must be ignored in the XBMIN exit; it always contains binary zeroes.
This section contains some considerations specific to the XBMOUT exit.
The actual data length (in BMXACTLN) may be less than the length defined in the map (in BMXMAPLN). This occurs due to the compression of trailing nulls performed by BMS for each output field.
The actual length of data cannot be changed in the exit program. The exit is invoked after the output datastream has been generated; consequently, an attempt to alter the data length could result in an invalid datastream. Therefore, if an XBMOUT exit program modifies data, it must do so with reference to the length value in BMXACTLN.
BMXDATA may contain a null value. This can be caused by a SEND MAP request with the MAPONLY option when the map has fields without default data; this causes BMS to send an attribute sequence for the field but no data.
BMXATTR may contain a null value. This can be caused by a SEND MAP request with the DATAONLY option, when the application is updating the data in a field and not the attributes.
When an application is performing cumulative mapping--that is, issuing a sequence of SEND MAP commands with the ACCUM option--BMS builds composite display in which a single page of output might be constructed from multiple SEND MAP requests. When cumulative mapping occurs, the XBMOUT exit is called when a page has been built, not as each SEND MAP request is processed.
When an application builds a routing message--for example, it issues a ROUTE command followed by one or more SEND MAP commands with the SET or PAGING option specified--the XBMOUT exit is invoked in the same way as for a non-routed mapping request.
However, the UEPBMTCT parameter is passed as a null value for a routed message. This is because a routed message may be destined for multiple devices, and BMS has optimized the features supported by the devices targeted by the routed message. When processing a routed message in the XBMOUT exit, referencing the TCTTE for any of these devices would probably not be relevant.