Send User Message (SNDUSRMSG)

The Send User Message (SNDUSRMSG) command is used by a program to send a message to a message queue and optionally receive a reply to that message. The message sent using this command can be either an impromptu or a predefined message and can be sent to a display station user in an interactive job or a specific message queue. For inquiry messages, a CL variable can be specified to receive the reply value, and the program using this command will wait for a response.

This command uses a combination of parameters available on the Send Program Message (SNDPGMMSG) and Receive Message (RCVMSG) commands to allow a program to send and receive messages by using a single command. Also, the SNDUSRMSG command provides validity checking and uppercase translation for replies to inquiry messages.

Restrictions:

  1. This command is valid only in CL programs.
  2. The SNDUSRMSG command allows a message of up to 512 characters of first-level message text to be sent. However, if the message is sent to an external message queue (*EXT) in an interactive job, only 76 characters are shown on the Display Program Messages display. If the message is sent to a user's, work station's, or system operator's message queue, the Display Message (DSPMSG) command allows all 512 characters to be displayed.

Parameters

Keyword Description Choices Notes
MSG Message text, or Character value Optional, Positional 1
MSGID Message identifier Name Optional
MSGF Message file Qualified object name Optional
Qualifier 1: Message file Name
Qualifier 2: Library Name, *LIBL, *CURLIB
MSGDTA Message data field values Character value Optional
VALUES Valid reply values Values (up to 20 repetitions): Character value, *NONE Optional
DFT Default reply value Character value, *MSGDFT Optional
MSGTYPE Message type *INQ, *INFO Optional
TOMSGQ To message queue Single values: *, *EXT, *SYSOPR
Other values: Qualified object name		 Optional
Qualifier 1: To message queue Name
Qualifier 2: Library Name, *LIBL, *CURLIB
TOUSR To user profile Name, *SYSOPR, *REQUESTER Optional
MSGRPY CL var for message reply Character value Optional
TRNTBL Translate table Single values: *NONE
Other values: Qualified object name		 Optional
Qualifier 1: Translate table Name, QSYSTRNTBL
Qualifier 2: Library Name, *LIBL, *CURLIB
CCSID Coded character set ID 1-65535, *HEX, *JOB Optional

Message text, or (MSG)

Specifies the message text of an immediate message that is sent by the program. A maximum of 512 characters can be specified. The text string must be enclosed in apostrophes if special characters (including blanks) are used. If this parameter is specified, values cannot be specified for the Message identifier (MSGID) parameter, Message file (MSGF) parameter, or Message data field values (MSGDTA) parameter.

'text'
Specify the text of the immediate message to be sent.

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 a coded character set identifier is supplied in the CCSID parameter. 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/.

Message identifier (MSGID)

Specifies the message identifier of a predefined message sent by the program to a message queue. If a value is specified for this parameter, a value must also be specified for the Message file (MSGF) parameter, and a value cannot be specified for the Message text, or (MSG) parameter.

identifier
Specify the message identifier of the message to be sent.

Message file (MSGF)

Specifies the message file that contains the predefined message to be sent. This parameter is valid only if a value is specified for the Message identifier (MSGID) parameter.

Qualifier 1: Message file

name
Specify the name of the message file which contains the predefined message to be 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 message file. If no current library entry exists in the library list, QGPL is used.
name
Specify the library in which the message file is located.

Message data field values (MSGDTA)

Specifies the character string or the CL variable that contains a character string used as the message data in the predefined message. A character string that is specified contains one or more substitution values that are used in place of the substitution variables that were defined in the message's text when the message was defined. The MSGDTA parameter is valid only if a predefined message is being sent. For more information, refer to the description of the MSGDTA parameter of the Send Program Message (SNDPGMMSG) command.

*NONE
No message data is specified for the predefined message.
message-data
Specify the character string that gives the substitution values in the specified predefined message that is sent, or specify the name of the variable that contains the character string.

Coded Character Set Identifier (CCSID) Considerations

The text supplied for the MSGDTA parameter that corresponds to the *CCHAR type field is assumed to be in the CCSID of the job running this command unless a coded character set identifier is supplied in the CCSID parameter. All other text supplied for the MSGDTA parameter is assumed to be 65535 and is not converted. 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/. For more information about the *CCHAR type field, see the Add Message Description (ADDMSGD) command.

Valid reply values (VALUES)

Specifies a list of valid replies to an inquiry message sent by this command. No more than 20 replies can be specified in the list. If the reply to the inquiry message does not match one of the specified values, an error message is sent to the reply's sender and the inquiry message is sent again. This value is valid only when a value is specified for the MSGRPY parameter.

Translation of the reply, if requested (on the TRNTBL parameter), will occur before verification of a match between the reply and the specified value. If TRNTBL (*LIBL/QSYSTRNTBL) is used to translate the reply values from lowercase to uppercase and lowercase characters still appear in a specified value, there is no match.

Variables can be used in the list of replies. This parameter is valid only if MSGTYPE(*INQ) is specified.

*NONE
No replies to inquiry messages are specified. Any reply to an inquiry message is valid.
allowable-values
Specify no more than 20 values that are compared to replies received for inquiry messages sent by this command. The maximum length of each value is 32 characters. If this value is specified, the CL var for message reply (MSGRPY) parameter must also be specified.

Default reply value (DFT)

Specifies the value used as the reply to an inquiry message (sent by this command) if the inquiry message is sent to a message queue that is in default delivery mode, or for any other reason the default reply is sent.

*MSGDFT
The default value defined in the message description of the message ID (specified for the MSGID parameter) is used. If no message ID is specified, the default value is *N.
'default-reply-value'
Specify the reply (enclosed in apostrophes) used as the default reply. This value can only be specified if the CL var for message reply (MSGRPY) parameter is specified. If a predefined message is being sent, this default-reply-value overrides any default reply specified in the message description.

Message type (MSGTYPE)

Specifies the type of message to be sent. Only inquiry and informational messages can be specified.

*INQ
An inquiry message is sent and the message queue receiving the message must reply to it.
*INFO
An informational message is sent.

To message queue (TOMSGQ)

Specifies the name of the message queue to which the message is to be sent. This parameter cannot be used if a value is specified for the To user profile (TOUSR) parameter.

Single values

*
In an interactive job, the message is to be sent to the external message queue (*EXT). In a batch job, the message is to be sent to the system operator (message queue QSYSOPR in library QSYS).
*SYSOPR
The message is to be sent to the system operator (message queue QSYSOPR in library QSYS).
*EXT
The message is to be sent to the job's external message queue. For batch job inquiry messages, the default reply is always received. Messages sent to this queue can be 512 characters in length, but only 76 characters are displayed on the Display Program Messages display.

Qualifier 1: To message queue

name
Specify the name of the message queue that is to receive the message being 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 message queue. If no current library entry exists in the library list, QGPL is used.
name
Specify the library where the message queue is located.

To user profile (TOUSR)

Specifies that the message is to be sent to the message queue specified in the user profile for the user named on this parameter. This parameter cannot be used if a value is specified for the To message queue (TOMSGQ) parameter.

*SYSOPR
The message is to be sent to the system operator user profile message queue, QSYS/QSYSOPR.
*REQUESTER
The message is to be sent to the user profile message queue for interactive jobs or to the system operator's message queue (QSYS/QSYSOPR) for batch jobs.
name
Specify the user profile name of the user to whom the message is to be sent.

CL var for message reply (MSGRPY)

Specifies the CL character variable (of up to 132 characters) that contains the reply received in response to an inquiry message. This parameter is valid only if *INQ is specified for the Message type (MSGTYPE) parameter. If the reply is longer than the variable, it is truncated; if it is shorter, it is padded to the right with blanks. This command will wait for a response to the inquiry message even if no value is coded for this parameter when MSGTYPE(*INQ) is specified. If no value is coded for this parameter when MSGTYPE(*INQ) is specified, the command awaits a response from the operator in reply to the inquiry message.

Translate table (TRNTBL)

Specifies the name of the translation table that is used if the reply value is being translated.

Qualifier 1: Translate table

QSYSTRNTBL
The translation table named QSYSTRNTBL is used to translate the reply value.

The IBM-supplied translation table QSYSTRNTBL table translates, for the English language only, all lowercase characters in the range of X'81' to X'A9' to uppercase characters. All other characters are not translated.

To use a different translation table, use the Create Table (CRTTBL) command and specify that particular table for this parameter.

*NONE
The reply is not being translated.
name
Specify the name of the translation table that is used to translate the message reply.

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 translation table. If no current library entry exists in the library list, QGPL is used.
name
Specify the library where the translation table is located.

Coded character set ID (CCSID)

Specifies the coded character set identifier (CCSID) that the message text supplied for the MSG (message) or MSGDTA (message data) parameters is in. If a message identifier is specified, the text supplied by the MSGDTA (message data) parameter that corresponds to the *CCHAR type field is assumed to be in the CCSID supplied by this parameter. The data supplied that does not correspond to the *CCHAR type field is assumed to be 65535 and is not converted. For more information about the *CCHAR type field see the Add Message Description (ADDMSGD) command.

If no message identifier is specified, the text supplied by the MSG (message) parameter is assumed to be in the CCSID supplied by this parameter. 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 supplied by the MSGDTA (message data) or MSG (message) parameter is assumed to be in the CCSID of the job running this command.
*HEX
The text supplied by the MSGDTA (message data) or MSG (message) parameter is not converted. CCSID 65535 is used.
coded-character-set-identifier
Specify a valid CCSID in which you want your text specified for the MSG (message) or MSGDTA (message data) parameter to be considered in. Valid values range from 1 through 65535. This command validates the CCSID. See the Globalization information in the iSeries Information Center at http://www.ibm.com/eserver/iseries/infocenter for a list of CCSID values.

Examples

Example 1: Message Requiring Specific Reply 

SNDUSRMSG   MSG('Data verified. Update master files (Y,N)?')
            TOMSGQ(*)  VALUES(Y N)  DFT(N)  MSGRPY(&REPLY)

This command sends an inquiry message to the display station operator (if it is used in an interactive job) or to the system operator (if it is used in a batch job). The valid replies are Y and N, and any other reply is rejected. The reply is returned in the variable &REPLY. The default translation table, QSYSTRNTBL, is used to translate the reply to uppercase characters.

Example 2: Message Requiring Any Reply 

SNDUSRMSG   MSG('Enter any response when ready to continue.')
            TOMSGQ(WS01)

This command sends an inquiry message to a specific message queue. Any reply is valid. Because the purpose of this example is simply to wait, no CL variable is provided to receive the reply.

Example 3: Sending an Information Message 

SNDUSRMSG   MSGID(USR0150)  TOUSR(FRED)  MSGF(QGPL/USRMSGF)
            MSGDTA(&ACCTNO)  MSGTYPE(*INFO)

This command sends a predefined message as an information message to the message queue specified in the user profile of the specified user (FRED). The message data provided is included in the message.

Error messages

*ESCAPE Messages

CPF247E
CCSID &1 is not valid.
CPF2559
Error occurred in SNDUSRMSG command.