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.