Data object's methods for data modification

TransactionStart

Begins a transaction for multiple data modifications.  This function can improve performance when there is a large number of operation and allows cancellation all operations included in a single transaction. The transaction is aborted if any of the operations inside of it fail.

Function TransactionStart( param(optional) )

Parameters:

string param - set it to "append" to request the fast record insertion mode, append only can be done in this mode

Return value:

none

An exception is thrown in case of errors.

VB Sample

DB.TransactionStart()

Do

   DB.UpdateStart()

   DB.SetCellNull "Field1"

   DB.UpdateFinish()

Loop While( DB.GoNext() )

DB.TransactionFinish()

End If

TransactionFinish

Closes a transaction started with TransactionStart.

Function TransactionFinish( commit(optional, default true) )

Parameters:

boolean commit - true: commit the operations contained in the transaction.  Otherwise, the transaction and all operations contained within are aborted

Return value:

none

An exception is thrown in case of errors.

VB Sample

DB.TransactionStart()

Do

   DB.UpdateStart()

   DB.SetCellNull "Field1"

   DB.UpdateFinish()

Loop While( DB.GoNext() )

DB.TransactionFinish()

End If

AppendStart

Prepares a record set for insertion of a new record. Should be concluded with a call to AppendFinish.

Function AppendStart()

Parameters:

none

Return value:

none

An exception is thrown in case of errors.

VB Sample

DB.TransactionStart()

For I = 1 To 100

   DB.AppendStart()

   DB.SetCellNull "Field1", I

   DB.AppnedFinish()

Next

DB.TransactionFinish()

End If

AppendFinish

Inserts a new record into the database table. AppendStart should be called prior to this method.

Function AppendStart( get_id(optional, default - false) )

Parameters:

boolean - get_id: true -  return the unique identifier for the newly inserted record.  For some databases, this id may be unavailable.

Return value:

variant - a new unique identifier for the inserted record; empty if a value is not available.

An exception is thrown in case of errors.

VB Sample

DB.TransactionStart()

For I = 1 To 100

   DB.AppendStart()

   DB.SetFieldValue "Field1", I

   DB.AppnedFinish()

Next

DB.TransactionFinish()

End If

UpdateStart

Prepares the record set for modification of record data. Should be concluded with a call to UpdateFinish. 

Function UpdateStart()

Parameters:

none

Return value:

none

An exception is thrown in case of errors.

VB Sample

DB.TransactionStart()

Do

   DB.UpdateStart()

   DB.SetCellNull "Field1"

   DB.UpdateFinish()

Loop While( DB.GoNext() )

DB.TransactionFinish()

End If

UpdateFinish

Finishes modifications to record data. UpdateStart should be called prior to calling this method.

Function UpdateFinish( scope(optional) )

Parameters:

string - scope: an SQL expression defining the records scope to be affected by this operation.  If this parameter is not present, only the current record is modified.

Return value:

none

An exception is thrown in case of errors.

VB Sample

DB.TransactionStart()

Do

   DB.UpdateStart()

   DB.SetCellNull "Field1"

   DB.UpdateFinish()

Loop While( DB.GoNext() )

DB.TransactionFinish()

End If

SetFieldValue

Sets a field value. This method should be called between AppendStart and AppendFinish or between UpdateStart and UpdateFinish.

Function SetFieldValue( name, value )

Parameters:

string name - name of the field to be modified.

variant value - the new field value.

Return value:

none

An exception is thrown in case of errors.

VB Sample

DB.TransactionStart()

For I = 1 To 100

   DB.AppendStart()

   DB.SetFieldValue "Field1", I

   DB.AppnedFinish()

Next

DB.TransactionFinish()

End If

SetCellNull

Sets a field value to Null. This method should be called between AppendStart and AppendFinish or UpdateStart and UpdateFinish.

Function SetCellNull( name )

Parameters:

string name - name of the field to be modified.

Return value:

none

An exception is thrown in case of errors.

VB Sample

DB.TransactionStart()

Do

   DB.UpdateStart()

   DB.SetCellNull "Field1"

   DB.UpdateFinish()

Loop While( DB.GoNext() )

DB.TransactionFinish()

End If

DeleteRecords

Deletes records from the database table according to the record object setup or according to a scope expression that can be passed in as a parameter.

Function DeleteRecords( scope(optional) )

Parameters:

string - scope: an SQL expression defining the scope to be effected by this operation; if scope is omitted, the record(s) defined by the record object setup is(are) deleted.

Return value:

none

An exception is thrown in case of errors.

VB Sample

'Sample 1

DB.record.Set "Field1", 100

DB.DeleteRecords() ' all records with Field1 = 100 will be deleted

'Sample 2

DB.DeleteRecords( "Field1 < 100" ) ' all records with Field1 < 100 will be deleted

Create

Creates a new database table.

Function Create()

Parameters:

none

Return value:

none

An exception is thrown in case of errors.

VB Sample

DB.Create() ' see an output data object setup to learn how to initialize the object

DB.TransactionStart()

For I = 1 To 100

   DB.AppendStart()

   DB.SetFieldValue "Field1", I

   DB.AppnedFinish()

Next

DB.TransactionFinish()

End If

Close

Closes the current database session and frees all of the related resources.

Function Close()

Parameters:

none

Return value:

none

An exception is thrown in case of errors.

VB Sample

Dim val

If DB.Select() Then

   Do

      val = DB.GetCellVaue( "Field1" )

   Loop While( DB.GoNext() )

   DB.Close()

End If