Legacy Documentclose button

Important: The information in this document is obsolete and should not be used for new development.

Previous Book Contents Book Index Next

Inside Macintosh: Interapplication Communication /
Chapter 12 - Data Access Manager / Data Access Manager Reference
Data Access Manager Routines / Low-Level Interface: Controlling the Session


DBInit

Use the DBInit function to initiate a session with a data server.

FUNCTION DBInit (VAR sessID: LongInt; ddevName: Str63; 
                 host: Str255; user: Str255; password: Str255;
                 connStr: Str255; 
                 asyncPB: DBAsyncParmBlkPtr): OSErr;
sessID
The DBInit function returns the session ID in this parameter. This session ID is unique; no other current session, for any database extension, has the same session ID. You must specify the session ID any time you want to send data to or retrieve data from this session. Depending on the database extension you are using, the DBInit function might return a session ID of 0 if it fails to initiate a session, or it might return a nonzero session ID and a result code other than noErr. In the latter case, you can pass the session ID to the DBGetErr function to determine the cause of the error.
ddevName
A string of no more than 63 characters that specifies the name of the database extension. The name of the database extension is contained in the database extension file in a resource of type 'STR ' with a resource ID of 128. For the Data Access Language database extension provided by Apple, for example, this string is "DAL".
host
The name of the host system on which the data server is located. This name depends on the manner in which the database extension initiates communication with the data server and how the system administrator has set up the computer system.
user
The name of the user.
password
The password associated with the user name.
connStr
A string that is passed to the data server, which might pass it on to the database management software on the host computer. This string is necessary in some systems to complete log-on procedures.
asyncPB
A pointer to an asynchronous parameter block. If you do not want to call the function asynchronously, set this parameter to NIL.
DESCRIPTION
You must initiate a session before you call any Data Access Manager function that requires a session ID as an input parameter. If the DBInit function returns a nonzero session ID, you must call the DBEnd function to terminate the session, even if the DBInit function also returns a result code other than noErr.

Because the high-level function DBStartQuery can call the DBInit function, you do not have to call the DBInit function if you have called the DBStartQuery function.

SPECIAL CONSIDERATIONS
The DBInit function may move or purge memory. You should not call this routine from within an interrupt, such as in a completion routine or a VBL task.

ASSEMBLY-LANGUAGE INFORMATION
The trap macro and routine selector for the DBInit function are
Trap macroSelector
_DBInit$0E02

RESULT CODES
noErr0No error
rcDBError-802Error initiating session
rcDBBadDDev-808Couldn't find the specified database extension, or error occurred in opening database extension
rcDBAsyncNotSupp-809The database extension does not support asynchronous calls
rcDBPackNotInited-813The InitDBPack function has not yet been called
SEE ALSO
For a description of the asynchronous parameter block, see page 12-56. See Listing 12-5 beginning on page 12-34 for an example of the use of the DBInit function. See page 12-64 for a description of the DBStartQuery function. The DBEnd function is described next.


Previous Book Contents Book Index Next

© Apple Computer, Inc.
7 JUL 1996