Macromedia ColdFusion provides access to many special variables that can be used within your applications. These variables generally fall into one of several categories:
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.
APPLICATION variables and the <cfapplication> tag are covered in detail in Chapter 19, "Introducing the Web Application Framework." ATTRIBUTE VariablesATTRIBUTE 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 VariablesCALLER 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 VariablesCGI 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:
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:
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:
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:
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:
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:
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:
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.
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:
These columns are described in Appendix B. Several query properties are also accessible:
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.
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:
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:
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.
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> VariablesNo<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 VariablesCLIENT 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.
CLIENT variables and the <cfapplication> tag are covered in detail in Chapter 20, "Working with Sessions." COOKIE VariablesCOOKIE 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:
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 VariablesFORM is a special scope that contains form submissions. FORM also contains one predefined variable within it, as listed in Table D.7.
Form use within ColdFusion is introduced in Chapter 12, "ColdFusion Forms." Query VariablesQueries 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 VariablesREQUEST is a special scope within ColdFusion, but it does not contain any predefined variables.
The REQUEST scope is explained in Chapter 23. SERVER VariablesSERVER 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 VariablesSESSION 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 VariablesThisTag 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.
The ThisTag scope and custom tags in general are covered in detail in Chapter 23. URL VariablesURL is a special scope within ColdFusion, but it does not contain any predefined variables.
URL use within ColdFusion is introduced in Chapter 10. |