Specifying Data with References Using Scroll Path Syntax and Dot Notation

This section provides an overview of scroll paths and discusses how to:

  • Structure scroll path syntax.

  • Reference scroll levels, rows, and buffer fields.

A scroll path is a construction found in the parameter lists of many component buffer functions, which specifies a scroll level in the currently active page. Additional parameters are required to locate a row or a buffer field at the specified scroll level.

Scroll path syntax enables you to eliminate ambiguous references, which, although rare, do sometimes occur in complex components.

See Using Contextual Buffer Field References.

PeopleTools also provides the convenience of object-oriented dot notation and default methods, which produce inherently non-ambiguous references from PeopleCode programs to component buffer data. There are examples of dot notation in this section along with examples of the legacy scroll path syntax.

PeopleTools offers two legacy constructions for scroll paths: a standard scroll path syntax (Record.recordname) and an alternative syntax using a Scroll.scrollname expression. The latter is more powerful in that it can process some rare cases where a Record.recordname expression results in an ambiguous reference.

Scroll Path Syntax with Record.recordname

Here is the standard scroll path syntax:

[Record.level1_recname, level1_row, [Record.level2_recname, level2_row, ]] Record.target_recname

If the target level (the level you want to reference) is one, you must supply only the Record.target_recname parameter. If the target scroll level is greater than one, you must provide scroll name and row level parameters for all hierarchically superior scroll levels, beginning at level one. The following table indicates the scroll path syntax for the three possible target scroll levels:

Target Level

Scroll Path Syntax

1

Record.target_recname

2

Record.level1_recname, level1_row, 
Record.target_recname

3

Record.level1_recname, level1_row, Record.level2_recname, level2_row, Record.target_recname

If you are referring to a row or a buffer field, additional parameters are required after the scroll path.

The following table describes the standard scroll path syntax parameters:

Syntax Parameters

Description

Record.level1_recname

Specifies the name of a record associated with scroll level one, normally the primary scroll record. This parameter is required if the target scroll level is two or three.

level1_row

An integer that selects a row on scroll level one. This parameter is required if the target scroll level is two or three.

Record.level2_recname

Specifies the name of a record associated with scroll level two, normally the primary scroll record. This parameter is required if the target row is on scroll level three.

level2_row

An integer that selects a row on scroll level two. This parameter is required if the target row is on scroll level three.

Record.target_recname

Specifies a record associated with the target scroll level, generally the primary scroll record. The scroll can be on level one, two, or three of the active page.

Scroll Path Syntax with Scroll.scrollname

As an alternative to Record.recordname expressions in scroll path constructions, PeopleTools permits use of a Scroll.scrollname expression. Scroll paths using Scroll.scrollname are functionally identical to those using Record.recordname, except that Scroll.scrollname expressions are more strict: they can refer only to a scroll level’s primary record; whereas Record.recordname expressions can refer to any record in the scroll level, which in some rare cases can result in ambiguous references. (This can occur, for example, if the Record.recordname expression inadvertently references a related display record in another page in the component.) Use of Record.recordname is still permitted, and there is no requirement to use the Scroll.scrollname alternative unless it is needed to avoid an ambiguous reference.

The scrollname is the same as the scroll level’s primary record name.

The scroll name cannot be viewed or changed through the PeopleSoft Application Designer interface. Here is the complete scroll path syntax using Scroll.scrollname expressions:

[Scroll.level1_scrollname, level1_row, [Scroll.level2_scrollname, level2_row, ]], Scroll.target_scrollname

The target scroll level in this construction is the scroll level that you want to specify. If the target level is one, you need to supply only the Scroll.target_scrollname parameter. If the target scroll level is greater than one, you need to provide scroll name and row-level parameters for hierarchically superior scroll levels, beginning at level one. The following table indicates the scroll path syntax for the three possible target scroll levels:

Target Level

Scroll Path Syntax

1

Scroll.target_scrollname

2

Scroll.level1_scrollname, level1_row, Scroll.target_scrollname

3

Scroll.level1_scrollname, level1_row, Scroll.level2_scrollname, level2_row, Scroll.target_scrollname

If the component you are referring to is a row or a buffer field, additional parameters are required after the scroll path.

The following table describes the alternative scroll path syntax parameters:

Parameter

Description

Scroll.level1_scrollname

Specifies the name of the page’s level-one scroll area. This is always the same as the name of the scroll level’s primary scroll record. This parameter is required if the target scroll level is two or three.

level1_row

An integer that selects a row on scroll level one. This parameter is required if the target scroll level is two or three.

Scroll.level2_scrollname

Specifies the name of the page’s level two scroll area. This is always the same as the name of the scroll level’s primary scroll record. This parameter is required if the target row is on scroll level three.

level2_row

An integer that selects a row on scroll level two. This parameter is required if the target row is on scroll level three.

Scroll.target_scrollname

The scroll name of the target scroll level, which can be level one, two, or three of the active page.

You can reference a scroll level using the scrollpath construct only. Functions that reference rows for buffer fields require additional parameters. The following table summarizes the three types of component buffer references:

Target Component

Reference Syntax

Example Function

Scroll level

scrollpath
HideScroll(scrollpath);

Row

scrollpath, row_number
HideRow(scrollpath, row_number);

Field

scrollpath, row_number,
[recordname.]fieldname
FetchValue(scrollpath, row_number, fieldname);

PeopleTools 8 provides an alternative to the scroll level, row, and field components in the form of the data buffer classes Rowset, Row, Record, and Field, which you reference using dot notation with object methods and properties. The following table demonstrates the syntax for instantiating and manipulating objects in the current context from these classes:

Target Object

Example Instantiation

Example Operation

Rowset

&MYROWSET = GetRowset();
&MYROWSET.Refresh();

Row

&MYROW = GetRow();
&MYROW.CopyTo(&SOMEROW);

Record

&MYRECORD = GetRecord();
&MYREC.CompareFields(&REC);

Field

&MYFIELD = GetRecord().
fieldname;
&MYFIELD.Label = "Last Name";

The following sections provide examples of functions using scroll path syntax, which refer to an example page from a fictitious veterinary clinic database. The page has three scroll levels, shown in the following table:

Level

Scroll Name (Primary Scroll Record Name)

0

VET

1

OWNER

2

PET

3

VISIT

The examples given for PeopleTools 8 object-oriented syntax assumes that the following initializing code was executed:

Local Rowset  &VET_SCROLL, &OWNER_SCROLL, &PET_SCROLL, &VISIT_SCROLL;

&VET_SCROLL = GetLevel0();
&OWNER_SCROLL = &VET_Scroll.GetRow(1).GetRowSet(Scroll.OWNER);
&PET_SCROLL = &OWNER_Scroll.GetRow(2).GetRowSet(Scroll.PET);
&VISIT_SCROLL = &PET_Scroll.GetRow(2).GetRowSet(Scroll.VISIT);

Referring to Scroll Levels

The HideScroll function provides an example of a reference to a scroll level. The syntax of the function is:

HideScroll(scrollpath)

where scrollpath is

[Record.level1_recname, level1_row, [Record.level2_recname, level2_row,]] Record.target_recname

To reference the level 1 scroll in the example, use this syntax:

HideScroll(Record.OWNER);

This hides the OWNER, PET, and VISIT scroll areas on the example page.

In PeopleTools 8, the object-oriented version of this is:

&OWNER_Scroll.HideAllRows();

To hide scroll levels two and below, supply the primary record and row in scroll level one, and then the record identifying the target scroll area:

HideScroll(Record.OWNER, &L1ROW, Record.PET);

Image: Sample scroll path

The following diagram shows the scroll path of this statement, assuming that the value of &L1ROW is 2:

Sample scroll path

Similarly, to hide the VISIT scroll area on level three, you specify rows on scroll levels one and two.

HideScroll(Record.OWNER, &L1ROW, Record.PET, &L2ROW, Record.VISIT);

To use the Scroll.scrollname syntax, the previous example could be written as the following:

HideScroll(Scroll.OWNER, &L1ROW, Scroll.PET, &L2ROW, Scroll.VISIT);

In PeopleTools 8, the object-oriented version of this is:

&VISIT_Scroll.HideAllRows();

Referring to Rows

Referring to rows is the same as referring to scroll areas, except that you need to specify the row you want to select on the target scroll area. As an example, examine the HideRow function, which hides a specific row in the level three scroll area of the page. Here is the function syntax:

HideRow(scrollpath, target_row)

To hide row number &ROW_NUM on level one:

HideRow(Record.OWNER, &ROW_NUM);

To do the same using the Scroll.scrollname syntax:

HideRow(Scroll.OWNER, &ROW_NUM);

In PeopleTools 8, the object-oriented version of this for the OWNER rowset is:

&OWNER_SCROLL(&ROW_NUM).Visible = False;

On level two:

HideRow(Record.OWNER, &L1_ROW), Record.PET, &ROW_NUM);

In PeopleTools 8, the object-oriented version of this for the PET rowset is:

&PET_SCROLL(&ROW_NUM).Visible = False;

Image: Scroll path statement

The following diagram indicates the scroll path of this statement, assuming that the value of &L1_ROW is 2 and that &ROW_NUM is equal to 2:

Scroll path statement

On level three:

HideRow(Record.OWNER, CurrentRowNumber(1), Record.PET, 
CurrentRowNumber(2), Record.VISIT, &ROW_NUM);

In PeopleTools 8, the object-oriented version of this for the VISIT rowset is:

&VISIT_SCROLL(&ROW_NUM).Visible = False;

Referring to Buffer Fields

Buffer field references require a [recordname.]fieldname parameter to specify a record field. The combination of scroll level, row number, and record field name uniquely identifies the buffer field. Here is the syntax:

 FetchValue(scrollpath, target_row, [recordname.]fieldname)

Assume, for example, that record definitions in the veterinary database have the following fields that you want to reference:

Record

Sample Field

OWNER

OWNER_NAME

PET

PET_BREED

VISIT

VISIT_REASON

You could use the following examples to retrieve values on levels one, two, or three from a PeopleCode program executing on level zero.

To fetch a value of the OWNER_NAME field on the current row of scroll area one:

&SOMENAME = FetchValue(Record.OWNER, &L1_ROW, OWNER.OWNER_NAME);

In PeopleTools 8, the object-oriented version of this for the OWNER rowset is:

&SOMENAME = &OWNER_SCROLL(&L1_ROW).OWNER.OWNER_NAME;

To fetch PET_BREED on level two:

&SOMEBREED = FetchValue(Record.OWNER, &L1_ROW, Record.PET, &L2_ROW, PET.PET_BREED);

In PeopleTools 8, the object-oriented version of this for the PET rowset is:

&SOMEBREED = &PET_SCROLL(&L2_ROW).PET.PET_BREED;

Image: Scroll path to target field

The following diagram indicates the scroll path to the target field, assuming that &L1_ROW equals 2, &L2_ROW equals 2, and field F3 is PET.PET_BREED.

Scroll path to target field

To fetch VISIT_REASON on level three:

&SOMEREASON = FetchValue(Record.OWNER, &L1_ROW, Record.PET, 
&L2_ROW, Record.VISIT, &L3_ROW, VISIT.VISIT_REASON);

To do the same using the Scroll.scrollname syntax:

&SOMEREASON = FetchValue(Scroll.OWNER, &L1_ROW, Scroll.PET, 
&L2_ROW, Scroll.VISIT, &L3_ROW, Scroll.VISIT_REASON);

In PeopleTools 8, the object-oriented version of this is:

&SOMEREASON = &VISIT_SCROLL(&L3_ROW).VISIT.VISIT_REASON;

Using CurrentRowNumber

The CurrentRowNumber function returns the current row, as determined by the current context, for a specific scroll level in the active page. CurrentRowNumber is often used to determine a value for the level1_row and level2_row parameters in scroll path constructions. Because current row numbers are determined by the current context, CurrentRowNumber cannot determine a current row on a scroll level outside the current context (a scroll level below the level where the PeopleCode program is currently executing).

For example, you could use a statement like this to retrieve the value of a buffer field on level three of the PET_VISITS page, in a PeopleCode program executing on level two:

&VAL = FetchValue(Record.OWNER, CurrentRowNumber(1), 
Record.PET, CurrentRowNumber(2), Record.VISIT, &TARGETROW, 
VISIT_REASON);

Because the PeopleCode program is executing on level two, CurrentRowNumber can return values for levels one and two, but not three, because level three is outside of the current context and has no current row number.

Looping Through Scroll Levels

Component buffer functions are often used in For loops to loop through the rows on scroll levels below the level where the PeopleCode program is executing. The following loop, for example could be used in PeopleCode executing on a level two record field to loop through rows of data on level three:

For &I = 1 To ActiveRowCount(Record.OWNER, 
CurrentRowNumber(1), Record.PET, CurrentRowNumber(2), Record.VISIT)
    &VAL = FetchValue(Record.OWNER, CurrentRowNumber(1), 
Record.PET, CurrentRowNumber(2), Record.VISIT, &I, VISIT_REASON);
   If &VAL = "Fleas" Then 
      /* do something about fleas */
   End-If;
End-For;

A similar construct may be used in accessing other level two or level one scroll areas, such as work scroll areas.

In these constructions, the ActiveRowCount function is often used to determine the upper bounds of the loop. When ActiveRowCount is used for this purpose, the loop goes through all of the active rows in the scroll (rows that have not been specified as deleted). If you use TotalRowCount to determine the upper bounds of the loop, the loop goes through all of the rows in the scroll area: first those that have not been specified as deleted, then those that have been specified as deleted.