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 | Mobile Access |
|---|---|---|---|---|---|---|
| DBCursorOpen | Database/ERP | Synchronous | Supported | Supported | Supported | Executed on Server |
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 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
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.
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
| 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. |