Displays a window and makes all its properties and controls available to scripts, as Open does. OpenWithParm also stores a parameter in the system's Message object so that it is accessible to the opened window.
Description
Opens a window object of a known datatype. OpenWithParm displays the window and makes all its properties and controls available to scripts. It also stores a parameter in the system's Message object.
Applies to
Window objects
Syntax
OpenWithParm ( windowvar, parameter {, parent } )
|
Argument |
Description |
|---|---|
|
windowvar |
The name of the window you want to display. You can specify a window object defined in the Window painter (which is a window datatype) or a variable of the desired window datatype. OpenWithParm places a reference to the open window in windowvar. |
|
parameter |
The parameter you want to store in the Message object when the window is opened. Parameter must have one of these datatypes:
|
|
parent (child and pop-up windows only) (optional) |
The window you want make the parent of the child or pop-up window you are opening. If you open a child or pop-up window and omit parent, PowerBuilder associates the window being opened with the currently active window. |
Return value
Integer. Returns 1 if it succeeds and -1 if an error occurs. If any argument's value is null, OpenWithParm returns null.
Usage
The system Message object has three properties for storing data. Depending on the datatype of the parameter specified for OpenWithParm, your scripts for the opened window would check one of the following properties.
|
Message object property |
Argument datatype |
|---|---|
|
Message.DoubleParm |
Numeric |
|
Message.PowerObjectParm |
PowerObject (PowerBuilder objects, including user-defined structures) |
|
Message.StringParm |
String |
In the opened window, it is a good idea to access the value passed in the Message object immediately because some other script may use the Message object for another purpose.
Avoiding null object references
When you pass a PowerObject as a parameter, you are passing a reference to the object. The object must exist when you refer to it later or you will get a null object reference, which causes an error. For example, if you pass the name of a control on a window that is being closed, that control will not exist when a script accesses the parameter.
Passing several values as a structure
To pass several values, create a user-defined structure to hold the values and access the PowerObjectParm property of the Message object in the opened window. The structure is passed by value, not by reference, so you can access the information even if the original structure has been destroyed.
See also the usage notes for Open, all of which apply to OpenWithParm.
Examples
This statement opens an instance of a window named w_employee and stores the string parameter in Message.StringParm. The script for the window's Open event uses the string parameter as the text of a StaticText control st_empname. The script that opens the window has the following statement:
OpenWithParm(w_employee, "James Newton")
The window's Open event script has the following statement:
st_empname.Text = Message.StringParm
The following statements open an instance of a window of the type w_employee. Since the parameter is a number it is stored in Message.DoubleParm:
w_employee w_to_open integer age = 50 OpenWithParm(w_to_open, age)
The following statement opens an instance of a child window named cw_data and makes w_employee the parent. The window w_employee must already be open. The parameter benefit_plan is a string and is stored in Message.StringParm:
OpenWithParm(cw_data, "benefit_plan", w_employee)
See also
Description
Opens a window object when you do not know its datatype until the application is running. OpenWithParm displays the window and makes all its properties and controls available to scripts. It also stores a parameter in the system's Message object.
Applies to
Window objects
Syntax
OpenWithParm ( windowvar, parameter, windowtype {, parent } )
|
Argument |
Description |
|---|---|
|
windowvar |
A window variable, usually of datatype window. OpenWithParm places a reference to the open window in windowvar. |
|
parameter |
The parameter you want to store in the Message object when the window is opened. Parameter must have one of these datatypes:
|
|
windowtype |
A string whose value is the datatype of the window you want to open. The datatype of windowtype must be the same or a descendant of windowvar. |
|
parent (child and pop-up windows only) |
The window you want to make the parent of the child or pop-up window you are opening. If you open a child or pop-up window and omit parent, PowerBuilder associates the window being opened with the currently active window. |
Return value
Integer. Returns 1 if it succeeds and -1 if an error occurs. If any argument's value is null, OpenWithParm returns null.
Usage
The system Message object has three properties for storing data. Depending on the datatype of the parameter specified for OpenWithParm, your scripts for the opened window would check one of the following properties.
|
Message object property |
Argument datatype |
|---|---|
|
Message.DoubleParm |
Numeric |
|
Message.PowerObjectParm |
PowerObject (PowerBuilder objects, including user-defined structures) |
|
Message.StringParm |
String |
In the opened window, it is a good idea to access the value passed in the Message object immediately because some other script may use the Message object for another purpose.
Avoiding null object references
When you pass a PowerObject as a parameter, you are passing a reference to the object. The object must exist when you refer to it later or you will get a null object reference, which causes an error. For example, if you pass the name of a control on a window that is being closed, that control will not exist when a script accesses the parameter.
Passing several values as a structure
To pass several values, create a user-defined structure to hold the values and access the PowerObjectParm property of the Message object in the opened window. The structure is passed by value, not by reference, so you can access the information even if the original structure has been destroyed.
See also the usage notes for Open, all of which apply to OpenWithParm.
Examples
These statements open a window of the type specified in the string s_w_name and store the reference to the window in the variable w_to_open. The script gets the value of s_w_name, the type of window to open, from the database. The parameter in e_location is text, so it is stored in Message.StringParm:
window w_to_open string s_w_name, e_location e_location = sle_location.Text SELECT next_window INTO :s_w_name FROM routing_table WHERE ... ; OpenWithParm(w_to_open, e_location, s_w_name)
The following statements open a window of the type specified in the string c_w_name, store the reference to the window in the variable wc_to_open, and make w_emp the parent window of wc_to_open. The parameter is numeric, so it is stored in Message.DoubleParm:
window wc_to_open string c_w_name integer age = 60 c_w_name = "w_c_emp1" OpenWithParm(wc_to_open, age, c_w_name, w_emp)
See also
