Obj-List method |
Beginning with V5.4, the Obj-List method is deprecated except when used with external classes. For best performance, use the Obj-Browse method followed if necessary by the Obj-Filter method rather than the Obj-List method. See Obj-Browse method and Obj-Filter method.
Use the Obj-List method to retrieve data to the clipboard as an array of embedded pages.
The Obj-List method searches sequentially through instances of the PegaRULES database or an external database and retrieves specified data to pages in the clipboard. It returns either:
This method is often used with a list rule (Rule-Obj-List rule type), which defines a list of properties to retrieve.
Execution of this method does not trigger declarative rule processing that depends on change tracking. Even when a property retrieved by the Obj-List method is involved in a Declare Expression, Declare Constraint or other declarative rule, retrieval does not cause the declarative rule to re-evaluate. GENTJ 04/05/05
To open a rule instance (for example, of a custom rule type), use PublicAPI facilities, not the Obj-List method, to perform rule resolution processing. The handle of a rule instance contains the creation date and time, but does not identify the RuleSets or version. Do not assume that the rule created most recently is the one in the highest RuleSet version. SR-186
The Obj-List method has four base parameters and an optional array of selection criteria. If you omit optional parameters, the system uses values from the specified list rule (Rule-Obj-List rule type).
Parameter |
Description |
PageName |
Enter the name of the destination page to contain search results. The system uses Code-Pega-List as the class of this page. |
ObjClass |
Identify the concrete ???? class to search. When this method references a list rule, it uses this value as the Applies To field (first key part) with rule resolution to find the list rule. Within the PegaRULES database, the class can correspond to a database table or to a database view. |
RuleObjList |
Optional. Identify the second key part — List Name — name of a list rule that specifies which properties are to be retrieved. The system uses the ObjClass parameter as the first key part of the list rule. |
MaxRecords |
Optional. Enter the maximum number of instances you want returned in the list at runtime. If this parameter is left blank, or set to a value of zero (0), no limit will be imposed on the number of instances retrieved. NOT 50 PRKB-19417 As a best practice, specify a MaxRecords value to reduce the demand for database activity memory. If necessary, your activity can test the property pxMore on the results page to see whether additional rows were not returned because the MaxRecords limit was reached. |
SelectionProperty |
Optional. Enter one or more properties to select and return from each instance of the class to be searched. At least one of these properties must be exposed as a column in the PegaRULES database. B-16079 optional If the ObjClass field identifies an external class, enter at least one Selection Property. B-24177 and CODE-194
As a best
practice for good performance, specify only You can review the database schema to see which properties are exposed. Consult your database administrator for information on the current database schema, or use the Modify Database Schema facility. See How to expose a property as a database column. |
SelectFrom |
Optional. Enter a literal, case-sensitive start value for this property, or a property reference on the step page, or other expression. TURBT 5/1/03 SmartPrompt B-15774B-16079 optional Click the magnifying glass icon () to start the Expression Builder. BUG-1107 5.4 Leave blank when the Selection Property value for a row contains a property reference and you want the results to include instances which contain no value of the property. PRKB-20392 |
SelectTo |
Optional. SmartPrompt B-15774 Enter a literal, case-sensitive end value for this property, or a property reference on the step page, or an expression. TURBT 5/1/03 When distinct, the SelectFrom and SelectTo values define an inclusive range. B-16079 optional Click the magnifying glass icon () to start he Expression Builder. BUG-1107 5.4 Leave blank when the Selection Property value for a row contains a property reference and you want the results to include instances which contain no value of the property. If the values in the SelectFrom and SelectTo are identical strings, Process Commander uses a LIKE SQL pattern. This selects database values that contain the string as an initial prefix rather than as an exact match. For example, if the SelectFrom and SelectTo values are both APE, then the database returns rows containing APE, but also returns rows containing APERITIF, APEX, and APERIODIC. As an alternative to Obj-List when you need only exact matches, your activity can call the PublicAPI method Database.list() in a Java step. MAHER CLINB 9/1/05 SR-570 BUG-15750 BUG-1243 |
Like |
GENTJ 10/13/03 Optional. If the property identified in this row is an exposed column in the corresponding database table, you can enter an SQL expression using syntax for the LIKE predicate, including the percent sign (%) for a wildcard character. (If your expression contains no percent sign characters, Process Commander automatically supplies a trailing percent sign character.) GENTJ 5/30/08 |
Lightweight Results |
Select to cause results from this
Obj-List method to be returned in a special format consistent
with a lightweight table in SQL rather than the standard
|
This method creates one embedded page for each instance retrieved. See Obj-List Method — Examples and Standard properties in the Code-Pega-List class.
The Obj-List method returns the data either to a previously created step page — which is cleared and reused — or to a new page that this method creates. The system writers search results in the specified step page, along with information that controlled the search.
This method also adds or updates these properties in the step page:
true
or false
.true
.This method can return thousands of database rows and create large clipboard pages. Use care to retrieve only the rows (instances) and columns (properties) you truly need.
The Obj-List-View method often produce more efficient SQL statements and provide better performance than the Obj-List method.
If the results of an Obj-List method are of multiple classes and will appear in an HTML display or be used in correspondence, consider using the optional pega:assert JSP tag to improve performance.
Execution of this method may cause an
alert to be added to the Alert log, of type
PEGA004
-PEGA007
, PEGA0025
,
PEGA0027
, or PEGA0028
. Review the Alert log to
understand the frequency and sources of such alerts, and for best
performance, alter your application or database to eliminate those alerts
that occur frequently. For example, if execution of an Obj-List method
accesses properties within the Storage Stream column, a
PEGA0025
alert occurs. The alert indicates that exposing one
or more columns in the PegaRULES database table that holds instances of
the class is likely to improve performance.
This method updates the pxMethodStatus property. See How to test method results using a transition.
See the Pega Developer Network article PRKB-25063 Comparing the Obj-List-View, Obj-Browse and Obj-List methods.