GetChild
method (DataWindows)
Description
Provides a reference to a child DataWindow or to a report in a
composite DataWindow, which you can use in DataWindow functions to
manipulate that DataWindow or report.
Applies to
|
DataWindow type |
Method applies to |
|---|---|
|
PowerBuilder |
DataWindow control, DataStore object |
Syntax
PowerBuilder
|
1 |
integer dwcontrol.GetChild (string name, REF DataWindowChild dwchildvariable ) |
|
Argument |
Description |
|---|---|
|
dwcontrol |
A reference to the DataWindow control or DataStore |
|
name |
A string that names the column containing the child |
|
dwchildvariable |
A variable in which you want to store the reference |
Return value
Returns 1 if it succeeds and -1 if an error occurs — for example,
if the child object does not exist.
If any argument is null, in PowerBuilder and JavaScript the method
returns null.
Usage
A child DataWindow is a DropDownDataWindow in a DataWindow
object.
A report is a DataWindow that is part of a composite DataWindow. A
report is read-only. When you define the composite DataWindow in the
DataWindow painter, each report is given a name. You can see the name in
the Name option of the Properties view. You must use the report name (not
the name of the DataWindow object in which the report has been placed)
when calling GetChild.
Use GetChild when you need to explicitly retrieve data for a child
DataWindow or report. Although PowerBuilder automatically retrieves data
for the child or report when the main DataWindow is displayed, you need to
explicitly retrieve data when there are retrieval arguments or when
conditions change and you want to retrieve new rows.
When you insert a row or retrieve data in the main DataWindow,
PowerBuilder automatically retrieves data for the child DataWindow. If the
child DataWindow has retrieval arguments, PowerBuilder displays a dialog
box asking the user for values for those arguments. To suppress the dialog
box, you can explicitly retrieve data for the child before changing the
main DataWindow (see the example).
Nested reports
You cannot use GetChild to get a reference to a report in a
composite DataWindow when the report itself is a composite or nested
DataWindow.
Changing property values with the Modify method can cause the
reference returned by GetChild to become invalid. After setting such a
property, call GetChild again. If a property causes this behavior, this is
noted in its description in DataWindow Object Properties
Examples
This example retrieves data for the child DataWindow associated with
the column emp_state before retrieving data in the main DataWindow. The
child DataWindow expects a region value as a retrieval argument. Because
you populate the child DataWindow first, specifying a value for its
retrieval argument, there is no need for PowerBuilder to display the
retrieval argument dialog box:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 |
DataWindowChild state_child integer rtncode rtncode = dw_1.GetChild('emp_state', state_child) IF rtncode = -1 THEN MessageBox( & "Error", "Not a DataWindowChild") // Establish the connection CONNECT USING SQLCA; // Set the transaction object for the child state_child.SetTransObject(SQLCA) // Populate with values for eastern states state_child.Retrieve("East") // Set transaction object for main DW and retrieve dw_1.SetTransObject(SQLCA) dw_1.Retrieve() |
In a composite DataWindow there are two reports: orders and current
inventory. The orders report has a retrieval argument for selecting the
order status. This report displays open orders. The composite DataWindow
is displayed in a DataWindow control called dw_news and the reports are
named open_orders and current_inv. The following code in the Open event of
the window that contains dw_news provides a retrieval argument for
open_orders:
|
1 2 3 4 |
DataWindowChild dwc_orders dw_news.GetChild("open_orders", dwc_orders) dwc_orders.SetTransObject(SQLCA) dwc_orders.Retrieve("open") |
See also