Updates JSDO memory with one or more record objects read from an array, single-table, or multi-table resource that are passed in an object parameter, including any pending changes and before-image data, if they exist.
This method updates all tables or a specified table in JSDO memory, depending on how the method is called. The data is merged into JSDO memory and affects existing data according to a specified merge mode and optional key fields.
A reference to the JSDO. If you call the method on jsdo-ref, the method merges data for all referenced tables in JSDO memory.
table-ref
A table reference on the JSDO. If you call the method on table-ref, the method merges data only for the referenced table in JSDO memory.
merge-object
An object with the data to merge. If you call the method on table-ref, the object can either be an object that contains an array of record objects to merge with the referenced table or a multi-table-formatted object containing such an array.
Note: This object must have a supported JavaScript object format that matches the data returned from the resource Read operation (JSDO fill( ) method). For example, an object returned as output from an invocation method called on a single-table or multi-table resource will work if it has the same schema as output from the resource Read operation.
The following formats are supported for merge-object:
A single table object with an array of record objects. For example:
{
eCustomer: [
// Record objects ...
]
}
An array of record objects for either a single table object or a multi-table object containing only a single table object. For example:
[
// Record objects ...
]
A multi-table object with a single table object or multiple table objects at the same level only. For example:
{
dsCustomerOrder: {
eCustomer: [
// Record objects ...
],
eOrder: [
// Record objects ...
]
}
}
The record objects passed in merge-object can contain before-image data, which this method merges into JSDO memory along with the data from the record objects. However, if a record object read in from local storage contains before-image data that conflicts with existing before-image data in JSDO memory for that same record object, addLocalRecords( ) throws an exception.
add-mode
An integer that represents a merge mode to use. If you also specify key-fields, each merge mode handles duplicate keys in a particular manner as described here. If you do not specify key-fields, the method adds all the records of merge-object regardless of the mode. You can specify the following numeric constants, which affect how the table record objects in merge-object are added to JSDO memory:
progress.data.JSDO.MODE_APPEND — Adds the table record objects in merge-object to the existing record objects in JSDO memory. If a duplicate key is found between a record object in merge-object and a record object in JSDO memory, the method throws an error.
progress.data.JSDO.MODE_MERGE — Adds the table record objects in merge-object to the existing record objects in JSDO memory. If duplicate keys are found between record objects in merge-object and record objects in JSDO memory, the method ignores (does not add) the record objects with duplicate keys in merge-object.
progress.data.JSDO.MODE_REPLACE — Adds the table record objects in merge-object to the existing record objects in JSDO memory. If duplicate keys are found between record objects in merge-object and record objects in JSDO memory, the record objects with duplicate keys in JSDO memory are replaced with the corresponding records in merge-object.
progress.data.JSDO.MODE_EMPTY — Empties all table record objects from JSDO memory and replaces them with the contents of merge-object.
If merge-object is an empty object ({}), this mode effectively empties the data from JSDO memory.
After execution, if the specified merge mode was progress.data.JSDO.MODE_EMPTY, the working record set for any table references is undefined, because JSDO memory is completely emptied or replaced. For any other merge mode, the working record set for each JSDO table reference remains unchanged.
If a table key-fields matches the unique indexes of corresponding tables, adding the contents of merge-object can result in records with duplicate keys. If the corresponding tables have unique indexes, you must make any affected duplicate key fields unique before calling saveChanges( ).
key-fields
An object with a list of key fields to check for records with duplicate keys. For example, when merging into a JSDO that has eCustomer and eOrder table references, you might use the following object:
When merging with a single table reference, you might use the following array object:
[ "CustNum", "Ordernum" ]
Note: For any key-fields that have the string data type, the character values for these fields are compared to identify duplicates according to the value of the caseSensitive property on each affected table reference.
Note: After this method checks for any duplicate keys and completes adding record objects to JSDO memory from merge-object, and if you have set up automatic sorting using the autoSort property, all the record objects for the affected table references are sorted accordingly. If the sorting is done using sort fields, any string values in the specified sort fields are compared according to the value of the caseSensitive property.
A typical use for addRecords( ) is to merge additional data returned by an invocation method without having to re-load JSDO memory with all the data from the fill( ) method.
Example
Given a JSDO (dataset) that you fill with available records from the eCustomer and eOrder tables of an OpenEdge ProDataSet, you might retrieve a new eOrder record as the result of a getNewOrder( ) invocation method on the JSDO and add the new record to JSDO memory as follows:
var dataset = progress.data.JSDO( "dsCustomerOrder" );
dataset.fill(); // Loads the JSDO with all available records from the ProDataSet resource
// Adds a new eOrder record restrieved from the service
var request = dataset.getNewOrder(null,false);
dataset.eOrder.addRecords( request.response, progress.data.JSDO.MODE_APPEND, [ "CustNum", "Ordernum" ], );
This code fragment adds the eOrder record for an existing eCustomer record specified by the CustNum property and a new order number specified by the Ordernum property of the single record object returned in result.dsCustomerOrder.eOrder[0].
A single table object with an array of record objects. For example: