SQLSetDescRec 함수
규칙
도입된 버전: ODBC 3.0 표준 준수: ISO 92
요약
SQLSetDescRec 함수는 열 또는 매개 변수 데이터에 바인딩된 데이터 형식 및 버퍼에 영향을 주는 여러 설명자 필드를 설정합니다.
구문
SQLRETURN SQLSetDescRec(
SQLHDESC DescriptorHandle,
SQLSMALLINT RecNumber,
SQLSMALLINT Type,
SQLSMALLINT SubType,
SQLLEN Length,
SQLSMALLINT Precision,
SQLSMALLINT Scale,
SQLPOINTER DataPtr,
SQLLEN * StringLengthPtr,
SQLLEN * IndicatorPtr);
인수
DescriptorHandle
[입력] 설명자 핸들입니다. IRD 핸들이 아니어야 합니다.
RecNumber
[입력] 설정할 필드가 포함된 설명자 레코드를 나타냅니다. 설명자 레코드는 0부터 번호가 매겨지고 레코드 번호 0은 책갈피 레코드입니다. 이 인수는 0보다 크거나 같아야 합니다. RecNumber가 SQL_DESC_COUNT 값보다 크면 SQL_DESC_COUNTis RecNumber 값으로 변경됩니다.
Type
[입력] 설명자 레코드의 SQL_DESC_TYPE 필드를 설정할 값입니다.
SubType
[입력] 형식이 SQL_DATETIME 또는 SQL_INTERVAL 레코드의 경우 SQL_DESC_DATETIME_INTERVAL_CODE 필드를 설정할 값입니다.
길이
[입력] 설명자 레코드의 SQL_DESC_OCTET_LENGTH 필드를 설정할 값입니다.
정밀도
[입력] 설명자 레코드의 SQL_DESC_PRECISION 필드를 설정할 값입니다.
스케일
[입력] 설명자 레코드의 SQL_DESC_SCALE 필드를 설정할 값입니다.
DataPtr
[지연된 입력 또는 출력] 설명자 레코드의 SQL_DESC_DATA_PTR 필드를 설정할 값입니다. DataPtr은 null 포인터로 설정할 수 있습니다.
DataPtr 인수를 null 포인터로 설정하여 SQL_DESC_DATA_PTR 필드를 null 포인터로 설정할 수 있습니다. DescriptorHandle 인수의 핸들이 ARD와 연결된 경우 열을 바인딩 해제합니다.
StringLengthPtr
[지연된 입력 또는 출력] 설명자 레코드의 SQL_DESC_OCTET_LENGTH_PTR 필드를 설정할 값입니다. StringLengthPtr 을 null 포인터로 설정하여 SQL_DESC_OCTET_LENGTH_PTR 필드를 null 포인터로 설정할 수 있습니다.
IndicatorPtr
[지연된 입력 또는 출력] 설명자 레코드의 SQL_DESC_INDICATOR_PTR 필드를 설정할 값입니다. IndicatorPtr 을 null 포인터로 설정하여 SQL_DESC_INDICATOR_PTR 필드를 null 포인터로 설정할 수 있습니다.
반품
SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR 또는 SQL_INVALID_HANDLE.
진단
SQLSetDescRec가 SQL_ERROR 또는 SQL_SUCCESS_WITH_INFO 반환하는 경우 SQL_HANDLE_DESC HandleType 및 DescriptorHandle 핸들을 사용하여 SQLGetDiagRec 를 호출하여 관련 SQLSTATE 값을 가져올 수 있습니다. 다음 표에서는 SQLSetDescRec에서 일반적으로 반환되는 SQLSTATE 값을 나열하고 이 함수의 컨텍스트에서 각각에 대해 설명합니다. 표기법 "(DM)"은 드라이버 관리자가 반환한 SQLSTATE에 대한 설명 앞에 나와 있습니다. 달리 명시되지 않는 한 각 SQLSTATE 값과 연결된 반환 코드는 SQL_ERROR.
| SQLSTATE | Error | 설명 |
|---|---|---|
| 01000 | 일반 경고 | 드라이버 관련 정보 메시지입니다. 함수는 SQL_SUCCESS_WITH_INFO 반환합니다. |
| 07009 | 설명자 인덱스가 잘못되었습니다. | RecNumber 인수가 0으로 설정되었고 DescriptorHandle이 IPD 핸들을 참조했습니다. RecNumber 인수가 0보다 작습니다. RecNumber 인수가 데이터 원본에서 지원할 수 있는 최대 열 또는 매개 변수 수보다 크고 DescriptorHandle 인수는 APD, IPD 또는 ARD였습니다. RecNumber 인수는 0과 같고 DescriptorHandle 인수는 암시적으로 할당된 APD를 참조했습니다. (이 오류는 명시적으로 할당된 애플리케이션 설명자가 실행 시간까지 APD 또는 ARD인지 여부를 알 수 없으므로 명시적으로 할당된 애플리케이션 설명자에서 발생하지 않습니다.) |
| 08S01 | 통신 링크 실패 | 드라이버와 드라이버가 연결된 데이터 원본 간의 통신 링크는 함수가 처리를 완료하기 전에 실패했습니다. |
| HY000 | 일반 오류 | 특정 SQLSTATE가 없고 구현별 SQLSTATE가 정의되지 않은 오류가 발생했습니다. *MessageText 버퍼의 SQLGetDiagRec에서 반환된 오류 메시지는 오류와 그 원인을 설명합니다. |
| HY001 | 메모리 할당 오류 | 드라이버가 함수 실행 또는 완료를 지원하는 데 필요한 메모리를 할당할 수 없습니다. |
| HY010 | 함수 시퀀스 오류 | (DM) DescriptorHandle은 비동기 실행 함수(이 함수가 아님)가 호출되고 이 함수가 호출될 때 여전히 실행 중인 StatementHandle과 연결되었습니다. (DM) DescriptorHandle이 연결되고 SQL_NEED_DATA 반환된 StatementHandle에 대해 SQLExecute, SQLExecDirect, SQLBulkOperations 또는 SQLSetPos가 호출되었습니다. 이 함수는 모든 실행 시 데이터 매개 변수 또는 열에 대한 데이터를 보내기 전에 호출되었습니다. (DM) DescriptorHandle과 연결된 연결 핸들에 대해 비동기적으로 실행되는 함수가 호출되었습니다. 이 비동기 함수는 SQLSetDescRec 함수가 호출되었을 때 계속 실행되었습니다. (DM) SQLExecute, SQLExecDirect 또는 SQLMoreResults는 DescriptorHandle과 연결된 문 핸들 중 하나에 대해 호출되고 SQL_PARAM_DATA_AVAILABLE 반환되었습니다. 이 함수는 모든 스트리밍된 매개 변수에 대해 데이터를 검색하기 전에 호출되었습니다. |
| HY013 | 메모리 관리 오류 | 메모리 조건이 낮기 때문에 기본 메모리 개체에 액세스할 수 없기 때문에 함수 호출을 처리할 수 없습니다. |
| HY016 | 구현 행 설명자를 수정할 수 없음 | DescriptorHandle 인수가 IRD와 연결되었습니다. |
| HY021 | 일관되지 않은 설명자 정보 | 형식 필드 또는 설명자의 SQL_DESC_TYPE 필드와 연결된 다른 필드가 잘못되었거나 일관되지 않았습니다. 일관성 검사 중에 확인된 설명자 정보가 일관되지 않았습니다. (이 섹션의 뒷부분에 있는 "일관성 검사"를 참조하세요.) |
| HY090 | 잘못된 문자열 또는 버퍼 길이 | (DM) 드라이버가 ODBC 2.x 드라이버이고, 설명자가 ARD이고, ColumnNumber 인수가 0으로 설정되었으며, BufferLength 인수에 지정된 값이 4와 같지 않습니다. |
| HY117 | 알 수 없는 트랜잭션 상태로 인해 연결이 일시 중단됩니다. 연결 끊기 및 읽기 전용 함수만 허용됩니다. | (DM) 일시 중단 상태에 대한 자세한 내용은 SQLEndTran 함수를 참조 하세요. |
| HYT01 | 연결 제한 시간이 만료됨 | 데이터 원본이 요청에 응답하기 전에 연결 제한 시간이 만료되었습니다. 연결 제한 시간은 SQL_ATTR_CONNECTION_TIMEOUT SQLSetConnectAttr를 통해 설정됩니다. |
| IM001 | 드라이버는 이 함수를 지원하지 않습니다. | (DM) DescriptorHandle과 연결된 드라이버는 함수를 지원하지 않습니다. |
주석
애플리케이션은 SQLSetDescRec를 호출하여 단일 열 또는 매개 변수에 대해 다음 필드를 설정할 수 있습니다.
SQL_DESC_TYPE
SQL_DESC_DATETIME_INTERVAL_CODE(형식이 SQL_DATETIME 또는 SQL_INTERVAL 레코드의 경우)
SQL_DESC_OCTET_LENGTH
SQL_DESC_PRECISION
SQL_DESC_SCALE
SQL_DESC_DATA_PTR
SQL_DESC_OCTET_LENGTH_PTR
SQL_DESC_INDICATOR_PTR
참고 항목
SQLSetDescRec에 대한 호출이 실패하면 RecNumber 인수로 식별된 설명자 레코드의 내용이 정의되지 않습니다.
열 또는 매개 변수를 바인딩할 때 SQLSetDescRec를 사용하면 SQLBindCol 또는 SQLBindParameter를 호출하거나 SQLSetDescField를 여러 개 호출하지 않고 바인딩에 영향을 주는 여러 필드를 변경할 수 있습니다. SQLSetDescRec 는 현재 문과 연결되지 않은 설명자에 필드를 설정할 수 있습니다. SQLBindParameter는 SQLSetDescRec보다 더 많은 필드를 설정하고, APD와 IPD에 대한 필드를 한 번의 호출로 설정할 수 있으며, 설명자 핸들이 필요하지 않습니다.
참고 항목
책갈피 필드를 설정하려면 RecNumber 인수가 0인 SQLSetDescRec를 호출하기 전에 문 특성 SQL_ATTR_USE_BOOKMARKS 항상 설정해야 합니다. 필수는 아니지만 권장됩니다.
일관성 검사
애플리케이션이 APD, ARD 또는 IPD의 SQL_DESC_DATA_PTR 필드를 설정하면 드라이버에서 일관성 검사를 자동으로 수행합니다. 필드가 다른 필드 와 일치하지 않는 경우 SQLSetDescRec 는 SQLSTATE HY021(일관성 없는 설명자 정보)을 반환합니다.
애플리케이션이 APD, ARD 또는 IPD의 SQL_DESC_DATA_PTR 필드를 설정할 때마다 드라이버는 SQL_DESC_TYPE 필드의 값과 해당 SQL_DESC_TYPE 필드에 적용할 수 있는 값이 유효하고 일관적인지 확인합니다. 이 검사는 SQLBindParameter 또는 SQLBindCol이 호출되거나 APD, ARD 또는 IPD에 대해 SQLSetDescRec가 호출될 때 항상 수행됩니다. 이 일관성 검사에는 설명자 필드에 대한 다음 검사가 포함됩니다.
SQL_DESC_TYPE 필드는 유효한 ODBC C 또는 SQL 형식 또는 드라이버별 SQL 형식 중 하나여야 합니다. SQL_DESC_CONCISE_TYPE 필드는 간결한 날짜/시간 및 간격 형식을 포함하여 유효한 ODBC C 또는 SQL 형식 또는 드라이버별 C 또는 SQL 형식 중 하나여야 합니다.
SQL_DESC_TYPE 레코드 필드가 SQL_DATETIME 또는 SQL_INTERVAL 경우 SQL_DESC_DATETIME_INTERVAL_CODE 필드는 유효한 날짜/시간 또는 간격 코드 중 하나여야 합니다. (에서 SQL_DESC_DATETIME_INTERVAL_CODE 필드에 대한 설명을 참조하세요. SQLSetDescField.)
SQL_DESC_TYPE 필드에 숫자 형식이 표시되면 SQL_DESC_PRECISION 및 SQL_DESC_SCALE 필드가 유효한 것으로 확인됩니다.
SQL_DESC_CONCISE_TYPE 필드가 시간 또는 타임스탬프 데이터 형식, 초 구성 요소가 있는 간격 형식 또는 시간 구성 요소가 있는 간격 데이터 형식 중 하나인 경우 SQL_DESC_PRECISION 필드는 유효한 초 정밀도로 확인됩니다.
SQL_DESC_CONCISE_TYPE 간격 데이터 형식인 경우 SQL_DESC_DATETIME_INTERVAL_PRECISION 필드가 올바른 간격 선행 전체 자릿수 값으로 확인됩니다.
IPD의 SQL_DESC_DATA_PTR 필드는 일반적으로 설정되지 않습니다. 그러나 애플리케이션은 IPD 필드의 일관성 검사를 강제로 수행할 수 있습니다. IRD에서는 일관성 검사를 수행할 수 없습니다. IPD의 SQL_DESC_DATA_PTR 필드가 설정된 값은 실제로 저장되지 않으며 SQLGetDescField 또는 SQLGetDescRec를 호출하여 검색할 수 없습니다. 이 설정은 일관성 검사를 강제하기 위해서만 이루어집니다.
관련 함수
| 추가 정보 | 참조 |
|---|---|
| 열 바인딩 | SQLBindCol 함수 |
| 매개 변수 바인딩 | SQLBindParameter 함수 |
| 단일 설명자 필드 가져오기 | SQLGetDescField 함수 |
| 여러 설명자 필드 가져오기 | SQLGetDescRec 함수 |
| 단일 설명자 필드 설정 | SQLSetDescField 함수 |