GetChild

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
Web ActiveX	DataWindow control

Syntax

PowerBuilder

integer dwcontrol.GetChild (string name, REF DataWindowChild dwchildvariable )

Web ActiveX

number dwcontrol.GetChild ( string name )

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.

Returns

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 3, “DataWindow Object Properties.”

Examples

Example 1

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()

Example 2

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")

Example 3

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

var  ls ;
var  ldwc;

window.dw_1.GetChild ("dept_id"); 
ldwc = window.dw_1.GetChildObject();
ls = ldwc.Describe ("Datawindow.Table.Select");
window.alert(ls);