OpenSheetWithParm PowerScript function
Description
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.
Controls
Window objects
Syntax
|
1 |
<span>OpenSheetWithParm</span> ( <span>sheetrefvar</span>, <span>parameter</span> {, <span>windowtype</span> }, <span>mdiframe</span><br> {, <span>position</span> {, <span>arrangeopen</span> } } ) |
|
Argument |
Description |
|---|---|
|
sheetrefvar |
The name of any window variable that |
|
parameter |
The parameter you want to store in the
|
|
windowtype (optional) |
A string whose value is the datatype |
|
mdiframe |
The name of the MDI frame window in which |
|
position (optional) |
The number of the menu item (in the menu |
|
arrangeopen (optional) |
A value of the ArrangeOpen enumerated
|
Return Values
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.
Usage
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 |
|
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.
Opening response windows
Do not use the OpenSheetWithParm function
to open a response window.
See the usage notes for OpenSheet, which also
apply to OpenSheetWithParm.
Examples
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:
|
1 |
integer li_return<br>try<br>    li_return = <span>OpenSheetWithParm</span>(w_child_1, "MA", &<br>       MDI_User, 2, Original!)<br>   if IsNull(li_return) then<br>       MessageBox ("Failure", "Null argument provided")<br>   elseif li_return= 1 then<br>       MessageBox ("Success", "Sheet opened.")<br>   else<br>       MessageBox ("Failure", "Sheet open failed.")<br>   end if<br> <br>catch (runtimeerror rt)<br>   Messagebox("Failure", "Sheet open failed. " &<br>      + rt.getmessage()) //Handle the error<br>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:
|
1 |
window child |
|
1 |
<span>OpenSheetWithParm</span>(child, sle_state, & |
|
1 |
"w_child_1", MDI_User, 4, Layered!) |
The second script, for the Open event in w_child_1,
is:
|
1 |
SingleLineEdit sle_state |
|
1 |
sle_state = Message.PowerObjectParm |
|
1 |
IF sle_state.Text = "overtime" THEN |
|
1 |
... // overtime hours calculations |
|
1 |
ELSEIF sle_state.Text = "vacation" THEN |
|
1 |
... // vacation processing |
|
1 |
ELSEIF sle_state.Text = "standard" THEN |
|
1 |
... // standard hours calculations |
|
1 |
END IF |