Creates a new record object for a table referenced in JSDO memory and returns a reference to the new record.

To synchronize the change on the server, call the saveChanges( ) method.

Alias: create( )

Return type: progress.data.JSRecord class

Applies to: progress.data.JSDO class, table reference property (JSDO class)

Working record: After completing execution, the new record becomes the working record for the associated table. If the table has child tables, the working record for these child tables is not set.

Syntax

jsdo-ref.add ( [new-record-object] )
jsdo-ref.table-ref.add ( [new-record-object] )
jsdo-ref
A reference to the JSDO. You can call the method on jsdo-ref if the JSDO has only a single table reference.
table-ref
A table reference on the JSDO.
new-record-object
If specified as a non-null object, passes in the data to create the record for the JSRecord instance. The data to create the record is identified by one or more properties, each of which has the name of a corresponding field in the table schema and has the value to set that field in the new table record.

If you omit or set the parameter to null, or you do not include properties of new-record-object for all fields in the new record, the method uses the default values from the table schema stored in the catalog to set the unspecified record fields.

Note: After this method adds the new record object, and if you have set up automatic sorting using the autoSort property, all the record objects for the affected table reference are sorted accordingly. If the sorting is done using sort fields, any string fields are compared according to the value of the caseSensitive property.

If the specified table reference is for a child table in a multi-table resource, when the useRelationships property is true, add( ) uses the relationship to set related field values of the new child record from the working record of the parent table. However, if the working record of the parent is not set, add( ) throws an error. If useRelationships is false, the fields for the new record are set as specified by new-record-object and no error is thrown.

Example

Assuming useRelationships is true, given a JSDO created for a multi-table resource with a customer and related child order table, the add( ) method in the following code fragment uses this relationship to automatically set the CustNum field in a new record added to the order table:

var dataSet = new Progress.data.JSDO( 'CustomerOrderDS' );
dataSet.customer.add( { CustNum: 1000, Balance: 10000, State: 'MA' } );

// CustNum is set automatically by using the relationship
dataSet.order.add( { OrderNum: 1000 } );

See also:

autoSort property, caseSensitive property, fill( ) method, getId( ) method, getSchema( ) method, data property, saveChanges( ) method