fill( ) method

Initializes JSDO memory with record objects from the data records in a single-table resource, or in one or more tables of a multi-table resource, as returned by the Read operation of the Data Object resource for which the JSDO is created.

This method always executes asynchronously and returns results (either or both) in subscribed JSDO event callbacks or in callbacks that you register using methods of a Promise object returned as the method value. A Promise object is always returned as the method value if jQuery Promises (or the exact equivalent) are supported in your development environment. Otherwise, this method returns undefined.

Working record: After completing execution, the working record for each JSDO table is set to its first record, depending on any active parent-child relationships (for a multi-table resource) and automatic sort settings. So, for each child table, the first record object is determined by its table reference sort order (if any) and its relationship to the related working record in its parent table.

Syntax

fill ( [ parameter-object | filter-string ] )

An Object initialized with a set of properties that can be used on the server depending on a JSDO MappingType plugin that is both registered on the client and for which a corresponding Read operation is defined in the server Data Object. For more information on JSDO Mapping Type plugins and how to register and use them, see the description of the progress.data.PluginManager class.

The JSDO also provides a built-in MappingType plugin named "JFP" that can be used if the server Data Object is built to support it. This "JFP" plugin allows you to specify properties that can be used on the server to select, sort, and page the records to be returned. This built-in plugin supports any JSDO accessed by the JSDO dialect of the Kendo UI DataSource or any JSDO involved in Rollbase data access. If you are using the JSDO dialect of the Kendo UI DataSource to bind a JSDO instance to Kendo UI widgets, the DataSource initializes and invokes fill( ) with specific parameter-object properties that are defined based on the settings of the DataSource serverPaging, serverFiltering, and serverSorting configuration properties. Also, if OpenEdge Data Objects are being accessed as Rollbase external objects, as well as in calls to standard Rollbase objects from Kendo UI, fill( ) is invoked with similar parameter-object properties based on Rollbase requirements.

The fill( ) method further converts these parameter-object property settings to a format that is customized for each server Data Object resource, depending on its type (OpenEdge or Rollbase). This format is then applied to the resource Read operation based on the presence of a mappingType property set to "JFP" in the Data Service Catalog. For information on the requirements and the effects of using a "JFP" MappingType plugin for a Read operation in OpenEdge resources, see the topics on updating Business Entities for access by Kendo UI DataSources and Rollbase external objects in OpenEdge Development: Web Services. For Rollbase internal objects accessed using the JSDO, the requirements for using the built-in "JFP" MappingType plugin are managed internally by the Rollbase server.

filter — An Object containing property settings used to select the records to be returned. These property settings are in the same format as the property settings in the Kendo UI DataSource filter property object. For more information, see the filter configuration property description in the Kendo UI DataSource documentation. The format that the fill( ) method uses to pass this selection criteria to the server is specified, again, in the Data Service Catalog using the mappingType property.

An Object with property settings in the same format as the property settings in the Kendo UI DataSource sort property object. For more information, see the sort configuration property description in the Kendo UI DataSource documentation.

tableRef — A string specifying the name of a table reference in the JSDO. This property is required when the JSDO represents a multi-table resource and the filter property Object is also specified with filter information.

Note: You must specify both skip and top to implement server paging. For example, if you want to return the 5th page of data with a page size (top) of 10, set skip to 40. If these properties are not specified together, the resource Read operation determines the records to return without using any paging information sent from the client.

Note: If you access the JSDO using only the JSDO dialect of the Kendo UI DataSource, the DataSource invokes the fill( ) method with appropriate settings for these properties based on the corresponding Kendo UI settings. For more information, see Using the JSDO dialect of the Kendo UI DataSource .

For an OpenEdge resource — This is a string that the resource defines for use on an OpenEdge application server to select records to be returned, much like the WHERE option of the ABL record phrase. The actual format of this string and its affect on the records returned is determined by the ABL routine that implements the resource Read operation. For example, you might pass:

For an OpenEdge resource, the JSDO requires the URI for the Read operation of the resource to contain the following query string: "?filter=~{filter~}", where filter is the name of a string input parameter defined for the ABL routine that implements the operation (INPUT filter AS CHARACTER).

Promise method callback signatures

jQuery Promise objects define methods that register a callback function with a specific signature. The callback signatures depend on the method that returns the Promise. Following are the signatures of callbacks registered by methods in any Promise object that fill( ) returns:

promise.done( function ( jsdo , success , request ) )
promise.fail( function ( jsdo , success , request ) )
promise.always( function ( jsdo , success , request ) )

Note: It is not always necessary to test the value of success in a Promise method callback for the fill( ) method, especially if the callback is registered using promise.done( ) and promise.fail( ), where the callback executes according to this value.

A reference to the request object returned after the fill( ) method completed execution and returned any results from its Read operation on the server. For more information, see the description of the request object.

General operation

This method invokes the Read operation on the resource defined for the current JSDO. The result of calling this method replaces any prior data in JSDO memory with the record objects returned by this Read operation. The record objects are stored in one or more JSDO tables that correspond to the table or tables defined for the resource. If the JSDO is accessing multi-table resource (with one or more tables), such as an OpenEdge ProDataSet, and the resource supports before-imaging, the JSDO also updates the state of its JSDO memory with any before-image data sent with the loaded record objects, including any changes to record objects recorded in their before-image data.

Caution: If the JSDO has pending record changes from the client that you want to save on the server, do not call this method before you call the JSDO saveChanges( ) method. Otherwise, the pending changes will be lost when JSDO memory is initialized with records from the Read operation.

Note: After this method initializes JSDO memory with record objects, and if you have set up automatic sorting using the autoSort property, the record objects of each affected JSDO table reference are sorted in JSDO memory according to the sort order you have established for the JSDO. If sorting is done using sort fields, any string fields are compared according to the value of the caseSensitive property on a given table reference. If the autoSort property setting is false for a given table reference, its record objects are loaded in the order that they were serialized from the corresponding resource table.

Returning and handling results

1. Using JSDO named events for all environments — The following events fire before and after the fill( ) method executes, respectively, with results handled by callback functions that you subscribe as documented for each event:

2. Using a Promise object returned for environments that support jQuery Promises — Any callbacks that you register using Promise object methods all execute both after the fill( ) method itself and after any subscribed afterFill event callbacks complete execution. Note that the signatures of all Promise method callbacks match the signature of the afterFill event callback function so you can specify an existing afterFill event callback as the callback function that you register using any Promise method.

Because the callbacks that you register with any returned Promise methods execute only after all subscribed afterFill event callbacks complete execution, you can invoke logic in the Promise method callbacks to modify any processing done by the event callbacks.

If the fill( ) method completes successfully, the success parameter for any afterFill event callback or Promise method and the success property of each handler's request parameter object are both set to true, and any data records returned by the resource Read operation are loaded into JSDO memory. Otherwise, both the success parameter and success property are set to false, and you can read any error results by calling the getErrors( ) method on a single JSDO table reference, or by inspecting the setting of the response property in the same request parameter object.

Note: When returning before-image data from an OpenEdge ProDataSet resource, it is possible (though rare) for record-change errors that result from server update activity to be returned as well. The fill( ) method does not return an unsuccessful result in this case. If you need to identify before-image errors in records returned by a Read operation, you can query the record objects in JSDO memory and call getErrorString( ) on each record object to identify any such errors that were returned.

You can read any record objects loaded into JSDO memory by fill( ) using the find( ), findById( ), foreach( ), and getData( ) methods of the JSDO. You can return the schema for this data by using the getSchema( ) method. You can create a new record object in JSDO memory using the JSDO add( ) method, and you can update or delete a single record object in JSDO memory by using the assign( ) or remove( ) method, respectively. You can display a record in a UI form that you dynamically bind to the record by calling the display( ) method on a progress.ui.UIHelper class instance. You can merge data returned by an invocation method with the data in JSDO memory using the addRecords( ) method, and you can store and merge records in JSDO memory both to and from a local storage location using the saveLocal( ), readLocal( ), and addLocalRecords( ) methods.

Example

dataSet = new progress.data.JSDO( 'dsCustomerOrder' );
dataSet.subscribe("afterFill", onAfterFill);

dataSet.fill();

function onAfterFill( jsdo , success , request ) {
var lenErrors,
errors,
errorType;

if (success) {
/* for example, add code to display all records on a list */
jsdo.foreach(function (jsrecord) {
/* you can reference the fields as jsrecord.data.field */
});
}
else {
/* handle Read operation errors */
errors = jsdo.getErrors();
lenErrors = errors.length;
for (var idxError=0; idxError < lenErrors; idxError++) {
switch(errors[idxError].type) {
case progress.data.JSDO.RETVAL:
errorType = "Server App Return Value: ";
break;
case progress.data.JSDO.APP_ERROR:
errorType = "Server App Error #"
+ errors[idxError].errorNum + ": ";
break;
case progress.data.JSDO.ERROR:
errorType = "Server General Error: ";
break;
}
console.log("READ ERROR: " + errorType + errors[idxError].error);
if (errors[idxError].responseText) {
console.log("HTTP FULL TEXT: " + errors[idxError].responseText);
}
}
}
};

dataSet = new progress.data.JSDO( 'dsCustomerOrder' );

dataSet.fill().done(
function( jsdo, success, request ) {
/* for example, add code to display all records in a list */
jsdo.foreach(function (jsrecord) {
/* you can reference the fields as jsrecord.data.<fieldName> */
});
}).fail(
function( jsdo, success, request ) {
var lenErrors,
errors,
errorType;

/* handle Read operation errors */
errors = jsdo.getErrors();
lenErrors = errors.length;
for (var idxError=0; idxError < lenErrors; idxError++) {
switch(errors[idxError].type) {
case progress.data.JSDO.RETVAL:
errorType = "Server App Return Value: ";
break;
case progress.data.JSDO.APP_ERROR:
errorType = "Server App Error #"
+ errors[idxError].errorNum + ": ";
break;
case progress.data.JSDO.ERROR:
errorType = "Server General Error: ";
break;
}
console.log("READ ERROR: " + errorType + errors[idxError].error);
if (errors[idxError].responseText) {
console.log("HTTP FULL TEXT: " + errors[idxError].responseText);
}
}
}
});

Using a Promise object, the Promise done and fail functions do not have to test the success parameter for a successful (true) or failed (false) execution of the fill( ) method, because done executes only when fill( ) succeeds and fail executes only when fill( ) fails.

dataSet = new progress.data.JSDO( 'Orders' );

dataSet.fill().done(
function( jsdo, success, request ) {
/* for example, add code to display all records on a list */
jsdo.foreach(function (jsrecord) {
/* you can reference the fields as jsrecord.data.<fieldName> */
});
}).fail(
function( jsdo, success, request ) {
var lenErrors,
errors,
errorType;

/* handle operation errors */
errors = jsdo.getErrors();
lenErrors = errors.length;
for (var idxError=0; idxError < lenErrors; idxError++) {
console.log("READ ERROR: " + errors[idxError].error);
if (errors[idxError].responseText) {
console.log("HTTP FULL TEXT: " + errors[idxError].responseText);
}
}
});

For a Rollbase resource, any error results from a Read operation are returned by getErrors( ) as the single error type progress.data.JSDO.ERROR with the errors[idxError].error property set to a single returned string value.