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 TLS communication using these parameters.
`pk_password`	Private key password for TLS.

Remarks

When the username and password parameters are null, the connection object presents a default user identity. If the server configuration permits that anonymous user, then the call succeeds.

If the connection factory used to create the connection object has OAuth 2.0 parameters set, the connection object will attempt to obtain an OAuth 2.0 access token and present it to the EMS server for authentication. If the EMS server successfully validates the token, then the call succeeds.

The value passed to the username parameter determines which grant type is used for requesting access tokens from the OAuth 2.0 authorization server. If the username parameter is null, the connection object will request access tokens via the client credentials grant type. Otherwise, the connection object will use the username and password parameter values to request access tokens via the resource owner password credentials grant type.

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 TLS and TCP protocols. Other error situations are possible.
`TIBEMS_SECURITY_EXCEPTION`	The server rejected the connection because the username or password was invalid. TLS setup is incorrect.
`TIBEMS_INVALID_CLIENT_ID`	The client ID is not unique; that is, another client already uses the ID.