Function
The //ADD-MSG statement adds a new message unit to the message file that is currently open.
In addition to the message code, which represents the address of the message unit within the message file, the user must define the message attributes, language identifiers and texts.
Message attributes include the access methods, output destination, routing code, weight code and message warranty. A message text must be written for each defined language identifier; meaning and response texts, however, can be entered as required. If the message text contains inserts, names and default texts can be assigned to these inserts in the INSERT-ATTRIBUTES operand. The message attributes and insert attributes are defined only once and are common to all the texts and languages of a message unit.
It is not possible to add texts in a new language to an existing message unit. If it were, the //ADD-MSG statement would cause the existing message unit to be overwritten. In batch mode and in interactive procedures, spinoff is triggered if the message is not overwritable (see the OVERWRITE operand of the //ADD-MSG and //MODIFY-OPTION statements).
Differences compared with the //ADD-MSG statement in menu mode
The //ADD-MSG statement that can be entered in the command area of the screen mask differs from the //ADD-MSG statement in command procedures in that
in menu mode, the operand value *PANEL-REQUEST can be assigned to any operand
additional values can be specified in the MSG-ID operand
the OVERWRITE operand is not available in menu mode.
For further details, see section “Special features of statements in menu mode”.
Format
ADD-MSG | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Operands
MSG-ID = <name 7..7>
Identifies the message unit to be added. The full message code, consisting of the threecharacter message class and the four-digit message number, must be entered.
ACCESS-METHODS = *ISAM / list-poss(4): *ISAM / *DLAM / *LOCAL-DLAM / *MINIMIP / *BAMR
Specifies the methods that MIP uses to access the messages. Up to three methods can be specified; a combination of *ISAM and *DLAM, and *ISAM and *LOCAL-DLAM, however, is not permitted.
ACCESS-METHODS = *ISAM
MIP searches for messages via the ISAM key (= message code).
ACCESS-METHODS = *DLAM
The DLAM access method is used for particularly frequent messages. If a message file containing a DLAM message is activated, the DLAM message is loaded into main memory. MIP can output the DLAM message directly without accessing the message file.
ACCESS-METHODS = *LOCAL-DLAM / *MINIMIP / *BAMR
These access methods are reserved for internal use with the manufacturer.
DESTINATIONS = *USER-TASK / *ALL(...) / list-poss(2): *USER-TASK / *CONSOLE
This operand allows the creator of the message to document its possible output destinations. The output destination proper is determined in the DEST (destination code) operand of the MSG7X macro.
DESTINATIONS = *USER-TASK
The message output destination is SYSOUT, SYSLST or a user-specific memory area.
DESTINATIONS = *ALL(...)
All output destinations are possible.
ROUTING-CODE = <alphanum-name 1..1> / *MAIN-CONSOLE / *CONSLOG
The one-character routing code is evaluated as a destination specification for console outputs. The meanings of the routing codes are given in the “Introduction to System Administration” [5 (Related publications)].
ROUTING-CODE = <alphanum-name 1..1>
Any letter, digit or one of the special characters #, $ and @ can be specified as the routing code. The meanings of the preassigned routing codes are given in the “Introduction to System Administration” [5 (Related publications)].
ROUTING-CODE = *MAIN-CONSOLE
The message’s destination is the special routing code *, which is always allocated to the main console at least.
ROUTING-CODE = *CONSLOG
Messages that do not require a response are only logged in the CONSLOG file. ROUTING-CODE = *CONSLOG has the same effect as ROUTING-CODE = @.
DESTINATION = *CONSOLE(...)
The message output destination is a console. Further information is provided in the "Introduction to System Administration” [5 (Related publications)].
ROUTING-CODE = <alphanum-name 1..1> / *MAIN-CONSOLE / *CONSLOG
The one-character routing code is evaluated as a destination specification for console outputs. The meanings of the routing codes are given in the “Introduction to System Administration” [5 (Related publications)].
ROUTING-CODE = <alphanum-name 1..1>
Any letter, digit or one of the special characters #, $ and @ can be specified as the routing code. The meanings of the preassigned routing codes are given in the “Introduction to System Administration” [5 (Related publications)].
ROUTING-CODE = *MAIN-CONSOLE
The message’s destination is the special routing code *, which is always allocated to the main console at least.
ROUTING-CODE = *CONSLOG
Messages that do not require a response are only logged in the CONSLOG file. ROUTING-CODE = *CONSLOG has the same effect as ROUTING-CODE = @.
WEIGHT = *NONE / <integer 0..99>
The weight code specifies the priority of a message.
A weight must be specified only for messages whose output destination is a console. Otherwise, *NONE is the default value. For further information on weight codes, see the “Introduction to System Administration” [5 (Related publications)].
WARRANTY = *NO / *YES
The message attribute “Warranty” is evaluated by MIP. The warranty declaration indicates that specific parts of the message will not be modified in future BS2000 versions.
The following message components are guaranteed:
message code
numbering and meaning of inserts
The message text is not guaranteed.
MIP creates S variables for warranty messages.
Further information is provided in the "Introduction to System Administration” [5 (Related publications)].
MSG-TEXT-OUTPUT = *UPPER-CASE / *LOWER-CASE
Specifies the output format of the message text. The default texts for inserts and the texts that are specified via the MSG7X macro are likewise adapted to this format. This does not apply to the meaning text and response text.
The possible output destinations are:
SYSOUT
a SYSLST file
a user-specific memory area
a console
The texts are output via the MSG7X macro or the /HELP-MSG-INFORMATION command.
MSG-TEXT-OUTPUT = * UPPER-CASE
The message text and the insert texts (default or current) are always converted into uppercase letters.
MSG-TEXT-OUTPUT = *LOWER-CASE
The message text and the insert texts (default or current) are output exactly as they are entered in the operand LANGUAGES = ...(MSG-TEXT='...').
LANGUAGES = list-poss(8): <name 1..1>(...)
Identifies the language in which the message, meaning and response texts are entered and output. The identifier consists of one letter; E stands for English and D for German. There are no conventions for other languages. The texts can be entered in up to eight different languages.
MSG-TEXT = <c-string 1..220 with-low>
A message text must be written for each message, which may be up to 220 characters long. This includes the strings (&00) through (&29) but not including the default texts that replace these strings on message output.
Separator “^”
The message text is entered as a continuous line of text. To structure the message text, the separator “^” can be used at any position in the message text as often as required. The text that follows the separator is output on the next line. Text output by the MSG7X macro or by the /HELP-MSG-INFORMATION command can be checked with the //SHOW statement.
Example
MSG-TEXT ='THIS MESSAGE IS OUTPUT TO ''(&04)''^ IN THE FOLLOWING
LANGUAGES; ''(&00)'', ''(&01)'' AND ''(&03)'''
The following text is output:
% ABC1234 THIS MESSAGE IS OUTPUT TO 'SYSOUT'
IN THE FOLLOWING LANGUAGES; 'E', 'D' AND 'F'
For further information on the format of the message text, see the “Introduction to System Administration” [5 (Related publications)].
MEANING = *NONE / list-poss(256): <c-string 1..74 with-low>
A meaning text may be written in the corresponding language for each message. This text can contain up to 256 lines of 74 characters each. Further information is provided in the "Introduction to System Administration” [5 (Related publications)].
RESPONSE = *NONE / list-poss(256): <c-string 1..74 with-low>
A response text may be written in the corresponding language for each message. This text can contain up to 256 lines of 74 characters each. Further information is provided in the "Introduction to System Administration” [5 (Related publications)].
INSERT-ATTRIBUTES = *NONE / list-poss(30): insert-number <integer 0..29>(...)
Describes the inserts defined in the message text.
INSERT-ATTRIBUTES = *NONE
No attributes are assigned to the inserts.
INSERT-ATTRIBUTES = list-poss(30): insert-number <integer 0..29>(...)
Specifies the number of the insert for which a default text is defined. Further information is provided in the "Introduction to System Administration” [5 (Related publications)].
NAME = *NONE / <structured-name 1..20>
Specifies the insert name. Insert names are evaluated by MIP. MIP uses them to create S variables. The value specified in the DEFAULT-VALUE operand or the current value (MSG7X) becomes the contents of these S variables. Further information is provided in the "Introduction to System Administration” [5 (Related publications)].
The letters of the names entered here are converted to uppercase.
Example
The inserts with numbers 0 and 4 are to be given the names “LANGUAGE” and “DESTINATION”:
INSERT-ATTRIBUTES=(0(NAME=LANGUAGE),4(NAME=DESTINATION))
DEFAULT-VALUE = *NONE / <c-string 1..54 with-low> / *EMPTY-STRING
Defines the default text to be inserted in the message text in place of the insert if no current text is defined in the MSG7X macro. DEFAULT-VALUE = *NONE means that there is no default text for the insert. DEFAULT-VALUE = *EMPTY-STRING specifies an empty string as the insert text.
DEFAULT-VALUE = *NULL (= *EMPTY-STRING) continues to be supported in batch jobs and procedures for compatibility reasons. Output format of the default text depends on the MSG-TEXT-OUTPUT operand.
Example
The inserts with the numbers 4, 0 and 1 are to be assigned the texts “F”, “E” and “D”:
INSERT-ATTRIBUTES=(4(DEF='F'),0(DEF='E'),1(DEF='D'))
AUTOMATIC-HELP = *NO / *YES(...)
If a message code or part of a message code is output using an insert (e.g. in the case of DVS errors only the message number is output), the automatic help function causes MIP to output the associated message text in addition to this message code.
AUTOMATIC-HELP = *NO
Only the message code is output.
AUTOMATIC-HELP = *YES(...)
The message code and the message text are output.
PREFIX = *BY-INSERT-VALUE / <name 3...7>
The complete message text is output for an insert included in the error message or for an explicitly specified message number.
PREFIX = *BY-INSERT-VALUE
Possible outputs:
message code with seven characters
DMS error code with “0...”at the beginning. The DMS error class is prefixed by /HELP-MSG-INFORMATION
four-character message code that is converted to a seven-character message code.
MSGMAKER does not check whether the default insert value contains a valid message code or a valid message number. If there is no valid message code, MIP issues the message “MESSAGE UNDEFINED”
The following rules are applicable to the length of the insert values and standard insert values
Length < 4: | value is left-padded with “0” up to four characters |
Length > 4 and < 7: | value is truncated at the last 4 characters |
Length > 7: | value is truncated at the last 7 characters. |
PREFIX = <name 3...7>
For output in the command /HELP-MSG-INFORMATION the message code is formed from the prefix and insert value or default insert text. The first three characters indicate the message class and must be letters.
If the prefix corresponds to a full message code, the automatic help function is applied to it directly, irrespective of insert value.
The insert value is either padded with “0” or truncated to the left so that the result corresponds to a message code with seven characters.
Example
Prefix | Insert value | /HELP-MSG-INFORMATION |
|---|---|---|
ABC | 12 | ABC0012 |
ABCX | 123 | ABCX123 |
ABCX | 1234 | ABCX234 |
ABC01 | XYZ1234 | ABC0134 |
ABC01 | <none> | ABC01 (error) |
If an insert number is defined repeatedly in a message text, the automatic help function is applied once only to this insert number.
In messages that require a response, MIP outputs the message a second time after executing the automatic help function. Automatic help is not activated if the message is sent to a user buffer.
OVERWRITE = *STD / *YES / *NO
Specifies whether the current message unit can overwrite an existing message unit with an identical message code.
OVERWRITE = *STD
The default value *STD refers to the last OVERWRITE specification made in the //MODIFY-OPTION statement (see "MODIFY-OPTION - Overwrite message unit").
OVERWRITE = *YES
The current message unit overwrites the existing message unit in its entirety.
OVERWRITE = *NO
The current message unit does not overwrite the existing message unit.
Example
MIP reports the DMS error code:
% DMS05F8 DMS error code '0533'. Command processing aborted.
IN SYSTEM MODE: /HELP-MSG DMS(0533)
Using the automatic help function the appropriate message text is output
DMS0533 REQUESTED FILE NOT CATALOGED IN PUBSET '(&00)'. COMMAND TERMINATED