Функция SQLGetData

Соответствие
Представлена версия: соответствие стандартам ODBC 1.0: ISO 92

Сводка
SQLGetData извлекает данные для одного столбца в результирующем наборе или для одного параметра после того, как SQLParamData возвращает SQL_PARAM_DATA_AVAILABLE. Его можно вызывать несколько раз, чтобы получить данные переменной длины в частях.

Синтаксис

  
SQLRETURN SQLGetData(  
      SQLHSTMT       StatementHandle,  
      SQLUSMALLINT   Col_or_Param_Num,  
      SQLSMALLINT    TargetType,  
      SQLPOINTER     TargetValuePtr,  
      SQLLEN         BufferLength,  
      SQLLEN *       StrLen_or_IndPtr);  

Аргументы

ОператорHandle
[Входные данные] Дескриптор инструкции.

Col_or_Param_Num
[Входные данные] Для получения данных столбца это число столбцов, для которого будут возвращены данные. Столбцы результирующего набора нумеруются в увеличении порядка столбцов, начиная с 1. Столбец закладки имеет номер 0; это можно указать только в том случае, если включены закладки.

Для получения данных параметров это порядковый номер параметра, который начинается с 1.

TargetType
[Входные данные] Идентификатор типа данных C для буфера *TargetValuePtr . Список допустимых типов данных C и идентификаторов типов см . в разделе "Типы данных C" в приложении D: Типы данных.

Если TargetType SQL_ARD_TYPE, драйвер использует идентификатор типа, указанный в поле SQL_DESC_CONCISE_TYPE ARD. Если TargetType SQL_APD_TYPE, SQLGetData будет использовать тот же тип данных C, который был указан в SQLBindParameter. В противном случае тип данных C, указанный в SQLGetData , переопределяет тип данных C, указанный в SQLBindParameter. Если это SQL_C_DEFAULT, драйвер выбирает тип данных C по умолчанию на основе типа данных SQL источника.

Можно также указать расширенный тип данных C. Дополнительные сведения о типах данных см. в разделе Типы данных C в ODBC.

TargetValuePtr
[Выходные данные] Указатель на буфер, в котором возвращаются данные.

TargetValuePtr не может иметь значение NULL.

BufferLength
[Входные данные] Длина буфера *TargetValuePtr в байтах.

Драйвер использует BufferLength , чтобы избежать записи в конце буфера *TargetValuePtr при возврате данных переменной длины, таких как символьные или двоичные данные. Обратите внимание, что драйвер подсчитывает символ завершения null при возврате символьных данных в *TargetValuePtr. *TargetValuePtr должен содержать пробел для символа завершения null, или драйвер усечь данные.

Когда драйвер возвращает данные фиксированной длины, например целое число или структуру дат, драйвер игнорирует BufferLength и предполагает, что буфер достаточно велик, чтобы хранить данные. Поэтому важно, чтобы приложение выделило достаточно большой буфер для данных фиксированной длины или драйвер будет записывать в конце буфера.

SQLGetData возвращает SQLSTATE HY090 (недопустимая строка или длина буфера), если BufferLength меньше 0, но не когда BufferLength равно 0.

StrLen_or_IndPtr
[Выходные данные] Указатель на буфер, в котором возвращается значение длины или индикатора. Если это пустой указатель, длина или значение индикатора не возвращается. При получении данных значение NULL возвращает ошибку.

SQLGetData может возвращать следующие значения в буфере длины или индикатора:

• Длина возвращаемых данных

• SQL_NO_TOTAL

• SQL_NULL_DATA

Дополнительные сведения см. в разделе "Использование значений длины или индикатора" и "Примечания" в этом разделе.

Возвраты

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_NO_DATA, SQL_STILL_EXECUTING, SQL_ERROR или SQL_INVALID_HANDLE.

Диагностика

Когда SQLGetData возвращает SQL_ERROR или SQL_SUCCESS_WITH_INFO, связанное значение SQLSTATE можно получить путем вызова SQLGetDiagRec с помощью HandleType SQL_HANDLE_STMT и handle of StatementHandle. В следующей таблице перечислены значения SQLSTATE, которые обычно возвращаются SQLGetData и объясняются каждый из них в контексте этой функции. Нотация "(DM)" предшествует описаниям SQLSTATEs, возвращаемым диспетчером драйверов. Возвращаемый код, связанный с каждым значением SQLSTATE, SQL_ERROR, если не указано иное.

Комментарии

SQLGetData возвращает данные в указанном столбце. SQLGetData можно вызывать только после получения одной или нескольких строк из результирующих наборов SQLFetch, SQLFetchScroll или SQLExtendedFetchFetch. Если данные переменной длины слишком большие для возврата в одном вызове SQLGetData (из-за ограничения в приложении), SQLGetData может получить его в частях. Можно привязать некоторые столбцы в строке и вызвать SQLGetData для других, хотя это связано с некоторыми ограничениями. Дополнительные сведения см. в разделе "Получение длинных данных".

Сведения об использовании SQLGetData с потоковыми выходными параметрами см. в разделе "Получение выходных параметров с помощью SQLGetData".

Использование SQLGetData

Если драйвер не поддерживает расширения в SQLGetData, функция может возвращать данные только для несвязанных столбцов с числом больше, чем последний привязанный столбец. Кроме того, в строке данных значение аргумента Col_or_Param_Num в каждом вызове SQLGetData должно быть больше или равно значению Col_or_Param_Num в предыдущем вызове; то есть данные должны быть получены в растущем порядке числа столбцов. Наконец, если расширения не поддерживаются, SQLGetData не может вызываться, если размер набора строк превышает 1.

Водители могут расслабить любой из этих ограничений. Чтобы определить, какие ограничения ослабляет драйвер, приложение вызывает SQLGetInfo с любым из следующих SQL_GETDATA_EXTENSIONS параметров:

• SQL_GD_OUTPUT_PARAMS = SQLGetData можно вызывать для возврата значений выходных параметров. Дополнительные сведения см. в разделе Получение выходных параметров с помощью метода SQLGetData.

• SQL_GD_ANY_COLUMN. Если этот параметр возвращается, SQLGetData можно вызывать для любого несвязанного столбца, в том числе до последнего привязанного столбца.

• SQL_GD_ANY_ORDER. Если этот параметр возвращается, SQLGetData может вызываться для несвязанных столбцов в любом порядке.

• SQL_GD_BLOCK. Если этот параметр возвращается SQLGetInfo для SQL_GETDATA_EXTENSIONS InfoType, драйвер поддерживает вызовы SQLGetData , если размер набора строк превышает 1, а приложение может вызывать SQLSetPos с параметром SQL_POSITION, чтобы разместить курсор в правильной строке перед вызовом SQLGetData.

• SQL_GD_BOUND. Если этот параметр возвращается, SQLGetData может вызываться для привязанных столбцов, а также несвязанных столбцов.

Существует два исключения этих ограничений и способность водителя расслабить их. Во-первых, SQLGetData никогда не следует вызывать для курсора только для пересылки, если размер набора строк превышает 1. Во-вторых, если драйвер поддерживает закладки, он всегда должен поддерживать возможность вызова SQLGetData для столбца 0, даже если приложения не позволяют приложениям вызывать SQLGetData для других столбцов до последнего привязанного столбца. (Если приложение работает с драйвером ODBC 2*.x*, SQLGetData успешно возвращает закладку при вызове с Col_or_Param_Num равно 0 после вызова SQLFetch. поскольку диспетчер драйверов ODBC 3*.x* сопоставляется с диспетчером драйверов SQLExtendedFetch с FetchOrientation SQL_FETCH_NEXT, а SQLGetData с Col_or_Param_Num 0 сопоставляется диспетчером драйверов ODBC 3*.x* с sqlGetStmtOption с fOption SQL_GET_BOOKMARK.)

SQLGetData нельзя использовать для извлечения закладки для строки, просто вставленной путем вызова SQLBulkOperations с параметром SQL_ADD, так как курсор не расположен в строке. Приложение может получить закладку для такой строки путем привязки столбца 0 перед вызовом SQLBulkOperations с SQL_ADD, в этом случае SQLBulkOperations возвращает закладку в связанном буфере. Затем SQLFetchScroll можно вызвать с помощью SQL_FETCH_BOOKMARK, чтобы изменить положение курсора в этой строке.

Если аргумент TargetType является типом данных интервала, то для данных используются значения интервала по умолчанию ( 2) и точность интервала по умолчанию (6), заданные в полях SQL_DESC_DATETIME_INTERVAL_PRECISION и SQL_DESC_PRECISION ARD соответственно. Если аргумент TargetType является типом данных SQL_C_NUMERIC, точность по умолчанию (определяемая драйвером) и шкала по умолчанию (0), как указано в SQL_DESC_PRECISION и SQL_DESC_SCALE полях ARD, используются для данных. Если какая-либо точность или масштаб по умолчанию не подходит, приложение должно явно задать соответствующее поле дескриптора вызовом SQLSetDescField или SQLSetDescRec. Оно может задать для поля SQL_DESC_CONCISE_TYPE значение SQL_C_NUMERIC и вызвать SQLGetData с аргументом TargetType SQL_ARD_TYPE, что приведет к использованию значений точности и масштабирования в полях дескриптора.

Получение данных переменной длины в частях

SQLGetData можно использовать для получения данных из столбца, содержащего данные переменной длины в частях, то есть если идентификатор типа данных SQL столбца SQL_CHAR, SQL_VARCHAR, SQL_LONGVARCHAR, SQL_WCHAR, SQL_WVARCHAR, SQL_WLONGVARCHAR, SQL_BINARY, SQL_VARBINARY, SQL_LONGVARBINARY или идентификатор драйвера для типа переменной длины.

Чтобы получить данные из столбца в частях, приложение вызывает SQLGetData несколько раз в последовательности для одного столбца. При каждом вызове SQLGetData возвращает следующую часть данных. Приложение выполняет повторное удаление частей, заботясь о том, чтобы удалить символ завершения null из промежуточных частей символов. Если для конца символа выделено больше данных для возврата или недостаточно буфера, SQLGetData возвращает SQL_SUCCESS_WITH_INFO и SQLSTATE 01004 (усеченные данные). При возвращении последней части данных SQLGetData возвращает SQL_SUCCESS. Ни SQL_NO_TOTAL, ни нулю не могут быть возвращены при последнем допустимом вызове для получения данных из столбца, так как приложение не сможет знать, сколько данных в буфере приложения допустимо. Если sqlGetData вызывается после этого, он возвращает SQL_NO_DATA. Дополнительные сведения см. в следующем разделе "Получение данных с помощью SQLGetData".

Закладки переменной длины можно возвращать в частях SQLGetData. Как и в случае с другими данными, вызов SQLGetData для возврата закладок переменной длины в частях вернет SQLSTATE 01004 (строковые данные, усеченные по правому краю) и SQL_SUCCESS_WITH_INFO при получении дополнительных данных. Это отличается от случая, когда закладка переменной длины усечена вызовом SQLFetch или SQLFetchScroll, который возвращает SQL_ERROR и SQLSTATE 22001 (строковые данные, усекаются право).

SQLGetData нельзя использовать для возврата данных фиксированной длины в частях. Если SQLGetData вызывается несколько раз в строке для столбца, содержащего данные фиксированной длины, он возвращает SQL_NO_DATA для всех вызовов после первого вызова.

Получение потоковых выходных параметров

Если драйвер поддерживает потоковые выходные параметры, приложение может вызывать SQLGetData с небольшим буфером много раз, чтобы получить большое значение параметра. Дополнительные сведения о потоковых выходных параметрах см. в разделе "Получение выходных параметров с помощью SQLGetData".

Получение данных с помощью SQLGetData

Чтобы вернуть данные для указанного столбца, SQLGetData выполняет следующую последовательность действий:

1. Возвращает SQL_NO_DATA, если он уже вернул все данные для столбца.

2. Задает значение *StrLen_or_IndPtr значение SQL_NULL_DATA , если данные равно NULL. Если данные равно NULL и StrLen_or_IndPtr был указателем NULL, SQLGetData возвращает SQLSTATE 22002 (переменная индикатора, требуемая, но не указана).

   Если данные для столбца не равно NULL, SQLGetData переходит к шагу 3.

3. Если атрибут инструкции SQL_ATTR_MAX_LENGTH имеет значение, отличное от нуля, если столбец содержит символьные или двоичные данные, а если SQLGetData не был вызван для столбца, данные усечены до SQL_ATTR_MAX_LENGTH байтов.

   Примечание.

   Атрибут оператора SQL_ATTR_MAX_LENGTH предназначен для уменьшения сетевого трафика. Обычно он реализуется источником данных, который усечение данных перед возвратом данных через сеть. Для поддержки драйверов и источников данных не требуется. Таким образом, чтобы гарантировать усечение данных до определенного размера, приложение должно выделить буфер этого размера и указать размер в аргументе BufferLength .

4. Преобразует данные в тип, указанный в TargetType. Данные получают точность и масштаб по умолчанию для этого типа данных. Если TargetType SQL_ARD_TYPE, используется тип данных в поле SQL_DESC_CONCISE_TYPE ARD. Если targetType SQL_ARD_TYPE, данные получают точность и масштаб в полях SQL_DESC_DATETIME_INTERVAL_PRECISION, SQL_DESC_PRECISION и SQL_DESC_SCALE ARD в зависимости от типа данных в поле SQL_DESC_CONCISE_TYPE. Если какая-либо точность или масштаб по умолчанию не подходит, приложение должно явно задать соответствующее поле дескриптора вызовом SQLSetDescField или SQLSetDescRec.

5. Если данные были преобразованы в тип данных переменной длины, например символ или двоичный файл, SQLGetData проверяет, превышает ли длина данных BufferLength. Если длина символьных данных (включая символ завершения null) превышает BufferLength, SQLGetData усечает данные в BufferLength меньше длины символа завершения null. Затем он завершает данные с пустым значением. Если длина двоичных данных превышает длину буфера данных, SQLGetData усечает его до байтов BufferLength .

   Если предоставленный буфер данных слишком мал для хранения символа завершения null, SQLGetData возвращает SQL_SUCCESS_WITH_INFO и SQLSTATE 01004.

   SQLGetData никогда не усечение данных, преобразованных в типы данных фиксированной длины; всегда предполагается, что длина *TargetValuePtr — это размер типа данных.

6. Помещает преобразованные (и, возможно, усеченные) данные в *TargetValuePtr. Обратите внимание, что SQLGetData не может возвращать данные из строки.

7. Помещает длину данных в *StrLen_or_IndPtr. Если StrLen_or_IndPtr был указателем null, SQLGetData не возвращает длину.

   • Для символьных или двоичных данных это длина данных после преобразования и перед усечением из-за BufferLength. Если драйвер не может определить длину данных после преобразования, как и в некоторых случаях с длинными данными, он возвращает SQL_SUCCESS_WITH_INFO и задает длину SQL_NO_TOTAL. (Последний вызов SQLGetData всегда должен возвращать длину данных, а не ноль или SQL_NO_TOTAL.) Если данные были усечены из-за атрибута оператора SQL_ATTR_MAX_LENGTH, значение этого атрибута ( в отличие от фактической длины) помещается в *StrLen_or_IndPtr. Это связано с тем, что этот атрибут предназначен для усечения данных на сервере перед преобразованием, поэтому драйвер не может определить фактическую длину. Если SQLGetData вызывается несколько раз в последовательности для одного столбца, это длина данных, доступных в начале текущего вызова, то есть длина уменьшается при каждом последующем вызове.

   • Для всех других типов данных это длина данных после преобразования; То есть это размер типа, в который были преобразованы данные.

8. Если данные усечены без потери значения во время преобразования (например, реальное число 1.234 усечено при преобразовании в целочисленное число 1) или так как BufferLength слишком мал (например, строка abcdef помещается в буфер 4-байтов), SQLGetData возвращает SQLSTATE 01004 (усеченные данные) и SQL_SUCCESS_WITH_INFO. Если данные усечены без потери значения из-за атрибута инструкции SQL_ATTR_MAX_LENGTH, SQLGetData возвращает SQL_SUCCESS и не возвращает SQLSTATE 01004 (усечено данных).

Содержимое связанного буфера данных (если SQLGetData вызывается в привязанном столбце) и буфер длины или индикатора не определен, если SQLGetData не возвращает SQL_SUCCESS или SQL_SUCCESS_WITH_INFO.

Последовательные вызовы SQLGetData извлекают данные из последнего запрошенного столбца. Предыдущие смещения становятся недопустимыми. Например, при выполнении следующей последовательности:

SQLGetData(icol=n), SQLGetData(icol=m), SQLGetData(icol=n)  

Второй вызов SQLGetData(icol=n) извлекает данные из начала n столбца. Любое смещение в данных из-за более ранних вызовов SQLGetData для столбца больше не является допустимым.

Дескрипторы и SQLGetData

SQLGetData не взаимодействует напрямую с полями дескриптора.

Если TargetType SQL_ARD_TYPE, используется тип данных в поле SQL_DESC_CONCISE_TYPE ARD. Если TargetType имеет значение SQL_ARD_TYPE или SQL_C_DEFAULT, данные получают точность и масштаб в полях SQL_DESC_DATETIME_INTERVAL_PRECISION, SQL_DESC_PRECISION и SQL_DESC_SCALE ARD в зависимости от типа данных в поле SQL_DESC_CONCISE_TYPE.

Пример кода

В следующем примере приложение выполняет инструкцию SELECT , чтобы вернуть результирующий набор идентификаторов клиентов, имен и номеров телефонов, отсортированных по имени, идентификатору и номеру телефона. Для каждой строки данных он вызывает SQLFetch для размещения курсора в следующей строке. Он вызывает SQLGetData для получения полученных данных; буферы для данных и возвращаемое число байтов указываются в вызове SQLGetData. Наконец, он печатает имя, идентификатор и номер телефона каждого сотрудника.

#define NAME_LEN 50  
#define PHONE_LEN 50  
  
SQLCHAR      szName[NAME_LEN], szPhone[PHONE_LEN];  
SQLINTEGER   sCustID, cbName, cbAge, cbBirthday;  
SQLRETURN    retcode;  
SQLHSTMT     hstmt;  
  
retcode = SQLExecDirect(hstmt,  
   "SELECT CUSTID, NAME, PHONE FROM CUSTOMERS ORDER BY 2, 1, 3",  
   SQL_NTS);  
  
if (retcode == SQL_SUCCESS) {  
   while (TRUE) {  
      retcode = SQLFetch(hstmt);  
      if (retcode == SQL_ERROR || retcode == SQL_SUCCESS_WITH_INFO) {  
         show_error();  
      }  
      if (retcode == SQL_SUCCESS || retcode == SQL_SUCCESS_WITH_INFO){  
  
         /* Get data for columns 1, 2, and 3 */  
  
         SQLGetData(hstmt, 1, SQL_C_ULONG, &sCustID, 0, &cbCustID);  
         SQLGetData(hstmt, 2, SQL_C_CHAR, szName, NAME_LEN, &cbName);  
         SQLGetData(hstmt, 3, SQL_C_CHAR, szPhone, PHONE_LEN,  
            &cbPhone);  
  
         /* Print the row of data */  
  
         fprintf(out, "%-5d %-*s %*s", sCustID, NAME_LEN-1, szName,   
            PHONE_LEN-1, szPhone);  
      } else {  
         break;  
      }  
   }  
}  

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

См. также

Справочник по API ODBC
Файлы заголовков ODBC
Получение выходных параметров с помощью метода SQLGetData