MESSAGE

The MESSAGE statement maintains in the dictionary informational messages that are used by CA IDMS software. If the SET OPTIONS statement specifies SECURITY FOR IDMS-DC IS ON, the user must be assigned the proper authority to issue MESSAGE statements.

Syntax

MESSAGE Statement

►►─┬─ ADD ─────┬─ MESsage name is message-name ───────────────────────────────►
   ├─ MODify ──┤
   ├─ REPlace ─┤
   └─ DELete ──┘

 ►─┬────────────────────────────────────────────────────────┬─────────────────►
   └┬─ PREpared ─┬─ by user-id ──┬────────────────────────┬─┘
    └─ REVised ──┘               └─ PASsword is password ─┘

 ►─┬─────────────────────────────────┬────────────────────────────────────────►
   └─ NEW NAMe is new-message-name ──┘

 ►─┬───────────────────────────────────────┬──────────────────────────────────►
   └─ message SEVerity is severity-level ──┘

   ┌──────────────────────────────────────────────────────────────────────────
 ►─▼─┬────────────────────────────────────────────────────────────────────────►─
     └─┬─ INClude ◄ ─┬─ text LINe is line-number ─────────────────────────────
       └─ EXClude ───┘

  ──────────────────────────────────────────────────┐
─►────────────────────────────────────────────────┬─┴─────────────────────────►
  ─┬────────────────────────────────────────────┬─┘
   │ ┌──────────────────────────────────┐       │
   ├─▼─ DESTination is ─┬─ LOG ──────┬──┴───────┤
   │                    ├─ OPErator ─┤          │
   │                    ├─ ID ───────┤          │
   │                    ├─ TERminal ─┤          │
   │                    └─ NULl ─────┘          │
   ├─ MESsage is message-text ──────────────────┤
   │ ┌───────────────────────────────────────┐  │
   ├─▼─ DESCription is os-description-code ──┴──┤
   │ ┌─────────────────────────────┐            │
   ├─▼─ ROUte is os-routing-code ──┴────────────┤
   ├─ SEVerity is severity-level ───────────────┤
   └─ ID is destination-id ─────────────────────┘

   ┌───────────────────────────────────────────────────────────────┐
 ►─▼─┬───────────────────────────────────────────────────────────┬─┴──────────►
     │                            ┌────────────────────┐         │
     └─ EDIt ─┬─ COMments ────┬───▼─ edit-instruction ─┴─ QUIT ──┘
              ├─ DEFinition ──┤
              └─ comment-key ─┘

   ┌──────────────────────────────────────────────────┐
 ►─▼─┬─────────────────────────────────────────────┬──┴───────────────────────►◄
     └─┬─ COMments ─────┬── is ─┬─ NULl ─────────┬─┘
       ├─ DEFinition ───┤       └─ comment-text ─┘
       └─ comment-key ──┘

DISPLAY/PUNCH MESSAGE Statement (for a single message)

►►─┬─ DISplay ─┬─ MESsage name is message-name ───────────────────────────────►
   └─ PUNch ───┘

 ►─┬───────────────────────────────────────────────────┬──────────────────────►
   └─ PREpared by user-id ─┬─────────────────────────┬─┘
                           └─ PASsword is password ──┘

   ┌───────────────────────────────────────────────────────────┐
 ►─▼─┬───────────────────────────────────────────────────────┬─┴──────────────►
     │                  ┌──────────────────────────────────┐ │
     └─┬─ WITh ──────┬──▼──┬─ ALL ───────────────────────┬─┴─┘
       ├─ ALSo WITh ─┤     ├─ ALL COMment TYPEs ─────────┤
       └─ WITHOut ───┘     ├─ COMments ──────────────────┤
                           ├─ DEFinitions ───────────────┤
                           ├─ DETails ───────────────────┤
                           ├─ HIStory ───────────────────┤
                           ├─ NONe ──────────────────────┤
                           └─┬─ USEr DEFINED COMments ─┬─┘
                             └─ UDCs ──────────────────┘

 ►─┬──────────────────────────────────────────────────────────────────────────►─
   └─ TO ─┬─ SYSpch ──────────────────────────────────────────────────────────
          └─ MODule module-name ─┬───────────────────────────────────┬────────
                                 └─ Version is ─┬─ version-number ─┬─┘
                                                ├─ HIGhest ────────┤
                                                └─ LOWest ─────────┘

─►──────────────────────────────────────────────────────────────────────────┬─►
  ─────────────────────────────────────────────────────────────────────────┬┘
  ─┬──────────────────────┬┬──────────────────────────────────────────────┬┘
   └ LANguage is language ┘└ PREpared by user-id ┬───────────────────────┬┘
                                                 └ PASsword is password ─┘

 ►─┬──────────────────────┬──┬─────────────────────┬──────────────────────────►◄
   └─ VERB ─┬─ DISplay ─┬─┘  └─ AS ─┬─ SYNtax ───┬─┘
            ├─ PUNch ───┤           └─ COMments ─┘
            ├─ ADD ─────┤
            ├─ MODify ──┤
            ├─ REPlace ─┤
            └─ DELete ──┘

DISPLAY/PUNCH MESSAGE Statement (for multiple messages)

►►─── DISplay ──┬─ ALL ──────────────────────────┬─ MESsages ─────────────────►
                └─┬─ FIRst ─┬─┬─ 1 ◄ ──────────┬─┘
                  ├─ NEXt ──┤ └─ entity-count ─┘
                  ├─ LASt ──┤
                  └─ PRIor ─┘

 ►─┬──────────────────────────────────────────────────┬───────────────────────►
   └─ PREpared by user-id ─┬────────────────────────┬─┘
                           └─ PASsword is password ─┘

 ►─┬─────────────────────────────────┬────────────────────────────────────────►
   └─ WHEre conditional-expression ──┘

(for complete conditional-expression syntax, see WHERE clause)

►─┬──────────────────────────────────────────────────────────────────────────►─
  └─ TO ─┬─ SYSpch ──────────────────────────────────────────────────────────
         └─ MODule module-name ─┬───────────────────────────────────┬────────
                                └─ Version is ─┬─ version-number ─┬─┘
                                               ├─ HIGhest ────────┤
                                               └─ LOWest ─────────┘

─►──────────────────────────────────────────────────────────────────────────┬─►
  ─────────────────────────────────────────────────────────────────────────┬┘
  ─┬──────────────────────┬┬──────────────────────────────────────────────┬┘
   └ LANguage is language ┘└ PREpared by user-id ┬───────────────────────┬┘
                                                 └ PASsword is password ─┘

 ►─┬──────────────────────┬──┬──────────────────────────────────────┬─────────►◄
   └─ VERB ─┬─ DISplay ─┬─┘  └─ AS ─┬─ SYNtax ───┬──┬─────────────┬─┘
            ├─ PUNch ───┤           └─ COMments ─┘  └─ RECursive ─┘
            ├─ ADD ─────┤
            ├─ MODify ──┤
            ├─ REPlace ─┤
            └─ DELete ──┘

Parameters

MESsage name is message-name

Identifies a new message to be established in the dictionary or an existing message to be modified, replaced, deleted, displayed, or punched. Message-name must be a 1- through 8-character identifier. When used in conjunction with the CA IDMS/DC WRITE LOG statement, the identifier consists of the literal DC followed by six digits.

NEW NAMe is new-message-name

Specifies a new name for the requested message. This clause changes only the name of the message occurrence; it does not alter or delete previously defined relationships in which this message participates. Subsequent references to the message must specify the new name.

message SEVerity is severity-level

Associates a severity level with all text lines in the named message. The specified severity level directs the DC/UCF system to take a specific action automatically when a program issues the associated message in response to an error condition. Severity-level must be a 1-digit unsigned integer in the range 0 through 9; the default is 0. See the table under Usage for a list of valid DC/UCF severity levels and the resulting actions.

text LINe is line-number

Identifies the relative position of the text line within the named message. Line-number must be an integer in the range 1 through 2,147,483,647 and must be unique within the message. Because contiguous line numbers need not be assigned, the user can configure messages in which the same line of text always appears last and into which additional text lines can be inserted.

DEStination is LOG/OPErator/ID/TERminal/NULl

Associates up to four destinations with the named text line or removes a previously specified destination (option for DC/UCF system messages only). Valid destinations are as follows:

LOG— the system log
OPERATOR— the console operator
ID— any terminal known to the DC/UCF system, other than the terminal associated with the user program; the ID IS parameter (described below) assigns the actual terminal. To direct the message to multiple terminals, repeat the LINE IS clause with appropriate DESTINATION, MESSAGE, and ID options for each terminal.
TERMINAL— the terminal associated with the user program
NULL— no destination; this option removes a previously defined destination.

MESsage is message-text

Specifies the text for the named line. Message-text is restricted to 132 characters and comprises user-supplied literals and operands. If message-text must be continued, the continuation character (-) must appear as the first character in the second and subsequent input lines. If message-text includes embedded blanks or delimiters, it must be enclosed in site-standard quote characters. Operands that will receive replacement values at runtime can appear anywhere within the message text but must be preceded by an ampersand (&). The relative positions of the replacement values correspond to the values of the symbolic operands in the message text; for example, the first value replaces &01 and the second replaces &02.

DEScription is os-description-code

Associates one or more operator-message descriptor codes with the message text line (option is for OS systems only). Os-description-code must be an unsigned integer in the range 1 through 16 and must be a valid OS descriptor code in the supervisor services and macro instructions manual for the applicable OS system. A list of codes, separated by commas and/or blanks, can be constructed to any length (for example, 1 2 9 3 5).

ROUte is os-routing-code

Associates one or more operator-message routing codes with the message text line (option is for OS systems only). The specified value supplies the ROUTCDE value for WTO macros used by the DC/UCF system. If this option is used, the system administrator should ensure that the values of os-routing-code correspond to the values specified during the OS system generation. Os-routing-code must be an unsigned integer in the range 1 through 16. A list of codes, separated by commas and/or blanks, can be constructed to any length (for example, 1 2 9 3 5).

SEVerity is severity-level

Associates a severity level with the named text line. This specification is documentation only.

ID is destination-id

Identifies the terminal to which the message is to be sent.

WITh/ALSo WITh/WITHOut

Includes or excludes the specified options when the named message is displayed or punched. Detailed information for each DISPLAY/PUNCH option is under SET OPTIONS Syntax. The option that is listed below presents special considerations for this entity type.

DETails

Includes all TEXT LINE clause specifications.

Usage

DC/UCF system message severity levels

Severity level	Meaning
0	Return to caller
1	Snap task and return to caller
2	Snap system and return to caller
3	Snap task and abend task
4	Snap system and abend task
5	Abend task
6	Not assigned
7	Not assigned
8	Snap system and abend system
9	Abend system

Message occurrence structure

Message occurrences have the following structure:

Identifier— A unique 8-character identifier. DC/UCF messages contain the prefix DC in addition to a 6-digit identifier in the range 000001 through 999999;
Message text lines— Individual lines of literals and operands. Each line is identified by a unique line number. Operands are preceded by an ampersand (&) and receive replacement values when the message is issued at runtime.
Operands that furnish system-defined replacement values can be placed in messages issued from online tasks. The user can include the following operands in messages issued from online tasks. The run-time system automatically substitutes the indicated data:

Operand	Replacement value
&$0	Task ID (from the TCETSKID field of the task control element)
&$1	Time of day
&$2	Date (ddd.yy)
&$3	IDMS/DC system version (from the CSADCVID field of the common system area)
&$4	Current task code (from the task control element)
&$5	Current program (from the TCECPRGM field of the task control element)
&$6	User ID (from the TCESONRC field of the task control element)
&$7.	CA IDMS/DC system node name (from the SDSNODE field in the SDS block)
&$8.	CA IDMS/DC release number
&$9	CA IDMS/DC tape volser

User-defined destination— A code associated with each message text line. Codes are available to direct messages to the console operator, the system log, or to specific terminals.
Note: Destinations for messages used by CA ADS Batch are documentation only.
Operating system and DC/UCF system information— A description code, route code, and/or a severity level associated with each line of text, according to user-established requirements.

Detailed information about using messages in DC/UCF application programs appears in the CA IDMS Navigational DML Programming Guide.

If you specify REPLACE

If you specify REPLACE, the DDDL compiler initializes to defaults or excludes the following options:

MESSAGE SEVERITY
TEXT LINE
COMMENTS/DEFINITION/comment-key

Example

In the following example, the ADD statements define two DC/UCF messages; note that message text can be continued between input lines if necessary.

add message dc317017
    text line 1
       destination is operator
       severity is 1
       message is
       'end of file encountered before end of idms'
       -'statement.'.

add message dc317020
    text line 1
        destination is operator
        severity is 0
        message is
           'duplicate parameter within this idms statement'.