JSDO methods operate locally on the client and execute synchronously in JavaScript. Synchronous execution means that the client waits for the method to finish and return its results before executing the next JavaScript statement or evaluating the next term of an expression. These results often include a method return value.

Some JSDO methods execute asynchronously in JavaScript. These include the JSDO fill( ) and saveChanges( ) methods, which execute standard Data Object operations on the server, as well as the default execution of custom invocation methods (with or without use of the JSDO invoke( ) method), which execute custom Data Object Invoke operations on the server. Asynchronous execution means that immediately after the client calls the method, it continues to execute the next JavaScript statement or to evaluate the next term of an expression whether or not the asynchronous method completes and returns results. These results are returned to one or more callback functions that you define and that execute on the client according to certain conditions.

You can define a callback function for an asynchronous method that can execute in one of the following ways:

  • As a handler subscribed to a named event — Which executes after invoking the asynchronous method when a specified condition for firing the named event occurs. Thus, multiple callbacks can execute when the asynchronous method completes, depending on how many you subscribe to events that fire in response to invoking the method.
  • As a callback registered using a method of a deferred Promise object — Which executes after invoking the asynchronous method when a specified condition occurs that is associated with the Promise object method that registered the callback. This Promise object, itself, is returned as the deferred value of the asynchronous method, allowing you to call one or more Promise object methods that register associated callbacks. Thus, multiple callbacks can execute when the asynchronous method completes, depending on how many of the conditions occur that are associated with the Promise object methods that you have called to register these callbacks.

The results of an asynchronous method execution only become available to the mobile app when either or both of the following occur, and in the following order:

  1. An event associated with the asynchronous method fires, and a callback function that is subscribed to the event executes and receives the results as one or more input parameters.
  2. A condition occurs that is associated with a deferred Promise object method that you have called to register a callback, and the callback executes and receives the results as one or more input parameters.

The callbacks that are available to return the results of asynchronous JSDO method calls depend on:

  • The named events supported for a given JSDO method call. For more information, see Named events.
  • Whether your environment supports Promises. For more information, see Promises.

Compare asynchronous and synchronous execution

Asynchronous execution is mandatory for the methods that execute the standard Data Object CRUD and Submit operations. These operations usually involve server access to data sources, which are typically databases. The Data Object Read operation executed by the fill( ) method can involve reading and returning hundreds to thousands (or more) records from a multi-table resource across the network. The Data Object Create, Update, Delete (CUD), and Submit operations, which require writes to, and lock management of, databases, are executed across the network by the saveChanges( ) method one record at a time for CUD operations and multiple records at a time for the Submit operation, and for as many records as are marked changed in JSDO memory.

This means that completion of these operations can require detectable wait times. If they were executed synchronously, the mobile app user would be prevented from doing any work within the app while these methods are executing. With asynchronous execution, they can perform other tasks, such as setting application options, while waiting for a list of customers and orders to be displayed in a list view, or while waiting for notification that changes they have posted have been saved to the database. For more information on the execution options for methods that execute the standard Data Object CRUD and Submit operations, see CRUD and Submit operations.

Asynchronous execution is also the default for custom invocation methods because these operations execute across the network and can involve complex database interactions on the server. However, it is also possible that an invocation method might perform a simple function and return a primitive value used in an expression—for example, a percentage or a credit limit. In this case, you might prefer to execute the method synchronously in the expression in order to complete the calculation with its return value. This you can do by passing false as an additional boolean parameter that indicates that the invocation method is to be executed synchronously. For more information on the execution options for invocation methods, see Access custom Invoke operations.