理解行集类

A rowset object, instantiated from a Rowset class, is a collection of rows associated with buffer data. A component scroll is a rowset. You can also have a level zero rowset.

If a rowset object is instantiated using GetRowset (either the function or one of the methods) the rowset object that is instantiated is populated with data according to the context in which it was instantiated.

If a rowset object is instantiated using the CreateRowset function, the rowset object that’s instantiated is a standalone rowset. Any records and field references created by this function are initialized to null values, that is, they do not contain any data. You can populate this rowset object using the CopyTo, Fill, or FillAppend methods.

Default processing isn't performed on a standalone rowset. In addition, a standalone rowset isn't tied to the Component Processor. When you fill it with data, no PeopleCode runs (for example, RowInsert, FieldDefault, and so on.) Delete and insert activity on these types of rowsets aren't automatically applied at save time. Use standalone rowsets for work records.

You might use a rowset object and the ActiveRowCount property to iterate over all the rows of the rowset, or to access a specific row (using the GetRow method) or to find the name of the primary record associated with the scroll (the DBName property).

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

See Also

Using Standalone Rowsets

Accessing the Data Buffer

The default method for the Rowset class is GetRow. This means you can specify just a row number, and not use the GetRow method. For example, the following two lines of code are equivalent:

&MyRow = GetRowset()(5); &MyRow = GetRowset().GetRow(5);

Rowset objects are declared as type Rowset. For example,

Local Rowset &MYROWSET;

Scope of a Rowset Object

A Rowset can be instantiated from PeopleCode or using Java.

This object can be used anywhere you have PeopleCode, that is, in an Application Class, record field PeopleCode, and so on.

You can’t pass a rowset object in as part of a Component Interface user-defined method. (Rowsets aren’t common data structures outside of a PeopleSoft system.) However, within a user-defined method for a Component Interface you can use rowset objects.

In an Application Engine program, a rowset object is the equivalent of a record object that contains one row and a single record, that is, the State Record. PeopleSoft suggests using the Record object instead of a rowset object to obtain access to the State Record.

Messages have the same structure as rowsets, that is, hierarchical data structures composed of rows, records, and fields.

File objects can have the same structure as rowsets, that is, hierarchical data structures composed of rows, records, and fields.

See Also

Using Standalone Rowsets

Rowset Class Built-In Functions

CreateRowset

CreateRowset

GetRowset

In this section, we discuss the Rowset class methods. The methods are discussed in alphabetical order.

Syntax

ClearDeletesChanges()

Description

Use the ClearDeletesChanges method to clear deleted rows and changed from a standalone rowset.

Note. This method works only with standalone rowsets, that is, rowsets created using the CreateRowset function.

This method differs from Flush in a number of ways:

• it does not remove all rows from the rowset, only deleted rows

• it only applies to standalone rowsets

This method first clears the deleted rows, that is, all rows that have been deleted using DeleteRow are removed from the rowset and their associated buffers are freed.

This method then clears changed rows. That means any changes done on a row (such as field values changed) or newly inserted rows are now propagated into their original state and the changed buffers, if any, are freed.

After executing this method on a standalone rowset, any row that was previously new or changed no longer has that state. The IsNew and IsChanged properties of a row return false.

This method does not do any database updates.

How would you use this method? Suppose you use a standalone rowset to track changes you need to make to some business process or object. After doing the appropriate database updates to reflect changes recorded in the rowset (that is, inserts or deletes or changes), you call this method to clean up the rowset in preparation for further processing. Without this method, newly inserted rows and changed rows preserve their IsNew and IsChanged status indefinitely, complicating program logic and potentially leading to duplicate inserts or deletes.

Parameters

None.

Returns

None.

Example

REM +--------------------------------------------------+; REM | Function to Update the DB for a Standalone Rowset|; REM +--------------------------------------------------+; Function ProcessDatabaseUpdateforRowset(&rsIn As Rowset) For &i = 1 To &rsIn.RowCount &rwTMP = &rsIn.GetRow(&i); If &rwIn.IsDeleted And Not &rwIn.IsNew Then &rTMP = &rwIn.GetRecord(1); &rTMP.Delete(); End-If; If &rwTMP.IsNew And &rwTMP.IsChanged And Not &rwTMP.IsDeleted Then &rTMP = &rwTMP.GetRecord(1); &rTMP.Insert() End-If; If Not &rwTMP.IsNew And &rwTMP.IsChanged And Not &rwTMP.IsDeleted Then &rTMP = &rwTMP.GetRecord(1); &rTMP.Update(); End-If; End-For; REM +-----------------------------------------------+; REM | Now we need to reset the Rowset flags and |; REM | remove deleted rows |; REM +-----------------------------------------------+; &rsIn.ClearDeletesChanges(); End-Function;

See Also

Rowset class: Flush method, FlushRow method, IsChanged property, IsNew property.

Syntax

CopyTo(&DestRowset [, record_list])

Where record_list is a list of record names in the form:

[RECORD.source_recname1, RECORD.target_recname1

[, RECORD.source_recname2, RECORD.target_recname2]]. . .

Description

The CopyTo method copies from the rowset executing the method to the specified destination rowset, copying like-named record fields and subscrolls at corresponding levels.

The CopyTo method uses the current data in the rowset. This might be different from the original data values if the rowset was retrieved from the database and values in it have been changed either by an end-user or a PeopleCode program

If pairs of source and destination record names are given, these are used to pair up the records and subscrolls before checking for like-named record fields. Then, after copying the named records pairs, this method copies all identically named records.

Note. This method does not work for Application Engine state records. If you don’t specify record_list, both the record name and the field name have to match exactly for data to be copied from one record field to another. If you specify record_list, after the records have been paired up, the field names have to match before any data is copied.

If the rowset you are copying from has the field level EditError, as well as the MessageNumber and MessageSetNumber properties set, these values are copied to the rowset you are copying to. For example, suppose you had an application message that had errors. Using the GetSubContractInstance function, these errors would be copied into the message object. From there, you could instantiate a message rowset, copy the message rowset into a work rowset, and use the work rowset to populate Component buffers. (After the field properties are set, the Record, Row, and Rowset properties IsEditError also get set.)

Parameters

Returns

None.

Example

If you set one rowset equal to another, you haven’t made a copy of the rowset. Instead, you have two variables pointing to the same data.

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 example copies data from one rowset object to another. Because no like-named records exist between the two rowsets, the record names are specified. Only the like-named fields are copied from one rowset to the other:

Local Rowset &RS1, &RS2; Local String &EMPLID; &RS1 = CreateRowset(RECORD.PERSONAL_DATA); &RS2 = CreateRowset(RECORD.PER_VENDOR_DATA); &EMPLID = "8001"; &RS1.Fill("WHERE EMPLID =: 1", &EMPLID); &RS1.CopyTo(&RS2, RECORD.PERSONAL_DATA, RECORD.PER_VENDOR_DATA);

The following example copies data from a message into the Component buffers, then calls the page (using TransferPage) to redraw the page. You could do this to fill a page with message data that is in error, so that an end-user can make corrections to the message data. &WRK_ROWSET0 is the level zero rowset and &WRK_ROWSET1 is where the data is copied to.

/* Get the Message */ &MSG = GetSubContractInstance(&PUBID, &PUBNODE, &CHNLNAME, &MSGNAME, &SUBNAME); /* Get the Message Rowset */ &MSG_ROWSET = &MSG.GetRowset(); /* Get Level 0 */ &WRK_ROWSET0 = GetLevel0(); /* Create Work rowset */ &WRK_ROWSET1 = GetLevel0()(1).GetRowset(SCROLL.EN_REVISION_TMP); /* Populate Work Rowset */ &MSG_ROWSET.CopyTo(&WRK_ROWSET1, RECORD.EN_REVISION, RECORD.EN_REVISION_TMP); SetNextPage("EN_REVISION_MSG"); TransferPage();

See Also

CopyTo, CreateRowset.

Assigning Objects

Syntax

DeleteRow(n)

Description

The DeleteRow method deletes the row in the rowset identified by the parameter.

If the program is being run from a component against Component buffer data, a RowDelete PeopleCode event also fires, followed by the events that normally follow a RowDelete, as if the user had manually pressed ALT+8 and ENTER.

This method initially marks the row as needing to be deleted. At save time the row is actually deleted from the database and cleared from the buffer. When the row is marked as deleted, it is ignored by other methods, such as GetCurrEffRow, Sort, and so on.

DeleteRow cannot be executed from the same rowset where the deletion takes place, or from a child rowset against a parent. Place your PeopleCode in a parent rowset and execute it against a child rowset.

When DeleteRow is used in a loop, you have to process rows from high to low to achieve the correct results, that is, you must delete from the bottom up rather than from the top down. This is necessary because the rows are renumbered after they are deleted (if you delete row one, row two becomes row one).

Note. If you use DeleteRow on a rowset created using the CreateRowset function, the row isn't automatically deleted in the database when the page is saved. 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.

Parameters

Returns

An optional Boolean value: True if row is deleted, False otherwise.

Example

In the following example DeleteRow is used in a For loop. The example checks a value in each row, then conditionally deletes the row. Note the syntax of the For loop, including the use of the -1 in the Step clause to loop from the highest to lowest values. This ensures that the renumbering of the rows do not affect the loop.

For &I = &RS2.ActiveRowCount To 1 Step -1 If None(&CHECK_SEQ) Then &RS2.DeleteRow(&I); End-If; End-For;

See Also

Rowset class: Flush method, FlushRow method, InsertRow method, Insert method.

Using Standalone Rowsets

Syntax

Fill([wherestring [, bindvalue] . . .])

描述

The Fill method flushes the rowset then reads records from the database into successive rows. The records are read from the database tables corresponding to the primary database record of the scroll into that record. The records are selected by the optional wherestring SQL clause, in which the optional bindvalues are substituted, using the usual bind placeholders (:n).

In general, use this method only with rowsets that were created using the CreateRowset function.

Note. Because Flush always leaves one row in the scroll, there will be one row in the scroll even if you don’t read any records.

The actual number of records read into the rowset is an optional return of this method.

Note. This method does not work with Application Engine state records. Also, you cannot use this method in dynamic views.

When this method executes, unlike the Select method, it does not cause any associated PeopleCode to run as part of reading data into the rowset.

Note. Fill reads only the primary database record. It does not read any related records, nor any subordinate rowset records.

For every record read with the Fill method, if the set language is not the base language and the record has related language records, the Fill method tries to read the related language record and does related language processing.

The Fill method uses a correlation ID of FILL for the table it reads. You must use the correlation ID if you want to refer to the rowset table name as part of the wherestring. You receive a runtime error if you use the table name as a column prefix instead of the correlation ID.

Rows come unsorted from the database when using Fill. This is not a problem for SQL server, however, it can be a problem for DB2 UDB for OS/390 and z/OS and Oracle.

See Rowset class: Sort method.

Parameters

返回值

The number of records read into the rowset.

Example

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

The following example reads all of the QA_MYRECORD records that have a MYRECORD field equal to the value of &UVAL into a rowset, and returns the number of rows read:

&NUM_READ = &RS.Fill("where MYRECORD = :1", &UVAL);

To re-use a WHERE clause for the wherestring you can use the SQL repository, and a SQL object.

&NUM_READ = &RS.Fill(SQL.MYWHERE, &UVAL);

The following example gets all the SET_CNTRL_REC rows related to the row on the page, then updates SETID with the value from the page. Fill is used with a rowset that was created from a message that was just created, that is, a rowset that was unpopulated.

If FieldChanged(SETID) Then &MSG = CreateMessage(OPERATION.SET_CNTRL_REC); &MSG_ROWSET = &MSG.GetRowset(); &MSG_ROWSET.Fill("where SETCNTRLVALUE =:1 and REC_GROUP_ID =:2", SETCNTRLVALUE,⇒ REC_GROUP_ID); For &I = 1 To &MSG_ROWSET.ActiveRowCount &MSG_ROWSET.GetRow(&I).SET_CNTRL_REC.SETID.Value = SETID; &MSG_ROWSET.GetRow(&I).PSCAMA.AUDIT_ACTN.Value = "C"; End-For; &MSG.Publish(); End-If;

When using the Fill method, the IsChanged property of each field in a part rowset is not set to true. Because the fields appear to be unchanged, this can create a problem for publication of data from Message rowsets. A technique to avoid this problem is to create a second rowset and use the CopyTo method to copy the changes to the Message rowset as shown in the following example:

&a = CreateMessage(Operation.MY_ASYNC); &rs = &a.GetPartRowset(1); &trs = CreateRowset(Record.PSPMAGENT); &trs.Fill("where PM_AGENTID >= 12345"); &trs.CopyTo(&rs); %IntBroker.Publish(&a);

The following example uses a correlation ID for the table in the Fill SELECT, to enable the use of correlated subqueries in the WHERE clause, such as the usual effective-date subquery:

&RSOWNER_NAME = CreateRowset(RECORD.PERSONAL_D00); &RSOWNER_NAME.Fill("where SETID=:1 AND EMPLID=:2 AND %EffDtCheck(PERSONAL_⇒ D00,FILL,:3)", &SETID, &EMPLID, &EFFDT);

The Fill method implicitly uses Fill as an alias for the Rowset record. This is helpful for complex Fill where clauses with subqueries.

&oprclasscountries = CreateRowset(Record.SCRTY_TBL_GBL); &oprclasscountries.Fill("WHERE FILL.OPRCLASS = :1 AND NOT EXISTS (SELECT 'X' FROM⇒ PS_SCRTY_SEC_GBL GBL2 WHERE GBL2.OPRCLASS = FILL.OPRCLASS AND GBL2.COUNTRY =⇒ FILL.COUNTRY AND GBL2.PNLNAME = :2)", &OPRCLASS, %Component);

In the following example, the necessary key field values are loaded into a rowset, then the following function is called, and the values are used as part of the Fill method.

Function FillRS2(); Local SQL &MySql; Local string &MySqlString; Local Record &ElemDefnRec; Local string &ElemDefnRecName, &fldname; Local Rowset &CompRec2RS; /* Build the record object that is used for building the SQL and executing the⇒ select */ &ElemDefnRec = CreateRecord(@("Record." | &pkgRecName)); /* Initialize the SQL string */ &MySqlString = "%SelectByKey(:1 A)"; /* Create a SQL to select a rows based on the key fields. */ For &i = 1 To &ElemDefnRec.FieldCount If &ElemDefnRec.GetField(&i).IsKey Then &fldname = &ElemDefnRec.GetField(&i).Name; &ElemDefnRec.GetField(&i).Value = &CompRec2RS.GetRow(1).GetRecord(@⇒ ("Record." | &pkgRecName)).GetField(@("Field." | &fldname)).Value; End-If; End-For; /* Create the SQL and execute the select */ &MySql = CreateSQL(&MySqlString); &MySql.Execute(&ElemDefnRec); /* Copy each selected row into the rowset */ While &MySql.Fetch(&ElemDefnRec) &ElemDefnRec.CopyFieldsTo(&CompRec2RS(&CompRec2RS.ActiveRowCount).GetRecord⇒ (1)); End-While; End-Function;

See Also

Rowset class: CopyTo method, Select method, FillAppend method.

SQL Class

CreateRowset

Using Related Language Tables

Syntax

FillAppend([wherestring [, bindvalue] . . .])

Description

The FillAppend method reads records from the database into successive rows of the rowset starting after the last row that exists in the rowset. Unlike Fill, it doesn’t first flush the rowset.

Note. FillAppend appends rows after the last active row in the rowset. If you have deleted rows in the rowset, they will still be the last rows.

When a rowset is selected into, any autoselected child rowsets are also read. The child rowsets are read using a where clause that filters the rows according to the where clause used for the parent rowset, using a subselect.

When a rowset is created using CreateRowset, it contains one empty row. If the rowset hasn’t been filled with data, FillAppend fills that row also (so you don’t have an empty row at the start of your rowset.)

The records are read from the database tables corresponding to the primary database record of the scroll into that record. The records are selected by the optional wherestring SQL clause, in which the optional bindvalues are substituted, using the usual bind placeholders (:n).

In general, use this method only with rowsets that were created using the CreateRowset function.

The actual number of records read into the rowset is an optional return of this method.

Note. This method does not work with Application Engine state records. Also, you cannot use this method in dynamic views.

When this method executes, unlike the Select method, it does not cause any associated PeopleCode to run as part of reading data into the rowset.

Note. FillAppend reads only the primary database record. It does not read any related records, nor any subordinate rowset records.

For every record read with the FillAppend method, if the set language is not the base language and the record has related language records, the FillAppend method tries to read the related language record and does related language processing.

The FillAppend method uses a correlation ID of FILLAPPEND for the table it reads. You must use the correlation ID if you want to refer to the rowset table name as part of the wherestring. You receive a runtime error if you use the table name as a column prefix instead of the correlation ID.

Parameters

Returns

The number of records read into the rowset.

Example

The following example reads all of the QA_MYRECORD records that have a MYRECORD field equal to the value of &UVAL into a rowset, and returns the number of rows read:

&NUM_READ = &RS.FillAppend("where MYRECORD = :1", &UVAL);

To re-use a WHERE clause for the wherestring you can use the SQL repository, and a SQL object.

&NUM_READ = &RS.FillAppend(SQL.MYWHERE, &UVAL);

See Also

Rowset class: CopyTo method, Select method, Fill method.

SQL Class

CreateRowset

Using Related Language Tables

Syntax

Flush()

Description

Use the Flush method to remove all rows from the rowset and free its associated buffer. Rows that are flushed are not deleted from the database. This function is often used to clear a work scroll before using the Select method.

Note. Flush always leaves one row in the scroll.

You cannot flush the current context of the executing program. This means Flush cannot be used for the rowset containing the executing program, or in any child rowset and executed against the parent rowset. Place your PeopleCode in a parent rowset and execute it against a child rowset.

For rowsets corresponding to component buffer data, the Flush method executes in turbo mode only—that is, default processing is performed, but only on the row being flushed. Additional information on turbo mode and non-turbo mode is available in the documentation with the InsertRow PeopleCode built-in function.

See InsertRow.

If a grid has a user personalized sort defined for it and your PeopleCode program flushes that grid and then repopulates it (for instance, through a Fill, a Select, or a series of InsertRow calls), this could invalidate the user's personalized sort and the current row in the user's view unless your PeopleCode program makes arrangements to reapply these user personalizations.

After flushing and repopulating the rowset, your PeopleCode program should re-sort the rowset (that is, re-sort the grid). If the user has a personalized sort, then the user's personalized sort will be reapplied via the PeopleCode sort.

Also, after flushing and repopulating a grid, it will be important to manage which row is deemed the current row. This can be managed using methods such as IsUserSorted, GetFirstUserSortedRow, MapBufRowToUserSortRow, and then by setting the TopRowNumber property accordingly.

See Rowset class: IsUserSorted method.

Parameters

None.

Returns

None.

Example

The following example checks for the value of the field CHECKLIST_CD. If something exists in this field, the second level rowset is flushed and new values are selected into it.

If All(CHECKLIST_CD) Then &RS1H.Flush(); &RS1H.Select(RECORD.CHECKLIST_ITEM, "where Checklist_CD = :1 and EffDt = ⇒ (Select Max(EffDt) from PS_CHECKLIST_ITEM Where CheckList_CD = :2)", CHECKLIST_CD,⇒ CHECKLIST_CD); End-If;

See Also

Rowset class: FlushRow method, DeleteRow method, InsertRow method.

Syntax

FlushRow(n)

Description

Use the FlushRow method to remove a specific row from a rowset and from the Component buffer. Rows that are flushed are not deleted from the database.

FlushRow is a specialized and infrequently used method. In most situations, you want to use DeleteRow to remove a row from the Component buffer and remove it from the database as well when the component is saved.

You cannot flush the current context of the executing program. This means FlushRow cannot be used for the rowset containing the executing program, or in any child rowset and executed against the parent rowset. Place your PeopleCode in a parent rowset and execute it against a child rowset.

Parameters

Returns

None.

Example

&ROWSET.FlushRow(&ROWNUMBER);

See Also

Rowset class: DeleteRow method, Flush method, InsertRow method.

Syntax

GetCurrEffRow()

Description

GetCurrEffRow returns a row object for the row with the current effective date. This includes dates equal to the current date, but not dates in the future. If the primary record associated with the rowset is not effective-dated this method returns a null object.

Newly inserted rows are intentionally skipped when looking for the current effective-dated row. This is to find the current effective row from the data that already exists in the database. In other words, a row cannot be considered as a current effective row until it is saved. To find the current effective-dated row in data that has been newly inserted and not yet saved, use the GetNewEffRow method instead.

Parameters

None.

Returns

A row object for the row with the current effective date.

Example

&tmp = &ROWSET.GetCurrEffRow().RowNumber; /* note RowNumber is a property of the row class */

See Also

Rowset class: DeleteEnabled property, GetRow method, GetNextEffRow method, GetNewEffRow method.

GetRow

Syntax

GetFirstUserSortedRow(GridName)

Description

Use this method to get the first row from a sort view.

Parameters

Returns

A row object for the first row from the sort view.

If the grid has not been sorted, the output row object is equivalent to the first row from the rowset.

See Also

IsUserSorted

Syntax

GetLastUserSortedRow(GridName [, visible])

Description

Use this method to get the last row from a sort view.

Parameters

Returns

A row object for the last row from the sort view (visible is true) or the absolute last row from the rowset (visible is false).

See Also

IsUserSorted

Syntax

GetNewEffRow()

Description

GetNewEffRow returns a row object for the row with the effective date closest to the current date, including newly inserted rows. This means dates equal to the current date, but not future dates. If the primary record associated with the rowset is not effective-dated this method returns a null object.

To find the current effective-dated row from the data that already exists in the database, that is, only from saved rows and not a newly created row, use the GetCurEffRow method instead.

Parameters

None.

Returns

A row object for the row with the current effective date.

Example

Local Row &MyRow = &ROWSET.GetNewEffRow();

See Also

GetRow, GetNextEffRow, GetCurrEffRow.

DeleteEnabled

GetRow

Syntax

GetRow(n)

Description

GetRow returns a row object from a rowset. This is a default method for rowsets. This means that any rowset object, followed by a parameter list, acts as if GetRow is specified.

Parameters

Returns

Returns a row object for the specified row of the rowset.

Example

In the following example, all of the lines of code do the same thing: they return the 5th row from the rowset (&ROWSET is a rowset object.)

&ROW = GetRowset().GetRow(5); &ROW = GetRowset()(5); &ROW = &ROWSET.GetRow(5); &ROW = &ROWSET(5);

The following example loops through all the rows in a rowset:

Local rowset &LEVEL1; Local row &ROW; &LEVEL1 = GetRowset(SCROLL.EMPL_CHECKLIST); For &I = 1 to &LEVEL1.ActiveRowCount &ROW = &LEVEL.GetRow(&I); /* do some processing */ End-For;

See Also

GetRow.

Syntax

HideAllRows()

Description

HideAllRows hides all rows of the rowset. Using this method is equivalent to a loop setting the visible property of each row of the rowset to False.

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

Parameters

None.

Returns

None.

Example

The following example hides the second level scroll if a value exists in the NO_COMMENTS field in the first level of the scroll. The code is running from the first level of the scroll.

Local Rowset &RS1, &RS2; &RS1 = GetRowset(); &RS2 = GetRowset(SCROLL.EMPL_CHKLST_ITM); For &I = 1 to &RS1.ActiveRowCount If ALL(&RS1.GetRow(&I).EMPLOYEE_CHECKLIST.NO_COMMENTS) Then &RS2.HideAllRows(); End-If; /*other processing */ End-For;

See Also

ShowAllRows, Visible.

Syntax

InsertRow(n)

Description

InsertRow programmatically performs the ALT+7 and ENTER (RowInsert) function. InsertRow inserts a new row in the current rowset after the row specified by the parameter if the primary record for the rowset is not effective-dated or a standalone rowset. If the primary record for the rowset is effective-dated or a standalone rowset, the new row is inserted before the current row, and all values from the current row are copied into the new row, except for EFFDT, which is set to the current date.

In addition, InsertRow propagates the keys from the higher level (if any) into the inserted row.

If the program is being run from a component against Component buffer data, a RowInit PeopleCode event also fires, followed by the events that normally follow a RowInsert, as if the user had manually pressed ALT+7 and ENTER.

The InsertRow method can be executed against the same rowset where the insertion will take place.

For rowsets corresponding to component buffer data, the InsertRow method executes in turbo mode only—that is, default processing is performed, but only on the row being inserted. Additional information on turbo mode and non-turbo mode is available in the documentation with the InsertRow PeopleCode built-in function.

See InsertRow.

InsertRow cannot be executed from the same rowset where the insertion will take place, or from a child rowset against a parent. Place your PeopleCode in a parent rowset and execute it against a child rowset.

Note. If you use InsertRow on a rowset created using the CreateRowset function, the row isn't automatically inserted in the database when the page is saved. 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.

When a row is inserted, if that row contains child scrolls, this method also inserts an empty row for any child scrolls. The effective-date field for this empty row is also empty. The current date is not used.

Parameters

Returns

An optional Boolean value: True if the row is inserted, False if the row is not inserted.

Example

In the following example, as the primary database record isn’t effective-dated, the new row is inserted after the second row in the rowset.

&ROWSET.InsertRow(2);

See Also

DeleteRow, Delete.

Using Standalone Rowsets

Syntax

IsUserSorted(GridName)

Description

Use this method to determine whether a user sort has been performed on the specified grid.

A user sort is defined as a user either having clicked on a column heading on the grid or having applied a sort order on the grid’s customization page. In the case of a user sort, a sort view is created based on the sort order defined by the user. Since this sort view is for display purposes only, the underlying buffer is not sorted and remains in the non-sorted order. Four additional methods (GetFirstUserSortedRow, GetLastUserSortedRow, MapBufRowToUserSortRow, and MapUserSortRowToBufRow) enable you to interrogate this sort view. These methods can be used to map the sort view to the buffer, to map the buffer to the sort view, to retrieve the first user-sorted row, and to retrieve the last user-sorted row.

Note. When a grid includes a hyperlink field that is user-sortable, the hyperlink label must be set in PeopleCode prior to allowing the user to perform the sort. Alternatively, the buffer can be sorted on the hyperlink field in PeopleCode upon entry into the page.

Parameters

Returns

A Boolean value: true if a user sort has been performed on the grid, false otherwise.

See Also

GetFirstUserSortedRow, GetLastUserSortedRow, MapBufRowToUserSortRow, MapUserSortRowToBufRow, Sort.

Syntax

MapBufRowToUserSortRow(GridName, number)

Description

Use this method to return the sort view row number that corresponds to the specified buffer row number.

Parameters

Returns

The row number, as a number, of the row in the sort view.

If the grid has not been sorted, the output row number is the same as the buffer row number.

Example

&szSortViewName = "QE_PIA_SORT_GRID1.L2RSSORTTEST"; Local Rowset &rsCurrent = GetLevel0()(1).GetRowset(Scroll.QE_PIA_SORTEST2)(1).Get⇒ Rowset(Scroll.QE_PIA_SORTEST3); If &rsCurrent.IsUserSorted(&szSortViewName) Then WinMessage("QE_PIA_SORT_GRID1-Rowset1 User Sorted"); Else WinMessage("QE_PIA_SORT_GRID1-Rowset1 Not User Sorted"); End-If; For &I = 1 To &rsCurrent.ActiveRowCount &index = &rsCurrent.MapBufRowToUserSortRow(&szSortViewName, &I); WinMessage("QE_PIA_SORT_GRID1-Rowset1, Buffer Row Index: " | &I | ", Sort Row⇒ Index: " | &index | ", Description: " | &rsCurrent(&I).QE_PIA_⇒ SORTEST3.DESCR30.Value); End-For;

See Also

IsUserSorted

Syntax

MapUserSortRowToBufRow(GridName, number)

Description

Use this method to return the buffer row number that corresponds to the specified sort view row number.

Parameters

Returns

The row number, as a number, of the row in the buffer.

If the grid has not been sorted, the output row number is the same as the buffer row number.

Example

&szSortViewName = "QE_PIA_SORT_GRID1.L2RSSORTTEST"; Local Rowset &rsCurrent = GetLevel0()(1).GetRowset(Scroll.QE_PIA_SORTEST2)(2).Get⇒ Rowset(Scroll.QE_PIA_SORTEST3); If &rsCurrent.IsUserSorted(&szSortViewName) Then WinMessage("QE_PIA_SORT_GRID1-Rowset2 User Sorted"); Else WinMessage("QE_PIA_SORT_GRID1-Rowset2 Not User Sorted"); End-If; For &I = 1 To &rsCurrent.ActiveRowCount &index = &rsCurrent.MapUserSortRowToBufRow(&szSortViewName, &I); WinMessage("QE_PIA_SORT_GRID1-Rowset2, Description: " | &rsCurrent(&index).QE_⇒ PIA_SORTEST3.DESCR30.Value); End-For;

See Also

IsUserSorted

Syntax

Refresh()

Description

Refresh reloads the rowset object from the database using the current page keys. This causes the page to be redrawn. The following code example refreshes the entire page:

GetLevel0().Refresh()

Important! Do not call GetLevel0().Refresh() from any context that is not at level 0. You are likely to leave invalid pointers to objects that have been cleared from the buffer, which can result in an application server crash.

If you only want a specific scroll to be redrawn, you can use the refresh method with that rowset. You don’t have to use a level zero rowset with this method. This is particularly useful after using RemoteCall.

Note. If a scroll is marked as No Auto Select in Application Designer, Refresh will not work on it. The Refresh method clears the existing buffers and does a refresh from the database. You do not want to use this method if your rowset is based on message data. Instead, you can use the CopyTo Rowset method combined with TransferPage.

Parameters

None.

Returns

None.

Example

The following example refreshes the entire page.

&Mylevel0 = GetLevel0().Refresh();

The following example refreshes only the second level scroll of the page:

&RowSetLevel2.Refresh();

See Also

Rowset class: CopyTo method.

RemoteCall

TransferPage

Syntax

Select([parmlist], RECORD.selrecord [, wherestr, bindvars])

Where paramlist is a list of child rowsets, given in the following form:

SCROLL.scrollname1 [, SCROLL.scrollname2] . . .

The first scrollname must be a child rowset of the rowset object executing the method, the second scrollname must be a child of the first child, and so on.

Description

Select, like the related method SelectNew, reads data from the database tables or views into either a row or rowset object.

Note. This method is valid only when used with rowsets that reference data from the component buffers. You cannot use this method with a message rowset, a rowset from an Application Engine state record, and so on. You can’t use this method with rowsets created using the CreateRowset function (use the Fill method instead.)

Select automatically places child rowsets in the rowset object executing the method under the correct parent row. If it cannot match a child rowset to a parent row, an error occurs.

When a rowset is selected into, any autoselected child rowsets is also read. The child rowsets are read using a where clause that filters the rows according to the where clause used for the parent rowset, using a subselect.

If you don’t specify any child rowsets in paramlist, Select selects from a SQL table or view specified by selrecord into the rowset object executing the method.

If you specify a child rowset in paramlist, Select selects from a SQL table or view specified by selrecord into the child rowset specified in paramlist, under the appropriate row of the rowset executing the method.

If the rowset executing the method is a level zero rowset, and you specify Select without specifying any child rowsets with paramlist, the method reads only a single row, because only one row is allowed at level zero.

The rowset executing the method does not have to be a level zero rowset, so the Select method can produce the functionality of both the ScrollSelect and RowScrollSelect functions.

Note. For developers familiar with previous releases of PeopleCode: If the rowset executing the method is a level zero rowset, and you specify a child rowset with paramlist, this method functions exactly like ScrollSelect. If the rowset executing the method is not a level zero rowset, and no child rowsets are specified with paramlist, the method acts like RowScrollSelect.

The record definition of the table or view being selected from is called the select record, and identified with RECORD. selrecord. The select record can be the same as the primary database record associated with the rowset, or it can be a different record definition that has compatible fields. If you define a select record that differs from the primary database record for the rowset, you can restrict the number of fields that are loaded into the buffers on the client workstation by including only the fields that you actually need.

Select accepts a SQL string that can contain a WHERE clause restricting the number of rows selected into the object. The SQL string can also contain an ORDER BY clause to sort the rows.

Select and its related methods generate a SQL SELECT statement at runtime, based on the fields in the select record and the WHERE clause passed to them in the method parameters.

For rowsets corresponding to component buffer data, the Select method executes in turbo mode only—that is, default processing is performed, but only on the row being selected. Additional information on turbo mode and non-turbo mode is available in the documentation with the InsertRow PeopleCode built-in function.

See InsertRow.

Parameters

Returns

The number of rows read (optional.) This counts only the lines read into the specified rowset. It does not include any additional rows read into any child rowsets of the rowset.

Example

The following example selects into the level zero rowset, only one row. Depending on the autoselect settings on any child scrolls, they may be reselected too.

&LEVEL0 = GetLevel0(); &LEVEL0.Select(RECORD.PERSONAL_DATA, "WHERE. . .");

The following example selects into the level one scroll specified. Depending on the autoselect settings on any child (level two) scrolls, they may also be selected.

&LEVEL0.Select(SCROLL.EMPL_CHECKLIST, RECORD.EMPL_CHECKLIST, "WHERE. . .");

The following example selects into the child scroll of the level one rowset. Each row fetched is placed under the appropriate row in &LEVEL1. Note that instead of hard-coding the WHERE clause, the SQL repository is used to access a SQL definition named SELECT_WHERE.

&LEVEL1 = &LEVEL0()(1).GetRowset(SCROLL.EMPL_CHECKLIST); &LEVEL1.Select(SCROLL.EMPL_CHKLST_ITM, RECORD.EMPL_CHKLST_ITM, SQL.SELECT_WHERE);

The following example first flushes the hidden work scroll, then selects into it based on a field on the page.

&RS1H.Flush(); &RS1H.Select(RECORD.CHECKLIST_ITEM, "where Checklist_CD = :1 and EffDt = (Select⇒ Max(EffDt) from PS_CHECKLIST_ITEM Where CheckList_CD = :2)", CHECKLIST_CD,⇒ CHECKLIST_CD);

See Also

SelectNew, SelectByKey.

Syntax

SelectNew([parmlist], RECORD.selrecord [, wherestr, bindvars])

Where paramlist is a list of child rowsets, given in the following form:

SCROLL.scrollname1 [, SCROLL.scrollname2] . . .

The first scrollname must be a child rowset of the rowset executing the method, the second scrollname must be a child of the first child, and so on.

Description

The SelectNew method is similar to the Select method, except that all rows read into the rowset are marked new so they are automatically inserted into the database at Save time. This capability can be used, for example, to insert new rows into the database by selecting data using a view of columns from other database tables.

Note. This method is valid only when used with rowsets that reference data from the Component buffers. You cannot use this method with a message rowset, a rowset from an Application Engine state record, and so on. You can’t use this method with rowsets created using the CreateRowset function (use the Fill method instead.)

Parameters

Returns

The number of rows read (optional.) This counts only the lines read into the specified rowset. It does not include any additional rows read into any child rowsets of the rowset.

Example

The following example selects rows from DATA2 and reads them into a level one scroll. If the user saves the page, these rows are inserted into DATA1.

&LEVEL0.SelectNew(SCROLL.DATA1, RECORD.DATA2, "Where SETID = :1 and CUST_ID =:2",⇒ CUSTOMER.SETID, CUSTOMER.CUST_ID);

If you use the same WHERE clause in more than one Select, you may want to use the SQL repository to store the SQL fragment. That way, if you ever want to change it, you will have to change it in only one place.

&LEVEL0.SelectNew(SCROLL.DATA1, RECORD.DATA2, SQL.Select_New);

See Also

Select, SelectByKey.

Syntax

SetDefault(recname.fieldname)

Description

The SetDefault method sets the value of the specified recname.fieldname to a null value in every row of the rowset. If this method is being run from a component against Component buffer data, the next time default processing is performed, this value is reinitialized to its default value: either a default specified in its record field definition or one set programmatically by PeopleCode located in a FieldDefault event. If neither of these defaults exist, the Component Processor leaves the field blank.

No default processing is performed against data that is not in the Component buffers.

Blank numbers correspond to zero on the database. Blank characters correspond to a space on the database. Blank dates and long characters correspond to NULL on the database. SetDefault gives each field data type its proper value.

Parameters

Returns

None.

Example

This example resets the PROVIDER to its null value. This field is reset to its default value when default processing is next performed:

If COVERAGE_ELECT = "W" Then &ROWSET.SetDefault(INS_NAME_TBL.PROVIDER); End-if;

See Also

Field class: SetDefault method.

Default Processing

Syntax

ShowAllRows()

Description

ShowAllRows "unhides" all rows of the rowset object executing the method. Using this method is equivalent to a loop setting the visible property of each row of the rowset to True.

ShowAllRows cannot be executed from the same rowset you want to display, or from a child rowset against a parent. Place your PeopleCode in a parent rowset and execute it against a child rowset.

Parameters

None

Returns

None.

Example

&ROWSET.ShowAllRows();

See Also

HideAllRows, Visible.

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

Description

This property returns the number of active (non-deleted) rows in the rowset.

This property returns a value of 1 for an empty scroll (Flush always leaves an empty row.) You can use the IsChanged or IsNew properties to verify if the row is new.

This property is read-only.

Example

&tmp = &ROWSET.ActiveRowCount;

Description

Normally, if a field value is changed, whether through PeopleCode or by an end user, the IsChanged property for the row is set to True. The exception to this is when a change is done in the FieldDefault or FieldFormula event, that is, if a value is set in one of these events, the row is not marked as changed.

At save time, all newly inserted and changed rows are written to the database. All newly inserted but not changed rows are not written to the database.

Use this property to specify whether a change made to a new row from RowInit or RowInsert PeopleCode is marked as changed. This property takes a Boolean value. The default value is True.

Setting this property to False causes changes to fields for the rowset done in RowInit and RowInsert PeopleCode to not mark a new row as IsChanged.

This property is read-write.

Description

This property specifies whether the view of a data area is collapsed or expanded.

Note. You must set the Collapsible Data Area field on the properties for the level-based control for this property to have any effect.

This property changes to reflect the current state of the data area, according to whether the user has collapsed or expanded it. Changing the value collapses or expands the data area, but it does not prevent the user from collapsing (or expanding) it themselves.

Note. Because the user can change the value of this property, whatever value is set in PeopleCode isn’t guaranteed to be still set the next time it is checked, because the user may have collapsed or expanded the data area in the meantime.

This property overwrites the value of the Default Initial View to Expanded field set in Application Designer. For example, if Default Initial View to Expanded is selected in Application Designer, then the value for the DataAreaCollapsed property is set to True, the control initially displays collapsed.

This property takes a Boolean value: True, initially display the data area collapsed, False, initially display the data area expanded.

This property is read-write.

Note. To collapse just a group box, use the DataAreaCollapsed field method.

See Also

Field class: DataAreaCollapsed property.

Example

The following example checks the number of rows in the level one rowset. If the number of rows returned is larger than 100, the data area is initially displayed collapsed.

If &Level1.RowCount > 100 Then &Level1.DataAreaCollapsed = True; Else &Level1.DataAreaCollapsed = False; End-If;

Description

This property returns the name of the primary database record as a string for the rowset.

This property is read-only.

Example

&DBNAME = &ROWSET.DBRecordName;

Description

This property determines whether a rowset allows rows to 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.

The initial value of this property depends on how the scroll was created at design time. If the No Row Delete setting is selected on the Use tab of the scroll properties dialog box, DeleteEnabled will be False: otherwise it will be True.

Note. If No Row Delete is selected in Application Designer, setting DeleteEnabled to True will not override this value. To control whether a rowset allows deletions at runtime, you should not select No Row Delete at design time.

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

For rowsets 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 rowsets that are 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, InsertEnabled property.

Using Scroll Areas and Scroll Bars

Using Standalone Rowsets

Description

This property references the effective date of the primary record associated with the rowset. If the primary record associated with the rowset is not effective-dated, this property has a null value. To find the primary record associated with a rowset object, you can use the DBRecordName property.

Note. This property isn’t valid with rowsets created using the CreateRowset function.

This property is read-only.

Example

&tmp = &ROWSET.EffDt;

See Also

CreateRowset.

Description

This property references the effective-sequence number of the primary record associated with the rowset. If the primary record associated with the rowset does not have an effective-sequence number, this property has the value 0. To find the primary record associated with a rowset object, you can use the DBRecordName property.

Note. This property isn’t valid with rowsets created using the CreateRowset function.

This property is read-only.

Example

&tmp = &ROWSET.EffSeq;

See Also

CreateRowset.

Description

This property determines whether a rowset allows rows to be inserted (the equivalent of the user pressing ALT+7 and ENTER). This property takes a Boolean value.

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

The initial value of this property depends on a value set at design time. If the No Row Insert setting is selected on the Use tab of the scroll properties dialog box, InsertEnabled is False: otherwise it is True.

Note. If No Row Insert is selected in Application Designer, setting InsertEnabled to True does not override this value. To control whether a rowset allows inserts at runtime, you should not select No Row Insert at design time.

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

For rowsets 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 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

Description

This property is True if an error has been found on any field in any record in any row or child rowset of the current rowset after executing the ExecuteEdits method on either a message object or a record object. This property can be used with the Field Class properties EditError (to find the field that’s in error), 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 ExecuteEdits could be used:

&REC.ExecuteEdits(); If &ROWSET.IsEditError Then For &I = 1 to &ROWSET.ActiveRowCount &ROW = &ROWSET(&I); For &J to &ROW.RecordCount &REC = &ROW.GetRecord(&J); For &K = 1 to &REC.FieldCount If &REC.GetField(&K).EditError Then LOG_ERROR(); /* application specific call */ End-If; End-For; End-For; End-For; End-If;

See Also

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

Description

This property refers to the name of the rowset. This property returns different values, based on the type of rowset.

This property is read-only.

Example

&tmp = &ROWSET.Name;

Description

This property returns a row object containing a reference to the parent row, that is, the row containing the rowset. If this is a top-level rowset (level zero), the ParentRow property has a null value.

This property is read-only.

Example

&tmp = &ROWSET.ParentRow.RowNumber; /* note that RowNumber is a property of the row class */

Description

This property returns a rowset object containing a reference to the parent rowset, that is, the rowset containing the rowset. If this is a top-level rowset (level zero), the ParentRowset property has a null value.

This property is read-only.

Example

&tmp = &ROWSET.ParentRowset.Level; /* note Level is another property of the rowset class */

Description

This property returns the total number of rows in the rowset. It includes deleted rows. (The ActiveRowCount property doesn’t include deleted rows.)

This property is read-only.

Example

&tmp = &ROWSET.RowCount;

Description

This property determines whether any changes to the rowset using PeopleCode marks the component as changed and the data written to the database if the rowset is not a based on a derived/work record.

This property takes a Boolean value: true, changes to the rowset mark the component as changed, false, the component is treated as if unchanged. The default is true.

If you set this property to false, this means that no row insert, row delete, field change on the rowset using PeopleCode would cause the system to treat the component data as changed.

The SetComponentChanged rowset class property overrides the SetComponentChanged field class property. If a field has SetComponentChanged set to true, but its associated rowset has SetComponentChanged set to false, any change to the field does not mark the component as changed.

This property is read-write.

See Also

SetComponentChanged

Description

This property returns the row that is being displayed at the top of the scroll (if any) for the rowset.

Generally, this property is used to return the top row number of a scroll. However, sometimes you want to reposition the scroll. For example, if you use SetCursorPos to move the focus to a given field, there is no guarantee that the row containing the field is at the top of the scroll.

This property is read-write.