Consumer : tibemsMsgConsumer

tibemsMsgConsumer
Type
Purpose
Consume messages from a destination.
Remarks
Consumers can receive messages synchronously (using the receive functions), or asynchronously.
Consumers can receive messages asynchronously using callback functions.
Clients create message consumers using functions of a tibemsSession object.
 
See Also
tibemsMsgCallback on page 172
tibemsSession_CreateConsumer on page 293
tibemsMsgConsumer_Close
Function
Purpose
Closes a message consumer and releases associated storage.
C Declaration
tibems_status tibemsMsgConsumer_Close(
    tibemsMsgConsumer msgConsumer );
COBOL Call
CALL "tibemsMsgConsumer_Close"
USING BY VALUE msgConsumer,
RETURNING tibems-status
END-CALL.
 
msgConsumer has usage pointer.
Parameters
 
Remarks
If a receive call or a message listener callback is in progress, then this function waits until that call returns, and then closes the consumer.
This call also notifies the server that the client program is closing the consumer. In response, the server stops sending message data to the consumer.
Your program must explicitly close all consumers that it creates.
See Also
tibemsMsgConsumer_Receive on page 168
tibemsSession_CreateConsumer on page 293
tibemsMsgConsumer_GetDestination
Function
Purpose
Get the destination from a message consumer.
C Declaration
tibems_status tibemsMsgConsumer_GetDestination(
    tibemsMsgConsumer msgConsumer,
    tibemsDestination* destination );
COBOL Call
CALL "tibemsMsgConsumer_GetDestination"
USING BY VALUE msgConsumer,
BY REFERENCE destination,
RETURNING tibems-status
END-CALL.
 
msgConsumer and destination have usage pointer.
Parameters
 
Remarks
The consumer consumes messages from this destination.
Programs set this destination when creating the consumer, and cannot subsequently change it.
tibemsMsgConsumer_GetMsgListener
Function
Purpose
Get the message callback and closure data from a consumer.
C Declaration
tibems_status tibemsMsgConsumer_GetMsgListener(
    tibemsMsgConsumer msgConsumer,
    tibemsMsgCallback* callbackPtr,
    void** closure );
Parameters
 
The function stores a pointer to the closure data in this location. This pointer is passed into the message listener callback.
Remarks
EMS C programs can implement a message listener as a callback function paired with closure data. This call extracts these items from a consumer object.
Your program implements the callback, and registers it by calling tibemsMsgConsumer_SetMsgListener. When a message arrives, the consumer calls the callback.
This call is not supported in COBOL.
See Also
tibemsMsgConsumer_SetMsgListener on page 171
tibemsMsgCallback on page 172
tibemsMsgConsumer_GetMsgSelector
Function
Purpose
Get the message selector from a consumer.
C Declaration
tibems_status tibemsMsgConsumer_GetMsgSelector(
    tibemsMsgConsumer msgConsumer,
    const char** selectorPtr );
COBOL Call
CALL "tibemsMsgConsumer_GetMsgSelector"
USING BY VALUE msgConsumer,
BY REFERENCE selectorPtr,
RETURNING tibems-status
END-CALL.
 
msgConsumer and selectorPtr have usage pointer.
Parameters
 
Remarks
A message selector restricts the set of messages that the consumer receives to those that match the selector; see Message Selectors.
Programs can set this property only when creating the consumer object; see tibemsSession_CreateConsumer on page 293.
See Also
tibemsMsgCallback on page 172
tibemsMsgConsumer_GetNoLocal
Function
Purpose
Get the no local property of a message consumer.
C Declaration
tibems_status tibemsMsgConsumer_GetNoLocal(
    tibemsMsgConsumer msgConsumer,
    tibems_bool* noLocal );
COBOL Call
CALL "tibemsMsgConsumer_GetNoLocal"
USING BY VALUE msgConsumer,
BY REFERENCE noLocal,
RETURNING tibems-status
END-CALL.
 
msgConsumer has usage pointer.
Parameters
 
Remarks
When true, the consumer does not receive messages sent through the same server connection (that is, the connection associated with the consumer).
Programs set this property when creating the consumer, and cannot subsequently change it.
This property is only associated with topics, and does not apply to queues.
tibemsMsgConsumer_Receive
Function
Purpose
Receive a message (synchronous).
C Declaration
tibems_status tibemsMsgConsumer_Receive(
    tibemsMsgConsumer msgConsumer,
    tibemsMsg* message );
COBOL Call
CALL "tibemsMsgConsumer_Receive"
USING BY VALUE msgConsumer,
BY REFERENCE message,
RETURNING tibems-status
END-CALL.
 
msgConsumer and message have usage pointer.
Parameters
 
Remarks
This function consumes the next message from the consumer’s destination.
When the destination does not have any messages ready, this function blocks:
 
When calling tibemsMsgConsumer_Receive from a transaction, the consumer retains the message until transaction commits.
See Also
tibemsMsgConsumer_ReceiveNoWait on page 169
tibemsMsgConsumer_ReceiveTimeout on page 170
tibemsMsgConsumer_ReceiveNoWait
Function
Purpose
Receive a message (synchronous, non-blocking).
C Declaration
tibems_status tibemsMsgConsumer_ReceiveNoWait(
    tibemsMsgConsumer msgConsumer,
    tibemsMsg* message);
COBOL Call
CALL "tibemsMsgConsumer_ReceiveNoWait"
USING BY VALUE msgConsumer,
BY REFERENCE message,
RETURNING tibems-status
END-CALL.
 
msgConsumer and message have usage pointer.
Parameters
 
Remarks
When the destination has at least one message ready, this function immediately returns the next message.
When the destination does not have any messages ready, this function immediately returns TIBEMS_NOT_FOUND.
 
When calling receiving within a transaction, the consumer retains the message until transaction commits.
See Also
tibemsMsgConsumer_Receive on page 168
tibemsMsgConsumer_ReceiveTimeout on page 170
 
tibemsMsgConsumer_ReceiveTimeout
Function
Purpose
Receive a message (synchronous, blocks up to a time limit).
C Declaration
tibems_status tibemsMsgConsumer_ReceiveTimeout(
    tibemsMsgConsumer msgConsumer,
    tibemsMsg* message,
    tibems_long timeout );
COBOL Call
CALL "tibemsMsgConsumer_ReceiveTimeout"
USING BY VALUE msgConsumer,
BY REFERENCE message,
BY VALUE timeout,
RETURNING tibems-status
END-CALL.
 
msgConsumer and message have usage pointer.
Parameters
 
When present, wait no longer than this interval (in milliseconds) for a message to arrive. Zero is a special value, which specifies no timeout (block indefinitely).
Remarks
This function consumes the next message from the consumer’s destination. When the destination does not have any messages ready, this function blocks:
 
When calling receive within a transaction, the consumer retains the message until transaction commits.
See Also
tibemsMsgConsumer_Receive on page 168
tibemsMsgConsumer_ReceiveNoWait on page 169
tibemsMsgConsumer_SetMsgListener
Function
Purpose
Set the message callback and closure data of a consumer.
C Declaration
tibems_status tibemsMsgConsumer_SetMsgListener(
    tibemsMsgConsumer msgConsumer,
    tibemsMsgCallback callback,
    void* closure );
Parameters
 
Remarks
EMS C programs can implement a message listener as a callback function paired with closure data. This call sets these items in a consumer object.
Your program implements the callback, and registers it by calling this function. When a message arrives, the consumer calls the callback.
This call is not supported in COBOL.
See Also
tibemsMsgCallback on page 172