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.
Applies to
Syntax
PowerBuilder
integer dwcontrol.Create ( string syntax {, string errorbuffer } )
|
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 value
In PowerBuilder, returns 1 if it succeeds and -1 if an error occurs.
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 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()See also
SyntaxFromSQL in the section called “SyntaxFromSQL” in PowerScript Reference
