SQLBulkOperations

SQLBulkOperations#

대량의 데이터를 삽입하거나, 북마크로 지정한 열을 갱신, 삭제, 또는 페치(fetch)한다.

구 문#

SQLRETURN  SQLBulkOperations (
    SQLHSTMT        stmt,
    SQLUSMALLINT    operation);

인 자#

자료유형	인자	사용	설명
SQLHSTMT	stmt	입력	명령문 핸들
SQLUSMALLINT	operation	입력	수행할 작업. 다음 중 하나의 작업을 수행할 수 있다: SQL_ADD SQL_UPDATE_BY_BOOKMARK SQL_DELETE_BY_BOOKMARK SQL_FETCH_BY_BOOKMARK

결괏값#

SQL_SUCCESS
SQL_SUCCESS_WITH_INFO
SQL_NEED_DATA
SQL_STILL_EXECUTING
SQL_INVALID_HANDLE
SQL_ERROR

설 명#

이 함수를 사용해서 아래와 같은 작업을 할 수 있다.

옵션	동작	필요한 커서 타입
SQL_ADD	새 데이터 삽입	UPDATABLE
SQL_UPDATE_BY_BOOKMARK	북마크로 지정한 열을 갱신	UPDATABLE, SCROLLABLE, USE_BOOKMARK
SQL_DELETE_BY_BOOKMARK	북마크로 지정한 열을 삭제	UPDATABLE, SCROLLABLE, USE_BOOKMARK
SQL_FETCH_BY_BOOKMARK	북마크로 지정한 열을 페치	UPDATABLE, SCROLLABLE, USE_BOOKMARK

북마크로 지정한 열에 대해서 UPDATE, DELETE, 또는 FETCH 명령을 수행하려면, 이 함수를 호출하기 전에 먼저 북마크를 지정해야 한다. 또한 커서 타입에 따라서 가능한 수행 옵션이 다르므로, 적절한 커서로 열어야 한다.

SQLBulkOperations이 호출된 후에는 커서 위치가 결정되지 않는다. 그러므로 SQL_FETCH_FIRST, SQL_FETCH_LAST, SQL_FETCH_ABSOLUTE 또는 SQL_FETCH_BOOKMARK 옵션으로 SQLFetchScroll을 호출해서 커서 위치를 설정해야 한다. 그러나 SQL_FETCH_PRIOR, SQL_FETCH_NEXT 또는 SQL_FETCH_RELATIVE 옵션으로는 SQLFetch나 SQLFetchScroll을 호출해도 커서 위치가 결정되지 않는다.

만약 이 함수를 호출하여 수행되는 벌크 작업에서 특정 칼럼을 무시하고 싶다면, SQLBindCol의 칼럼 length/indicator 인자에 SQL_COLUMN_IGNORE를 입력한다. 단, 이 방법은 SQL_DELETE_BY_BOOKMARK 벌크 작업에는 적용되지 않는다.

이 함수로 벌크 작업을 수행할 때 행은 무시될 수 없다. 따라서 애플리케이션에서 SQLBulkOperations을 호출할 때 SQL_ATTR_ROW_OPERATION_PTR 명령문 속성을 설정할 필요가 없다.

벌크 작업을 수행한 결과는 SQL_ATTR_ROW_STATUS_PTR 명령문 속성으로 설정한 배열에 반환된다. 각 행의 상태는 수행 옵션에 따라 SQL_ROW_ADDED, SQL_ROW_DELETED 또는 SQL_ROW_UPDATED로 표시되며, 만약 에러가 발생했다면 SQL_ROW_ERROR가 반환된다.

SQL_FETCH_BY_BOOKMARK 옵션으로 벌크 작업을 수행했을 때, 드라이버가 HOLE(처음 SELECT시에는 존재했으나, bulk fetch로 가져올 때 없는 행을 HOLE이라고 표현)을 발견하면 행의 상태 값으로 SQL_ROW_DELETED를 반환한다. 또한 SENSITIVE 유형의 커서에 SQL_FETCH_BY_BOOKMARK 옵션으로 이 함수를 수행하면 데이터베이스에서 최신 데이터를 가져오고, SENSITIVE 커서가 아닌 경우에는 캐시에서 기존 데이터를 가져온다.

Bulk Insert#

SQLBulkOperations을 이용해서 데이터를 삽입하려면, 아래 순서대로 프로그램을 작성하라:

결과 집합을 반환하는 SELECT 쿼리를 실행하라.
SQL_ATTR_ROW_ARRAY_SIZE 명령문 속성에 삽입하고자 하는 행의 개수를 설정하라.
SQLBindCol을 호출해서 삽입할 데이터를 바인딩하라.
- 바인딩할 데이터는 SQL_ATTR_ROW_ARRAY_SIZE 값과 같은 크기의 배열이어야 한다.
- SQL_ATTR_ROW_STATUS_PTR 명령문 속성에 설정된 배열의 크기는 SQL_ATTR_ROW_ARRAY_SIZE 보다 같거나 커야 한다.
SQLBulkOperations(stmt, SQL_ADD)를 호출하라.
- SQL_ATTR_ROW_STATUS_PTR 명령문 속성에 상태 배열을 설정했다면, 이를 통해 각 행의 수행 결과(SQL_ROW_ADDED인지 여부)를 확인할 수 있다.

벌크 삽입을 위해 SELECT 쿼리를 수행할 때, 단일 테이블에서 순수 칼럼만 조회하는 단순 쿼리문을 사용할 것을 권장한다. 만약 SELECT 리스트에 한 칼럼이 여러 번 오거나 수식이 포함된 경우에는 벌크 삽입이 올바르게 동작하지 않을 수 있다.

북마크를 이용한 Bulk Update#

SQLBulkOperations와 북마크를 이용해서 벌크 업데이트를 수행하려면, 아래 순서대로 프로그램을 작성하라:

SQL_ATTR_USE_BOOKMARKS 명령문 속성을 SQL_UB_VARIABLE로 설정하라.
결과 집합을 반환하는 SELECT 쿼리를 실행하라.
SQL_ATTR_ROW_ARRAY_SIZE 명령문 속성에 갱신하고자 하는 행의 개수를 설정하라.
SQLBindCol을 호출해서 갱신할 데이터를 바인딩하라.
- 바인딩할 데이터는 SQL_ATTR_ROW_ARRAY_SIZE 값과 같은 크기의 배열이어야 한다.
- 갱신할 행의 북마크 값을 넣을 배열을 북마크 칼럼인 0번째 칼럼에 바인딩하라.
데이터를 설정하라.
- 갱신할 행들의 북마크를 0번째 칼럼에 바인딩한 배열에 복사하라.
- 바인딩한 버퍼의 데이터를 갱신할 값으로 변경하라.
SQLBulkOperations(stmt, SQL_UPDATE_BY_BOOKMARK)를 호출하라.
- SQL_ATTR_ROW_STATUS_PTR 명령문 속성에 상태 배열을 설정했다면, 이를 통해 각 행의 수행 결과(SQL_ROW_UPDATED인지 여부)를 확인할 수 있다.

벌크 업데이트를 위해 SELECT 쿼리를 수행할 때, 단일 테이블에서 순수 칼럼만 조회하는 단순 쿼리문을 사용할 것을 권장한다. 만약 SELECT 리스트에 한 칼럼이 여러 번 오거나 수식이 포함된 경우에는 벌크 업데이트가 올바르게 동작하지 않을 수 있다.

0번째 칼럼에 설정하는 북마크 값들이 중복되지 않도록 한다. 중복될 경우 벌크 업데이트가 올바르게 동작하지 않을 수 있다.

북마크를 이용한 Bulk Fetch#

SQLBulkOperations와 북마크를 이용해서 벌크 페치(fetch)를 수행하려면, 아래 순서대로 프로그램을 작성하라:

SQL_ATTR_USE_BOOKMARKS 명령문 속성을 SQL_UB_VARIABLE로 설정하라.
결과 집합을 반환하는 SELECT 쿼리를 실행하라.
SQL_ATTR_ROW_ARRAY_SIZE 명령문 속성에 fetch하고자 하는 행의 개수를 설정하라.
SQLBindCol을 이용해 가져올 데이터를 바인딩하라.
- 바인딩할 데이터는 SQL_ATTR_ROW_ARRAY_SIZE 값과 같은 크기의 배열이어야 한다.
- 가져올 행의 북마크를 넣을 배열을 북마크 칼럼인 0번째 칼럼에 바인딩하라.
가져올 행의 북마크를 0번째 칼럼에 바인딩한 배열 버퍼에 복사하라.
SQLBulkOperations(stmt, SQL_FETCH_BY_BOOKMARK)를 호출하라.
- SQL_ATTR_ROW_STATUS_PTR 명령문 속성에 상태 배열을 설정했다면, 이를 통해 각 행의 수행 결과(SQL_ROW_SUCCESS 또는 SQL_ROW_DELETED인지)를 확인할 수 있다.

만약 커서를 SENSITIVE로 열었다면 드라이버가 HOLE(처음 SELECT시에는 존재했으나, bulk fetch로 가져올 때 없는 행을 hole이라고 표현)을 감지할 수 있다. 상태 배열(SQL_ATTR_ROW_STATUS_PTR 명령문 속성으로 설정한 배열)을 설정한 경우에 드라이버가 HOLE을 발견하면, HOLE인 행에 대응하는 배열 요소에 SQL_ROW_DELETED를 반환한다. 그러나 상태 배열을 설정하지 않은 경우에 드라이버가 HOLE을 발견하면 에러를 반환한다.

북마크를 이용한 Bulk Delete#

SQLBulkOperations와 북마크를 이용해서 벌크 삭제를 수행하려면, 아래 순서대로 프로그램을 작성하라:

SQL_ATTR_USE_BOOKMARKS 명령문 속성을 SQL_UB_VARIABLE로 설정하라.
결과 집합을 반환하는 SELECT 쿼리를 실행하라.
SQL_ATTR_ROW_ARRAY_SIZE 명령문 속성에 페치하고자 하는 행의 개수를 설정하라.
SQLBindCol을 호출해서 북마크 칼럼인 0번째 칼럼을 바인딩하라.
삭제할 행의 북마크를 0번째 칼럼에 바인딩한 배열 버퍼에 복사하라.
SQLBulkOperations(stmt, SQL_DELETE_BY_BOOKMARK)를 호출하라.
- A.SQL_ATTR_ROW_STATUS_PTR 명령문 속성에 상태 배열을 설정했다면, 이를 통해 각 행의 수행 결과(SQL_ROW_DELETED 인지 여부)를 확인할 수 있다.

0번째 칼럼에 설정하는 북마크 값들이 중복되지 않도록 한다. 중복될 경우 벌크 삭제가 올바르게 동작하지 않을 수 있다.

진 단#

SQLSTATE	설명	부연설명
HY000	일반 오류
HY001	메모리 할당 오류	Altibase CLI 드라이버가 함수를 실행하고 완료하기 위해 요구된 메모리를 할당할 수 없음
08S01	통신 회선 장애 (데이터 송수신 실패)	Altibase CLI 드라이버와 DB간에 함수 처리가 완료되기 전에 통신 회선 실패
08003		stmt가 연결되지 않거나 connection이 끊어진 상태
HY010	함수 연속 오류	주어진 stmt는 이 함수를 수행할 수 없음. 비동기 방식은 미지원.
HY024	유효하지 않은 배열 크기
21S02	타입과 칼럼 개수가 칼럼 리스트와 일치하지 않음
HY111	유효하지 않은 북마크 값
02502	삭제 또는 갱신 홀 감지
24519	홀이 발견되었으나 지시자 변수가 없음
07006	데이터 타입 속성 위배	사용할 수 없는 데이터 타입 사용
HY003	프로그램에서 범위를 벗어난 데이터 타입
01S01	행에서 오류	operation이 SQL_ADD일 때, 작업 수행 중에 한 개 이상의 행에서 오류 발생
01001	커서 작업 충돌
01S07	소숫점 이하 잘림
01004	문자열 데이터 잘림
07009	유효하지 않은 디스크립터 인덱스
22003	범위를 벗어난 값
22007	올바르지 않은 DATETIME 포맷
22008	Datetime 항목 오버플로
24000	올바르지 않은 커서 상태
HY008	작업 취소

Administrator

Reference

Developer

Tools

External Tools

SQLBulkOperations