Chapter 7 Connection : tibemsConnection

tibemsConnection
Type
Purpose
Represent a server connection.
Remarks
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).
Asynchronous Errors
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).
 
tibemsConnection_Close
Function
Purpose
Close the connection; reclaim resources.
C Declaration
tibems_status tibemsConnection_Close(
    tibemsConnection connection );
COBOL Call
CALL "tibemsConnection_Close"
USING BY VALUE connection,
RETURNING tibems-status
END-CALL.
 
connection has usage pointer.
Parameters
 
Remarks
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.
Closing a connection deletes all temporary destinations associated with the connection.
Blocking
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.
Acknowledge
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.
Transactions
Closing a connection rolls back all open transactions in all sessions associated with the connection.
 
See Also
tibemsMsg_Acknowledge on page 24
tibemsMsgConsumer on page 162
tibemsMsgProducer on page 174
tibemsDestination on page 144
tibemsSession on page 286
tibemsConnection_Create
Function
Purpose
Create a new connection to an EMS server.
C Declarations
tibems_status tibemsConnection_Create(
    tibemsConnection* connection,
    const char* brokerURL,
    const char* clientId,
    const char* username,
    const char* password );
 
tibems_status tibemsConnection_CreateSSL(
    tibemsConnection* connection,
    const char* brokerURL,
    const char* clientId,
    const char* username,
    const char* password,
    tibemsSSLParams sslParams,
    const char* pk_password );
COBOL Call
CALL "tibemsConnection_Create"
USING BY REFERENCE connection,
BY REFERENCE brokerURL,
BY REFERENCE clientId,
BY REFERENCE username,
BY REFERENCE password
RETURNING tibems-status
END-CALL.
 
CALL "tibemsConnection_CreateSSL"
USING BY REFERENCE connection,
BY REFERENCE brokerURL,
BY REFERENCE clientId,
BY REFERENCE username,
BY REFERENCE password,
BY VALUE tibemsSSLParams,
BY REFERENCE pk-password,
RETURNING tibems-status
END-CALL.
 
connection and sslParams have usage pointer.
Parameters
 
Remarks
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.
The call could not communicate with a server because of mismatched SSL and TCP protocols.
The server rejected the connection because the username or password was invalid.
The client ID is not unique; that is, another client already uses the ID.
See Also
tibemsConnectionFactory_Create on page 257
tibemsConnection_CreateSession
Function
Purpose
Create a session object.
C Declaration
tibems_status tibemsConnection_CreateSession(
    tibemsConnection connection,
    tibemsSession* session,
    tibems_bool transacted,
    tibemsAcknowledgeMode acknowledgeMode );
COBOL Call
CALL "tibemsConnection_CreateSession"
USING BY VALUE connection,
BY REFERENCE session,
BY VALUE transacted,
BY VALUE acknowledgeMode,
RETURNING tibems-status
END-CALL.
 
connection and session have usage pointer.
Parameters
 
Remarks
The new session uses the connection for all server communications.
See Also
tibemsMsg_Acknowledge on page 24
tibemsSession on page 286
tibemsAcknowledgeMode on page 313
tibemsConnection_GetActiveURL
Function
Purpose
Get the active URL of a connection.
C Declaration
tibems_status tibemsConnection_GetActiveURL(
    tibemsConnection connection,
    char** serverURL );
COBOL Call
CALL "tibemsConnection_GetActiveURL"
USING BY VALUE connection,
BY REFERENCE serverURL,
RETURNING tibems-status
END-CALL.
 
connection and serverURL have usage pointer.
Parameters
 
Remarks
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.
tibemsConnection_GetClientId
Function
Purpose
Get the client ID of a connection.
C Declaration
tibems_status tibemsConnection_GetClientId(
    tibemsConnection connection,
    const char** clientId );
COBOL Call
CALL "tibemsConnection_GetClientId"
USING BY VALUE connection,
BY REFERENCE clientId,
RETURNING tibems-status
END-CALL.
 
connection and clientId have usage pointer.
Parameters
 
Remarks
Each connection uses a unique client ID.
Client IDs partition the namespace of durable subscribers; see tibemsSession_CreateDurableSubscriber on page 295.
See Also
tibemsConnection_SetClientId on page 214
tibemsConnection_GetExceptionListener
Function
Purpose
Get the exception listener of a connection.
C Declaration
tibems_status tibemsConnection_GetExceptionListener(
    tibemsConnection connection,
    tibemsExceptionCallback* listener,
    void** closure );
Parameters
 
Remarks
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 call is not available in COBOL.
See Also
tibemsConnection_SetExceptionListener on page 215
Asynchronous Errors.
tibemsExceptionCallback on page 225
tibemsConnection_GetMetaData
Function
Purpose
Get the metadata from a connection.
C Declaration
tibems_status tibemsConnection_GetMetaData(
    tibemsConnection connection,
    tibemsConnectionMetaData* metaData );
COBOL Call
CALL "tibemsConnection_GetMetaData"
USING BY VALUE connection,
BY REFERENCE metaData,
RETURNING tibems-status
END-CALL.
 
connection and metaData have usage pointer.
Parameters
 
See Also
tibemsConnectionMetaData on page 219
tibemsConnection_IsDisconnected
Function
Purpose
Checks whether the connection has been disconnected.
C Declaration
tibems_status tibemsConnection_IsDisconnected(
    tibemsConnection* connection,
    tibems_bool* disconnected);
COBOL Call
CALL "tibemsConnection_IsDisconnected"
     USING BY REFERENCE connection,
           BY REFERENCE disconnected,
           RETURNING tibems-status
END-CALL.
 
connection has usage pointer.
Parameters
 
Remarks
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.
tibemsConnection_SetClientId
Function
Purpose
Set the client ID of a connection.
C Declaration
tibems_status tibemsConnection_SetClientId(
    tibemsConnection connection,
    const char* clientId );
COBOL Call
CALL "tibemsConnection_SetClientId"
USING BY VALUE connection,
BY REFERENCE clientId,
RETURNING tibems-status
END-CALL.
 
connection has usage pointer.
Parameters
 
Remarks
Each connection uses a unique client ID.
Client IDs partition the namespace of durable subscribers; see tibemsSession_CreateDurableSubscriber on page 295.
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.
See Also
tibemsConnection_GetClientId on page 210
tibemsConnection_SetExceptionListener
Function
Purpose
Set the exception listener for a connection.
C Declaration
tibems_status tibemsConnection_SetExceptionListener(
    tibemsConnection connection,
    tibemsExceptionCallback listener,
    const void* closure );
COBOL Call
CALL "tibemsConnection_SetExceptionListener_STL"
USING BY VALUE tibemsConnection,
BY REFERENCE tibems-Exception-Status,
BY VALUE     TIBEMS-NULLPTR,
RETURNING tibems-status
END-CALL.
 
connection has usage pointer.
tibems-Exception-Status has usage binary.
Parameters
 
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_GetExceptionListener on page 211
Asynchronous Errors.
tibemsExceptionCallback on page 225
tibemsConnection_Start
Function
Purpose
Start delivering inbound messages.
C Declaration
tibems_status tibemsConnection_Start(
    tibemsConnection connection );
COBOL Call
CALL "tibemsConnection_Start"
USING BY VALUE connection,
RETURNING tibems-status
END-CALL.
 
connection has usage pointer.
Parameters
 
Remarks
When a connection is created, it is stopped. It does not deliver inbound messages until the program calls this function to explicitly start it.
If the connection is not stopped, this call has no effect.
Outbound messages flow even before calling start.
See Also
tibemsConnection_Stop on page 217
tibemsConnection_Stop
Function
Purpose
Stop delivering inbound messages.
C Declaration
tibems_status tibemsConnection_Stop(
    tibemsConnection connection );
COBOL Call
CALL "tibemsConnection_Stop"
USING BY VALUE connection,
RETURNING tibems-status
END-CALL.
connection has usage pointer.
Parameters
 
Remarks
This call temporarily stops the connection from delivering inbound messages. A program can restart delivery by calling tibemsConnection_Start.
When a connection is created, it is stopped. It does not deliver inbound messages until the program calls this function to explicitly start it.
If the connection is already stopped, this call has no effect.
Effect
When this call returns, the connection has stopped delivery to all consumers associated with the connection:
Blocking
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.
However, the stopped connection prevents the client program from processing any new messages.
Sending
A stopped connection can still send outbound messages.
See Also
tibemsConnection_Start on page 216