Send Message (QEZSNDMG) API

The Send Message (QEZSNDMG) API sends a message to one or more users or display stations and optionally shows the Operational Assistant Send a Message display before sending the message. Parameters can be specified, providing the ability to display initial values (defaults) to the user. Parameters determine:

• The type of message that is sent (informational or inquiry)
• The delivery mode of the message (break or normal)
• The message text
• The users or the display stations who will receive the message
• The message queue to receive the reply to an inquiry message
• Whether or not the Send a Message display is shown
• Whether the list of names contains user profile names or display station names

This API combines the functions of the Send Message (SNDMSG) and Send Break Message (SNDBRKMSG) commands. In addition, it provides the ability to:

• Send inquiry messages to more than one user
• Send break messages to user profiles
• Send break and inquiry messages to all active users
• Send nonbreak and inquiry messages to display stations

This API can be called with or without parameters. If parameters are specified, at least nine parameters are required. If this API is called in a batch job, parameter 10, Show Send a Message display, must be specified with a value of N. This will cause the message to be sent without using the Send a Message display.

Refer to Network Management APIs for information on alert messages. Refer to Message Handling APIs for information on the message handling APIs.

Authorities and Locks

Special Authority (*ALL or *ALLACT value on parameter 5)

*JOBCTL

SNDBRKMSG Command (*BREAK delivery mode on parameter 2)

*USE

Message Queue Authority

*OBJOPR and *ADD

Message Queue Library Authority

*EXECUTE

Send a Message Display

Optional Parameter Group 1

Message type

INPUT; CHAR(10)

The type of message to send. The value you specify determines the default for the Message needs reply prompt on the Send a Message display (N for *INFO and Y for *INQ). You must specify one of these values:

*INFO	Informational. The message does not need a reply.
*INQ	Inquiry. The message needs a reply. If the message queue and library name parameter was specified, the reply is placed on that message queue; otherwise, the reply is placed on the message queue specified in the user profile of the sender.
	The user profile name of the person sending the reply is added to the beginning of the message text, allowing the person receiving the reply to determine which user it is from.

Delivery mode

INPUT; CHAR(10)

The delivery mode of the message. The value you specify determines the default for the Interrupt user prompt on the Send a Message display (Y for *BREAK and N for *NORMAL). If the user is not authorized to send a break message, *NORMAL is used regardless of the value you specify. You must specify one of these values:

*BREAK

Break message. If the user is signed on, the message goes to the work station message queues that the user is signed on to and temporarily interrupts the work that the user is doing. If the user is not signed on, the message goes to the user profile message queue and the sender is notified. If display station names are specified, the message goes to the message queues for the specified display stations.

*NORMAL

The message goes to the user profile or display station message queue. If the message queue is in notify mode for that user, the message waiting light is turned on. If the message queue is in break mode, the message temporarily interrupts the work that the receiver is doing. If the message queue is in hold mode, the receiver is not notified.

Message text

INPUT; CHAR(*)

The complete text of the message. The text you specify is displayed as the default on the Send a Message display. This must not be blank if used in a batch job or if the Show Send a Message display parameter is N.

Length of message text

INPUT; BINARY(4)

The length of the message text, in bytes. Valid values are 0 through 494. This must be greater than 0 if the API is used in a batch job or if the Send a Message display is not to be shown.

List of user profile or display station names

INPUT; ARRAY OF CHAR(10)

A list of 0 through 299 user profile or display station names to which the message is being sent. The list you specify is shown as the default on the Send a Message display.

The name type indicator parameter indicates whether the names in the list are user profile names or display station names; the default is user profile names. At least one name must be specified if the API is used in a batch job or if the Send a Message display is not to be used.

The message is sent to the user profile or display station message queue. To specify other user message queues, use one of the following special values:

*ALL	The message queues of all users. When you use this value, it must be the only item in the list. This value cannot be used if *DSP is specified for the name type indicator parameter.
*ALLACT	The message queues of all active users or display stations. This value can be used in combination with specific user profile names or display station names and with *SYSOPR.
*SYSOPR	The system operator's message queue, QSYSOPR. This value can be used in combination with specific user profile names and with *ALLACT. It cannot be used if *DSP is specified for the name type indicator parameter.

If the list specifies display station names, the library list will be used to find the work station message queues.

Note: *JOBCTL special authority is required to use the *ALL or *ALLACT value in this parameter.

Number of user profile

or display station names

INPUT; BINARY(4)

The number of user profile or display station names specified. Valid values are 0 through 299. When you use the special value *ALL for the list of user profile or display station names parameter, specify 1. This must be greater than 0 if the API is used in a batch job or if the Send a Message display is not to be used.

Message sent indicator

OUTPUT; BINARY(4)

Whether the user pressed F10 (Send message) to send one or more messages from the Send a Message display. One of the following values is returned:

0	No messages were sent.
1	One or more messages were sent. If the Show Send a Message display parameter is N and the program completes without error, this will always be 1.
2	One or more messages were sent, but one or more of the names specified were not valid. If the Show Send a Message display parameter is Y or not specified, the user names will be displayed and validated before the message is sent; therefore, this value will not be used.

Function requested

OUTPUT; BINARY(4)

The function that the user requested when exiting the Send a Message display. One of the following values is returned:

-4	User pressed the Exit key (F3).
-8	User pressed the Cancel key (F12).
0	Send a Message display was not used.

Error code

I/O; CHAR(*)

The structure in which to return error information. For the format of the structure, see Error code parameter.

Optional Parameter Group 2

Show Send a Message display

INPUT; CHAR(1)

Whether or not to show the Send a Message display before sending the message. If this parameter is used, one of the following values must be specified;

Y	Use the Send a Message display. This is the default.
N	Do not use the Send a Message display. This value must be specified if the program is running in a batch job.

Qualified message queue name

INPUT; CHAR(20)

The name of the message queue that is to receive the reply for inquiry-type messages. The first 10 characters contain the message queue name, and the second 10 characters contain the library name. If this parameter is blank or not specified, the reply will be sent to the message queue specified in the user profile of the sender. This parameter is ignored if the message type parameter is not *INQ. If this parameter is used, you can use these special values for the library name:

*LIBL	The library list
*CURLIB	The job's current library

Name type indicator

INPUT; CHAR(4)

The type of names in the list. If this parameter is used, one of the following values must be specified:

*USR	The list of names contains only user profile names. *USR is the default.
*DSP	The list of names contains only display station names. This value may not be specified if the Show Send a Message display parameter is Y.

Optional Parameter Group 3

Coded character set identifier

INPUT; BINARY(4)

The coded character set identifier (CCSID) that the immediate message text is in. The following values are allowed:

0	The immediate message text is assumed in the CCSID of the job running this API. This is the default value if this parameter is not specified.
65535	The immediate message text will not be converted.
CCSID	Specify a valid CCSID that your immediate message is in. Valid values are between 1 and 65535. This API will validate the CCSID. For a list of valid CCSIDs, see the i5/OS globalization topic collection.

Error Messages

[ Back to top | Operational Assistant APIs | APIs by category ]