| 1 | Message text | Input | Char(*) |
| 2 | Length of message text | Input | Binary(4) |
| 3 | Message type | Input | Char(10) |
| 4 | List of qualified message queue names | Input | Array of Char(20) |
| 5 | Number of message queues | Input | Binary(4) |
| 6 | Qualified name of the reply message queue | Input | Char(20) |
| 7 | Error code | I/O | Char(*) |
| 8 | Coded character set identifier | Input | Binary(4) |
The Send Break Message (QMHSNDBM) API sends an immediate message to a work station message queue. This forces the message queue to be displayed, interrupting whatever is on the user's display. A message delivered in this way is called a break message. Use break messages to ensure that users see important information, such as a warning to sign off before you shut the system down for maintenance.
To keep break messages from interrupting a job, change the value of the BRKMSG parameter of the Change Job (CHGJOB) command to either *NOTIFY or *HOLD.
If your application attempts to diagnose and recover from errors, it might need to take additional action when using the QMHSNDBM API. The QMHSNDBM 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 program message queue. It 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 a general escape message CPF2469. This message is returned as an exception or in the error code.
To diagnose and recover from these errors, your program should call the QMHRCVPM API to receive the diagnostic messages sent.
When the message type being sent is an inquiry, the sender needs the following authority to the reply message queue:
The complete text of the immediate message being sent. You cannot include pointer data in this parameter.
Coded Character Set Identifier (CCSID) Considerations: The text supplied on the Message text parameter is assumed to be in the CCSID of the job executing this API unless the coded character set identifier is supplied in the CCSID parameter. For more information about message handler and its use of CCSIDs, see CCSID support for messages.
The length of the message text, in bytes. Valid values are 1 through 6000.
The type of the message. You must specify one of these values:
| *INFO | Informational. Conveys information without asking for a reply. |
| *INQ | Inquiry. Conveys information and asks for a reply. |
A list of 1 through 50 work station message queues to which the message is being sent, and the libraries in which they reside.
When you send an informational message, you can specify 1 through 50 specific message queues or use this special value for the message queue name:
| *ALLWS | All work station message queues. Use blanks for the library name, do not specify any other message queues, and specify 1 for the number of message queues parameter. |
When you send an inquiry message, specify only one message queue.
When you send an informational or inquiry message to a specific message queue, use the first 10 characters for the message queue name. Use the second 10 characters for the library name.
You can use this special value for the library name:
| *LIBL | The library list |
If you send a break message to a specific work station message queue and that work station is not logged on, no error is returned. However, diagnostic message CPF2429, Message to work station did not break, appears in the job log.
The number of message queues specified in the list of qualified message queue names parameter.
For informational (*INFO) messages, valid values are 1 through 50.
For inquiry (*INQ) messages or when using the special value *ALLWS for the message queue, you must specify 1.
For an inquiry message, 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 this special value for the message queue name:
| *PGMQ | The current call stack entry's call message queue. Use blanks for the library name. |
You can use these special values for the library name:
| *CURLIB | The job's current library |
| *LIBL | The library list |
For an informational message, use blanks for this parameter. If you specify a message queue, the API ignores it and does not return an error.
The structure in which to return error information. For the format of the structure, see Error code parameter.
The coded character set identifier (CCSID) that the supplied message text is in. The following values are allowed:
| 0 | The 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 message text will not be converted. |
| CCSID | Specify a valid CCSID that your message text 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. |
| Message ID | Error Message Text |
|---|---|
| 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. |
| CPF2421 E | Message not sent. &1 in &2 not work station message queue. |
| CPF2428 E | Message queue parameter is not valid. |
| CPF2429 E | Message to work station &1 did not break. |
| CPF2469 E | Error occurred when sending message&1. |
| CPF2401 E | Not authorized to library &1. |
| CPF2403 E | Message queue &1 in &2 not found. |
| CPF2408 E | Not authorized to message queue &1. |
| 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. |
| CPF2481 E | Work station message queue not available. |
| CPF8100 E | All CPF81xx messages could be returned. xx is from 01 to FF. |
| CPF3CF1 E | Error code parameter not valid. |
| CPF3C90 E | Literal value cannot be changed. |
| CPF9830 E | Cannot assign library &1. |
| CPF9872 E | Program or service program &1 in library &2 ended. Reason code &3. |