Chapter 15 Administration : tibemsConsumerInfo

tibemsConsumerInfo
Type
Purpose
Represent a message consumer in the server.
 
Related Types
tibemsStatData on page 491
tibemsDetailedDestStat on page 458
tibemsConsumerInfo_Destroy
Function
Purpose
Destroy a consumerInfo object.
C Declaration
tibems_status tibemsConsumerInfo_Destroy(
    tibemsConsumerInfo consumerInfo);
COBOL Call
CALL "tibemsConsumerInfo_Destroy"
 USING BY VALUE consumerInfo,
       RETURNING tibems-status
END-CALL.
Parameters
 
The consumerInfo object to be destroyed.
tibemsConsumerInfo_GetCreateTime
Function
Purpose
Get a consumer's creation time in milliseconds.
C Declaration
tibems_status tibemsConsumerInfo_GetCreateTime(
    tibemsConsumerInfo consumerInfo,
    tibems_long* ctime);
COBOL Call
CALL "tibemsConsumerInfo_GetCreateTime"
 USING BY VALUE consumerInfo,
       BY REFERENCE created,
       RETURNING tibems-status
END-CALL.
Parameters
 
tibemsConsumerInfo_GetCurrentMsgCountSentByServer
Function
Purpose
Get the number of messages sent to consumer and not yet acknowledged by consumer's session.
C Declaration
tibems_status tibemsConsumerInfo_GetCurrentMsgCountSentByServer(
    tibemsConsumerInfo consumerInfo,
    tibems_long* count);
COBOL Call
CALL "tibemsConsumerInfo_GetCurrentMsgCountSentByServer"
 USING BY VALUE consumerInfo,
       BY REFERENCE count,
       RETURNING tibems-status
END-CALL.
Parameters
 
Remarks
This function gets the number of messages sent to but not yet acknowledged by the consumer. For topic consumers, this number is included in the number of pending messages returned by tibemsConsumerInfo_GetPendingMessageCount.
See Also
tibemsConsumerInfo_GetPendingMessageCount on page 450
tibemsConsumerInfo_GetCurrentMsgSizeSentByServer
Function
Purpose
Get the combined size of messages sent to consumer and not yet acknowledged by consumer's session.
C Declaration
tibems_status tibemsConsumerInfo_GetCurrentMsgSizeSentByServer(
    tibemsConsumerInfo consumerInfo,
    tibems_long* size);
COBOL Call
CALL "tibemsConsumerInfo_GetCurrentMsgSizeSentByServer"
 USING BY VALUE consumerInfo,
       BY REFERENCE size,
       RETURNING tibems-status
END-CALL.
Parameters
 
Remarks
This function gets the combined size of messages sent to consumer and not yet acknowledged by consumer's session. For topic consumers this size is included into the combined size of pending messages returned by tibemsConsumerInfo_GetPendingMessageSize.
See Also
tibemsConsumerInfo_GetPendingMessageSize on page 451
tibemsConsumerInfo_GetDestinationName
Function
Purpose
Get the consumer's destination name.
C Declaration
tibems_status tibemsConsumerInfo_GetDestinationName(
    tibemsConsumerInfo consumerInfo,
    char* name,
    tibems_int name_len);
COBOL Call
CALL "tibemsConsumerInfo_GetDestinationName"
 USING BY VALUE consumerInfo,
       BY REFERENCE destName,
       BY VALUE name_len,
       RETURNING tibems-status
END-CALL.
Parameters
 
Length of the name buffer.
tibemsConsumerInfo_GetDestinationType
Function
Purpose
Get consumer's destination type.
C Declaration
tibems_status tibemsConsumerInfo_GetDestinationType(
    tibemsConsumerInfo consumerInfo,
    tibemsDestinationType* type);
COBOL Call
CALL "tibemsConsumerInfo_GetDestinationType"
 USING BY VALUE consumerInfo,
       BY REFERENCE destType,
       RETURNING tibems-status
END-CALL.
Parameters
 
See Also
tibemsDestinationType on page 143
tibemsConsumerInfo_GetDetailedStatistics
Function
Purpose
Get detailed statistics for a wildcarded consumer.
C Declaration
tibems_status tibemsConsumerInfo_GetDetailedStatistics(
   tibemsConsumerInfo consumerInfo,
   tibemsCollection* collection);
COBOL Call
CALL "tibemsConsumerInfo_GetDetailedStatistics"
 USING BY VALUE consumerInfo,
       BY REFERENCE collection,
       RETURNING tibems-status
END-CALL.
 
collection has usage pointer.
Parameters
 
The function stores the collection of tibemsDetailedDestStat objects in this location.
Remarks
Returns detailed statistics for the consumer, giving a breakdown of the consumer's aggregate statistics across all destinations that it has received messages on.
This function returns NULL when there are no detailed statistics available for the consumer. This can happen for any of the following reasons:
Detailed statistics were not included into this consumerInfo object by the function tibemsAdmin_GetConsumers that was used to obtain the object.
See Also
tibemsAdmin_GetConsumers on page 418
tibemsCollection on page 432
tibemsConsumerInfo_GetDurableName
Function
Purpose
Get the name of the consumer's durable subscription.
C Declaration
tibems_status tibemsConsumerInfo_GetDurableName(
    tibemsConsumerInfo consumerInfo,
    char* name,
    tibems_int name_len);
COBOL Call
CALL "tibemsConsumerInfo_GetDurableName"
 USING BY VALUE consumerInfo,
       BY REFERENCE durableName,
       BY VALUE name_len,
       RETURNING tibems-status
END-CALL.
Parameters
 
Remarks
This function returns the name of the consumer's durable subscription. Only durable topic consumers have a durable name. The function returns NULL if the consumer is a non-durable topic subscriber or a queue receiver.
tibemsConsumerInfo_GetElapsedSinceLastAcknowledged
Function
Purpose
Get the approximate number of milliseconds elapsed since the last time a message sent to this consumer was acknowledged by the consumer's session.
C Declaration
tibems_status tibemsConsumerInfo_GetElapsedSinceLastAcknowledged(
    tibemsConsumerInfo consumerInfo,
    tibems_long* time);
COBOL Call
CALL "tibemsConsumerInfo_GetElapsedSinceLastAcknowledged"
 USING BY VALUE consumerInfo,
       BY REFERENCE time,
       RETURNING tibems-status
END-CALL.
Parameters
 
Remarks
This function gets the approximate number of milliseconds that have elapsed since last time a message sent to this consumer was acknowledged by consumer's session. This value, while returned in milliseconds, has a precision of 1 second. This value should be used for informational purposes only. For example, it can be used to identify consumers which receive messages but do not acknowledge them for some reason.
tibemsConsumerInfo_GetElapsedSinceLastSent
Function
Purpose
Get the approximate number of milliseconds elapsed since last time the server sent a message to this consumer.
C Declaration
tibems_status tibemsConsumerInfo_GetElapsedSinceLastSent(
    tibemsConsumerInfo consumerInfo,
    tibems_long* time);
COBOL Call
CALL "tibemsConsumerInfo_GetElapsedSinceLastSent"
 USING BY VALUE consumerInfo,
       BY REFERENCE time,
       RETURNING tibems-status
END-CALL.
Parameters
 
Remarks
This function gets the approximate number of milliseconds that have elapsed since last time the server sent a message to this consumer. The value returned, while given in milliseconds, has a precision of 1 second. It should be used for informational purposes only.
tibemsConsumerInfo_GetID
Function
Purpose
Get the consumer’s unique ID.
C Declaration
tibems_status tibemsConsumerInfo_GetID(
    tibemsConsumerInfo consumerInfo,
    tibems_long* cid);
COBOL Call
CALL "tibemsConsumerInfo_GetID"
 USING BY VALUE consumerInfo,
       BY REFERENCE id,
       RETURNING tibems-status
END-CALL.
Parameters
 
tibemsConsumerInfo_GetPendingMessageCount
Function
Purpose
Get the number of pending messages for a topic consumer.
C Declaration
tibems_status tibemsConsumerInfo_GetPendingMessageCount(
    tibemsConsumerInfo consumerInfo,
    tibems_long* count);
COBOL Call
CALL "tibemsConsumerInfo_GetPendingMessageCount"
 USING BY VALUE consumerInfo,
       BY REFERENCE count,
       RETURNING tibems-status
END-CALL.
Parameters
 
Remarks
This function can be used to retrieve the number of pending messages for a topic consumer only. For queue consumers, the number of pending messages in the corresponding queue must be obtained from the queue. If the consumer is a queue consumer, the function returns 0 (zero).
See Also
tibemsQueueInfo_GetPendingMessageCount on page 482
tibemsConsumerInfo_GetPendingMessageSize
Function
Purpose
Get the combined size of pending messages for a topic consumer.
C Declaration
tibems_status tibemsConsumerInfo_GetPendingMessageSize(
    tibemsConsumerInfo consumerInfo,
    tibems_long* size);
COBOL Call
CALL "tibemsConsumerInfo_GetPendingMessageSize"
 USING BY VALUE consumerInfo,
       BY REFERENCE size,
       RETURNING tibems-status
END-CALL.
Parameters
 
Remarks
This function can be used to retrieve the combined size of the pending messages for a topic consumer. If the consumer is a queue consumer, the function returns 0 (zero).
See Also
tibemsQueueInfo_GetPendingMessageSize on page 483
tibemsConsumerInfo_GetStatistics
Function
Purpose
Get total statistics for a consumer.
C Declaration
tibems_status tibemsConsumerInfo_GetStatistics(
    tibemsConsumerInfo consumerInfo,
    tibemsStatData* statData);
COBOL Call
CALL "tibemsConsumerInfo_GetStatistics"
 USING BY VALUE consumerInfo,
       BY REFERENCE stat,
       RETURNING tibems-status
END-CALL.
Parameters
 
Remarks
This function returns NULL when there are no statistics available for the consumer. This can happen for any of the following reasons:
Statistics were not included into this consumerInfo object by the function tibemsAdmin_GetConsumers that was used to obtain the object.
See Also
tibemsAdmin_GetConsumers on page 418
tibemsStatData on page 491
tibemsConsumerInfo_GetTotalAcknowledgedCount
Function
Purpose
Get the total number of messages which were delivered to this consumer and have been acknowledged by the consumer's session.
C Declaration
tibems_status tibemsConsumerInfo_GetTotalAcknowledgedCount(
    tibemsConsumerInfo consumerInfo,
    tibems_long* count);
COBOL Call
CALL "tibemsConsumerInfo_GetTotalAcknowledgedCount"
 USING BY VALUE consumerInfo,
       BY REFERENCE count,
      RETURNING tibems-status
END-CALL.
Parameters
 
tibemsConsumerInfo_GetTotalMsgCountSentByServer
Function
Purpose
Get the total number of messages the server sent to this consumer since the consumer was created.
C Declaration
tibems_status tibemsConsumerInfo_GetTotalMsgCountSentByServer(
    tibemsConsumerInfo consumerInfo,
    tibems_long* count);
COBOL Call
CALL "tibemsConsumerInfo_GetTotalMsgCountSentByServer"
 USING BY VALUE consumerInfo,
       BY REFERENCE count,
       RETURNING tibems-status
END-CALL.
Parameters
 
Remarks
This function returns total number of messages the server sent to this consumer since consumer was created. This value include duplicates of messages that were resent after a consumer's session recovery or rollback. Therefore, the count may not represent true number of unique messages received by this consumer and should be used only for statistical and informational purposes.
tibemsConsumerInfo_IsActive
Function
Purpose
Get the active status of the consumer.
C Declaration
tibems_status tibemsConsumerInfo_IsActive(
    tibemsConsumerInfo consumerInfo,
    tibems_bool* active);
COBOL Call
CALL "tibemsConsumerInfo_IsActive"
 USING BY VALUE consumerInfo,
       BY REFERENCE active,
       RETURNING tibems-status
END-CALL.
Parameters
 
Remarks
If the consumer is active, the active status is TRUE. Otherwise, active is FALSE. A consumer is active if the server can send messages to it. Only queue consumers which have never called a receive function remain in inactive state.
Queue consumers which called have called tibemsMsgConsumer_Receive, tibemsMsgConsumer_ReceiveNoWait, or tibemsMsgConsumer_ReceiveTimeout at least once or are configured with a message callback, and all topic consumers are always active. This function can identify inactive queue consumers which have never called a receive function which and have never received any messages from the server, even when pending messages exist in the corresponding queue.
See Also
tibemsMsgConsumer_Receive on page 168
tibemsMsgConsumer_ReceiveNoWait on page 169
tibemsMsgConsumer_ReceiveTimeout on page 170
tibemsConsumerInfo_IsConnected
Function
Purpose
Get the connection status of the consumer.
C Declaration
tibems_status tibemsConsumerInfo_IsConnected(
    tibemsConsumerInfo consumerInfo,
    tibems_bool* connected);
COBOL Call
CALL "tibemsConsumerInfo_IsConnected"
 USING BY VALUE consumerInfo,
       BY REFERENCE connected,
       RETURNING tibems-status
END-CALL.
Parameters
 
Remarks
The connection status will be set to TRUE if this consumer is connected to the server, and FALSE otherwise. Only durable topic subscribers may be in a disconnected state. This function always sets the connection status to TRUE for queue receivers and non-durable topic consumers.
tibemsConsumerInfo_IsConnectionConsumer
Function
Purpose
Get whether this is connection consumer.
C Declaration
tibems_status tibemsConsumerInfo_IsConnectionConsumer(
    tibemsConsumerInfo consumerInfo,
    tibems_bool* connectionConsumer);
COBOL Call
CALL "tibemsConsumerInfo_IsConnectionConsumer"
 USING BY VALUE consumerInfo,
       BY REFERENCE connectionConsumer,
       RETURNING tibems-status
END-CALL.
Parameters
 
The function stores consumer connection status in this location. TRUE indicates that the consumer is a connection consumer.
Remarks
Sets the connection status to TRUE if the consumer is a connection consumer, and FALSE otherwise. Notice that for disconnected durable topic subscribers the function returns FALSE even if the durable was created as connection consumer.