AddNew - method of the AdoRecordset object

Description:

Specifies 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 record automatically.
The edit mode is ended and confirmed by the Update method or cancelled by the CancelUpdate method.

Syntax:

Empty AddNew([Variant aFields], [Variant aValues])

Parameters:

aFields	[optional] (Variant) A single name, or an array of column 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, then aValues must be also 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 disables 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 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 Update method) all modified values.
There are 3 ways to set 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 parameters. See option 1) Example

2) Adding the record by the AddNew method without parameters, then modify the field values by repeating the Value method and then confirming the data by the Update method without parameters. See option 2) Example

3) Adding the record by the AddNew method without 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 current record position, 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 means of the Pm_LastErr property of the Wrapper object object (that wrapps each AdoRecordset object automatically in the PROMOTIC system).
In case of an error, either the operation can be executed again with correct values or cancel the edit mode by the CancelUpdate method. See Example.

Example:

Adds a new record into the table ("table1"), by the stored AdoRecordset object ("table1"), in the PmaAdo object ("/TestAdoDb"), that is already connected to the database (see the DbOpen method), by means of the SQL query ("SELECT * FROM table1").

1)Example

JavaScriptVBScriptSelect and copy to clipboard



var oDb = pMe.Pm("/TestAdoDb");

var oRs = oDb.RsOpen("table1", "SELECT * FROM table1", "cursor:static;lock:optimistic;");

var aColsName = Pm.Array1("name", "value");

var aValues = Pm.Array1("pi", 3.14);

if (oRs)

{

	oRs.AddNew(aColsName, aValues);

	oRs.Update();

	if (oRs.Pm_LastErr != 0)

	{

		oRs.CancelUpdate();

	}

}

2) Example

JavaScriptVBScriptSelect and copy to clipboard



var oDb = pMe.Pm("/TestAdoDb");

var oRs = oDb.RsOpen("table1", "SELECT * FROM table1", "cursor:static;lock:optimistic;");

if (oRs)

{

	oRs.AddNew();

	oRs.Fields.Item("name").Value = "pi";

	oRs.Fields.Item("value").Value = 3.14;

	oRs.Update();

	if (oRs.Pm_LastErr != 0)

	{

		oRs.CancelUpdate();

	}

}

3) Example

JavaScriptVBScriptSelect and copy to clipboard



var oDb = pMe.Pm("/TestAdoDb");

var oRs = oDb.RsOpen("table1", "SELECT * FROM table1", "cursor:static;lock:optimistic;");

var aColsName = Pm.Array1("name", "value");

var aValues = Pm.Array1("pi", 3.14);

if (oRs)

{

	oRs.AddNew();

	oRs.Update(aColsName, aValues);

	if (oRs.Pm_LastErr != 0)

	{

		oRs.CancelUpdate();

	}

}

4) It is also possible to add a record while not using the AdoRecordset object, but by calling directly the SQL statement INSERT by the DbExecute method.

JavaScriptVBScriptSelect and copy to clipboard



var oDb = pMe.Pm("/TestAdoDb");


oDb.DbExecute("", "INSERT table1 (name, value) VALUES ('pi', 3.14)", "");

if (oDb.LastErr != 0)

{

	// ...

}

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 with confirmation the Update.