Sets the connection handle for all successive table opens.

Syntax

AX_SetConnectionHandle( <hConnection> ) -> nil

 

Returns

This function always succeeds. Nil is always returned.

Description

AX_SetConnectionHandle sets the Advantage connection handle that will be used by the Advantage RDD for all future operations that cause a table to be opened. If no connection handle has been set (i.e., this function has never been called with a specific Advantage connection handle, or this function has been called with a parameter value of 0 to clear the connection handle), all future operations that cause a table to be opened will use an existing connection if one to the same server type exists. In cases where a connection to the server doesn't exist or can't be used, a new connection will be created. For example, an existing connection to the Advantage Internet Server will not be used when opening a table via the Advantage Database server. Instead, a new connection will be created and used. This is due to the server types of the existing connection and the requested connection being different.

The only way to open a database table is to use this function with a connection handle to the appropriate Advantage Data Dictionary file. Use of this function is also required when connecting to the Advantage Internet Server. This connection handle can be used along with the AX_Transaction function.

Object-oriented Example

LOCAL oDB AS DBServer

LOCAL dwError AS DWORD

LOCAL pacError AS PSZ

LOCAL wLen AS WORD

LOCAL lReturn AS LONGINT

LOCAL hConnect AS LONGINT

 

pacError := MemAlloc( 200 )

wLen := 200

dwError := AE_SUCCESS

 

/*

* HandleErrors is a function you may write to catch and handle connection errors.

*/

HandleErrors( AdsConnect60( "X:\DATA\TEST.ADD", ADS_REMOTE_SERVER, ;

"UserName", "Password", ADS_INC_USERCOUNT, @hConnect ))

 

/* Set the connection handle */

AX_SetConnectionHandle( hConnect )

 

/*

* Since a database path is specified in the connection, it does not need

* to be specified here. No extension to the table name is needed unless the

* table name in the Data Dictionary includes an extension.

*/

oDB := DBServer {"MYTABLE", DBShared,, "ADSADT"}

 

AdsGetLastError( @dwError, pacError, @wLen)

IF dwError != AE_SUCCESS

ErrorBox{ , " Advantage error = " + Psz2String(pacError) }:Show()

ENDIF

ErrorBox{ , " SUCCESS" }:Show()

 

/* Clear the connection handle. It is not required to clear the connection handle unless

* you no longer want to use hConnect as the connection handle for future table opens.

*/

AX_SetConnectionHandle( 0 )

 

oDB:Close()