INVOKE( ) method (Handle)

Lets you do the following dynamically:

Invoke an external procedure, internal procedure, or user-defined function

Invoke a Windows DLL routine or Unix shared library routine

Get or set an object handle attribute

Run an object handle method

Return type: None (Similar to the RUN statement.)

Applies to: Call object handle

Syntax

INVOKE( )

To determine what action to take, INVOKE( ) examines the CALL-NAME and CALL-TYPE attributes.

Before you execute INVOKE( ), you must set the CALL-NAME attribute.

The following table describes what INVOKE( ) does for each call type.

Table 84. What INVOKE( ) does for each call type
For this call type . . .	INVOKE( ) . . .
PROCEDURE-CALL-TYPE (the default)	Follows the rules of the RUN statement to determine what to invoke and whether to invoke external or internal procedures.
FUNCTION-CALL-TYPE	Follows the rules of the DYNAMIC-FUNCTION function.
GET-ATTR-CALL-TYPE	Follows the rules of widget:attribute. Note: The IN-HANDLE attribute must be set before INVOKE( ) is executed.
SET-ATTR-CALL-TYPE	Sets the attribute specified by the CALL-NAME attribute to the first parameter specified by the SET-PARAMETER( ) method. Note: The IN-HANDLE attribute must be set before INVOKE( ) is executed.

If the PERSISTENT attribute is TRUE or PROCEDURE-TYPE attribute is set to "PERSISTENT" (which is valid only for invoking an external procedure), the procedure runs persistently, and when INVOKE( ) returns, IN-HANDLE contains a handle to the persistent procedure. If PROCEDURE-TYPE is set to "SINGLE-RUN" or "SINGLETON", IN-HANDLE contains a handle to the single-run or singleton procedure, respectively. Note that unlike persistent procedures, procedures run as single-run or singleton cannot have parameters in their main blocks.

Before you dynamically invoke an external procedure that is remote—that is, one that resides on an AppServer—you must set the SERVER attribute to the handle of the AppServer.

When INVOKE( ) starts executing, it examines the NUM-PARAMETERS attribute. If NUM-PARAMETERS is nonzero, INVOKE( ) uses each parameter set by the SET-PARAMETER( ) method, even one set during a previous use of the call object.

Note: To clear all parameters, even those set during a previous use of the call object, set the NUM-PARAMETERS attribute to zero.

No parameters are evaluated during INVOKE( ) processing. Parameters are evaluated only during SET-PARAMETER( ) processing.

When the invoked routine starts, if any parameter indicated by the NUM-PARAMETERS attribute has not been set, you will get an error message.

For more information on INVOKE( ), see the reference entries for the RUN statement and the DYNAMIC-FUNCTION function.

Note: INVOKE( ) cannot occur within an expression.