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

Note: On IBM z/OS systems, the `pk-password` must always be a null value.

## Parameters

Parameter | Description
--- | ---
`connection` | Store the new connection in this location.
`brokerURL` | URL location of the EMS server. If configuring a fault-tolerant client, enter two or 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`

Copyright © Cloud Software Group, Inc. All rights reserved.