Chapter 8 Connection Factory : tibemsConnectionFactory

tibemsConnectionFactory
Type
Purpose
Administered object for creating server connections.
Remarks
Connection factories are administered objects. They support concurrent use.
Administrators define connection factories in a repository. Each connection factory has administrative parameters that guide the creation of server connections. Usage follows either of two models:
EMS Server
You can use the EMS server as a name service provider—one tibemsd process provides both the name repository and the message service. Administrators define factories in the name repository. Client programs create connection factory objects with the URL of the repository, and call tibemsConnectionFactory_CreateConnection. This function automatically accesses the corresponding factory in the repository, and uses it to create a connection to the message service.
 
Administered Objects
Administered objects let administrators configure EMS behavior at the enterprise level. Administrators define these objects, and client programs use them. This arrangement relieves program developers and end users of the responsibility for correct configuration.
See Also
tibemsLookupContext on page 322
tibemsConnectionFactory_Create
Function
Purpose
Create a connection factory.
C Declaration
tibemsConnectionFactory tibemsConnectionFactory_Create( void );
COBOL Call
CALL "tibemsConnectionFactory_Create"
RETURNING factory
END-CALL.
 
factory has usage pointer.
Remarks
The resulting connection factory object is empty. This call does not attempt to access the repository (see also tibemsLookupContext on page 322).
See Also
tibemsLookupContext on page 322
tibemsConnectionFactory_CreateConnection
Function
Purpose
Create a connection object.
C Declaration
tibems_status tibemsConnectionFactory_CreateConnection(
    tibemsConnectionFactory factory,
    tibemsConnection* connection,
    const char * username,
    const char * password );
COBOL Call
CALL "tibemsConnectionFactory_CreateConnection"
USING BY VALUE factory,
BY REFERENCE connection,
BY REFERENCE username,
BY REFERENCE password,
RETURNING tibems-status
END-CALL.
factory and connection have usage pointer.
Parameters
 
The connection object presents this user identity to the server. Set to NULL if the server isn’t authenticating or authorizing users.
The connection object authenticates the user identity with this password. Set to NULL if the server isn’t authenticating or authorizing users.
Remarks
When the identity parameters are null, the connection object presents a default user identity. If the server configuration permits that anonymous user, then the call succeeds.
See Also
tibemsConnection on page 202
tibemsConnectionFactory_CreateXAConnection
Function
Purpose
Create an XA connection object.
C Declaration
extern tibems_status
tibemsConnectionFactory_CreateXAConnection(
    tibemsConnectionFactory factory,
    tibemsConnection* connection,
    const char* username,
    const char* password);
COBOL Call
CALL "tibemsConnectionFactory_CreateXAConnection"
    USING BY VALUE factory,
           BY REFERENCE connection,
           BY REFERENCE username,
           BY REFERENCE password,
           RETURNING tibems-status
END-CALL.
factory and connection have usage pointer.
Parameters
 
The connection object presents this user identity to the server. Set to NULL if the server isn’t authenticating or authorizing users.
The connection object authenticates the user identity with this password. Set to NULL if the server isn’t authenticating or authorizing users.
Remarks
When the identity parameters are null, the connection object presents a default user identity. If the server configuration permits that anonymous user, then the call succeeds.
See Also
tibemsConnection on page 202
tibemsConnectionFactory_Destroy
Function
Purpose
Destroy a connection factory object.
C Declaration
tibems_status tibemsConnectionFactory_Destroy(
    tibemsConnectionFactory factory )
COBOL Call
CALL "tibemsConnectionFactory_Destroy"
USING BY VALUE factory,
RETURNING tibems-status
END-CALL.
 
factory has usage pointer.
Parameters
 
Remarks
This call destroys an object within the program. It does not affect objects in the repository.
tibemsConnectionFactory_GetSSLProxyHost
Function
Purpose
Get the SSL proxy host from a connection factory.
C Declaration
tibems_status tibemsConnectionFactory_GetSSLProxyHost(
    tibemsConnectionFactory factory,
    const char** proxy_host);
COBOL Call
CALL "tibemsConnectionFactory_GetSSLProxyHost"
     USING BY VALUE factory,
           BY REFERENCE proxy-host,
     RETURNING tibems-status
END-CALL.
 
factory and proxy-host have usage pointer.
Parameters
 
See Also
tibemsConnectionFactory_SetSSLProxy on page 279
tibemsConnectionFactory_GetSSLProxyPort
Function
Purpose
Get the SSL proxy port from a connection factory.
C Declaration
tibems_status tibemsConnectionFactory_GetSSLProxyPort(
    tibemsConnectionFactory factory,
    tibems_int* proxy_port);
COBOL Call
CALL "tibemsConnectionFactory_GetSSLProxyPort"
     USING BY VALUE factory,
           BY REFERENCE proxy-port,
     RETURNING tibems-status
END-CALL.
 
factory has usage pointer.
Parameters
 
See Also
tibemsConnectionFactory_SetSSLProxy on page 279
tibemsConnectionFactory_GetSSLProxyUser
Function
Purpose
Get the SSL proxy username from a connection factory.
C Declaration
tibems_status tibemsConnectionFactory_GetSSLProxyUser(
    tibemsConnectionFactory factory,
    const char** proxy_user);
COBOL Call
CALL "tibemsConnectionFactory_GetSSLProxyUser"
     USING BY VALUE factory,
           BY REFERENCE proxy-user,
     RETURNING tibems-status
END-CALL.
 
factory and proxy-user have usage pointer.
Parameters
 
See Also
tibemsConnectionFactory_SetSSLProxyAuth on page 280
tibemsConnectionFactory_GetSSLProxyPassword
Function
Purpose
Get the SSL proxy password from a connection factory.
C Declaration
tibems_status tibemsConnectionFactory_GetSSLProxyPassword(
    tibemsConnectionFactory factory,
    const char** proxy_password);
COBOL Call
CALL "tibemsConnectionFactory_GetSSLProxyPassword"
     USING BY VALUE factory,
           BY REFERENCE proxy-password,
     RETURNING tibems-status
END-CALL.
 
factory and proxy-password have usage pointer.
Parameters
 
See Also
tibemsConnectionFactory_SetSSLProxyAuth on page 280
tibemsConnectionFactory_Print
Function
Purpose
Print the parameters set in a connection factory object.
C Declaration
tibems_status tibemsConnectionFactory_Print(
    tibemsConnectionFactory factory);
COBOL Call
CALL "tibemsConnectionFactory_Print"
     USING BY VALUE factory,
           RETURNING tibems-status
END-CALL.
 
factory has usage pointer.
Parameters
 
 
tibemsConnectionFactory_SetClientID
Function
Purpose
Set the client ID of a connection factory object.
C Declaration
tibems_status tibemsConnectionFactory_SetClientID(
    tibemsConnectionFactory factory,
    const char* cid );
COBOL Call
CALL "tibemsConnectionFactory_SetClientID"
USING BY VALUE factory,
BY REFERENCE cid,
RETURNING tibems-status
END-CALL.
 
factory has usage pointer.
Parameters
 
Remarks
A client ID string lets the server associate a client-specific factory with each client program. When such a factory already exists, the server supplies that factory to the client. If a factory does not yet exist for the client, the server creates one, and stores it for future use by that specific client.
tibemsConnectionFactory_SetConnectAttemptCount
Function
Purpose
Modify the connection attempts setting.
C Declaration
tibems_status tibemsConnectionFactory_SetConnectAttemptCount(
    tibemsConnectionFactory factory,
    tibems_int connAttempts );
COBOL Call
CALL "tibemsConnectionFactory_SetConnectAttemptCount"
USING BY VALUE factory,
BY VALUE connAttempts,
RETURNING tibems-status
END-CALL.
 
factory has usage pointer.
Parameters
 
This value limits the number of times that a connection object attempts to establish a connection to the server. The minimum value is 1.
See Also
tibemsConnectionFactory_SetConnectAttemptDelay on page 268
tibemsConnectionFactory_SetConnectAttemptTimeout on page 269
Setting Connection Attempts, Timeout and Delay Parameters in the TIBCO Enterprise Message Service User’s Guide
 
tibemsConnectionFactory_SetConnectAttemptDelay
Function
Purpose
Modify the connection delay setting.
C Declaration
tibems_status tibemsConnectionFactory_SetConnectAttemptDelay(
    tibemsConnectionFactory factory,
    tibems_int delay );
COBOL Call
CALL "tibemsConnectionFactory_SetConnectAttemptDelay"
USING BY VALUE factory,
BY VALUE delay,
RETURNING tibems-status
END-CALL.
 
factory has usage pointer.
Parameters
 
This value determines the time (in milliseconds) between connection attempts. The minimum value is 250.
See Also
tibemsConnectionFactory_SetConnectAttemptCount on page 267
tibemsConnectionFactory_SetConnectAttemptTimeout on page 269
Setting Connection Attempts, Timeout and Delay Parameters in the TIBCO Enterprise Message Service User’s Guide
 
tibemsConnectionFactory_SetConnectAttemptTimeout
Function
Purpose
Modify the connection timeout setting.
C Declaration
tibems_status tibemsConnectionFactory_SetConnectAttemptTimeout(
    tibemsConnectionFactory factory,
    tibems_int timeout );
COBOL Call
CALL "tibemsConnectionFactory_SetConnectAttemptTimeout"
USING BY VALUE factory,
BY VALUE timeout,
RETURNING tibems-status
END-CALL.
 
factory has usage pointer.
Parameters
 
This value determines the maximum time (in milliseconds) the client will wait for a connection to the server to be established.
See Also
tibemsConnectionFactory_SetConnectAttemptCount on page 267
tibemsConnectionFactory_SetConnectAttemptDelay on page 268
Setting Connection Attempts, Timeout and Delay Parameters in the TIBCO Enterprise Message Service User’s Guide
tibemsConnectionFactory_SetMetric
Function
Purpose
Modify the load balancing metric.
C Declaration
tibems_status tibemsConnectionFactory_SetMetric(
    tibemsConnectionFactory factory,
    tibemsFactoryLoadBalanceMetric metric );
COBOL Call
CALL "tibemsConnectionFactory_SetMetric"
USING BY VALUE factory,
BY VALUE metric,
RETURNING tibems-status
END-CALL.
 
factory has usage pointer.
Parameters
 
Remarks
When the connection factory balances the client load among several servers, it uses this metric to determine the least loaded server, so the connection factory can create a connection to it. For values, see tibemsFactoryLoadBalanceMetric on page 283.
tibemsConnectionFactory_SetMulticastDaemon
Function
Purpose
Sets the port on which the client will connect to the multicast daemon.
C Declaration
tibems_status tibemsConnectionFactory_SetMulticastDaemon(
    tibemsConnectionFactory factory,
    const char* multicastDaemon);
Parameters
 
The port number for the multicast daemon that connections created using this factory will connect to.
Remarks
A connection to the multicast daemon is required when multicast is enabled and a consumer is subscribed to a multicast-enabled topic. Setting the port with this method will override the default port supplied by the server.
See Also
tibemsConnectionFactory_SetMulticastEnabled on page 272
tibems_SetMulticastDaemon on page 398
 
tibemsConnectionFactory_SetMulticastEnabled
Function
Purpose
Set whether message consumers subscribed to multicast-enabled topics will receive messages over multicast.
C Declaration
tibems_status tibemsConnectionFactory_SetMulticastEnabled(
    tibemsConnectionFactory factory,
    tibems_bool multicastEnabled);
Parameters
 
When true, multicast is enabled. When false, multicast is disabled.
Remarks
When enabled, message consumers using a connection created by this factory, and which are subscribed to a multicast-enabled topic will receive messages over multicast. The default is enabled.
See Also
tibemsConnectionFactory_SetMulticastDaemon on page 271
tibems_SetMulticastEnabled on page 399
multicast and multicast_daemon_default server parameters in the TIBCO Enterprise Message Service User’s Guide
tibemsConnectionFactory_SetPkPassword
Function
Purpose
Set the SSL private key password for the connection factory.
C Declaration
extern tibems_status tibemsConnectionFactory_SetPkPassword(
    tibemsConnectionFactory factory,
    const char* pk_password);
COBOL Call
CALL "tibemsConnectionFactory_SetPkPassword"
    USING BY VALUE factory,
           BY REFERENCE pk_password,
           RETURNING tibems-status
END-CALL.
 
factory has usage pointer.
Parameters
 
Connections created by the connection factory decode their SSL private key using this password when establishing SSL communication.
Remarks
It is an error to call this function on a connection factory for which an tibemsSSLParams struct is not yet set.
Notice that this SSL private key encryption password is distinct from the server authentication password, and from the proxy authentication password.
See Also
tibemsSSLParams on page 231
tibemsConnectionFactory_SetSSLParams on page 278
tibemsConnectionFactory_SetReconnectAttemptCount
Function
Purpose
Modify the reconnection attempts setting.
C Declaration
tibems_status tibemsConnectionFactory_SetReconnectAttemptCount(
    tibemsConnectionFactory factory,
    tibems_int connAttempts );
COBOL Call
CALL "tibemsConnectionFactory_SetReconnectAttemptCount"
USING BY VALUE factory,
BY VALUE connAttempts,
RETURNING tibems-status
END-CALL.
 
factory has usage pointer.
Parameters
 
This value limits the number of times that a connection object attempts to reestablish a connection to the server. The minimum value is 1.
See Also
tibemsConnectionFactory_SetReconnectAttemptDelay on page 275
tibemsConnectionFactory_SetReconnectAttemptTimeout on page 276
 
Setting Reconnection Failure Parameters in the TIBCO Enterprise Message Service User’s Guide.
tibemsConnectionFactory_SetReconnectAttemptDelay
Function
Purpose
Modify the reconnection delay setting.
C Declaration
tibems_status tibemsConnectionFactory_SetReconnectAttemptDelay(
    tibemsConnectionFactory factory,
    tibems_int delay );
COBOL Call
CALL "tibemsConnectionFactory_SetReconnectAttemptDelay"
USING BY VALUE factory,
BY VALUE delay,
RETURNING tibems-status
END-CALL.
 
factory has usage pointer.
Parameters
 
This value determines the time (in milliseconds) between reconnection attempts. The minimum value is 250.
See Also
tibemsConnectionFactory_SetReconnectAttemptCount on page 274
tibemsConnectionFactory_SetReconnectAttemptTimeout on page 276
 
Setting Reconnection Failure Parameters in the TIBCO Enterprise Message Service User’s Guide.
 
tibemsConnectionFactory_SetReconnectAttemptTimeout
Function
Purpose
Modify the reconnection timeout setting.
C Declaration
tibems_status tibemsConnectionFactory_SetReconnectAttemptTimeout(
    tibemsConnectionFactory factory,
    tibems_int timeout );
COBOL Call
CALL "tibemsConnectionFactory_SetReconnectAttemptTimeout"
USING BY VALUE factory,
BY VALUE timeout,
RETURNING tibems-status
END-CALL.
 
factory has usage pointer.
Parameters
 
This value determines the maximum time (in milliseconds) a client will wait for the reconnection to be established.
See Also
tibemsConnectionFactory_SetReconnectAttemptCount on page 274
tibemsConnectionFactory_SetReconnectAttemptDelay on page 275
 
Setting Reconnection Failure Parameters in the TIBCO Enterprise Message Service User’s Guide.
 
tibemsConnectionFactory_SetServerURL
Function
Purpose
Set the server URL.
C Declaration
tibems_status tibemsConnectionFactory_SetServerURL(
    tibemsConnectionFactory factory,
    const char* url );
COBOL Call
CALL "tibemsConnectionFactory_SetServerURL"
USING BY VALUE factory,
BY REFERENCE url,
RETURNING tibems-status
END-CALL.
 
factory has usage pointer.
Parameters
 
The factory object contacts the EMS server at this URL, to access a corresponding factory defined by the administrator.
Reconnect and Fault Tolerance
To enable reconnection behavior and fault tolerance, the connection factory’s server URL parameter must be a comma-separated list of two or more URLs. To enable client reconnection in a situation with only one server, you may supply two copies of that server’s URL (for example, tcp://localhost:7222,tcp://localhost:7222).
Note that tibemsConnectionFactory_SetServerURL can be used to set the server URL for a connection factory only once. If the URL has previously been set for the connection factory, tibemsConnectionFactory_SetServerURL returns the status code TIBEMS_EXCEPTION.
tibemsConnectionFactory_SetSSLParams
Function
Purpose
Set a connection factory’s default SSL parameters.
C Declaration
tibems_status tibemsConnectionFactory_SetSSLParams(
    tibemsConnectionFactory factory,
    tibemsSSLParams sslparams );
COBOL Call
CALL "tibemsConnectionFactory_SetSSLParams"
USING BY VALUE factory,
BY VALUE sslparams,
RETURNING tibems-status
END-CALL.
 
factory and sslparams have usage pointer.
Parameters
 
See Also
tibemsSSLParams on page 231
tibemsConnectionFactory_CreateConnection on page 258
tibemsConnectionFactory_SetSSLProxy
Function
Purpose
Set a connection factory’s parameters for connecting through an SSL proxy.
C Declaration
tibems_status tibemsConnectionFactory_SetSSLProxy(
    tibemsConnectionFactory factory,
    const char* proxy_host,
    tibems_int proxy_port);
COBOL Call
CALL "tibemsConnectionFactory_SetSSLProxy"
     USING BY VALUE factory,
           BY REFERENCE proxy-host,
           BY VALUE proxy-port,
           RETURNING tibems-status
END-CALL.
 
factory has usage pointer.
Parameters
 
The connection factory establishes SSL communication through a web proxy at this host. Supply a simple hostname, a fully qualified hostname with domain name, or an IP address (dot notation).
Remarks
An SSL proxy lets an EMS application create an SSL connection to an EMS server, even though a firewall separates the application from the server. The proxy usually runs within the firewall’s DMZ.
A connection factory contacts the SSL proxy, requesting an SSL connection to the server. The proxy authenticates the application program, and mediates the initial SSL negotiation between application and server. After the SSL connection is established, the application and server use it to communicate directly with one another.
See Also
tibemsConnectionFactory_GetSSLProxyHost on page 261
tibemsConnectionFactory_GetSSLProxyPort on page 262
tibemsConnectionFactory_SetSSLProxyAuth on page 280
tibemsConnectionFactory_SetSSLProxyAuth
Function
Purpose
Set a connection factory’s username and password for connecting through an SSL proxy.
C Declaration
tibems_status
tibemsConnectionFactory_SetSSLProxyAuth(
    tibemsConnectionFactory factory,
    const char* proxy_user,
    const char* proxy_password);
COBOL Call
CALL "tibemsConnectionFactory_SetSSLProxy"
     USING BY VALUE factory,
           BY REFERENCE proxy-user,
           BY REFERENCE proxy-password,
           RETURNING tibems-status
END-CALL.
 
factory has usage pointer.
Parameters
 
Remarks
When a connection factory establishes an EMS server connection through an SSL proxy host, the proxy might first require authentication before facilitating a connection. When required, use this call to set that authentication data on the connection factory. Notice that this proxy authentication data is distinct from the server authentication data, and from the SSL private key encryption password.
See Also
tibemsConnectionFactory_GetSSLProxyUser on page 263
tibemsConnectionFactory_GetSSLProxyPassword on page 264
tibemsConnectionFactory_SetSSLProxy on page 279
tibemsConnectionFactory_SetUserName
Function
Purpose
Set a connection factory’s username.
C Declaration
tibems_status
tibemsConnectionFactory_SetUserName(
    tibemsConnectionFactory factory,
    const char* username);
COBOL Call
CALL "tibemsConnectionFactory_SetUserName"
     USING BY VALUE factory,
           BY REFERENCE username,
           RETURNING tibems-status
END-CALL.
 
factory has usage pointer.
Parameters
 
Remarks
When a connection factory establishes an EMS server connection, the EMS server requests identification. Use this call to set the username that the connection factory uses to identify itself to the EMS server. Notice that this server authentication data is different from SSL authentication data.
See Also
tibemsConnectionFactory_SetUserPassword on page 282
tibemsConnectionFactory_SetUserPassword
Function
Purpose
Set the password used by the connection factory to authenticate itself with the EMS Server.
C Declaration
tibems_status
tibemsConnectionFactory_SetUserPassword(
    tibemsConnectionFactory factory,
    const char* password);
COBOL Call
CALL "tibemsConnectionFactory_SetUserPassword"
     USING BY VALUE factory,
           BY REFERENCE password,
           RETURNING tibems-status
END-CALL.
 
factory has usage pointer.
Parameters
 
Remarks
When a connection factory establishes an EMS server connection, the EMS server requests authentication. Use this call to set the password that the connection factory uses to authenticate itself with the EMS server. Notice that this server authentication data is different from SSL authentication data.
See Also
tibemsConnectionFactory_SetUserName on page 281