Share via

Функция JetRetrieveColumns

  • Статья

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

Функция JetRetrieveColumns

Функция JetRetrieveColumns извлекает несколько значений столбцов из текущей записи в одной операции. Массив структур JET_RETRIEVECOLUMN используется для описания набора извлекаемых значений столбцов, а также для описания выходных буферов для каждого извлекаемого значения столбца.

    JET_ERR JET_API JetRetrieveColumns(
      __in          JET_SESID sesid,
      __in          JET_TABLEID tableid,
      __in_out_opt  JET_RETRIEVECOLUMN* pretrievecolumn,
      __in          unsigned long cretrievecolumn
    );

Параметры

sesid

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

tableid

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

pretrievecolumn

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

cretrievecolumn

Число JET_RETRIEVECOLUMN структур в массиве, заданное pretrievecolumn.

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

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

Код возврата

Описание

JET_errSuccess

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

JET_errBadItagSequence

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

JET_errBadColumnId

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

JET_errClientRequestToStopJetService

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

JET_errColumnNotFound

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

JET_errIndexTuplesCannotRetrieveFromIndex

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

JET_errInvalidBufferSize

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

JET_errInvalidgrbit

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

JET_errInvalidParameter

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

JET_errInstanceUnavailable

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

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

JET_errNoCurrentRecord

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

JET_errNotInitialized

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

JET_errRestoreInProgress

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

JET_errSessionSharingViolation

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

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

JET_errTermInProgress

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

JET_wrnBufferTruncated

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

При успешном выполнении данные столбцов и размер столбцов возвращаются в предоставленных буферах, описанных в массиве структур JET_RETRIEVECOLUMN . Если параметру itagSequence присвоено значение 0 (ноль), чтобы указать, что вместо данных столбца требуется число экземпляров поля с несколькими значениями, то количество экземпляров многозначного столбца возвращается в самом поле itagSequence . Каждая структура JET_RETRIEVECOLUMN имеет поле ошибки, содержащее предупреждения для полученного столбца. Если столбец имеет значение NULL , код ошибки будет иметь значение JET_wrnColumnNull.

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

Комментарии

JetRetrieveColumns поддерживает одну функцию, которую не поддерживает JetRetrieveColumn . Это возможность получить количество экземпляров многозначного столбца. Цель этой функции — разрешить приложению извлекать все значения столбца. Это можно сделать, сначала определив количество значений столбца. Затем их длину можно определить, вызвав JetRetrieveColumns еще раз с одной JET_RETRIEVECOLUMN структурой, выделенной для каждого значения, чтобы определить длину данных столбца. Это можно сделать путем передачи указателей NULLpvData с cbMax 0 (ноль) и получения длины столбца в cbActual. Третий и последний вызов можно выполнить с выделенной памятью для данных значения столбца.

Если полученный столбец усекается из-за недостаточной длины буфера, API вернет JET_wrnBufferTruncated. Однако другие ошибки, JET_wrnColumnNull возвращаются только в поле ошибки в JET_RETRIEVECOLUMN. Причиной этого является то, что приложения часто хотят убедиться, что все данные были извлечены, и возврат этой ошибки из JetRetrieveColumns упрощает это понимание.

Требования

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

Клиент

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

Сервер

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

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

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

Библиотека

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

DLL

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

См. также:

JET_ERR
JET_SESID
JET_TABLEID
JET_RETRIEVECOLUMN
JetEnumerateColumns
JetRetrieveColumn
JetSetColumns