Catalog

SYNOPSIS

name catalog_directory link_program_path...

DESCRIPTION

The directive registers a catalog that will run on the corresponding Interchange installation.

The directive expects three or more arguments.

First expected is the name of the catalog. It will be referred to by the specified name in error, warning, and informational messages. It must contain only alphanumeric characters, hyphens, and underscores. It is highly recommended that it is also all lowercase.

Second argument specifies the filesystem base directory of the catalog. If the directory does not exist, the required catalog.cfg is not there, or Interchange detects any other problem, catalog configuration will be skipped and the catalog won't be activated.

Third argument is the so called SCRIPT_NAME of the link program. It is a webserver path by which the catalog can be accessed. It can be followed by different aliases, all allowing access to the same catalog. For example, this is useful when calling an SSL server or a members-only alias that requires a Basic HTTP authorization using the username/password pair. All subsequently generated links would be called using the aliased URL.

The script name must be unique among CGI program paths that run on the Interchange server, unless the FullUrl directive is specified. In this case, hostnames can be added to differentiate otherwise same paths; as usual, see the section called “EXAMPLES” for clarification.

It is also possible to define catalog-specific configuration directives from the global interchange.cfg file. Again, see the section called “EXAMPLES”.

DIRECTIVE TYPE AND DEFAULT VALUE

Global directive

EXAMPLES

Example: Registering a catalog

Catalog simple /home/catalogs/simple /cgi-bin/ic/simple

Example: Using FullUrl to differentiate same-named catalogs on different hosts

FullUrl yes

Catalog simple1 /home/catalogs/simple1 www.company1.com/cgi-bin/ic/simple
Catalog simple2 /home/catalogs/simple2 www.company2.com/cgi-bin/ic/simple

Make sure to read the FullUrl directive reference page before just including it in your configuration.

Example: Elaborate Catalog directive definition

Given the nature of the Catalog directive, a catalog can be registered somewhat verbosely with:

Catalog simple  directory /home/catalogs/simple
Catalog simple  script    /cgi-bin/ic/simple
Catalog simple  alias     /simple

Example: Defining catalog-specific directives in the global config file

Re-using the elaborate example from just above, it is also possible to define catalog-specific directives in the global interchange.cfg file. This is most useful to do with the ErrorFile and DisplayErrors directives:

Catalog simple  directive ErrorFile /var/log/interchange/simple-error.log

NOTES

Catalog is one of the basic Interchange configuration directives.

makecat, the catalog creation helper script, automatically inserts the Catalog line in the interchange.cfg file as part of the standard procedure.

If the catalog.cfg file, expected in the catalog base directory, is not found, or is unreadable by the Interchange server, somewhat misguiding error message will be reported. Instead of the appropriate permissions-problem message, the mandatory VendURL directive will be reported as undefined.

AVAILABILITY

Catalog is available in Interchange versions:

4.6.0-5.9.0 (git-head)

SOURCE

Interchange 5.9.0:

Source: lib/Vend/Config.pm
Line 515

['Catalog',       'catalog',        ''],

Source: lib/Vend/Config.pm
Line 4147 (context shows lines 4147-4248)

sub parse_catalog {
my ($var, $setting) = @_;
my $num = ! defined $Global::Catalog ? 0 : $Global::Catalog;
return $num unless (defined $setting && $setting); 

my($name,$base,$dir,$script, @rest);
($name,@rest) = Text::ParseWords::shellwords($setting);

my %remap = qw/
        base      base
        alias     alias
        aliases   alias
        directory dir
        dir       dir
        script    script
        directive directive
        fullurl   full_url
        full      full_url
        /;

my ($cat, $key, $value);
if ($Global::Catalog{$name}) {
  # already defined
  $cat   = $Global::Catalog{$name};
  $key   = shift @rest;
  $value = shift @rest;
}
elsif(
    $var =~ /subcatalog/i and
    @rest > 2
    and file_name_is_absolute($rest[1]) 
    )
{
  $cat = {
    name   => $name,
    base   => $rest[0],
    dir    => $rest[1],
    script => $rest[2],
  };
  splice(@rest, 0, 3);
  $cat->{alias} = [ @rest ]
    if @rest;
}
elsif( file_name_is_absolute($rest[0]) ) {
  $cat = {
    name   => $name,
    dir    => $rest[0],
    script => $rest[1],
  };
  splice(@rest, 0, 2);
  $cat->{alias} = [ @rest ]
    if @rest;
}
else {
  $key   = shift @rest;
  $value = shift @rest;
  $cat = { name   => $name };
}

$key = $remap{$key} if $key && defined $remap{$key};

if(! $key) {
  # Nada
}
elsif($key eq 'alias' or $key eq 'server') {
  $cat->{$key} = [] if ! $cat->{$key};
  push @{$cat->{$key}}, $value;
  push @{$cat->{$key}}, @rest if @rest;
}
elsif($key eq 'global') {
  $cat->{$key} = $Global::AllowGlobal->{$name} = is_yes($value);
}
elsif($key eq 'directive') {
  no strict 'refs';
  my $p = $value;
  my $v = join " ", @rest;
  $cat->{$key} = {} if ! $cat->{$key};
  my $ref = set_directive($p, $v, 1);

  if(ref $ref->[1] =~ /HASH/) {
    if(! $cat->{$key}{$ref->[0]} ) {
      $cat->{$key}{$ref->[0]} =  { %{"Global::$ref->[0]"} };
    }
    for (keys %{$ref->[1]}) {
      $cat->{$key}{$ref->[0]}{$_} = $ref->[1]->{$_};
    }
  }
  else {
    $cat->{$key}{$ref->[0]} = $ref->[1];
  }
}
else {
  $cat->{$key} = $value;
}

#::logDebug ("parsing catalog $name = " . uneval_it($cat));

$Global::Catalog{$name} = $cat;

# Define the main script name and array of aliases
return ++$num;
}

AUTHORS

Interchange Development Group

Name