Row Class

This chapter provides an overview of Row class and discusses the following topics:

Click to jump to parent topicUnderstanding Row Class

A row object, instantiated from the Row class, is a single row of data that consists of one to n records of data. A single row in a component scroll is a row.

A row object is always associated with a rowset object, that is, you cannot instantiate a row object without first either explicitly or implicitly instantiating a rowset object.

A row may have one to n child rowsets. For example, a row in a level two scroll may have n level three child rowsets.

CopyTo and GetRecord are two commonly use methods for this class. Visible and IsChanged are two commonly used properties for this class.

The row class is one of the data buffer access classes.

If a rowset object is instantiated using the CreateRowset function, the rowset object that’s instantiated is a standalone rowset. Delete and insert activity on these types of rowsets aren't automatically applied at save time. Use standalone rowsets for work records.

See Also

Accessing the Data Buffer

Using Standalone Rowsets

Click to jump to parent topicShortcut Considerations

The default method for the row class is GetRecord. This means you can specify just a record name to access a record on the row. For example, the following two lines of code are equivalent:

&Count = &MyRow.EMPL_CHECKLIST.FieldCount;

&Count = &MyRow.GetRecord(RECORD.EMPL_CHECKLIST).FieldCount;

In addition, the row class has a method scrollname. This enables you to access a specific child rowset and row within that rowset. This isn't a default method: you're not accessing a child object, but rather, something within that object. For example, the following two lines of code are equivalent:

&ChildRow = &MyRow.EMPL_CHKLST_ITM(&I);

&ChildRow = &MyRow.GetRowset(SCROLL.EMPL_CHKLST_ITM).GetRow(&I);

Click to jump to parent topicData Type of a Row Object

Row objects are declared as type Row. For example, 

Local Row &MYROW;

Click to jump to parent topicScope of a Row Object

A Row can only be instantiated from PeopleCode.

This object can be used anywhere you have PeopleCode, that is, in an application class, Application Engine PeopleCode, Component Interface PeopleCode, and so on.

Click to jump to parent topicRow Class Built-in Function

GetRow

Click to jump to parent topicRow Class Methods

In this section, we discuss each Row class method. The methods are discussed in alphabetical order.

Click to jump to top of pageClick to jump to parent topicCopyTo

Syntax

CopyTo(row)

Description

The CopyTo method copies fromthe row executing the method tothe specified target row, copying like-named record fields and subscrolls at corresponding levels. The target row object must be from a "related" rowset, that is, built from the same records, but it can be under a different parent at higher levels.

This method copies all the records from the row object executing the method to the target row, not just the primary data record associated with the rowset.

Parameters

row

Specify a target row. This must be a row object, not a row number.

Returns

None

Example

The following example copies rows from a child rowset (DERIVED_HR) to the current rows.

Local Row &ROW;
Local Rowset &RS1;

&RS1 = GetRowset();
For &I = 1 to &RS1.ActiveRowCount
   &ROW = GetRowset(SCROLL.DERIVED_HR).GetRow(&I);
   &ROW.CopyTo(GetRow(&I));
End-For;

See Also

ParentRowset, CopyFieldsTo, CopyChangedFieldsTo.

Click to jump to top of pageClick to jump to parent topicGetNextEffRow

Syntax

GetNextEffRow()

Description

The GetNextEffRow method finds the row, in the same rowset as the row executing the method, that has the next effective date (when compared to the row executing the method.)

Parameters

None

Returns

A row object. If there is no row with a later effective date, this method returns a null object.

Example

&ROW2 = &ROW.GetNextEff();

If &ROW2 <> NULL Then
   &TMP = &ROW2.RowNumber;
   /* other processing */
Else
   /* no effective dated row - do error processing */
End-if;

See Also

GetPriorEffRow, GetCurrEffRow, DeleteEnabled.

Click to jump to top of pageClick to jump to parent topicGetPriorEffRow

Syntax

GetPriorEffRow()

Description

The GetPriorEffRow method finds the row, from the same rowset as the row executing the method, that has the prior effective date to the row executing the method.

Parameters

None

Returns

A row object. If there is no row with a prior effective date, this method returns a null object.

Example

&TMP = &ROW.GetPriorEffrow().RowNumber;

See Also

GetNextEffRow, GetCurrEffRow, DeleteEnabled.

Click to jump to top of pageClick to jump to parent topicGetRecord

Syntax

GetRecord({n | RECORD.recname})

Description

The GetRecord method creates a record object that references the specified record within the current row object. This is the default method for a row object. This means that any row object, followed by a parameter list, acts as if GetRecord is specified.

Parameters

n | RECORD.recname

Specify a record to be used for instantiating the record object. You can specify either n or RECORD.recname, Specifying n creates a record object for the nth record in the row. This might be used if writing code that needs to examine all records in a row without being aware of the record name. Specifying RECORD.recname creates a record object for the record recname.

Note. There is no way to predict the order the records will be accessed. Use the n option only if the order in which the records are processed doesn’t matter.

Returns

A record object.

Example

The following example gets a record, then assigns the name of the record to the variable &TMP:

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

&TMP = &REC.NAME;  /* note that NAME is a property of the record class */

Because GetRecord is the default method for a row, the following code is identical to the previous:

&REC = &ROW.QEPC_LEVEL1_REC;

&TMP = &REC.NAME;

The following example loops through all the records for a row:

Local rowset &LEVEL1;
Local row &ROW;
Local record &REC;

&LEVEL1 = GetRowset(SCROLL.EMPL_CHECKLIST);
For &I = 1 to &LEVEL1.ActiveRowCount
   &ROW = &LEVEL1.GetRow(&I);
   For &J = 1 to &ROW.RecordCount
      &REC = &ROW.GetRecord(&J);
         /* do processing */
   End-For;
End-For;

The following function takes a rowset and a record, passed in from another program. GetRecord won’t take a variable for the record, however, using the @ symbol you can convert the string to a component record name.

Function Get_My_Row(&PASSED_ROWSET, &PASSED_RECORD)
   
   For &ROWSET_ROW = 1 To &PASSED_ROWSET.RowCount
      &UNDERLYINGREC = "RECORD." | &PASSED_ROWSET.DBRecordName;
      &ROW_RECORD = &PASSED_ROWSET.GetRow(&ROWSET_ROW).GetRecord(@&UNDERLYINGREC);
      
      /* Do other processing */
      
   End-For;
   
End-Function;

See Also

GetRecord, CreateRecord.

Click to jump to top of pageClick to jump to parent topicGetRowset

Syntax

GetRowset({n | SCROLL.scrollname})

Description

The GetRowset method creates a rowset object that references a child rowset of the current row. scrollname must specify the primary record for the child rowset.

Parameters

n | SCROLL.scrollname

Specify a rowset to be used for instantiating the rowset object. You can specify either n or SCROLL.scrollname. Specifying n creates a rowset object for the nth child rowset in the row. This might be used if you are writing code that examines all rowsets in a row without being aware of the name. Specifying SCROLL.scrollname creates a rowset object for the record scrollname. scrollname must specify the primary record for the child rowset.

Note. There is no way to predict the order the rowsets will be accessed. Use the n option only if the order in which the rowsets are processed doesn’t matter.

Returns

A rowset object.

Example

&CHILDROWSET = &ROW.GetRowset(SCROLL.QEPC_LEVEL1_REC);

See Also

Row class: scrollname method.

GetRowset

Click to jump to top of pageClick to jump to parent topicscrollname

Syntax

scrollname(n)

Description

If scrollname is used as a method name for a row, it is used to select a child rowset and a row within that rowset. 

&ROW.scrollname(n)

acts the same as 

&ROW.GetRowset(SCROLL.scrollname).GetRow(n)

Parameters

n

Must be a valid row number for the selected child rowset.

Returns

A row object.

Example

&SUBROW1 = &ROW.QEPC_LEVEL1_REC(1);

See Also

GetRowset.

Click to jump to parent topicRow Class Properties

In this section, we discuss the Row class properties. The properties are discussed in alphabetical order.

Click to jump to top of pageClick to jump to parent topicChildCount

Description

This property returns the number of child rowsets of the row. It is defined by the "structure" of the scroll, so it is the same for all rows of the rowset.

It might be used, in conjunction with the GetRowset method, to write code that examines all child rowsets.

This property is read-only.

Example

For &I = 1 to &ROW.ChildCount
   &ROWSET = &ROW.GetRowset(&I);
      /* do processing */
End-For;

Click to jump to top of pageClick to jump to parent topicDeleteEnabled

Description

This property determines whether a row can be deleted (the equivalent of the user pressing ALT+8 and ENTER). This property takes a Boolean value.

Note. This property controls only whether an end-user can delete a row. Rows can still be deleted using PeopleCode.

This property is typically used to prevent deletion of an individual row that the other properties controlling deletion would allow to be deleted. The following table goes through the Boolean logic.

Will delete be allowed by user?

Others enable

Others disable

DeleteEnabled = True

Yes

No

DeleteEnabled = False

No

No

The initial value of this property is True.

Note. If No Row Delete is selected in Application Designer, setting the DeleteEnabled row property to True will not override this value. If you want to control whether a row can be deleted at runtime, you should not select No Row Delete at design time. Likewise, if the DeleteEnabled Rowset property is False, setting the DeleteEnabled Row property to True will not override the rowset property. If you want to control whether an individual row can be deleted at runtime, you should not set the DeleteEnabled rowset property to False.

For consistency, PeopleSoft recommends that either all rows at a level should disable deletions, or they should all allow deletions.

For rows created with non-Component Processor data (such as message rowsets, Application Engine rowsets, and so on) this property has no effect.

Note. Don't use this property with rows from rowsets created using CreateRowset. Rowsets created using the CreateRowset function are standalone rowsets, not tied to the database, so there are no database updates when they are manipulated. Delete and insert activity on these types of rowsets aren't automatically applied at save time.

This property is read-write.

See Also

Rowset class: DeleteEnabled property.

Using Scroll Areas and Scroll Bars

Using Standalone Rowsets

Click to jump to top of pageClick to jump to parent topicIsChanged

Description

This property returns True if any field value on the primary database record of the row has been changed.

Note. Use this property only with the primary database record. It doesn't return valid results if used with a work record. This property returns True only if the existing row object has a field that has changed. If a field in a lower level rowset has changed, this property returns False.

This property is read-only.

Considerations Using IsChanged

This property and the IsChanged record property do notalways return identical values.

If a row in a scroll contains multiple records (such as a primary database record and one or more work records), the IsChanged row property returns True if any of the records in the row are changed. The IsChanged record property returns True only if a specific record, namely, the primary database record, is changed.

If a row is deleted from a scroll, onlythe primary database record has its IsChanged property marked to False (since the row has been deleted.) Any work records in the row stillhave their IsChanged properties set to True.

Example

&tmp =  &ROW.IsChanged;
if &tmp = True then
   Warning("A Field on this row has been changed");
End-If;

Click to jump to top of pageClick to jump to parent topicIsDeleted

Description

This property returns True if the row has been deleted.

This property is read-only.

Note. This property also returns True if the row is new and hasn't been changed.

Example

&tmp = &ROW.IsDeleted;

Click to jump to top of pageClick to jump to parent topicIsEditError

Description

This property is True if an error has been found for any field associated with any record in the current row or on any row in any child rowset of the current row after executing the ExecuteEdits method. This property can be used with the Field class properties EditError (to find out which field is in error), and MessageSetNumber and MessageNumber to find the error message set number and error message number.

This property is read-only.

Example

The following is an example showing how IsEditError, along with the ExecuteEdits method could be used:

&MSG.ExecuteEdits();
If &MSG.IsEditError Then
&RS = &MSG.GetRowset();
   For &J = 1 to &RS.RowCount
      &ROW = &RS.GetRow(&J);
         If &ROW.IsEditError Then 
            &REC = &ROW.GetRecord();
            For &I = 1 to &REC.FieldCount
               If &REC.GetField(&I).EditError Then
                  LOG_ERROR();  /* application specific call */
               End-If;
            End-For;
      End-If;
   End-For;
End-If;

See Also

Record class: ExecuteEdits method, IsEditError property, EditError property, MessageNumber property, MessageSetNumber property.

Click to jump to top of pageClick to jump to parent topicIsNew

Description

This property is True if the row is a new (inserted) row.

This property is read-only.

Example

&tmp = &ROW.IsNew;

Click to jump to top of pageClick to jump to parent topicParentRowset

Description

This property returns a rowset object referencing the rowset containing the row.

This property is read-only.

Example

&tmp = &ROW.ParentRowset.RowCount;

/* note that rowcount is a property of the Rowset class */

Click to jump to top of pageClick to jump to parent topicrecname

Description

If a record name is used as a property, it accesses the record object with that name. This means the following code:

&ROW.somerecname

acts the same as 

&ROW.GetRecord(RECORD.somerecname);

This property is read-only.

Example

&REC = &ROW.QEPC_LEVEL1_REC;

Click to jump to top of pageClick to jump to parent topicRecordCount

Description

This property returns the number of records in the row. It is defined by the "structure" of the scroll, so it is the same for all rows of the rowset.

This property might be used in conjunction with the GetRecord method to write code that examines all records in some way.

This property is read-only.

Example

For &I = 1 to &ROW.RecordCount
   &REC = &ROW.GetRecord(&I);
   /* do processing */
End-For;

Click to jump to top of pageClick to jump to parent topicRowNumber

Description

This property returns the row number (starting from 1) of the row within its rowset.

This property is read-only.

Example

The following returns the row number of the current effective-date row.

&NUMBER = GetRowset(SCROLL.MYRECORD).GetCurrEffRow().RowNumber;

Click to jump to top of pageClick to jump to parent topicSelected

Description

This property returns True if the row is part of a grid and has been selected either by the user or programmatically.

This property is meaningful in PIA only if the grid or scroll area attribute has been set to provide the selection control. In this case, the property reflects the state of the checkbox or radio button used for selection.

This property is read-write.

Example

The following example determines how many rows in a grid are selected.

Function Count_Child_Assets(&GRIDLEVEL1 As Rowset, &NUM_CHILDREN)
   REM *** How many child assets are selected?                  *;
   &GRIDLEVEL1 = GetRowset(SCROLL.PARENT_CHILD_VW);
   For &CHILDROW_COUNT = 1 To &GRIDLEVEL1.ActiveRowCount
      If &GRIDLEVEL1.GetRow(&CHILDROW_COUNT).Selected = True Then
         &NUM_CHILDREN = &NUM_CHILDREN + 1;
      End-If;
   End-For;
End-Function;

Click to jump to top of pageClick to jump to parent topicStyle

Description

This property returns the name of the style class if one has been set for the row. You can also use this property to change the style of a row. This property takes a string value.

Note. This property overrides only the existing style. It doesn't change it. The next time the page is accessed the original style is used.

The PSSTYLE style sheet does not contain a default style class for a row. The Style property for all rows is initially NULL (that is, two quotation marks with no space between them ("")). The row assumes the style of the grid alternate row style. Fields in the row assume field styles if set.

Setting the property for a row overrides the grid alternate row style and any page field styles (field styles that were set in Application Designer). It does not override any field styles set (using the Field class Style property) for fields in the row.

Setting the Style property back to NULL (that is, two quotation marks with no space between them ("")) turns off the override.

Note. This property is not valid for Windows Client applications.

Example

&Scroll = GetLevel0().GetRow(1).GetRowset(Scroll.IC_PC_STYLE_2);

&row_class = &Scroll.GetRow(&row);

&row_class.Style = &style;

See Also

Field class: Style property.

Creating Field Definitions

Click to jump to top of pageClick to jump to parent topicVisible

Description

If this property is True, the row is visible if displayed on the current page. This property can be set False to hide the row.

When Visible is set to False to hide a row, the row moves to the end of the rowset. This means that the row number of the row being hidden, and any subsequent rows, changes as a result of hiding a row. If the row is later made visible again, it is not moved back to its original position, but remains at the end of the rowset. It is just moved to the start of all the other hidden rows.

For example, if there are 4 rows in a rowset and row 2 is hidden (that is, Visible = False), that row now becomes row 4. In order to make that row visible again, row 4 must be set to Visible = True. Alternatively, you can use a row object reference: this remains valid even though the row number of the row may have been changed.

Note. If you use the Sort method on a rowset with hidden rows, the hidden rows aren't sorted. Only visible rows are sorted.

You cannot hide rows in the current context of the executing program. This means Visible cannot hide the row containing the executing program, or in a child rowset and be executed against its parent rowset. Place your PeopleCode in a parent rowset and execute it against a child rowset.

Example

&ROW.Visible = False;

The following code uses the Visible property to determine if a row is visible or not before updating the value of the row.

&ROWSET = GetRowset(SCROLL.LD_SHP_INV_VW)

For &I = 1 To &ROWSET.ActiveRowCount
   If &ROWSET(&I).Visible Then
      ITEM_SELECTED.value = "N";
   End-If;
End-For;

The following code starts with the last row and works forward to the first. If any changes are made they don't impact the position of rows that still have to be processed.

For &I = &ACTIVE_STREAMS to 1 Step -1
   &Row = &STREAM_ROWSET(&I);
   If &Row.QS_STREAM8.STREAM_ROOT_ID.Value <> &STREAM_ROOT_ID Then
      &Row.Visible = False;
   End-if;
End-For;