createInstance()

Asynchronously creates a DSP component instance and executes the specified operation (if any).

uniface.createInstance(ComponentName, {InstanceName {,OperationName{, Parameters}}})

Arguments

  • ComponentName—name of the component definition
  • InstanceName—component instance name; if omitted an instance with the name of the component will be created (if it does not exist)
  • Operation—name of an operation on the component; value can be EXEC, ACCEPT, QUIT, or a named operation; if not specified, default is EXEC

    Note:  It is not possible to create a new instance using a client-side operation (weboperation). Such a request will be rejected with a security error.

  • Parameters—comma-separated list of arguments to the operation

Return Value

Returns a JavaScript Promise object. If the promise is resolved, the newly-created uniface.Instance object is returned. See Promise Resolution.

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

For more information, see Promises .

Errors and Exceptions

At runtime, errors may occur in the following situations.

  • The syntax of the Instance name string used to call the function is invalid.
  • An instance with the specified name already exists (either explicitly specified or with the component name, if it was omitted). This results in an DuplicateDSPInstanceNameException.
  • The specified component is not available on the server
  • The specified operation cannot be found
  • The specified parameters do not match or are invalid
  • There was no other activation error, but the server did not return the requested instance (for example, because webdefinitions was not called on the requested instance). This returns a uniface.NoteCreated error object.

Description

When the createInstance function is called in JavaScript, the following actions occur:

  1. The request is put on the queue to be sent asynchronously to the server.
  2. createInstance immediately returns a promise object to the browser. The promise is resolved or rejected after a response from the server has been received and processed.
  3. When the Uniface Server receives the request, it creates the instance and executes the operation (if specified). However, if the instance already exists, an exception is thrown.
  4. The new instance object is added to the collection of instances available in the browser. It can then be addressed using the functions available on the uniface.Instance object.

The createInstance function can only apply output scope, not input scope, and ignores any references to scope in other operations. This is because, at the moment createInstance is executed, the client side does not yet have the definition of the instance to be created, so it does not have the input scope of the specified operation.

Parameters

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

IN and INOUT 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

A promise is resolved when:

  • A response has been received from the server to the activation request
  • 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.
  • Definitions for the newly-created instance were included in the response, so the server actually created the instance and called webdefinitions for it.

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

Returned Promise Object
Name Description
instance uniface.Instance object that represents the component instance whose operation was invoked
returnValue The ProcScript return value of the operation, which is always a number.
args 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.

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) ... } );
Promise Rejection Errors
e instance of Meaning
uniface.UnifaceError A ProcScript error (‘yellow screen’).
uniface.TransportError It was not possible to send a request to the server; for example, the server or network was down or not reachable.
uniface.HTTPError The server was reachable, but it replied with an HTTP error. The error object has the following members:
  • statuscode—the HTTP response code (for example, 404 or 501)
  • statustext—description of the 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. The error object has the following members:
  • moduleName—the operation name
  • instanceName
  • componentName
uniface.NotCreated There was no other activation error, but the server did not return the requested instance (for example, because webdefinitions was not called on the requested instance).
Error An unknown error occurred. Members: message: the error message text

Related Topics