DFHMDF

The DFHMDF macro defines a field within a map defined by the previous DFHMDI macro.

DFHMDF (part 1)

Notes:

¹ DBCS characters start with a shift-out character X'0E' and end with a shift-in character X'0F'.

DFHMDF (part 2)

Description

A map contains zero or more fields.

“fld” is the name (1–30 characters) of the field. Refer to your compiler manual to ensure that there are no other restrictions on the length.

For more information about defining field names, see Creating the map . If “fld” is omitted, application programs cannot access the field to change its attributes or alter its contents. For an output map, omitting the field name might be appropriate when the INITIAL operand is used to specify the contents of a field. If a field name is specified and the map that includes the field is used in a mapping operation, data supplied by the user overlays data supplied by initialization (unless default data only is being written).

The performance of input mapping operations is optimized if DFHMDF macros are arranged in numeric order of the POS operand.

You cannot define more than 1023 named fields for a COBOL, C, or PL/I input/output map.

You must ensure that the names of maps, and names of fields within a mapset (or within multiple mapsets that are copied into one application program) are unique. However, a map can have the same name as a mapset.

Before CICS® can load a physical map, you must define a physical map using an RDO transaction with the MAPSET attribute.

Operands

ATTRB

This operand applies only to 3270 data stream devices; it is ignored for other devices, except that ATTRB=DRK is honored for the SCS Printer Logical Unit. It is also ignored (except for ATTRB=DRK) if the NLEOM option is specified on the SEND MAP command for transmission to a 3270 printer. In particular, ATTRB=DRK must not be used as a method of protecting secure data on output on non-3270, non-SCS printer terminals.

If ATTRB is specified within a group of fields, it must be specified in the first field entry. A group of fields appears as one field to the 3270. Therefore, the ATTRB specification refers to all the fields in a group as one field rather than as individual fields. It specifies device-dependent characteristics and attributes, such as the capability of a field to receive data, or the intensity to be used when the field is output. It could however, be used for making an input field nondisplay for secure entry of a password from a screen. For input map fields, DET and NUM are the only valid options; all others are ignored.

ASKIP

is the default and specifies that data cannot be keyed into the field and causes the cursor to skip over the field.

BRT

specifies that a high-intensity display of the field is required. Because of the 3270 attribute character bit assignments, a field specified as BRT is also potentially detectable. However, for the field to be recognized as detectable by BMS, DET must also be specified.

DET

specifies that the field is potentially detectable.

The first character of a 3270 detectable field must be one of the following:

?  >  &  blank

If ? or >, the field is a selection field; if & or blank, the field is an attention field. (See An Introduction to the IBM 3270 Information Display System for further details about detectable fields.)

A field for which BRT is specified is potentially detectable to the 3270, because of the 3270 attribute character bit assignments, but is not recognized as such by BMS unless DET is also specified.

DET and DRK are mutually exclusive.

If DET is specified for a field on a map with MODE=IN, only one data byte is reserved for each input field. This byte is set to X'00', and remains unchanged if the field is not selected. If the field is selected, the byte is set to X'FF'.

No other data is supplied, even if the field is a selection field and the ENTER key has been pressed.

If the data in a detectable field is required, all the following conditions must be fulfilled:

The field must begin with one of the following characters:
```
?  >  &  blank
```
and DET must be specified in the output map.
The ENTER key (or some other attention key) must be pressed after the field has been selected, although the ENTER key is not required for detectable fields beginning with & or a blank.
DET must not be specified for the field in the input map. DET must, however, be specified in the output map. For more information about BMS support of the light pen, see the CICS Application Programming Guide.

DRK

specifies that the field is nonprint/nondisplay. DRK cannot be specified if DET is specified.

FSET

specifies that the modified data tag (MDT) for this field must be set when the field is sent to a terminal.

Specification of FSET causes the 3270 to treat the field as though it has been modified. On a subsequent read from the terminal, this field is read, whether it has been modified. The MDT remains set until the field is rewritten without ATTRB=FSET, or until an output mapping request causes the MDT to be reset.

Either of two sets of defaults can apply when a field to be displayed on a 3270 is being defined but not all parameters are specified. If no ATTRB parameters are specified, ASKIP and NORM are assumed. If any parameter is specified, UNPROT and NORM are assumed for that field unless overridden by a specified parameter.

IC

specifies that the cursor is to be placed in the first position of the field. The IC attribute for the last field for which it is specified in a map is the one that takes effect. If not specified for any fields in a map, the default location is zero. Specifying IC with ASKIP or PROT causes the cursor to be placed in an unkeyable field.

This option can be overridden by the CURSOR option of the SEND MAP command that causes the write operation.

NORM

specifies that the field intensity is to be normal.

NUM

ensures that the data entry keyboard is set to numeric shift for this field unless the operator presses the alpha shift key, and prevents entry of nonnumeric data if the Keyboard Numeric Lock feature is installed.

PROT

specifies that data cannot be keyed into the field.

If data is to be copied from one device to another attached to the same 3270 control unit, the first position (address 0) in the buffer of the device to be copied from must not contain an attribute byte for a protected field. Therefore, when preparing maps for 3270s, ensure that the first map of any page does not contain a protected field starting at position 0.

UNPROT

specifies that data can be keyed into the field.

CASE

specifies that the field contains both uppercase and lowercase data that is to be converted to uppercase if the terminal definition specifies katakana support (KATAKANA(YES) option on RDO TYPETERM definition).

This must be specified if a field is known to contain lowercase Latin characters but can be displayed on a katakana display. It must not be specified if the field can contain valid katakana characters.

COLOR

indicates the individual color, or the default color for the mapset (where applicable).

The valid colors are blue, red, pink, green, turquoise, yellow, and neutral.

The COLOR operand is ignored unless the terminal supports color, as indicated by the RDO option COLOR.

GINIT

specifies constant or default data for an output field. GINIT is used to specify data in DBCS character strings, which must be enclosed by SO (shift out, X'0E') and SI (shift in, X'0F') characters. When GINIT is specified, the length must be even and is the number of bytes in the string (that is, not the number of DBCS characters). If a graphic data type (PS=X'F8') is used, and the language is stated as COBOL2 (Enterprise COBOL or VS COBOL II), a PIC G is generated. Only one of GINIT, INITIAL, or XINIT can be specified.

GRPNAME

is the name used to generate symbolic storage definitions and to combine specific fields under one group name. The same group name must be specified for each field that is to belong to the group. The length of the name is up to 30 characters, refer to your compiler manual to ensure that there are no other restrictions on the length.

The rules for defining group names are the same as for defining field names. See Creating the map for details.

If this operand is specified, the OCCURS operand cannot be specified.

The fields in a group must follow on; there can be gaps between them, but not other fields from outside the group. A field name must be specified for every field that belongs to the group, and the POS operand must also be specified to ensure that the fields follow each other. All the DFHMDF macros defining the fields of a group must be placed together, and in the correct order (ascending numeric order of the POS value).

For example, the first 20 columns of the first six lines of a map can be defined as a group of six fields, as long as the remaining columns on the first five lines are not defined as fields.

The ATTRB operand specified on the first field of the group applies to all of the fields within the group.

HILIGHT

specifies the default highlighting attribute for all fields in all maps in a mapset.

OFF: is the default and indicates that no highlighting is used.
BLINK: specifies that the field must flash.
REVERSE: specifies that the character or field is displayed in reverse video, for example, on a 3278, black characters on a green background.
UNDERLINE: specifies that a field is underlined.

The HILIGHT operand is ignored unless the terminal supports highlighting, as indicated by the RDO TYPETERM option HILIGHT(YES).

INITIAL (or XINIT)

specifies constant or default data for an output field. INITIAL is used to specify data in character form; XINIT is used to specify data in hexadecimal form.

For fields with the DET attribute, initial data that begins with one of the following characters:

?  >  &  blank

must be supplied.

The number of characters that can be specified in the INITIAL operand is restricted to the continuation limitation of the assembler to be used or to the value specified in the LENGTH operand (whichever is the smaller).

Hexadecimal data is written as an even number of hexadecimal digits, for example, XINIT=C1C2. If the number of valid characters is smaller than the field length, the data is padded on the right with blanks. For example, if LENGTH=3, XINIT=C1C2 results in an initial field of 'AB'.

If hexadecimal data is specified that corresponds with line or format control characters, the results are unpredictable. The XINIT operand must therefore be used with care. Only one of GINIT, INITIAL, or XINIT can be specified.

JUSTIFY

specifies the field justifications for input operations. This operand is ignored for VTAM®-supported 3600, 3650, and 3790 terminals, because input mapping is not available.

LEFT: specifies that data in the input field is left-adjusted.
RIGHT: specifies that data in the input field is right-adjusted.
BLANK: specifies that blanks are to be inserted in any unfilled positions in an input field.
ZERO: specifies that zeros are to be inserted in any unfilled positions in an input field.

LEFT and RIGHT are mutually exclusive, as are BLANK and ZERO. If certain arguments are supplied but others are not, assumptions are made as follows:

Specified       Assumed
 
LEFT            BLANK
RIGHT           ZERO
BLANK           LEFT
ZERO            RIGHT

If JUSTIFY is omitted, but the NUM attribute is specified, RIGHT and ZERO are assumed. If JUSTIFY is omitted, but attributes other than NUM are specified, LEFT and BLANK are assumed.

Note: If a field is initialized by an output map or contains data from any other source, data that is typed as input overwrites only the equivalent length of the existing data; surplus existing data remains in the field and could cause unexpected interpretation of the new data.

LENGTH

specifies the length (1–256 bytes) of the field or group of fields. This length is the maximum length required for application program data to be entered into the field; it does not include the 1 byte attribute indicator appended to the field by CICS for use in subsequent processing. The length of each individual subfield within a group must not exceed 256 bytes.

In general LENGTH can be omitted if PICIN or PICOUT is specified, unless PICOUT defines a COBOL picture containing a currency symbol that replaces a currency sign of length greater than 1. LENGTH is required otherwise. You can specify a length of zero only if you omit the label (field name) from the DFHMDF macro. That is, the field is not part of the application data structure and the application program cannot modify the attributes of the field. You can use a field with zero length to delimit an input field on a map.

The map dimensions specified in the SIZE operand of the DFHMDI macro defining a map can be smaller than the actual page size or screen size defined for the terminal.

If the LENGTH specification in a DFHMDF macro causes the map-defined boundary on the same line to be exceeded, the field on the output screen is continued by wrapping.

OCCURS

specifies that the indicated number of entries for the field are to be generated in a map, and that the map definition is to be generated in such a way that the fields are addressable as entries in a matrix or an array. This permits several data fields to be addressed by the same name (subscripted) without generating a unique name for each field.

OCCURS and GRPNAME are mutually exclusive; that is, OCCURS cannot be used when fields have been defined under a group name. If this operand is omitted, a value of OCCURS=1 is assumed.

OUTLINE

allows lines to be included above, below, to the left, or to the right of a field. You can use these lines in any combination to construct boxes around fields or groups of fields.

PICIN (COBOL and PL/I only)

specifies a picture to be applied to an input field in an IN or INOUT map; this picture serves as an editing specification that is passed to the application program, thus permitting the user to use the editing capabilities of COBOL or PL/I. BMS checks that the specified characters are valid picture specifications for the language of the map.

However, the validity of the input data is not checked by BMS or the high-level language when the map is used, so any wanted checking must be performed by the application program. The length of the data associated with “value” must be the same as that specified in the LENGTH operand if LENGTH is specified. If both PICIN and PICOUT are used, an error message is produced if their calculated lengths do not agree; the shorter of the two lengths is used. If PICIN or PICOUT is not coded for the field definition, a character definition of the field is automatically generated regardless of other operands that are coded, such as ATTRB=NUM.

As an example, assume that the following map definition is created for reference by a COBOL application program:

MAPX  DFHMSD  TYPE=DSECT,
              LANG=COBOL,
              MODE=INOUT
MAP   DFHMDI  LINE=1,COLUMN=1,
              SIZE=(1,80)
F1    DFHMDF  POS=0,LENGTH=30
F2    DFHMDF  POS=40,LENGTH=10,
              PICOUT='$$$,$$0.00'
F3    DFHMDF  POS=60,LENGTH=6,
              PICIN='9999V99',
              PICOUT='ZZ9.99'
      DFHMSD  TYPE=FINAL

This generates the following DSECT:

01  MAPI.
    02  F1L     PIC S9(4) COMP.
    02  F1A     PIC X.
    02  FILLER REDEFINES F1A.
     03  F1F    PIC X.
    02  F1I     PIC X(30).
    02  FILLER  PIC X.
    02  F2L     PIC S9(4) COMP.
    02  F2A     PIC X.
    02  FILLER REDEFINES F2A.
     03  F2F    PIC X.
    02  F2I     PIC X(10).
    02  FILLER  PIC X.
    02  F3L     PIC S9(4) COMP.
    02  F3A     PIC X.
    02  FILLER REDEFINES F3A.
     03  F3F    PIC X.
    02  F3I     PIC 9999V99.
    02  FILLER  PIC X.

01  MAPO REDEFINES MAPI.
    02  FILLER  PIC X(3).
    02  F1O     PIC X(30).
    02  FILLER  PIC X.
    02  FILLER  PIC X(3).
    02  F2O     PIC $$$,$$0.00.
    02  FILLER  PIC X.
    02  FILLER  PIC X(3).
    02  F3O     PIC ZZ9.99.
    02  FILLER  PIC X.

Valid picture values for COBOL input maps are:

A P S V X 9 / and (

Valid picture values for PL/I input maps are:

A B E F G H I K M P R S T V
X Y and Z
 
1 2 3 6 7 8 9 / + - , . *
$ and (

Refer to the appropriate language reference manual for the correct syntax of the PICTURE attribute.

Note: PL/I supports multiple currency signs and multi-character currency signs in PICTURE specifications.

The default currency picture symbol is the dollar sign ($), which represents the national currency symbol; for example the dollar ($), the pound (£), or the yen (¥).

The default currency picture symbol can be replaced by a currency string enclosed by less than (<) and greater than (>) symbols. For example:

DECLARE
    USPRICE PICTURE '$99.99',
    UKPRICE PICTURE '<£>99.99',
    EUPRICE PICTURE '<EUR>99.99';

PICOUT (COBOL and PL/I only)

is like PICIN, except that a picture to be applied to an output field in the OUT or INOUT map is generated.

Valid picture values for COBOL output maps are:

A B E P S V X Z 0 9 , . + - $
CR DB / and (

Valid picture values for PL/I output maps are:

A B E F G H I K M P R S T V
X Y and Z
 
1 2 3 6 7 8 9 / + - , . * $
CR DB and (

Refer to the appropriate language reference manual for the correct syntax of the PICTURE attribute.

Note: PL/I supports multiple currency signs and multi-character currency signs in PICTURE specifications.

The default currency picture symbol is the dollar sign ($), which represents the national currency symbol; for example the dollar ($), the pound (£), or the yen (¥).

The default currency picture symbol can be replaced by a currency string enclosed by less than (<) and greater than (>) symbols. For example:

DECLARE
    USPRICE PICTURE '$99.99',
    UKPRICE PICTURE '<£>99.99',
    EUPRICE PICTURE '<EUR>99.99';

Note: COBOL supports multiple currency signs and multi-character currency signs in PICTURE specifications.

The default currency picture symbol is the dollar sign ($), which represents the national currency symbol; for example the dollar ($), the pound (£), or the yen (¥).

The default currency picture symbol can be replaced by a different currency picture symbol that is defined in the SPECIAL NAMES clause. The currency sign represented by the picture symbol is defined in the same clause. For example:

SPECIAL NAMES.
CURRENCY SIGN IS '$' WITH PICTURE SYMBOL '$'.
CURRENCY SIGN IS '£' WITH PICTURE SYMBOL '£'.
CURRENCY SIGN IS 'EUR' WITH PICTURE SYMBOL '#'.

WORKING STORAGE SECTION.
01 USPRICE PIC $99.99.
01 UKPRICE PIC £99.99.
01 ECPRICE PIC #99.99.

LENGTH must be specified when PICOUT specifies a COBOL picture containing a currency symbol that replaces a currency sign of length greater than 1.

POS

specifies the location of a field. This operand specifies the individually addressable character location in a map at which the attribute byte that precedes the field is positioned.

number

specifies the displacement (relative to zero) from the beginning of the map being defined.

(line,column)

specify lines and columns (relative to one) within the map being defined.

The location of data on the output medium is also dependent on DFHMDI operands.

The first position of a field is reserved for an attribute byte. When supplying data for input mapping from non-3270 devices, the input data must allow space for this attribute byte. Input data must not start in column 1 but can start in column 2.

The POS operand always contains the location of the first position in a field, which is normally the attribute byte when communicating with the 3270. For the second and subsequent fields of a group, the POS operand points to an assumed attribute-byte position, ahead of the start of the data, even though no actual attribute byte is necessary. If the fields follow on immediately from one another, the POS operand points to the last character position in the previous field in the group.

When a position number is specified that represents the last character position in the 3270, 2 special rules apply:

ATTRIB=IC must not be coded. The cursor can be set to location zero by using the CURSOR option of a SEND MAP, SEND CONTROL, or SEND TEXT command.
If the field is to be used in an output mapping operation with MAP=DATAONLY on the SEND MAP command, an attribute byte for that field must be supplied in the symbolic map data structure by the application program.

PS

specifies that programmed symbols are to be used. This overrides any PS operand set by the DFHMDI macro or the DFHMSD macro.

BASE: is the default and specifies that the base symbol set is to be used.
psid: specifies a single EBCDIC character, or a hexadecimal code of the form X'nn', that identifies the set of programmed symbols to be used.

The PS operand is ignored unless the terminal supports programmed symbols, as indicated by PROGSYMBOLS(YES) on the RDO TYPETERM definition.

SOSI

indicates that the field can contain a mixture of EBCDIC and DBCS data. The DBCS subfields within an EBCDIC field are delimited by SO (shift out) and SI (shift in) characters. SO and SI both occupy a single screen position (normally displayed as a blank). They can be included in any non-DBCS field on output, if they are correctly paired. The terminal user can transmit them inbound if they are already present in the field, but can add them to an EBCDIC field only if the field has the SOSI attribute.

TRANSP

determines whether the background of an alphanumeric field is transparent or opaque, that is, whether an underlying (graphic) presentation space is visible between the characters.

VALIDN

specifies that:

validation is to be used on an 8775 terminal
this field can be processed by the BMS global user exits

This overrides any VALIDN operand on the DFHMDI macro or the DFHMSD macro.

MUSTFILL: specifies that the field must be filled completely with data. An attempt to move the cursor from the field before it has been filled, or to transmit data from an incomplete field, raises the INHIBIT INPUT condition
MUSTENTER: specifies that data must be entered into the field, though need not fill it. An attempt to move the cursor from an empty field raises the INHIBIT INPUT condition
TRIGGER: specifies that this field is a trigger field. Trigger fields are discussed in Trigger field support .
USEREXIT: specifies that this field is to be processed by the BMS global user exits, XBMIN and XBMOUT, if this field is received or transmitted in a 3270 datastream when the respective exit is enabled.

The MUSTFILL, MUSTENTER, and TRIGGER specifications are valid only for terminals that support the field validation extended attribute, otherwise they are ignored. The USEREXIT specification applies to all 3270 devices.

Note: The USEREXIT specification is unconnected with the field validation extended attribute as defined in the 3270 datastream architecture.

XINIT

see INITIAL, earlier in the list. Only one of GINIT, INITIAL, or XINIT can be specified.