Send Nonprogram Message (QMHSNDM) API
Required Parameter Group:
| 1 | Message identifier | Input | Char(7) |
| 2 | Qualified message file name | Input | Char(20) |
| 3 | Message data or immediate text | Input | Char(*) |
| 4 | Length of message data or immediate text | Input | Binary(4) |
| 5 | Message type | Input | Char(10) |
| 6 | List of qualified message queue names | Input | Array of Char(20) |
| 7 | Number of message queues | Input | Binary(4) |
| 8 | Qualified name of the reply message queue | Input | Char(20) |
| 9 | Message key | Output | Char(4) |
| 10 | Error code | I/O | Char(*) |
Optional Parameter Group:
| 11 | Coded character set identifier | Input | Binary(4) |
Default Public Authority: *USE
Threadsafe: Yes
The Send Nonprogram Message (QMHSNDM) API sends a message to a nonprogram message queue so your program can communicate with another job or user.
To send a message to a call message queue or the external message queue, see Send Program Message (QMHSNDPM) API.
Before coding your call to the QMHSNDM API, see Dependencies among Parameters.
If your application attempts to diagnose and recover from errors, it might need to take additional action before calling the QMHSNDM API. The QMHSNDM API sends a message to a list of message queues. When the API encounters an error in sending your message to a message queue in the list, it sends a diagnostic message to your call message queue. The API then proceeds to the next message queue in the list. After trying to send the message to all specified message queues and if the API detected any errors, it returns the general escape message CPF2469. This message is sent as an exception or in the error code.
To diagnose and recover from these errors, your program should call the Receive Program Message (QMHRCVPM) API to receive the diagnostic messages sent.
Authorities and Locks
- Message File Authority
- *USE
- Message File Library Authority
- *EXECUTE
- Message Queue Authority
- *OBJOPR and *ADD
- Message Queue Library Authority
- *EXECUTE
- Reply Message Queue Authority
- *OBJOPR and *ADD
- Reply Message Queue Library Authority
- *EXECUTE
Required Parameter Group
- Message identifier
- INPUT; CHAR(7)
The identifying code for the predefined message being sent, or blanks for an immediate message.
If you specify a message identifier, you must specify a qualified message file name. If you do not specify a message identifier, the qualified message file name parameter is ignored.
- Qualified message file name
- INPUT; CHAR(20)
For a predefined message, the name of the message file and the library in which it resides. The first 10 characters specify the file name, and the second 10 characters specify the library.
You can use these special values for the library name:
*CURLIB The job's current library *LIBL The library list For an immediate message, use blanks for this parameter. If you specify a name, the API ignores it and does not return an error.
- Replacement data or impromptu message text
- INPUT; CHAR(*)
If a message identifier is specified, the data to insert in the predefined message's substitution variables. If no message identifier is specified, the complete text of an immediate message.
If this parameter contains pointer data, each pointer must start on a 16-byte boundary to keep the data accurate.
- Length of replacement data or impromptu message text
- INPUT; BINARY(4)
The length of the message data or immediate text, in bytes. Valid values for each are:
Replacement data 0-32767 Impromptu message text 1-6000
- Message type
- INPUT; CHAR(10)
The type of the message. You must specify one of these values:
*COMP Completion *DIAG Diagnostic *INFO Informational *INQ Inquiry. When you send an inquiry message, a copy of the message is placed on the reply message queue. The message key returned by this API is the key to that copy. To receive the reply, use the Receive Nonprogram Message (QMHRCVM) API, specifying that key and a message type of reply. To receive the copy of the inquiry, specify the same key and a message type of *COPY. To send reply messages, see Send Reply Message (QMHSNDRM) API. For descriptions of the message types, see Message Types. For details about coding the other parameters when sending a particular type of message, see Dependencies among Parameters.
- List of qualified message queue names
- INPUT; ARRAY of CHAR(20)
A list of 1 through 50 message queues to which the message is being sent, and the libraries in which they reside. When sending an inquiry message, you can list one message queue, or you can list two message queues if one of the queues is *HSTLOG. The special value *HSTLOG indicates the message will be sent to QSYS/QHST. When using the special value *ALLACT, you can list only one queue. In all other cases, you can list up to 50 message queues.
You can specify user profile message queues or other nonprogram message queues, or you can use several special values.
To specify the default message queue associated with a user profile, use the first 10 characters for the user profile name. In the second 10 characters, use the special value *USER.
To specify other nonprogram message queues, use the first 10 characters for the message queue name and the second 10 characters for the library name. You can use these special values for the library name:
*CURLIB The job's current library *LIBL The library list To specify other types of message queues, use one of the following special values for the first 10 characters, and leave the second 10 characters blank:
*ALLACT The default message queues of all active users. When you use this value, it must be the only item in the list. You cannot use this value with inquiry messages. *REQUESTER In an interactive job, the current user's message queue. In a batch job, the system operator's message queue, QSYSOPR. *SYSOPR The system operator's message queue, QSYS/QSYSOPR. Any message sent to QSYSOPR automatically has a copy of the message sent to QHST. *HSTLOG he system history log message queue, QSYS/QHST. If *HSTLOG is specified more than once, only one message will be sent to QSYS/QHST. If *HSTLOG is specified with QSYSOPR, only one message is sent to QSYS/QHST.
- Number of message queues
- INPUT; BINARY(4)
The number of message queues specified in the list of qualified message queue names parameter. Valid values are 1 through 50. When using the special value *ALLACT for the message queue, you must specify 1. When sending an inquiry message, you can specify 1 or you can specify 2 if one of the values is *HSTLOG.
- Qualified name of the reply message queue
- INPUT; CHAR(20)
For an inquiry message only, the name of the message queue to receive the reply message, and the library in which it resides.
The first 10 characters specify the message queue, and the second 10 characters specify the library.
You can use these special values for the message queue name:
*PGMQ The current call stack entry's call message queue. Use blanks for the library name. *WRKSTN The work station message queue. Use blanks for the library name. You cannot use this value when running in batch mode. You can use these special values for the library name:
*CURLIB The job's current library *LIBL The library list For all message types except inquiry, use blanks for this parameter. If you specify a message queue, the API ignores it and does not return an error.
- Message key
- OUTPUT; CHAR(4)
For an inquiry message only, the key to the sender's copy of the message in the reply message queue. This API assigns the key when it sends the message.
For all other message types, no key is returned.
- 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
- Coded character set identifier
- INPUT; BINARY(4)
The coded character set identifier (CCSID) that the supplied replacement data or impromptu message text is in. If a message identifier is specified, the text supplied by the replacement data or impromptu message text parameter that corresponds to *CCHAR type fields is assumed to be in the CCSID supplied by this parameter. The data supplied that does not correspond to a *CCHAR field is 65535 and is not converted. For more information about *CCHAR type fields see the Add Message Description (ADDMSGD) command.
If no message identifier is specified, the impromptu message text supplied by the replacement data or impromptu message text parameter will all be assumed to be in the CCSID supplied by this parameter. For more information about message handler and its use of CCSIDs, see CCSID support for messages. The following values are allowed:
0 The replacement data or impromptu 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 replacement data or impromptu message text will not be converted. CCSID Specify a valid CCSID that your replacement data or impromptu message is in. Valid values are between 1 and 65535. This API will validate the CCSID. For a list of valid CCSIDs, see CCSID support for messages.
Dependencies among Parameters
You can use many different combinations of parameters when calling the QMHSNDM API. The values you specify for the message identifier and message type parameters determine which other input parameters you must specify and which you must code as blanks. They also determine whether the system returns the message key in the message key output parameter.
The following table summarizes the use of parameters for the QMHSNDM API.
| Parameter | Message Type | |||
|---|---|---|---|---|
| *COMP, *DIAG, *INFO | *INQ | |||
| Predefined | Immediate | Predefined | Immediate | |
| Message identifier | Message ID | Blank | Message ID | Blank |
| Qualified message file name | Required | Ignored | Required | Ignored |
| Message data or immediate text | Data | Text | Data | Text |
| Length of message data or immediate text | 0-32767 | 1-6000 | 0-32767 | 1-6000 |
| List of qualified message queue names | Required | Required | Required | Required |
| Number of message queues | 1-50 | 1-50 | 1,2 if *HSTLOG | 1,2 if *HSTLOG |
| Reply message queue | Ignored | Ignored | Required | Required |
| Message key | Not used | Not used | Returned | Returned |
| Error code | Required | Required | Required | Required |
The terms used in the table to describe the parameter values are defined in the following list.
| Term | Meaning |
|---|---|
| Blank | You must use blanks for this parameter. |
| Data | You must specify data for this parameter. The data is used as the values for a predefined message's substitution variables. |
| Ignored | The API ignores this parameter. You should use blanks for the value, but if you use another value, no error is returned. |
| Message ID | You must specify the message identifier of the predefined message being sent. |
| Not used | The API does not return data in this output parameter. The space remains unchanged. |
| Required | You must specify a valid value for this parameter. |
| Returned | The API returns data in this output parameter. |
| Text | You must specify text for this parameter. The text is used as the complete text of an immediate message. |
Error Messages
| Message ID | Error Message Text |
|---|---|
| CPF2204 E | User profile &1 not found. |
| CPF24AC E | Either message identifier or message text must be specified. |
| CPF24A2 E | Value for number of message queues not valid. |
| CPF24B3 E | Message type &1 not valid. |
| CPF24B4 E | Severe error while addressing parameter list. |
| CPF24B6 E | Length of &1, not valid for message text or data. |
| CPF2428 E | Message queue parameter is not valid. |
| CPF2433 E | Function not allowed for system log message queue &1. |
| CPF2435 E | System reply list not found. |
| CPF2469 E | Error occurred when sending message&1. |
| CPF2401 E | Not authorized to library &1. |
| CPF2403 E | Message queue &1 in &2 not found. |
| CPF2407 E | Message file &1 in &2 not found. |
| CPF2408 E | Not authorized to message queue &1. |
| CPF2411 E | Not authorized to message file &1 in &2. |
| CPF2421 E | Message not sent. &1 in &2 not work station message queue. |
| CPF2460 E | Message queue &1 could not be extended. |
| CPF2467 E | &3 message queue &1 in library &2 logically damaged. |
| CPF2477 E | Message queue &1 currently in use. |
| CPF247E E | CCSID &1 is not valid. |
| CPF2548 E | Damage to message file &1 in &2. |
| CPF2557 E | System reply list damaged. |
| CPF2558 E | System reply list currently in use. |
| CPF8100 E | All CPF81xx messages could be returned. xx is from 01 to FF. |
| CPF2481 E | Work station message queue not available. |
| CPF2488 E | Reply message queue *WRKSTN not valid for batch job. |
| CPF2499 E | Message identifier &1 not allowed. |
| CPF3C90 E | Literal value cannot be changed. |
| CPF3CF1 E | Error code parameter not valid. |
| CPF9830 E | Cannot assign library &1. |
| CPF9872 E | Program or service program &1 in library &2 ended. Reason code &3. |
API introduced: V3R6