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 |
{ <span>objectname</span>.} { <span>type</span> } { <span>calltype</span> } { <span>when</span> } <span>name</span> ( { <span>argumentlist</span> } ) |
The following table describes the arguments used in function
and event calls.
|
Argument |
Description |
|---|---|
|
objectname |
The name of the object where the function If a function name is not qualified, PowerBuilder uses the For system or global functions, omit objectname. For the rules PowerBuilder uses to find unqualified |
|
type |
A keyword specifying whether you are
|
|
calltype |
A keyword specifying when PowerBuilder
For more information about static versus dynamic |
|
when |
A keyword specifying whether the function
For more about triggering and posting, see “Triggering versus posting |
|
name |
The name of the function or event you |
|
argumentlist |
The values you want to pass to name. |
Usage
Function and event names are not case sensitive. For example,
the following three statements are equivalent:
|
1 |
Clipboard("PowerBuilder")<br>clipboard("PowerBuilder")<br>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 |
Parent.FUNCTION STATIC TRIGGER wf_process( ) |
|
1 |
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.