An object reference property on a JSDO that has the name of a corresponding table in the Data Object resource for which the current JSDO was created.
Its value is a reference (table reference) to the table object in JSDO memory. This table object provides access to a working record, if defined. If the server Data Object provides access to a multi-table resource, such as an OpenEdge ProDataSet, the JSDO provides one table reference for every table in the multi-table resource.
In JSDO syntax descriptions, wherever a table reference can be used, for example, in jsdo-ref.table-ref, where jsdo-ref represents a reference to a JSDO instance, table-ref represents the name of a property containing the table reference. Every referenced table object, in turn, provides the following properties:
record property — A reference to a JSRecord object (record object), which provides the data for the working record of the table in its own data property. This data property provides access to the field values of the working record as corresponding field reference properties (see the following bullet). If no working record is defined for the table object, its record property is null.
field reference property — Also referred to as a field reference, a property on the table object that has the name and data type of a field (as defined in the table schema) and the value for that field in the working record. In JSDO syntax descriptions, wherever a field reference can appear, for example, in jsdo-ref.table-ref.field-ref, field-ref represents a property with the name of a corresponding table field containing the field reference.
A JSDO table object provides one such field reference for each field defined in the corresponding resource table. If no working record is defined for a given table object, all of its field references are null. However, you can reference the current value for any field-ref on the data property of any JSRecord object reference that you have previously saved for a working record or that you otherwise return during a search of JSDO memory, for example, using the JSDO foreach( ) method.
The JSDO also provides support for accessing array fields, which can be defined in an OpenEdge resource temp-table. You can reference individual array elements of any field-ref defined as an array using any of the following mechanisms:
Standard JavaScript subscript reference — Such as an integer subscript reference, field-ref[index], where index is a zero (0)-based integer expression that indexes the array.
JSDO array-element reference — Which specifies each element of the array as a separate field reference property with a unique name specified according to the format, field-ref_integer, where field-ref is the name of the original array field, integer is a one (1)-based integer that qualifies the field name, and where field-ref and integer are separated by a single underscore (_). Each field-ref_integer property contains the same value as the corresponding field-ref array element, field-ref[index], where index is equal to integer - 1. (Note: The integer name qualifier is one-based to match OpenEdge array field subscripts, which are one-based in OpenEdgeAdvanced Business Language (ABL).)
A given JSDO array-element reference can conflict with a scalar field that happens to have the same field-ref_integer name. If this happens for an OpenEdge resource table, you can resolve the conflict by assigning a different scalar field name to be generated in the Catalog for the corresponding ABL temp-table field definition. To assign a different generated field name, specify the SERIALIZE-NAME option for the affected scalar field in the temp-table definition. For more information, see the description of the DEFINE TEMP-TABLE statement in OpenEdge Development: ABL Reference.
You can therefore read field values in the working record of a given table reference using corresponding field references either on the data property of the JSRecord object returned by the record property of the table reference or directly on the table reference itself. However, although you can assign values directly to fields referenced on this data property, doing so does not trigger any automatic sorting of the data in JSDO memory, or any saving of the updated field value to the Data Object resource on the server. Instead, to write field values, Progress strongly recommends that you either call the JSDO assign( ) method on a jsdo-ref.table-ref with a working record (or on any valid JSRecord object reference), or assign values directly to any jsdo-ref.table-ref.field-ref with a working record.
Caution: Again, never write directly (by assigning a value) to a field-ref on the record.data property (or on the data property of any JSRecord object reference); use field-ref on this data property only to read the current field value. Writing field values directly on data.field-ref of a JSRecord object reference does not mark the record for update when you subsequently call the saveChanges( ) method, nor does it re-sort the updated record in JSDO memory according to any order you have established using the autoSort property. To mark a record for update and automatically re-sort the record according to the autoSort property, you must set a field value either by calling the assign( ) method on a record object or by assigning the value directly to the jsdo-ref.table-ref.field-ref of a working record, as described above.
Note: The record property with a working record does provide an alternative way to read a table field that happens to have the same name as any JSDO property (or method) that you can access (or invoke) directly on a table reference with a working record (except, of course, a table field with the name, record). That is, not every JSDO property (or method) that is available on a table reference is also available on the record.data property itself.
Examples
For example, the following code fragment shows two different ways to read the CustNum field of a record added to a Customer table provided by a Data Object resource ('CustomerOrderDS'):
var dataSet = new Progress.data.JSDO( 'CustomerOrderDS' );
dataSet.Customer.add();
alert(dataSet.Customer.record.data.CustNum);
alert(dataSet.Customer.CustNum);
Both calls to the alert( ) function access the same CustNum field in the working record of the Customer table created using the add( ) method.
In the following code fragment, MonthQuota is an array field with 12 elements (one for each month of the year) in the Salesrep table, and shows two different ways to read an element of the MonthQuota array from a record added to a Salesrep table provided by an OpenEdge Data Object resource (SalesDS):
var dataSet = new Progress.data.JSDO( 'SalesDS' );
var idx = 0;
dataSet.Salesrep.add();
alert(dataSet.Salesrep.record.data.MonthQuota[idx]);
alert(dataSet.Salesrep.MonthQuota_1);
Both calls to the alert( ) function access the same MonthQuota array element in the working record of the Salesrep table created using the add( ) method.
Note: Both of the previous examples assume the names of tables and fields in the OpenEdge sports2000 sample database. However, note also that where MonthQuota is presented as an array field for this example, that same field in the OpenEdge-installed instance of sports2000 is defined instead as a scalar integer field.
For more information on accessing the working record of a table reference, see the notes in the section on progress.data.JSDO class.
record property — A reference to a JSRecord object (record object), which provides the data for the working record of the table in its own data property. This data property provides access to the field values of the working record as corresponding field reference properties (see the following bullet). If no working record is defined for the table object, its record property is null.