CA IDMS Reference 19.0

PDF
English

INQUIRE MAP (COBOL)

The INQUIRE MAP statement is used after a MAP IN request to accomplish one of the following actions:
idmscu
The INQUIRE MAP statement is used after a MAP IN request to accomplish one of the following actions:
The following rules apply to INQUIRE MAP statements:
  • If any of the test conditions are requested, INQUIRE MAP must specify a statement to execute when the condition is found to be true.
  • An INQUIRE MAP statement can specify only one field-oriented inquiry. This inquiry can be specified alone or with a map-specific inquiry.
  • A MAP IN request must be issued before INQUIRE MAP is used.
Move Map-Related Data
This version of the INQUIRE MAP statement moves one of the following map-related data items into variable storage:
  • The attention ID (AID) key that was used
  • The current cursor position (row and column)
  • The entered length of a specific map input field
Syntax

►►─── INQUIRE MAP 
map-name
 ───────────────────────────────────────────────────►

 ►─── MOVE ─┬─ AID TO 
aid-indicator 
─────────────────────┬─ . ────────────────►◄
            ├─ CURSOR TO 
cursor-row cursor-column 
───────┤
            └─ IN LENGTH FOR 
field-name
 TO 
field-length 
─┘
Parameters
  • INQUIRE MAP
    map-name
    Specifies the map for which the inquiry is to be made. This map must be included in the MAP SECTION of the program.
  • MOVE
    Moves screen-related information to program variable storage.
  • AID TO 
    aid-indicator
    Returns the attention ID to the specified location in variable storage. Specify the symbolic name of a 1-byte user-defined field that will be set to the 3270 AID character received in the last map input request. The following table lists the AID characters that are associated with each 3270-type control key.
    The data dictionary includes a record that defines the AID character values as level-88 items to test for particular keyed input by including a COPY IDMS DC-AID-CONDITION-NAMES statement in the WORKING-STORAGE SECTION.
  • CURSOR TO 
    cursor-row cursor-column
    Returns the cursor address from the last map input function to the specified location in program variable storage. Specify the symbolic names of user-defined PIC S9(4) COMP fields to which the row and column cursor address will be returned.
  • IN LENGTH FOR 
    field-name
    Returns the length in bytes of the data in the specified map field. Specify the name of the map field for which the length is being requested.
  • TO 
    field-length
    Specifies where to return the field length. Specify the symbolic name of a user-defined PIC S9(4) COMP field.
Attention ID (AID) Key Values
Key
AID Character
Key
AID Character
ENTER
''' (single quote)
PF14
'B'
CLEAR
'_' (underscore)
PF15
'C'
PF01
'1'
PF16
'D'
PF02
'2'
PF17
'E'
PF03
'3'
PF18
'F'
PF04
'4'
PF19
'G'
PF05
'5'
PF20
'H'
PF06
'6'
PF21
'I'
PF07
'7'
PF22
'¢'
PF08
'8'
PF23
'.'
PF09
'9'
PF24
'<'
PF10
':'
PA01
'%'
PF11
'#'
PA02
'>'
PF12
'@'
PA03
','
PF13
'A'
 
 
The following figure shows the code that is copied into the program as a result of the COPY IDMS DC-AID-CONDITION-NAMES specification:

*01 COPY IDMS DC-AID-CONDITION-NAMES.
 01 DC-AID-CONDITION-NAMES.
   03 DC-AID-IND-V      PIC X.
               88 ENTER-HIT VALUE QUOTE.
               88 CLEAR-HIT VALUE '_'.
               88 PF01-HIT VALUE '1'.
               88 PF02-HIT VALUE '2'.
               88 PF03-HIT VALUE '3'.
               88 PF04-HIT VALUE '4'.
               88 PF05-HIT VALUE '5'.
               88 PF06-HIT VALUE '6'.
               88 PF07-HIT VALUE '7'.
               88 PF08-HIT VALUE '8'.
               88 PF09-HIT VALUE '9'.
               88 PF10-HIT VALUE ':'.
               88 PF11-HIT VALUE '#'.
               88 PF12-HIT VALUE '@'.
               88 PF13-HIT VALUE 'A'.
               88 PF14-HIT VALUE 'B'.
               88 PF15-HIT VALUE 'C'.
               88 PF16-HIT VALUE 'D'.
               88 PF17-HIT VALUE 'E'.
               88 PF18-HIT VALUE 'F'.
               88 PF19-HIT VALUE 'G'.
               88 PF20-HIT VALUE 'H'.
               88 PF21-HIT VALUE 'I'.
               88 PF22-HIT VALUE '¢'.
               88 PF23-HIT VALUE '.'.
               88 PF24-HIT VALUE '<'.
               88 PA01-HIT VALUE '%'.
               88 PA02-HIT VALUE '>'.
               88 PA03-HIT VALUE ','.
               88 PEN-ATTN-SPACE-NULL VALUE '='.
               88 PEN-ATTN VALUE QUOTE.
Example
The following example moves the 3270 AID character that was received in the last map input request to DC-AID-IND-V. If the AID character indicates that PF1 was pressed, the program performs a DC RETURN:

INQUIRE MAP EMPMAPLR
  MOVE AID TO DC-AID-IND-V.
IF CLEAR-HIT
  DC RETURN.
Test for Global Map Input Conditions
This version of the INQUIRE MAP statement tests for one of the following global map input conditions:
  • If the screen was not formatted before the input operation was performed
  • If one or more input fields were truncated when transferred to variable storage data fields
  • If one or more input fields were modified on the screen before being transferred
  • If one or more fields that were modified on the screen are undefined in the map being used
Syntax

►►─── INQUIRE MAP 
map-name
 ───────────────────────────────────────────────────►

                                         ┌────────────────────────┐
 ►─── IF INPUT ─┬─ UNFORMATTED ─┬─ THEN ─▼─ 
imperative-statement
 ─┴─ . ───────►◄
                ├─ TRUNCATED ───┤
                ├─ CHANGED ─────┤
                └─ EXTRANEOUS ──┘
Parameters
  • INQUIRE MAP
    map-name
    Specifies the map for which the inquiry is being made. The map must be included in the MAP SECTION of the program.
  • IF INPUT
    Tests the outcome of the last map input request for conditions relating to the data input to the program.
    • UNFORMATTED
      Tests whether the screen was formatted before the input operation.
    • TRUNCATED
      Tests whether any map fields were truncated when they were transferred to variable-storage data fields.
    • CHANGED
      Tests whether any map fields were mapped to variable-storage data fields when the map input operation was performed.
    • EXTRANEOUS
      Tests whether the input data stream contained any data from a field that was not defined to the map. If this condition is true, the undefined data field is ignored.
  • THEN 
    imperative-statement
    Specifies the action to take when the test condition is true. Specify a COBOL statement, a DML statement, or a nested block of COBOL and/or DML statements.
Example
The following example tests to determine whether any fields in the EMPMAPLR map have been truncated. If fields were truncated, the DATA-TRUNC routine is performed:

INQUIRE MAP EMPMAPLR
  IF INPUT TRUNCATED
   THEN PERFORM DATA-TRUNC.
Test for Cursor Position
This version of the INQUIRE MAP statement tests a map field for the presence of the cursor.
Syntax

►►─── INQUIRE MAP 
map-name
 ───────────────────────────────────────────────────►

                                         ┌────────────────────────┐
 ►─── IF CURSOR at DFLD 
field-name
 THEN ─▼─ 
imperative-statement
 ─┴─ . ───────►◄
Parameters
  • INQUIRE MAP
    map-name
    Specifies the map for which the inquiry is being made. The map must be included in the MAP SECTION of the program.
  • IF CURSOR at DFLD 
    field-name
    Specifies the field to test. This syntax determines whether the cursor was in the named map field during the last map input operation.
  • THEN 
    imperative-statement
    Specifies the action to take when the test condition is true. Specify a COBOL statement, a DML statement, or a nested block of COBOL and/or DML statements.
Example
The following example tests for the presence of the cursor in the PASSED-DATA-01 data field. If the cursor is present, the CHECK-2 routine is performed:

INQUIRE MAP EMPMAPLR
   IF CURSOR AT DFLD EMP-LAST-NAME-0415
     THEN PERFORM CHECK-2.
Test for Input Nonzero Status Conditions
This version of the INQUIRE MAP statement tests for the following input conditions relating to specific map fields:
  • If map fields have been modified
  • If map fields have been erased by operator action
  • If map fields have been truncated
  • If map fields are identical to map data that is currently in program variable storage
  • If map fields are different from map data that is currently in program variable storage
  • If the specified map fields are in error (the error flag has been set on for those fields)
  • If the specified map fields are correct (the error flag has been set off)
Syntax

►►─── INQUIRE MAP 
map-name
 ───────────────────────────────────────────────────►

 ►─── IF ─┬─┬─ CURRENT ─────────┬───────────┬─────────────────────────────────►
          │ ├─ ALL ─────────────┤           │
          │ ├─ NONE ────────────┤           │
          │ ├─ ANY ─────────────┤           │
          │ ├─ SOME ────────────┤           │
          │ └─ ALL BUT CURRENT ─┘           │
          │                                 │
          ├─┬─ ALL ◄ ───┬─ DFLD 
field-name
 ─┤
          │ ├─ NONE ────┤                   │
          │ ├─ ANY ─────┤                   │
          │ ├─ SOME ────┤                   │
          │ └─ ALL BUT ─┘                   │
          │                                 │
          └─ DFLD 
field-name
 ───────────────┘
 ►─┬─ DATA is ─┬─ YES ───────┬─┬──────────────────────────────────────────────►
   │           ├─ NO ────────┤ │
   │           ├─ ERASE ─────┤ │
   │           ├─ TRUNCATED ─┤ │
   │           ├─ IDENTICAL ─┤ │
   │           └─ DIFFERENT ─┘ │
   │                           │
   └─ EDIT is ─┬─ ERROR ───┬───┘
               └─ CORRECT ─┘

            ┌────────────────────────┐
 ►─── THEN ─▼─ 
imperative-statement
 ─┴─ . ────────────────────────────────────►◄
Parameters
  • INQUIRE MAP
    map-name
    Specifies the map for which the inquiry is being made. The map must be included in the MAP SECTION of the program.
  • IF
    Specifies the map fields to test.
    • CURRENT
      Applies the test only to the current field; that is, the map field that was referenced in the last MODIFY MAP or INQUIRE MAP statement that the program issued. If the last MODIFY MAP or INQUIRE MAP statement specified a field list, no currency exists.
    • ALL
      Specifies that the test is true when all map fields meet the specified condition.
    • NONE
      Specifies that the test is true when none of the map fields meet the specified condition.
    • ANY
      Specifies that the test is true when one or more map fields meet the specified condition.
    • SOME
      Specifies that the test is true if one or more 
      but not all
       of the map fields meet the specified condition.
    • ALL BUT CURRENT
      Specifies that the test is true when all map fields except the current field meet the specified condition.
  • IF
    Specifies the extent to which the condition applies to the map field.
    • ALL
      Specifies that the test is true when all of the named map fields meet the specified condition.
    • NONE
      Specifies that the test is true when none of the named map fields meet the specified condition.
    • ANY
      Specifies that the test is true when one or more of the named map fields meet the specified condition.
    • SOME
      Specifies that the test is true when one or more but not all of the named map fields meet the specified condition.
    • ALL BUT
      Specifies that the test is true when all map fields except for the named field meet the specified condition.
  • DFLD 
    field-name
    Specifies the individual map fields to which the test conditions apply. Specify a field within the named map. Separate multiple DFLD specifications by at least one blank.
  • DATA IS
    Tests the input data in the specified map fields.
    • YES
      Determines whether the terminal operator entered data in the specified map fields.
    • NO
      Determines whether the terminal operator did not enter data in the specified map fields.
    • ERASE
      Determines whether data has been erased from the specified map fields.
    • TRUNCATED
      Determines whether data has been truncated in the specified map fields.
    • IDENTICAL
      Tests whether input data is identical to map data that is currently in program variable storage.
      IDENTICAL is true in either of the following cases:
      • The modified data tag (MDT) for the field is off. On mapin, the MDT is usually off when the user did not type any characters in the field.
      • The MDT for the field is on, but each character that the user typed is identical (including capitalization) to the data in variable storage.
    • DIFFERENT
      Tests whether input data is different from map data that is currently in program variable storage.
      DIFFERENT is true when the field MDT is on,
      and
       at least one input character differs from the data in variable storage.
  • EDIT IS
    Tests for errors in the named map fields. When EDIT is specified, automatic editing must be enabled for the map and for each of the named map fields.
    • ERROR
      Determines whether the named map fields were found to be in error during automatic editing.
    • CORRECT
      Determines whether the named map fields were found to be correct during automatic editing.
  • THEN 
    imperative-statement
    Specifies the action to take when the test condition is true. Specify a single COBOL statement, a DML statement, or a nested block of COBOL and/or DML statements.
Examples
The following examples illustrate the use of the INQUIRE MAP statement.
  • Example 1: Test for Erroneous Data
    The following example determines whether automatic editing has detected erroneous data in any field in the EMPMAPLR map. If errors were detected, the program modifies the map temporarily to display the erroneous fields with the bright and blinking attributes:
    
INQUIRE MAP EMPMAPLR
  IF ANY EDIT IS ERROR
   THEN MODIFY MAP EMPMAPLR TEMPORARY
      FOR ALL ERROR FIELDS
      ATTRIBUTES BRIGHT BLINK.
  • Example 2: Test for Identical Data
    Use an INQUIRE MAP statement to test whether the user has entered an employee ID number:
    
INQUIRE MAP MAP01
  IF DFLD EMP-ID-0415 DATA IS IDENTICAL THEN
   PERFORM EMP-PROMPT-20
  ELSE
   PERFORM EMP-OBTAIN-20.
    If the IDENTICAL condition is 
    true
     (the user does not specify a different ID number), the program displays the menu screen.
    If the IDENTICAL condition is 
    false
     (the user specifies a different ID number), the program obtains the corresponding employee record from the database.
  • Example 3: Test for Changed Data
    Use an INQUIRE MAP statement to test whether the user has entered a new department ID or department name. If the user has changed either value (DIFFERENT is 
    true
    ), the program branches to DEPTUP-30:
    
INQUIRE MAP MAP02
  IF ANY DFLD DEPT-ID-0410
     DFLD DEPT-NAME-0410 DATA IS DIFFERENT
  THEN PERFORM DEPTUP-30.
Status Codes
After completion of the INQUIRE MAP function, the ERROR-STATUS field of the IDMS-DC communications block indicates the outcome:
Status code
Meaning
0000
The request has been serviced successfully.
4629
An invalid parameter has been passed from the program.
4641
The test condition has been found to be true. (This condition is tested for automatically by COBOL DML expansion statements.)
4644
The referenced map field is not in the specified map. A possible cause is a reference to an invalid map field subscript.
4656
The referenced map contains no data fields.