Reads the record objects stored in the specified local storage area and updates JSDO memory based on these record objects, including any pending changes and before-image data, if they exist.
This method updates all affected tables of the JSDO with the locally stored record objects. These record objects are merged into JSDO memory and affect existing data according to a specified merge mode and optional key fields.
The name of the local storage area from which to update JSDO memory. If storage-name is not specified, blank, or null, the name of the default storage area is used. The name of this default area is jsdo_serviceName_resourceName, where serviceName is the name of the Data Object Service that supports the JSDO instance, and resourceName is the name of the resource (table, dataset, etc.) for which the JSDO instance is created.
Note: Record objects read in from local storage 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 constant that represents a merge mode to use. Each merge mode handles duplicate keys in a particular manner, depending on your specification of key-fields. You can specify the following numeric constants, which affect how the table record objects in the specified local storage area are added to JSDO memory:
progress.data.JSDO.MODE_REPLACE — Adds the table record objects in the specified local storage area to the existing record objects in JSDO memory. If duplicate keys are found between record objects in local storage and record objects in JSDO memory, the record objects with duplicate keys in JSDO memory are replaced with the corresponding records in local storage.
For the current release, only this single merge mode is supported. Use of any other merge mode (for example, as specified for the addRecords( ) method) throws an exception.
If any specified key-fields match the unique indexes of corresponding tables on the server, adding the contents of the specified local storage area can result in records with duplicate keys. If the corresponding server tables have unique indexes, you must make any affected duplicate key fields unique before calling saveChanges( ).
key-fields
An object with a list of primary key fields to check for records with duplicate keys. For example, when merging with a multi-table resource 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.
If key-fields is specified, the method checks for duplicate keys using the specified primary keys found in key-fields. If key-fields is not specified, the method searches other possible sources for definitions of primary keys in the following order, and uses the first source of definitions found:
1. Primary key annotations from any OpenEdge resource (as identified in the Data Service Catalog)
2. Unique ID properties associated with the resource (for example, the idProperty property as identified in the Data Service Catalog for a Rollbase object)
If no source of primary key definitions is found, the method adds all local storage records to JSDO memory, regardless of the specified add-mode, and regardless of any duplicate records that might result.
Note: For Rollbase resources, all tables that correspond to Rollbase objects have a defined primary key. For OpenEdge resources, the Progress Developer Studio for OpenEdge defines the primary key automatically using a primaryKey annotation when you create a Business Entity for the resource, either with a new Express project or with the New Business Entity wizard using the Select database table option. If you use the Select schema from file option in the New Business Entity wizard or you create the Business Entity manually, you must add this annotation for each temp-table definition yourself, which you can do using the Define Service Interface wizard in Developer Studio. For more information on service interface annotations, see the Progress Developer Studio for OpenEdge online help.
Note: After this method checks for any duplicate keys and completes adding record objects to JSDO memory, 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.
This method returns true if it successfully reads the data from the local storage area; it then updates JSDO memory with this data according to the specified add-mode. If storage-name does not exist, but otherwise encounters no errors, the method leaves JSDO memory unchanged and returns false. If the method does encounter errors (for example, with reading the data in the specified storage area), it also leaves JSDO memory unchanged and throws an exception.
Example
The following code fragment fills memory for a JSDO (dataset) with records from an OpenEdge ProDataSet named csCustomerOrder, which is used to implement a multi-table resource on the server. The JSDO then contains tables that correspond to the Customer and Order tables of the OpenEdge sports2000 database:
var dataset = progress.data.JSDO( "dsCustomerOrder" );
dataset.fill(); // Loads the JSDO with all available records from the ProDataSet resource
// Adds records
dataset.addLocalRecords( progress.data.JSDO.MODE_REPLACE, [ "CustNum", "Ordernum" ] );
The fragment then calls addLocalRecords( ) on the JSDO to add a set of similar records to JSDO memory from the default local storage area, where the records were previously stored using the JSDO saveLocal( ) method. Duplicate Customer and Order records are checked and replaced with the records from local storage based on the respective primary key fields, CustNum and Ordernum.
progress.data.JSDO.MODE_REPLACE — Adds the table record objects in the specified local storage area to the existing record objects in JSDO memory. If duplicate keys are found between record objects in local storage and record objects in JSDO memory, the record objects with duplicate keys in JSDO memory are replaced with the corresponding records in local storage.