Understanding Component Buffer Structure and 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 Classes and Objects.

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.

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.

Image: Scroll path to a buffer field

The following diagram illustrates the scroll path taken by the user 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 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.

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: