Understanding Data Buffer Classes Examples

Level Zero Access

The following code instantiates a rowset object, from the Rowset class, that references the level zero rowset, containing all the page data. It stores the object in the &LEVEL0 variable.

&LEVEL0 = GetLevel0();

The level zero rowset contains all the rows, rowsets, records, and fields underneath it.

If the level zero rowset is formed from component buffer data, then the level zero rowset has one row of data and that row contains all the child rowsets, which in turn contain rows of data that contain other child rowsets.

If the level zero rowset is formed from buffer data, such as from an application message, then the level zero rowset may contain more than one row of data. Each row of the level zero rowset contains all the child rowsets associated with that row, which in turn contain rows of data that contain other child rowsets.

Use a level zero rowset when you want an absolute path to a lower-level object or to do some processing on the entire data buffer. For example, suppose you load all new data into the component buffers and want to redraw the page. You could use the following code:

/* Do processing to reload Component Buffers */
&LEVEL0 = GetLevel0();
&LEVEL0.Refresh();

Rowset Object

The following code instantiates a rowset object that references the rowset that contains the currently running PeopleCode program:

&ROWSET = GetRowset();

You might later use the &ROWSET variable and the ActiveRowCount property to iterate over all the rows of the rowset, to access a specific row (using the GetRow method), or to hide a child rowset (by setting the Visible property).

The level one rowset contains all the level two rowsets. However, the level two rowsets can only be accessed using the different rows of the level one rowset. From the level zero or level one rowset, you can only access a level two rowset by using the level one rowset and the appropriate row.

Image: Level two rowset from level one row

For example, suppose your program is running on some field of row five of a level two scroll area, which is on row three of its level one scroll area. The resulting rowset contains all the rows of the level two scroll area that are under the row three of the level one scroll area. The rowset does not contain any data that is under any other level two scroll areas. The following diagram illustrates these results:

A further illustration uses an example from the Employee Checklist page.

Suppose that one employee was associated with three different checklists: Foreign Loan Departure, Foreign Loan Arrival, and Foreign Loan Host. The checklist code field (CHECKLIST_CD) on the first level of the page drives the entries on the second level. Each row in the level one rowset produces a different level two rowset.

Image: EMPLOYEE_CHECKLIST Foreign Loan Departure checklist

The Foreign Loan Departure checklist (000001) produces a checklist that contains such items as Briefing with Human Resources and Apply for Visas/Work permits, as shown in the following example:

Image: EMPLOYEE_CHECKLIST Foreign Load Arrival Checklist

The Foreign Loan Arrival checklist (0000004) produces a checklist that contains items such as Register at Consulate and Open New Foreign Bank Accounts, as shown in the following example:

Row Object

When you create a page, you put fields from different records onto the page. You can think of this as creating a type of pseudo-SQL join. The row returned from this pseudo-join is a row object.

For example, the first level scroll area of the EMPLOYEE_CHECKLIST page contains the following fields, associated with these records:

The pseudo-SQL join might look like this:

JOIN A.CHECKLIST_DT, A.CHECKLIST_CD, A.COMMENTS, B.DESCR, C.NAME, A.RESPONSIBLE_ID
FROM PS_EMPL_CHECKLIST A, PS_CHECKLIST_TBL B, PS_PERSONAL_DATA C, WHERE. . . 

What goes into the Where clause is determined by the level zero of the page. For our example, the value is WHERE EMPLID=8001.

When the component is opened, data is loaded into the component buffers. Any row returned by the pseudo-SQL statement is a level one row object. The following table shows a returned row:

Record Object

A record definition is a definition of what your underlying SQL database tables look like and how they process data. After you create record definitions, you build the underlying SQL tables that contain the application data that your users enter online in your production environment.

When you create a record object using the CreateRecord function, you are creating an area in the data buffers that has the same structure as the record definition, but no data.

When you instantiate a record object from the Record class using some variation of GetRecord, that record object references a single row of data in the SQL table.

The following code instantiates a record object for referencing the EMPL_CHECKLIST record of the specified row:

&REC = &ROW.GetRecord(RECORD.EMPL_CHECKLIST);

Using the short method, the following line of code is identical to the previous line:

&REC = &ROW.EMPL_CHECKLIST;

You might later use the &REC variable and the CopyFieldsTo property to copy all like-named fields from one record to another. In the following example, two row objects are created, the copy from row (COPYFRMROW) and the copy to row (COPYTROW). Using these rows, like-named fields are copied from CHECKLIST_ITEM to EMPL_CHKLST_ITM.

For &I = 1 To &ROWSET1.ActiveRowCount
   &COPYFRMROW = &ROWSET1.GetRow(&I);
   &COPYTROW = &RS2.GetRow(&I);
   &COPYFRMROW.CHECKLIST_ITEM.CopyFieldsTo(&COPYTROW.EMPL_CHKLST_ITM);
End-For;

A row may contain more than one record: in addition to the primary database record, you may have a related display record or a derived record. You can access these records as well. The level one rowset, &ROWSET1, is made up of many records. The following accesses two of them: EMPL_CHECKLIST and DERIVED_HR.

&REC1 = &ROW.EMPL_CHECKLIST;
&REC2 = &ROW.DERIVED_HR;

Field Object

The following instantiates a field object, from the Field class, that is used to access a specific field in the record:

&FIELD = &REC.GetField(FIELD.CHECKLIST_CD);

You might later use the &FIELD variable as a condition:

If ALL(&FIELD) Then

Here is another example:

If &FIELD.Value = "N" Then

You can also set the value of a field. Using the GetField function does not create a copy of the data from the component buffer. Setting the value or a property of the field object sets the actual component buffer field or property.

See Assigning Objects.

In the following example, the type of field is verified, and the value is replaced with the tangent of that value if it is a number

If &FIELD.Type <> "NUMBER" Then
   /* do error recording */
Else
   &FIELD.Value = Tan(&FIELD.Value);
End-If;

Obtaining the Rowset

You first obtain the level zero rowset, which is the PERSONAL_DATA rowset. You do not need to know the name of the level zero rowset to access it:

&LEVEL0 = GetLevel0();

Obtaining Rows

The next object to get is a row. As the following code is working with data that is loaded from a page, only one row is at level zero. However, if you have rowsets that are populated with data that is not based on component buffers (for example, an application message), you may have more than one row at level zero.

&LEVEL0_ROW = &LEVEL0(1);

Obtaining Child Rowsets

To obtain the level two rowset, traverse through the level one rowset first. Therefore, the next object to get is the level one rowset, as shown in the following example:

&LEVEL1 = &LEVEL0_ROW.GetRowset(SCROLL.EMPL_CHECKLIST);

Obtaining Subsequent Rows

If you are traversing a page, obtain the appropriate row after you get a rowset. To process all the rows of the rowset, set this functionality up in a loop, as shown in the following example:

For &I = 1 to &LEVEL1.ActiveRowCount
   &LEVEL1_ROW = &LEVEL1(&I);
   . . .
End-For;

Obtaining Subsequent Rowsets and Rows

Traverse another level in the page structure to access the second level rowset, and then use a loop to access the rows in the level two rowset.

Because we are processing all the rows at level one, we are just adding code to the previous For loop. As we process through all the rows at level two, we are adding a second For loop. The new code is in bold in the following example:

For &I = 1 to &LEVEL1.ActiveRowCount
   &LEVEL1_ROW = &LEVEL1(&I);
   &LEVEL2 = &LEVEL1_ROW.GetRowset(SCROLL.
EMPL_CHKLST_ITM);
   For &J = 1 to &LEVEL2.ActiveRowCount
      &LEVEL2_ROW = &LEVEL2(&J);
   . . .
   End-For;
End-For;

Obtaining Records

A row always contains a record, and it may contain only a child rowset, depending on how your page is set up. GetRecord is the default method for a row, so all you have to specify is the record name.

Because we are processing all the rows at level two, we just add code to the For loops of the previous example. The new code is in bold:

For &I = 1 to &LEVEL1.ActiveRowCount
   &LEVEL1_ROW = &LEVEL1(&I);
   &LEVEL2 = &LEVEL1_ROW.GetRowset(SCROLL.EMPL_CHKLST_ITM);
   For &J = 1 to &LEVEL2.ActiveRowCount
      &LEVEL2_ROW = &LEVEL2(&J);
      &RECORD = &LEVEL2_ROW.EMPL_CHKLST_ITM;
   . . .
   End-For;
End-For;

Obtaining Fields

Records are made up of fields. GetField is the default method for a record, so all you have to specify is the field name.

Because we are processing all the rows at the level one, we are just adding code to the For loops of the previous example. The new code is in bold:

For &I = 1 to &LEVEL1.ActiveRowCount
   &LEVEL1_ROW = &LEVEL1(&I);
   &LEVEL2 = &LEVEL1_ROW.GetRowset(SCROLL.EMPL_CHKLST_ITM);
   For &J = 1 to &LEVEL2.ActiveRowCount
      &LEVEL2_ROW = &LEVEL2(&J);
      &RECORD = &LEVEL2_ROW.EMPL_CHKLST_ITM;
      &FIELD = &RECORD.BRIEFING_STATUS;
      /* Do processing */
   End-For;
End-For;

Using Shortcuts

Image: Rowset example

The previous code is the long way of accessing this field. The following example uses shortcuts to access the field in one line of code. The following code assumes all rows are level one:

Here’s another method of expressing the code:

Rowset

&LEVEL0 = GetLevel0();

Row

&LEVEL0_ROW = &LEVEL0(1);

Rowset

&LEVEL1 = &LEVEL0_ROW.GetRowset(SCROLL.EMPL_CHECKLIST);

For &I = 1 to &LEVEL1.ActiveRowCount

Row

&LEVEL1_ROW = &LEVEL1(&I);

Rowset

&LEVEL2 = &LEVEL1_ROW.GetRowset(SCROLL.EMPL_CHKLST_ITM);

    For &J = 1 to &LEVEL2.ActiveRowCount

Row

       &LEVEL2_ROW = &LEVEL2(&J);

Record

       &RECORD = &LEVEL2_ROW.EMPL_CHKLST_ITM;

Field

       &FIELD = &RECORD.BRIEFING_STATUS;

            /* Do processing */

    End-For;

End-For;