Warning: Native session support has been removed with Aptilis 2.4 RC1. Please use apt.util.Session from the library instead.

1. Introduction
2. Restrictions
3. Troubleshooting and technical details

1. Introduction

Session persistence has to do with CGI applications, or in other words, web based applications.
One annoying thing about web applications, is that your aptilis program (or a program written in any other language) is called repeatedly after each form submission, but it's not the same program (or the same instance of that program) that keeps running from one form to another.
In other words, from one form to the next in -say a booking procedure, all data is lost. To retain it, you must pass it along in hidden fields.
Aptilis remedies that with the '_Session variable'. This variable (which can be an array) keeps its data across sessions.

2. Restrictions

In some cases, although it may appear ideal, it is better not to use the '_Session' variable.

• The '_Session' variable is cleared after an hour, but its time stamp is reset each time a script is run. So a session may last longer than an hour, provided the user doe not stay idle for more than an hour.
• The '_Session' variable relies on an IP number that uniquely identifies the person connecting to your server. In some rare cases, this number can not be retrieved and the '_Session' variable will not be saved.
• Some ISPs (Internet Service Providers) do not give their customers a fixed IP number. This can be a problem when a connection is lost and the customer has to re-dial. Also, several PCs sharing a connection behind a NAT system will share one IP number between them. So from your point of view, your script may confuse data between unrelated users!
• If the person connecting to your server has several browser windows opened, you can be confused as those different windows present you with the same IP number. They might be in different stages of your booking process, or even in a completly different application altogether.
• The persistence mechanism relies on having write access to a temporary directory, or the directory where the aptilis executable resides. Under NT, that will generally not be a problem, but with a Unix server, your scripts may not have write access by default to a temporary directory. This however may be arranged with your system administrator.

In conclusion, a professional, reliable application should rely on hidden fields passed along the different forms of your web application. You can download a example script which uses session ids and cookies from our script archive. However, the '_Session' variable allows you to develop prototypes much faster, or can even be considered seriously if you have control over the network where your application is used.
Control means that you can ascertain that people's IP numbers don't change, and that -should you need to- you can modify read/write permissions on the server you're using.
You usually have this kind of control when you program for an Intranet (a private network using Internet protocols and software) as opposed to the Internet.
Check the Session example.

3. Troubleshooting and technical details

A. Under Windows 9x/NT/2K/XP
When saving session data, aptilis will look for the following environment variables:
1. tmp
2. temp
3. the default directory where aptilis is, at launch time.

You can check the value of the environment variables through the aptilis global array '_ENV'. It's a key based array, so to get the value for the 'tmp' variable, you need to do:

sub main

        print("Content-type: text/plain\n\n")
        .
        .
        .

        print("tmp: ", _ENV["tmp"]$, "\n")

end main

B. Under Unix
The Unix version of aptilis can only use one directory:
/tmp/aptilis
This directory must be writable by the user the webserver runs as, or by everyone, but that's not recommended, as basically this allows scripts to write tons of data, leaving you with little control over what's happening.
Note that if the /tmp/aptilis/ directory does not exist, or the write permissions are wrong, the session persistance feature of aptilis is disabled with negligible effects on performance.

C. general information
Aptilis keeps its information tidy in a file called 'aptilis-cgi-sessions.dat' in the Session Directory. Several other files with names following the pattern 'sessXXXX.dat' where 'XXXX' is a hexadecimal serial number are also kept in the Session Directory.
If errors occur, they are kept in an error log file called 'aptilis-cgi-session-errors.txt' which you can check. However, if you do not have write permission to the Session Directory aptilis will not be able to log the errors!
Your troubleshooting should start with finding out where aptilis wants to save it's session data (tmp? temp? the default directory?), then check write permissions and finally analysing the error log.
Note that you can reset all session data by erasing the 'aptilis-cgi-sessions.dat' file.