Функция JetSetColumn

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

Функция JetSetColumn

Функция JetSetColumn изменяет одно значение столбца в измененной записи для вставки или обновления текущей записи. Он может перезаписать существующее значение, добавить новое значение в последовательность значений в многозначном столбце, удалить значение из последовательности значений в многозначном столбце или обновить все или часть длинного значения, столбец типа JET_coltypLongText или JET_coltypLongBinary.

    JET_ERR JET_API JetSetColumn(
      __in          JET_SESID sesid,
      __in          JET_TABLEID tableid,
      __in          JET_COLUMNID columnid,
      __in_opt      const void* pvData,
      __in          unsigned long cbData,
      __in          JET_GRBIT grbit,
      __in_opt      JET_SETINFO* psetinfo
    );

Параметры

Sesid

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

табличный

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

columnid

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

pvData

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

cbData

Размер входного буфера в байтах.

гбит

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

Ценность

Значение

JET_bitSetAppendLV

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

JET_bitSetOverwriteLV

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

JET_bitSetRevertToDefaultValue

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

JET_bitSetSeparateLV

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

JET_bitSetSizeLV

Этот параметр используется для интерпретации входного буфера в виде целочисленного числа байтов, чтобы задать длину длинного значения, описанного заданным столбцом , а если указано, порядковый номер в psetinfo-itagSequence>. Если указанный размер превышает существующее значение столбца, столбец будет расширен с 0.0. Если размер меньше существующего значения столбца, значение будет усечено.

JET_bitSetUniqueMultiValues

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

JET_bitSetUniqueNormalizedMultiValues

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

JET_bitSetZeroLength

Этот параметр используется для задания значения нулевой длины. Как правило, значение столбца имеет значение NULL , передав cbMax 0 (ноль). Однако для некоторых типов, таких как JET_coltypText, значение столбца может быть равно 0 (ноль) вместо NULL, и этот параметр используется для различения длины NULL и 0 (ноль).

Заметка Как правило, если столбец является столбцом фиксированной длины, этот бит игнорируется, а столбец имеет значение NULL. Однако если столбец является столбцом с тегом фиксированной длины, длина столбца имеет значение 0. Если для столбца фиксированной длины задана длина 0, попытка получить столбец с помощью JetRetrieveColumn или JetRetrieveColumns будет успешно выполнена, но фактическая длина, возвращаемая в параметре cbActual, равна 0.

JET_bitSetIntrinsicLV

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

JET_bitSetCompressed

Этот параметр используется для попытки сжатия данных при хранении данных.

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

JET_bitSetUncompressed

Этот параметр не используется при хранении данных при попытке сжатия.

Windows 7: JET_bitSetUnCompressed представлен в Windows 7.

psetinfo

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

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

Для этого параметра можно задать следующие параметры:

Ценность

Значение

ibLongValue

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

itagSequence

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

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

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

Код возврата

Описание

JET_errSuccess

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

JET_errBadColumnId

Идентификатор столбца, указанный вне юридических ограничений идентификатора столбца.

JET_errClientRequestToStopJetService

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

JET_errColumnNotFound

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

JET_errColumnNotUpdatable

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

JET_errColumnTooBig

Данные значения столбца, заданные в входном буфере, превышают ограничение размера, естественное для столбца фиксированной длины или настроенного для текста фиксированной длины или двоичных столбцов. Эта ошибка также возвращается при передаче более 1024 байтов данных для длинного столбца и установке флага JET_bitSetIntrinsicLV.

JET_errInstanceUnavailable

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

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

JET_errInvalidBufferSize

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

JET_errInvalidColumnType

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

JET_errInvalidgrbit

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

JET_errInvalidParameter

Указанный объект psetinfo-cbStruct> не является допустимым размером для структуры JET_SETINFO .

JET_errMultiValuedDuplicate

Операция набора столбцов попыталась создать повторяющееся значение и указала либо JET_bitSetUniqueMultiValues, либо JET_bitSetUniqueNormalizedMultiValues.

JET_errNotInitialized

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

JET_errNotInTransaction

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

JET_errNullInvalid

Предпринята неправлая попытка задать для столбца, отличного от NULL.

JET_errColumnIllegalNull

То же, что и JET_errNullInvalid.

JET_errRecordTooBig

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

JET_errRestoreInProgress

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

JET_errSessionSharingViolation

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

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

JET_errTermInProgress

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

JET_errUpdateNotPrepared

Курсор в настоящее время не входит в процесс вставки новой записи или обновления существующей записи.

JET_errVersionStoreOutOfMemory

Эта ошибка возникает, когда настроенный размер хранилища версий недостаточно для хранения всех невыполненных обновлений.

JET_wrnColumnMaxTruncated

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

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

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

Замечания

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

Обновления индекса не выполняются в результате операций JetSetColumn . Вместо этого индексы обновляются только после завершения всех изменений столбцов и вызывается JetUpdate . Это позволяет наиболее эффективно обновлять индексы при изменении нескольких столбцов.

Запись ограничена размером на основе размера страницы базы данных. Любые длинные значения в записи размером более пяти байтов будут храниться отдельно от записи, если данные в записи превышают его предел в результате операции JetSetColumn . Ошибка, JET_errRecordTooBig будет возвращена только после того, как все данные столбца с разделителями записей хранятся отдельно от записи, а запись по-прежнему превышает ограничение размера записи.

Требования

Требование Ценность

Клиент

Требуется Windows Vista, Windows XP или Windows 2000 Профессиональный.

Сервер

Требуется 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_SETINFO
JetRetrieveColumn
JetSetColumns

  • Last updated on