Appendix J. Basic Mapping Support Example

This appendix has a list of steps that you must follow so you can use the CICS basic mapping support (BMS) within the REXX/CICS environment. The steps include:

  1. BMS maps must be assembled and linked into a CICS library. This library must be in the LIBDEF in the CICS region startup JCL.
  2. If you are going to use the REXX/CICS CONVTMAP command to generate a file structure, the BMS map must be assembled to produce the map DSECT.
  3. BMS maps must be defined to CICS using Resource Definition Online (RDO).
  4. If you want to read from or send data to the screen, you need to GETMAIN CICS storage for the length of the map input/output areas. The storage must be initialized to nulls.
  5. If a field within a file structure is represented by more than one label, then the last label to reference that field in the structure must be used when referencing the field.

The example in this appendix is using BMS map PANELG. The following is the map definition.

         TITLE 'PANEL GROUP FOR REXX/CICS       '                       00000010
         PRINT ON,NOGEN                                                 00000020
PANELG   DFHMSD TYPE=MAP,LANG=ASM,MODE=INOUT,STORAGE=AUTO,SUFFIX=       00000030
         TITLE 'TEST PANEL FOR REXX/CICS        '                       00000040
DPANEL1  DFHMDI SIZE=(24,80),CTRL=(FREEKB),MAPATTS=(COLOR,HILIGHT),    *00000050
               DSATTS=(COLOR,HILIGHT),COLUMN=1,LINE=1,DATA=FIELD,      *00000060
               TIOAPFX=YES,OBFMT=NO                                     00000070
         DFHMDF POS=(1,1),LENGTH=1,ATTRB=(PROT,BRT)                     00000080
         DFHMDF POS=(5,27),LENGTH=22,INITIAL='REXXCICS HEADER PANEL1', *00000090
               ATTRB=(PROT,NORM)                                        00000100
         DFHMDF POS=(5,73),LENGTH=6,INITIAL='PANEL1',ATTRB=(PROT,NORM)  00000110
         DFHMDF POS=(9,6),LENGTH=25,                                   *00000120
               INITIAL='PLEASE ENTER YOUR USERID:',ATTRB=(PROT,NORM)    00000130
* DUSERID                                                               00000140
DUSERID  DFHMDF POS=(9,32),LENGTH=8,ATTRB=(UNPROT,BRT,IC,FSET)          00000150
         DFHMDF POS=(9,41),LENGTH=1,ATTRB=(PROT,NORM)                   00000160
         DFHMDF POS=(14,6),LENGTH=4,INITIAL='MSG:',ATTRB=(PROT,NORM)    00000170
* DMSG                                                                  00000180
DMSG     DFHMDF POS=(14,11),LENGTH=29,ATTRB=(UNPROT,NORM,FSET)          00000190
         DFHMDF POS=(14,41),LENGTH=1,ATTRB=(PROT,NORM)                  00000200
         DFHMSD TYPE=FINAL                                              00000210
         END                                                            00000220

The map DSECT follows.

* TEST PANEL FOR REXX/CICS                                              00000010
PANEL1S  EQU   *                     START OF DEFINITION                00000020
         SPACE                                                          00000030
         DS    CL12                      TIOA PREFIX                    00000040
DUSERIDL DS    CL2                       INPUT DATA FIELD LENGTH        00000050
DUSERIDF DS    0C                        DATA FIELD FLAG                00000060
DUSERIDA DS    C                         DATA FIELD 3270 ATTRIBUTE      00000070
DUSERIDC DS    C                         COLOR ATTRIBUTE                00000080
DUSERIDH DS    C                         HIGHLIGHTING ATTRIBUTE         00000090
DUSERIDI DS    0CL8                  INPUT DATA FIELD                   00000100
DUSERIDO DS    CL8                   OUTPUT DATA FIELD                  00000110
         SPACE                                                          00000120
DMSGL    DS    CL2                       INPUT DATA FIELD LENGTH        00000130
DMSGF    DS    0C                        DATA FIELD FLAG                00000140
DMSGA    DS    C                         DATA FIELD 3270 ATTRIBUTE      00000150
DMSGC    DS    C                         COLOR ATTRIBUTE                00000160
DMSGH    DS    C                         HIGHLIGHTING ATTRIBUTE         00000170
DMSGI    DS    0CL29                 INPUT DATA FIELD                   00000180
DMSGO    DS    CL29                  OUTPUT DATA FIELD                  00000190
         SPACE                                                          00000200
PANEL1E  EQU   *                                                        00000210
         ORG   PANEL1S                   ADDRESS START                  00000220
* CALCULATE MAPLENGTH, ASSIGNING A VALUE OF ONE WHERE LENGTH=ZERO       00000230
PANEL1L  EQU   PANEL1E-PANEL1S                                          00000240
PANEL1I  DS    0CL(PANEL1L+1-(PANEL1L/PANEL1L))                         00000250
PANEL1O  DS    0CL(PANEL1L+1-(PANEL1L/PANEL1L))                         00000260
         ORG                                                            00000270
* * * END OF DEFINITION * * *                                           00000280
         SPACE 3                                                        00000290
         ORG                                                            00000300
PANELGT  EQU   *                     * END OF MAP SET                   00000310
* * * END OF MAP SET DEFINITION * * *                                   00000320
         SPACE 3                                                        00000330

The CONVTMAP command is used to take the DSECT and create a file structure stored in the RFS. The command is entered as follows:

'CONVTMAP USER.TEST(PANELG) POOL1:\USERS\USER1\PANELG.DATA'

The following is the file structure created by CONVTMAP.

00000 ***************************** TOP OF DATA *************************
00001 DUSERIDL 13 2   C
00002 DUSERIDF 15 1   C
00003 DUSERIDA 15 1   C
00004 DUSERIDC 16 1   C
00005 DUSERIDH 17 1   C
00006 DUSERIDI 18 8   C
00007 DUSERIDO 18 8   C
00008 DMSGL 26 2   C
00009 DMSGF 28 1   C
00010 DMSGA 28 1   C
00011 DMSGC 29 1   C
00012 DMSGH 30 1   C
00013 DMSGI 31 29  C
00014 DMSGO 31 29  C
00015 ***************************** BOTTOM OF DATA***********************

The following example is exec BMSMAP1. It creates a simple panel that asks for a user ID.

/* This EXEC uses CICS SEND and RECEIVE commands                 */
/* The panel has two fields USERID and a message                 */
/* field.  The panel is initially displayed with                 */
/* a message - "USERID must be 8 characters"                     */

/* GETMAIN storage to be used for data mapping                   */
/* and initialize                                                */
'PSEUDO OFF'
ZEROES = '00'x
'CICS GETMAIN SET(WORKPTR) LENGTH(90) INITIMG(ZEROES)'

VAR1 = 'USERID must be 8 characters'

/* Copy the REXX variable VAR1 to the GETMAINed storage          */
'COPYR2S VAR1 WORKPTR 30'

/* Copy the storage area to REXX variable                        */
'COPYS2R WORKPTR X 0 90'

'CICS SEND MAP(PANELG) FREEKB ERASE FROM(X)'
'CICS RECEIVE MAP(PANELG) INTO(Y)'

/* Copy Y into the GETMAINED storage area and then copy the data */
/* to REXX variables using the file structure generated          */
/* previously by the CONVTMAP command                            */
'COPYR2S Y WORKPTR 0 90'
'COPYS2R WORKPTR * POOL1:\USERS\USER1\PANELG.DATA'

/* loop until the user enters a USERID exactly 8 characters in   */
/* length                                                        */
do forever
MUSERID = STRIP(DUSERIDO)
if LENGTH(MUSERID) < 8  then
  do
   DMSGO = 'Please enter 8 char USERID'
   'COPYR2S * WORKPTR POOL1:\USERS\USER1\PANELG.DATA'
   'COPYS2R WORKPTR X 0 90'
   'CICS SEND MAP(PANELG) FREEKB ERASE FROM(X)'
   'CICS RECEIVE MAP(PANELG) INTO(Z)'
   'COPYR2S Z WORKPTR 0 90'
   'COPYS2R WORKPTR * POOL1:\USERS\USER1\PANELG.DATA'
  END
 ELSE LEAVE
END
'SENDE'
say ' '
say 'Hello' DUSERIDO', Welcome to REXX/CICS !!'
exit

The BMSMAP1 exec created the following panels.

                 REXX/CICS HEADER PANEL1                     PANEL1

PLEASE ENTER YOUR USERID:

MSG: USERID must be 8 characters








                 REXX/CICS HEADER PANEL1                     PANEL1

PLEASE ENTER YOUR USERID: TEST

MSG: Please enter 8 character USERID