DbiBatchMove

C syntax

DBIResult DBIFN DbiBatchMove (pSrcTblDesc, hSrcCur, pDstTblDesc, hDstCur, ebatMode, iFldCount, pSrcFldMap, pszIndexName, pszIndexTagName, iIndexId, [pszKeyviolName], [pszProblemsName], [pszChangedName], p1ProbRecs, p1KeyvRecs, p1ChangedRecs, bAbortOnFirstProb, bAbortOnFirstKeyviol, p1RecsToMove, bTransliterate);

Delphi syntax

function DbiBatchMove (pSrcTblDesc: pBATTblDesc; hSrcCur: hDBICur; pDstTblDesc: pBATTblDesc; hDstCur: hDBICur; ebatMode: eBATMode; iFldCount: Word; pSrcFldMap: PWord; pszIndexName: PChar; pszIndexTagName: PChar; iIndexId: Word; pszKeyviolName: PChar; pszProblemsName: PChar; pszChangedName: PChar; lProbRecs: PLongint; lKeyvRecs: PLongint; lChangedRecs: PLongint; bAbortOnFirstProb: Bool; bAbortOnFirstKeyviol: Bool; var lRecsToMove: Longint; bTransliterate: Bool): DBIResult stdcall;

Description

DbiBatchMove is used to append, update, or subtract records from a source table to a destination table. It can also be used to copy an entire table to a table of a different driver type.

Parameters
pSrcTblDesc	Type: pBATTblDesc	(Input)
Optional. Pointer to the source table descriptor (BATTblDesc). If NULL, then hSrcCur is used to identify the source table. If not NULL, the specified table is opened, and the entire table is processed.
hSrcCur	Type: hDBICur	(Input)
Optional. Specifies the cursor handle of the source table; hSrcCur is used only if psrcTab is NULL. The source table is processed from the current position of the cursor.
pDstTblDesc	Type: pBATTblDesc	(Input)
Optional. Pointer to the destination table descriptor (BATTblDesc). If NULL, then hDstCur is used to identify the destination table. If not NULL, the specified table is opened, and the entire table is processed. Must be specified if mode is batCOPY.
hDstCur	Type: hDBICur	(Input)
Optional. Specifies the cursor handle of the destination table; hDstCur is used only if pdstTab is NULL. The destination table is processed from the current position of the cursor.
ebatMode	Type: eBATMode	(Input)
Specifies the mode; valid modes are batAPPEND, batUPDATE, batAPPENDUPDATE, batSUBTRACT, or batCOPY. The mode determines how the append operation is used. See the Usage section for details.
iFldCount	Type: UINT16	(Input)
Specifies the number of fields in pSrcFldMap. Optional. Normally set to 0.
pSrcFldMap	Type: pUINT16	(Input)
Pointer to an array of field numbers in the source table to be copied; the number of fields in the array must be equal to iFldCount. Optional. If set to NULL, the fields in the source are matched from left to right with the fields in the destination. This array is indexed by the destination field position (0 to n-1) and contains either the source field number (1 to n) to be matched with the destination or zero to leave the destination field blank or unmodified.
pszIndexName	Type: pCHAR	(Input)
Pointer to the index name. Optional. This parameter is used only when ebatMode is batUPDATE, batAPPENDUPDATE, or batSUBTRACT to specify the index used by the destination table to define matching records.
pszIndexTagName	Type: pCHAR	(Input)
Pointer to the index tag name. Optional. This parameter is used only when ebatMode is batUPDATE, batAPPENDUPDATE, or batSUBTRACT to specify the index used by the destination table to define matching records.
iIndexId	Type: UINT16	(Input)
Specifies the index identification number. Optional. This parameter is used only when ebatMode is batUPDATE, batAPPENDUPDATE, or batSUBTRACT to specify the index used by the destination table to define matching records.
pszKeyviolName	Type: pCHAR	(Input)
Optional. Pointer to the Key Violation table name. All records that cause an integrity violation when inserted or updated into the destination table can be placed here. If NULL, no Key Violation table is created. If the user supplies a table name, that name is used. If not NULL and a pointer to a NULL character is specified, BDE generates a name for the auxiliary table and copies the name back to the location specified by the pointer; therefore, this area must be at least DBIMAXPATHLEN+1 bytes. If no auxiliary table is created, this area is set to all NULLs.
pszProblemsName	Type: pCHAR	(Input)
Optional. Pointer to the Problems table name. Unless the user has overridden the default behavior with a callback, records are placed in a Problems table if they cannot be placed into the destination table without trimming data.
If NULL, no Problems table is created. If the user supplies a table name, that name is used. If not NULL and a pointer to a NULL character is specified, BDE generates a name for the auxiliary table and copies the name back to the location specified by the pointer; therefore, this area must be at least DBIMAXPATHLEN+1 bytes. If no auxiliary table is created, this area is set to all NULLs.
pszChangedName	Type: pCHAR	(Input)
Optional. Pointer to the Changed table name. A change table is created when DbiBatchMove is called with ebatMode being either batUPDATE or batAPPENDUPDATE. If NULL, no Changed table is created. If the user supplies a table name, that name is used. If not NULL and a pointer to a NULL character is specified, BDE generates a name for the auxiliary table and copies the name back to the location specified by the pointer; therefore, this area must be at least DBIMAXPATHLEN+1 bytes. If no auxiliary table is created, this area is set to all NULLs.
p1ProbRecs	Type: pUINT32	(Output)
Pointer to the client variable that receives the number of records that were added, or would have been added to the Problems table. (When pszProblemsName is NULL, the Problems table is not actually created. In that case, p1ProbRecs reports the number of records that would have been added to the Problems table.) Optional. If p1ProbRecs is NULL, the number of records is not returned.
p1KeyvRecs	Type: pUINT32	(Output)
Pointer to the client variable that receives the number of records that were added, or would have been added to the Key Violations table. (If pszKeyViolName is NULL, the Key Violations table is not actually created. In that case, p1KeyvRecs reports the number of records that would have been added to the Key Violations table.) Optional. If p1KeyvRecs is NULL, the number of records is not returned.
p1ChangedRecs	Type: pUINT32	(Output)
Pointer to the client variable that receives the number of records that were added, or would have been added to the Changed table. (If pszChangedName is NULL, the Changed table is not actually created. In that case, p1ChangedRecs reports the number of records that would have been added to the Changed table.) Optional. If p1ChangedRecs is NULL, the number of records is not returned.
bAbortOnFirstProb	Type: BOOL	(Input)
Specifies whether to cancel as soon as a record is encountered that would be written to the Problems table. If TRUE, the operation is canceled and DBIERR_NONE is returned.
bAbortOnFirstKeyviol	Type: BOOL	(Input)
Specifies whether to cancel as soon as a record is encountered that would be written to the Key Violations table. If TRUE, the operation is canceled and DBIERR_NONE is returned.
p1RecsToMove	Type: pUINT32	(Input/Output)
On input, p1RecsToMove specifies the number of records to be read from the source table. On output, pointer to the client variable that receives the actual number of records read from the source table. If p1RecsToMove contains 0 or p1RecsToMove is NULL, all of the records in the table are processed.
bTransliterate	Type: BOOL	(Input)
Specifies whether to transliterate character data from one character set to another, when the source and destination character sets differ. TRUE causes all data in character fields of the source table to be transliterated into the character set of the destination table.

Usage

Depending on the mode specified in ebatMode, DbiBatchMove can be used in the following ways:

Mode	Use
batAPPEND	Adds records from the source table to the destination table.
batUPDATE	Overwrites matching records in the destination table, which must have a unique index. (Records from the source table that don't match are not added.)
batAPPENDUPDATE	Adds non-matching records to the destination table, which must have a unique index, and overwrites matching records.
batSUBTRACT	Deletes matching records from the destination table, which must have a unique index.
batCOPY	Copies a table to a new table of a different driver type. This creates the destination table with a record structure that minimizes potential data loss. (See the following section for a description of the method by which field types are translated.)

Important:

For batAPPEND and batCOPY no index is required on the destination table. For the other three mode options an index is required.

Where an index is required on the destination table, the index is used to find matching records.

When the source and destination record structures differ in the field size or type, data from the source table is converted to the size or type of the destination table. If the conversion is not allowed, an error is returned and no data is transferred.

As each destination record is constructed, the default behavior is to trim any data that does not fit, possibly producing a NULL value in the destination. To override this default behavior, the client must register a callback of type cbBATCHRESULT with a client-allocated callback buffer CBRESTCbDesc (the same structure as is used for DbiDoRestructure). Before data transfer begins a callback is made for each pair of source and destination fields that could result in data loss. During this callback, RESTCBDesc.iErrCode is set to DBIERR_OBJMAYBETRUNCATED, RESTCBDesc.eRestrObjType is set to restrNEWFLD, RESTCBDesc.iObjNum is set to the field number of the destination field, and RESTCBDesc.uObjDesc.fldDesc contains the destination FLDDesc. If the client returns cbrYES from the callback, this field is trimmed. If cbrNO is returned, then any records that would be trimmed are written to the problems table instead of the destination. If any one field is marked for no trimming and the data must be trimmed, the entire record is written to the Problems table.

You can adjust the size of a batch to accommodate server transaction logs that are not big enough to handle the whole batch. Set the database property dbBATCHCOUNT for the number of records you want to include in a batch before an auto-commit occurs. The value you set will override the default and take effect for all subsequent calls of DbiBatchMove. You can reset the default (32 Kb) by using the BDE Administrator to change the Database Configuration option BATCH COUNT.

Note:

When using a Sybase or Microsoft backend, you cannot do a DbiBatchMove using eBATMode set to batCOPY to copy a table containing a memo field larger than 32K. This is a server limitation. You should create the new table, add a unique index, and then use DbiBatchMove with eBATMode set to batAPPEND instead.

Oracle8: Not supported for object types (ADT, REF, nested table, and VARARRAY).

Prerequisites

If cursors are not passed in, this call acquires a read lock on the source and a write lock on the destination. If cursors are passed in, the client is responsible for controlling locking behavior.

Completion state

If the function is called within the context of a transaction on the destination database handle, it does not modify the transaction.

DbiResult	Meaning
DBIERR_NONE	The operation was performed successfully.
DBIERR_INVALIDPARAM	Either the source or the destination table identification is invalid.
DBIERR_INVALIDFILENAME	The source table name provided is an empty string.