PeopleTools 8.51 PeopleBook: PeopleCode API Reference

RowsetCache Class

This chapter provides an overview of the RowsetCache class and discusses:

Using the RowsetCache class
Data type of a RowsetCache object
Scope of a RowsetCache object
RowsetCache object reference

Understanding a Rowset Cache

Many PeopleSoft applications use a metadata based design, where application PeopleCode reads metadata from a database record or some other source, then presents the user with an interface that is modified based on the metadata.

PeopleTools stores application data in a database cache to increase system performance. The RowsetCache class enables you to access this memory structure, created at runtime, and shared by all users.

Data that would qualify as metadata and would be appropriate for the RowsetCache class would be data that was commonly used yet fairly static, for example, country or currency tables.

The RowsetCache class does not provide a mechanism for synchronizing the data between database tables and the cache. If the underlying data changes, you must repopulate the rowset cache.

Note. Non-base language users may see different performance due to language table considerations.

See Also

Setting MaxCacheMemory

Cache Settings

Using the RowsetCache Class

The first time a user accesses a database, the rowset cache for that database is automatically created and populated. After that first user, all users and applications can take advantage of the rowset cache.

If the underlying data for a rowset cache changes, at the very least your application must delete the existing rowset cache. Your application can also delete, then recreate and repopulate the rowset cache if it changes the underlying data. For example:

Local Rowset &RS;
Local RowsetCache &CRS;
Local Boolean &RSLT = False;

Repeat
   &I = &I + 1;
   If &RS(&I).IsChanged Then
      &RSLT = True;
   End-If;
Until &RSLT or
   &RS.RowCount = &I;

If &RSLT Then
   &CRS = GetRowsetCache(&RS);
   &CRS.Delete();
   &CRS = CreateRowsetCache(&RS);
   &CRS.Save();
End-if;

PeopleSoft recommends that any standard operations used by your application, such as deleting and repopulating the rowset cache, be encapsulated in an application class.

See Application Classes.

The RowsetCache contains a rowset, and serializes the contained rowset to binary form for speed. As with most PeopleTools objects, RowsetCache objects are cached to memory and file, but they are also cached to the data base.

RowsetCache objects are intended to be local to a data base : they should not be transferred to another data base.

Error Handling

Every time you use the GetRowsetCache function, you should verify that the function executed successfully by testing for a null object. For example:

Local RowsetCache &RSC;

&RSC = GetRowsetCache(Rowset.MyRowset);

If (&RSC <> NULL) Then
   /* do processing */
Else
   /* call to populate rowset cache */
End-if;

Data Type of a RowsetCache Object

Cached rowset objects are declared as type RowsetCache. For example,

Local RowsetCache &Cache;

Scope of a RowsetCache Object

A RowsetCache object can only be instantiated from PeopleCode.

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

Note. PeopleSoft recommends that you do not specify RowsetCache objects as Global, due to their potential size.

RowsetCache Class Built-in Functions

CreateRowsetCache

GetRowsetCache

RowsetCache Class Methods

In this section, we discuss the RowsetCache class methods. These methods are discussed in alphabetical order.

Delete

Syntax

Delete()

Description

Use the Delete method to delete the RowsetCache from memory. The RowsetCache must have already been created, either using the CreateRowsetCache and saving the RowsetCache, or by a user using the application.

If this method is called as part of a larger transaction, such as in the SavePreChange or SavePostChange event, the commit is tied to the commit of the outer transaction. If an error occurs in this method, the outer transaction will be rolled back.

If this method is invoked in a non-transactional PeopleCode event (such as RowInit) the commit is controlled by the regular Component Processor flow.

Parameters

None.

Returns

A Boolean value: True if the delete was successful, False if the specified RowsetCache wasn't found.

This method terminates with an error message if there was another problem.

Example

Local RowsetCache &CRS;
Local Boolean &RSLT;

&CRS = GetRowsetCache(Rowset.MyRowset);

/* do processing*/

If (&CRS <> NULL) Then
   &RSLT = &CRS.Delete();
End-If;

See Also

CreateRowsetCache, GetRowsetCache.

Get

Syntax

Get()

Description

Use the Get method to convert a RowsetCache object into a rowset object. After using this method, you can manipulate the data in the rowset like you would any other rowset, using the regular rowset methods and properties.

Parameters

None.

Returns

A rowset object populated with the cached rowset data.

Example

Local Rowset &RS;
Local RowsetCache &CRS;

&CRS = GetRowsetCache(Rowset.MyRowset);

If (&CRS <> NULL) Then 
   &RS = &CRS.Get();
Else
   /* do error processing */
End-if;

See Also

GetRowsetCache

Rowset Class

Save

Syntax

Save([[Rowset.]name] [, Description] [, Lang])

Description

Use the Save method to save a new or existing rowset to the cache. If a rowset of the specified name already exists, it will be replaced. Otherwise, the rowset will be added.

If this method is called as part of a larger transaction, such as in the SavePreChange or SavePostChange event, The commit is tied to the commit of the outer transaction. If an error occurs in this method, the outer transaction will be rolled back.

If this method is invoked in a non-transactional PeopleCode event (such as RowInit) the commit is controlled by the regular Component Processor flow.

Parameters

Rowset. name	Specify the name of the rowset to be saved to the cache. If you just specify name, you must enclose the name in quotation marks.
Description	Specify a text string describing the rowset.
Lang	Specify the language to use when saving the rowset. See the values below.

The values for the Lang parameter are:

Value	Description
%RowsetCache_SignonLang	Attempt to save the rowset to the cache using the sign-in language. However, if the base language rowset doesn't already exist in the cache, then the save to the sign-in language fails. This is because the system requires that base language data exist before related language data can be saved. If the Lang parameter is omitted, this is the default behavior.
%RowsetCache_BaseLang	Save the rowset to the cache using the base language.
%RowsetCache_SignonOrBaseLang	Attempt to save the rowset to the cache using the sign-in language. If that fails, then save the rowset using the base language.

Returns

A Boolean value: True if the save was successful, False otherwise.

Example

The following code cashes &RS as a rowset definition.

Local RowsetCache &CRS;
Local Rowset &RS;

&CRS = GetRowsetCache(Rowset.MyRowset);

If (&CRS <> Null) Then 
   &RS = &CRS.Get();
. . . /* do processing */
Else
   /* do error processing */
End-if;

&CRS.Save();

See Also

GetRowsetCache.

RowsetCache Class Properties

In this section, we discuss the RowsetCache class properties These properties are discussed in alphabetical order.

Content

Description

Use this property to specify the contents of a RowsetCache object.

This property is read-write.

Example

The following code example verifies if the rowset cache is populated. If it isn't, the Else statement populates the rowset cache.

&Cache2 = GetRowsetCache("CACHE1");
If &Cache2.Get() <> Null Then
   WinMessage("Cache found");
Else
   &RS = CreateRowset(Record.PSLANGUAGES);
   &NUM_READ = &RS.Fill();
   &Cache2.Content = &RS;
   &Cache2.Description = "test " | %Language_Data;
   &RSLT = &Cache2.Save();
End-If;

Description

This property can be used to set the description of the rowset cache as a string.

This property is read-write.