class Query

A representation of an SQL statement that describes a query and contains the resulting rowset.

Syntax

[<oRef> =] new Query( )

<oRef>

A variable or property in which to store a reference to the newly created Query object.

Properties

The following tables list the properties, events, and methods of the Query class. For details on each property, click on the property below:

Property	Default	Description
active	false	Whether the query is open and active or closed
baseClassName	QUERY	Identifies the object as an instance of the Query class
className	(QUERY)	Identifies the object as an instance of a custom class. When no custom class exists, defaults to baseClassName
constrained	false	Whether the WHERE clause of the SQL SELECT statement will be enforced when attempting to update Standard tables
database	null	Database to which the query is assigned
handle		BDE statement handle
masterSource	null	Query that acts as master query and provides parameter values
name	Empty string	The name of custom object
params	AssocArray	Associative array that contains parameter names and values for the SQL statement
parent	null	Container, form or report
requestLive	true	Whether you want a writable rowset
rowset	Object	Reference to the rowset object containing the results of the query
session	null	Session to which the query is assigned
sql	Empty string	SQL statement that describes the query
unidirectional	false	Whether to assume forward-only navigation to increase performance on SQL-based servers
updateWhere	AllFields	Enum to determine which fields to use in constructing the WHERE clause of an SQL UPDATE statement, used for posting changes to SQL-based servers
usePassThrough	false	Controls whether or not a query, with a simple sql select statement (of the form "select * from <table>), is sent directly to the DBMS for execution or is setup to behave like a local database table.
Event	Parameters	Description
beforeRelease		Before the object is released.
canClose		When attempting to close query; return value allows or disallows closure
canOpen		When attempting to open query; return value allows or disallows opening
onClose		After query closes
onOpen		After query first opens
Method	Parameters	Description
execute( )		Executes query (called implicitly when active property is set to true)
prepare( )		Prepares SQL statement
requery( )		Rebinds and executes SQL statement
unprepare( )		Cleans up when query is deactivated (called implicitly when active property is set to false)

Description

The Query object is where you specify which fields you want from which rows in which tables and the order in which you want to see them, through an SQL SELECT statement stored in the query’s sql property. The results are accessed through the query’s rowset property. To use a stored procedure that results in a rowset, use a StoredProc object instead.

Whenever you create a query object, it is initially assigned to the default database in the default session. If you want to use Standard tables in the default session you don’t have to do anything with that query’s database or session properties. If you want to use a Standard table in another session, assign that session to the query’s session property, which causes that session’s default database to be assigned to that query.

For non-Standard tables, you will need to set up a BDE alias for the database if you haven’t done so already. After creating a new Database object, you may assign it to another session if desired; otherwise it is assigned to the default session. Once the Database object is active, you can assign it to the query’s database property. If the database is assigned to another session, you need to assign that session to the query’s session property first.

After the newly created query is assigned to the desired database, an SQL SELECT statement describing the data you want is assigned to the query’s sql property.

If the SQL statement contains parameters, the Query object’s params array is automatically populated with the corresponding elements. The value of each array element must be set before the query is activated. A Query with parameters can be used as a detail query in a master-detail relationship through the masterSource property.

Setting the Query object’s active property to true opens the query and executes the SQL statement stored in the sql property. If the SQL statement fails, for example the statement is misspelled or the named table is missing, an error is generated and the active property remains false. If the SQL statement executes but does not generate any rows, the active property is true and the endOfSet property of the query’s rowset is true. Otherwise the endOfSet property is false, and the rowset contains the resulting rows.

Setting the active property to false closes the query, writing any buffered changes.