The cci_connect_with_url function connects a database by using connection information passed with a url argument. If CUBRID HA of broker is enabled in CCI, you must specify the connection information of the standby broker server, which is used for failover in althost property when failure occurs, in the url argument of this function. If it has succeeded, the ID of connection handle is returned; it returns an error code on failure. For details about HA features of broker, see Administrator Guide > CUBRID HA > CUBRID Features > Duplexing Brokers.
althosts is the property related to connection target and loginTimeout, queryTimeout, and disconnectOnQueryTimeout are the properties related to timeout; logSlowQueries, logTraceApi, and logTraceNetwork are the properties related to log information configuration for debugging.
Note that a property name which is a value to be entered in the url argument is not case sensitive.
int cci_connect_with_url (char *url, char *db_user, char *db_password )
<properties> ::= <property> [&<property>]
<property> ::= althosts=<alternative_hosts> [ &rctime=<time>]
<alternative_hosts> ::= <host>:<port> [,<host>:<port>]
<host> := HOSTNAME | IP_ADDR
<time> := SECOND
<milli_sec> := MILLI SECOND
- url: (IN) A string that contains server connection information
- host: A host name or IP address of the master database
- port: A port number
- db_name: A name of the database
- db_user: A name of the database user
- db_password: A database user password
- althosts=standby_broker1_host, standby_broker2_host, . . .: Specifies the broker information of the standby server, which is used for failover when it is impossible to connect to the active server. You can specify multiple brokers for failover, and the connection to the brokers is attempted in the order listed in alhosts.
- rctime: An interval between the attempts to connect to the active broker in which failure occurred. After a failure occurs, the system connects to the broker specified by althosts (failover), terminates the transaction, and then attempts to connect to the active broker of the master database at every rctime. The default value is 600 seconds.
- login_timeout|loginTimeout: Timeout value (unit: msec.) for database login. Upon timeout, a CCI_ER_LOGIN_TIMEOUT (-38) error is returned. The default value is 0, which means infinite postponement.
- query_timeout|queryTimeout: If time specified in these properties has expired when calling cci_prepare(), cci_execute(), etc. a cancellation message for query request which was sent to a server will be delivered and called function returns a CCI_ER_QUERY_TIMEOUT (-39) error. The value returned upon timeout may vary depending on a value specified in disconnect_on_query_timeout. For details, see disconnect_on_query_timeout.
- disconnect_on_query_timeout|disconnectOnQueryTimeout: Whether to disconnect socket immediately after time for query request has expired. It determines whether to terminate a socket connection immediately or wait for server response after sending cancellation message for query request to a server when calling cci_prepare(), cci_execute(), etc. The default value is false, meaning that it will wait for server response. It this value is true, a socket will be closed immediately after sending a cancellation message to a server upon timeout and returns the CCI_ER_QUERY_TIMEOUT (-39) error. (If an error occurs on database server side, not on broker side, it returns -1. If you want to view error details, see error codes in "database error buffer." You can get information how to check error codes in CCI Error Codes and Error Messages.) In this case, you must explicitly close the database connection handle by using the cci_disconnect function. Please note that there is a possibility that a database server does not get a cancellation message and execute a query even after an error is returned.
- logFile: A log file name for debugging (default value: cci_<handle_id>.log). <handle_id> indicates the ID of a connection handle returned by this function.
- logBaseDir: A directory where a debug log file is created
- logSlowQueries: Whether to log slow query for debugging (default value: false)
- slowQueryThresholdMillis: Timeout for slow query logging if slow query logging is enabled (default value: 60000, unit: milliseconds)
- logTraceApi: Whether to log the start and end of CCI functions
- logTraceNetwork: Whether to log network data content transferred of CCI functions
- db_user: (IN) Database user name. If it is NULL or an empty string, use <db_user> in url.
- db_passwd: (IN) Database user password. If it is NULL or an empty string, use <db_password> in url.
- Success: Connection handle ID (int)
- Failure: Error code
--connection URL string when a property(althosts) is specified for HA
--connection URL string when properties(althosts,rctime) is specified for HA
--connection URL string when properties(logSlowQueries,slowQueryThresholdMills, logTraceApi, logTraceNetwork) are specified for interface debugging
URL = "cci:cubrid:192.168.0.1:33000:demodb:::?logSlowQueries=true&slowQueryThresholdMillis=1000&logTraceApi=true&logTraceNetwork=true"
- Because a colon (:) and a question mark (?) are used as a separator in URL string, it is not allowed to include them for password of URL string. To use them, you must specify a user name (db_user) and a password (db_passwd) as a separate parameter.