For more information... RTFM!
NAVIGATION
PAGES THAT LINK HERE
ACCOUNT LOGIN

You are not logged in

Powered by Interchange version 5.7.0

Interchange Perl objects

Table of contents
1. $Carts
2. $CGI
3. $CGI_array
4. $Config
5. %Db
5.1. Keys
5.1.1. Key for a normal table with one primary key
5.1.2. Array reference key for a COMPOSITE_KEY table
5.1.3. Alternate hash reference key for a COMPOSITE_KEY table
5.1.4. Alternate null-separated key for a COMPOSITE_KEY table
5.2. Database access methods
5.2.1. Get a specific row/column from the table
5.2.2. Set a specific row/column in the table
5.2.3. Atomic increment of an element of the table
5.2.4. Return a complete hash of the database row (minus the key)
5.2.5. Return some columns from a row
5.2.6. Set some columns in a row (slice)
5.2.7. Alternate method for setting a slice
5.2.8. Specifying INSERT or UPDATE
5.2.9. Perform a SQL query, returning an array of arrays
5.2.10. Perform a SQL query, returning an array of hashes
5.2.11. See if a column's datatype is numeric
5.2.12. Quote a value for SQL query purposes
5.2.13. Check configuration of the database
5.2.14. Find the names of the columns (not including the key)
5.2.15. Check whether a column is in the table
5.2.16. Check whether a key is in the table
5.2.17. Create a subroutine to return a single column from the table
5.2.18. Create a subroutine to set a single column in the database
5.2.19. Create a subroutine to set a slice of the database
5.2.20. Return a complete array of the database (minus the key)
5.2.21. Delete a row from the table
6. $DbSearch
7. $Document
7.1. header
7.2. hot
7.3. insert
7.4. ref
7.5. replace
7.6. review
7.7. send
7.8. write
8. $Items
9. $Scratch
10. $Session
11. %Sql
12. $Sub
13. $Tag
14. $Tmp
15. $Values
16. $Variable
17. Subroutines
17.1. Debug
17.2. HTML
17.3. Log
17.4. errmsg
17.5. uneval
 

$Carts

This is a reference to the $Session->{carts} shopping cart hash.  The default cart is "main".  Shopping carts are stored as an array of hash references.  Here is an example of a session cart array, containing a main and a layaway cart.  $Items is an alias to the current cart, within the %$Carts hash.

{
    'main' => [
        {
            'code' => '00-0011',
            'mv_ib' => 'products',
            'quantity' => 1,
            'size' => undef,
            'color' => undef,
        },
        {
            'code' => '99-102',
            'mv_ib' => 'products',
            'quantity' => 2,
            'size' => 'L',
            'color' => 'BLUE',
        },
    ],
    'layaway' => [
        {
            'code' => '00-341',
            'mv_ib' => 'products',
            'quantity' => 1,
            'size' => undef,
            'color' => undef,
        },
    ],
}

In this cart array, "$Carts->{main}->[1]->{code}" is equal to "99-102".  This would be equivalent to the shorter "$Items->[1]->{code}", unless the [cart] tag has been used to make a cart other than "main" the default.

Global context

Global context

You cannot use this object in a global context, such as from within a global UserTag or a GlobalSub etc. Use the "$::Carts" hashref instead.

$CGI

This is a hash reference to %CGI::values, which contains the value of user variables submitted in the current page or form.

To get the value of a variable submitted as:

<input type="hidden" name="foo" value="bar">

You would use:

[perl]
    return "Value of foo is $CGI->{foo}";
[/perl]

Actually, you should not do that.  If someone sends you a value you should not output it willy-nilly, for security reasons.  Filter it first with the [filter] tag, which may be accessed via the $Tag object, as follows:

[perl]
    my $val = $Tag->filter('encode_entities',$CGI->{foo});
    return "Value of foo is $val";
[/perl]

Remember, multiple settings of the same variable are separated by an ASCII NUL character.  To get an array value, use $CGI_array.

Global context

Global context

You cannot use this object in a global context, such as from within a global UserTag or a GlobalSub etc. Use the "%CGI::values" hash (not hashref) instead.

$CGI_array

This is a hash reference to the %CGI::values_array, arrays containing the value (or values) of user variables as submitted in the current page or form.  To get the value of a variable submitted as:

<input type="hidden" name="foo" value="bar">
<input type="hidden" name="foo" value="baz">

You would use:

[perl]
    return "The values of foo are " . join(', ',@{$CGI_array->{'foo'}});
[/perl]

Global context

Global context

You cannot use this object in a global context, such as from within a global UserTag or a GlobalSub etc. Use the "%CGI::values_array" hash (not hashref) instead.

$Config

This points at the $Vend::Cfg hashref, and can be used to look up or set website configuration values.  For instance:

#
#    allow searches of the userdb table on this page only
#
$Config->{NoSearch} =~ s/\buserdb\b//;

Changes are not persistent;  They are reset upon the next page access.

Global context

Global context

You cannot use this object in a global context, such as from within a global UserTag or a GlobalSub etc. Use the "$Vend::Cfg" hashref instead.

%Db

A hash of database tables, shared with the [perl] tag's tables="foo" parameter.  Once a table is shared, it is open and can be accessed by any of its methods.  This will not work with SQL unless the Safe::Hole Link to an external page module is installed, or AllowGlobal is set for the website.

Note

Note

This object is not available when using the [calc], [calcn] and [PREFIX-calc] tags.

You can use the following to get a reference to a particular table:

my $db = $Db{tablename};
Note

Note

If you want to access a table from withing a local UserTag then your tag code may need to call "$Tag->perl({ table => "tablename" });" in order to initialize "$Db{tablename}".

Keys

The examples that follow make use of a "$key" which can be one of the following:

Key for a normal table with one primary key

$key = 'foo';

Array reference key for a COMPOSITE_KEY table

$composite_array_key = ['foo','bar','baz'];

Alternate hash reference key for a COMPOSITE_KEY table

$composite_hash_key = { key1 => 'foo', key2 => 'bar', key3 => 'baz'};

Alternate null-separated key for a COMPOSITE_KEY table

$composite_nullsep_key = join("\0", 'foo', 'bar', 'baz');

Database access methods

The available methods are as follows:

Get a specific row/column from the table

$value = $db->field($key, $column_name);

Set a specific row/column in the table

$db->set_field($key, $column_name, $value);

Atomic increment of an element of the table

$db->inc_field($key, $column_name, 1);

Return a complete hash of the database row (minus the key)

$hashref = $db->row_hash($key);

Return some columns from a row

my @columns = qw/sku price description/;
@values = $db->get_slice($key, \@columns);

Set some columns in a row (slice)

my $key = 'os28004';
my @columns = qw/price description/;
my @values = (5.95, "Ergo Roller");
$array_ref = $db->set_slice($key, \@columns, \@values);

Alternate method for setting a slice

my $key = 'os28004';
my %columns = ( price => 5.95, description => "Ergo Roller");
$array_ref = $db->set_slice($key, \%columns);

Specifying INSERT or UPDATE

Either:

my $key = 'os28004';
my %columns = ( price => 5.95, description => "Ergo Roller");
my %opt = ( dml => 'insert' );

my $array_ref = $db->set_slice([\%opt, $key], \%columns);

or:

my $key = 'os28004';
my %columns = ( price => 5.95, description => "Ergo Roller");
my %opt = ( dml => 'update' );

my $array_ref = $db->set_slice([\%opt, $key], \%columns);

The "dml" option may be set to either "insert", "update" or may be left unset.  If unset then the default will be to insert a new row or update an existing rows, as appropriate.

Availability

Availability

This facility was introduced in version 5.5.2, and is therefore not available for use with any earlier Interchange version.

Perform a SQL query, returning an array of arrays

This is the equivalent of DBI $sth->fetchall_arrayref.

$ary = $db->query($sql);

The following is the same, except that it also obtains hash reference of pointers to column positions and array reference containing list of columns:

my $sql = 'select * from products';
($ary, $index_hash, $name_ary) = $db->query($sql);
$columns_returned = join ",", @$name_ary;
$pointer_to_price = $index_hash->{price};

Perform a SQL query, returning an array of hashes

$ary = $db->query({ sql => $sql, hashref => 1 });

See if a column's datatype is numeric

$is_numeric = $db->numeric($column_name);

Quote a value for SQL query purposes

$quoted = $db->quote($value, $column_name);

Check configuration of the database

$delimiter = $db->config('DELIMITER');

Find the names of the columns (not including the key)

@columns = $db->columns();

#
#    insert the key column name
#
unshift @columns, $db->config('KEY');

Check whether a column is in the table

$is_a_column = defined $db