Every screen you see and use in KICKS is called a map in the IBM world. The part in the real CICS, but also in our free KICKS is called BMS, or Basic Mapping Support.
See previous step for a better understanding.
See previous step for a better understanding.
You can find a lot of manuals about how this works in detail. In this blog post we are going into the specifics to let it compile in TK4, or MVS 3.8J.
If you look at the examples supplied with KICKS you can see that some are compiled without including the source code in the JCL, and some have the source code included in the JCL. These are two methods to work with, and I prefer to include it in the JCL. Its faster to work with then saving work, opening the JCL and compile and go back to the source.
Two methods to compile the map as shown above.
The include method looks for example as this:
The red part is the JCL where we declare some job instructions. The light yellow part is the actual mapping definition, and the green part at the bottom is where we place the compiled map, and where the copybook dataset is going to be.
Now, to design such a map there are some options. Use a pen and paper and draw it out, use your head and with some trail and error its doable, or use a tool. Most tools however are payware, but one of them is free and online. Take a look here.
The website lets you draw a map, and on the bottom you see the code life updated. You need to copy this and place it between the JCL statements.
My example:
//MAPCMPL JOB CLASS=C,MSGCLASS=H,MSGLEVEL=(1,1)
//JOBPROC DD DSN=BIS.KICKSSYS.V1R5M0.PROCLIB,DISP=SHR
// EXEC KIKMAPS,MAPNAME=AL12MAP
//COPY.SYSUT1 DD *
PRINT NOGEN
AL12MAP DFHMSD TYPE=&SYSPARM,MODE=INOUT,LANG=COBOL,TIOAPFX=YES, *
CTRL=(FREEKB,PRINT),TERM=3270-2,STORAGE=AUTO
AL12 DFHMDI SIZE=(24,80)
* CHANGE MAP SET AND MAP NAME AT 6 PLACES IN THIS TEMPLATE
DFHMDF POS=(01,01),LENGTH=08,INITIAL='AL12MAP'
DFHMDF POS=(01,13),LENGTH=55,INITIAL='BIS ACCOUNTING DEPARTMEN*
T - LOCATIONS AND SUBSIDARIES'
F01ALF DFHMDF POS=(01,72),LENGTH=08,ATTRB=ASKIP
*
F00DAT DFHMDF POS=(02,01),LENGTH=08
F02ALF DFHMDF POS=(02,72),LENGTH=08,ATTRB=ASKIP
*
DFHMDF POS=(03,25),LENGTH=31, *
INITIAL='LOCATION DEFINITION - ADD NEW'
*
DFHMDF POS=(06,14),LENGTH=15,INITIAL='LOCATION NUMBER'
F03NUM DFHMDF POS=(06,41),LENGTH=03,ATTRB=(IC,UNPROT,FSET), *
PICIN='999',PICOUT='999'
DFHMDF POS=(06,45),LENGTH=01
*
DFHMDF POS=(08,14),LENGTH=04,INITIAL='NAME'
F04ALF DFHMDF POS=(08,41),LENGTH=30,ATTRB=(UNPROT,FSET)
DFHMDF POS=(08,72),LENGTH=01
*
DFHMDF POS=(09,14),LENGTH=18,INITIAL='ADDRESS'
F05ALF DFHMDF POS=(09,41),LENGTH=25,ATTRB=(UNPROT,FSET)
DFHMDF POS=(09,67),LENGTH=01
*
DFHMDF POS=(10,14),LENGTH=04,INITIAL='CITY'
F06ALF DFHMDF POS=(10,41),LENGTH=22,ATTRB=(UNPROT,FSET)
DFHMDF POS=(10,64),LENGTH=01
*
DFHMDF POS=(11,14),LENGTH=07,INITIAL='COUNTRY'
F07ALF DFHMDF POS=(11,41),LENGTH=03,ATTRB=(UNPROT,FSET)
DFHMDF POS=(11,45),LENGTH=01
*
DFHMDF POS=(14,14),LENGTH=16,INITIAL='MASTER LOCATION'
F08NUM DFHMDF POS=(14,41),LENGTH=03,ATTRB=(UNPROT,FSET), *
PICIN='999',PICOUT='999'
DFHMDF POS=(14,45),LENGTH=01
*
DFHMDF POS=(22,07),LENGTH=67,INITIAL='TYPE REQUIRED DATA AND P*
RESS ENTER. CLR/PF12=MENU PF5=SAVE'
*
F24ALF DFHMDF POS=(24,01),LENGTH=79,ATTRB=ASKIP
*
DFHMSD TYPE=FINAL
END
/*
//LINKMAP.SYSLMOD DD DSN=BIS.KICKS.V1R5M0.KIKRPL(AL12MAP),
// DISP=SHR
//COBMAP.SYSPRINT DD DSN=BIS.KICKS.V1R5M0.COBCOPY(AL12MAP),
// DISP=SHR
//
Lets take a closer look. I painted the map, gave the fields where the user needs to input data, or where I want to display data a FIELDNAME. This fieldname for me is just FxxNUM/ALF, meaning F03NUM for example, the third field, expecting nummeric values. Note that for the map it doesnt matter, its just for later reference easier to remember.
The red part is the job JCL, be sure to give the map a unique name.
Next we see the map definition, where we have the MAPSET name, and the MAP name. There can be more than one map present in any set. However, the field names must be unique in the whole set.
I prefer to use them as shown, AL12MAP(set) and AL12(map)
All fields where we expect the user to enter data in, must be UNPROT(ect) and the field that initially has the cursor on, the IC attribute added, like ATTRB=(IC,UNPROT)
Below that, in green shows the location and name of the copybook and compiled program.
Above is a part of the generated copybook member (actually just an include file for your Cobol program). that is generated by the map compiler. This is a declaration of the fields, their attributes ready to use.
In KICKS/CICS there are always two variables for each field in a map, and input and an output variant. The map compiler generates a copybook member with both variants automatically.
Thus, F03NUM is known to Cobol later as F03NUMI and F03NUMO, where the I (input) variant contains the user entered data, and if we process it we can show it with F03NUMO (output) variable.
Thus, F03NUM is known to Cobol later as F03NUMI and F03NUMO, where the I (input) variant contains the user entered data, and if we process it we can show it with F03NUMO (output) variable.
Finally you see the macros DFHMSD, DFHMDI, and DFHMDF. The first two declares the mapset and map properties. The last one just the fields. You can code them by hand, but the online tool does is nicely for us. Small adjustments however are easy to do by hand.
What else is there to say ? You need, no must, do your own research. There is a wealth of information available, and all official IBM documentation applies.
Ah, colors.. I forget about those colors.
Above sample will give you a monochrome screen, with default terminal colors. But you can change them obviously.
PRINT NOGEN
ADMSMAP DFHMSD TYPE=&SYSPARM,MODE=INOUT,LANG=COBOL,STORAGE=AUTO, *
CTRL=(FREEKB,FRSET),TERM=3270,TIOAPFX=YES,EXTATT=YES
ADMS DFHMDI SIZE=(24,80),COLOR=TURQUOISE
Just adding EXTATT=YES (extended attributes) you enable the map to use colors. You do this in the DFHMSD definition, and set the default color in the DFHMDI definition as shown above.
To change for example the field colors you can just add COLOR= to them like this:
DFHMDF POS=(01,01),LENGTH=08,INITIAL='ADMSMAP',COLOR=BLUE
DFHMDF POS=(01,13),LENGTH=47,COLOR=GREEN, *
INITIAL='BIS INFO SYSTEMS - USER MESSAGES'
F01ALF DFHMDF POS=(01,72),LENGTH=08,ATTRB=ASKIP,COLOR=BLUE
DFHMDF POS=(02,01),LENGTH=08,COLOR=BLUE
DFHMDF POS=(02,25),LENGTH=15,INITIAL='ADD MESSAGE', *
COLOR=NEUTRAL
F02ALF DFHMDF POS=(02,72),LENGTH=08,ATTRB=ASKIP,COLOR=BLUE
DFHMDF POS=(03,02),LENGTH=11,INITIAL='TO TSO USER'
F10ALF DFHMDF POS=(03,15),LENGTH=08,ATTRB=(UNPROT,FSET),COLOR=RED
DFHMDF POS=(03,24),LENGTH=01,
DFHMDF POS=(03,27),LENGTH=07,INITIAL='SUBJECT'
F11ALF DFHMDF POS=(03,36),LENGTH=42,ATTRB=(UNPROT,FSET),COLOR=GREEN
If you use COLOR=NEUTRAL, then it will be white on the screen.
Finally, there is a pitfall in this what I explain when we are looking to the Cobol program to use these maps.
Stay tuned!