To create a new User DSN, open the ODBC Setup PPC control panel. Hit the Add button.

Figure3.42.MacOSClass11.gif

Pick the ODBC Driver to be used to create your ODBC DSN, in the case of the OpenLink Universal Data Access Driver Suite 5.0, this would be the Driver identified below as "OpenLink Generic ODBC PPC".

Figure3.43.MacOSClass12.gif

Once you have selected the "OpenLink Generic 32 Bit Driver v5.0", you will be presented with the OpenLink ODBC Data Source Configuration dialog (depicted below).

Figure3.44.MacOSClass13.gif

The Datasource settings are only important to your Client machine; the OpenLink Server, Database, and Optional Server settings should be provided by your Database Administrator, or whoever is handling the Server-side components of the OpenLink Universal Data Access Suite.

	Note:
	The connections will not succeed until Server-side components are installed and properly configured.

Explanations of each field follows:

Datasource Name. The name of the ODBC DSN. This is how you will interact with the OpenLink ODBC Driver from within ODBC compliant applications once your ODBC DSN has been created.

Comment. Additional information that further describes the ODBC DSN that you are creating. This is generally visible whenever a list of DSNs is generated. This option corresponds to the Description parameter in the preference files.

Domain. This is how you pick the Database Engine Type (also called a DBMS, or DataBase Management System) that your ODBC DSN is to be associated with, e.g. Informix 7, Oracle 9, Progress 8.3B, etc. This option corresponds to the ServerType parameter in the preference files.

Protocol. Select the network transport protocol used to connect your ODBC DSN with a remote database engine. This will be TCP/IP in most installations. This option corresponds to the Protocol parameter in the preference files.

Hostname. Enter the hostname or IP address that identifies a Server Machine running OpenLink Server Components, that speak the OpenLink Data Access Protocol. This option corresponds to the Host parameter in the preference files.

Port. Enter the TCP port number of the Broker to contact. This corresponds to the Listen parameter on the target Broker. This option corresponds to the Port parameter in the preference files.

Database Name. This is how an actual database name within the Provider Type Domain is identified, for instance "stores7" indicates an "Informix 7" database called "stores7". This option corresponds to the Database parameter in the preference files.

Username. The default database UserID to be used when logging on to a remote database engine (identified by the Provider Type above). Generally left blank on shared machines. This option corresponds to the User parameter in the preference files.

Server Name. This is where you place any database specific database connection options. This field in a majority of cases should be left blank by default. Your Database Administrator (DBA) should give you any special settings. This option corresponds to the Options parameter in the preference files.

Read-only connection. Forces the connection is to be "Read-only". Make sure the checkbox is unchecked to request a "Read/Write" connection. This option corresponds to the ReadOnly parameter in the preference files.

No Login Dialog Box. Suppress the ODBC "Username" and "Password" login dialog box when interacting with your ODBC DSN from within an ODBC compliant application. This should be unchecked if the database requires this information. This option corresponds to the NoLoginBox parameter in the preference files.

Defer fetching of long data. Check this box to defer the fetching of long data. See the Release Notes section for more details. This option corresponds to the DeferLongFetch parameter in the preference files.

Row Buffer Size. This attribute specifies the number of records to be transported over the network in a single network hop. Values can range from 1 to 999. Smaller values are generally appropriate when each row contains large records; larger values are generally appropriate for smaller record sizes. Adjusting this value up and down can improve or degrade performance substantially, both for your own connection and for other users of the same Database, so check with your DBA before changing it from the default (30). This option corresponds to the FetchBufferSize parameter in the preference files.

Click OK, and you'll see your new DSN in the list.

Figure3.45.MacOSClass14.gif

Now, to verify that your settings are correct and all is functional, select the new DSN, and click Test. You'll be presented with the following dialog.

Figure3.46.MacOSClass15.gif

Input the correct password for the username shown. You can connect as another user, if you wish, by simply typing a different username in the field. To verify that your settings have all "stuck", you can click the Database tab:

Figure3.47.MacOSClass16.gif

The "About" tab shows you basic information about the Driver on which the DSN is based.

Figure3.48.MacOSClass17.gif

When you click OK, your Mac will think for a moment, while it makes a connection to the remote Data Source. If all is well, you will be presented with this Success message:

Figure3.49.MacOSClass18.gif

To create a new File DSN, open the ODBC Setup PPC control panel. Click on the File DSN tab, and follow the steps below:

Click the Add button.

Figure3.50.MacOSClass19.gif

Pick the ODBC Driver to be used to create your ODBC DSN. As with the User DSN, this would be the Driver identified below as "OpenLink Generic ODBC PPC". Input a name for the File DSN, and any description. Click "Finish" or "OK".

Figure3.51.MacOSClass20.gif

File DSNs are configured through the login screens, as if you were connecting through a User DSN. Starting with the Identity tab, input the appropriate Username and Password. (The Password will not be saved in the DSN, as this would present a significant security risk.)

Figure3.52.MacOSClass21.gif

The OpenLink Server, Database, and Optional Server settings seen in the User DSN configuration screen are combined into the Database tab. Again, these should be provided by your Database Administrator, or whoever is handling the Server-side components of the OpenLink Universal Data Access Suite.

	Note:
	The connections will not succeed until Server-side components are installed and properly configured.

Figure3.53.MacOSClass16.gif

Explanations of each field in the Database tab follows:

Domain. This is how you pick the Database Engine Type (also called a DBMS, or DataBase Management System) that your ODBC DSN is to be associated with, e.g. Informix 7, Oracle 9, Progress 8.3B, etc. This option corresponds to the ServerType parameter in the preference files.

Name. This is how an actual database name within the Provider Type Domain is identified, for instance "stores7" indicates an "Informix 7" database called "stores7". This option corresponds to the Database parameter in the preference files.

Server. This is where you place any database specific database connection options. This field in a majority of cases should be left blank by default. Your Database Administrator (DBA) should give you any special settings. This option corresponds to the Options parameter in the preference files.

Hostname. Enter the hostname or IP address that identifies a Server Machine running OpenLink Server Components, that speak the OpenLink Data Access Protocol. This option corresponds to the Host parameter in the preference files.

Protocol. Select the network transport protocol used to connect your ODBC DSN with a remote database engine. This will be TCP/IP in most installations. This option corresponds to the Protocol parameter in the preference files.

Port. Enter the TCP port number of the Broker to contact. This corresponds to the Listen parameter on the target Broker. This option corresponds to the Port parameter in the preference files.

Defer fetching of long data. Check this box to defer the fetching of long data. See the Release Notes section for more details. This option corresponds to the DeferLongFetch parameter in the preference files.

Read-only connection. Forces the connection is to be "Read-only". Make sure the checkbox is unchecked to request a "Read/Write" connection. This option corresponds to the ReadOnly parameter in the preference files.

Row Buffer Size. This attribute specifies the number of records to be transported over the network in a single network hop. Values can range from 1 to 999. Smaller values are generally appropriate when each row contains large records; larger values are generally appropriate for smaller record sizes. Adjusting this value up and down can improve or degrade performance substantially, both for your own connection and for other users of the same Database, so check with your DBA before changing it from the default (30). This option corresponds to the FetchBufferSize parameter in the preference files.

The About tab, here, refers to the Driver you've selected for this DSN.

Figure3.54.MacOSClass17.gif

Click OK when all settings are correct, and you will see the new DSN available in the File DSN list. Sharing this DSN with other users and machines may be accomplished by going to the 'ODBC File Data Sources' folder, found in the 'Preferences' folder, within your System Folder. Other Macintosh Classic OpenLink clients may use the file by placing it in the same location on their machine.

Figure3.55.MacOSClass22.gif

When the ODBC tracing parameters are changed, they are saved in the [ODBC] section of the ODBC.preference or odbc.ini file, whichever is active on your system.

The following example is for a one time trace to sql.log file on the active user's desktop.

[ODBC]
Trace         = 1
TraceAutoStop = 1
TraceDLL      =
TraceFile     = ~/Desktop/sql.log

Once the tracing of a connection is complete, the Trace and TraceAutoStop parameters will both be set to 0.

Use the 'ODBC SDK 2.0 C++ Sample PPC' application to test a DSN:

Figure3.57.MacOSClass23.gif

From the Environment menu, select "Open Connection...".

Figure3.58.MacOSClass24.gif

Choose a User DSN, or press the File DSN tab, and select a File DSN.

Figure3.59.MacOSClass25.gif

With a DSN highlighted, press OK. Input Username and Password as appropriate, and click OK.

Figure3.60.MacOSClass15.gif

From the SQL menu select Execute SQL...

Figure3.61.MacOSClass26.gif

Enter an SQL query in the dialog.

Figure3.62.MacOSClass27.gif

With success, the results will be shown.

Figure3.63.MacOSClass28.gif

When you QUIT the application, you will see a warning message about your DSN connection. Please note you will continue to consume one licensed connection until the application is terminated.

Figure3.64.MacOSClass29.gif

Use the 'iODBC Test PPC' application to test a DSN:

Figure3.65.MacOSClass30.gif

Type a question mark ('?') and hit <return> to get a list of available User DSNs.

Figure3.66.MacOSClass31.gif

Type a connect string, using one of the listed User DSNs, following the format DSN=<DSN>;UID=<username>;PWD=<password>. You may leave the UID and/or PWD parameters out of your string; if you do, you will be presented with the usual log-in dialog:

Figure3.67.MacOSClass32.gif

If you do not wish to type so much, need to add a DSN, or wish to connect to a File DSN, type anything else, and hit the <return> key. You will be presented with the DSN Chooser dialog, in which you may do select an existing User or File DSN, or create a new DSN of either type. Instructions on creation may be found earlier in this chapter.

Figure3.68.MacOSClass33.gif

When the 'SQL>' prompt comes up, you can enter any SQL statement, including UPDATE, INSERT, DELETE, or SELECT, followed by <return>.

Figure3.69.MacOSClass34.gif

Results are returned in plain text, to your query window.

Figure3.70.MacOSClass35.gif

Type 'exit<return>' to close your DSN connection. The prompt 'Again (y/n) ?' is asking whether you wish to connect to another DSN. Respond y(es) or n(o) and hit <return>. Yes brings you back to the 'Enter ODBC string' prompt; no returns 'Have a nice day.'

When you QUIT the application, you will be prompted to save the output text. Default is "Don't save".

Figure3.71.MacOSClass38.gif