Поделиться через

Функция JetEnumerateColumns

  • Статья

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

Функция JetEnumerateColumns

Функция JetEnumerateColumns эффективно извлекает набор столбцов и их значения из текущей записи курсора или буфера копирования этого курсора. Полученные столбцы и значения могут быть ограничены списком идентификаторов столбцов, номерами itagSequence и другими характеристиками. Этот API извлечения столбцов уникален тем, что он возвращает сведения в динамически выделенной памяти, полученной с помощью предоставленного пользователем обратного вызова, совместимого с realloc . Эта новая гибкость позволяет эффективно извлекать данные столбцов с определенными характеристиками (такими как размер и кратность), которые неизвестны вызывающей объекту. Это избавляет от необходимости использовать режимы обнаружения JetRetrieveColumn для определения этих характеристик, чтобы настроить окончательный вызов JetRetrieveColumn , который будет успешно извлекать нужные данные.

Windows XP: JetEnumerateColumns представлен в Windows XP.

    JET_ERR JET_API JetEnumerateColumns(
      __in          JET_SESID sesid,
      __in          JET_TABLEID tableid,
      __in          unsigned long cEnumColumnId,
      __in_opt      JET_ENUMCOLUMNID* rgEnumColumnId,
      __out         unsigned long* pcEnumColumn,
      __out         JET_ENUMCOLUMN** prgEnumColumn,
      __in          JET_PFNREALLOC pfnRealloc,
      __in          void* pvReallocContext,
      __in          unsigned long cbDataMost,
      __in          JET_GRBIT grbit
    );

Параметры

sesid

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

tableid

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

cEnumColumnId

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

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

Если параметр ctagSequence равен 0 (ноль) для заданного элемента массива идентификаторов столбцов, то rgtagSequence игнорируется, а все значения столбцов для этого идентификатора столбца перечисляются и возвращаются вызывающему объекту. Если элемент массива чисел itagSequence ссылается на число itagSequence 0 (ноль), то перечисление этого числа itagSequence пропускается и соответствующий слот в выходных данных будет создан с состоянием столбца JET_wrnColumnSkipped.

rgEnumColumnId

См. раздел cEnumColumnId.

pcEnumColumn

Возвращает перечисляемый массив столбцов и их значения в памяти, выделенной с помощью предоставленного обратного вызова, совместимого с itagSequence .

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

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

prgEnumColumn

См . pcEnumColumn.

pfnRealloc

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

pvReallocContext

См. раздел pfnRealloc.

cbDataMost

Устанавливает ограничение на объем данных, возвращаемых из длинного текста или длинного двоичного столбца.

Этот параметр можно использовать для предотвращения перечисления очень большого значения столбца. Обычно такое перечисление может завершиться ошибкой вызова API с JET_errOutOfMemory. Если большое значение столбца усекается таким образом, состояние столбца будет JET_wrnColumnTruncated.

grbit

Группа битов, задающая ноль или несколько следующих параметров.

Значение

Значение

JET_bitEnumerateCompressOutput

При перечислении значений столбцов все столбцы, для которых мы извлекаем все значения и которые имеют только одно значение столбца, отличное от NULL, могут быть возвращены в сжатом формате. Для таких столбцов будет задано состояние JET_wrnColumnSingleValue, а размер значения столбца и память, содержащая значение столбца, будут возвращены непосредственно в структуре JET_ENUMCOLUMN . Таким образом не гарантируется, что все подходящие столбцы сжимаются. Дополнительные сведения см. в разделе JET_ENUMCOLUMN .

JET_bitEnumerateCopy

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

Этот параметр идентичен JET_bitRetrieveCopy при использовании с JetRetrieveColumn или JetRetrieveColumns.

JET_bitEnumerateIgnoreDefault

Если данный столбец отсутствует в записи, то значение столбца не будет возвращено. Обычно в этом случае возвращается значение по умолчанию для столбца, если таковое имеется. Гарантируется, что если для столбца задано значение, отличное от значения по умолчанию, будет возвращено другое значение (то есть, если для столбца со значением по умолчанию явно задано значение NULL , то в качестве значения для этого столбца будет возвращено значение NULL ). Обратите внимание, что даже если этот параметр запрашивается, по-прежнему можно увидеть значение столбца, равное значению по умолчанию. Для удаления значений столбцов, соответствующих значениям по умолчанию, не предпринимаются никакие усилия.

Важно отметить, что этот параметр влияет на выходные данные JetEnumerateColumns при использовании с JET_bitEnumeratePresenceOnly или JET_bitEnumerateTaggedOnly.

JET_bitEnumerateIgnoreUserDefinedDefault

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

Windows Server 2003 и более ранние версии: Для Windows Server 2003 и более ранних версий операция завершится сбоем с JET_errCallbackFailed.

Windows Server 2003 с пакетом обновления 1 (SP1): Это возможное значение доступно только для операционных систем Windows Server 2003 с пакетом обновления 1 (SP1) и более поздних версий. Если указано это возможное значение и таблица содержит столбец, имеющий определенное пользователем значение по умолчанию, операция завершится сбоем с JET_errCallbackFailed.

JET_bitEnumeratePresenceOnly

Если для запрошенного столбца или значения столбца существует значение, отличное от NULL, связанные данные не возвращаются. Вместо этого связанное состояние для этого столбца или значения столбца будет установлено в JET_wrnColumnPresent. Если значение столбца или столбца равно NULL , JET_wrnColumnNull будет возвращено обычным образом.

JET_bitEnumerateTaggedOnly

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

JET_bitEnumerateInRecordOnly

Windows 7: JET_bitEnumerateInRecordOnly появилась в Windows 7.

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

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

Код возврата

Описание

JET_errSuccess

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

JET_errBadColumnId

Указанный идентификатор столбца выходит за юридические рамки идентификатора столбца. Эта ошибка будет возвращена JetEnumerateColumns , если были запрошены определенные идентификаторы столбцов, один из этих идентификаторов столбцов был недопустимым, а первый недопустимый идентификатор столбца завершился ошибкой с этой ошибкой для кода состояния столбца.

JET_errClientRequestToStopJetService

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

JET_errColumnNotFound

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

JET_errInstanceUnavailable

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

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

JET_errInvalidgrbit

Один из запрошенных вариантов был недопустим или не реализован. Эта ошибка будет возвращена JetEnumerateColumns , когда:

  • JET_bitEnumerateLocal указано.

  • Указан недопустимый гбит .

JET_errInvalidParameter

Один из предоставленных параметров содержал непредвиденное значение или значение, которое не имело смысла в сочетании со значением другого параметра. Эта ошибка будет возвращена JetEnumerateColumns , если:

  • pcEnumColumn имеет значение NULL.

  • prgEnumColumn имеет значение NULL.

  • pfnRealloc имеет значение NULL.

JET_errNoCurrentRecord

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

JET_errNotInitialized

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

JET_errRecordDeleted

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

JET_errRestoreInProgress

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

JET_errSessionSharingViolation

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

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

JET_errTermInProgress

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

При успешном выполнении запрошенные данные будут возвращены в выходных буферах. Вызывающий объект отвечает за освобождение памяти, выделенной этим обратным вызовом и возвращаемой в выходных буферах. Эта память должна быть освобождена с помощью предоставленного обратного вызова , совместимого с realloc . Изменение состояния базы данных не произойдет.

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

Комментарии

Если вы перечисляете все значения столбцов в записи и не указали JET_bitEnumerateIgnoreDefaults вы не можете предположить, что вы никогда не увидите значение столбца или столбца с кодом состояния JET_wrnColumnNull. Этот код состояния можно увидеть, если столбец имеет значение по умолчанию и явно задано значение NULL или столбец является неразреженным столбцом (например, фиксированным или переменным столбцом).

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

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

Требования

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

Клиент

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

Сервер

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

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

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

Библиотека

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

DLL

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

См. также:

JET_ERR
JET_GRBIT
JET_SESID
JET_TABLEID
JET_ENUMCOLUMNID
JET_ENUMCOLUMN
JET_ENUMCOLUMNVALUE
JET_PFNREALLOC
realloc
JetRetrieveColumn
JetRetrieveColumns