Legacy Document

Inside Macintosh: Interapplication Communication /

Chapter 12 - Data Access Manager / Data Access Manager Reference

Data Structures

The Results Record

The results record describes the data that was returned by a data source in response to a query. To get the results of a query, allocate a results record and pass this record to the DBGetQueryResults function. The Data Access Manager allocates the handles inside the results record. When your application is finished using the results record, you must deallocate both the results record and the handles inside the results record.

The results record is defined by the ResultsRecord data type.

TYPE ResultsRecord = 
   RECORD
      numRows:    Integer;          {number of rows retrieved}
      numCols:    Integer;          {number of columns per row}
      colTypes:   ColTypesHandle;   {type of data in each column}
      colData:    Handle;           {array of data items}
      colInfo:    ColInfoHandle;    {info about each data item}
   END;

Field Description

numRows

The total number of rows retrieved. If the DBGetQueryResults function returns a result code other than rcDBValue, then not all of the data actually returned by the data source was retrieved. This could happen, for instance, if the user's computer does not have sufficient memory space to hold all the data. In this case, your application can make more space available (by writing the data in the data record to disk, for example) and then call the DBGetQueryResults function again to complete retrieval of the data.

Note

The DBGetQueryResults function retrieves whole rows only; if it runs out of space in the middle of a row, it stores the partial row in a private buffer so that the data in the results record ends with the last complete row. Because the last partial row is no longer available from the data server, you cannot start to retrieve data with the DBGetQueryResults function and then switch to the DBGetItem function to complete the data retrieval.

numCols

The number of columns in each row of data.

colTypes

A handle to an array of data types, specifying the type of data in each column. The number of elements in the array is equal to the value in the numCols field. Table 12-1 beginning on page 12-39 shows the standard data types.

colData

A handle to the data retrieved by the DBGetQueryResults function.

colInfo

A handle to an array of records of type DBColInfoRecord, each of which specifies the length, places, and flags for a data item. There are as many records in the array as there are data items retrieved by the DBGetQueryResults function. Here is the DBColInfoRecord type definition:

               TYPE DBColInfoRecord = 
                  RECORD
                     len:     Integer;    {length of data item}
                     places:  Integer;    {places for decimal }
                                          { and money data items}
                     flags:   Integer;    {flags for data item}
                  END;

The len field indicates the length of the data item. The DBGetQueryResults function returns a value in this field only for those data types that do not have implied lengths; see Table 12-1 on page 12-39 for a list of these data types.

The places field indicates the number of decimal places in data items of types typeMoney and typeDecimal. For all other data types, the places field returns 0.

The least significant bit of the flags field is set to 1 if the data item is in the last column of the row. The third bit of the flags field is 1 if the data item is NULL. You can use the constants kDBLastColFlag and kDBNullFlag to test for these flag bits.