Open Source RDBMS - Seamless, Scalable, Stable and Free

한국어 | Login |Register

Versions available for this page: CUBRID 8.3.0 |  CUBRID 8.3.1 |  CUBRID 8.4.0 |  CUBRID 8.4.1 |  CUBRID 8.4.3 |  CUBRID 9.0.0 | 

cci_connect_with_url

Description

The cci_connect_with_url function connects a database by using connection information passed with a url argument. If the broker's HA feature is used in CCI, you must specify the altHosts property, connection information of the standby broker server, which is used for failover when failure occurs. If it has succeeded, the ID of connection handle is returned it returns an error code on failure.

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.

Syntax

int cci_connect_with_url (char *url [, char *db_user, char *db_password ])

 

< url> ::=

cci:CUBRID:< host> :< port> :< db_name> :< db_user> :< db_password> :[?< properties> ]

 

< properties> ::= < property> [& < property> ]

< property> ::= altHosts=< alternative_hosts> [ & rcTime=<time> ]

[ &loadBalance=true|false]

                          |{login_timeout|loginTimeout}=< milli_sec>

                          |{query_timeout|queryTimeout}=< milli_sec>

                          |{disconnect_on_query_timeout|disconnectOnQueryTimeout}=true|false

                          | logFile=< file_name>

                          | logBaseDir=< dir_name>

                          | logSlowQueries=true|false[& slowQueryThresholdMillis=< milli_sec> ]

                          | logTraceApi=true|false

                          | logTraceNetwork=true|false

 

< 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 altHosts.
    • 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.
    • loadBalance: When this value is true, the applications try to connect with the main host and alternative hosts specified with altHost property as random order. (default value: false).
    • 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. The file name including the path will be logBaseDir/logFile, and the relative path is possible.
    • 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.
Return Value
  • Success: Connection handle ID (int)
  • Failure: Error code
Error Code
  • CCI_ER_NO_MORE_MEMORY
  • CCI_ER_HOSTNAME
  • CCI_ER_INVALID_URL
  • CCI_ER_CON_HANDLE
  • CCI_ER_CONNECT
  • CCI_ER_DBMS
  • CCI_ER_COMMUNICATION
  • CCI_ER_LOGIN_TIMEOUT
Example

--connection URL string when a property(altHosts) is specified for HA

URL=cci:CUBRID:192.168.0.1:33000:demodb:::?altHosts=192.168.0.2:33000,192.168.0.3:33000

 

--connection URL string when properties(altHosts,rcTime) is specified for HA

URL=cci:CUBRID:192.168.0.1:33000:demodb:::?altHosts=192.168.0.2:33000,192.168.0.3:33000& rcTime=600

 

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