Coding CICS maps

CICS maps are created using special Assembler Language macros. It is not necessary to know much about assembler to create CICS maps.

 There are special screen painters available (eg IBM's SDF II) which take the hard work out of coding assembler macros, these screen painters will generate the necessary assembler macros to create your map.

 This page will show you how to code the assembler macros necessary to create a CICS map for your program.

 This page is intended as a quick guide only, many other options are available, if you want to know more, check out the CICS Application Programming Guide.
 
 Symbolic and Physical Maps Two terms commonly used when creating maps are the Symbolic Map and the Physical Map. The symbolic map is essentially a copy library member which allows you to refer to fields on the map from your COBOL (or PL/1 or C or Assembler) program. The physical map is the code generated by the assembler to allow the system to display the map i.e. the object module.

 Some Rules
 Before coding your map you must be aware of some rules for coding the assembler statements. There may seem to be a lot of rules, but don't worry they are fairly simple to get your head round.

 Columns:
 Columns 1 to 71 are where you code your assembler statements.
 Column 72 is for a continuation marker if you need to continue a line.
 Columns 73 to 80 are for a line sequence number of comment.

 Continuation Lines:
 Any statement can have only two continuation lines. The text of the continuation line must start in column 16.
 To continue a line you put any character (except blank) in column 72.
 
 Comments: Comment line are indicated by placing an asterisk ('*') in column 1. A comment line can NOT be placed between continuation lines. and comment lines can NOT be continued.

 You cannot have blank lines in the assembler program.

 The Assembler Statement:
 The statement consists of four components: The optional name, starting in column1 (max length seven characters), the mandatory operation specifying the assembler instruction or macro, the operands which specify the parameters and an optional comment.

 Creating A Map Once you have created your map, you need to run it through the assembler. The map must be assembled twice with different parameters. The first pass throught the assembler, you specify TYPE=DSECT, this will create a copy library member that you can copy into your CICS/COBOL program. The second pass through the assembler, you specify TYPE=MAP, this will create an object module which will be passed through the link editor (binder) to produce a CICS load library member.
 
 Coding the CICS Map. There are normally 3 macro used when coding your map. They are DFHMSD, DFHMDI and DFHMDF.
 The DFHMSD macro defines a mapset.
 The DFHMDI macro defines a map within a mapset defined by by DFHMSD
 The DFHMDF macro defines a field within the map defined by DFHMDI.
 
Don't worry too much about the first two macros, they won't change much from map to map.
 The first statement in your program should be a DFHMSD macro statement, this will define the mapset.
 It will look something like this:
 
MAPSN DFHMSD TYPE=DSECT,                               X
             CTRL=FREEKB,DATA=FIELD,LANG=COBOL,        X
             MODE=INOUT,TERM=3270,TIOAPFX=YES 

"MAPSN" is the name of the mapset to be created. "TYPE=" is used to specify whether a copybook member is to be generated (TYPE=DSECT) or an object library member is to be created (TYPE=MAP).
 "CTRL=" specifies the characteristics of the 3270 terminal
 "DATA=FIELD" specifies that data is passed as contiguous fields.
 "LANG=COBOL" specifies the source language for generating the copy library member.
 "MODE=INOUT" specifies that the mapset is to be used for both input and output.
 "TERM=" specifies the terminal type associated with the mapset.
 "TIOAPFX=YES" specifies that fillers should be included in the generated copy library member.
 
The next statement you should include is the DFHMDI macro statement to define the map charcteristics.

 It will look something like this:

MAPNM DFHMDI COLUMN=1,DATA=FIELD,                       X
             JUSTIFY=(LEFT,FIRST),LINE=1,               X
             SIZE=(24,80)

 "MAPMN" is the name of the map.
 "COLUMN=1","LINE=1" and "JUSTIFY=(LEFT,FIRST)" establish the position of the map on the page.
 "DATA=FIELD" specifies that the data is passed as a contiguous stream.
 Most of the time the DFHMSD and DFHMDI operands will not need to be changed. the only changes will be the mapset name and map name.
 Once you have coded these statements you can now get on with defining the fields that will appear in your map. (ie the important bit).

 We'll start out with a couple of sample definintions:


FNAME  DFHMDF POS=(1,5),LENGTH=10,                          X
              ATTRB=(UNPROT,BRT,FSET),                      X
              INITIAL='XXXXXXXXXX',PICIN='X(10)',           X
              PICOUT='X(10)',COLOR=RED
*
DOB    DFHMDF POS=(2,5),LENGTH=8,                           X
              ATTRB=(UNPROT,NORM,NUM,ASKIP),                X
              INITIAL='00000000',PICOUT='9(8)' 

First in the definition is the field name ("FNAME" and "DOB") followed by the macro DFHMDF
 "POS=(x,y)" specifies where on the screen the field is to be placed. x is the line and y is the column.
 "LENGTH=" specifies the length of the field to be generated.
 "ATTRB=" specifies a list of attributes for the field. UNPROT means you can type data in to the field, BRT means the field intensity is BRighT, NUM that the field is numeric only.
 "INITIAL=" specifies an initial value for the field.
 "PICIN=" and "PICOUT=" allows you to specify a picture clause for the field. This lets you specify editing characters such as Z to suppress leading zeros.
 "COLOR=" is used to define the colour of the field. Note that you must specify MAPATTS=COLOR on the DFHMDI macro to use the COLOR option .
 Once you have specified all the fields to be included on the map (the maximum number of fields is 1023) you must then specify a final macro to indicate the end of the map. You specify the DFHMDF macro with the operand TYPE=FINAL, like this:
 DFHMDF TYPE=FINAL
And that's it.

 Here's a quick example mapset definition (note this has not been tested):

 MAPS1 DFHMSD TYPE=&SYSPARM,MODE=INOUT,TIOAPFX=YES,LANG=COBOL, X
              TERM=3270-2
 MAP1  DFHMDI SIZE=(24,80),CTRL=FREEKB,MAPATTS=COLOR
 FNAME DFHMDF POS=(1,5),LENGTH=10,                             X
              ATTRB=(UNPROT,BRT,FSET),                         X
              PICIN='X(10)',PICOUT='X(10)'
 LNAME DFHMDF POS=(1,25),LENGTH=10,                            X
              ATTRB=(UNPROT,BRT,FSET),                         X
              COLOR=RED,                                       X
              PICIN='X(10)',PICOUT='X(10)'
 CRLIM DFHMDF POS=(3,5),LENGTH=8,                              X
              ATTRB=(UNPROT,NUM,NORM,FSET),                    X
              PICOUT='ZZZZ9.99'
       DFHMSD TYPE=FINAL
 END

 Generating the Load module (Physical Map) and Copybook (Symbolic Map)

Once you have defined your map,you must then 'Assemble' the map. The code you have created has to be passed through the assembler twice. The first time is to create the load module, the second time is to create the Copybook layout. As mentioned above, to create the load module the TYPE parameter of the DFHMSD macro must be set to MAP, and to create the copybook the TYPE parameter must be set to DSECT. To make life easier you can specify TYPE=&SYSPARM. This will let you pass the MAP or DSECT parms when you assemble the map.
 There is an IBM supplied JCL PROC called DFHMAPS which can be used to assemble the maps, this will handle the assembling of maps for you and pass the appropriate value for TYPE when required, or you site may have it's own way of assembling maps.


 Using The Generated Copybooks (Symbolic Map).When your map has been generated you will have a new Copybook. If you take a look at the copybook you will see that there are two main definitions (Level 01). The first is the mapname suffixed by an 'I' , for Input, the second is the mapname suffixed by an O, for Output. The input definition is used to display the map field via the SEND MAP CICS command. Within the Input definition you will see all the fields you specified defined. For each of these fields there will also be a length field suffixed by 'L', and an Attribute field, suffixed by 'A'. There will also be a Flag field suffixed by F, this isn't normally used.
 You can change the colour, and protection attributes by changing the A field. To do this you should copy the DFHBMSCA copybook into working storage. This contains definitions for attributes eg DFHBMASK to set a field to SKIP. Then move the required attribute to the 'A' field.
The length field can be used to set where the cursor will be positioned when the map is displayed. Simply move -1 to the length field, prior to the SEND MAP.
 The output part of the copybook definition should be used as a receive area after the user has pressed Enter (or a PF Key) - RECEIVE MAP...... INTO...


Arrays
You can use BMS Macros to define an array of fields with the same name. However using Assembler Macros you can only specify a horizontal array. To do this you use the ‘OCCURS=’ parameter on the DFHMDF macro.
If you want to specify a Vertical array then you must specify each field in the array seperatley using BMS Macros and then edit the generated symbolic map (Copybook).
 When using a screen painter such as IBM’s SDF II you can specify the array direction, and the screen painter will generate the correct symbolic map to let you use horizontal arrays.without the need for editing the generated code.