SQLDescribeParam 함수
규칙
도입된 버전: ODBC 1.0 표준 준수: ODBC
요약
SQLDescribeParam 은 준비된 SQL 문과 연결된 매개 변수 표식에 대한 설명을 반환합니다. 이 정보는 IPD의 필드에서도 사용할 수 있습니다.
구문
SQLRETURN SQLDescribeParam(
SQLHSTMT StatementHandle,
SQLUSMALLINT ParameterNumber,
SQLSMALLINT * DataTypePtr,
SQLULEN * ParameterSizePtr,
SQLSMALLINT * DecimalDigitsPtr,
SQLSMALLINT * NullablePtr);
인수
StatementHandle
[입력] 문 핸들입니다.
ParameterNumber
[입력] 매개 변수 표식 번호는 1부터 시작하여 증가하는 매개 변수 순서로 순차적으로 정렬됩니다.
DataTypePtr
[출력] 매개 변수의 SQL 데이터 형식을 반환할 버퍼에 대한 포인터입니다. 이 값은 IPD의 SQL_DESC_CONCISE_TYPE 레코드 필드에서 읽습니다. 부록 D: 데이터 형식 또는 드라이버별 SQL 데이터 형식의 SQL 데이터 형식 섹션에 있는 값 중 하나입니다.
ODBC 3에서.x, SQL_TYPE_DATE, SQL_TYPE_TIME 또는 SQL_TYPE_TIMESTAMP 각각 날짜, 시간 또는 타임스탬프 데이터에 대해 *DataTypePtr로 반환되고 ODBC 2에서는 반환됩니다.x, SQL_DATE, SQL_TIME 또는 SQL_TIMESTAMP 반환됩니다. 드라이버 관리자는 ODBC 2일 때 필요한 매핑을 수행합니다.x 애플리케이션이 ODBC 3에서 작동합니다.x 드라이버 또는 ODBC 3인 경우x 애플리케이션이 ODBC 2에서 작동합니다.x 드라이버입니다.
ColumnNumber가 책갈피 열의 경우 0과 같으면 변수 길이 책갈피의 경우 *DataTypePtr에 SQL_BINARY 반환됩니다. (SQL_INTEGER ODBC 3에서 책갈피를 사용하는 경우 반환됩니다.ODBC 2를 사용하는 x 애플리케이션입니다.x 드라이버 또는 ODBC 2.ODBC 3을 사용하는 x 애플리케이션입니다.x driver.)
자세한 내용은 부록 D: 데이터 형식의 SQL 데이터 형식을 참조하세요. 드라이버별 SQL 데이터 형식에 대한 자세한 내용은 드라이버 설명서를 참조하세요.
ParameterSizePtr
[출력] 데이터 원본에서 정의한 대로 해당 매개 변수 표식의 열 또는 식 크기를 문자 단위로 반환할 버퍼에 대한 포인터입니다. 열 크기에 대한 자세한 내용은 열 크기, 10진수, 8진수 길이 전송 및 표시 크기를 참조 하세요.
DecimalDigitsPtr
[출력] 데이터 원본에서 정의한 대로 해당 매개 변수의 열 또는 식의 10진수 수를 반환할 버퍼에 대한 포인터입니다. 10진수에 대한 자세한 내용은 열 크기, 10진수, 8진수 길이 전송 및 표시 크기를 참조하세요.
NullablePtr
[출력] 매개 변수에서 NULL 값을 허용하는지 여부를 나타내는 값을 반환할 버퍼에 대한 포인터입니다. 이 값은 IPD의 SQL_DESC_NULLABLE 필드에서 읽습니다. (다음 버전 중 하나)
SQL_NO_NULLS: 매개 변수는 NULL 값을 허용하지 않습니다(기본값).
SQL_NULLABLE: 매개 변수는 NULL 값을 허용합니다.
SQL_NULLABLE_UNKNOWN: 드라이버는 매개 변수가 NULL 값을 허용하는지 여부를 확인할 수 없습니다.
반품
SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_STILL_EXECUTING, SQL_ERROR 또는 SQL_INVALID_HANDLE.
진단
SQLDescribeParam이 SQL_ERROR 또는 SQL_SUCCESS_WITH_INFO 반환하는 경우 SQL_HANDLE_STMT HandleType 및 Handle of StatementHandle을 사용하여 SQLGetDiagRec 를 호출하여 관련 SQLSTATE 값을 가져올 수 있습니다. 다음 표에서는 일반적으로 SQLDescribeParam에서 반환되는 SQLSTATE 값을 나열하고 이 함수의 컨텍스트에서 각각에 대해 설명합니다. 표기법 "(DM)"은 드라이버 관리자가 반환한 SQLSTATE에 대한 설명 앞에 나와 있습니다. 달리 명시되지 않는 한 각 SQLSTATE 값과 연결된 반환 코드는 SQL_ERROR.
| SQLSTATE | 오류 | 설명 |
|---|---|---|
| 01000 | 일반 경고 | 드라이버 관련 정보 메시지입니다. 함수는 SQL_SUCCESS_WITH_INFO 반환합니다. |
| 07009 | 설명자 인덱스가 잘못되었습니다. | (DM) ParameterNumber 인수에 지정된 값이 1보다 작습니다. ParameterNumber 인수에 지정된 값이 연결된 SQL 문의 매개 변수 수보다 큽니다. 매개 변수 표식은 비 DML 문의 일부였습니다. 매개 변수 표식이 SELECT 목록의 일부였습니다. |
| 08S01 | 통신 링크 실패 | 드라이버와 드라이버가 연결된 데이터 원본 간의 통신 링크는 함수가 처리를 완료하기 전에 실패했습니다. |
| 21S01 | 값 삽입 목록이 열 목록과 일치하지 않음 | INSERT 문의 매개 변수 수가 문에 이름이 지정된 테이블의 열 수와 일치하지 않습니다. |
| HY000 | 일반 오류 | 특정 SQLSTATE가 없고 구현별 SQLSTATE가 정의되지 않은 오류가 발생했습니다. *MessageText 버퍼의 SQLGetDiagRec에서 반환된 오류 메시지는 오류와 그 원인을 설명합니다. |
| HY001 | 메모리 할당 오류 | 드라이버가 함수 실행 또는 완료를 지원하는 데 필요한 메모리를 할당할 수 없습니다. |
| HY008 | 작업이 취소됨 | StatementHandle에 대해 비동기 처리를 사용하도록 설정했습니다. 함수가 호출되었고 실행이 완료되기 전에 StatementHandle에서 SQLCancel 또는 SQLCancelHandle이 호출되었습니다. 그런 다음 StatementHandle에서 함수가 다시 호출되었습니다. 함수가 호출되었고 실행을 완료하기 전에 다중 스레드 애플리케이션의 다른 스레드에서 StatementHandle에서 SQLCancel 또는 SQLCancelHandle이 호출되었습니다. |
| HY010 | 함수 시퀀스 오류 | (DM) 이 함수는 StatementHandle에 대해 SQLPrepare 또는 SQLExecDirect를 호출하기 전에 호출되었습니다. (DM) StatementHandle과 연결된 연결 핸들에 대해 비동기적으로 실행되는 함수가 호출되었습니다. SQLDescribeParam 함수가 호출되었을 때 이 비동기 함수는 여전히 실행 중입니다. (DM) 이 함수가 아닌 비동기 실행 함수가 StatementHandle에 대해 호출되었고 이 함수가 호출되었을 때 계속 실행되고 있었습니다. (DM) SQLExecute, SQLExecDirect, SQLBulkOperations 또는 SQLSetPos가 StatementHandle에 대해 호출되고 SQL_NEED_DATA 반환되었습니다. 이 함수는 모든 실행 시 데이터 매개 변수 또는 열에 대한 데이터를 보내기 전에 호출되었습니다. |
| HY013 | 메모리 관리 오류 | 메모리 조건이 낮기 때문에 기본 메모리 개체에 액세스할 수 없기 때문에 함수 호출을 처리할 수 없습니다. |
| HY117 | 알 수 없는 트랜잭션 상태로 인해 연결이 일시 중단됩니다. 연결 끊기 및 읽기 전용 함수만 허용됩니다. | (DM) 일시 중단 상태에 대한 자세한 내용은 SQLEndTran 함수를 참조 하세요. |
| HYT01 | 연결 제한 시간이 만료됨 | 데이터 원본이 요청에 응답하기 전에 연결 제한 시간이 만료되었습니다. 연결 제한 시간은 SQL_ATTR_CONNECTION_TIMEOUT SQLSetConnectAttr를 통해 설정됩니다. |
| IM001 | 드라이버는 이 함수를 지원하지 않습니다. | (DM) StatementHandle과 연결된 드라이버는 함수를 지원하지 않습니다. |
| IM017 | 비동기 알림 모드에서 폴링을 사용할 수 없습니다. | 알림 모델을 사용할 때마다 폴링이 비활성화됩니다. |
| IM018 | 이 핸들에서 이전 비동기 작업을 완료하기 위해 SQLCompleteAsync 가 호출되지 않았습니다. | 핸들의 이전 함수 호출이 SQL_STILL_EXECUTING 반환하고 알림 모드가 활성화된 경우 사후 처리를 수행하고 작업을 완료하려면 핸들에서 SQLCompleteAsync 를 호출해야 합니다. |
설명
매개 변수 표식은 SQL 문에 나타나는 순서대로 1부터 시작하여 증가하는 매개 변수 순서로 번호가 매겨집니다.
SQLDescribeParam 은 SQL 문에서 매개 변수의 형식(입력, 입력/출력 또는 출력)을 반환하지 않습니다. 프로시저 호출을 제외하고 SQL 문의 모든 매개 변수는 입력 매개 변수입니다. 프로시저 호출에서 각 매개 변수의 형식을 확인하기 위해 애플리케이션은 SQLProcedureColumns를 호출 합니다.
자세한 내용은 매개 변수 설명을 참조 하세요.
코드 예
다음 예제에서는 사용자에게 SQL 문을 묻는 메시지를 표시한 다음 해당 문을 준비합니다. 다음으로 SQLNumParams를 호출하여 문에 매개 변수가 포함되어 있는지 여부를 확인합니다. 문에 매개 변수가 포함된 경우 SQLDescribeParam을 호출하여 해당 매개 변수를 설명하고 SQLBindParameter를 호출하여 바인딩합니다. 마지막으로 사용자에게 매개 변수 값을 묻는 메시지를 표시한 다음 문을 실행합니다.
SQLCHAR Statement[100];
SQLSMALLINT NumParams, i, DataType, DecimalDigits, Nullable;
SQLUINTEGER ParamSize;
SQLHSTMT hstmt;
// Prompt the user for a SQL statement and prepare it.
GetSQLStatement(Statement);
SQLPrepare(hstmt, Statement, SQL_NTS);
// Check to see if there are any parameters. If so, process them.
SQLNumParams(hstmt, &NumParams);
if (NumParams) {
// Allocate memory for three arrays. The first holds pointers to buffers in which
// each parameter value will be stored in character form. The second contains the
// length of each buffer. The third contains the length/indicator value for each
// parameter.
SQLPOINTER * PtrArray = (SQLPOINTER *) malloc(NumParams * sizeof(SQLPOINTER));
SQLINTEGER * BufferLenArray = (SQLINTEGER *) malloc(NumParams * sizeof(SQLINTEGER));
SQLINTEGER * LenOrIndArray = (SQLINTEGER *) malloc(NumParams * sizeof(SQLINTEGER));
for (i = 0; i < NumParams; i++) {
// Describe the parameter.
SQLDescribeParam(hstmt, i + 1, &DataType, &ParamSize, &DecimalDigits, &Nullable);
// Call a helper function to allocate a buffer in which to store the parameter
// value in character form. The function determines the size of the buffer from
// the SQL data type and parameter size returned by SQLDescribeParam and returns
// a pointer to the buffer and the length of the buffer.
AllocParamBuffer(DataType, ParamSize, &PtrArray[i], &BufferLenArray[i]);
// Bind the memory to the parameter. Assume that we only have input parameters.
SQLBindParameter(hstmt, i + 1, SQL_PARAM_INPUT, SQL_C_CHAR, DataType, ParamSize,
DecimalDigits, PtrArray[i], BufferLenArray[i],
&LenOrIndArray[i]);
// Prompt the user for the value of the parameter and store it in the memory
// allocated earlier. For simplicity, this function does not check the value
// against the information returned by SQLDescribeParam. Instead, the driver does
// this when the statement is executed.
GetParamValue(PtrArray[i], BufferLenArray[i], &LenOrIndArray[i]);
}
}
// Execute the statement.
SQLExecute(hstmt);
// Process the statement further, such as retrieving results (if any) and closing the
// cursor (if any). Code not shown.
// Free the memory allocated for each parameter and the memory allocated for the arrays
// of pointers, buffer lengths, and length/indicator values.
for (i = 0; i < NumParams; i++) free(PtrArray[i]);
free(PtrArray);
free(BufferLenArray);
free(LenOrIndArray);
관련 함수
| 추가 정보 | 참조 |
|---|---|
| 매개 변수에 버퍼 바인딩 | SQLBindParameter 함수 |
| 문 처리 취소 | SQLCancel 함수 |
| 준비된 SQL 문 실행 | SQLExecute 함수 |
| 실행을 위한 문 준비 | SQLPrepare 함수 |