Important: The information in this document is obsolete and should not be used for new development.
DBInit
Use theDBInit
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, theDBInit
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 thannoErr
. In the latter case, you can pass the session ID to theDBGetErr
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 theDBInit
function returns a nonzero session ID, you must call theDBEnd
function to terminate the session, even if theDBInit
function also returns a result code other thannoErr
.Because the high-level function
DBStartQuery
can call theDBInit
function, you do not have to call theDBInit
function if you have called theDBStartQuery
function.SPECIAL CONSIDERATIONS
TheDBInit
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 theDBInit
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 calledSEE 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 theDBInit
function. See page 12-64 for a description of theDBStartQuery
function. TheDBEnd
function is described next.