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.

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


Syntax 1 For generating an EAServer result set or an ADO Recordset

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

DataWindow type

Method applies to

PowerBuilder

DataStore object

Syntax

PowerBuilder

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

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

Usage


How to use it

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.


Result set format

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.

NoteDestroying 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.


Other data exchange techniques

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


Syntax 2 For generating a result set using an EAServer Method As Stored Procedure

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

DataWindow type

Method applies to

PowerBuilder

DataWindow control, DataStore object

Syntax

PowerBuilder

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:

  • Primary! – (Default) The data in the primary buffer (data that has not been deleted or filtered out).

  • Delete! – The data in the delete buffer (data deleted from the DataWindow object).

  • Filter! – The data in the filter buffer (data that was filtered out).

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:

Table 9-3: Correspondence between DataWindow datatypes and CS-Library constants

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.

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