DFHMSD

Mapset definition.

Syntax

DFHMSD

Note:

TRANSP is not supported by CICS® TX on Cloud, therefore ignored; see operand description for more information.

Description

A DFHMSD macro contains one or more map definition macros, each of which contains one or more field definition macros. It begins:

mapset DFHMSD TYPE=MAP  (or TYPE=DSECT)

and ends:

[mapset] DFHMSD TYPE=FINAL

mapset is the one- through seven-character name of the map set. For TYPE=FINAL, mapset is optional; but if used, it must be the same as that which is on the DFHMSD macro that began the map set. You cannot use DSATTS=YES if you specify DATA=BLOCK. Some BMS attributes (for example COLOR or OUTLINE) use the screen manipulation facilities (extended curses) that are provided by the underlying operating system on which the IBM® CICS Client is running. If the extended curses facility package does not support a particular attribute, it will be ignored. If a particular BMS attribute appears not to work, ensure first that it is supported by the extended curses facilities that are on the operating system on which the client is running.

Options

BASE

Specifies that the same storage base is used for the symbolic description maps from more than one map set. The same name is specified for each map set that is to share the same storage base. Because all map sets with the same base describe the same storage, data that is related to a previously used map set might be overwritten when a new map set is used. Different maps within the same map set also overlay one another.

This operand cannot be used when STORAGE=AUTO has been specified.

For example, assume that the following macros are used to generate symbolic description maps for:

MAPSET1 DFHMSD TYPE=DSECT,                        *
               TERM=3270,LANG=COBOL,              *
               BASE=DATAREA1,MODE=IN
MAPSET2 DFHMSD TYPE=DSECT,                        *
               TERM=3270,LANG=COBOL,              *
               BASE=DATAREA1,MODE=OUT
MAPSET3 DFHMSD TYPE=DSECT,                        *
               TERM=3270,LANG=PLI,                *
               BASE=DATAREA1,MODE=OUT

The symbolic description maps of this example might be referred to in a COBOL application program as follows:

LINKAGE SECTION.
01 DATAREA1 PIC X(1920).
      COPY MAPSET1.
      COPY MAPSET2.
   .
   .
EXEC CICS GETMAIN
          LENGTH(1000)
          SET(ADDRESS OF DATAREA1) INITIMG(0)
END-EXEC.

MAPSET1, MAPSET2, and MAPSET3 redefine DATAREA1, so the program can use the fields in only one of the symbolic description maps at a time.

If BASE=DATAREA1 is deleted from this example, the 01 DATAREA1 statement is not needed. The program could then refer to fields concurrently in both symbolic description maps.

The GETMAIN command should specify enough storage to contain the largest map of all those that share the same storage base. In this case, the programmer has decided that the largest map requires 1000 bytes of storage.

COLOR

Indicates the color that is to be used for all the maps in the map set. This color can be overridden for individual maps by the COLOR operand of the DFHMDI macro, which is in turn overridden for individual fields by the COLOR operand of the DFHMDF macro. If this operand is omitted, the default color for the output device is used.

When the map is displayed, the COLOR operand is ignored unless the terminal supports color.

color

Specifies the basic color that is to be used for all maps that are in the map set. 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 basic color for all maps that are in the map set.

CTRL

Specifies control actions that are to be performed when the map set is displayed. The use of any of the control options that are in the SEND MAP command overrides all control actions that are specified in the DFHMDI macro, which in turn override all control actions that are specified in the DFHMSD macro.

PRINT

Must be specified if the printer is to be started; if omitted, the data is sent to the printer buffer but is not printed. This operand is ignored if the map set is used with 3270 displays that do not have the Printer Adapter feature.

length

Indicates the line length that is used on the printer; it can be specified as:

L40
L64
L80
HONEOM

L40, L64, and L80 force a new line after 40, 64, and 80 characters respectively. HONEOM causes the default printer line length to be used. If the length value is omitted, BMS sets the line length to 64.

FREEKB

Specifies that the keyboard is to be unlocked after the map has been sent. If FREEKB is not specified, the keyboard remains locked; data entry from the keyboard is inhibited until this status is changed or the reset key is pressed.

ALARM

Specifies that the alarm feature is to be activated.

FRSET

Specifies that the Modified Data Tags (MDTs) of all fields that are currently in the terminal buffer are to be reset to the not-modified condition (that is, field reset) before any map data is written to the buffer. This allows the DFHMDF macro with the ATTRB operand to control the final status of any fields that are written or rewritten in response to a BMS command.

DATA

Specifies the format of the data. This parameter is supported only for compatibility with /390. The format of the data can be one of the following:

FIELD

Specifies that the data is passed as contiguous fields. This is the default. Each field has the format:

vv a datafield

where:

vv is a 16-bit value that specifies the data as input from the terminal (ignored in output processing).
a is an 8-bit value into which you can place an attribute that overrides the attribute that is specified in the map that is used to process this data (see copybook DFHBMSCA).
datafield represents the actual data.

BLOCK

DSATTS

Specifies the attribute types that are to be included in the symbolic description map. These types can be one or more of the following:

COLOR
HILIGHT
OUTLINE
PS
SOSI
TRANSP
VALIDN

Any type that is included in DSATTS should also be included in MAPATTS.

Note: TRANSP is supported only for application portability; it is ignored by CICS TX on Cloud.

EXTATT

This operand is supported for compatibility with early releases of IBM mainframe-based CICS. For new maps, the DSATTS and MAPATTS operands should be used instead.

If DSATTS or MAPATTS is specified in addition to EXTATT, the attribute types are combined. For example, EXTATT=MAPONLY and MAPATTS=SOSI is equivalent to MAPATTS=(COLOR,HILIGHT,PS,SOSI).

NO

Equivalent to specifying neither the DSATTS operand nor the MAPATTS operand.

YES

Equivalent to:

MAPATTS=(COLOR,HILIGHT,PS)
DSATTS=(COLOR,HILIGHT,PS)

MAPONLY

Equivalent to:

MAPATTS=(COLOR,HILIGHT,PS)

FOLD

This option is applicable only when you specify LANG=C. It specifies whether map and field names that are in the symbolic map are generated in uppercase or lowercase. The attributes can be:

LOWER: The default value. It specifies that names that are in the symbolic map are generated in lowercase.
You should use only FOLD=LOWER for maps that are translated for use with CICS TX on Cloud.
UPPER: Specifies that names that are in the symbolic map are generated in uppercase.
Note: All names that are in the BMS macros must be entered in uppercase for compatibility with IBM mainframe-based CICS.

HILIGHT

Specifies the default highlighting attribute for all fields in all maps that are in a map set. This is overridden by the HILIGHT operand of the DFHMDI macro, which is in turn overridden by the HILIGHT operand of the DFHMDF macro.

OFF: The default. It 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.
When the map is displayed, the HILIGHT operand is ignored unless the terminal supports highlighting.

LANG

Specifies the source language of the application programs into which the symbolic description maps that are in the map set are copied. If this operand is omitted, COBOL is assumed. For application portability, however, you should always code the LANG operand. The supported programming languages are COBOL, C, and C++.

MAPATTS

Specifies the attribute types that are to be included in the physical map. These types can be one or more of the following.

COLOR
HILIGHT
OUTLINE
PS
SOSI
TRANSP
VALIDN

This list must include all the attribute types that are to be specified for individual fields in the map (DFHMDF macro).

Note: TRANSP is supported only for application portability; it is ignored by CICS TX on Cloud.

MODE

Specifies whether the map set is to be used for input (IN), output (OUT), or both (INOUT).

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.

PS

Specifies that programmed symbols are to be used. This is overridden by the PS operand of the DFHMDI macro, which is in turn overridden by the PS operand of the DFHMDF macro.

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. CICS TX on Cloud supports a value of 8, which indicates that only Multi-Byte Character Set (MBCS) data can be contained in the field.

Note: For compatibility with maps that are generated on other CICS systems, the values X'F8' and X'38', specific to EBCDIC and ASCII systems, are supported. New maps should use the portable value 8.

If PS is specified but is not in the MAPATTS list for the map set, the BMS processor issues a warning message and adds PS to the MAPATTS list.

When the map is displayed, the PS operand is ignored unless the terminal supports programmed symbols.

SOSI

Indicates whether the user can enter Multi-Byte Character Set (MBCS) data into the field.

If SOSI is specified but is not in the MAPATTS list for the map set, the BMS processor issues a warning message and adds SOSI to the MAPATTS list.

STORAGE

The meaning of this operand depends on the language in which application programs are written, as follows:

For COBOL programs, STORAGE=AUTO specifies that the symbolic description maps that are in the map set are to occupy separate (that is, not redefined) areas of storage. This operand is used when the symbolic description maps are copied into the working storage section, and the storage for the separate maps that are in the map set is to be used concurrently.

For C or C++ programs, STORAGE=AUTO specifies that the symbolic description maps that are in the mapset are to be defined such that the compiler defines their storage. If STORAGE=AUTO is not specified, they are declared as pointers.

You cannot specify both BASE=name and STORAGE=AUTO for the same map set.

SUFFIX

The option specifies a one character user-defined device-dependent suffix for this map set, as an alternative to a suffix that is generated by the TERM option. See Table 1.

TERM

Specifies the type of terminal or logical unit (LU) that is associated with the map set. Permitted values for TERM are shown in Table 1.

Table 1. Suffix used for terminal types
Type	Columns	Suffix
3270	80	M
3270-1	40	L
3270-2	80	M

TIOAPFX

Specifies that BMS should include a filler in the symbolic description maps to allow for the unused Terminal Input/Output Area (TIOA) prefix that occurs with command-level application programs. If this operand is not specified, the BMS processor issues a warning message and assumes TIOAPFX=YES. For application portability, however, always code it.

Note: TIOAPFX can be set to YES or NO if -a command option is mentioned. The generated maps would be similar to that of CICS TS if TIOAPFX is set toNO.

TRANSP

This operand is not supported by CICS TX on Cloud and should not be used in applications that are developed to run under CICS TX on Cloud.

TYPE

Specifies the type of map (symbolic description or physical) that is to be generated through use of the definition. Both types of map must be generated before the mapset can be used by an application program.

For further details, see Coding BMS map sets using BMS macros.

TYPE is also used to specify the end of a map set definition.

DSECT: Specifies that a symbolic description map is to be generated. Symbolic description maps must be copied into the source program before it is translated and compiled.
FINAL: Specifies the end of a map set definition.
MAP: Specifies that a physical map is to be generated. Physical maps must be processed and added to the CICS maps directory before an application program can use them.
Note: This option is included for compatibility with IBM mainframe-based CICS systems, but the production of symbolic and physical maps can be more easily controlled on CICS TX on Cloud by the cicsmap -p and -s command line options.

VALIDN

specifies that validation is to be used on an 8775 terminal. This is overridden by the VALIDN operand of the DFHMDI macro, which is in turn overridden by the VALIDN operand of the DFHMDF macro.

CICS TX on Cloud does not support this operand for all terminal types, so it is not recommended that you use it.

MUSTFILL: Specifies that the field must be filled completely with data. An attempt to move the cursor from the field before it has been filed, or to transmit data from an incomplete field, causes the inhibit input condition.
MUSTENTER: Specifies that data must be entered into the field, although it need not fill the field. An attempt to move the cursor from an empty field causes the inhibit input condition.
TRIGGER: Specifies that this field is a trigger field.