Opens a sheet within an MDI (multiple document interface) frame window and creates a menu item for selecting the sheet on the specified menu, as OpenSheet does. OpenSheetWithParm also stores a parameter in the system’s Message object so that it is accessible to the opened sheet.
Window objects
OpenSheetWithParm ( sheetrefvar, parameter {, windowtype }, mdiframe
{, position {, arrangeopen } } )
Argument |
Description |
|---|---|
sheetrefvar |
The name of any window variable that is not an MDI frame window. OpenSheetWithParm places a reference to the open sheet in sheetrefvar. |
parameter |
The parameter you want to store in the Message object when the sheet is opened. Parameter must have one of these datatypes:
|
windowtype (optional) |
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 sheetrefvar. |
mdiframe |
The name of the MDI frame window in which you want to open this sheet. |
position (optional) |
The number of the menu item (in the menu associated with the sheet) to which you want to append the names of the open sheets. Menu bar menu items are numbered from the left, beginning with 1. The default is to list the open sheets under the next-to-last menu item. |
arrangeopen (optional) |
A value of the ArrangeOpen enumerated datatype specifying how you want the sheets arranged in the MDI frame when they are opened:
|
Integer. Returns 1 if it succeeds and -1 if an error occurs. If any argument’s value is null, OpenSheetWithParm returns null. In some cases, such as if the windowtype argument is invalid, OpenSheetWithParm throws a runtime error and does not return a value; therefore, it is recommended that you both test the return value and wrap the function call in a try-catch block as shown in the first example in the Examples section.
The system Message object has three properties for storing data. Depending on the datatype of the parameter specified for OpenSheetWithParm, scripts for the opened sheet 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 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.
See the usage notes for OpenSheet, which also apply to OpenSheetWithParm.
This example opens the sheet w_child_1 in
the MDI frame MDI_User in its original
size and stores MA in message.StringParm.
It appends the names of the open sheet to the second menu item in
the menu bar of MDI_User (the menu associated
with w_child_1). OpenSheetWithParm might
return -1 or throw a runtime error if the call fails. To ensure
that both of these possibilities are trapped, this example checks
the return value of the function and uses a try-catch statement
to catch a possible runtime error:
integer li_return
try
li_return = OpenSheetWithParm(w_child_1, "MA", &
MDI_User, 2, Original!)
if IsNull(li_return) then
MessageBox ("Failure", "Null argument provided")
elseif li_return= 1 then
MessageBox ("Success", "Sheet opened.")
else
MessageBox ("Failure", "Sheet open failed.")
end if
catch (runtimeerror rt)
Messagebox("Failure", "Sheet open failed. " &
+ rt.getmessage()) //Handle the error
end try
The next example illustrates how to access parameters passed in the Message object. These statements are in the scripts for two different windows. The script for the first window declares child as a window and opens an instance of w_child_1 as an MDI sheet. The name of the sheet is appended to the fourth menu item associated with w_child_1 and is layered.
The script also passes a reference to the SingleLineEdit control sle_state as a PowerObject parameter of the Message object. The script for the Open event of w_child_1 uses the text in the edit control to determine what type of calculations to perform. Note that this would fail if sle_state no longer existed when the second script refers to it. As an alternative, you could pass the text itself, which would be stored in the String parameter of Message.
The second script determines the text in the SingleLineEdit and performs processing based on that text.
The script for the first window is:
window child
OpenSheetWithParm(child, sle_state, &
"w_child_1", MDI_User, 4, Layered!)
The second script, for the Open event in w_child_1, is:
SingleLineEdit sle_state
sle_state = Message.PowerObjectParm
IF sle_state.Text = "overtime" THEN
... // overtime hours calculations
ELSEIF sle_state.Text = "vacation" THEN
... // vacation processing
ELSEIF sle_state.Text = "standard" THEN
... // standard hours calculations
END IF
