Control Commands › DISPLAY

DISPLAY

Purpose

Displays a dialog's map, or reexecutes a dialog's premap process.

Additionally, DISPLAY can specify a message that appears in a map's message field. If a dialog has a map and a premap process, the premap process must include a DISPLAY command to display the map. If a DISPLAY command is not coded, nothing is written to the terminal at run time.

DISPLAY issued without the CONTINUE keyword, displays the map associated with the current dialog. DISPLAY can be used in a premap process or a response process.

In a pageable map, the detail occurrences that are displayed when the DISPLAY command is issued depend on the value of the system-defined data field $PAGE and the number of detail occurrences that a single screen can hold. For example, given a screen that can hold ten detail lines, if $PAGE equals 1, detail occurrences 1 through 10 are displayed; if $PAGE equals 2, occurrences 11 through 20 are displayed; and so forth.

Syntax

►►── DISPlay ─┬────────┬─┬──────────────────────────────────────────────┬─ . ─►◄
              └ NOSAVE ┘ ├── ERAse ─────────────────────────────────────┤
                         ├── CONTinue ──────────────────────────────────┤
                         └┬─ MESSAGE ─┬ message-options ────────────────┘
                          └─  MSG    ─┘

Expansion of Message-Options

►►────┬─ TEXT ─────┬──────┬────────── message-text ───────────────────────────►
      │            ├─ IS ─┤
      │            └─ =  ─┘
      └─ CODE ─────┬──────┬────────── message-code ───────────────────────────
                   ├─ IS ─┤
                   └─ =  ─┘

 ►────────────────────────────────────────────────────────────────────────────►
  ────┬───────────────────────────────────────────────┬───────────────────────
      │                         ┌──────────────┐      │
      └─ PARMS ────┬─────┬─── (─▼── parameter ─┴─ ) ──┘
                   └─ = ─┘

 ►────────────────────────────────────────────────────┬───────────────────────►◄
  ────┬────────────────────────────────────────┬──────┘
      └─ PREFIX ───┬──────┬─────── prefix ─────┘
                   ├─ IS ─┤
                   └─ =  ─┘

Parameters

NOSAVE

Specifies that currencies are not saved when control passes from the current process to the pseudo-converse or premap process. After the pseudo-converse, or when the premap process begins execution, the dialog's currencies are initialized to those of the next higher level dialog, if any.

ERAse

Specifies that the following actions are performed at the terminal:

• Unprotected map data fields are cleared.
• The modified data tags (MDTs) for all unprotected map data fields are reset.
• The keyboard is unlocked.
• The cursor is placed at the first unprotected map data field.

If specified, ERASE is the only keyword that can follow DISPLAY in a DISPLAY command.

CONTinue

(Used in a response process) Requests reexecution of the premap process associated with the current dialog.

The keyword CONTINUE is ignored in a premap process.

MESSage message-options

Identifies message to be displayed.

MSG can be used in place of MESSAGE.

Expanded syntax for message-options is shown above immediately following the CONTINUE syntax.

TEXT IS message-text

Specifies the text of a message to be displayed in an online map's message field or sent to a batch application and a system log file.

Message-text specifies either the name of a variable data field containing the message text or the text string itself, enclosed in single quotation marks.

The text string can contain up to 240 displayable characters.

IS or = are optional keywords and have no effect on processing.

CODE IS message-code

Specifies the message dictionary code of a message to be displayed in an online map's message field or sent to the log file in a batch application.

In a batch application, the message is also sent to the operator, if directed by the destination specified in the dictionary.

Message-code specifies either the name of a variable data field that contains the message code or the 6-digit code itself, expressed as a numeric literal.

IS or = are optional keywords and have no effect on processing.

PARMS = parameter

Specifies a replacement parameter for each variable field in the stored message identified by message-code.

Up to nine replacement parameters can be specified for a message. Multiple parameters must be specified in the order in which they are numbered and separated by blanks or commas.

Parameter specifies either the name of an EBCDIC or unsigned zoned decimal variable data field that contains the parameter value or the actual parameter value, enclosed in single quotation marks.

The parameter value must contain displayable characters. At run time, each variable data field in a stored message expands or contracts to accommodate the size of its replacement parameter. A replacement parameter can be a maximum of 240 bytes.

PREFIX IS prefix

Overrides the default prefix of a dialog and a map.

Prefix must either specify an EBCDIC or unsigned zoned decimal variable data field that contains a 2-character prefix or the 2-character prefix itself, enclosed in single quotation marks

IS or = are optional keywords and have no effect on processing.

Usage

Rules for Mapping Out Fields

The DISPLAY command maps out literal fields and data fields according to these rules:

• If the map is different than the map previously displayed, both literal fields and data fields are mapped out.
• If the map is the same as the map previously displayed, literal fields are not mapped out. Data fields, except those set IN ERROR, are mapped out. Note that the MODIFY MAP command can be used to change the IN ERROR setting for a map field.
• If the ERASE keyword is specified, data fields are not mapped out. Instead, unprotected data fields on the screen are cleared.
• Data fields are further regulated by specifications made during map definition and by MODIFY MAP process commands. Both methods allow the specification that data is not displayed or is erased on a DISPLAY command.
• For a pageable map, if a PUT DETAIL command causes the first map page to be displayed, the following DISPLAY command does not map out literal or data fields. However, the DISPLAY command is still required to terminate the current process and create a pseudo-converse.

Specifying a Message

The DISPLAY command is also used to specify a message that is to appear in a map's message field.

Message fields are defined by the map field $MESSAGE.

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

One $MESSAGE field can be defined anywhere on the map. If the $MESSAGE field is defined in the detail area of a pageable map, the PUT DETAIL command is used to specify a message.

If a DISPLAY command specifies a message but the map has no message field, CA ADS creates a special message map.

Considerations for Specifying a Message Code

• Each message in the message dictionary is identified by a 6-digit code preceded by the letters DC. A request for message 987654 retrieves message DC987654.

  User-defined messages added to the message dictionary should be identified by a code in the range 900001 through 999999 and preceded by letters other than DC.

• Each message in the message dictionary can be assigned a severity code. The severity code specifies the action that CA ADS takes when the message is retrieved. Severity codes are listed in the following table.

Message Dictionary Severity Codes

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 DISPLAY command, the PARMS parameter can be used 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 2-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 2-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.

If the message is defined in the dictionary with a destination of TERMINAL, the message will be redisplayed at the user's terminal when control exits from the CA ADS application.

Examples

The examples below are based on the sample applications shown in Application Thread where dialog UPDATEO updates or erases all ORDOR records associated with a CUSTOMER record that is retrieved by dialog UPDATEC.

Example 1: Retrieving records

The following sample premap process from UPDATEO retrieves the ORDOR records to be changed. The DISPLAY command is used to display the dialog's map with a message informing the user of the processing status:

READY.
OBTAIN NEXT ORDOR WITHIN CUSTOMER-ORDER.
IF DB-END-OF-SET
THEN
    DISPLAY MESSAGE TEXT IS
    'CUSTOMER HAS NO ORDERS. HIT 'CLEAR' TO EXIT.'.
ELSE
    DISPLAY MESSAGE CODE IS 900101
    PARMS = (ORD-NUMBER,'ORDERS').

Example 2: Erasing records

The following sample response process from UPDATEO erases a retrieved ORDOR record. DISPLAY CONTINUE is used to return control to the dialog's premap process, which retrieves the next ORDOR record:

READY USAGE-MODE IS UPDATE.
ERASE ORDOR ALL MEMBERS.
DISPLAY CONTINUE.

More information:

PUT DETAIL