Add Support for Retrieving Messages from IBM MQ by Matching Correlation ID and Message ID

[MohamedSabthar]

Description:
There is a requirement to obtain the message from the IBM-MQ using Correlation ID and/or Message ID.
For more information about obtaining message using matching Ids refer: https://www.ibm.com/docs/en/ibm-mq/9.4?topic=descriptor-msgid-mqbyte24-mqmd

Describe your problem(s)

Describe your solution(s)

Related Issues (optional):

Suggested Labels (optional):

Suggested Assignees (optional):

[ayeshLK]

To support the above change we need to do following API changes.

Introduce ibmmq:MatchOptions record type

# Represents the selection criteria that determine which message is retrieved.
#
# + messageId - The message identifier of the message which needs to be retrieved
# + correlationId - The Correlation identifier of the message which needs to be retrieved
public type MatchOptions record {|
    byte[] messageId?;
    byte[] correlationId?;
|};

Include ibmmq:MatchOptions as an optional parameter to ibmmq:GetMessageOptions record type

# IBM MQ get message options.
#
# + matchOptions - Message selection criteria
public type GetMessageOptions record {|
    // other fields
    MatchOptions matchOptions?;
|};

@NipunaRanasinghe please review.

[ayeshLK]

According to the IBM MQ documentation [1][2], when retrieving messages from a queue or a topic, multiple identifiers such as messageId and correlationId can be used together for message selection. If both messageId and correlationId are specified, only messages that match both identifiers will be retrieved.

[1] - IBM MQ - MQGMO Options
[2] - IBM MQ - Getting a Particular Message from a Queue

[NipunaRanasinghe]

@ayeshLK Ack. As per the offline discussion we had, then its okay to proceed with the existing design.

One minor improvement we can do is to use MQMI_NONE and MQCI_NONE as the default values for the messageId and correlationId, respectively.

public type MatchOptions record {|
    byte[] messageId = MQMI_NONE;
    byte[] correlationId = MQCI_NONE;
|};

wdyt?

[ayeshLK]

@ayeshLK Ack. As per the offline discussion we had, then its okay to proceed with the existing design.

One minor improvement we can do is to use MQMI_NONE and MQCI_NONE as the default values for the messageId and correlationId, respectively.

public type MatchOptions record {|
    byte[] messageId = MQMI_NONE;
    byte[] correlationId = MQCI_NONE;
|};

wdyt?

As per the documentation [1];

The message identifier MQMI_NONE is a special value that matches any message identifier in the MQMD for the message. Therefore, specifying MQMO_MATCH_MSG_ID with MQMI_NONE is the same as not specifying MQMO_MATCH_MSG_ID.

Same applies to the correlationId field as well. Hence marking the messageId and correlationId as optional would suffice IMO.

[1] - https://www.ibm.com/docs/en/ibm-mq/9.4?topic=options-matchoptions-mqlong-mqgmo