Функция JetUpdate

Статья
06/13/2023

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

Функция JetUpdate

Функция JetUpdate выполняет операцию обновления, включая вставку новой строки в таблицу или обновление существующей строки. Удаление строки таблицы выполняется путем вызова JetDelete.

JetUpdate — это последний шаг при выполнении вставки или обновления. Обновление начинается с вызова JetPrepareUpdate , а затем путем вызова JetSetColumn или JetSetColumns один или несколько раз, чтобы задать состояние записи. Наконец, вызывается JetUpdate для завершения операции обновления. Индексы обновляются только JetUpdate или JetUpdate2, но не во время JetSetColumn или JetSetColumns.

    JET_ERR JET_API JetUpdate(
      __in          JET_SESID sesid,
      __in          JET_TABLEID tableid,
      __out_opt     void* pvBookmark,
      __in          unsigned long cbBookmark,
      __out_opt     unsigned long* pcbActual
    );

Параметры

sesid

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

tableid

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

pvBookmark

Указатель на возвращенную закладку для вставленной строки.

cbBookmark

Размер буфера, на который указывает pvBookmark.

pcbActual

Возвращаемый размер закладки для вставленной строки, возвращаемой в pvBookmark.

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

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

Код возврата	Описание
JET_errSuccess	Операция выполнена успешно.
JET_errBufferTooSmall	Указанный буфер для закладки записи недостаточно велик для хранения закладки записи.
JET_errClientRequestToStopJetService	Невозможно выполнить операцию, так как все действия экземпляра, связанного с сеансом, прекратились в результате вызова JetStopService.
JET_errColumnIllegalNull	То же, что и JET_errNullInvalid.
JET_errDiskFull	Операция обновления требует увеличения файла базы данных или выделения файла журнала, но диск, на котором находится файл базы данных или ряд журналов, заполнен. Кроме того, файл базы данных находится на томе в формате FAT32, а размер файла базы данных уже составляет 4 ГБ, что является ограничением на каждый файл для FAT32.
JET_errInstanceUnavailable	Невозможно выполнить операцию, так как экземпляр, связанный с сеансом, столкнулся с неустранимой ошибкой, требующей отмены доступа ко всем данным для защиты целостности этих данных. Windows XP: Эта ошибка будет возвращена только в Windows XP и более поздних выпусках.
JET_errInvalidParameter	Заданный параметр подготовки в функции JetPrepareUpdate не является допустимым флагом.
JET_errKeyDuplicate	Ключ индекса для этой записи является дубликатом другого ключа индекса для другой записи, уже существующей в таблице, и индекс не допускает дублирования.
JET_errKeyTruncated	Вставленная или обновленная запись имеет один или несколько индексов, для которых созданный ключ превысил бы максимально допустимый размер. В результате операции не удалось предотвратить усечение ключа.
JET_errMultiValuedIndexViolation	Вставленная или обновленная запись содержит индексированные многозначные столбцы с двумя или более значениями, идентичными в пределах максимального размера ключа длины, установленного для индекса. В результате запись содержит две одинаковые записи в индексе, которая является недопустимой.
JET_errNotInitialized	Невозможно выполнить операцию, так как экземпляр, связанный с сеансом, еще не инициализирован.
JET_errNullInvalid	Один или несколько столбцов в вставленной записи или в обновленном состоянии заменяемой записи имеет значение NULL , что нарушает определенное ограничение для этих столбцов.
JET_errNullKeyDisallowed	Один или несколько индексов не допускают ключ NULL , а вставленное или обновленное состояние заменяемой записи нарушает это определенное ограничение.
JET_errRecordPrimaryChanged	Операция замены записей обновила первичный ключ. Обновления столбцов первичного ключа необходимо удалить существующую запись и вставить новую запись с нужными данными.
JET_errRestoreInProgress	Невозможно выполнить операцию, так как операция восстановления выполняется в экземпляре, связанном с сеансом.
JET_errSessionSharingViolation	Один и тот же сеанс нельзя использовать для нескольких потоков одновременно. Windows XP: Эта ошибка будет возвращена только в Windows XP и более поздних выпусках.
JET_errTermInProgress	Невозможно завершить операцию, так как экземпляр, связанный с сеансом, завершает работу.
JET_errTransReadOnly	Попытка обновления в область транзакции только для чтения является недопустимой. Транзакция только для чтения — это транзакция, запущенная с помощью вызова JetBeginTransaction2 с JET_bitTransactionReadOnly. Windows XP: Эта ошибка будет возвращена только в Windows XP и более поздних выпусках.
JET_errUpdateNotPrepared	Метод JetPrepareUpdate был вызван с JET_prepCancel но курсор не находился в подготовленном состоянии.
JET_errVersionStoreOutOfMemory	Операция завершилась сбоем, так как недостаточно памяти для хранения транзакционных сведений об обновлении.
JET_errWriteConflict	Другой сеанс ранее заблокировал запись для обновления. Попытка обновления, предпринятая этим сеансом, завершится ошибкой.

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

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

Важно понимать влияние выполнения большого количества операций обновления в одной транзакции. Каждое обновление базы данных должно отслеживаться ядром СУБД в хранилище версий. Хранилище версий содержит динамическую запись всех разных версий каждой записи или записи индекса в базе данных, которую могут видеть все активные транзакции. Эти версии используются для поддержки управления параллелизмом с несколькими версиями, используемого ядром СУБД для поддержки транзакций, использующих изоляцию snapshot. После того как ядро СУБД исчерпало ресурсы, используемые для хранения этих версий, оно больше не сможет принимать дальнейшие изменения, пока не будут завершены некоторые транзакции, чтобы позволить освободить эти ресурсы. Когда подсистема находится в этом состоянии, все обновления завершатся сбоем с JET_errVersionStoreOutOfMemory. Ресурсами, доступными ядру СУБД для хранения этих версий, можно управлять с помощью JetSetSystemParameter с JET_paramMaxVerPages и JET_paramGlobalMinVerPages.

Требования

Требование	Значение
Клиент	Требуется 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
JetDelete
JetPrepareUpdate
JetRegisterCallback
JetRetrieveColumn
JetRetrieveColumns
JetSetColumn
JetSetColumns
JetSetSystemParameter
Системные параметры

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

Функция JetUpdate