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

See Also

tibemsConnectionFactory_Create


TLS Implementation on IBM EBCDIC Systems