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 modeThis 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).
Each update operation re-reads the disk record, so previous changes made in this
transaction are recognized.
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.
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.
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:
This allows multiple index files to be updated in the transaction while only updating the
data record once.
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.
*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.