Progress
Version 9
Product Update Bulletin


CALL Object Handle

Interfaces
OS
SpeedScript
All
All
Yes

A handle to a CALL object, which lets you do the following dynamically:

Invoking logic dynamically requires many more lines of code than does invoking it statically, which can make your program hard to read. For this reason, Progress Software Corporation recommends that you invoke logic dynamically only when absolutely necessary. Specifically, use the CALL object only when you cannot use the RUN statement, the DYNAMIC-FUNCTION() function, or widget:attribute or widget:method syntax, as in the following situations:

The CALL object handle has attributes and methods that tell CALL what to do, how to do it, and when to do it.

SYNTAX

call-object-handle [ :attribute | :method ] 

call-object-handle

A handle to a CALL object.

attribute

An attribute of the CALL object. Table D–1 summarizes each attribute.

Table D–1: CALL Object Attributes
Attribute
Type
Description
LOGICAL
(Applies only when the logic to be dynamically invoked resides on a Progress AppServer.)
Indicates whether you want the logic to run asynchronously.
HANDLE
(Applies only when ASYNCHRONOUS is TRUE.)
A handle to an asynchronous-request object containing detailed information on your asynchronous request.
Set by INVOKE() when ASYNCHRONOUS is TRUE.
CHARACTER
The name of one of the following:
  • A procedure or user-defined function you want to invoke dynamically
  • An attribute or you want to get or set dynamically
  • A method you want to invoke dynamically
INTEGER
Whether you are dynamically:
  • Invoking a procedure
  • Invoking a user-defined function
  • Getting an attribute or invoking a method
  • Setting an attribute
CHARACTER
(Applies only when ASYNCHRONOUS is TRUE.)
The name of an internal procedure you want executed when a dynamic, asynchronous invoke returns.

NOTE: You must set EVENT-
PROCEDURE before you run INVOKE().

HANDLE
(Applies only when ASYNCHRONOUS is TRUE.)
A handle to a running persistent procedure containing an internal procedure you want executed when a dynamic, asynchronous invoke returns.
HANDLE
Contains one of the following:
  • A handle to a persistent procedure you just invoked dynamically
  • A handle to an already-running persistent procedure containing logic you want to invoke dynamically
  • A handle to an object whose attributes or methods you want to invoke dynamically
LOGICAL
Whether you have already set a particular parameter.
INTEGER
The number of parameters you are passing.
LOGICAL
Whether you want an external procedure you plan to invoke dynamically to run persistently.
RETURN-
VALUE-
DATA-TYPE
(Applies only to user-defined functions, attributes, and methods)
One of the following:
  • The value returned by a user-defined function
  • The value of an attribute
  • The value returned by a method
CHARACTER
(Applies only to user-defined functions, attributes, and methods)
The data type of the return value.
If you set this before you execute INVOKE(), the return value is converted to this data type.
If you do not set this before you execute INVOKE(), it indicates the return value’s data type.
HANDLE
A handle to an AppServer containing logic you want to invoke dynamically.

method

A method of the CALL object. The methods let you set parameters, reset attributes to their default values, and invoke the CALL object.

Table D–2 briefly describes each method.

Table D–2: CALL Object Methods 
Method
Return Type
Description
LOGICAL
Resets each attribute of the CALL object to its default value.

NOTE: To reset just the parameters, set the NUM-PARAMETERS attribute to zero.

None
(similar to the RUN statement)
Lets you dynamically do the following:
  • Invoke an external procedure, internal procedure, or user-defined function
  • Get or set an attribute
  • Invoke a method

NOTE: INVOKE() cannot occur within an expression.

LOGICAL
Lets you set parameters of one of the following:
  • A procedure or user-defined function you want to invoke dynamically
  • An attribute you want to get or set dynamically
  • A method you want to invoke dynamically

EXAMPLES

The following fragment dynamically invokes an external procedure nonpersistently:

:

DEFINE VARIABLE hCall AS HANDLE. 
CREATE CALL hCall. 
/*invoke hello.p nonpersistently */ 
hCall:CALL-NAME = "hello.p". 
hCall:NUM-PARAMETERS = 1. 
hCall:SET-PARAMETER( 1, "CHARACTER", "INPUT", "HELLO WORLD"). 
hCall:INVOKE. 
/* clean up */ 
DELETE OBJECT hCall. 

The following fragment dynamically invokes an external procedure persistently, then dynamically invokes one of its internal procedures:

DEFINE VARIABLE hCall AS HANDLE. 
  
CREATE CALL hCall. 
/*invoke persis.p persistently */ 
hCall:CALL-NAME = "persis.p". 
hCall:PERSISTENT = true. 
HCall:INVOKE. 
   /* IN-HANDLE is automatically set
     to the handle of the persistent procedure
  */
  
/* invoke internal-persis-proc in persis.p */ 
HCall:CALL-NAME = "internal-persis-proc". 
hCall:NUM-PARAMETERS = 1. 
hCall:SET-PARAMETER( 1, "INTEGER", "INPUT", 333). 
hCall:INVOKE. 
/* clean up */ 
DELETE PROCEDURE hCall:IN-HANDLE. 
DELETE OBJECT hCall. 

The following fragment uses a single CALL object handle multiple times:

DEFINE VARIABLE hCall AS HANDLE. 
  
CREATE CALL hCall. 
/*invoke hello.p nonpersistently */ 
hCall:CALL-NAME = "hello.p". 
hCall:NUM-PARAMETERS = 1. 
hCall:SET-PARAMETER( 1, "CHARACTER", "INPUT", "HELLO WORLD"). 
hCall:INVOKE. 
/* reset the CALL object handle */ 
hCall:CLEAR. 
/*invoke persis.p persistently */ 
hCall:CALL-NAME = "persis.p". 
hCall:PERSISTENT = true. 
HCall:INVOKE.   
   /* IN-HANDLE is automatically set
      to the handle of the persistent procedure
  */
                                          
/* invoke internal-persis-proc in persis.p 
HCall:CALL-NAME = "internal-persis-proc". 
hCall:NUM-PARAMETERS = 1. 
hCall:SET-PARAMETER( 1, "INTEGER", "INPUT", 333). 
hCall:INVOKE. 
/* clean up */ 
DELETE PROCEDURE hCall:IN-HANDLE. 
DELETE OBJECT hCall. 

The following fragment gets an attribute:

/* get title of frame */ 
hCall:IN-HANDLE = myframe_handle. 
HCALL:CALL-TYPE = GET-ATTR-CALL-TYPE. 
hCall:CALL-NAME = "TITLE". 
hCall:INVOKE. 
Mytitle = hCall:RETURN-VALUE. 

The following fragment sets an attribute:

/* set SESSION:NUMERIC-FORMAT to "european" */ 
hCall:IN-HANDLE = "session". 
HCALL:CALL-TYPE = SET-ATTR-CALL-TYPE. 
hCall:CALL-NAME = "numeric-format". 
hCall:NUM-PARAMETERS = 1. 
hCall:SET-PARAMETER( 1, "CHAR", "INPUT", "european"). 
hCall:INVOKE. 

The following fragment drives the INVOKE() from a TEMP-TABLE:

/*suppose hRuntt is a temp-table that has one record with the 
following fields: 
   parm_1 
   parm_2 
   ... 
   parm_n 
   run-name 
   nparms 
   datatypes, extent nparms 
   iomodes, extent nparms 
*/ 
DEFINE INPUT PARAMETER TABLE-HANDLE hRuntt. 
DEFINE VARIABLE hDtypes  AS HANDLE. 
DEFINE VARIABLE hIOmodes AS HANDLE. 
DEFINE VARIABLE hCall    AS HANDLE. 
DEFINE VARIABLE i        AS INTEGER. 
hDtypes  = hRuntt:BUFFER-FIELD("datatypes"). 
hIOmodes = hRuntt:BUFFER-FIELD("iOmodes"). 
hRuntt:FIND-FIRST. 
CREATE CALL hCall. 
hCall:CALL-NAME = hRuntt:BUFFER-FIELD("run-name"):BUFFER-VALUE. 
hCall:NUM-PARAMETERS = hRuntt:BUFFER-FIELD("nparms"):BUFFER-VALUE. 
FOR i = 1 to hCall:NUM-PARAMETERS. 
    hCall:SET-PARAMETER( i, 
           hDtypes:BUFFER-VALUE(i), 
           hIOmodes:BUFFER-VALUE(i), 
           hRuntt:BUFFER-FIELD(i):BUFFER-VALUE). 
END. 
hCall:INVOKE. 
DELETE OBJECT hCall. 
/* if there are output parms,
    get the values from hRuntt:BUFFER-FIELD(i)
*/ 

NOTES

SEE ALSO

RUN Statement in the Progress Language Reference .


Copyright © 2004 Progress Software Corporation
www.progress.com
Voice: (781) 280-4000
Fax: (781) 280-4095