Legacy Document

Inside Macintosh: Interapplication Communication /

Chapter 12 - Data Access Manager / Data Access Manager Reference

Data Structures

The Query Record

The DBGetNewQuery function converts a 'qrsc' resource in a query document into a query record in memory and returns a handle to the query record. The query record specifies connection information and also contains a handle to an array of queries; each query can be either a complete query or a template for a query. The DBGetNewQuery function creates the queries from the 'wstr' resources stored in the query document.

The QueryRecord data type defines a query record.

TYPE QueryRecord = 
   RECORD
      version:    Integer;          {query record format version}
      id:         Integer;          {resource ID of 'qrsc'}
      queryProc:  Handle;           {handle to qdef}
      ddevName:   Str63;            {name of database extension}
      host:       Str255;           {name of host computer}
      user:       Str255;           {name of user}
      password:   Str255;           {user's password}
      connStr:    Str255;           {connection string}
      currQuery:  Integer;          {index of current query}
      numQueries: Integer;          {number of queries in list}
      queryList:  QueryListHandle;  {handle to array of }
                                    { handles to text}
      numRes:     Integer;          {number of resources in list}
      resList:    ResListHandle;    {handle to array of resource }
                                    { list elements}
      dataHandle: Handle;           {handle to memory for qdef}
      refCon:     LongInt;          {reserved for use by app}
   END;
QueryPtr    = ^QueryRecord;         {pointer to query record}
QueryHandle = ^QueryPtr;            {handle to query record}

Field Description

version

The version number of the query record format. For the Data Access Manager released with System 7, the version number is 0.

id

The resource ID of the 'qrsc' resource from which the Data Access Manager created this query record.

queryProc

A handle to the query definition function that the DBStartQuery function calls. This handle is NIL if there is no query definition function--that is, if the DBStartQuery function should send the query specified by this query record to the data server without modifications.

ddevName

The database extension name used as a parameter to the DBInit function.

host

The name of the host computer system used as a parameter to the DBInit function.

user

The name of the user, used as a parameter to the DBInit function.

password

The user's password, used as a parameter to the DBInit function.

connStr

The connection string used as a parameter to the DBInit function.

currQuery

An index value from 1 through numQueries, indicating which element in the array of query handles represents the current query. The current query is the one actually sent to the data server. If the query document contains more than one 'wstr' resource, the query definition function can prompt the user to select a new current query and modify this field in the query record appropriately.

numQueries

The number of queries referred to by the queryList field.

queryList

A handle to an array of handles. Each handle in this array refers to a query. Each query is created from a 'wstr' resource in the query document and is stored in memory as a 2-byte length field followed by ASCII text. (The length does not include the 2 bytes of the length field.) The query definition function can create a new query. To add a new handle to the array of handles, use the Memory Manager's SetHandleSize function to increase the size of the array. Don't forget to change the value of the numQueries field as well.

numRes

The number of resources referred to by the resList field.

resList

A handle to an array of records of type ResListElem. Each record in the array contains the type and ID of a resource that is needed by the query definition function.

               TYPE ResListElem = 
                  RECORD
                     theType: ResType;    {resource type}
                     id:      Integer;    {resource ID}
                  END;

dataHandle

A handle to memory for use by the query definition function. When the Data Access Manager first creates the query record, it sets this field to NIL. The query definition function can allocate memory and place a handle to it in this field. The query definition function should dispose of any memory it allocates before it returns control to the Data Access Manager.

refCon

The query record's reference value. The application can use this field for any purpose.