Send Reply Message (QMHSNDRM) API


  Required Parameter Group:


  Optional Parameter Group 1:


  Optional Parameter Group 2:


  Default Public Authority: *USE

  Threadsafe: Yes

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 Break Handling Exit Program for more information.
  • Through an inquiry handling program. See Inquiry Handling Exit Program 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 special value *EXT to send a reply to an inquiry message on the job's external message queue. The library portion of the name must be set to blanks. This value can be used by an inquiry handling exit program to send a reply to an inquiry on *EXT that needs a reply.

When a message queue name other than *EXT is specified, you can use these special values for the library name:


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:


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:

For a list of valid CCSIDs, see CCSID support for messages.


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:

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 CCSID support for messages.


Error Messages


API introduced: V2R1.1

[ Back to top | Message Handling APIs | APIs by category ]