counter

Manipulates a persistent counter, by default incrementing it and returning the new value.

Summary

[counter file]

Parameter	Description	Default
file	Filename to use (not required if using SQL-based counters).	None
name	Alias for file.	None
decrement	Count down instead of up.	No
start	Start the count using this value.	1
value	Shows the value of the counter without incrementing or decrementing it.	No
sql	Uses a SQL-based counter.	None
date	Uses a date-based counter.	None
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

Examples

Perl example

$Tag->counter({
file => 'foo',
sql => 'table:seq',
start => 1,
});

or similarly with positional parameters:

$Tag->counter($filename, $attribute_hash_reference);

Description

Manipulates a persistent counter, by default incrementing it and returning the new value.

The counter value is stored in the specified file. If the file name begins with a "/" then it is an absolute path. Otherwise, it is relative to website's home directory, as specified using the Catalog global configuration directive. The default file is etc/counter. If the file does not exist, it is created and initialised to the value of the start parameter.

If the optional sql attribute is used, a SQL sequence will be used. Currently MySQL and Postgres are supported. The sequence must already exist. If no bypass parameter is sent, the table in the sequence callout (explained below) will be used and must be an Interchange table (i.e. set up with Database setting). If bypass is set then the DSN for the sequence will be passed in the dsn parameter.

If the optional date parameter is used, a date-based counter will be made. Date-based counters take the form of the date in YYYYMMDD, followed by the start value, by default 0001. When the date changes, the counter will flip over to the next day and the beginning start value.

Warning

This tag may not work when called from within embedded Perl, because of

Safe restrictions.

SQL Counter Examples

To set up a PostgreSQL counter, simply create a named sequence in the database:

CREATE SEQUENCE "foo" start 1 increment 1 maxvalue 2147483647 minvalue 1 cache 1

You will want to make sure you have an Interchange table that uses that database ("sometable" in the example, below).

Then access it with:

[counter sql="sometable:foo"]

You can create as many sequences as you like.

To set up a MySQL counter, add a table to your MySQL database into catalog.cfg or other place like dbconf/mysql:

Database sequence_name sequence_name.txt dbi:mysql:test_foundation
Database sequence_name column_def "id=int NOT NULL AUTO_INCREMENT PRIMARY KEY"

Make sure you set up the sequence.txt file if you want Interchange to create the table for you. Otherwise you can create the table yourself from a MySQL client:

mysql> CREATE TABLE sequence_name(id INTEGER NOT NULL AUTO_INCREMENT PRIMARY KEY);

Then access it with:

[counter sql="sequence_name:sequence_name"]

Alternatively, you can create the table without Interchange definition, as long as it is in the same database as an Interchange table:

mysql> create table sequence_name(id int NOT NULL AUTO_INCREMENT PRIMARY KEY);

Then access it by calling the Interchange-defined table name followed by the table that has the AUTO_INCREMENT key:

[counter sql="products:sequence_name"]

To set up an Oracle counter, create a sequence:

SQL> CREATE SEQUENCE foo START WITH 10000 INCREMENT BY 1 MAXVALUE 2147483647 MINVALUE 1 CACHE 2;

Then access via a table already connected to Oracle, use the following:

[counter sql="sometable:foo"]

Parameters

file

An actual text file that will be used to store the current count.

decrement

Causes the counter to count down instead of up. This option is not applicable to SQL counters.

start

Causes a new counter to be created and to start from 50 (for example) if it did not exist before. This option is not applicable to SQL counters.

value

Shows the value of the counter without incrementing or decrementing it. This option is not applicable to SQL counters.

sql

The table and sequence name of the SQL counter.

If the type of database is Postgres, the table is used to derive the database and the sequence will be a named sequence independent of the table; the sequence is incremented and accessed by "SELECT nextval('sequence_name')".

If the type of database is MySQL, an AUTO_INCREMENT key column is assumed and an insert of 0 followed by "select last_insert_id()" will increment then access the counter.

date

This parameter can have one of two values, as follows:

"local" specifies that the counter should be date-based, using the server's local timezone.
"gmt" specifies that the counter should be date-based, using GMT (UTC).

Either way, the counter will be formatted as "%Y%m%d" (see the list of time format tokens), followed by a four-digit number. By default, the number starts counting from "0001", but can be overridden with the use of the start parameter, as usual.