Copyright © TIBCO Software Inc. All Rights Reserved

> tibemsXAConnection
> This implicit type is not defined; instead it is identical to tibemsConnection on page 202. The functions we present on the following pages apply only to connection objects used with XA.
> tibemsXAConnection_Close
> Function
> Purpose
> Close the connection; reclaim resources.
> C Declaration
> tibems_status tibemsXAConnection_Close(
> tibemsConnection connection );
> COBOL Call
> CALL "tibemsXAConnection_Close"
> USING BY VALUE connection,
> RETURNING tibems-status
> END-CALL.

> | connection has usage pointer.

> Parameters

> Parameter | Description
> connection | Close this connection.

> Remarks
> Closing an XA connection reclaims all XA resources associated with the connection or its sessions.
> 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 returns the 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
> tibemsXAConnection_Create
> Function
> Purpose
> Create a new XA connection to an EMS server; use XA for transactions.
> C Declarations
> tibems_status tibemsXAConnection_Create(
> tibemsConnection* connection,
> const char* brokerURL,
> const char* clientId,
> const char* username,
> const char* password );
> tibems_status tibemsXAConnection_CreateSSL(
> tibemsConnection* connection,
> const char* brokerURL,
> const char* clientId,
> const char* username,
> const char* password,
> tibemsSSLParams sslParams,
> const char* pk_password );
> COBOL Call
> CALL "tibemsXAConnection_Create"
> USING BY REFERENCE connection,
> BY REFERENCE brokerURL,
> BY REFERENCE clientId,
> BY REFERENCE username,
> BY REFERENCE password,
> RETURNING tibems-status
> END-CALL.
> CALL "tibemsXAConnection_CreateSSL"
> USING BY REFERENCE connection,
> BY REFERENCE brokerURL,
> BY REFERENCE clientId,
> BY REFERENCE username,
> BY REFERENCE password,
> BY VALUE sslParams,
> 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 | Identify 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.

> Status Code | Description
> TIBEMS_OK | The call succeeded.
> 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
> tibemsConnection_Create on page 206
> tibemsXAConnection_CreateXASession
> Function
> Purpose
> Create an XA session object.
> C Declaration
> tibems_status tibemsXAConnection_CreateXASession(
> tibemsConnection connection,
> tibemsSession* session );
> COBOL Call
> CALL "tibemsXAConnection_CreateXASession"
> USING BY VALUE connection,
> BY REFERENCE session,
> 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.

> Remarks
> The new session has transactional semantics with an external transaction manager, and uses the connection for all server communications.

> | XA sessions do not support routed queues.

> See Also
> tibemsSession on page 286
> tibemsXAConnection_Get
> Function
> Purpose
> Find the XA connection object for a server URL.
> C Declaration
> tibems_status tibemsXAConnection_Get(
> tibemsConnection* connection,
> const char* brokerURL );
> COBOL Call
> CALL "tibemsXAConnection_Get"
> USING BY REFERENCE connection,
> BY REFERENCE brokerURL,
> RETURNING tibems-status
> END-CALL.

> | connection has usage pointer.

> Parameters

> Parameter | Description
> connection | The function stores the connection object in this location.
> brokerURL | Find the connection 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.

> Remarks
> If the TM has implicitly created a connection by calling xa_open, then the TM can get that connection object with this call.
> tibemsXAConnection_GetXASession
> Function
> Purpose
> Get the XA session object from an XA connection.
> C Declaration
> tibems_status tibemsXAConnection_GetXASession(
> tibemsConnection* connection,
> tibemsSession* xaSession );
> COBOL Call
> CALL "tibemsXAConnection_GetXASession"
> USING BY VALUE connection,
> BY REFERENCE xaSession,
> RETURNING tibems-status
> END-CALL.

> | connection and xaSession have usage pointer.

> Parameters

> Parameter | Description
> connection | Get the XA session object from this XA connection.
> xaSession | The function stores the XA session object in this location.

> Remarks
> If the TM has implicitly created a session by calling xa_open, then the TM can get that session object with this call.

Copyright © TIBCO Software Inc. All Rights Reserved