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:

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

Top

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 Globalization topic in the iSeries Information Center at http://www.ibm.com/eserver/iseries/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.

*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 Globalization topic in the iSeries Information Center at http://www.ibm.com/eserver/iseries/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.

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

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.

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.

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 Globalization topic in the iSeries Information Center at http://www.ibm.com/eserver/iseries/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.