TableUpdate Function | ![X#](../icons/logo100.jpg) |
-- todo --
Commits changes made to a buffered row, a buffered table, cursor, or cursor adapter.
Namespace:
XSharp.VFP
Assembly:
XSharp.VFP (in XSharp.VFP.dll) Version: 2.19
Syntax FUNCTION TableUpdate(
nRows,
lForce,
uArea,
cErrorArray
) AS LOGIC CLIPPER
[ClipperCallingConventionAttribute(new string[] { ... })]
public static bool TableUpdate(
Usual nRows = default,
Usual lForce = default,
Usual uArea = default,
Usual cErrorArray = default
)
Request Example
View SourceParameters
- nRows (Optional)
- Type: Usual
Specifies which changes made to the table or cursor should be committed.
Note |
---|
X# enables Optimistic Row Buffering by default for those cursors associated with a CursorAdapter object.
|
The table in the remarks section describes the values for nRows.
- lForce (Optional)
- Type: Usual
Determines whether X# overwrites changes made to the table or cursor by another user on a network.
The table in the remarks section describes the values for lForce.
- uArea (Optional)
- Type: Usual
Specifies the alias of the table or cursor in which the changes are committed. If you include a table or cursor alias,
you must include the lForce argument.
Or
Specifies the work area of the table or cursor in which the changes are committed. If you include a work area,
you must include the lForce argument.
- cErrorArray (Optional)
- Type: Usual
Specifies the name of an array created when nRows = 2 and changes to a record cannot be committed.
The array contains a single column containing the record numbers of the records for which changes could not be committed.
If you include an array name, you must include either a table or cursor alias uArea or a work area number.
Note |
---|
If an error other than a simple commit error occurs while updating records, the first element of cErrorArray will contain –1,
and you can then use AError( ) to determine the why the changes could not be committed.
|
X# passes the value of cErrorArray, when it exists, to the CursorAdapter AfterCursorUpdate event.
Return Value
Type:
Logic
Logical data type.
TableUpdate( ) returns True (.T.) if changes to all records are committed.
Otherwise,
TableUpdate( ) returns False (.F.) indicating a failure. An ON ERROR routine isn't executed.
The AError( ) function can be used to retrieve information about the cause of the failure.
Note |
---|
TableUpdate( ) always returns True (.T.) when you are updating data, using Table Buffering,
and updating the table or tables in the data source from multiple clients when setting BatchUpdateCount to a value greater than 1.
|
Therefore, avoid setting
BatchUpdateCount to a value greater than 1 in these scenarios.
RemarksTableUpdate( ) cannot commit changes made to a table or cursor that does not have row or table buffering enabled.
If you issue
TableUpdate( ) and row or table buffering is not enabled, X# generates an error message.
However,
TableUpdate( ) can still commit changes to a table or cursor that has validation rules.
To enable or disable row and table buffering, use
CursorSetProp( ).
Changes are committed to the table or cursor open in the currently selected work area if
TableUpdate( )
is issued without the optional uArea arguments.
If table buffering is used and multiple records are updated,
TableUpdate( ) moves the record pointer to the last record updated.
Note |
---|
Calling TableUpdate( ) for a local table or view that does not use key fields generates a long Where clause to find the update row.
The default number of fields supported in the Where clause is 40. If you receive the error SQL: Statement too long (Error 1812),
you should either use a key field for the update or increase the complexity of the Where clause with SYS(3055).
If you use the SYS(3055) function,
increase its value to a number that is eight times the number of fields in the table as shown in the following example:
|
1SYS(3055, 8 * MIN(40, FCOUNT( ))
When performing a batched
TableUpdate( ) operation, due to the way that Open Database Connectivity (ODBC) behaves,
X# is unable to detect conflicts when no error is generated by the server, yet nothing is updated, for example,
no row matches the
Where clause. This can occur when you use WhereType set to DB_KEYANDUPDATable, DB_KEYANDMODIFIED,
or DB_KEYANDTIMESTAMP, and another user has changed one of the underlying values in the
Where clause such that the row is not
found by the update statement.
Interaction with CursorAdapter Objects The following behaviors apply when working with
CursorAdapter objects:
For more information about
GetFldState( ), see GetFldState( ) Function.
You can also modify data in the cursor. This functionality supports scenarios such as retrieving the autoincrement value from the base
table and inserting it into the cursor. When this scenario occurs, the
CursorAdapter object should automatically return to the
record whose changes are about to be committed after the event has occurred and commit the changes.
In X# 9.0, you cannot issue the TableRevert( ) Function when a TableUpdate( ) is in operation.
Typically, the CursorAdapter object uses the transaction management functionality provided by the ADO or ODBC API's and X# closes
transactions when the TableUpdate( ) function completes successfully. However, if you want to send transaction management commands directly
to the backend, you can set the UseTransactions property of the CursorAdaptor object to False (.F.) and the CursorAdapter does not use
transactions to send Insert, Update, or Delete commands.
nRows | Description |
---|
0 |
If row or table buffering is enabled, commit only the changes made to the current row in the cursor. (Default)
When working with CursorAdapter objects, X# executes the appropriate command in the InsertCmd, UpdateCmd, or DeleteCmd property for that row only.
|
1 |
If table buffering is enabled, commit changes made to all records to the table or cursor.
If row buffering is enabled, commit only changes made to the current record in the table or cursor.
When working with CursorAdapter objects, X# executes the appropriate commands in the InsertCmd,
UpdateCmd, and DeleteCmd properties for each affected row.
|
2 |
Commit changes made to the table or cursor in the same manner as when nRows = 1.
However, an error does not occur when a change cannot be committed. X# continues to process any remaining records in the table or cursor.
If cErrorArray is included, an array containing error information is created when an error occurs.
|
For compatibility with previous X# applications, the nRows parameter also accepts False (.F.) and True (.T.) instead of 0 and 1 respectively.
When specifying 0 or 1 for nRows, the record pointer remains on the record where changes could not be committed.
To determine why the changes could not be committed, use the AError( ) function.
When working with
CursorAdapter objects and specifying 1 or 2 for nRows, all changes made to the cursor in the following
CursorAdapter events must be committed during the same call to
TableUpdate( ) unless an error occurs:
X# passes the values of nRows to the
CursorAdapter BeforeCursorUpdate event.
lForce | Description |
---|
False (.F.) |
Commits changes to the table or cursor, starting with the first record and continuing towards the end of the table or cursor.
(Default)
|
True (.T.) |
Overwrites any changes made to the table or cursor by another user on a network. The Where clause uses only key fields.
|
When working with
CursorAdapter objects, X# passes the value of lForce to the following
CursorAdapter events:
Examples 1Close Databases
2Create Table employee (cLastName C(10))
3Set MultiLocks ON
4= CursorSetProp('Buffering', 5, 'employee' )
5Insert Into employee (cLastName) VALUES ('Smith')
6Clear
7? 'Original cLastName value: '
8?? cLastName
9Replace cLastName WITH 'Jones'
10? 'New cLastName value: '
11?? cLastName
12= TableUpdate(.T.)
13? 'Updated cLastName value: '
14?? cLastName
See Also