DBCursorOpen

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 Database/ERP functions.

Syntax

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

strDBConn

The name of the database connection. Connections are configured in the Database/ERP folder, in the Project Explorer. For more information, see Database/ERP worksheet.

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 parameter is optional; if no rows are specified, 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 parameter is optional; if no columns are specified, 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 parameter is optional; if no tags are specified, 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 parameter is optional; if no order is specified, the rows will be left in the default order of the table.

optStrErrorTag

The name of a project tag that will receive detailed error messages, if errors occur during project run time.

Note: If this parameter is enclosed in quotes, the string literal will be used. Otherwise, the value of the tag/expression will be used.

This parameter is optional.

Return value

In the case of success, this function returns a numeric value that can be used as a cursor handle in other Database/ERP functions.

In the case of error, this function returns one of the following possible values:

Notes

Database/ERP functions emulate Structured Query Language (SQL) database operations. Before you use these functions, familiarize yourself with how SQL statements are formed and executed.

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 compose your own SELECT statement, you can use the function DBCursorOpenSQL instead.

This function recognizes only 16000 rows of a table at one time. If a selected section of table has more than 16000 rows, only the first 16000 rows of the selection will be accessible to any built-in language Database/ERP functions. Exceeding this limit may return an EOF error even if the end of the file has not been reached.

By default, the database interface can have a maximum of 1000 database connections — including cursor handles — open at the same time. If this limit is reached, the database interface will automatically close the oldest connection before it opens a new one. As such, you should use the function DBCursorClose to close open cursor handles as soon as you have finished with them.

You can also increase the maximum number of database connections, if necessary. To do that, use a text editor to open your project file (typically located at AVEVA Edge 2026 Projects\<project name>\<project name>.app) and edit the following property:

[StDB]

MaxConnections=<from 1 to 32767>

Having a large number of database connections open at the same time can affect runtime performance.

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

Examples

Open Table1 of DB1 and select all rows where Column1 has a value greater than 3; map Column1 to Tag1 and Column2 to Tag2; order the rows first by Column1, then by Column2, in descending order; and write error messages to TagError:

DBCursorOpen("DB1","Table1","Column1 > 3","Column1, Column2","Tag1, Tag2","Column1, Column2 DESC","TagError")