DbAppend Function

Add a new record to a database file.

Namespace: XSharp.RT
Assembly: XSharp.RT (in XSharp.RT.dll) Version: 2.21

Syntax

 FUNCTION DbAppend(
	lReleaseLocks,
	uArea
) AS LOGIC CLIPPER

[ClipperCallingConventionAttribute(new string[] { ... })]
public static bool DbAppend(
	Usual lReleaseLocks = default,
	Usual uArea = default
)

Request Example View Source

Parameters

lReleaseLocks (Optional): Type: Usual
A logical data type that, if TRUE, clears all pending record locks, then appends the next record.
If FALSE, all pending record locks are maintained, and the new record is added to the end of the lock list.
The default value is TRUE.
uArea (Optional): Type: Usual
Specifies the work area name or number for a table from which the value must be retrieved.

Return Value

Type: Logic
TRUE if successful; otherwise, FALSE.
If successfully added, each field in the record is set to the empty value for its data type, and the new record becomes the current record.

Remarks

By default, this function operates on the database file in the currently selected work area.
It can be made to operate on an unselected work area by specifying it within an aliased expression. DBAppend(TRUE) performs the same function as the APPEND BLANK command.
For more information, refer to APPEND BLANK.

Tip
Logical records: DBAppend() does not respect logical visibility. That is, if the record is successfully added, it becomes the current record, regardless of any order or filter condition. Shared mode: For a shared database, DBAppend() automatically places a record lock on the new record. If the record cannot be locked, NetErr() is set to TRUE, indicating that the record was not added, and execution continues.

Tip

Logical records: DBAppend() does not respect logical visibility.
That is, if the record is successfully added, it becomes the current record, regardless of any order or filter condition. Shared mode:
For a shared database, DBAppend() automatically places a record lock on the new record.
If the record cannot be locked, NetErr() is set to TRUE, indicating that the record was not added, and execution continues.

Examples

The following example appends a blank record, checks for a NetErr() condition, and updates the data:

Copy

 1DBUseArea(TRUE, "DBFNTX", "sales", "Sales", ;
 2                TRUE)
 3... <paramref name="Statements" />
 4DBAppend()
 5IF !NetErr()
 6    Sales->FirstName := cFirst
 7    Sales->LastName := cLast
 8ELSE
 9    QOut("Append operation failed")
10ENDIF

The following example first locks a record and then appends a blank record to the SALES database without releasing the record locks in the current lock list.
It also checks for errors:

Copy

1USE sales NEW
2DBRLock()        // Lock the current record
3// Add a new record but keep the old lock
4IF DBAppend(FALSE) .AND. !NetErr()
5    ? "Multiple records are locks"
6ELSE
7    ? "An error has occurred!"
8ENDIF

Reference

Functions, Globals and Defines

XSharp.RT Namespace

VoDbAppend(Logic)

DBServer:Append