newinstance

Creates a new instance of a component.

newinstance{/sync | /async} {/attached}   ComponentName, Handle | InstanceName   {, InstanceProperties}

Example: newinstance "MYCOMPONENT", vHandle, vProps

Qualifiers

Qualifiers
Qualifier Description
/async Specify the communication mode for the operation as asynchronous. Not applicable if Handle is specified. See Communication Modes.
/sync Specify the communication mode for the operation as synchronous. Not applicable if Handle is specified. See Communication Modes.
/attached Attaches the new instance to the current component instance. See Attached Instances.

Parameters

Parameters
Parameter Data Type Description
ComponentName

String

Name of the component. If ComponentName is a Uniface component, the string has a maximum length of 16 bytes. Otherwise, the string has a maximum length of 32 bytes.
Handle

String

An empty variable of type handle. Uniface generates a handle to the instance that is unique within the application and stores it in that variable. See Using Handles
InstanceName

String

Name of the component instance.The name can contain letters (A-Z), digits (0-9), and underscores (_); the first character must be a letter. The string has a maximum length of 32 bytes; trailing blanks are removed. See Using Instance Names
InstanceProperties

String

Associative list defining the properties for this instance.

Note:  Most instance properties are meaningful only for form components; they are ignored for other component types. See Instance Properties

Return Values

Values returned in $status
Value Description
<0 Component instance could not be created. $procerror contains the exact error.
0 Component instance was successfully created.
Values commonly returned by $procerror following newinstance
Value Error constant Meaning
-50 <UACTERR_NO_SIGNATURE> Signature descriptor for the current component not found. For example, the component name provided is not valid.

Signature descriptor found, but an interface is missing or invalid.

-51 <UACTERR_SIGNATURE_ID> The identifier of the compiled component does not match the identifier in the signature descriptor.
-58 <UACTERR_NO_COMPONENT> The named component cannot be found.
-154 <UACTERR_INSTANCE_NAME_EXISTS> An instance with this name already exists.

For example:

  • A modal form is already active and is activated again
  • An attempt is made to activate a modal form from a non-modal form
-155 <UACTERR_CREATE_INSTANCE> An error occurred while creating an instance:

An unknown property occurs in the instance properties. A property in the instance properties has a value that is not valid. The component could not be loaded. An exit statement was executed in the operation INIT.

-166 <UACTERR_STATELESS> Component instance could not be created because the component is stateless.
-1105 <UPROCERR_INSTANCE> The instance name provided is not valid. for example, the argument contains incorrect characters.
-1106 <UPROCERR_COMPONENT> The component name provided is not valid; for example, the argument contains an empty string ("").
-1110 <UPROCERR_TOPIC> Topic name not known.
-1410 <UPROCERR_PROPERTY_VALUE> A property has been assigned an incorrect value.

Use

Allowed in all component types.

Description

The newinstance statement creates an instance of the specified component. When InstanceName is specified, it creates a new instance with that name.

Note:  Use the instance name when creating dynamic and static server pages. For other components, it is preferable to use handles.

When a handle is specified, the identifier of the new instance is returned as a handle and all communication with the instance is done via the handle. The reference count of the handle is 1 after the newinstance statement is complete. The compiled component is loaded and added to the component pool. Control then returns to the component that issued the newinstance statement.

By default, an instance is created as a synchronous process.

Before creating the new instance, Uniface locates a signature descriptor for ComponentName (in a resource or UAR archive). This information is used to create the new instance.

For Uniface components, the signature and signature descriptor are created (and updated) automatically whenever the component is compiled. For other types of component, such as 3GL components, you must use the Signature Editor to create the signature and the compiled descriptor.

A component instance remains in the component pool until one of the following situations occurs:

  • The instance executes an exit statement.
  • The ACCEPT or QUIT operation of an instance returns a non-negative value.
  • A deleteinstance statement that specifies instance name is executed.
  • For an instance created using a handle, there is no longer a handle that refers to the instance.

If the component defines an operation named CLEANUP, this operation is executed before the instance is removed.

Using newinstance allows you to start several instances of the same component, each known by its own instance name. If, for example, the component is a service or report, assignments in the [SERVICES_EXEC] or [REPORTS_EXEC] section of the assignment file determine if the instance is created on the client or server machine. (Instances of Form components are always created on the client machine.)

Communication Modes

When the first instance of a component is created, the communications mode for that component is determined; that is, the new instance and all further instances of the same component run either synchronously or asynchronously. The communication mode affects the execution as follows:

  • If the new instance runs synchronously, each time an operation of the instance is activated, the component that requests the operation waits until the operation completes before proceeding.
  • If the new instance runs asynchronously, the component that requests an operation does not wait for the operation to complete; it simply proceeds with its next ProcScript statement.

By default, an instance is created as a synchronous process. You can override this by choosing setting the component's Communication Default property to Asynchronous. This information is included in the component descriptor.

You can override the information in the component descriptor by using either the /sync or /async switch in the newinstance statement. Note that:

  • The /async and /sync switches cannot be used if you specify a Handle, which is, by definition, a pointer to a synchronous instance.
  • If one of these switches is used on the activate statement, it gets precedence over the switch on the newinstance statement and the component property as specified in the Signature Editor. If neither are present, the information in the component descriptor is considered.
  • All form components run synchronously. The /sync and /async switches, and the Communication Default property is ignored.

Attached Instances

The new component instance is attached to the current instance in the following circumstances:

  • The component's Attached property is set to True.
  • The /attached switch is used to create a child instance.
  • The property Modality & Attachment for ComponentName is set to Modal, Attached or Non-Modal, Attached.

    When set to Non-Modal, Detached, the new instance can be viewed as a child of the application shell. In this case, the new, detached instance remains active until it exits itself or until the application exits.

When /attached is used:

  • If the current instance is deleted, the child instance and all other child instances that still exist are removed before the current instance is deleted.
  • If the current instance is iconized, the child instance and all other child instances that still exist are also iconized. When the current instance is restored, all its child instances are restored with it.

Note:  The /attached switch has no meaning in a trigger of the application shell. In this case, all new instances can be considered as attached to the application screen.

When using /attached in desktop environments, note the following:

  • A similar problem can occur when a shared server has been started with a /maxidle or /maxreq switch and all the instances are deleted—the Uniface Router may shut down the server. If an invalid handle to a child instance exists, Uniface performs an implicit deleteinstance and the Router will log error messages such as:

    err=-25: Problems handling request
    err=-25: Server gone

To avoid these problems, do not use attached instances, or delete them before the parent is deleted (although this incurs extra network traffic).

Using Handles

A handle is a physical reference to a component instance. You can use handles to identify components when the components exist within the same process (or context). For example:

  • All Uniface components in a client process.
  • All Uniface components in one Uniface Server process.
  • All component instances created with the C Call-in API.

If you need to exchange instance identifiers over multiple processes (for example, in web applications), you should use unique instance names to create new instances. See Using Instance Names.

The following ProcScript is used to create a new instance of the component MYCOMPONENT, and Uniface returns a unique identifier in myHandle:

variables
   handle vHandle
endvariables
newinstance "MYCOMPONENT", vHandle

This identifier can be used to activate operations of the component instance. For example:

myHandle->myOperation(myParam)

If the argument that is specified in the position of Handle or InstanceName is an empty generic variable, by default, Uniface returns a handle in that generic variable. For example, if the following ProcScript is used to create a new instance of the component MYCOMPONENT, Uniface returns a unique identifier in $1 of type handle:

$1 = ""
newinstance "MYCOMPONENT", $1

This identifier can be used to activate operations of the component instance. For example:

$1->myOperation(myParam)

If the identification of a component instance that is created in a Uniface Server has to be returned to a client application, a handle must be used:

On the server:

operation createInstance
params
   handle pHandle : OUT
endparams
newinstance "COMPONENT", pHandle
end ; operation createInstance

And on the client:

variables
   handle myHandle
endvariables
; $handleToServerInstance$ is a handle to an instance on a Uniface server.
; createInstance operation creates a new instance on the server.

$handleToServerInstance$->createInstance(myHandle)


; Do something with the instance
myHandle->someOperation(17);


; When finished remove the reference to the instance
myHandle = 0;

Using Instance Names

You can use component instance names when creating component instances and activating components.

Using instance names is required when exchanging component identifications over multiple application processes, because handles are physical references to instances and cannot be maintained over different processes.

This is always true for dynamic and static server pages, because a handle cannot be transported to the web client. Therefore, always use unique instance names when creating or activating instances for dynamic and static server pages.

The name of an instance is valid only within the process in which it is created, which could be an interactive Uniface desktop application or a Uniface Server process. However, there is no guarantee that when an instance name is used in another context, the correct instance will be addressed.

Although Uniface will generate an instance name if none is provided, or if activate is used without first using newinstance, this has the following limitations:

  • A Uniface-generated name is only unique within the process in which it is created.
  • In web applications, when a trigger or operation is activated in a dynamic server page, the Uniface Server cannot reconstruct the Uniface-generated instance name. The implicit newinstance of a generated instance name fails, typically because it does not start with a letter, or because it is not necessarily unique within the Uniface Server process.

Therefore, when you need to exchange instance identifications over multiple processes, you need to define or generate your own unique instance names, and ensure they are unique over the whole application span.

Instance Properties

With the exception of Transaction, instance properties are meaningful only for Form components; they are ignored for other component types.

Instance Properties
Property Possible values Default value, if omitted
Display True | False False
Dimension Top, Left, Width, Height 0, 0, 0, 0
Query True | False False
Modality MODAL, NON-MODAL Determined by the component window property Modality & Attachment.
Transaction True | False False
InitialFocus True | False True
Window Type (WindowType) Popup None

Note:  The following properties are only applicable to popup windows. For more information, see Popup Window.

FieldName FieldName Name of current field
PopupAt field | mouse field
Position Origin_Direction | overlay BOTTOMLEFT_DOWNRIGHT
Reposition True | False True
Auto Close (AutoClose) True | False False
InheritWinProps True | False False

New Instances of Stateless Components

You are not allowed to create an instance of a component that is marked as stateless in the Signature Editor. An error is issued if you do this. For more information, see activate.

Init and Cleanup Operations

If an Init operation has been defined in the component, it is executed before the new instance is created. Since the new instance does not really exist at this point, the Init operation should not perform any action that involves the new instance. For example, it should not use deleteinstance on the instance or activate for an operation contained in the instance.

If a Cleanup operation has been defined in the component, it is executed as the instance is removed (by an exit statement, by executing an ACCEPT operation, or a deleteinstance statement, and so on). Since the instance being deleted no longer exists at this point, the Cleanup operation should not perform any action that involves its own instance. For example, it should not use deleteinstance on the instance or activate for an operation contained in the instance.

The return values of Init and Cleanup have no effect on further processing.

Use of Functions

When referring to an instance created with newinstance, the following functions return the requested information for the current instance:

The following functions return various modification statuses associated with the instance:

Creating and Deleting Instances

In the following example, the apStart trigger starts a sequence of non-modal forms before allowing the user to take control of the application. When control returns to this trigger, the ProcScript removes any detached instances that are still in the component pool.

trigger apStart

; start the initial forms
newinstance "form10",$1,"MODALITY=NON-MODAL"
newinstance "form20",$2,"MODALITY=NON-MODAL"
newinstance "form40",$3,"MODALITY=NON-MODAL"
; show them
$1->EXEC()
$2->EXEC()
$3->EXEC()
; let the user play
; control returns to me, so clean up any detached instances
getitem $1, $detachedinstances, 1
while ( $status > 0 )
   deleteinstance $1
   getitem $1, $detachedinstances, 1
endwhile
end
History
Version Change
9.6.04 X401 Added InitialFocus instance property
9.6.01 Added instance properties for Popup windows

Related Topics