Field definition.

The DFHMDF macro defines a field within a map that is defined by the DFHMDI macro.
A map contains zero or more fields.

Description

Note:

TRANSP is ignored on TXSeries for Multiplatforms; see operand description for more information.

The fld option is the name of the field.
It can contain 1 through 30 characters.

If the fld option is omitted, application programs cannot access the field to change its attributes or change its contents.
For an output map, omitting the field name can be appropriate when the INITIAL operand is used to specify the contents of a field or to switch off the effect of a previous attribute byte.
If a field name is specified and the map that includes the field is used in a mapping operation, non null data that is supplied by the user overlays data that is supplied by initialization (unless only default data is being written).

Optimize the performance of input-mapping operations by arranging DFHMDF macros in numeric sequence of the POS operand.

You cannot define more than 1023 named fields for a COBOL, C, C++, or PL/I program.

Ensure that the names of fields within a mapset (or within multiple mapsets that are copied into one application program) are unique.
Before CICS can load a physical map, you must define the map by creating a Program Definition entry with the ProgType attribute set to map.

Operands

• ATTRB
  • Specifies field characteristics and attributes, such as the field's capacity to receive data or the intensity to be used when the field is output.
    Also, use it to prevent data in an input field from being displayed, for example, for secure entry of a password from a screen.
  • If ATTRB is specified for a group of fields, it must be specified in the first field entry.
    The ATTRB specification refers to all the fields in a group as one field rather than as individual fields.

• ASKIP
  • Specifies that data cannot be keyed into the field and causes the cursor (current location pointer) to skip over the field.

• PROT
  • Specifies that data cannot be keyed into the field.

• UNPROT
  • Specifies that data can be keyed into the field.

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

• BRT
  • Specifies that the field is displayed in high intensity. By virtue of the 3270 attribute character bit assignments, a field specified as BRT is also potentially detectable, although detectable fields are not supported by TXSeries for Multiplatforms.

• NORM
  • Specifies that the field is displayed in normal intensity.

• DRK
  • Specifies that the field is not printed or displayed.

• DET
  • Specifies that the field is potentially detectable.
    This attribute value is ignored by TXSeries for Multiplatforms.

• IC
  • Specifies that the cursor is to be placed in the first position (after the attribute byte) of the field.
    The IC attribute that takes effect is the one that is specified for the last field in a map. 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 a field that cannot be keyed.
  • ATTRB=IC can be overridden by the CURSOR option of the SEND MAP command that causes the write operation.

• FSET
  • Specifies that the Modified Data Tag (MDT) for this field is set when the field is sent to a terminal.
  • Specification of FSET causes the 3270 to handle the field as though it has been modified.
    On a subsequent read from the terminal, this field is read, whether or not 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 that is to be displayed on a 3270 system is being defined, but not all attributes are specified.
    If no ATTRB values are specified, ASKIP and NORM are assumed.
    If any value is specified, UNPROT and NORM are assumed for that field unless overridden by a specified value.

• CASE
  • Specifies that the field contains lowercase data that is to be converted to uppercase on output, if the terminal is capable of displaying Multi-Byte Character Set (MBCS) characters (that is, if the Katakana attribute in the Terminal Definitions (WD) is set to yes).
  • CASE=MIXED should be specified if a field is known to contain lowercase Latin characters but might possibly be displayed on a Katakana display.
    It must not be specified if the field can contain valid Katakana characters.

• COLOR
  • Indicates the color that is to be used for the named field.
    This overrides the COLOR operands of the DFHMSD and DFHMDI macros.
  • If this operand is omitted, the field color is taken from the COLOR operand of the DFHMDI macro.
  • If COLOR is specified but is not in the (effective) MAPATTS list for the map, the BMS processor issues a warning message and ignores the operand.
  • The COLOR operand is ignored unless the terminal supports color.
    • color
      • Specifies the color that is to be used for this field.
        The valid colors are:
        • BLUE, GREEN, NEUTRAL, PINK, RED, TURQUOISE, YELLOW.
    • DEFAULT
      • Specifies that the default color for the output device is to be used as the color for this field.

• GINIT
  • Specifies, in graphic form, constant or default data for an output field.
  • Only one of INITIAL, XINIT, or GINIT can be specified.
  • Use INITIAL to specify data in character form; use XINIT to specify data in hexadecimal form.
  • Use GINIT with fields that also use the PS=8 operand.

• GRPNAME
  • The character name that is used to generate symbolic storage definitions and to combine specific fields under one group name.
  • It can be 1 through 30 characters.
  • The same group name must be specified for each field that is to belong to the group.
  • If this operand is specified, the OCCURS operand cannot be specified.
  • For more information about field groups, see Defining field groups.

• HILIGHT
  • Specifies the default highlighting attribute for the named field.
    This overrides the HILIGHT operands of the DFHMSD and DFHMDI macros.
  • If HILIGHT is specified but is not in the (effective) MAPATTS list for the map, the BMS processor issues a warning message and ignores the operand.
  • The HILIGHT operand is ignored unless the terminal supports highlighting.
    • OFF
      • Is the default and indicates that no highlighting is used.
    • BLINK
      • Specifies that the field must blink.
    • REVERSE
      • Specifies that the character or field is displayed in reverse video.
    • UNDERLINE
      • Specifies that a field is underlined.

• INITIAL
  • Specifies, in character form, constant or default data for an output field.
  • Only one of INITIAL, XINIT, or GINIT can be specified.
  • Use XINIT to specify data in hexadecimal form; use GINIT to specify data in graphic form.
  • The number of characters that you can specify in the INITIAL operand is restricted to the value that is specified in the LENGTH operand.

• LENGTH
  • Specifies the length (in the range 0 through 256 bytes) of the field.
  • This length is the maximum length that is required for application program data to be entered into the field; do not include the one-byte attribute indicator that is included in the field by CICS for use in subsequent processing.
  • LENGTH is required unless the PICOUT option is specified.
  • If PICOUT is specified and LENGTH is not, the LENGTH value is calculated from the computed value of PICOUT.
  • However, a warning message appears any time LENGTH is calculated in this way because the resulting value can be incorrect for your application.
  • For example, if a sequence of characters such as "EUR" is used as the CURRENCY SYMBOL in COBOL, and you do not set LENGTH to an appropriate value, the resulting LENGTH that is calculated from the PICOUT value is incorrect because the calculation assumes that the currency symbol needs only one character.
  • 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.
  • See LENGTH for more information about using this option.
  • Note:
    • Although lines are allowed to wrap, they are not permitted to wrap from bottom to top.

• 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 so 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 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 group fields.
    • BOX
      • Constructs a box around the field.
    • LEFT
      • Puts a line to the left of the field.
    • RIGHT
      • Puts a line to the right of the field.
    • OVER
      • Puts a line at the top of the field.
    • UNDER
      • Puts a line at the bottom of the field.

• 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 that is being defined.
    • (line,column)
      • Specifies lines and columns (relative to one) within the map that is 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.
  • 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 a 3270 device.
  • 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, although no actual attribute byte is necessary.
  • If the fields follow immediately from one another, the POS operand should point to the last character position of the previous field in the group.
  • When a position number is specified that represents the last character position in the 3270 screen, two special rules apply:
    1. ATTRB=IC should not be coded. The cursor can be set to location zero by using the CURSOR option of the SEND MAP or SEND CONTROL command.
    2. If the field is to be used in an output mapping operation with the DATAONLY option 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 the PS operands of the DFHMSD and DFHMDI macros.

• BASE
  • Specifies that the base symbol set is to be used.
    • psid
      • Specifies a single character that identifies the set of programmed symbols that is to be used.
      • TXSeries for Multiplatforms supports a value of 8, which indicates that a field can contain only Multi-Byte Character Set (MBCS) data.
  • Note:
    • For compatibility with maps that are generated on other CICS systems, the values X'F8' and X'38', which are specific to EBCDIC and ASCII systems, are supported.
    • New maps should use the portable value8.
  • If PS is specified but is not in the (effective) MAPATTS list for the map, the BMS processor issues a warning message and ignores the operand.
  • The PS operand is ignored unless the terminal supports programmed symbols.

• SOSI
  • Indicates whether Multi-Byte Character Set (MBCS) data can be entered into the field by the user.
  • The MBCS subfields within an ASCII field are delimited by emulated SO (shift out) and SI (shift in) characters.
  • If a mixed string is sent to a host CICS system during transaction routing, SO and SI characters are inserted during the conversion from ASCII to EBCDIC. Because SO and SI both occupy character positions, the corresponding strings are of different lengths.
  • If the original field was full, the field overruns on the host, and data at the end of the string is lost.
  • If SOSI is specified but is not in the (effective) MAPATTS list for the map, the BMS processor issues a warning message and ignores the operand.

• TRANSP
  • This operand is not supported by TXSeries for Multiplatforms.
  • Do not use it in applications that are developed to run under TXSeries for Multiplatforms.
  • However, if this operand is present (for example, in a migrated map) the BMS processor issues a warning message and ignores it.
  • Generation of the map continues; the usability of the map is not affected.

• VALIDN
  • Specifies that validation is to be used on an 8775 terminal.
  • This overrides the VALIDN operand of the DFHMDF macro, which, in turn, overrides the VALIDN operand of the DFHMDI macro.
  • TXSeries for Multiplatforms do not support this operand for all terminal types, so its use is not recommended.
    • 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, although the data does not need to 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.

• XINIT
  • Specifies, in hexadecimal form, constant or default data for an output field.
  • Only one of INITIAL, XINIT, and GINIT can be specified. Use INITIAL to specify data in character form; use GINIT to specify data in graphic form.
  • Hexadecimal data appears as even numbers of hexadecimal digits (for example, XINIT=4142).
  • If the number of valid characters is smaller than the field length, the data is padded on the right with blanks.
  • For example, XINIT=4142 results in an initial field of "AB".
  • If specified hexadecimal data corresponds with line-; or format-control characters, the results are unpredictable.
  • Use the XINIT operand with care.
  • If the hexadecimal values have been migrated from a non-CICS on Open Systems or non-CICS for Windows system, you possibly need to use cicsmap -e to convert them into the code page that is used by TXSeries for Multiplatforms.
  • See the TXSeries for Multiplatforms Application Programming Guide for details.