When a JSDO method is called, depending on the method and the situation, it might result in setting a working record for one or more of the table references. A working record is a record object that is associated with a table object in JSDO memory and that is available to reference implicitly using the table reference. If a table reference has a working record set for it, you can then reference any field value in the working record using its field reference property on the table reference. The name of a field reference property is the same as the name of the corresponding field in the table schema that is defined for the Data Object resource. You can also save the record object returned as a working record for future reference (as described in this topic), allowing you to access its field values at any time during the same JSDO session.
For example in Table and field references, when the foreach( ) method in the example returns from execution (based on the return value of its function parameter), it leaves a working record set for the ttCustomer table reference. You can assign a value to the Name field of this working record using the Name field reference property on the table reference:
dsOrderEntry.ttCustomer.Name = "Evellyn Doe";
This is one of the supported mechanisms to update a field value in JSDO memory. The other is to call the assign( ) method directly on a table reference or on a saved record object, itself.
Also, if JSDO memory has a multi-table data model with active data-relations and a working record is set in a parent table reference, a search through the records of a child table reference reflects the data-relation. For example, with a working record set for a ttCustomer that is a parent of ttOrder, calling the foreach( ) method on ttOrder only loops through records related to the working record in ttCustomer.
Note: Table references for tables referenced in JSDO memory use a flat reference model. In other words, regardless of data-relations, you reference the property for each table reference directly on the JSDO (for example, ttOrder in dsOrderEntry.ttOrder.Ordernum).
Depending on the results of JSDO methods that you call, JSDO memory either leaves a working record set for each table reference or leaves the working record undefined for one or more table references. Essential programming for a JSDO involves calling appropriate methods to locate working records in JSDO memory in order to read and modify their contents (see also Record IDs). The documentation for each JSDO method (see JSDO properties, methods, and events reference) indicates whether and how it leaves working records set when it completes execution.
The following table lists each JSDO method that has an effect on working record settings and generally how it affects them.
Table 6. JSDO methods that affect working record settings
This JSDO method...
Leaves working records...
acceptChanges( )
Set depending on the changes accepted
acceptRowChanges( )
Set depending on the changes accepted
add( )
Set for the affected table
addLocalRecords( )
Set for each JSDO table reference depending on the specified merge mode
addRecords( )
Set for each JSDO table reference depending on the specified merge mode
create( )
Set for the affected table
fill( )
Set for every table of the JSDO according to any active data-relations and the current table sort order
find( )
If a record is found, set for the affected table, any child tables, and the effects of the callback function
findById( )
Set for the affected table
foreach( )
Set for the most recent record found in the affected table, any child tables, and the effects of the callback function
read( )
Set for every table of the JSDO according to any active data-relations and the current table sort order
readLocal( )
Not set for any table of the JSDO
rejectChanges( )
Set depending on the changes rejected
rejectRowChanges( )
Set depending on the changes rejected
remove( )
No longer set for the affected table and its child tables
saveChanges( )
Not longer set for every table in the JSDO
If a method sets a working record, you can reference the field values of the record object using field reference properties on the table reference, as described in the previous section. You can also use the record property on the table reference to return a JSRecord object reference to the working record, which you can reference directly or store separately to access contents of the record object later. A JSRecord object provides a data property that references a separate JavaScript object containing the actual field reference properties for the record (see also progress.data.JSRecord class). Also as a convenience, if the JSDO supports only a single table, you can access the record property for the working record directly on the JSDO reference itself.
So, using the previous example with ttCustomer, you can access the Name field of the working record using a JSRecord object reference in the following ways:
var custName = dsOrderEntry.record.data.Name; // Single table only
var custName = dsOrderEntry.ttCustomer.Name; // One table of many
var custName = dsOrderEntry.ttCustomer.record.data.Name;
var custRecord = dsOrderEntry.ttCustomer.record; // Stored for later reference
var custName = custRecord.data.Name; // Later reference
Once you store the record object of a working record for later reference, the stored record object remains available using its JSRecord reference even when it is no longer the working record for the table. Note that Progress does not recommend using the data property to write a value to a field because the record object is not marked as changed in JSDO memory and won't be updated on the server. To update a field value in a JSRecord object so the change is reflected on the server, either call the assign( ) method directly on the JSRecord reference or assign the value directly to the field reference property that you reference directly on the table reference where the appropriate working record is set.
Note: One reason to use the record.data property on a table reference is to read a field value when the field happens to have the same name as a JSDO method that you can call on any table reference.
Caution: Because the record object is not marked as changed in JSDO memory, never use the data property on a JSRecord reference to update the value of a field. Otherwise, the change in value will never be reflected on the server. Use the data property to read the field value only.