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.

Controls

DataWindow type	Method applies to
PowerBuilder	DataWindow control, DataStore object
Web ActiveX	DataWindow control

Syntax

[PowerBuilder]

integer <span>dwcontrol</span>.<span>GetChild</span> (string <span>name</span>, REF DataWindowChild <span>dwchildvariable</span> )

1	integer <span>dwcontrol</span>.<span>GetChild</span> (string <span>name</span>, REF DataWindowChild <span>dwchildvariable</span> )

[Web ActiveX]

number <span>dwcontrol</span>.<span>GetChild</span> ( string <span>name</span> )

1	number <span>dwcontrol</span>.<span>GetChild</span> ( string <span>name</span> )

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. For the Web ActiveX, the separate function GetChildObject must be called to get the reference variable to the child object.

Return Values

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 Chapter
38, “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

1	DataWindowChild state_child

integer rtncode

1	integer rtncode

rtncode = dw_1.<span>GetChild</span>(<span>'</span>emp_state', state_child)

1	rtncode = dw_1.<span>GetChild</span>(<span>'</span>emp_state', state_child)

IF rtncode = -1 THEN MessageBox( &amp;

1	IF rtncode = -1 THEN MessageBox( &

        "Error", "Not a DataWindowChild")

1	"Error", "Not a DataWindowChild")

// Establish the connection

1	// Establish the connection

CONNECT USING SQLCA;

1	CONNECT USING SQLCA;

// Set the transaction object for the child

1	// Set the transaction object for the child

state_child.SetTransObject(SQLCA)

1	state_child.SetTransObject(SQLCA)

// Populate with values for eastern states

1	// Populate with values for eastern states

state_child.Retrieve("East")

1	state_child.Retrieve("East")

// Set transaction object for main DW and retrieve

1	// Set transaction object for main DW and retrieve

dw_1.SetTransObject(SQLCA)

1	dw_1.SetTransObject(SQLCA)

dw_1.Retrieve()

1	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

1	DataWindowChild dwc_orders

dw_news.<span>GetChild</span>("open_orders", dwc_orders)

1	dw_news.<span>GetChild</span>("open_orders", dwc_orders)

dwc_orders.SetTransObject(SQLCA)

1	dwc_orders.SetTransObject(SQLCA)

dwc_orders.Retrieve("open")

1	dwc_orders.Retrieve("open")

The following example for the Web ActiveX displays
the reference to the child object in a message box:

var  ls ;<br>var  ldwc;<br>

1	var ls ;<br>var ldwc;<br>

window.dw_1.<span>GetChild</span> ("dept_id"); <br>ldwc = window.dw_1.GetChildObject();<br>ls = ldwc.Describe ("Datawindow.Table.Select");<br>window.alert(ls);

1	window.dw_1.<span>GetChild</span> ("dept_id"); <br>ldwc = window.dw_1.GetChildObject();<br>ls = ldwc.Describe ("Datawindow.Table.Select");<br>window.alert(ls);

GetChild – PB Docs 126