Copyright © TIBCO Software Inc. All Rights Reserved

> tibemsAdmin
> Type
> Purpose
> Represent an administrative connection to the server.
> Remarks
> tibemsAdmin provides an administrative connection to the server. To use these functions, first create an administrative connection to the server with tibemsAdmin_Create. With that connection you can retrieve information about the server and its components at runtime.

> Function | Description | Page
> tibemsAdmin_Close | Close the administrative connection to the server. | 417
> tibemsAdmin_Create | Create an administration connection to a server. | 418
> tibemsAdmin_GetCommandTimeout | Get the command timeout. | 420
> tibemsAdmin_GetConsumer | Get consumer with specified ID. | 421
> tibemsAdmin_GetConsumers | Returns consumers matching specified filters. | 422
> tibemsAdmin_GetInfo | Get the current set of server metrics. | 425
> tibemsAdmin_GetProducerStatistics | Returns statistical information about producers that match the specified parameters. | 426
> tibemsAdmin_GetQueue | Get information about a queue of the given queue name. | 428
> tibemsAdmin_GetQueues | Get the queues that match the given pattern and the given permanence type. | 429
> tibemsAdmin_GetTopic | Get the topic for the given topic name. | 431
> tibemsAdmin_GetTopics | Get the topics that match the given pattern and the given permanence type. | 432
> tibemsAdmin_SetCommandTimeout | Sets the command timeout. | 434
> tibemsAdmin_SetExceptionListener | Set an exception listener for the connection used by the administration API to communicate with the EMS server. | 434

> Related Types
> tibemsCollection on page 436
> tibemsConsumerInfo on page 441
> tibemsProducerInfo on page 466
> tibemsQueueInfo on page 474
> tibemsTopicInfo on page 500
> tibemsAdmin_Close
> Function
> Purpose
> Close the administrative connection to the server.
> C Declaration
> tibems_status tibemsAdmin_Close(
> tibemsAdmin admin);
> COBOL Call
> CALL "tibemsAdmin_Close"
> USING BY VALUE admin,
> RETURNING tibems-status
> END-CALL.
> Parameters

> Parameter | Description
> admin | The administrative connection to be closed.

> See Also
> tibemsAdmin_Create on page 418
> tibemsAdmin_Create
> Function
> Purpose
> Create an administration connection to a server.
> C Declaration
> tibems_status tibemsAdmin_Create(
> tibemsAdmin* admin,
> const char* url,
> const char* userName,
> const char* password,
> tibemsSSLParams sslparams);
> COBOL Call
> CALL "tibemsAdmin_Create"
> USING BY REFERENCE admin,
> BY REFERENCE url,
> BY REFERENCE userName,
> BY REFERENCE password,
> BY VALUE sslParams,
> RETURNING tibems-status
> END-CALL.

> | sslParams has usage pointer.

> Parameters

> Parameter | Description
> admin | Store the new administrative connection in this location.
> url | Find the EMS server at this URL.
> userName | Authenticate the client program to the server with this username.
> password | Authenticate the client program to the server with this password.
> sslparams | Establish SSL communication using these parameters. See the section on SSL server parameters in the TIBCO Enterprise Message Service User’s Guide for more information.

> Status Codes

> Status Code | Description
> TIBEMS_SERVER_NOT_CONNECTED |
> • | No server is running at the specified URL.
> • | The call could not communicate with a server because of mismatched SSL and TCP protocols.
> • | Other error situations are possible.
> TIBEMS_SECURITY_EXCEPTION |
> • | The server rejected the connection because the username or password was invalid.
> • | SSL setup is incorrect.

> tibemsAdmin_GetCommandTimeout
> Function
> Purpose
> Get the command timeout.
> C Declaration
> tibems_status tibemsAdmin_GetCommandTimeout(
> tibemsAdmin admin,
> tibems_long* timeout);
> COBOL Call
> CALL "tibemsAdmin_GetCommandTimeout"
> USING BY VALUE admin,
> BY REFERENCE timeout,
> RETURNING tibems-status
> END-CALL.
> Parameters

> Parameter | Description
> admin | Get the command timeout of this administrative connection.
> timeout | The function stores the timeout in this location.

> Remarks
> Gets the command timeout in milliseconds. The command timeout determines how long to wait for the server to respond to a command. If the server does not respond within the timeout limit, the command throws an exception. The default timeout is 60000 (60 seconds).
> See Also
> tibemsAdmin_SetCommandTimeout on page 434
> tibemsAdmin_GetConsumer
> Function
> Purpose
> Get consumer with specified ID.
> C Declaration
> tibems_status tibemsAdmin_GetConsumer(
> tibemsAdmin admin,
> tibemsConsumerInfo* consumerInfo,
> tibems_long ID);
> COBOL Call
> CALL "tibemsAdmin_GetConsumer"
> USING BY VALUE admin,
> BY REFERENCE consumerInfo,
> BY VALUE consumerID,
> RETURNING tibems-status
> END-CALL.
> Parameters

> Parameter | Description
> admin | Get a consumer using this administrative connection.
> consumerInfo | The functions stores information about the consumer in this location.
> ID | The consumer ID for which the function will retrieve information.

> Remarks
> Returns the consumer object with specified ID. The returned consumer object contains information about consumer known to server, including details, available statistics. If a consumer with the specified ID does not exist, the function returns NULL.
> Status Codes

> Status Code | Description
> TIBEMS_TIMEOUT | The administrative query timed out while waiting for a server response.
> TIBEMS_NOT_FOUND | No consumer found matching the requested ID.

> See Also
> tibemsConsumerInfo on page 441
> tibemsAdmin_GetConsumers
> Function
> Purpose
> Returns 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.

> | collection has usage pointer.

> Parameters

> Parameter | Description
> admin | Get consumers using this administrative connection.
> collection | The function stores 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 | When TRUE, this parameter specifies that only durable topic subscribers should be returned. This parameter is applied 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 | Specifies 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
> Returns 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 on page 495
> tibemsDetailedDestStat on page 462
> tibemsAdmin_GetInfo
> Function
> Purpose
> Get the current set of server metrics.
> C Declaration
> tibems_status tibemsAdmin_GetInfo(
> tibemsAdmin admin,
> tibemsServerInfo* serverInfo);
> COBOL Call
> CALL "tibemsAdmin_GetInfo"
> USING BY VALUE admin,
> BY REFERENCE serverInfo,
> RETURNING tibems-status
> END-CALL.
> Parameters

> Parameter | Description
> admin | Get server metrics using this administrative connection.
> serverInfo | The function stores the server metrics in this location.

> Status Codes

> Status Code | Description
> TIBEMS_TIMEOUT | The administrative query timed out while waiting for a server response.

> tibemsAdmin_GetProducerStatistics
> Function
> Purpose
> Returns statistical information about producers that match the specified parameters.
> C Declaration
> tibems_status tibemsAdmin_GetProducerStatistics(
> tibemsAdmin admin,
> tibemsCollection* collection,
> tibems_long connectionID,
> const char* username,
> tibemsDestinationInfo destination);
> COBOL Call
> CALL "tibemsAdmin_GetProducerStatistics"
> USING BY VALUE admin,
> BY REFERENCE prodInfos,
> BY REFERENCE username,
> BY VALUE connectionID,
> BY VALUE destination,
> RETURNING tibems-status
> END-CALL.

> | prodInfos has usage pointer.

> Parameters

> Parameter | Description
> admin | Get the producer statistics using this administrative connection.
> collection | The function stores the returned producer data in the location specified here, as a collection of tibemsProducerInfo objects.
> connectionID | Must be set to zero. This parameter is reserved for future use.
> username | If specified, only producers for connections that use the specified user name will be returned. Specify NULL if all producers should be returned.
> destination | If specified, only producers 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 producers.
> The destination name may include wildcards.

> Remarks
> Returns information about message producers, including the statistical information about producers with specified parameters.
> Status Codes

> Status Code | Description
> TIBEMS_TIMEOUT | The administrative query timed out while waiting for a server response.
> TIBEMS_NOT_FOUND | No producers found matching the specified parameters.

> See Also
> tibemsStatData on page 495
> tibemsDetailedDestStat on page 462
> tibemsAdmin_GetQueue
> Function
> Purpose
> Get information about a queue of the given queue name.
> C Declaration
> tibems_status tibemsAdmin_GetQueue(
> tibemsAdmin admin,
> tibemsQueueInfo* queueInfo,
> const char* queueName);
> COBOL Call
> CALL "tibemsAdmin_GetQueue"
> USING BY VALUE admin,
> BY REFERENCE queueInfo,
> BY REFERENCE name,
> RETURNING tibems-status
> END-CALL.
> Parameters

> Parameter | Description
> admin | Get information about a queue using this administrative connection.
> queueInfo | The function will store information about the specified queue in this location.
> queueName | The name of the queue for which information will be retrieved.

> Remarks
> This function gets a tibemsQueueInfo object for the specified queue name. If the queueName does not exist, the function returns TIBEMS_NOT_FOUND.
> Status Codes

> Status Code | Description
> TIBEMS_TIMEOUT | The administrative query timed out while waiting for a server response.
> TIBEMS_NOT_FOUND | No queue found matching the specified queueName.

> See Also
> tibemsQueueInfo on page 474
> tibemsAdmin_GetQueues
> Function
> Purpose
> Get the queues that match the given pattern and the given permanence type.
> C Declaration
> tibems_status tibemsAdmin_GetQueues(
> tibemsAdmin admin,
> tibemsCollection* collection,
> const char* pattern,
> tibems_int permType);
> COBOL Call
> CALL "tibemsAdmin_GetQueues"
> USING BY VALUE admin,
> BY REFERENCE collection,
> BY REFERENCE pattern,
> BY VALUE permType,
> RETURNING tibems-status
> END-CALL.

> | collection has usage pointer.

> Parameters

> Parameter | Description
> admin | Get information about queues using this administration connection.
> collection | The function stores the returned queue data in the location specified here, as a collection of tibemsQueueInfo objects.
> pattern | The queue name pattern that must be matched. The pattern may contain the wildcards * and >. A pattern of > or NULL will return all queues that exist in the server. See the TIBCO Enterprise Message Service User’s Guide for information about working with wildcards in queues.
> permType | The permanence type of the queue must match the type given here. Possible permanence types are:
> • | TIBEMS_DEST_GET_ALL – Return all queues that match the pattern.
> • | TIBEMS_DEST_GET_STATIC – Return only static queues that match the pattern.
> • | TIBEMS_DEST_GET_DYNAMIC – Return only dynamic queues that match the pattern.
> • | TIBEMS_DEST_GET_NOTEMP – Do not return any temporary queues.
> A NULL value matches all queues.

> Status Codes

> Status Code | Description
> TIBEMS_TIMEOUT | The administrative query timed out while waiting for a server response.
> TIBEMS_NOT_FOUND | No queues found matching the specified pattern and performance type.

> See Also
> tibemsQueueInfo on page 474
> tibemsAdmin_GetTopic
> Function
> Purpose
> Get the topic for the given topic name.
> C Declaration
> tibems_status tibemsAdmin_GetTopic(
> tibemsAdmin admin,
> tibemsTopicInfo* topicInfo,
> const char* topicName);
> COBOL Call
> CALL "tibemsAdmin_GetTopic"
> USING BY VALUE admin,
> BY REFERENCE topicInfo,
> BY REFERENCE name,
> RETURNING tibems-status
> END-CALL.
> Parameters

> Parameter | Description
> admin | Get information about a topic using this administrative connection.
> topicInfo | The function stores information about the topic in this location.
> topicName | The name of the topic for which information will be retrieved.

> Remarks
> This function gets a tibemsTopicInfo object for the specified topic name. If the topicName does not exist, the function returns TIBEMS_NOT_FOUND.
> Status Codes

> Status Code | Description
> TIBEMS_TIMEOUT | The administrative query timed out while waiting for a server response.
> TIBEMS_NOT_FOUND | No topic found matching the specified topicName.

> See Also
> tibemsTopicInfo on page 500
> tibemsAdmin_GetTopics
> Function
> Purpose
> Get the topics that match the given pattern and the given permanence type.
> C Declaration
> tibems_status tibemsAdmin_GetTopics(
> tibemsAdmin admin,
> tibemsCollection* collection,
> const char* pattern,
> tibems_int permType);
> COBOL Call
> CALL "tibemsAdmin_GetTopics"
> USING BY VALUE admin,
> BY REFERENCE collection,
> BY REFERENCE pattern,
> BY VALUE permType,
> RETURNING tibems-status
> END-CALL.

> | collection has usage pointer.

> Parameters

> Parameter | Description
> admin | Get information about topics using this administrative connection.
> collection | The function stores the returned topic data in the location specified here, as a collection of tibemsTopicInfo objects.
> pattern | The topic name pattern that must be matched. The pattern may contain the wildcards * and >. A pattern of > or NULL will return all topics. See the TIBCO Enterprise Message Service User’s Guide for information about working with wildcards in topics.
> permType | The permanence type of the topic must match the type given here. Possible permanence types are:
> • | TIBEMS_DEST_GET_ALL – Return all topics that match the pattern.
> • | TIBEMS_DEST_GET_STATIC – Return only static topics that match the pattern.
> • | TIBEMS_DEST_GET_DYNAMIC – Return only dynamic topics that match the pattern.
> • | TIBEMS_DEST_GET_NOTEMP – Do not return any temporary topics.
> A NULL value matches all topics.

> Status Codes

> Status Code | Description
> TIBEMS_TIMEOUT | The administrative query timed out while waiting for a server response.
> TIBEMS_NOT_FOUND | No topics found matching the specified pattern and performance type.

> See Also
> tibemsTopicInfo on page 500
> tibemsAdmin_SetCommandTimeout
> Function
> Purpose
> Sets the command timeout.
> C Declaration
> tibems_status tibemsAdmin_SetCommandTimeout(
> tibemsAdmin admin,
> tibems_long timeout);
> COBOL Call
> CALL "tibemsAdmin_SetCommandTimeout"
> USING BY VALUE admin,
> BY VALUE timeout,
> RETURNING tibems-status
> END-CALL.
> Parameters

> Parameter | Description
> admin | Set the command timeout on this administrative connection.
> timeout | The length of time, in milliseconds, to wait for the server to respond to a command. When not specified, the default command timeout is 60000 (60 seconds).

> Remarks
> Sets the command timeout. The command timeout determines how long, in milliseconds, the command waits for the server to respond. If the server does not respond within the timeout limit, the command throws an exception. The default timeout is 60000 (60 seconds).
> See Also
> tibemsAdmin_GetCommandTimeout on page 420
> tibemsAdmin_SetExceptionListener
> Function
> Purpose
> Set an exception listener for the connection used by the administration API to communicate with the EMS server.
> C Declaration
> tibems_status tibemsAdmin_SetExceptionListener(
> tibemsAdmin admin,
> tibemsExceptionCallback listener,
> const void* closure);
> COBOL Call
> CALL "tibemsAdmin_SetExceptionListener_STL"
> USING BY VALUE admin,
> BY REFERENCE tibems-AdminException-Status,
> BY VALUE TIBEMS-NULLPTR,
> RETURNING tibems-status
> END-CALL.
> Parameters

> Parameter | Description
> admin | Resister the exception listener callback on this administration connection.
> listener | Register this exception listener callback. For more information about exception listeners, see the TIBCO Enterprise Message Service User’s Guide.
> closure | Register this closure argument.

> Remarks
> This is an alternate pathway for alerting a client program of connection problems. The program defines an exception listener callback function, and calls this function to register the callback and a closure argument. When the client library detects a connection problem, it calls the callback with a status code that identifies the problem.
> See Also
> tibemsConnection_SetExceptionListener on page 215
> Asynchronous Errors.
> tibemsExceptionCallback on page 225

Copyright © TIBCO Software Inc. All Rights Reserved