3.2.Generic Client For Macintosh OS 8.6+

There are several ODBC Driver Managers distributed for the Classic Macintosh OS. OpenLink Software distributes iODBC, an Open Source, Cross-Platform, LGPL and BSDI licensed, ODBC 3.5-compliant Driver Manager maintained by OpenLink. Additional information regarding iODBC can be obtained from http://www.iodbc.org.

The iODBC Driver Manager requires Mac OS 9 or later; the OpenLink Generic Client Driver for ODBC may be used on System 7 through Mac OS 9, with any ODBC 2.x- or 3.x-compliant Driver Manager.

The OpenLink ODBC Client Components for Macintosh Classic comprise the following:

Table3.2.

Component Purpose
iODBC Driver Manager A shared library that links ODBC compliant applications to ODBC Drivers
Generic ODBC Driver A shared library that provides database connectivity and data access services to ODBC compliant applications
Sample ODBC Applications Simple programs that can be used to verify your ODBC installation and working environment

3.2.1.Installation

After downloading the OpenLink Data Access Driver Suite client components from our Website, uncompress the contents of the Stuffit format archive into a temporary location on your client machine. The Desktop is often best.

Figure3.32.MacOSClass01.jpg

MacOSClass01.jpg

Double click the 'OpenLink MacOS ODBC Client 5.0' icon to launch the installer. Click OK at the splash screen.

Figure3.33.MacOSClass02.gif

MacOSClass02.gif

Check the contents of the 'Read Me'. Then click Continue.

Figure3.34.MacOSClass03.gif

MacOSClass03.gif

Read and Agree to the Software License.

Figure3.35.MacOSClass04.gif

MacOSClass04.gif

There are two types of installation. The Easy Install option is best for most users, and will install the iODBC Driver Manager, if no other Driver Manager is present.

Figure3.36.MacOSClass05.gif

MacOSClass05.gif

If you need to replace an older Driver Manager (Merant, Visigenic, Intersolv), select the Custom Install, and check off all appropriate components. The iODBC Driver Manager will only run on PowerPC machines, under Mac OS 9 or later. If you're installing on an older Mac, running Mac OS 8.1 or earlier, you can use Custom Install to get the 68K components you'll need.

Figure3.37.MacOSClass06.gif

MacOSClass06.gif

Press the Install button to start the installation. You will be prompted to select a location for Sample Applications and other files.

Figure3.38.MacOSClass07.gif

MacOSClass07.gif

You Macintosh will need to be restarted after installation has completed. You will be given the opportunity to save any open documents.

Figure3.39.MacOSClass08.gif

MacOSClass08.gif

Installation will proceed.

Figure3.40.MacOSClass09.gif

MacOSClass09.gif

After installation you may safely delete the files in the temporary location ('OpenLink MacOS ODBC Client 4.1', 'OplMacClient-4.1.sit', mmoczzzz.hqx).

Figure3.41.MacOSClass10.jpg

MacOSClass10.jpg

3.2.2.Data Source Configuration

Once you have completed the installation process, proceed to create a new ODBC DSN using the OpenLink ODBC Administrator (formerly ODBC Setup PPC) control panel.

The OpenLink ODBC Administrator for Mac Classic currently supports the creation of User and File DSNs.

If in Multiple Users mode, a User DSN is only available to the user who creates the data source. Its parameters are stored in that user's settings file: Preferences/ODBC Preferences PPC.

If in Single User mode, a User DSN is only available to the whole system so that any user, including the system itself, will be able to use that data source. Its parameters are stored in the System settings file: System Folder/Preferences/ODBC Preferences PPC.

A File DSN is a special 'mobile' data source that stores the data source information associated with the Driver in a file, which may then be copied and shared among different users and ODBC application host machines.

File DSNs are usually created when the same DSN needs to be used by many different users, from many different workstations. File DSNs may be passed from Macintosh to Macintosh, or User to User in Multiple Users mode, and will be usable by anyone with the same ODBC Drivers installed. By default, File DSNs are found in: System Folder/Preferences/ODBC File Data Sources.

Most often, a User DSN will be appropriate for use on a Macintosh running the Classic Mac OS.

User Data Source Names

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

Figure3.42.MacOSClass11.gif

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

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

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] 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

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

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

MacOSClass16.gif

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

Figure3.48.MacOSClass17.gif

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

MacOSClass18.gif

Configuring File Data Sources

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

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

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

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] Note:

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

Figure3.53.MacOSClass16.gif

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

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

MacOSClass22.gif

3.2.3.Tracing Data Sources

From the Tracing Tab of the iODBC Data Source Administrator, the level of Tracing can be configured.

Figure3.56.MacTrace.gif

MacTrace.gif

When to trace. Use this option to turn tracing off or on. For a One-time only trace, the trace is made for the duration of the next connection. Click the Apply button to make your selection active. This option corresponds to the Trace and TraceAutoStop parameters in the preference files.

Custom trace library. Use the Select Library button to browse the machine for a library file that contains the code to intercept the trace output. This field should generally be left blank. When setting this parameter, you may use the Browse button to locate the library, or specify it manually. If specified manually, note that the location must be specified as it would be in a Terminal session. You may use ~/ as a shortcut to your user Home directory. This option corresponds to the TraceDLL parameter in the preference files.

Log file path. Specify the complete location of the file to which you wish to write the trace. You may use the Browse button to locate or create the file, or specify it manually. If specified manually, note that the location must be specified as it would be in a Terminal session. You may use ~/ as a shortcut to your user Home directory. This option corresponds to the TraceFile parameter in the preference files.

Trace Parameters in ODBC.INI

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.

3.2.4.Testing Data Sources

ODBC SDK C++ Sample

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

Figure3.57.MacOSClass23.gif

MacOSClass23.gif

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

Figure3.58.MacOSClass24.gif

MacOSClass24.gif

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

Figure3.59.MacOSClass25.gif

MacOSClass25.gif

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

Figure3.60.MacOSClass15.gif

MacOSClass15.gif

From the SQL menu select Execute SQL...

Figure3.61.MacOSClass26.gif

MacOSClass26.gif

Enter an SQL query in the dialog.

Figure3.62.MacOSClass27.gif

MacOSClass27.gif

With success, the results will be shown.

Figure3.63.MacOSClass28.gif

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

MacOSClass29.gif

iODBC Test PPC

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

Figure3.65.MacOSClass30.gif

MacOSClass30.gif

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

Figure3.66.MacOSClass31.gif

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

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

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

MacOSClass34.gif

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

Figure3.70.MacOSClass35.gif

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

MacOSClass38.gif