OpenWithParm

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.

To

Use

Open an instance of a particular window datatype

Syntax 1

Allow the application to select the window's datatype when the script is executed

Syntax 2


Syntax 1: For windows of a known datatype

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:

  • String

  • Numeric

  • PowerObject

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

CloseWithReturn

Open

Syntax 2: For windows of unknown datatype

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:

  • String

  • Numeric

  • PowerObject

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

CloseWithReturn

Open