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
Syntax
PowerBuilder
integer dwcontrol.GetChild (string name, REF DataWindowChild dwchildvariable )
|
Argument |
Description |
|---|---|
|
dwcontrol |
A reference to the DataWindow control or DataStore that contains the child DataWindow or report. |
|
name |
A string that names the column containing the child DataWindow or that names the report in the composite DataWindow. |
|
dwchildvariable |
A variable in which you want to store the reference to the child DataWindow or report. |
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:
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:
DataWindowChild dwc_orders
dw_news.GetChild("open_orders", dwc_orders)
dwc_orders.SetTransObject(SQLCA)
dwc_orders.Retrieve("open")See also
