Функция 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 должен вызываться на дескрипторе для выполнения последующей обработки и завершения операции.

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

См. также

Справочник по API ODBC
Файлы заголовков ODBC

Кері байланыс

Бет пайдалы болды ма?

Last updated on 2025-01-02

Бөлісу құралы: