A custom method on the JSDO that executes an Invoke operation defined for a Data Object resource.
For an OpenEdge resource, this invocation method can be implemented as a corresponding ABL routine on an OpenEdge application server. This implementation can be any ABL routine that is defined in its Data Service Catalog with an Invoke operation type. The invocation method name can be the same as the ABL routine or an alias, as defined by the resource. The method passes any ABL input parameters as properties of an object parameter. The method returns results from the ABL routine, including any return value and output parameters, as properties of a request object that is returned by the method.
For a Rollbase object resource, this invocation method can be implemented as an API defined by the Rollbase server that reads and returns data from a related Rollbase object.
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 custom invocation method can be executed either synchronously, returning results in an object return value, or asynchronously, returning similar results in an afterInvoke event callback, depending on a parameter that you pass. You can also call the invocation method asynchronously using the JSDO invoke( ) method, which returns results as a jQuery Promise. For more information on using invoke( ), see the description of the invoke( ) 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.
The name (specified as an identifier) 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.
async-flag
A boolean that when true causes the method to execute asynchronously and when false causes the method to execute synchronously. The default value is true.
Returning and handling results
For a synchronous invocation, the method returns, as its value, a request object that contains several properties depending on the status of the Invoke operation.
For an asynchronous invocation, the method return value is undefined, but returns a similar request object as input to any event handler (callback) function subscribed to the following named events that fire in the following operational order:
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 more 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.
Note: For an OpenEdge resource, if you are calling an invocation method that either sends a single table object or a ProDataSet object (with one or more tables) as a property of input-object or returns a single table object or ProDataSet object as a property of the response property object, you need to apply a rule in order to access this table or ProDataSet object. The rule is that wherever you de-reference or reference a table or ProDataSet object, you must reference that value twice, separated by a period or a colon, depending on the context. The reason is that the table or ProDataSet name is both the name of the parameter defined for the ABL routine and also the name of the JavaScript object containing the JSON data returned from the server. For example, to access a table object, ttCust returned by the response property in a request object, you must code the following de-reference: request.response.ttCust.ttCust. Similarly, if you pass ttCust to an invocation method, InputTT( ), you must code the following reference: jsdo.InputTT( {ttCust: {ttCust:ttCust}});
Note: For an OpenEdge resource, if the invocation method passes ProDataSet as an input or output parameter, that ProDataSet can contain before-image data. However, the invocation method does no processing of the before-image data in any way. You must therefore manage the object appropriately. For example, you can use an output ProDataSet containing before-image data as a merge-object parameter to the addRecords( ) method as long as your JSDO is created with the same ProDataSet schema and the OpenEdge resource supports before-imaging.
Note: For a Rollbase resource, each specified invocation method returns table records from a Rollbase object that is related to the resource-defined Rollbase object. For example, the resource might have an invocation method named getOrders( ) on a Customers resource. So, to return records from a Rollbase Orders object that is related to the resource-defined Customers object, you can make the following reference on the request object returned by getOrders( ): request.response.Orders.
Example
The following code fragment shows an invocation method (getOrderTotalAndStatus( )) called asynchronously on a JSDO as defined for an OpenEdge resource (dsCustomerOrder), with results returned in the callback (onAfterInvokeGetOrderTotalAndStatus) subscribed to the afterInvoke event:
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 the callback is subscribed only for execution of getOrderTotalAndStatus( ) and the call to getOrderTotalAndStatus( ) is asynchronous by default, with its input parameters passed in paramObject. For a successful execution in the callback, 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. For an unsuccessful execution, the callback inspects the response property to return one or more error messages in an array of objects.