Every JSDO has a number of built-in methods, many of which interact with JSDO memory. Some are called on the JSDO itself, while most are called on a JSDO table reference. Most execute synchronously, but some execute asynchronously as noted. For more information, see Asynchronous and synchronous execution. A few JSDO methods are also available on a JSRecord object.
Some methods affect working record settings in JSDO memory as noted, while all other methods have no effect on working record settings.
A JSDO includes built-in methods for:
Executing standard Data Object operations and calling their implementing server API:
fill( ) (or its alias, read( )) — Executes the Read operation on a Data Object resource, loading the records sent from the server into JSDO memory according to the resource data model; the first record of every loaded table reference is set as its working record.
saveChanges( ) — Executes the Create, Update, Delete (CUD), or Submit operation on a Data Object resource for each record that has changed in JSDO memory since the last execution of the fill( ) (or alias read( )) or saveChanges( ) method; no working records are set for any tables in JSDO memory.
You call these methods on the JSDO and they always execute asynchronously, with results returned using handlers either or both for named events and jQuery Promises.
Executing custom Data Object Invoke operations that directly call a server API. In order to call a server API, the Data Object resource defines a uniquely named, JSDO invocation method that calls each Invoke operation supported by the resource. These invocation methods can return results from their corresponding Invoke operations, but they have no direct effect on JSDO memory. You can call a JSDO invocation method using one of the following mechanisms:
Calling the method directly on the JSDO — This mechanism provides the option to execute the Invoke operation either asynchronously (the default) or synchronously. To pass input parameters to the implementing server API, you pass an object to the invocation method that contains properties with the values for the operation parameters. You can return asynchronous results using handlers for named events, and you can return synchronous results as an object method value.
For an OpenEdge resource, each property that corresponds to an input parameter of an implementing ABL routine has the same name (and letter case) as the corresponding ABL input parameter, and has a JavaScript data type that maps to the ABL data type of the input parameter (see OpenEdge ABL to JavaScript data type mappings).
Calling the method by using the JSDO invoke( ) method API — This mechanism always executes the Invoke operation asynchronously. In this case, you pass both the name of the invocation method and any input object that the invocation method requires to the invoke( ) method, which you call directly on the JSDO. You can return the asynchronous results using handlers either or both for named events and jQuery Promises.
Updating JSDO memory:
acceptChanges( ) — Called on the JSDO or a JSDO table reference, this method accepts changes to the data in JSDO memory for the specified table reference or for all table references of the specified JSDO; the effect on working record settings depends on the changes accepted. This method works only if you have set the autoApplyChanges property to false.
acceptRowChanges( ) — Called on a JSDO table reference or a JSRecord reference, this method accepts changes to the data in JSDO memory for a specified record object; the effect on working record settings depends on the changes accepted. This method works only if you have set the autoApplyChanges property to false.
add( ) (or its alias, create( )) — Called on a JSDO table reference, this method creates a new record object for the table in JSDO memory; the new record is set as the working record for the table reference.
addRecords( ) — Called either on a JSDO or on a JSDO table reference, this method merges record objects from a merge object passed as a method parameter with the specified existing record objects in JSDO memory. The merge object must follow the same schema as JSDO memory itself. Merge modes determine how to handle record objects with duplicate key fields, if specified. The case sensitivity for merges on string fields can be changed by setting the caseSensitive property. This method sets working records for all JSDO table references depending on the merge mode that is used.
assign( ) (or its alias, update( )) — Called on a JSDO table reference or a JSRecord reference, this method updates field values for an existing record in JSDO memory from property values in an object that you pass as a parameter to the method.
An assign( ) method is also available on a table reference of a progress.ui.UIHelper object. This method updates the field values of an existing record from values in an associated HTML page. For more information, see Dynamic data binding for alternate client platforms.
rejectChanges( ) — Called on the JSDO or a JSDO table reference, this method rejects changes to the data in JSDO memory for the specified table reference or for all table references of the specified JSDO; the effect on working record settings depends on the changes rejected. This method works only if you have set the autoApplyChanges property to false.
rejectRowChanges( ) — Called on a JSDO table reference or a JSRecord reference, this method rejects changes to the data in JSDO memory for a specified record object; the effect on working record settings depends on the changes rejected. This method works only if you have set the autoApplyChanges property to false.
remove( ) — Called on a JSDO table reference or a JSRecord reference, this method deletes an existing record in JSDO memory; no working record is set for the table reference or any of its child table references.
These methods always execute synchronously. You save the changes that these methods make in JSDO memory to the server by calling the saveChanges( ) method on the JSDO, which executes asynchronously.
Moving data between JSDO memory and local device storage:
addLocalRecords( ) — Called on the JSDO, this method merges record objects from a specified local storage area with the existing record objects in JSDO memory. The local storage area must follow the same schema as JSDO memory itself. Merge modes determine how to handle record objects with duplicate key fields, if specified. The case sensitivity for merges on string fields can be changed by setting the caseSensitive property. This method sets working records for all JSDO table references depending on the merge mode that is used.
deleteLocal( ) — Called on the JSDO, this method removes all data and changes stored in the specified local storage area, and removes the storage area.
hasChanges( ) — Called on the JSDO, this method indicates if JSDO memory has any pending changes (with or without before-image data) and is typically used to determine if there are any changes in JSDO memory that you might want to save to a local storage area.
hasData( ) — Called on the JSDO or a JSDO table reference, this method indicates if either all tables, or a specified table, in JSDO memory contains record objects (with or without pending changes) and is typically used to determine if there is any data in JSDO memory that you might want to save to a local storage area, for example, to avoid losing if you decide to replace JSDO memory with other records from a different local storage area.
readLocal( ) — Called on the JSDO, this method removes all data in JSDO memory and replaces it with the data in a specified local storage area, including pending changes, if any. After execution, this method leaves no working record settings in the JSDO.
saveLocal( ) — Called on the JSDO, this method removes any existing data in a specified local storage area and replaces it with the data in JSDO memory as specified by a data mode, which indicates whether JSDO data and changes or only the data changes are saved to the storage area.
Sorting record objects in JSDO memory:
setSortFields( ) — Specifies or clears the record fields on which to automatically sort the record objects for a table reference after you have set its autoSort property to true. When enabled, this automatic sorting occurs in JSDO memory after supported JSDO operations update the associated data.
setSortFn( ) — Specifies or clears a user-defined sort function on which to automatically sort the record objects for a table reference after you have set its autoSort property to true. When enabled, this automatic sorting occurs in JSDO memory after supported JSDO operations update the associated data.
sort( ) — Sorts the existing record objects for a table reference in JSDO memory using either specified sort fields or a specified user-defined sort function. This method sorts the record objects for a table reference whether or not the associated data has changed.
These methods are all called on a JSDO table reference, and always execute synchronously. The case sensitivity of sorting on string fields can be changed by setting the caseSensitive property.
Searching for record objects in JSDO memory:
find( ) — Searches for a record in a referenced table according to the criteria defined by a function that you pass, and returns the record object if the function indicates it has been found; sets any record found as the working record for the table reference, and (assuming the useRelationships property is true) sets the working record for any child table references to the first record that is related to the parent working record.
findById( ) — Searches for a record in a referenced table with the specified record ID, and returns the record object if found; sets any record found as the working record for the table reference, and (assuming the useRelationships property is true) sets the working record for any child table references to the first record that is related to the parent working record.
foreach( ) — Loops through the records of a referenced table, and allows a function that you pass to access each record object and perform whatever actions you define until the function tells the method to stop looping or the method has reached the end of the record set; the record for each iteration is set as the working record for the table reference, and (assuming the useRelationships property is true) sets the working record for any child table references to the first record that is related to the parent working record. When the loop terminates, the last working record set remains the working record for the table reference.
These methods are called on a JSDO table reference and always execute synchronously.
Returning data and information from JSDO memory:
getData( ) — Called on a JSDO table reference, this method returns an array of record objects for a referenced table.
getErrors( ) — Called on a JSDO table reference, this method returns all types of error information associated with the table reference from the most recent call to the fill( ) or saveChanges( ) method. This error information is returned as an array of objects, each of which has properties that return the information for a specific error according its type.
Updated for Progress Data Objects Version 4.3 or later.
getErrorString( ) — Called on a JSDO table reference or a JSRecord reference, this method returns the value of any before-image returned in the specified record object after a record change operation that includes before-image data.
getId( ) — Called on a JSDO table reference or a JSRecord reference, this method returns the unique internal record ID for the specified record object.
getSchema( ) — Called on a JSDO table reference, this method returns an array of objects, one for each field, that defines the schema of the referenced table.
These methods always execute synchronously.
Managing JSDO event subscriptions:
subscribe( ) — Subscribes a given event handler function to a named event on a JSDO or on a JSDO table reference.
unsubscribe( ) — Unsubscribes a given event handler function from a named event on a JSDO or on a JSDO table reference.
These methods are called on the JSDO or on a JSDO table reference, and execute synchronously. For more information on JSDO events and managing JSDO event subscriptions, see Asynchronous and synchronous execution.
Creating and accessing JSDO user-defined properties:
getProperties( ) — Returns an object containing the names and values of the user-defined properties defined in the current JSDO instance.
getProperty( ) — Returns the value of the specified JSDO user-defined property.
setProperties( ) — Replaces all user-defined properties in the current JSDO instance with the user-defined properties defined in the specified object.
setProperty( ) — Sets the value of the specified JSDO user-defined property.
These methods are called on the JSDO only, execute synchronously. For more information on user-defined properties, see Properties of a JSDO.
Note: Applies to Progress Data Objects Version 4.3 or later.
Executing standard Data Object operations and calling their implementing server API: