SQLAllocHandle

SQLAllocHandle

환경, 연결, 그리고 명령문 핸들을 위한 메모리를 할당하고 초기화 한다.

구 문

SQLRETURN  SQLAllocHandle (
    SQLSMALLINT     HandleType,
    SQLHANDLE       InputHandle,
    SQLHANDLE *     OutputHandlePtr );

인 자

자료유형	인자	사용	설명
SQLSMALLINT	HandleType	입력	할당 될 핸들 타입으로 다음 세 값 중에 하나이다. SQL_HANDLE_ENV SQL_HANDLE_DBC SQL_HANDLE_STMT
SQLHANDLE	InputHandle	입력	입력 핸들 HandleType이 SQL_HANDLE_ENV이면 InputHandle은 SQL_NULL_HANDLE이고 SQL_HANDLE_DBC이면 환경 핸들이어야 하고 SQL_HANDLE_STMT이면 연결 핸들이어야 한다.
SQLHANDLE *	OutputHandlePtr	출력	할당 받은 핸들의 포인터

결괏값

SQL_SUCCESS
SQL_SUCCESS_WITH_INFO
SQL_INVALID_HANDLE
SQL_ERROR

설 명

SQLAllocHandle()은 다음 단락에서 묘사될 환경, 연결, 그리고 명령문 핸들을 할당한다.

이 함수는 SQLAllocEnv(), SQLAllocConnect() 및 SQLAllocStmt() 함수들을 대치한다. 환경 핸들을 요구하기 위하여 애플리케이션은 HandleType이 SQL_HANDLE_ENV이고, InputHandle이 SQL_NULL_HANDLE인 SQLAllocHandle()을 호출한다. 연결 핸들을 요구하기 위하여 애플리케이션은 HandleType이 SQL_HANDLE_DBC인 SQLAllocHandle()을 호출하고, 그때의 InputHandle은 유효한 환경 핸들이어야 한다. 명령문 핸들을 요구하기 위하여 애플리케이션은 HandleType이 SQL_HANDLE_STMT인 SQLAllocHandle()을 호출하고, 그때의 InputHandle은 유효한 연결 핸들이어야 한다.

한 애플리케이션에 의해 한 번에 한 개 이상의 환경, 연결, 그리고 명령문 핸들들이 할당 될 수 있는데, 한 프로세스 내의 다른 쓰레드 상에서 같은 환경, 연결, 또는 명령문 핸들은 동시에 사용할 수 없다.

환경 핸들 할당

환경 핸들은 연결 핸들이 유효하다든지 활성화 돼 있다든지 하는 전역적인 정보를 제공한다.

환경 핸들을 요구하기 위해 애플리케이션은 Handletype이 SQL_HANDLE_ENV이고 InputHandle이 SQL_NULL_HANDLE인 SQLAllocHandle()을 호출한다. Altibase CLI 드라이버는 환경 정보에 필요한 메모리를 할당하고, *OutputHandle에 관련 핸들의 값을 돌려준다. 애플리케이션은 *OutputHandle 값을 환경 핸들을 필요로하는 후속 호출들에 전달한다.

연결 핸들 할당

연결 핸들은 연결 핸들상에서 명령문 핸들이 유효한가, 트랜잭션이 현재 열려있는가와 같은 정보를 제공한다.

연결 핸들을 요구하기위해, 애플리케이션은 HandleType이 SQL_HANDLE_DBC인 SQLAllocHandle()을 호출한다. InputHandle 인자는 SQLAllocHandle()을 호출함으로서 반환된 환경 핸들로 설정된다. Altibase CLI 드라이버는 연결 정보에 필요한 메모리를 할당하고, *OutputHandle에 관련 핸들의 값을 돌려준다. 애플리케이션은 *OutputHandle 값을 연결 핸들을 필요로하는 후속 호출들에 전달한다.

명령문 핸들 할당

명령문 핸들은 SQL문 처리에 대한 오류 메세지 그리고 상태 정보등과 같은 명령문 정보를 제공한다.

명령문 핸들을 요구하기위해, 애플리케이션은 데이터베이스와 연결하고, SQL 문을 보내기 전에 SQLAllocHandle()을 호출한다. 이러한 호출에서 HandleType은 SQL_HANDLE_STMT로 설정돼야만 하고 InputHandle 인자는 SQLAllocHandle()을 호출함으로서 반환된 연결 핸들로 설정되야만 한다. Altibase CLI 드라이버는 명령문 정보에 필요한 메모리를 할당하고, 명시된 연결로 명령문 핸들과 연결하고, *OutputHandle에 관련 핸들의 값을 돌려준다. 애플리케이션은 *OutputHandle 값을 명령문 핸들을 필요로하는 후속 호출들에 전달한다.

진 단

SQLSTATE	설명	부연설명
HY000	일반 오류
HY001	메모리 할당 오류	명시된 핸들을 위한 메모리 할당에 실패 함.
HY009	유효하지 않은 인자 (null pointer) 사용	OutputHandlePtr가 null pointer 임.

관련 함수

SQLExecDirect
SQLExecute
SQLFreeHandle
SQLPrepare
SQLSetConnectAttr
SQLSetEnvAttr
SQLSetStmtAttr

예 제

< $ALTIBASE_HOME/sample/SQLCLI/demo_meta1.cpp 참고 >

/* Environment 을 위한 메모리를 할당 */
if (SQLAllocHandle(SQL_HANDLE_ENV, SQL_NULL_HENV, &env) != SQL_SUCCESS)
{
    printf("SQLAllocEnv error!!\n");
    return SQL_ERROR;
}

/* Connection 을 위한 메모리를 할당  */
if (SQLAllocHandle(SQL_HANDLE_DBC, env, &dbc) != SQL_SUCCESS)
{   
    printf("SQLAllocConnect error!!\n");
    return SQL_ERROR;
}