DBTransaction

Description: This function executes in its own thread to perform a transaction on a VTS database and returns an indication of parameter errors.

Returns: Numeric

Usage: Script

Format: DBTransaction(DBSysVal, IDKey, Event, EventCode [, Timestamp, FieldVals])

DBTransaction(DBSysVal, IDKey, Event, EventCode [, Timestamp, FieldVal1, FieldVal2, FieldVal3, …])

Parameters: DBSysVal { handle } { required } { no default }
The database value to use; this is the return value from a DBSystem call.

IDKey { text } { required } { no default }
Any text expression that designates the record to use; it can contain the wildcard characters "*" and "?".

Event { text } { required } { no default }
Any text expression containing on byte for each list in the system; any missing bytes or bytes with values not included in the list below default to "do nothing to list". Note that there is one byte for each list in the system, not for each list that has been selected by the List parameter.

Text Value	Event
+	Add to list
-	Remove from list
<space>	Do nothing to list

EventCode { numeric (return value) } { required } { no default }
Any variable in which the event code for the function is returned; this parameter may be used to indicate completion of the function, as it will not be set to a valid value until execution is complete. It has the following meaning:

Value	Meaning
0	Record exists and was updated
1	Record did not exist and was added
2	Error occurred

EventCode may be replaced by a constant or Invalid if it is not required.

This parameter will never be set if there is a parameter error (see comments)

Timestamp { Timestamp } { optional } { no default }
An optional parameter that defines the time to record for the event. If this value is invalid or omitted, the transaction time defaults to the current time; if it is negative, the database file will be updated with the absolute value of this parameter and the transaction log will not be updated.

FieldVals { varies } { optional } { no default }
Required when adding a new record, otherwise, optional. This takes the form of either an array or a list of values. In either case, this is data that is to be written to the database. When writing to an existing record, the values provided will over-write the values in matching fields. When creating a new record, all fields must be defined.

Comments: This function executes in the thread created by the DBSystem call, so it will not block other statements from executing. This does mean, however, that the timing for EventCode becoming valid (marking that the statement has finished executing) is unpredictable and should therefore be checked for validity prior to executing other statements that rely on this statement's results.

The return value for this function indicates if any of its key parameters (DBSysVal, IDKey or Event) are invalid. It will immediately return a value of false (0) unless a key parameter was invalid, in which case it will return true (1). Note that the return value only signals completion of the function's execution if it is true, otherwise the function will continue executing in the thread created for it.

If the user attempts to add a record to a list on which it already exists, that record's time and position on the list will be updated unless the new time is 0, in which case no change will occur.

If the database file has its read-only attribute set when this function is executed, it will be cleared automatically by execution of the function.

Example:

db1 = DBSystemDBSystem(dbFile, "", 0, 0, 64 { key }, 10 { field 1 },

1 { field 2 }, -3 { field 3 });

If ValidValid(db1) && ! done;

[

done = 1;

DBTransaction(db1 { Database to use },

"Motor_425" { ID key },

"--+" { Subtract from lists 1 and 2,

add to list 3 },

code { Event code },

CurrentTime() { Time of the event },

FieldValues { Array of values for fields });

]