Basic Mapping Support exits XBMIN and XBMOUT

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:

  1. The address of the TCTTE associated with the mapping request
  2. The address of the system EIB associated with the task issuing the mapping request
  3. The address of a halfword binary count of the number of elements in the field element table
  4. The address of the field element table.
Sample program, DFH$BMXT

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.

Exit XBMIN

When invoked
After BMS has successfully processed an input mapping operation.
Exit-specific parameters
UEPBMTCT
Address of the TCTTE associated with the mapping request.
UEPEXECB
Address of the system EIB associated with the task.
UEPBMCNT
Address of the halfword binary number of "field elements" in the field element table.
UEPBMTAB
Address of the field element table.
Return codes
UERCNORM
Continue processing.
UERCPURG
Task purged during XPI call.
XPI calls
All can be used.

Exit XBMOUT

When invoked
After BMS has successfully completed a page of output during an output mapping operation.
Exit-specific parameters
UEPBMTCT
Address of the TCTTE associated with the mapping request.
UEPEXECB
Address of the system EIB associated with the task.
UEPBMCNT
Address of the halfword binary number of "field elements" in the field element table.
UEPBMTAB
Address of the field element table.
Return codes
UERCNORM
Continue processing.
UERCPURG
Task purged during XPI call.
XPI calls
All can be used.

The field element table structure

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:

BMXMAPST
is an 8-byte area which contains the name of the mapset associated with this field. If terminal or alternate suffixes are used with mapset names in your CICS installation, the mapset name may have a suffix appended to the name specified in the mapping request.
BMXMAP
is a 7-byte area which contains the name of the map associated with this field.
BMXFDFB
is a one-byte field copied from the field specification in the map load module. It contains indicators as follows:
X'80'
CASE=MIXED
X'40'
Group field entry
X'20'
Group field descriptor
X'10'
ATTRB=DET
X'08'
JUSTIFY=ZERO
X'04'
JUSTIFY=RIGHT
X'02'
INITIAL,XINIT, or GINIT specified
X'01'
Named field (DSECT entry exists)
BMXMAPLN
is a halfword binary value which contains the field length defined in the LENGTH option of the DFHMDF macro.
BMXACTLN
is a halfword binary value which contains the actual length of the data received or transmitted in this field.
BMXDATA
is the address of the field data.

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.

BMXATTR
is only relevant in the XBMOUT exit. It is the address of the attributes (if any) which BMS has placed in the output datastream preceding this field.
BMXMAPOF
is the offset of the field in the map. For example, if a map is defined as
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'.
BMXBUF
is the offset of the field in the device buffer. Usually--that is, when the map dimensions are the same as the current screensize in use by the device--this value will be the same as that of BMXMAPOF. However, using the example given in the BMXMAPOF description above, if MYMAP is sent to a device currently using a 24 by 80 screensize, the offset of the field in the device buffer (again relative to zero) is 320 in decimal notation. In this example, BMXBUF would contain the value X'0140'.

Programming the XBMIN exit

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.

Programming the XBMOUT exit

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.

Cumulative mapping operations

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.

Message routing

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.

Related concepts
Overview -- what is a global user exit?
Overview of the XPI
Global user exit XPI examples, showing the use of storage
Related tasks
Writing global user exit programs
Making an XPI call
Related reference
List of global user exit points
The XPI functions
[[ Contents Previous Page | Next Page Index ]]