User manual MACROMEDIA COLFUSION MX 7 -CFML REFERENCE

COLDFUSION MX 7 ® CFML Reference Trademarks 1 Step RoboPDF, ActiveEdit, ActiveTest, Authorware, Blue Sky Software, Blue Sky, Breeze, Breezo, Captivate, Central, ColdFusion, Contribute, Database Explorer, Director, Dreamweaver, Fireworks, Flash, FlashCast, FlashHelp, Flash Lite, FlashPaper, Flex, Flex Builder, Fontographer, FreeHand, Generator, HomeSite, JRun, MacRecorder, Macromedia, MXML, RoboEngine, RoboHelp, RoboInfo, RoboPDF, Roundtrip, Roundtrip HTML, Shockwave, SoundEdit, Studio MX, UltraDev, and WebHelp are either registered trademarks or trademarks of Macromedia, Inc. and may be registered in the United States or in other jurisdictions including internationally. Other product names, logos, designs, titles, words, or phrases mentioned within this publication may be trademarks, service marks, or trade names of Macromedia, Inc. or other entities and may be registered in certain jurisdictions including internationally. This product includes code licensed from RSA Data Security. Third-Party Information This guide contains links to third-party websites that are not under the control of Macromedia, and Macromedia is not responsible for the content on any linked site. If you access a third-party website mentioned in this guide, then you do so at your own risk. Macromedia provides these links only as a convenience, and the inclusion of the link does not imply that Macromedia endorses or accepts any responsibility for the content on those third-party sites. Copyright © 1999­2005 Macromedia, Inc. All rights reserved. U.S. Patents Pending. This manual may not be copied, photocopied, reproduced, translated, or converted to any electronic or machine-readable form in whole or in part without written approval from Macromedia, Inc. Notwithstanding the foregoing, the owner or authorized user of a valid copy of the software with which this manual was provided may print out one copy of this manual from an electronic version of this manual for the sole purpose of such owner or authorized user learning to use such software, provided that no part of this manual may be printed out, reproduced, distributed, resold, or transmitted for any other purposes, including, without limitation, commercial purposes, such as selling copies of this documentation or providing paid-for support services. Part Number ZCF70M600 Acknowledgments Project Management: Randy Nielsen Writing: Hal Lichtin, Randy Nielsen Editing: Linda Adler, Noreen Maher Production Management: Patrice O'Neill, Media Design and Production: John Francis, Adam Barnett First Edition: January 2005 Macromedia, Inc. 600 Townsend St. San Francisco, CA 94103 CONTENTS INTRODUCTION ................................................... 5 ............................. 7 CHAPTER 1: Reserved Words and Variables Reserved words . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 Scope-specific built-in variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 Custom tag variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 ColdFusion tag-specific variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 Standard CGI variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16 CGI environment variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 CHAPTER 2: ColdFusion Tags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21 Tags by function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26 Tag changes since ColdFusion 5 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29 CHAPTER 3: ColdFusion Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 449 Functions by category . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 452 Function changes since ColdFusion 5 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 457 CHAPTER 4: ColdFusion MX Flash Form Style Reference . . . . . . . . . . . . . . . . 933 Styles valid for all controls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 934 Styles for cfform . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 936 Styles for cfformgroup with horizontal or vertical type atributes . . . . . . . . . . . . . 936 Styles for box-style cfformgroup elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 937 Styles for cfformgroup with accordion type attribute . . . . . . . . . . . . . . . . . . . . . . 938 Styles for cfformgroup with tabnavigator type attribute . . . . . . . . . . . . . . . . . . . . 939 Styles for cfformitem with hrule or vrule type attributes . . . . . . . . . . . . . . . . . . . 939 Styles for cfinput with radioButton, checkbox, button, image, or submit type attributes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 940 Styles for cftextarea tag and cfinput with text, password, or hidden type attributes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 941 Styles for cfselect with size attribute value of 1. . . . . . . . . . . . . . . . . . . . . . . . . . . 941 Styles for cfselect with size attribute value greater than 1 . . . . . . . . . . . . . . . . . . . 942 Styles for cfcalendar tag and cfinput with dateField type attribute . . . . . . . . . . . . 942 Styles for the cfgrid tag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 943 Styles for the cftree tag. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 943 3 CHAPTER 5: Application.CFC Reference. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 945 Application variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 945 Method summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 946 CHAPTER 6: ColdFusion MX Event Gateway Reference . . . . . . . . . . . . . . . . . . 963 Gateway development interfaces and classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . 963 CFML CFEvent structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1004 IM gateway methods and commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1004 SMS Gateway CFEvent structure and commands . . . . . . . . . . . . . . . . . . . . . . . 1042 CHAPTER 7: ColdFusion C++ CFX Reference . . . . . . . . . . . . . . . . . . . . . . . . . 1055 C++ class overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1055 Deprecated class methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1056 CCFXException class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1056 CCFXQuery class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1058 CCFXRequest class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1062 CCFXStringSet class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1072 CHAPTER 8: ColdFusion Java CFX Reference . . . . . . . . . . . . . . . . . . . . . . . . 1075 Class libraries overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1075 Custom tag interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1076 Query interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1077 Request interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1082 Response interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1087 Debugging classes reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1090 CHAPTER 9: WDDX JavaScript Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1091 JavaScript object overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1091 WddxSerializer object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1092 WddxRecordset object. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1095 CHAPTER 10: ColdFusion ActionScript Functions. . . . . . . . . . . . . . . . . . . . . . 1101 4 Contents INTRODUCTION CFML Reference is your primary ColdFusion Markup Language (CFML) reference. Use this manual to learn about CFML tags and functions, ColdFusion expressions, and using JavaScript objects for WDDX in Macromedia ColdFusion MX 7. It also provides detailed references for Java and C++ CFX interfaces. About Macromedia ColdFusion MX documentation The ColdFusion MX documentation is designed to provide support for the complete spectrum of participants. Documentation set The ColdFusion documentation set includes the following titles: Manual Installing and Using ColdFusion MX Configuring and Administering ColdFusion MX Description Describes system installation and basic configuration for Windows, Solaris, Linux, and HP-UX. Part I describes how to manage the ColdFusion environment, including connecting to your data sources and configuring security for your applications. Part II describes Verity search tools and utilities that you can use for configuring the Verity K2 Server search engine, as well as creating, managing, and troubleshooting Verity collections. Describes how to develop your dynamic web applications, including retrieving and updating your data, and using structures and forms. Contains an overview of ColdFusion features and application development procedures. Includes a tutorial that guides you through the process of developing an example ColdFusion application. Provides descriptions, syntax, usage, and code examples for all ColdFusion tags, functions, and variables. ColdFusion MX Developer's Guide Getting Started Building ColdFusion MX Applications CFML Reference CFML Quick Reference A brief guide that shows the syntax of ColdFusion tags, functions, and variables. 5 Viewing online documentation All ColdFusion MX documentation is available online in HTML and Adobe Acrobat Portable Document Format (PDF) files. Go to the documentation home page for ColdFusion MX on the Macromedia website: www.macromedia.com. 6 Introduction: CHAPTER 1 Reserved Words and Variables This chapter provides information on Macromedia ColdFusion reserved words, and lists scope variables. Contents Reserved words . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 Scope-specific built-in variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 ColdFusion tag-specific variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 CGI environment variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 Reserved words The following list indicates words you must not use for ColdFusion variables, user-defined function names, or custom tag names. While some of these words can be used safely in some situations, you can prevent errors by avoiding them entirely. · Any name starting with cf. However, when you call a CFML custom tag directly, you prefix the custom tag page name with cf_. · · · · · · Built-in function names, such as Now or Hash Scope names, such as Form or Session Operators, such as NE or IS The names of any built-in data structures, such as Error or File The names of any built-in variables, such as RecordCount or CGI variable names CFScript language element names such as for, default, or continue Remember that ColdFusion is not case-sensitive. For example, all of the following are reserved words: IS, Is, iS, and is. 7 Reserved words in forms You must also not create form field names ending in any of the following, except to specify a form field validation rule using a hidden form field name. · · · · · · _integer _float _range _date _time _eurodate Reserved words in queries The following table lists SQL keywords that are reserved in ColdFusion queries of queries. This list includes all reserved words in the SQL standard, and should be avoided in variables used in all queries. Do not use these keywords as variable names in any queries. Note: Many database management systems have additional reserved words that you cannot use as variable names in queries to their databases. For a detailed list, see your DBMS documentation. ABSOLUTE ALTER ASC BEGIN BY CATALOG CHECK COLUMN ACTION AND ASSERTION BETWEEN CASCADE CHAR CLOSE COMMIT ADD ANY AT BIT CASCADED CHARACTER COALESCE CONNECT CONVERT CURRENT CURSOR DECIMAL DELETE DISCONNECT ELSE EXCEPTION EXTRACT FOR ALL ARE AUTHORIZATION BIT_LENGTH CASE CHARACTER_ LENGTH COLLATE CONNECTION ALLOCATE AS AVG BOTH CAST CHAR_LENGTH COLLATION CONSTRAINT CONSTRAINTS CONTINUE CREATE CURRENT_ TIMESTAMP DEALLOCATE DEFERRABLE DESCRIPTOR DOUBLE ESCAPE EXISTS FIRST CROSS CURRENT_ USER DEC DEFERRED DIAGNOSTICS DROP EXCEPT EXTERNAL FLOAT CORRESPONDING COUNT CURRENT_DATE DATE DECLARE DESC DISTINCT END EXEC FALSE FOREIGN CURRENT_TIME DAY DEFAULT DESCRIBE DOMAIN END-EXEC EXECUTE FETCH FOUND 8 Chapter 1: Reserved Words and Variables FROM GOTO IDENTITY INNER INTEGER ISOLATION LEADING LOWER MODULE NCHAR NULLIF ONLY OUTER POSITION PRIOR REAL RIGHT SECOND SET SQL SUM TIME TRAILING TRUE UPPER VALUES WHENEVER YEAR FULL GRANT IMMEDIATE INPUT INTERSECT JOIN LEFT MATCH MONTH NEXT NUMERIC OPEN OUTPUT PRECISION PRIVILEGES REFERENCES ROLLBACK SECTION SIZE SQLCODE GET GROUP IN INSENSITIVE INTERVAL KEY LEVEL MAX NAMES NO OCTET_LENGTH OPTION OVERLAPS PREPARE PROCEDURE RELATIVE ROWS SELECT SMALLINT SQLERROR GLOBAL HAVING INDICATOR INSERT INTO LANGUAGE LIKE MIN NATIONAL NOT OF OR PAD PRESERVE PUBLIC RESTRICT SCHEMA SESSION SOME SQLSTATE TEMPORARY TIMEZONE_ MINUTE TRANSLATION UNKNOWN USING VIEW WORK GO HOUR INITIALLY INT IS LAST LOCAL MINUTE NATURAL NULL ON ORDER PARTIAL PRIMARY READ REVOKE SCROLL SESSION_USER SPACE SUBSTRING THEN TO TRIM UPDATE VALUE WHEN WRITE SYSTEM_USER TABLE TIMESTAMP TRANSACTION UNION USAGE VARCHAR WHERE ZONE TIMEZONE_ HOUR TRANSLATE UNIQUE USER VARYING WITH Scope-specific built-in variables ColdFusion returns variables, such as those returned in a cfdirectory or cfftp operation. A variable is usually referenced by scoping it according to its type: naming it according to the code context in which it is available; for example, Session.varname, or Application.varname. For more information on ColdFusion scopes, see Chapter 3, "Using ColdFusion Variables" in ColdFusion MX Developer's Guide Scope-specific built-in variables 9 You use the cflock tag to limit the scope of CFML constructs that modify shared data structures, files, and CFXs, to ensure that modifications occur sequentially. For more information, see cflock on page 270, and Chapter 15, "Using Persistent Data and Locking" in ColdFusion MX Developer's Guide. Variable scope ColdFusion supports the Variables scope. Unscoped variables created with the cfset tag acquire the Variables scope by default. For example, the variable created by the statement can be referenced as #Variables.linguist# Caller scope History ColdFusion MX: The Caller scope is accessible as a structure. (In earlier releases, it was not.) Client variables The following client variables are reserved: Client.CFID Client.CFToken Client.HitCount Client.LastVisit Client.TimeCreated Client.URLToken Server variables Use the Server prefix to reference server variables, as follows: Server.ColdFusion.ProductName Server.ColdFusion.ProductVersion Server.ColdFusion.ProductLevel Server.ColdFusion.SerialNumber Server.ColdFusion.SupportedLocales Server.ColdFusion.AppServer Server.ColdFusion.Expiration Server.ColdFusion.RootDir Server.OS.Name Server.OS.AdditionalInformation Server.OS.Version Server.OS.BuildNumber Application and session variables To enable application and session variables, use the cfapplication tag or Application.cfc. Reference them as follows: Application.myvariable Session.myvariable To ensure that modifications to shared data occur in the intended sequence, use the cflock tag. For more information, see cflock on page 270. 10 Chapter 1: Reserved Words and Variables The predefined application and session variables are as follows: Application.ApplicationName Session.CFID Session.CFToken Session.URLToken Custom tag variables A ColdFusion custom tag returns the following variables: ThisTag.ExecutionMode ThisTag.HasEndTag ThisTag.GeneratedContent ThisTag.AssocAttribs[index] A custom tag can set a Caller variable to provide information to the caller. The Caller variable is set as follows: The calling page can access the variable with the cfoutput tag, as follows: #variable_name# Request variable Request variables store data about the processing of one page request. Request variables store data in a structure that can be passed to nested tags, such as custom tags, and processed once. To provide information to nested tags, set a Request variable, as follows: ... Each nested tag can access the variable with the cfoutput tag, as follows: #Request.field_name1# Form variable ColdFusion supports the Form variable FieldNames. FieldNames returns the names of the fields on a form. You use it on the action page associated with a form, as follows: Form.FieldNames ColdFusion tag-specific variables Some ColdFusion tags return data as variables. For example, the cffile tag returns file size information in the FileSize variable, referenced as CFFILE.FileSize. The following tags return data that can be referenced in variables: cfcatch cfdirectory cferror ColdFusion tag-specific variables 11 cffile cfftp cfhttp cfindex cfldap cfpop cfquery cfregistry cfsearch cfstoredproc ColdFusion query variables A ColdFusion tag that returns a query object supports the following variables, where queryname is the value of the name attribute: queryname.CurrentRow queryname.RecordCount queryname.ColumnList CFCATCH variables Within a cfcatch block, the active exception properties can be accessed as the following variables: CFCATCH.Type CFCATCH.Message CFCATCH.Detail CFCATCH.ErrNumber CFCATCH.NativeErrorCode CFCATCH.SQLState CFCATCH.LockName CFCATCH.LockOperation CFCATCH.MissingFileName CFCATCH.TagContext CFCATCH.ErrorCode CFCATCH.ExtendedInfo Within a cfcatch block, database exception properties can be accessed as the following variables: CFCATCH.QueryError CFCATCH.SQL CFCATCH.Where CFCATCH.Datasource Within a cfcatch block, undefined variable exception properties can be accessed as the following variable: CFCATCH.Name Within a cfcatch block, syntax and parsing exception properties can be accessed as the following variables: CFCATCH.TokenText CFCATCH.Snippet CFCATCH.Column CFCATCH.KnownColumn 12 Chapter 1: Reserved Words and Variables CFCATCH.Line CFCATCH.KnownLine CFDIRECTORY variables The cfdirectory tag, with action=list, returns a query object as follows, where queryname is the name attribute value: queryname.Name queryname.Size queryname.Type queryname.DateLastModified queryname.Attributes queryname.Mode CFERROR variables type="request" When cferror generates an error page, the following error variables are available if or "exception". Error.Diagnostics Error.MailTo Error.DateTime Error.Browser Error.GeneratedContent Error.RemoteAddress Error.HTTPReferer Error.Template Error.QueryString The following error variables are available if type="validation". Error.ValidationHeader Error.InvalidFields Error.ValidationFooter Any cfcatch variable that applies to exception type can be accessed within the Error scope, as follows: Error.Type Error.Message Error.Detail Error.ErrNumber Error.NativeErrorCode Error.SQLState Error.LockName Error.LockOperation Error.MissingFileName Error.TagContext Error.ErrorCode Error.ExtendedInfo Note: You can substitute the prefix CFERROR for Error, if type = "Exception"; for example, CFERROR.Diagnostics, CFERROR.Mailto, or CFERROR.DateTime. ColdFusion tag-specific variables 13 CFFILE ACTION=Upload variables CFFILE.ClientDirectory. File variables are read-only. Use the CFFILE prefix to reference file variables; for example, The File prefix is deprecated in favor of the CFFILE prefix. 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 CFFTP error variables When you use the cfftp stoponerror attribute, these variables are populated: CFFTP.Succeeded CFFTP.ErrorCode CFFTP.ErrorText CFFTP ReturnValue variable Some cfftp file and directory operations provide a return value, in the variable CFFTP.ReturnValue. Its value is determined by the results of the action attribute. When you specify any of the following actions, cfftp returns a value: GetCurrentDir GetCurrentURL ExistsDir ExistsFile Exists CFFTP query object columns queryname When you use the cfftp tag with the listdir action, cfftp returns a query object, where is the name attribute value, and row is the row number of each file or directory entry: queryname.Name[row] queryname.Path[row] queryname.URL[row] queryname.Length[row] 14 Chapter 1: Reserved Words and Variables queryname.LastModified[row] queryname.Attributes queryname.IsDirectory queryname.Mode CFHTTP variables A cfhttp get operation can return text and binary files. Files are downloaded and the contents stored in a variable or file, depending on the MIME type, as follows: CFHTTP.FileContent CFHTTP.MimeType CFHTTP.Header CFHTTP.ResponseHeader[http_hd_key] CFHTTP.StatusCode CFLDAP variables The cfldap action=query tag returns information about the LDAP query, as follows: queryname.CurrentRow queryname.RecordCount queryname.ColumnList CFPOP variables The cfpop tag returns the following result columns, depending on the action attribute value and the use of other attributes, such as attachmentpath, where queryname is the name attribute value: queryname.Date queryname.From queryname.Body queryname.Header queryname.MessageNumber queryname.ReplyTo queryname.Subject queryname.CC queryname.To queryname.CurrentRow queryname.RecordCount queryname.ColumnList queryname.Attachments queryname.AttachmentFiles CFQUERY and CFSTOREDPROC variables The cfquery tag returns information about the query in this variable: CFQUERY.ExecutionTime The cfquery tag uses the query name to scope the following data about the query: queryname.CurrentRow queryname.RecordCount queryname.ColumnList ColdFusion tag-specific variables 15 The cfstoredproc tag returns the following variables: CFSTOREDPROC.ExecutionTime CFSTOREDPROC.StatusCode CFREGISTRY variables The cfregistry tag returns a query record set that you can reference after executing the GetAll action, as follows, where queryname is the name attribute value: queryname.Entry queryname.Type queryname.Value CFSEARCH variables A cfsearch operation returns the following variables, where searchname is the name attribute value: searchname.URL searchname.Key searchname.Title searchname.Score searchname.Custom1 and Custom2 searchname.Summary searchname.RecordCount searchname.CurrentRow searchname.RecordsSearched searchname.ColumnList Standard CGI variables The CGI variables that are available for your use vary with the web server and configuration. This section lists the CGI 1.1 variables that some web servers create when a CGI script is called. Some of the following variables may not be available. Request CGI.AUTH_TYPE CGI.CONTENT_LENGTH CGI.CONTENT_TYPE CGI.METHOD CGI.PATH_INFO CGI.PATH_TRANSLATED CGI.QUERY_STRING CGI.REMOTE_ADDR CGI.REMOTE_HOST CGI.REMOTE_USER CGI.REQUEST_METHOD CGI.SCRIPT_NAME 16 Chapter 1: Reserved Words and Variables Server CGI.GATEWAY_INTERFACE CGI.SERVER_NAME CGI.SERVER_PORT CGI.SERVER_PROTOCOL CGI.SERVER_SOFTWARE Client CGI.CERT_ISSUER CGI.CERT_SUBJECT CGI.CLIENT_CERT_ENCODED CGI.HTTP_ACCEPT CGI.HTTP_IF_MODIFIED_SINCE CGI.HTTP_USER_AGENT The CERT_ISSUER, CERT_SUBJECT, CLIENT_CERT_ENCODED variables are available only when you use client certificates. CGI environment variables When a browser makes a request to a server, the web server and the browser create environment variables. In ColdFusion, these variables are referred to as CGI environment variables. They take the CGI prefix regardless of whether the server uses a server API or CGI to communicate with the ColdFusion server. Environment variables contain data about the transaction between the browser and the server, such as the IP Address, browser type, and authenticated username. You can reference CGI environment variables for a given page request anywhere in the page. CGI variables are read-only. Note: The environment variables available to applications depend on the browser and server software. Testing for CGI variables Because some browsers do not support some CGI variables, ColdFusion always returns True when it tests for the existence of a CGI variable, regardless of whether the browser supports the variable. To determine if the CGI variable is available, test for an empty string, as shown in the following example: CGI variable exists CGI variable does not exist CGI environment variables 17 CGI server variables The following table describes common CGI environment variables that the server creates (some of these are not available with some servers): CGI server variable SERVER_SOFTWARE SERVER_NAME GATEWAY_INTERFACE SERVER_PROTOCOL SERVER_PORT REQUEST_METHOD PATH_INFO Description Name and version of the information server software answering the request (and running the gateway). Format: name/version. Server's hostname, DNS alias, or IP address as it appears in selfreferencing URLs. CGI specification revision with which this server complies. Format: CGI/revision. Name and revision of the information protocol this request came in with. Format: protocol/revision. Port number to which the request was sent. Method with which the request was made. For HTTP, this is Get, Head, Post, and so on. Extra path information, as given by the client. Scripts can be accessed by their virtual pathname, followed by extra information at the end of this path. The extra information is sent as PATH_INFO. Translated version of PATH_INFO after any virtual-to-physical mapping. Virtual path to the script that is executing; used for self-referencing URLs. Query information that follows the ? in the URL that referenced this script. Hostname making the request. If the server does not have this information, it sets REMOTE_ADDR and does not set REMOTE_HOST. IP address of the remote host making the request. If the server supports user authentication, and the script is protected, the protocol-specific authentication method used to validate the user. If the server supports user authentication, and the script is protected, the username the user has authenticated as. (Also available as AUTH_USER.) If the HTTP server supports RFC 931 identification, this variable is set to the remote username retrieved from the server. Use this variable for logging only. For queries that have attached information, such as HTTP POST and PUT, this is the content type of the data. Length of the content as given by the client. PATH_TRANSLATED SCRIPT_NAME QUERY_STRING REMOTE_HOST REMOTE_ADDR AUTH_TYPE REMOTE_USER AUTH_USER REMOTE_IDENT CONTENT_TYPE CONTENT_LENGTH 18 Chapter 1: Reserved Words and Variables CGI client variables The following table describes common CGI environment variables the browser creates and passes in the request header: CGI client variable HTTP_REFERER HTTP_USER_AGENT HTTP_IF_MODIFIED_SINCE Description The referring document that linked to or submitted form data. The browser that the client is currently using to send the request. Format: software/version library/version. The last time the page was modified. The browser determines whether to set this variable, usually in response to the server having sent the LAST_MODIFIED HTTP header. It can be used to take advantage of browser-side caching. CGI client certificate variables ColdFusion makes available the following client certificate data. These variables are available when running Microsoft IIS 4.0 or Netscape Enterprise under SSL if your web server is configured to accept client certificates. CGI client certificate variable Description CERT_SUBJECT Client-specific information provided by the web server. This data typically includes the client's name, e-mail address, and so on; for example: O = "VeriSign, Inc.", OU = VeriSign Trust Network, OU = "www.verisign.com/repository/RPA Incorp. by Ref.,LIAB.LTD(c)98", OU = Persona Not Validated, OU = Digital ID Class 1 - Microsoft, CN = Matthew Lund, E = mlund@macromedia.com CERT_ISSUER Information about the authority that provided the client certificate; for example: O = "VeriSign, Inc.", OU = VeriSign Trust Network, OU = "www.verisign.com/repository/RPA Incorp. By Ref.,LIAB.LTD(c)98", CN = VeriSign Class 1 CA Individual Subscriber-Persona Not Validated CLIENT_CERT_ENCODED The entire client certificate binary, base-64 encoded. This data is typically of interest to developers, so they can integrate with other software that uses client certificates. CGI environment variables 19 20 Chapter 1: Reserved Words and Variables