activate

Calls an operation on a component instance.

Example: activate "MyCpt1"

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

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:

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

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

; 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.