activate()

Asynchronously activates an operation on the current component instance, or the main instance.

ComponentInstance.activate({OperationName{,Parameters})

Arguments

  • Operation—name of an operation. This can be a server-side operation declared with operation or a client-side operation declared with weboperation.
  • Parameters—comma-separated list of arguments to the Operation

Return Value

A JavaScript Promise object is returned. See Promise Resolution.

If the promise is rejected, an Error object is returned as a parameter. See Promise Rejection.

For more information, see Promises .

Errors and Exceptions

At runtime, errors may occur in the following situations.

  • The syntax of the operation name is invalid.
  • The specified component cannot be found.
  • The specified operation cannot be found or is invalid.
  • The specified parameters do not match or are invalid.

The following exception may be thrown:

  • uniface.InvalidDSPInstanceException

If the promise is rejected, an error object is returned. The nature of the error can be queried using the instanceof operator. For example:

uniface.activate("OPER").catch(function(e) { if (e instanceof ErrorType) ... } );

Description

Use this function to call an operation on the current component instance, or when called on the uniface object, the main instance. The operation may be run on the client or the server, depending on whether it is declared using the operation or weboperation ProcScript instructions.

Operations are subject to scoping rules, so execution of the operation may be postponed if its input or output is blocked.

Parameters

You can use both IN and IN/OUT parameters when activating operations. To get the values for the IN/OUT parameters that are sent back to the browser, you can use the value that the promise is resolved with.

IN and IN/OUT parameters are passed as strings. If a parameter has a different data type, you must ensure that the incoming parameters are converted to the appropriate data type. This must be a simple data type; entity parameters, or complex data type parameters are not supported.

For OUT parameters sent back to the browser, an appropriate Javascript data type is chosen. For more information, see Data Type Mapping Between Uniface and JavaScript.

Promise Resolution

For a server-side operation, the promise is fulfilled when a response has been received from the server to the activation request, and any data and other commands sent as part of the response have been processed. All instances, fields, entities, and occurrences reflect the data that was sent by the server.

For a client-side weboperation, the promise is fulfilled when the call to the JavaScript function associated with the web operation is finished.

Promise resolution is asynchronous, which means that any code immediately following the call to activate() will be executed before the promise is resolved.

The promise returned from activate() resolves with an object that has the following members:

Members of Returned Promise Object
Name Description
instance uniface.Instance object that represents the component instance whose operation was invoked
returnValue Return value of the operation.

For a server -side ProcScript operation, the ProcScript return value, which is always a number.

For a client-side weboperation, the JavaScript value that was returned.
args For a server-side operation, an array with the arguments of the operation. There are array slots for all IN and INOUT parameters, with the first parameter at index 0. The value for IN parameters is the empty string. The value for INOUT parameters is the value set by the ProcScript code in the operation.

For a client-side weboperation, the value is undefined.

Promise Rejection

If the promise is rejected, an Error object is returned. The nature of the error can be queried using the instanceof operator. For example:

uniface.activate("OPER").catch(function(e) { if (e instanceof ErrorType) ... } );

If a client-side weboperation throws an exception, the activate() promise will be rejected with the exception object as value.

Promise Rejection Errors
e instance of Meaning
uniface.UnifaceError The server-side code returned a ProcScript error (‘yellow screen’)
uniface.TransportError It was not possible to send a request to the server; for instance, the server or network was down or not reachable.
uniface.HTTPError The server was reachable, but it replied with an HTTP error

Members:

  • statuscode—the HTTP response code (for example, 404 or 501)
  • statustext—friendly form of HTTP error (for example "not found")
uniface.ServerError The Uniface Server encountered an internal error; for example, the Uniface Router was not reachable (‘red screen’)
SyntaxError The response from the server had invalid (JSON) syntax
uniface.NotCallable The operation is not callable; for example, it is not ‘public web’

Members:

  • moduleName—the operation name
  • instanceName
  • componentName
uniface.ModuleNotFound The JavaScript implementation of the web operation was not found, possibly because of a syntax error in the weboperation’s JavaScript, or failure to include the appropriate JavaScript file. Members:
  • moduleName—the operation name
  • instanceName
  • componentName
Error An unknown error occurred Members: message: the error message text

Calling an Operation with Parameters

A DSP component has the following operation which accepts and employee ID as input parameter. It is executed on the server.

operation loadEmployee
public web
scope
  input
  output
endscope

params
	 string pEmpID   : IN
  string pEmpName : INOUT
endparams

; Retrieve the record for the specified employee
ID.PERSON = pEmpID
retrieve/e PERSON.ORG

;Return the data in the second parameter:
pEmpName = NAME.PERSON

end ;loadEmployee

To activate this operation from JavaScript, you can use the following code, which displays the name of the employee associated with :

var vEmpId = "1" ;
var vEmpName = ""

var vEmpId = "1" ;
var vEmpName = ""
var vReturn = uniface.activate("loadEmployee",vEmpId, vEmpName).then(function (response) {
    console.log(response.args[1]); // Display the second argument (the returned employee name) in the console
 }).catch(function (err) {
  console.log(err);
 });

Related Topics