Interchange Perl objects

$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.

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

You would use:

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:

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

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:

You would use:

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:

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

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  module is installed, or AllowGlobal is set for the website.

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:

Note If you want to access a table from withing a local UserTag then your tag code may need to call "$Tags->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

Array reference key for a COMPOSITE_KEY table

Alternate hash reference key for a COMPOSITE_KEY table

Alternate null-separated key for a COMPOSITE_KEY table

Database access methods

The available methods are as follows:

Get a specific row/column from the table

Set a specific row/column in the table

Atomic increment of an element of the table

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

Return some columns from a row

Set some columns in a row (slice)

Alternate method for setting a slice

Specifying INSERT or UPDATE

Either:

or:

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

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

Perform a SQL query, returning an array of hashes

See if a column's datatype is numeric

Quote a value for SQL query purposes

Check configuration of the database

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

Check whether a column is in the table

Check whether a key is in the table

Create a subroutine to return a single column from the table

Create a subroutine to set a single column in the database

Create a subroutine to set a slice of the database

Return a complete array of the database (minus the key)

Delete a row from the table

$DbSearch

This is a search object that will search a database table.  It is the same as Interchange's db searchtype.  Options are specified in a hash and passed to the object.  All multiple column options should be passed as array references.  Before using the $DbSearch object, it must be told which table to search.

To use the "foo" table, it must first have been shared with [perl tables=foo].

There are three search methods, as follows:

Method	Description
array	Returns a reference to an array of arrays (best).
hash	Returns a reference to an array of hashes (slower).
list	Returns a reference to an array of tab-delimited lines.

For example:

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::DbSearch" hashref instead.

$Document

This is an object which will allow you to write and manipulate the output of your embedded Perl.  For instance, you can emulate a non-parsed-header program with the following:

Note the write of 4096 spaces.  Because Interchange's link program is parsed by default and your web server (and the link program) have buffers, you need to fill up the buffer to cause a write.  You can do it without the extra padding if you set the link up as a non-parsed-header program.  See your web server documentation on how to do that.

There are several methods associated with the $Document object, as follows:

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::Document" hashref instead.

header

Add a line to the HTTP header:

This can be used to change the page content type, cache options or other attributes.  The code below changes the content type (MIME type) to text/plain:

There is an optional hash that can be sent, with the only valid value being "replace" The code below scrubs all previous header lines:

Once output has been sent with $Document->send(), the $Document->header() method no longer has any effect.

hot

If the parameter is true (in the Perl sense), then all $Document->write() operations will be immediately sent, until a $Document->hot(0) is called.

For instance, the following causes writes to be sent to the user's browser immediately:

Stop immediate writes:

insert

Insert a value to front of write buffer array:

The following example will output "123":

while this example will output "231"

ref

Get a reference to output buffer:

replace

Replace contents of the write buffer with the contents of a supplied array:

review

Return the contents of the write buffer as an array:

send

Flush the write buffer array to the output, done automatically upon the end of the [perl] call.  This also clears the buffer and invalidates $Document->header().

write

Append a value to the write buffer array

The above will write $foo to the page in a buffered fashion.  The buffer is an array containing the results of all previous $Document->write() operations.  If $Document->hot(1) has been set then the output will immediately be sent to the user's browser.

Also see the HTML subroutine.

$Items

This is a reference to the current shopping cart array.  This will normally be the same as $Carts->{main}, unless the Interchange [cart] tag has been used to make a cart other than "main" the default.

See the $Carts section for an example of the array structure.

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::Items" arrayref instead.

$Scratch

A reference to the scratchpad values ala [scratch foo].

is equivalent to:

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

$Session

A reference to the session hash maintained for the current user.

The following two blocks of code are equivalent:

Session values can also be set.  For instance, if the value of [data session source] needs to be changed, for some reason, then you could use the following:

The following keys are available in the $Session hash reference.

Name	Description
accesses	Accesses within the last 30 seconds
arg	The argument passed in an [area] tag.
browser	The identification value sent by the user agent.
carts	A reference to a Perl hash containing shopping carts.  See $Carts for more information.
host	Interchange's note of the visitor's hostname (possibly modified by DomainTail).  If the hostname could not be looked up (HostnameLookups switched off or DNS error etc.) then the visitor's IP address will be stored here instead.
id	The current session ID.
last_error	The last error or status message from the error logging routine.
last_search	The last non-SQL Interchange search specification invoked.
last_url	The current Interchange path_info.
logged_in	Will be true if the user is logged in.
ohost	Interchange's note of the visitor's IP address when using	a non-SSL link (also see shost)
pageCount	Number of unique URIs generated by Interchange for this session.
payment_result	A hash of result messages from payment module transaction attempts.  See examples in the Interchange payment modules documentation.
prev_url	The previous path_info.
referer	HTTP_REFERER string.
ship_message	The last error messages from shipping.
shost	Interchange's note of the visitor's IP address when using	a SSL link (also see ohost)
spider	Will be true if the user is a search engine spider.
source	Source of original entry to Interchange.
teleport	Date and time (in "%Y%m%d%H%M%S" format) for use with the PageTables directive.
time	Time (seconds since 01 January 1970) of the last access.
user	The REMOTE_USER string.
username	Logged-in username.  See the Interchange user database page.

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::Session" hashref instead.

Warning Make sure you know what you're doing before you start monkeying about with the values stored in the $Session hashref.

%Sql

A hash of SQL tables that you shared with [perl tables="foo"].  It returns the DBI database handle, so operations like the following can be performed:

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

$Sub

The $Sub allows access to any Sub or GlobalSub subroutines you may have defined.

Note Safe  mode will be in operation during the subroutine call, so unsafe operations will be trapped as usual.

Usage example:

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::Subs" object instead.

$Tag

Using the $Tag object, most standard Interchange tags, and all user-defined tags can be accessed.

Note If the tag will access a database that has not been previously opened, the table name must be passed in the [perl] call.

Usage example:

is the same as:

If the tag has a dash (-) in its name then use an underscore instead: