Defining map fields: DFHMDF

You should design the layout of your screen before you attempt to code any macros. After you have done that, you define each field on the screen (page) with a DFHMDF macro. In it, you indicate:

Fields that are referenced by the application must be allocated field names. The length of the field name and the characters that may be used to form field names must conform to the following rules. (Note that these rules apply to currently-supported compilers and assemblers.)

The characters used must be valid for names of assembler ordinary symbols. This character set consists of the alphabetic characters A - Z (upper or lower case), $, #, @, numeric digits 0 - 9, and the underscore (_) character.

There is one exception to this rule. The hyphen (-) character may be used in field names provided that:

The first character of the field name must be alphabetic, but the other characters can be any from the character set described above.

In addition, the characters used in field names must conform to the character set supported by the programming language of the application using the map. For example, if the application language is COBOL, you cannot use either the @ character or an underscore. You should refer to the appropriate Language Reference manual for information about these character sets.

The DFHMDF macro allows the length of field names to be from one through 30 characters. DFHMDF derives additional variable names by appending one of several additional characters to the defined name to generate a symbolic description map. These derived names may therefore be up to 31 characters in length. The assembler, PL/1, and C languages all support variable names of at least 31 characters. However the COBOL language only allows up to 30 characters, which means that field names used in maps must not exceed 29 characters for COBOL applications. For example, the following field definition is valid for all languages except COBOL:

 ThisIsAnExtremelyLongFieldName DFHMDF LENGTH=10,POS=(2,1)

and the following field definition is only valid for COBOL:

Must-Not-Exceed-29-Characters DFHMDF LENGTH=10,POS=(2,1) "

Not all the options for field definition are described here; the rest are described in the CICS® Application Programming Reference manual.

Figure 106 shows the field definitions for the map we considered in Figure 103.

Figure 106. BMS map definitions
        DFHMDF POS=(1,1),LENGTH=3,ATTRB=(ASKIP,BRT),INITIAL='QCK'
        DFHMDF POS=(1,26),LENGTH=28,ATTRB=(ASKIP,NORM),                X
              INITIAL='Quick Customer Account Check'
        DFHMDF POS=(3,1),LENGTH=8,ATTRB=(ASKIP,NORM),INITIAL='Account:'
ACCTNO  DFHMDF POS=(3,13),LENGTH=7,ATTRB=(ASKIP,NORM)
        DFHMDF POS=(4,1),LENGTH=5,ATTRB=(ASKIP,NORM),INITIAL='Name:'
SURNAME DFHMDF POS=(4,13),LENGTH=15,ATTRB=(ASKIP,NORM)
FNAME   DFHMDF POS=(4,30),LENGTH=10,ATTRB=(ASKIP,NORM)
        DFHMDF POS=(5,1),LENGTH=11,ATTRB=(ASKIP,NORM),INITIAL='Max charge:'
CHG     DFHMDF POS=(5,13),ATTRB=(ASKIP,NORM),PICOUT='$,$$0.00'
MSG     DFHMDF LENGTH=20,POS=(7,1),ATTRB=(ASKIP,NORM)

  1. The POS (position) parameter indicates the row and column position of the field, relative to the upper left corner of the map, position (1,1). It must be present. Remember that every field begins with a field attributes byte; POS defines the location of this byte; the contents of the field follow immediately to the right.
  2. The LENGTH option tells how many characters long the field is. The length does not include the attributes byte, so each field occupies one more column than its LENGTH value. In the case of the first field in our map, for example, the attributes byte is in row 1, column 1, and the display data is in columns 2-4. Fields can be up to 256 characters long and can wrap from one line to another. (Take care with fields that wrap if your map is smaller than your screen. See Outside the map for further information.)
  3. The ATTRB (attributes) option sets the field attributes of the field, which we discussed in 3270 field attributes. It is not required; BMS uses a default value of (ASKIP, NORM)--autoskip protection, normal intensity, modified data tag off--if you omit it. There are other options for each of the extended attributes, none of which was used in this map; these are described in Setting the display characteristics.
  4. The INITIAL value for the field is not required either. You use it for label and title fields that have a constant value, such as ‘QCK’, and to assign a default value to a field, so that the program does not always have to supply a value.
  5. The PICOUT option on the definition of the field CHG tells BMS what sort of PICTURE clause to generate for the field. It lets you use the edit facilities of COBOL or PL/I directly, as you move data into the map. If you omit PICOUT, and also the numeric (NUM) attribute, BMS assumes character data. Figure 104 shows the effects of the PICOUT option for CHG and, in the other fields, its absence. You can omit the LENGTH option if you use PICOUT, because BMS infers the length from the picture.
  6. The GRPNAME and OCCURS options do not appear in our simple example, because they are for more complex problems. GRPNAME allows you to subdivide a map field within the program for processing, and OCCURS lets you define adjacent, like map fields so that you can treat them as an array in the program. These options are explained in Using complex fields after some further information about maps.
[[ Contents Previous Page | Next Page Index ]]