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 <span>dwcontrol</span><span>.Create</span> ( string <span>syntax</span> {, string <span>errorbuffer</span> } )

1	integer <span>dwcontrol</span><span>.Create</span> ( string <span>syntax</span> {, string <span>errorbuffer</span> } )

[Web DataWindow]

string <span>dwcontrol</span><span>.Create</span> ( string <span>syntax</span> )

1	string <span>dwcontrol</span><span>.Create</span> ( string <span>syntax</span> )

[Web ActiveX]

number <span>dwcontrol</span><span>.Create</span> ( string <span>syntax</span> )

1	number <span>dwcontrol</span><span>.Create</span> ( string <span>syntax</span> )

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)<br>dw_1.BringToTop=true

1	dw_1.Create(ls_syntax, ls_errors)<br>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

1	string error_syntaxfromSQL, error_create

string new_sql, new_syntax

1	string new_sql, new_syntax

new_sql = 'SELECT emp_data.emp_id, ' &amp;

1	new_sql = 'SELECT emp_data.emp_id, ' &

        + 'emp_data.emp_name ' &amp;

1	+ 'emp_data.emp_name ' &

        + 'from emp_data ' &amp;

1	+ 'from emp_data ' &

        + 'WHERE emp_data.emp_salary&gt;45000'

1	+ 'WHERE emp_data.emp_salary>45000'

new_syntax = SQLCA.SyntaxFromSQL(new_sql, &amp;

1	new_syntax = SQLCA.SyntaxFromSQL(new_sql, &

        'Style(Type=Form)', error_syntaxfromSQL)

1	'Style(Type=Form)', error_syntaxfromSQL)

IF Len(error_syntaxfromSQL) &gt; 0 THEN

1	IF Len(error_syntaxfromSQL) > 0 THEN

        // Display errors

1	// Display errors

        mle_sfs.Text = error_syntaxfromSQL

1	mle_sfs.Text = error_syntaxfromSQL

ELSE

ELSE

        // Generate new DataWindow

1	// Generate new DataWindow

        dw_new.<span>Create</span>(new_syntax, error_create)

1	dw_new.<span>Create</span>(new_syntax, error_create)

        IF Len(error_create) &gt; 0 THEN

1	IF Len(error_create) > 0 THEN

            mle_create.Text = error_create

1	mle_create.Text = error_create

        END IF

END IF

END IF