Функция 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_errInvalidParameter |
Один из предоставленных параметров содержал непредвиденное значение или значение, которое не имело смысла в сочетании со значением другого параметра. Эта ошибка будет возвращена JetEnumerateColumns , если:
|
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
Обратная связь
Ожидается в ближайшее время: в течение 2024 года мы постепенно откажемся от GitHub Issues как механизма обратной связи для контента и заменим его новой системой обратной связи. Дополнительные сведения см. в разделе https://aka.ms/ContentUserFeedback.
Отправить и просмотреть отзыв по