4.16. counter

4.16.1. Summary

Parameters: file start date sql

Positional parameters: file

Invalidates cache: YES

Called Routine:

ASP-like Perl call:

    $Tag->counter(
        {
         file => VALUE,
         sql => VALUE,
         start => VALUE,
         date => 'local' || 'gmt',
        }
    )

 OR

    $Tag->counter($file, $ATTRHASH);

Attribute aliases

            name ==> file
    [counter file]
Parameters Description Default
file   DEFAULT_VALUE
name Alias for file DEFAULT_VALUE
sql Asserts a SQL-based counter DEFAULT_VALUE
date Asserts a date-based counter DEFAULT_VALUE
Attributes Default
interpolate (reparse) No
Other_Characteristics  
Invalidates cache YES
Container tag No
Has Subtags No
Nests Yes

Tag expansion example:

    [counter file]
---
    TODO: (tag result)

ASP-like Perl call:

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

or similarly with positional parameters,

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

4.16.2. 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 VendRoot. The default file is etc/counter. If the file does not exist, it is created and initialized 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 attribute is used, a date-based counter will be made. It takes 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 under Safe, i.e. in embedded Perl.

Additional parameters:

4.16.2.1. decrement=1

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

4.16.2.2. start=50

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.

4.16.2.3. value=1

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

4.16.2.4. sql="table:sequence"

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.

4.16.2.5. date="local"

Specifies the counter will be date-based with local time.

4.16.2.6. date="gmt"

Specifies the counter will be date-based with GMT.

4.16.2.7. file

4.16.3. SQL Counter Examples

To set up a Postgres 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 below example).

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 in 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 int 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, in below sometable:

    [counter sql="sometable:foo"]
  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 int 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"]