DbiInsertRecord

C syntax

DBIResult DBIFN DbiInsertRecord (hCursor, [eLock], pRecBuf);

Delphi syntax

function DbiInsertRecord (hCursor: hDBICur; eLock: DBILockType; pRecBuff: Pointer): DBIResult stdcall;

Description

DbiInsertRecord inserts a new record, contained in pRecBuf, into the table associated with the given cursor.

Parameters

hCursor Type: hDBICur (Input)
Specifies the cursor handle.

eLock Type: DBILockType (Input)
Specifies the lock request type. Optional.

pRecBuf Type: pBYTE (Input)
Pointer to the record buffer.

Usage

The client application can optionally acquire a lock on the newly inserted record by specifying the lock type in eLock.

dBASE, FoxPro, Access: For dBASE, FoxPro, and Access, there is no difference between DbiAppendRecord and DbiInsertRecord. The record is inserted at the end of the table. The cursor is positioned at the inserted record. If an active range exists, the cursor might be positioned at the beginning or end of the file.

Paradox: Before inserting the record, the function verifies any referential integrity requirements or validity checks that may be in place. If either fails, an error is returned and the insert operation is canceled. If a primary index is in place, the record is physically placed at a location that conforms to the primary index order. With non-indexed tables, the record is inserted before the current position.

SQL: The table must be opened for write access. After the insert, the cursor is always positioned on the inserted record.

Prerequisites

Other users cannot have a write lock, or greater, on the table. The record buffer should be initialized with DbiInitRecord, and data filled in using DbiPutField or DbiOpenBlob, and DbiPutBlob.

Completion state

After successful completion, the cursor is positioned on the new record. If the function fails, the record is not inserted and the current position of the cursor is not affected.

If the cursor has a filter or a range associated with it, the cursor might be positioned on a crack or BOF/EOF and the operation will fail if a record lock was requested.

DbiResult	Meaning
DBIERR_NONE	The record was successfully inserted.
DBIERR_INVALIDHNDL	The specified cursor handle is invalid or NULL.
DBIERR_INVALIDPARAM	The specified record buffer is NULL.
DBIERR_FOREIGNKEYERR	The target table is a detail table in a referential integrity link, and the linking value cannot be found in the master table.
DBIERR_MINVALERR	The specified data is less than the required minimum value.
DBIERR_MAXVALERR	The specified data is greater than the required maximum value.
DBIERR_REQDERR	The field cannot be blank.
DBIERR_LOOKUPTABLEERR	The specified value was not found in the assigned lookup table.
DBIERR_KEYVIOL	The table has a unique index and the inserted key value conflicts with an existing record's key value.
DBIERR_FILELOCKED	The table is locked by another user.
DBIERR_TABLEREADONLY	Table access denied; the specified cursor handle is read-only.
DBIERR_NOTSUFFTABLERIGHTS	Insufficient table rights to insert a record (Paradox only).
DBIERR_NODISKSPACE	Insert failed due to insufficient disk space.
DBIERR_RECLOCKFAILED	Insert failed because the record could not be locked due to range or filter constraint.