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:
Uses the KEEP_ROWS scrolling mode and the default where and sort expressions.
Uses the KEEP_ROWS scrolling mode.
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:
- String sdoName
(Required) Specifies the filename of the SmartDataObject (
custSDO.w
, for example).- String where
Allows the application to open a query with a where expression that is different than the default one specified when the SmartDataObject was created. For more information, see the description of the setQueryWhere method in the Progress ADM 2 Reference .
- String sortBy
Allows the application to open a query with a sort expression that is different from the default one specified when the SmartDataObject was created. You can specify the sort expression using one of the following syntax styles:
In this style, field is a valid database field referenced by the SmartDataObject and specifying no fields ("") is equivalent to null. Examples include:
"Name"
"Name, City"
"Name DESCEND, City, Zip"
This style represents a valid 4GL sort clause (omitting the first BY keyword). Examples include:
"Name"
"Name BY City"
"Name DESCEND BY City BY Zip"
For more information on specifying this parameter, see the description of the setQuerySort method in the Beta Progress ADM 2 Guide .
- SDOParameters parameters
Used for passing any additional initial parameters to the ResultSet object, such as the scrolling mode.
You only need to set values that differ from the defaults. The methods to set and get these values on the SDOParameters object follow:
Sets the row ID of the first row to be fetched from the created and opened SDOResultSet. A null
rowId
is equivalent to not callingsetRowIdentity()
(see also, thereOpenQuery(String
rowId
) extended method in the "Miscellaneous Management Methods" section). It is usually more efficient to usesetRowIdentity()
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 withsetRowIdentity()
. For more information onPREFETCH
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 theSDOResultSet.getRowIdentity()
method, see the "Miscellaneous Management Methods" section.
Gets the row ID of the first row to be fetched from the created and opened SDOResultSet.
Sets the number of rows the scrolling mechanism fetches each time it accesses the AppServer. The default is 200 rows.
Gets the number of rows the scrolling mechanism fetches each time it accesses the AppServer.
Sets the St
ateless
mode for the SDOResultSet. Specify state astrue
for aStateless
SDOResultSet andfalse
for a nonStateless
SDOResultSet. For more information on theStateless
mode of SDOResultSet, see the "Understanding SDOResultSet Stateless Mode" section.
Gets the
Stateless
mode for the SDOResultSet. For more information on theStateless
mode of SDOResultSet, see the "Understanding SDOResultSet Stateless Mode" section.
Sets the scrolling mode for the SDOResultSet specified as a class constant in
com.progress.open4gl.SDOScrollingMode
. If the SDOResultSet isStateless
, the default isSDOScrollingMode.PREFETCH
. Otherwise, the default isSDOScrollingMode.KEEP_ROWS
. The other supported scrolling mode isSDOScrollingMode.FORWARD_ONLY
. For more information on these scrolling modes, see the "Understanding SDOResultSet Scrolling Modes" section.
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.
Sets the maximum number of rows to be fetched when the scrolling mode is
SDOScrollingMode.PREFETCH
. ThesetPrefetchMaxRows()
method has no effect for scrolling modes other thanSDOScrollingMode.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.
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:
NOTE: If you are accessing a large result set, you might want to use theSDOScrollingMode.PREFETCH
— This is the default and only allowable mode for aStateless
SDOResultSet. In this mode, the whole result set is fetched into memory when the SDOResultSet object is created. The response time and amount of memory required is directly related to the size of the result set. This mode creates the highest level of isolation. (For more information, see the information on visibility of updates in the "Updating SDOResultSet Objects" section.) The size of the result set is known from the beginning and does not change until the result set is closed or the query is reopened. Also, navigation in this mode is guaranteed to be fast since all the rows are in memory. This mode is ideal for small result sets in combination with slow networks.setPrefetchMaxRows()
method to limit the number of rows that you fetch. Otherwise, your Java application can run with an excessively long response time and large memory consumption. This can be a special problem for applications accessingStateless
SDOResultSets, which are always in thePREFETCH
scrolling mode. For more information, see the "Understanding SDOResultSet Stateless Mode" section.SDOScrollingMode.KEEP_ROWS
— This is the default mode for an SDOResultSet that is notStateless
. The rows are not prefetched but retrieved from the AppServer on demand. Rows that were retrieved are kept in memory until the result set is closed or a row is refreshed or updated. The response time to get the first rows inKEEP_ROWS
mode is shorter than inPREFETCH
mode.Stateless
SDOResultSets do not support this mode (see the "Understanding SDOResultSet Stateless Mode" section).SDOScrollingMode.FORWARD_ONLY
— In this mode, only thenext()
navigation method is supported—the cursor cannot be randomly repositioned. Since there is no need to maintain an in-memory cache of rows, the amount of required memory does not depend on the size of the result set. Therefore, this scrolling mode should be used when a very large result set is accessed and thenext()
method is sufficient—no other navigation methods are required.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 ofStateless
mode is with a stateless AppServer, theStateless
mode for SDOResultSet is orthogonal to the operating mode of the AppServer. The client can set the SDOResultSet toStateless
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 ifsetStateless(true)
is called on the SDOParameters that the application passes to the_createSDOResultSet()
class factory method.The SDOResultSet
Stateless
mode has the following limitations:
- Only batch updates are allowed. For more information, see the "Using Batch Mode [Extension]" section.
- Stateless mode is only allowed with the
PREFETCH
scrolling mode. For more information, see the "Understanding SDOResultSet Scrolling Modes" section.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 inPREFETCH
mode, you can explicitly set the maximum number of rows fetched for a query by using theSDOParameters.setPrefetchMaxRows()
method. Typically, you use this method together with theSDOResultSet.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 thereOpenQuery(String
rowId
)
method, see the "Miscellaneous Management Methods" section.) Thus:
- The
SDOParameters.setPrefetchMaxRows()
sets the maximum rows to fetch for the query when the SDOResultSet is created.- The
SDOResultSet.reOpenQuery(String
rowId
) fetches a new set of rows, using another instance of the same query and maximum number of rows, but starting from the specified rowId, which identifies one of the rows in the previous instance of the query.The following block of Java code uses these two methods to manage the fetching of rows for a
Stateless
SDOResultSet:
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 inlastRowid
. Finally, it useslastRowid
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 |