Функция 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