Where allowed to run: All environments (*ALL) Threadsafe: No |
Parameters Examples Error messages |
The Add Message Description (ADDMSGD) command describes a message and stores it in a message file for later use. The message description remains in the message file until the file is deleted or until the Remove Message Description (RMVMSGD) command is used to remove it from the file. To change any of the attributes of the message description, such as its message text or severity code, use the Change Message Description (CHGMSGD) command.
Note: A description of how to print a single message or a group of messages is in the section entitled Handling Messages in the Basic system operations topic collection in the IBM i Information Center at http://www.ibm.com/systems/i/infocenter/.
Substitution variables can be embedded both in the first-level and second-level message text. They can be replaced later by message data fields specified in the Retrieve Message (RTVMSG), Send User Message (SNDUSRMSG), and Send Program Message (SNDPGMMSG) commands.
Note: The type of message being defined is not specified in the ADDMSGD command. The type is specified in the command that actually sends the message.
If the message second-level text exceeds 512 characters, it will not fit because of the IBM i Prompter limit. In this case, enter the command on the Command Entry panel or in a CL program.
Restrictions:
Top |
Keyword | Description | Choices | Notes |
---|---|---|---|
MSGID | Message identifier | Name | Required, Positional 1 |
MSGF | Message file | Qualified object name | Required, Positional 2 |
Qualifier 1: Message file | Name | ||
Qualifier 2: Library | Name, *LIBL, *CURLIB | ||
MSG | First-level message text | Character value | Required, Positional 3 |
SECLVL | Second-level message text | Character value, *NONE | Optional, Positional 4 |
SEV | Severity code | 0-99, 00 | Optional, Positional 5 |
FMT | Message data fields formats | Single values: *NONE Other values (up to 99 repetitions): Element list |
Optional |
Element 1: Data type | *QTDCHAR, *CHAR, *HEX, *SPP, *DEC, *BIN, *UBIN, *CCHAR, *UTC, *UTCD, *UTCT, *DTS, *SYP, *ITV | ||
Element 2: Length | Integer, *VARY | ||
Element 3: *VARY bytes or dec pos | Integer, 0 | ||
TYPE | Reply type | *CHAR, *DEC, *ALPHA, *NAME, *NONE | Optional |
LEN | Maximum reply length | Single values: *TYPE, *NONE Other values: Element list |
Optional |
Element 1: Length | Integer | ||
Element 2: Decimal positions | Integer | ||
VALUES | Valid reply values | Single values: *NONE Other values (up to 20 repetitions): Character value |
Optional |
SPCVAL | Special reply values | Single values: *NONE Other values (up to 20 repetitions): Element list |
Optional |
Element 1: Original from-value | Character value | ||
Element 2: Replacement to-value | Character value | ||
RANGE | Range of reply values | Single values: *NONE Other values: Element list |
Optional |
Element 1: Lower value | Character value | ||
Element 2: Upper value | Character value | ||
REL | Relationship for valid replies | Single values: *NONE Other values: Element list |
Optional |
Element 1: Relational operator | *EQ, *LE, *GE, *GT, *LT, *NE, *NL, *NG | ||
Element 2: Value | Character value | ||
DFT | Default reply value | Character value, *NONE | Optional |
DFTPGM | Default program to call | Single values: *NONE Other values: Qualified object name |
Optional |
Qualifier 1: Default program to call | Name | ||
Qualifier 2: Library | Name, *LIBL, *CURLIB | ||
DMPLST | Data to be dumped | Single values: *NONE Other values (up to 102 repetitions): 1-99, *JOB, *JOBINT, *JOBDMP |
Optional |
LVL | Level of message | Element list | Optional |
Element 1: Creation date | Date, *CURRENT | ||
Element 2: Level number | 1-99, 1 | ||
ALROPT | Alert options | Element list | Optional |
Element 1: Alert type | *IMMED, *DEFER, *UNATTEND, *NO | ||
Element 2: Resource name variable | 1-99, *NONE | ||
LOGPRB | Log problem | *NO, *YES | Optional |
CCSID | Coded character set ID | 1-65535, *JOB, *HEX | Optional |
Top |
Specifies the message identifier under which the message is stored in the message file. Every message must have an identifier, and every identifier in the message file must be unique.
This is a required parameter.
The message identifier must be 7 characters in length and in the following format: pppnnnn
The first 3 characters must be a code consisting of an alphabetic character followed by two alphanumeric (alphabetic or decimal) characters; the last 4 characters must consist of numbers ranging from 0 through 9 and characters ranging from A through F.
For user-defined messages, the same format must be used; in addition, the 3-character prefix should start with a U to distinguish user-defined messages from IBM-supplied messages. For example, the message identifier of a message in a payroll application message file could be UPY0027.
The following is a representative sample of the message identifier prefixes that are used to identify messages in several IBM-supplied message files. Shown are some of the prefixes for the IBM i operating system, ILE COBOL/400*, ILE RPG/400*, the IDU and SDA utilities, keyboard and machine interface (MI) messages.
CPA IBM i messages requiring operator action CPC IBM i system completion messages CPD IBM i system diagnostic messages CPI IBM i system informational messages CPX IBM i system titles and texts CPF IBM i system abnormal termination CBE COBOL run time CBL COBOL compiler CBX COBOL titles and texts CSC COBOL syntax checker QRG RPG language compiler RPG RPG run time RPT RPG auto report RSC RPG syntax checker RTX RPG auto report titles and texts RXT RPG relational diagnostic texts IDU Interactive database utilities (IDU) IDX IDU titles and texts SDA Screen design aid (SDA) SDX Screen design aid titles and texts KBD Keyboard MCH IBM i machine instruction interface
Top |
Specifies the message file where the message is to be stored.
This is a required parameter.
Qualifier 1: Message file
Qualifier 2: Library
Top |
Specifies the text of the message being defined. This text is the message that is initially shown or printed, or sent to a program or log. A maximum of 132 characters enclosed in apostrophes can be specified, but the limitations of the display stations (their screen size) should be considered. The entire message must be enclosed in apostrophes if blanks are included in the message. To code an apostrophe for use in the message, enter a double apostrophe.
One or more substitution variables can be embedded in the message text string to indicate positional replacement fields. These replacement fields allow substitution of variable data in the message by the program before the message is sent. The rules below must be followed if variables are used.
Command&34&72 &2 &99help
Command&345 &244 &999help
Note: The data fields are described positionally in the FMT parameter and are specified positionally in the MSGDTA parameter of the Send Program Message (SNDPGMMSG) and Send User Message (SNDUSRMSG) commands. Details on substituting data fields in message text are in CL topic collection in the Programming category in the IBM i Information Center at http://www.ibm.com/systems/i/infocenter/
This is a required parameter.
Double-Byte Character Set Considerations
When entering double-byte characters on this parameter, several combinations of characters may cause errors to occur on this command. If double-byte characters contain the string, X'50Fn' (where n is a 1-digit number ranging from 0 through 9), error messages CPF2424 or CPF2431 may result. Examples are: X'50F0', X'50F4', X'50F9'.
Coded Character Set Identifier (CCSID) Considerations
The text supplied for the MSG parameter is assumed to be in the CCSID of the job running this command unless the CCSID parameter is coded. If the CCSID parameter is coded, the text is assumed to be in the CCSID specified. For more information about the message handler and its use of CCSIDs, see the i5/OS globalization topic collection in the IBM i Information Center at http://www.ibm.com/systems/i/infocenter/.
Top |
Specifies the message help that is shown to a display station user to further explain the message specified for the First-level message text (MSG) parameter. The user presses the Help key to request the message help. Message help can also be written to the job log if *SECLVL is specified for the Log in service log (LOG) parameter of the job commands.
Message help can be formatted for the work station using three format control characters. Each must be followed by a blank
Note: When formatting the message help for the display station, the format control characters must be followed by a blank space.
Double-Byte Character Set Considerations
When entering double-byte characters on this parameter, several combinations of characters may cause errors to occur on this command. The double-byte characters should not contain the string, X'50Fn' (where n is a 1-digit number, 0-9) or error messages CPF2424 or CPF2431 may result. Examples are: X'50F0', X'50F4', X'50F9'.
Coded Character Set Identifier (CCSID) Considerations
The text supplied for the SECLVL parameter will be assumed to be in the CCSID of the job running this command unless the CCSID parameter is coded. If the CCSID parameter is coded, the text will be assumed in the CCSID specified. For more information about message handler and its use of CCSIDs, see the i5/OS globalization topic collection in the IBM i Information Center at http://www.ibm.com/systems/i/infocenter/.
Top |
Specifies the severity code of the message being defined. The severity code indicates the severity level of the condition that causes the message to be sent. (99 is the most important severity.)
Top |
Specifies the formats of up to 99 message data fields. Each field is described in this parameter by a list of attributes. These attributes specify the type of data in the field, the total length of the field, and, optionally, the number of decimal digits to the right of the decimal point. Certain data types do not require a length field. Boundary alignment requirements must be considered (for example, pointers are always aligned on 16-byte boundaries).
All 99 of the message data fields can be used as substitution values in the message and message help defined in this message description. They can also be specified for the Data to be dumped (DMPLST) parameter and the Alert options (ALROPT) parameter of this command. When specified in the MSGDTA parameter of the SNDPGMMSG or SNDUSRMSG command, the data fields must be concatenated in one character string and must match the format and sequence specified. The length of the entire character string of concatenated message data fields must not exceed 512 characters.
Single values
type [length [decimal-positions]]
Element 1: Data type
The first element specifies the type of data the substitution field contains and how the data is formatted when substituted in the message text. The contents of the second and third elements vary depending on the type specified. One of the following types can be specified for each field described on this parameter:
The following formats are valid only in IBM-provided message descriptions and should not be used for other messages.
Element 2: Length
Following the type specification, a second element can be specified to indicate the number of characters or digits that are passed in the message data. How the second element is used depends on the type specified in the first element.
Element 3: *VARY bytes or dec pos
The third element is used in one of two ways, depending on the type specified in the first element: (1) If *QTDCHAR, *CHAR, *CCHAR, *HEX, or *SPP is specified, and if *VARY is specified or assumed for the second element, the third element is used with *VARY to indicate the size of the length field actually passed. The third element can be either a 2 or a 4, which is the number of bytes used to specify the length (in binary) of the passed value. (2) If *DEC is specified, the third element indicates the number of decimal positions in the decimal value. If not specified, the default is 0 decimal positions.
Note: If an object has been damaged or deleted, the substitution variable is not replaced by the object name when it is displayed; instead, the variable appears as &n, where n = number. Also, if the length of the message data that is passed to the substitution variable is shorter than the length specified, the substitution value becomes a null field.
If the message is sent as an inquiry (*INQ) message or as a notify (*NOTIFY) message and a reply is expected, seven parameters can be used to specify some requirements that relate to the allowed values in the reply received. The seven validity checking parameters are: TYPE, LEN, VALUES, SPCVAL, RANGE, REL, and DFT. These parameters are not necessary for a message to allow a reply, but they can be used to define valid replies that can be made to the message. Also note that the VALUES, RANGE, and REL parameters are mutually exclusive, and only one of them may be specified on this command.
Top |
Specifies the type of reply that can be made to an inquiry or notify message.
Top |
Specifies the maximum length of a reply to an inquiry or notify message. The values specified apply only if one or more of the other validity checking parameters are specified. If none of the validity checking parameters are specified, the reply type can contain up to 132 characters.
Single values
Element 1: Length
Element 2: Decimal positions
Top |
Specifies a list of values of which one can be received as a valid reply to an inquiry or notify message. No more than 20 values can be specified in the list. Each value in the list must meet the requirements specified for message replies for the Reply type (TYPE) parameter and the Maximum reply length (LEN) parameter. If this parameter is specified, the Range of reply values (RANGE) parameter and the Relationship for valid replies (REL) parameter cannot be specified. To be valid, a reply must match one of the values in this list.
For the reply value to match the compare value, both must be of the same keyboard shift. For example, if the program requires a reply containing only uppercase characters, one of the following methods ensures a response in uppercase:
Single values
Other values
Top |
Specifies a list of up to 20 sets of special values of which one set is used as the reply for an inquiry or notify message. The reply sent is compared to the from-value in each set; if a match is found, and a to-value was specified in that set, the to-value is sent as the reply. If no to-value was specified, the from-value is sent as the reply.
The to-value must meet the requirements specified in the Reply type (TYPE) parameter and the Maximum reply length (LEN) parameter. If the reply sent does not match any from-value, the reply is checked for validity by the specifications in the other reply-oriented parameters.
Single values
from-value [to-value]
Specify a list of up to 20 sets of special values to determine the reply to this message. Each set must have a from-value, with which the reply is compared, and an optional to-value, which is sent as the reply if its from-value matches the reply.
Element 1: Original from-value
Element 2: Replacement to-value
Top |
Specifies the upper and lower value limits for valid replies sent to an inquiry or notify message. These values must meet the requirements specified on the Reply type (TYPE) parameter and the Maximum reply length (LEN) parameter, and both values must be of the same type. If both values are not the same length, the shorter value is padded on the right with blanks. For replies of types *CHAR and *ALPHA, the reply is padded on the right with blanks, or truncated on the right, to the specified length before the value range is checked for validity.
If this parameter is specified, the Valid reply values (VALUES) parameter and the Relationship for valid replies (REL) parameter cannot be specified.
Single values
Element 1: Lower value
Element 2: Upper value
Top |
Specifies the relationship that must be met for a valid reply to an inquiry or notify message. The value specified must meet the requirements specified for replies on the Reply type (TYPE) parameter and the Maximum reply length (LEN) parameter. For replies of types *CHAR and *ALPHA, the reply is padded on the right with blanks, or truncated on the right, to match the length of the value specified, before the system performs the relational test on the reply value that is sent.
If this parameter is specified, Valid reply values (VALUES) parameter and the Range of reply values (RANGE) parameter cannot be specified.
Single values
Element 1: Relational operator
Element 2: Value
Top |
Specifies, if the message is sent as an inquiry or notify message, the default reply (enclosed in apostrophes, if it contains special characters) that is used when the receiver of the message has indicated that all incoming messages are to receive default replies, or when a message is deleted from a message queue and no reply is specified. The default reply can also be used to answer unmonitored notify messages. The default reply must meet the requirements specified for replies on the Reply type (TYPE) parameter and the Maximum reply length (LEN) parameter.
Top |
Specifies the qualified name of any default program called to take default action if this message is sent as an escape message to a program or procedure that is not monitoring for it. This parameter is ignored if the message is not sent as an escape message. If the message is sent as an escape message, the following parameters are passed to the specified default program:
Characters 1 through 10 are the name of the program to which the message is sent.
Characters 11 through 20 are the name of the module to which the message is sent. If the message is not sent to an Integrated Language Environment (ILE) procedure, the value *N is returned in this field padded on the right with blanks.
Characters 21 through 276 are the name of the procedure to which the message is sent. If the message is not sent to an ILE procedure, the value *N is returned in this field padded on the right with blanks.
Character 277 is set to the value 1 if the message is sent to an ILE procedure, or to the value 0 if the message is not sent to an ILE procedure.
Single values
Qualifier 1: Default program to call
Qualifier 2: Library
Top |
Specifies the data that is dumped when this message is sent as an escape message to a program that is not monitoring for it. This parameter can specify that data related to the job be dumped, that data from message data fields be dumped, or that a combination of these be dumped. If data from message data fields is to be dumped, this parameter specifies one or more numbers that positionally identify the data fields to be dumped.
The system objects indicated by system pointers are completely dumped. The data in a space object, indicated by a space pointer, is dumped starting from the offset indicated by the space pointer for the length indicated in the field description. The standard job dump can also be requested. Dumps are taken as part of system default actions if escape messages are not monitored by the program to which they were sent.
Single values
Other values
Note:
Top |
Specifies the level identifier of the message description being defined. The level identifier is made up of the date on which the message is defined and a 2-digit number that makes the identifier unique.
Element 1: Creation date
Element 2: Level number
Top |
Specifies the alert option associated with messages sent to the history log (QHST) or the system operator message queue (QSYSOPR). Alerts can be used to send a message to the host system indicating that an error has occurred on this system.
Element 1: Alert type
Element 2: Resource name variable
Top |
Specifies, for IBM-supplied messages, whether an entry is put into the problem log. If there is an error log ID for the message and *YES is specified for this parameter, the user can request problem analysis by pressing F14 from the system operator message queue display (by running the DSPMSG *SYSOPR command).
Top |
Specifies the coded character set identification (CCSID) that the text supplied for the MSG and SECLVL parameters is in. If the message file that this message description is being added to is not 65534 or 65535, the text supplied is converted from the CCSID specified to the CCSID of the message file. Otherwise, the text is not converted but the CCSID is saved in case a conversion is needed during a retrieve or display function. For more information about the message handler and its use of CCSIDs, see the i5/OS globalization topic collection in the IBM i Information Center at http://www.ibm.com/systems/i/infocenter/.
Top |
Example 1: Defining a Message
ADDMSGD MSGID(UIN0115) MSGF(INV) MSG('Enter the name of user''s department') SECLVL('Valid departments: &B X12 &B X13 &B X14') TYPE(*CHAR) LEN(3) DFT('ZZZ')
This command defines a message and stores it in a file named INV under the identifier UIN0115. The message supplies second-level message text by using the &B formatting character to show the three valid department names (X12, X13, and X14) each on a separate line. The reply requires validity checking so that a valid reply can only be a 3-character identifier. A default reply of ZZZ is also provided.
Example 2: Defining a Message Description
ADDMSGD MSGID(UPY0047) MSGF(PAYLIB/TIMECARD) MSG('For week of &1, &2 time cards. Are there more?') FMT((*CHAR 8) (*CHAR 3)) TYPE(*ALPHA) LEN(1) VALUES(N Y) SPCVAL((YES Y)(NO N)) DFT(N)
This command defines a message description that is stored in the TIMECARD message file in the PAYLIB library. The program that processes the time cards can send a message (as an inquiry type message) telling how many time cards (in &2) have been processed for the week (specified in &1). To send this message to a user via a message queue, the program must use the SNDPGMMSG or SNDUSRMSG commands. In this example, the command specifies:
If a reply of YES is sent, it is accepted as a Y (SPCVAL parameter). If NO is sent, it is accepted as an N. If neither YES nor NO is sent, the reply is checked for validity by the TYPE, LEN, and VALUES parameters. If the user chooses, no reply is sent and the default reply (N) is assumed.
Example 3: Defining an Escape Message
ADDMSGD MSGID(UPY1234) MSGF(PAYLIB/TIMECARD) MSG('Tax for employee &1 exceeds gross salary.') SEV(75) FMT((*CHAR 6) (*DEC 9 2) (*CHAR 8)) DFTPGM(PAYLIB/BADTAX) DMPLST(1 2 3 *JOB)
This command defines an escape message. The sender of the message passes three data values, the first of which (employee serial number) is used as replacement text in the message. If this message is sent as an escape message and the program to which the message is sent does not monitor for message UPY1234, default system action is taken. This includes dumping the three data values that were passed and the job structure. After the dump is taken, program BADTAX is called.
See the Monitor Message (MONMSG) command for more about monitoring for messages.
Top |
*ESCAPE Messages
Top |