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

Note: `connection` and `sslParams` have usage pointer.

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

`SSL Implementation on IBM EBCDIC Systems`

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