# tibemsAdmin_GetConsumers

Function

## Purpose

Return consumers matching specified filters.

## C Declaration

    tibems_status tibemsAdmin_GetConsumers(
        tibemsAdmin admin,
        tibemsCollection* collection,
        tibems_long connectionID,
        const char* username,
        tibemsDestinationInfo destination,
        tibems_bool durable,
        tibems_int dataFlags)

## COBOL Call

    CALL "tibemsAdmin_GetConsumers"
     USING BY VALUE admin,
           BY REFERENCE collection,
           BY VALUE connectionID,
           BY REFERENCE username,
           BY VALUE destination,
           BY VALUE durable,
           BY VALUE dataFlags,
           RETURNING tibems-status
    END-CALL.

Note: `collection` has usage pointer.

## Parameters

Parameter | Description
--- | ---
`admin` | Get consumers using this administrative connection.
`collection` | Store the returned consumer data in the location specified here, as a collection of `tibemsConsumerInfo` objects.
`connectionID` | `connectionID` is reserved for future use and must be set to zero.
`username` | If specified, only consumers for connections that use the specified user name will be returned. Specify `NULL` if all consumers should be returned.
`destination` | If specified, only consumers on destinations of the same type and matching this destination name will be returned. destination can be: A `tibemsQueueInfo` or `tibemsTopicInfo` object. `TIBEMS_INVALID_ADMIN_ID` to return all consumers. The destination name may include wildcards.
`durable` | (If TRUE) Specify that only durable topic subscribers should be returned. Applies only to topic subscribers, and when included prevents the function from returning non-durable topic consumers. However, it does not affect which queue consumers are returned.
`dataFlags` | Specify what information will be returned for each consumer that matches the filter criteria. Possible values for this parameter are: `GET_STAT`—gets a `tibemsStatData` for each consumer. `GET_DETAILED_STAT`—gets a `tibemsCollection` of `tibemsDetailedDestStat` objects for each consumer When no flag is specified, the returned information does not include statistics. If statistics are disabled in the server, no statistics will be returned regardless of the flag specified in this parameter.

## Remarks

Return a list of consumers matching the specified filters. The consumers are returned in a `tibemsCollection`; if no consumers matching the filter criteria exist in the server, then no `tibemsCollection` will be returned.

The returned consumers are not sorted and are placed in the `tibemsCollection` object in any order. Your application may need to sort the consumers into a specific order if required.

Example 1

For example, this call returns all consumers known to the server, but does not include statistical information for each consumer:

    tibemsAdmin      admin;
    tibemsCollection consumerInfoCollection;
    tibems_status    status;

    status = tibemsAdmin_GetConsumers(admin, &consumerInfoCollection, 0L, NULL, TIBEMS_ADMIN_INVALID_ID, TIBEMS_FALSE, 0);

Example 2

This call returns all queue consumers and all durable topic consumers:

    tibemsAdmin      admin;
    tibemsCollection consumerInfoCollection;
    tibems_status    status;

    status = tibemsAdmin_GetConsumers(admin, &consumerInfoCollection, 0L, NULL, TIBEMS_ADMIN_INVALID_ID, TIBEMS_TRUE, 0);

Example 3

This call returns all durable topic consumers that subscribe to any topic matching topic news.*. If statistics are enabled in the server, the returned `tibemsConsumerInfo` objects will include detailed statistics about the consumers.

    tibemsAdmin      admin;
    tibemsCollection consumerInfoCollection;
    tibems_status    status;
    tibemsTopicInfo  topicInfo;

    status = tibemsTopicInfoCreate(&topicInfo, "news.*");
    status = tibemsAdmin_GetConsumers(admin, &consumerInfoCollection, 0L, NULL, topicInfo, TIBEMS_TRUE, TIBEMS_GET_DETAILED_STAT);

Example 4

This call returns all queue consumers created by user `OrderProcessor` and receiving messages from all queues matching name `purchase.order.>`. Each `tibemsConsumerInfo` object will include the full statistics available for the consumer.

    tibemsAdmin      admin;
    tibemsCollection consumerInfoCollection;
    tibems_status    status;
    tibemsQueueInfo  queueInfo;

    status = tibemsQueueInfoCreate(&queueInfo, "purchase.order.>");
    status = tibemsAdmin_GetConsumers(admin, &consumerInfoCollection, 0L, "OrderProcessor", queueInfo, TIBEMS_FALSE, TIBEMS_GET_DETAILED_STAT);

## Status Codes

Status Code | Description
--- | ---
`TIBEMS_TIMEOUT` | The administrative query timed out while waiting for a server response.
`TIBEMS_NOT_FOUND` | No consumers found matching the specified filters.

## See Also

`tibemsStatData`

`tibemsDetailedDestStat`

Copyright © Cloud Software Group, Inc. All rights reserved.