Batch Compiler Statements › Statements for Manual Panel Definition › MAP Statement Syntax

MAP Statement Syntax

Functions Performed

A MAP statement typically is used to perform the following functions:

• Create or maintain a map occurrence in the data dictionary
• Identify the map occurrence with a unique combination of name and version number
• Identify the existing panel occurrence on which the map is based
• Identify the records or roles referenced by map data fields
• Enable global automatic editing and error-handling, specifying correct-field and incorrect-field attributes
• Specify various terminal hardware control functions (such as alarm or numeric options) to be invoked during mapout operations

The actual map is constructed with MFLD statements, presented later in this section, by selecting fields from the panel occurrence named in the MAP statement and by associating the variable panel fields with record elements defined in the data dictionary.

►►──┬──────────┬─ MAP map-name ──┬───────────────────────────────┬────────────►
    ├─ ADD ────┤                 └─ VERsion ─┬──────┬─ version ──┘
    ├─ MODIFY ─┤                             ├─ IS ─┤
    └─ DELETE ─┘                             └─ =  ─┘

 ►──┬────────────────────────────────────────┬────────────────────────────────►
    └─ DATETIME ─┬──────┬─ date-time-stamp ──┘
                 ├─ IS ─┤
                 └─ =  ─┘

 ►──┬─────────────────────────────────────────────┬───────────────────────────►
    └─ MSG PREFIX ─┬──────┬───┬──── DC ◄ ─────────┤
                   ├─ IS ─┤   └─ message-prefix ──┘
                   └─ =  ─┘

 ►──┬─────────────────────────────────────────────────────────────────┬───────►
    └─ PANel ─┬──────┬─ panel-name ─┬───────────────────────────────┬─┘
              ├─ IS ─┤              └─ VERsion ─┬──────┬─ version ──┘
              └─ =  ─┘                          ├─ IS ─┤
                                                └─ =  ─┘
 ►──┬────────────────────────────────┬─────┬─ RESident ──────┬────────────────►
    └─ SYStem ─┬──────┬─ dc-version ─┘     └─ NONRESident ◄ ─┘
               ├─ IS ─┤
               └─ =  ─┘

 ►──┬─────────────────────────────────────────────────────────────────────────►
    └─ USING ─┬──────────────┬────────────────────────────────────────────────
              └┬─ RECORDS ─┬─┘
               └─ REC ─────┘
 ►─────────────────────────────────────────────────────────────────────────┬──►
            ┌──────────────────────────────────────────────────────┐       │
  ────── ( ─▼─ record-name ─┬───────────┬─┬──────────────────────┬─┴── ) ──┘
                            └─ version ─┘ └─ ROLEname role-name ─┘

 ►──┬── EDIT ◄ ─┬──┬────────────────────────────┬─────────────────────────────►
    └─ NOEDIT ──┘  └─ CURSOR at panel-field-name ─┘

 ►──┬─────────────────────────────┬───┬───────────────────────────────┬───────►
    ├─ RESET ◄ ─┬─┬──────────────┬┘   ├─ LOCK ────┬─┬───────────────┬─┘
    └─ NORESET ─┘ └┬─ MODIFIED ─┬┘    └─ UNLOCK ◄─┘ └┬─ KEYBOARD ─┬─┘
                   └─ MOD ──────┘                    └─ KEY ──────┘

 ►──┬─ ALARM ────┬──┬─ STARTPRT ─┬──┬─ NLCR ◄ ┬──┬─ PAGeable ─────┬───────────►
    └─ NOALARM ◄ ┘  └─ NOPRT ◄ ──┘  ├─ 40CR   │  └─ NONPAGeable ◄ ┘
                                    ├─ 64CR   │
                                    └─ 80CR ──┘
 ►──┬──────────────────────────────────────────┬──────────────────────────────►
    └─ DECimal point ─┬──────┬───┬─ Comma ───┬─┘
                      ├─ IS ─┤   └─ Period ◄ ┘
                      └─ =  ─┘

 ►─┬──────────────────────────────────────────────────────────────────────────►
   └─ HELP ─┬─ NO ────────────────────────────────────────────────────────────
            └─ LOAD MODule ─┬──────┬─ module-name ────────────────────────────
                            ├─ IS ─┤
                            └─ =  ─┘

─►────────────────────────────────────────────────────────────────────────────►─
 .────────────────────────────────────────────────────────────────────────────
  ─┬──────────────────────────────────────────────────────────────────────────
   └─ SOUrce ─┬─ NONE ────────────────────────────────────────────────────────
              └─ MODule module-name ─┬───────────────────────────────┬────────
                                     └─  version ─┬──────┬─ version ─┘
                                                  ├─ IS ─┤
                                                  └─ =  ─┘
─►──────────────────────────┬─────────────────────────────────────────────────►
  ────────────────────────┬─┘
  ──────────────────────┬─┘
  ────────────────────┬─┘
  ─┬─ HALF screen ◄ ┬─┘
   └─ FULL screen ──┘

 ►────────────────────────────────────────────────────────────────────────────►─
  ────────────────────────────────────────────────────────────────────────────
  ─┬─────────────────────────────┬────────────────────────────────────────────
   └─ HELPKEY ─┬──────┬── PFnn ──┘
               ├─ IS ─┤
               └─ =  ─┘
 ►─┬──────────────────────────────────────────────────────────────────────────►
   └─ ON edit ERROR ──┬─────────────────────────────────────────────────────┬─
                      └─ INCORRECT fields ATTRibutes = ( attributes-list ) ─┘

 ►────────────────────────────────────────────────────────────────────────────►
  ─┬───────────────────────────────────────────────────┬──────────────────────
   └─ CORRECT fields ATTRibutes = ( attributes-list ) ─┘

 ►────────────────────────────┬───────────────────────────────────────────────►
  ─┬────────────────────────┬─┘
   └─ SOUND ─┬─ ALARM ────┬─┘
             └─ NOALARM ◄ ┘

 ►─┬─────────────────────────────────────────────────────────────────────┬ . ─►◄
   └─ ORIGIN for ─┬─ ALL ─────────────────────┬─┬──────┬─( row  column )─┘
                  │     ┌───────────────┐     │ ├─ IS ─┤
                  └─ ( ─▼─ device-code ─┴─ ) ─┘ └─ = ──┘

Parameters

ADD/MODIFY/DELETE

Specifies the action taken with regard to the MAP statement. ADD, MODIFY, and DELETE access for a map is subject to security restrictions specified for the batch compiler and individual maps, as outlined in "Compiler Security".

MAP map-name

Specifies the unique 1- through 8-character name for the map being defined, modified, or deleted. The following considerations apply to the composition of map-name:

• Map-name can consist of any alphanumeric or special characters.
• Map-name must begin with an alphanumeric or national character; for example, pound sign (#), at sign (@), or dollar sign ($).
• Map-name must not contain embedded period or blank characters.

VERSION IS version-n

Optionally specifies a version number to further identify the map. Version-n must be in the range 1 through 9999. If omitted, version-n defaults to the data dictionary version default, as defined by the Data Dictionary Definition Language (DDDL) SET OPTIONS statement.

DATETIME IS date-time-stamp

The map compiler DATETIME clause is returned in map source statements when you use the map utility to decompile a map.

If you use the DATETIME option to decompile a map from one DC system and add it to another system:

• Do not change decompiled map source statements. If you change statements, unpredictable errors will occur at runtime when you access the map.
• Define identical record element descriptions on each system. You can accomplish this by using IDD.

MSG PREFIX IS message-prefix

Defines the two-character prefix to be used as the default prefix for any MFLD in the map that is defined using the ERROR MESSAGE clause.

PANEL panel-name

Specifies the name of the panel with which the map is associated. The panel occurrence must already be defined in the data dictionary.

VERsion is version

Optionally specifies a version number to further identify the panel occurrence. If omitted, version defaults to the data dictionary version default as defined by the Data Dictionary Definition Language (DDDL) SET OPTIONS statement.

SYSTEM IS dc-version-n

Specifies the version number of a CA IDMS system with which the map is associated. Dc-version-n is the 1- through 4-character identifier assigned to the system at system generation.

RESIDENT/NONRESIDENT

Indicates whether the map load module is resident in storage at system runtime:

• RESIDENT specifies that the map load module is resident. This is useful for frequently used maps.
• NONRESIDENT (default) specifies that the map load module is not resident; the load module is loaded dynamically when required for a program mapping request.

USING RECORDS

(record-name/(record-name version-n) ROLENAME role-name)

Specifies the list of predefined schema and/or work records used by the map and optionally specifies role names for records:

• Record-name identifies the name of a record that contains elements referenced by the map. If record-name is not unique in the data dictionary, the version number of the necessary schema or work record must be supplied; the default value for version-n is specified at system generation.

  If a logical record is being used, the developer names the records containing elements that are part of the logical record and that are used in the map definition. The logical record name is later specified by the dialog or program using the map.

• ROLENAME role-name specifies the role name used for the record at runtime. Role names are needed when a given record type is referenced in more than one context. For example, the developer might specify the EMPLOYEE record layout twice for a map that uses the EMPLOYEE record for both employee-related and manager-related fields on a single map:
  • One specification of the EMPLOYEE record would not include a role name for the record.
  • The second specification of the EMPLOYEE record would include a valid role name for the record (for example, MANAGER). The role name must be used in subsequent references to the record in the map-definition.

  The specified role name can be established in two ways:

  • The role name can be previously defined for the record by a logical record definition in the subschema used by the program or dialog.
  • The role name can be unique to the map, defined at map definition time on the Associated Records screen or via the batch compiler.

EDIT/NOEDIT

Indicates whether automatic editing and error-handling are enabled for the map, as follows:

• EDIT (default) globally enables automatic editing and error-handling for the map.
• NOEDIT globally disables automatic editing and error-handling for the map; editing and error-handling criteria (if any) defined for map fields are ignored.

Note: For more information about enabling and disabling automatic editing, see "Enabling Automatic Editing and Error Handling".

RESET/NORESET MODIFIED

Indicates whether the modified data tags (MDTs) for data fields are reset automatically on a mapout operation:

• RESET (default) specifies that all MDTs are reset (turned off) when the map is mapped out.
• NORESET specifies that MDTs are left unchanged when the map is mapped out.

The MDT/NOMDT specification in the MFLD ATTRIBUTES clause for a field overrides the RESET/NORESET specification for that field if the map-level and field-level specifications differ. If MDT is chosen for a field, the MDT is set on regardless of the RESET MDT specification.

Note: For more information about the MDT/NOMDT setting, see "Attributes for Fields".

LOCK/UNLOCK KEYBOARD

Specifies whether the keyboard unlocks automatically after a mapout operation:

• LOCK specifies that the keyboard remains locked until the operator presses the RESET key.
• UNLOCK (default) specifies that the keyboard is unlocked after a mapout.

ALARM/NOALARM

Indicates whether a terminal alarm sounds automatically on a mapout operation:

• ALARM specifies that the terminal alarm sounds on a mapout operation. This specification is meaningful only if the terminal is equipped with a hardware alarm.
• NOALARM (default) specifies that the terminal alarm does not sound on mapout.

STARTPRT/NOPRT

Specifies whether the contents of the printer terminal buffer should be printed automatically upon completion of data transmission on a mapout operation:

• STARTPRT specifies that the contents of the printer terminal buffer are printed. This specification is meaningful only for mapping operations associated with 3280-type printers.
• NOPRT (default) specifies that the contents of the printer terminal buffer are not printed.

NLCR/40CR/64CR/80CR

Specifies character-per-line formatting for printer output:

• NLCR (default) specifies that no line formatting is performed on the printed output. Printing skips to a new line only when new line (NL) and carriage return (CR) characters are encountered.
• 40CR specifies that the buffer contents are printed at 40 characters per line.
• 64CR specifies that the buffer contents are printed at 64 characters per line.
• 80CR specifies that the buffer contents are printed at 80 characters per line.

These specifications are applicable only if the STARTPRT clause is specified for the map.

PAGEABLE/NONPAGEABLE

Specifies whether the map is pageable:

• PAGEABLE specifies that the map is pageable. A pageable map is a map that can display more than one page of information at runtime.
• NONPAGEABLE (default) specifies that the map is not a pageable map.

Note: For more information about pageable maps, see "Pageable Maps".

DECIMAL POINT IS COMMA/PERIOD

Specifies the decimal point character for numeric fields on the map:

• COMMA specifies that the comma (,) is used as the decimal point, in accordance with international format. An external picture for the field also must be specified in international format, with the comma as the decimal point.
• PERIOD (default) specifies that the period (.) is used as the decimal point.

HELP

Specifies whether help will be implemented for the map.

NO/LOAD MODule module name

If there is Help for the map, the name of the load module that contains all the help source for the map.

HELPKEY IS PFnn

The PFKey designated as the Help key for the map.

SOUrce NONE/MODule module-name

The name of the IDD module that contains the help text for the map.

If module name is specified, you can optionally specify:

• The version number
• Whether the help is displayed on a full or half screen

ON EDIT ERROR

Defines incorrect-field attributes, correct-field attributes, and alarm status for use when a dialog or map redisplays a map that contains input errors. The following clauses assign error-handling criteria:

• INCORRECT FIELDS ATTRIBUTES=(attributes-list) specifies attributes that are assigned to incorrect fields when an edit error occurs. Typically, incorrect fields are given an attribute such as BRIGHT or BLINK to draw the operator's attention to the erroneous data. No default attributes are defined.

  Note: For more information about syntax for the attributes-list, see Attributes List.

• CORRECT FIELDS ATTRIBUTES=(attributes-list) specifies attributes that are assigned to correct and unedited fields when an edit error occurs. No default attributes are defined.

  Syntax for the attributes-list is discussed in Attributes List.

• SOUND ALARM/NOALARM specifies whether a terminal alarm sounds on input error:
  • ALARM indicates that the alarm is sounded. This option is meaningful only when a terminal is equipped with a hardware alarm.
  • NOALARM (default) indicates that the alarm is not sounded.

For example, a dialog or program can include code to redisplay a map when an error is detected in a field on mapin. When the display is mapped back out, incorrect-field attributes take effect for fields that are in error, and correct-field attributes take effect for fields that are not in error. The terminal operator can correct the errors and resubmit the map.

Notes:

• For more information about the use of error-handling specifications, see "Error-handling Criteria."
• For more information about how dialogs and programs override specifications made in the ON EDIT ERROR clause, see "Map Inquiry and Modification."

ORIGIN FOR (device-code)/ALL IS (row column)

Positions the origin of the runtime map at a row/column location on specified devices:

• Device-code names one device. Available device-code specifications are 12X40, 12X80, 24X80, 32X80, 43X80, and 27X132. The specified device must be defined in the DEVICES clause of the MAP statement. More than one ORIGIN FOR device-code clause can be included in a single MAP statement.

  Parentheses are required when a device code(s) is specified.

• ALL names all devices defined in the DEVICES clause of the MAP statement.
• Row column specifies the coordinates at which the upper left-hand corner of the runtime map is plotted for all devices specified in the ORIGIN FOR specification. Only one row column specification can be made for a given ORIGIN FOR clause; if specified, it must be enclosed in parentheses. If not specified, column defaults to 1.

  Parentheses are required around the row column coordinates.