Inside Macintosh: Interapplication Communication /

Chapter 12 - Data Access Manager

This chapter describes how your application can use the Data Access Manager to gain access to data in another application. It also tells you how to provide templates to be used for data transactions.

The Data Access Manager is available in System 7 and later versions. Use the Gestalt Manager to determine whether the Data Access Manager is present. To determine whether the Data Access Manager is available, use the Gestalt function with the gestaltDBAccessMgrAttr environmental selector. If the Data Access Manager is not available, the Gestalt function returns an error. For more information on the Gestalt Manager, see Inside Macintosh: Operating System Utilities.

The Data Access Manager allows your application to communicate with a database or other data source even if you do not know anything about databases in general or the specific data source with which the users of your software will be communicating. All your application needs are a few high-level Data Access Manager functions and access to a file called a query document. The query document, provided by another application, contains commands and data in the format appropriate for the database or other data source. The string of commands and data sent to the data source are referred to as a query. Note that a query does not necessarily extract data from a data source; it might only send data or commands to a database or other application.

The Data Access Manager makes it easy for your application to communicate with data sources. You need only add a menu item that opens a query document, using a few standard Data Access Manager functions to implement the menu selection. Users of your application can then access a database or other data source whenever they have the appropriate query documents. A user of a word-processing program might use this feature, for example, to obtain access to archived material, dictionaries in a variety of languages, or a database of famous quotations. A user of a spreadsheet program might use a query document to obtain tax records, actuarial tables, or other data. A user of an art or computer-aided design program might download archived illustrations or designs. And for the user of a database application for the Macintosh computer, the Data Access Manager can provide the resources and power of a mainframe database.

The Data Access Manager also provides a low-level interface for use by applications that are capable of creating their own queries and that therefore do not have to use query documents.

If your application uses only the high-level interface and relies on query documents created by other programs, then all the routines you need to know are described in this chapter. However, if you want to create a query document or an application that uses the low-level interface, then you must also be familiar with the command language used by the data server.

You need the information in this chapter if you want your application to access data in other applications or if you want to write a query document.

Note

The Data Access Manager makes it easy for your application to communicate with a database running on a remote computer, and this chapter generally assumes that you are using it for that purpose. However, there is no reason why the database could not be local--that is, running on the same computer as your application. To implement such a system, you would have to have a database that runs on a Macintosh computer and that has a command-language interface, plus a database extension that can use that command language. In most cases, it would be much simpler to run the database as a separate application and use the Clipboard to transfer data into and out of the database.

Note also that the program containing the data need not be a database. With the appropriate database extension, your application could read data from a spreadsheet, for example, or any other program that stores data.

Apple Computer, Inc. provides a database extension that uses Data Access Language (DAL). A database extension provides an interface between the Data Access Manager and the database or other program that contains the data. If you want to write an application that uses the low-level interface to communicate with a Data Access Language server, or if you want to create a query document that uses Data Access Language, you must be familiar with that language. Data Access Language Programmer's Reference, available from APDA, fully describes this language.

---

Chapter Contents

About the Data Access Manager

The High-Level Interface

Sending a Query Through the High-Level Interface

Retrieving Data Through the High-Level Interface

The Low-Level Interface

Sending a Query Through the Low-Level Interface

Retrieving Data Through the Low-Level Interface

Comparison of the High-Level and Low-Level Interfaces

Using the Data Access Manager

Executing Routines Asynchronously

General Guidelines for the User Interface

Keep the User in Control

Provide Feedback to the User

Using the High-Level Interface

Writing a Status Routine for High-Level Functions

Using the Low-Level Interface

Getting Information About Sessions in Progress

Processing Query Results

Getting Query Results

Converting Query Results to Text

Creating a Query Document

User Interface Guidelines for Query Documents

Contents of a Query Document

Query Records and Query Resources

Writing a Query Definition Function

Data Access Manager Reference

Data Structures

The Asynchronous Parameter Block

The Query Record

The Results Record

Data Access Manager Routines

Initializing the Data Access Manager

High-Level Interface: Handling Query Documents

High-Level Interface: Handling Query Results

Low-Level Interface: Controlling the Session

Low-Level Interface: Sending and Executing Queries

Low-Level Interface: Retrieving Results

Installing and Removing Result Handlers

Application-Defined Routines

Resources

The Query Resource

The Query String Resource

The Query Definition Function Resource

Summary of the Data Access Manager

Pascal Summary

Constants

Data Types

Data Access Manager Routines

Initializing the Data Access Manager

High-Level Interface: Handling Query Documents

High-Level Interface: Handling Query Results

Low-Level Interface: Controlling the Session

Low-Level Interface: Sending and Executing Queries

Low-Level Interface: Retrieving Results

Installing and Removing Result Handlers

Application-Defined Routines

C Summary

Constants

Data Types

Data Access Manager Routines

Initializing the Data Access Manager

High-Level Interface: Handling Query Documents

High-Level Interface: Handling Query Results

Low-Level Interface: Controlling the Session

Low-Level Interface: Sending and Executing Queries

Low-Level Interface: Retrieving Results

Installing and Removing Result Handlers

Application-Defined Routines

Assembly-Language Summary

Trap Macros

Trap Macros Requiring Routine Selectors

Result Codes