Terminal Control and Basic Mapping Support

Basic Mapping Support

BMS is provided by CICS to help you define and format screens. Using BMS frees the applications programmer from many lower-level details of screen definition, particularly details associated with device dependence and I/O operations.

When you define a screen using BMS, the screen is called a map. A collection of screens is called a mapset. Both physical (used primarily by CICS) and logical or symbolic maps (used primarily by the application program) must be created.

To create the original map definition, CICS provides assembler-language macros for use under BMS. For more information about defining maps and using these macros, consult the IBM CICS Application Programmer's Reference appropriate for your site.

Commonly used macros include the following:

DFHMDF: defines a field in a map and its characteristics.
DFHMDI: defines a map and its characteristics within a mapset.
DFHMSD: defines a mapset and its characteristics and ends a definition.

After you finish creating a map, the map definition must be assembled and link-edited. This is done once for the physical map, and once for the symbolic map. The final destination for the physical map is the CICS load module library; the symbolic map goes into the header file library. Your site probably provides cataloged procedures that simplify this process.

You can use either of the following techniques to generate symbolic maps that are suitable for use in your C application:

You can specify LANG=C in the DFHMSD macro.
You can specify LANG=ASM and convert the generated DSECT to a C structure using the DSECT2C utility. For systems prior to CICS/ESA, this technique is the only one available.

Using LANG=C

If you use symbolic maps generated by specifying LANG=C in the DFHMSD macro, you must either specify the CBMSMAPS option to the CICS translator, or you must use the FROM option of the SEND MAP command and the INTO option of the RECEIVE MAP command. This example of code for BMS macros illustrates the use of the LANG=C option:

M0      DFHMSD TYPE=MAP,
               LANG=C,
               MAPATTS=(COLOR,HILIGHT),
               EXTATT=YES,
               MODE=INOUT,
               CTRL=FREEKB,
               STORAGE=AUTO,
               TIOAPFX=YES
M01     DFHMDI SIZE=(3,80),LINE=1
*
        DFHMDF ...
*
M02     DFHMDI SIZE=(3,80),LINE=4
*
        DFHMDF ...
*
        DFHMSD TYPE=FINAL
        END

Here's an example of C code that uses the CBMSMAPS option and a symbolic map named "mapmm0":

#pragma options xopts(cbmsmaps)
#include "mapm0.h"


void main()
{
   EXEC CICS SEND   MAP("m01")
                    MAPSET("m0")
                    ERASE
                    ;
}

Here's what the equivalent command would look like if you did not specify the CBMSMAPS option:

#pragma options xopts(cbmsmaps)
#include "mapm0.h"


void main()
{
   EXEC CICS SEND   MAP("m01")
                    MAPSET("m0")
                    ERASE
                    FROM (M01.MM01o)
                    ;
}

Using DSECT2C

When using C as the application programming language, create physical and logical maps for your mapset as described earlier. However, in addition to these steps, you must also process the assembler-language output listing for the symbolic assembly through the SAS/C utility, DSECT2C. This utility creates a C structure that must be included into the SAS/C application program source. It is recommended that you use #include , but you may also in-line the C structure into the source.

The DSECT2C utility, provided as part of the SAS/C product, converts assembler-language dummy sections, known as DSECTs, to equivalent C structure definitions. (For details on using this utility, refer to the SAS/C Compiler and Library User's Guide.) The SAS/C translator expects DSECT2C to generate the structure used to represent a map.

The -d option for the DSECT2C utility facilitates BMS map generation. By default, DSECT2C generates a structure definition only, as shown in the following example:

struct XYZ {
.
.
.
};

When you specify the -d option, DSECT2C adds an identifier to the definition, thereby declaring a variable of the structure type. The identifier name is the structure tag in lowercase, as shown here:

struct XYZ {
.
.
.
} xyz;

When you use the SEND MAP or RECEIVE MAP commands with string literal map names, the FROM/INTO options for these commands are optional. The translator will generate a default FROM/INTO argument that is the map name in lowercase. For example, the following commands are equivalent:

SEND MAP("MAP1");

SEND MAP("MAP1") FROM(map1)...;

Therefore, a simple way to use BMS maps is to use -d with DSECT2C to generate the structure declaration in a header file. When you include the header file (outside of any function), you are, in effect, declaring an extern variable of the structure type. When you use SEND MAP or RECEIVE MAP and allow the FROM/INTO options to default, the map will be sent from, or received into, the external structure.

The translator also generates a default length for the SEND command. BMS map generation always assigns the map length to a symbol whose name is the map name (in uppercase) followed by an E. In C, this symbol is a macro name. For example, if the length of MAP1 is 28, then the DSECT2C-created structure will include the following statement:

#define MAP1E 28

The translator uses this symbol as the default LENGTH value. Therefore, the following commands are equivalent:

SEND MAP("MAP1");

SEND MAP("MAP1") FROM(map1) LENGTH(MAP1E);

DSECT2C-generated Variable and Macro Names

The following characters, when used as the first character, are legal in a map name but not in a C variable name or a macro name: @, #, and $. For example, #MAP1 is a legal BMS map name, but #map1 is not valid as a C variable name. DSECT2C replaces these unacceptable characters with a digraph when it generates a variable name or a macro name. The character @ is replaced by A_, # with P_, and $ with D_. For example, the length of "MAP#1" will be defined via a macro named MAPP_1E, and the length of "$MAP1" will be defined via D_MAP1E.

Because the translator is aware of these changes, the correct defaults are generated. For example, the command SEND MAP("MAP#1"); causes the translator to emit default values equivalent to the following:

SEND MAP("MAP#1") FROM(mapp_1) LENGTH(MAPP_1E);

Example of Using BMS with C

Sample Map uses one of the maps specified for the sample application found in Examples. Map SASCAGA is created in mapset MAPSETA. The BMS definition for the map follows the display.

Sample Map
+OPERATOR INSTRUCTIONS --------------------- +OPERATOR INSTR - ENTER SMNU +FILE INQUIRY - ENTER SINQ AND NUMBER +FILE BROWSE - ENTER SBRW AND NUMBER +FILE ADD - ENTER SADD AND NUMBER +FILE UPDATE - ENTER SUPD AND NUMBER +PRESS CLEAR TO EXIT +ENTER TRANSACTION:+ +NUMBER+ +

The BMS map definition for this map is shown here:

TITLE 'FILEA - MAP FOR OPERATOR INSTRUCTIONS - SAS/C'
MAPSETA  DFHMSD TYPE=&SYSPARM,MODE=INOUT,CTRL=(FREEKB,FRSET),          *
               LANG=ASM,TIOAPFX=YES,EXTATT=MAPONLY,COLOR=BLUE
SASCAGA  DFHMDI SIZE=(12,40)
         DFHMDF POS=(1,10),LENGTH=21,INITIAL='OPERATOR INSTRUCTIONS',  *
               HILIGHT=UNDERLINE
         DFHMDF POS=(3,1),LENGTH=29,INITIAL='OPERATOR INSTR - ENTER*
               SMNU'
         DFHMDF POS=(4,1),LENGTH=38,INITIAL='FILE INQUIRY   - ENTER*
               SINQ AND NUMBER'
         DFHMDF POS=(5,1),LENGTH=38,INITIAL='FILE BROWSE    - ENTER*
               SBRW AND NUMBER'
         DFHMDF POS=(6,1),LENGTH=38,INITIAL='FILE ADD       - ENTER*
               SADD AND NUMBER'
         DFHMDF POS=(7,1),LENGTH=38,INITIAL='FILE UPDATE    - ENTER*
               SUPD AND NUMBER'
MSG      DFHMDF POS=(11,1),LENGTH=39,INITIAL='PRESS CLEAR TO EXIT'
         DFHMDF POS=(12,1),LENGTH=18,INITIAL='ENTER TRANSACTION:'
         DFHMDF POS=(12,20),LENGTH=4,ATTRB=IC,COLOR=GREEN,             *
               HILIGHT=REVERSE
         DFHMDF POS=(12,25),LENGTH=6,INITIAL='NUMBER'
KEY      DFHMDF POS=(12,32),LENGTH=6,ATTRB=NUM,COLOR=GREEN,            *
               HILIGHT=REVERSE
         DFHMDF POS=(12,39),LENGTH=1
         DFHMSD TYPE=FINAL
         END

After the map has been defined by using assembler-language macros, the map is assembled, and the DSECT2C utility is invoked to create the C header defining the map.

Under OS/390, the following JCL illustrates how a BMS map definition can be converted to a C structure:

//SASCAMA JOB ...(your job accounting info )...
//* 
//*    EXECUTE THE IBM-SUPPLIED BMS CATALOGED PROCEDURE
//*    TO CREATE A LOGICAL MAP FOR USE BY CICS AND A
//*    SYMBOLIC MAP TO BE USED DURING DSECT2C PROCESSING
//* //  EXEC DFHMAPS,
//  DSCTLIB='your.symbolic.map.library ',
//  MAPNAME=SASCAGA
//SYSUT1   DD DISP=SHR,DSNAME=SASC.SAMPLE(SASCAMA)    INPUT MAP SOURCE //*
//*    EXECUTE THE SAS/C DSECT2C CATALOGED PROCEDURE
//*    USING THE PREVIOUSLY CREATED SYMBOLIC MAP TO CREATE
//*    A C STRUCTURE
//*
//  EXEC DSECT2C,PARM.D2C='SASCAGA -D'
//SYSLIB   DD DISP=SHR,DSN=your.symbolic.map.library
//SYSIN    DD *
 SASCAGA  DSECT
          COPY SASCAGA
          END
//D2C.D2COUT   DD DISP=SHR,DSN=your.c.header.library(SASCAGA)

To use this map, the program would specify the following:

#include <sascaga.h>

main()
{
   EXEC CICS SEND MAP("SASCAGA") MAPONLY ERASE;
   EXEC CICS RETURN;
}

For additional information on this application, see the example in Examples.

BMS Input/Output Operations

Use I/O commands (such as SEND MAP, RECEIVE MAP, SEND CONTROL, SEND TEXT, and SEND PAGE) to send the map, receive the map, handle text, and so on. These commands have no special SAS/C considerations. For details on using these commands in your program, see the IBM CICS Application Programmer's Reference appropriate for your site.

Chapter Contents
Previous
Next
Top of Page