Change Message Description (CHGMSGD)

The Change Message Description (CHGMSGD) command changes an existing message description stored in a message file, and stores those changes in that message file for later use. The message description remains in the message file until the file is deleted, until the Remove Message Description (RMVMSGD) command is used to remove the message from the file, or until another change to the message is made with a Change Message Description (CHGMSGD) command.

Note: If the message and its second-level text exceeds 512 characters, it will not fit in the prompt field. In this case, enter the command on the Command Entry panel or in a CL program.

If the message is sent as an inquiry message or as a notify message and a reply is expected, the following validity-checking parameters can be used to specify some requirements that validate the reply received.

Reply type (TYPE) parameter.
Maximum reply length (LEN) parameter.
Valid reply values (VALUES) parameter.
Special reply values (SPCVAL) parameter.
Range of reply values (RANGE) parameter.
Relationship for valid replies (REL) parameter.
Default reply value (DFT) parameter.

These parameters are not necessary for a message to allow a reply, but they can be used to define valid replies made to the message.

Caution: Specifying the alert option in the range CPx7B00 to CPx7BFF (messages sent from the alert process) may cause unpredictable results.

Restrictions: To change a message description in a message file, you must have change (*CHANGE) authority for the message file and read (*READ) authority for the library in which the file is located.

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, *SAME	Optional, Positional 3
SECLVL	Second-level message text	Character value, SAME, NONE, X''	Optional, Positional 4
SEV	Severity code	0-99, *SAME	Optional, Positional 5
FMT	Message data fields formats	Single values: SAME, 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	SAME, NONE, CHAR, DEC, ALPHA, NAME	Optional
LEN	Maximum reply length	Single values: SAME, NONE, TYPE Other values: Element list*	Optional
	Element 1: Length	Integer
	Element 2: Decimal positions	Integer
VALUES	Valid reply values	Single values: SAME, NONE Other values (up to 20 repetitions): Character value	Optional
SPCVAL	Special reply values	Single values: SAME, 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: SAME, 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: SAME, 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, SAME, NONE	Optional
DFTPGM	Default program to call	Single values: SAME, 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: SAME, NONE Other values (up to 102 repetitions): 1-99, JOB, JOBINT, *JOBDMP	Optional
ALROPT	Alert options	Single values: SAME Other values: Element list*	Optional
	Element 1: Alert type	Character value, IMMED, DEFER, UNATTEND, NO
	Element 2: Resource name variable	1-99, *NONE
LOGPRB	Log problem	SAME, NO, *YES	Optional
CCSID	Coded character set ID	1-65535, SAME, HEX, *JOB	Optional

Top

Message identifier (MSGID)

Specifies the message identifier of the message being changed. The message identifier must be 7 characters long and in the following format: pppnnnn

The first 3 characters (ppp) must be a code consisting of an alphabetic character followed by two alphanumeric (alphabetic or decimal) characters. The last 4 characters (nnnn) must consist of the decimal numbers 0 through 9 and the characters A through F.

This is a required parameter.

Message file (MSGF)

Specifies the message file where the message description being changed is stored. This command ignores any message file overrides in effect for the job.

This is a required parameter.

Qualifier 1: Message file

name: Specify the name of the message file where the message description is stored.

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 new text for the message.

*SAME: The message text is not changed.
'message-text': Specify the text of the message that is initially displayed, printed, or sent to a program or log. A maximum of 132 characters (enclosed in apostrophes) can be specified, but the display station screen size may cause additional limitations.

Note: If the message text is changing, the entire message text is replaced with the specified change.

One or more substitution variables can be embedded in the message text string to indicate positional replacement fields that allow the program to substitute variable data in the message before the message is sent. The rules below must be followed when variables are used.

Variables must be specified in the form &n, where n is a 1- or 2-digit (1-99) number identifying the data feld that is substtuted.
Variables can be preceded by any alphanumeric character, including blanks. For example, the variables shown in the message below are all valid.
```
Command&34&72 &2 &99help
```
Variables must not be followed by a numeric character 0-9. For example, the variables shown in the following example are all not valid.
```
Command&345 &244 &999help
```
The variables can be enclosed in apostrophes. For example, to show a two-part decimal value, the message '&1.&2' can be specified.
Variables for this parameter do not have to occur positionally (in ascending or descending sequence).

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. More details on substituting data fields in message text are in the CL topic collection in the Programming category in the IBM i Information Center at http://www.ibm.com/systems/i/infocenter/.

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 the double-byte characters contain the string X'50Fn' (where n is a 1-digit number, 0-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 calling 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 any message help changes. 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.

*SAME: The message help is not changed.
*NONE: There is to be no message help for this message description. Any message help in the message description is removed.
'second-level-text': Enter the text to show as message help. 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, as described on the First-level message text (MSG) parameter. If you are changing the message help, the entire message help will be replaced with the specified change.

Message help can be formatted for the work station using three format control characters. Each must be followed by a blank.

&N Forces the message help to a new line (column 2). If the help is longer than one line, the next lines are indented to column 4 until the end of the help or until another format control character is found.
&P Forces the message help to a new line, indented to column 6. If the help is longer than one line, the next lines start in column 4 until the end of the help or until another format control character is found.
&B Forces the message help to a new line, starting in column 4. If the help is longer than one line, the next lines are indented to column 6 until the end of the help or until another format control character is found.

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). Examples are: X'50F0', X'50F4', X'50F9'.

Coded Character Set Identifier (CCSID) Considerations

The text supplied for the SECLVL parameter is assumed to be in the CCSID of the job calling 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/.

Severity code (SEV)

Specifies the severity code of the message being changed. The severity code indicates the severity level of the condition that causes the message to be sent.

*SAME: The severity code of this message is not changed.
severity-code: Specify a value, 00 through 99, to represent the severity level of this message (99 is the highest severity level). The assigned code for the message should correspond to the IBM predefined severity codes. Any 2-digit value can be specified, even if no severity code has been defined for it (either predefined or user-defined).

Message data fields formats (FMT)

Specifies the formats of from one to 99 message data fields being changed. Each field is described in this parameter by a list of attributes. 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 of this command. When specified for the Message data field values (MSGDTA) parameter of the Send Program Message (SNDPGMMSG) or Send User Message (SNDUSRMSG) command, the data fields must be concatenated to form one character string of no more than 512 characters and must match the format and sequence specified here.

Note: If any of the previously defined formats are being changed, all existing formats must be included in this parameter. For example, if seven formats had been previously defined and now the third of the seven formats is to be changed from *CHAR 24 to *HEX 8, all seven of the formats (including their types and lengths) must be included in the FMT parameter.

Single values

*SAME: The formats of the message are not changed.
*NONE: No format is being described for message fields, or the existing formats are removed. If *NONE is specified, no message data fields can be referred to in the First-level message text (MSG) parameter, Second-level message text (SECLVL) parameter, or Data to be dumped (DMPLST) parameter.
Note: If a format had been originally specified, but *NONE is specified, all referrals to those formats must be removed from the message and message help and from the dump list.

type [length [decimal-positions]] Specify a list of attributes that define each message data field (up to 99 fields) in this message description. 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). Fields &1 through &99 can be defined in and can appear in, the message text. Fields beyond that number can appear only in the dump list.

Element 1: Data type

The first element specifies the type of data the substitution field contains and how the data is to be formatted 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 by this parameter:

*QTDCHAR: A character string formatted with enclosing apostrophes ('Monday, the 1st') can be specified.
*CHAR: A character string formatted without enclosing apostrophes can be specified. It is an alphanumeric string that can be used to specify a name, for example, BOB. Trailing blanks are truncated.
*HEX: A string of bytes formatted as a hexadecimal value (X'C0F4') can be specified.
*DEC: A packed decimal number (X'058C') that is formatted in the message as a signed decimal value with a decimal point (5.8) can be specified. Values for length (required) and decimal positions (optional) specified *DEC indicate the number of decimal digits and the number of digits to the right of the decimal point. If the number of decimal positions is not specified, zero is assumed.
*BIN: A binary value that is either 2, 4 or 8 bytes long (B'0000000000111010'), formatted in the message as a signed decimal value (58) can be specified.
*UBIN: A binary value that is either 2, 4 or 8 bytes long (B'0000000000111010'), formatted in the message as an unsigned decimal value (58) can be 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 on 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 can be specified. *SPP is not valid as a replacement field in message text.
*SYP: A 16-byte system pointer to a system object can be specified. When referred to in message text, the simple name of the system object is formatted as described in the name type, *CHAR.

Element 2: Length

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

If a length is not specified for *QTDCHAR, *CHAR, *HEX, or *SPP, then *VARY is assumed for the length. If *VARY is assumed, the message data field passed by the SNDPGMMSG or SNDUSRMSG command 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 first bytes pointed to by the space pointer contain the field length. 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.
If type *DEC is specified, the total number of decimal digits (including the fraction) must be specified as the second element; the number of digits in the fraction can be specified optionally as the third element.
If type *BIN or *UBIN is specified, the message data field can be only 2, 4 or 8 bytes long; the default is 2 bytes.
If type *CCHAR is specified, the message data length field can be only *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 specifying 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 for a decimal substitution value, the default is 0 decimal positions.

Note: If an object has been damaged or deleted, the substitution variable, when displayed, is not replaced by the name of the object. Instead, the object appears as &n (where n = number).

Reply type (TYPE)

Specifies, only if the message is sent as an inquiry or notify message, the type of valid reply to this message.

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.

Note: If the reply type or length is changed, and if VALUES, RANGE, or REL had been previously specified, the existing VALUES, RANGE, REL, SPCVAL and DFT must also be changed to be compatible with the new reply type and/or length. If the reply type is changed, LEN must be changed also. If the reply type is changed to *NONE, then LEN and (if they were coded previously) VALUES, SPCVAL, RANGE, REL, and DFT must be coded as *NONE.

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

Maximum reply length (LEN)

Specifies, only if the message is sent as an inquiry or notify message, the maximum reply length.

Single values

*SAME

The reply length is not changed.

*NONE

There is no reply validity checking. The existing length specification, if any, is removed. *NONE must also be specified for the Reply type (TYPE) parameter.

*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 132 characters for types *CHAR and *ALPHA can be specified. If any additional validity checking is to be performed (VALUES, RANGE, REL, SPCVAL, or DFT are specified), the maximum length allowed for *CHAR and *ALPHA is 32 characters.
Up to 15 digits can be specified for *DEC, of which a maximum of 9 digits can be to the right of the decimal point.
Up to 10 alphanumeric characters can be specified for *NAME.

Element 1: Length

length: Specify the maximum reply length. The length specified here cannot exceed the maximums shown above.

Element 2: Decimal positions

number: If the reply type is a decimal value, the number of decimal positions can be optionally specified. If a value is not specified, zero decimal positions are assumed.

Valid reply values (VALUES)

Specifies, only if the message is sent as an inquiry or notify message, a list of values of which one can be received as a valid reply. No more than 20 values can be specified in the list. Each value in the list must meet the requirements specified for message replies on 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.

Single values

*SAME: The existing values list is not changed.
*NONE: No list of reply values is specified. The reply can have any value that is consistent with the other validity-checking parameters. Any existing values are removed.

Other values

value: Specify 1 to 20 values. To be valid, these must match a reply value sent in response to the message defined in this message description. The maximum length of each value is 32 characters.

Special reply values (SPCVAL)

Specifies, only if the message is sent as an inquiry or notify message, a list of up to 20 sets of special values of which one set (if the from-value is matched by the sent reply) is used as the reply. These values are special in that they may not meet all the validity checking specifications given in the other reply-oriented parameters. 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. If the reply sent does not match any from-value, then the reply is validity-checked by the specifications in the other reply-oriented parameters.

Single values

*SAME: The special values list is not changed.
*NONE: No special values are specified for the replies to this message. Any existing special values are removed from the message description.

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, only if the message is sent as an inquiry or notify message, the upper and lower value limits for valid replies to this message. These values must meet the requirements specified for replies by the TYPE and LEN parameters, and both values must be of the same type. If both values are not of the same length, the shorter value is padded on the right with blanks. For type *CHAR and *ALPHA replies, the reply is padded on the right with blanks or truncated on the right (to the length of the specified values) before the value range is validity-checked. If this parameter is specified, the Valid reply values (VALUES) parameter and the Relationship for valid replies (REL) parameter cannot be specified.

Single values

*SAME: The upper and lower range limits are not changed.
*NONE: No range values are specified for the replies to this message. Any existing range values are removed from the message description.

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, only if the message is sent as an inquiry or notify message, the relationship that must exist for a reply to be valid. 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 the 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 test on the reply value sent.

Single values

*SAME: The relationship is not changed.
*NONE: No relationship is specified for replies to this message. Any existing relationship specifications are removed from the message description.

Element 1: Relational operator

operator

Specify one of the following relational operators:

*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 value against which the message reply is checked. If the reply is valid in the relational test, it is sent to the sender of the message.
Note: If VALUES, RANGE, or REL had been specified on the existing message, and they are being changed to another type of reply validity-checking, then the existing check must be removed by specifying *NONE. For example, if VALUES had been specified originally, but now the user wants to specify a RANGE, then VALUES(*NONE) and RANGE(lower-value upper-value) must be specified in the CHGMSGD command.

Default reply value (DFT)

Specifies, only if the message is sent as an inquiry or notify message, the default reply (enclosed in apostrophes, if it contains special characters) used when the receiver of the message has indicated that all messages to him are to use default replies, or when a message is deleted from a message queue and no reply was specified. The default reply can also be used to answer notify messages that are not monitored. The default reply must meet the requirements specified for replies by the validity-checking parameters.

*SAME: The default reply is not changed.
*NONE: No default reply is specified. Any existing default reply is removed.
'default-reply': Specify the reply, enclosed in apostrophes if it contains special characters, to use as the default reply.

Default program to call (DFTPGM)

Specifies the default program (if any) to take default action when this message is sent as an escape message to a program that is not monitoring for it. This parameter is ignored if the message is not sent as an escape message. If it is sent as an escape message, the following parameters are passed to the default program:

Program message queue name (10 characters). The name of the program message queue to which the message was sent. This is the same name as that of the program that did not monitor for the message.
Message reference key (4 characters). The message reference key of the escape message on the program message queue.

Single values

*SAME: The default program is not changed.
*NONE: No default program is specified for this message. Any existing default program is removed from the message description.

Qualifier 1: Default program to call

name: Specify the name of the default program 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, QGPL is used.
name: Specify the library where the program is located.

Data to be dumped (DMPLST)

Specifies the data 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. When data from message data fields is dumped, this parameter specifies one or more numbers that identify, by position, the data fields being dumped.

The system objects indicated by system pointers are 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.

Note:

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).
Values specified for the DMPLST parameter may be overridden by the QSRVDMP system value. More information is in the chapter on system values in the Work management topic collection in the IBM i Information Center at http://www.ibm.com/systems/i/infocenter/.
The program receiving the unmonitored message either must have a name starting with 'Q' or the message severity must be 50 or higher.
The user of the job in which the dump is specified must be authorized to the dump command requested on this parameter.

Single values

*SAME: The dump list is not changed.
*NONE: There is no dump list for this message. Any existing dump list is removed from the message description.

Other values

*JOB: This value is the same as specifying * for the Job name (JOB) parameter and *PRINT for the Output (OUTPUT) parameter of the DSPJOB (Display Job) command.
*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 job processing are dumped to the machine error log as specified by the Dump Job Internal (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 dumped when this escape message is sent but not monitored. As many as 99 data field numbers can be specified in the list; additionally, the list can contain the values *JOB, *JOBDMP and *JOBINT.

Alert options (ALROPT)

Specifies the alert option associated with messages sent to the QHST log and the system operator message queue.

Single values

*SAME: The alert option is not changed.

Element 1: Alert type

*NO

No alert is sent.

*IMMED

An alert is sent immediately, simultaneous with sending the message to QHST.

*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 or not an entry can be put into the problem log. If there is an error log ID for the message and *YES is specified for this parameter, you can request problem analysis by pressing F14 from the system operator message queue display (by running DSPMSG *SYSOPR command).

*SAME: The value is not changed.
*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 the message.

Coded character set ID (CCSID)

Specifies the coded character set identifier (CCSID) that the text supplied for the MSG and SECLVL parameters is in.

If the MSG and SECLVL parameters are not coded, the value supplied for the CCSID parameter is used to change the CCSID tag associated with the message description. No text conversion occurs in this case. Use the CCSID parameter in this way to correct a message description that has an incorrect CCSID tag.

If either the MSG or the SECLVL parameters are coded along with the CCSID parameter, the text supplied for the MSG and SECLVL parameters will be assumed to be in the CCSID specified. If only one of the MSG or SECLVL parameters is coded, but not both, any existing text associated with the parameter that is not coded is converted to the specified CCSID so that all the text is in the same CCSID.

If the message file is anything other than 65535 or 65534, the text is converted from the CCSID specified to the CCSID of the message file. Otherwise, the CCSID specified is saved with the MSG description in the event a conversion is needed during a retrieve or display function.

If the CCSID specified does not match the character encoding of the message description, unpredictable results may occur.

To use the CCSID associated with the message description, the CCSID associated with the message file must be 65534. See the Change Message File (CHGMSGF) command for details on how to change the CCSID associated with the message file.

The CCSID only applies to the first level message text and the second level message text of the message description.

*JOB: The CCSID tag of the message description is changed to the CCSID of the job running this command. If the MSG and SECLVL parameters are specified, the text supplied in these parameters is assumed to be in the CCSID specified. If the MSG and SECLVL parameters are not coded, the CCSID of the message description is not changed.
*SAME: The CCSID tag of the message description is not changed. If the MSG or SECLVL parameter is specified, the text is assumed to be in the same CCSID as the text it is replacing.
*HEX: The CCSID tag of the message description is changed to the special CCSID value of 65535 which means this message description is not to be converted when used.
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.
If the MSG and SECLVL parameters are specified, the text supplied in these parameters 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/.

Examples

Example 1: Changing the First-Level Message and Severity

CHGMSGD   MSGID(UIN0115)  MSGF(INV)  MSG('Enter your name')
          SEV(55)

This command changes the first-level message and the severity of message UIN0115 stored in the message file INV. The rest of the message description remains as originally specified in the ADDMSGD command.

Example 2: Changing to a Range of Valid Replies

Assume the user created message UPY0047 as follows:

ADDMSGD   MSGID(UPY0047)  MSGF(PAYLIB/TIMECARD)
          MSG('Enter department number:')
          TYPE(*DEC)  LEN(4)  VALUES(0816 0727 0319 8774)

To change to a range of valid replies (RANGE parameter), instead of specific reply values (as specified with the VALUE parameter), the following command can be used:

CHGMSGD   MSGID(UPY0047)  MSGF(PAYLIB/TIMECARD)  VALUES(*NONE)
          RANGE(0300 8900)

The VALUES as originally defined are removed and the RANGE parameters are added to the message description. The type and length of the reply values do not change.

Note: All changes made to an existing message description must be compatible with the existing message description. For example, the following change would be diagnosed as invalid because the RANGE values are not compatible with the reply length as defined on the original ADDMSGD command.

Example 3: Changing the Length Parameter

ADDMSGD   MSGID(XYZ0202)  MSGF(XYZMSGF)
          MSG('Enter routing code:')
          TYPE(*CHAR)  LEN(2)  VALUES(AA BB CC DD EE)

CHGMSGD   MSGID(XYZ0202)  MSGF(XYZMSGF)  VALUES(*NONE)
          RANGE(AAA ZZZ)

To make the change to the range of reply values valid, the user must also change the length (LEN parameter). The correct command coding would be as follows:

CHGMSGD   MSGID(XYZ0202)  MSGF(XYZMSGF)  LEN(3)
          VALUES(*NONE)  RANGE(AAA ZZZ)

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.
CPF2419: Message identifier &1 not found in message file &2 in &3.
CPF2461: Message file &1 could not be extended.
CPF2483: Message file currently in use.
CPF2499: Message identifier &1 not valid.
CPF2510: Message file &1 in &2 logically damaged.
CPF2542: Message description not changed for &1.
CPF9830: Cannot assign library &1.
CPF9838: User profile storage limit exceeded.