Syntax
for calling PowerBuilder functions and events
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
|
1 |
{ 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 If For system or global functions, omit For the rules PowerBuilder uses to find |
|
type (optional) |
A keyword specifying whether you are calling a
|
|
calltype (optional) |
A keyword specifying when PowerBuilder looks for the
For more information about static versus |
|
when (optional) |
A keyword specifying whether the function or event
For more about triggering and posting, see |
|
name |
The name of the function or event you want to |
|
argumentlist (optional) |
The values you want to pass to name. Each value in |
Usage
Function and event names are not case sensitive. For example, the
following three statements are equivalent:
|
1 2 3 |
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:
|
1 |
charnum = Asc("x") |
This statement calls the DataWindow function in a script that
belongs to the DataWindow:
|
1 |
Update( ) |
This statement calls the global user-defined function
gf_setup_appl:
|
1 |
gf_setup_appl(24, "Window1") |
This statement calls the system function PrintRect:
|
1 |
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:
|
1 |
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:
|
1 |
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:
|
1 2 |
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:
|
1 |
This.EVENT DoubleClicked(xpos, ypos, row, dwo) |
This statement posts the same event:
|
1 |
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:
|
1 |
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:
|
1 |
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.