CreateRowset function

Syntax

CreateRowset({RECORD.recname | &Rowset} [, {FIELD.fieldname, RECORD.recname | &Rowset}] .  .  .)

Description

Use the CreateRowset function to create an unpopulated, standalone rowset.

A standalone rowset is a rowset that has the specified structure, but is not tied to any data (that is, to the component buffer or to a message.) In addition, a standalone rowset isn’t tied to the Component Processor. When you fill it with data, no PeopleCode runs (like RowInsert, FieldDefault, and so on.)

The first parameter determines the structure of the rowset to be created.

If you specify a record as the first parameter, it’s used as the primary level 0 record. If you don’t specify any other parameters, you create a rowset containing one row, with one unpopulated record. To populate this type of rowset with data, you should only use:

  • the Fill or FillAppend rowset class methods

  • a record method (SelectByKey)

  • the SQLExec function

If you specify a rowset object, you are creating a new rowset based on the structure of the specified rowset object, including any child rowsets. It will not contain any data. If you want to populate this type of rowset with data, use the CopyTo method or a SQL statement.

Note:

You should not use the rowset Select or SelectNew methods for populating rowsets created using CreateRowset. Use Fill or FillAppend instead.

Parameters

Parameter Description

RECORD.recname | &Rowset

Specify either a record name or an existing rowset object.

FIELD.fieldname, RECORD.recname | &Rowset

Use FIELD.fieldname, RECORD.recname to specify a related display record. FIELD.fieldname refers to the controlling field, (not the related display field) while RECORD.recname refers to the related display record.

If you specify &rowset, you are adding a child rowset object to the newly created rowset. This must be an existing rowset object.

Returns

An unpopulated, standalone rowset object.

Example

The following creates a simple rowset of just a single record per row:

&RS = CreateRowset(RECORD.QA_MYRECORD);

The following creates a rowset with the same structure as the specified rowset:

&RS2 = CreateRowset(&RS);

The following code creates a rowset structure composed of four records in an hierarchical structure, that is, 

QA_INVEST_HDR 
   QA_INVEST_LN 
      QA_INVEST_TRANS 
         QA_INVEST_DTL

Note that you have to start at the bottom of the hierarchy, and add the upper levels, not the other way around. 

Local Rowset &RS, &RS2, &RS_FINAL; 
&RS2 = CreateRowset(RECORD.QA_INVEST_DTL); 
&RS = CreateRowset(RECORD.QA_INVEST_TRANS, &RS2); 
&RS2 = CreateRowset(RECORD.QA_INVEST_LN, &RS); 
&RS_FINAL = CreateRowset(RECORD.QA_INVEST_HDR, &RS2);

The following example reads all of the QA_MYRECORD records into a rowset, and returns the number of rows read:

&RS = CreateRowset(RECORD.QA_MYRECORD); 
&NUM_READ = &RS.Fill();

To make a clone of an existing rowset, that is, to make two distinct copies, you can do the following: 

&RS2 = CreateRowset(&RS); 
&RS.CopyTo(&RS2);

The following code example is used for creating multiple children in a standalone rowset:

Local Rowset &rsBOCMRole, &rsBOCMRel, &rsBOCMUse;

   &rsBOCMRole = CreateRowset(Record.BO_CM_ROLE);
   &rsBOCMRel = CreateRowset(Record.BO_CM_REL);
   &rsBOCMUse = CreateRowset(Record.BO_CM_USE);
   &rsBOCM = CreateRowset(Record.BO_CM, &rsBOCMUse, &rsBOCMRole, &rsBOCMRel);

Restrictions on Using CreateRowset

The following methods and properties don’t work with a rowset created using CreateRowset:

  • Select

  • SelectNew

  • Any GUI methods (like HideAllRows)

  • Any effective date methods or properties (like EffDt, EffSeq, or GetCurrEffRow)

In addition, rowsets created using CreateRowset are not automatically tied to the database. This means if you insert or delete rows, the rows will not be inserted or deleted in the database when you save the page.

Related Topics