Функция JetRetrieveColumn

  • Статья

Применимо к: Windows | Windows Server

Функция JetRetrieveColumn

Функция JetRetrieveColumn извлекает значение одного столбца из текущей записи. Запись — это запись, связанная с записью индекса в текущей позиции курсора. Кроме того, эта функция может получить столбец из записи, создаваемой в буфере копирования курсоров. Эта функция также может получать данные столбца из записи индекса, которая ссылается на текущую запись. Помимо получения фактического значения столбца, можно также использовать JetRetrieveColumn для получения размера столбца, прежде чем получать данные самого столбца, чтобы буферы приложений могли иметь соответствующий размер.

    JET_ERR JET_API JetRetrieveColumn(
      __in          JET_SESID sesid,
      __in          JET_TABLEID tableid,
      __in          JET_COLUMNID columnid,
      __out_opt     void* pvData,
      __in          unsigned long cbData,
      __out_opt     unsigned long* pcbActual,
      __in          JET_GRBIT grbit,
      __in_out_opt  JET_RETINFO* pretinfo
    );

Параметры

sesid

Сеанс, используемый для этого вызова.

tableid

Курсор, используемый для этого вызова.

columnid

JET_COLUMNID извлекаемого столбца.

Можно задать значение columnid , равное 0 (ноль), которое само по себе не ссылается ни на один отдельный столбец. Если задано значение columnid 0 (ноль), все столбцы с тегами, разреженные и многозначные столбцы обрабатываются как один столбец. Это упрощает извлечение всех разреженных столбцов, присутствующих в записи.

pvData

Выходной буфер, получающий значение столбца.

cbData

Максимальный размер выходного буфера в байтах.

pcbActual

Получает фактический размер (в байтах) значения столбца.

Если этот параметр имеет значение NULL, фактический размер значения столбца не возвращается.

grbit

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

Значение

Значение

JET_bitRetrieveCopy

Этот флаг приводит к получению столбца измененного значения вместо исходного. Если значение не было изменено, извлекается исходное значение. Таким образом, значение, которое еще не было вставлено или не обновлено, может быть получено во время вставки или обновления записи.

JET_bitRetrieveFromIndex

Этот параметр используется для получения значений столбцов из индекса, если это возможно, без доступа к записи. Таким образом, можно избежать ненужной загрузки записей, если необходимые данные доступны из самих записей индекса. В случаях, когда исходное значение столбца не удается получить из индекса из-за необратимых преобразований или усечения данных, доступ к записи будет осуществляться, а данные извлекаются в обычном режиме. Это параметр производительности, который следует указывать только в том случае, если вероятно, что значение столбца можно извлечь из индекса. Этот параметр не следует указывать, если текущий индекс является кластеризованным, так как записи индекса для кластеризованного или первичного индекса являются записями. Этот бит нельзя задать, если также задано JET_bitRetrieveFromPrimaryBookmark.

JET_bitRetrieveFromPrimaryBookmark

Этот параметр используется для получения значений столбцов из закладки индекса и может отличаться от значения индекса, если столбец отображается как в основном, так и в текущем индексе. Этот параметр не следует указывать, если текущий индекс является кластеризованным или первичным индексом. Этот бит нельзя задать, если также задано JET_bitRetrieveFromIndex.

JET_bitRetrieveTag

Этот параметр используется для получения порядкового номера значения многозначного столбца в pretinfo-itagSequence>. Поле itagSequence обычно является входными данными для получения значений столбцов с несколькими значениями из записи. Однако при получении значений из индекса также можно связать запись индекса с определенным порядковым номером и получить этот порядковый номер. Получение порядкового номера может быть дорогостоящей операцией, и ее следует выполнять только при необходимости.

JET_bitRetrieveNull

Этот параметр используется для получения значений NULL в столбце с несколькими значениями. Если этот параметр не указан, значения NULL столбца с несколькими значениями будут автоматически пропущены.

JET_bitRetrieveIgnoreDefault

Этот параметр влияет только на столбцы с несколькими значениями и приводит к возврату значения NULL , если запрошенный порядковый номер равен 1, а для столбца в записи нет заданных значений.

JET_bitRetrieveLongId

Этот флаг предназначен только для внутреннего использования и не предназначен для использования в приложении.

JET_bitRetrieveLongValueRefCount

Этот флаг предназначен только для внутреннего использования и не предназначен для использования в приложении.

JET_bitRetrieveTuple

Этот флаг позволяет получить сегмент кортежа индекса. Этот бит необходимо указать с помощью JET_bitRetrieveFromIndex.

pretinfo

Если параметр pretinfo имеет значение NULL , функция ведет себя так, как если бы было задано значение itagSequence 1 и значение ibLongValue 0 (ноль). Это приводит к получению столбца первого значения многозначного столбца и получению длинных данных со смещением 0 (ноль).

Этот параметр используется для предоставления одного или нескольких из следующих компонентов:

Значение

Значение

ibLongValue

Возвращает двоичное смещение в значение длинного столбца при извлечении части значения столбца.

itagSequence

Задает порядковый номер нужного значения столбца с несколькими значениями. Обратите внимание, что это поле задается только в том случае, если указано JET_bitRetrieveTag. В противном случае он не будет изменен.

columnidNextTagged

Возвращает идентификатор столбца возвращаемого значения столбца при получении всех столбцов с тегами, разреженных и многозначных столбцов с использованием передачи columnid 0 (ноль).

Возвращаемое значение

Эта функция возвращает тип данных JET_ERR с одним из следующих кодов возврата. Дополнительные сведения о возможных ошибках ESE см. в разделах Ошибки подсистемы расширяемого хранилища и Параметры обработки ошибок.

Код возврата

Описание

JET_errSuccess

Операция выполнена успешно.

JET_errBadColumnId

Указанный идентификатор столбца выходит за пределы идентификатора столбца.

JET_errBadItagSequence

В pretinfo-itagSequence> передано недопустимое значение порядкового номера столбца с несколькими значениями. Допустимые значения для порядковых номеров значений столбцов с несколькими значениями — 1 или больше. Недопустимое значение 0 (ноль) для этой функции.

JET_errClientRequestToStopJetService

Невозможно выполнить операцию, так как все действия экземпляра, связанного с сеансом, прекратились в результате вызова JetStopService.

JET_errColumnNotFound

Столбец, описанный заданным columnid , не существует в таблице.

JET_errIndexTuplesCannotRetrieveFromIndex

Столбцы, индексированные как подстроки, не могут быть получены из индекса, так как в каждой записи индекса обычно присутствует только небольшая часть столбца.

JET_errInstanceUnavailable

Невозможно выполнить операцию, так как экземпляр, связанный с сеансом, столкнулся с неустранимой ошибкой, требующей отмены доступа ко всем данным для защиты целостности этих данных. Эта ошибка будет возвращена только в Windows XP и более поздних выпусках.

JET_errInvalidBufferSize

В некоторых случаях буфер, заданный для извлекаемого столбца, должен быть достаточного размера, чтобы возвращать любое значение столбца. Например, обновляемые столбцы escrow корректируются таким образом, чтобы они соответствовали контексту транзакций вызывающего сеанса, и для этой корректировки требуется буфер, предоставленный вызывающим объектом. Если буфер недостаточно места, возвращается JET_errInvalidBufferSize и данные столбца вообще не возвращаются.

JET_errInvalidParameter

Один или несколько заданных параметров неверны. Это может произойти, если retinfo.cbStruct меньше размера JET_RETINFO.

JET_errInvalidgrbit

Указанные параметры неизвестны или являются недопустимым сочетанием известных битовых параметров.

JET_errNoCurrentRecord

Курсор не располагается на записи. Это может произойти по различным причинам. Например, это произойдет, если курсор находится после последней записи в текущем индексе.

JET_errNotInitialized

Невозможно выполнить операцию, так как экземпляр, связанный с сеансом, еще не инициализирован.

JET_errRestoreInProgress

Невозможно выполнить операцию, так как операция восстановления выполняется в экземпляре, связанном с сеансом.

JET_errSessionSharingViolation

Один и тот же сеанс нельзя использовать для нескольких потоков одновременно.

Windows XP: Эта ошибка будет возвращена только в Windows XP и более поздних выпусках.

JET_errTermInProgress

Невозможно завершить операцию, так как экземпляр, связанный с сеансом, завершает работу.

JET_wrnBufferTruncated

Не удалось получить значение всего столбца, так как заданный буфер меньше размера столбца.

JET_wrnColumnNull

Полученное значение столбца равно NULL.

При успешном выполнении значение столбца для заданного столбца копируется в заданный буфер. Меньше, чем все значения столбца копируются с предупреждением JET_wrnBufferTruncated возвращается. Если был задан pcbActual , возвращается фактический размер значения столбца. Обратите внимание, что значения NULL имеют длину 0 (ноль) и, таким образом, устанавливают для возвращаемого размера значение 0 (ноль). Если полученный столбец был столбцом с несколькими значениями и параметром pretinfo , а JET_bitReturnTag задан в качестве параметра, порядковый номер значения столбца возвращается в pretinfo-itagSequence>.

При сбое расположение курсора остается без изменений, а данные не копируются в предоставленный буфер.

Комментарии

Этот вызов используется только один раз для получения данных фиксированного или известного размера для столбцов, не являющихся многозначными. Однако если данные столбца неизвестного размера, этот вызов обычно используется дважды. Сначала он вызывается для определения размера данных, чтобы выделить необходимое дисковое пространство. Затем этот же вызов выполняется снова для получения данных столбца. Если фактическое количество значений неизвестно, так как столбец имеет многозначное значение, вызов обычно используется три раза. Сначала нужно получить количество значений, а затем дважды больше, чтобы выделить хранилище и получить фактические данные.

Получение всех значений для многозначного столбца можно выполнить, многократно вызывая эту функцию со значением pretinfo-itagSequence>, начинающимся с 1, и увеличиваясь при каждом последующем вызове. Известно, что последнее значение столбца извлекается при возврате JET_wrnColumnNull из функции. Обратите внимание, что этот метод не может быть выполнен, если в столбце с несколькими значениями явно заданы значения NULL в последовательности значений, так как эти значения будут пропущены. Если приложению требуется получить все значения столбцов с несколькими значениями, включая значения NULL, вместо JetRetrieveColumn следует использовать JetRetrieveColumns. Обратите внимание, что эта функция не возвращает число значений для функции с несколькими значениями, если задано значение itagSequence 0 (ноль). Только JetRetrieveColumns будет возвращать количество значений столбца при передаче значения itagSequence 0 (ноль).

Если эта функция вызывается на уровне транзакции 0 (ноль), например, вызывающий сеанс не находится в транзакции, то транзакция открывается и закрывается внутри функции. Цель этого — вернуть согласованные результаты в случае, если длинное значение охватывает страницы базы данных. Обратите внимание, что транзакция освобождается между вызовами функций, и ряд вызовов этой функции, когда сеанс не входит в транзакцию, может возвращать данные, обновленные после первого вызова этой функции.

Значение столбца по умолчанию будет получено, если для столбца не было явно задано другое значение, если не задан параметр JET_bitRetrieveIgnoreDefault.

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

При извлечении всех помеченных, многозначных и разреженных столбцов, задав columnid значение 0 (ноль), столбцы извлекаются в порядке columnid от самого низкого столбца до самого высокого значения columnid. Каждый раз при извлечении значений столбцов возвращается один и тот же порядок значений столбцов. Порядок детерминирован.

Требования

Требование Значение

Клиент

Требуется Windows Vista, Windows XP или Windows 2000 Professional.

Сервер

Требуется Windows Server 2008, Windows Server 2003 или Windows 2000 Server.

Верхняя часть

Объявлено в Esent.h.

Библиотека

Используйте ESENT.lib.

DLL

Требуется ESENT.dll.

См. также:

JET_COLUMNID
JET_ERR
JET_SESID
JET_TABLEID
JET_RETINFO
JetSetColumn
JetRetrieveColumns