Функция SQLDescribeParam
Соответствие
Представлена версия: соответствие стандартам ODBC 1.0: ODBC
Сводка
SQLDescribeParam возвращает описание маркера параметра, связанного с подготовленной инструкцией SQL. Эти сведения также доступны в полях IPD.
Синтаксис
SQLRETURN SQLDescribeParam(
SQLHSTMT StatementHandle,
SQLUSMALLINT ParameterNumber,
SQLSMALLINT * DataTypePtr,
SQLULEN * ParameterSizePtr,
SQLSMALLINT * DecimalDigitsPtr,
SQLSMALLINT * NullablePtr);
Аргументы
ОператорHandle
[Входные данные] Дескриптор инструкции.
ПараметрNumber
[Входные данные] Номер маркера параметра упорядочивался последовательно в порядке увеличения порядка параметров, начиная с 1.
DataTypePtr
[Выходные данные] Указатель на буфер, в котором возвращается тип данных SQL параметра. Это значение считывается из поля записи SQL_DESC_CONCISE_TYPE IPD. Это будет одно из значений в разделе "Типы данных SQL" приложения D: Типы данных или тип данных 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 driver.
Если columnNumber равно 0 (для столбца закладки), SQL_BINARY возвращается в *DataTypePtr для закладок переменной длины. (SQL_INTEGER возвращается, если закладки используются ODBC 3.приложение x , работающее с ODBC 2.драйвер x или ODBC 2.приложение x , работающее с ODBC 3.x driver.)
Дополнительные сведения см . в разделе "Типы данных SQL" в приложении D: Типы данных. Сведения о типах данных SQL для конкретного драйвера см. в документации по драйверу.
ParameterSizePtr
[Выходные данные] Указатель на буфер, в котором возвращается размер в символах столбца или выражения соответствующего маркера параметра, определенного источником данных. Дополнительные сведения о размере столбца см. в разделе "Размер столбца", "Десятичные цифры", " Длина октета" и "Размер отображения".
DecimalDigitsPtr
[Выходные данные] Указатель на буфер, в котором возвращается число десятичных цифр столбца или выражения соответствующего параметра, определенного источником данных. Дополнительные сведения о десятичных цифрах см. в разделе "Размер столбца", "Десятичные цифры", " Длина октета" и "Размер отображения".
NullablePtr
[Выходные данные] Указатель на буфер, в котором возвращается значение, указывающее, допускает ли параметр значения NULL. Это значение считывается из поля SQL_DESC_NULLABLE IPD. Один из следующих:
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, связанное значение SQLSTATE можно получить путем вызова SQLGetDiagRec с помощью HandleType SQL_HANDLE_STMT и handle of StatementHandle. В следующей таблице перечислены значения SQLSTATE, которые обычно возвращаются SQLDescribeParam и объясняются каждый из них в контексте этой функции. Нотация "(DM)" предшествует описаниям SQLSTATEs, возвращаемым диспетчером драйверов. Возвращаемый код, связанный с каждым значением SQLSTATE, SQL_ERROR, если не указано иное.
| SQLSTATE | Ошибка | Описание |
|---|---|---|
| 01000 | Общее предупреждение | Информационное сообщение для конкретного драйвера. (Функция возвращает SQL_SUCCESS_WITH_INFO.) |
| 07009 | Недопустимый индекс дескриптора | (DM) Значение, указанное для аргумента ParameterNumber , меньше 1. Значение, указанное для аргумента ParameterNumber , больше количества параметров в связанной инструкции SQL. Маркер параметра был частью инструкции, отличной от DML. Маркер параметра был частью списка SELECT . |
| 08S01 | Сбой связи | Связь между драйвером и источником данных, к которому был подключен драйвер, произошел сбой до завершения обработки функции. |
| 21S01 | Список вставок значений не соответствует списку столбцов | Количество параметров в инструкции INSERT не соответствовало количеству столбцов в таблице с именем в инструкции. |
| HY000 | Общая ошибка | Произошла ошибка, для которой не было определенного SQLSTATE и для которого не было определено значение SQLSTATE для конкретной реализации. Сообщение об ошибке, возвращаемое SQLGetDiagRec в буфере *MessageText , описывает ошибку и ее причину. |
| HY001 | Ошибка выделения памяти | Драйверу не удалось выделить память, необходимую для поддержки выполнения или завершения функции. |
| HY008 | Операция отменена | Асинхронная обработка была включена для ОператораHandle. Функция была вызвана и до завершения выполнения, SQLCancel или SQLCancelHandle была вызвана на ОператорHandle. Затем функция снова была вызвана на ОператорHandle. Функция была вызвана и до завершения выполнения SQLCancel или SQLCancelHandle была вызвана оператором StatementHandle из другого потока в многопотоковом приложении. |
| HY010 | Ошибка последовательности функций | (DM) Функция была вызвана перед вызовом SQLPrepare или SQLExecDirect для StatementHandle. (DM) Асинхронно выполняющаяся функция была вызвана для дескриптора соединения, связанного с ОператоромHandle. Эта асинхронная функция по-прежнему выполнялась при вызове функции SQLDescribeParam . (DM) асинхронно выполняющаяся функция (не эта) была вызвана для StatementHandle и по-прежнему выполнялась при вызове этой функции. (DM) SQLExecute, SQLExecDirect, SQLBulkOperations или SQLSetPos были вызваны для ОператораHandle и возвращены SQL_NEED_DATA. Эта функция была вызвана до отправки данных для всех параметров выполнения или столбцов. |
| HY013 | Ошибка управления памятью | Не удалось обработать вызов функции, так как к базовым объектам памяти не удалось получить доступ, возможно, из-за низкой памяти. |
| HY117 | Подключение приостановлено из-за неизвестного состояния транзакции. Разрешены только функции отключения и только для чтения. | (DM) Дополнительные сведения о приостановленном состоянии см. в статье SQLEndTran Function. |
| HYT01 | Время ожидания для подключения истекло | Срок ожидания подключения истек до того, как источник данных ответил на запрос. Период времени ожидания подключения задается через SQLSetConnectAttr SQL_ATTR_CONNECTION_TIMEOUT. |
| IM001 | Драйвер не поддерживает эту функцию | (DM) Драйвер, связанный с StatementHandle , не поддерживает функцию. |
| IM017 | Опрос отключен в асинхронном режиме уведомлений | При использовании модели уведомлений опрос отключается. |
| IM018 | SQLCompleteAsync не был вызван для выполнения предыдущей асинхронной операции с этим дескриптором. | Если предыдущий вызов функции дескриптора возвращает SQL_STILL_EXECUTING и если включен режим уведомлений, sqlCompleteAsync должен вызываться на дескрипторе для выполнения последующей обработки и завершения операции. |
Комментарии
Маркеры параметров нумеруются в порядке увеличения порядка параметров, начиная с 1, в том порядке, в котором они отображаются в инструкции SQL.
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 |