The WHERE clause for SQL command SELECT, which executes the selection from a table, is defined by either the value of strExpression_Str, or, if this value is not defined, the values from the defined (valid) key items (those items which were set as key when configuring the object Table) in the first row of structure (rowIdent or localStructIdent[1]). These values must be set before executing DB_READ (DBS_READ).
Note: if neither the condition is specified nor the table has key columns, all data from the table will be read (unles there are more than the specified maximum).

Note: if the data is read into one row of the structure (versions with the rowIdent_Int parameter) using key items, then the values of all key items in rowIdent_Int must be valid, otherwise the reading will not take place, it will end with an error and %GetLastExtErrorCode() will return error 667.

It follows that WHERE clause is not a part of SQL command SELECT, if the value of strExpression_Str is not defined and

• there are not the key items (the items specified as key ones when configuring the object Tabuľka),
• or there is not defined (valid) any value of the key items,
• or the structure has a null size (for localStructIdent).

The first form of the action declaration allows to read just one row of a table to one line of a structure.

If more rows than one meet the selection condition during the selection, the action DB_READ (DBS_READ) is to be read the first row. If no row meet the condition, the action will send back the error by means of retCodeIdent_Int. Structure type (rowIdent) must be equal to the table type.

The second form of the declaration allows to read one or more rows from a table. Value of the parameter maxRows determines the maximal number of rows. If this value is set to -1, then the system will attempt to read all rows matching the specified condition. Maximum number of rows is limited by a Database configuration parameter Maximum returned rows. Exceeding this number, the first Maximum returned rows will be stored in local structure localStructIdent and retCodeIdent_Int will be set to _ERR_DATABASE_ROWS_LIMIT.
If the value of maxRows is greater than Maximum returned rows, at the most Maximum returned rows will be read. If more rows are available, retCodeIdent_Int will be set to error code _ERR_DATABASE_ROWS_LIMIT.

If the value of the parameter maxRows is set to -2, the system at first detects how many rows meet given condition. If the number of rows is 0 or it is more than Maximum returned rows, the system will not read any rows, or reads all detected rows otherwise. For optimization reasons, this method may be faster than the method for maxRows=-1. Number of rows is detected by the SQL command "SELECT COUNT(*) FROM table_name [WHERE where_condition]". If the condition StrExpression_Str is defined, it is also tested for the presence of an ORDER BY clause. If the result is positive, the clause is removed along with all following text. It is removed because when detecting the number of rows e.g. Sybase doesn't accept "SELECT COUNT(*) FROM aaaa WHERE bbbb = cccc ORDER BY dddd" and returns the error Function or column reference to 'dddd' in the select list must also appear in a GROUP BY.

The parameter localStructIdent must be the name of a local structure of the corresponding type (i.e. with the same Structure type that is used in the configuration of the object dbObjIdent of Table type). If you want to be sure that the result will not be controlled by WHERE clause, which consists of the key items, you should change the size of local structure to 0 (zero) before calling DB_READ (DBS_READ).

After reading rows from the database, they are assigned to the local variable localStructIdent. Its size may be changed in case of need (REDIM). If no row meet the selection condition, the action is to be terminated successfully (retCodeIdent_Int = _ERR_NO_ERROR) and the structure size localStructIdent is to be changed to 0.

The advantage of using the action DBS_READ is omitting the table opening and closing (shorter code).

For D2000 v5.00: an disadvantage of the action DBS_READ is in speed. Each DBS_READ call results in necessity to open and close the database in DBManager - it can be a time-consuming operation and it is a comparatively nonstandard method in term of databases.
The need to open and close the database may be avoided in the scope of transaction processing so that the command is followed by the parameter

TRANS

For D2000 v6.00 and higher: DBManager optimization (connection recycling, predefined connections) causes the action DBS_READ to execute as fast as the action DB_READ and moreover time is saved omitting the execution of the action DB_CONNECT.