Sample instantiation for an OpenEdge Data Object Service

The following DataSource is instantiated to access an OpenEdge ProDataSet resource that supports before-imaging and the Submit operation, dsCustomerOrd:

myjsdo = new progress.data.JSDO({ name: 'dsCustomerOrd' });

var dataSource = new kendo.data.DataSource( {
    type: "jsdo",
    serverPaging: true,
    serverFiltering: true,
    filter: { field: "State", operator: "eq", value: "MA" },
    serverSorting: true,
    sort: { field: "State", dir: "desc" },
    transport: {
        jsdo: myjsdo,
        tableRef: "ttCustomer",
        countFnName: "count",
        autoSave: false,
        readLocal: true
    },
    batch: true,
    error: function(e) {
        var dataErrors, error = "", i, j;
        
        console.log('Error: ', e);
        if (e.errorThrown) {
            error = "\n" + e.errorThrown.message;
        }
        dataErrors = this.transport.jsdo.ttCustomer.getErrors();
        for (var i = 0; i < dataErrors.length; i++) { /* each error */
            error += "\n" + JSON.stringify(dataErrors[i]);
        }
        alert("JSDO error(s) returned: " + error);
        e.preventDefault();
    }
} );

Note that this example DataSource accesses a JSDO that is instantiated prior to instantiating the DataSource itself. This also assumes that a user login session has been created for the JSDO and a Data Service Catalog describing the dsCustomerOrd resource has already been added to the JSDO session. For more information on creating a user login session for a JSDO and adding a Catalog to the session, see progress.data.JSDOSession class.

Following is a brief description of the configuration options specified in the sample definition for the JSDO dialect of the Kendo UI DataSource shown above:

• Setting the standard type property to "jsdo" — Specifies that the Kendo UI DataSource is being instantiated for the JSDO dialect.
• Setting the standard serverPaging, serverFiltering, or serverSorting properties to true — If server* properties are true, the specified processing (paging, filtering, sorting) is performed on the server, and if server* properties are false, the specified processing is done locally by the Kendo UI DataSource.

  For example, if the serverFiltering property is true, the settings for its related filter property on the DataSource (or from any more recent invocation of the filter( ) method on the DataSource) are passed to the resource's Read operation on the server to filter the data before it is returned to the client. If serverFiltering is false, the latest DataSource filter settings are used to filter the data that already populates the DataSource. The same is true of the remaining server* configuration properties and their related property settings, such as the settings of the serverPaging property and its related pageSize property, and the settings of the serverSorting property and its related sort property.

  Note: When any server* properties are true, the format of the related property values that the DataSource passes to the resource's Read operation depends on the Data Object Service type. For more information, see the description of the JSDO fill( ) method.

  If all of these server* properties are false, the JSDO receives the records for the single (or specified) table of its resource, in whatever quantity and order they are received from the resource's most recent Read operation on the server, and passes them to the DataSource which then manages all paging, filtering, and sorting of the records in its own internal memory.

  Note: The JSDO dialect of the DataSource does not support setting the serverGrouping or serverAggregates configuration properties to true. You should either leave these properties not set, or set them to false. That is, any data grouping and aggregate features of Kendo UI can only be managed by the Kendo UI DataSource itself. If you set any of these properties to true, the respective feature is ignored by both the server and the JSDO dialect of the Kendo UI DataSource.
• Set the JSDO dialect jsdo transport property — The jsdo property specifies the JSDO that is accessed by the DataSource. In the sample, an existing instance of the JSDO (myjsdo) is specified. You can also specify the name of a JSDO resource as a string, and the DataSource will create the JSDO instance for you. This is the same resource name you would use to create the JSDO yourself. In this sample, you would specify the jsdo value as "dsCustomerOrd".
• Set the JSDO dialect tableRef transport property — Required only for a JSDO created for a resource that is a multi-table ProDataSet, the tableRef property specifies the name of the JSDO table whose data the DataSource handles. So, for an OpenEdge ProDataSet, you specify the name of the corresponding temp-table in the Business Entity (ttCustomer in the sample). If you want to access the data in all tables in the ProDataSet, you need to create a separate Kendo UI DataSource for each table accessed by the JSDO and attach it to a Kendo UI widget appropriately.
• Set the JSDO dialect countFnName transport property — The countFnName property specifies the name of the Invoke operation method in the Business Entity that returns the total number of records in the server result set to the Kendo UI DataSource when using server paging (serverPaging == true). For more information on implementing this method, see the sections on updating Business Entities for remot http client access in OpenEdge Development: Web Services. Note that for a JSDO that reads data from a multi-table ProDataSet, this Invoke operation method only returns the total number of records in the result set (in all pages) of the parent table.
  Note: You can annotate a Count operation method in a Business Entity that you implement to return the total number of records. With this annotation, you do not need to specify the countFnName transport property for the corresponding Kendo UI DataSource. For more information, see the documentation on coding Business Entities for access by Kendo UI DataSources.
• Set the JSDO dialect autoSave and readLocal transport properties — These settings are most useful if the tableRef property specifies the name of a child table that is related to a parent table residing in the same JSDO instance specified by the jsdo property. For more information, see the description of these properties in Features of the JSDO dialect.
• Set the standard batch property — Specifies how record changes are processed when the sync( ) method is called on the DataSource, depending on the batch property setting (false by default). If batch == true, the JSDO resource must define a Data Object Service Submit operation. The following table shows how the DataSource responds to the setting of its batch property, depending on whether a Submit operation is defined in the JSDO:

  Table 2. JSDO dialect response to the batch property setting on the DataSource

  DataSource batch property setting	Does JSDO define a Submit operation?	DataSource response when saving changes
  false	No	The transport gets a change for a single record. This record change is sent to the server one record at a time, using the corresponding Data Object Service Create, Update, or Delete operation (by calling saveChanges(false) on the JSDO).
  true	No	The DataSource throws an exception if saving changes to the server with batch == true when the JSDO does not define a Submit operation.
  false	Yes	The transport gets a change for a single record. This record change is sent to the server one record at a time, using the Data Object Service Submit operation (by calling saveChanges(true) on the JSDO).
  true	Yes	The transport gets changes for one or more records in an array. All the changes are grouped by the JSDO and sent to the server using the Data Object Service Submit operation (by calling saveChanges(true) on the JSDO).

  Note: For a standard Kendo UI DataSource with batch == true, multiple record changes are grouped together so that all record changes of a given type (create, update, or destroy) are sent to the server at one time by the DataSource transport. However, the transport for the JSDO dialect can only send the entire set of record changes (all create, update, and destroy changes together) in a single Data Object Service Submit operation.
• Handle the parameter (e) and associated JSDO errors returned by the DataSource error event handler function — The error event handler function is called when an error occurs while performing CRUD or Submit operations on a remote data service (the JSDO in this case). An error can thus be returned when invoking the read( ) method or the sync( ) method on the DataSource, which in this case invokes a Submit operation on any changed data in the JSDO.

  As shown in Table 1, the errorThrown property of the event parameter (e) is set, along with some additional properties, depending on the types of errors returned. To process these errors for a JSDO, you can look at the following:

  • e.errorThrown.message
  • The result of calling getErrors( ) on the JSDO table reference that the DataSource is accessing

  If an error occurs after invoking the DataSource sync( ) method when saving changes in the JSDO to the server, the following generic message is typically returned in e.errorThrown.message: "JSDO: Error while saving changes.". This message is returned if one or more errors occurs while saving JSDO changes, regardless of the batch property setting on the DataSource. So for example, if batch == true, and multiple errors occur for a single Data Object Service Submit operation, this one error message is returned for all of them.

  Additional errors from calls to the JSDO dialect read( ) or sync( ) method can be returned in other property settings of the e parameter, such as e.xhr, as well as from the JSDO table itself, depending on the type of error. However, all of these errors can be returned using a single call to the JSDO getErrors( ) method on the JSDO table reference.

  This JSDO method thus returns different types of errors that result from calling the:

  • JSDO dialect read( ) method, which ultimately calls the JSDO fill( ) method to invoke a Progress Data Object Read operation. These include errors from executing the Read operation itself.
  • JSDO dialect sync( ) method, which ultimately calls the JSDO saveChanges( ) method to invoke Progress Data Object CUD or Submit operations. These include errors from executing the operations themselves. They, in turn, can include different types of errors depending on if the Data Object resource supports before-imaging or not.
    Note: Submit operations must always process data with before-image support. Note also that even when the DataSource invokes sync( ) for one record change at a time (with batch == false), if the JSDO defines a Submit operation, the DataSource invokes a separate Submit operation for each record that is changed.
  • JSDO dialect read( ) or sync( ) method regardless of the Data Object operation. These include errors that originate from the network, web server, or web application that hosts the Data Object Service, or otherwise result from the operation being inaccessible.

  The error handler in the sample handles all these types of errors. The JSDO getErrors( ) method is invoked on the JSDO table (ttCustomer) that the DataSource references and returns an array of objects, each of which contains properties describing an error depending on the error type. The method call stores this array in a variable (dataErrors), as shown in the following fragment from the previous sample:

  myjsdo = new progress.data.JSDO({ name: 'dsCustomerOrd' }); var dataSource = new kendo.data.DataSource( { type: "jsdo", . . . transport: { jsdo: myjsdo, tableRef: "ttCustomer", . . . }, batch: true, error: function(e) { var dataErrors, error = "", i, j; console.log('Error: ', e); if (e.errorThrown) { error = "\n" + e.errorThrown.message; } dataErrors = this.transport.jsdo.ttCustomer.getErrors(); for (var i = 0; i < dataErrors.length; i++) { /* each error */ error += "\n" + JSON.stringify(dataErrors[i]); } alert("JSDO error(s) returned: " + error); e.preventDefault(); } } );

  Note: In the sample, this refers to the Kendo UI DataSource, allowing access to its properties, methods, and events.

  The sample then loops through the dataErrors array to log the contents of each error object as a string using the standard JSON.stringify( ) method. The properties that can be returned for each getErrors( ) error object include:

  • errNum — An error number that appears only in errors from operation routines running on the server.
  • error — A string containing an error message, depending on the error type (type property value).
  • id — The internal ID of any single record object associated with the error. This value can be used to return the record and its current field values by calling the findById( ) method on the JSDO table reference.
  • responseText — A string that can contain additional error information for general network and server errors, regardless of the operation.
  • type — Identifies the type of error, indicated by a numeric constant.

  Some errors returned by getErrors( ) are exclusive of other errors, while others can be returned as part of a series of errors, depending on the operations and the data for which the errors are generated. For more information on these error object properties and how they can be returned by getErrors( ), see the getErrors( ) method description.

  So, when the sample error function executes, it:

  1. Logs the entire contents of e to the console log.
  2. Creates a multi-line error string (error) starting with the contents of e.errorThrown.message.
  3. Concatenates one or more error lines to the multi-line error string from the contents of each error object returned by getErrors( ).
  4. Displays an alert box showing the contents of the multi-line error string.