Generates a result set that can be used by non-DataWindow controls for displaying data. A result set is usually generated by a component on a transaction server and returned to a client application.
To generate a result set |
Use |
|---|---|
That can be an EAServer result set or an ADO Recordset |
Syntax 1 For generating an EAServer result set or an ADO Recordset |
Using an EAServer Method As Stored Procedure (MASP) |
Syntax 2 For generating a result set using an EAServer Method As Stored Procedure |
Generates a result set from data in a DataStore or DataWindow control.
In PowerBuilder, when the result set is generated in a component on a transaction server, the format of the result set is determined by the server—TabularResults in EAServer and ADO Recordset on MTS.
DataWindow type |
Method applies to |
|---|---|
PowerBuilder |
DataStore object |
integer dsobject.GenerateResultSet (REF ResultSet rsdest { ,dwBuffer dwbuffer } )
Argument |
Description |
|---|---|
dsobject |
The name of the DataStore object that contains the data to be returned in the result set. |
rsdest |
The ResultSet object into which the data in the DataStore is written. This value is passed by reference. |
dwbuffer (optional) |
A value of the dwBuffer enumerated datatype identifying the DataWindow buffer containing the data for the result set. The default is the primary buffer. For a list of valid values, see DWBuffer. |
Returns 1 if it succeeds and –1 if it fails. If any argument is null, it returns null.
Result sets are intended for exchanging data between a DataStore and some data-aware application that does not use DataWindow technology. With result sets, the receiving end does not support updating of the data.
The GenerateResultSet method is typically used in a PowerBuilder custom class user object that has been packaged as a component on EAServer or on an MTS server. A function in the user object generates a result set from information that has been retrieved into a DataStore. The function then returns the result set or passes it to another method.
For example, a function for PowerBuilder custom class user object running in a transaction server can retrieve data into a DataStore object, create a result set object, and return the result set. A client application calls the function to get the data. The client application must be able to handle result sets, but it does not need to have support for DataWindow technology.
Likewise, a client application can generate a result set from a DataStore and pass the result set to the server.
The CreateFrom method can convert a result set back to a DataStore.
The result set is returned to a client in a format that is standard for the server. In user objects deployed to EAServer, user-defined functions that return a PowerBuilder ResultSet object are represented in the IDL definition of the component as methods that return a result set of type TabularResults::ResultSet. Multiple result sets returned in a ResultSets object are represented in the IDL as TabularResults::ResultSets datatypes. In MTS, returning a result set created by GenerateResultSet causes an ADO Recordset to be marshaled to the client.
The GenerateResultSet method can also be called in a client application. Since the format of the result set depends on the server on which it is used, the format is fixed when that result set is passed to a server. For EAServer, the format is TabularResults::ResultSet; for MTS, the format is an ADO Recordset.
Destroying or modifying the DataStore
The generated ResultSet object maintains a reference to the
DataStore from which it was generated, so changes made to the DataStore
object after the result set is generated will be reflected in the
generated ResultSet object. If you destroy the DataStore object
before returning the result set, the result set becomes invalid.
You can rely on garbage collection to destroy the DataStore object
or destroy it explicitly in the component’s deactivate
event.
To exchange data between a DataWindow on a client and a DataStore on EAServer, use the data-synchronizing methods GetFullState and SetFullState. With these methods, both controls remain updatable. If updating is not a concern, you still might choose result sets instead of synchronizing methods because result sets transfer less data.
In this example, a DataStore object is created and data is retrieved into it, and then the GenerateResultSet method is used to create a result set that can be returned to a client.
datastore ds_datastore
resultset lrs_resultset
integer li_rc
ds_datastore = CREATE DataStore
ds_datastore.SetTransObject (SQLCA)
IF ds_datastore.Retrieve() = -1 THEN
... // report error and return
END IF
li_rc = ds_datastore.GenerateResultSet(lrs_resultset)
IF li_rc <> 1 THEN
... // report error and return
END IF
return lrs_resultset
SetRecordSet in PowerScript Reference
Generates an EAServer result set that can be returned from a PowerBuilder user object running as a component on EAServer. The result set is retrieved using a DataWindow control or DataStore object whose data source is an EAServer component method.
DataWindow type |
Method applies to |
|---|---|
PowerBuilder |
DataWindow control, DataStore object |
dwcontrol.GenerateResultSet ( { dwbuffer } )
Argument |
Description |
|---|---|
dwcontrol |
The DataWindow control or DataStore object that contains the data to be returned in the result set. |
dwbuffer (optional) |
A value of the dwBuffer enumerated datatype specifying the DataWindow buffer from which you want to copy rows. Valid values are:
|
Returns 1 if it succeeds or one of the following negative values if an error occurs:
The GenerateResultSet method allows you to return a result set from a PowerBuilder custom class user object that has been packaged as a component on EAServer using the EAServer Method As Stored Procedure (MASP) technique. For more information about MASP, see the EAServer and PowerDynamo documentation.
GenerateResultSet does not return a result set if the custom class user object is not running on EAServer.
To use GenerateResultSet, create a user object function for the custom class user object that will be installed on EAServer. The user object function must not return a value. It connects to a database and retrieves data into a DataStore object using the PowerBuilder Transaction object. The call to GenerateResultSet uses column data in the DataStore object to generate an EAServer result set.
In the installed EAServer component, the user object function runs as a method on EAServer. EAServer can return the generated result set to any client that can interpret a Tabular Data Stream (TDS) result set. To retrieve the result set from a PowerBuilder client, create a DataWindow object whose data source is Stored Procedure and select the method on EAServer as the data source.
DataWindow datatypes map to CS-Library type constants in the result set as follows:
DataWindow datatype |
Datatype in result set |
|---|---|
Date |
CS_CHAR_TYPE |
DateTime |
CS_DATETIME_TYPE |
Decimal |
CS_DECIMAL_TYPE |
Long, Ulong |
CS_INT_TYPE |
Number |
CS_FLOAT_TYPE |
Real |
CS_REAL_TYPE |
String (length <= 244) |
CS_CHAR_TYPE |
String (length > 244) |
CS_LONGCHAR_TYPE |
Time |
CS_CHAR_TYPE |
The precision of all decimal datatypes in the result set will be 16.
The sort order of the result set remains the same whether or not the method running on EAServer performs a sort operation on the DataStore object. If the result set is returned to a PowerBuilder client, you can use the Sort and SetSort PowerScript methods to sort the returned data.
If GenerateResultSet is called multiple times within a single script, EAServer passes multiple duplicate result sets back to the client.
The following is a user object function that runs as a method on EAServer. The function creates an instance of a DataStore object, connects to a database, and retrieves data into the DataStore object. The call to GenerateResultSet creates an EAServer result set that is returned to the client from the data in the DataStore object.
// User object function: uf_gettraintimes
// Set transaction object properties
...
// Open a log file for connect errors
integer li_FileNum
li_FileNum = FileOpen("C:\SCHEDULES\ERRORS.TXT", &
LineMode!, Write!, LockWrite!, Append!)
// Connect to the database
CONNECT using SQLCA;
IF SQLCA.SQLCode <>0 THEN
FileWrite(li_FileNum, &
"Cannot connect to database " &
+ SQLCA.SQLErrText)
RETURN
ELSE
// Create a DataStore object and retrieve data
uo_ds_traintimes u_DataStore
u_DataStore = CREATE uo_ds_traintimes
u_DataStore.SetTransObject(sqlca)
u_DataStore.Retrieve()
// Generate the result set
long ll_return
ll_return = &
u_DataStore.GenerateResultSet(Primary!)
IF ll_return <> 1 THEN
FileWrite(li_FileNum, &
"GenerateResultSet return code: " &
+ string(ll_return))
ELSE
FileWrite(li_FileNum, "Result set generated")
END IF
FileClose(li_FileNum)
DESTROY u_DataStore
DISCONNECT using SQLCA;
END IF
To use the method above with a PowerBuilder client, start PowerBuilder and connect with ODBC or with the SYC database interface to EAServer where the user object is installed. Create a new DataWindow object with Stored Procedure as its data source and then select the component method from the list of stored procedures. Define the result set to correspond to the result set returned by the method on the server.
In the client application, use the Retrieve method to retrieve data from the server:
// The data source for dw_traintimes is
// PBPackage.PBServer.uf_gettraintimes
dw_traintimes.Retrieve()
