Notes
This function sets a session and returns true if successful. Sessions are used to preserve state on the server. The session is stored in a text file in a specified folder.
The session lifetime and session file path can be configured using:
- a local pwu_unix or pwu_win config file in the program directory using the session_life_time variable
- a global pwu_unix or pwu_win config file using the session_life_time variable
- manually calling the SetWebConfigVar function and setting the session time before making any calls to webwrite or other output functions.
An example of when to use sessions would be in a forum. In the PasForum/PSP4UM sources (1.3.x/1.5.x) the login of a user is saved for a period of time. This way the user does not have to log in to the forum each hour they come back to visit.
Session Time Tips
The default session time usually is 25 minutes as setup in your configuration file. If you are not using a configuration file and you have disabled the CONFIG_ON define switch in versions 1.6.1 and above, then the default session time is 25 minutes also. To change the default session time, either modify the config file or make a call to SetWebConfigVar before calling webwrite an similar output functions.
Session Path Tips
The default session path is usually session/pwuess.sds which is a local session directory in your cgi program's directory. If you do not create a session subdirectory with your cgi program and you use sessions, then you may have trouble debugging sessions or deleting old session files.. as the sessions may be stored in a temporary directory on your server if a temporary directory can be found.
You can change the session path in the config file or by calling SetWebConfigVar.
Example 1
begin
// initially setting or preserving a state between http requests
SetSess('customer', 'John');
SetSess('login', 'John235');
// accessing the preserved state of the application
webwrite('Session name: ' + GetSess(customer));
webwrite('<p>');
webwrite('Session value: ' + GetSess(login));
end.
Example 2
This particular SetWebConfig call only works in 1.6.1 or later and not in 1.6.0.2 since in 1.6.1 this ability to change the session through code was added. Previously in 1.6.0.2 and earlier versions, one could make calls to SetWebConfigVar to change other config variables, but not the session related ones.
begin
// set session life time in minutes (could use config file instead)
SetWebConfigVar('session_life_time', '2500');
SetSess('Customer', 'John');
SetSess('Login', 'John235');
end.
Storing Sessions To SQL
Sessions were chosen to be stored in a text file by default, but one could write their own custom SetSess function and have the sessions stored in an SQL database or other storage medium. Because there are so many databases, we have not chosen to store sessions in any specific database yet - but there are plans to add database session storage in the future for MySQL/Firebird/Postreg/etc using some sort of flexible multi-database plugin system.
To write your own SetSess function, peek into the sources of the SetSess/GetSess function in pwumain.pas to see how it works.