Installing map sets

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.

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.

Defining the type of map set you require

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.

Table 7. SYSPARM and DFHMSD operand combinations for map assembly
 
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.

Using extended data stream terminals

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.

Installing physical map sets

Figure 27 shows the the assembler and linkage editor steps for installing physical map sets.

Figure 27. Installing physical map sets
 This diagram shows the macro statements defining the map set being processed by the assembler to produce a a listing and an intermediate object file that is then process ed by the linkage editor to produce a listing and a physical map set stored in CICS.SDFHLOAD.

Figure 28 gives an example job stream for the assembly and link-editing of physical map sets.

Figure 28. Assembling and link-editing a physical map set
//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.

Installing symbolic description map sets

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.

Figure 29. Installing symbolic description map sets using the DFHASMVS procedure
 This diagram shows the steps in the DFHASMVS procedure to assemble the macro statements defining a symbolic map set to produce an output listing and an output file that is directed to SYSPUNCH.

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:

  1. Define two map sets each with the same fields, but positioned to suit the screen sizes. Each map set has the same name but a different suffix, which would match the suffix specified for the terminal.
  2. Assemble and link-edit the different physical map sets separately, but create only one symbolic description map set, because the symbolic description map set would be the same for all physical map sets.

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.

Figure 30. Listing of a symbolic description map set
//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

Installing physical and symbolic description maps together

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:

  1. The BMS macros that you coded for the map set are added to a temporary sequential data set.
  2. The macros are assembled to create the physical map set. The MAP option is coded in the SYSPARM global variable in the EXEC statement (PARM='SYSPARM(MAP)').
  3. The physical map set is link-edited to the CICS load library.
  4. Finally, the macros are assembled again, this time to produce the symbolic description map set. In this step, DSECT is coded in the SYSPARM global variable in the EXEC statement (PARM='SYSPARM(DSECT)'). Output is directed to the destination specified in the //SYSPUNCH DD statement. In the DFHMAPS procedure, that destination is the CICSTS31.CICS.SDFHMAC library.

Figure 31. Installing a physical map set and a symbolic description map set together
 This diagram shows the steps required to install a physical mapset and a symbolic map set together, as described in the preceding text.

Using the DFHMAPT procedure to install HTML templates from BMS maps

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:

  1. Change the PARM parameter of the EXEC statement to
    PARM='SYSPARM(TEMPLATE,macro_name),DECK,NOOBJECT'
  2. Add the library that contains your macro to the SYSLIB concatenation.

JCL to install physical and symbolic description maps

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.

Figure 32. Installing physical and symbolic description maps together
//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
  ·
  ·
  ·
/* //
Note:
The RMODE 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.

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.

Adding a CSECT to your map assembly

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:

Figure 33. Adding a CSECT to the map assembly
//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                                                                
.                                                          
 /*                                                                
//                                                                                                                              
[[ Contents Previous Page | Next Page Index ]]