FindGroupChange

Description

Searches for the next break for the specified group. A group break occurs when the value in the column for the group changes. FindGroupChange reports the row that begins the next section.

Applies to

DataWindow type

Method applies to

PowerBuilder

DataWindow control, DataStore object


Syntax

PowerBuilder

long dwcontrol.FindGroupChange ( long row, integer level ) 

Argument

Description

dwcontrol

A reference to a DataWindow control or the DataStore.

row

A value identifying the row at which you want to begin searching for the group break.

level

The number of the group for which you are searching. Groups are numbered in the order in which you defined them.


Return value

Returns the number of the row whose group column has a new value, meaning that it begins a new group. Returns 0 if the value in the group column did not change and a negative number if an error occurs.

If any argument's value is null, in PowerBuilder and JavaScript the method returns null.

The return value observes these rules based on the value of row. If the starting row is:

  • The first row in a group, then FindGroupChange returns the starting row number

  • A row within a group, other than the last group, then FindGroupChange returns the row number of the first row of the next group

  • A row in the last group, other than the first row of the last group, then FindGroupChange returns 0

Usage

If the starting row begins a new section at the specified level, then that row is the one returned. To continue searching for subsequent breaks, increment the starting row so that the search resumes with the second row in the group.

Examples

This statement searches for the first break in group 2 in dw_regions. The search begins in row 5:

dw_regions.FindGroupChange(5, 2)

This code finds the number of the row at which a break occurs in group 1. It then checks whether the department number is 121. The search begins at row 0:

boolean lb_found
long ll_breakrow
 
lb_found = false
ll_breakrow = 0
 
DO WHILE NOT (lb_found)
   ll_breakrow = dw_1.FindGroupChange(ll_breakrow, 1)
 
   // If no breaks are found, exit.
   IF ll_breakrow <= 0 THEN EXIT
 
   // Have we found the section for Dept 121?
   IF dw_1.GetItemNumber(ll_breakrow, &
      "dept_id") = 121 THEN
         lb_found = true
   END IF
 
   // Increment starting row to find next break
   ll_breakrow = ll_breakrow + 1
LOOP
 
IF lb_found = false THEN
   MessageBox( &
      "Not Found", &
      "The Department was not found.")
ELSE
      ... // Processing for Dept 121
END IF

See also

Find

FindRequired