When a program first opens a connection, the connection is stopped—that is, it does not deliver inbound messages. To begin the flow of inbound messages, the program must explicitly call
tibemsConnection_Start. (Outbound messages flow even before calling
tibemsConnection_Start.)
The EMS C and COBOL APIs do not support the JMS methods
createConnectionConsumer and
createDurableConnectionConsumer (which are optional in the JMS specification).
When a program uses a connection to send messages, the send calls can detect problems with the connection, and notify the client program (synchronously) by returning error codes.
However, when a program uses a connection only to receive messages, the client lacks that opportunity to detect problems. Instead, programs can handle such errors asynchronously by defining an exception listener callback (see
tibemsExceptionCallback on page 225).
Closing the connection is not sufficient to reclaim all of its resources; your program must explicitly close the sessions, producers, and consumers associated with the connection.
If any message listener or receive call associated with the connection is processing a message when the program calls this function, all facilities of the connection and its sessions remain available to those listeners until they return. In the meantime, this function blocks until that processing completes—that is, until all message listeners and receive calls have returned.
Closing a connection does not force acknowledgment in client-acknowledged sessions. When the program still has a message that it received from a connection that has since closed,
tibemsMsg_Acknowledge indicates status code
TIBEMS_ILLEGAL_STATE.
When the authentication parameters are null, the connection object presents a default user identity. If the server configuration permits that anonymous user, then the call succeeds.
This property is the URL of the server at the other endpoint of the connection. When the connection interacts with several servers in a fault-tolerant arrangement, this property indicates the current active server.
This is an alternate pathway for alerting a client program of connection problems. The program defines an exception listener callback function, and registers the callback using
tibemsConnection_SetExceptionListener. When the client library detects a connection problem, it calls the callback with an exception argument that details the problem.
This function gets a value indicating whether the connection is disconnected from the server. If the connection is disconnected from the server,
tibemsConnection_IsDisconnected sets the the connection status to
TRUE. Otherwise, the connection status is
FALSE.
That is, if the client has called tibemsConnection_Close, or if the connection has been terminated due to a network failure,
tibemsConnection_IsDisconnected returns
TRUE.
Administrators can configure connection factories to assign client IDs to new connections. Alternatively, administrators can allow client programs to assign their own IDs. If the factory does not assign an ID, the program may set this property. However, it is illegal to overwrite an existing client ID value, and or to set this property after using the connection in any way (for example, after creating a session, or starting the connection); attempting to set this property in these situations results in
TIBEMS_ILLEGAL_STATE.
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.
If any message listener or receive call associated with the connection is processing a message when the program calls this function, all facilities of the connection and its sessions remain available to those listeners until they return. In the meantime, this function blocks until that processing completes—that is, until all message listeners and receive calls have returned.