CA IDMS Reference 19.0

PDF
English

MODIFY MAP (COBOL)

The MODIFY MAP statement modifies the options in the map request block (MRB) for a map. Modifications can be designated as permanent or temporary. You can request modifications that are field-specific, map-specific, or both. Field-specific revisions apply to the variable data fields in the map.
idmscu19
The MODIFY MAP statement modifies the options in the map request block (MRB) for a map. Modifications can be designated as permanent or temporary. You can request modifications that are field-specific, map-specific, or both. Field-specific revisions apply to the variable data fields in the map.
The MODIFY MAP statement parameters that revise predefined map or map data field attributes have no defaults. If a parameter is not specified, it remains set to the value that was specified at map generation or in a previous MODIFY MAP PERMANENT statement.
Syntax

►►─── MODIFY MAP 
map-name 
────────────────────────────────────────────────────►◄


 ►─┬───────────────┬──────────────────────────────────────────────────────────►
   ├─ PERMANENT ◄ ─┤
   └─ TEMPORARY ───┘

 ►─┬────────────────────────────────────────────┬─────────────────────────────►
   └─ CURSOR at ─┬─ 
cursor-row cursor-column
 ─┬─┘
                 └─ DFLD 
field-name
 ──────────┘
 
 ►─┬──────────────────────────────┬───────────────────────────────────────────►
   │       ┌────────────────────┐ │
   └─ WCC ─▼─┬─┬─ RESETMDT ─┬─┬─┴─┘
             │ └─ NOMDT ────┘ │
             │                │
             ├─┬─ RESETKBD ─┬─┤
             │ └─ NOKBD ────┘ │
             │                │
             ├─┬─ ALARM ───┬──┤
             │ └─ NOALARM ─┘  │
             │                │
             ├─┬─ STARTPRT ─┬─┤
             │ └─ NOPRT ────┘ │
             │                │
             └─┬─ NLCR ─┬─────┘
               ├─ 40CR ─┤
               ├─ 64CR ─┤
               └─ 80CR ─┘

►─┬────────────────────────────────────────────────────────┬─────────────────►◄
  │                             ┌────────────────────────┐ │
  └─ FOR 
field-specifications
 ──▼─ 
modification-options
 ─┴─┘
 


Expansion of field-specifications








►─┬─ ALL ─┬─ BUT ────┬─ CURRENT ───────────────┬─────────────────────────────►
  │       └─ EXCEPT ─┘                         │
  │                                            │
  ├─ ALL ─┬─ CORRECT ─┬─ FIELDS ───────────────┤
  │       └─ ERROR ───┘                        │
  │                       ┌───────────────────┐│
  └─┬───────────────────┬─▼─ DFLD 
field-name 
─┴┘
    ├─ ALL ◄ ───────────┤
    └─ all ─┬─ BUT ────┬┘
            └─ EXCEPT ─┘
 


Expansion of
 
modification-options








►───┬─┬─ BACKSCAN ───┬─────────────────────────┬─ . ─────────────────────────►
    │ └─ NOBACKSCAN ─┘                         │
    │                                          │
    ├─ OUTPUT DATA is ─┬─ YES ───────┬─────────┤
    │                  ├─ NO ────────┤         │
    │                  ├─ ERASE ─────┤         │
    │                  └─ ATTRIBUTE ─┘         │
    │                                          │
    ├─ INPUT DATA is ─┬─ YES ─┬────────────────┤
    │                 └─ NO ──┘                │
    │                                          │
    ├─┬─ RIGHT ─┬─ JUSTIFY ────────────────────┤
    │ └─ LEFT ──┘                              │
    │                                          │
    ├─ PAD ─┬─ 
pad-character
 ─┬────────────────┤
    │       ├─ LOW-VALUE ─────┤                │
    │       └─ HIGH-VALUE ────┘                │
    │                                          │
    ├─ EDIT is ─┬─ ERROR ───┬──────────────────┤
    │           └─ CORRECT ─┘                  │
    │                                          │
    ├─┬─ REQUIRED ─┬───────────────────────────┤
    │ └─ OPTIONAL ─┘                           │
    │                                          │
    ├─ 
error message is
 ─┬─ ACTIVE ─────┬──────┤
    │                    └─ SUPPRESS ───┘      │
    │                                          │
    │              ┌─────────────────────────┐ │
    └─ ATTRIBUTES ─▼─┬─ SKIP ──────────────┬─┴─┘
                     │                     │
                     ├─┬─ ALPHAMERIC ─┬────┤
                     │ └─ NUMERIC ────┘    │
                     │                     │
                     ├─┬─ PROTECTED ───┬───┤
                     │ └─ UNPROTECTED ─┘   │
                     │                     │
                     ├─┬─ DISPLAY ─┬───────┤
                     │ ├─ DARK ────┤       │
                     │ └─ BRIGHT ──┘       │
                     │                     │
                     ├─ DETECT ────────────┤
                     │                     │
                     ├─┬─ MDT ───┬─────────┤
                     │ └─ NOMDT ─┘         │
                     │                     │
                     ├─┬─ BLINK ───┬───────┤
                     │ └─ NOBLINK ─┘       │
                     │                     │
                     ├─┬─ REVERSE-VIDEO ─┬─┤
                     │ └─ NORMAL-VIDEO ──┘ │
                     │                     │
                     ├─┬─ UNDERSCORE ───┬──┤
                     │ └─ NOUNDERSCORE ─┘  │
                     │                     │
                     └─┬─ NOCOLOR ───┬─────┘
                       ├─ BLUE ──────┤
                       ├─ RED ───────┤
                       ├─ PINK ──────┤
                       ├─ GREEN ─────┤
                       ├─ TURQUOISE ─┤
                       ├─ YELLOW ────┤
                       └─ WHITE ─────┘
Parameters
  • MODIFY MAP
    map-name
    Specifies the map to modify. The map must be included in the MAP SECTION of the program.
  • PERMANENT
    Applies the modifications to all mapping mode I/O requests until the program terminates or until a subsequent MODIFY MAP request overrides the requested revisions. This value is the default.
  • TEMPORARY
    Applies the modifications only to the next mapping mode I/O request (that is, MAP IN, MAP OUT, or MAP OUTIN).
  • CURSOR AT
    Specifies where to position the cursor during output operations.
    • cursor-row
       
      Specifies a row on the terminal screen. Specify the symbolic name of the user-defined field that contains the row value, or the value itself expressed as a numeric constant. Typically, fields with cursor row and column coordinates are level-77 data items that are defined as PIC S9(4) USAGE COMP (halfword).
    • cursor-column
       
      Specifies a column on the terminal screen. Specify the symbolic name of a user-defined field that contains the column value, or the value itself expressed as a numeric constant. Typically, fields with cursor row and column coordinates are level-77 data items that are defined as PIC S9(4) USAGE COMP (halfword).
    • DFLD
      field-name
       
      Specifies a map field. The cursor is moved to the first position in the field.
  • WCC
    Specifies the write-control character (WCC) options for the output operation. If a MODIFY MAP request alters any WCC option, unspecified options are reset to NOMDT, NOKBD, and NOALARM.
    • RESETMDT 
      Resets (turns off) the modified data tags (MDTs) for the map fields automatically when the map is displayed.
    • NOMDT 
      Does not reset (turn off) the modified data tags (MDTs) for the map fields when the map is displayed. The associated data is retransmitted to variable-storage data fields during the next MAP IN request.
    • RESETKBD 
      Unlocks the keyboard automatically when the map is displayed.
    • NOKBD 
      Does not unlock the keyboard when the map is displayed.
    • ALARM 
      Sounds the terminal audible alarm (if installed) automatically when the map is displayed.
    • NOALARM 
      Does not sound the terminal audible alarm when the map is displayed.
    • STARTPRT 
      Prints the contents of the terminal buffer automatically when the data has been transmitted to the terminal. This option applies only to 3280-type printers.
    • NOPRT 
      Does not print the contents of the terminal buffer when the data has been transmitted to the terminal. This option applies only to 3280-type printers.
    • NLCR 
      Does not perform line formatting on the printer output. Printing begins on a new line only when the printer encounters new line (NL) and carriage control (CR) characters.
    • 40CR 
      Prints the contents of the 3280-type printer buffer at 40 characters per line.
    • 64CR 
      Prints the contents of the 3280-type printer buffer at 64 characters per line.
    • 80CR 
      Prints the contents of the 3280-type printer buffer at 80 characters per line.
  • FOR
    Specifies the map fields to modify or to exclude from modification.
Expansion of field-specifications
  • ALL BUT (EXCEPT) CURRENT
    Modifies all fields except the current field. The current field is the map field that was referenced in the last MODIFY MAP or INQUIRE MAP request. If that request referenced a list of fields rather than a single map field, no currency exists and all map fields are modified.
    BUT and EXCEPT are synonyms and can be used interchangeably.
  • ALL CORRECT FIELDS
    Modifies all fields that are found to be correct during automatic editing or by a user-written edit module.
    To specify, ALL CORRECT FIELDS, automatic editing must be enabled for the map.
  • ALL ERROR FIELDS
    Modifies all fields that are found to be in error during automatic editing or by a user-written edit module.
    If you specify ALL ERROR FIELDS, automatic editing must be enabled for the map.
  • ALL
    Modifies all named map fields. This value is the default.
  • all BUT (EXCEPT)
    Modifies all map fields except for the named fields.
    BUT and EXCEPT are synonyms and can be used interchangeably.
    • DFLD 
      field-name
      Specifies the map fields to modify or exclude from modification. Separate multiple DFLD specifications by at least one blank. Multiple DFLD specifications must come from the same map record. Field names that are not unique within the program must be qualified with the name of the associated record.
    • Likewise, multiply occurring fields must be qualified with the appropriate subscripts. Use the following syntax:
      


      map-data-field-name
       ─┬─────────────┬──┬────────────────────────┬─
                     └─ 
      subscript
       ─┘  └─┬─ IN ─┬─ 
      record-name
       ─┘
                                        └─ OF ─┘
Modification Options
  • BACKSCAN
    Backscans the specified fields and removes trailing blanks before performing a MAPOUT operation. Only the characters up to the last nonblank are sent to the terminal. Fields that remain on the screen contain whatever characters were present before the MAP OUT or MAP OUTIN request was issued. If the MAP OUT or MAP OUTIN request specifies the ERASE option, the contents of all terminal data fields are erased.
  • NOBACKSCAN
    Does not backscan the specified fields and remove trailing blanks.
  • OUTPUT DATA IS
    Specifies how to treat the output map fields.
    • YES 
      Sets the fields to the value of the corresponding variable-storage data fields.
    • NO 
      Leaves the fields unchanged.
    • ERASE 
      Erases the fields.
    • ATTRIBUTE 
      Transmits only the attribute byte of the fields.
  • INPUT DATA is YES
    Moves map fields automatically to the corresponding variable-storage data fields during an input operation.
  • INPUT DATA is NO
    Does not move map fields to the corresponding variable-storage data fields during an input operation.
  • RIGHT JUSTIFY
    Right justifies the variable-storage fields on input.
  • LEFT JUSTIFY
    Left justifies the variable-storage fields on input.
  • PAD
    Specifies whether to pad variable-storage data fields on input and defines the padding value or character.
    If RIGHT JUSTIFY is specified, fields are padded on the left. If LEFT JUSTIFY is specified, fields are padded on the right.
    • pad-character
       
      Specifies the symbolic name of a user-defined PIC X DISPLAY field that contains the pad character, or the character itself enclosed in quotation marks.
    • LOW-VALUE 
      Pads the fields with zeros.
    • HIGH-VALUE 
      Pads the fields with the highest value in the computer collating sequence.
  • EDIT IS ERROR
    Sets the error flag 
    on 
    for the specified map fields. Automatic editing must be enabled for the map.
    Setting the error flag enables programs to perform their own editing and validation in addition to that provided by the automatic editing feature.
    On a MAPOUT operation, when any field has an error flag, only attribute bytes are transmitted for all fields (both CORRECT and INCORRECT). No data is moved from program variable storage to the screen.
  • EDIT IS CORRECT
    Sets the error flag 
    off 
    for the specified map fields. Automatic editing must be enabled for the map.
    Setting the error flag enables programs to perform their own editing and validation in addition to that provided by the automatic editing feature.
    On a MAPOUT operation, when any fieldhas an error flag, only attribute bytes are transmitted for all fields (both CORRECT and INCORRECT). No data is moved from program variable storage to the screen.
  • REQUIRED
    Requires the user to type data in the specified map fields. If no data is entered, an error occurs on MAPIN.
    Automatic editing must be enabled for the map and for the specified map fields.
  • OPTIONAL
    Does not require the user to type data in the specified map fields.
  • error message is
    Specifies whether to display an error message that is associated with the field.
    • ACTIVE 
      Displays the error message that is associated with the field. This value is the default.
      Typically, ACTIVE is specified after specifying ERROR MESSAGE SUPPRESS for the map in a previous MODIFY MAP PERMANENT statement.
    • SUPPRESS
      Does not display the error message. When the map is redisplayed because of errors, the message that is defined for the map field is not displayed even when the field contains edit errors.
  • ATTRIBUTES
    Indicates the 3270- and 3279-type terminal display attributes for the specified map fields. Only the named attributes are modified in the MRB. Separate multiple attributes by blanks.
    • SKIP 
      Repositions the cursor automatically past the map fields to the next unprotected field. When you specify SKIP, the NUMERIC and PROTECTED attributes are assigned to the affected map fields automatically.
    • ALPHAMERIC 
      Allows the user to type any character on the 3270 keyboard into the map fields.
    • NUMERIC 
      Allows the user to type numeric characters only into the map fields. If the terminal does not have the numeric lock option, NUMERIC is ignored.
    • PROTECTED 
      Protects the specified map fields from data entry or modification by the user.
    • UNPROTECTED 
      Makes the specified map fields available for data entry or modification by the user.
      You cannot specify both UNPROTECTED and SKIP.
    • DISPLAY 
      Displays the specified map fields in normal intensity.
    • DARK 
      Does not display the specified map fields.
      You cannot specify both DARK and DETECT.
    • BRIGHT 
      Displays the specified map fields in bright intensity.
      Fields that have the BRIGHT attribute are detectable by a light pen.
    • DETECT 
      Makes the specified map fields detectable by a light pen.
      Fields that have the BRIGHT attribute are also detectable by a light pen.
    • MDT 
      Sets the modified data tag automatically for the map fields when they are displayed.
    • NOMDT 
      Does not set the modified data tag automatically for the map fields when they are displayed.
    • BLINK 
      Displays the specified map fields with blinking characters. This option applies only to 3279 terminals.
      If you specify BLINK, you cannot specify REVERSE-VIDEO or UNDERSCORE.
    • NOBLINK 
      Does not display the specified map fields with blinking characters. This option applies only to 3279 terminals.
    • REVERSE-VIDEO 
      Displays the specified map fields in reverse video (background and character colors reversed). This option applies only to 3279 terminals.
      If you specify REVERSE-VIDEO, you cannot specify BLINK or UNDERSCORE.
    • NORMAL-VIDEO 
      Displays the specified map fields in normal video. This option applies only to 3279 terminals.
    • UNDERSCORE 
      Displays the specified map fields with underlined characters. This option applies only to 3279 terminals.
      If you specify UNDERSCORE, you cannot specify BLINK or REVERSE-VIDEO. 
    • NOUNDERSCORE 
      Displays the specified map fields without underlined characters. This option applies only to 3279 terminals.
    • NOCOLOR/BLUE/RED/PINK/GREEN/TURQUOISE/YELLOW/WHITE 
      Specifies a display color for the specified map fields. This option applies only to 3279 terminals.
Examples
The following examples illustrate the use of the MODIFY MAP statement.
  • Example 1
    The following statement positions the cursor at EMP-ID-0415 and prohibits the user from entering data in any field except EMP-ID-0415 and DEPT-ID-0410:
    
MODIFY MAP EMPMAPLR TEMPORARY
  CURSOR AT DFLD EMP-ID-0415
  FOR ALL BUT DFLD EMP-ID-0415
        DFLD DEPT-ID-0410
  ATTRIBUTES PROTECTED.
  • Example 2
    The following statement sets the edit flag on for the TASK-CODE-01 field, which overrides automatic editing and error handling for the next MAP IN request:
    
MODIFY MAP EMPMAPLR TEMPORARY
  FOR DFLD TASK-CODE-01
  EDIT IS ERROR.
  • Example 3
    The following statement suppresses the display of default error messages for fields EMP-ID and DEPT-ID on the current map:
    
MODIFY MAP EMPMAPLR TEMPORARY
  FOR DFLD EMP-ID DFLD DEPT-ID
   ERROR MESSAGE IS SUPPRESS.
    Because this MODIFY MAP statement specifies TEMPORARY, the error messages are suppressed only for the next MAPOUT. If PERMANENT (default) was specified, the error messages would be suppressed until the program terminated or until a subsequent MODIFY MAP overrode the error message specifications.
Status Codes
After completion of the MODIFY MAP function, the ERROR-STATUS field in the IDMS-DC communications block indicates the outcome:
Status code
Meaning
0000
The request has been serviced successfully.
4629
The program passed an invalid parameter.
4644
The map field is not in the specified map. A reference to a map field subscript may be invalid.
4656
The referenced map contains no data fields.