Description
This syntax is used to call all PowerBuilder functions and events. Depending on the keywords used, this syntax can be used to call system, global, object, user-defined, and external functions as well as system and user-defined events.
Syntax
{ objectname.} { type } { calltype } { when } name ( { argumentlist } )The following table describes the arguments used in function and event calls.
|
Argument |
Description |
|---|---|
|
objectname (optional) |
The name of the object where the function or event is defined followed by a period or the descendant of that object/the name of the ancestor class followed by two colons. If a function name is not qualified, PowerBuilder uses the rules for finding functions and executes the first matching function it finds. For system or global functions, omit objectname. For the rules PowerBuilder uses to find unqualified function names, see Finding and executing functions and events. |
|
type (optional) |
A keyword specifying whether you are calling a function or event. Values are:
|
|
calltype (optional) |
A keyword specifying when PowerBuilder looks for the function or event. Values are:
For more information about static versus dynamic calls, see Static versus dynamic calls. For more information on dynamic calls, see Dynamic calls. |
|
when (optional) |
A keyword specifying whether the function or event should execute immediately or after the current script is finished. Values are:
For more about triggering and posting, see Triggering versus posting functions and events. |
|
name |
The name of the function or event you want to call. |
|
argumentlist (optional) |
The values you want to pass to name. Each value in the list must have a datatype that corresponds to the declared datatype in the function or event definition or declaration. |
Usage
Function and event names are not case sensitive. For example, the following three statements are equivalent:
Clipboard("PowerBuilder")
clipboard("PowerBuilder")
CLIPBOARD("PowerBuilder")Calling arguments
The type, calltype, and when keywords can be in any order after objectname.
Not all options in the syntax apply to all types. For example, there is no point in calling a system PowerScript object function dynamically. It always exists, and the dynamic call incurs extra overhead. However, if you had a user-defined function of the same name that applied to a different object, you might call that function dynamically.
User-defined global functions and system functions can be triggered or posted but they cannot be called dynamically.
Finding functions
If a global function does not exist with the given name, PowerBuilder will look for an object function that matches the name and argument list before it looks for a PowerBuilder system function.
Calling functions and events in the ancestor
If you want to circumvent the usual search order and force PowerBuilder to find a function or event in an ancestor object, bypassing it in the descendant, use the ancestor operator (::).
For more information about the scope operator for ancestors, see Calling functions and events in an object's ancestor.
Cascaded calls
Calls can be cascaded using dot notation. Each function or event call must return an object type that is the appropriate object for the following call.
For more information about cascaded calls, see Using cascaded calling and return values.
Using return values
If the function has a return value, you can call the function on the right side of an assignment statement, as an argument for another function, or as an operand in an expression.
External functions
Before you can call an external function, you must declare it. For information about declaring external functions, see Declaring external functions.
Examples
Example 1
The following statements show various function calls using the most simple construction of the function call syntax.
This statement calls the system function Asc:
charnum = Asc("x")This statement calls the DataWindow function in a script that belongs to the DataWindow:
Update( )
This statement calls the global user-defined function gf_setup_appl:
gf_setup_appl(24, "Window1")
This statement calls the system function PrintRect:
PrintRect(job, 250, 250, 7500, 1000, 50)
Example 2
The following statements show calls to global and system functions.
This statement posts the global user-defined function gf_setup_appl. The function is executed when the calling script finishes:
POST gf_setup_appl(24, "Window1")
This statement posts the system function PrintRect. It is executed when the calling script finishes. The print job specified in job must still be open:
POST PrintRect(job, 250, 250, 7500, 1000, 50)
Example 3
In a script for a control, these statements call a user-defined function defined in the parent window. The statements are equivalent, because FUNCTION, STATIC, and TRIGGER are the defaults:
Parent.FUNCTION STATIC TRIGGER wf_process( ) Parent.wf_process( )
Example 4
This statement in a DataWindow control's Clicked script calls the DoubleClicked event for the same control. The arguments the system passed to Clicked are passed on to DoubleClicked. When triggered by the system, PowerBuilder passes DoubleClicked those same arguments:
This.EVENT DoubleClicked(xpos, ypos, row, dwo)
This statement posts the same event:
This.EVENT POST DoubleClicked(xpos, ypos, row, dwo)
Example 5
The variable iw_a is an instance variable of an ancestor window type w_ancestorsheet:
w_ancestorsheet iw_a
A menu has a script that calls the wf_export function, but that function is not defined in the ancestor. The DYNAMIC keyword is required so that the script compiles:
iw_a.DYNAMIC wf_export( )
At execution time, the window that is opened is a descendant with a definition of wf_export. That window is assigned to the variable iw_a and the call to wf_export succeeds.
