SetTrans

Specifies connection information for a DataWindow or DataStore.

To specify connection information

Use

Using values from an external transaction object

Syntax 1Using values from an external transaction object

For the Web DataWindow server component

Syntax 2For the Web DataWindow server component


Syntax 1Using values from an external transaction object

Description

Sets the values in the internal transaction object for a DataWindow control or DataStore to the values from the specified transaction object. The transaction object supplies connection settings, such as the database name.

Applies to

DataWindow type

Method applies to

PowerBuilder

DataWindow control, DataWindowChild object, DataStore object

Syntax

PowerBuilder

integer dwcontrol.SetTrans ( transaction transaction )

Argument

Description

dwcontrol

A reference to a DataWindow control, DataStore, or child DataWindow in which you want to set the values of the internal transaction object

transaction

The name of the transaction object from which you want dwcontrol to get values

Returns

Returns 1 if it succeeds and –1 if an error occurs. If any argument’s value is null, the method returns null.

Usage

In most cases, use the SetTransObject method to specify the transaction object. It is more efficient and allows you to control when changes get committed to the database.

SetTrans copies the values from a specified transaction object to the internal transaction object for the DataWindow control or DataStore. When you use SetTrans in a script, the DataWindow uses its internal transaction object and automatically connects and disconnects as needed; any errors that occur cause an automatic rollback. With SetTrans, you do not specify SQL statements, such as CONNECT, COMMIT, and DISCONNECT. The DataWindow control connects and disconnects after each Retrieve or Update function.

If you use SetTrans for an EAServer component, you must not set the UseContext Object database parameter to Yes.

NoteUse SetTransObject with composite DataWindows You must use SetTransObject with DataWindow objects that use the Composite presentation style. Composite DataWindows are containers for other DataWindow objects and do not have any internal transaction information of their own.

If you use SetTrans with each nested DataWindow in a composite DataWindow, disconnect does not occur until the PowerBuilder session ends.

Use SetTrans when you want PowerBuilder to manage the database connections automatically because you have a limited number of available connections or expect to use the application from a remote location. SetTrans is appropriate when you are only retrieving data and do not need to hold database locks on records the user is modifying. For better performance, however, you should use SetTransObject.

NoteDBMS connection settings You must set the parameters required to connect to your DBMS in the transaction object before you can use the transaction object to set the DataWindow’s internal transaction object and connect to the database.

Updating more than one table When you use SetTrans to specify the transaction object, you cannot update multiple DataWindow objects or multiple tables within one object.

Examples

Example 1

This statement sets the values in the internal transaction object for dw_employee to the values in the default transaction object SQLCA:

dw_employee.SetTrans(SQLCA)

Example 2

The following statements change the database type and password of dw_employee. The first two statements create the transaction object emp_TransObj. The next statement uses the GetTrans method to store the values of the internal transaction object for dw_employee in emp_TransObj. The next two statements change the database type and password. The SetTrans method assigns the revised values to dw_employee:

// Name the transaction object.

transaction emp_TransObj


// Create the transaction object.

emp_TransObj = CREATE transaction


// Fill the new object with the original values.

dw_employee.GetTrans(emp_TransObj)

// Change the database type.

emp_TransObj.DBMS ="Sybase"

// Change the password.

emp_TransObj.LogPass = "cam2"


// Put the revised values into the

// DataWindow transaction object.

dw_employee.SetTrans(emp_TransObj)

See also


Syntax 2For the Web DataWindow server component

Description

Specifies connection information for the Web DataWindow, such as the database name.

Applies to

DataWindow type

Method applies to

Web

Server component

Syntax

Web DataWindow server component

integer dwcontrol.SetTrans ( string dbms, string dbparm, string lock,
string logid, string logpass, string database, string servername )

Argument

Description

dwcontrol

A reference to a DataWindow control, DataStore, or child DataWindow in which you want to set the values of the internal transaction object.

dbms

PowerBuilder vendor identifier.

dbparm

DBMS-specific parameters. For example, this connection string uses the Sybase JConnect driver and connects to SQL Anywhere running on the local machine (localhost):

"Driver='com.sybase.jdbc3.jdbc.SybDriver',URL ='jdbc:sybase:Tds:localhost:7373'"

lock

The isolation level. For information about values for different types of connections, see Connecting to Your Database.

logid

The name or ID to be used to log on to the database server.

logpass

The password to be used to log on to the server.

database

The name of the database to which you are connecting.

servername

The name of the server where the database resides.

Returns

Returns 1 if it succeeds and –1 if an error occurs.

Usage

When the server component is installed in EAServer, you must use EAServer Manager to set up a connection cache for the component.

You use SetTrans when you want the DataWindow engine to manage database connections, transaction state primitives, and related EAServer component deactivation. This is incompatible with the UseContextObject database parameter, which you set only to retain control of connection and transaction functions yourself.

Because the default Web DataWindow component uses SetTrans to specify database connection information, you must not set the UseContextObject database parameter to Yes in your database profile or in the EAServer properties for the component.

Examples

Example 3

This statement specifies ODBC connection information for the server component called webDW:

webDW.SetTrans("ODBC", 
"ConnectString='DSN=EAS Demo DB V10; UID=dba;PWD=sql'", "", "", "", "", "");

Example 4

This statement specifies JDBC connection information:

webDW.SetTrans("JDS", "Driver='com.sybase.jdbc3.jdbc.SybDriver',
URL='jdbc:sybase:Tds:localhost:7373'", 
"", "dba", "sql", "", "");

See also

Retrieve