SQLSetStmtAttr

SQLSetStmtAttr

명령문 핸들과 관련된 속성을 설정한다.

Unicode SQLSetStmtAttrW() 동작은 SQLSetStmtAttr()와 동일하다.

구 문

SQLRETURN  SQLSetStmtAttr (
    SQLHSTMT    stmt,
    SQLINTEGER  Attribute,
    SQLPOINTER  param,
    SQLINTEGER  StringLength );

인 자

자료유형	인자	사용	설명
SQLHENV	stmt	입력	명령문 핸들
SQLINTEGER	Attribute	입력	설정할 속성. 지원되는 속성값은 - SQL_ATTR_CONCURRENCY - SQL_ATTR_CURSOR_SCROLLABLE - SQL_ATTR_CURSOR_SENSITIVITY - SQL_ATTR_CURSOR_TYPE - SQL_ATTR_PARAM_BIND_TYPE - SQL_ATTR_PARAM_STATUS_PTR - SQL_ATTR_PARAMS_PROCESSED_PTR - SQL_ATTR_PARAMSET_SIZE - SQL_ATTR_PREFETCH_ROWS - SQL_ATTR_ROW_ARRAY_SIZE - SQL_ATTR_ROW_BIND_TYPE - SQL_ATTR_ROW_STATUS_PTR - SQL_ATTR_ROWS_FETCHED_PTR - ALTIBASE_STMT_ATTR_ATOMIC_ARRAY - SQL_ATTR_FETCH_BOOKMARK_PTR - SQL_ATTR_ROW_OPERATION_PTR - SQL_ATTR_USE_BOOKMARKS - SQL_ATTR_CURSOR_HOLD - ALTIBASE_PREFETCH_AUTO_TUNING - ALTIBASE_PREPARE_WITH_DESCRIBEPARAM 현재 지원되지 않는 속성값은 - SQL_ATTR_APP_PARAM_DESC - SQL_ATTR_APP_ROW_DESC - SQL_ATTR_ASYNC_ENABLE - SQL_ATTR_ENABLE_AUTO_IPD - SQL_ATTR_IMP_PARAM_DESC - SQL_ATTR_IMP_ROW_DESC - SQL_ATTR_KEYSET_SIZE - SQL_ATTR_MAX_LENGTH - SQL_ATTR_METADATA_ID - SQL_ATTR_NOSCAN - SQL_ATTR_PARAM_BIND_OFFSET_PTR - SQL_ATTR_PARAM_OPERATION_PTR - SQL_ATTR_QUERY_TIMEOUT - SQL_ATTR_RETRIEVE_DATA - SQL_ATTR_ROW_BIND_OFFSET_PTR - SQL_ATTR_ROW_NUMBER - SQL_ATTR_SIMULATE_CURSOR
SQLPOINTER	param	입력	Attribute와 연관된 값의 포인터. Attribute 값에 따라 param은 32 bit 부호 없는 정수 값이거나 null-terminated 문자열의 포인터, 바이너리 버퍼, 또는 ODBC에서 정의된 값 Attribute가 ODBC 고유의 값이면 param은 부호 표시 정수이다.
SQLINTEGER	StringLength	입력	Attribute가 ODBC에서 정의된 속성이고 param이 문자열 또는 바이너리 버퍼를 가리키면 이 인자는 *param의 바이트 길이 여야만 한다. Attribute가 ODBC에서 정의된 속성이고 param이 정수면 이 인자는 무시된다.

결괏값

SQL_SUCCESS 
SQL_SUCCESS_WITH_INFO
SQL_INVALID_HANDLE  
SQL_ERROR

설 명

명령문 속성은 다른 SQLSetStmtAttr() 호출에 의해 옵션이 변경되거나 명령문이 SQLFreeHandle()을 호출하여 stmt가 제거될 때까지 stmt에 대한 명령문 옵션은 효력이 있다. 핸들 해제 방식 SQL_CLOSE, SQL_UNBIND, 또는 SQL_RESET_PARAMS과 함께 SQLFreeStmt()를 호출하는 것은 명령문 속성을 재설정하지 않는다.

열 양식 바인딩을 사용하기 위해 애플리케이션은 함수 SQLSetStmtAttr()의 인자 Attribute에 SQL_ATTR_PARAM_BIND_TYPE을 설정하고 인자 param에 SQL_PARAM_BIND_BY_COLUMN을 설정한다. 만약 실행 도중 매번 ARRAY_SIZE가 변경된다면, PARAM_SIZE만 변경을 하면 된다.

PARAM_STATUS_PTR은 각 열들이 수행되었는지에 대한 여부를 돌려주기 위한 값으로 SQLSMALLINT의 배열로 지정한다. 성공하면 SQL_SUCCESS, SQL_SUCCESS_WITH_INFO가, 실패하면 SQL_PARAM_ERROR, 수행되지 않은 경우 SQL_PARAM_UNUSED가 반환된다. 매크로 값은 SQL_PARAM_SUCCESS은 0, SQL_PARAM_ERROR는 5, SQL_PARAM_SUCCESS_WITH_INFO는 6, SQL_PARAM_UNUSED는 7이다.

SQLSetStmtAttr(stmt, SQL_ATTR_PARAM_BIND_TYPE, SQL_PARAM_BIND_BY_COLUMN);
SQLSetStmtAttr(stmt, SQL_ATTR_PARAMSET_SIZE, ARRAY_SIZE, 0);
SQLSetStmtAttr(stmt, SQL_ATTR_PARAM_STATUS_PTR, ParamStatusArray, 0);

PARAMS_PROCESSED_PTR에 처리된 열의 개수를 저장하기 위한 변수의 포인터를 지정한다. SQLINTEGER의 포인터형이다. 그 다음 기존처럼 SQLBindParameter()를 수행하면 된다.

SQLSetStmtAttr(stmt, SQL_ATTR_PARAMS_PROCESSED_PTR, &ParamsProcessed, 0);

SQLBindParameter()를 수행

행 양식 바인딩을 사용할 때, 열 양식 바인딩과의 차이는 PARAM_BIND_TYPE에 structure의 크기를 지정하는 것이다.

SQLSetStmtAttr(stmt, SQL_ATTR_PARAM_BIND_TYPE, sizeof(struct…));
SQLSetStmtAttr(stmt, SQL_ATTR_PARAMSET_SIZE, ARRAY_SIZE, 0);
SQLSetStmtAttr(stmt, SQL_ATTR_PARAM_STATUS_PTR, ParamStatusArray, 0);
SQLSetStmtAttr(stmt, SQL_ATTR_PARAMS_PROCESSED_PTR, &ParamsProcessed, 0);

SQLBindParameter()를 수행

명령문 속성

Attribute	내용
SQL_ATTR_CONCURRENCY	커서의 동시성 처리를 명시하는 SQLUINTEGER 값. - SQL_CONCUR_READ_ONLY: 커서는 read-only이다. update는 허용하지 않는다. - SQL_CONCUR_ROWVER: 행 버전으로 동시성 제어 - SQL_CONCUR_LOCK 및 SQL_CONCUR_VALUES는 미지원.
SQL_ATTR_CURSOR_SCROLLABLE	이 명령문 핸들에 대해 열린 커서를 스크롤할 수 있는지를 지정하는 32비트 정수 값.
SQL_ATTR_CURSOR_SENSITIVITY	명령문 핸들에 대해 열린 커서가 다른 커서가 변경한 내용을 볼 수 있는지 여부를 지정하는 32비트 정수 값. SQL_INSENSITIVE 또는 SQL_SENSITIVE로 지정 가능. SQL_UNSPECIFIED는 미지원.
SQL_ATTR_CURSOR_TYPE	커서 타입을 명시하는 SQLUINTEGER 값. - SQL_CURSOR_FORWARD_ONLY: 커서는 순방향으로만 진행 - SQL_CURSOR_STATIC: 결과 집합 내의 데이터는 STATIC 이다. - SQL_CURSOR_KEYSET_DRIVEN: 커서에 포함되는 행의 멤버와 순서가 고정적이다. Altibase CLI 드라이버는 순수한 키집합 커서를 지원한다. SQL_KEYSET_SIZE 명령문 속성은 무시된다.
SQL_ATTR_PARAM_BIND_TYPE	(array binding 시 필요한 설정값) 이 필드는 열 양식 바인딩으로 검색하기 위해 SQL_PARAM_BIND_BY_COLUMN (기본값)이 설정된다. 행 양식 바인딩으로 검색하기 위해서는 구조의 길이나 동적 매개변수들이 바인드될 버퍼의 길이가 설정된다. 이 길이는 바인드된 매개변수 스페이스를 포함해야 한다.
SQL_ATTR_PARAM_STATUS_PTR	(array binding 시 필요한 설정값) 이 필드는 PARAMSET_SIZE가 1 보다 클 때만 요구된다. 상태 값들은 다음 값들을 가질 수 있다: - SQL_PARAM_SUCCESS: SQL 문이 성공적으로 수행된다.. 매크로 값은 0. - SQL_PARAM_SUCCESS_WITH_INFO: SQL 문이 성공적으로 수행된다.; 그러나 경고 정보를 진단 데이터 구조에서 볼 수 있다. 매크로 값은 5. - SQL_PARAM_ERROR: 매개변수들을 수행하는데 있어서 오류가 있다. 추가적인 오류 정보를 진단 데이터 구조에서 볼 수 있다. 매크로 값은 6. - SQL_PARAM_UNUSED: 이 매개변수 집합은 사용되지 않는다. 아마도 이전 매개변수 집합이 추가 진행을 중단하는 오류를 야기했기 때문이다. 매크로 값은 7.
SQL_ATTR_PARAMS_PROCESSED_PTR	(array binding 시 필요한 설정값) 오류를 포함한 매개변수 개수를 반환하는 버퍼를 가리킴. null pointer이면 아무 값도 반환되지 않을 것이다. SQLExecDirect() or SQLExecute()의 호출에 대해 SQL_SUCCESS 또는 SQL_SUCCESS_WITH_INFO이 반환되지 않는다면 버퍼의 내용은 정의되지 않는다.
SQL_ATTR_PARAMSET_SIZE	(array binding 시 필요한 설정값) 각 매개변수에 대한 값들의 개수를 명시하는 SQLUINTEGER 값
SQL_ATTR_PREFETCH_ROWS	한 번의 Fetch 연산으로 서버에서 한 번에 가져올 행의 개수를 지정한다. 이 속성을 0으로 설정하면, CLI 드라이버는 한 네트워크 패킷에 담을 수 있는 최대 크기만큼 서버로부터 데이터를 가지고 온다. 설정 가능한 값의 범위는 0에서 2147483647이다.
SQL_ATTR_ROW_ARRAY_SIZE	(SELECT 문에서 array fetch 할 때 필요한 설정값) 각 SQLFetch()을 호출 함으로서 반환되는 행들의 개수를 명시하는 SQLUINTEGER 값
SQL_ATTR_ROW_BIND_TYPE	(SELECT 문에서 array fetch 할 때 필요한 설정값) SQLFetch()가 호출될 때 사용될 바인딩 방향을 설정하는 SQLUINTEGER 값. 열 양식 바인딩은 SQL_BIND_BY_COLUMN 값을 설정 함으로서 검색된다. 행 양식 바인딩은 구조의 길이나 결과 열들이 바인드될 버퍼의 길이를 설정 함으로서 검색된다. 길이가 명시된다면, 바인드될 열에 대해 스페이스를 포함해야만 한다.
SQL_ATTR_ROW_STATUS_PTR	(SELECT 문에서 array fetch 할 때 필요한 설정값)배열의 크기는 행집합의 행의 수만큼 이다. 이 속성은 null pointer가 설정될 수 있고, 그런 경우 Altibase CLI 드라이버는 열 상태 값을 반환하지 않는다.
SQL_ATTR_ROWS_FETCHED_PTR	(SELECT 문에서 array fetch 할 때 필요한 설정값) SQLFetch()를 호출 후에 페치된 행들의 수를 반환하는 버퍼를 가리키는 SQLUINTEGER * 값
ALTIBASE_STMT_ATTR_ATOMIC_ARRAY	Altibase의 전용 속성으로, Atomic Array Insert를 수행한다. 일반적인 Array Insert가 구문들을 각각 처리하는 것과 비교해 Atomic Array Insert는 1개의 구문으로 여러 개의 구문을 처리한다. Attribute에 ALTIBASE_STMT_ATTR_ATOMIC_ARRAY를 설정하고 인자 param에 SQL_TRUE 또는 SQL_FALSE를 설정한다. SQL_TRUE를 설정하면 Atomic Array Insert를 실행한다. 그러나 Atomic Array Insert가 기존의 Array Insert보다 빠른 성능을 발휘하기 위해선 Array Size(SQL_ATTR_PARAMSET_SIZE) 를 지정한다. 또한 다음의 속성들과 함께 사용해 결괏값을 저장할 수 있다. - SQL_ATTR_PARAM_STATUS_PRT : 1번째 로우 자리에만 실제 결괏값이 저장되고 나머지는 모두 성공으로 처리된다. - SQL_ATTR_PARAMS_PROCESSED_PTR : 1번째 로우 자리에만 실제 결괏값 저장되고 나머지는 정의되지 않는다.
SQL_ATTR_FETCH_BOOKMARK_PTR	바이너리 북마크 값을 담고 있는 버퍼를 가리키는 포인터. SQL_FETCH_BOOKMARK로 SQLFetchScroll을 호출하면, 드라이버는 이 속성으로 설정한 북마크 값을 사용해서 행을 스크롤한다. 이 속성의 기본값은 null 포인터이다. 이 속성으로 설정한 북마크 값은 SQLBulkOperations가 북마크로 삭제, 갱신, 또는 fetch할 때 사용되지는 않는다. SQLBulkOperations은 행집합 버퍼에 캐시된 북마크를 사용한다.
SQL_ATTR_ROW_OPERATION_PTR	SQLSetPos를 이용한 벌크 작업 중에 어떤 행을 작업할 것인지 무시할 것인지를 지정하기 위한 SQLUSMALLINT 값들의 배열을 가리키는 포인터. - SQL_ROW_IGNORE: 벌크 작업에서 제외할 행 - SQL_ROW_PROCEED: 벌크 작업에 포함할 행. SQLBulkOperations 수행 중에는 이 배열의 값이 적용되지 않는다.
SQL_ATTR_USE_BOOKMARKS	북마크 사용 여부를 설정하는 SQLULEN 값. - SQL_UB_OFF: 기본값 - SQL_UB_ON 또는 SQL_UB_FIXED: 고정 길이(4bytes) 북마크 사용 - SQL_UB_VARIABLE: 가변 길이 북마크 사용
SQL_ATTR_CURSOR_HOLD	열린 커서에서 트랜잭션 완료 효과를 제어하는 SQLULEN 값. - SQL_CURSOR_HOLD_ON: 트랜잭션 커밋 시 커서가 닫히지 않는다. - SQL_CURSOR_HOLD_OFF: 트랜잭션 커밋 시 커서가 닫힌다.(기본값)
ALTIBASE_PREFETCH_ASYNC	비동기적으로 prefetch를 수행하여 fetch 성능을 향상시킨다. TCP, SSL 접속에서만 사용할 수 있다. - ALTIBASE_PREFETCH_ASYNC_OFF: 동기적으로 prefetch를 수행한다.(기본값) - ALTIBASE_PREFETCH_ASYNC_PREFERRED: 비동기적으로 prefetch를 수행한다. 명령문마다 비동기 prefetch 하도록 설정할 수 있지만 접속 당 하나의 명령문만 prefetch가 비동기적으로 수행된다.
ALTIBASE_PREFETCH_AUTO_TUNING	비동기적으로 prefetch를 수행할 경우, 네트워크 상태에 따라 auto-tuning 할 것인지 여부를 지정한다. Auto-tuning이란 네트워크 상태에 따라 prefetch row 개수를 자동으로 조절해주는 기능이다. 이 기능은 리눅스에서만 사용할 수 있다. - ALTIBASE_PREFETCH_AUTO_TUNING_OFF: auto-tuning 기능을 사용하지 않는다. (리눅스 이외의 OS에서 기본값) - ALTIBASE_PREFETCH_AUTO_TUNING_ON: auto-tuning 기능을 사용한다. (리눅스에서 기본값)
ALTIBASE_PREPARE_WITH_DESCRIBEPARAM	Prepare시 매개변수(parameter) 정보를 같이 요청해서 네트워크 I/O 비용을 줄이기 위한 속성이다. 매개변수 정보가 필요한 경우 사용하면 성능을 향상시킬 수 있다. - ALTIBASE_PREPARE_WITH_DESCRIBEPARAM_OFF: Prepare시 매개변수 정보를 요청하지 않는다.(기본값) - ALTIBASE_PREPARE_WITH_DESCRIBEPARAM_ON: Prepare시 매개변수 정보를 같이 요청한다.

진 단

SQLSTATE	설명	부연설명
HY000	일반 오류
24000	올바르지 않은 커서 상태
HY010	함수 순서 오류
HY011	현재는 속성 설정 불가능
HY013	메모리 관리 오류
HYC00	지원하지 않는 속성 사용	인자 Attribute에 명시된 값이 드라이버가 지원 안 하는 값이다.
HY009	null 포인터의 유효하지 않은 사용
HY017	자동으로 할당되는 descriptor 핸들의 유효하지 않은 사용
01S02	미지원 옵션 값 사용
HY024	유효하지 않은 속성 값	명시한 Attribute에 대해 유효하지 않은 값이 지정되었다.
HY024	유효하지 않은 배열 크기

예 제

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

SQLSetStmtAttr(stmt, SQL_ATTR_PARAM_BIND_TYPE, (void*)sizeof(demo_ex4_data), 0);
SQLSetStmtAttr(stmt, SQL_ATTR_PARAMSET_SIZE, (void*)10, 0);
SQLSetStmtAttr(stmt, SQL_ATTR_PARAMS_PROCESSED_PTR,(void*) &processed_ptr, 0);
SQLSetStmtAttr(stmt, SQL_ATTR_PARAM_STATUS_PTR, (void*)status, 0);
Automic Array Insert를 사용한다.
SQLSetStmtAttr(stmt, SQL_ATTR_PARAMSET_SIZE, (SQLPOINTER) array_size, 0); // Array Size를 지정한다.
SQLSetStmtAttr(stmt, ALTIBASE_STMT_ATTR_ATOMIC_ARRAY, (SQLPOINTER) SQL_TRUE, 0); // Atomic 속성을 지정한다.
아래는 커서 타입을 지정하는 예제 코드이다.
...
SQLAllocStmt(sDbc, &sStmt);
SQLSetStmtAttr(sStmt, SQL_ATTR_CURSOR_TYPE, (SQLPOINTER) SQL_CURSOR_KEYSET_DRIVEN, NULL);
SQLSetStmtAttr(sStmt, SQL_ATTR_ROW_STATUS_PTR, (SQLPOINTER) sRowStatus, NULL);

/* ... */

SQLExecDirect(sStmt, (SQLCHAR *)"SELECT t1.* FROM t1", SQL_NTS);
while (1)
{
    sRC = SQLFetch(sStmt);
    if (! SQL_SUCCEEDED(sRC))
    {
    break;
    }
    if (sRowStatus == SQL_ROW_DELETED)
    {
    /* hole */
    }
    else
    {
    /* todo */
    }
}
...