Acquiring and defining storage for the maps

The first step in creating mapped output is to provide storage in which to arrange the variable map data that your program passes to BMS. If you place the map structure in working storage, CICS® does the allocation for you. (CICS allocates a private copy of working storage for each execution of a program, so that data from one task does not get confused with that from another, as explained in Program storage.) To use working storage, copy the symbolic map set there with the language statement provided for the purpose:

       COPY        in COBOL and assembler
       %INCLUDE    in PL/I
       #include    in C and C++

Working storage is the WORKING-STORAGE SECTION in COBOL, automatic storage in PL/I, C, C++, and DFHEISTG in a CICS assembler program. For example:

       WORKING-STORAGE SECTION.
       ...
       01  COPY QCKSET.
       ...

Alternatively, you can obtain and release map set storage as you need it, using CICS GETMAIN commands. (GETMAIN is discussed in Storage control.) In this case you copy the map into storage addressed by a pointer variable (the LINKAGE SECTION in COBOL, based storage in PL/I, C, and C++, a DSECT in assembler). On return from the GETMAIN, you use the address returned in the SET option to associate the storage with the data structure, according to the facilities of the programming language.

We used working storage in the example back on page Figure 105, but we could have used a GETMAIN. If we had, the code we just showed you would change to:

       LINKAGE SECTION.
       ...
       01  COPY QCKSET.
       ...
       PROCEDURE DIVISION.
       ...
       MOVE LENGTH OF QCKMAPO TO LL.
       EXEC CICS GETMAIN SET(ADDRESS OF QCKMAPO)
                   LENGTH(LL) END-EXEC.
       ...

The length you need on your GETMAIN command is the length of the variable whose name is the map name suffixed by the letter "O". In COBOL, PL/I, C, and C++, you can use language facilities to determine this length, as in the example above. In assembler, it is defined in an EQUate statement whose label is the map name suffixed by "L".

BASE and STORAGE options

Two options on the DFHMSD map set definition macro affect how storage for maps is defined: BASE and STORAGE=AUTO (the STORAGE option always has the value AUTO). You can use either one or neither, so there are three possibilities. If you specify neither for a map set containing several maps, the symbolic structures for the maps are defined so that they overlay one another. If you specify STORAGE=AUTO, they do not; each occupies separate space. Thus STORAGE=AUTO requires more storage.

However, when you use maps that overlay one another in a single program, you must use them serially or compensate for the reuse of storage by programming. Unless storage is a major issue, STORAGE=AUTO simplifies programming and reduces the risk of error.

In PL/I, C, and C++, STORAGE=AUTO has the additional effect of defining the map as automatic storage (storage that CICS allocates); the absence of STORAGE=AUTO causes these compilers to assume based storage, for which you generally incur the overhead of an additional GETMAIN. BMS assigns the name BMSMAPBR to the associated pointer variable, unless you specify another name with the BASE option.

The third possibility, BASE, lets you use the same storage for all the maps in multiple map sets. Its effect varies slightly with the programming language, but essentially, all the maps in map sets with the same BASE value overlay one another. In COBOL, BASE=xxxx causes the 01 levels (that is, each individual map) to contain a REDEFINES xxxx clause. In PL/I, C, and C++, it designates each map as storage based on the pointer variable xxxx. BASE cannot be used when the programming language is assembler.

[[ Contents Previous Page | Next Page Index ]]