Getfield Peoplecode Scroll 1
In this section, we discuss the Rowset class methods. The methods are discussed in alphabetical order.
ClearDeletesChanges
Description
Peoplecode Error'GetField: -Field REQLINEWRK.ACCOUNTCODE not found in scroll level 0. (2155) PVREQMASSCHGSEC.Activate' When Clicking on Mass Change Link on ePro Requisition (Doc ID 2267471.1) Last updated on FEBRUARY 10, 2019.
Use the ClearDeletesChanges method to clear deletedrows 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 deletedrows
it only applies to standalonerowsets
This method first clears the deleted rows, thatis, all rows that have been deleted using DeleteRow are removed fromthe rowset and their associated buffers are freed.
This method then clears changed rows. That meansany changes done on a row (such as field values changed) or newlyinserted rows are now propagated into their original state and thechanged 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 astandalone rowset to track changes you need to make to some businessprocess or object. After doing the appropriate database updates toreflect changes recorded in the rowset (that is, inserts or deletesor changes), you call this method to clean up the rowset in preparationfor further processing. Without this method, newly inserted rows andchanged rows preserve their IsNew and IsChanged status indefinitely,complicating program logic and potentially leading to duplicate insertsor deletes.
Returns
None.
CopyTo
Syntax
Where record_list is a list of record names in the form:
Description
The CopyTo method copies from the rowset executing the method to the specified destination rowset, copying like-named record fields and subscrollsat corresponding levels.
The CopyTo method uses the current data in the rowset.This might be different from the original data values if the rowsetwas retrieved from the database and values in it have been changedeither by an end-user or a PeopleCode program
If pairs of source and destination record namesare 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 Enginestate records. If you don’t specify record_list, both the record name and the field name have to match exactlyfor data to be copied from one record field to another. If you specify record_list, after the records have beenpaired 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 MessageNumberand MessageSetNumber properties set, these values are copied to therowset you are copying to. For example, suppose you had an applicationmessage 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 intoa work rowset, and use the work rowset to populate Component buffers. (After the field properties are set, the Record, Row, and Rowsetproperties IsEditError also get set.)
Parameters
| &DestRowset | Specifythe rowset to be copied to. This rowset object must have alreadybeen instantiated. |
| SourceRecname | Specifya record to be copied from, in the rowset object being copied from. |
| DestRecname | Specify a recordto be copied to, in the rowset object to be copied to. |
Example
If you set one rowset equal to another, you haven’tmade a copy of the rowset. Instead, you have two variables pointingto the same data.
To make a clone of an existing rowset, that is,to make two distinct copies, you can do the following:
The following example copies data from one rowsetobject to another. Because no like-named records exist between thetwo rowsets, the record names are specified. Only the like-namedfields are copied from one rowset to the other:
The following example copies data from a messageinto the Component buffers, then calls the page (using TransferPage)to redraw the page. You could do this to fill a page with messagedata that is in error, so that an end-user can make corrections tothe message data. &WRK_ROWSET0 is the level zero rowset and &WRK_ROWSET1is where the data is copied to.
DeleteRow
Description
The DeleteRow method deletes the row in the rowsetidentified by the parameter.
If the program is being run from a component againstComponent buffer data, a RowDelete PeopleCode event also fires, followedby the events that normally follow a RowDelete, as if the user hadmanually pressed ALT+8 and ENTER.
This method initially marks the row as needing tobe deleted. At save time the row is actually deleted from the databaseand cleared from the buffer. When the row is marked as deleted, itis ignored by other methods, such as GetCurrEffRow, Sort, and so on.
DeleteRow cannot be executed from the same rowsetwhere the deletion takes place, or from a child rowset against a parent. Place your PeopleCode in a parent rowset and execute it against achild rowset.
When DeleteRow is used in a loop, you have to processrows from high to low to achieve the correct results, that is, youmust delete from the bottom up rather than from the top down. Thisis 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 theCreateRowset function, the row isn't automatically deleted in thedatabase when the page is saved. Rowsets created using the CreateRowsetfunction are standalone rowsets, not tied to the database, so thereare no database updates when they are manipulated. Delete and insertactivity on these types of rowsets aren't automatically applied atsave time.
Parameters
| n | An integeridentifying a row within the rowset object. This must be >= 1 and<= the number of active rows in the rowset (see ActiveRowCount). |
Returns
An optional Boolean value: True if row is deleted,False otherwise.
Example
In the following example DeleteRow is used in aFor loop. The example checks a value in each row, then conditionallydeletes the row. Note the syntax of the For loop, including the useof 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.
Fill
Description
The Fill method flushes the rowset then reads recordsfrom the database into successive rows. The records are read fromthe database tables corresponding to the primary database record ofthe scroll into that record. The records are selected by the optional wherestring SQL clause, in which the optional bindvalues are substituted, using the usualbind placeholders (:n).
In general, use this method only with rowsets thatwere 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 rowsetis an optional return of this method.
Note: This method does not work with Application Enginestate records. Also, you cannot use this method in dynamic views.
When this method executes, unlike the Select method,it does not cause any associatedPeopleCode to run as part of reading data into the rowset.
Note: Fill reads only the primary database record. Itdoes not read any related records, nor any subordinate rowset records.
For every record read with the Fill method, if theset language is not the base language and the record has related languagerecords, the Fill method tries to read the related language recordand does related language processing.
The Fill method uses a correlation ID of FILL forthe table it reads. You must use the correlation ID if you want torefer to the rowset table name as part of the wherestring. You receive a runtime error if you use thetable name as a column prefix instead of the correlation ID.
Sorting Considerations
Rows come unsorted from the database when usingFill. This is not a problem for SQL server, however, it can be a problemfor DB2 UDB for OS/390 and z/OS and Oracle.
See Sort.
Parameters
| wherestring | Specifya SQL WHERE clause to use for selecting records to fill the rowset. This can be a string or a SQL definition. |
| bindvalue | Specifyoptional bind variables to be used with the WHERE clause. |
Returns
The number of records read into the rowset.
Example
The following example reads all of the QA_MYRECORDrecords into a rowset, and returns the number of rows read:
The following example reads all of the QA_MYRECORDrecords that have a MYRECORD field equal to the value of &UVALinto a rowset, and returns the number of rows read:
To re-use a WHERE clause for the wherestring you can use the SQL repository,and a SQL object.
The following example gets all the SET_CNTRL_RECrows related to the row on the page, then updates SETID with the valuefrom the page. Fill is used with a rowset that was created from amessage that was just created, that is, a rowset that was unpopulated.
When using the Fill method, the IsChanged propertyof each field in a part rowset is not set to true. Because the fieldsappear to be unchanged, this can create a problem for publicationof data from Message rowsets. A technique to avoid this problem isto create a second rowset and use the CopyTo method to copy the changesto the Message rowset as shown in the following example:
The following example uses a correlation ID forthe table in the Fill SELECT, to enable the use of correlated subqueriesin the WHERE clause, such as the usual effective-date subquery:
The Fill method implicitly uses Fill as an aliasfor the Rowset record. This is helpful for complex Fill where clauses with subqueries.
In the following example, the necessary key fieldvalues are loaded into a rowset, then the following function is called,and the values are used as part of the Fill method.
FillAppend
Description
The FillAppend method reads records from the databaseinto successive rows of the rowset starting after the last row that exists in the rowset. UnlikeFill, it doesn’t first flush the rowset.
Note: FillAppend appends rows after the last active row in the rowset. If you have deletedrows in the rowset, they will still be the last rows.
When a rowset is selected into, any autoselectedchild rowsets are also read. The child rowsets are read using a whereclause that filters the rows according to the where clause used forthe parent rowset, using a subselect.
When a rowset is created using CreateRowset, itcontains 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 atthe start of your rowset.)
The records are read from the database tables correspondingto the primary database record of the scroll into that record. Therecords 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 thatwere created using the CreateRowset function.
The actual number of records read into the rowsetis an optional return of this method.
Note: This method does not work with Application Enginestate records. Also, you cannot use this method in dynamic views.
When this method executes, unlike the Select method,it does not cause any associatedPeopleCode 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 rowsetrecords.
For every record read with the FillAppend method,if the set language is not the base language and the record has relatedlanguage records, the FillAppend method tries to read the relatedlanguage record and does related language processing.
The FillAppend method uses a correlation ID of FILLAPPENDfor the table it reads. You must use the correlation ID if you wantto refer to the rowset table name as part of the wherestring. You receive a runtime error if you use thetable name as a column prefix instead of the correlation ID.
Parameters
| wherestring | Specifya SQL WHERE clause to use for selecting records to fill the rowset. This can be a string or a SQL definition. |
| bindvalue | Specifyoptional bind variables to be used with the WHERE clause. |
Returns
The number of records read into the rowset.
Example
The following example reads all of the QA_MYRECORDrecords that have a MYRECORD field equal to the value of &UVALinto a rowset, and returns the number of rows read:
To re-use a WHERE clause for the wherestring you can use the SQL repository,and a SQL object.
Flush
Description
Accessing Level 2 Scroll Peoplecode
Use the Flush method to remove all rows from therowset and free its associated buffer. Rows that are flushed arenot deleted from the database. This function is often used to cleara work scroll before using the Select method.
Note: Flush always leaves one row in the scroll.
You cannot flush the current context of the executingprogram. This means Flush cannot be used for the rowset containingthe executing program, or in any child rowset and executed againstthe parent rowset. Place your PeopleCode in a parent rowset and executeit against a child rowset.
For rowsets corresponding to component buffer data,the Flush method executes in turbo mode only—that is, default processingis performed, but only on the row being flushed. Additional informationon turbo mode and non-turbo mode is available in the documentationwith the InsertRow PeopleCode built-in function.
See InsertRow.
Considerations When Initializing New Rows
Flush removes all rows and inserts a row.
If you want to initialize the row, that is, havethe defaults and any RowInit PeopleCode run, you must do somethingto invoke the default value processing. This can be as simple as settingthe value of another field on the same page that has a PeopleCodeprogram associated with it.
If the rowset is created from message data, anApplication Engine program, and so on, the rows are flushed but therow that is inserted is not initialized.
Considerations for User-Sorted Grids
If a grid has a user personalized sort defined forit and your PeopleCode program flushes that grid and then repopulatesit (for instance, through a Fill, a Select, or a series of InsertRowcalls), this could invalidate the user's personalized sort and thecurrent row in the user's view unless your PeopleCode program makesarrangements to reapply these user personalizations.
After flushing and repopulating the rowset, yourPeopleCode program should re-sort the rowset (that is, re-sort thegrid). If the user has a personalized sort, then the user's personalizedsort will be reapplied via the PeopleCode sort.
Also, after flushing and repopulating a grid, itwill be important to manage which row is deemed the current row. Thiscan be managed using methods such as IsUserSorted, GetFirstUserSortedRow,MapBufRowToUserSortRow, and then by setting the TopRowNumber propertyaccordingly.
See IsUserSorted.
Returns
None.
Example
The following example checks for the value of thefield CHECKLIST_CD. If something exists in this field, the secondlevel rowset is flushed and new values are selected into it.
FlushRow
Description
Use the FlushRow method to remove a specific rowfrom a rowset and from the Component buffer. Rows that are flushedare not deleted from the database.
FlushRow is a specialized and infrequently usedmethod. In most situations, you want to use DeleteRow to remove arow from the Component buffer and remove it from the database as wellwhen the component is saved.
You cannot flush the current context of the executingprogram. This means FlushRow cannot be used for the rowset containingthe executing program, or in any child rowset and executed againstthe parent rowset. Place your PeopleCode in a parent rowset and executeit against a child rowset.
Parameters
| n | Aninteger identifying a row within the rowset object. This must be >= 1 and <= the number of rows in the rowset (see property RowCount). |
Example
GetCurrEffRow
Description
GetCurrEffRow returns a row object for the rowwith the current effective date. This includes dates equal to thecurrent date, but not dates in the future. If the primary record associatedwith the rowset is not effective-dated this method returns a nullobject.
Newly inserted rows are intentionally skipped whenlooking for the current effective-dated row. This is to find thecurrent effective row from the data that already exists in the database. In other words, a row cannot be considered as a current effectiverow until it is saved. To find the current effective-dated row indata that has been newly inserted and not yet saved, use the GetNewEffRowmethod instead.
Returns
A row object for the row with the current effectivedate.
GetFirstUserSortedRow
Description
Use this method to get the first row from a sortview.
Parameters
| GridName | Specifythe grid name as a string in PAGE.RECORD format in which PAGE is thepage name and RECORD is the name of the grid as defined in ApplicationDesigner. (In Application Designer, select Page Field Properties,General tab to view the value for the Page Field Name field. The PageField Name field’s value defaults to the primary record name for thelevel at which the grid occurs; however, the value can be changedby the application developer.) |
Returns
A row object for the first row from the sort view.
If the grid has not been sorted, the output rowobject is equivalent to the first row from the rowset.
GetLastUserSortedRow
Description
Use this method to get the last row from a sortview.
Parameters
| GridName | Specifythe grid name as a string in PAGE.RECORD format in which PAGE is thepage name and RECORD is the name of the grid as defined in ApplicationDesigner. (In Application Designer, select Page Field Properties,General tab to view the value for the Page Field Name field. The PageField Name field’s value defaults to the primary record name for thelevel at which the grid occurs; however, the value can be changedby the application developer.) |
| visible | Specify, as anoptional Boolean parameter, whether to return the absolute last rowfrom the rowset, which could be hidden, or the last visible row fromthe sort view. If true, the last visible row is returned; otherwise,the absolute last row from the rowset is returned. The default valueis false—that is, return the absolute last row. |
Returns
A row object for the last row from the sort view(visible is true) or the absolutelast row from the rowset (visible is false).
GetNewEffRow
Description
GetNewEffRow returns a row object for the row withthe effective date closest to the current date, including newly insertedrows. This means dates equal to the current date, but not future dates.If the primary record associated with the rowset is not effective-datedthis method returns a null object.
To find the current effective-dated row from thedata that already exists in the database, that is, only from savedrows and not a newly created row,use the GetCurEffRow method instead.
Returns
A row object for the row with the current effectivedate.
GetRow
Description
GetRow returns a row object from a rowset. Thisis a default method for rowsets. This means that any rowset object,followed by a parameter list, acts as if GetRow is specified.
Parameters
| n | Aninteger identifying a row within the rowset object. This must be >= 1 and <= the number of rows in the rowset (see property RowCount). |
Returns
Returns a row object for the specified row of therowset.
Example
In the following example, all of the lines of codedo the same thing: they return the 5th rowfrom the rowset (&ROWSET is a rowset object.)
The following example loops through all the rowsin a rowset:
HideAllRows
Description
HideAllRows hides all rows of the rowset. Usingthis method is equivalent to a loop setting the visible property ofeach row of the rowset to False.
You cannot hide rows in the current context of theexecuting program. This means HideAllRows cannot hide the rowsetcontaining the executing program, or in any child rowsets and be executedagainst the parent rowset. Place your PeopleCode in a parent rowsetand execute it against a child rowset.
Returns
None.
Example
The following example hides the second level scrollif a value exists in the NO_COMMENTS field in the first level of thescroll. The code is running from the first level of the scroll.
InsertRow
Description
InsertRow programmatically performs the ALT+7 and ENTER (RowInsert) function. InsertRow inserts a new row inthe current rowset after the rowspecified by the parameter if the primary record for the rowset isnot effective-dated or a standalone rowset. If the primary recordfor the rowset is effective-dated or a standalone rowset, the newrow is inserted before the currentrow, 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 fromthe higher level (if any) into the inserted row.
If the program is being run from a component againstComponent buffer data, a RowInit PeopleCode event also fires, followedby the events that normally follow a RowInsert, as if the user hadmanually pressed ALT+7 and ENTER.
The InsertRow method can be executed against thesame rowset where the insertion will take place.
For rowsets corresponding to component buffer data,the InsertRow method executes in turbo mode only—that is, defaultprocessing is performed, but only on the row being inserted. Additionalinformation on turbo mode and non-turbo mode is available in the documentationwith the InsertRow PeopleCode built-in function.
See InsertRow.
InsertRow cannot be executed from the same rowsetwhere the insertion will take place, or from a child rowset againsta parent. Place your PeopleCode in a parent rowset and execute itagainst a child rowset.
Note: If you use InsertRow on a rowset created using theCreateRowset function, the row isn't automatically inserted in thedatabase when the page is saved. Rowsets created using the CreateRowsetfunction are standalone rowsets, not tied to the database, so thereare no database updates when they are manipulated. Delete and insertactivity on these types of rowsets aren't automatically applied atsave time.
Effective-Dated Row Considerations
When a row is inserted, if that row contains childscrolls, this method also inserts an empty row for any child scrolls.The effective-date field for this empty row is also empty. The currentdate is not used. Riders of icarus download ita.
Parameters
| n | An integer identifyinga row within the rowset object. This must be >= 0 and <= thenumber of active rows in the rowset (see property ActiveRowCount). A value of 0 inserts in front of the first row. |
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 databaserecord isn’t effective-dated, the new row is inserted after the second row in the rowset.
IsUserSorted
Description
Use this method to determine whether a user sorthas been performed on the specified grid.
A user sort isdefined as a user either having clicked on a column heading on thegrid 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 thissort view is for display purposes only, the underlying buffer is notsorted 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 mapthe 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 theuser to perform the sort. Alternatively, the buffer can be sortedon the hyperlink field in PeopleCode upon entry into the page.
Parameters
| GridName | Specify the gridname as a string in PAGE.RECORD format in which PAGE is the page nameand RECORD is the name of the grid as defined in Application Designer.(In Application Designer, select Page Field Properties, General tabto view the value for the Page Field Name field. The Page Field Namefield’s value defaults to the primary record name for the level atwhich the grid occurs; however, the value can be changed by the applicationdeveloper.) |
Returns
A Boolean value: true if a user sort has been performedon the grid, false otherwise.
MapBufRowToUserSortRow
Description
Use this method to return the sort view row numberthat corresponds to the specified buffer row number.
Parameters
| GridName | Specifythe grid name as a string in PAGE.RECORD format in which PAGE is thepage name and RECORD is the name of the grid as defined in ApplicationDesigner. (In Application Designer, select Page Field Properties,General tab to view the value for the Page Field Name field. The PageField Name field’s value defaults to the primary record name for thelevel at which the grid occurs; however, the value can be changedby the application developer.) |
| number | Specifythe row number of the row in the buffer. |
Returns
The row number, as a number, of the row in the sortview.
If the grid has not been sorted, the output rownumber is the same as the buffer row number.
MapUserSortRowToBufRow
Description
Use this method to return the buffer row numberthat corresponds to the specified sort view row number.
Parameters
| GridName | Specifythe grid name as a string in PAGE.RECORD format in which PAGE is thepage name and RECORD is the name of the grid as defined in ApplicationDesigner. (In Application Designer, select Page Field Properties,General tab to view the value for the Page Field Name field. The PageField Name field’s value defaults to the primary record name for thelevel at which the grid occurs; however, the value can be changedby the application developer.) |
| number | Specifythe row number of the row in the sort view. |
Returns
The row number, as a number, of the row in the buffer.
If the grid has not been sorted, the output rownumber is the same as the buffer row number.
Refresh
Description
Refresh reloads the rowset object from the databaseusing the current page keys. This causes the page to be redrawn. The following code example refreshes the entire page:
Important! Do not call GetLevel0().Refresh() from any contextthat is not at level 0. You are likely to leave invalid pointers toobjects that have been cleared from the buffer, which can result inan 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 touse a level zero rowset with this method. This is particularly usefulafter using RemoteCall.
Note: If a scroll is marked as No Auto Select in ApplicationDesigner, Refresh will not work on it. The Refresh method clearsthe existing buffers and does a refresh from the database. You do not want to use this method if your rowsetis based on message data. Instead, you can use the CopyTo Rowsetmethod combined with TransferPage.
Returns
None.
Example
The following example refreshes the entire page.
The following example refreshes only the secondlevel scroll of the page:
Select
Syntax
Where paramlist is a list of child rowsets, given in the following form:
The first scrollname must be a child rowset of the rowset object executing the method,the second scrollname must be achild of the first child, and so on.
Description
Select, like the related method SelectNew, readsdata from the database tables or views into either a row or rowsetobject.
Note: This method is valid only when used with rowsetsthat reference data from the component buffers. You cannot use thismethod with a message rowset, a rowset from an Application Enginestate record, and so on. You can’t use this method with rowsets createdusing the CreateRowset function (use the Fill method instead.)
Select automatically places child rowsets in therowset 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 autoselectedchild rowsets is also read. The child rowsets are read using a whereclause that filters the rows according to the where clause used forthe parent rowset, using a subselect.
If you don’t specify any child rowsets in paramlist, Select selects from a SQL tableor view specified by selrecord intothe rowset object executing the method.
If you specify a child rowset in paramlist, Select selects from a SQL tableor view specified by selrecord intothe child rowset specified in paramlist, under the appropriate row of the rowset executing the method.
If the rowset executing the method is a level zerorowset, and you specify Select without specifying any child rowsetswith paramlist, the method readsonly 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 ScrollSelectand RowScrollSelect functions.
Note: For developers familiar with previous releasesof PeopleCode: If the rowset executing the method is a level zerorowset, 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, andno child rowsets are specified with paramlist, the method acts like RowScrollSelect.
The record definition of the table or view beingselected from is called the select record, and identified with RECORD.selrecord. The select recordcan be the same as the primary database record associated with therowset, or it can be a different record definition that has compatiblefields. If you define a select record that differs from the primarydatabase record for the rowset, you can restrict the number of fieldsthat are loaded into the buffers on the client workstation by includingonly the fields that you actually need.
Select accepts a SQL string that can contain aWHERE 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 SELECTstatement at runtime, based on the fields in the select record andthe 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 processingis performed, but only on the row being selected. Additional informationon turbo mode and non-turbo mode is available in the documentationwith the InsertRow PeopleCode built-in function.
See InsertRow.
Parameters
| paramlist | Anoptional parameter list, for specifying children rowsets of the rowsetexecuting the method, as the rowset to be selected into. The first scrollname in paramlist 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. |
| RECORD.selrecord | Specifiesthe select record. The selrecord record must be defined in Application Designer and be a build SQLtable (using Build, Project) as a table or a view, unless selrecord is the same record as the primarydatabase record associated with the rowset. selrecord can contain fewer fields than the primary recordassociated with the rowset, although it must contain any key fieldsto maintain dependencies with other records. |
| wherestr | Contains a WHEREclause to restrict the rows selected from selrecord and/or an ORDER BY clause to sort the rows. The WHERE clause can contain the PeopleSoft meta-SQL functions suchas %DateIn() or %CurrentDateIn. It can also contain inline bind variables. |
| bindvars | A listof bind variables to be substituted in the WHERE clause. The samerestrictions that exist for SQLExec exist for these variables. SeeSQLExec for further information. |
Returns
The number of rows read (optional.) This countsonly the lines read into the specified rowset. It does not includeany additional rows read into any child rowsets of the rowset.
Example
The following example selects into the level zerorowset, only one row. Depending on the autoselect settings on anychild scrolls, they may be reselected too.
The following example selects into the level onescroll specified. Depending on the autoselect settings on any child(level two) scrolls, they may also be selected.
The following example selects into the child scrollof the level one rowset. Each row fetched is placed under the appropriaterow in &LEVEL1. Note that instead of hard-coding the WHERE clause,the SQL repository is used to access a SQL definition named SELECT_WHERE.
The following example first flushes the hidden workscroll, then selects into it based on a field on the page.
SelectNew
Syntax
Where paramlist is a list of child rowsets, given in the following form:
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 intothe database at Save time. This capability can be used, for example,to insert new rows into the database by selecting data using a viewof columns from other database tables.
Note: This method is valid only when used with rowsetsthat reference data from the Component buffers. You cannot use thismethod with a message rowset, a rowset from an Application Enginestate record, and so on. You can’t use this method with rowsets createdusing the CreateRowset function (use the Fill method instead.)
Parameters
| paramlist | Anoptional parameter list, for specifying children rowsets of the rowsetexecuting the method, as the rowset to be selected into. The first scrollname in paramlist 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. |
| RECORD.selrecord | Specifiesthe select record. The selrecord record must be defined in Application Designer and be a build SQLtable (using Build, Project) as a table or a view, unless selrecord is the same record as the primarydatabase record associated with the rowset. selrecord can contain fewer fields than the primary recordassociated with the rowset, although it must contain any key fieldsto maintain dependencies with other records. |
| wherestr | Containsa WHERE clause to restrict the rows selected from selrecord and/or an ORDER BY clause to sortthe rows. The WHERE clause can contain the PeopleSoft meta-SQL functionssuch as %DateIn() or %CurrentDateIn. It can also contain inline bindvariables. |
| bindvars | A listof bind variables to be substituted in the WHERE clause. The samerestrictions that exist for SQLExec exist for these variables. SeeSQLExec for further information. |
Returns
The number of rows read (optional.) This countsonly the lines read into the specified rowset. It does not includeany additional rows read into any child rowsets of the rowset.
Example
The following example selects rows from DATA2 andreads them into a level one scroll. If the user saves the page, theserows are inserted into DATA1.
If you use the same WHERE clause in more than oneSelect, 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 changeit in only one place.
SetDefault
Description
The SetDefault method sets the value of the specified recname.fieldname to a null value in everyrow of the rowset. If this method is being run from a component againstComponent buffer data, the next time default processing is performed,this value is reinitialized to its default value: either a defaultspecified in its record field definition or one set programmaticallyby PeopleCode located in a FieldDefault event. If neither of thesedefaults exist, the Component Processor leaves the field blank.
No default processing is performed against datathat is not in the Component buffers.
Blank numbers correspond to zero on the database. Blank characters correspond to a space on the database. Blank datesand long characters correspond to NULL on the database. SetDefaultgives each field data type its proper value.
Parameters
| recname.fieldname | Specifies a field. The field must be in the specified record, on the rows of the rowset. |
Example
This example resets the PROVIDER to its null value. This field is reset to its default value when default processingis next performed:
ShowAllRows
Description
ShowAllRows 'unhides' all rows of the rowset objectexecuting the method. Using this method is equivalent to a loop settingthe visible property of each row of the rowset to True.
ShowAllRows cannot be executed from the same rowsetyou want to display, or from a child rowset against a parent. Placeyour PeopleCode in a parent rowset and execute it against a childrowset.
Returns
None.
Sort
Syntax
Where paramlist is a list of child rowsets, given in the following form:
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.
And where sort_fields is a list of field specifiers in the form:
Description
Sort programmatically sorts the rows in a rowset. The rows can be sorted on one or more fields.
If you specify a child rowset in paramlist, Sort selects a set of child rowsetsto be sorted. If you don’t specify a child rowset in paramlist, the rowset executing the methodis sorted.
The type of sort done by this function, that is,whether it is a linguistic or binary sort, is determined by the SortOrder Option on the PeopleTools Options page.
Note: The Sort method sorts only visible rows in a rowset. If the rowset you're sortinghas hidden rows, the hidden rows are not sorted. Rows marked for deletionare also not sorted.
Parameters
| paramlist | Anoptional parameter list, for specifying children rowsets of the rowsetexecuting the method, as the rowset to be sorted. The first scrollname in paramlist 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. |
| sort_fields | A listof field and order specifiers which act as sort keys. The rows inthe rowset will be sorted by the first field in either ascending ordescending order, then by the second field in either ascending ordescending order, and so on. |
| [recordname.]field_n | Specifiesa sort key field in the rowset. The recordname prefix is required if you’ve specified a field that is not on thecurrent record. |
| order_n | A single-characterstring. 'A' specifies ascending order; 'D' specifies descending order. |
Example
The first example repopulates a rowset in a pageprogrammatically by first flushing its contents, selecting new contentsusing Select, then sorting the rows in ascending order by EXPORT_OBJECT_NAME:
Accessing the Data Buffer
This chapter provides overviews of data buffer access, data buffer class examples, and current context, and discusses how to:
Access secondary component buffer data.
Instantiate rowsets using non-component buffer data.
Understanding Data Buffer Access
This section discusses:
Data buffer access.
Access classes.
Data buffer model and data access objects.
Data Buffer Access
In addition to the built-in functions you use to access the component buffer, classes of objects are available that provide access to structured data buffers using the PeopleCode object syntax.
The data buffers accessed by these classes are typically the component buffers that are loaded when you open a component. However, these classes may also be used to access data from general data buffers, loaded by an Application Engine program, a component interface, and so on.
The methods and properties of these classes provide functionality that is similar to what has been available using built-in functions. However, they also provide improved consistency, flexibility, and new functionality.
Access Classes
The four data buffer classes are: Rowset, Row, Record, and Field. These four classes are the foundation for accessing component buffer data through the new object syntax.
A field object, which is instantiated from the Field class, is a single instance of data within a record. It is based on a field definition.
A record object, which is instantiated from the Record class, is a single instance of a data within a row. It is based on a record definition. A record object consists of one to n fields.
A row object, which is 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 area is a row. A row may have one to n child rowsets. For example, a row in a level two scroll area may have n level three child rowsets.
A rowset object is a data structure used to describe hierarchical data. It is made up of a collection of rows. A component scroll area is a rowset. You can also have a level zero rowset.
Data Buffer Model and Data Access Classes
The data model assumed by the data buffer classes is that of a PeopleTools component, where scroll bars or grids are used to describe a hierarchical, multiple-occurrence data structure. You can access these classes using dot notation.
The four data buffer classes relate to each other in a hierarchical manner. The main points to understand these relationships are:
A record contains one or more fields.
A row contains one or more records and zero or more child rowsets.
A rowset contains one or more rows.
For component buffers, think of a rowset as a scroll area on a page that contains all of the data in that scroll area. A level zero rowset contains all the data for the entire component. You can use rowsets with application messages, file layouts, business interlinks, and other definitions in addition to components. A level zero rowset from a component buffer only contains one row: the keys that the user specifies to initiate that component. A level zero rowset from data that is not a component, such as a message or a file layout, might contain more than one level zero row.
The following is basic PeopleCode that traverses through a two-level component buffer using dot notation syntax. Level zero is based on record QA_INVEST_HDR, and level one is based on record QA_INVEST_LN.
Each rowset is declared and instantiated. In general, your code is easier to read and maintain if you follow this practice.
Understanding Data Buffer Classes Examples
This section discusses:
Employee Checklist page structure.
Object creation examples.
Data buffer hierarchy examples.
Rowset examples.
Hidden work scroll area example.
Employee Checklist Page Structure
Most of the examples in this section use the Employee Checklist page.
Employee Checklist page
This page has the following record structure:
Scroll Level | Associated Primary Record | Rowset and Variable Name |
Level zero | PERSONAL_DATA | Level zero rowset: &RS0 |
Level one scroll area | EMPL_CHECKLIST | Level one rowset: &RS1 |
Level one hidden work scroll area | CHECKLIST_ITEM | Level one rowset: &RS1H |
Level two scroll area | EMPL_CHKLST_ITM | Level two rowset: &RS2 |
Another way of looking at the structure of a component is to use the Structure view. All the scroll areas are labeled, and the primary record is associated with each:
EMPLOYEE_CHECKLIST structure
In the example, the visible level one scroll area also has only one row. That row is made up of the following records:
Getfield Peoplecode Scroll 1 Piece
EMPL_CHECKLIST
DERIVED_HR
CHECKLIST_TBL
PERSONAL_DATA
You can see which records are associated with a scroll area by looking at the Order view for a page:
EMPLOYEE_CHECKLIST page Order view showing records
The level two rowset has three rows. Each row is made up of two records: the primary record, EMPL_CHKLST_ITM, and CHKLST_ITM_TBL, the record associated with the related display field DESCR. The following example shows the rowset:
EMPLOYEE_CHECKLIST rowsets and rows
Every record has fields associated with it, such as NAME, EMPLID and CHECKLIST_SEQ. These fields are associated with the record definitions; they are not the fields that appear on the page.
Object Creation Examples
When declaring variables, use the class with the same name as the data buffer access data type (rowset objects should be declared as type Rowset, field objects as type Field, and so on). Data buffer access class objects can be of type Local, Global, or Component.
The following declarations are assumed throughout the examples that follow:
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.
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:
Rowset Object
The following code instantiates a rowset object that references the rowset that contains the currently running PeopleCode program:
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.
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:
Level two rowset from level one row
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.
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:
EMPLOYEE_CHECKLIST Foreign Loan Departure 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:
EMPLOYEE_CHECKLIST Foreign Load Arrival Checklist
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:
Field | Record |
CHECKLIST_DT | EMPL_CHECKLIST |
CHECKLIST_CD | EMPL_CHECKLIST |
COMMENTS | EMPL_CHECKLIST |
DESCR | CHECKLIST_TBL |
NAME | PERSONAL_DATA |
RESPONSIBLE_ID | EMPL_CHECKLIST |
The pseudo-SQL join might look like this:
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:
CHECKLIST_DT | CHECKLIST_CD | COMMENTS | DESCR | NAME | RESPONSIBLE_ID |
12/03/98 | 000001 | Foreign Loan Department Checklist | Peppen, Jacques | 6602 |
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.
Note. The data in the record that you retrieve is based on the row, which is analogous to setting keys to return a unique record.
The following code instantiates a record object for referencing the EMPL_CHECKLIST record of the specified row:
Using the short method, the following line of code is identical to the previous line:
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.
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.
Field Object
The following instantiates a field object, from the Field class, that is used to access a specific field in the record:
You might later use the &FIELD variable as a condition:
Here is another example:
Note. The data in the field that you retrieve is based on the record, which is in turn based on the row.
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
Data Buffer Hierarchy Examples
Suppose you want to access the BRIEFING_STATUS field at level two of the following page:
EMPLOYEE_CHECKLIST repatriation checklist
First, determine where your code is running. For this example, the code is starting at a field on a record at level zero. However, you do not always have to start at level zero.
If you start with level zero, you must traverse the data hierarchy, through the level one rowset to the level two rowset, before you can access the record that contains the field.
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:
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.
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:
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:
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:
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:
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:
Using Shortcuts
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:
Rowset example
Here’s another method of expressing the code:
Object Type | Code |
Rowset Examples
The following code example traverses up to four levels of rowsets and could easily be modified to do more. This example only processes the first record in every rowset. To process every record, set up another For loop (For &R = 1 to &LEVELX.RECORDCOUNT, and so on). Notice the use of the ChildCount function (to process all children rowsets within a rowset), ActiveRowCount, IsChanged, and dot notation.
In the following example, ellipses indicate where application-specific code should go.
Hidden Work Scroll Example
In the FieldChange event for the CHECKLIST_CD field on the EMPL_CHECKLIST record, a PeopleCode program does the following:
Flushes the rowset and hidden work scroll area.
Performs a Select statement on the hidden work scroll area based on the value of the CHECKLIST_CD field and the effective date.
Clears the level two scroll area.
Copies like-named fields from the hidden work scroll area to the level two scroll area.
The following example shows how to do this using built-in functions.
The following example performs the same function as the previous code, only it uses the data buffer classes:
Flushes the rowset and hidden work scroll area (&RS1H).
Performs a Select statement on &RS1H based on the value of the CHECKLIST_CD field and the effective date.
Clears the level two rowset (&RS2).
Copies like-named fields from &RS1H to &RS1.
Understanding Current Context
Most PeopleCode programs run in a current context. The current context determines which buffer fields can be contextually referenced from PeopleCode, and which row of data is the current row on each scroll level at the time a PeopleCode program is running.
The current context for the data buffer access classes is similar to the current context for accessing the component buffer, as shown in the following diagram:
Current context for rowsets
In this example, a PeopleCode program is running in a buffer field on the second row of the level one rowset. The following code returns a row object for the second row of the level one rowset, because that is the row that is the current context.
The following code returns the B2 level two rowset because of the current context:
This code does not return either the C2 or the A2 rowsets. It returns only the rowset associated with the second row of the level one rowset.
Creating Records or Rowsets and Current Context
When you instantiate a record object using the CreateRecord function, you are only creating an area in the data buffers that has the same structure as the record definition. It does not contain any data. This record object does not have a parent rowset and is not associated with a row. It is a freestanding record object and, therefore, is not considered part of the current context.
The same concept applies when you instantiate a rowset object using the CreateRowset function. You are only creating an area in the data buffers that has the same structure as the records or rowset that the new rowset is based on. The rowset does not contain any data. This type of rowset does not have a parent rowset or row.
See Also
Accessing Secondary Component Buffer Data
When a secondary page is run, the data for its buffers is copied from the parent component to a buffer structure for the secondary page. That is, two copies of this data are made. The data buffer classes give access to both of these copies of the data. Direct field references (recname.fieldname) always use the current context to determine which value to access. So, in general, when using a secondary page, make sure that references are based on the secondary page.
Instantiating Rowsets Using Non-Component Buffer Data
Both the application message and the file layout technologies represent hierarchical data, and both use the rowset, row, record, and field hierarchy. Though you use different methods to instantiate a rowset object for this data, you still use the same rowset, row, record, and field methods and properties to manipulate the data. (Any exceptions are marked in the documentation.)
To instantiate a rowset for a message:
To instantiate a rowset for a file layout:
In an Application Engine program, the default state record is considered the primary record and the main record in context. You can access the default state record using the following:
If you have more than one state record associated with an Application Engine program, you can access them the same way you would access other, nonprimary data records, by specifying the record name. For example:
See Also