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.
Applies to
Window objects
Syntax
|
1 |
OpenSheetWithParm ( sheetrefvar, parameter {, windowtype }, mdiframe {, position {, arrangeopen } } ) |
|
Argument |
Description |
|---|---|
|
sheetrefvar |
The name of any window variable that is not an MDI frame |
|
parameter |
The parameter you want to store in the Message object when
|
|
windowtype (optional) |
A string whose value is the datatype of the window you |
|
mdiframe |
The name of the MDI frame window in which you want to open |
|
position (optional) |
The number of the menu item (in the menu associated with |
|
arrangeopen (optional) |
A value of the ArrangeOpen enumerated datatype specifying
|
Return value
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 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 |
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:
|
1 2 3 |
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:
|
1 2 3 4 5 6 7 8 9 |
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 |
See also