BltIx4UpdateEx


< Prev  TOC  Next >

TBLT_RETC TBLT_ENTRY BltIx4UpdateEx(TBLT_IUEX *iuexPtr,
                                    ULONG *slotPtr,
                                    ULONG maMode);


 iuexPtr        I:insert/update control structure
 slotPtr        O:slot that failed
 maMode         I:memory allocation mode

This routine operates on a list of update operations as a single transaction. If any of the operations fail, all previous operations are backed out.

The following TBLT_IUEX structure must be filled, one for each operation in the list to perform:

 typedef struct _BLTIUEX {
  TBLT_KH *khPtr;       // I:KH of index file
  VOID *keyBufferPtr;   // O:key buffer (separate buffer for each operation)
  VOID *recordPtr;      // I:updated record data
  ULONG recNo;          // I:recNo to update
  ULONG action;         // O:action performed (see below) (I:set to 0)
  ULONG flags;          // I:operation flags (see below)
  VOID *rsvPtr;         // set to 0 (used internally)
  VOID *nextPtr;        // I:next TBLT_IUEX, or 0 if no more
 } TBLT_IUEX;

khPtr is the pointer to the TBLT_KH structure for this list item.

keyBufferPtr must be at least as large as the key length for the handle. This cannot be shared with other items in the list (ie, key buffers cannot be shared with other TBLT_IUEX items in the list).

recordPtr is the new data with which the record at recNo is to be updated. It must always be a valid pointer to an entire data record. This data is written to the khPtr->xbLinkPtr->handle (ie, the data file for this index).

recNo is the record number to update.

action is set to one of the following values for each operation performed:

  0=nothing done (new record and disk record are the same, or nothing done due to error)
  1=updated data record only (key did not change)
  2=updated index only (flags bit0=1 so no record update)
  3=updated index and updated data record (key did change)
 16=could not store new key (reindex required)
 17=record update failed (data is unchanged)
 32=same as 16 plus: could not restore original key (reindex required)
 33=same as 17 plus: could not remove new and/or restore original key (reindex required)
 64 plus 16,17,32,33 then backout failed

flags modifies the operation performed on this item:

 FLAGSEX_IU_SKIPDATA: the data at recordPtr is not updated to the data file
For FLAGSEX_IU_SKIPDATA to be used, the following must be true:
  1. The first list item may not use FLAGSEX_IU_SKIPDATA
  2. The data at *recordPtr has already been updated (written to disk) in this operation
This allows multiple index files to be updated in the transaction while only updating the data record once.

Each update operation re-reads the disk record, so previous changes made in this transaction are recognized.

rsvPtr is used internally, and should be initialized to 0.

nextPtr is used to link to the next operation in the list. Each operation uses a separate TBLT_IUEX structure. When linked together via this nextPtr, the list becomes the transaction list: each operation (each IUEX) is executed in order; if all operations succeed, the transaction is successful. Set .nextPtr to 0 in the last list operation to mark that TBLT_IUEX structure as the last in the list.

On a successful transaction, the index for each handle is re-positioned to the last key updated.

If any update operation failed, for whatever reason, all previous operations in the list are backed out automatically, thereby restoring the database to its original state. *slotPtr has the the list item that failed (the first list item is 1).

maMode is the memory allocation mode used for a temporary buffer to store all data records that are to be modified in the transaction. The standard maMode is 0. The maximum memory that can be allocated is determined by the global bullet_MASZ value (available using BltGetVar()/BltSetVar(). If this size is exceeded EXB_UPDATE_TOO_LARGE is returned before doing any work. Otherwise, there is no limit to the number of operations performed in this, or any, Bullet transaction list.

You need to manually handle memo data in transactions. For help on this contact Bullet support (see the Technical support page in this manual).

Return: Non-zero indicates an error, with *slotPtr set to the list item that failed (slot 1 is the first item in the list); otherwise all operations in the list completed successfully.

All content Copyright © 1999 Cornel Huth. All rights reserved.