activate

Calls an operation on a component instance.

activate {/list | /sync | /async} | { /stateless} InstName{.LitOperationName ( {ArgumentList} ) }

Example: activate "MyCpt1"

Example: activate /async "MyCpt".do_it(vArg1, vArg2)

Qualifiers

Qualifiers
Qualifier	Description
/list	Passes two parameters in ArgumentList, each of which is a typed Uniface list, to hold the input and output parameters.
/stateless	Invokes a component operation in a stateless manner. When stateless operations are invoked on Uniface components, a temporary instance is created that is automatically deleted when the operation is finished. Stateless operation invocation is also supported in the communication to Uniface servers. Stored procedure components are stateless by default.
/async or /sync	Sets the communication mode for the operation; that is, the operation communicates either synchronously or asynchronously. These switches takes precedence over the switch on the newinstance statement and the component property as specified in the Signature Editor. Asynchronous operation invocation is only supported for components that are executed in a shared Uniface server or in an external middleware environment. Operations that are asynchronously invoked are not allowed to have OUT or INOUT parameters. They do not return a return value.

Parameters

Parameters
Parameter	Data Type	Description
InstName	String	Name of a component instance that holds the definition for the requested operation; maximum length of 16 bytes. If an instance with this name cannot be found, an implicit newinstance statement is executed to create an instance, using InstName as the name of the component; default properties are used for the new instance.
LitOperationName	Literal	Literal name of an operation that is part of the specified component instance, or a variable containing the name of an operation as a string. The value can be `exec`, `accept`, `quit`, or a named operation. If no operation and arguments are specified, .exec() is assumed; that is, the exec operation of the component InstName is started with no parameters. Do not enclose the name in quotation marks (").
ArgumentList	String	Comma-separated list of arguments to the operation. The number of arguments supplied must match the number and type of parameters defined with the params statement for the operation LitOperationName. If the data type of an argument does not match the type of the corresponding parameter, Uniface attempts to convert the data to the proper type.

Return Values

Operations that are asynchronously invoked are not allowed to have OUT or INOUT parameters. They will not return a return value.

If no return or exit statement is present, activate returns default values in $status.

Values returned in $status
Value	Description
10	The user used ^QUIT to leave the form that was started with activate.
9	The user used ^ACCEPT to leave the form that was started with activate.
0	$status has not been assigned a value by the activated operation, or if there is no return statement present
<0	An error occurred. $procerror contains the exact error. When a negative value is returned for $status, the values of parameters with direction OUT and INOUT must be considered to be undefined in the component that activated LitOperationName.
>0	Value returned by the operation that was activated. In this case, $procerror is set to zero. (Since Uniface considers a negative value to be an error, it is not a good idea to return a negative value from the activated operation.)

Values commonly returned by $procerror following activate
Value	Error constant	Meaning
-50	`<UACTERR_NO_SIGNATURE>`	Signature descriptor for the current component not found (in UAR or resource file). 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 (in UAR or resource file).
-52	`<UACTERR_PROTOCOL>`	Protocol error (wrong sequence of operations).
-53	`<UACTERR_ENTITY_GET>`	An error occurred while copying the occurrences of an entity parameter to occurrences of the activated operation. This occurs at the start of processing for the activate statement on either the client or the server.
-54	`<UACTERR_ENTITY_PUT>`	An error occurred while copying occurrences of the entity parameter in the activated operation to occurrences of the component instance. This occurs at the end of processing for the activate statement on either the client or the server.
-55	`<UACTERR_PARAMETER_GET>`	An error occurred while getting an `OUT` or `INOUT` parameter from the activated operation. For example, the actual parameter provided cannot be used to receive output because it is a constant string. This occurs at the end of processing for the activate statement on either the client or the server.
-56	`<UACTERR_PARAMETER_PUT>`	An error occurred while putting an `IN` or `INOUT` parameter into the activated operation. This error occurs at the start of processing for the `activate` statement on either the client or the server.
-57	`<UACTERR_NO_INSTANCE>`	The named instance cannot be found in the component pool.
-58	`<UACTERR_NO_COMPONENT>`	The named component cannot be found.
-59	`<UACTERR_NO_OPERATION>`	No definition found for operation.
-60	`<UACTERR_ACTION_ON_MODALFORM>`	An attempt was made by an instance other than the current modal form instance to start an operation other than the `EXEC` operation.
-61	`<UACTERR_ENTITY_DUMMY>`	The entity specified as an entity parameter is a dummy entity.
-62	`<UACTERR_ENTITY_PARAM_MISMATCH>`	The entity specified as an entity parameter must be the same entity as that specified in the operation. That is, one is a supertype and the other is a subtype of that supertype, or both are subtypes of the same supertype.
-73	`<ACTERR_REMOTE_NOT_SUPPORTED>`	Operation with `byref Struct` parameter cannot be activated across processes. For more information, see Passing Struct Parameters.
-104	`<UNS_UNSPATH_ERROR>`	The path to the remote component is not specified in the Name Server assignment file.
-151	`<UACTERR_EXCEPTION_THROWN>`	An exception error has been thrown. This error may be returned when a synchronous activation of a remote operation results in an uncaught exception.
-154	`<UACTERR_INSTANCE_NAME_EXISTS>`	An instance with this name already exists. This error code is returned, for example, in the following cases: when a modal form which is already active is activated again when 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: The component could not be loaded. An exit statement was executed in the operation `INIT`.
-164	`<UACTERR_DEL_POSTPONED_PROC>`	The instance is in the process of being deleted. For example, between a deleteinstance or exit and the time the instance is actually deleted, an attempt is made to activate an operation in the instance being deleted.
-168	`<UACTERR_ZOOM_ACTIVE>`	Zoom window active. It is not possible to start a Form from a zoom window.
-180	`<UACTERR_ACCESS_DENIED>`	An operation or trigger that is being activated from a web or SOAP client has not been declared as public web or public soap.
-1105	`<UPROCERR_INSTANCE>`	The instance name provided is not valid.) For example, the argument contains incorrect characters.
-1120	`<UPROCERR_OPERATION>`	The operation name provided is not valid.
-1122	`<UPROCERR_NARGUMENTS>`	Wrong number of arguments.
-1123	`<UPROCERR_NPARAMETERS>`	Wrong number of parameters.
-1411	`<UPROCERR_EDITTWICE>`	activate was performed on a modal form that is already in edit mode and that has an empty exec operation (an implicit edit).

Use

Allowed in all component types.

Description

The activate command is normally used after newinstance, which creates a (named) instance of the specified component.

However, if newinstance is not used first, or the specified instance name cannot be found, an implicit newinstance statement is executed to create an instance, using InstName as the name of the component; default properties are used for the new instance.

For example, the following command:

activate "myCpt"

implicitly executes the following statements:

newinstance "myCpt", "myCpt"
activate "myCpt".exec()

For more information, see newinstance.

Note: For form components, we recommend that you use handles variable for the instance name. For more information, see Activating Operations Using Handles.

Specifying the Operation Name

The LitOperationName can be specified as a literal or as a variable. For example:

Literal Operation Name

newinstance "myCpt", "myCptInstance"
activate "myCptInstance".do_it()

Component Variable for Operation Name

; $vOperation$ is a component variable
newinstance "myCpt", "myCptInstance"
$vOperation$ = "do_it"
activate "myCptInstance".$vOperation$()

Local Variable for Operation Name

; vOperation is a local variable
 
 newinstance "myCpt", "myCptInstance"
 vOperation="do_it"
 activate "myCptInstance"."%%vOperation%%%"()

Specifying Operation Arguments

At runtime, when an operation is activated, the operation requirements are obtained from the signature descriptor. The arguments supplied in ArgumentList must match the number and data type of the parameters defined for the operation.

Arguments for IN parameters can be specified as a constant, or as an assignable expression (field, variable, or function) that evaluates to a value.
Arguments for INOUT must be specified as an assignable expression that evaluates to a value.
Arguments for OUT parameters must be specified as an assignable expression.

When an operation is activated, the argument values for IN or INOUT parameters are placed in the matching parameters at the start of the operation. When the operation completes, the values of its OUT and INOUT parameters are returned to the field, variable, or function specified by the argument.

If the data type of an argument is not specified or does not match the type of the corresponding parameter, Uniface attempts to convert the data to the proper type. For example, the operation ADD_WEEK in the service SERV2 expects to find three parameters, with data types Date, Numeric, and Date.

operation ADD_WEEK
params
  date INDATE : IN
  numeric ADDWKS : IN
  date OUTDATE : OUT
endparams
...
end ; ADD_WEEK

When the operation ADD_WEEK is activated with the following statement, the string constant supplied as the first argument is converted to a Date for the operation:

activate "SERV2".ADD_WEEK ("19-jul-96", 5, $DELIV_DATE$)

If the operation expects an entity or occurrence parameter (that is, a constructed parameter), the ArgumentList must be a string (or assignable expression that evaluates to a string) containing the name of a modeled entity (database or non-database) that is painted on the component.

For example, if the current component contains the modeled entity PO_ITEMS, the following statements sends all the occurrences of the entity PO_ITEMS to the operation TOTAL_LNS in the service SERV2:

setocc "PO_ITEMS", -1
activate "SERV2".TOTAL_LNS("PO_ITEMS")

Passing Typed Lists of Parameters

You can use activate/list to pass typed lists of parameters.

Tip: You can explicitly specify the data type of arguments using the $typed ProcScript function, or other data type functions. For more information, see $typed.

For example:

operation CallAddWeek
variables 
  String vInParms, vOutParms
endvariables

;Create a typed list of parameters
putitem vInParms, -1, $date(19980203)
putitem vInParms, -1, $number(1)

activate/list "SERV2".ADD_WEEK(vInParms,vOutParms)
end

After calling this activate, vOutParms has the value ";;$date(19980210)"

Parameters for Operations in 3GL Services

When you activate an operation in a 3GL service, consider the following:

If a parameter is declared as IN or INOUT, Uniface handles the memory management for the parameter.
If a parameter is declared as OUT, the 3GL program is responsible for managing the memory required.

Activating Operations in Modal Forms

An operation in a modal form can be started only in the following circumstances:

A modal form instance starts an operation contained within itself. This can be an operation in the Operations trigger or a special operation like ACCEPT or QUIT.
A component instance starts the EXEC operation of a modal form. This is equivalent to using the run statement to start a modal form (with the additional possibility of using parameters).

Activating Operating System Operations

You can activate commands on the operating system command line by creating a signature for an operating system service with the Implementation Type set to Operating System Command. This implementation provides the default operations COMMAND and COMMANDOUT. You can then use the activate command to pass an operating system command to one of these operations. You can use your assignment file to redirect the OS service components to a Uniface server. The maximum length of a command is 511 bytes. For more information, see Implementing an OS Service.

In the following example, the exec operation starts two attached, non-modal forms:

operation exec
  newinstance/attached "NMF2A", "NMF2A", "MODALITY=NON-MODAL"
  activate "NMF2A".EXEC()
  newinstance/attached "NMF2B", "NMF2B", "MODALITY=NON-MODAL"
  activate "NMF2B".EXEC()
end; exec

If the forms NMF2A and NMF2B are both defined with their window property Modality & Attachment set to Non-Modal, Attached, these properties do not need to be explicitly stated on a newinstance statement. In this case, the exec operation can be simplified as follows:

operation exec
  activate "NMF2A"
  activate "NMF2B"
end; exec

Even though the required ProcScript is longer, for documentation purposes, it can be helpful to use newinstance to explicitly state the properties when creating instances.

Exception Handling in an Activated Operation

When an activated operation is exception-enabled and throws an exception, this exception bubbles up to the activate statement. If activate is exception-enabled, and does not catch the exception, it propagates it up to the next level. The information within $procerrorcontext will show that the origin of the exception is from the operation, or deeper in the call stack.

If activate is not exception-enabled, activate passes the $procerror and $procerrorcontext values set by the operation to the following statement. Code execution simply continues and no exception is thrown.

If an exception-enabled activate statement fails to activate the operation, for example by calling the wrong operation, the exception is thrown from activate itself.