Assembling the map

Before you start coding, you must assemble and link edit your map set. You usually have to assemble twice, to create the map set in two different forms. The TYPE option in the DFHMSD macro tells the assembler the form to produce in any particular assembly.

Physical and symbolic map sets

A TYPE=MAP assembly, followed by a link-edit, produces a load module called the physical map set. The physical map set contains format information in encoded form. CICS® uses it at execution time for constant fields and to determine how to merge in the variable data from the program. The physical map set normally is stored in the same library as your application programs, and it requires a MAPSET resource definition within CICS, just as a program requires a PROGRAM resource definition.

The output of a TYPE=DSECT assembly is a series of data structures, collectively called the symbolic map set, coded in the source language specified in the LANG option. There is a structure for each map used for input, called the symbolic input map, and one for each map used for output, called the symbolic output map.

Symbolic map sets are used at compile (assembly) time. You copy them into your program, and they allow you to refer to the fields in the maps by name and to pass the variable data in the form dictated by the physical map set. We have already shown you an example of a symbolic output map in COBOL (see Figure 104) and used it in the example code. Symbolic map sets are usually stored in the library your installation defines for source code that gets copied into programs. Member names are usually the same as the map set names, but they need not be.

You need the TYPE=DSECT assembly before you compile or assemble your program. You can defer the TYPE=MAP assembly and link-edit until you are ready to test, because the physical map set is not used until execution time. However, because you must do both eventually, many installations provide a catalogued procedure to do this automatically; the procedure copies the source file for the map set and processes it once using TYPE=MAP and again using TYPE=DSECT. You also can use the SYSPARM option in your assembler procedure to override the TYPE value in a particular assembly. See the Assembler H Version 2 Application Programming Language Reference manual for a description of SYSPARM in connection with map assemblies, and Installing map sets and partition sets for more information about assembling maps.

Notes:
  1. The fact that symbolic map sets are coded in a specific language does not prevent you from using the same map in programs coded in different languages. You simply assemble with TYPE=DSECT for each LANG value you need, taking care to store the outputs in different libraries or under different names. The LANG value does not affect the TYPE=MAP assembly, which need be done only once.
  2. If you modify an existing map in a way that affects the symbolic map, you must recompile (reassemble) any programs using it, so that the compilation uses the symbolic structure that corresponds to the new physical structure. Changes to unnamed map fields do not affect the symbolic map, but addition, deletion, rearrangement, and length changes of named fields do. (Rearrangement refers to the DFHMDF macros; the order of the fields on the screen does not affect the symbolic map, although it is more efficient to have the DFHMDF macros in same order as the fields on the screen.) So make changes to the DSATTS option in the map definition--this option states the extended attributes you may want to change by program. It is always safest to recompile, of course.

The SDF II alternative

None of these assembly or link-edit steps is required if you use the IBM® licensed program Screen Definition Facility II. SDF II produces creates both the symbolic map set and the physical map set in the final step of the interactive map creation process. SDF II can run under either MVS™ (Program 5665-366) or VM (5664-307). Refer to the Screen Definition Facility II Primer for CICS/BMS Programs, the Screen Definition Facility II General Introduction Part 1, and the Screen Definition Facility II General Introduction Part 2. More information can be found in the Screen Definition Facility II General Information and Screen Definition Facility II Primer for CICS/BMS Programs.

Grouping maps into map sets

Because they are assembled together, all of the physical maps in a map set constitute a single load module. BMS gains access to all of them with a single load request, issued on the first use of the map set in the task. No further loads are required unless you request a map in a different set, in which case BMS releases the old map set and loads the new one. If you go back to the first map set subsequently, it gets loaded again. Loading and deleting does not necessarily involve I/O, but you should consider the path length when grouping your maps into map sets. Generally, if maps are used together, they should be in the same map set; those not used together should be in different map sets.

The limit to the number of maps in a set is 9 998, but you should also keep the size of any given load module reasonable. So you might keep infrequently used maps separate from those normally used in a given process.

Similarly, all of the symbolic maps for a map set are in a single symbolic structure. This affects the amount of storage you need while using the maps, as explained in BASE and STORAGE options. Depending on the programming language, it also may affect high-level names, and this may be a reason for separating or combining maps as well.

The Application Data Structure (ADS)

The symbolic map generated by the BMS macros is also known as the application data structure (ADS).

Physical maps produced by CICS Transaction Server for z/OS®, Version 3 Release 1 also include an ADS descriptor in the output load module. This is provided to allow interpretation of the BMS Application Data Structure (the structure used by the application program for the data in SEND and RECEIVE MAP requests), without requiring your program to include the relevant DSECT or copybook at compile time.

The ADS descriptor contains a header with general information about the map, and a field descriptor for every field that appears in the ADS (corresponding to every named field in the map definition macro). It can be located in the mapset from an offset field in DFHMAPDS.

The ADS descriptor is generated for all maps. You can choose to map the long or short form of the ADS by specifying the DSECT=ADS|ADSL option. The default is ADS,the short (normal) form. The long form of the ADS aligns all fields on 4-byte boundaries and is required for some interfaces with other products, such as MQSeries®.

Map sets generated with CICS releases before CICS Transaction Server for OS/390® Release 2 do not contain the ADS descriptor.

The format of the ADS descriptor is contained in the following copybooks:

Table 38. ADS descriptor copybooks
Language
Copybook
Assembler
DFHBRARD
C
DFHBRARH
PL/I
DFHBRARL
COBOL
DFHBRARO

For further information about the ADS descriptor, see the CICS External Interfaces Guide.

If you need to reassemble maps but have no access to the source, a utility program, DFHBMSUP, is provided in CICS Transaction Server for z/OS, Version 3 Release 1 to recreate BMS macro source from a mapset load module.

See the CICS Operations and Utilities Guide for more information about DFHBMSUP.

[[ Contents Previous Page | Next Page Index ]]