RDB-Open method

Use this method to retrieve a single row (record) of data from an external relational database and add the retrieved data into a specified clipboard page as property names and values.

Use this method in conjunction with a Connect SQL rule that contains SQL SELECT or EXECUTE statements in the Open tab. Define the SQL statements so that the database returns exactly one row. (To search the external database with criteria that may sometimes find no rows, or find more than one row, use the RDB-Browse method, not the RDB-Open method.)

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

Except in rare cases, identify in the Step Page field the name of the page to be created by this method. If the Step Page field of the step is blank, this method clears the primary page of the current activity and may change its class. Typically, this is not desirable.

Use Connect SQL rules and the RDB-Open method only with an external database. Do not use Connect SQL rules or RDB methods to updated the PegaRULES database(s). Because not all properties in the Pega Platform 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.

Parameters

This method has four parameters. Three required parameters together identify a Connect SQL rule. The final parameter controls a processing option.

Parameter Description
OpenClass Enter the Applies To key part of the Connect SQL rule that defines the open SQL. This must match the class of the step page.

Identify the exact class of the rule. The system does not use class inheritance to find the Rule-Connect-SQL rule instance.

RequestType Enter the third key part — Request Type — of the Connect SQL rule containing the open operation.
Access Enter the second key part — Package Name — of the Connect SQL rule (by convention MSSQL, Oracle, Db2, UDB, or Sybase, but you are not restricted to these values).
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 the current requestor session to wait until the connector processing completes.

Results

This method uses the three required parameters and rule resolution to retrieve a Connect SQL rule.

Next, the system processes the SQL text on the Open tab of the Connect RDB rule, performing any keyword evaluations and clipboard substitutions. It then sends the resulting SQL text to the external database. When the Pega Platform receives the results from the external database, it places the results into the single clipboard page identified in the Step Page column of the step.

The system chooses the class of the results from the value of the pxObjClass property, if any returned from the database. In the common case that the RDB-Open method is used with an external database (rather than the PegaRULES database), the opened instance has no pxObjClass property: the system then determines a concrete class for its results from either:

  • The Applies To key part of this Connect SQL rule, or
  • CLASS instructions within the SQL statement. If the SQL statement contains more than one CLASS directive, the most specific concrete class is used.

If the step page exists, the system changes the class of the step page to the class determined by the above algorithm. If the step page does not exist, the system creates a new page with a that class.

If the external database request returns no rows, or more than one row, the step page is not updated and the method returns a fail status.

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.

CAUTION:
Each RDB-Open, RDB-Save, and RDB-Delete method involves an SQL database commit operation. You cannot implement SQL transaction commit operations spanning two or more Connect SQL rules.

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.

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 Open 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.)

Restrictions

This method cannot be used in a step that involves iteration.

Methods and instructions by function