Using Application and Session Variables  
 
 

In ColdFusion, you use variables to work around the Web's inherent statelessness. Session and application variables are persistent variable "scopes." You access these variables by prefacing the variable name with the scope name, for example: Session.MyVariable or Application.MyVariable. And because they are persistent, you can pass values between pages with a minimum of effort.

 
 
  Enabling application and session variables  
 

Session and application variables are similar in operation to client variables. Like client variables, they are enabled with the CFAPPLICATION tag. See the CFML Language Reference for more information on the CFAPPLICATION tag.

Unlike client variables, however, which are stored in either the system registry, a data source, or a cookie, application and session variables are always stored in the ColdFusion server's memory. This method offers obvious performance advantages. In addition, you can set time-out values for these variables either with CFAPPLICATION, or by specifying time-outs in the ColdFusion Administrator. You can also simply disable application and session variables entirely.

For information on setting time-outs for variables, see Administering ColdFusion Server.

 
 
  Session variables  
 
 

Use session variables when the variables are needed 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 car application. (Use client variables when the variable is needed for future visits.)

 
 
  How long do sessions last?  
 

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. This logical view of a session begins with the first connection by a client and ends (after a specified time-out period) after that client's last connection.

It's important to understand that 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.

It's also important to understand that a session is a logical construct. Because of the stateless nature of the Web, it's 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 and goes off to do something else. In most cases, however, a web application has no way of knowing if a user is finished or if he's just lingering over a page.

To impose some structure where there is none, session variables have a programmer-specified time-out period associated with them. If the user does not access a page of the application within this time-out period, ColdFusion interprets this as the end of the session and clears any variables associated with that session.

 
 
  Session variable time-outs  
 

Session variables have a specific lifetime, and it is this lifetime that defines a "session." For example, when you access a session variable within its specified lifetime, the variable returns a value because your request occurs during a single, time-limited session. On the other hand, if you do not access a session variable within its specified lifetime, the variable will time-out and will no longer be available to you.

The default time-out for session variables is set to 20 minutes. In the Variables page of the ColdFusion Administrator, you can change this time-out value. See the Administering ColdFusion Server book for more information.

You can also set the time-out period for session variables inside a specific application (thereby overruling the Administrator default setting) by using the SESSIONTIMEOUT attribute of the CFAPPLICATION tag.

 
 
  Using 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 could initialize itself with user-specific data the first time a user hit a page of that application. This information could then remain available while that user continues to use that application. For example, information about a specific user's preferences could be retrieved from a database once, the first time a user hits any page of an application. This information would remain available throughout that user's session, thereby avoiding the overhead of retrieving the preferences again and again.

Session variables work exactly as client variables do, in that they 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 will be the combination of the client ID and the application name.

Because session variables no longer require client variables to be turned on, the following read-only variables have been added to the session variable scope: CFID, CFTOKEN, and URLTOKEN.

To enable session variables, set SESSIONMANAGEMENT="Yes" in the CFAPPLICATION tag in your Application.cfm file.

 
 
  Example  
 
<!--- This example illustrates CFAPPLICATION --->
<!-- Begin Application -->
<!---
    MODULE:   application.cfm
    PURPOSE:  application.cfm file for our sample
    CREATED:  today's date
    AUTHOR:   the author
    COPYRIGHT: (c) 1998 the author for a company
    CHANGE HISTORY: 
--->
<!--- name application, set session variables to on --->
<CFAPPLICATION NAME='GetLeadApp' SESSIONMANAGEMENT='Yes'>
<!--- set data source for this application --->
<CFSET dsn = 'my_dsn'>
<!--- set global error handling for this application --->
<CFERROR TYPE='REQUEST' TEMPLATE='request_err.cfm'
    MAILTO='webmaster@mysite.com'>
<CFERROR TYPE='VALIDATION' TEMPLATE='val_err.cfm'
    MAILTO='webmaster@mysite.com'>

<!--- set some global variables for this application 
to be triggered on every page --->
<CFSET MainPage = 'default.cfm'>
<CFSET session.current_location = 'Davis, Porter, Alewife'>
<CFSET sm_location = 'dpa'>
<CFSET current_page = '#cgi.path_info#?#cgi.query_string#'>
<!-- End Application -->
 
 
  Application variables  
 
 

An application refers to all the related web pages that make up a particular piece of functionality. In ColdFusion, you define an application by giving it a name using the CFAPPLICATION tag. By using the same application name in a CFAPPLICATION tag, you definte a set of pages as being part of the same logical application.

 
 
  Note  
 

The value you set for the NAME attribute in CFAPPLICATION is limited to 64 characters.

 
 
  Using application variables  
 

Application variables are designed to store application-level data. They are a convenient place to store information that all pages of your application might need no matter who (what client) is running that application. Using application variables, an application could initialize itself, say, when the first user hit any page of that application. This information could then remain available indefinitely to all subsequent hits of any pages of that application, by all users, thereby avoiding the overhead of repeated initialization.

Because the data stored in application variables is available to all pages of an application and remains available until ColdFusion Server is shut down, application variables are very convenient. However, because all clients running an application see the same set of application variables, they are not useful for client-specific information. To target variables for specific clients, use session variables.

Application variables require an application name be associated with them and are always scoped within that application name.

Unlike client and session variables, however, they do not require that a client name (client ID) be associated with them. Thus, they are available to any clients that specify the same application name.

 
 
  Application variable time-outs  
 

Application variables have a specific lifetime, and this lifetime defines an "application." For example, when you access an application variable inside a specific application, the variable returns a value because your request occurs on a page declared in the CFAPPLICATION tag to be part of a single application.

The default time-out period for application variables is two days. In the Variables page of the ColdFusion Administrator, you can define time-out values for application and session variables. See Administering ColdFusion Server for more information.

You can set the time-out period for application variables within a specific application (thereby overriding the default setting in the ColdFusion Administrator) by using the APPLICATIONTIMEOUT attribute of the CFAPPLICATION tag.

If no clients access the application within the specified time-out period, ColdFusion Server destroys its application variables.

 
 
  Differentiating client, session, and application variables  
 

This table shows the relationships among client, session, and application variables:

Kinds of Variables
Variable Type
Application Names
Client IDs
Client Mgmt
Session Mgmt
Time-out
Client
Optional
Required
Required
n/a
Optional
Session
Optional
Required
Required
Required
Optional
Application
Required
n/a
n/a
n/a
Optional

 
 
  Variable scopes are required  
 

ColdFusion does not attempt to automatically evaluate Application and Session variables. You must use variable prefixes with these variables, as in Session.variablename or Application.variablename.

 
 
  Tips for using session and application variables  
 
 

In general, session and application variables are designed to hold information that you seldom write but are read often. In most cases, the values of these variables are set once, most often when an application is first started (Application variables) or the first time a user begins using an application (Session variables). Then the values of these variables will be referenced many times throughout the life of the application or the course of a session.

When using application variables, keep in mind that these variables are shared by all instances of an application that might be running on a server. Because of this sharing, applications cannot assume that values saved in these variables will not be overwritten by other instances of the same application that might be simultaneously running on the server. Of course, this is not a problem if these variables are treated as "write-once, read-many," but can be a problem if they are written to indiscriminately.

 
 
  Example  
 

Here is an example of the use of several application variables. Note that they are used within the Application.cfm file since this is a natural place to perform an operation that needs to be done every time any of the application's pages are run. In this example, an application variable, Application.Initialized, is used as a flag to indicate whether or not the application variables have been initialized.

<!--- Declare a name for this application. This 
automatically turns on application scope --->

<CFAPPLICATION NAME="AccountCheck">

<!--- Test to see if application variables 
have already been defined --->

<CFIF NOT IsDefined("application.initialized")>
    <CFSET application.query1=   ??? >
    <CFSET application.query2=   ??? >
    <CFSET application.initialized=1>
</CFIF>
 
 
  Managing session and application variables  
 
 

When you install ColdFusion, the default time-out for session variables is set to 20 minutes and for application variables, two days. There are two ways to manage application and session variable expiration. You can override these values by specifying different time-out values in the CFAPPLICATION tag. Or you can redefine the default time-out values in the ColdFusion Administrator.

To enable session and application scopes, and to define time-out options, open the Variables page of the ColdFusion Administrator. You can specify individual time-out settings for each variable type. Although these variables occupy very little of ColdFusion's available memory, you have the option of disabling their use altogether, or limiting their use with time-outs. See Administering ColdFusion Server for more information about using the Variables settings.

 
 
  Getting a list of application and session variables  
 

The variable scope names "application" and "session" are registered as ColdFusion structures. This enables you to use the ColdFusion Structure functions to get a list of application and session variables. For example, you can use CFLOOP with the StructFind function to output a list of application and session variables defined for a specific application.

To find a list of client variables, you use the GetClientList function.

See the CFML Language Reference for more information on these functions. See the chapter Working with Structures in the Advanced ColdFusion Development book.



 
 
BackUp LevelNext
 
 

allaire     AllaireDoc@allaire.com
    Copyright © 1998, Allaire Corporation. All rights reserved.