SQLSTRINGCONNECT( ) Function
Establishes a connection to a data source using a connection string.
SQLSTRINGCONNECT([lShared] | [cConnectString [, lSharable]])
Parameters
lShared
Specifies whether to create a shared connection.lShared
Description
False (.F.)
SQLSTRINGCONNECT( ) does not create a shared connection. (Default)
True (.T.)
SQLSTRINGCONNECT( ) creates a shared connection.
cConnectString
Specifies the data source connection string required by some Open Database Connectivity (ODBC) drivers. Visual FoxPro passes the connection string to the ODBC driver. For more information about data source connection strings, see your ODBC driver documentation.You can also choose a data source from the Select Connection or Data Source Dialog Box, which appears when you call SQLSTRINGCONNECT( ) without cConnectString.
lSharable
Specifies if the data source specified with cConnectString has a shared connection.
Return Value
Numeric data type. SQLSTRINGCONNECT( ) returns a positive nonzero numeric value as the statement handle if you successfully connect to the data source. SQLSTRINGCONNECT( ) returns –1 if it cannot make the connection.
Tip
You should store this statement handle in a memory variable and use the variable in subsequent function calls that require a connection handle.
Remarks
The SQLCONNECT( ) and SQLSTRINGCONNECT( ) functions return a numeric value as the statement handle rather than a connection handle. You cannot obtain a connection handle directly. You can still set and get connection properties using the SQLSETPROP( ) and SQLGETPROP( ) functions by passing the statement handle for that connection and the string, "Shared", as arguments. All other SQL functions use a statement handle instead of a connection handle.
SQLSTRINGCONNECT( ) always creates a new connection when it successfully makes a connection. However, setting the lShared parameter determines whether you can share the connection later. If you specify a connection as shareable by setting lShared to True (.T.), you can share the connection later by calling SQLCONNECT( ) and passing the numeric value of the connection handle as the first parameter. For more information, see SQLCONNECT( ) Function.
You can use SQLCONNECT( ) to obtain a new statement handle on a shared connection that was opened using SQLSTRINGCONNECT( ).
Example
Example 1
The following example assumes that an ODBC data source called MyFoxSQLNT exists and is available. SQLSTRINGCONNECT( ) returns a numeric value, which is stored to a variable named gnHandle.
If you successfully connect to the data source, SQLSTRINGCONNECT( ) returns a positive number, a dialog box appears, and SQLDISCONNECT( ) is called to disconnect from the data source.
If you cannot connect to the data source, SQLSTRINGCONNECT( ) returns a negative number and displays a message.
STORE SQLSTRINGCONNECT('dsn=MyFoxSQLNT;uid=myUserID;pwd=myPassword')
TO gnConnHandle
IF gnConnHandle < 0
= MESSAGEBOX('Cannot make connection', 16, 'SQL Connect Error')
ELSE
= MESSAGEBOX('Connection made', 48, 'SQL Connect Message')
= SQLDISCONNECT(gnHandle)
ENDIF
Example 2
The following examples show how you can use the SQLSTRINGCONNECT( ) function without a Data Source Name (DSN).
lcDSNLess="driver = SQL Server;server=<servername>;uid=<userid>;pwd=<password>"
-or-
lcDSNLess="driver = {SQL Server};server=<servername>;uid=<userid>;pwd=<password>"
-or-
lcDSNLess="DRIVER = {SQL Server};" ;
+ "SERVER=<servername>;" ;
+ "UID=<userid>;" ;
+ "PWD=<password>;" ;
+ "DATABASE=PUBS;" ;
+ "WSID=<machine name or userid>;" ;
+ "APP=MicroX(R) Sample App"
lnConnHandle=SQLSTRINGCONNECT(m.lcDSNLess)
Example 3
Each of the following examples creates a new shared connection. In the first statement, the Select Connection or Data Source Dialog Box appears and SQLSTRINGCONNECT( ) creates the resulting connection as shared.
SQLSTRINGCONNECT(.T.)
SQLSTRINGCONNECT('myConnectionString', .T.)