Utilities : Utility Functions

Utility Functions
The following functions are not related to a specific data type.
tibems_Close
Function
Purpose
Deallocate the memory used by the EMS internal global data structures.
C Declaration
void tibems_close(void);
COBOL Call
CALL "tibems_close"
RETURNING tibems-Return-Value
END-CALL.
Remarks
Before unloading the EMS library, you must call this function to clean up. Windows platforms allow selective unloading of DLLs.
Applications that call tibems_Open and tibems_Close one or more times will allocate and deallocate correctly as long as the close calls match the open calls.
See Also
tibems_Open on page 394
tibems_GetAllowCloseInCallback
Function
Purpose
Gets whether the client application is allowed to call close functions inside message listener callbacks.
C Declaration
tibems_status tibems_GetAllowCloseInCallback(
    tibems_bool *isAllowed);
COBOL Call
CALL "tibems_GetAllowCloseInCallback"
  USING BY REFERENCE isAllowed,
  RETURNING tibems-status
END-CALL.
Parameters
 
Returns true when the client application does not wait for the message callback to return before closing a message consumer, session, or connection. Returns false if the application waits for the callback to return.
See Also
tibems_SetAllowCloseInCallback on page 395
tibems_GetConnectAttemptCount
Function
Purpose
Return the connection attempts limit.
C Declaration
tibems_int tibems_GetConnectAttemptCount(void);
COBOL Call
CALL "tibems_GetConnectAttemptCount"
  RETURNING tibems-Return-Value
END-CALL.
Remarks
This setting governs all client tibemsConnection objects, limiting the number of times that connection objects attempt to establish a connection to the server. The default value is 2. The minimum value is 1.
See Also
tibems_SetConnectAttemptCount on page 396
Setting Connection Attempts, Timeout and Delay Parameters in the TIBCO Enterprise Message Service User’s Guide
tibems_GetConnectAttemptDelay
Function
Purpose
Return the connection delay.
C Declaration
tibems_int tibems_GetConnectAttemptDelay(void);
COBOL Call
CALL "tibems_GetConnectAttemptDelay"
RETURNING tibems-Return-Value
END-CALL.
Remarks
This setting governs all client tibemsConnection objects. It determines the delay time between successive attempt to establish a connection to the server. Its value is the time (in milliseconds) between connection attempts. The default value is 500. The minimum value is 250.
See Also
tibems_SetConnectAttemptDelay on page 397
Setting Connection Attempts, Timeout and Delay Parameters in the TIBCO Enterprise Message Service User’s Guide
 
tibems_GetConnectAttemptTimeout
Function
Purpose
Return the connection timeout.
C Declaration
tibems_int tibems_GetConnectAttemptTimeout(void);
COBOL Call
CALL "tibems_GetConnectAttemptTimeout"
RETURNING tibems-Return-Value
END-CALL.
Remarks
This setting governs all client tibemsConnection objects. It determines the maximum time (in milliseconds) the client allows to establish a connection to the server. The default value is 500.
See Also
tibems_SetConnectAttemptTimeout on page 398
Setting Connection Attempts, Timeout and Delay Parameters in the TIBCO Enterprise Message Service User’s Guide
 
tibems_GetExceptionOnFTEvents
Function
Purpose
Detects whether exception listener is called on any of the following fault-tolerant events: disconnected, each reconnect attempt, reconnected.
C Declaration
tibems_status tibems_GetExceptionOnFTEvents(
    tibems_bool* isSet);
COBOL Call
CALL "tibems_GetExceptionOnFTEvents"
  USING BY REFERENCE isSet,
  RETURNING tibems-status
END-CALL.
Parameters
 
Returns true if the exception listener is to be called on any of the following fault-tolerant events: disconnected, each reconnect attempt, reconnected. Returns false if it is not to be called. Default is false.
See Also
tibems_SetExceptionOnFTEvents on page 399
Setting an Exception Listener in the TIBCO Enterprise Message Service User’s Guide
tibems_GetExceptionOnFTSwitch
Function
Purpose
Detects whether exception listener is called on a fault-tolerant switchover.
C Declaration
tibems_status tibems_GetExceptionOnFTSwitch(
    tibems_bool* isSet);
COBOL Call
CALL "tibems_GetExceptionOnFTSwitch"
  USING BY REFERENCE isSet,
  RETURNING tibems-status
END-CALL.
Parameters
 
Returns true if the exception listener is to be called on a fault-tolerant switchover and false if it is not to be called. Default is false.
See Also
tibems_setExceptionOnFTSwitch on page 400
Setting an Exception Listener in the TIBCO Enterprise Message Service User’s Guide
tibems_GetMulticastDaemon
Function
Purpose
Gets the port of the multicast daemon that this application connects to.
C Declaration
const char* tibems_GetMulticastDaemon(void);
Remarks
Gets the port of the multicast daemon that this application connects to.
See Also
tibems_SetMulticastDaemon on page 401
Chapter 13, Using Multicast, in the TIBCO Enterprise Message Service User’s Guide
tibems_GetMulticastEnabled
Function
Purpose
Gets whether message consumers subscribed to multicast-enabled topics in EMS client applications can receive messages over multicast.
C Declaration
tibems_bool tibems_GetMulticastEnabled(void);
Remarks
Gets whether message consumers subscribed to multicast-enabled topics in EMS client applications can receive messages over multicast.
See Chapter 13, Using Multicast, in the TIBCO Enterprise Message Service User’s Guide, for more information.
See Also
tibems_SetMulticastEnabled on page 402
tibemsConnectionFactory_SetMulticastEnabled on page 272
tibems_GetReconnectAttemptCount
Function
Purpose
Return the reconnection attempts limit.
C Declaration
tibems_int tibems_GetReconnectAttemptCount(void);
COBOL Call
CALL "tibems_GetReconnectAttemptCount"
  RETURNING tibems-Return-Value
END-CALL.
Remarks
This setting governs all client tibemsConnection objects limiting the number of times that they attempt to reconnect to the server after a network disconnect. The default value is 4. The minimum value is 1.
See Also
tibems_GetConnectAttemptCount on page 381
tibems_SetReconnectAttemptCount on page 404
Setting Reconnection Failure Parameters in the TIBCO Enterprise Message Service User’s Guide.
tibems_GetReconnectAttemptDelay
Function
Purpose
Return the reconnection delay.
C Declaration
tibems_int tibems_GetReconnectAttemptDelay(void);
COBOL Call
CALL "tibems_GetReconnectAttemptDelay"
RETURNING tibems-Return-Value
END-CALL.
Remarks
This setting governs all client tibemsConnection objects. It determines the delay time between successive attempt to establish a connection to the server. Its value is the time (in milliseconds) between connection attempts. The default value is 500. The minimum value is 250.
See Also
tibems_GetConnectAttemptDelay on page 382
tibems_SetReconnectAttemptDelay on page 405
Setting Reconnection Failure Parameters in the TIBCO Enterprise Message Service User’s Guide.
tibems_GetReconnectAttemptTimeout
Function
Purpose
Return the reconnection timeout.
C Declaration
tibems_int tibems_GetReconnectAttemptTimeout(void);
COBOL Call
CALL "tibems_GetReconnectAttemptTimeout"
RETURNING tibems-Return-Value
END-CALL.
Remarks
This setting governs all client tibemsConnection objects. It determines the maximum time (in milliseconds) to client will allow to reestablish a connection to the server. The default value is 500. The minimum value is 250.
See Also
tibems_SetReconnectAttemptTimeout on page 406
Setting Reconnection Failure Parameters in the TIBCO Enterprise Message Service User’s Guide.
 
tibems_GetSocketReceiveBufferSize
Function
Purpose
Return the size of socket receive buffers.
C Declaration
tibems_int tibems_GetSocketReceiveBufferSize(void);
COBOL Call
CALL "tibems_GetSocketReceiveBufferSize"
RETURNING tibems-Return-Value
END-CALL.
Remarks
When set, this value overrides the operating system’s default for the size of receive buffers associated with sockets that the client uses for connections to the server. (Some operating systems do not allow you to override the default size.)
See Also
tibems_SetSocketReceiveBufferSize on page 407
tibems_GetSocketSendBufferSize
Function
Purpose
Return the size of socket send buffers.
C Declaration
tibems_int tibems_GetSocketSendBufferSize(void);
COBOL Call
CALL "tibems_GetSocketSendBufferSize"
RETURNING tibems-Return-Value
END-CALL.
Remarks
When set, this value overrides the operating system’s default for the size of send buffers associated with sockets that the client uses for connections to the server. (Some operating systems do not allow you to override the default size.)
See Also
tibems_SetSocketSendBufferSize on page 408
tibems_IsConsumerMulticast
Function
Purpose
Checks if a consumer can receive messages over multicast.
C Declaration
tibems_bool tibems_IsConsumerMulticast(
    tibemsMsgConsumer consumer,
    tibems_bool *isMulticast);
Remarks
It is possible for a consumer to be a multicast consumer yet only receive messages over TCP. This may happen when the consumer is created on a wildcard destination that includes both unicast and multicast topics.
See Also
tibems_SetSocketSendBufferSize on page 408
tibems_Open
Function
Purpose
Allocate the global memory for the EMS library.
C Declaration
void tibems_Open(void);
COBOL Call
CALL "tibems_Open"
RETURNING tibems-Return-Value
END-CALL.
Remarks
Applications that do not call tibems_Open will work as expected because the EMS internal global data structures are allocated when any public EMS function is called. However, the EMS data structures will not be deallocated until the application calls the tibems_Close function or exits.
Existing Windows applications that only call the tibems_Close function will work as expected.
Applications that call tibems_Open and tibems_Close one or more times will allocate and deallocate correctly as long as the close calls match the open calls.
See Also
tibems_Close on page 379
tibems_SetAllowCloseInCallback
Function
Purpose
Sets whether client applications can close message consumers, sessions, or connections inside message listener callbacks.
C Declaration
tibems_status tibems_SetAllowCloseInCallback(
    tibems_bool allow);
COBOL Call
CALL "tibems_SetAllowCloseInCallback",
 USING BY VALUE isAllowed,
       RETURNING tibems-status
END-CALL.
Parameters
 
When true, the application will not wait for the message callbacks to return before closing a message consumer, session, or connection. When false, the application waits for the callback to return.
Remarks
This function can be used to change the default EMS client behavior, and set whether the client application can call tibemsMsgConsumer_Close, tibemsSession_Close, or tibemsConnection_Close functions from the tibemsMsgCallback.
The default behavior is to wait for callbacks and parallel the behavior specified in the JMS specification, which the EMS client API adheres to. However, this function allows applications to override the default behavior and close EMS objects inside message callbacks.
Normally, the C client API will wait for the tibemsMsgCallback callback to return before the close functions can return to the calling application. Consequently, if these close functions are called inside the callback it causes a deadlock. If calling close functions inside the callback is allowed, then the close function will not wait for the tibemsMsgCallback to return. This prevents the deadlock.
See Also
tibemsMsgCallback on page 172
tibemsMsgConsumer_Close on page 163
tibemsConnection_Close on page 204
tibemsSession_Close on page 289
tibems_GetAllowCloseInCallback on page 380
tibems_SetConnectAttemptCount
Function
Purpose
Modify the connection attempt limit.
C Declaration
tibems_status tibems_SetConnectAttemptCount(
    tibems_int count);
COBOL Call
CALL "tibems_SetConnectAttemptCount"
USING BY VALUE count,
       RETURNING tibems-status
END-CALL.
Remarks
This setting governs all client tibemsConnection objects, limiting the number of times that connection objects attempt to establish a connection to the server.
Parameters
 
See Also
tibems_GetConnectAttemptCount on page 381
Setting Connection Attempts, Timeout and Delay Parameters in the TIBCO Enterprise Message Service User’s Guide
tibems_SetConnectAttemptDelay
Function
Purpose
Modify the connection delay.
C Declaration
tibems_status tibems_SetConnectAttemptDelay(
    tibems_int delay);
COBOL Call
CALL "tibems_SetConnectAttemptDelay"
USING BY VALUE delay,
       RETURNING tibems-status
END-CALL.
Remarks
This setting governs all client tibemsConnection objects. It determines the delay time between successive attempt to establish a connection to the server. Its value is the time (in milliseconds) between connection attempts.
Parameters
 
See Also
tibems_GetConnectAttemptDelay on page 382
Setting Connection Attempts, Timeout and Delay Parameters in the TIBCO Enterprise Message Service User’s Guide
tibems_SetConnectAttemptTimeout
Function
Purpose
Modify the connection timeout.
C Declaration
tibems_status tibems_SetConnectAttemptTimeout(
    tibems_int timeout);
COBOL Call
CALL "tibems_SetConnectAttemptTimeout"
USING BY VALUE timeout,
       RETURNING tibems-status
END-CALL.
Remarks
This setting governs all client tibemsConnection objects. It determines the maximum time (in milliseconds) the client allows to establish a connection to the server.
Parameters
 
Set the connect attempt timeout to this time (in milliseconds). Zero is a special value, which specifies no timeout.
See Also
tibems_GetConnectAttemptTimeout on page 383
Setting Connection Attempts, Timeout and Delay Parameters in the TIBCO Enterprise Message Service User’s Guide
tibems_SetExceptionOnFTEvents
Function
Purpose
Sets whether exception listener is called each step of the fault-tolerant switchover process.
C Declaration
tibems_status tibems_SetExceptionOnFTEvents(
    tibems_bool* callExceptionListener);
COBOL Call
CALL "tibems_SetExceptionOnFTEvents"
  USING BY VALUE callExceptionListener,
  RETURNING tibems-status
END-CALL.
Remarks
This setting determines exception behavior when the fault-tolerant client goes through phases in the failover process. If an exception listener is set on the connection, the callback is invoked when the client detects:
Disconnection, or TIBEMS_SERVER_DISCONNECTED.
Each reconnect attempt, or TIBEMS_SERVER_RECONNECTING.
Reconnection to the server, or TIBEMS_SERVER_RECONNECTED.
This call reports on all events during the failover process. To report only the successful reconnection event, use the tibems_setExceptionOnFTSwitch method instead.
Parameters
 
When true, the connection’s ExceptionListener catches an exception, which contains a status code indicating the state of the fault-tolerant failover: TIBEMS_SERVER_DISCONNECTED, TIBEMS_SERVER_RECONNECTING, or TIBEMS_SERVER_RECONNECTED
When false, fault-tolerant failover does not trigger an exception in the client.
See Also
tibems_GetExceptionOnFTEvents on page 384
tibems_setExceptionOnFTSwitch on page 400
Setting an Exception Listener in the TIBCO Enterprise Message Service User’s Guide
tibems_setExceptionOnFTSwitch
Function
Purpose
Sets whether exception listener is called on fault-tolerant switchover.
C Declaration
tibems_status tibems_setExceptionOnFTSwitch(
    tibems_bool callExceptionListener);
COBOL Call
CALL "tibems_setExceptionOnFTSwitch"
  USING BY VALUE callExceptionListener,
  RETURNING tibems-status
END-CALL.
Remarks
This setting determines exception behavior when the client successfully switches to a different server (fault-tolerant failover).
Parameters
 
When true, the connection’s ExceptionListener catches an exception, which contains the name of the new server.
When false, fault-tolerant failover does not trigger an exception in the client.
See Also
tibems_GetExceptionOnFTSwitch on page 385
tibems_GetExceptionOnFTEvents on page 384
Setting an Exception Listener in the TIBCO Enterprise Message Service User’s Guide
tibems_SetMulticastDaemon
Function
Purpose
Sets the port on which the EMS client will connect to the multicast daemon.
C Declaration
tibems_status tibems_SetMulticastDaemon(
    const char* port);
Parameters
 
The multicast daemon port that connections created in this application will connect to.
Remarks
A connection to the multicast daemon is required when multicast is enabled and a consumer is subscribed to a multicast-enabled topic. Setting the port with this method will override the default port supplied by the server and any port specified in a connection factory for all connections in the application.
See Also
tibemsConnectionFactory_SetMulticastDaemon on page 271
tibems_SetMulticastEnabled on page 402
Chapter 13, Using Multicast, in the TIBCO Enterprise Message Service User’s Guide
tibems_SetMulticastEnabled
Function
Purpose
Set whether message consumers subscribed to multicast-enabled topics in the EMS client application will receive messages over multicast.
C Declaration
tibems_status tibems_SetMulticastEnabled(
    tibems_bool enabled);
Parameters
 
When true, multicast is enabled for the client.
When false, multicast is disabled and the client application will receive all messages over TCP.
Remarks
When enabled, message consumers subscribed to a multicast-enabled topic will receive messages over multicast. By default, multicast is enabled.
tibems_SetMulticastEnabled overrides both the EMS server and factory settings that enable multicast.
See Also
tibemsConnectionFactory_SetMulticastDaemon on page 271
multicast and multicast_daemon_default server parameters in the TIBCO Enterprise Message Service User’s Guide
tibems_SetMulticastExceptionListener
Function
Purpose
Sets the multicast exception listener for an application.
C Declaration
tibems_status tibems_SetMulticastExceptionListener(
    tibemsMulticastExceptionCallback listener,
    void* closure);
Parameters
 
This parameter receives the closure data in this location, which the program supplied in the call that registered the callback. This is a way to pass application related data to the multicast exception listener callback.
See Also
tibemsMulticastExceptionCallback on page 226
Chapter 13, Using Multicast, in the TIBCO Enterprise Message Service User’s Guide
tibems_SetReconnectAttemptCount
Function
Purpose
Modify the reconnection attempts limit.
C Declaration
tibems_status tibems_SetReconnectAttemptCount(
    tibems_int count);
COBOL Call
CALL "tibems_SetReconnectAttemptCount"
USING BY VALUE count,
       RETURNING tibems-status
END-CALL.
Remarks
This setting governs all client tibemsConnection objects as they attempt to reconnect to the server after a network disconnect.
Parameters
 
See Also
tibems_GetReconnectAttemptCount on page 388
Setting Reconnection Failure Parameters in the TIBCO Enterprise Message Service User’s Guide.
tibems_SetReconnectAttemptDelay
Function
Purpose
Modify the reconnection delay.
C Declaration
tibems_status tibems_SetReconnectAttemptDelay(
    tibems_int delay);
COBOL Call
CALL "tibems_SetReconnectAttemptDelay"
USING BY VALUE delay,
       RETURNING tibems-status
END-CALL.
Remarks
This setting governs all client tibemsConnection objects. It determines the delay time between successive attempt to establish a connection to the server. Its value is the time (in milliseconds) between connection attempts.
Parameters
 
See Also
tibems_GetReconnectAttemptDelay on page 389
Setting Reconnection Failure Parameters in the TIBCO Enterprise Message Service User’s Guide.
tibems_SetReconnectAttemptTimeout
Function
Purpose
Modify the reconnection timeout.
C Declaration
tibems_status tibems_SetReconnectAttemptTimeout(
    tibems_int timeout);
COBOL Call
CALL "tibems_SetReconnectAttemptTimeout"
USING BY VALUE timeout,
       RETURNING tibems-status
END-CALL.
Remarks
This setting governs all client tibemsConnection objects. It determines the maximum time (in milliseconds) to client will allow to reestablish a connection to the server.
Parameters
 
See Also
tibems_GetReconnectAttemptTimeout on page 390
Setting Reconnection Failure Parameters in the TIBCO Enterprise Message Service User’s Guide.
tibems_SetSocketReceiveBufferSize
Function
Purpose
Set the size of socket receive buffers.
C Declaration
tibems_status tibems_SetSocketReceiveBufferSize(
    tibems_int size);
COBOL Call
CALL "tibems_SetSocketReceiveBufferSize"
USING BY VALUE size,
       RETURNING tibems-status
END-CALL.
Remarks
This value overrides the operating system’s default for the size of receive buffers associated with sockets that the client uses for connections to the server.
Use this call before creating server connections. This call sets an override buffer size for new socket buffers; it does not change the size of existing socket buffers.
Parameters
 
See Also
tibems_GetSocketReceiveBufferSize on page 391
tibems_SetSocketSendBufferSize
Function
Purpose
Set the size of socket send buffers.
C Declaration
tibems_status tibems_SetSocketSendBufferSize(
    tibems_int size);
COBOL Call
CALL "tibems_SetSocketSendBufferSize"
 USING BY VALUE size,
       RETURNING tibems-status
END-CALL.
Remarks
This value overrides the operating system’s default for the size of send buffers associated with sockets that the client uses for connections to the server.
Use this call before creating server connections. This call sets an override buffer size for new socket buffers; it does not change the size of existing socket buffers.
Parameters
 
See Also
tibems_GetSocketSendBufferSize on page 392
tibems_SetTraceFile
Function
Purpose
Start or stop directing client trace information to a file.
C Declaration
tibems_status tibems_SetTraceFile(
    const char* fileName);
COBOL Call
CALL "tibems_SetTraceFile"
 USING BY REFERENCE fileName,
       RETURNING tibems-status
END-CALL.
Parameters
 
The name of the file to which tracing information should be directed, or NULL to stop directing tracing to a file.
Remarks
This call directs client tracing information to the file specified by the fileName argument. This function does not generate tracing; tracing must be enabled separately. Tracing can be enabled using the set server client_trace command in the administration tool, or, for SSL tracing, using the tibemsSSL_SetTrace or tibemsSSL_SetDebugTrace function. See the TIBCO Enterprise Message Service User’s Guide for more information about the administration tool.
To stop sending tracing information to the file and resume regular tracing to stderr or stdout, call tibems_SetTraceFile, passing NULL for fileName parameter.
 
Tracing information is already being directed to a file, and the fileName argument was not NULL.
The file specified by fileName could not be opened in append mode.
tibems_Sleep
Function
Purpose
Sleep thread.
C Declaration
void tibems_Sleep(
    tibems_long milliseconds);
COBOL Call
CALL "tibems_Sleep"
USING BY VALUE milliseconds
END-CALL.
 
COBOL usage of milliseconds is COMP-2.
Parameters
 
Remarks
This call instructs its calling thread to sleep for a fixed interval (in milliseconds).
tibems_Version
Function
Purpose
Return the EMS library version number.
C Declaration
const char* tibems_Version(void);
COBOL Call
CALL "tibems_Version"
RETURNING tibems-Pointer
END-CALL.
 
tibems-Pointer has usage pointer.
After this COBOL call, store the tibems-Pointer data item to tibems-Cobol-Char, using the following SET statement:
Remarks
This string represents the three-part version number of the release (major.minor.update).