Sample c example solClient_msg_getCorrelationTag

Abhishek

Hi,
Can any one send the sample example for the correct usage of the correlation tag pointer API. solClient_msg_getCorrelationTag

TomF

Hi @Abhishek,
Yes, there don't seem to be any examples of getting the correlation tag in the samples directories. In the samples provided with the API, adPubAck.c does set the correlation tag:

   /*
         * For correlation to take effect, it must be set on the message prior to 
         * calling send. Note: the size parameter is ignored in the API.
         */
        if ( ( rc = solClient_msg_setCorrelationTagPtr ( msg_p, msgMemoryItem_p, sizeof ( *msgMemoryItem_p ) ) ) != SOLCLIENT_OK ) {

But getCorrelationTagPtr is never used because the tag is passed as part of the eventInfo_p in the flow acknowledge event:

    void
adPubAck_eventCallback ( solClient_opaqueSession_pt opaqueSession_p,
                         solClient_session_eventCallbackInfo_pt eventInfo_p, void *user_p )
{
    solClient_errorInfo_pt errorInfo_p;
    messageCorrelationStruct_pt correlationInfo = ( messageCorrelationStruct_pt ) eventInfo_p->correlation_p;

You'd use getCorrelationTag in a request/reply asynchronous interaction so that you could tell which request a reply you'd received was related to. So you'd store the outgoing correlation tag in a structure, attach it to your outgoing request, and then when a reply is received, call getCorrelationTag, look through your structure and find the outgoing request.

Abhishek

Thanks it helps.

Can you also please give a sample code example/use case for the usage below function for retrieving correlation tag,

solClient_dllExport solClient_returnCode_t solClient_msg_getCorrelationTagPtr(solClient_opaqueMsg_pt msg_p,
solClient_opaquePointer_pt bufPtr_p,
solClient_uint32_t * size_p
)

TomF

msg_getCorrelationTagPtr(solClient_opaqueMsg_pt msg_p, solClient_opaquePointer_pt bufPtr_p,solClient_uint32_t * size_p);
mytype correlation_id_ptr = (mytype*) bufPtr_p;

You mean? As in cast the void* buffer pointer to whatever type you filled it with?

Abhishek

I mean in which function we need to call this, because in the event call back ack we dont have solClient_opaqueMsg_pt.
In the event call back we have solClient_opaqueSession_pt .

TomF

Oh I see. This would normally be in the receive callback rather than the event callback.

What you're doing here is sending a request/response pattern message using persistence. Check this is what you want to do. I suspect you want request/response without persistence (if so, skip to the end)

The event callback is where you get the acknowledgment that the broker has received your outgoing request and persisted it - NOT that the request has been received by the destination replying application. This means that your requestor can assume that the request has been sent. You can now remove the message (not request) from memory.

In your replying application, you'll get the request in the receive callback. You'll just want to copy the correlation ID in to your reply.

Finally, in your original requesting application, you'll get the response in the receive callback for the flow that you've bound to the response queue. You'll extract the correlation ID there.

So, if in reality you want non-persistent request/reply (which I think is the case), the requester sends the message and waits for the reply. In the replying application, copy the correlation ID to the response message in the receive callback. In the requestor, when you get the response in the receive callback extract the correlation ID and look it up to match the request.

Abhishek

Thanks a lot Tom, this is very helpful. This is new insight to me.
In your response you mention, "In your replying application, you'll get the request in the receive callback. You'll just want to copy the correlation ID in to your reply."

Which c API can we use it? As per my understanding correlation ID and Correlation tag pointer are two similar but different concept in the solace.
I read somewhere that correlation tag pointer buffer do not get passed to the subscriber-side application. And so subscriber does not get to know the content of the correlation tag pointer buffer. Is it correct understanding?

And how does correlation ID works? As per your explanation correlation ID get passed through the solace appliance to the subscriber-application.

TomF

Damn, damn and more damn! @Abhishek you've caught me out. I didn't read the correlationTag docs properly and my answer above is wrong as you've spotted. I conflated the two but they're not the same. Apologies for the confusion.

Right, let's start again. Forget everything I've said.

correlationTag/correlationTagPtr is used for publishing guaranteed messages, and allows the application to correlate a "sent" published message with an asynchronous acknowledgement that comes in via the event callback. You can see this being used in the adPubAck.c sample that is shipped with the API.

correlationIDs are used for any style of messaging (direct or persistent) where you expect an asynchronous response from another application. It allows you to understand which request caused this incoming response.

So, to summarise:

• You are using direct (non-persistent) request/response: -> use correlationID;
• You are publishing a guaranteed message: -> use correlationTag
• You are publishing a request/response message using persistent messaging: -> use correlationTag to check your guaranteed request has been received by the broker, use correlationID to work out which request caused this incoming response.

Some psuedo code for the guaranteed request/response case:
1. Create request;
2. Create correlationID. Add request to your request tracking data structure with the correlationID;
3. Create the correlationTag. Create the request message, add the correlationID and the correlationTag;
4. Add the correlationTag to your guaranteed ack tracking data structure;
5. Send request message;
6. Some time later, you get a session event indicating an acknowledgement of the sent message. Check the correlationTag against your ack tracking structure and release the request message buffer (not the request istelf).
7. Some time after that, you get the response from the responding application. Check the correlationID against the request tracking structure to find out which request caused this response. Do your business logic. Once that's all finished, release the response message, free that part of the request tracking structure and release the request data.

Hope that makes sense.