invocation method

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.

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.

Return type: request object or undefined

Applies to: progress.data.JSDO class

Syntax

op-name ( [ input-object ] [ , async-flag ] )

op-name

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:

1. beforeInvoke event
2. afterInvoke event

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 more information on data type mappings for an OpenEdge resource, see OpenEdge ABL 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. For more information on error information returned in the response property, see the description of the response property.

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:

dataSet = new progress.data.JSDO( 'dsCustomerOrder' );
dataSet.subscribe( 'afterInvoke', 'getOrderTotalAndStatus', 
                   onAfterInvokeGetOrderTotalAndStatus );

dataSet.getOrderTotalAndStatus( paramObject ); // An asynchronous call is the default
    
function onAfterInvokeGetOrderTotalAndStatus( jsdo , success , request )
    if (success) {

        var response = request.response;        
        var ordTotal = response._retVal;
        var ordStatus = response.pcStatus;
        /* process successful results */
        . . .
        
    }
    else {
        if (request.response && request.response._errors && 
            request.response._errors.length > 0) {

            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.

See also:

addRecords( ) method, invoke( ) method, fill( ) method, record property, request object, saveChanges( ) method