DBCursorOpen

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.

Function	Group	Execution	Windows	Embedded	Thin Client
DBCursorOpen	Database/ERP	Synchronous	Supported	Supported	Supported

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

DBCursorOpen( strDBConn, strTable, optStrCondition, optStrColumns, optStrTags, optStrOrder, "optStrErrorTag" )

strDBConn: The name of the database connection. Connections are configured in the Database/ERP folder.
strTable: The name of the table in the database.
optStrCondition: A string specifying which rows of the table to select. This is equivalent to the SQL WHERE clause, and the string should follow the same syntax.
This is an optional parameter. If no rows are specified, then all rows of the table will be selected.
optStrColumns: A string specifying which columns of the table to select. This list of column names should be comma-delimited.
This is an optional parameter. If no columns are specified, then all columns of the table will be selected.
optStrTags: A string specifying 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 optStrColumns. 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.
optStrOrder: The order in which the rows will be sorted. This is equivalent to the SQL ORDER BY clause, and the string should follow the same syntax.
This is an optional parameter. If no order is specified, then the rows will be left in the default order of the table.
optStrErrorTag: The name of a String tag that will receive detailed error messages, if errors occur during runtime.
Note: The tag name must be enclosed in quotes, as shown in the syntax diagram, or else the project will try to get the value of the named 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

This function is equivalent to a SQL SELECT statement, except that it breaks the clauses of the statement into separate function parameters. If you know SQL and want to construct your own SELECT statement from scratch, you may use DBCursorOpenSQL instead.

Examples

As used in a Math worksheet:

Tag Name	Expression
`nCursor`	`DBCursorOpen( "DB1", "Table1", "Column1 > 3", "Column1, Column2", "Tag1, Tag2", "Column1, Column2 DESC", "TagError" )` // Opens Table1 of DB1 and selects all rows where Column1 has a value greater than 3. Column1 is mapped to Tag1, and Column2 is mapped to Tag2. Rows are ordered first by Column1, then by Column2, in descending order. Error messages are written to TagError.