For more information... RTFM!

You are not logged in

Powered by Interchange version 5.7.0


Executes the Perl code, contained in the tag's body text, and returns the result.


  • [perl tables] Perl code [/perl]

Parameter Description Default
tables Database tables to be made available to Perl code. None
table Alias for tables. None
failure Return the specified value if the Perl code fails to evaluate. None
no_return Suppress this tag's return value. No
subs Allow calls to GlobalSub routines, from within the enclosed Perl code, if AllowGlobal is also set. No
arg Same as subs (arg="subs") No
global Turn off Safe Link to an external page protection within the Perl code if AllowGlobal is also set. No
file Prepend the contents of the specified file, or FileDatabase entry, to the enclosed Perl code. None
number_errors Add line numbers to the source code displayed in the error.log file. No
short_errors Only logs errors - not the whole block of Perl code. No
trim_errors On error, only the specified number of lines before and after the broken line will be logged. No
hide Suppress any output text that would ordinarily be returned from this tag.  (This universal parameter was introduced with Interchange version 5.5.2.) No
interpolate Parse Interchange tags, included in the body text, before this container tag executes. No
reparse Process any Interchange tags found in the text output from this tag. Yes


Tag expansion example

    my $foo = 'Hello world'
    return $foo;
Hello world

Perl example

    tables => $tables,
    body => $perl_code,

or similarly with positional parameters:

$Tag->perl($tables, $attribute_hash_reference, $perl_code);


This tag allows you to embed Perl code within an Interchange page.  The code will run under the restrictions of Perl's Safe Link to an external page module by default.

Perl's "warnings" and "strict" pragmas are both turned off and, since it blocks Perl's "use" command, Safe Link to an external page will block you from turning them on.  This is not usually a problem, as you should probably use an alternative such as a UserTag if your code is complex enough to need "strict".

This tag expands to the value returned by the enclosed code and so printing to STDOUT or STDERR is useless.

    $name = $Values->{name};
    $browser = $Session->{browser};
    return "Hello, $name.  How do you like your $browser?"

Object references are available for most Interchange tags and functions, as well as direct references to Interchange session and configuration values.  See Interchange Perl objects for more information.

The [perl] tag will remember variable values inside the current page, unless scoped with "my", so you can do the equivalent of a memory store and recall for a loop.  Having said that, you must ensure that unscoped variables are initialised to a known value before they are used, as their default value cannot be relied upon.

Also see the [calc] and [calcn] tags.



This should be a whitespace-separated list of database tables you want to make available within your Perl code.

If you would like to use database values in your Perl code then the tag must pre-open the table(s) you will be using.  Here is an example using the products table:

[perl tables="products"]
    my $cost = $Tag->data({
        table => 'products',
        column => 'our_cost',
        key => $Values->{code},
    $min_price = $cost * ($min_margin + 1);

    return ($min_price > $sale_price) ? $min_price : $sale_price;

If you do not pre-open your tables then your code will fail, with a runtime Safe Link to an external page error, when it tries to use the [data] tag to look up "our_cost" in the products table.

Even if you properly specify the tables to pre-open, some database operations will still be restricted because Safe Link to an external page mode prohibits creation of new objects.  For SQL, most operations can be performed if the Safe::Hole Link to an external page module is installed.  Otherwise, you may have to set the global=1 attribute to use data from SQL tables.

Interchange database tables can always be accessed as long as they are pre-opened by using an item first.

Safe Link to an external page objects (including database handles) may persist within a page, and the [perl] tag does not necessarily destroy objects created earlier in the page.  As a result, your code may work even though you did not specify the "tables" properly, only to break later when you change something elsewhere on the page.

For example, this will work because the first call to [accessories] "opens" the (default) products table:

[accessories code="os28044" attribute="size"]

    return $Tag->accessories({
        attribute => 'size',
        code => 'os28085',

If you remove the first [accessories] tag, then the $Tag->accessories() call will fail with a Safe Link to an external page error, unless you also specified tables=products in your call to the [perl] tag.

The moral of this story is to ensure that you pass all necessary tables in the [perl] tag.


If your code contains a compile or runtime error, and fails to evaluate (i.e. eval($code) would set $@), the [perl] tag will return the value set for the failure attribute.  The error will be logged as usual.

For example:

[perl failure="It Broke"]
    my $cost = $Tag->data('products', 'our_cost', $Values->{code});
    $min_price = $cost * ( 1 + $min_margin );
    return ($min_price > $sale_price) ? $min_price : $sale_price;

will return "It Broke" because the $Tag->data() call will fail under the Safe Link to an external page module.  See the tables parameter for the reason why.


If no_return is set true then the Perl code's return value will be suppressed.

You can retrieve the return value from the session hash via [data session mv_perl_result] until it gets overwritten by another [perl] tag's return value.

If no_return is true then the [perl] tag will still return any output explicitly written with the &HTML or $Document->write() functions.

If no_return is not set then the $Document->write() buffer will not be returned (unless you use $Document->hot(1) or $Document->send(), in which case the contents of the write buffer will probably appear before anything else on the page).  See the Interchange Perl objects page for more information.

Here is an example:

[perl tables="products" no_return=1]
    my $cost = $Tag->data('products', 'our_cost', $Values->{code});

    $min_price = $cost * ( 1 + $min_margin );
    &HTML( ($min_price > $sale_price) ? $min_price : $sale_price );
    return ($min_price > $sale_price) ? 'too low' : 'ok';

This will put the same price on the page as our earlier example, but $Session->{mv_perl_result} will be set to either "too low" or "ok".

Deprecation notice

Deprecation notice

The arg parameter was deprecated in Interchange 5.5.2.  Please do not make use of this parameter as it may be removed, without warning, at any time.  See the hide parameter, which was created in version 5.5.2


If you have set the AllowGlobal configuration directive then passing this parameter with a "1", "Yes" or "True" value will enable you to call GlobalSub routines from within the enclosed Perl code.

Security warning

Security warning

This can compromise security.


If arg="subs" then this is exactly the same as the subs parameter.


If you have set the AllowGlobal configuration directive then setting the global paremeter to "1", "Yes" or "True" will turn off Safe Link to an external page protection within the Perl code.

Security warning

Security warning

The enclosed Perl code will be able to do anything the user ID running Interchange can do.  This seriously compromises security, and you should know what you are doing before using it on a public website.  It is especially dangerous if a single Interchange server is shared by multiple companies or user IDs.

Full "use strict" checking is turned on by default when in global mode.  You can switch strict checking off by using "no strict" within your code.  Note that any strict errors will go to the Interchange error logs, and the [perl] tag itself will fail silently within the page.


This prepends the contents of the specified file, or FileDatabase entry, to the enclosed Perl code (if any), and then execute the Perl code as usual.

For example:

[perl file=""][/perl]

The above would execute and expand to its return value.

Absolute file names (file names starting with "/" or containing "../") may be prohibited by the NoAbsolute configuration directive.

If the file name is not absolute then Interchange will first look for a file in the current directory.  If it fails to find the named file in the current directory then it will look in the list set with the TemplateDir configuration directive(s).  If it still fails to find the file then it will look for an entry by that name in the FileDatabase table.


Add line numbers to the source code displayed in the error.log file.  This can be useful if some of the Perl is generated or included from elsewhere, included into the [perl] body and then executed.


This will will replace the "(eval ###)" in the error message with the specified label string.  This is useful for quickly tracking down bugs when you have more than one [perl] block in the page - especially if you are also using short_errors.


If set to a true value, syntax errors and the like in [perl] tags will log just the error, not the whole source code of the block in question.  This is handy when you have the code open in an editor anyway, and don't want the error itself to get scrolled away when running "tail -f error.log".


If set to a number, and the error produced includes a line number, only the specified number of lines before and after the broken line will be logged, instead of the whole block.

Categories:  Interchange Perl usage | Interchange tags
Last modified by: Peter Ajamian
Modification date: Sunday 31 May 2009 at 1:45 AM (EDT)
Home  |  Legal nonsense  |  Privacy policy  |  Donations  |  Contact us