Asynchronously calls a custom invocation method on the JSDO to execute an Invoke operation defined by a Data Object resource.
Both OpenEdge and Rollbase resources can define and implement custom invocation methods that you can call using this method.
The asynchronous execution of the specified invocation method using invoke( ) returns results using a jQuery Promise. You can also directly call an invocation method on the JSDO either synchronously, returning results as its return value, or asynchronously, returning results using a callback subscribed to the afterInvoke event.
Note: In order to call invoke( ) successfully, jQuery Promises must be supported in your development environment. Otherwise, the method throws an exception.
For more information on the possible implementations for custom invocation methods, and how to call them directly on the JSDO, see the description of the invocation method.
Note: The results of an Invoke operation have no effect on JSDO memory. However, you can use the JSDO addRecords( ) method to merge any record data that is returned by an invocation method into JSDO memory.
A string that specifies the name of the invocation method as defined by the resource.
input-object
An object whose properties and values match the case-sensitive names and data types of the input parameters specified for the server routine that implements the invocation method. If the implementing routine does not take input parameters, specify null or leave out the argument entirely.
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 invoke( ) 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 invoke( ) 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 invoke( ) method (Invoke 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 Invoke 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 invoke( ) 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 invoke( ) method completed execution and returned any results from its Invoke operation on the server. For more information, see the description of the request object.
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 invoke( ) 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 invoke( ) method itself and after any subscribed afterInvoke event callbacks for the op-name-specified invocation method complete execution. Note that the signatures of all Promise method callbacks match the signature of the afterInvoke event callback function so you can specify an existing afterInvoke 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 afterInvoke event callbacks for the op-name-specified invocation method complete execution, you can invoke logic in the Promise method callbacks to modify any processing done by the event callbacks.
If the invoke( ) method completes successfully, the success parameter for any afterInvoke event callback or Promise method and the success property of each handler's request parameter object are both set to true. Otherwise, both the success parameter and success property are set to false, and you can read any error results by inspecting the setting of the response property in the same request parameter object.
The request object returned as an input parameter to any subscribed event callback or to any registered Promise object callback contains several properties depending on the status of the Invoke operation.
For a successful execution, if there are any output parameters or a method return value, they are returned as properties of an object referenced by the response property of the request object. For an OpenEdge resource, the referenced properties for output parameters match the case-sensitive names and data types of the output parameters defined for the implementing ABL routine. Any method return value is returned by a JSDO-defined _retVal property with a matching JavaScript data type. For a Rollbase resource, all successful execution results are returned using this JSDO-defined _retVal property, typically in a referenced object. For information on data type mappings for an OpenEdge resource, see OpenEdge ABL to JavaScript data type mappings, and for a Rollbase resource, see Rollbase object to JavaScript data type mappings.
For an unsuccessful execution in an OpenEdge resource, the request object response property references an object that can contain a both a _retVal property, which is a string value with the error information, and an _errors property, which is an array with information on one or more errors. In a Rollbase resource, the request object response property is itself a string value containing the error information. For more information on error information returned in the response property, see the description of the response property.
For more information on working with the results of invocation methods that you call with invoke( ), see the notes on handling results in the description of the invocation method.
Example
The following code fragment shows invoke( ) calling an invocation method (getOrderTotalAndStatus( )) as defined for an OpenEdge resource (dsCustomerOrder), with asynchronous results returned in appropriate callbacks registered by methods of the returned Promise object:
dataSet = new progress.data.JSDO( 'dsCustomerOrder' );
var lenErrors = request.response._errors.length;
for (var idxError=0; idxError < lenErrors; idxError++) {
var errorEntry = request.response._errors[idxError];
var errorMsg = errorEntry._errorMsg;
var errorNum = errorEntry._errorNum;
/* handle error */
. . .
}
}
});
Note that for the call to getOrderTotalAndStatus( ) in the previous example, its input parameters are passed in paramObject, as required by the implementing ABL routine. Depending on the success of the getOrderTotalAndStatus( ) call, the appropriate callback registered for the Promise executes, making it unnecessary to test its success parameter.
Thus, when the callback registered by the Promise's done( ) method executes for a successful getOrderTotalAndStatus( ) call, the order total is returned as the method return value in the JSDO-defined _retVal property, and the one output parameter with the order status is returned as the value of the ABL-defined pcStatus property, both of which are returned in the response property object. When the callback registered by the Promise's fail( ) method executes for an unsuccessful getOrderTotalAndStatus( ) call, the callback inspects the response property to return one or more possible error messages in an array of objects.
The following code fragment shows the invoke( ) method calling a getOrders( ) invocation method to return record objects from a Rollbase object that is related to the Rollbase resource object (Customers), with results similarly returned using a Promise object:
rbCustomers = new progress.data.JSDO( 'Customers' );
/* Initialize paramObject with a customer identity */
. . .
var response = request.response;
var tblOrders = response._retVal;
/* process successful results */
. . .
}).fail(
function( jsdo, success, request ) {
if (request.response) {
var errorMsg = request.response;
/* handle error */
}
});
Note that for the call to getOrders( ), any input parameters are passed in paramObject, as required by the implementing Rollbase API to identify a customer to return record objects from the related Orders Rollbase object. Depending on the success of the getOrders( ) call, the appropriate callback registered for the Promise executes.
Thus, when the callback registered by the Promise's done( ) method executes for a successful getOrders( ) call, a table object containing the record objects from the resource-related Orders Rollbase object is returned as the method return value in the JSDO-defined _retVal property, which is returned in the response property object. When the callback registered by the Promise's fail( ) method executes for an unsuccessful getOrders( ) call, the callback reads the response property to return any single error message as a string value.