INVOKE( ) method (Handle)

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.

Table 83 describes what INVOKE( ) does for each call type.

Table 83: 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 (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.

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.

Syntax
INVOKE( )

Table 83: 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.

OpenEdge Release 10.2B