ODBCConnect

Description: This function forms a connection to an ODBC-compliant database and returns the ODBC value associated with that database.

Returns: ODBC database

Usage: Script

Format: ODBCConnect(DSName, UserName, Password [, ErrorMsg, SQLState, ErrorCode, Disconnect])

Parameters: DSName { text } { required } { no default }

Any text expression for the ODBC data source name, as configured in the ODBC setup menu under Microsoft Windows™.

UserName { text } { required } { no default }

Any text expression for the ODBC login user name.

Password { text } { required } { no default }

Any text expression for the ODBC login password.

ErrorMsg { text (return value) } { optional } { no default }

An optional parameter that will contain the last error message returned by the function.

SQLState { numeric (return value) } { optional } { no default }

An optional parameter that will return the SQL state that the statement was in when the last error occurred.

ErrorCode { numeric (return value) } { optional } { no default }

An optional parameter that is a variable that will contain the native error code for the given driver and an error condition for the last error that occurred.

Disconnect { Boolean } { optional } { default: FALSE }

An optional parameter that is any logical expression that determines how errors are to be handled. If true (non-0), the connection to the database will be disconnected should any error (no matter how minor) occur; if false (0) an error will not cause a disconnect to occur. The default value is false.

Comments: If the UserName and Password parameters are specified as invalid, the DSName parameter is treated as a literal connection string for the ODBC connection. For example, in the statement ODBCConnect("DSN=MyData;UID=;PWD=", Invalid, Invalid), the first parameter is used to set the attributes of the connection, which makes this statement equivalent to ODBCConnect("MyData", "", "").

In the case of the optional parameters, any parameter that is not required may be set to 0 if it is followed by a valid parameter, or may be simply omitted if no valid parameters follow it.

With regards to error information returned on successful completion of the ODBC and ODBCConnect functions, the native error code will be set to 0, allowing the user to tell if a command that has no result set has been completed. The user should not assume that since a 0 is returned in the native error code that the command has been executed successfully. Some drivers (such as Excel) will return a 0 in the native error code, even when an error has occurred.

64-bit VTS: 64-bit VTS is able to connect to either 64-bit or 32-bit ODBC data sources. ODBCConnect will first try to connect to the database through a 64-bit ODBC driver. If this fails for any reason it will then try the connection through a 32-bit ODBC driver. This means that any ODBC code that worked under 32-bit VTS should not need to be modified for use with 64-bit VTS, but 64-bit VTS has the extra capability of being able to use 64-bit ODBC drivers.