getMessageByCorrelationID

getMessageByCorrelationID(msg:          JadeGenericMessage input;
                          options:      String;
                          correlIdList: Any): Boolean

The getMessageByCorrelationID method of the JadeGenericQueue class retrieves a message from the queue when the value of the correlationID property of the message matches one of the elements of the correlIdList parameter.

The contents of the message are copied into the message object passed into the method and specified by the msg parameter. If there are no messages with the specified correlationID value in the queue, the method returns false.

The value of the correlIdList parameter is a single Binary value or a BinaryArray value. In WebSphere MQ, the correlIdList parameter can be a single Binary value only, which should be stored in a maximum length variable or property, as trailing null characters are significant. If an empty Binary or null is passed, the method behaves identically to the getMessage method and the first available message is returned. A BinaryArray list must not contain more than 64 entries.

The JadeGenericQueue instance that created the msg message object (using the createMessage method) need not be the same instance that retrieves the message with the getMessageByCorrelationID method, but both JadeGenericQueue instances must use the same transport. If the msg object has previously been used to put an object in a queue by using the putMessage method or to retrieve a message from a queue by using the getMessage or getMessageByCorrelationID method, it must be initialized by using the initializeForGet method defined in the JadeGenericMessage class.

If the options parameter is an empty string, transport-specific default actions are taken. Options passed to this method override any specified in the defaultPutMessageOptions property. Components that can be included in the options parameter string for the JadeMQ transport are listed in the following table. (These options are ignored for the WebSphere MQ transport.)

Component	Result
NoWait	The method returns immediately if no message is available
Timeout=milliseconds	The method waits for the specified number of milliseconds for a message to arrive
Timeout=0	The method waits indefinitely (the default implied option)

The queue must be opened by the openQueue method defined in the JadeMessagingFactory class, with Usage=Get or Usage=All included in the options parameter.

The following example shows the use of the getMessageByCorrelationID method to retrieve a message from a queue.

vars
    factory : JadeMessagingFactory;
    msg : JadeGenericMessage;
    requestQ : JadeGenericQueue;
    replyQ : JadeGenericQueue;
    id : Binary;
begin
    create factory transient;
    requestQ := factory.openQueue("JadeMQ://localnode/RequestQ",
                                                             "Usage=Put");
    replyQ := factory.openQueue("JadeMQ://localnode/ReplyQ", "Usage=Get");
    msg := requestQ.createMessage(true);
    msg.replyQueueFullName := "JadeMQ://localnode/ReplyQ";
    msg.type := JadeGenericMessage.Type_Request;
    msg.appendString("Please reply to this request");
    requestQ.putMessage(msg, null);
    id := msg.messageID;     // To be used as the correlationID in the reply
    msg.initializeForGet;
    replyQ.getMessageByCorrelationID(msg, null, id);
    write msg.body.String;
epilog
    delete factory;
    delete msg;
    delete requestQ;
    delete replyQ;
end;