IN-HANDLE attribute

Holds one of the following:

A handle to a persistent procedure (a procedure invoked with the PERSISTENT attribute set to TRUE or PROCEDURE-TYPE attribute set to "PERSISTENT")

A handle to a single-run or singleton procedure (a procedure invoked with the PROCEDURE-TYPE set to "SINGLE-RUN" or "SINGLETON", respectively)

A handle to an object, such as a buffer or socket, which has attributes you want to get or set dynamically or methods you want to run dynamically

Data type:

HANDLE

Access:

Readable/Writable

Applies to:

Call object handle

You can set IN-HANDLE using the following syntax:

 

Syntax 

call-object:IN-HANDLE [ = { handle-expression | char-expression } ]

handle-expression

A HANDLE expression.

char-expression

A CHARACTER expression indicating the name of a system object, such as "SESSION" or "FILE-INFO", whose handle is returned.

The default is the Unknown value (?).

IN-HANDLE will be set automatically to a procedure handle when you run a persistent, single-run, or singleton procedure by calling the INVOKE( ) method on the call object:

 

Syntax 

call-object:INVOKE( )

Table 82 lists the different ways of setting IN-HANDLE.

 

Table 82:

Setting IN-HANDLE

If you want to access. . .	Then IN-HANDLE. . .
A procedure as persistent, single-run, or singleton	Is automatically set to the procedure handle after calling the INVOKE( ) method on the call object
An internal procedure or user-defined function of a previously invoked persistent, single-run, or singleton procedure	Must be manually set to the handle of the existing object, unless IN-HANDLE already holds the procedure handle from a previous INVOKE( )
Any handle-based object whose attributes you want to get or set dynamically	Must be manually set IN-HANDLE to the handle of the existing object, such as a temp-table, buffer, or socket

When you use IN-HANDLE to call an internal procedure, IN-HANDLE affects INVOKE( ) the same way the IN proc-handle phrase affects the RUN statement. Similarly, when you use IN-HANDLE to call a user-defined function, it affects INVOKE( ) the same way the IN proc-handle phrase affects the DYNAMIC-FUNCTION function. In both cases, IN-HANDLE specifies the instance of the external procedure that contains the internal procedure or user-defined function.

When IN-HANDLE is used to get or set an attribute or to invoke a method, it represents a handle to the object to which the attribute applies. If the attribute applies to a system object such as the SESSION handle or the FILE-INFO handle, IN-HANDLE can be set to a character string such as "SESSION" or "FILE-INFO" that indicates the name of the system object.

Note:

You can run a procedure as persistent, single-run, or singleton statically or dynamically. Similarly, you can run any of the persistent, single-run, or singleton procedure’s internal procedures and user-defined functions statically or dynamically.

For information on dynamically invoking logic that resides on an AppServer, see the reference entry for SERVER attribute.