Creating a Query Document
A query document is a file of type 'qery' that contains a 'qrsc' resource and one
or more 'wstr' resources, and may contain a 'qdef' resource plus other
resources. Query documents make it possible for you to write applications that
can communicate with data servers without requiring familiarity with the
command language used by the data server. Because a query document is most
useful if it can be used by many different applications, no query document
should depend on the presence of a particular application in order to function.
'wstr' resource that contains either a complete query or a template for a
query. If the 'wstr' resource is a template, it contains the commands and data
necessary to create a query, without any information that the user must add
just before the query is sent. The 'qdef' resource contains a query definition
and define the 'qrsc', 'wstr', and 'qdef' resources.
User Interface Guidelines for Query Documents
All query documents should behave in fundamentally the same way. They
should be self-explanatory and should never execute a query without an
explicit command from the user. When your application opens a query
document, the query document should display a dialog box with enough
information about the query so that the user can decide if it's the right query.
The dialog box should describe the purpose of the query, what kind of data it
transfers and in which direction, the type of data source it accesses, and any
warnings or instructions. The dialog box can describe how the user interprets
the data, such as the name of each field in a record. The Figure below shows an
example of a query document dialog box.
This dialog box should allow the user to cancel the request for data. In
addition, it may be useful to allow the user to set parameters with text boxes,
check boxes, or radio buttons. For example, a query to a database of financial
information could provide a list of these options: a trial balance,
profit-and-loss statements, or net worth re ports. Save the last set of
user-specified parameters with the query document. This way the user can
review the parameters used to generate the data or use the same parameters
the next time.
Once a query starts running, it must be able to complete its task without user
intervention. If a query must run modally (that is, it must run to completion
before returning control to the user), display a dialog box that shows the
query's progress and be sure to return control to the user as soon as possible.
The philosophy of this process is similar to that of receiving electronic
mail-that is, inform the user when the information arrives, but let the user
decide when to read it.
Whenever possible, query documents should check data before it is
transmitted to a data source to be sure it's compatible. Establish a connection
with a data source only after you have checked the data.
Contents of a Query Document
The query document must contain
• an 'STR#' resource that contains the name of the database extension to
be used, plus any host, user name, password, and connection string
• one or more 'wstr' resources containing queries-that is, strings of
A 'wstr' resource consists of a 2-byte length field followed by a character
string. (The w in 'wstr' refers to the length word as opposed to the length byte
used in an 'STR ' resource.) Each 'wstr' resource contains one query (or one
query template, to be modified by the query definition function before it is sent
to the data server). The 'qrsc' resource includes an array that lists the
resource ID numbers of all of the 'wstr' resources in the query document and
an index into the array that specifies which one of the 'wstr' resources should
be sent to the data server.
In addition, the query document may contain
• a 'qdef' resource that contains a query definition function
• any resources needed by the query definition function, such as 'DLOG'
and 'DITL' resources (which support dialog boxes)
A query document dialog box
• resources to support a customized icon (to replace the default icon
that the Finder uses for files of type 'qery'); see the section entitled
Finder Interface for more information on icon resources and the
User Interface Guidelines for guidelines for customized icons.
The Figure below illustrates the relationship between a query document, the
QueryRecord, and the query definition function. The following sections
Function of a query document
Referenced by (1):