This example file illustrates using ODBscript for a simple MS-Access database
named "Products", which has only one table, also named "Products."  This
example is set up assuming a Web site directory named /wwwidget with two
subdirectories, /wwwidget/odb and /wwwidget/db, but you can change these.

To install this example on your Web site, note that it has one standard HTML
file, named index.htm.  If you do not wish to set up /wwwidget as a separate
site directory, you can install the index.htm file anywhere on your site, and
you can rename it if you like.  The ODBscript files are assumed to be on a
subdirectory named odb, but you can also change that if you like, provided
that you also change the links in the index.htm file to match your site
installation (see below).  But be sure to install all of the files with names
ending with ".odb" AND the file named "wwwtitle.incl" on the SAME directory.

(You can install .odb files on the same directory as your HTML files, but a
better technique is to put them on a separate directory and then make that
directory unreadable from the Web.  The CGI program will still be able to read
the scripts because it opens them through the local file system, but if you
don't allow read access through the Web server, then outside users won't be
able to download the scripts with a direct URL.  Alternatively, you may wish
to use "script mapping," as explained in the Users Guide, which allows URLs to
directly reference script files without having to specify in the URL the CGI
script processor that handles them:  That is, the URL can point directly to a
script file and the server will use the file name extension, e.g. ".odb", to
run the mapped script processor as a CGI.  This is really the best option, if
you have access to the server configuration to define this script mapping, but
this example will assume that you are using standard CGI.)

The database is an MS-Access file named products.mdb on the subdirectory named
db.  IMPORTANT: To be able to modify the database, the products.mdb file needs
to be on a directory that allows both read and write access for all "local"
Windows users.  This is a Windows file system permission that must be set, not
a Web server permission.  (Servers have similar permission specifications for
Web site directories, but those only control what can be done through the Web
server itself.  In this case, the odb.exe CGI is running as a Windows process
under an "anonymous" Windows user ID, and it is accessing files through the
local file system rather than through the Web server, so the CGI anonymous
user ID must be able to read and update the files.  Permissions on Windows
files can be set using the Properties panel in Windows Explorer; you can give
"All" users "Change" control.  If you are using a commercial hosting service,
your site may have a predefined database directory, or the site management
interface may provide a way of changing the permissions for a directory.  If
you have difficulty with the database being "non-updateable", contact your
support group for assistance.)  You can change where you install the database
file on your site, provided that you specify your database "connection string"
or define an ODBC DSN accordingly, as explained below, and in the User Guide.

You will need to install the odb.exe file on your server's CGI directory.  The
name of this directory will depend on your Web server, but common names for
this directory are /cgi-bin (as assumed in the example) or possibly /scripts,
but this can actually be any directory on your Web site that has "execute"
permissions specified in the Web server.  (If you wish, you can also use a
different name for the executable file, provided that you always use that
name in all of your URLs.)

The important thing is that the index.htm file has links to the CGI, and those
links also tell odb.exe where to find the script files.  Here's an example:

   <A HREF="/cgi-bin/odb.exe/wwwidget/odb/table1.odb">

So, if your CGI directory is not /cgi-bin, then you will need to change that
directory reference in all of the links in the index.htm file.  And if you do
not install the ODBscript files on a subdirectory named odb under a site
directory named wwwidget, then you will need to change the "extra path info"
following odb.exe.  This "extra path info" needs to point to the .odb files as
if they were the target of the URL, although odb.exe is the actual target:
That is, the server will run odb.exe, and odb.exe will open the script files
using the server's directory and virtual directory mapping.  So, that part of
the URL following odb.exe is similar to a URL that would be used to access a
file on your scripts directory through the Web server.

You may also need to modify the wwwtitle.incl file on the odb subdirectory,
which is an "include" file used by all of the .odb scripts.  (You will only 
need to modify this file if you do not set up your database DSN as the example
file expects it to be.)  The top section of wwwtitle.incl outputs a standard
"World Wide Widget" banner at the top of each page.  Then, it sets a database
connection string in a  variable named "db".  (The $db$ variable is also used
in some scripts to get "in_database" for "no script mode".)  The connectio
string uses an ODBC Data Source Name (DSN), which you must create.  On Win95
and 98, this is done through the ODBC Manager in the Windows Control Panel.
On NT, XP, Win2000 and above, use the "Data Sources (ODBC)" link in the
Administrative Tools panel (which is available from the Control Panel).
NOTE: the DSN *must* be a *system* DSN (not a user DSN) to be accessible by
the CGI program.  Select the MS-Access driver for this database, give it a DSN
name of "myProducts", and then locate the products.mdb file that you have
installed.  (You can use a different DSN name if you also change it in the
wwwtitle.incl file.)  If you are using a commercial hosting service that
supports ODBC, there should be a management interface for defining DSNs; if
not, contact your hosting service support group for details.  If you create a
system DSN named "myProducts" as an MS-Access database, you do not need to
modify the wwwtitle.incl file.

On Windows 95, 98, and NT, you can also use a "DSN-less" connection, as
explained in the Users Guide.  (XP and above also support this feature, but in
the default configuration, CGIs cannot make use of this feature because it
requires permission to create registry keys, and the default CGI user ID does
not have this permission.  Since modifying permissions for the CGI user ID is
not recommended, you should use a DSN on these systems.)  Here is a example of
a DSN-less connection string that you might use:

<% SET db="DRIVER={Microsoft Access Driver (*.mdb)};DBQ=C:\webroot\wwwidget\db\products.mdb;
       FIL=MS Access;UID=Admin" %>

Note that the DBQ in that connection string needs to be the actual file system
path, not a Web URL path, and it depends on where you installed the 
products.mdb database file, so change the DBQ above as needed.

(This sample database does not have a password on the Admin user name.  For
your own databases, you may wish to define passwords for all user names, and
if so, you will need to add a ";PWD=password" specification to the connection
string, whether or not you are using a DSN.)

The DATABASE $db$ command in wwwtitle.incl then sets up the database 
connection for all the scripts that include this file.  Doing this in the
include file means that if the database connection changes, the DATABASE
command only needs to be changed in one place.

The scripts use a predefined variable named $script_name$ for generating form
"action" links to odb.exe.  This variable will be automatically set when the
program runs (e.g., it will be set to "/cgi-bin/odb.exe" if that's where you
ran the current script from), so you do not need to change these references,
regardless of where your CGI is installed, as long as the initial link to
odb.exe is correct.  To include the wwwtitle.incl file, the scripts use a
built-in function, $pathTranslated("wwwtitle.incl"), which will automatically
produce a file system path for the same directory as the current script, so 
if wwwtitle.incl is on that same directory, these references also do not need
to be changed.  (The $pathTranslated( ) function also allows referencing
other directories relative to the script directory; see the Users Guide.)
Using these techniques in your own scripts will make it easier to move your
application to a different site or directory structure: The example scripts
should run, regardless of your installation, if you create a DSN named
"myProducts" (or you specify a different working ODBC connection string in the
wwwtitle.incl file), and if you insure that the initial "hard coded" HREF
links in the index.htm file are correct.
