Minimal Catalog

Catalog Files

This section describes the minimum of files and directories that need to be established to create a properly functioning catalog named "tutorial". Start creating the files with superuser privileges; you'll be notified when we move to regular users space.

Link Program

First of all, you need a link program. Read the link program glossary entry for an introduction and compilation instructions.

It is perfectly possible to re-use the existing link program under the same server instance. So if you already have one compiled, you only need to find it (look into your cgi-bin directory) and copy it to a new catalog's name, making sure the permissions stay intact. Run

  • cd /usr/lib/cgi-bin/ic; cp -p vlink tutorial (on Debian GNU), or

  • cd /var/www/cgi-bin; cp -p standard tutorial (on RPM-based systems).

If everything is working correctly, typing ls -l /usr/lib/cgi-bin/ic/ or ls -l /var/www/cgi-bin should roughly describe your files like this:

-rwsr-xr-x    1 interchange  interchange      7708 Dec 16 22:47 standard
-rwsr-xr-x    1 interchange  interchange      7708 Dec 16 22:47 tlink
-rwsr-xr-x    1 interchange  interchange      7708 Dec 16 22:47 tutorial
-rwsr-xr-x    1 interchange  interchange      7708 Dec 16 22:47 vlink

The link program enables communication with the Interchange daemon. You might notice both vlink and tlink files present; vlink uses Unix sockets to talk to the Interchange daemon (what you want most of the time), while tlink uses Inet sockets[1] and won't be used in this tutorial.

Catalog Root Directory (CATROOT)

In the Interchange (base) catalogs directory, you need to create a new subdirectory for the tutorial catalog. This is where all of your catalog-specific files will go. The directory needs to be readable, writable, and executable by the Interchange user. This will be referred to as your catalog directory[2] or CATROOT.

If you don't know where your CATROOT directory is, use any directory with write permissions (e.g. ~/catalogs/ is a good choice).

Then type the following within CATROOT:

mkdir tutorial
chown interchange.interchange tutorial
chmod 775 tutorial

For the rest of this tutorial, all file locations will be given relative to the tutorial catalog directory. For example, pages/ord/basket.html would be /var/lib/interchange/catalogs/tutorial/pages/ord/basket.html on Debian GNU, /var/lib/interchange/tutorial/pages/ord/basket.html on RPM-based systems, or the equivalent (such as ~/catalogs/tutorial/pages/ord/basket.html). The only exception is interchange.cfg, which is implicitly meant to be edited in /etc/interchange/ (or in the Interchange software directory ICROOT, such as /usr/local/interchange/ or ~/interchange/).

In addition, at places which require full pathnames (or other "hard-coded" values, such as usernames), Debian defaults will be used to avoid duplication and preserve the natural text flow. RPM-based systems users, please translate Debian GNU paths and other names to your system equivalents.

Interchange-managed Catalog Subdirectories

Now switch from the superuser to the Interchange user (interchange by default), by typing su -s /bin/sh - interchange. It is important to complete the rest of the steps under the "interchange" account or you'll run into permission problems later. (By the way, also make sure your umask setting is correct by running umask 022).

Move to the catalog directory (/var/lib/interchange/catalogs/tutorial/, /var/lib/interchange/tutorial/, ~/catalogs/tutorial/ or the like).

There, you need to create few catalog subdirectories that Interchange will use as it sees fit. The session/ subdirectory of the catalog root will be used to save information on visitors' browsing sessions. The etc/ and tmp/ directories are needed too, your catalog wouldn't work without them. The directories go under your catalog directory. Type mkdir session etc tmp to create them all.

For the next part, prepare your text editor of preference.

Catalog Registration: interchange.cfg

Interchange configuration is controlled by a number of directives, which are specified in two main files. Global configuration directives go to the interchange.cfg file which is common for all catalogs running on servers started from the same Interchange installation directory (ICROOT). Catalog-specific configuration directives go to catalog.cfg in the catalog directory.

The first directive we need to add is the global Catalog directive, specifying details for the new catalog. Open file /etc/interchange/catalogs.cfg and add the following:

Catalog  tutorial  /var/lib/interchange/catalogs/tutorial  /cgi-bin/ic/tutorial

At the end of /etc/interchange/interchange.cfg, add:

DebugFile /var/log/interchange/debug.log
ErrorFile /var/log/interchange/error.log

As you can intuitively see, an example of a complete (although somewhat basic) configuration directive consists of the directive name (Catalog, DebugFile, ErrorFile, ...), followed by directive-specific parameters. Any number of spaces or tabs can appear between the directives and their options. The directives are case-insensitive, but it is recommended that you stick to your choice for readability. You can insert blank lines or comment lines (lines where the first non-blank character is '#') throughout the configuration files. The order in which the lines appear is important, but it won't matter in the simple catalog we're creating.

For more information on Interchange configuration files, see configuration glossary entry.

Catalog Configuration: catalog.cfg

There are few catalog.cfg directives that Interchange expects to see in order to complete the minimum configuration. Those directives are VendURL (your catalog's base URL), SecureURL (HTTPS base URL), MailOrderTo, Database and ProductFiles. If you do not have a suitable HTTPS location for your catalog (if you're not running https, for example), simply use the same value as for VendURL. In our catalog, we will use a minimal products table[3] with only the three necessary fields. The table will be TAB delimited text file, stored in products/products.txt. In general, you can specify unlimited number of databases of any type (for unlimited purposes), but at least one must be considered a Product Files database, reflecting Interchange's e-commerce roots.

So the basic /var/lib/interchange/catalogs/tutorial/catalog.cfg config file should look like this:

VendURL       http://myhost.mydomain.local/cgi-bin/ic/tutorial
SecureURL     http://myhost.mydomain.local/cgi-bin/ic/tutorial
MailOrderTo   myname@mydomain.local

ErrorFile     /var/log/interchange/tutorial-error.log

Database      products  products.txt  TAB
ProductFiles  products


Products Database

The products database we mentioned, kept in products/products.txt, will serve two purposes. It will provide Interchange with the layout of the products database table and it will also provide the data. When Interchange comes around to parse the products.txt file, it will expect the first line to contain the names of the fields for the database table (the sku, description and price fields are mandatory for a products database, but you can add arbitrary other fields as you see fit). The first field in the list is expected to be the primary key (unique identifier). In most cases you are going to use the SKU (Stock Keeping Unit) as the unique identifier for each product. The simple store that we are going to build will sell some kind of tests or exams. You can choose another sample product line, but it is recommended that you keep it simple. Create the file products/products.txt, separating fields with a single TAB:

sku	description	price
4595	Nice Bio Test	275.45
2623	Stack of Econ Quizzes	1.24
0198	Really Hard Physics Test	1589.34
1299	Ubiquitous diff eq final	37.00


You may notice that the columns don't line up in your text editor. This is the nature of tab-delimited files. Do not try to fix these.

If you need more entries for the sample products database, you can use the dbgen Perl script to automatically create random database files for testing. The output of the script is much more meaningful if you provide it a list of words to work on (instead of just random characters) so make sure you have the /usr/share/dict/words file (in Debian, it's provided by the wenglish package), and then run perl dbgen -c 10 -r /usr/share/dict/words > products/products.txt. See the script source for available options and the complete usage syntax.

It is important to know that Interchange does not use plain-text databases (such as our products database) as-is; the performance would be poor. So instead, the data is imported and stored in a variant of the DBM database (Berkeley DB or GDBM, depending on which variant is available on your system). That's why on most Linux systems, you will see the products/products.gdbm file created once you put the catalog on-line. It is also possible to specify a different backend, such as MySQL, PostgreSQL or Oracle database; in fact, most non-trivial setups choose some SQL backend.

Whenever you use a DBM-based backend and edit the text database file, Interchange will detect the change and re-import the source file into the DBM database on next access. All aspects of this auto-import (including its deactivation) are of course controlled by config file options (but are out of scope of this tutorial).

Now that we have the majority of base files ready, we just need to create the HTML page templates.

[1] Unix sockets are a way for programs on the same machine to communicate. It is not possible to connect to an Unix socket remotely (this is interprocess communication, mind you, and it doesn't mean you can't browse the website from a different machine). When you need remote connection, you then have to use Inet sockets.

[2] Please note the difference between Interchange catalogs directory which holds all of the catalogs, and the catalog directory which, always in a context, designates one of the subdirectories.

[3] Keep in mind that Interchange uses both terms "database" and "table" to identify the same thing - a table. This terminology is a historic leftover from the time when Interchange only used a single table.

DocBook! Interchange!