newinstance
Creates a new instance of a component.
newinstance{/sync |
/async} {/attached}
ComponentName,
Handle |
InstanceName
{,
InstanceProperties}
Example: newinstance "MYCOMPONENT", vHandle, vProps
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
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
Value | Description |
---|---|
<0 | Component instance could not be created. $procerror contains the exact error. |
0 | Component instance was successfully created. |
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:
|
-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 |
-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
orNon-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.
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
Version | Change |
---|---|
9.6.04 X401 | Added InitialFocus instance property |
9.6.01 | Added instance properties for Popup windows |