SNDUSRMSG (Send User Message)

SNDUSRMSG Command syntax diagram

 

Purpose

The Send User Message (SNDUSRMSG) command is used by a program to send a message to a message queue and, optionally, to receive a reply to that message. The message sent using this command can be either an immediate message or a predefined message and it can be sent to a display station user either in an interactive job queue or in 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.

 

Required Parameters

MSG
Specifies the message text that is sent. A maximum of 512 characters can be specified. The string must be enclosed in apostrophes if special characters (including blanks) are used. If a value is specified on this parameter, the MSGID, MSGF, and MSGDTA parameters cannot be specified.

Coded Character Set Identifier (CCSID) Considerations

The text supplied on 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 Information Center.

MSGID
Specifies the message identifier of a predefined message sent by the program to a message queue. If a value is specified for the MSGID parameter, a value must also be specified for the MSGF parameter, while the MSG parameter cannot be specified.

MSGF
Specifies the qualified name of the message file that contains the predefined message (specified in the MSGID parameter) being sent. The MSGF parameter is valid only if a predefined message is being sent.

The name of the message file can be qualified by one of the following library values:

*LIBL: All libraries in the job's library list are searched until the first match is found.

*CURLIB: The current library for the job is searched. If no library is specified as the current library for the job, the QGPL library is used.

library-name: Specify the name of the library to be searched.

message-file-name: Specify the name of the message file to use.

 

Optional Parameters

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

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 predefined replies to inquiry messages are given. 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.

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 if for any other reason the default reply is sent. The value specified here as the default reply does not have to match an entry in the list of valid replies specified in the VALUES parameter. The default reply value is not translated to uppercase or validity-checked. This parameter is valid only if a value is specified for the MSGRPY parameter.

*MSGDFT: The default value defined in the message description of the message ID (specified on 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) which is used as the default reply. If a predefined message is being sent, this default-reply-value overrides any default reply specified in the message description.

MSGTYPE
Specifies the type of message 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.

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

*SYSOPR: The message is sent to the system operator's message queue, QSYS/QSYSOPR.

*REQUESTER: The message is sent to the user profile's message queue for interactive jobs or to the system operator's message queue (QSYS/QSYSOPR) for batch jobs.

user-profile-name: Specify the user profile name of the user to whom the message is sent.

TOMSGQ
Specifies the qualified name of the message queue to which the message is sent. This parameter cannot be used if TOUSR is specified.

*: In an interactive job, the message is sent to the external message queue (*EXT). In a batch job, the message is sent to the system operator's (QSYS/QSYSOPR) message queue.

*SYSOPR: The message is sent to the system operator's message queue, QSYS/QSYSOPR.

*EXT: The message is 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.

The name of the message queue can be qualified by one of the following library values:

*LIBL: All libraries in the job's library list are searched until the first match is found.

*CURLIB: The current library for the job is searched. If no library is specified as the current library for the job, the QGPL library is used.

library-name: Specify the name of the library to be searched.

message-queue-name: Specify the name of the message queue that is to receive the message being sent.

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 MSGTYPE(*INQ) is specified. 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.

TRNTBL
Specifies, if the reply value is being translated, the qualified name of the translate table used.

The name of the translate table can be qualified by one of the following library values:

*LIBL: All libraries in the job's library list are searched until the first match is found.

*CURLIB: The current library for the job is searched. If no library is specified as the current library for the job, the QGPL library is used.

library-name: Specify the name of the library to be searched.

QSYSTRNTBL: The translate table named QSYSTRNTBL (found in library *LIBL) is used to translate the reply value.

The IBM-supplied translate 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 translate table, use the Create Table (CRTTBL) command and specify that particular table for this parameter.

table-name: Specify the name of the translate table used to translate the message reply.

Other Single Values

*NONE: The reply is not being translated.

CCSID
Specifies the coded character set identifier (CCSID) that the message text supplied on 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 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 Information Center.

*JOB: The text supplied by the MSGDTA (message data) or MSG (message) parameters 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) parameters is not converted. CCSID 65535 is used.

coded-character-set-identifier: Specify a valid CCSID in which you want your text specified on 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 topic in the Information Center for a list of valid CCSID values.

Examples for SNDUSRMSG

Example 1: Message Requiring Specific Reply 

SNDUSRMSG  MSG('Data has been verified.  Do you
  want to update the master files (Y or 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 to this
  message when ready to continue with updates.')
  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 for SNDUSRMSG

*ESCAPE Messages

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