Copyright © TIBCO Software Inc. All Rights Reserved

> 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.

> Function | Description | Page
> tibemsMsgConsumer_Close | Closes a message consumer and releases associated storage. | 163
> tibemsMsgConsumer_GetDestination | Get the destination from a message consumer. | 164
> tibemsMsgConsumer_GetMsgListener | Get the message callback and closure data from a consumer. | 165
> tibemsMsgConsumer_GetMsgSelector | Get the message selector from a consumer. | 166
> tibemsMsgConsumer_GetNoLocal | Get the no local property of a message consumer. | 167
> tibemsMsgConsumer_Receive | Receive a message (synchronous). | 168
> tibemsMsgConsumer_ReceiveNoWait | Receive a message (synchronous, non-blocking). | 169
> tibemsMsgConsumer_ReceiveTimeout | Receive a message (synchronous, blocks up to a time limit). | 170
> tibemsMsgConsumer_SetMsgListener | Set the message callback and closure data of a consumer. | 171

> 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

> Parameter | Description
> msgConsumer | Close this consumer.

> 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

> Parameter | Description
> msgConsumer | Get the destination from this consumer.
> destination | The function stores the destination in this location.

> 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

> Parameter | Description
> msgConsumer | Get the listener from this consumer.
> callbackPtr | The function stores a pointer to the callback in this location.
> closure | 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

> Parameter | Description
> msgConsumer | Get the listener from this consumer.
> selectorPtr | The function stores a pointer to the selector string in this location.

> 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

> Parameter | Description
> msgConsumer | Get the property from this consumer.
> noLocal | The function stores the property value in this location.

> 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

> Parameter | Description
> msgConsumer | Receive a message through this consumer.
> message | The function stores a pointer to the inbound message in this location.

> Remarks
> This function consumes the next message from the consumer’s destination.
> When the destination does not have any messages ready, this function blocks:

> • | If a message arrives at the destination, this call immediately consumes that message and returns.

> • | If another thread closes the consumer, this call returns TIBEMS_INTR.

> 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

> Parameter | Description
> msgConsumer | Receive a message through this consumer.
> msg | The function stores a pointer to the inbound message in this location.

> 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

> Parameter | Description
> msgConsumer | Receive a message through this consumer.
> msg | The function stores a pointer to the inbound message in this location.
> timeout | 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:

> • | If a message arrives at the destination, this call immediately consumes that message and returns.

> • | If the (non-zero) timeout elapses before a message arrives, this call returns TIBEMS_TIMEOUT.

> • | If another thread closes the consumer, this call returns TIBEMS_INTR.

> 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

> Parameter | Description
> msgConsumer | Set the listener of this consumer.
> callback | Use this callback function.
> closure | Use this closure data.

> 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

Copyright © TIBCO Software Inc. All Rights Reserved