Writing Map Source Code

This chapter describes the IBM assembler macro format used to write map source codes.

1. Map Writing Rules

In a map source code, multiple fields, maps, and mapsets can be defined.

A mapset is a set of maps, and a map is a set of fields. Descriptions for each are as follows:

Category Description

Field

An individual item displayed on the terminal. Each field is made up of attributes and their values. Users can define default values in the map source code or new values in the application.

Map

One full screen displayed on the terminal. In the map, users can define common attributes that affect all fields present in that map. Keywords that apply to all fields in a map will be overridden by keywords for specific fields, but will override keywords for the entire mapset.

Mapset

A logical concept that refers to a set of maps. A mapset must contain at least one map definition in addition to common attributes that affect all of the maps and fields in the mapset. Keywords that apply to an entire mapset will be overridden by keywords for individual maps or fields.

Since the map source codes are written in the IBM assembler macro format, they must follow the syntax and constraints for that format. In addition to syntax rules, map source code must follow the following.

  • The name (field name, map name, or mapset name) is entered beginning at the first column. Map and mapset names can be a maximum of seven characters long. Although the field name can be longer than seven characters, its length cannot exceed the maximum variable name length permitted by the programming language used by the application program that will read the map. For COBOL, the limit is 29 bytes.

  • Map commands can be entered starting at the tenth column. Each map command must start with one of the following three macros.

    Macro Description

    DFHMDF

    Declares a field.

    DFHMDI

    Declares a map.

    DFHMSD

    Declares a mapset.

  • Keywords can come after each macro. Keywords are delimited from the macro command with a blank area. The list of keywords available for each macro is given in section Macro Keywords.

  • Keywords are separated by commas; no spaces are allowed between them.

  • A keyword that gets option values is linked to them with an equals (=) sign. If the option value permits multiple attributes, parentheses ((, )) must be placed around the list of attributes. Commas must be used to separate each option; no spaces are allowed between them.

  • Keyword information can be entered until the 71st column. If more columns are needed, the row can be split by inserting a comma (to indicate the end of an option) and then inserting any character (other than a space) in the 72nd column. This indicates that the keyword continues in the next row. Continue entering the keyword, starting at the 16th column of the next row.

  • When an option of a keyword (INITIAL, XINIT, GINIT) that gets field initialization values must be split in the middle, the rule described previously does not apply. For these cases, do not enter a comma; instead, enter characters until the 71st column and enter any character (other than a space) in the 72nd column. Continue entering the initialization value, starting at the 16th column of the next row.

  • Initial values must be enclosed in single quotation marks. The MAP compiler interprets single quotation mark(') and parentheses(()) as special characters and ignores them if they are used in a value. To escape a special character, double the character. For example, use two single quotation marks ('') to represent a single quotation mark.

  • To comment a row, add the asterisk (*) in the first column. Then, the columns from the second to 71st can be used for user comments.

  • All keywords and option values, with the exception of initial values, must be capital letters only.

2. Macro Keywords

This section describes keywords that can be used with the DFHMDF, DFHMDI, and DFHMSD macros.

2.1. DFHMDF

The DFHMDF macro command defines a map field.

  • ATTRB

    • Specifies a field’s attributes.

    • There are three groups of ATTRB fields, and only one attribute can be specified from each group. The groups are: (ASKIP,PROT,(UNPROT{,NUM})), (BRT,NORM,DRK), and (DET,IC,FSET).

      Option Description

      ASKIP

      Disables the cursor for the field. If the user tries to move the cursor to the field, the cursor will automatically jump to the next field. This option cannot be used with the PROT or UNPROT attributes.

      PROT

      Protects the value(s) in the field. This option cannot be used with the DRK or NORM attributes.

      UNPROT

      Enables the cursor for the field and allows the value(s) in the field to be changed. This option cannot be used with the ASKIP or PROT attributes.

      NUM

      Allows only numbers to appear in the field. The NUM attribute can only be used when UNPROT is specified.

      BRT

      Makes the field brighter. This option cannot be used with the DRK or NORM attributes.

      NORM

      Displays the field with normal brightness. This option can be omitted and cannot be used with the BRT or DRK attributes.

      DRK

      Hides the field from the screen (makes it dark). This option cannot be used with the BRT, NORM, or DET attributes.

      DET

      Sets the field to 'detectable'. This option cannot be used with the DRK attribute.

      IC

      Sets the cursor location to be shown in the field. If several fields have the IC attribute set, the IC attribute of the last field takes precedence.

      FSET

      Sets the field’s modified data tag (MDT) bit.

  • CASE

    • If KATAKANA is set to YES in the TYPETERM definition of a terminal, whether English lowercase letters will be used in a field must be set.

    • To allow lowercase letters to be entered in a field, use the MIXED keyword. To use katakana characters, MIXED does not need to be set.

      The keyword KATAKANA is used to define a resource named TYPETERM (which is one of CICS resources), not used in Map. In the EBCDIC code used by the mainframe, katakana characters and English lowercase letters share the same area so at a Japanese terminal, English lowercase letters can be displayed in katakana. To prevent this, all English lowercase letters and any data in the area are converted into capital letters through system settings. These settings include MSGCASE=UPPER in the SIT file (System Initialization Table, CICS configuration file) and KATAKANA=YES in the TYPETERM resource definition for the terminal to which data is displayed. Therefore, to use both katakana characters and English lowercase letters, CASE must be set to MIXED.

  • COLOR

    • Sets the font color of the field.

    • Users can choose one of the following: DEFAULT, BLUE, RED, PINK, GREEN, TURQUOISE, YELLOW, or NEUTRAL.

  • GINIT

    • Sets the default value of the field.

    • Wrap a character string (default value) with single quotation marks (', ').

    • Only two-byte letters can be input. Spaces that represent SO and SI must be added before and after the two-byte value. When the graphic data type is used (PS=X’F8’), a PIC G type variable is created. This keyword cannot be used with the INITIAL and XINIT keywords.

  • HILIGHT

    • Specifies the highlight attribute of the field.

    • One of the following options can be chosen.

      Option Description

      OFF

      Highlighting is not used.

      BLINK

      Makes the field blink.

      REVERSE

      Reverses, or inverts, the field colors. For example, green letters on a black background would be changed to black letters on a green background.

      UNDERLINE

      Underlines the field data.

  • INITIAL

    • Sets the field’s default value.

    • Character strings must be surrounded with single quotation marks.

    • This keyword cannot be used with the GINIT and XINIT keywords.

      Both one-byte and two-byte letters can be input with INITIAL, while only two-byte letters can be entered with GNIT. If a one-byte letter is used for GNIT, an error occurs in the map conversion process, making normal data output impossible.

  • JUSTIFY

    • Arranges the data entered in the field.

    • The options are as follows:

      Option Description

      LEFT

      Uses left-justification for the field. Unless BLANK or ZERO are specified, the BLANK option is applied together by default.

      RIGHT

      Uses right-justification for the field. Unless BLANK or ZERO are specified, the ZERO option is applied together by default.

      BLANK

      Inserts blanks in empty locations. Unless LEFT or RIGHT are specified, the LEFT option is applied together by default.

      ZERO

      Inserts zeros in empty locations. Unless LEFT or RIGHT are specified, the RIGHT option is applied together by default.

      LEFT cannot be used together with RIGHT, and BLANK cannot be used together with ZERO. A common use for RIGHT and ZERO is in fields where the NUM attribute has been specified; LEFT and BLANK are usually used for fields where NUM has not been specified.

  • LENGTH

    • Specifies the length of the field.

    • The length can be a number between 1 and 256.

    • When PICIN and PICOUT are given, LENGTH does not need to be specified.

    • If the field’s name is not given, the length can be specified as 0.

    • In this case, the field’s contents cannot be accessed by programs since the field was not included when the symbolic map was created.

  • OUTLINE

    • Specifies one or more borders (outlines) for a field.

    • Any combination of LEFT, RIGHT, OVER, and UNDER can be chosen.

    • The BOX setting is equivalent to all four borders.

  • PICIN

    • Specifies the data type to be used when the field is sent to the application.

    • When PICIN and PICOUT are defined together and LENGTH is undefined, the length of the data type specified in PICIN must match with that specified in PICOUT. Otherwise, an error will occur.

  • PICOUT

    • Specifies the data type to be used when the field is sent from the application to the terminal.

  • POS

    • Designates the location in the terminal where the POS field will be displayed.

    • This can be designated by a number or by a [line, column] format.

    • When using a number, it is set as a relative address starting from 0. For example, in the 80*24 screen, the location of the third row and the fourth column becomes 80 x (3-1) + (4-1)=163.

  • PS

    • Decides whether or not to use Programmed Symbols.

    • The Programmed Symbol IDs can be given as one-byte characters or in the X’nn’ form. If the PS keyword is set as BASE, the basic symbol set is used.

  • SOSI

    • Indicates that the field can be a mixture of one-byte characters and two-byte characters.

  • TRANSP

    • Sets whether the background of the field is transparent or not.

  • XINIT

    • Sets the default value of a field using hexadecimal values.

    • Do not use single quotation marks here. This keyword cannot be used together with the GINIT or INITIAL keywords.

  • OCCURS

    • Creates the specified number of fields. Created fields can be accessed with the same name using subscripts.

2.2. DFHMDI

The DFHMDI macro command defines a map. Keywords in DFHMDI macro commands will be overridden by individual keywords in DFHMDF macro commands. The following keywords can be specified for the DFHMDI macro command.

  • COLOR

    • Specifies the basic color of a map.

    • Users can choose one of the following: DEFAULT, BLUE, RED, PINK, GREEN, TURQUOISE, YELLOW, or NEUTRAL.

    • COLOR for DFHMDF is already set; the color set for DFHMDF is preferred.

  • CTRL

    • Sets characteristics of maps.

    • One of the following options can be entered.

      Option Description

      PRINT

      Prints transferred map data.

      LENGTH

      Sets the maximum number of characters for a row transferred to a printer.

      FREEKB

      Releases the keyboard lock when transferring maps.

      ALARM

      Sends an alarm if an alarm is set in the TN3270 terminal.

      FRSET

      Resets the MDT bits of all fields included in maps when transferring maps.

  • CURSLOC

    • Sets the flag value of the field where the cursor of the input map is located to X'02'.

  • HEADER

    • Pins the map at the top of the page when the SEND MAP ACCUM command is used.

  • HILIGHT

    • Specifies the basic highlight attributes of a map.

    • HILIGHT for DFHMDF is already set; the HILIGHT set for DFHMDF is preferred.

    • One of the following options can be entered.

      Option Description

      OFF

      Does not use highlighting.

      BLINK

      Makes the field blink.

      REVERSE

      Reverses, or inverts, the field colors. For example, green letters on a black background would be changed to black letters on a green background.

      UNDERLINE

      Underlines the field data.

  • OUTLINE

    • Specifies one or more borders (outlines) for map fields.

    • Any combination of LEFT, RIGHT, OVER, and UNDER can be chosen.

    • The BOX setting is equivalent to all four borders.

    • OUTLINE for DFHMDF is already set; the borders set for DFHMDF is preferred.

  • PS

    • Decides whether or not to use Programmed Symbols for map fields.

    • The Programmed Symbol IDs can be given as one-byte characters or in the X’nn' form. If the PS keyword is set as BASE, the basic symbol set is used.

    • PS for DFHMDF is already set; the PS set for DFHMDF is preferred.

  • SOSI

    • Indicates that the field can be a mixture of one-byte characters and two-byte characters.

    • SOSI for DFHMDF is already set; the SOSI set for DFHMDF is preferred.

  • TRAILER

    • Pins the map at the bottom of the page when the SEND MAP ACCUM command is used.

  • TRANSP

    • Sets whether the backgrounds of all fields included in maps are transparent or not.

2.3. DFHMSD

The DFHMSD macro command defines a mapset. Keywords in the DFHMSD macro command will be overridden by keywords in DFHMDI and DFHMDF macro commands. The following keywords can be specified for the DFHMSD macro command.

  • COLOR

    • Specifies the basic color for the mapset.

    • Users can choose one of the following: DEFAULT, BLUE, RED, PINK, GREEN, TURQUOISE, YELLOW, or NEUTRAL.

    • COLOR for DFHMDF or DFHMDI is already set; the color set for DFHMSD has the lowest priority.

  • CTRL

    • Sets characteristics of all maps included in mapsets.

    • One of the following options can be entered.

      Option Description

      PRINT

      Prints transferred map data.

      LENGTH

      Sets the maximum number of characters for a row transferred to a printer.

      FREEKB

      Releases the keyboard lock when transferring maps.

      ALARM

      Sends an alarm if an alarm is set in the TN3270 terminal.

      FRSET

      Resets the MDT bits of all fields included in maps when transferring maps.

  • HILIGHT

    • Specifies the basic highlight attribute for the mapset.

    • HILIGHT for DFHMDF or DFHMDI is already set; the HILIGHT set for DFHMSD has the lowest priority.

    • One of the following options can be entered.

      Option Description

      OFF

      Does not use highlighting.

      BLINK

      Makes the field blink.

      REVERSE

      Reverses, or inverts, the field colors. For example, green letters on a black background would be changed to black letters on a green background.

      UNDERLINE

      Underlines the field data.

  • LANG

    • Sets what language is used in the mapset.

    • Users can choose one of the following: COBOL or PCI. When COBOL is not specified, a symbolic map will not be created in a compilation.

  • MODE

    • Sets the input/output mode of the mapset. The value can be IN, OUT or INOUT – [IN|OUT|INOUT].

  • OUTLINE

    • Specifies one or more borders (outlines) for fields in the mapset.

    • Any combination of LEFT, RIGHT, OVER, and UNDER can be chosen.

    • The BOX setting is equivalent to all four borders.

    • OUTLINE for DFHMDF or DFHMDI is already set; the borders set for DFHMSD have the lowest priority.

  • PS

    • Decides whether or not to use Programmed Symbols for fields in the mapset.

    • The Programmed Symbol IDs can be given as one-byte characters or in the X’nn’ form. If the PS keyword is set as BASE, the basic symbol set is used.

    • PS for DFHMDF or DFHMDI is already set; the PS set for DFHMSD has the lowest priority.

  • SOSI

    • Indicates that the field can be a mixture of one-byte characters and two-byte characters.

    • SOSI for DFHMDF or DFHMDI is already set; the SOSI set for DFHMSD has the lowest priority.

  • TRANSP

    • Sets whether the backgrounds of all fields included in mapsets are transparent or not.

  • TYPE

    • One of the following options can be specified.

      Option Description

      MAP

      Indicates the start of mapset definition.

      DSECT

      Indicates the start of mapset definition.

      FINAL

      Indicates the end of mapset definition. If it is set, other additional attributes cannot be specified.

    • MAP and DSECT allow spaces and currently work the same.