Send Reply Message (QMHSNDRM) API

The Send Reply Message (QMHSNDRM) API sends a reply message to the sender of an inquiry message.

If your application attempts to diagnose and recover from errors, it might need to take additional action when using the QMHSNDRM API. When the QMHSNDRM API encounters errors in the reply being sent, it sends a diagnostic message describing each error to your program message queue. After the last diagnostic message, the QMHSNDRM API sends a general escape message, CPF2422. Exit point QIBM_QMH_REPLY_INQ has been added to the system registration facility to allow an exit program to be called when a reply is sent to an inquiry message. A reply handling exit program can accept, reject or replace the reply value. If the reply is rejected, a diagnostic is sent followed by CPF2422 as indicated above. If the reply value sent with this API is replaced by a reply handling exit program, CPF2458 (Reply replaced by reply handling exit program) is sent as a diagnostic message to the caller of the QMHSNDRM API to identify the new reply value and then the CPF2458 is sent again as a status message that could be monitored to allow an application to be notified of the reply replacement.

To diagnose and recover from these errors, your application should call the QMHRCVPM API to receive the diagnostic messages sent.

Authorities and Locks

Message File Authority

*USE

Message File Library Authority

*EXECUTE

Message Queue Authority

*USE and *ADD. Also need *DLT to remove a message.

Message Queue Library Authority

*EXECUTE

Required Parameter Group

Message key

INPUT; CHAR(4)

The key to the inquiry message that the reply answers. The key is assigned by the command or API that sends the message. You can obtain the key in these ways:

• By receiving an inquiry message with any of the following:
  • Receive Message (RCVMSG) command
  • Receive Program Message (QMHRCVPM) API
  • Receive Nonprogram Message (QMHRCVM) API
  • List Messages (QMHLSTM) API
  • List Job Log (QMHLJOBL) API
• Through a break-handling program. See the CL Programming topic for more information.

Qualified message queue name

INPUT; CHAR(20)

The name of the message queue containing the inquiry message being answered, and the library in which it resides. The message queue is the one in which the inquiry--not the sender's copy--is located. The first 10 characters specify the message queue, 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

Reply text

INPUT; CHAR(*)

The complete text of the reply being sent. To send the default reply stored in the message description, use blanks for this parameter. A reply handling exit program can be used to limit the use of default replies. See the allow default reply rejection parameter below for more information.

Length of reply text

INPUT; BINARY(4)

The length of the reply text, in bytes. If you use blanks in the reply text parameter to indicate that you are using the default reply, you can specify any valid value for this parameter. Valid values are 1 through 132.

Remove message

INPUT; CHAR(10)

Whether the inquiry message and the reply are removed from the message queue after the reply is sent. Valid values follow:

*NO	Keep the inquiry message and the reply.
*YES	Remove the inquiry message and the reply.

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 1

Coded character set identifier

INPUT; BINARY(4)

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

0	The message reply text is assumed to be in the CCSID of the job running this API. This is the default value if this parameter is not specified.
65535	The message reply text will not be converted.
CCSID	Specify a valid CCSID that your message reply text is in. Valid values are between 1 and 65535. This API will validate the CCSID.

For a list of valid CCSIDs, see CCSIDs: Message Support in the Globalization topic.

Optional Parameter Group 2

Allow default reply rejection

INPUT; CHAR(10)

Specifies whether a reply handling exit program will be allowed to reject a default reply. A default reply is requested by using blanks as the value for the reply text parameter. A reply handling exit program can be registered using the system registration facility for exit point QIBM_QMH_REPLY_INQ. If this parameter is not specified, a value of *NO is used. Valid values are:

*NO

A reply handling exit program will not be allowed to reject a default reply.

*YES

A reply handling exit program will be allowed to reject a default reply. If an exit program rejects the reply, a CPD2476 (Reply rejected by a reply handling exit program) will be sent as a diagnostic message to the program using this function. The CPD2476 will be followed by a CPF2422 (Reply not valid) escape message that the program using this function should monitor for to handle and recover from error situations.

Note: If a default reply is not being sent, this parameter is ignored and a reply handling exit program can reject or replace the reply value.

Coded Character Set Identifier (CCSID) Considerations

If the inquiry message that this reply is being sent to is an impromptu message, the text supplied on the reply 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. If the inquiry message that this reply is being sent to is a predefined message, then the text supplied on the reply text parameter is considered 65535 and is not converted. For more information about message handler and its use of CCSIDs, see CCSIDs: Message Support in the Globalization topic.

Error Messages