Using Session Variables

Use Session variables when you need the variables for a single site visit or set of requests. For example, you might use Session variables to store a user's selections in a shopping cart application. (Use Client variables when you need the variable for future visits.)

Caution

You must use the cflock tag to prevent multiple requests from accessing any Session variable simultaneously. Failure to do so can result in data corruption.

Enabling Session variables

You enable Session variables in the cfapplication tag in your Application.cfm file. To enable Session variables:

Set sessionManagement="Yes"
Use the name attribute to specify the application's name.
Optionally, use the sessionTimeout attribute to set an application-specific session timeout value. Use the CreateTimeSpan function to specify the number of days, hours, minutes, and seconds for the timeout.

The following code is an example of turning on session management:

<!--- Name the application, and turn on Session management 

with a 45-minute timeout --->

<cfapplication name="GetLeadApp" 

sessionmanagement="Yes"

sessiontimeout=#CreateTimeSpan(0,0,45,0)#>

What is a session?

A session refers to all the connections that a single client might make to a server in the course of viewing any pages associated with a given application. Sessions are specific to individual users. As a result, every user has a separate session and has access to a separate set of Session variables.

This logical view of a session begins with the first connection by a client and ends (after a specified timeout period) after that client's last connection. However, because of the stateless nature of the Web, it is not always possible to define a precise point at which a session ends. In the real world, a session ends when the user finishes using an application. In most cases, however, a Web application has no way of knowing if a user is finished or just lingering over a page.

You can impose some structure on Session variable duration by specifying a timeout period. If the user does not access a page of the application within this timeout period, ColdFusion interprets this as the end of the session and clears any variables associated with that session.

The default timeout for Session variables is set to 20 minutes. You can change the timeout on the Memory Variables page of the ColdFusion Administrator Server tab. For more information, see Advanced ColdFusion Administration.

You can also set the timeout period for Session variables inside a specific application (thereby overruling the Administrator default setting) by using the cfapplication tag sessionTimeout attribute.

Storing session data in Session variables

Session variables are designed to store session-level data. They are a convenient place to store information that all pages of your application might need during a user session. Using Session variables, an application can initialize itself with user-specific data the first time a user accesses one of the application's pages. This information can remain available while that user continues to use that application. For example, you can retrieve information about a specific user's preferences from a database once, the first time a user accesses any page of an application. This information remains available throughout that user's session, thereby avoiding the overhead of retrieving the preferences again and again.

Like Client variables, Session variables require a client name (client ID) and are always scoped within that client ID. Session variables also work within the scope of an application name if one is supplied, in which case their scope is the combination of the client ID and the application name.

Standard Session variables

The Session Client scope has four built-in, read-only variables that your application can use:

Variable

Description

Session.CFID
The client ID, normally stored on the client system as a cookie.

Session.CFToken
The client security token, normally stored on the client system as a cookie.

Session.URLToken
A combination of the CFID and CFToken in the form CFID=IDNum&CFTOKEN=tokenNum. Use this variable if the client does not support cookies and you must pass the CFID and CFToken variables from page to page.

Session.SessionID
A unique identifier for the session. You use this variable in cflock tags to identify the scope of the lock.

Variable	Description
Session.CFID	The client ID, normally stored on the client system as a cookie.
Session.CFToken	The client security token, normally stored on the client system as a cookie.
Session.URLToken	A combination of the CFID and CFToken in the form `CFID=`IDNum`&CFTOKEN=`tokenNum. Use this variable if the client does not support cookies and you must pass the `CFID` and `CFToken` variables from page to page.
Session.SessionID	A unique identifier for the session. You use this variable in `cflock` tags to identify the scope of the lock.

If you are also using Client variables, the Session.CFID, Session.CFToken, and Session.URL token are identical to the corresponding Client variables.

Getting a list of Session variables

The variable Session scope is registered as a ColdFusion structure. This lets you use the ColdFusion Structure functions to get a list of Session variables. For example, you can use cfloop with the StructFind function to output a list of Session variables defined for a specific application.

To find a list of Client variables, you use the GetClientVariablesList function.

For more information on these functions, see the CFML Reference.

Developing ColdFusion Applications
Using the Application Framework