GenerateResultSet

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.

Description

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.

Applies to

Syntax

integer dsobject.GenerateResultSet (REF ResultSet rsdest { ,dwBuffer dwbuffer } )

Returns

Returns 1 if it succeeds and –1 if it fails. If any argument is null, it returns null.

Usage

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.

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.

Examples

Example 1

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

See also

Description

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.

Applies to

Syntax

dwcontrol.GenerateResultSet ( { dwbuffer } )

Returns

Returns 1 if it succeeds or one of the following negative values if an error occurs:

Usage

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 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:

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.

Examples

Example 2

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()