Q_CONNECT

This command establishes a connection to the data source you specify.

Syntax

The "Read-only" setting only works if the ODBC driver supports a Read-only connection.

Q_CONNECT connection_number, "connection_string", "use_GainSeeker_ODBC_driver", "read-only_connection"

connection_number

This parameter must be a number from 1 to 10.

A template may have up to 10 distinct connections to external data sources. A separate data buffer is maintained for each connection.

If you specify a connection_number that already has an active connection to a data source, that previous connection will automatically be disconnected and any queries on that previous connection will be ended.

connection_string

This parameter specifies the name of the data source and any connection information needed to connect to it. There are three basic options for setting this parameter:

• "datasource_name"

• Use this option to specify the name of any ODBC data source name that requires no additional connection information, such as a Pervasive database or for a SQL Server database using Windows NT authentication.

• To view a list of ODBC data source names, launch the ODBC Data Source Administrator.

  Click Start, and then click Control Panel. Double-click Administrative Tools., and then double-click Data Sources (ODBC).

• "datasource_name;connect_information"

• Use this option to specify the name of any ODBC data source name for which additional connection information is required, such as an Oracle database, a MySQL database, or a SQL Server database using SQL Server authentication – all of which require a database login name and password.

• datasource_name

• To view a list of ODBC data source names, launch the ODBC Data Source Administrator.

  Click Start, and then click Control Panel. Double-click Administrative Tools., and then double-click Data Sources (ODBC).

• connect_information

For many data sources, you must specify a login name and password (or encrypted password) for the database.

1. • the database login name and password are usually specified as uid=name;pwd=password

   • the database login name and encrypted password are usually specified as uid=name;pwde=encrypted_password
     
     For information on setting up an encrypted password, please contact technical support.

   • the database login name and strongly encrypted password are usually specified as uid=name;pwdse=strongly_encrypted_password

• "<default>"

• When connecting to the GainSeeker database, use this option to automatically detect connection information (except when using dsn=iList or using command line parameters that specify a database login name and password).

  This option will determine the data source name and database login name and password as follows:

  1.  Read the data source name from the dsn= setting in Cms.ini. If this setting is blank or does not exist, read the config_db= setting to determine whether to use the default GainSeeker data source name for a Pervasive database (GainSeeker71_B) or for an Oracle, SQL Server or MySQL database (GainSeeker71_O).

  2.  Read the database login name from the dbnm= setting.

  3.  Read the encrypted password from the dbpwe= setting. If this setting is blank or does not exist, read the password from the dbpw= setting.

use_GainSeeker_ODBC_driver

• When connecting to the GainSeeker data source on a Pervasive or Oracle database, this parameter must be set to "Y". This sets license information needed for the Pervasive and Oracle drivers used by GainSeeker.

• For any other data source, this parameter must be set to any other string value, such as "N" or a blank string.

read-only_connection

• To establish a read-only connection to the data source, set this parameter to "Y". This prevents you from accidentally changing information in the data source.

• To establish a connection that will allow you to add, modify or delete data in the data source, set this parameter to any other string value, such as "N" or a blank string.

Return value

If the connection to the data source is successful, this command returns the number 1.

Otherwise, it returns the number 0. To understand why the connection was not successful, use Q_ERROR and Q_ERRORDESC.

Notes

The template automatically adds "dsn=" to the beginning of the connection_string parameter.

For a sample template that connects to a data source and then queries the data source, see Database Query Commands.

Examples

Q_CONNECT 1, "GainSeeker71_B", "Y", "N"

This formula uses data source connection number 1 to establish a connection to the "GainSeeker71_B" data source. It also specifies that the "GainSeeker71_B" data source is a GainSeeker ODBC driver and that this is not a read-only connection.

Q_CONNECT 2, "<default>", "Y", "Y"

This formula uses data source connection number 2 to establish a connection to the GainSeeker database. It also specifies that the GainSeeker database is a GainSeeker ODBC driver and that this is a read-only connection.

Q_CONNECT 3, "Production_db;uid=Prod;pwde=NsDf", "N", "Y"

This formula uses data source connection number 3 to establish a connection to the "Production_db" data source with user name "Prod" and encrypted password "NsDf". It also specifies that the "Production_db" data source is not a GainSeeker ODBC driver and that this is a read-only connection.