Copyright © TIBCO Software Inc. All Rights Reserved

> 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).

> Function | Description | Page
> tibemsConnection_Close | Close the connection; reclaim resources. | 204
> tibemsConnection_Create tibemsConnection_CreateSSL | Create a new connection to an EMS server. | 206
> tibemsConnection_CreateSession | Create a session object. | 208
> tibemsConnection_GetActiveURL | Get the active URL of a connection. | 209
> tibemsConnection_GetClientId | Get the client ID of a connection. | 210
> tibemsConnection_GetExceptionListener | Get the exception listener of a connection. | 211
> tibemsConnection_GetMetaData | Get the metadata from a connection. | 212
> tibemsConnection_IsDisconnected | Checks whether the connection has been disconnected. | 213
> tibemsConnection_SetClientId | Set the client ID of a connection. | 214
> tibemsConnection_SetExceptionListener | Set the exception listener for a connection. | 215
> tibemsConnection_Start | Start delivering inbound messages. | 216
> tibemsConnection_Stop | Stop delivering inbound messages. | 217

> 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

> Parameter | Description
> connection | Close this connection.

> 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.

> Status Code | Description
> TIBEMS_ILLEGAL_STATE | The connection is currently processing a message callback.

> 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

> Parameter | Description
> connection | The function stores the new connection in this location.
> brokerURL | Find the EMS server at this URL. If configuring a fault-tolerant client, enter two of more URLs, as described in Configuring C and COBOL Clients for Fault-Tolerant Connections.
> clientId | Identify the client program to the server with this unique ID.
> username | Authenticate the client program to the server with this user name.
> password | Authenticate the client program to the server with this password.
> sslParams | Establish SSL communication using these parameters.
> pk_password | Private key password for SSL.

> 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.

> 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.
> TIBEMS_INVALID_CLIENT_ID | 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

> Parameter | Description
> connection | Create a session on this connection.
> session | The function stores the new session in this location.
> transacted | When true, the new session has transaction semantics. When false, it has non-transaction semantics.
> acknowledgeMode | This parameter determines the acknowledge mode of the session. Supply a value enumerated by tibemsAcknowledgeMode.

> 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 312
> 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

> Parameter | Description
> connection | Get the active URL of this connection.
> serverURL | The function stores a pointer to the URL in this location.

> 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

> Parameter | Description
> connection | Get the client ID of this connection.
> clientId | The function stores a pointer to the ID string in this location.

> 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

> Parameter | Description
> connection | Get the exception listener of this connection.
> listener | The function stores a pointer to the exception listener callback in this location.
> closure | The function stores a pointer to the exception listener closure argument in this location.

> 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

> Parameter | Description
> connection | Get the metadata of this connection.
> metaData | The function stores a metadata object in this location.

> 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

> Parameter | Description
> connection | Get the status of this connection.
> disconnected | The function stores the connection status in this location.

> 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

> Parameter | Description
> connection | Set the client ID of this connection.
> clientId | Set the client ID to this string.

> 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

> Parameter | Description
> connection | Set the exception listener for this connection.
> listener | Register this exception listener callback.
> 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_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

> Parameter | Description
> connection | Start delivering inbound messages on this connection.

> 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

> Parameter | Description
> connection | Stop delivering inbound messages on this connection.

> 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:

> • | Messages do not arrive to trigger asynchronous message handler events, nor message listeners.

> • | Synchronous receive functions block. If their timeout intervals expire, they return null.

> 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

Copyright © TIBCO Software Inc. All Rights Reserved