Функция 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, если не указано иное.

Комментарии

Маркеры параметров нумеруются в порядке увеличения порядка параметров, начиная с 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);  

Связанные функции

См. также

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