Legacy Document

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 macro	Selector
_DBInit	$0E02

RESULT CODES

noErr	0	No error
rcDBError	-802	Error initiating session
rcDBBadDDev	-808	Couldn't find the specified database extension, or error occurred in opening database extension
rcDBAsyncNotSupp	-809	The database extension does not support asynchronous calls
rcDBPackNotInited	-813	The 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.