Map Commands › Pageable Maps › Specifying a Message to Appear in the Message Field of an Occurrence

Specifying a Message to Appear in the Message Field of an Occurrence

The text of a message or a code associated with a message that has already been defined in the message dictionary can be specified in a PUT DETAIL command. When the dialog is executed, the runtime system moves the appropriate message to the message field in the dialog's map.

A message field is defined by the $MESSAGE map field.

Note: For more information, see the CA IDMS Mapping Facility Guide.

If no message field is defined for the detail area of the pageable map, the runtime system places the message in the header or footer message field or, if neither the header nor the footer has a message field, the runtime system ignores the message. If more than one message is placed in the header or footer message field, the messages are concatenated up to the length of the message field.

Considerations

The following considerations apply to specifying a message code in a PUT DETAIL command:

• Each system-supplied message in the data dictionary message area (DDLDCMSG) is identified by a six-digit code prefixed by the letters DC. For example, a request for message 987654 retrieves message DC987654.

  User-defined messages added to the message dictionary can have a prefix other than DC and digits in the range 900001 through 999999.

• Each message in the message dictionary can be assigned a severity code. The severity code specifies the action CA ADS takes when a message is retrieved. The following table lists the severity codes and their associated actions.

• A message in the message dictionary can contain one or more variable fields that are replaced with application-specific values at run time. In a PUT DETAIL command, the application developer can use the PARMS parameter to code replacement parameters for each variable field in a specified message.

  Within the message definition in the dictionary, symbolic parameters are identified by an ampersand (&) followed by a two-digit numeric identifier. These identifiers can appear in any order. The position of the replacement values in the PARMS parameter must correspond directly to the two-digit numeric identifiers in the message; the first value corresponds to &01, the second to &02, and so forth. For example, assume that the stored message text is as follows:

  THIS IS TEXT &01 AND &03 OR &02
  

  The PARMS parameter reads PARMS=('A','B','C'). The resulting text would read as follows:

  THIS IS TEXT A AND C OR B
  

• If the message is defined in the dictionary with more than one text line, only the first line appears in the map's message field.

Example

The following example illustrates the map and the premap and response processes of a dialog that:

• Lists the employees in a department one page at a time
• Allows the user to modify employee information and delete employees
• Updates the database based on the user's entries
• Redisplays the map with appropriate messages and allows the user to make further modifications

The paging type in this example is WAIT. If the user makes a paging request and no MDTs are set, the runtime system displays the requested page. If the user makes a nonpaging request or if any MDTs are set, the runtime system initiates the response process. The response process is associated with the control keys ENTER, FWD (paging forward), and BWD (paging backward).

The pageable map associated with the dialog is shown in the screen that follows. The following considerations apply to the detail area map fields:

• The fields are defined once. At run time, the number of occurrences of these fields that are displayed to the user at any one time depends on the number of occurrences that can fit on the screen between the header and footer areas.
• At run time, the fields map to variable data fields through detail occurrences:
  • PUT NEW DETAIL commands create detail occurrences from associated variable data fields.
  • When a map page is displayed, the detail occurrences for the page are displayed.
  • When the user presses a control key, the appropriate detail occurrence fields are updated.
  • GET DETAIL commands can retrieve modified detail occurrences into associated variable data fields.
• The fields map to work record data fields and not directly to EMPLOYEE database record elements. This facilitates the update of EMPLOYEE database records in the response process.

 ┌─
 │              1
 │  DEPT. ID: _____
 │
 └─

 ┌─            2                    3                                   4
 │  EMP. ID: _____   LAST NAME: _______________             ACTION CODE: ___
 │                                   5                                6
 │                   START DATE: ________                   MESSAGE: ________
 │
 │
 │
 │
 │
 │
 │
 │
 └─

 ┌─         7
 │  PAGE: _____
 │
 │
 │  8
 │  ____________________________________________________________________________
 └─

Note:

1. Maps to DEPT-ID of DEPARTMENT database record
2. Maps to WK-EMP-ID through detail occurrence
3. Maps to WK-EMP-LNAME through detail occurrence
4. Maps to WK-ACTION through detail occurrence
5. Maps to WK-EMP-START-DATE through detail occurrence
6. Maps to $MESSAGE through detail occurrence
7. Maps to $PAGE system-supplied data field
8. Maps to WK-MESSAGE

Sample Premap Process

The premap process shown below performs the following:

• Obtains a DEPARTMENT record based on a CALC key passed from another dialog or function
• Obtains all associated EMPLOYEE records
• Creates a detail occurrence for each retrieved record
• Displays the first map page at the terminal

      OBTAIN CALC DEPARTMENT.
      IF DB-REC-NOT-FOUND
        THEN
          DO.
            MOVE 'DEPARTMENT NOT FOUND' TO WK-MESSAGE.
            DISPLAY.
          END.
      MOVE SPACES TO WK-ACTION.
      OBTAIN FIRST EMPLOYEE WITHIN DEPT-EMPLOYEE.
      WHILE NOT DB-END-OF-SET
        REPEAT.
          MOVE EMP-ID TO WK-EMP-ID.
          MOVE EMP-LNAME TO WK-EMP-LNAME.
          MOVE EMP-START-DATE TO WK-EMP-START-DATE.
          ACCEPT DB-KEY INTO WK-KEY FROM CURRENCY.
          PUT NEW DETAIL KEY WK-KEY.
  IF $PAGE-READY
            THEN
              DO.
                 MOVE 'MORE EMPLOYEES EXIST FOR THIS DEPT' TO WK-MESSAGE.
                 DISPLAY.
              END.
  OBTAIN NEXT EMPLOYEE WITHIN DEPT-EMPLOYEE.
        END.
  MOVE 'ALL EMPLOYEES DISPLAYED FOR THIS DEPT' TO WK-MESSAGE.
      DISPLAY.
  

Sample Response Process

The response process shown below performs the following:

• Retrieves each modified detail occurrence.
• Updates the EMPLOYEE database accordingly.
• Modifies each retrieved detail occurrence:
  • Moves a confirming message to the message field
  • Initializes the action code
  • Protects the fields if the associated database record is deleted
• Redisplays the map. The value of $PAGE is saved at the beginning of the response process and is restored at the end in order to display the page requested by the user. During the response process, $PAGE is modified by GET DETAIL commands.

  READY USAGE-MODE UPDATE.
  MOVE $PAGE TO WK-PAGE.
  GET DETAIL FIRST RETURN KEY WK-KEY.
  WHILE NOT $END-OF-DATA
    REPEAT.
      OBTAIN EMPLOYEE DB-KEY IS WK-KEY.
      IF WK-ACTION EQ 'DEL'
        THEN
          DO.
            ERASE EMPLOYEE.
            PROTECT (WK-EMP-ID WK-EMP-LNAME
                     WK-EMP-START-DATE WK-ACTION) PERMANENT.
            MOVE SPACES TO WK-ACTION.
            PUT CURRENT DETAIL TEXT 'DELETED'.
          END.
        ELSE
          DO.
            MOVE WK-EMP-LNAME TO EMP-LNAME.
            MOVE WK-EMP-START-DATE TO EMP-START-DATE.
            MODIFY EMPLOYEE.
            MOVE SPACES TO WK-ACTION.
            PUT CURRENT DETAIL TEXT 'MODIFIED'.
          END.
      GET DETAIL NEXT RETURN KEY WK-KEY.
    END.
   MOVE WK-PAGE TO $PAGE.
   DISPLAY.