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.




Macromedia Coldfusion MX 7 Web Application Construction Kit
Macromedia Coldfusion MX 7 Web Application Construction Kit
ISBN: 321223675
EAN: N/A
Year: 2006
Pages: 282

flylib.com © 2008-2017.
If you may any questions please contact us: flylib@qtcs.net