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.

Table D.1. APPLICATION Variables

VARIABLE	DESCRIPTION
APPLICATION.ApplicationName	Application name, as specified in the <Cfapplication> tag

NOTE

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

APPLICATION variables and the <cfapplication> tag are covered in detail in 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.

The CALLER scope is explained in 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.

Table D.2. CGI Variables

VARIABLE	DESCRIPTION
CGI.ALL_HTTP	All HTTP headers in header:value sets
CGI.ALL_RAW	All HTTP headers in raw form (as submitted by the client)
CGI.APPL_MD_PATH	Metabase path for the application when using ISAPI
CGI.APPL_PHYSICAL_PATH	Physical metabase path for the application when using ISAPI
CGI.AUTH_GROUP	Authentication group
CGI.AUTH_PASSWORD	Authentication password as specified by the client (if AUTH_TYPE is Basic)
CGI.AUTH_REALM	Authentication realm
CGI.AUTH_REALM_DESCRIPTION	Authentication realm browser string
CGI.AUTH_TYPE	Authentication method if authentication is supported and used, usually null or Basic
CGI.AUTH_USER	Authenticated username if authenticated by the operating system
CGI.CERT_COOKIE	Unique ID of client certificate
CGI.CERT_FLAGS	Certification flags; first bit will be on if client certificate is present; second bit will be on if the client certificate certifying authority (CA) is unknown
CGI.CERT_ISSUER	Client certificate issuer
CGI.CERT_KEYSIZE	Number of bits in SSL connection key size
CGI.CERT_SECRETKEYSIZE	Number of bits in server certificate private key
CGI.CERT_SERIALNUMBER	Client certificate serial number
CGI.CERT_SERVER_ISSUER	Server certificate issuer field
CGI.CERT_SERVER_SUBJECT	Server certificate subject field
CGI.CERT_SUBJECT	Server certificate subject field
CGI.CF_TEMPLATE_PATH	Path of ColdFusion file being executed
CGI.CLIENT_CERT_ENCODED	The binary, base-64 encoded certificate; used for integrating with client certificates
CGI.CONTENT_LENGTH	Length of submitted content (as reported by the client)
CGI.CONTENT_TYPE	Content type of submitted data
CGI.DATE_GMT	Current GMT date and time
CGI.DATE_LOCAL	Current local date and time
CGI.DOCUMENT_NAME	The complete local directory path of the current document
CGI.DOCUMENT_URI	Local path of the current document relative to the Web site base directory
CGI.GATEWAY_INTERFACE	CGI interface revision number (if CGI interface is used)
CGI.HTTP_ACCEPT	List of content types that the client browser will accept
CGI.HTTP_ACCEPT_CHARSET	ID of the client browser ISO character set in use
CGI.HTTP_ACCEPT_ENCODING	List of types of encoded data that the browser will accept
CGI.HTTP_ACCEPT_LANGUAGE	The human languages that the client can accept
CGI.HTTP_AUTHORIZATION	Authorization string within the Web server (used by IIS)
CGI.HTTP_CONNECTION	HTTP connection type; usually Keep-Alive
CGI.HTTP_COOKIE	The cookie sent by the client
CGI.HTTP_FORWARDED	Any proxies or gateways that forwarded the request
CGI.HTTP_HOST	HTTP host name, as sent by the client
CGI.HTTP_IF_MODIFIED_SINCE	Cache request value as submitted by the client
CGI.HTTP_PRAGMA	Any pragma directives
CGI.HTTP_REFERER	URL of the referring document (if referred)
CGI.HTTP_UA_CPU	Client computer CPU (processor) identifier (as provided by the client browser)
CGI.HTTP_UA_COLOR	Client computer color capabilities (as provided by the client browser)
CGI.HTTP_UA_OS	Client computer operating system (as provided by the client browser)
CGI.HTTP_UA_PIXELS	Client computer display resolution
CGI.HTTP_USER_AGENT	Client browser identifier (as provided by the client itself)
CGI.HTTPS	Flag indicating whether the request was via a secure HTTPS connection
CGI.HTTPS_KEYSIZE	Number of bits in SSL connection key size
CGI.HTTPS_SECRETKEYSIZE	Number of bits in server certificate private key
CGI.HTTPS_SERIALNUMBER	Server certificate serial number
CGI.HTTPS_SERVER_ISSUER	Server certificate issuer field
CGI.HTTPS_SERVER_SUBJECT	Server certificate subject field
CGI.INSTANCE_ID	ID of IIS instance
CGI.INSTANCE_META_PATH	Metabase path for the instance of IIS responding to a request
CGI.LAST_MODIFIED	Date and time of the last modification to the document
CGI.LOCAL_ADDRESS	IP address of server on which the request came in (used primarily in multihomed hosts)
CGI.LOGON_USER	Windows account the user is logged in to
CGI.PATH_INFO	Requested file path information (as provided by the client)
CGI.PATH_TRANSLATED	Server translation of CGI.PATH_INFO (can be set even if CGI.PATH_INFO is empty)
CGI.QUERY_STRING	Contents of the URL after the ?
CGI.QUERY_STRING_UNESCAPED	Unescaped version of CGI.QUERY_STRING
CGI.REMOTE_ADDR	Client IP address
CGI.REMOTE_HOST	Client host name (if available)
CGI.REMOTE_IDENT	Remote user identification (if server supports RFC 931)
CGI.REMOTE_USER	Authentication method if authentication is supported and used
CGI.REQUEST_BODY	Request body text (used by Apache)
CGI.REQUEST_METHOD	Request method (for example, GET, HEAD, or POST)
CGI.REQUEST_URI	Requested URL; useful when multiple hosts share a single IP address (used by Apache)
CGI.SCRIPT_FILENAME	Logical path of script being executed (used by Apache)
CGI.SCRIPT_NAME	Logical path of script being executed
CGI.SERVER_ADMIN	Email address of server administrator (used by Apache)
CGI.SERVER_CHARSET	Server default character set
CGI.SERVER_NAME	Server name
CGI.SERVER_PORT	Server port on which the request was received
CGI.SERVER_PORT_SECURE	Server port on which the secure request was received (usually 0 if not secure)
CGI.SERVER_PROTOCOL	Name and version of the server protocol with which the request was received
CGI.SERVER_SIGNATURE	Server ID, host, and port (used by Apache)
CGI.SERVER_SOFTWARE	HTTP server software name and version
CGI.URL	URL base
CGI.WEB_SERVER_API	Web server API used (if not CGI)

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

These variables are described in Appendix B.

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

These columns are described in Appendix B.

<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

These columns are described in Appendix B.

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.

These variables are described in 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.

These variables are described in 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

These columns are described in Appendix B.

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

These variables are described in Appendix B.

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

These columns are described in Appendix B.

Several query properties are also accessible:

• query.ColumnList

• query.CurrentRow

• query.RecordCount

• query.UID

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.

Not all query columns are returned when action="GetHeaderOnly".

<cfpop> results and the <cfpop> tag are covered in detail in Chapter 27, "Interacting with Email."

<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 Table D.3.

Table D.3. <cfquery> Variables

VARIABLE	DESCRIPTION
CFQUERY.ExecutionTime	Query execution time (in milliseconds)Note that you can optionally use the result attribute of <cfquery> to define your own name for the structure that contains the results of you query operation. It contains the variables described in table D.4

Table D.4. <cfquery> Result Variables

VARIABLE	DESCRIPTION
queryStruct.cached	True or False-indicates whether the query was cached
queryStruct.columnList	Array containing list of column in the result set
queryStruct.executionTime	Query execution time (in milliseconds)
queryStruct.recordCount	Number of records returned in the result set
queryStruct.SQL	The SQL that was employed in the query

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 <cfquery> tag is introduced 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

These columns are described in Appendix B.

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

These columns are described in 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

This structure is described in Appendix B.

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.

Table D.5. <cfstoredproc> Variables

VARIABLE	DESCRIPTION
CFSTOREDPROC.ExecutionTime	Stored procedure execution time (in milliseconds)

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 Table D.6.

Table D.6. CLIENT Variables

VARIABLE	DESCRIPTION
CLIENT.CFID	Client ID, used as part of the client identification mechanism
CLIENT.CFToken	Client token, used as part of the client identification mechanism
CLIENT.HitCount	Request counter
CLIENT.LastVisit	Date and time of last client visit
CLIENT.TimeCreated	Date and time of first client visit
CLIENT.URLToken	String containing complete CFID and CFToken values (for URL embedding)

CLIENT variables and the <cfapplication> tag are covered in detail in Chapter 20, "Working with Sessions."

COOKIE Variables

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

The COOKIE scope is explained in 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)

These variables are described in Appendix B.

NOTE

Not all ERROR variables are always available; this varies based on the type of error and error page.

ERROR variables and the <cferror> tag are covered in detail in Chapter 19.

FORM Variables

FORM is a special scope that contains form submissions. FORM also contains one predefined variable within it, as listed in Table D.7.

Table D.7. FORM Variables

VARIABLE	DESCRIPTION
FORM.FieldNames	Comma-delimited list of all submitted form field names

Form use within ColdFusion is introduced 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.

Table D.8. QUERY Variables

VARIABLE	DESCRIPTION
ColumnList	Comma-delimited list of query column names
CurrentRow	Current row (when being looped within <cfoutput>)
RecordCount	Number of rows in a query

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.

The REQUEST scope is explained in 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.

Table D.9. SERVER Variables

VARIABLE	DESCRIPTION
SERVER.ColdFusion.AppServer	Identifies the application server platform (e.g. JRun)
SERVER.ColdFusion.Expiration	Date that license expires (if there is a date)
SERVER.ColdFusion.InstallKit	Identifies the manner in which CF was installed
SERVER.ColdFusion.ProductName	ColdFusion product name
SERVER.ColdFusion.ProductVersion	ColdFusion product version
SERVER.ColdFusion.ProductLevel	ColdFusion product level
SERVER.ColdFusion.RootDir	Directory in which CF is installed
SERVER.ColdFusion.SerialNumber	ColdFusion serial number
SERVER.ColdFusion.SupportedLocales	List of supported ColdFusion locales
SERVER.OS.Arch	Hardware architecture (e.g., x86)
SERVER.OS.Name	Operating system name
SERVER.OS.AdditionalInformation	Operating system additional information
SERVER.OS.Version	Operating system version
SERVER.OS.BuildNumber	Operating system build number

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.

Table D.10. SESSION Variables

VARIABLE	DESCRIPTION
SESSION.CFID	Client ID, used as part of the client identification mechanism
SESSION.CFToken	Client token, used as part of the client identification mechanism
SESSION.URLToken	String containing complete CFID and CFToken values (for URL embedding)

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 Table D.11.

Table D.11. ThisTag Variables

VARIABLE	DESCRIPTION
ThisTag.AssocAttribs	Associated attributes (if an associated tag is used)
ThisTag.ExecutionMode	Tag execution mode
ThisTag.GeneratedContent	Content between the tag pairs in the caller page
ThisTag.HasEndTag	Flag indicating calling convention (as a single tag, or as part of a tag pair)

The ThisTag scope and custom tags in general are covered in detail in Chapter 23.

URL Variables

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

URL use within ColdFusion is introduced in Chapter 10.