Special ColdFusion Variables and Result Codes

Macromedia ColdFusion provides access to many special variables that can be used within your applications. These variables generally fall into one of several categories:

• System variables

• Scope-related variables

• Tag-specific variables

• Query-related variables

All of these can be used like any other variables, by simply referencing them. Some have a specific prefix; others use a designated name (for example, a query name) as their prefix.

The following is a list of all special ColdFusion variables. Descriptions are provided for those that are not tag related (tag-related variables are described along with the appropriate tags in Appendix B, "ColdFusion Tag Reference"). For your convenience, cross-references to appropriate chapters in this book are provided as well.

It should be noted that <cffile>, <cfftp>, <cfhttp>, <cfquery>, and <cfstoredproc> include an attribute named result. This attribute is used to store the name of variable that you would prefer to use as an alternative to ColdFusion's name for the resulting variable.

For example, <cfquery> produces a structure variable named CFQUERY. You can use code like <cfquery result="myVar" ...> to create a structure named myVar which will work exactly like the system-generated variable, CFQUERY. APPLICATION Variables.

APPLICATION is a special scope whose contents are available to all requests within an application. APPLICATION is used primarily for the storage of custom information, but one predefined variable exists within it, as listed in Table D.1.

NOTE

APPLICATION variables must be locked (using <cflock>) before they are accessed.

Chapter 19, "Introducing the Web Application Framework."

ATTRIBUTE Variables

ATTRIBUTE is a special scope within ColdFusion, but it does not contain any predefined variables. This scope is used in ColdFusion custom tags to reference the tag's attribute values.

CALLER Variables

CALLER is a special scope that contains no predefined variables. Valid only for use within custom tags, CALLER provides access to variables in the calling page's scope as a structure.

Chapter 23, "Building Reusable Components."

CGI Variables

CGI variables are read-only variables that are pre-populated by ColdFusion for your use. They contain information about the server, request, and client. Some of the more common CGI variables are listed in Table D.2.

NOTE

Not all servers and clients set all these variables; check for their existence before use.

NOTE

Some popular "internet security" solutions (such as Symantec's Norton Internet Security software) block some CGI variables in your browser. Be aware that ColdFusion applications that you build that rely on certain CGI variables (e.g., HTTP_REFERER) may not work on browsers under the control of this software. Most of these packages can be configured to enable the use of the CGI variables but how it's done will vary from one package to the next.

TIP

CGI variable support varies from server to server and from browser to browser. Not all the CGI variables listed in Table D.2 will always be available, so check for their existence before using them.

NOTE

The ColdFusion function GetHTTPRequestData() returns a structure containing all browser-specified information, potentially including information not available via CGI variables.

<cfcatch> Variables

<cfcatch> is part of ColdFusion's error-handling system; when errors occur, details are made available via these variables:

• CFCATCH.Detail

• CFCATCH.ErrNumber

• CFCATCH.ErrorCode

• CFCATCH.ExtendedInfo

• CFCATCH.LockName

• CFCATCH.LockOperation

• CFCATCH.Message

• CFCATCH.MissingFileName

• CFCATCH.NativeErrorCode

• CFCATCH.QueryError

• CFCATCH.SQL

• CFCATCH.SQLState

• CFCATCH.TagContext

• CFCATCH.Type

• CFCATCH.Where

CFCATCH variables and the <cfcatch> tag are covered in detail in Chapter 32, "Error Handling."

<cfcollection action="list"> Query Columns

<cfcollection> is used to administer ColdFusion's Verity collections. When action="list" a query object is produced. There will be one row for each collection. The query object will contain the following columns:

• query.Charset

• query.Created

• query.Doccount

• query.External

• query.Language

• query.LastModified

• query.Name

• query.Path

• query.Size

<cfdirectory action="list"> Query Columns

<cfdirectory> is used to perform operations on file system directories. When ACTION="list" is used to retrieve directory contents, a query is returned containing the following columns:

• query.Attributes

• query.DateLastModified

• query.Directory

• query.Mode

• query.Name

• query.Size

• query.Type

NOTE

As with all queries, the standard query variables can also be used with the result set. The standard query variables are listed in the section "Query Variables," later in this appendix.

The <cfdirectory> tag is covered in detail in Chapter 34, "Interacting with the Operating System.".

<cffile action="upload"> Variables

<cffile> is used to perform file system operations. When action="upload" is used to process uploaded files, process details are made available with the following variables:

• CFFILE.AttemptedServerFile

• CFFILE.ClientDirectory

• CFFILE.ClientFile

• CFFILE.ClientFileExt

• CFFILE.ClientFileName

• CFFILE.ContentSubType

• CFFILE.ContentType

• CFFILE.DateLastAccessed

• CFFILE.FileExisted

• CFFILE.FileSize

• CFFILE.FileWasAppended

• CFFILE.FileWasOverwritten

• CFFILE.FileWasRenamed

• CFFILE.FileWasSaved

• CFFILE.OldFileSize

• CFFILE.ServerDirectory

• CFFILE.ServerFile

• CFFILE.ServerFileExt

• CFFILE.ServerFileName

• CFFILE.TimeCreated

• CFFILE.TimeLastModified

Note that you can optionally use the result attribute of <cffile> to define your own name for the structure that contains the upload results. It will contain the same information as the CFFILE variables.

Appendix B.

CFFILE variables and the <cffile> tag are covered in detail in Chapter 34.

<cfftp> Variables

<cfftp> is used to perform server-side FTP operations. Upon the completion of an operation, the following variables will contain status information:

• CFFTP.ErrorCode

• CFFTP.ErrorText

• CFFTP.ReturnValue

• CFFTP.Succeeded

Note that you can optionally use the result attribute of <cfftp> to define your own name for the structure that contains the results of your file operation. It will contain the same information as the CFFTP variables.

Appendix B.

NOTE

CFFTP variables and the <cfftp> tag are covered in the sequel to this book, Advanced ColdFusion MX 7 Application Development (Macromedia Press, ISBN: 0-321-29269-3).

<cfftp action="ListDir"> Query Columns

<cfftp> is used to perform server-side FTP operations. When ACTION="listdir" is used to retrieve directory contents, a query is returned containing the following columns:

• query.Attributes

• query.IsDirectory

• query.LastModified

• query.Length

• query.Mode

• query.Name

• query.Path

• query.URL

NOTE

As with all queries, the standard query variables can also be used with a result set. The standard query variables are listed in the section "Query Variables," later in this appendix.

<cfhttp> Variables

<cfhttp> is used to perform server-side HTTP operations. Upon the completion of an operation, the following variables will contain status information:

• CFHTTP.Charset

• CFHTTP.ErrorDetail

• CFHTTP.FileContent

• CFHTTP.Header

• CFHTTP.MimeType

• CFHTTP.ResponseHeader

• CFHTTP.StatusCode

• CFHTTP.Text

Note that you can optionally use the result attribute of <cfhttp> to define your own name for the structure that contains the results of your HTTP operation. It will contain the same information as the CFHTTP variables.

NOTE

Not all available variables are returned when method="post".

<cfldap action="query"> Query columns

<cfldap> is used to interact with LDAP servers. When action="query" is used to retrieve directory information, a query is returned containing the requested data. There are three predefined query variables listed below. The query will contain a column for each value specified in ATTRIBUTES.

• query.ColumnList

• query.CurrentRow

• query.RecordCount

NOTE

As with all queries, the standard query variables can also be used with a result set. The standard query variables are listed in the section "Query Variables," later in this appendix.

<cfpop action="GetHeaderOnly|GetAll"> Query Columns

<cfpop> is used to access POP3 mailboxes. When either ACTION="GetHeaderOnly" or ACTION="GetAll" is used to retrieve mailbox contents, a query is returned containing the following columns:

• query.AttachmentFiles (returned only when action = "GetAll")

• query.Attachments (returned only when action = "GetAll")

• query.Body (returned only when action = "GetAll")

• query.CC

• query.Date

• query.From

• query.Header (returned only when action = "GetAll")

• query.HTMLbody (returned only when action = "GetAll")

• query.MessageNumber

• query.ReplyTo

• query.Subject

• query.To

Several query properties are also accessible:

• query.ColumnList

• query.CurrentRow

• query.RecordCount

• query.UID

<cfquery> Variables

<cfquery> is used to execute SQL statements. In addition to returning a query (named in the name attribute), one predefined variable exists, as listed in Chapter 10, "Creating Data-Driven Pages."

<cfregistry> Query Variables

<cfregistry> is used to access the Windows Registry. When ACTION="GetAll" is used to retrieve Registry data, a query is returned containing the following columns:

• query.Entry

• query.Type

• query.Value

NOTE

As with all queries, the standard query variables can also be used with a result set. The standard query variables are listed in the section "Query Variables," later in this appendix.

The <cfregistry> tag and returned query columns are covered in detail in Chapter 34.

<cfsearch> Results Variables

<cfsearch> is used to perform full-text searches using the integrated Verity search engine. When a search is performed, a query is returned containing the following columns:

• query.Author

• query.Category

• query.CategoryTree

• query.Context

• query.CurrentRow

• query.ColumnList

• query.Custom1

• query.Custom2

• query.Custom3

• query.Custom4

• query.Key

• query.Rank

• query.RecordsSearched

• query.Score

• query.Size

• query.Summary

• query.Title

• query.3URL

Appendix B.

<cfsearch> also optionally returns a structure, which you name in its status attribute. If you employ this option, the following structure will be returned in a structure you've named.

• yourStruct.found

• yourStruct.keyWords

• yourStruce.searched

• yourStruct.suggestedQuery

• yourStruct.time

NOTE

As with all queries, the standard query variables can also be used with a result set. The standard query variables are listed in the section "Query Variables," later in this appendix.

The <cfsearch> tag and returned query columns are covered in detail in Chapter 35, "Full-Text Searching."

<cfservlet> Variables

No<cfservlet> has been deprecated and is no longer in use as of the release of ColdFusion.

<cfstoredproc> Variables

<cfstoredproc> is used to execute SQL stored procedures. In addition to returning one or more queries, two predefined variables exist, as listed in Table D.5.

Note that you can optionally use the result attribute of <cfstoredproc> to define your own name for the structure that contains the results of your stored proc. It will contain the same information as the CFSTOREDPROC variable.

Query-related tags are listed in the section "Query Variables," later in this appendix.

The <cfstoredproc> tag is covered in Chapter 31, "Working with Stored Procedures."

CLIENT Variables

CLIENT is a special scope whose contents are client-specific and persistent. CLIENT is used primarily for the storage of custom information, but several predefined variables exist within it, as listed in Chapter 20, "Working with Sessions."

COOKIE Variables

COOKIE is a special scope within ColdFusion, but it does not contain any predefined variables.

Chapter 20.

ERROR Variables

<cferror> is used to create alternate error pages to be displayed when errors occur. Within those pages, the following ERROR variables are available for use:

• ERROR.Browser

• ERROR.DateTime

• ERROR.Detail

• ERROR.Diagnostics

• ERROR.GeneratedContent

• ERROR.HTTPReferer

• ERROR.InvalidFields (only on validation errors)

• ERROR.LockName

• ERROR.LockOperation

• ERROR.MailTo

• ERROR.Message

• ERROR.MissingFileName

• ERROR.QueryString

• ERROR.RemoteAddress

• ERROR.RootCause

• ERROR.TagContext

• ERROR.Template

• ERROR.Type

• ERROR.ValidationHeader (only on validation errors)

• ERROR.ValidationFooter (only on validation errors)

Chapter 19.

FORM Variables

FORM is a special scope that contains form submissions. FORM also contains one predefined variable within it, as listed in Chapter 12, "ColdFusion Forms."

Query Variables

Queries are result sets returned by many ColdFusion tags (or created with the QueryNew() function). Queries primarily contain columns of data, but three predefined variables also exist, as listed in Table D.8.

NOTE

ColdFusion queries are introduced in Chapter 10.

REQUEST Variables

REQUEST is a special scope within ColdFusion, but it does not contain any predefined variables.

Chapter 23.

SERVER Variables

SERVER is a special scope whose contents are available to all requests within all applications. SERVER should generally not be used for the storage of custom information. Several predefined variables exist within it, as listed in Table D.9.

NOTE

SERVER variables must be locked (using <cflock>) before they are accessed.

SESSION Variables

SESSION is a special scope, the contents of which are client-specific and persistent for a specified duration. SESSION is used primarily for the storage of custom information, but several predefined variables exist within it, as listed in Table D.10.

SESSION variables and the <cfapplication> tag are covered in detail in Chapter 19.

TIP

SESSION variables must be locked (using <cflock>) before they are accessed.

ThisTag Variables

ThisTag is a special scope that exists only within ColdFusion custom tags. It can be used for the storage of data and also includes several predefined variables within it, as listed in Chapter 23.

URL Variables

URL is a special scope within ColdFusion, but it does not contain any predefined variables.

Chapter 10.