Referencing Data in the Component Buffer

This chapter provides an overview of component buffer structure and contents and discusses how to:

• Specify data with contextual references.

• Specify data with references using scroll path syntax and dot notation.

Understanding Component Buffer Structure and Contents

This section discusses:

• Component buffer contents.

• Rowsets and scroll areas.

• Record fields in the component buffer.

See Also

Specifying Data with References Using Scroll Path Syntax and Dot Notation

Component Buffer Contents

PeopleCode frequently must refer to data in the component buffer, the area in memory that stores data for the currently active component.

The two methods for specifying a piece of data in the component buffer from within PeopleCode are:

• Contextual references, which refer to data relative to the location of the currently executing PeopleCode program.

• References using scroll path syntax, which provide a complete, or absolute, path through the component buffer to the referenced component.

In addition to the built-in functions used to access the component buffer, PeopleCode provides enhanced access to structured data buffers using the object syntax. Use the object-oriented PeopleCode to resolve contextual ambiguities when you reference a nonprimary record field that appears on more than one scroll level in a component. As with built-in functions, object syntax provides for both relative and absolute references to component buffer data.

See Understanding Objects and Classes in PeopleCode.

The component buffer consists of rows of buffer fields that hold data for the records associated with page controls, including primary scroll records, related display records, derived/work records, and Translate table records. PeopleCode can reference buffer fields associated with page controls and other buffer fields from the primary scroll record and related display records.

See Record Fields and the Component Buffer.

Primary scroll records are the principal SQL tables or views associated with page scroll levels. A primary scroll record uniquely identifies a scroll level in the context of its page: each scroll level can have only one primary scroll record, and the same primary scroll record cannot occur on more than one scroll area at the same level of the page. Parent-child relations between primary scroll records determine the dependency structure of the scroll areas on the page. The primary record on a level one scroll area must be a child of the primary record on level zero, the primary record on a level two scroll area must be a child of the primary record on its enclosing level one scroll area, and the primary record on a level three scroll area must be a child of the primary record on its enclosing level two scroll area.

Note. Level zero may have multiple records.

The hierarchical relations among scroll areas, controlled by hierarchical relations among primary scroll records, enable the user and PeopleCode to drill down through the scroll hierarchy to access any buffer field, including related display, derived/work, and Translate table buffer fields, which occupy space on the same rows as the primary scroll record buffer fields with which they are associated.

For example, to access a page field on level two of a page, a user must:

1. Select a field on level one of the page.

2. Scroll to and select the field on level two of the page.

The following diagram illustrates this scroll path taken by the user:

Scroll path to a buffer field

To access the same field in the component buffer, PeopleCode must:

1. Specify a scroll area and row on scroll level one: this selects a subset of dependent rows on level two.

2. Specify a scroll area and row on scroll level two.

3. Specify the recordname.fieldname on the level two row.

PeopleCode component buffer functions use a common scroll path syntax for locating scrolls, rows, and fields in multiple-scroll pages.

Rowsets and Scroll Areas

Rowsets enable more consistent, more convenient, and less ambiguous manipulation of buffer data than previous built-in functions could achieve. It’s a hierarchical data object that can represent an entire scroll area and all of its subordinate scroll areas.

A rowset can contain the entire contents of a component buffer, or the contents of any lower-level scroll area plus all of its subordinate buffer data. The hierarchical structure of component levels—scroll area, row, record, field—is provided by the new object data types, Rowset, Row, Record, and Field.

You can access any rowset, row, record, or field within the buffer using the dot notation inherent in PeopleTools 8 object-oriented programming. This enables you to reference fields within a record object, records within a row object, and rows within a rowset object as properties of the parent objects.

See Also

Accessing the Data Buffer

Rowset Class

Understanding Objects and Classes in PeopleCode

Record Fields and the Component Buffer

The record fields in the component buffer are a superset of those accessible to the user through page controls. In most cases, PeopleCode can reference any record field in a scroll area’s primary scroll record or in a related display record, not just those fields that are associated with page controls. The following table lists record types and locations:

Note. In RowSelect PeopleCode, you can refer only to record fields on the record that is currently being processed.

Specifying Data with Contextual References

In a contextual reference, PeopleCode refers to a row or buffer field determined by the context in which a PeopleCode program is currently executing.

This section includes an overview of current context and discusses how to:

• Use contextual row references.

• Use contextual buffer field references.

Understanding Current Context

All PeopleCode programs, with the exception of programs associated with standard menu items, execute in a current context. The current context determines which buffer fields can be contextually referenced from PeopleCode, and which row of data is the current row on each scroll level at the time a PeopleCode program is executing.

The current context comprises a subset of the buffer fields in the component buffer, determined by the row of data where a PeopleCode program is executing. The current context includes:

• All buffer fields in the row of data where the PeopleCode program is executing.

• All buffer fields in rows that are hierarchically superior to the row where the PeopleCode program is executing.

In the following diagram, all rows enclosed in dotted rectangles are part of the current context:

Context of PeopleCode executing on a level two scroll area

In the preceding diagram, a PeopleCode program is executing in a buffer field on row R3 on scroll level two. The rows in scroll level two are dependent on row R2 on scroll level one. The rows in scroll level one are dependent on the single row at scroll level zero. The current context consists of all the buffer fields at level two row R3, level one row R2, and level zero row R1. The rows in the current context on levels one and two are the current rows on their respective scroll areas. The single row on level zero is always current and is included in any current context. All rows other than the current rows and the level zero row are outside the current context. No current row can be determined on scroll areas below the one where the PeopleCode is executing.

With PeopleTools 8, contextual references work within the structure of a rowset object, and can include references to all field objects, record objects, row objects, and rowset objects in the current context.

Contextual Reference Processing Order

PeopleCode resolves contextual references at runtime by first checking the row where the PeopleCode program is executing. If PeopleCode does not find an appropriate buffer field, it looks in progressively higher rows in the current context. The following diagram indicates this processing order:

Processing order of a contextual reference

In typical pages, this processing order is not significant; however, if the same record occurs on more than one level of a page, you should understand how the direct reference is resolved.

Using Contextual Row References

A contextual row reference refers to a row in the current context on level one or lower in the page. Because each scroll area uses a unique primary record, the name of that record uniquely identifies whichever row is in the current context for that scroll level. A contextual row reference uses a RECORD. recordname component name reference to specify the scroll level of the intended row, resulting in a reference to the current row at the specified scroll level.

For example, you can use contextual row references with the RecordDeleted, RecordNew, and RecordChanged functions:

If RecordDeleted(RECORD.SOME_REC) Then...

With PeopleTools 8 object-oriented programming, a row can be referenced by specifying parent rows or rowsets of the current rowset:

If GetRowSet().ParentRowset.ParentRow.IsDeleted Then...

In early versions of PeopleTools, you could make contextual row references using a recordname.fieldname expression:

HideRow(SOME_REC.ANY_FIELD) 
                
If RecordDeleted(SOME_REC.ANY_FIELD) Then...

This syntax is still supported.

See Also

Understanding Current Context

Using Contextual Buffer Field References

A contextual buffer field reference is a type of PeopleCode expression that refers to a buffer field by specifying a record field. The row of the buffer field is determined by the current context of the PeopleCode program where the reference is made. You can use a contextual buffer field reference to retrieve or update the value in the buffer field, to pass the buffer field value to a function, or to reference an instance of a page control associated with the buffer field. The following statements use contextual buffer field references:

/* Assigns value of variable to buffer field */
SOME_RECORD.SOME_FIELD = &VAL; 
/* Assigns value of buffer field to variable */
&VAL = SOME_RECORD.SOME_FIELD; 
/* Hides instance of control associated with buffer field */
Hide(SOME_RECORD.SOME_FIELD); 

With PeopleTools 8 object-oriented programming, a field object incorporates information about both the record field on which the buffer field is based and the page control with which the buffer field is associated. By referring to the field object, you either make a contextual buffer field reference or you change an interface attribute of the associated page control, depending on the object property you use. The following example has the same effect as a contextual buffer field reference:

/* Assigns value of a variable to a buffer field */
&MYFIELD.Value = &SOMEVAL;  

Contextual Buffer Field Reference Ambiguity

Nonprimary record fields may appear on more than one scroll level in a page. For example, a page may use a derived/work field DERIVED_JS.CALC_1 as a work field on level one and level two of the same page. This creates distinct DERIVED_JS.CALC_1 buffer fields for rows on both levels. Because of the order in which PeopleCode resolves contextual buffer field references, if the contextual reference &VAL = DERIVED_JS.CALC_1; executes in a PeopleCode program on a level-two row, the reference always retrieves the buffer field value on the current row on level two. PeopleCode on level two is unable to retrieve the value of the DERIVED_JS.CALC_1 on level one using a contextual reference.

To explicitly reference the DERIVED_JS.CALC_1 buffer field on level one, use a component buffer function with a scroll path:

&VAL = FetchValue(SCROLL.level1_scrollname, CurrentRowNumber(1), DERIVED_JS.CALC_⇒
1);

The CurrentRowNumber function returns the current row on level one, or the parent row of the level two row where the PeopleCode program is executing.

Ambiguous Contextual References to Buffer Fields on Level Zero

Level zero of a page contains only a single row of data, and the buffer fields in this row are always in the current context. For this reason you can almost always refer to a level zero buffer field using a contextual reference. However, referential ambiguity can make it impossible to reference a buffer field on level zero contextually. For example, a page may use a derived/work field DERIVED_JS.CALC_1 as a work field on level zero and level one of the same page. This creates distinct DERIVED_JS.CALC_1 buffer fields for rows on both levels. Because of the order in which PeopleCode resolves contextual field references, if the &VAL = DERIVED_JS.CALC_1; contextual reference executes in a PeopleCode program on a level-one row, it always retrieves the buffer field value on the current row on level one.

To explicitly reference the DERIVED_JS.CALC_1 buffer field on level zero, you must use a component buffer function with this syntax:

Function([recordname.]fieldname, rownum)

Here rownum, because it is on level zero, is always equal to one. In the previous example of the DERIVED_JS.CALC_1 field, you would use this statement:

&VAL = FetchValue(DERIVED_JS.CALC_1, 1);

Ambiguous References with Objects

With PeopleTools 8 object-oriented programming, even if two field objects that are in different rowsets contain buffer data that’s based on the same underlying record field, references to those objects are inherently unique, because each is instantiated with respect to a specific point in the hierarchy of the buffer. Any manipulation of a field object’s interface properties affects only the page control with which it’s associated.

The following example instantiates a field object using the long form, to emphasize the hierarchical form of the data. It then hides the field’s associated page control. Because this is a unique instance of the field, based on its hierarchy, hiding this field does not affect the visibility of any other page control associated with the same record field:

&MYFIELD = GetRowset(SCROLL.EMPL_CHECKLIST).GetRow(&I).
GetRecord(RECORD.EMPL_CHECKLIST).GetField(EMPL_CHECKLIST.EMPLID);
&MYFIELD.Visible = False;
/* the same code, using the "short" form */
&MYFIELD = GetRowset(SCROLL.EMPL_CHECKLIST).GetRow(&I).
EMPL_CHECKLIST.EMPLID;

Note. Any change in a field object’s value affects both the underlying record field and the value of any other field object oriented on the same record field. This behavior is the same as the behavior of contextual buffer field references that alter the field value.

See Also

Specifying Data with References Using Scroll Path Syntax and Dot Notation

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 in PeopleTools 7.5.

• Reference scroll levels, rows, and buffer fields.

See Also

Accessing the Data Buffer

Understanding Scroll Paths

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.

PeopleTools 7.5 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 8 adds the convenience of object-oriented dot notation and default methods, which produce inherently non-ambiguous references, to PeopleCode programs. There are examples of dot notation in this section and examples of the scroll path syntax available in PeopleTools 7.5, which is still valid in PeopleTools 8.

Structuring Scroll Path Syntax in PeopleTools 7.5

PeopleTools 7.5 offers two constructions for scroll paths: a standard scroll path syntax 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:

RECORD.target_recname

RECORD.level1_recname, level1_row, 
​RECORD.target_recname

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:

Scroll Path Syntax with SCROLL.scrollname

As an alternative to RECORD.recordname expressions in scroll path constructions, PeopleTools 7.5 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:

SCROLL.target_scrollname

SCROLL.level1_scrollname, ​level1_row, ​SCROLL.target_⇒
scrollname

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:

See Also

Referencing Scroll Levels, Rows, and Buffer Fields

Referencing Scroll Levels, Rows, and Buffer Fields

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:

scrollpath

HideScroll(scrollpath);

scrollpath, row_number

HideRow(scrollpath, ​⇒
row_number);

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:

&MYROWSET = GetRowset();

&MYROWSET.Refresh();

&MYROW = GetRow();

&MYROW.CopyTo(&SOMEROW);

&MYRECORD = GetRecord();

&MYREC.CompareFields(&REC);

&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:

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

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;

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:

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;

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.

See Also

Structuring Scroll Path Syntax in PeopleTools 7.5

Understanding Current Context

CurrentRowNumber