TODBCConnect

Description: This statement forms a connection to an ODBC database; it is similar to ODBCConnect except that it runs in its own thread (see "Comments" section for differences)

Returns: Nothing

Usage: Script

Format: TODBCConnect(DSName, UserName, Password, DB, ErrorMsg, SQLState, ErrorCode [, Disconnect, LoginTimeout, ConnectionTimeout])

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.

DB { ODBC handle } { required } { no default: }

An ODBC value for the ODBC database once a connection has been established.

ErrorMsg { text (return value) } { required } {default: 0 }

Any variable that will contain the last error message returned by the function. If no errors occurred this parameter will be set to 0 to indicate the termination of the thread.

SQLState { text (return value) } { required } { no default: }

Any variable that will contain the SQL state that the statement was in when the last error occurred.

ErrorCode { numeric (return value) } { required } { no default: }

Any 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 } { no default: false }

An optional parameter which 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.

LoginTimeout { numeric } { optional } { default: 0 }

Sets the period (in seconds) which the driver will wait for a login request to complete. The default value of "0" indicates that there is no timeout.

ConnectionTimeout { numeric } { optional } { default: 0 }

Sets the period (in seconds) which the driver will wait for any request other than a query or login on the connection to complete. The default value of "0" indicates that there is no timeout.

Comments: When TODBCConnect is executed in its script, it starts its own thread and VTS will continue executing. This is similar to ODBCConnect except that execution of the application is not suspended while waiting for the connection to the database (i.e. waiting for the return value to be set). Instead, execution continues and sometime in the future when the connection to the database is established, DB will be set to the ODBC value for the database. If any errors occurred, the error parameters, ErrorMsg, SQLState and ErrorCode, would be set at that time to indicate the nature of the error. ErrorCode will be set to zero if no error occurs.

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.

Example:

Init[

If 1 Wait;

[

TODBCConnect("VTS_data" { Driver name },

" "," " { No user name or password },

ODBCHandle { Handle to use },

ErrMsg, ErrState, ErrCode { Error details });

]

Wait[

If TimeOut(1, Retry) Init { Retry ODBC every Retry seconds };

If Valid(ODBCHandle) Main { If valid connection go to Main };

]