PB datawindows create

Create method (DataWindows)

Description

Creates a DataWindow object using DataWindow source code and puts that object in the specified DataWindow control or DataStore object. This dynamic DataWindow object does not become a permanent part of the application source library.

Controls

DataWindow type	Method applies to
PowerBuilder	DataWindow control, DataStore object
Web	Server component
Web ActiveX	DataWindow control

Syntax

[PowerBuilder]

integer dwcontrol.Create ( string syntax {, string errorbuffer } ) 

[Web DataWindow]

string dwcontrol.Create ( string syntax )

[Web ActiveX]

number dwcontrol.Create ( string syntax )

Argument	Description
dwcontrol	A reference to the DataWindow control or DataStore in which PowerBuilder will create the new DataWindow object.
syntax	A string whose value is the DataWindow source code that will be used to create the DataWindow object.
errorbuffer (optional)	The name of a string that will hold any error messages that are generated. If you do not specify an error buffer, a message box will display the error messages.

Return Values

In PowerBuilder and the Web ActiveX, returns 1 if it succeeds and -1 if an error occurs. In the Web DataWindow, returns the string that holds error messages (see errorbuffer).

If any argument's value is null, the method returns null.

Usage

The Create method creates a DataWindow object using the source code in syntax. It substitutes the new DataWindow object for the DataWindow object currently associated with dwcontrol.

DataWindow source code syntax is complex and is best produced by copying existing DataWindows. In a PowerBuilder application, you can use the Describe and LibraryExport methods to obtain the source code of existing DataWindows to use as models. In the PowerBuilder development environment, you can export the syntax of a DataWindow object in the Library painter.

Another source of DataWindow code is the SyntaxFromSQL method, which creates DataWindow source code based on a SQL statement. Many values in the source code syntax correspond to properties of the DataWindow object, which are documented in Chapter 38, "DataWindow Object Properties."

When you examine syntax for existing DataWindow objects, you will see that the order of the syntax can vary. Release must be the first statement, and DataWindow should be the next statement. If you change the order, use care; the order can affect the results.

Calling SyntaxFromSQL as the syntax argument

You can call SyntaxFromSQL directly as the value for syntax. However, this does not give you the chance to check whether errors have been reported in its error argument. Before you use SyntaxFromSQL in Create, make sure the SQL syntax is valid.

Comments

To designate text in your DataWindow syntax as a comment, use either of the standard PowerBuilder methods:

• Use double slashes (//) to indicate that the text after the slashes and on the same line is a comment.

  When you use this method, the comment can be all or part of a line but cannot cover multiple lines; the compiler ignores everything following the double slashes on the line.

• Begin a comment with slash asterisk (/*) and end it with asterisk slash (*/) to indicate that all the text between the delimiters is a comment.

  When you use this method, the comment can be all or part of a line or occupy multiple lines; the compiler ignores everything between /* and */.

For DataWindows in group boxes

If a DataWindow object is in a group box, it is not automatically moved to the top when you call Create, even if the BringToTop property is set to true in the DataWindow painter. You must explicitly set the BringToTop property to true after you call Create. For example:

dw_1.Create(ls_syntax, ls_errors)
dw_1.BringToTop=true

Examples

These statements create a new DataWindow in the control dw_new from the DataWindow source code returned by the SyntaxFromSQL method. Errors from SyntaxFromSQL and Create are displayed in the MultiLineEdits mle_sfs and mle_create. After creating the DataWindow, you must call SetTransObject for the new DataWindow object before you can retrieve data:

string error_syntaxfromSQL, error_create

string new_sql, new_syntax

new_sql = 'SELECT emp_data.emp_id, ' &

        + 'emp_data.emp_name ' &

        + 'from emp_data ' &

        + 'WHERE emp_data.emp_salary>45000'

new_syntax = SQLCA.SyntaxFromSQL(new_sql, &

        'Style(Type=Form)', error_syntaxfromSQL)

IF Len(error_syntaxfromSQL) > 0 THEN

        // Display errors

        mle_sfs.Text = error_syntaxfromSQL

ELSE

        // Generate new DataWindow

        dw_new.Create(new_syntax, error_create)

        IF Len(error_create) > 0 THEN

            mle_create.Text = error_create

        END IF

END IF

dw_new.SetTransObject(SQLCA)

dw_new.Retrieve()