For each field in a map, you need one DFHMDF macro, which looks like this:

fldname DFHMDF POS=(line,column),LENGTH=number,
               INITIAL='text',OCCURS=number,
               ATTRB=(attr1,attr2,....)

The items in this macro are:

At the beginning of each map there is a macro, DFHMDI, which provides the control information:

mapname DFHMDI SIZE=(line,column),
               CTRL=(ctrl1,ctrl2,...)

The items in this macro are:

You can put several maps together into a map set. In fact, all maps (even a single map) must form a map set. For efficiency reasons, it’s a good idea to put related maps that are generally used in the same transactions in the same map set. All the maps in a map set get assembled together, and they’re loaded together at execution time as well. So far you have defined only one map but our sample uses more than one map; see Map Definitions for the Sample Application.

When you’ve defined all the maps for a set, you put another macro in front of all the others to define the map set. This is the DFHMSD macro:

mapset DFHMSD TYPE=type,MODE=mode,LANG=COBOL,
              STORAGE=AUTO,TIOAPFX=YES,
              CTRL=(ctrl1,ctrl2,...)

The items in this macro are:

Since all the maps in the sample application are used together, we’ll put them all into a single map set and call it NACTSET. The DFHMSD macro we need, then, is:

NACTSET DFHMSD TYPE=MAP,MODE=INOUT,LANG=COBOL,TIOAPFX=YES,STORAGE=AUTO

The only thing now missing from our map definition is the control information to show where the mapset ends. This is very simple: It’s another macro, DFHMSD TYPE=FINAL, followed by the Assembler END statement:

DFHMSD TYPE=FINAL
END

When you write assembler language (which is what you are doing when using these macros), you have to observe some syntax rules. Here’s a simple set of format rules that works. This is by no means the only acceptable format:

Figure 11-2 shows the map in an account record screen. It’s used for displaying and printing the record, and for additions, modifications, and deletions.

Example 11-1 shows the map definition for this screen; after the code there are notes on some of the macros.

The highlighted numbers(1–6) are not part of the code:

When CICS abends our transaction, it is stopped in its tracks; detected errors are also processed by the same logic (NACT04). This screen (shown in Figure 11-3) is used to display error information if the transaction abended and was run at a 3270 terminal.

Figure 11-3. The Error screen

The first time a map is sent to a terminal occurs in program NACT01, the menu screen is displayed. The command we need is:

EXEC CICS SEND MAP('ACCTMNU') MAPSET(WS-LITS-MAPSET)
          CURSOR(EIBCPOSN) MAPONLY FRSET FREEKB
          RESP(RESPONSE) RESP2(REASON-CODE)
END-EXEC

The option MAPONLY states that only the constants within your map are to be sent, so initializing the screen. NACT01 uses the DATAONLY option when the screen has the constants displayed and only the data fields are to be sent. If either of these options is not set then both the constants and the data are sent. CICS would expect the data to be used for filling in the map to be in a structure whose name is the name (as specified in the MAP option) suffixed with the letter O. So, when we issue the command:

EXEC CICS SEND MAP('ACCTDTL') MAPSET(WS-LITS-MAPSET)
          ERASE FREEKB CURSOR
          RESP(RESPONSE) RESP2(REASON-CODE)
END-EXEC

CICS expects the data for the map to be in a structure within the program (of exactly the sort generated by the map structure generation) named ACCTDTLO. This structure is usually in your WORKING-STORAGE section, but it might be in a LINKAGE area instead.

Let’s look at the more common situation in which we’re merging program data into the map. In program NACT01, we’re supposed to build a detail display map for one record and send it to the screen. Since the contents of the screen vary somewhat with the type of request, and we’re using the same screen for all types, this entails the following:

Examples Example 11-4 through Example 11-7 show how the necessary code might look for the display of a record.

PERFORM BBAB-MOVE-TO-DETAIL-MAP
MOVE -1 TO SNAMEDL
MOVE 'PRESS "CLEAR" OR "ENTER" TO RETURN TO THE MENU WHEN FINISHED'
 TO  MSGDO
PERFORM BBAC-PROTECT-DETAILS
SET CA-DISPLAYING TO TRUE

The need to move the details read from the file to the map area occurs in several places, so it has been placed in a common routine (BBAB-MOVE-TO-DETAIL-MAP). In order to ensure that the cursor is placed at the beginning of the surname field, its Length field is set to the special value of -1. (More about this later.) An explanatory/operational message is also placed in the map for transmission to the user. Finally the details on display are not modifiable, so we need to protect them by setting their attributes to autoskip (ASKIP). This requirement also occurs in several places so it has been placed in a common routine (BBAC-PROTECT-DETAILS).

 BBAB-MOVE-TO-DETAIL-MAP SECTION.
*
* This routine populates the detail map from the data obtained.
*
 BBAB-010.
     MOVE ACCTDO   IN NACTREC-DATA TO ACCTDO   IN ACCTDTLO
     MOVE SNAMEDO  IN NACTREC-DATA TO SNAMEDO  IN ACCTDTLO
     MOVE FNAMEDO  IN NACTREC-DATA TO FNAMEDO  IN ACCTDTLO
     MOVE MIDO     IN NACTREC-DATA TO MIDO     IN ACCTDTLO
     MOVE TTLDO    IN NACTREC-DATA TO TTLDO    IN ACCTDTLO
     MOVE TELDO    IN NACTREC-DATA TO TELDO    IN ACCTDTLO
     MOVE ADDR1DO  IN NACTREC-DATA TO ADDR1DO  IN ACCTDTLO
     MOVE ADDR2DO  IN NACTREC-DATA TO ADDR2DO  IN ACCTDTLO
     MOVE ADDR3DO  IN NACTREC-DATA TO ADDR3DO  IN ACCTDTLO
     MOVE AUTH1DO  IN NACTREC-DATA TO AUTH1DO  IN ACCTDTLO
     MOVE AUTH2DO  IN NACTREC-DATA TO AUTH2DO  IN ACCTDTLO
     MOVE AUTH3DO  IN NACTREC-DATA TO AUTH3DO  IN ACCTDTLO
     MOVE AUTH4DO  IN NACTREC-DATA TO AUTH4DO  IN ACCTDTLO
     MOVE CARDSDO  IN NACTREC-DATA TO CARDSDO  IN ACCTDTLO
     MOVE IMODO    IN NACTREC-DATA TO IMODO    IN ACCTDTLO
     MOVE IDAYDO   IN NACTREC-DATA TO IDAYDO   IN ACCTDTLO
     MOVE IYRDO    IN NACTREC-DATA TO IYRDO    IN ACCTDTLO
     MOVE RSNDO    IN NACTREC-DATA TO RSNDO    IN ACCTDTLO
     MOVE CCODEDO  IN NACTREC-DATA TO CCODEDO  IN ACCTDTLO
     MOVE APPRDO   IN NACTREC-DATA TO APPRDO   IN ACCTDTLO
     MOVE SCODE1DO IN NACTREC-DATA TO SCODE1DO IN ACCTDTLO
     MOVE SCODE2DO IN NACTREC-DATA TO SCODE2DO IN ACCTDTLO
     MOVE SCODE3DO IN NACTREC-DATA TO SCODE3DO IN ACCTDTLO
     MOVE STATDO   IN NACTREC-DATA TO STATDO   IN ACCTDTLO
     MOVE LIMITDO  IN NACTREC-DATA TO LIMITDO  IN ACCTDTLO
*
 END-BBAB-MOVE-TO-DETAIL-MAP.
     EXIT.

Each field is moved individually to the map area. This looks a bit tedious when coding, but is something which must be done. With a good block editor, this can be done in just a few minutes.

BBAC-PROTECT-DETAILS SECTION.
*
* This routine protects the detail data fields from modification.
*
 BBAC-010.
     MOVE DFHBMASK TO SNAMEDA
                      FNAMEDA
                      MIDA
                      TTLDA
                      TELDA
                      ADDR1DA
                      ADDR2DA
                      ADDR3DA
                      AUTH1DA
                      AUTH2DA
                      AUTH3DA
                      AUTH4DA
                      CARDSDA
                      IMODA
                      IDAYDA
                      IYRDA
                      RSNDA
                      CCODEDA
                      APPRDA
                      SCODE1DA
                      SCODE2DA
                      SCODE3DA
*
 END-BBAC-PROTECT-DETAILS.
     EXIT.

All of the data fields on the screen need to be protected from modification, so the same attribute (DFHBMASK, AUTOSKIP) is set for all of them.

EXEC CICS SEND MAP('ACCTDTL') MAPSET(WS-LITS-MAPSET)
            ERASE FREEKB CURSOR
            RESP(RESPONSE) RESP2(REASON-CODE)
  END-EXEC

Finally, the SEND MAP command instructs BMS to create and send a data stream to the device by identifying which MAP to use (ACCTDTL) in which MAPSET. Note this latter option references a data name which is included in source code which is copied into the program. The reason for this is to allow flexibility in naming of the objects referenced by the application. The ERASE option is included to ensure residual data on the screen is removed. The FREEKB option ensures that the user is able to continue work without needing to reset the device. The CURSOR option is explained in the following section. The RESP option is used in order to allow the program to deal with an abnormal return in a standard way.

When you want to receive input from a terminal, you use the RECEIVE MAP command, which looks like this:

EXEC CICS RECEIVE MAP(MAPNAME) MAPSET(MAPSETNAME)
                  RESP(RESPONSE) RESP2(REASON-CODE)
END-EXEC.

The MAP and MAPSET parameters have exactly the same meaning as for the SEND MAP command. MAP is required and so is MAPSET, unless it is the same as the map name. Again, it does no harm to include it for documentation purposes.

The form of the RECEIVE MAP command below does not specify where the input data is to be placed. This causes CICS to bring the data into a structure whose name is the map name suffixed with the letter I, which is assumed to be in either your WORKING-STORAGE or LINKAGE area.

For example, program NACT01 requires that we receive the filled-in account detail map. The command to do this is:

*
 DA-RECEIVE-DETAIL SECTION.
*
* This routine get the detail input from the user.
*
 DA-010.
     MOVE LOW-VALUES TO ACCTDTLI
*
     EXEC CICS RECEIVE MAP('ACCTDTL') MAPSET(WS-LITS-MAPSET)
                       RESP(RESPONSE) RESP2(REASON-CODE)
     END-EXEC

It brings the input data into a data area named ACCTDTLI, which is expected to have exactly the format produced by the map generation structure ACCTDTL.

As soon as the map is read in, we have access to all the data subfields associated with the map fields. For example, we can test whether the user made any entry in the request field of:

IF REQML = 0

Or we could discover if the user erased the field:

IF REQMF = DFHBMEOF ...

Or we could examine the input in that field:

IF REQMI = 'A'

This last case is discouraged. Generally we need to retain the data the user has input in a separate area that we will keep across the pseudo-conversational series of transactions used to perform the business function. We will therefore need to merge the current user input with whatever had been entered (if relevant) in any previous CICS task relevant to this business operation. Thus any validation or logic determination will be performed from this special area rather than the input directly. One of the main reasons for this relates to the fact that the Input and Output map areas are really descriptions of the same storage as mentioned earlier.

Before we explain how to find out what key was used to send the input, we need to introduce one CICS control block. This is the EXEC Interface Block (EIB), and it is the only one that you need to know anything about for the type of applications described in this book.

You can write programs without using even this one, but it contains information that is very useful and is sometimes really essential.

There is one EIB for each task, and it exists for the duration of the task. Every program that executes as part of the task has access to the same EIB. You can address the fields in it directly in your COBOL program without any preliminaries. You should only read these fields, however, not try to modify them. All of the EIB fields are discussed in detail in the CICS Application Programming Reference, but the ones that are of general use follow.

Getting back to the attention identifier, we can also tell what key was used to send the input by looking at the EIBAID field, as noted above.

When a transaction is started,EIBAID is set according to the key used to send the input that caused the transaction to get started. It retains this value through the first RECEIVE command, which only formats the input already read, until after a subsequent RECEIVE, at which time it is set to the value used to send that input from the terminal.

EIBAID is one byte long and holds the actual attention identifier value used in the 3270 input stream. As it is hard to remember these values and hard to understand code containing them, it is a good idea to use symbolic rather than absolute values when testing EIBAID. CICS provides you with a precoded set which you simply copy into your COBOL program by writing:

COPY DFHAID.

in your WORKING-STORAGE SECTION. For other languages the data structure gets placed in a library along with similar copy or include statements to add it into your program in the normal way. Example 11-8 shows some of the definitions this brings into your program.

01  DFHAID.
     02  DFHNULL       PIC X VALUE IS ' '.
     02  DFHENTER      PIC X VALUE IS ''''.
     02  DFHCLEAR      PIC X VALUE IS '_'.
     02  DFHCLRP       PIC X VALUE IS ' '.
     02  DFHPEN        PIC X VALUE IS '='.
     02  DFHOPID       PIC X VALUE IS 'W'.
     02  DFHMSRE       PIC X VALUE IS 'X'.
     02  DFHSTRF       PIC X VALUE IS ' '.
     02  DFHTRIG       PIC X VALUE IS '"'.
     02  DFHPA1        PIC X VALUE IS '%'.
     02  DFHPA2        PIC X VALUE IS '>'.
     02  DFHPA3        PIC X VALUE IS ','.
     02  DFHPF1        PIC X VALUE IS '1'.
     02  DFHPF2        PIC X VALUE IS '2'.
         . . .
         . . .
     02  DFHPF23       PIC X VALUE IS '.'.
     02  DFHPF24       PIC X VALUE IS '<'.

DFHENTER is the Enter key, DFHPA1 is Program Attention (PA) Key 1, DFHPF1 is Program Function (PF) Key 1, and so on. As in the case of the DFHBMSCA macro, any values above that appear to be spaces are not; they correspond to bit patterns for which there is no printable character.

MAPFAIL occurs on a RECEIVE MAP command when there are no fields at all on the screen for BMS to map for you. This happens if you issue a RECEIVE MAP after the user has pressed a Clear or a Program Attention key. These are known as “short-read” keys because the only data that flows from the termial is the keycode, no data from the terminal is passed. It can also occur even if the user does not use a short-read key. If, for example, you send a screen to be filled in (without any fields in which the map or the program turns on the modified-data tag), and the user presses the Enter key or one of the program function keys without keying any data into the screen, you’ll get MAPFAIL.

The reason for the failure is essentially the same in both cases. With the short read, the terminal does not send any screen data; hence no fields. In the other case, there are no fields to send; no modified-data tags have been turned on.

MAPFAIL is almost invariably a user error (and, hence, an expected program condition). It may occur on almost any RECEIVE MAP, and therefore you should handle it explicitly in the program. For instance, Example 11-9 shows the code that the example application contains to deal with a MAPFAIL that occurs when the menu map is received.

 BB-MENU-DATA-ENTERED SECTION.
*
* Obtain the input (if any) from the user.
*
 BB-010.
     MOVE LOW-VALUES TO ACCTMNUI
*
     EXEC CICS RECEIVE MAP('ACCTMNU') MAPSET(WS-LITS-MAPSET)
               RESP(RESPONSE) RESP2(REASON-CODE)
     END-EXEC
*
     IF  (RESPONSE NOT = DFHRESP(NORMAL))
     AND (RESPONSE NOT = DFHRESP(MAPFAIL))
          PERFORM Y-UNEXPECTED-ERROR
     END-IF

This code is designed to make the occurrence of MAPFAIL somewhat transparent to the program. It is important to realize the difference in what BMS does when there is and there is not data to map. If BMS finds data to map, it clears the target map area to nulls (LOW-VALUES) before setting up the appropriate Length, Flag and Input fields. If BMS finds no data to map, it immediately raises the MAPFAIL condition and leaves the target map area exactly as it was.

In order to ensure the basic logic of the program can proceed regardless of the input, it primes the target map area with LOW-VALUES (nulls) before requesting BMS services. We then detect that the response from BMS is acceptable by the test of the EIBRESP value. Note that the key causing the initiation of the transaction was tested before we reached this part of the program, so we know it isn’t the CLEAR key.

If data is passed in the START command, the transaction that gets started uses the EXEC CICS RETRIEVE command to get access to this data. The syntax of the RETRIEVE command looks like this:

EXEC CICS RETRIEVE
          INTO(data-area)LENGTH(length)
END-EXEC

Notice the difference between this RETRIEVE command and the RECEIVE command described in The RECEIVE MAP command. Both commands may be used to get the initial input to a transaction, but they aren’t interchangeable: RECEIVE must be used in transactions that are initiated by input from a terminal, and RETRIEVE must be used in transactions that were started by another transaction. The options for this command are:

In our sample application, program NACT01 uses the START command when a user asks for a record to be printed:

EXEC CICS START TRANSID(PRINT-TRANSID) TERMID(CA-PRINTER)
                FROM(ACCTDTLO)
                RESP(RESPONSE) RESP2(REASON-CODE)
ENDEXEC

This START command tells CICS to start transaction PRINT-TRANSID as soon as possible after the printer whose name is in data area CA-PRINTER is available to be its terminal.

Program NACT03, running on behalf of this transaction, in turn issues the following RETRIEVE command to retrieve the data passed from program NACT01:

EXEC CICS RETRIEVE
          INTO(ACCTDTLI)
          RESP(RESPONSE) RESP2(REASON-CODE)
END-EXEC

ACCTDTLO and ACCTDTLI refer to the symbolic map structure, located in WORKING-STORAGE in both programs. The map, of course, contains the data read by transaction NACT. This data is to be printed by transaction NACP.

A number of different problems may arise in connection with the START and RETRIEVE commands that we’ve described. Possible errors are: