Функция JetSetColumn

Статья
06/13/2023

Применимо к: 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

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

tableid

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

columnid

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

pvData

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

cbData

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

grbit

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

Значение	Значение
JET_bitSetAppendLV	Этот параметр используется для добавления данных в столбец типа JET_coltypLongText или JET_coltypLongBinary. Такого же поведения можно достичь, определив размер существующего длинного значения и указав ibLongValue в psetinfo. Однако использовать этот гбит проще, так как знать размер существующего значения столбца не требуется.
JET_bitSetOverwriteLV	Этот параметр используется для замены существующего значения long новыми данными. Если этот параметр используется, это так, как если бы существующее значение long было задано в 0 (ноль) длины перед установкой новых данных.
JET_bitSetRevertToDefaultValue	Этот параметр применим только для столбцов с тегами, разреженных или многозначных столбцов. Это приводит к тому, что столбец возвращает значение столбца по умолчанию при последующих операциях извлечения столбцов. Удаляются все существующие значения столбцов.
JET_bitSetSeparateLV	Этот параметр используется для принудительного хранения длинного значения столбцов типа JET_coltypLongText или JET_coltypLongBinary отдельно от остальных данных записи. Обычно это происходит, когда размер длинного значения не позволяет сохранить его с оставшимися данными записи. Однако этот параметр можно использовать для принудительного хранения значения long отдельно. Обратите внимание, что длинные значения размером четыре байта меньшего размера не могут быть принудительно разделены. В таких случаях параметр игнорируется.
JET_bitSetSizeLV	Этот параметр используется для интерпретации входного буфера как целочисленного числа байтов, устанавливаемого в качестве длины длинного значения, описанного заданным columnid , и , если он указан, порядковый номер в psetinfo-itagSequence>. Если заданный размер больше существующего значения столбца, столбец будет расширен на 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 (ноль), то указанное значение должно быть добавлено в конец последовательности многозначных значений. Если указанный порядковый номер больше, чем последнее существующее многозначное значение, то снова данное значение добавляется в конец последовательности значений. Если порядковый номер соответствует существующему значению, то это значение заменяется заданным значением.

Значение

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, значение 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 Professional.
Сервер	Требуется 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

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

Функция JetSetColumn