In PowerBuilder, arguments for built-in or user-defined functions and events can be passed three ways:
|
Method of passing |
Description |
|---|---|
|
By value |
A copy of the variable is available in the function or event script. Any changes to its value affect the copy only. The original variable in the calling script is not affected. |
|
By reference |
A pointer to the variable is passed to the function or event script. Changes affect the original variable in the calling script. |
|
Read-only |
The variable is available in the function or event. Its value is treated as a constant changes to the variable are not allowed and cause a compiler error. Read-only provides a performance advantage for some datatypes because it does not create a copy of the data, as with by value. Datatypes for which read-only provides a performance advantage are string, blob, date, time, and DateTime. For other datatypes, read-only provides documentation for other developers by indicating something about the purpose of the argument. |
When you pass an object to a function or event, the object must exist when you refer to its properties and functions. If you call the function but the object has been destroyed, you get the execution error for a null object reference. This is true whether you pass by reference, by value, or read-only.
To illustrate, suppose you have a window with a SingleLineEdit. If you post a function in the window's Close event and pass the SingleLineEdit, the object does not exist when the function executes. To use information from the SingleLineEdit, you must pass the information itself, such as the object's text, rather than the object. When passing an object, you never get another copy of the object. By reference and by value affect the object reference, not the object itself.
Objects passed by value
When you pass an object by value, you pass a copy of the reference to the object. That reference is still pointing to the original object. If you change properties of the object, you are changing the original object. However, you can change the value of the variable so that it points to another object without affecting the original variable.
Objects passed by reference
When you pass an object by reference, you pass a pointer to the original reference to the object. Again, if you change properties of the object, you are changing the original object. You can change the value of the variable that was passed, but the result is different -- the original reference now points to the new object.
Objects passed as read-only
When you pass an object as read-only, you get a copy of the reference to the object. You cannot change the reference to point to a new object (because read-only is equivalent to a CONSTANT declaration), but you can change properties of the object.
Structures as arguments behave like simple variables, not like objects.
Structures passed by value
When you pass a structure by value, PowerBuilder passes a copy of the structure. You can modify the copy without affecting the original.
Structures passed by reference
When you pass a structure by reference, PowerBuilder passes a reference to the structure. When you changes values in the structure, you are modifying the original. You will not get a null object reference, because structures always exist until they go out of scope.
Structures passed as read-only
When you pass a structure as read-only, PowerBuilder passes a copy of the structure. You cannot modify any members of the structure.
When an argument is an array, you specify brackets as part of the argument name in the declaration for the function or event.
Variable-size array as an argument
For example, suppose a function named uf_convertarray accepts a variable-size array of integers. If the argument's name is intarray, then for Name enter intarray[ ] and for Type enter integer.
In the script that calls the function, you either declare an array variable or use an instance variable or value that has been passed to you. The declaration of that variable, wherever it is, looks like this:
integer a[]
When you call the function, omit the brackets, because you are passing the whole array. If you specified brackets, you would be passing one value from the array:
uf_convertarray(a)
Fixed-size array as an argument
For comparison, suppose the uf_convertarray function accepts a fixed-size array of integers of 10 elements instead. If the argument's name is intarray, then for Name enter intarray[10], and for Type enter integer.
The declaration of the variable to be passed looks like this:
integer a[10]
You call the function the same way, without brackets:
uf_convertarray(a)
If the array dimensions do not match
If the dimensions of the array variable passed do not match the dimensions declared for the array argument, then array-to-array assignment rules apply. For more information, see Declaring arrays.
