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

DBGetConnInfo

The DBGetConnInfo function returns information about the specified session, including

• the version of the database extension
• the name of the host system on which the session is running
• the user name
• the connection string that was used to initiate communication
• the name of the network
• the time at which the session started, in ticks (sixtieths of a second)
• the status of the session

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;

sessID

The session ID that was returned by the DBInit function. If you include a nonzero value for the sessID parameter when you call the DBGetConnInfo function, the function returns the name of the database extension in the ddevName parameter. If you use 0 for the sessID parameter and specify the database extension and session number instead (in the ddevName and sessNum parameters), the function returns the session ID in the returnedID parameter.

sessNum

The session number of the session about which you want information. If you specify a nonzero session number, you must also provide the database extension in the ddevName parameter.

returnedID

Returns the session ID if you specify the session number and the database extension.

version

Returns the version number of the database extension that is currently in use.

ddevName

A string of no more than 63 characters that specifies the name of the database extension. If you specify 0 for the session ID, you must include the name of the database extension as well as a session number. If you specify a valid session ID, then the DBGetConnInfo function returns the name of the database extension in the ddevName parameter. 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

Returns the host string used to initiate communication with the data server.

user

Returns the user string used to initiate communication with the data server.

network

Returns the name of the network through which the database extension is communicating with the data server. This parameter is an empty string if you are not communicating through a network.

connStr

Returns the connection string used to initiate communication with the data server.

start

Returns the time, in ticks (sixtieths of a second), at which this session was initiated.

state

Returns one of the following values to provide information about the status of the session:

   CONST  noErr    =    0;   {no error--ready for more }
            { text}
     rcDBValue    = -801;   {output data available}
     rcDBError    = -802;   {execution ended in an }
            { error}
     rcDBExec    = -805;   {busy--currently executing }
            { query}

asynchPB

A pointer to an asynchronous parameter block. If you do not want to call the function asynchronously, set this parameter to NIL.

DESCRIPTION

You can use the DBGetConnInfo function to get information about a particular session, or you can call the function repeatedly, incrementing the session number each time, to get information about all of the sessions associated with a particular database extension.

The sessID parameter is the session ID that was returned by the DBInit function. The sessNum parameter is the session number of the session about which you want information. You can specify either the session ID or the session number when you call the DBGetConnInfo function. If you specify the sessID parameter, use 0 for the sessNum parameter. If you specify the sessNum parameter, then use 0 for the sessID parameter. If you specify the sessNum parameter, you must specify a value for the ddevName parameter as well. If you specify the session number and the database extension, then the DBGetConnInfo function returns the session ID in the returnedID parameter.

SPECIAL CONSIDERATIONS

The DBGetConnInfo 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 DBGetConnInfo function are

Trap macro	Selector
_DBGetConnInfo	$1704

RESULT CODES

noErr	0	No error
rcDBBadSessID	-806	Session ID is invalid or database extension name is invalid
rcDBBadSessNum	-807	Invalid session number
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. For more information on the use of the DBGetConnInfo function, see "Getting Information About Sessions in Progress" on page 12-36.