This section first describes the types of map sets, how you define them, and how CICS® recognizes them. This is followed by a description of how to prepare physical map sets and symbolic description map sets separately. Finally, there is a description of how to prepare both physical and symbolic description map sets in one job. In these descriptions, it is assumed that the SYSPARM parameter is used to distinguish the two types of map sets.
To install a map set, you must actually prepare two types of map sets:
Physical map sets must be cataloged in the CICS load library. Symbolic description map sets can be cataloged in a user copy library, or inserted directly into the application program itself.
The map set definition macros are assembled twice; once to produce the physical map set used by BMS in its formatting activities, and once to produce the symbolic description map set that is copied into the application program.
The two types of map set can be distinguished by either:
If you use the SYSPARM operand for this purpose, the TYPE operand of the DFHMSD macro is ignored. Using SYSPARM allows both the physical map set and the symbolic description map set to be generated from the same unchanged set of BMS map set definition macros.
Map sets can be assembled as either unaligned or aligned (an aligned map is one in which the length field is aligned on a halfword boundary). Use unaligned maps except in cases where an application package needs to use aligned maps.
The SYSPARM value alone determines whether the map set is aligned or unaligned, and is specified on the EXEC PROC=DFHMAPS statement. The SYSPARM operand can also be used to specify whether a physical map set or a symbolic description map set (DSECT) is to be assembled, in which case it overrides the TYPE operand. If neither operand is specified, an unaligned DSECT is generated.
The TYPE operand of the DFHMSD macro can only define whether a physical or symbolic description map set is required.
For the possible combinations of operands to generate the various types of map set, see Table 7.
Type of map set |
SYSPARM operand of EXEC DFHMAPS statement | TYPE operand
of DFHMSD macro |
---|---|---|
Aligned symbolic description map set (DSECT) |
A A ADSECT |
Not specified DSECT Any (takes SYSPARM) |
Aligned physical map set |
A AMAP |
MAP Any (takes SYSPARM) |
Unaligned symbolic description map set (DSECT) |
Not specified Not specified DSECT |
Not specified DSECT Any (takes SYSPARM) |
Unaligned physical map set |
Not specified MAP |
MAP Any (takes SYSPARM) |
The physical map set indicates whether it was assembled for aligned or unaligned maps. This information is tested at execution time, and the appropriate map alignment used. Thus aligned and unaligned map sets can be mixed.
Applications and maps designed for the 3270 Information Display System run unchanged on devices supporting extensions to the 3270 data stream such as color, extended highlighting, programmed symbols, and validation. To use fixed extended attributes such as color, you only need to reassemble the physical map set. If dynamic attribute modification by the application program is needed, you must reassemble both the physical and symbolic description map sets, and you must reassemble or recompile the application program.
Figure 27 shows the the assembler and linkage editor steps for installing physical map sets.
Figure 28 gives an example job stream for the assembly and link-editing of physical map sets.
//PREP JOB 'accounting information',CLASS=A,MSGLEVEL=1
//STEP1 EXEC PROC=DFHASMVS,PARM.ASSEM='SYSPARM(MAP)' 1
//SYSPUNCH DD DSN=&&TEMP,DCB=(RECFM=FB,BLKSIZE=2960),
// SPACE=(2960,(10,10)),UNIT=SYSDA,DISP=(NEW,PASS)
//SYSIN DD *
·
·
·
Macro statements defining the map set
·
·
·
/*
//STEP2 EXEC PROC=DFHLNKVS,PARM='LIST,LET,XREF' 2
//SYSLIN DD DSN=&&TEMP,DISP=(OLD,DELETE)
// DD *
MODE RMODE(ANY|24) 3
NAME mapsetname(R) 4
/*
//
Notes:
1 For halfword-aligned length fields, specify the option SYSPARM(AMAP) instead of SYSPARM(MAP).
2 Physical map sets are loaded into CICS-key storage, unless they are link-edited with the RMODE(ANY) and RENT options. If they are link-edited with these options, they are loaded into key-0 protected storage, provided that RENTPGM=PROTECT is specified on the RENTPGM initialization parameter. However, it is recommended that map sets (except for those that are only sent to 3270 or LU1 devices) should not be link-edited with the RENT or the REFR options because, in some cases, CICS modifies the map set. Generally, use the RENT or REFR options for map sets that are only sent to 3270 or LU1 devices.For more information about the storage protection facilities available in CICS, see the CICS System Definition Guide.
3 The MODE statement specifies whether the map set is to be loaded above (RMODE(ANY)) or below (RMODE(24)) the 16MB line. RMODE(ANY) indicates that CICS can load the map set anywhere in virtual storage, but tries to load it above the 16MB line, if possible.
4 Use the NAME statement to specify the name of the physical map set that BMS loads into storage. If the map set is device-dependent, derive the map set name by appending the device suffix to the original 1- to 7-character map set name used in the application program. The suffixes to be appended for the various terminals supported by CICS BMS depend on the parameter specified in the TERM or SUFFIX operand of the DFHMSD macros used to define the map set. For programming information giving a complete list of map set suffixes, see the CICS Application Programming Reference manual.
To use a physical map set, you must define and install a resource definition for it. You can do this either by using the program autoinstall function or by using the CEDA DEFINE MAPSET and INSTALL commands. as described in Defining programs, map sets, and partition sets to CICS.
Symbolic description map sets enable the application programmer to make symbolic references to fields in the physical map set. Figure 29 shows the preparation of symbolic description map sets for BMS.
To use a symbolic description map set in a program, you must assemble the source statements for the map set and obtain a punched copy of the storage definition through SYSPUNCH. The first time this is done, you can direct the SYSPUNCH output to SYSOUT=A to get a listing of the symbolic description map set. If many map sets are to be used at your installation, or there are multiple users of common map sets, establish a private user copy library for each language that you use.
When a symbolic description is prepared under the same name for more than one programming language, a separate copy of the symbolic description map set must be placed in each user copy library. You must ensure that the user copy libraries are correctly concatenated with SYSLIB.
You need only one symbolic description map set corresponding to all the different suffixed versions of the physical map set. For example, to run the same application on terminals with different screen sizes, you would:
You can use the sample job stream in Figure 30 to obtain a listing of a symbolic description map set. It applies to all the programming languages supported by CICS.
//DSECT JOB 'accounting information',CLASS=A,MSGLEVEL=1
//ASM EXEC PROC=DFHASMVS,PARM.ASSEM='SYSPARM(DSECT)'
//SYSPUNCH DD SYSOUT=A
//SYSIN DD *
·
·
·
Macro statements defining the map set
·
·
·
/*
//
If you want to assemble symbolic description map sets in which length fields are halfword-aligned, change the EXEC statement of the sample job in Figure 30 to the following:
//ASSEM EXEC PROC=DFHASMVS,PARM.ASSEM='SYSPARM(ADSECT)'
To obtain a punched copy of a symbolic description map set, code the //SYSPUNCH statement in the above example to direct output to the punch data stream. For example:
//SYSPUNCH DD SYSOUT=B
To store a symbolic description map set in a private copy library, use job control statements similar to the following:
//SYSPUNCH DD DSN=USER.MAPLIB.ASM(map set name),DISP=OLD
//SYSPUNCH DD DSN=USER.MAPLIB.COB(map set name),DISP=OLD
//SYSPUNCH DD DSN=USER.MAPLIB.PLI(map set name),DISP=OLD
Figure 31 shows the DFHMAPS procedure for installing physical and symbolic description maps together. The DFHMAPS procedure consists of the following four steps, shown in Figure 31:
The DFHMAPT procedure is similar to DFHMAPS, with an additional step that installs HTML templates generated from the BMS maps. In this step, TEMPLATE is coded in the SYSPARM global variable in the EXEC statement (PARM='SYSPARM(TEMPLATE)'). In the DFHMAPT procedure, the output is directed to CICSTS31.CICS.SDFHHTML.
If you wish to use your own macro to customize HTML templates, and you do not wish to add your macro to the BMS source you should modify step ASMTEMPL:
PARM='SYSPARM(TEMPLATE,macro_name),DECK,NOOBJECT'
The load module from the assembly of the physical map set and the source statements for the symbolic description map set can be produced in the same job by using the sample job stream in Figure 32.
//PREPARE JOB 'accounting information',CLASS=A,MSGLEVEL=1
//ASSEM EXEC PROC=DFHMAPS,MAPNAME=mapsetname,RMODE=ANY|24 (see note)
//SYSUT1 DD *
·
·
·
Macro statements defining the map set
·
·
·
/*
//
The DFHMAPS procedure produces map sets that are not halfword-aligned. If you want the length fields in input maps to be halfword-aligned, you have to code A=A on the EXEC statement. In the sample job in Figure 32, change the EXEC statement to:
//ASSEM EXEC PROC=DFHMAPS,MAPNAME=mapsetname,A=A
This change results in the SYSPARM operands in the assembly steps being altered to SYSPARM(AMAP) and SYSPARM(ADSECT) respectively.
The DFHMAPS procedure directs the symbolic description map set output (SYSPUNCH) to the CICSTS31.CICS.SDFHMAC library. Override this by specifying DSCTLIB=name on the EXEC statement, where "name" is the name of the chosen user copy library.
It is possible that you might need to generate your BMS maps with a CSECT. For example, you might need to specify AMODE and RMODE options to ensure your maps reside above 16MB, or you might need to use the DFSMS binder IDENTIFY statement for reasons of change management. In this case, you need not only include the appropriate CSECT at the front of your BMS macro statements, but also add some conditional assembler statements to ensure that the CSECT statement is not included in the symbolic description map. The following example shows how you can add both a CSECT name and AMODE and RMODE statements:
//PREPARE JOB 'accounting information',CLASS=A,MSGLEVEL=1
//ASSEM EXEC PROC=DFHMAPS,MAPNAME=mapsetname,RMODE=ANY|24
//SYSUT1 DD *
.
AIF ('&SYSPARM' EQ 'DSECT').SKIPSD
AIF ('&SYSPARM' EQ 'ADSECT').SKIPSD
ANYNAME CSECT Binder IDENTIFY requires CSECT name
ANYNAME AMODE 31
ANYNAME RMODE ANY
.SKIPSD ANOP ,
DFH0STM DFHMSD TYPE=DSECT,MODE=INOUT,CTRL=FREEKB,LANG=COBOL, C
TIOAPFX=YES,TERM=3270-2,MAPATTS=(COLOR,HILIGHT), C
DSATTS=(COLOR,HILIGHT)
SPACE
DFH0STM DFHMDI SIZE=(24,80)
.
.
.
SPACE
DFHMSD TYPE=FINAL
END
.
/*
//