Whatever message this page gives is out now! Go check it out!
Configuring and using client variables
Last update:
Jun 9, 2026
Use client variables for data that is associated with a particular client and application and that must be saved between user sessions. Use client variables for long-term information such as user display or content preferences.
Enabling client variables
To enable client variables, you specify this.clientmanagement="True" in the Application.cfc initialization code, or set the cfapplication tag clientmanagement attribute to Yes in the Application.cfm file. For example, to enable client variables in an application named SearchApp, you can use the following line in the application's Application.cfm page:
<cfapplication NAME="SearchApp" clientmanagement="Yes">Choosing a client variable storage method
y default, ColdFusion stores client variables in the Registry. In most cases, however, it is more appropriate to store the information as client cookies or in a SQL database.
The ColdFusion Administrator Client Variables page controls the default client variable location. You can override the default location by specifying a This. clientStorage value in Application.cfc or by setting the clientStorage attribute in the cfapplication tag.
You can specify the following values for the client storage method:
The ColdFusion Administrator Client Variables page controls the default client variable location. You can override the default location by specifying a This. clientStorage value in Application.cfc or by setting the clientStorage attribute in the cfapplication tag.
You can specify the following values for the client storage method:
- Registry (default). Client variables are stored under the key HKEY_LOCAL_MACHINE\ SOFTWARE\Macromedia\ColdFusion\CurrentVersion\Clients.
- Name of a data source configured in ColdFusion Administrator
- Cookie
Generally, it is most efficient to store client variables in a database. Although the Registry option is the default, the Registry has significant limitations for client data storage. The Registry cannot be used in clustered systems and its use for client variables on UNIX is not supported in ColdFusion.
Using cookie storage
When you set the client storage method to Cookie, the cookie that ColdFusion creates has the application's name. Storing client data in a cookie is scalable to large numbers of clients, but this storage mechanism has some limitations. In particular, if the client turns off cookies in the browser, client variables do not work.
Consider the following additional limitations before implementing cookie storage for client variables:
Consider the following additional limitations before implementing cookie storage for client variables:
- Any Client variable that you set after a cfflush tag is not sent to the browser, so the variable value does not get saved.
- Some browsers allow only 20 cookies to be set from a particular host. ColdFusion uses two of these cookies for the CFID and CFToken identifiers, and also creates a cookie named cfglobals to hold global data about the client, such as HitCount , TimeCreated, and LastVisit . This limits you to 17 unique applications per client-host pair.
- Some browsers set a size limit of 4K bytes per cookie. ColdFusion encodes nonalphanumeric data in cookies with a URL encoding scheme that expands at a 3-1 ratio, which means you should not store large amounts of data per client. ColdFusion throws an error if you try to store more than 4,000 encoded bytes of data for a client.
Configuring database storage
When you specify a database for client variable storage, do not always have to manually create the data tables that store the client variables.
If ColdFusion can identify that the database you are using supports SQL creation of database tables, create the database in advance. When you click the Add button on the Select Data Source to Add as Client Store box on the Memory Variables page, the Administrator displays a Add/Edit Client Store page which contains a Create Client Database Tables selection box. Select this option to have ColdFusion create the necessary tables in your database. (The option does not appear if the database already has the required tables.)
If your database does not support SQL creation of tables, or if you are using the ODBC socket Macromedia driver to access your database, use your database tool to create the client variable tables. Create the CDATA and CGLOBAL tables.
The CDATA table must have the following columns:
If ColdFusion can identify that the database you are using supports SQL creation of database tables, create the database in advance. When you click the Add button on the Select Data Source to Add as Client Store box on the Memory Variables page, the Administrator displays a Add/Edit Client Store page which contains a Create Client Database Tables selection box. Select this option to have ColdFusion create the necessary tables in your database. (The option does not appear if the database already has the required tables.)
If your database does not support SQL creation of tables, or if you are using the ODBC socket Macromedia driver to access your database, use your database tool to create the client variable tables. Create the CDATA and CGLOBAL tables.
The CDATA table must have the following columns:
Column | Data type |
cfid | CHAR(64), TEXT, VARCHAR, or any data type capable of taking variable length strings up to 64 characters |
app | CHAR(64), TEXT, VARCHAR, or any data type capable of taking variable length strings up to 64 characters |
data | MEMO, LONGTEXT, LONG VARCHAR, CLOB, or any data type capable of taking long, indeterminate-length strings |
The CGLOBAL table must have the following columns:
Column | Data type |
cfid | CHAR(64), TEXT, VARCHAR, or any data type capable of taking variable length strings up to 64 characters |
data | MEMO, LONGTEXT, LONG VARCHAR, CLOB, or any data type capable of taking long, indeterminate-length strings |
lvisit | TIMESTAMP, DATETIME , DATE, or any data type that stores date and time values |
Note:
Different databases use different names for their data types. The names in the preceding tables are common, but your database might use other names.
To improve performance, create indexes when you create these tables. For the CDATA table, index these cfid and app columns. For the CGLOBAL table, index the cfid column.
Specifying client variable storage in your application
The override the default client variable storage location, set the This. clientstorage variable in the Application.cfc initialization code, or use the cfapplication tag clientStorage attribute.
The following lines from an Application.cfc file tell ColdFusion to store the client variables in the mydatasource data source:
The following lines from an Application.cfc file tell ColdFusion to store the client variables in the mydatasource data source:
<cfscript>
this.name="SearchApp";
this.clientManagement="Yes";
this.clientStorage="mydatasource";
</cfscript>The following code from an Application.cfm file does the same thing as the previous example:
clientmanagement="Yes"
clientstorage="mydatasource">Using client variables
When you enable client variables for an application, you can use them to keep track of long-term information that is associated with a particular client.
Client variables must be simple data types: strings, numbers, lists, Booleans, or date and time values. They cannot be arrays, recordsets , XML objects, query objects, or other objects. If you must store a complex data type as a client variable, you can use the cfwddx tag to convert the data to WDDX format (which is represented as a string), store the WDDX data, and use the cfwddx tag to convert the data back when you read it. For more information on using WDDX, see Using WDDX.
Client variables must be simple data types: strings, numbers, lists, Booleans, or date and time values. They cannot be arrays, recordsets , XML objects, query objects, or other objects. If you must store a complex data type as a client variable, you can use the cfwddx tag to convert the data to WDDX format (which is represented as a string), store the WDDX data, and use the cfwddx tag to convert the data back when you read it. For more information on using WDDX, see Using WDDX.
When saving client variable data in WDDX format, in the case of the registry and SQL Server, the limit is about 4K; with ORACLE, the limit is about 2K. |
Creating a client variable
<cfset Client.FavoriteColor="Red">After you set a client variable this way, it is available for use within any page in your application that is accessed by the client for whom the variable is set.
The following example shows how to use the cfparam tag to check for the existence of a client parameter and set a default value if the parameter does not exist:
The following example shows how to use the cfparam tag to check for the existence of a client parameter and set a default value if the parameter does not exist:
<cfparam name="Client.FavoriteColor" default="Red">Accessing and changing client variables
You use the same syntax to access a client variable as for other types of variables. You can use client variables anywhere you use other ColdFusion variables.
To display the favorite color that has been set for a specific user, for example, use the following code:
To display the favorite color that has been set for a specific user, for example, use the following code:
Your favorite color is #Client.FavoriteColor#.
</cfoutput>To change the client's favorite color, for example, use code such as the following:
<cfset Client.FavoriteColor = Form.FavoriteColor>Standard client variables
The Client scope has the following built-in, read-only variables that your application can use:
Variable | Description |
Client.CFID | The client ID, normally stored on the client system as a cookie. |
Client.CFToken | The client security token, normally stored on the client system as a cookie. |
Client.URLToken | Value depends on whether J2EE session management is enabled. No session management or ColdFusion session management: A combination of the CFID and CFToken values, in the form CFID=IDNum{{&CFTOKEN=}}tokenNum. This variable is useful if the client does not support cookies and you pass the CFID and CFToken variables from page to page.J2EE session management: A combination of CFID, CFToken, and session ID values in the form {{CFID=}}IDNum{{&CFTOKEN=}}tokenNum{{&jsessionid=}}SessionID. |
Client.HitCount | The number of page requests made by the client. |
Client.LastVisit | The last time the client visited the application. |
Client.TimeCreated | The time the CFID and CFToken variables that identify the client to ColdFusion were first created. |
Note:
ColdFusion lets you delete or change the values of the built-in client variables. As a general rule, avoid doing so.
You use the Client.CFID, Client.CFToken, and Client.URLToken variables if your application supports browsers that do not allow cookies. For more information on supporting browsers that do not allow cookies, see Using client and session variables without cookies in Managing the client state.
You can use the Client.HitCount and time information variables to customize behavior that depends on how often users visit your site and when they last visited. For example, the following code shows the date of a user's last visit to your site:
You can use the Client.HitCount and time information variables to customize behavior that depends on how often users visit your site and when they last visited. For example, the following code shows the date of a user's last visit to your site:
Welcome back to the Web SuperShop. Your last
visit was on #DateFormat(Client.LastVisit)#.
</cfoutput>Getting a list of client variables
To obtain a list of the custom client parameters associated with a particular client, use the GetClientVariablesList function, as follows:
<cfoutput>#GetClientVariablesList()#</cfoutput>The GetClientVariablesList function returns a comma-separated list of the names of the client variables for the current application. The standard system-provided client variables (CFID, CFToken, URLToken, HitCount , TimeCreated, and LastVisit ) are not returned in the list.
Deleting client variables
To delete a client variable, use the StructDelete function or the DeleteClientVariable function. For example, the following lines are equivalent:
<cfset IsDeleteSuccessful=StructDelete(Client, "MyClientVariable")>The Client Variables page in the ColdFusion Administrator lets you set a time-out period of inactivity after which ColdFusion removes client variables stored in either the Registry or a data source. (The default value is 10 days for client variables stored in the Registry, and 90 days for client variables stored in a data source.)
Note:
You cannot delete the system-provided client variables (CFID, CFToken, URLToken, HitCount, TimeCreated, and LastVisit).
Using client variables with cflocation
If you use the cflocation tag to redirect ColdFusion to a path that ends with .dbm or .cfm, the Client. URLToken variable is automatically appended to the URL. You can prevent this behavior by adding the attribute addtoken="No" to the cflocation tag.
Caching client variable
When ColdFusion reads or writes client variables, it caches the variables in memory to help decrease the overhead of accessing the client data. As a result, ColdFusion only accesses the client data store when you read its value for the first time or, for values you set, when the request ends. Additional references to the client variable use the cached value in ColdFusion memory, thereby processing the page more quickly.
Exporting the client variable database
If your client variable database is stored in the Windows system Registry and you need to move it to another machine, you can export the Registry key that stores your client variables and take it to your new server. The system Registry lets you export and import Registry entries.
To export your client variable database from the Registry in Windows:
To export your client variable database from the Registry in Windows:
- Open the Registry editor.
- Find and select the following key:
HKEY_LOCAL_MACHINE\SOFTWARE\Macromedia\ColdFusion\CurrentVersion\Clients- On the Registry menu, click Export Registry File.
- Enter a name for the Registry file.
After you create a Registry file, you can copy it to a new machine and import it by clicking Import Registry File on the Registry editor Registry menu.
Note:
On UNIX systems, the registry entries are kept in /opt/coldfusion/registry/cf.registry, a text file that you can copy and edit directly.
We're glad. Tell us how this page helped.
We're sorry. Can you tell us what didn't work for you?
Share additional feedback to help us improve.
0/255
|
