Open Source RDBMS - Seamless, Scalable, Stable and Free

한국어 | Login |Register

Versions available for this page: CUBRID 8.2.1 |  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

설명

url 인자로 전달된 접속 정보를 이용하여 데이터베이스로 연결을 시도한다. CCI에서 브로커의 HA 기능을 사용하는 경우 이 함수의 url 인자에 active 브로커 서버의 연결 정보 및 장애 발생 시 altHosts 속성에 failover할 standby 브로커 서버의 연결 정보를 명시해야 한다. 서버 연결에 성공하면 연결 핸들 ID를 반환하고, 실패하면 에러 코드를 반환한다. 브로커의 HA 기능에 대한 자세한 내용은 관리자 안내서 > CUBRID HA > CUBRID 기능 > 브로커 이중화를 참고한다

연결 대상과 관련된 속성은 altHosts이며, 타임아웃과 관련된 속성은 loginTimeout, queryTimeout, disconnectOnQueryTimeout이다.

디버깅용 로그 정보 설정과 관련된 속성은 logSlowQueries, logTraceApi, logTraceNetwork이다.

참고로, url 인자에 입력하는 모든 속성(property) 이름은 대소문자 구별을 하지 않는다.

구문

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) 서버 연결 정보 문자 스트링
    • host : 마스터 데이터베이스의 호스트 이름 또는 IP 주소
    • port : 포트 번호
    • db_name : 데이터베이스 이름
    • db_user : 데이터베이스 사용자 이름
    • db_password : 데이터베이스 사용자 비밀번호
    • altHosts=standby_broker1_host, standby_broker2_host, ... : active 서버에 연결할 수 없는 경우, 그 다음으로 연결을 시도(failover)할 standby 서버의 브로커 정보를 나타낸다. failover할 브로커를 여러 개 지정할 수 있고, altHosts에 나열한 순서대로 연결을 시도한다.
    • rcTime : 장애가 발생했던 active 브로커에 연결을 시도하는 주기이다. 장애 발생 후 altHosts에 명시한 브로커로 접속하여(failover) 트랜잭션을 종료한 후, rcTime만큼 시간이 경과할 때마다 마스터 데이터베이스의 active 브로커에 연결을 시도한다. 기본값은 600초이다.
    • loadBalance : 이 값이 true이면 응용 프로그램이 메인 호스트와 altHosts에 지정한 호스트들에 랜덤한 순서로 연결한다(기본값: false).
    • login_timeout|loginTimeout : 데이터베이스에 로그인 시 타임아웃 값(단위: msec). 이 시간을 초과하면 CCI_ER_LOGIN_TIMEOUT(-38) 에러를 반환한다. 기본값은 0이며, 무한 대기를 의미한다.
    • query_timeout|queryTimeout : cci_prepare(), cci_execute() 등의 함수를 호출했을 때 이 값으로 설정한 시간이 지나면 서버로 보낸 질의 요청에 대한 취소 메시지를 보내고 호출된 함수는 CCI_ER_QUERY_TIMEOUT(-39) 에러를 반환한다. 질의를 수행한 함수에서 타임아웃 발생 시 함수의 반환 값은 disconnect_on_query_timeout의 설정에 따라 달라질 수 있다. 자세한 내용은 다음의 disconnect_on_query_timeout을 참고한다.
    • disconnect_on_query_timeout|disconnectOnQueryTimeout : 질의 요청 타임아웃 시 즉시 소켓 연결 종료 여부. cci_prepare(), cci_execute() 등의 함수를 호출했을 때 query_timeout으로 설정한 시간이 지나면 질의 취소 요청 후 즉시 소켓 연결을 종료할 것인지, 아니면 질의 취소 요청을 받아들인다는 서버의 응답을 기다릴 것인지를 설정한다. 기본값은 false로, 서버의 응답을 기다린다. 이 값이 true이면 cci_prepare(), cci_execute() 등의 함수 호출 도중 질의 타임아웃이 발생할 때 서버에 질의 취소 메시지를 보낸 후, 소켓을 닫고 CCI_ER_QUERY_TIMEOUT(-39) 에러를 반환한다. (브로커가 아닌 데이터베이스 서버 쪽에서 에러가 발생한 경우 -1을 반환한다. 상세 에러를 확인하고 싶으면 "데이터베이스 에러 버퍼"의 에러 코드를 확인한다. 데이터베이스 에러 버퍼에서 에러 코드를 확인하는 방법은 CCI 에러 코드와 에러 메시지를 참고한다.) 이 경우 사용자는 명시적으로 cci_disconnect 함수를 통해 데이터베이스 연결 핸들을 닫아야 한다. 응용 프로그램이 질의 취소 메시지를 보낸 후 에러를 반환했음에도 불구하고, 데이터베이스 서버는 그 메시지를 받지 못하고 해당 질의를 수행할 수 있음을 주의한다. false이면 서버에 취소 메시지를 보낸 후, 서버의 질의 요청에 대한 응답이 올 때 까지 대기한다.
    • logFile : 디버깅용 로그 파일 이름(기본값: cci_<handle_id>.log). <handle_id>는 이 함수가 반환하는 연결 핸들 ID이다.
    • logBaseDir : 디버깅용 로그 파일이 생성되는 디렉터리. 경로를 포함한 파일 이름의 형식은 logBaseDir/logFile이 되며, 상대 경로로 지정할 수 있다.
    • logSlowQueries : 디버깅용 슬로우 쿼리 로깅 여부(기본값: false)
    • slowQueryThresholdMillis : 디버깅용 슬로우 쿼리 로깅 시 슬로우 쿼리 제한 시간(기본값: 60000). 단위는 밀리 초이다.
    • logTraceApi : CCI 함수 시작과 끝의 로깅 여부
    • logTraceNetwork : : CCI 함수 네트워크 데이터 전송 내용의 로깅 여부
  • db_user : (IN) 데이터베이스 사용자 이름. NULL 혹은 빈 문자열인 경우 url의 <db_user>를 사용한다.
  • db_passwd : (IN) 데이터베이스 사용자 비밀번호. NULL 혹은 빈 문자열인 경우 url의 <db_password>를 사용한다.
리턴 값
  • 성공 : 연결 핸들 ID (int)
  • 실패 : 에러 코드
에러 코드
  • 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
예제

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