newinstance

Creates a new instance of a component.

Example: newinstance "MYCOMPONENT", vHandle, vProps

Return Values

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.

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.

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:

• $componentname
• $componenttype
• $instancechildren
• $instancename
• $instanceparent

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

• $instancedb
• $instancedbmod
• $instancemod