Running Basic Mapping Support (BMS) applications using the CICS-MQ bridge

If a CICS® 3270 transaction uses BMS maps, the non-CICS application can use the copybooks created during map assembly to help interpret data in the vectors. If you do not have access to the copybooks, the application can analyze the data indirectly through the use of an application data structure (ADS) descriptor.

CICS Basic Mapping Support (BMS) provides a way for CICS applications to support a number of different terminal types. When the application issues an EXEC CICS SEND MAP command, BMS merges terminal-specific control data with the application data to produce a 3270 data stream that can be displayed at the terminal. When the application issues an EXEC CICS RECEIVE MAP command, application data is extracted from an inbound 3270 data stream and returned to the application.

A BMS map for a CICS application is created by assembling a set of BMS macros that define the characteristics of fields that are required for the display. One of the outputs from map assembly is a copybook that maps the display fields to an ADS. The CICS application must include the copybook in its data definitions so that it can address the fields in the map symbolically. The application data in a SEND MAP, and expected by a RECEIVE MAP, is mapped directly to the ADS in the copybook.

When the transaction runs under the CICS bridge, EXEC CICS SEND MAP and EXEC CICS RECEIVE MAP commands generate SEND MAP and RECEIVE MAP vectors in outbound messages. Instead of a 3270 data stream, these vectors contain ADSs equivalent to those used by the CICS application to address fields in the map.

The format of the ADS is unique for each map. It is described by a copybook created as part of map generation. Without this copybook it is difficult to interpret the data. Typically, non-CICS applications that use the IBM® MQ bridge include the BMS copybooks so that they can create RECEIVE MAP data and interpret SEND MAP data. However, you can write an application without the specific BMS copybooks. The format of the data is described by a structure known as the ADS descriptor (ADSD). The ADSD is added to the end of a SEND MAP vector, and it describes the format of the ADS in the vector. The ADSD contents include the names, positions, and lengths of the fields in the ADS. An ADSD can also be sent on a RECEIVE MAP request. You can use this information in conversational applications to tell the non-CICS application the structure of the ADS requested by the CICS application. The non-CICS application can then build a RECEIVE MAP vector with this ADS, and send it as a new request.

As an application programmer, you can choose whether you want to interpret vector data in messages using the ADS, the ADSD, or the ADSDL (long form of the application data structure descriptor). To interpret the ADS directly, include the copybook from map assembly in your CICS-MQ bridge application. If you want to include it, but you do not have access to the copybook or map, re-create the map with the CICS utility DFHBMSUP.

To interpret the ADS indirectly through the ADSD or ADSDL, for example if you are creating a generic application that will handle all maps, you do not have to include the copybook in your bridge application. Instead, you send control information to the bridge that tells it to include the ADSD or ADSDL in outbound SEND MAP and RECEIVE MAP request vectors as required.

If your application must run in the distributed environment, include an ADSDL in outbound SEND MAP vectors. IBM MQ can then convert data in the outbound message.

You can specify any of the following options by setting appropriate values in field MQCIH.ADSDescriptor in inbound messages:

To include an ADSD (short form of the application data structure descriptor) with the SEND MAP vector, set:
```
MQCIH.ADSDescriptor = MQCADSD_SEND
```
With this setting, you also get the short form of the ADS (application data structure) included in the SEND MAP vector.
To include an ADSD with the RECEIVE MAP vector, set:
```
MQCIH.ADSDescriptor = MQCADSD_RECV
```
The ADS is never present in an outbound RECEIVE MAP request vector.
To include an ADSDL in the SEND MAP or RECEIVE MAP vector, set:
```
MQCIH.ADSDescriptor = MQCADSD_MSGFORMAT
```
With this setting, you also get the long form of the ADS included in the SEND MAP vector.
To not include an ADS descriptor in the SEND MAP or RECEIVE MAP vector set:
```
MQCIH.ADSDescriptor = MQCADSD_NONE
```
This setting is the default. With this setting, you get the short form of the ADS included in the SEND MAP vector.

You can add together MQCADSD_* values to include the long form of the application data structure descriptor in both SEND MAP and RECEIVE MAP vectors:

MQCIH.ADSDescriptor = MQCADSD_SEND + MQCADSD_RECV + MQCADSD_MSGFORMAT

In this case, the SEND MAP vector also includes an ADS in long form.