MQMD SOAP settings

The IBM MQ SOAP sender and IBM MQ SOAP listener create a message descriptor ( MQMD ). The topic describes the fields you must set in the MQMD if you create your own SOAP sender or listener.

Purpose

The values set in the MQMD control the exchange of messages between the IBM MQ SOAP sender, the IBM MQ SOAP listener, and the SOAP client program. If you create your own SOAP sender or listener, follow the rules in Table 1.

Description

Table 1 describes how the MQMD fields are set by the IBM MQ SOAP sender and IBM MQ SOAP listener. If you write your own sender or listener you must set these fields in accordance with the rules for exchanging messages. The IBM MQ SOAP listener conforms to typical IBM MQ message exchange protocols. If you write your own sender to work with the IBM MQ SOAP listeners, we can set different MQMD values. In Table 1, the values in the Setting column are organized as follows:

Request, One way: Sets made by IBM MQ SOAP sender.
Response, Report: Sets made by IBM MQ SOAP listener in response to IBM MQ SOAP sender request.
ALL: Sets made by both the IBM MQ SOAP sender and IBM MQ SOAP listener.
Customized sender: We can write your own sender. Typically, a customized sender overrides the standard report options.

Table 1. MQMD SOAP settings
Field name	Set	Values
StrucId	ALL MQMD_STRUC_ID	'MD¬¬' ¹
Version	ALL MQMD_VERSION_2	2
Report	ALL MQRO_NONE + MQRO_NEW_MSG_ID + MQRO_COPY_MSG_ID_TO_CORREL_ID + MQRO_EXCEPTION + MQRO_EXPIRY + MQRO_DISCARD Customized sender See Customized report options	52428800
MsgType	Request MQMT_REQUEST Response MQMT_REPLY Report MQMT_REPORT One way MQMT_DATAGRAM	MQMT_REQUEST 1 MQMT_REPLY 2 MQMT_REPORT 4 MQMT_DATAGRAM 8
Expiry	Request, One way Specified by Expiry option in URI. Defaults to MQEI_UNLIMITED. Response Value of Expiry in request message Report MQEI_UNLIMITED	MQEI_UNLIMITED -1
Feedback	Request, Response, One way MQFB_NONE. Report Generated by queue manager - value set according to normal rules. Generated by IBM MQ SOAP Listener: MQRC_BACKOUT_THRESHOLD_REACHED Backout threshold for multiple attempts exceeded. MQRCCF_MD_FORMAT_ERROR The message is not recognized as having an MQRFH2 header. MQRC_RFH_PARM_MISSING A required parameter, for example, SoapAction, in MQRFH2 is missing. MQRC_RFH_FORMAT_ERROR A basic integrity check of the MQRFH2 failed, for example, internal lengths are corrupted. MQRC_RFH_ERROR The MQRFH2 passed an integrity check, but the body of the message is not set to MQFMT_NONE.	MQFB_NONE 0 MQRC_BACKOUT_THRESHOLD_REACHED 2362 MQRCCF_MD_FORMAT_ERROR 3023 MQRC_RFH_PARM_MISSING 2339 MQRC_RFH_FORMAT_ERROR 2421 MQRC_RFH_ERROR 2334
Encoding	ALL MQENC_NATIVE	Depends on environment
CodedCharSetId	ALL Set to UTF-8	1208
Format	Request, Response, One way MQFMT_RF_HEADER_2 Report Queue manager reports Follows IBM MQ rules IBM MQ SOAP listener reports Format of the original request message.	MQFMT_RF_HEADER_2 MQRFH2
Priority	Request, One way Specified by Priority option in URI. Defaults to MQPRI_PRIORITY_AS_Q_DEF. Response, Report Value of Priority in the request message.	MQPRI_PRIORITY_AS_Q_DEF -1
Persistence	Request, One way MQPER_PERSISTENCE_AS_Q_DEF. Response, Report Value of Persistence in the request message.	MQPER_PERSISTENCE_AS_Q_DEF 2
MsgId	Request, One way Generated by the queue manager. Response, Report The IBM MQ SOAP sender sets MQRO_NEW_MSG_ID and MsgId is generated	Generated Unique value generated by the queue manager
CorrelId	Request, One way, Report MQCI_NONE Response, Report The IBM MQ SOAP sender sets MQRO_COPY_MSG_ID_TO_CORREL_ID and the listener copies MsgId from the request message.	MQCI_NONE 0
BackoutCount	ALL Not used	0
ReplyToQ	Request Specified by replyDestination option in URI. Defaults to SYSTEM.SOAP.RESPONSE.QUEUE. Response, One way, Report Left blank
ReplyToQMgr	ALL Field left blank	Generated by the queue manager; see Reply-to queue and queue manager.
UserIdentifier	Request, One way, Report Left blank Response Depends on the -i passContext option supplied to the listener, and the authority the listener is running under.	Request, One way, Report Generated by the queue manager; see UserIdentifier (MQCHAR12) Response Variable
AccountingToken	ALL MQACT_NONE	MQACT_NONE Null string or blanks Set by the queue manager; see AccountingToken (MQBYTE32)
ApplIdentityData	ALL None	Null string or blanks ²
PutApplType	ALL MQAT_NO_CONTEXT	MQAT_NO_CONTEXT 0 Value generated by queue manager; see PutApplType (MQLONG).
PutApplName	ALL None	Value generated by queue manager; see PutApplName (MQCHAR28).
PutDate	ALL None	Value generated by queue manager; see PutDate (MQCHAR8).
PutTime	ALL None	Value generated by queue manager; see PutTime (MQCHAR8).
ApplOriginData	ALL None	Null string or blanks ²
GroupId	Request, One way, Report MQGI_NONE Response Field is copied from the request message	Nulls
MsgSeqNumber	Request, One way, Report Not used Response Field is copied from the request message	Generated by the queue manager; see Physical order on a queue.
Offset	Request, One way, Report Not used Response Field is copied from the request message	0
MsgFlags	Request, One way, Report MQMF_NONE Response Field is copied from the request message	MQMF_NONE 0 See MsgFlags (MQLONG)
OriginalLength	Request, One way, Response MQOL_UNDEFINED Report Length of original request message	MQOL_UNDEFINED -1
Notes: The symbol ¬ represents a single blank character. The value Null string or blanks denotes the null string in C, and blank characters in other programming languages.

Customized report options

We can write your own SOAP sender and use it with the supplied listeners. Typically you might write a sender to change the choice of report options. The IBM MQ SOAP listeners support most combinations of report options, as described in the following lists.

Report options supported by IBM MQ SOAP listeners:
- MQRO_EXCEPTION
- MQRO_EXCEPTION_WITH_DATA
- MQRO_EXCEPTION_WITH_FULL_DATA
- MQRO_DEAD_LETTER_Q
- MQRO_DISCARD_MSG
- MQRO_NONE
- MQRO_NEW_MSG_ID
- MQRO_PASS_MSG_ID
- MQRO_COPY_MSG_ID_TO_CORREL_ID
- MQRO_PASS_CORREL_ID
Report options supported by the queue manager:
- MQRO_COA
- MQRO_COA_WITH_DATA
- MQRO_COA_WITH_FULL_DATA
- MQRO_COD
- MQRO_COD_WITH_DATA
- MQRO_COD_WITH_FULL_DATA
- MQRO_EXPIRATION
- MQRO_EXPIRATION_WITH_DATA
- MQRO_EXPIRATION_WITH_FULL_DATA
The following report options are not supported by the IBM MQ SOAP listeners.
- MQRO_PAN
- MQRO_NAN

The behavior of IBM MQ SOAP listeners in response to combinations of MQRO_EXCEPTION_* and MQRO_DISCARD is described in Table 2.

The notation MQRO_EXCEPTION_* indicates the use of either MQRO_EXCEPTION, MQRO_EXCEPTION_WITH_DATA or MQRO_EXCEPTION_WITH_FULL_DATA.

Table 2. Listener behavior resulting from MQRO_EXCEPTION_* and MQRO_DISCARD settings
	MQRO_DISCARD enabled	MQRO_DISCARD not enabled
MQRO_EXCEPTION_* enabled	Default behavior. Report messages are automatically generated if necessary and the original request discarded. If a report message could not be returned to the response queue the report message is sent to the dead letter queue.	Report messages are automatically generated if necessary and the original message is sent to the dead letter queue. If the report message could not be returned to the response queue it is also be sent to the dead-letter queue. In this case there are therefore two dead letter queue entries for the failed request.
MQRO_EXCEPTION_* not enabled	Report messages are not automatically generated when the incoming format is not recognized or the number of backout attempts is exceeded. The message is not sent to the dead letter queue. No notification is returned that the client can inspect, and the original request message is lost.	Report messages are not automatically generated when the incoming format is not recognized or the number of backout attempts is exceeded. The original request message is however written to the dead letter queue when a report would otherwise have been generated.