Legacy Document
Important: The information in this document is obsolete and should not be used for new development.
Important: The information in this document is obsolete and should not be used for new development.
Summary of the Data Access Manager
Pascal Summary
Constants
CONST gestaltDBAccessMgrAttr = 'dbac'; {Gestalt selector for } { Data Access Manager} {Gestalt selector response} gestaltDBAccessMgrPresent = 0; {TRUE if Data Access Manager } { is present} {DBStartQuery status messages} kDBUpdateWind = 0; {update windows} kDBAboutToInit = 1; {about to call DBInit} kDBInitComplete = 2; {DBInit has completed} kDBSendComplete = 3; {DBSend has completed} kDBExecComplete = 4; {DBExec has completed} kDBStartQueryComplete = 5; {DBStartQuery is about } { to complete} {DBGetQueryResults status messages} kDBGetItemComplete = 6; {DBGetItem has completed} kDBGetQueryResultsComplete = 7; {DBGetQueryResults has } { completed data types} {data type codes} typeNone = 'none'; {no more data expected} typeDate = 'date'; {date} typeTime = 'time'; {time} typeTimeStamp = 'tims'; {date and time} typeDecimal = 'deci'; {decimal number} typeMoney = 'mone'; {money value} typeVChar = 'vcha'; {variable character} typeVBin = 'vbin'; {variable binary} typeLChar = 'lcha'; {long character} typeLBin = 'lbin'; {long binary} typeDiscard = 'disc'; {discard next data item} typeBoolean = 'bool'; {Boolean} typeChar = 'TEXT'; {character} typeSMInt = 'shor'; {short integer} typeInteger = 'long'; {integer} typeSMFloat = 'sing'; {short floating point} typeFloat = 'doub'; {floating point} {dummy data types for DBResultsToText} typeUnknown = 'unkn'; {result handler for unknown } { data type} typeColBreak = 'colb'; {result handler for column } { break} typeRowBreak = 'rowb'; {result handler for end of } { line} {any data type in DBGetItem} typeAnyType = 0; {any data type} {infinite timeout value for DBGetItem} kDBWaitForever = -1; {infinite timeout value for } { DBGetItem} {flags for DBGetItem} kDBLastColFlag = $0001; {data item is last column } { of the row} kDBNullFlag = $0004; {data item is NULL}Data Types
TYPE DBType = OSType; {data type} DBAsyncParamBlockRec = {asynchronous parameter block} RECORD completionProc: ProcPtr; {pointer to completion routine} result: OSErr; {result of call} userRef: LongInt; {reserved for use by } { application} ddevRef: LongInt; {reserved for use by database } { extension} reserved: LongInt; {reserved for use by } { Data Access Mgr} END; DBAsyncParmBlkPtr = ^DBAsyncParamBlockRec; ResListElem = {resource list in QueryRecord} RECORD theType: ResType; {resource type} id: Integer; {resource ID} END; ResListArray = ARRAY[0..255] OF ResListElem; ResListPtr = ^ResListArray; ResListHandle = ^ResListPtr; QueryRecord = RECORD version: Integer; {query record format version} id: Integer; {resource ID of 'qrsc'} queryProc: Handle; {handle to query def proc} 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 query def proc} refCon: LongInt; {reserved for use by application} END; QueryPtr = ^QueryRecord; {pointer to query record} QueryHandle = ^QueryPtr; {handle to query record} {query list in QueryRecord} QueryArray = ARRAY[0..255] OF Handle; QueryListPtr = ^QueryArray; QueryListHandle = ^QueryListPtr; {column types array in ResultsRecord} ColTypesArray = ARRAY[0..255] OF DBType; ColTypesPtr = ^ColTypesArray; ColTypesHandle = ^ColTypesPtr; DBColInfoRecord = {column info in ResultsRecord} RECORD len: Integer; {length of data item} places: Integer; {places for decimal and money } { data items} flags: Integer; {flags for data item} END; ColInfoArray = ARRAY[0..255] OF DBColInfoRecord; ColInfoPtr = ^ColInfoArray; ColInfoHandle = ^ColInfoPtr; {structure of results returned by DBGetResults} 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; {DBColInfoRecord array--info about } { each data item} END;Data Access Manager Routines
Initializing the Data Access Manager
FUNCTION InitDBPack:OSErr;High-Level Interface: Handling Query Documents
FUNCTION DBGetNewQuery(queryID: Integer; VAR query: QueryHandle) : OSErr; FUNCTION DBDisposeQuery(query: QueryHandle): OSErr; FUNCTION DBStartQuery(VAR sessID: LongInt; query: QueryHandle; statusProc: ProcPtr; asyncPB: DBAsyncParmBlkPtr): OSErr;High-Level Interface: Handling Query Results
FUNCTION DBGetQueryResults(sessID: LongInt; VAR results: ResultsRecord; timeout: LongInt; statusProc: ProcPtr; asyncPB: DBAsyncParmBlkPtr): OSErr; FUNCTION DBResultsToText(results: ResultsRecord; VAR theText: Handle) : OSErr;Low-Level Interface: Controlling the Session
FUNCTION DBInit(VAR sessID: LongInt; ddevName: Str63; host: Str255; user: Str255; password: Str255; connStr: Str255; asyncPB: DBAsyncParmBlkPtr) : OSErr; FUNCTION DBEnd(sessID: LongInt; asyncPB: DBAsyncParmBlkPtr): OSErr; FUNCTION DBGetConnInfo(sessID: LongInt; sessNum: Integer; VAR returnedID: LongInt; VAR version: LongInt; VAR ddevName: Str63; VAR host: Str255; VAR user: Str255; VAR network: Str255; VAR connStr: Str255; VAR start: LongInt; VAR state: OSErr; asyncPB: DBAsyncParmBlkPtr) : OSErr; FUNCTION DBGetSessionNum(sessID: LongInt; VAR sessNum: Integer; asyncPB: DBAsyncParmBlkPtr): OSErr; FUNCTION DBKill(asyncPB: DBAsyncParmBlkPtr): OSErr;Low-Level Interface: Sending and Executing Queries
FUNCTION DBSend(sessID: LongInt; text: Ptr; len: Integer; asyncPB: DBAsyncParmBlkPtr): OSErr; FUNCTION DBSendItem(sessID: LongInt; dataType: DBType; len: Integer; places: Integer; flags: Integer; buffer: Ptr; asyncPB: DBAsyncParmBlkPtr) : OSErr; FUNCTION DBExec(sessID: LongInt; asyncPB: DBAsyncParmBlkPtr) : OSErr; FUNCTION DBState(sessID: LongInt; asyncPB: DBAsyncParmBlkPtr) : OSErr; FUNCTION DBGetErr(sessID: LongInt; VAR err1: LongInt; VAR err2: LongInt; VAR item1: Str255; VAR item2: Str255; VAR errorMsg: Str255; asyncPB: DBAsyncParmBlkPtr): OSErr; FUNCTION DBBreak(sessID: LongInt; abort: Boolean; asyncPB: DBAsyncParmBlkPtr): OSErr;Low-Level Interface: Retrieving Results
FUNCTION DBGetItem(sessID: LongInt; timeout: LongInt; VAR dataType: DBType; VAR len: Integer; VAR places: Integer; VAR flags: Integer; buffer: Ptr; asyncPB: DBAsyncParmBlkPtr): OSErr; FUNCTION DBUnGetItem(sessID: LongInt; asyncPB: DBAsyncParmBlkPtr): OSErr;Installing and Removing Result Handlers
FUNCTION DBInstallResultHandler (dataType: DBType; theHandler: ProcPtr; isSysHandler: Boolean): OSErr; FUNCTION DBGetResultHandler(dataType: DBType; VAR theHandler: ProcPtr; getSysHandler: Boolean): OSErr; FUNCTION DBRemoveResultHandler (dataType: DBType): OSErr;Application-Defined Routines
FUNCTION MyStatusFunc(message: Integer; result: OSErr; dataLen: Integer; dataPlaces: Integer; dataFlags: Integer; dataType: DBType; dataPtr: Ptr): Boolean; FUNCTION MyResultHandler(dataType: DBType; theLen: Integer; thePlaces: Integer; theFlags: Integer; theData: Ptr; theText: Handle): OSErr; FUNCTION MyQDef(VAR sessID: LongInt; query: QueryHandle): OSErr;C Summary
Constants
enum { #define gestaltDBAccessMgrAttr 'dbac' /*Gestalt selector for */ /* Data Access Manager*/ /*Gestalt selector response*/ gestaltDBAccessMgrPresent = 0 /*TRUE if Data Access Manager */ /* is present*/ }; enum { /*DBStartQuery status messages*/ kDBUpdateWind = 0, /*update windows*/ kDBAboutToInit = 1, /*about to call DBInit*/ kDBInitComplete = 2, /*DBInit has completed*/ kDBSendComplete = 3, /*DBSend has completed*/ kDBExecComplete = 4, /*DBExec has completed*/ kDBStartQueryComplete = 5 /*DBStartQuery is about */ /* to complete*/ }; enum { /*DBGetQueryResults status messages*/ kDBGetItemComplete = 6, /*DBGetItem has completed*/ kDBGetQueryResultsComplete = 7, /*DBGetQueryResults has */ /* completed data types*/ /*data type codes*/ #define typeNone 'none' /*no more data expected*/ #define typeDate 'date' /*date*/ #define typeTime 'time' /*time*/ #define typeTimeStamp 'tims' /*date and time*/ #define typeDecimal 'deci' /*decimal number*/ #define typeMoney 'mone' /*money value*/ #define typeVChar 'vcha' /*variable character*/ #define typeVBin 'vbin' /*variable binary*/ #define typeLChar 'lcha' /*long character*/ #define typeLBin 'lbin' /*long binary*/ #define typeDiscard 'disc' /*discard next data item*/ /*dummy data types for DBResultsToText*/ #define typeUnknown 'unkn' /*result handler for unknown */ /* data type*/ #define typeColBreak 'colb' /*result handler for */ /* column break*/ #define typeRowBreak 'rowb' /*result handler for */ /* end of line*/ /*any data type in DBGetItem*/ #define typeAnyType (DBType)0 /*any data type*/ /*infinite timeout value for DBGetItem*/ kDBWaitForever = -1, /*infinite timeout value for */ /* DBGetItem*/ /*flags for DBGetItem*/ kDBLastColFlag = 0x0001,/*data item is last column */ /* of the row*/ kDBNullFlag = 0x0004 /*data item is NULL*/ }; enum { /*more data type codes*/ typeBoolean = 'bool', /*Boolean*/ typeChar = 'TEXT', /*character*/ typeSMInt = 'shor', /*short integer*/ typeInteger = 'long', /*integer*/ typeSMFloat = 'sing', /*short floating point*/ typeFloat = 'doub' /*floating point*/ };Data Types
typedef OSType DBType; /*data type*/ struct DBAsyncParamBlockRec { /*asynchronous parameter block*/ ProcPtr completionProc; /*pointer to completion routine*/ OSErr result; /*result of call*/ long userRef; /*reserved for use by application*/ long ddevRef; /*reserved for use by database */ /* extension*/ long reserved; /*reserved for use by */ /* Data Access Manager*/ }; typedef struct DBAsyncParamBlockRec DBAsyncParamBlockRec; typedef DBAsyncParamBlockRec *DBAsyncParmBlkPtr; struct ResListElem { /*resource list in QueryRecord*/ ResType theType; /*resource type*/ short id; /*resource ID*/ }; typedef struct ResListElem ResListElem; typedef ResListElem *ResLisPtr, **ResListHandle; typedef Handle **QueryListHandle; struct QueryRecord { /*query record*/ short version; /*query record format version*/ short id; /*resource ID of 'qrsc'*/ Handle queryProc; /*handle to query def proc*/ Str63 ddevName; /*name of database extension*/ Str255 host; /*name of host computer*/ Str255 user; /*name of user*/ Str255 password; /*user's password*/ Str255 connStr; /*connection string*/ short currQuery; /*index of current query*/ short numQueries; /*number of queries in list*/ QueryListHandle queryList; /*handle to array of handles to text*/ short numRes; /*number of resources in list*/ ResListHandle resList; /*handle to array of resource list */ /* elements*/ Handle dataHandle; /*handle to memory for query def proc*/ long refCon; /*reserved for use by application*/ }; typedef struct QueryRecord QueryRecord; typedef QueryRecord *QueryPtr, **QueryHandle; /*column types array in ResultsRecord*/ typedef Handle ColTypesHandle; struct DBColInfoRecord { /*column info in ResultsRecord*/ short len; /*length of data item*/ short places; /*places for decimal and money */ /* data items*/ short flags; /*flags for data item*/ }; typedef struct DBColInfoRecord DBColInfoRecord; typedef Handle ColInfoHandle; struct ResultsRecord { /*results returned by DBGetResults*/ short numRows; /*number of rows retrieved*/ short numCols; /*number of columns per row*/ ColTypesHandle colTypes; /*type of data in each column*/ Handle colData; /*array of data items*/ ColInfoHandle colInfo; /*DBColInfoRecord array--info about */ /* each data item*/ }; typedef struct ResultsRecord ResultsRecord;Data Access Manager Routines
Initializing the Data Access Manager
pascal OSErr InitDBPack (void);High-Level Interface: Handling Query Documents
pascal OSErr DBGetNewQuery(short queryID, QueryHandle *query); pascal OSErr DBDisposeQuery(QueryHandle query); pascal OSErr DBStartQuery(long *sessID, QueryHandle query, ProcPtr statusProc, DBAsyncParmBlkPtr asyncPB);High-Level Interface: Handling Query Results
pascal OSErr DBGetQueryResults (long sessID, ResultsRecord *results, long timeout, ProcPtr statusProc, DBAsyncParmBlkPtr asyncPB); pascal OSErr DBResultsToText (ResultsRecord *results, Handle *theText);Low-Level Interface: Controlling the Session
pascal OSErr DBInit(long *sessID, ConstStr63Param ddevName, ConstStr255Param host, ConstStr255Param user, ConstStr255Param passwd, ConstStr255Param connStr, DBAsyncParmBlkPtr asyncPB); pascal OSErr DBEnd(long sessID, DBAsyncParmBlkPtr asyncPB); pascal OSErr DBGetConnInfo(long sessID, short sessNum, long *returnedID, long *version, Str63 ddevName, Str255 host, Str255 user, Str255 network, Str255 connStr, long *start, OSErr *state, DBAsyncParmBlkPtr asyncPB); pascal OSErr DBGetSessionNum (long sessID, short *sessNum, DBAsyncParmBlkPtr asyncPB); pascal OSErr DBKill(DBAsyncParmBlkPtr asyncPB);Low-Level Interface: Sending and Executing Queries
pascal OSErr DBSend(long sessID, char *text, short len, DBAsyncParmBlkPtr asyncPB); pascal OSErr DBSendItem(long sessID, DBType dataType, short len, short places, short flags, void *buffer, DBAsyncParmBlkPtr asyncPB); pascal OSErr DBExec(long sessID, DBAsyncParmBlkPtr asyncPB); pascal OSErr DBState(long sessID, DBAsyncParmBlkPtr asyncPB); pascal OSErr DBGetErr(long sessID, long *err1, long *err2, Str255 item1, Str255 item2, Str255 errorMsg, DBAsyncParmBlkPtr asyncPB); pascal OSErr DBBreak(long sessID, Boolean abort, DBAsyncParmBlkPtr asyncPB);Low-Level Interface: Retrieving Results
pascal OSErr DBGetItem(long sessID, long timeout, DBType *dataType, short *len, short *places, short *flags, void *buffer, DBAsyncParmBlkPtr asyncPB); pascal OSErr DBUnGetItem(long sessID, DBAsyncParmBlkPtr asyncPB);Installing and Removing Result Handlers
pascal OSErr DBInstallResultHandler (DBType dataType, ProcPtr theHandler, Boolean isSysHandler); pascal OSErr DBGetResultHandler (DBType dataType, ProcPtr *theHandler, Boolean getSysHandler); pascal OSErr DBRemoveResultHandler (DBType dataType);Application-Defined Routines
pascal Boolean MyStatusFunc(short message, OSErr result, short dataLen, short dataPlaces, short dataFlags, DBType dataType, Ptr dataPtr); pascal OSErr MyResultHandler (DBType dataType, short theLen, short thePlaces, short theFlags, Ptr theData, Handle theText); pascal OSErr MyQDef(long *sessID, QueryHandle query);Assembly-Language Summary
Trap Macros
Trap Macros Requiring Routine Selectors
_Pack13
Selector Routine $0100 InitDBPack$020E DBKill$0210 DBDisposeQuery$0215 DBRemoveResultHandler$030F DBGetNewQuery$0403 DBEnd$0408 DBExec$0409 DBState$040D DBUnGetItem$0413 DBResultsToText$050B DBBreak$0514 DBInstallResultHandler$0516 DBGetResultHandler$0605 DBGetSessionNum$0706 DBSend$0811 DBStartQuery$0A12 DBGetQueryResults$0B07 DBSendItem$0E02 DBInit$0E0A DBGetErr$100C DBGetItem$1704 DBGetConnInfoResult Codes