You are here: Reference > Activity methods > RDB-List

RDB-List method

Use this method to retrieve rows from an external relational database and place the results as embedded pages in a specified step page of class Code-Pega-List.

This method references a Connect SQL rule instance, and executes SQL statements stored in the Browse tab of that rule instance. The search can do anything you can specify in a SQL statement, such as a SELECT WHERE statement. Any constraints on the returned data are in the SQL.

On the Browse tab of the Connect SQL rule, use the special data syntax described in Connect SQL rules — Data mapping.

In all but rare cases, use Connect SQL rules only with an external database. Do not use Connect SQL rules or RDB methods for the PegaRULES database(s). Because not all properties in the PegaRULES databases are distinct database columns, use the Obj-Open and Obj-Save methods, not the RDB- methods, with the PegaRULES database to prevent loss of data.

Specify a page of class Code-Pega-List as the step page of the RDB-List method. Also identify this page and class on the Pages & Classes tab of the Activity form.

Parameters

This method has several parameters. The first three parameters are required; together they identify the key of a Connect SQL rule.

Parameter

Description
RequestType

Enter the third key part — Request Type — of the Connect SQL rule containing the search operation.

Access

Enter the second key part — Package Name — of the Connect SQL rule (by convention MSSQL, Oracle, DB2, UDB, or Sybase, but not restricted to these values).
ClassName

Enter a class name, the Applies To key part of a Rule-Connect-SQL rule.

Identify the exact class of the rule. The system does not use class inheritance to find the Rule-Connect-SQL rule instance. This is also the class of the pxResults embedded pages which hold the search results. It can be a class that you created to hold the results.

This class is distinct from the class which the RDB-List method searches, which you identify in the SQL code in the Rule-Connect-SQL rule.
MaxRecords

Optional. Enter a positive integer that is the maximum number of rows to return in the search results.
BrowsePage

Optional. Identify the top-level page into which the search results are to be returned. The pxResults pages are embedded in this page. If left blank, the system uses the step page you specified for the RDB-List method in the activity step.

If you select this option, do not select the RunInParallel option. Parallel operations cannot update the single top-level browse page.

ApplyDeclaratives

Select to cause change tracking for Declare Expression and Declare Constraint rules processing to be applied to the properties returned by this method.

You cannot select this box if the RunInParallel box is selected.
RunInParallel

Select if you want processing for the connector to continue in a separate requestor, in parallel with the current requestor. When selected, use the Connect-Wait method later in the current or a later activity to access results from the connector.

Clear if you want processing in this requestor session to pause until the connector processing completes.

You cannot select this box if the ApplyDeclaratives box is selected. Do not select this option if you supplied a page name in the BrowsePage field.

Results

This method accesses the Rule-Connect-SQL rule instance identified by the first three parameters, using rule resolution. It converts table, class, and property references on the Browse tab of this rule using clipboard data, and sends the resulting updated SQL to the external database.

The RDB-List method returns data to the page you specify in the Step Page field on the activity form. This can be a previously created page — which is cleared and reused — or a new page created with this method.

When the RunInParallel box is selected, the SQL operation occurs in a new requestor session. This temporary requestor has the same access group and clipboard as the original. At most 10 such child requestor sessions can be active at once.

When the system receives information from the external database, it updates properties on the step page, which has the class Code-Pega-List.

If the search is successful, this method also creates a page list page named pxResults, which contains pages pxResults(1), pxResults(2), and so on. These embedded pages contain the row results as properties. Depending on the ApplyDeclaratives box, the declarative processing may be activated for the properties.

Finally, this method can create a (classless) error page, if specified in the Connect SQL rule.

Properties of Code-Pega-List

 

Closed Expand this node to review the main properties of Code-Pega-List.

This table identifies some of the main properties of the Code-Pega-List class, which is output from various methods. Properties marked with a yellow diamond dot can hold input parameters for the search. Other properties specified as read-only contain outputs from the search.

Property

Purpose
pyCacheFile

For list view reports that save results as an XML file in the lookup list cache, identifies the file name.
pyCondition dot

A Page List. Identifies the parameters that define search comparisons, for the Obj-List method:

  • pyConditionFieldName — A property reference resulting in a single text value
  • pyConditionOperation — A comparison operator, such as "<"
  • pyConditionValue1 — An expression for the comparison value
pyDetailsAction dot

For list view and summary view rules, identifies the value of the pyAction parameter to the ShowView activity, such as PREPARE or SHOW.
pyDetailsWindowdot

For list view and summary view rules, identifies the name of the window that is to hold the resulting display.
pxElapsedTime

Elapsed time in seconds to process the RDB-List operation. Read-only.
pxMore

Indicates whether there are more instances not returned. Values are true or false. Read-only.
pyMaxRecords dot

Optional input to limit the number of rows returned.
pxNextKey

Indicates the key of the first row (instance) not returned, if pxMore is true. Read-only.
pyObjClassdot

Identifies the class containing the instances that are to be searched. This property is different from pxObjClass, the class of this page, which always has the value Code-Pega-List.
pyPageSizedot

For list view or summary view rules that support report paging, the maximum number of results to presented on a page.
pyQueryTimeStamp

A DateTime value recording the start of the operation. Read-only.
pxResults

A Page List containing pages with individual search results. each of the class defined in the pxObjClass property. (Not used for Obj-List methods that specify the lightweight results format.) Read-only.
pxResultCount

Number of rows of data returned by the search. Read-only.
pyReturnLightweightResultsdot

For the Obj-List method, indicates that the results are in a special format rather than in pxResults pages. Read-only.
pxSelectStatement

For the Obj-List method, the SQL statement sent to the database before substitution. Read-only.
pxSQLStatementPost dot

For the RDB-List method, SQL statements as sent to the SQL database. Appears only when requested through the {SQLPage} syntax. Read-only.
pxSQLStatementPre dot

For the RDB-List method, SQL statements before substitution. Appears only when requested through the {SQLPage} syntax. Read-only.
pxTimeElapsed

For the Obj-List method, elapsed seconds taken for the method. Read-only.
pxTotalResultCount

For the RDB-List method, the total number of results returned by the query. This is set only if pyReturnTotalResultCount is true. (If pyReturnTotalResultCount is false, then this is zero.) Read-only.
pyUseAlternateDb Set to true if an alternate database, not the primary PegaRULES database, was the source of data for a list view or summary view report.

Debugging SQL and SQL performance

You can use the DB Trace feature of the Performance tool to view in depth the SQL operations of a Connect SQL rule.

Execution of this method may cause an alert to be added to the Alert log, of type PEGA004-PEGA007, PEGA0025, 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.

Checking the method status

This method updates the pxMethodStatus property. See How to test method results using a transition.

When a {SQLPage:pagename} directive appears as the first line of the SQL code on the Browse tab, a top-level page named pagename is created. If errors occur, properties on that page contain additional error details. (When RunInParallel is selected, this page is not available to the original requestor.)

Related information

Methods and instructions by function

Open topic with navigation