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 also causes an offline or online event to fire if it detects that there has been a change in the JSDO login session's online state.

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.

Alias: read( )

Return type: jQuery Promise or undefined

Applies to: progress.data.JSDO class

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 ] )

parameter-object

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 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 external objects, as well as in calls to standard objects from Kendo UI, fill( ) is invoked with similar parameter-object properties based on requirements.

Note: Upon execution, the fill( ) method immediately passes the parameter-object to a requestMapping( ) function in the plugin to perform conversions.

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. 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 external objects in OpenEdge Development: Web Services. For internal objects accessed using the JSDO, the requirements for using the built-in "JFP" MappingType plugin are managed internally by the server.

The parameter-object properties required for the built-in "JFP" MappingType plugin, which you can initialize when you call fill( ) directly, include:

• 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.

  If a filter object is not specified, the resource Read operation determines the records to return without selection criteria sent from the client.

• id — A string specifying a unique ID that the resource understands to identify a specific record.
  Note: This property is not currently used by the Kendo UI.
• skip — A number that specifies how many records to skip before returning (up to) a page of data. You must specify this property together with the top property.
• sort — An expression that specifies how to sort the records to be returned using one of the following formats:
  • 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.
  • An Array of strings in the same format as the sort-fields parameter of the setSortFields( ) method.

  If this property is not specified, the resource Read operation determines the order of records to return without sort information sent from the client.

• 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.
• top — A number that specifies how many records (the page size) to return in a single page of data after using skip. You must specify this property together with the skip property.
  Note: The final page of a larger result set can contain a smaller number of records than top specifies.

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.

filter-string

This is a string containing selection criteria used by the Read operation as required by the resource:

• 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:
  • A single key value (e.g., "30")
  • A relational expression (e.g., "CustNum > 10 AND CustNum < 30")
  • An actual WHERE string (e.g., 'Item.CatDescription CONTAINS "ski & (gog* ! pol*)"')
  Note: 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).
  CAUTION: Using an actual WHERE string for a dynamic ABL query can create a potential security issue.

Note: If you want to use sorting or paging that your server Data Object resource supports, you must pass parameter-object instead of filter-string.

If you do not pass either parameter-object or filter-string to this method, the records returned depend entirely on the Read operation that the resource implements.

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:

Syntax:

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

promise

A reference to the Promise object that is returned as the value of the fill( ) method. For more information on Promises, see the notes on Promises in the description of the progress.data.JSDO class.

jsdo

A reference to the JSDO that invoked the fill( ) method (Read operation) on its resource. For more information, see the description of the jsdo property of the request object.

success

A boolean that is true if the Read operation was successful. For more information, see the description of the success property of the request object.

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.

request

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.

Returning and handling results

This method returns results asynchronously in two different ways, and in the following order, depending on the development environment used to build the mobile app:

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:
   1. beforeFill event
   2. afterFill 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.

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 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

The following code fragment shows the fill( ) method invoked on a JSDO for an OpenEdge single-table resource (dsCustomerOrder), with results returned using the afterFill event:

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);
            }
        }
    }
};

Note that for an OpenEdge resource, the getErrors( ) method can return one or more error messages for a Read operation in an array of error objects.

The following code fragment shows the fill( ) method invoked on a JSDO for a similar OpenEdge single-table resource (dsCustomerOrder), with results returned using a Promise object:

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.

The following code fragment shows the fill( ) method invoked on a JSDO for a resource (Orders), with results returned using a Promise object:

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);
            }
        }
    });

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.

See also:

autoSort property, caseSensitive property, getErrors( ) method, getId( ) method, invocation method, progress.data.PluginManager class, response property, saveChanges( ) method, setSortFields( ) method, success property