준수
도입 버전: ODBC 3.0 표준 준수: ODBC
Summary
SQLBulkOperations 는 북마크에 의한 업데이트, 삭제, 가져오기 등 대량 삽입과 대량 북마크 작업을 수행합니다.
Syntax
SQLRETURN SQLBulkOperations(
SQLHSTMT StatementHandle,
SQLUSMALLINT Operation);
Arguments
StatementHandle
[입력] 문 핸들입니다.
Operation
[입력] 수행 작업:
SQL_ADD SQL_UPDATE_BY_BOOKMARK SQL_DELETE_BY_BOOKMARK SQL_FETCH_BY_BOOKMARK
자세한 내용은 "설명"을 참조하세요.
Returns
SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_NEED_DATA, SQL_STILL_EXECUTING, SQL_ERROR, 또는 SQL_INVALID_HANDLE.
진단
SQLBulkOperations가 SQL_ERROR 또는 SQL_SUCCESS_WITH_INFO를 반환하면, HandleType을 SQL_HANDLE_STMT, Handle을 StatementHandle으로 사용하여 SQLGetDiagRec을 호출하여 관련 SQLSTATE 값을 얻을 수 있습니다. 다음 표는 SQLBulkOperations 가 일반적으로 반환하는 SQLSTATE 값을 나열하며, 각 값이 이 함수의 맥락에서 설명됩니다; 드라이버 매니저가 반환하는 SQLSTATE 설명 앞에 "(DM)"이라는 표기가 붙습니다. 달리 명시되지 않는 한 각 SQLSTATE 값과 연결된 반환 코드는 SQL_ERROR.
SQL_SUCCESS_WITH_INFO 또는 SQL_ERROR를 반환할 수 있는 모든 SQLSTATE(01xxx SQLSTATE를 제외하고)에 대해, 다중 행 연산의 하나 이상의 행에서 오류가 발생하면 SQL_SUCCESS_WITH_INFO가 반환되고, 단일 행 연산에서 오류가 발생하면 SQL_ERROR가 반환됩니다.
| SQLSTATE | 오류 | Description |
|---|---|---|
| 01000 | 일반 경고 | 드라이버 관련 정보 메시지입니다. 함수는 SQL_SUCCESS_WITH_INFO 반환합니다. |
| 01004 | 문자열 데이터 오른쪽 절단 | Operation 인자가 SQL_FETCH_BY_BOOKMARK되었고, SQL_C_CHAR 또는 SQL_C_BINARY 데이터 타입을 가진 열들에 대해 문자열 또는 이진 데이터를 반환하면 빈칸이 아닌 문자나 NULL이 아닌 이진 데이터가 절단되었습니다. |
| 01S01 | 오류 발생 |
Operation 인자가 SQL_ADD되었고, 연산 수행 중 하나 이상의 행에서 오류가 발생했지만 적어도 한 행은 성공적으로 추가되었습니다. 함수는 SQL_SUCCESS_WITH_INFO 반환합니다. (이 오류는 애플리케이션이 ODBC 2를 사용할 때만 발생합니다. x 드라이버.) |
| 01S07 | 분수 잘림 |
Operation 인수가 SQL_FETCH_BY_BOOKMARK되었고, 애플리케이션 버퍼의 데이터 타입이 SQL_C_CHAR 또는 SQL_C_BINARY 아니었으며, 하나 이상의 열에 대해 애플리케이션 버퍼로 반환된 데이터는 잘려 나갔습니다. (수치 C 데이터 유형에서는 소수 부분이 잘려 나갔습니다. 시간, 타임스탬프, 구간 C 데이터 타입 중 시간 성분이 포함된 경우, 시간의 분수 부분이 잘렸습니다.) 함수는 SQL_SUCCESS_WITH_INFO 반환합니다. |
| 07006 | 제한된 데이터 형식 특성 위반 |
Operation 인자가 SQL_FETCH_BY_BOOKMARK되었고, 결과 집합의 열의 데이터 값은 SQLBindCol 호출 시 TargetType 인자로 지정된 데이터 타입으로 변환할 수 없었습니다. Operation 인자는 SQL_UPDATE_BY_BOOKMARK 또는 SQL_ADD이었고, 애플리케이션 버퍼의 데이터 값은 결과 집합의 열의 데이터 타입으로 변환할 수 없었다. |
| 07009 | 잘못된 디스크립터 인덱스 | 인수 Operation SQL_ADD 있었고, 열 번호가 결과 집합의 열 수보다 큰 것으로 묶여 있었습니다. |
| 21S02 | 파생 테이블의 정도가 열 목록과 일치하지 않음 | 조작 주장은 SQL_UPDATE_BY_BOOKMARK; 그리고 모든 열이 언바인딩이거나 읽기 전용이거나, 구속된 길이/지시기 버퍼의 값이 SQL_COLUMN_IGNORE되어 있어 열은 업데이트가 불가능했습니다. |
| 22001 | 문자열 데이터 오른쪽 절단 | 결과 집합의 열에 문자나 이진 값을 할당하면 빈칸이 아닌 문자(이진수)나 빈 문자나 바이트가 잘려 나갔습니다. |
| 22003 | 숫자 값이 범위를 벗어났습니다. |
연산 인자는 SQL_ADD 또는 SQL_UPDATE_BY_BOOKMARK이었으며, 결과 집합의 열에 숫자 값을 할당하면 전체 부분(소수가 아닌) 부분이 잘려나갔습니다. 인자 Operation SQL_FETCH_BY_BOOKMARK 있었으며, 하나 이상의 묶인 열에 대해 숫자 값을 반환하면 유효한 숫자가 손실되었습니다. |
| 22007 | 날짜/시간 형식이 잘못되었습니다. |
Operation 인자는 SQL_ADD 또는 SQL_UPDATE_BY_BOOKMARK이었으며, 결과 집합의 열에 날짜나 타임스탬프 값을 할당하면 연도, 월, 일 필드가 범위 밖이 되었습니다. 인수 Operation SQL_FETCH_BY_BOOKMARK 있었으며, 하나 이상의 바인딩 열에 대해 날짜나 타임스탬프 값을 반환하면 연도, 월, 일 필드가 범위 밖이 되었습니다. |
| 22008 | 날짜/시간 필드 오버플로우 |
Operation 인항은 SQL_ADD 또는 SQL_UPDATE_BY_BOOKMARK이었으며, 데이터 전송 시 날짜 산술을 수행하면, 결과의 datetime 필드(연도, 월, 일, 시, 분, 초 필드)가 허용 범위 밖에 있거나 그레고리력의 자연스러운 날짜 규칙에 따라 유효하지 않게 되었습니다. Operation 논자가 SQL_FETCH_BY_BOOKMARK되었고, 결과 집합에서 데이터를 가져오는 데이터에 대해 datetime 산술을 수행하면, 결과의 datetime 필드(연, 월, 일, 시, 분, 또는 초 필드)가 해당 필드의 허용 범위 밖에 있거나 그레고리력의 자연 규칙에 따라 유효하지 않게 되었습니다. |
| 22015 | 간격 필드 오버플로 |
Operation 인자는 SQL_ADD 또는 SQL_UPDATE_BY_BOOKMARK이었고, 정확한 숫자 또는 구간 C 타입을 구간 SQL 데이터 타입에 할당하면 유수 자리가 손실되었습니다. 작전 주장은 SQL_ADD 혹은 SQL_UPDATE_BY_BOOKMARK였다; 구간 SQL 타입에 할당할 때, 그 구간 SQL 타입에 C 타입의 값을 표현하지 않았습니다. Operation 인자가 SQL_FETCH_BY_BOOKMARK되었고, 정확한 숫자 또는 구간 SQL 타입에서 구간 C 타입으로 할당하면 선두 필드에서 유의미한 숫자가 손실되었습니다. 작전 주장은 SQL_FETCH_BY_BOOKMARK되었다; 구간 C 타입에 할당할 때, 구간 C 타입 내 SQL 타입 값을 표현하지 않았습니다. |
| 22018 | 캐스트 사양에 잘못된 문자 값 |
작전 주장은 SQL_FETCH_BY_BOOKMARK되었다; C 유형은 정확한 수치, 날짜 시간, 또는 구간 데이터 유형이었으며; 열의 SQL 유형은 문자 데이터 유형이었고; 그리고 열의 값은 바운드 C 타입의 유효한 리터럴이 아니었습니다. 조작 논증은 SQL_ADD 또는 SQL_UPDATE_BY_BOOKMARK였다; SQL 타입은 정확한 수치, 날짜 또는 구간 데이터 타입이었으며; C형은 SQL_C_CHAR; 그리고 열의 값이 바인드 SQL 타입의 유효한 리터럴이 아니었습니다. |
| 23000 | 무결성 제약 조건 위반 |
연산 인자는 SQL_ADD, SQL_DELETE_BY_BOOKMARK, 또는 SQL_UPDATE_BY_BOOKMARK 있었으며, 무결성 제약 조건이 위반되었습니다. Operation 인자가 SQL_ADD되었고, 묶이지 않은 열은 NOT NULL로 정의되며 기본값이 없습니다. Operation 인자는 SQL_ADD되었고, StrLen_or_IndPtr 묶인 버퍼에 지정된 길이는 SQL_COLUMN_IGNORE되었으며, 열에는 기본값이 없었습니다. |
| 24000 | 커서 상태가 잘못되었습니다. | StatementHandle은 실행 상태였지만, StatementHandle과 연관된 결과 세트는 없었습니다. |
| 40001 | Serialization 실패 | 다른 트랜잭션과의 리소스 교착 상태 때문에 트랜잭션이 롤백되었습니다. |
| 40003 | 문 완성을 알 수 없음 | 이 함수를 실행하는 동안 연결된 연결이 실패했으며 트랜잭션 상태를 확인할 수 없습니다. |
| 42000 | 구문 오류 또는 액세스 위반 | 드라이버는 Operation 인자에서 요청된 연산을 수행하는 데 필요한 행을 잠글 수 없었습니다. |
| 44000 | WITH CHECK OPTION 위반 | Operation 인자는 SQL_ADD 또는 SQL_UPDATE_BY_BOOKMARK 있었으며, 삽입 또는 업데이트는 WITH CHECK OPTION을 지정하여 생성된 뷰 테이블(또는 뷰링 테이블에서 파생된 테이블)에서 수행되었습니다. 이 경우 삽입 또는 업데이트로 인해 영향을 받는 하나 이상의 행이 뷰 테이블에 더 이상 존재하지 않습니다. |
| HY000 | 일반 오류 | 특정 SQLSTATE가 없고 구현별 SQLSTATE가 정의되지 않은 오류가 발생했습니다. *MessageText 버퍼의 SQLGetDiagRec에서 반환된 오류 메시지는 오류와 그 원인을 설명합니다. |
| HY001 | 메모리 할당 오류 | 드라이버가 함수 실행 또는 완료를 지원하는 데 필요한 메모리를 할당할 수 없습니다. |
| HY008 | 작업이 취소됨 | StatementHandle에 대해 비동기 처리를 사용하도록 설정했습니다. 함수가 호출되었고 실행이 완료되기 전에 StatementHandle에서 SQLCancel 또는 SQLCancelHandle이 호출되었습니다. 그런 다음 StatementHandle에서 함수가 다시 호출되었습니다. 함수가 호출되었고 실행을 완료하기 전에 다중 스레드 애플리케이션의 다른 스레드에서 StatementHandle에서 SQLCancel 또는 SQLCancelHandle이 호출되었습니다. |
| HY010 | 함수 시퀀스 오류 | (DM) StatementHandle과 연결된 연결 핸들에 대해 비동기적으로 실행되는 함수가 호출되었습니다. 이 비동기 함수는 SQLBulkOperations 함수가 호출될 때까지 여전히 실행 중이었습니다. (DM) SQLExecute, SQLExecDirect 또는 SQLMoreResults가 StatementHandle에 대해 호출되고 SQL_PARAM_DATA_AVAILABLE 반환되었습니다. 이 함수는 모든 스트리밍된 매개 변수에 대해 데이터를 검색하기 전에 호출되었습니다. (DM) 지정된 StatementHandle 이 실행 상태가 아니었습니다. 이 함수는 먼저 SQLExecDirect, SQLExecute, 또는 카탈로그 함수를 호출하지 않고 호출되었습니다. (DM) 이 함수가 아닌 비동기 실행 함수가 StatementHandle에 대해 호출되었고 이 함수가 호출되었을 때 계속 실행되고 있었습니다. (DM) SQLExecute, SQLExecDirect, 또는 SQLSetPos가StatementHandle 을 호출받았고 반환SQL_NEED_DATA. 이 함수는 모든 실행 시 데이터 매개 변수 또는 열에 대한 데이터를 보내기 전에 호출되었습니다. (DM) 운전자는 ODBC 2였다. x 드라이버를 호출하고, SQLBulkOperations가 SQLFetchScroll이나 SQLFetch가 호출되기 전에 StatementHandle을 호출했습니다. (DM) SQLBulkOperations는 StatementHandle에서 SQLExtendedFetch가 호출된 후에 호출되었습니다. |
| HY011 | 지금은 특성을 설정할 수 없습니다. | (DM) 운전자는 ODBC 2였다. x 드라이버를 사용하며, SQL_ATTR_ROW_STATUS_PTR 문장 속성은 SQLFetch 또는 SQLFetchScroll 과 SQLBulkOperations 호출 사이에 설정되었습니다. |
| HY013 | 메모리 관리 오류 | 메모리 조건이 낮기 때문에 기본 메모리 개체에 액세스할 수 없기 때문에 함수 호출을 처리할 수 없습니다. |
| HY090 | 잘못된 문자열 또는 버퍼 길이 |
작전 주장은 SQL_ADD 혹은 SQL_UPDATE_BY_BOOKMARK였다; 데이터 값은 널 포인터가 아니었고; C 데이터 타입은 SQL_C_BINARY 또는 SQL_C_CHAR였으며; 열 길이 값은 0보다 작았으나, SQL_DATA_AT_EXEC, SQL_COLUMN_IGNORE, SQL_NTS, SQL_NULL_DATA 또는 SQL_LEN_DATA_AT_EXEC_OFFSET보다 작지 않았다. 길이/지시 버퍼의 값은 SQL_DATA_AT_EXEC였으며; SQL 유형은 SQL_LONGVARCHAR, SQL_LONGVARBINARY, 또는 긴 데이터 소스별 데이터 타입이었으며; SQLGetInfo 의 SQL_NEED_LONG_DATA_LEN 정보 유형은 "Y"였습니다. Operation 인자는 SQL_ADD되었고, SQL_ATTR_USE_BOOKMARK 문장 속성은 SQL_UB_VARIABLE로 설정되었으며, 열 0은 이 결과 세트의 북마크 최대 길이와 같지 않은 버퍼에 묶여 있었습니다. (이 길이는 IRD의 SQL_DESC_OCTET_LENGTH 필드에서 확인할 수 있으며, SQLDescribeCol, SQLColAttribute, 또는 SQLGetDescField를 호출하면 얻을 수 있습니다.) |
| HY092 | 유효하지 않은 속성 식별자 | (DM) Operation 인자에 지정된 값이 유효하지 않았다. Operation 인자는 SQL_ADD, SQL_UPDATE_BY_BOOKMARK, 또는 SQL_DELETE_BY_BOOKMARK이었고, SQL_ATTR_CONCURRENCY 문장 속성은 SQL_CONCUR_READ_ONLY로 설정되었습니다. Operation 인자는 SQL_DELETE_BY_BOOKMARK, SQL_FETCH_BY_BOOKMARK, 또는 SQL_UPDATE_BY_BOOKMARK이었고, 북마크 열은 바인딩되어 있지 않았고 SQL_ATTR_USE_BOOKMARKS 문장 속성은 SQL_UB_OFF로 설정되어 있지 않았습니다. |
| HY117 | 알 수 없는 트랜잭션 상태로 인해 연결이 일시 중단됩니다. 연결 끊기 및 읽기 전용 함수만 허용됩니다. | (DM) 일시 중단 상태에 대한 자세한 내용은 SQLEndTran 함수를 참조 하세요. |
| HYC00 | 선택적 기능이 구현되지 않음 | 드라이버나 데이터 소스는 Operation 인자에서 요청된 연산을 지원하지 않습니다. |
| HYT00 | 시간 제한 만료됨 | 데이터 원본이 결과 집합을 반환하기 전에 쿼리 제한 시간이 만료되었습니다. 타임아웃 기간은 SQLSetStmtAttr 를 통해 속성 인자 로 설정되며, SQL_ATTR_QUERY_TIMEOUT입니다. |
| HYT01 | 연결 제한 시간이 만료됨 | 데이터 원본이 요청에 응답하기 전에 연결 제한 시간이 만료되었습니다. 연결 제한 시간은 SQL_ATTR_CONNECTION_TIMEOUT SQLSetConnectAttr를 통해 설정됩니다. |
| IM001 | 드라이버는 이 함수를 지원하지 않습니다. | (DM) StatementHandle과 연결된 드라이버는 함수를 지원하지 않습니다. |
| IM017 | 비동기 알림 모드에서 폴링을 사용할 수 없습니다. | 알림 모델을 사용할 때마다 폴링이 비활성화됩니다. |
| IM018 | 이 핸들에서 이전 비동기 작업을 완료하기 위해 SQLCompleteAsync 가 호출되지 않았습니다. | 핸들의 이전 함수 호출이 SQL_STILL_EXECUTING 반환하고 알림 모드가 활성화된 경우 사후 처리를 수행하고 작업을 완료하려면 핸들에서 SQLCompleteAsync 를 호출해야 합니다. |
코멘트
Caution
어떤 문장 상태를 SQLBulkOperations 를 호출할 수 있는지, 그리고 ODBC 2와의 호환성을 위해 무엇을 해야 하는지에 대한 정보를 참고하세요. x 개의 애플리케이션은 부록 G: 하위 호환성을 위한 드라이버 지침의 블록 커서, 스크롤 가능한 커서, 하위 호환성 섹션을 참조하세요.
애플리케이션은 현재 쿼리에 대응하는 기본 테이블이나 뷰에 대해 다음과 같은 연산을 수행하기 위해 SQLBulkOperations 를 사용합니다:
새 행을 추가합니다.
각 행이 북마크로 식별되는 행 집합을 업데이트합니다.
각 행이 북마크로 식별되는 행 집합을 삭제하세요.
각 행이 책갈피로 식별되는 행 집합을 가져옵니다.
SQLBulkOperations를 호출한 후에는 블록 커서 위치가 정의되지 않습니다. 애플리케이션은 커서 위치를 설정하기 위해 SQLFetchScroll 을 호출해야 합니다. 애플리케이션은 SQL_FETCH_FIRST, SQL_FETCH_LAST, SQL_FETCH_ABSOLUTE, 또는 SQL_FETCH_BOOKMARK의 FetchOrientation 인자를 사용해야만 SQLFetchScroll을 호출해야 합니다. 애플리케이션이 SQL_FETCH_PRIOR, SQL_FETCH_NEXT, 또는 SQL_FETCH_RELATIVE의 FetchOrientation 인자로 SQLFetch 또는 SQLFetchScroll을 호출하면 커서 위치는 정의되지 않습니다.
SQLBindCol 호출에서 지정된 열의 길이/표시 버퍼를 SQL_COLUMN_IGNORE로 설정하여 SQLBulkOperations 호출을 수행할 때 컬럼을 무시할 수 있습니다.
애플리케이션이 SQLBulkOperations 를 호출할 때 SQL_ATTR_ROW_OPERATION_PTR 문장 속성을 설정할 필요가 없습니다. 이 함수로 대량 연산을 수행할 때 행을 무시할 수 없기 때문입니다.
SQL_ATTR_ROWS_FETCHED_PTR 문장 속성이 가리키는 버퍼는 SQLBulkOperations 호출에 영향을 받는 행 수를 포함합니다.
Operation 인자가 SQL_ADD 또는 SQL_UPDATE_BY_BOOKMARK 되고 커서와 연관된 쿼리 명세의 select-list에 동일한 열에 대한 참조가 여러 개 있을 경우, 오류가 발생하는지 드라이버가 중복된 참조를 무시하고 요청된 연산을 수행하는지 여부를 드라이버가 정의합니다.
SQLBulkOperations 사용법에 대한 자세한 내용은 SQLBulkOperations로 데이터 업데이트(Update Data with SQLBulkOperations)를 참조하세요.
대량 인서트 수행
SQLBulkOperations로 데이터를 삽입하기 위해 애플리케이션은 다음과 같은 단계들을 수행합니다:
결과 집합을 반환하는 쿼리를 실행합니다.
SQL_ATTR_ROW_ARRAY_SIZE 문장 속성을 삽입하려는 행 수로 설정합니다.
삽입하려는 데이터를 SQLBindCol 로 바인딩합니다. 데이터는 SQL_ATTR_ROW_ARRAY_SIZE 값과 같은 크기의 배열에 바인딩됩니다.
Note
SQL_ATTR_ROW_STATUS_PTR 문장 속성이 가리키는 배열의 크기는 SQL_ATTR_ROW_ARRAY_SIZE와 같거나 null 포인터SQL_ATTR_ROW_STATUS_PTR 되어야 합니다.
SQLBulkOperations(StatementHandle, SQL_ADD)를 호출하여 삽입을 수행합니다.
애플리케이션이 SQL_ATTR_ROW_STATUS_PTR 문장 속성을 설정했다면, 이 배열을 검사하여 연산 결과를 확인할 수 있습니다.
애플리케이션이 SQLBulkOperations 를 호출하기 전에 0열을 SQL_ADD 인수 로 바인딩하면, 드라이버는 새로 삽입된 행의 북마크 값으로 바인딩된 0열 버퍼를 업데이트합니다. 이를 위해서는 애플리케이션이 SQL_ATTR_USE_BOOKMARKS 문장 속성을 SQL_UB_VARIABLE로 설정한 후 문장을 실행해야 합니다. (이 방법은 ODBC 2에서는 작동하지 않습니다. x 드라이버.)
긴 데이터는 SQLBulkOperations를 통해 SQLParamData와 SQLPutData에 호출하여 부분적으로 추가할 수 있습니다. 자세한 내용은 이 함수 참고문헌의 "Providing Long Data for Bulk Inserts and Updates"를 참조하세요.
애플리케이션이 SQLBulkOperations를 호출하기 전에 반드시 SQLFetch 또는 SQLFetchScroll을 호출할 필요는 없습니다(ODBC 2를 상대로 할 때를 제외하고).x 드라이버; 하위 호환성 및 표준 준수 항목을 참조하세요.
이 동작은 드라이버 정의로 정의된 동작입니다. SQLBulkOperations가 SQL_ADD Operation 인자를 가진 커서에서 중복 열이 포함된 커서에서 호출될 때입니다. 드라이버는 드라이버 정의 SQLSTATE를 반환하거나, 결과 집합에 나타나는 첫 번째 열에 데이터를 추가하거나, 기타 드라이버 정의 동작을 수행할 수 있습니다.
북마크를 이용한 대량 업데이트 수행
SQLBulkOperations의 북마크를 사용하여 대량 업데이트를 수행하려면, 애플리케이션은 다음 단계를 순서대로 수행합니다:
SQL_ATTR_USE_BOOKMARKS 문장 속성을 SQL_UB_VARIABLE로 설정합니다.
결과 집합을 반환하는 쿼리를 실행합니다.
SQL_ATTR_ROW_ARRAY_SIZE 문장 속성을 업데이트하고자 하는 행 수로 설정합니다.
업데이트하고자 하는 데이터를 SQLBindCol 로 바인딩합니다. 데이터는 SQL_ATTR_ROW_ARRAY_SIZE 값과 같은 크기의 배열에 바인딩됩니다. 또한 SQLBindCol 을 호출해 열(북마크 열)을 결합합니다.
관심 있는 행의 북마크를 0열 묶인 배열에 복사합니다.
바운드 버퍼의 데이터를 업데이트합니다.
Note
SQL_ATTR_ROW_STATUS_PTR 문장 속성이 가리키는 배열의 크기는 SQL_ATTR_ROW_ARRAY_SIZE와 같아야 하며, SQL_ATTR_ROW_STATUS_PTR null 포인터여야 합니다.
SQLBulkOperations(StatementHandle, SQL_UPDATE_BY_BOOKMARK)를 호출합니다.
Note
애플리케이션이 SQL_ATTR_ROW_STATUS_PTR 문장 속성을 설정했다면, 이 배열을 검사하여 연산 결과를 확인할 수 있습니다.
선택적으로 SQLBulkOperations(StatementHandle, SQL_FETCH_BY_BOOKMARK)를 호출하여 바인드 애플리케이션 버퍼에 데이터를 가져오어 업데이트가 발생했는지 확인합니다.
데이터가 업데이트된 경우, 드라이버는 해당 행의 행 상태 배열 값을 SQL_ROW_UPDATED으로 변경합니다.
SQLBulkOperations가 수행하는 대량 업데이트는 SQLParamData와 SQLPutData를 호출하여 긴 데이터를 포함할 수 있습니다. 자세한 내용은 이 함수 참고문헌의 "Providing Long Data for Bulk Inserts and Updates"를 참조하세요.
커서 간에 북마크가 지속된다면, 애플리케이션은 북마크로 업데이트하기 전에 SQLFetch 또는 SQLFetchScroll 을 호출할 필요가 없습니다. 이전 커서에서 저장한 북마크를 사용할 수 있습니다. 커서 간에 북마크가 지속되지 않으면, 애플리케이션은 SQLFetch 또는 SQLFetchScroll 을 호출해 북마크를 가져와야 합니다.
이 동작은 SQLBulkOperations가 SQL_UPDATE_BY_BOOKMARK 인자 인 커서에서 중복 열이 포함된 커서에서 호출될 때 드라이버 정의로 정의됩니다. 드라이버는 드라이버 정의 SQLSTATE를 반환하거나, 결과 집합에 나타나는 첫 번째 열을 업데이트하거나, 기타 드라이버 정의 동작을 수행할 수 있습니다.
북마크를 이용한 대량 가져오기 수행
SQLBulkOperations를 이용한 북마크를 이용한 대량 가져오기를 수행하려면, 애플리케이션은 다음 단계를 순서대로 수행합니다:
SQL_ATTR_USE_BOOKMARKS 문장 속성을 SQL_UB_VARIABLE로 설정합니다.
결과 집합을 반환하는 쿼리를 실행합니다.
SQL_ATTR_ROW_ARRAY_SIZE 문장 속성을 가져오고자 하는 행 수에 설정합니다.
SQLBindCol을 호출해 가져오려는 데이터를 바인딩합니다. 데이터는 SQL_ATTR_ROW_ARRAY_SIZE 값과 같은 크기의 배열에 바인딩됩니다. 또한 SQLBindCol 을 호출해 열(북마크 열)을 결합합니다.
관심 있는 행의 북마크를 0열에 묶인 배열에 복사합니다. (이는 애플리케이션이 이미 별도로 책갈피를 확보했다는 전제입니다.)
Note
SQL_ATTR_ROW_STATUS_PTR 문장 속성이 가리키는 배열의 크기는 SQL_ATTR_ROW_ARRAY_SIZE와 같아야 하며, SQL_ATTR_ROW_STATUS_PTR null 포인터여야 합니다.
SQLBulkOperations(StatementHandle, SQL_FETCH_BY_BOOKMARK)를 호출합니다.
애플리케이션이 SQL_ATTR_ROW_STATUS_PTR 문장 속성을 설정했다면, 이 배열을 검사하여 연산 결과를 확인할 수 있습니다.
커서 간에 북마크가 지속된다면, 애플리케이션은 북마크로 가져오기 전에 SQLFetch 또는 SQLFetchScroll 을 호출할 필요가 없습니다. 이전 커서에서 저장한 북마크를 사용할 수 있습니다. 만약 커서에서 북마크가 지속되지 않으면, 애플리케이션은 SQLFetch 또는 SQLFetchScroll 을 한 번 호출해 북마크를 가져와야 합니다.
북마크를 이용한 대량 삭제 수행
SQLBulkOperations를 이용한 북마크를 사용해 대량 삭제를 수행하려면, 애플리케이션은 다음 단계를 순서대로 수행합니다:
SQL_ATTR_USE_BOOKMARKS 문장 속성을 SQL_UB_VARIABLE로 설정합니다.
결과 집합을 반환하는 쿼리를 실행합니다.
SQL_ATTR_ROW_ARRAY_SIZE 문장 속성을 삭제하려는 행 수로 설정합니다.
SQLBindCol을 호출하여 열(북마크 열)을 묶습니다.
삭제하려는 행의 북마크를 0열에 묶인 배열에 복사합니다.
Note
SQL_ATTR_ROW_STATUS_PTR 문장 속성이 가리키는 배열의 크기는 SQL_ATTR_ROW_ARRAY_SIZE와 같아야 하며, SQL_ATTR_ROW_STATUS_PTR null 포인터여야 합니다.
SQLBulkOperations(StatementHandle, SQL_DELETE_BY_BOOKMARK)를 호출합니다.
애플리케이션이 SQL_ATTR_ROW_STATUS_PTR 문장 속성을 설정했다면, 이 배열을 검사하여 연산 결과를 확인할 수 있습니다.
커서 간에 북마크가 지속된다면, 애플리케이션은 북마크로 삭제하기 전에 SQLFetch나 SQLFetchScroll을 호출할 필요가 없습니다. 이전 커서에서 저장한 북마크를 사용할 수 있습니다. 만약 커서에서 북마크가 지속되지 않으면, 애플리케이션은 SQLFetch 또는 SQLFetchScroll 을 한 번 호출해 북마크를 가져와야 합니다.
대량 삽입 및 업데이트를 위한 긴 데이터 제공
SQLBulkOperations 호출을 통해 대량 삽입과 업데이트를 수행할 수 있는 긴 데이터를 제공할 수 있습니다. 긴 데이터를 삽입하거나 업데이트하기 위해, 애플리케이션은 이 주제 앞서 언급한 "대량 삽입 수행" 및 "북마크를 이용한 대량 업데이트 수행" 섹션에서 설명한 단계들 외에 다음과 같은 단계를 수행합니다.
SQLBindCol을 사용해 데이터를 바인딩할 때, 애플리케이션은 실행 시 데이터 열의 *TargetValuePtr 버퍼에 열과 같은 애플리케이션 정의 값을 배치합니다. 이 값은 나중에 열을 식별하는 데 사용할 수 있습니다.
애플리케이션은 SQL_LEN_DATA_AT_EXEC(길이) 매크로 결과를 *StrLen_or_IndPtr 버퍼에 배치합니다. 열의 SQL 데이터 타입이 SQL_LONGVARBINARY, SQL_LONGVARCHAR 또는 긴 데이터 소스별 데이터 타입이고 드라이버가 SQLGetInfo의 SQL_NEED_LONG_DATA_LEN 정보 타입에 대해 "Y"를 반환한다면, 길이 는 해당 매개변수에 대해 전송할 데이터 바이트 수이며; 그렇지 않으면 음수가 아닌 값이어야 하며 무시됩니다.
SQLBulkOperations가 호출될 때, 실행 시 data-at-execution 열이 있으면 함수는 SQL_NEED_DATA 반환하고 3단계로 넘어갑니다. (실행 시 데이터 열이 없다면 프로세스가 완료됩니다.)
애플리케이션은 SQLParamData 를 호출하여 처리할 첫 번째 실행 데이터 열의 *TargetValuePtr 버퍼 주소를 가져옵니다. SQLParamData 는 SQL_NEED_DATA 반환합니다. 애플리케이션은 *TargetValuePtr 버퍼에서 애플리케이션 정의 값을 가져옵니다.
Note
실행 시 데이터 매개 변수는 실행 시 데이터 열과 유사하지만 SQLParamData에서 반환되는 값은 각각 다릅니다.
실행 시 데이터(Data-at-execution) 컬럼은 행셋 내 열로, 행이 SQLBulkOperations로 업데이트되거나 삽입될 때 데이터가 SQLPutData로 전송됩니다. SQLBindCol에 바인딩됩니다. SQLParamData가 반환하는 값은 처리 중인 *TargetValuePtr 버퍼의 행 주소입니다.
애플리케이션은 열에 대한 데이터를 전송하기 위해 SQLPutData 를 한 번 이상 호출합니다. SQLPutData에서 지정한 *TargetValuePtr 버퍼에서 모든 데이터 값을 반환할 수 없을 경우, 두 개 이상의 호출이 필요합니다; 동일한 열에 대해 SQLPutData에 여러 번 호출하는 것은 문자, 바이너리 또는 데이터 소스별 데이터 타입이 있는 열로 문자 C 데이터를 전송하거나, 문자, 바이너리 또는 데이터 소스별 데이터 타입이 있는 열로 C 데이터를 보낼 때만 허용됩니다.
애플리케이션은 다시 SQLParamData 를 호출하여 해당 열에 대한 모든 데이터가 전송되었음을 알립니다.
실행 시 데이터열 수가 더 많으면, SQLParamData 는 다음에 처리할 데이터- 실행 열 TargetValuePtr 버퍼의 주소와 SQL_NEED_DATA을 반환합니다. 애플리케이션은 4단계와 5단계를 반복합니다.
더 이상 실행 시 데이터 열이 없으면 프로세스가 완료됩니다. 문장이 성공적으로 실행되면 SQLParamData 는 SQL_SUCCESS 또는 SQL_SUCCESS_WITH_INFO를 반환합니다; 실행이 실패하면 SQL_ERROR를 반환합니다. 이 시점에서 SQLParamData 는 SQLBulkOperations가 반환할 수 있는 모든 SQLSTATE를 반환할 수 있습니다.
만약 SQLBulkOperations가 SQL_NEED_DATA를 반환하고 모든 실행 시 데이터 열에 대한 데이터가 전송되기 전에 연산이 취소되거나 SQLParamData 또는 SQLPutData에서 오류가 발생하면, 애플리케이션은 문장 또는 문장과 연관된 연결에 대해 SQLCancel, SQLGetDiagField, SQLGetFunctions, SQLParamData, 또는 SQLPutData만 호출할 수 있습니다. 만약 해당 문장이나 문장과 연관된 연결에 대해 다른 함수를 호출하면, 함수는 SQL_ERROR와 SQLSTATE HY010(함수 시퀀스 오류)을 반환합니다.
만약 애플리케이션이 SQLCancel 을 호출하는 동안 드라이버가 실행 시 데이터 열에 데이터를 필요로 하면, 드라이버는 해당 작업을 취소합니다. 그 후 애플리케이션은 다시 SQLBulkOperations 를 호출할 수 있습니다; 취소는 커서 상태나 현재 커서 위치에 영향을 주지 않습니다.
행 상태 배열
행 상태 배열은 SQLBulkOperations를 호출한 후 행셋 내 각 데이터 행의 상태 값을 포함합니다. 드라이버는 SQLFetch, SQLFetchScroll, SQLSetPos, 또는 SQLBulkOperations를 호출한 후 이 배열의 상태 값을 설정합니다. 이 배열은 SQLBulkOperations 이전에 SQLFetch 또는 SQLFetchScroll이 호출되지 않은 경우, SQLBulkOperations 호출로 초기적으로 채워집니다. 이 배열은 SQL_ATTR_ROW_STATUS_PTR 문장 속성으로 가리킵니다. 행 상태 배열의 요소 수는 행 집합의 행 수(SQL_ATTR_ROW_ARRAY_SIZE 명문 속성에 의해 정의됨)와 같아야 합니다. 이 행 상태 배열에 대한 정보는 SQLFetch를 참조하세요.
코드 예제
다음 예시는 고객 테이블에서 한 번에 10행의 데이터를 가져오는 방식입니다. 그 후 사용자가 취할 행동을 유도합니다. 네트워크 트래픽을 줄이기 위해 예제 버퍼는 바운드 배열에 업데이트, 삭제, 삽입을 하지만, 행셋 데이터 이너머의 오프셋에 위치합니다. 사용자가 데이터 소스에 업데이트, 삭제, 삽입을 선택하면, 코드는 바인딩 오프셋을 적절히 설정하고 SQLBulkOperations를 호출합니다. 간단히 하기 위해 사용자는 10회 이상의 업데이트, 삭제 또는 삽입을 버퍼링할 수 없습니다.
// SQLBulkOperations_Function.cpp
// compile with: ODBC32.lib
#include <windows.h>
#include <sqlext.h>
#include "stdio.h"
#define UPDATE_ROW 100
#define DELETE_ROW 101
#define ADD_ROW 102
#define SEND_TO_DATA_SOURCE 103
#define UPDATE_OFFSET 10
#define INSERT_OFFSET 20
#define DELETE_OFFSET 30
// Define structure for customer data (assume 10 byte maximum bookmark size).
typedef struct tagCustStruct {
SQLCHAR Bookmark[10];
SQLINTEGER BookmarkLen;
SQLUINTEGER CustomerID;
SQLINTEGER CustIDInd;
SQLCHAR CompanyName[51];
SQLINTEGER NameLenOrInd;
SQLCHAR Address[51];
SQLINTEGER AddressLenOrInd;
SQLCHAR Phone[11];
SQLINTEGER PhoneLenOrInd;
} CustStruct;
// Allocate 40 of these structures. Elements 0-9 are for the current rowset,
// elements 10-19 are for the buffered updates, elements 20-29 are for
// the buffered inserts, and elements 30-39 are for the buffered deletes.
CustStruct CustArray[40];
SQLUSMALLINT RowStatusArray[10], Action, RowNum, NumUpdates = 0, NumInserts = 0,
NumDeletes = 0;
SQLLEN BindOffset = 0;
SQLRETURN retcode;
SQLHENV henv = NULL;
SQLHDBC hdbc = NULL;
SQLHSTMT hstmt = NULL;
int main() {
retcode = SQLAllocHandle(SQL_HANDLE_ENV, SQL_NULL_HANDLE, &henv);
retcode = SQLSetEnvAttr(henv, SQL_ATTR_ODBC_VERSION, (SQLPOINTER*)SQL_OV_ODBC3, 0);
retcode = SQLAllocHandle(SQL_HANDLE_DBC, henv, &hdbc);
retcode = SQLSetConnectAttr(hdbc, SQL_LOGIN_TIMEOUT, (SQLPOINTER)5, 0);
retcode = SQLConnect(hdbc, (SQLCHAR*) "Northwind", SQL_NTS, (SQLCHAR*) NULL, 0, NULL, 0);
retcode = SQLAllocHandle(SQL_HANDLE_STMT, hdbc, &hstmt);
// Set the following statement attributes:
// SQL_ATTR_CURSOR_TYPE: Keyset-driven
// SQL_ATTR_ROW_BIND_TYPE: Row-wise
// SQL_ATTR_ROW_ARRAY_SIZE: 10
// SQL_ATTR_USE_BOOKMARKS: Use variable-length bookmarks
// SQL_ATTR_ROW_STATUS_PTR: Points to RowStatusArray
// SQL_ATTR_ROW_BIND_OFFSET_PTR: Points to BindOffset
retcode = SQLSetStmtAttr(hstmt, SQL_ATTR_CURSOR_TYPE, (SQLPOINTER)SQL_CURSOR_KEYSET_DRIVEN, 0);
retcode = SQLSetStmtAttr(hstmt, SQL_ATTR_ROW_BIND_TYPE, (SQLPOINTER)sizeof(CustStruct), 0);
retcode = SQLSetStmtAttr(hstmt, SQL_ATTR_ROW_ARRAY_SIZE, (SQLPOINTER)10, 0);
retcode = SQLSetStmtAttr(hstmt, SQL_ATTR_USE_BOOKMARKS, (SQLPOINTER)SQL_UB_VARIABLE, 0);
retcode = SQLSetStmtAttr(hstmt, SQL_ATTR_ROW_STATUS_PTR, RowStatusArray, 0);
retcode = SQLSetStmtAttr(hstmt, SQL_ATTR_ROW_BIND_OFFSET_PTR, &BindOffset, 0);
// Bind arrays to the bookmark, CustomerID, CompanyName, Address, and Phone columns.
retcode = SQLBindCol(hstmt, 0, SQL_C_VARBOOKMARK, CustArray[0].Bookmark, sizeof(CustArray[0].Bookmark), &CustArray[0].BookmarkLen);
retcode = SQLBindCol(hstmt, 1, SQL_C_ULONG, &CustArray[0].CustomerID, 0, &CustArray[0].CustIDInd);
retcode = SQLBindCol(hstmt, 2, SQL_C_CHAR, CustArray[0].CompanyName, sizeof(CustArray[0].CompanyName), &CustArray[0].NameLenOrInd);
retcode = SQLBindCol(hstmt, 3, SQL_C_CHAR, CustArray[0].Address, sizeof(CustArray[0].Address), &CustArray[0].AddressLenOrInd);
retcode = SQLBindCol(hstmt, 4, SQL_C_CHAR, CustArray[0].Phone, sizeof(CustArray[0].Phone), &CustArray[0].PhoneLenOrInd);
// Execute a statement to retrieve rows from the Customers table.
retcode = SQLExecDirect(hstmt, (SQLCHAR*)"SELECT CustomerID, CompanyName, Address, Phone FROM Customers", SQL_NTS);
// Fetch and display the first 10 rows.
retcode = SQLFetchScroll(hstmt, SQL_FETCH_NEXT, 0);
// DisplayCustData(CustArray, 10);
// Call GetAction to get an action and a row number from the user.
// while (GetAction(&Action, &RowNum)) {
Action = SQL_FETCH_NEXT;
RowNum = 2;
switch (Action) {
case SQL_FETCH_NEXT:
case SQL_FETCH_PRIOR:
case SQL_FETCH_FIRST:
case SQL_FETCH_LAST:
case SQL_FETCH_ABSOLUTE:
case SQL_FETCH_RELATIVE:
// Fetch and display the requested data.
SQLFetchScroll(hstmt, Action, RowNum);
// DisplayCustData(CustArray, 10);
break;
case UPDATE_ROW:
// Check if we have reached the maximum number of buffered updates.
if (NumUpdates < 10) {
// Get the new customer data and place it in the next available element of
// the buffered updates section of CustArray, copy the bookmark of the row
// being updated to the same element, and increment the update counter.
// Checking to see we have not already buffered an update for this
// row not shown.
// GetNewCustData(CustArray, UPDATE_OFFSET + NumUpdates);
memcpy(CustArray[UPDATE_OFFSET + NumUpdates].Bookmark,
CustArray[RowNum - 1].Bookmark,
CustArray[RowNum - 1].BookmarkLen);
CustArray[UPDATE_OFFSET + NumUpdates].BookmarkLen =
CustArray[RowNum - 1].BookmarkLen;
NumUpdates++;
} else {
printf("Buffers full. Send buffered changes to the data source.");
}
break;
case DELETE_ROW:
// Check if we have reached the maximum number of buffered deletes.
if (NumDeletes < 10) {
// Copy the bookmark of the row being deleted to the next available element
// of the buffered deletes section of CustArray and increment the delete
// counter. Checking to see we have not already buffered an update for
// this row not shown.
memcpy(CustArray[DELETE_OFFSET + NumDeletes].Bookmark,
CustArray[RowNum - 1].Bookmark,
CustArray[RowNum - 1].BookmarkLen);
CustArray[DELETE_OFFSET + NumDeletes].BookmarkLen =
CustArray[RowNum - 1].BookmarkLen;
NumDeletes++;
} else
printf("Buffers full. Send buffered changes to the data source.");
break;
case ADD_ROW:
// reached maximum number of buffered inserts?
if (NumInserts < 10) {
// Get the new customer data and place it in the next available element of
// the buffered inserts section of CustArray and increment insert counter.
// GetNewCustData(CustArray, INSERT_OFFSET + NumInserts);
NumInserts++;
} else
printf("Buffers full. Send buffered changes to the data source.");
break;
case SEND_TO_DATA_SOURCE:
// If there are any buffered updates, inserts, or deletes, set the array size
// to that number, set the binding offset to use the data in the buffered
// update, insert, or delete part of CustArray, and call SQLBulkOperations to
// do the updates, inserts, or deletes. Because we will never have more than
// 10 updates, inserts, or deletes, we can use the same row status array.
if (NumUpdates) {
SQLSetStmtAttr(hstmt, SQL_ATTR_ROW_ARRAY_SIZE, (SQLPOINTER)NumUpdates, 0);
BindOffset = UPDATE_OFFSET * sizeof(CustStruct);
SQLBulkOperations(hstmt, SQL_UPDATE_BY_BOOKMARK);
NumUpdates = 0;
}
if (NumInserts) {
SQLSetStmtAttr(hstmt, SQL_ATTR_ROW_ARRAY_SIZE, (SQLPOINTER)NumInserts, 0);
BindOffset = INSERT_OFFSET * sizeof(CustStruct);
SQLBulkOperations(hstmt, SQL_ADD);
NumInserts = 0;
}
if (NumDeletes) {
SQLSetStmtAttr(hstmt, SQL_ATTR_ROW_ARRAY_SIZE, (SQLPOINTER)NumDeletes, 0);
BindOffset = DELETE_OFFSET * sizeof(CustStruct);
SQLBulkOperations(hstmt, SQL_DELETE_BY_BOOKMARK);
NumDeletes = 0;
}
// If there were any updates, inserts, or deletes, reset the binding offset
// and array size to their original values.
if (NumUpdates || NumInserts || NumDeletes) {
SQLSetStmtAttr(hstmt, SQL_ATTR_ROW_ARRAY_SIZE, (SQLPOINTER)10, 0);
BindOffset = 0;
}
break;
}
// }
// Close the cursor.
SQLFreeStmt(hstmt, SQL_CLOSE);
}
관련 함수
| 정보에 대해 | 보십시오 |
|---|---|
| 결과 집합의 열에 버퍼 바인딩 | SQLBindCol 함수 |
| 문 처리 취소 | SQLCancel 함수 |
| 데이터 블록을 가져오거나 결과 집합을 스크롤합니다. | SQLFetchScroll 함수 |
| 디스크립터의 단일 필드를 얻기 | SQLGetDescField 함수 |
| 디스크립터의 여러 필드를 얻기 | SQLGetDescRec 함수 |
| 디스크립터의 단일 필드 설정 | SQLSetDescField 함수 |
| 디스크립터의 여러 필드 설정 | SQLSetDescRec 함수 |
| 커서 위치 변경, 행셋 내 데이터 새로고침, 행셋 내 데이터 업데이트 또는 삭제 | SQLSetPos 함수 |
| 문 특성 설정 | SQLSetStmtAttr 함수 |