SQLBindCol 함수

아티클
08/21/2023

규칙
버전 소개: ODBC 1.0 표준 준수: ISO 92

요약
SQLBindCol 은 애플리케이션 데이터 버퍼를 결과 집합의 열에 바인딩합니다.

구문

  
SQLRETURN SQLBindCol(  
      SQLHSTMT       StatementHandle,  
      SQLUSMALLINT   ColumnNumber,  
      SQLSMALLINT    TargetType,  
      SQLPOINTER     TargetValuePtr,  
      SQLLEN         BufferLength,  
      SQLLEN *       StrLen_or_IndPtr);

인수

StatementHandle
[입력] 문 핸들입니다.

ColumnNumber
[입력] 바인딩할 결과 집합 열의 수입니다. 열 번호는 0부터 시작하여 열 순서로 번호가 매겨집니다. 여기서 열 0은 책갈피 열입니다. 책갈피를 사용하지 않는 경우( 즉, SQL_ATTR_USE_BOOKMARKS 문 특성이 SQL_UB_OFF 설정됨) 열 번호는 1에서 시작합니다.

TargetType
[입력] *TargetValuePtr 버퍼의 C 데이터 형식 식별자입니다. SQLFetch, SQLFetchScroll, SQLBulkOperations 또는 SQLSetPos를 사용하여 데이터 원본에서 데이터를 검색하는 경우 드라이버는 데이터를 이 형식으로 변환합니다. SQLBulkOperations 또는 SQLSetPos를 사용하여 데이터 원본으로 데이터를 보낼 때 드라이버는 이 형식에서 데이터를 변환합니다. 유효한 C 데이터 형식 및 형식 식별자 목록은 부록 D: 데이터 형식의 C 데이터 형식 섹션을 참조하세요.

TargetType 인수가 간격 데이터 형식인 경우 ARD의 SQL_DESC_DATETIME_INTERVAL_PRECISION 및 SQL_DESC_PRECISION 필드에 각각 설정된 기본 간격 선행 전체 자릿수(2) 및 기본 간격 초 정밀도(6)가 데이터에 사용됩니다. TargetType 인수가 SQL_C_NUMERIC 경우 ARD의 SQL_DESC_PRECISION 및 SQL_DESC_SCALE 필드에 설정된 기본 전체 자릿수(드라이버 정의) 및 기본 소수 자릿수(0)가 데이터에 사용됩니다. 기본 전체 자릿수 또는 소수 자릿수가 적절하지 않은 경우 애플리케이션은 SQLSetDescField 또는 SQLSetDescRec를 호출하여 적절한 설명자 필드를 명시적으로 설정해야 합니다.

확장된 C 데이터 형식을 지정할 수도 있습니다. 자세한 내용은 ODBC의 C 데이터 형식을 참조하세요.

TargetValuePtr
[지연된 입력/출력] 열에 바인딩할 데이터 버퍼에 대한 포인터입니다. SQLFetch 및 SQLFetchScroll 은 이 버퍼의 데이터를 반환합니다. SQLBulkOperations는 작업이 SQL_FETCH_BY_BOOKMARK 때 이 버퍼의 데이터를 반환합니다. 작업이 SQL_ADD 또는 SQL_UPDATE_BY_BOOKMARK 때 이 버퍼에서 데이터를 검색합니다. SQLSetPos는 작업이 SQL_REFRESH 때 이 버퍼의 데이터를 반환합니다. 작업이 SQL_UPDATE 때 이 버퍼에서 데이터를 검색합니다.

TargetValuePtr이 null 포인터인 경우 드라이버는 열의 데이터 버퍼를 바인딩 해제합니다. 애플리케이션은 SQL_UNBIND 옵션을 사용하여 SQLFreeStmt를 호출하여 모든 열을 바인딩 해제할 수 있습니다. SQLBindCol 호출의 TargetValuePtr 인수가 null 포인터이지만 StrLen_or_IndPtr 인수가 유효한 값인 경우 애플리케이션은 열에 대한 데이터 버퍼를 바인딩 해제할 수 있지만 여전히 열에 바인딩된 길이/표시기 버퍼가 있습니다.

BufferLength
[입력] *TargetValuePtr 버퍼의 길이(바이트)입니다.

드라이버는 버퍼Length를 사용하여 문자 또는 이진 데이터와 같은 가변 길이 데이터를 반환할 때 *TargetValuePtr 버퍼의 끝을 지나서 쓰는 것을 방지합니다. *TargetValuePtr에 문자 데이터를 반환할 때 드라이버는 null 종료 문자 수를 계산합니다. *따라서 TargetValuePtr 은 null 종료 문자에 대한 공간을 포함해야 합니다. 그렇지 않으면 드라이버가 데이터를 자른다.

드라이버가 정수 또는 날짜 구조와 같은 고정 길이 데이터를 반환하는 경우 드라이버는 BufferLength를 무시하고 버퍼가 데이터를 보유할 만큼 충분히 크다고 가정합니다. 따라서 애플리케이션이 고정 길이 데이터에 충분한 버퍼를 할당하거나 드라이버가 버퍼의 끝을 지나서 쓰는 것이 중요합니다.

BufferLength가 0보다 작지만 BufferLength가 0이 아닌 경우 SQLBindCol은 SQLSTATE HY090(잘못된 문자열 또는 버퍼 길이)을 반환합니다. 그러나 TargetType에서 문자 형식을 지정하는 경우 ISO CLI 규격 드라이버는 SQLSTATE HY090(잘못된 문자열 또는 버퍼 길이)을 반환하므로 애플리케이션에서 BufferLength를 0으로 설정하면 안 됩니다.

StrLen_or_IndPtr
[지연된 입력/출력] 열에 바인딩할 길이/표시기 버퍼에 대한 포인터입니다. SQLFetch 및 SQLFetchScroll 은 이 버퍼의 값을 반환합니다. 작업이 SQL_ADD, SQL_UPDATE_BY_BOOKMARK 또는 SQL_DELETE_BY_BOOKMARK 경우 SQLBulkOperations는 이 버퍼에서 값을 검색합니다. 작업이 SQL_FETCH_BY_BOOKMARK 경우 SQLBulkOperations는 이 버퍼의 값을 반환합니다. SQLSetPos는 Operation이 SQL_REFRESH 때 이 버퍼의 값을 반환합니다. 작업이 SQL_UPDATE 때 이 버퍼에서 값을 검색합니다.

SQLFetch, SQLFetchScroll, SQLBulkOperations 및 SQLSetPos 는 길이/표시기 버퍼에서 다음 값을 반환할 수 있습니다.

반환할 수 있는 데이터의 길이
SQL_NO_TOTAL
SQL_NULL_DATA

애플리케이션은 SQLBulkOperations 또는 SQLSetPos와 함께 사용하기 위해 길이/표시기 버퍼에 다음 값을 넣을 수 있습니다.

전송되는 데이터의 길이
SQL_NTS
SQL_NULL_DATA
SQL_DATA_AT_EXEC
SQL_LEN_DATA_AT_EXEC 매크로의 결과
SQL_COLUMN_IGNORE

표시기 버퍼와 길이 버퍼가 별도의 버퍼인 경우 표시기 버퍼는 SQL_NULL_DATA 반환할 수 있는 반면 길이 버퍼는 다른 모든 값을 반환할 수 있습니다.

자세한 내용은 SQLBulkOperations 함수, SQLFetch 함수, SQLSetPos 함수 및 길이/표시기 값 사용을 참조하세요.

StrLen_or_IndPtr null 포인터인 경우 길이 또는 표시기 값이 사용되지 않습니다. 데이터를 가져올 때 오류가 발생하며 데이터는 NULL입니다.

애플리케이션이 64비트 운영 체제에서 실행되는 경우 ODBC 64비트 정보를 참조하세요.

반품

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR 또는 SQL_INVALID_HANDLE.

진단

SQLBindCol이 SQL_ERROR 또는 SQL_SUCCESS_WITH_INFO 반환하는 경우 SQL_HANDLE_STMT HandleType 및Handle of StatementHandle을 사용하여 SQLGetDiagRec 를 호출하여 관련 SQLSTATE 값을 가져올 수 있습니다. 다음 표에서는 일반적으로 SQLBindCol에서 반환되는 SQLSTATE 값을 나열하고 이 함수의 컨텍스트에서 각 값을 설명합니다. "(DM)" 표기법은 드라이버 관리자가 반환한 SQLSTATE에 대한 설명 앞에 나와 있습니다. 달리 명시되지 않는 한 각 SQLSTATE 값과 연결된 반환 코드는 SQL_ERROR.

SQLSTATE	Error	설명
01000	일반 경고	드라이버 관련 정보 메시지입니다. 함수는 SQL_SUCCESS_WITH_INFO 반환합니다.
07006	제한된 데이터 형식 특성 위반	(DM) ColumnNumber 인수가 0이고 TargetType 인수가 SQL_C_BOOKMARK 또는 SQL_C_VARBOOKMARK 않았습니다.
07009	설명자 인덱스가 잘못되었습니다.	ColumnNumber 인수에 지정된 값이 결과 집합의 최대 열 수를 초과했습니다.
HY000	일반 오류	특정 SQLSTATE가 없고 구현별 SQLSTATE가 정의되지 않은 오류가 발생했습니다. *MessageText 버퍼의 SQLGetDiagRec에서 반환된 오류 메시지는 오류와 그 원인을 설명합니다.
HY001	메모리 할당 오류	드라이버가 함수 실행 또는 완료를 지원하는 데 필요한 메모리를 할당할 수 없습니다.
HY003	잘못된 애플리케이션 버퍼 유형	TargetType 인수가 유효한 데이터 형식도 아니고 SQL_C_DEFAULT.
HY010	함수 시퀀스 오류	(DM) StatementHandle과 연결된 연결 핸들에 대해 비동기적으로 실행되는 함수가 호출되었습니다. SQLBindCol이 호출되었을 때 이 비동기 함수는 여전히 실행 중입니다. (DM) SQLExecute, SQLExecDirect 또는 SQLMoreResults가 StatementHandle에 대해 호출되고 SQL_PARAM_DATA_AVAILABLE 반환되었습니다. 이 함수는 모든 스트리밍된 매개 변수에 대해 데이터를 검색하기 전에 호출되었습니다. (DM) StatementHandle에 대해 비동기적으로 실행되는 함수가 호출되었고 이 함수가 호출되었을 때에도 여전히 실행 중입니다. (DM) SQLExecute, SQLExecDirect, SQLBulkOperations 또는 SQLSetPos가 StatementHandle에 대해 호출되고 SQL_NEED_DATA 반환되었습니다. 이 함수는 모든 실행 시 데이터 매개 변수 또는 열에 대한 데이터를 보내기 전에 호출되었습니다.
HY013	메모리 관리 오류	메모리 조건이 낮기 때문에 기본 메모리 개체에 액세스할 수 없기 때문에 함수 호출을 처리할 수 없습니다.
HY090	잘못된 문자열 또는 버퍼 길이	(DM) BufferLength 인수에 지정된 값이 0보다 작습니다. (DM) 드라이버는 ODBC 2였습니다.x 드라이버, ColumnNumber 인수가 0으로 설정되었으며 BufferLength 인수에 지정된 값이 4와 같지 않습니다.
HY117	알 수 없는 트랜잭션 상태로 인해 연결이 일시 중단됩니다. 연결 끊기 및 읽기 전용 함수만 허용됩니다.	(DM) 일시 중단 상태에 대한 자세한 내용은 SQLEndTran 함수를 참조 하세요.
HYC00	선택적 기능이 구현되지 않음	드라이버 또는 데이터 원본은 TargetType 인수와 해당 열의 드라이버별 SQL 데이터 형식 조합으로 지정된 변환을 지원하지 않습니다. ColumnNumber 인수가 0이고 드라이버가 책갈피를 지원하지 않습니다. 드라이버는 ODBC 2만 지원합니다.x 및 TargetType 인수는 다음 중 하나입니다. SQL_C_NUMERIC SQL_C_SBIGINT SQL_C_UBIGINT 및 부록 D: 데이터 형식의 C 데이터 형식에 나열된 간격 C 데이터 형식입니다. 드라이버는 3.50 이전의 ODBC 버전만 지원하며 TargetType 인수는 SQL_C_GUID.
HYT01	연결 제한 시간이 만료됨	데이터 원본이 요청에 응답하기 전에 연결 제한 시간이 만료되었습니다. 연결 제한 시간은 SQL_ATTR_CONNECTION_TIMEOUT SQLSetConnectAttr를 통해 설정됩니다.
IM001	드라이버는 이 함수를 지원하지 않습니다.	(DM) StatementHandle과 연결된 드라이버는 함수를 지원하지 않습니다.

주석

SQLBindCol 은 결과 집합의 열을 애플리케이션의 데이터 버퍼 및 길이/표시기 버퍼에 연결하거나 바인딩 하는 데 사용됩니다. 애플리케이션이 SQLFetch, SQLFetchScroll 또는 SQLSetPos를 호출하여 데이터를 가져오는 경우 드라이버는 지정된 버퍼의 바인딩된 열에 대한 데이터를 반환합니다. 자세한 내용은 SQLFetch 함수를 참조하세요. 애플리케이션이 행 또는 SQLSetPos를 업데이트하거나 삽입하기 위해 SQLBulkOperations를 호출하면 드라이버는 지정된 버퍼에서 바인딩된 열의 데이터를 검색합니다. 자세한 내용은 SQLBulkOperations 함수 또는 SQLSetPos 함수를 참조하세요. 바인딩에 대한 자세한 내용은 결과 검색(기본)을 참조하세요.

열에서 데이터를 검색하기 위해 열을 바인딩할 필요가 없습니다. 또한 애플리케이션은 SQLGetData를 호출하여 열에서 데이터를 검색할 수 있습니다. 행의 일부 열을 바인딩하고 다른 열에 대해 SQLGetData를 호출할 수 있지만 몇 가지 제한 사항이 적용됩니다. 자세한 내용은 SQLGetData를 참조하세요.

바인딩, 바인딩 해제 및 열 다시 바인딩

결과 집합에서 데이터를 가져온 후에도 언제든지 열을 바인딩, 언바운드 또는 리바운드할 수 있습니다. 새 바인딩은 다음에 바인딩을 사용하는 함수가 호출되면 적용됩니다. 예를 들어 애플리케이션이 결과 집합의 열을 바인딩하고 SQLFetch를 호출한다고 가정합니다. 드라이버는 바인딩된 버퍼의 데이터를 반환합니다. 이제 애플리케이션이 열을 다른 버퍼 집합에 바인딩한다고 가정합니다. 드라이버는 방금 가져온 행에 대한 데이터를 새로 바인딩된 버퍼에 넣지 않습니다. 대신 SQLFetch가 다시 호출될 때까지 기다린 다음, 다음 행에 대한 데이터를 새로 바인딩된 버퍼에 배치합니다.

참고 항목

열 0에 열을 바인딩하기 전에 문 특성 SQL_ATTR_USE_BOOKMARKS 항상 설정해야 합니다. 이는 필수는 아니지만 강력하게 권장됩니다.

열 바인딩

열을 바인딩하기 위해 애플리케이션은 SQLBindCol을 호출하고 데이터 버퍼의 열 번호, 형식, 주소 및 길이/표시기 버퍼의 주소를 전달합니다. 이러한 주소를 사용하는 방법에 대한 자세한 내용은 이 섹션의 뒷부분에 있는 "버퍼 주소"를 참조하세요. 열 바인딩에 대한 자세한 내용은 SQLBindCol 사용을 참조하세요.

이러한 버퍼의 사용은 지연됩니다. 즉, 애플리케이션은 SQLBindCol에서 바인딩하지만 드라이버는 SQLBulkOperations, SQLFetch, SQLFetchScroll 또는 SQLSetPos와 같은 다른 함수에서 액세스합니다. 바인딩이 계속 적용되는 한 SQLBindCol에 지정된 포인터가 유효한지 확인하는 것은 애플리케이션의 책임입니다. 애플리케이션에서 이러한 포인터를 유효하지 않게 하는 경우(예: 버퍼를 해제한 다음 유효한 것으로 예상되는 함수를 호출) 결과는 정의되지 않습니다. 자세한 내용은 지연 버퍼를 참조 하세요.

바인딩은 새 바인딩으로 대체되거나 열이 바인딩 해제되거나 문이 해제될 때까지 계속 적용됩니다.

열 바인딩 해제

단일 열을 바인딩 해제하기 위해 애플리케이션은 ColumnNumber가 해당 열의 수로 설정되고 TargetValuePtr이 null 포인터로 설정된 SQLBindCol을 호출합니다. ColumnNumber가 언바운드 열을 참조하는 경우 SQLBindCol은 여전히 SQL_SUCCESS 반환합니다.

모든 열을 바인딩 해제하기 위해 애플리케이션은 fOption이 SQL_UNBIND 설정된 SQLFreeStmt 를 호출합니다. ARD의 SQL_DESC_COUNT 필드를 0으로 설정하여 이 작업을 수행할 수도 있습니다.

열 다시 바인딩

애플리케이션은 두 작업 중 하나를 수행하여 바인딩을 변경할 수 있습니다.

SQLBindCol을 호출하여 이미 바인딩된 열에 대한 새 바인딩을 지정합니다. 드라이버는 이전 바인딩을 새 바인딩으로 덮어씁니다.
SQLBindCol에 대한 바인딩 호출에 의해 지정된 버퍼 주소에 추가할 오프셋을 지정합니다. 자세한 내용은 다음 섹션인 "바인딩 오프셋"을 참조하세요.

바인딩 오프셋

바인딩 오프셋은 역참조되기 전에 데이터 주소와 길이/표시기 버퍼(TargetValuePtr 및 StrLen_or_IndPtr 인수에 지정된 대로)에 추가되는 값입니다. 오프셋을 사용하는 경우 바인딩은 애플리케이션의 버퍼가 배치되는 방식의 "템플릿"이며 애플리케이션은 오프셋을 변경하여 이 "템플릿"을 다른 메모리 영역으로 이동할 수 있습니다. 각 바인딩의 각 주소에 동일한 오프셋이 추가되므로 서로 다른 열에 대한 버퍼 간의 상대 오프셋은 각 버퍼 집합 내에서 동일해야 합니다. 행 단위 바인딩을 사용하는 경우 항상 해당됩니다. 애플리케이션은 열 단위 바인딩을 사용할 때 이를 적용하려면 해당 버퍼를 신중하게 배치해야 합니다.

바인딩 오프셋을 사용하면 기본적으로 SQLBindCol을 호출 하여 열을 다시 바인딩하는 것과 동일한 효과가 있습니다. 차이점은 SQLBindCol에 대한 새 호출이 데이터 버퍼 및 길이/표시기 버퍼에 대한 새 주소를 지정한다는 점입니다. 반면 바인딩 오프셋을 사용하면 주소가 변경되지 않고 오프셋만 추가됩니다. 애플리케이션은 원하는 때마다 새 오프셋을 지정할 수 있으며 이 오프셋은 항상 원래 바인딩된 주소에 추가됩니다. 특히 오프셋이 0으로 설정되거나 문 특성이 null 포인터로 설정된 경우 드라이버는 원래 바인딩된 주소를 사용합니다.

바인딩 오프셋을 지정하기 위해 애플리케이션은 SQL_ATTR_ROW_BIND_OFFSET_PTR 문 특성을 SQLINTEGER 버퍼의 주소로 설정합니다. 애플리케이션이 바인딩을 사용하는 함수를 호출하기 전에 이 버퍼에 오프셋을 바이트 단위로 넣습니다. 사용할 버퍼의 주소를 확인하기 위해 드라이버는 바인딩의 주소에 오프셋을 추가합니다. 주소와 오프셋의 합계는 유효한 주소여야 하지만 오프셋이 추가된 주소는 유효하지 않아도 됩니다. 바인딩 오프셋을 사용하는 방법에 대한 자세한 내용은 이 섹션의 뒷부분에 있는 "버퍼 주소"를 참조하세요.

바인딩 배열

행 집합 크기(SQL_ATTR_ROW_ARRAY_SIZE 문 특성 값)가 1보다 크면 애플리케이션은 단일 버퍼 대신 버퍼 배열을 바인딩합니다. 자세한 내용은 블록 커서를 참조 하세요.

애플리케이션은 다음 두 가지 방법으로 배열을 바인딩할 수 있습니다.

배열을 각 열에 바인딩합니다. 각 데이터 구조(배열)에는 단일 열에 대한 데이터가 포함되어 있으므로 이를 열 단위 바인딩이라고 합니다.
전체 행에 대한 데이터를 보관하고 이러한 구조체의 배열을 바인딩하는 구조를 정의합니다. 각 데이터 구조에는 단일 행에 대한 데이터가 포함되어 있으므로 이를 행 단위 바인딩 이라고 합니다.

버퍼의 각 배열에는 행 집합의 크기만큼 많은 요소가 있어야 합니다.

참고 항목

애플리케이션은 맞춤이 유효한지 확인해야 합니다. 맞춤 고려 사항에 대한 자세한 내용은 맞춤을 참조 하세요.

열 단위 바인딩

열 단위 바인딩에서 애플리케이션은 개별 데이터와 길이/표시기 배열을 각 열에 바인딩합니다.

열 단위 바인딩을 사용하기 위해 애플리케이션은 먼저 SQL_ATTR_ROW_BIND_TYPE 문 특성을 SQL_BIND_BY_COLUMN 설정합니다. 기본값입니다. 바인딩할 각 열에 대해 애플리케이션은 다음 단계를 수행합니다.

데이터 버퍼 배열을 할당합니다.
길이/표시기 버퍼의 배열을 할당합니다.

참고 항목

열 단위 바인딩을 사용할 때 애플리케이션이 설명자에 직접 쓰는 경우 길이 및 표시기 데이터에 별도의 배열을 사용할 수 있습니다.
다음 인수를 사용하여 SQLBindCol을 호출합니다.
- TargetType 은 데이터 버퍼 배열에 있는 단일 요소의 형식입니다.
- TargetValuePtr 은 데이터 버퍼 배열의 주소입니다.
- BufferLength 는 데이터 버퍼 배열에 있는 단일 요소의 크기입니다. 데이터가 고정 길이 데이터인 경우 BufferLength 인수는 무시됩니다.
- StrLen_or_IndPtr 길이/표시기 배열의 주소입니다.

이 정보를 사용하는 방법에 대한 자세한 내용은 이 섹션의 뒷부분에 있는 "버퍼 주소"를 참조하세요. 열 단위 바인딩에 대한 자세한 내용은 열 단위 바인딩을 참조하세요.

행 단위 바인딩

행 단위 바인딩에서 애플리케이션은 바인딩할 각 열에 대한 데이터 및 길이/표시기 버퍼를 포함하는 구조를 정의합니다.

행 단위 바인딩을 사용하기 위해 애플리케이션은 다음 단계를 수행합니다.

단일 데이터 행(데이터 및 길이/표시기 버퍼 포함)을 보유하는 구조를 정의하고 이러한 구조체의 배열을 할당합니다.

참고 항목

행 단위 바인딩을 사용할 때 애플리케이션이 설명자에 직접 쓰는 경우 길이 및 표시기 데이터에 별도의 필드를 사용할 수 있습니다.
SQL_ATTR_ROW_BIND_TYPE 문 특성을 단일 데이터 행을 포함하는 구조체의 크기 또는 결과 열이 바인딩될 버퍼 인스턴스의 크기로 설정합니다. 바운드 열의 주소가 지정된 길이로 증가하면 결과가 다음 행에서 동일한 열의 시작을 가리키도록 하려면 길이에 모든 바인딩된 열의 공백과 구조 또는 버퍼의 패딩이 포함되어야 합니다. ANSI C에서 sizeof 연산자를 사용하는 경우 이 동작이 보장됩니다.
바인딩할 각 열에 대해 다음 인수를 사용하여 SQLBindCol을 호출합니다.
- TargetType 은 열에 바인딩할 데이터 버퍼 멤버의 형식입니다.
- TargetValuePtr 은 첫 번째 배열 요소에 있는 데이터 버퍼 멤버의 주소입니다.
- BufferLength 는 데이터 버퍼 멤버의 크기입니다.
- StrLen_or_IndPtr 바인딩할 길이/표시기 멤버의 주소입니다.

이 정보를 사용하는 방법에 대한 자세한 내용은 이 섹션의 뒷부분에 있는 "버퍼 주소"를 참조하세요. 열 단위 바인딩에 대한 자세한 내용은 행 단위 바인딩을 참조하세요.

버퍼 주소

버퍼 주소는 데이터 또는 길이/표시기 버퍼의 실제 주소입니다. 드라이버는 버퍼에 쓰기 직전에 버퍼 주소를 계산합니다(예: 인출 시간 중). TargetValuePtr에 지정된 주소와 StrLen_or_IndPtr 인수, 바인딩 오프셋 및 행 번호를 사용하는 다음 수식에서 계산됩니다.

바인딩된 주소 + 바인딩 오프셋 + ((행 번호 - 1) x 요소 크기)

여기서 수식의 변수는 다음 표에 설명된 대로 정의됩니다.

변수	설명
바인딩된 주소	데이터 버퍼의 경우 SQLBindCol에서 TargetValuePtr 인수로 지정된 주소입니다. 길이/표시기 버퍼의 경우 SQLBindCol에서 StrLen_or_IndPtr 인수로 지정된 주소입니다. 자세한 내용은 "설명자 및 SQLBindCol" 섹션의 "추가 주석"을 참조하세요. 바인딩된 주소가 0이면 이전 수식에서 계산한 주소가 0이 아닌 경우에도 데이터 값이 반환되지 않습니다.
바인딩 오프셋	행 단위 바인딩을 사용하는 경우 SQL_ATTR_ROW_BIND_OFFSET_PTR 문 특성으로 지정된 주소에 저장된 값입니다. 열 단위 바인딩을 사용하거나 SQL_ATTR_ROW_BIND_OFFSET_PTR 문 특성의 값이 null 포인터 인 경우 Binding Offset 은 0입니다.
Row Number	행 집합에 있는 행의 1부터 시작하는 번호입니다. 기본값인 단일 행 페치의 경우 1입니다.
요소 크기	바인딩된 배열에 있는 요소의 크기입니다. 열 단위 바인딩을 사용하는 경우 길이/표시기 버퍼에 대한 sizeof(SQLINTEGER) 입니다. 데이터 버퍼의 경우 데이터 형식이 가변 길이인 경우 SQLBindCol의 BufferLength 인수 값이고 데이터 형식이 고정 길이인 경우 데이터 형식의 크기입니다. 행 단위 바인딩을 사용하는 경우 데이터 및 길이/표시기 버퍼 모두에 대한 SQL_ATTR_ROW_BIND_TYPE 문 특성의 값입니다.

설명자 및 SQLBindCol

다음 섹션에서는 SQLBindCol이 설명자와 상호 작용하는 방법을 설명합니다.

주의

한 문에 대해 SQLBindCol을 호출하면 다른 문에 영향을 줄 수 있습니다. 이 문제는 문과 연결된 ARD가 명시적으로 할당되고 다른 문과도 연결된 경우에 발생합니다. SQLBindCol은 설명자를 수정하므로 이 설명자가 연결된 모든 문에 수정 내용이 적용됩니다. 이 동작이 필수 동작이 아닌 경우 애플리케이션은 SQLBindCol을 호출하기 전에 다른 문에서 이 설명자를 분리해야 합니다.

인수 매핑

개념적으로 SQLBindCol 은 다음 단계를 순서대로 수행합니다.

SQLGetStmtAttr을 호출하여 ARD 핸들을 가져옵니다.
이 설명자의 SQL_DESC_COUNT 필드를 가져오기 위해 SQLGetDescField를 호출하고 ColumnNumber 인수의 값이 SQL_DESC_COUNT 값을 초과하는 경우 SQLSetDescField를 호출하여 SQL_DESC_COUNT 값을 ColumnNumber로 늘입니다.
SQLSetDescField를 여러 번 호출하여 ARD의 다음 필드에 값을 할당합니다.
- targetType이 날짜/시간 또는 간격 하위 형식의 간결한 식별자 중 하나인 경우 각각 SQL_DATETIME 또는 SQL_INTERVAL SQL_DESC_TYPE 설정하고, SQL_DESC_CONCISE_TYPE 간결한 식별자에 설정하고, SQL_DESC_DATETIME_INTERVAL_CODE 해당 날짜/시간 또는 간격 하위 코드로 설정한다는 점을 제외하고 SQL_DESC_TYPE 및 SQL_DESC_CONCISE_TYPE TargetType 값으로 설정합니다.
- TargetType에 적합한 하나 이상의 SQL_DESC_LENGTH, SQL_DESC_PRECISION, SQL_DESC_SCALE 및 SQL_DESC_DATETIME_INTERVAL_PRECISION 설정합니다.
- SQL_DESC_OCTET_LENGTH 필드를 BufferLength 값으로 설정합니다.
- SQL_DESC_DATA_PTR 필드를 TargetValuePtr 값으로 설정합니다.
- SQL_DESC_INDICATOR_PTR 필드를 StrLen_or_IndPtr 값으로 설정합니다. (다음 단락을 참조하세요.)
- SQL_DESC_OCTET_LENGTH_PTR 필드를 StrLen_or_IndPtr 값으로 설정합니다. (다음 단락을 참조하세요.)

StrLen_or_IndPtr 인수가 참조하는 변수는 표시기와 길이 정보 모두에 사용됩니다. 페치에서 열에 대한 null 값이 발견되면 이 변수에 SQL_NULL_DATA 저장합니다. 그렇지 않으면 이 변수에 데이터 길이를 저장합니다. null 포인터 를 StrLen_or_IndPtr 전달하면 페치 작업이 데이터 길이를 반환하지 않지만 null 값이 발생하고 SQL_NULL_DATA 반환할 방법이 없는 경우 인출이 실패합니다.

SQLBindCol에 대한 호출이 실패하면 ARD에서 설정한 설명자 필드의 콘텐츠가 정의되지 않고 ARD의 SQL_DESC_COUNT 필드 값이 변경되지 않습니다.

COUNT 필드의 암시적 재설정

SQLBindCol은 SQL_DESC_COUNT columnNumber 인수의 값으로 설정하며, 이 경우 SQL_DESC_COUNT 값이 증가합니다. TargetValuePtr 인수의 값이 null 포인터이고 ColumnNumber 인수의 값이 SQL_DESC_COUNT(즉, 가장 높은 바인딩된 열을 바인딩 해제하는 경우)인 경우 SQL_DESC_COUNT 가장 높은 나머지 바운드 열의 수로 설정됩니다.

SQL_DEFAULT 관련 주의 사항

열 데이터를 성공적으로 검색하려면 애플리케이션이 애플리케이션 버퍼에 있는 데이터의 길이와 시작점을 올바르게 결정해야 합니다. 애플리케이션이 명시적 TargetType을 지정하면 애플리케이션 오해가 쉽게 검색됩니다. 그러나 애플리케이션이 SQL_DEFAULT TargetType을 지정하는 경우 SQLBindCol은 메타데이터 변경에서 또는 코드를 다른 열에 적용하여 애플리케이션이 의도한 것과 다른 데이터 형식의 열에 적용할 수 있습니다. 이 경우 애플리케이션에서 가져온 열 데이터의 시작 또는 길이를 항상 결정하는 것은 아닙니다. 이로 인해 보고되지 않은 데이터 오류 또는 메모리 위반이 발생할 수 있습니다.

코드 예

다음 예제에서 애플리케이션은 Customers 테이블에서 SELECT 문을 실행하여 이름별로 정렬된 고객 ID, 이름 및 전화 번호의 결과 집합을 반환합니다. 그런 다음 SQLBindCol을 호출하여 데이터 열을 로컬 버퍼에 바인딩합니다. 마지막으로 애플리케이션은 SQLFetch를 사용하여 각 데이터 행을 가져오고 각 고객의 이름, ID 및 전화 번호를 출력합니다.

자세한 코드 예제는 SQLBulkOperations 함수, SQLColumns 함수, SQLFetchScroll 함수 및 SQLSetPos 함수를 참조하세요.

// SQLBindCol_ref.cpp  
// compile with: odbc32.lib  
#include <windows.h>  
#include <stdio.h>  
  
#define UNICODE  
#include <sqlext.h>  
  
#define NAME_LEN 50  
#define PHONE_LEN 60
  
void show_error() {  
   printf("error\n");  
}  
  
int main() {  
   SQLHENV henv;  
   SQLHDBC hdbc;  
   SQLHSTMT hstmt = 0;  
   SQLRETURN retcode;  
   SQLWCHAR szName[NAME_LEN], szPhone[PHONE_LEN], sCustID[NAME_LEN];  
   SQLLEN cbName = 0, cbCustID = 0, cbPhone = 0;  
  
   // Allocate environment handle  
   retcode = SQLAllocHandle(SQL_HANDLE_ENV, SQL_NULL_HANDLE, &henv);  
  
   // Set the ODBC version environment attribute  
   if (retcode == SQL_SUCCESS || retcode == SQL_SUCCESS_WITH_INFO) {  
      retcode = SQLSetEnvAttr(henv, SQL_ATTR_ODBC_VERSION, (SQLPOINTER*)SQL_OV_ODBC3, 0);   
  
      // Allocate connection handle  
      if (retcode == SQL_SUCCESS || retcode == SQL_SUCCESS_WITH_INFO) {  
         retcode = SQLAllocHandle(SQL_HANDLE_DBC, henv, &hdbc);  
  
         // Set login timeout to 5 seconds  
         if (retcode == SQL_SUCCESS || retcode == SQL_SUCCESS_WITH_INFO) {  
            SQLSetConnectAttr(hdbc, SQL_LOGIN_TIMEOUT, (SQLPOINTER)5, 0);  
  
            // Connect to data source  
            retcode = SQLConnect(hdbc, (SQLWCHAR*) L"NorthWind", SQL_NTS, (SQLWCHAR*) NULL, 0, NULL, 0);  
  
            // Allocate statement handle  
            if (retcode == SQL_SUCCESS || retcode == SQL_SUCCESS_WITH_INFO) {   
               retcode = SQLAllocHandle(SQL_HANDLE_STMT, hdbc, &hstmt);   
  
               retcode = SQLExecDirect(hstmt, (SQLWCHAR *) L"SELECT CustomerID, ContactName, Phone FROM CUSTOMERS ORDER BY 2, 1, 3", SQL_NTS);  
               if (retcode == SQL_SUCCESS || retcode == SQL_SUCCESS_WITH_INFO) {  
  
                  // Bind columns 1, 2, and 3  
                  retcode = SQLBindCol(hstmt, 1, SQL_C_WCHAR, &sCustID, 100, &cbCustID);  
                  retcode = SQLBindCol(hstmt, 2, SQL_C_WCHAR, szName, NAME_LEN, &cbName);  
                  retcode = SQLBindCol(hstmt, 3, SQL_C_WCHAR, szPhone, PHONE_LEN, &cbPhone);   
  
                  // Fetch and print each row of data. On an error, display a message and exit.  
                  for (int i=0 ; ; i++) {  
                     retcode = SQLFetch(hstmt);  
                     if (retcode == SQL_ERROR || retcode == SQL_SUCCESS_WITH_INFO)  
                        show_error();  
                     if (retcode == SQL_SUCCESS || retcode == SQL_SUCCESS_WITH_INFO)  
                     {
                        //replace wprintf with printf
                        //%S with %ls
                        //warning C4477: 'wprintf' : format string '%S' requires an argument of type 'char *'
                        //but variadic argument 2 has type 'SQLWCHAR *'
                        //wprintf(L"%d: %S %S %S\n", i + 1, sCustID, szName, szPhone);  
                        printf("%d: %ls %ls %ls\n", i + 1, sCustID, szName, szPhone);  
                    }    
                     else  
                        break;  
                  }  
               }  
  
               // Process data  
               if (retcode == SQL_SUCCESS || retcode == SQL_SUCCESS_WITH_INFO) {  
                  SQLCancel(hstmt);  
                  SQLFreeHandle(SQL_HANDLE_STMT, hstmt);  
               }  
  
               SQLDisconnect(hdbc);  
            }  
  
            SQLFreeHandle(SQL_HANDLE_DBC, hdbc);  
         }  
      }  
      SQLFreeHandle(SQL_HANDLE_ENV, henv);  
   }  
}

샘플 ODBC 프로그램도 참조하세요.

추가 정보	참조
결과 집합의 열에 대한 정보 반환	SQLDescribeCol 함수
데이터 블록을 가져오거나 결과 집합을 스크롤합니다.	SQLFetchScroll 함수
여러 행의 데이터 가져오기	SQLFetch 함수
문에서 열 버퍼 해제	SQLFreeStmt 함수
데이터 열의 일부 또는 전체 가져오기	SQLGetData 함수
결과 집합 열 수 반환	SQLNumResultCols 함수

참고 항목

ODBC API 참조
ODBC 헤더 파일

다음을 통해 공유

SQLBindCol 함수

구문

인수

반품

진단

주석

바인딩, 바인딩 해제 및 열 다시 바인딩

열 바인딩

열 바인딩 해제

열 다시 바인딩

바인딩 오프셋

바인딩 배열

열 단위 바인딩

행 단위 바인딩

버퍼 주소

설명자 및 SQLBindCol

인수 매핑

COUNT 필드의 암시적 재설정

SQL_DEFAULT 관련 주의 사항

코드 예

참고 항목

피드백

추가 리소스

다음을 통해 공유

SQLBindCol 함수

구문

인수

반품

진단

주석

바인딩, 바인딩 해제 및 열 다시 바인딩

열 바인딩

열 바인딩 해제

열 다시 바인딩

바인딩 오프셋

바인딩 배열

열 단위 바인딩

행 단위 바인딩

버퍼 주소

설명자 및 SQLBindCol

인수 매핑

COUNT 필드의 암시적 재설정

SQL_DEFAULT 관련 주의 사항

코드 예

관련 함수

참고 항목

피드백

추가 리소스