DBCursorOpenSQL

Selects a set of rows and columns in a database table, initializes the cursor at the first row of the result set, copies that row’s values to mapped tags, and then returns a cursor handle that can be referenced by other DB/ERP functions. (This function is equivalent to a SQL SELECT statement.)

Function Group Execution Windows Embedded Thin Client Mobile Access
DBCursorOpenSQL Database/ERP Synchronous Supported Supported Supported Executed on Server
Note: This feature emulates SQL (Structured Query Language) database operations. You should be familiar with how SQL commands are formed and executed before you use this feature.

Syntax

  DBCursorOpenSQL( strDBConn, strSQL, optStrTags, "optStrErrorTag" )  
strDBConn
The name of the database connection. Connections are configured in the Database/ERP folder.
strSQL
A string that gives a complete, syntactically correct SQL SELECT statement.
Note: In SQL, curly brackets ({}) are typically used to enclose an expression that must be evaluated before the entire SQL statement is executed. For example:
  SELECT * INTO inmates FROM OPENROWSET ('MSDASQL','Driver={Microsoft Text Driver (*.txt; *.csv)};DEFAULTDIR=C:;Extensions=CSV;','SELECT * FROM flat.csv')  

In IWS, however, curly brackets are used to reference tags in text fields that are not normally evaluated (e.g., in the caption of a Button object). If you pass a SQL statement that includes such an expression to DBCursorOpenSQL, then the project will try to evaluate the expression as a tag reference and the function will fail.

To pass the SQL statement so that the project can correctly evaluate the expression, create a new String tag that contains the text of the expression and then reference the tag in the SQL statement. For example:
  $AuxTag = "{Microsoft Text Driver (*.txt; *.csv)}"          $DBCursorOpenSQL( "inmates", "SELECT * INTO inmates FROM OPENROWSET ('MSDASQL','Driver={AuxTag};DEFAULTDIR=C:;Extensions=CSV;','SELECT * FROM flat.csv')")  
optStrTags
A string that lists the project tags to which the columns will be mapped. This list of tag names should be comma-delimited and in the same order as the columns specified by the WHERE clause of strSQL. As the cursor is moved through the result set, the values in the current row are copied to these tags.

This is an optional parameter. If no tags are specified, then no values will be copied.

optStrErrorTag
The name of a String tag that will receive detailed error messages, if errors occur during runtime.
Note: The tag name should be enclosed in quotes, as shown in the syntax diagram, or else the function will try to use the value of the tag.

This is an optional parameter.

Returned value

Returns a numeric value that represents the cursor handle. In case of error, returns a negative number.

Notes

See also DBCursorClose.

You can use the Studio Database Gateway to directly monitor database connections for leaks and errors. For more information, see Database Interface.

Examples

As used in a Math worksheet:
Tag Name Expression
nCursor DBCursorOpenSQL( “DB1″, “SELECT Column1, Column2 FROM Table1 WHERE Column1 > 3 ORDER BY Column1, Column2 DESC”, “Tag1, Tag2″)

DBCursorOpenSQL