Promotic
WikipediaLinkedInYoutubeTwitterFacebook

AddNew - method of object AdoRecordset

Description:
Defines the beginning of the edit mode for adding a new record into the AdoRecordset object. The content of the added record is either empty or filled with parameter values aFields and aValues. The new added record becomes a current selected record automatically. The edit mode is ended and confirmed by the Update method or cancelled by the CancelUpdate method.
Syntax:
AddNew([aFields As Variant], [aValues As Variant])
Calling:
oRs.AddNew aFields, aValues
Parameters:
aFields[optional] (Variant) A single name, or an array of names or ordinal positions of the fields in the record.
aValues[optional] (Variant) A single value, or an array of values for the fields in the new record. If aFields is an array, aValues must also be an array with the same number of members; otherwise, an error occurs. The order of field names must match the order of field values in each array.
Note:

If the table has a defined index or column, that forbids adding record with the <Null> value, then it is necessary to initialize the record with the parameter values aFields and aValues.

After calling this method, the values of the new record can be modified, for example, by the Fields and Value methods (e.g. oRs.Fields("test1").Value = 123).

 
The parameters aFields and aValues can be used to give the AddNew method (also to the Updatemethod) all modified values. There are 3 ways to define the values of a new record:
1) Adding the record by the AddNew method with defined parameters aFields and aValues with initialization values of the record fields, and the confirming the record by the Update method without any parameters. See option 1) Example
2) Ading the record by the AddNew method withou any parameters, then modify the field values by repeating the Value method and then confirming the data by the Update method without any parameters. See option 2) Example
3) Adding the record by the AddNew method without any parameters, and then confirming the data by the Update method with additional parameters aFields and aValues. See option 3) Example
 
Caution:In the edit mode, the AdoRecordset object is locked, so it is impossible to call methods for moving the position of current record, etc., until the edit mode is terminated by calling the Update or CancelUpdate methods. The Update method returns no value, but it can possibly fail (e.g. when trying to write a record with key value that allready exists or with invalid values). If the Update method fails, the AdoRecordset object stays locked and cannot be used in a normal way. Therefore it is necessary to test the result of the Update method by the Pm_LastErr property of the Wrapper object object (that wrapps each AdoRecordset object automatically in the PROMOTIC system). In case of error the operation can be executed again with correct values or cancel the edit mode by the CancelUpdate method. See Example.
Example:
Adding a new record into the table ("table1"), by the stored AdoRecordset object ("table1"), over the PmAdo object ("/TestAdoDb"), that is already connected to the database (see DbOpen), by the SQL query ("SELECT * FROM table1").
 
Common part:
Dim oDb, oRs
Set oDb = pMe.Pm("/TestAdoDb")
Set oRs = oDb.RsOpen("table1", "SELECT * FROM table1", "cursor:static;lock:optimistic;")
 
1)
  oRs.AddNew Array("name", "value"), Array("pi", 3.14)
  oRs.Update
  If oRs.Pm_LastErr <> 0 Then
    oRs.CancelUpdate
  End If
End If
 
2)
  oRs.AddNew
  oRs.Fields("name") = "pi"
  oRs.Fields("value") = 3.14
  oRs.Update
  If oRs.Pm_LastErr <> 0 Then
    oRs.CancelUpdate
  End If
End If
 
3)
  oRs.AddNew
  oRs.Update Array("name", "value"), Array("pi", 3.14)
  If oRs.Pm_LastErr <> 0 Then
    oRs.CancelUpdate
  End If
End If
 
4) It is also possible to add a record while not using the AdoRecordset object, but by calling directly the SQL command INSERT by the DbExecute method.
oDb.DbExecute "", "INSERT table1 (name, value) VALUES ('pi', 3.14)", ""
If oDb.LastErr <> 0 Then
  ...
End If
 
Caution:The options 2) and 3) are also used for editing the existing record. Only the adding of empty record by the AddNew method is omitted and it continues identically by modifying the values of the current record and confirming the Update.
© MICROSYS, spol. s r. o.Tavičská 845/21 703 00 Ostrava-Vítkovice