Add Message Description (ADDMSGD)

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:

Parameters

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

Message identifier (MSGID)

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

Message file (MSGF)

Specifies the message file where the message is to be stored.

This is a required parameter.

Qualifier 1: Message file

name
Specify the name of the message file where the message is to be stored. The IBM-supplied message files, such as QCPFMSG and QRPGMSG, cannot be specified unless the user entering the command has authority to update those files. When the system is installed, only the system security officer has that authority.

Note: Message file overrides in effect for the job are ignored by this command and the message is stored in the specified file.

Qualifier 2: Library

*LIBL
All libraries in the library list for the current thread are searched until the first match is found.
*CURLIB
The current library for the job is used to locate the message file. If no current library entry exists in the library list, QGPL is used.
name
Specify the library where the message file is located.

First-level message text (MSG)

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.

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/.

Second-level message text (SECLVL)

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.

*NONE
There is no message help for this message description.
'second-level-text'
Specify the message help that is shown when it is requested by the user. No more than 3000 characters enclosed in apostrophes can be specified, but display limitations must be considered. One or more substitution variables can be embedded in the message help string, as described in the MSG parameter.

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/.

Severity code (SEV)

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.)

00
The severity code assigned to this message is 00. The message is an informational message.
severity-code
Specify a value, ranging from 00 through 99. The higher the value, the more severe or important the condition.
00
Informational messages. For informational purposes only; no reply is needed. The message can indicate that a function is in progress or that a function has completed successfully.
10
Warning. A potential error condition exists. The program may have taken a default, such as supplying missing data. The results of the operation are assumed to be successful.
20
Error. An error has been found, but it is one for which automatic recovery procedures probably were applied; processing has continued. A default may have been taken to replace the wrong data. The results of the operation may not be correct. The function may not have completed; for example, some items in a list ran correctly, while other items did not.
30
Severe error. The error found is too severe for automatic recovery procedures and no defaults are possible. If the error was in the source data, the entire data record was skipped. If the error occurred during a program, it leads to an abnormal end of program (severity 40). The results of the operation are not correct.
40
Severe error: abnormal end of program or function. The operation has ended, possibly because the program was not able to handle data that was not correct or because the user canceled it.
50
Abnormal end of job or program. The job was not started or failed to start, a job-level function may not have been done as required, or the job may have been canceled.
60
System status. Issued only to the system operator message queue. It gives either the status of or a warning about a device, a subsystem, or the system.
70
Device integrity. Issued only to the system operator message queue, indicating that a device is not working correctly or is in some way no longer operational.
80
System alert and user messages. A condition exists that, although not severe enough to stop the system now, could become more severe unless preventive measures are taken.
90
System integrity. Issued only to the system operator message queue. Describes a condition where either a subsystem or system cannot operate.
99
Action. Some manual action is required, such as entering a reply or changing printer forms.

Message data fields formats (FMT)

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

*NONE
No format is being described for message fields. If *NONE is specified, or if this parameter is omitted, no message data fields can be referred to in the First-level message text (MSG), Second-level message text (SECLVL), Data to be dumped (DMPLST), or Alert options (ALROPT) parameters.

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:

*QTDCHAR
A character string formatted with enclosing apostrophes ('Monday, the 1st') is specified.
*CHAR
A character string formatted without enclosing apostrophes is specified. It is an alphanumeric string that can be used, for example, to specify a name (BOB). Trailing blanks are truncated.
*HEX
A string of bytes formatted as a hexadecimal value (X'C0F4') is specified.
*DEC
A packed decimal number that is formatted in the message as a signed decimal value with a decimal point is specified. Values for length (required) and decimal positions (optional) are specified for this type (*DEC) to indicate the number of decimal digits and the number of digits to the right of the decimal point. Zeros to the left of the first significant digit are suppressed, and leading blanks are truncated (removed). If a decimal position other than zero is specified, a decimal point is shown in the result even if the decimal precision in the result is zeros; examples are 128.00 and 128.01 if FMT(*DEC 5 2) is specified. If the number of decimal positions is not specified, zero is assumed. The following gives two examples:
  • If FMT(*DEC 2) is specified for a substitution field and the message data is a packed decimal value of X'058C', the message text contains a positive value of 58 with no decimal point indicated.
  • If FMT(*DEC 4 2) is specified and the packed value is specified as X'05810C' (3 bytes long), the text contains the formatted decimal value of 58.10.
*BIN
A binary value that is either 2, 4 or 8 bytes long (B'0000 0000 0011 1010') and is formatted in the message as a signed decimal value (58) is specified.
*UBIN
A binary value that is either 2, 4 or 8 bytes long (B'0000 0000 0011 1010') and is formatted in the message as an unsigned decimal value (58) is specified.
*CCHAR
A character string that can be converted. If data of this type is sent to a message queue that has a CCSID tag other than 65535 or 65534, the data is converted from the CCSID specified by the send function to the CCSID of the message queue. Conversions can also occur on data of this type when the data is obtained from the message queue using a receive or display function. See the Message Handler section of the i5/OS globalization topic collection in the IBM i Information Center at http://www.ibm.com/systems/i/infocenter/ for more details on CCSID conversions.
*UTC
An 8-byte field that contains a system date time stamp in Coordinated Universal Time (UTC) is specified. The output formatted date time stamp contains the date followed by one blank separator and the time. The date and time in the output message are adjusted from UTC using the time zone specified for the job. The date is formatted using the job definition attributes for date format and date separator. The time is formatted using the job definition attribute for time separator. When the 8-byte field is passed as hex zero (X'0000000000000000') the value will be formatted as *N.
*UTCD
An 8-byte field that contains a system date time stamp in Coordinated Universal Time (UTC) is specified. The date in the output message is adjusted from UTC by the time zone specified for the job. The date is formatted using the job definition attributes for date format and date separator. When the 8-byte field is passed as hex zero (X'0000000000000000') the value will be formatted as *N.
*UTCT
An 8-byte field that contains a system date time stamp in Coordinated Universal Time (UTC) is specified. The time in the output message is adjusted from UTC by the time zone specified for the job and is formatted using the job definition attribute for time separator. When the 8-byte field is passed as hex zero (X'0000000000000000') the value will be formatted as *N.
*DTS
An 8-byte field that contains a system date time stamp is specified. The date time stamp contains the date followed by one blank separator and the time. The date is formatted in the output message using the job definition attributes for date format and date separator. The time is formatted using the job definition attribute for time separator.
*ITV
An 8-byte binary field that contains the time interval (in seconds) for wait time-out conditions is specified. The time interval is formatted in the message as a zero-suppressed zoned decimal value (15 0) representing the number of seconds to wait.

The following formats are valid only in IBM-provided message descriptions and should not be used for other messages.

*SPP
A 16-byte space pointer to data in a space object is specified. When referred to in the DMPLST parameter, the data in the space object (from the offset indicated by the pointer) for the length specified, is dumped. *SPP is not valid as a replacement field in message text.
*SYP
A 16-byte system pointer to a system object is specified. When referred to in message text, the simple name of the system object is formatted as described in the name type, *CHAR. When referred to on the Data to be dumped (DMPLST) parameter, the object itself is dumped.

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.

  1. If a length is not specified for *QTDCHAR, *CHAR, *HEX, or *SPP, then *VARY is assumed for the length. If *VARY is specified or assumed, the message data field passed by the SNDUSRMSG or SNDPGMMSG commands must be preceded by a 2-byte or 4-byte binary field that indicates the actual number of bytes of data being passed. However, when *SPP is specified, the length field is contained in the first bytes pointed to by the space pointer. Therefore, the 2-byte or 4-byte field must precede the data pointed to by the space pointer, and not precede the space pointer that is passed as part of the message data.
  2. If the type *DEC is specified, the total number of decimal digits (including the fraction) must be specified as the second value; the number of digits in the fraction optionally can be specified (optional) as the third value.
  3. If the type *BIN or *UBIN is specified, the message data field can be only 2, 4 or 8 bytes long; the default is 2 bytes.
  4. If the type *CCHAR is specified, the message data length field can only be *VARY. A variable length field is required because as the data in this field gets converted to different coded character set identifiers (CCSIDs), its length may change.

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.

Reply type (TYPE)

Specifies the type of reply that can be made to an inquiry or notify message.

*CHAR
Any character string is valid. If it is a quoted character string, the apostrophes are passed as part of the character string.
*NONE
No reply type is specified, and no reply validity checking is performed. LEN(*NONE) must also be specified. for the Maximum reply length (LEN) parameter.
*DEC
Only a decimal number is a valid reply.
*ALPHA
Only an alphabetic string is valid. Blanks are not allowed.
*NAME
Only a simple name is a valid reply. The name does not have to be an object name, but it must start with an alphabetic character; the remaining characters must be alphanumeric. If all reply characters are alphabetic (A-Z), the reply is converted to uppercase.

Maximum reply length (LEN)

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

*TYPE
The maximum length is determined by the type of reply specified for the Reply type (TYPE) parameter. The maximum length for each type of reply is:
  • Up to 32 characters can be specified for types *CHAR and *ALPHA (132 characters if no additional validity checking is being performed).
  • Up to 15 digits are specified for *DEC, of which a maximum of 9 digits can be to the right of the decimal point.
  • Up to 10 alphanumeric characters are specified for *NAME.
*NONE
No reply length is specified. No reply validity checking is performed if this message is sent as an inquiry or notify message. *NONE must also be specified for the Reply type (TYPE) parameter.

Element 1: Length

length
Specify the maximum length allowed for the message reply.

Element 2: Decimal positions

decimal-positions
Specify the maximum length allowed for the message reply. The length specified cannot exceed the maximums specified on the *TYPE value. If *DEC is specified for the Reply type (TYPE) parameter, specify the number of decimal positions can be optionally specified; if it is not specified, zero decimal positions are assumed.

Valid reply values (VALUES)

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

*NONE
No list of reply values is specified. The reply can have any value that is consistent with the other validity specification parameters.

Other values

compare-value
Specify a list of up to 20 values to compare with a reply value that is sent in response to the message defined in this message description. The reply value must match one of the values in this list to be a valid reply to this message. The maximum length of each value is 32 characters.

Special reply values (SPCVAL)

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

*NONE
No special values are specified for the replies to this message.

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

from-value
Specify a from-value to compare to a message reply value.

Element 2: Replacement to-value

to-value
Specify a to-value that the from-value will be mapped to before the reply is sent.

Range of reply values (RANGE)

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

*NONE
No range values are specified for the replies to this message.

Element 1: Lower value

lower-value
Specify the lower limit value for valid replies to this message.

Element 2: Upper value

upper-value
Specify the upper limit value for valid replies to this message.

Relationship for valid replies (REL)

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

*NONE
No relationship values are specified for the replies to this message.

Element 1: Relational operator

operator-value
Specify one of the relational operators and the value against which the message reply is validity checked. If the reply is valid in the relational test, it is sent to the message sender. The relational operators that can be entered are:
  • *LT -- Less than
  • *LE -- Less than or equal to
  • *GT -- Greater than
  • *GE -- Greater than or equal to
  • *EQ -- Equal to
  • *NL -- Not less than
  • *NG -- Not greater than
  • *NE -- Not equal to

Element 2: Value

value
Specify the value to be used to compare against a message reply value.

Default reply value (DFT)

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.

*NONE
No default reply is specified for the replies to this message.
'default-reply'
Specify the default reply to send (enclosed in apostrophes if it contains special characters) to inquiry or notify messages.

Default program to call (DFTPGM)

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:

Single values

*NONE
No default program is specified for this message.

Qualifier 1: Default program to call

name
Specify the name of the default program that is called when an escape message is sent.

Qualifier 2: Library

*LIBL
All libraries in the library list for the current thread are searched until the first match is found.
*CURLIB
The current library for the job is used to locate the program. If no current library entry exists in the library list, the QGPL library is used.
name
Specify the library where the program is located.

Data to be dumped (DMPLST)

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

*NONE
There is no dump list for this message. No dump occurs.

Other values

*JOB
This value is the equivalent of specifying * for the Job name (JOB) parameter and *PRINT for the Output (OUTPUT) parameter of the Display Job (DSPJOB) command. See the DSPJOB command description for more information.
*JOBDMP
The data areas of the job are dumped as specified by the Dump Job (DMPJOB) command. *JOBDMP can be specified by itself, with *JOB, with *JOBINT, or with a list of message data field numbers.
*JOBINT
The internal machine data structures, related to the machine process in which the job is running, are dumped to the machine error log as specified on the DMPJOBINT command. *JOBINT can be specified by itself, with *JOBDMP, *JOB, or with a list of message data field numbers.
message-data-field-number
Specify the numbers of the message data fields that identify the data that is dumped when this escape message is sent but not monitored. A maximum of 99 data field numbers can be specified. Additionally, the list can contain the values *JOB, *JOBINT, and *JOBDMP.

Note:

  1. If any of these values are specified for DMPLST, *JOB is assumed to be part of the values. For example, DMPLST (1 2 *JOBDMP) gives the same result as DMPLST(*JOB 1 2 *JOBDMP).
  2. Values specified for the DMPLST parameter may be overridden by the QSRVDMP system value. More information is in the section entitled System value parameters in the Systems Management topic collection in the IBM i Information Center at http://www.ibm.com/systems/i/infocenter/.
  3. The program receiving the unmonitored message either must have a name starting with 'Q' or the message severity must be 50 or higher.
  4. The user of the job in which the dump is specified must be authorized to the dump command requested on this parameter.

Level of message(LVL)

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

*CURRENT
The current date is used as the first part of the message description level identifier.
creation-date
Specify the date on which the message description is being defined. The date must be specified in the format defined by the system values QDATFMT and, if separators are used, QDATSEP.

Element 2: Level number

1
The number 1 is used as the second part of the message description level identifier.
1-99
Specify a number (ranging from 1 through 99) that makes the level identifier of the message description unique.

Alert options (ALROPT)

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

*NO
No alert is sent.
*IMMED
An alert is sent immediately, simultaneous with sending the message to QHST or QSYSOPR.
*UNATTEND
An alert is sent immediately only when *UNATTEND is specified for the Alert status (ALRSTS) parameter of the Change Network Attributes (CHGNETA) command.
*DEFER
The alert is sent after local problem analysis. *DEFER should be specified only for those messages against which problem analysis can be run. An alert is sent at the first exit from problem analysis for the problem referred to by the message. All alerts set to *DEFER are treated as *IMMED if:
  • *UNATTEND is specified for the Alert status (ALRSTS) parameter of the Change Network Attributes (CHGNETA) command.
  • An error log ID is not available for a problem that might be resolved using problem analysis.
  • *NO is specified for the Log problem (LOGPRB) parameter (problem analysis is not available for the condition reported by the message).

Element 2: Resource name variable

*NONE
No message data field format number is passed with the alert identifier.
1-99
Specify the message data field format number that is passed with the alert identifier.

Log problem (LOGPRB)

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).

*NO
An entry is not put in the problem log.
*YES
An entry is put in the problem log if there is an error log ID associated with this message.

Coded character set ID (CCSID)

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/.

*JOB
The text for this message description is assumed to be in the CCSID of the job running this command.
*HEX
The text for this message description is not converted and is tagged 65535.
coded-character-set-identifier
Specify the CCSID you want the text to be considered in. Valid values range form 1 through 65535. See the Globalization information in the iSeries Information Center at http://www.ibm.com/eserver/iseries/infocenter for a list of valid CCSID values. Only CCSIDs that a job can be changed to are accepted.

Examples

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.

Error messages

*ESCAPE Messages

CPF2401
Not authorized to library &1.
CPF2407
Message file &1 in &2 not found.
CPF2411
Not authorized to message file &1 in &2.
CPF2412
Message ID &1 already exists in message file &2 in &3.
CPF2430
Message description not added to message file
CPF2461
Message file &1 could not be extended.
CPF2483
Message file currently in use.
CPF2510
Message file &1 in &2 logically damaged.
CPF9830
Cannot assign library &1.
CPF9838
User profile storage limit exceeded.