Progress
Open Client
Developer’s Guide


Creating an SDOResultSet Object

Once you have instantiated an SDOAppObject, AppObject, or SubAppObject, you can use the object’s _createSDOResultSet() factory method to create an SDOResultSet object and associate it with a specified SmartDataObject.

NOTE: You cannot create an SDOResultSet instance by calling its constructor. The _createSDOResultSet() factory method prepares and calls the SDOResultSet constructor based on the AppServer connection maintained by the associated AppObject.

The capabilities of SmartDataObjects provide several options for presenting data. You can pass parameters to the _createSDOResultSet() method that enable one or more of these options.

You can call one of these overloaded versions of the _createSDOResultSet() method, which supports different combinations of the four factory method parameters, as follows:

SYNTAX
public SDOResultSet _createSDOResultSet (String sdoName) 

Uses the KEEP_ROWS scrolling mode and the default where and sort expressions.

SYNTAX
public SDOResultSet _createSDOResultSet (String sdoName, String where, String 
sortBy) 

Uses the KEEP_ROWS scrolling mode.

SYNTAX
public SDOResultSet _createSDOResultSet (String sdoName, String where, String 
sortBy, SDOParameters parameters) 

Uses whatever scrolling mode is specified by parameters. If parameters does not specify a scrolling mode, the default is used.

These are the possible parameters for the _createSDOResultSet() method:

You only need to set values that differ from the defaults. The methods to set and get these values on the SDOParameters object follow:

SYNTAX
void setRowIdentity(String rowId) 

Sets the row ID of the first row to be fetched from the created and opened SDOResultSet. A null rowId is equivalent to not calling setRowIdentity() (see also, the reOpenQuery(String rowId) extended method in the "Miscellaneous Management Methods" section). It is usually more efficient to use setRowIdentity() than to create the SDOResultSet and then call the extended method, absolute(String rowId), to reposition the cursor on the specified row.

If you create the SDOResultSet in PREFETCH scrolling mode, you cannot access rows before the rowId that you set with setRowIdentity(). For more information on PREFETCH scrolling mode, see the "Understanding SDOResultSet Scrolling Modes" section.

The rowId value is equivalent to the value returned by the 4GL ROWID function and the SDOResultSet.getRowIdentity() method. For more information on ROWID, see the Progress Programming Handbook , or the appropriate Progress DataServer Guide for any DataServer accessed by the SmartDataObject. For more information on the SDOResultSet.getRowIdentity() method, see the "Miscellaneous Management Methods" section.

SYNTAX
String getRowIdentity() 

Gets the row ID of the first row to be fetched from the created and opened SDOResultSet.

SYNTAX
void setFetchSize(int fetchsize) 

Sets the number of rows the scrolling mechanism fetches each time it accesses the AppServer. The default is 200 rows.

SYNTAX
int getFetchSize() 

Gets the number of rows the scrolling mechanism fetches each time it accesses the AppServer.

SYNTAX
void setStateless(boolean state) 

Sets the Stateless mode for the SDOResultSet. Specify state as true for a Stateless SDOResultSet and false for a nonStateless SDOResultSet. For more information on the Stateless mode of SDOResultSet, see the "Understanding SDOResultSet Stateless Mode" section.

SYNTAX
boolean getStateless() 

Gets the Stateless mode for the SDOResultSet. For more information on the Stateless mode of SDOResultSet, see the "Understanding SDOResultSet Stateless Mode" section.

SYNTAX
void setScrollingMode(SDOScrollingMode constant) 

Sets the scrolling mode for the SDOResultSet specified as a class constant in com.progress.open4gl.SDOScrollingMode. If the SDOResultSet is Stateless, the default is SDOScrollingMode.PREFETCH. Otherwise, the default is SDOScrollingMode.KEEP_ROWS. The other supported scrolling mode is SDOScrollingMode.FORWARD_ONLY. For more information on these scrolling modes, see the "Understanding SDOResultSet Scrolling Modes" section.

SYNTAX
SDOScrollingMode getScrollingMode() 

Gets the scrolling mode specified for the SDOResultSet, returned as a class constant in com.progress.open4gl.SDOScrollingMode. For more information on SDOResultSet scrolling modes, see the "Understanding SDOResultSet Scrolling Modes" section.

SYNTAX
void setPrefetchMaxRows(int maxRows) 

Sets the maximum number of rows to be fetched when the scrolling mode is SDOScrollingMode.PREFETCH. The setPrefetchMaxRows() method has no effect for scrolling modes other than SDOScrollingMode.PREFETCH. The default for this mode is to get all the rows of the SDOResultSet. For more information on using this method, see the "Understanding SDOResultSet Scrolling Modes" and "Understanding SDOResultSet Stateless Mode" sections.

SYNTAX
int getPrefetchMaxRows( ) 

Gets the value for the maximum number of rows to be fetched when the scrolling mode is SDOScrollingMode.PREFETCH. For more information on using this method, see the "Understanding SDOResultSet Scrolling Modes" and "Understanding SDOResultSet Stateless Mode" sections.

Understanding SDOResultSet Scrolling Modes

Different scrolling modes allow you to control response time, memory requirements, and the result set isolation level. The isolation level (in this context) is the visibility of modifications made to the result set by applications other than the current Open Client. Each mode represents tradeoffs between these requirements and capabilities. You can set the scrolling mode on the SDOParameters object using the setScrollingMode(SDOScrollingMode constant) method and pass the object to the _createSDOResultSet() factory method. These are the values that you can pass for constant:

Understanding SDOResultSet Stateless Mode

The SDOResultSet Stateless mode allows the client to scroll through and update data without maintaining an active persistent procedure on the Application Server process. Its primary value is in support of an AppServer running in stateless operating mode. In this operating mode, maintaining a persistent procedure on the Application Server process binds the process to the client, making it unable to serve other clients.

In Stateless mode, the underlying ProcObject (mapped to the SmartDataObject) is held only for the short duration when more data is fetched from the AppServer and updates are sent to the AppServer. After that interaction, the ProcObject is released and the SmartDataObject persistent procedure is deleted.

NOTE: Although the most useful application of Stateless mode is with a stateless AppServer, the Stateless mode for SDOResultSet is orthogonal to the operating mode of the AppServer. The client can set the SDOResultSet to Stateless mode even if the AppServer is not running in stateless operating mode. The client can also create a nonStateless SDOResultSet to access a stateless AppServer.

An SDOResultSet is in Stateless mode if setStateless(true) is called on the SDOParameters that the application passes to the _createSDOResultSet() class factory method.

The SDOResultSet Stateless mode has the following limitations:

As with any SDOResultSet opened in PREFETCH mode, Stateless mode causes the SDOResultSet to return all of its rows to the client application at one time. This can pose performance problems for excessively large result sets. To manage an SDOResultSet created in PREFETCH mode, you can explicitly set the maximum number of rows fetched for a query by using the SDOParameters.setPrefetchMaxRows() method. Typically, you use this method together with the SDOResultSet.reOpenQuery(String rowId) method to limit the number of rows fetched for any one query and to fetch the next set of rows for a different instance of the query. (For more information on the reOpenQuery(String rowId) method, see the "Miscellaneous Management Methods" section.) Thus:

The following block of Java code uses these two methods to manage the fetching of rows for a Stateless SDOResultSet:

{
   // The code shows the fetching of 19 rows in two batches under
   // the Stateless mode.

   SDOParameters params = new SDOParameters();
   params.setStateless(true);

   // A maximum of 10 rows is fetched

   params.setPrefetchMaxRows(10);
   com.progress.open4gl.SDOResultSet rSet =
      appObj._createSDOResultSet("CustSDO.w",null,null,params);
   String lastRowid = null;

   // Displays the first 10 rows

   while (rSet.next())
   {
      System.out.println(
            rSet.getObject(1)) + " " +
            rSet.getObject(2) + " " +
            rSet.getObject(3));
      lastRowid = rSet.getRowIdentity();
   }

   // Get 10 more rows starting at lastRowid
   rSet.reOpenQuery(lastRowid);

   // Skip the row we already visited
   rSet.next();

   // Displays the next 9 rows.
   while (rSet.next())
   {
      System.out.println(
            rSet.getObject(1) + " " +
            rSet.getObject(2) + " " +
            rSet.getObject(3));
   }
} 

The code sets the maximum number of rows to fetch to 10 and creates the Stateless SDOResultSet, rSet, to access the SmartDataObject, CustSDO.w. It then fetches the rows, maintaining the last-fetched row ID in lastRowid. Finally, it uses lastRowid to reopen the query and fetch the next 10 rows.

Note that because you must use the last-fetched row ID as the starting point, this causes the same row to be returned as the first row in the next query. The code thus uses the next() method to skip the already-visited row, and fetches the next nine (9) rows that have not yet been fetched, for a total of 10 returned for the query.


Copyright © 2004 Progress Software Corporation
www.progress.com
Voice: (781) 280-4000
Fax: (781) 280-4095