User Guide

Manuals Brands Macromedia Manuals Other COLDFUSION MX 61-CFML REFERENCE

CFML Reference

Summary of content (806 pages)

PAGE 1

CFML Reference
PAGE 2

Trademarks Afterburner, AppletAce, Attain, Attain Enterprise Learning System, Attain Essentials, Attain Objects for Dreamweaver, Authorware, Authorware Attain, Authorware Interactive Studio, Authorware Star, Authorware Synergy, Backstage, Backstage Designer, Backstage Desktop Studio, Backstage Enterprise Studio, Backstage Internet Studio, ColdFusion, Design in Motion, Director, Director Multimedia Studio, Doc Around the Clock, Dreamweaver, Dreamweaver Attain, Drumbeat, Drumbeat 2000, Extreme 3D, Fireworks,
PAGE 3

CONTENTS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 About Macromedia ColdFusion MX documentation . . . . . . . . . . . . . . . . . . . . . . 17 Documentation set . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 Viewing online documentation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18 INTRODUCTION CHAPTER 1: Reserved Words and Variables . . . . . . . . . . . . . . . . .
PAGE 4

CGI environment variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Testing for CGI variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . CGI server variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . CGI client variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . CGI client certificate variables . . . . . . . . . . . . . . . . . . . .
PAGE 5

cfexecute . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106 cfexit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108 cffile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110 cffile action = "append" . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
PAGE 6

cfloop: looping over a query . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 236 cfloop: looping over a list or file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 238 cfloop: looping over a COM collection or structure . . . . . . . . . . . . . . . . . . . . 239 cfmail . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 240 cfmailparam . . . . . . . . . . . . . . . . . . . . . . . . . . .
PAGE 7

cftreeitem . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . cftry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . cfupdate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . cfwddx . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . cfxml . . . . . . . . . . . . . .
PAGE 8

Asc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 395 ASin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 396 Atn . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 398 AuthenticatedContext . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 399 AuthenticatedUser. .
PAGE 9

Decrypt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 462 DeleteClientVariable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 463 DirectoryExists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 464 DollarFormat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 465 Duplicate . . . . . . . . . . .
PAGE 10

Insert. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 522 Int . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 523 IsArray. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 524 IsAuthenticated . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
PAGE 11

ListValueCount . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 590 ListValueCountNoCase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 592 LJustify . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 594 Log . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 595 Log10 . . . . . . . . . . . .
PAGE 12

Reverse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 668 Right . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 669 RJustify . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 670 Round . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 671 RTrim . . . .
PAGE 13

XmlFormat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . XmlNew . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . XmlParse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . XmlSearch. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . XmlTransform. . . . . . . . . . . . . . . .
PAGE 14

CHAPTER 5: ColdFusion Java CFX Reference . . . . . . . . . . . . . . . . . . . . . . . . . 769 Overview class libraries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 770 CustomTag interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 770 Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 770 processRequest . . . . . . . . . . . . . . . . . . . . . . . . .
PAGE 15

setField . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 796 wddxSerialize . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 797 CHAPTER 7: ColdFusion ActionScript Functions . . . . . . . . . . . . . . . . . . . . . . . . 799 CF.query . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 800 CF.http . . . . . . . . . . . . . . . . . . . . . . .
PAGE 16

Contents
PAGE 17

INTRODUCTION CFML Reference is your primary ColdFusion Markup Language (CFML) reference. Use this book to learn about CFML tags and functions, ColdFusion expressions, and using JavaScript objects for WDDX in Macromedia ColdFusion MX. 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.
PAGE 18

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.
PAGE 19

CHAPTER 1 Reserved Words and Variables This chapter provides information on ColdFusion reserved words and lists scope variables. Contents Reserved words . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20 Scope-specific built-in variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22 ColdFusion tag-specific variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
PAGE 20

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_.
PAGE 21

COLUMN COMMIT CONNECT CONNECTION CONSTRAINT CONSTRAINTS CONTINUE CONVERT CORRESPON DING COUNT CREATE CROSS CURRENT CURRENT_DATE CURRENT_TIME CURRENT_TIME STAMP CURRENT_USER CURSOR DATE DAY DEALLOCATE DEC DECIMAL DECLARE DEFAULT DEFERRABLE DEFERRED DELETE DESC DESCRIBE DESCRIPTOR DIAGNOSTICS DISCONNECT DISTINCT DOMAIN DOUBLE DROP ELSE END END-EXEC ESCAPE EXCEPT EXCEPTION EXEC EXECUTE EXISTS EXTERNAL EXTRACT FALSE FETCH FIRST FLOAT FOR FOREIGN FOUND FROM
PAGE 22

TIME TIMESTAMP TIMEZONE_ HOUR TIMEZONE_ MINUTE TO TRAILING TRANSACTION TRANSLATE TRANSLATION TRIM TRUE UNION UNIQUE UNKNOWN UPDATE UPPER USAGE USER USING VALUE VALUES VARCHAR VARYING VIEW WHEN WHENEVER WHERE WITH WORK WRITE YEAR ZONE 22 Chapter 1: Reserved Words and Variables
PAGE 23

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.
PAGE 24

To ensure that modifications to shared data occur in the intended sequence, use the cflock tag. For more information, see cflock on page 221. 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.
PAGE 25

cfhttp cfindex cfldap cfmail 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.
PAGE 26

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.
PAGE 27

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.
PAGE 28

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 The cfstoredproc tag returns the following variables: CFSTOREDPROC.ExecutionTime CFSTOREDPROC.
PAGE 29

Standard CGI variables This section lists the CGI 1.1 variables that some web servers create when a CGI script is called. The CGI variables that are available for your use vary with the web server and configuration. Some of the following variables may not be available. Request CGI.AUTH_TYPE CGI.CONTENT_LENGTH CGI.CONTENT_TYPE CGI.PATH_INFO CGI.PATH_TRANSLATED CGI.QUERY_STRING CGI.REMOTE_ADDR CGI.REMOTE_HOST CGI.REMOTE_USER CGI.REQUEST_METHOD CGI.SCRIPT_NAME Server CGI.GATEWAY_INTERFACE CGI.SERVER_NAME CGI.
PAGE 30

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:
PAGE 31

CGI server variable Description REMOTE_IDENT 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. CONTENT_TYPE For queries that have attached information, such as HTTP POST and PUT, this is the content type of the data. CONTENT_LENGTH Length of the content as given by the client.
PAGE 32

Chapter 1: Reserved Words and Variables
PAGE 33

CHAPTER 2 ColdFusion Tags ColdFusion Markup Language (CFML) includes a set of tags that you use in ColdFusion pages to interact with data sources, manipulate data, and display output. CFML tag syntax is similar to HTML element syntax. This chapter contains categorized and alphabetical lists of the tags followed by the detailed tag descriptions. Contents Tag summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
PAGE 34

Tag summary The following table briefly describes CFML tags: 34 CFML tag Category Description cfabort Flow-control tags Stops the processing of a ColdFusion page at the tag location cfapplet Forms tags Embeds Java applets in a cfform tag cfapplication Application framework tags Defines an application name; activates client variables; specifies client variable storage mechanism cfargument Extensibility tags Creates a parameter definition within a component definition; defines a function argum
PAGE 35

CFML tag Category Description cferror Exception handling tags, Displays custom HTML error pages when errors Application framework occur tags cfexecute Flow-control tags, Extensibility tags Executes developer-specified process on server computer cfexit Flow-control tags Aborts processing of executing CFML tag cffile File management tags Performs typical file-handling tasks from within ColdFusion application cfflush Data output tags, Page processing tags Flushes currently available data to cli
PAGE 36

CFML tag Category Description cfinvokeargument Extensibility tags Passes a parameter to a component method or a web service cfldap Forms tags, Internet Protocol tags Provides access to LDAP directory servers cflocation Flow-control tags Controls execution of a page cflock Application framework tags Ensures data integrity and synchronizes execution of CFML code cflog Data output tags, Other tags Writes a message to a log file cflogin Extensibility tags Defines a container for user login a
PAGE 37

CFML tag Category Description cfquery Database manipulation tags Passes SQL statements to a database cfqueryparam Database manipulation tags Checks data type of a query parameter cfregistry Other tags, Variable manipulation tags Reads, writes, and deletes keys and values in a Windows system registry cfreport Exception handling tags Embeds a Crystal Reports report cfrethrow Exception handling tags Rethrows currently active exception cfreturn Extensibility tags Returns results from a compone
PAGE 38

CFML tag Category Description cftreeitem Forms tags Populates a tree control element in a form; used with cftree cftry Exception handling tags, Catches exceptions in ColdFusion pages Flow-control tags cfupdate Database manipulation tags Updates rows in a database data source cfwddx Extensibility tags Serializes and de-serializes CFML data structures to XML-based WDDX format cfxml Extensibility tags Creates an XML document object Chapter 2: ColdFusion Tags
PAGE 39

Tags by function The following tables list Tags by their function or purpose. Application framework tags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39 Database manipulation tags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39 Data output tags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39 Debugging tags . . . . . . . . .
PAGE 40

Exception handling tags cfcatch cfrethrow cferror cfthrow cftry Extensibility tags cfchart cffunction cfobject cfchartdata cfindex cfproperty cfchartseries cfinvoke cfreport cfcollection cfinvokeargument cfreturn cfcomponent cflogin cfsearch cfexecute cfloginuser cfwddx cfftp cflogout cfxml cffile cfftp File management tags cfdirectory Flow-control tags cfabort cfexecute cfrethrow cfbreak cfexit cfswitch cfcase cfif cfthrow cfdefaultcase cfinclude cftry cfelse cfloc
PAGE 41

Internet Protocol tags cfftp cfldap cfmailpart cfhttp cfmail cfpop cfhttpparam cfmailparam Page processing tags cfcache cfheader cfsetting cfcontent cfhtmlhead cfsilent cfflush cfinclude Variable manipulation tags cfcookie cfregistry cfset cfdump cfsavecontent cfsetting cfparam cfschedule Other tags cflog cfregistry Tags by function 41
PAGE 42

Tag changes since ColdFusion 5 The following tables list Tags, attributes, and values that have changed since ColdFusion 5.0 and indicate the specific release in which the change was made. New tags, attributes, and values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42 Deprecated tags, attributes, and values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44 Obsolete tags, attributes, and values . . . . . . . . . . . .
PAGE 43

Tag Attribute or value Added in this ColdFusion release cfimport All ColdFusion MX cfinvoke All ColdFusion MX cfinvokeargument All ColdFusion MX cflogin All ColdFusion MX cfloginuser All ColdFusion MX cflogout All ColdFusion MX cfmail spoolEnable attribute ColdFusion MX charset attribute ColdFusion MX 6.1 failto attribute ColdFusion MX 6.1 replyTo attribute ColdFusion MX 6.1 userName attribute ColdFusion MX 6.1 password attribute ColdFusion MX 6.
PAGE 44

Deprecated tags, attributes, and values The following tags, attributes, and attribute values are deprecated. Do not use them in ColdFusion applications. They might not work, and might cause an error, in releases later than ColdFusion MX.
PAGE 45

Tag Attribute or value Deprecated as of this ColdFusion release cfquery connectString attribute ColdFusion MX dbName attribute ColdFusion MX dbServer attribute ColdFusion MX The following dbType attribute values: • dynamic • ODBC • Oracle73 • Oracle80 • Sybase11 • OLEDB • DB2 ColdFusion MX (The value query is valid.
PAGE 46

Obsolete tags, attributes, and values The following tags, attributes, and attribute values are obsolete. Do not use them in ColdFusion applications. They do not work, and might cause an error, in releases later than ColdFusion 5. Tag Attribute or value Obsolete as of this ColdFusion release cfauthenticate All ColdFusion MX cfimpersonate All ColdFusion MX cfindex action attribute value optimize ColdFusion MX cfinternaladminsecurity All ColdFusion MX This tag did not appear in CFML Reference.
PAGE 47

cfabort Description Stops the processing of a ColdFusion page at the tag location. ColdFusion returns everything that was processed before the tag. The tag is often used with conditional logic to stop processing a page when a condition occurs.
PAGE 48

The value of myVariable after incrementing through the loop #counter# times is: #my
PAGE 49

cfapplet Description This tag references a registered custom Java applet. To register a Java applet, in the ColdFusion Administrator, click Extensions > Java Applets. Using this tag within a cfform tag is optional. If you use it within cfform, and the method attribute is defined in the Administrator, the return value is incorporated into the form.
PAGE 50

Attribute Req/Opt Default Description align Optional Alignment: • Left • Right • Bottom • Top • TextTop • Middle • AbsMiddle • Baseline • AbsBottom notSupported Optional param_n See Text to display if a page that contains a Java applet-based Description cfform control is opened by a browser that does not support Java or has Java support disabled.
PAGE 51

cfapplication Description Defines the scope of a ColdFusion application; enables and disables storage of Client variables; specifies the Client variable storage mechanism; enables Session variables; and sets Application variable timeouts.
PAGE 52

Attribute Req/Opt Default Description clientStorage Optional registry How client variables are stored: • datasource_name: in ODBC or native data source. You must create storage repository in the Administrator. • registry: in the system registry. • cookie: on client computer in a cookie. Scalable. If client disables cookies in the browser, client variables do not work.
PAGE 53

If you use this tag to activate the Application and Client scopes, ColdFusion saves the application name as a key, whose maximum length is 64 characters. If an application name is longer than this, the client store fails during database processing. Note: The CFTOKEN variable is 8 bytes in length. Its range is 10000000 —99999999.If you specify ClientStorage=cookie, any Client scope variables set following a cfflush tag are not saved in the Client browser.
PAGE 54

cfargument Description Creates a parameter definition within a component definition. Defines a function argument. Used within a cffunction tag.
PAGE 55

Attribute Req/Opt Default Description required Optional Whether the parameter is required to execute the component method. • yes (the parameter is not required if you specify a default attribute.) • no default Optional displayname Optional hint Optional no If no argument is passed, specifies a default argument value. name attribute value Meaningful only for CFC method parameters. A value to be displayed when using introspection to show information about the CFC.
PAGE 56

cfassociate Description Allows subtag data to be saved with a base tag. Applies only to custom tags.
PAGE 57

cfauthenticate Description This tag is obsolete. Use the newer security tools; see “Authentication functions” on page 367 and Chapter 16, “Securing Applications,” in Developing ColdFusion MX Applications. History ColdFusion MX: this tag is obsolete. It does not work in ColdFusion MX and later releases.
PAGE 58

cfbreak Description Used within a cfloop tag. Breaks out of a loop. Category Flow-control tags Syntax See also cfabort, cfexecute, cfif, cflocation, cfloop, cfswitch, cfthrow, cftry Example
PAGE 59

cfcache Description Stores a copy of a page on the server and/or client computer, to improve page rendering performance. To do this, the tag creates temporary files that contain the static HTML returned from a ColdFusion page. Use this tag if it is not necessary to get dynamic content each time a user accesses a page. You can use this tag for simple URLs and for URLs that contain URL parameters.
PAGE 60

Attributes Attribute Req/Opt Default Description action Optional cache • cache: server-side and client-side caching. • flush: refresh cached page(s). • clientcache: browser-side caching only. To cache a personalized page, use this option. • servercache: server-side caching only. Not recommended. • optimal: same as "cache". directory Optional cf_root/cache Absolute path of cache directory. timespan Optional Page is The interval until the page is flushed from the cache.
PAGE 61

You can specify client-side caching or a combination of client-side and server-side caching (the default), using the action attribute. The advantage of client-side caching is that it requires no ColdFusion resources; the browser stores pages in its own cache, improving performance. The advantage of combination caching is that it optimizes server performance; if the browser does not have a cache of the page, the server can get data from its own cache.
PAGE 62

cfcase Description Used only inside the cfswitch tag body. Contains code to execute when the expression specified in the cfswitch tag has one or more specific values. Category Flow-control tags Syntax See also cfdefaultcase, cfswitch Attributes Attribute Req/Opt value Required delimiter Optional Default Description The value or values that the expression attribute of the cfswitch tag must match.
PAGE 63

Your grade is #grade# cfcase 63
PAGE 64

cfcatch Description Used inside a cftry tag. Together, they catch and process exceptions in ColdFusion pages. Exceptions are events that disrupt the normal flow of instructions in a ColdFusion page, such as failed database operations, missing include files, and developer-specified events.
PAGE 65

Attributes Attribute Req/Opt Default Description type Any application: catches application exceptions database: catches database exceptions template: catches ColdFusion page exceptions security: catches security exceptions object: catches object exceptions missingInclude: catches missing include file exceptions expression: catches expression exceptions lock: catches lock exceptions custom_type: catches the specified custom exception type that is defined in a cfthrow tag • searchengine: catches Verity s
PAGE 66

The cfinclude, cfmodule, and cferror tags throw an exception of type = "template". An exception that is thrown within a cfcatch block cannot be handled by the cftry block that immediately encloses the cfcatch tag. However, you can rethrow the currently active exception with the cfrethrow tag. The cfcatch variables provide the following exception information: 66 cfcatch variable Content cfcatch.type Type: Exception type, as specified in cfcatch. cfcatch.
PAGE 67

Advanced Exception types You can specify the following advanced exception types in the type attribute: ColdFusion advanced exception type COM.Allaire.ColdFusion.CFEXECUTE.OutputError COM.Allaire.ColdFusion.CFEXECUTE.Timeout COM.Allaire.ColdFusion.FileException COM.Allaire.ColdFusion.HTTPAccepted COM.Allaire.ColdFusion.HTTPAuthFailure COM.Allaire.ColdFusion.HTTPBadGateway COM.Allaire.ColdFusion.HTTPBadRequest COM.Allaire.ColdFusion.HTTPCFHTTPRequestEntityTooLarge COM.Allaire.ColdFusion.
PAGE 68

ColdFusion advanced exception type COM.Allaire.ColdFusion.HTTPNotModified COM.Allaire.ColdFusion.HTTPPartialContent COM.Allaire.ColdFusion.HTTPPaymentRequired COM.Allaire.ColdFusion.HTTPPreconditionFailed COM.Allaire.ColdFusion.HTTPProxyAuthenticationRequired COM.Allaire.ColdFusion.HTTPRequestURITooLarge COM.Allaire.ColdFusion.HTTPResetContent COM.Allaire.ColdFusion.HTTPSeeOther COM.Allaire.ColdFusion.HTTPServerError COM.Allaire.ColdFusion.HTTPServiceUnavailable COM.Allaire.ColdFusion.
PAGE 69

The contents of the tag stack are:
PAGE 70

cfchart Description Generates and displays a chart.
PAGE 71

Attributes Attribute Req/Opt Default Description format flash File format in which to save graph. • flash • jpg • png chartHeight 240 Chart height; integer number of pixels chartWidth 320 Chart width; integer number of pixels scaleFrom Determined by Y-axis minimum value; integer.
PAGE 72

Attribute 72 Req/Opt Default Description fontSize 11 Font size; integer fontBold no • yes • no fontItalic no • Yes • No labelFormat number Format for Y-axis labels. • number • currency • percent • date xAxisTitle text; X-axis title yAxisTitle text; Y-axis title xAxisType category • category The axis indicates the data category. Data is sorted according to the sortXAxis attribute. • scale The axis is numeric. All cfchartdata item attribute values must numeric.
PAGE 73

Attribute Req/Opt Default Description tipStyle mouseOver Determines the action that opens a popup window to display information about the current chart element. • mouseDown: displays if the user positions the cursor at the element and clicks the mouse down. Applies only to Flash format graph file. (For other formats, this option functions the same as mouseOver.
PAGE 74

Data is passed to the cfchartseries tag in the following ways: • As a query • As data points, using the cfchartdata tag For the font attribute value "ArialUnicodeMS", the following rules apply: • On Windows: to permit Flash charts (type = "flash") to render double-byte character set, you must select this value • On UNIX: for all type values, to render a double-byte character set, you must select this value.
PAGE 75

cfchartdata Description Used with the cfchart and cfchartseries tags. This tag defines chart data points. Its data is submitted to the cfchartseries tag. Category Data output tags, Extensibility tags Syntax See also cfchart, cfchartseries History ColdFusion MX: Added this tag.
PAGE 76

cfchartseries Description Used with the cfchart tag. This tag defines the style in which chart data displays: bar, line, pie, and so on. Category Data output tags, Extensibility tags Syntax See also cfchart, cfchartdata History ColdFusion MX 6.
PAGE 77

Attribute Req/Opt Default Description seriesLabel Optional Text of data series label seriesColor Optional Color of the main element (such as the bars) of a chart. For a pie chart, the color of the first slice. Hex value or supported named color; see name list in the cfchart Usage section. For a hex value, use the form "##xxxxxx", where x = 0-9 or A-F; use two pound signs or none. paintStyle Optional plain Sets the paint display style of the data series.
PAGE 78

cfcol Description Defines table column header, width, alignment, and text. Used within a cftable tag. Category Data output tags Syntax See also cfcontent, cfoutput, cftable History ColdFusion MX: Added the ability to construct dynamic cfcol statements. Attribute Req/Opt header Required Default Description Column header text.
PAGE 79

FROM Employees
cfcol Example
PAGE 80

cfcollection Description Creates, registers, and administers Verity search engine collections. A collection that is created with the cfcollection tag is internal. A collection created any other way is external. A collection that is registered with ColdFusion using the cfcollection tag or registered with the K2 Server by editing the k2server.ini file is registered. Other collections are unregistered.
PAGE 81

Attributes Attribute Req/Opt Default Description action list • create: registers the collection with ColdFusion. - If the collection is present: creates a map to it - If the collection is not present: creates it • repair: fixes data corruption in a collection. • delete: unregisters a collection. - If the collection was registered with action = create: deletes its directories - If the collection was registered and mapped: does not delete collection directories • map: creates a map to the collection.
PAGE 82

Before you attempt to delete or purge a collection that is also opened by the K2Server, you must stop the K2Server. If you do not, some files may be open, and ColdFusion might not complete the action.
PAGE 83

With the European Verity Locales language pack installed, the language attribute of this tag supports the following options: bokmal french norweg danish german portug dutch italian portuguese english nynorsk spanish finnish norwegian swedish With the Asian Verity Locales language pack installed, the language attribute of this tag supports the following options: arabic hungarian russian czech japanese simplified_chinese greek korean traditional_chinese hebrew polish turkish The def
PAGE 84

Collection optimized.

Collection deleted.
PAGE 85

cfcomponent Description Creates and defines a component object; encloses functionality that you build in CFML and enclose within cffunction tags. This tag contains one or more cffunction tags that define methods. Code within the body of this tag, other than cffunction tags, is executed when the component is instantiated. A component file has the extension CFC and is stored in any directory of an application.
PAGE 86

Attributes Attribute Req/Opt extends Optional output Optional displayname Optional hint Default Description Name of parent component from which to inherit methods and properties. Component body displayable text is processed as standard CFML Specifies whether constructor code in the component can generate HTML output; does not affect output in the body of cffunction tags in the component. • yes: Constructor code is processed as if it were within a cfoutput tag.
PAGE 87

cfcontent Description Does either or both of the following: • Sets the MIME content encoding header for the current page • Sends the contents of a file from the server as the page output Note: This tag executes only if it is enabled in the ColdFusion Administrator. For more information, see Configuring and Administering ColdFusion MX.
PAGE 88

Attributes 88 Attribute Req/Opt type Optional deleteFile Optional file Optional reset Optional Default Description The MIME content type of the page, optionally followed by a semicolon and the character encoding. By default, ColdFusion sends pages as text/html content type in the UTF-8 character encoding. The content type determines how the browser or client interprets the page contents.
PAGE 89

Usage To set the character encoding (character set) of generated output, use code such as the following: When ColdFusion processes an HTTP request, it determines the character encoding of the data returned in the HTTP response. By default, ColdFusion returns character data using the Unicode UTF-8 format (regardless of the value of an HTML meta tag in the page). You can use the cfcontent tag to override the default character encoding of the response.
PAGE 90

cfcontent Example 2

This example shows how reset
reset = "Yes ": 123 This example shows how reset
reset = "No ": 123 reset = "Yes ">456
attribute changes output for text.
PAGE 91

cfcookie Description Defines web browser cookie variables, including expiration and security options. Category Forms tags, Variable manipulation tags Syntax See also cfdump, cfparam, cfregistry, cfsavecontent, cfschedule, cfset History ColdFusion MX 6.1: • Changed the expires attribute: it now accepts a date time object.
PAGE 92

Attribute Req/Opt path domain Default Description Optional URL, within a domain, to which the cookie applies; typically a directory. Only pages in this path can use the cookie. By default, all pages on the server that set the cookie can access the cookie. path = "/services/login" To specify multiple URLs, use multiple cfcookie tags. If you specify path, you must also specify domain. Required if Domain in which cookie is valid and to which cookie content can be sent from the user’s system.
PAGE 93
PAGE 94

cfdefaultcase Description Used only inside the cfswitch tag body. Contains code to execute when the expression specified in the cfswitch tag does not match a of the value specified by a cfcase tag. Category Flow-control tags Syntax See also cfcase, cfswitch History ColdFusion MX: Changed placement requirements: this tag does not have to follow all cfcase tags in the cfswitch tag body.
PAGE 95

cfdirectory Description Manages interactions with directories. Category File management tags Syntax See also cffile History ColdFusion MX: • Changed behavior for action ■ ■ ■ = "list": On Windows, cfdirectory action = "list" no longer returns the directory entries "." (dot) or "..
PAGE 96

Attribute Req/Opt mode Optional sort Optional; used if action = Default Description Used with action = "create". Permissions. Applies only to UNIX and Linux. Octal values of chmod command. Assigned to owner, group, and other, respectively. For example: • 644: Assigns read/write permission to owner; read permission to group and other • 777: Assigns read/write/execute permission to all ASC "list" newDirectory Required if Query column(s) by which to sort directory listing.
PAGE 97

Note: If the cfdirectory tag does not appear to work, for example, if a list operation returns an empty result set, make sure that you have correct permissions to access the directory. For example, if you run ColdFusion as a service on Windows, it operates by default as System, and cannot access directories on a remote system or mapped drive; to resolve this issue, do not run ColdFusion using the local system account. The filter attribute specifies a pattern of one or more characters.
PAGE 98

cfdump Description Outputs the elements, variables and values of most kinds of ColdFusion objects. Useful for debugging. You can display the contents of simple and complex variables, objects, components, user-defined functions, and other elements. Category Debugging tags, Variable manipulation tags Syntax See also cfcookie, cfparam, cfsavecontent, cfschedule, cfset, cfwddx History ColdFusion MX 6.
PAGE 99

If a table cell is empty, this tag displays "[empty string]". Example This example shows how to use this tag to display a URL variable. URL variables contain parameters that are passed in a URL string in a page request.
PAGE 100

cfelse Description Used as the last control block in a cfif tag block to handle any case not identified by the cfif tag or a cfelseif tag.
PAGE 101

cfelseif Description Used as a control block in a cfif tag block to handle any case not identified by the cfif tag or a cfelseif tag.
PAGE 102

cferror Description Displays a custom HTML page when an error occurs. This lets you maintain a consistent look and feel among an application’s functional and error pages. Category Exception handling tags, Extensibility tags, Application framework tags Syntax See also cfrethrow, cfthrow, cftry History ColdFusion MX: Deprecated the monitor option of the exception attribute.
PAGE 103

Usage Use this tag to provide custom error messages for pages in an application. You generally embed this tag in the Application.cfm file. For more information, see Chapter 14, “Handling Errors,” in Developing ColdFusion MX Applications. To ensure that error pages display successfully, avoid using the cfencode tag to encode pages that include the cferror tag. Page Types The following table describes the types of errors you can specify and code you can use on the pages that handle these error type.
PAGE 104

Page type Error variable Description Request and Exception error.diagnostics Detailed error diagnostics from ColdFusion MX. error.mailTo E-mail address (same as value in cferror.MailTo). error.dateTime Date and time when error occurred. error.browser Browser that was running when error occurred. error.remoteAddress IP address of remote client. error.HTTPReferer Page from which client accessed link to page where error occurred. error.template Page executing when error occurred. error.

PAGE 105

We’re sorry -- An Error Occurred

If you continue to have this problem, please contact #error.mailTo# with the following information:

Your Location: #error.remoteAddress#
Your Browser: #error.browser#
Date and Time the Error Occurred: #error.dateTime#
Page You Came From: #error.HTTPReferer#
Message Content:
#error.
PAGE 106

cfexecute Description Executes a ColdFusion developer-specified process on a server computer. Category Extensibility tags, Flow-control tags Syntax ... See also cfcollection, cfindex, cfobject, cfreport, cfsearch, cfwddx History ColdFusion MX 6.1: • Added the variable attribute.
PAGE 107

Attribute Req/Opt variable Optional Default Description Variable in which to put program output. If no outputfile or variable attribute is specified, output is displayed on page from which it was called. timeout Optional 0 Length of time, in seconds, that ColdFusion waits for output from the spawned program. • 0: equivalent to non-blocking mode. • A very high value: equivalent to blocking mode If the value is 0: • ColdFusion starts a process and returns immediately.
PAGE 108

cfexit Description This tag aborts processing of the currently executing CFML custom tag, exits the page within the currently executing CFML custom tag, or re-executes a section of code within the currently executing CFML custom tag.
PAGE 109

cfexit is used primarily to perform a conditional stop of processing inside a custom tag. cfexit returns control to the page that called that custom tag, or in the case of a tag called by another tag, to the calling tag. PAGE 113
cffile action = "append" Description Appends text to a text file on the server. Syntax See also cfdirectory History See the History section of the main cffile tag page. Attributes Attribute Req/Opt action Required Type of file manipulation that the tag performs.
PAGE 114

Attribute Req/Opt attributes Optional charset Optional Default Description Applies to Windows. A comma-delimited list of attributes to set on the file. If omitted, the file's attributes are maintained. Each value must be specified explicitly. For example, if you specify attributes = "readOnly", all other attributes are overwritten. • readOnly • hidden • normal JVM default file character set. The character encoding in which the file contents is encoded.
PAGE 115

cffile action = "copy" Description Copies a file from one directory to another on the server. Syntax See also cfdirectory History See the History section of the main cffile tag page. Attributes Attribute Req/Opt Default Description action Required Type of file manipulation that the tag performs. source Required Pathname of the file to copy.
PAGE 116

cffile action = "delete" Description Deletes a file on the server. Syntax See also cfdirectory Attributes Attribute Req/Opt Default Description action Required Type of file manipulation that the tag performs. file Required Pathname of the file to delete.
PAGE 117

cffile action = "move" Description Moves a file from one location to another on the server. Syntax See also cfdirectory History See the History section of the main cffile tag page. Attributes Attribute Req/Opt Default Description action Required Type of file manipulation that the tag performs. source Required Pathname of the file to move.
PAGE 118

Attribute Req/Opt attributes Optional charset Optional Default Description Applies to Windows. A comma-delimited list of attributes to set on the file. If omitted, the file's attributes are maintained. Each value must be specified explicitly. For example, if you specify attributes = "readOnly", all other attributes are overwritten. • readOnly • hidden • normal JVM default file character set. The character encoding in which the file contents is encoded.
PAGE 119

cffile action = "read" Description Reads a text file on the server. The file is read into a dynamic, local variable that you can use in the page. For example: • Read a text file; insert the file’s contents into a database • Read a text file; use the find and replace function to modify the file’s contents Note: This action reads the file into a variable in the local Variables scope. It is not intended for use with large files, such as logs, because this can bring down the server.
PAGE 120

Usage The following example creates a variable named Message for the contents of the file message.txt: The variable Message can be used in the page. For example, you could display the contents of the message.txt file in the final web page as follows: #Message# ColdFusion supports functions for manipulating the contents of text files.
PAGE 121

cffile action = "readBinary" Description Reads a binary file (such as an executable or image file) on the serve, into a binary object parameter that you can use in the page. To send it through a web protocol (such as HTTP or SMTP) or store it in a database, first convert it to Base64 using the ToBase64 function. Note: This action reads the file into a variable in the local Variables scope. It is not intended for use with large files, such as logs, because they can bring down the server.
PAGE 122

cffile action = "rename" Description Renames or moves a file on the server. Syntax See also cfdirectory History See the History section of the main cffile tag page. Attributes Attribute Req/Opt Default Description action Required Type of file manipulation that the tag performs. source Required Pathname of file to rename.
PAGE 123

PAGE 124
cffile action = "upload" Description Copies a file to a directory on the server. Syntax See also cfdirectory History See the History section of the main cffile tag page. Attributes Attribute Req/Opt action Required Type of file manipulation that the tag performs.
PAGE 125

Attribute Req/Opt Default Description mode Optional Applies only to UNIX and Linux. Permissions. Octal values of chmod command. Assigned to owner, group, and other, respectively. For example: • 644: Assigns read/write permission to owner; read permission to group and other • 777: Assigns read/write/execute permission to all attributes Optional Applies to Windows. A comma-delimited list of attributes to set on the file. If omitted, the file's attributes are maintained.
PAGE 126

Parameter Description fileWasSaved Whether ColdFusion saves a file (Yes or No) oldFileSize Size of a file that was overwritten in the file upload operation serverDirectory Directory of the file saved on the server serverFile Filename of the file saved on the server serverFileExt Extension of the uploaded file on the server (without a period) serverFileName Name of the uploaded file on the server (without an extension) timeCreated Time the uploaded file was created timeLastModified Date and
PAGE 127

cffile action = "write" Description Writes a text file on the server, based on dynamic content. You can create static HTML files from the content, or log actions in a text file. Syntax See also cfdirectory History See the History section of the main cffile tag page.
PAGE 128

Attribute Req/Opt attributes Optional charset Optional Default Description Applies to Windows. A comma-delimited list of attributes to set on the file. If omitted, the file's attributes are maintained. Each value must be specified explicitly. For example, if you specify attributes = "readOnly", all other attributes are overwritten. • readOnly • hidden • normal JVM default file character set. The character encoding in which the file contents is encoded.
PAGE 129

This example uploads a file and gives it the permissions owner/group/other = read/write/execute): cffile action = "upload" fileField = "fieldname" destination = "/tmp/program.
PAGE 130

cfflush Description Flushes currently available data to the client. Category Data output tags, Page processing tags Syntax See also cfcache, cfheader, cfinclude, cfsetting, cfsilent Attributes Attribute Req/Opt interval Optional Default Description Integer. Flushes output each time this number of bytes becomes available. HTML headers, and data that is already available when the tag is executed, are omitted from the count.
PAGE 131

It will take us a little while to calculate your ten magic numbers. It takes a lot of work to find numbers that truly fit your personality. So relax for a minute or so while we do the hard work for you.
PAGE 132

cfform Description Builds a form with CFML custom control tags; these provide more functionality than standard HTML form input elements. Category Forms tags Syntax ...
PAGE 133

Attribute Req/Opt preserveData Optional Default Description No When the cfform action attribute posts back to the same page as the form, this determines whether to override the control values with the submitted values. • false: values specified in the control tag attributes are used • true: corresponding submitted values are used Applies to these controls: • cfform controls cfinput, cfslider, cftextinput; overrides value attribute value • cfselect controls that are populated from queries.
PAGE 134

Usage This tag requires an end tag. Some custom control tags that you can use within this tag require the client to download a Java applet; they might execute slightly more slowly than using an HTML form element to get the same information.
PAGE 135

• HTML tags that can ordinarily be put within the HTML form tag. For example, you can use the HTML input tag to create a submit button in a cfform, without the other features of cfinput: Example
cfform Example

Results of Radio Button Test
Your radio button answer was yes
PAGE 136

This example shows the use of the cfslider tag.

Rate your approval of this example from 1 to 10 by sliding control.
PAGE 137

cfftp Description Lets users implement File Transfer Protocol (FTP) operations. Category File management tags, Internet Protocol tags Syntax The tag syntax depends on the action attribute value. See the following sections: • “cfftp: Opening and closing FTP server connections” on page 138 • “cfftp: Connection: File and directory operations” on page 141 • “cfftp action = "listDir"” on page 145 See also cfhttp, cfldap, cfmail, cfpop History ColdFusion MX: Deprecated the agentname attribute.
PAGE 138

cfftp: Opening and closing FTP server connections Description To establish a connection with an FTP server, you use the open action with a connection attribute.
PAGE 139

Attribute Req/Opt Default Description stopOnError Optional No • Yes: halts processing, displays an appropriate error. • No: populates these variables: - cfftp.succeeded – Yes or No. - cfftp.errorCode – Error number. See the IETF Network Working Group RFC 959: File Transfer Protocol (FTP) www.ietf.org/rfc/rfc0959.txt. - cfftp.errorText – Message text For conditional operations, use cfftp.errorCode. Do not use cfftp.errorText for this purpose.
PAGE 140

stopOnError = "Yes" name = "ListFiles" directory = "/" connection = "my_query"> #name#

Close the connection:
Did it succeed? #cfftp.
PAGE 141

cfftp: Connection: File and directory operations Description Use this form of the cfftp tag to perform file and directory operations with cfftp.
PAGE 142

Attribute Req/Opt Default Description ASCIIExtension Optional List txt;htm;html; Delimited list of file extensions that force ASCII transfer mode, if transferMode = "auto".
PAGE 143

The cfftp.returnValue variable provides the return value for these actions: • • • • • getCurrentDir getCurrentURL existsDir existsFile exists For more information, see Developing ColdFusion MX Applications. Caution: Object (file and directory) names are case-sensitive. Action (cfftp.ReturnValue variable) The results of an action determine the value of the cfftp.returnValue variable. cfftp action Value of cfftp.returnValue getCurrentDir String. Current directory. getCurrentURL String. Current URL.
PAGE 144

action = "close" stopOnError = "Yes">
Did it succeed? #cfftp.
PAGE 145

cfftp action = "listDir" Description To access the columns in a query object, use this tag with action = "listDir". Usage When you use this action, you must specify a value for the name attribute. This value holds the results of the listDir action in a query object. The query object consists of columns that you can reference, in the form queryname.columname[row], where queryname is the name of the query, specified in the name attribute; and columnname is a column returned in the query object.
PAGE 146

cffunction Description Defines a function that you can call in CFML. Required to defined ColdFusion component methods.
PAGE 147

Attribute Req/Opt Default Description roles Optional "" (empty) A comma-delimited list of ColdFusion security roles that can invoke the method. Only users who are logged in with the specified roles can execute the function. If this attribute is omitted, all users can invoke the method.
PAGE 148

access="remote" returnType="query" hint="This query returns all records in the employee database. It can drill-down or narrow the search, based on optional input parameters."> For information on using the cffunction tag for ColdFusion components, see Chapter 11, “Building and Using ColdFusion Components,” in Developing ColdFusion MX Applications. If you specify a roles attribute, the function executes only if a user is logged in and belongs to one of the specified roles.
PAGE 149

cfgraph Description This tag is deprecated. Use the cfchart, cfchartdata, and cfchartseries tags instead. Displays data graphically. History ColdFusion MX: Deprecated this tag. It works differently than it did in ColdFusion 5, and it might not work in later releases.
PAGE 150

cfgraph tag attribute ColdFusion MX functionality Showvaluelabel • yes: displays values on mouse-click; • no: suppresses value displays • rollover: displays values on mouse-over. Valuelocation Ignored url URL of page to open if any item in the graph is clicked.
PAGE 151

cfgraphdata Description This tag is deprecated. Use the cfchart, cfchartdata, and cfchartseries tags instead. Displays a data point in a graph. Used within the cfgraph tag. History ColdFusion MX: Deprecated this tag. It works differently than in ColdFusion 5 and might not work in later releases.
PAGE 152

cfgrid Description Used within the cfform tag. Puts a grid control (a table of data) in a ColdFusion form. To specify grid columns and row data, use the cfgridcolumn and cfgridrow tags, or use the query attribute, with or without cfgridcolumn tags.
PAGE 153

deleteButton = "text" sortAscendingButton = "text" sortDescendingButton = "text"> See also cfgridcolumn, cfgridrow, cfgridupdate, cfapplet, cfform, cfinput, cfselect, cfslider, cftextinput, cftree, cftreeitem History ColdFusion MX: Changed the rowHeaderWidth attribute: ColdFusion does not use the rowHeaderWidth attribute. You can omit it. Attributes Attribute Req/Opt Default Description name Required height Optional 300 Height of grid control, in pixels.
PAGE 154

Attribute Req/Opt Default Description sort Optional No The sort button performs simple text sort on column. User can sort columns by clicking column head or by clicking sort buttons. Not valid with selectmode=browse. • Yes: sort buttons display on grid control • No font Optional Font of column data in the grid control. fontSize Optional Size of text in the grid control, in points.
PAGE 155

Attribute Req/Opt Default Description rowHeight Optional rowHeaders Optional Yes • Yes: displays a column of numeric row labels in grid control • No rowHeaderAlign Optional Left • Left: left-aligns data within row header • Right: right-aligns data within row header • Center: center-aligns data within row header rowHeaderFont Optional Row label font. rowHeaderFontSize Optional Row label text size in grid control, in points.
PAGE 156

Attribute Req/Opt Default Description selectMode Optional Browse Selection mode for items in grid control. • Edit: user can edit grid data. Selecting a cell opens the editor for the cell type. • Single: user selections are limited to selected cell. • Row: user selections automatically extend to the row that contains selected cell. • Column: user selections automatically extend to column that contains selected cell.
PAGE 157

Simple selection data (SelectMode = Single, Column, or Row) The data that form variables return to the cfform's action page contains information about which cells the user selected. In general, ColdFusion makes this data available in the action page, as ColdFusion variables in the Form scope, with the naming convention form.#GridName#.#ColumnName# Each SelectMode returns these form variable(s): • SelectMode="single" form.#GridName#.#ColumnName# = "SelectedCellValue" • SelectMode="column" form.
PAGE 158

Loop Index Action Old Value New Value

#LoopCount# #Val_Action# #Val_Orig# #Val_New#

form.#GridName#.
PAGE 159

SELECT Course_ID, Dept_ID, CorNumber, CorName, CorLevel, CorDesc FROM CourseList ORDER by Dept_ID ASC, CorNumber ASC cfgrid Example
cfgrid Example
Try adding a course to the database, and then deleting it.

PAGE 160

...

PAGE 161

cfgridcolumn Description Used with the cfgrid tag in a cfform. Use this tag to specify column data in a cfgrid control. The font and alignment attributes used in cfgridcolumn override global font or alignment settings defined in cfgrid.

PAGE 162

Attribute Req/Opt Default Description width Optional; see Description Column head Column width, in pixels. width font Optional As specified by cfgrid Font of data in column. fontSize Optional As specified by cfgrid Size of text in column.

PAGE 163

Attribute Req/Opt Default Description select Optional display Optional type Optional headerFont Optional as specified by cfgrid Column header font headerFontSize Optional as specified by cfgrid Column header text size, in pixels headerItalic Optional as specified by cfgrid • Yes: displays column header in italics • No headerBold Optional as specified by cfgrid • Yes: displays header in bold • No • Yes: user can select the column in grid control.

PAGE 164

Attribute Req/Opt values Optional Default Description Formats cells in column as drop-down list boxes; specify items in drop-down list. Example: values = "arthur, scott, charles, 1-20, mabel" valuesDisplay Optional valuesDelimiter Optional Maps elements in values attribute to string to display in drop-down list. Delimited strings and/or numeric range(s). , [comma] Delimiter in values and valuesDisplay attributes.

PAGE 165

numberFormat mask characters You can use the following numberFormat attribute mask characters, which correspond to those in the NumberFormat function, to format output in U.S. numeric and currency styles. For more information, see NumberFormat on page 631. (This tag does not support international number formatting.) Character Meaning _ (Underscore) Digit placeholder. 9 Digit placeholder. . (Period) Location of mandatory decimal point.

PAGE 166

cfgridrow Description Lets you define a cfgrid that does not use a query as source for row data. If a query attribute is specified in cfgrid, the cfgridrow tags are ignored. Category Forms tags Syntax See also cfgrid, cfgridcolumn, cfgridupdate, cfapplet, cfform, cfinput, cfselect, cfslider, cftextinput, cftree Attributes Attribute Req/Opt Default Description data Required Delimited list of column values.

PAGE 167

PAGE 168

This grid shows how the same grid can be built using cfgridrow with cfloop (i.e., defining query external to cfgrid, rather than within cfgrid).
...

PAGE 171

cfheader Description Generates custom HTTP response headers to return to the client. Category Data output tags, Page processing tags Syntax or See also cfcache, cfflush, cfhtmlhead, cfinclude, cfsetting, cfsilent, cfcontent History ColdFusion MX 6.

PAGE 172

Attribute Req/Opt Default Description statusCode Required if name not specified Number. HTTP status code statusText Optional Explains status code Usage If you use this tag after the cfflush tag on a page, an error is thrown. Example
cfheader Example

cfheader generates custom HTTP response headers to return to the client.
This example forces browser client to purge its cache of requested file.

PAGE 173

cfhtmlhead Description Writes text to the head section of a generated HTML page. It is useful for embedding JavaScript code, or putting other HTML tags, such as meta, link, title, or base in an HTML page header. Category Page processing tags Syntax See also cfcache, cfflush, cfheader, cfheader, cfinclude, cfsetting, cfsilent Attributes Attribute Req/Opt text Required Default Description Text to add to the area of an HTML page.

PAGE 174

cfhttp Description Generates an HTTP request and handles the response from the server.

PAGE 175

ColdFusion MX: • Added the charset and firstrowasheaders attributes. • Changed Secure Sockets Layer (SSL) support: ColdFusion uses the Sun JSSE library, which supports 128-bit encryption, to support SSL. Attributes The following attributes control the HTTP transaction and can be used for all HTTP methods: Attribute Req/Opt Default Description url Req Uses the http protocol Address of the resource on the server which will handle the request. The URL must include the hostname or IP address.

PAGE 176

Attribute Req/Opt Default Description proxyUser Opt User name to provide to the proxy server. proxyPassword Opt Password to provide to the proxy server. username Opt A username. May be required by server. password Opt A password. May be required by server userAgent Opt Cold Fusion Text to put in the user agent request header. Used to identify the request client software. Can make the ColdFusion application appear to be a browser.

PAGE 177

Attribute Req/Opt Default Description throwOnError Opt No • Yes if the server returns an error response code, throws an exception that can be caught using the cftry and cfcatch or ColdFusion error pages. • No does not throw an exception if an error response is returned. In this case, your application can use the cfhttp.StatusCode variable to determine if there was an error and its cause.

PAGE 178

The following attribute is used with the PUT method to determine how to send data specified with httpparam type="formField": Attribute Req/Opt Default Description multipart Optional Tells ColdFusion to send all data specified by cfhttpparam type="formField" tags as multipart form data, with a No (Sends as multipart only if request includes File type data.) Content-Type of multipart/form-data.

PAGE 179

The following attributes tell ColdFusion to convert the HTTP response body into a ColdFusion query object. They can be used with the GET and POST methods only: Attribute Req/Opt Default Description name Opt Tells ColdFusion to create a query object with the given name from the returned HTTP response body. columns Opt First row of response contains column names. The column names for the query, separated by commas. Column names must start with a letter.

PAGE 180

The HTTP protocol is the backbone of the World Wide Web and is used for every web transaction. Because the cfhttp tag can generate most types of requests, it provides significant flexibility. Possible uses include: • Interacting with dynamic web sites and services that are not available as web services. (Use the the cfinvoke tag to access SOAP web services.) • Getting the contents of an HTML page or other file such as an image on a web server for use in your CFML page or storage in a file.

PAGE 181

Building a query from a delimited text file The cfhttp tag can create a ColdFusion query object form the response body. To do so, the response body must consist of lines of text, with each line having fields that are delimited by a character that identifies the column breaks. The default delimiter is a comma (,). The response data can also use a text qualifier; the default is a double quotation mark ("). If you surround a string field in the text qualifier, the field can contain the delimiter character.

PAGE 182

http://www.macromedia.com/desdev/resources/macromedia_resources.xml See http://www.macromedia.com/desdev/articles/xml_resource_feed.html for more information on this feed ---> PAGE 198
query="book"> PAGE 199
datasource="book"> select * from book where bookid='file' --#description#--
PAGE 200
200 Chapter 2: ColdFusion Tags

PAGE 201

cfinput Description Used within the cfform tag, to place radio buttons, check boxes, or text boxes on a form. Provides input validation for the specified control type.

PAGE 202

Attribute Req/Opt Default Description validate Optional Verifies a value’s format: • date: US date mm/dd/yyyy • eurodate: European date dd/mm/yyyy • time: time hh:mm:ss • float: floating point entry • integer: integer entry • telephone: telephone ###-###-####. Separator: hyphen or blank. Area code and exchange must begin with a digit 1 – 9. • zipcode: (U.S. formats only) 5-digit ##### or 9-digit #####-####. Separator: hyphen or blank.

PAGE 203

• • • • • • • • • class id onBlur onChange onClick onDblclick onFocus style tabIndex Usage If the cfform preserveData attribute is true and the form posts back to the same page, the posted value of the cfinput control is used, instead of its Value or Checked attribute. If cfinput check box or radio type values match the submitted value for the control, ColdFusion checks their values. If no value matches, nothing is checked.

PAGE 204

message = "Enter a correctly formatted date (dd/mm/yy)" validate = "date" required = "No"> 204 Chapter 2: ColdFusion Tags

PAGE 205

cfinsert Description Inserts records in data sources from data in a ColdFusion form or form Scope. Category Database manipulation tags Syntax PAGE 206
Example
Your record was added to the database.

PAGE 207

type = "hidden" = "posted" value = "#Now()#"> type = "Submit" = "" value = "insert my comment"> cfinsert 207

PAGE 208

cfinvoke Description Does either of the following: • Invokes a component method from within a ColdFusion page or component. • Invokes a web service.

PAGE 209

inputParam1 = "value1" inputParam2 = "value2" ... returnVariable = "var_name" ...> OR #res# Example3 This example uses Syntax 2.

PAGE 213

cfinvokeargument Description Passes the name and value of a parameter to a component method or a web service. This tag is used within the cfinvoke tag. Category Extensibility tags Syntax See also cfargument, cfcomponent, cffunction, cfinvoke, cfobject, cfproperty, cfreturn History ColdFusion MX: Added this tag.

PAGE 214

name="sourcedata" value="Hello world, friend"> #varName# 214 Chapter 2: ColdFusion Tags

PAGE 215

cfldap Description Provides an interface to a Lightweight Directory Access Protocol (LDAP) directory server, such as the Netscape Directory Server. Category Forms tags, Internet Protocol tags Syntax PAGE 216
Attributes Attribute Req/Opt server Required port Optional 389 Port Required if (anonymous) User ID username Default Description Host name or IP address of LDAP server. secure = "CFSSL_BASIC" password Password that corresponds to user name. If secure = "CFSSL_BASIC", V2 encrypts the password before transmission. Required if secure = "CFSSL_BASIC" action name Optional query Required if • query: returns LDAP entry information only. Requires name, start, and attributes attributes.

PAGE 217

Attribute Req/Opt sort Optional sortControl Optional dn startRow Default Description Attribute(s) by which to sort query results. Use a comma delimiter. asc • nocase: case-insensitive sort • asc: ascending (a to z) case-sensitive sort • desc: descending (z to a) case-sensitive sort You can enter a combination of sort types; for example, sortControl = "nocase, asc". Required if Distinguished name, for update action.

PAGE 218

Attribute Req/Opt Default Description separator Optional , [comma] Delimiter to separate attribute values of multi-value attributes. Used by query, add, and modify actions, and by cfldap to output multi-value attributes. For example, if $ (dollar sign), the attributes attribute could be "objectclass = top$person", where the first value of objectclass is top, and the second value is person. This avoids confusion if values include commas.

PAGE 219

Provides an interface to LDAP directory servers. The example uses the University of Connecticut public LDAP server. For more public LDAP servers, see http://www.emailman.com.

Enter a name and search the public LDAP resource. An asterisk before or after the name acts as a wildcard.

PAGE 220

cflocation Description Stops execution of the current page and opens a ColdFusion page or HTML file. Category Flow-control tags, Page processing tags Syntax See also cfabort, cfbreak, cfexecute, cfexit, cfif, cfloop, cfswitch, cfthrow, cftry Attributes Attribute Req/Opt Default Description url Required URL of HTML file or CFML page to open. addToken Optional clientManagement must be enabled (see cfapplication on page 51).

PAGE 221

cflock Description Ensures the integrity of shared data. Instantiates the following kinds of locks: • • Exclusive allows single-thread access to the CFML constructs in its body. The tag body can be executed by one request at a time. No other requests can start executing code within the tag while a request has an exclusive lock. ColdFusion issues exclusive locks on a first-come, first-served basis. Read-only allows multiple requests to access CFML constructs within the tag body concurrently.

PAGE 222

Attribute Req/Opt Default Description throwOnTimeout Optional Yes type Exclusive • readOnly: lets more than one request read shared data. • exclusive: lets one request read or write shared data. Optional How timeout conditions are handled. • Yes: exception is generated for the timeout. • No: execution continues past this tag. Note: Limit the scope of code that updates shared data structures, files, and CFXs.

PAGE 223

These examples show situations that cause deadlocks: Example deadlock with two users User 1 User 2 Locks the session scope. Locks the Application scope. Deadlock: Tries to lock the Application scope, but it is already locked by User 2. Deadlock: Tries to lock the Session scope, but it is already locked by User 1. The following deadlock could occur if you tried to nest an exclusive lock inside a read lock: Example deadlock with one user User 1 Locks the Session scope with a read lock.

PAGE 224

E-Turtleneck has sold #application.number# turtlenecks to date.

Congratulations! You selected the most comfortable turtleneck in the world. Please select color and size.

Select a color.

PAGE 226

cflog Description Writes a message to a log file. Category Data output tags Syntax See also cfcol, cfcontent, cfoutput, cftable History ColdFusion MX: Deprecated the thread, date, and time attributes. They might not work, and might cause an error, in later releases. (In earlier releases, these attributes determined whether the respective data items were output to the log.

PAGE 227

Usage This tag logs custom messages to standard or custom log files. You can specify a file for the log message or send messages to the default application or scheduler log. The log message can include ColdFusion expressions. Log files must have the suffix .log and must be located in the ColdFusion log directory. Log entries are written as comma-delimited lists with these fields: • • • • • • type coio date time application text Values are enclosed in double quotation marks.

PAGE 228

cflogin Description A container for user login and authentication code. ColdFusion runs the code in this tag if a user is not already logged in. You put code in the tag that authenticates the user and identifies the user with a set of roles. Used with cfloginuser tag. Category Extensibility tags Syntax ...

PAGE 229

The cflogin tag has a built-in cflogin structure that contains two variables, cflogin.name and cflogin.password, if the page is executing in response to any of the following: • Submission of a form that contains input fields with the names j_username and j_password. • A request that uses CFHTTP Basic authentication, and therefore includes an Authorization header with the username and password. • A request that uses NTLM or Digest authentication.

PAGE 230

cfloginuser Description Identifies an authenticated user to ColdFusion. Specifies the user ID and roles. Used within a cflogin tag. Category Extensibility tags Syntax See also cflogin, cflogout, GetAuthUser, IsUserInRole, cfapplication, Chapter 16, “Securing Applications,” in Developing ColdFusion MX Applications History ColdFusion MX 6.

PAGE 231

cflogout Description Logs the current user out. Removes knowledge of the user ID, password, and roles from the server. If you do not use this tag, the user is automatically logged out when the session ends. Category Extensibility tags Syntax See also cflogin, cfloginuser, Chapter 16, “Securing Applications,” in Developing ColdFusion MX Applications History ColdFusion MX 6.

PAGE 232

cfloop Description Looping is a programming technique that repeats a set of instructions or displays output repeatedly until one or more conditions are met.

PAGE 233

cfloop: index loop Description An index loop repeats for a number of times that is determined by a numeric value. An index loop is also known as a FOR loop. Syntax ... HTML or CFML code ... See also cfabort, cfbreak, cfdirectory, cfexecute, cfexit, cfif, cflocation, cfrethrow, cfswitch, cfthrow, cftry Attributes Attribute Req/Opt Default Description index Required Index value.

PAGE 234

In this example, the code loops four times, displaying the index value each time. The value of j is decreased by one for each iteration. This does not affect the value of to, because it is a copy of j that is made before entering the loop. The loop index is #LoopCount#.
The output of this loop is as follows: The The The The loop loop loop loop index index index index is is is is 1. 2. 3.

PAGE 235

cfloop: conditional loop Description A conditional loop iterates over a set of instructions as long as a condition is True. To use this type of loop correctly, the instructions must change the condition every time the loop iterates, until the condition is False. Conditional loops are known as WHILE loops, as in, "loop WHILE this condition is true." Syntax ...

PAGE 236

cfloop: looping over a query Description A loop over a query executes for each record in a query record set. The results are similar to those of the cfoutput tag. During each iteration, the columns of the current row are available for output. The cfloop tag loops over tags that cannot be used within a cfoutput tag.

PAGE 237

dataSource = "Library" maxRows = "5"> SELECT TemplateName FROM Templates cfloop: looping over a query 237

PAGE 238

cfloop: looping over a list or file Description Looping over a list steps through elements contained in any of these entities: • A variable • A value that is returned from an expression • A file Syntax ...

PAGE 239

cfloop: looping over a COM collection or structure Description The cfloop collection attribute loops over every object within a COM/DCOM collection object, or every element in a structure: • A COM/DCOM collection object is a set of similar items referenced as a group. For example, the group of open documents in an application is a collection. • A structure contains a related set of items, or it can be used as an associative array.

PAGE 240

cfmail Description Sends an e-mail message that optionally contains query output, using an SMTP server.

PAGE 241

Attributes Attribute Req/Opt Default Description to Required Message recipient e-mail addresses. • Static address. For example, "support@macromedia.com" • Variable that contains an address. For example, "#Form.Email#". • Name of a query column that contains an address. For example, "#EMail#". An e-mail message is sent for each returned row. from Required E-mail message sender: • A static string; for example, "support@mex.com" • A variable; for example, "#GetUser.

PAGE 242

Attribute Req/Opt Default Description charset Optional Character encoding selected in ColdFusion MX Administrator Mail page; default is UTF-8 Character encoding of the mail message, including the headers. The following list includes commonly used values: • utf-8 • iso-8859-1 • windows-1252 • us-ascii • shift_jis • iso-2022-jp • euc-jp • euc-kr • iso-2022-kr • big5 • hz-gb-2312 • euc-cn • utf-16 For more information on character encodings, see: www.w3.org/International/O-charset.html.

PAGE 243

Attribute Req/Opt Default Description port Optional TCP/IP port on which SMTP server listens for requests (normally 25). A value here overrides the Administrator. mailerID Optional timeout Optional ColdFusion MX Application Server spoolEnable Optional Mailer ID to be passed in X-Mailer SMTP header, which identifies the mailer application. Number of seconds to wait before timing out connection to SMTP server. A value here overrides the Administrator.

PAGE 244

Specifying mail servers The server attribute can specify one or more mail servers. Note: If you specify multiple mail servers in ColdFusion MX Standard, the cfmail tag uses only the first server in the specification. ColdFusion logs a warning message to the mail log file and ignores the additional servers. For each server, you can optionally specify a username, password, and port. These values override the corresponding attributes, if any.

PAGE 245

---> cfmail 245

PAGE 246

cfmailparam Description Attaches a file or adds a header to an e-mail message. Can only be used in the cfmail tag. You can use more than one cfmailparam tag within a cfmail tag. Category Forms tags, Internet Protocol tags Syntax or ...

PAGE 247

= "Importance" value = "Hich"> new logo. Tell us what you think. = "c:\work\readme.txt" type="text/plain"> = "c:\work\logo.

PAGE 248

cfmailpart Description Specifies one part of a multipart e-mail message. Can only be used in the cfmail tag. You can use more than one cfmailpart tag within a cfmail tag. Category Forms tags, Internet Protocol tags Syntax (Optional cfmailparam entries) Mail part contents ... History ColdFusion MX 6.1: Added this tag.

PAGE 249

Attribute Req/Opt Default Description wraptext Optional Do not wrap text Specifies the maximum line length, in characters of the mail text. If a line has more than the specified number of characters, replaces the last white space character, such as a tab or space, preceding the specified position with a line break. If there are no white space characters, inserts a line break at the specified position. A common value for this attribute is 72.

PAGE 250

cfmodule Description Invokes a custom tag for use in ColdFusion application pages. This tag processes custom tag name conflicts. For more information, see Chapter 9, “Creating and Using Custom CFML Tags,” in Developing ColdFusion MX Applications. Category Application framework tags Syntax

PAGE 251

Attribute Req/Opt Default Description attributeCollection Optional Structure. A collection of key-value pairs that represent attribute names and values. You can specify multiple key-value pairs. You can specify this attribute only once. attribute_name Optional Attribute for a custom tag. You can include multiple instances of this attribute to specify the parameters of a custom tag.

PAGE 252

Here is another way to invoke the custom tag, using the NAME attribute.

PAGE 253

cfobject Description Creates a ColdFusion object, of a specified type. Note: You can enable and disable this tag in the ColdFusion Administrator page, under ColdFusion Basic Security, Tag Restrictions. Category Extensibility tags Syntax The tag syntax depends on the object type. Some types use the type attribute; others do not.

PAGE 254

cfobject: COM object Description Creates and manipulates a Component Object Model (COM) object. Invokes a registered automation server object type. For information on OLEView, and about COM and DCOM, see the Microsoft OLE Development website: www.microsoft.com. To use this tag, you must provide the object’s program ID or filename, the methods and properties available through the IDispatch interface, and the arguments and return types of the object's methods.

PAGE 255

Attribute Req/Opt context Optional • inproc • local • remote On Windows: If not specified, uses Registry setting. server Required if Server name, using Universal Naming Convention (UNC) or Domain Name Serve (DNS) convention, in one of these forms: • \\lanserver • lanserver • http://www.servername.com • www.servername.com • 127.0.0.1 context = "Remote" Default Description Example
cfobject (COM) Example
SELECT Dept_ID, CorName, CorLevel FROM courseList ORDER by Dept_ID, CorLevel, CorName
cfoutput Example

cfoutput tells ColdFusion Server to begin processing, and then to hand back control of page rendering to the web server.
For example, to show today’s date, you could write #DateFormat("#Now()#").

PAGE 265

cfparam Description Tests for a parameter’s existence, tests its data type, and, if a default value is not assigned, optionally provides one. Category Variable manipulation tags Syntax See also cfcookie, cfregistry, cfsavecontent, cfschedule, cfset Attributes Attribute Req/Opt Default Description name Required Name of parameter to test (such as "Client.Email " or "Cookie.BackgroundColor ").

PAGE 266

• To test whether an optional variable exists, use this tag with the name and default attributes. If the variable does not exist, it is created and set to the default attribute value. If the variable exists, processing continues; the value is not changed.

PAGE 267

cfpop Description Retrieves or deletes e-mail messages from a POP mail server. Category Forms tags, Internet Protocol tags Syntax See also cfftp, cfhttp, cfldap, cfmail, cfmailparam, SetLocale History ColdFusion MX 6.

PAGE 268

Attribute Req/Opt Default Description action Optional getHeaderOnly • getHeaderOnly: returns message header information only • getAll: returns message header information, message text, and attachments if attachmentPath is specified • delete: deletes messages on POP server name Required if action = "getAll" or Name for query object that contains the retrieved message information. "getHeaderOnly" message Number Message number or comma-delimited list of message numbers to get or delete.

PAGE 269

cfpop query variables The following table describes the variables that provide information about the query that is returned by cfpop: Variable names Description queryname.recordCount Number of records returned by query queryname.currentRow Current row that cfoutput is processing queryname.columnList List of column names in query queryname.

PAGE 270

To create a ColdFusion date/time object from the date-time string that is extracted from a mail message in the queryname.date column, use the following table: Locale How to create a ColdFusion date/time object from queryname.date English (US) Use the ParseDateTime function. If you specify the pop-conversion attribute, the function adjusts the date/time object to UTC.

PAGE 271

cfprocessingdirective Description Provides the following insformation to ColdFusion on how to process the current page: • Specifies whether to remove excess whitespace character from ColdFusion generated content in • the tag body. Identifies the character encoding (character set) of the page contents.

PAGE 272

Attributes Attribute Req/Opt Default suppressWhiteSpace Optional pageEncoding Optional Description Boolean; whether to suppress white space characters within the cfprocessingdirective block that are generated by CFML tags and often do not affect HTML appearance. Does not affect any white space in HTML code. Character encoding identified by the page byte order mark, if any; otherwise, system default encoding A string literal; cannot be a variable.

PAGE 273

• If a page has a byte order mark (BOM), and a pageengoding attribute specifies an encoding that differs from the BOM, ColdFusion generates an error. The following rules apply to the suppressWhiteSpace attribute: • You can specify the suppresswhitespace attribute value as a constant or a variable.

PAGE 274

cfprocparam Description Defines stored procedure parameters. This tag is nested within a cfstoredproc tag. Category Database manipulation tags Syntax See also cfinsert, cfprocresult, cfquery, cfqueryparam, cfstoredproc, cftransaction, cfupdate History ColdFusion MX: • The maxrows attribute is obsolete.

PAGE 275

Attribute Req/Opt Default Description CFSQLType Required SQL type to which the parameter (any type) is bound. ColdFusion supports the following values, where the last element of the name corresponds to the SQL data type. Different database systems might support different subsets of this list. See your DBMS documentation for information on supported parameter types.

PAGE 276

Example The following example shows how to invoke an Oracle 8 PL/SQL stored procedure. It makes use of Oracle 8 support of the Reference Cursor type. The following package, Foo_Data, houses a procedure refcurproc that declares output parameters as Reference Cursor: • Parameter pParam1 returns the rows in the EMP table • Parameter pParam2 returns the rows in the DEPT table The procedure declares one input parameter as an integer, and one output parameter as a twobyte char varying type.

PAGE 277

The second result set:

PAGE 278

cfprocresult Description Associates a query object with a result set returned by a stored procedure. Other ColdFusion tags, such as cfoutput and cftable, use this query object to access the result set. This tag is nested within a cfstoredproc tag.

PAGE 279

The output param value: ’#foo#’

The Results Information
#name#,#DATE_COL#

Record Count: #RS1.recordCount#
Columns: #RS1.

PAGE 280

cfproperty Description Defines properties of a ColdFusion component (CFC). Used to create complex data types for web services. The attributes of this tag are exposed as component metadata and are subject to inheritance rules.

PAGE 281

Attribute Req/Opt Default Description required Optional no Whether the parameter is required yes no default Optional If no property value is set when the component is used for a web service, specifies a default value. If this attribute is present, the required attribute must be set to "no" or not specified. displayname Optional A value to be displayed when using introspection to show information about the CFC. The value appears in parentheses following the property name.

PAGE 282

cfquery Description Passes queries or SQL statements to a data source. Macromedia recommends that you use the cfqueryparam tag within every cfquery tag, to help secure your databases from unauthorized users. For more information, see: • Security Bulletin ASB99-04, "Multiple SQL Statements in Dynamic Queries," in the • Macromedia Security Zone, http://www.macromedia.com/devnet/security/security_zone/ asb99-04.html.

PAGE 283

Attributes Attribute Req/Opt name Required Name of query. Used in page to reference query record set. Must begin with a letter. Can include letters, numbers, and underscores. dataSource Required Name of data source from which query gets data. dbtype Optional username Optional Overrides username in data source setup. password Optional Overrides password in data source setup. maxRows Optional -1 (All) Maximum number of rows to return in record set.

PAGE 284

This tag creates a query object, providing this information in query variables: Variable name Description query_name.currentRow Current row of query that cfoutput is processing query_name.columnList Comma-delimited list of the query columns query_name.RecordCount Number of records (rows) returned from the query cfquery.ExecutionTime Cumulative time required to process the query You can cache query results and execute stored procedures.

PAGE 285

State

#GetParks.

PAGE 286

cfqueryparam Description Verifies the data type of a query parameter and, for DBMSs that support bind variables, enables ColdFusion to use bind variables in the SQL statement. Bind variable usage enhances performance when executing a cfquery statement multiple times. This tag is nested within a cfquery tag, embedded in a query SQL statement. If you specify optional parameters, this tag performs data validation.

PAGE 287

Attributes Attribute Req/Opt value Required Default Description Value that ColdFusion passes to the right of the comparison operator in a where clause. If CFSQLType is a date or time option, ensure that the date value uses your DBMS-specific date format. Use the CreateODBCDateTime or DateFormat and TimeFormat functions to format the date value. CFSQLType Optional CF_SQL_ SQL type that parameter (any type) is bound to.

PAGE 288

Usage Use cfqueryparam in any SQL statement (for example, SELECT, INSERT, UPDATE, and DELETE) that uses ColdFusion variables. For maximum validation of string data, specify the maxlength attribute. This tag does the following: • • • • Allows the use of SQL bind parameters, which improves performance. Ensures that variable data matches the specified SQL type. Allows long text fields to be updated from a SQL statement. Escapes string variables in single quotation marks.

PAGE 289

SELECT * FROM employees WHERE LastName=
Course Number: #FirstName# #LastName# Description: #Department#
cfqueryparam 289

PAGE 290

cfregistry Description This tag is deprecated for the UNIX platform. Reads, writes, and deletes keys and values in the system registry. Provides persistent storage of client variables. Note: For this tag execute, it must be enabled in the ColdFusion Administrator. For more information, see Configuring and Administering ColdFusion MX. Category Other tags, Variable manipulation tags Syntax The tag syntax depends on the action attribute value. See the following sections.

PAGE 291

cfregistry action = "getAll" Description Returns all registry keys and values defined in a branch. You can access the values as you would any record set. Syntax Attributes Attribute Req/Opt Default Description action Required getall branch Required Name of a registry branch. type Optional String • • • • name Required Name of record set to contain returned keys and values.

PAGE 292

cfregistry action = "get" Description Accesses a registry value and stores it in a ColdFusion variable. Syntax Attributes Attribute Req/Opt Default action Required get branch Required Name of a registry branch. entry Required Registry value to access. variable Required Variable into which to put value.

PAGE 293

cfregistry action = "set" Description Adds a registry key, adds a value, or updates a value. Syntax Attributes Attribute Req/Opt Default Description action Required set branch Required Name of a registry branch. entry Required Key or value to set. type Optional • string: set a string value (default). • dWord: set a DWord value. • key: create a key. value Optional Value data to set.

PAGE 294

cfregistry action = "delete" Description Deletes a registry key or value. Syntax Attributes Attribute Req/Opt Default Description action Required delete branch Required • For key deletion: name of registry key to delete. Do not specify the entry. • For value deletion: name of registry branch that contains value to delete. You must specify entry.

PAGE 295

cfreport Description Runs a predefined Crystal Reports report. Applies only to Windows systems. Uses the CFCRYSTAL.exe file to generate reports. Sets parameters in the Crystal Reports engine according to its attribute values.

PAGE 296

Attribute Req/Opt Default Description password Optional Password that corresponds to username required for database access. Overrides default settings for data source in ColdFusion Administrator. formula Optional One or more named formulas. Terminate each formula with a semicolon. Use the format: formula = "formulaname1 = 'formula1';formulaname2 = 'formula2';" If you use a semicolon in a formula, you must escape it by typing it twice (;;).

PAGE 297

cfrethrow Description Rethrows the currently active exception. Preserves the exception’s cfcatch.type and cfcatch.tagContext variable values. Category Exception handling tags, Extensibility tags Syntax See also cferror, cfthrow, cftry Usage Use this tag within a cfcatch block. This tag is useful in error handling code, if the error handler cannot handle an error that it catches.

PAGE 298

cfreturn Description Returns result values from a component method. Contains an expression returned as result of the function. Return value An expression; the result of the function from which this tag is called. Category Extensibility tags Syntax See also cfargument, cfcomponent, cffunction, cfinvoke, cfinvokeargument, cfobject, cfproperty History ColdFusion MX: Added this tag.

PAGE 299

cfreturn 299

PAGE 300

cfsavecontent Description Saves the generated content of the cfsavecontent tag, including the results of evaluating expressions and executing custom tags, in the specified variable. Category Variable manipulation tags Syntax the content See also cfcookie, cfparam, cfregistry, cfschedule, cfset Attributes Attribute Req/Opt Default Description variable Name ofthe variable in which to save the generated content of the tag.

PAGE 301

cfschedule Description Provides a programmatic interface to the ColdFusion scheduling engine. Can run a CFML page at scheduled intervals, with the option to write the page output to a static HTML page. This feature enables you to schedule pages that publish data, such as reports, without waiting while a database transaction is performed to populate the page.

PAGE 302

Attributes Attribute Req/Opt Default action Required • delete: deletes the specified task • update: updates an existing task or creates a new task, if one with the name specified by the task attribute does not exist • run: executes the specified task task Required Name of the task. operation Required if action = Operation that the scheduler performs. Must be HTTPRequest. "update" file Name of the file in which to store the published output of the scheuled task.

PAGE 303

Attribute Req/Opt proxyPassword Opt resolveURL Optional Default Description Password to provide to the proxy server. No • Yes: resolve links in the output page to absolute references • No Usage This tag and the ColdFusion MX Administrator Scheduled task page schedule ColdFusion tasks. Tasks that you add or change using this tag are visible in the Aministrator. You can disable this tag in the Administrator Sandbox/Resource security page.

PAGE 304

cfscript Description Encloses a code block that contains cfscript statements.

PAGE 305

You cannot use the elseif construct within a cfscript tag. You can use code such as the following: else if ( condition ) { ... } Exception handling with the cfscript tag To handle exceptions with this tag, use try and catch statements, which are equivalent to the cftry and cfcatch tags. For each try statement, you must have a catch statement. In the catch block, the variable exceptionVariable contains the exception type. This variable is the equivalent of the cfcatch tag built-in variable cfcatch.Type.

PAGE 306

xlatstring = ws.BabelFish("en_es", "Hello world, friend"); writeoutput(xlatstring); For more information, see Chapter 32, “Using Web Services,” in Developing ColdFusion MX Applications. Example
This simple example shows variable declaration and manipulation. y = x; z = 2 * y; StringVar = form.myString;
twice #x# is #z#.

PAGE 307

cfsearch Description Searches Verity collections using ColdFusion or K2Server, whichever search engine a collection is registered by. (ColdFusion can also search collections that have not been registered, with the cfcollection tag.) A collection must be created and indexed before this tag can return search results.

PAGE 308

• Changed Verity operations behavior: ColdFusion supports Verity operations on Acrobat PDF files. • Changed multiple collection behavior: this tag can search multiple collections. In a multiple • • • collection search, you cannot combine collections that are registered with K2Server and registered in another way. Changed acceptable collection naming: this tag accepts collection names that include spaces. Changed the following support: this tag supports Verity 2.6.1 and the LinguistX and ICU locales.

PAGE 309

cf_root\lib\common\style\file Unix: ■ cf_root/lib/common/style (typically, cf_root = /opt/coldfusionmx) ■ cf_root/lib/common/style/custom ■ cf_root/lib/common/style/file ■ • Note: To search for a character such as an angle bracket (< or >), you must use a criteria attribute value such as "<:" or "<:". The bracket characters are reserved in Verity, and using a backslash to escape the character (criteria="\<") does not work in this context.

PAGE 310

You can use query result columns in standard CFML expressions, preceding the result column name with the name of the query, as follows: #DocSearch.url# #DocSearch.key# #DocSearch.title# #DocSearch.score# Example
Search Result total = #name.RecordCount#
url=#name.url#
key=#name.key#
title=#name.title#
score=#name.

PAGE 311

criteria = "cf_key=bookid2"> url=#book.url#
key=#book.key#
title=#book.titleE#
score=#book.score#
custom1=#book.custom1#
custom2=#book.custom2#
summary=#book.summary#
recordcount=#book.recordcount#
currentrow=#book.currentrow#
columnlist=#book.columnlist#
recordssearched=#book.

PAGE 312

cfselect Description Constructs a drop-down list box form control. Used within a cfform tag. You can populate the list from a query, or by using the HTML option tag.

PAGE 313

Attribute Req/Opt value Optional display Optional Default Description Query column to use for the value of each list element. Used with query attribute. Value of Query column to use for the display label of each list element. value Used with query attribute. attribute passThrough Optional Passes one or more arbitrary attribute-value pairs to the HTML code that is generated for the tag.

PAGE 314

Example

PAGE 315

expand="No" queryasroot="No"> 344 Chapter 2: ColdFusion Tags

PAGE 345

cftree Description Inserts a tree control in a form. Validates user selections. Used within a cftree tag block. You can use a ColdFusion query to supply data to the tree.

PAGE 346

Attribute 346 Req/Opt Default Description completePath Optional No; tree name is returned as root • Yes: passes the root part of treename.path form variable when cftree is submitted • No, or omitted: root level of form variable is not passed; path value starts with the first node For the preserveData attribute of cfform to work with the tree, you must set this attribute to Yes. If you specify a root name for a tree item with cftreeitem queryasroot, that value is returned.

PAGE 347

Attribute Req/Opt Default Description align Optional • • • • • • • • • border Optional Yes • Yes • No hScroll Optional Yes • Yes: permits horizontal scrolling • No vScroll Optional Yes • Yes: permits vertical scrolling • No notSupported Optional top left bottom baseline texttop absbottom middle absmiddle right Message to display if page that contains Java applet-based form control is opened by browser that does not support Java, or has Java support disabled.

PAGE 348

SELECT Emp_ID, FirstName, LastName, EMail, Phone, Department FROM Employees where lastname = ’#employeeNames#’
cftree Example
PAGE 349
cftreeitem Description Populates a form tree control, created with the cftree tag, with elements. To display icons, you can use the img values that ColdFusion provides, or reference your own icons.

PAGE 350

Attribute Req/Opt Default Description imgopen Optional Icon displayed with open tree item. You can specify icon filename with a relative path. You can use a ColdFusion image. href Optional URL to associate with tree item or query column for a tree that is populated from a query. If href is a query column, its value is the value populated by query. If href is not recognized as a query column, it is assumed that its text is an HTML href.

PAGE 351

cfselect Presentation of Data

Click an employee’s last name and click "see information for this employee" to see expanded information.
PAGE 352
headeritalic="No">

PAGE 353

cftry Description Used with one or more cfcatch tags. Together, they catch and process exceptions in ColdFusion pages. Exceptions are events that disrupt the normal flow of instructions in a ColdFusion page, such as failed database operations, missing include files, and developer-specified events.

PAGE 354

354 Chapter 2: ColdFusion Tags

PAGE 355

cfupdate Description Updates records in a data source from data in a ColdFusion form or form Scope.

PAGE 356

Example

PAGE 357

cfupdate 357

PAGE 358

cfwddx Description Serializes and deserializes CFML data structures to the XML-based WDDX format. The WDDX is an XML vocabulary for describing complex data structures in a standard, generic way. Implementing it lets you use the HTTP protocol to such information among application server platforms, application servers, and browsers. This tag generates JavaScript statements to instantiate JavaScript objects equivalent to the contents of a WDDX packet or CFML data structure. Interoperates with Unicode.

PAGE 359

Attribute Req/Opt Default Description useTimeZoneInfo Optional Yes Whether to output time-zone information when serializing CFML to WDDX. • Yes: the hour-minute offset, represented in ISO8601 format, is output. • No: the local time is output. validate No Applies if action = "wddx2cfml" or "wddx2js". • yes: validates WDDX input with an XML parser using WDDX DTD. If parser processes input without error, packet is deserialized. Otherwise, an error is thrown.

PAGE 360

Deserializing WDDX packet...
The recordset data is:...

PAGE 361

cfxml Description Creates a ColdFusion XML document object that contains the markup in the tag body. This tag can include XML and CFML tags. ColdFusion processes the CFML code in the tag body, then assigns the resulting text to an XML document object variable. Category Extensibility tags Syntax See also IsXmlDoc, IsXmlElem, IsXmlRoot, XmlChildPos, XmlNew, XmlParse, XmlSearch, XmlTransform History ColdFusion MX: Added this tag.

PAGE 362

362 Chapter 2: ColdFusion Tags

PAGE 363

CHAPTER 3 ColdFusion Functions This chapter lists and categorizes ColdFusion Markup Language (CFML) functions. Contents Function list. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 364 Functions by category . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 367 Function changes since ColdFusion 5 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

PAGE 364

Function list ColdFusion Markup Language (CFML) includes a set of functions that you use in ColdFusion pages to perform logical and arithmetic operations and manipulate data.

PAGE 365

BitXor IsDefined Reverse Ceiling IsK2ServerABroker Right Chr IsK2ServerDocCountExceeded RJustify CJustify IsK2ServerOnline Round Compare IsLeapYear RTrim CompareNoCase IsNumeric Second Cos IsNumericDate SetEncoding CreateDate IsObject SetLocale CreateDateTime IsQuery SetProfileString CreateObject IsSimpleValue SetVariable CreateODBCDate IsStruct Sgn CreateODBCDateTime IsUserInRole Sin CreateODBCTime IsWDDX SpanExcluding CreateTime IsXmlDoc SpanIncluding CreateTimeSp

PAGE 366

DollarFormat ListQualify TimeFormat Duplicate ListRest ToBase64 Encrypt ListSetAt ToBinary Evaluate ListSort ToString Exp ListToArray Trim ExpandPath ListValueCount UCase FileExists ListValueCountNoCase URLDecode Find LJustify URLEncodedFormat FindNoCase Log URLSessionFormat FindOneOf Log10 Val FirstDayOfMonth LSCurrencyFormat ValueList Fix LSDateFormat Week FormatBaseN LSEuroCurrencyFormat Wrap GetAuthUser LSIsCurrency WriteOutput GetBaseTagData LSIsDate Xml

PAGE 367

Functions by category The following tables list functions by their category or purpose. Array functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 367 Authentication functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 367 Conversion functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

PAGE 368

ToBinary ListToArray XmlFormat ToString URLDecode XmlParse Date and time functions CreateDate DateFormat GetTimeZoneInfo MonthAsString CreateDateTime DatePart Hour Now CreateODBCDate Day IsDate ParseDateTime CreateODBCDateTime DayOfWeek IsLeapYear Quarter CreateODBCTime DayOfWeekAsString IsNumericDate Second CreateTime DayOfYear LSDateFormat TimeFormat CreateTimeSpan DaysInMonth LSIsDate Week DateAdd DaysInYear LSParseDateTime Year DateCompare FirstDayOfMonth LSTimeFo

PAGE 369

Dynamic evaluation functions DE Evaluate IIf SetVariable Extensibility functions CreateObject XmlElemNew XmlParse ReleaseComObject XmlFormat XmlSearch XmlChildPos XmlNew XmlTransform Full-text search functions History ColdFusion MX 6.1: These functions are deprecated. They might not work, and might cause errors, in a future release.

PAGE 370

Mathematical functions Abs BitNot FormatBaseN Randomize ACos BitOr IncrementValue RandRange ArrayAvg BitSHLN InputBaseN Round ArraySum BitSHRN Int Sgn ASin BitXor Log Sin Atn Ceiling Log10 Sqr BitAnd Cos Max Tan BitMaskClear DecrementValue Min BitMaskRead Exp Pi BitMaskSet Fix Rand Other functions CreateUUID GetBaseTagList QuotedValueList URLEncodedFormat Decrypt GetBaseTemplatePath StripCR URLSessionFormat DeleteClientVariable GetClientVariablesList ToBase64 Val

PAGE 371

Compare Len REFind ToBase64 CompareNoCase LJustify REFindNoCase ToBinary DayOfWeekAsString ListValueCount RemoveChars ToString Decrypt ListValueCountNoCase RepeatString Trim Encrypt LSIsCurrency Replace UCase FormatBaseN LSIsDate ReplaceList URLDecode Find LSIsNumeric ReplaceNoCase URLEncodedFormat FindNoCase LSParseCurrency REReplace Val FindOneOf LSParseDateTime REReplaceNoCase Wrap GetToken LSParseEuroCurrency Reverse XmlFormat Hash LSParseNumber Right Insert LT

PAGE 372

Function changes since ColdFusion 5 The following tables list functions, parameters and values that have changed since ColdFusion 5.0 and indicate the specific release in which the change was made. Array functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 367 Deprecated functions, parameters, and values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 373 Obsolete functions, parameters, and values . . . . . .

PAGE 373

Function Parameter or value Added in this ColdFusion release XmlSearch All ColdFusion MX XmlTransform All ColdFusion MX Deprecated functions, parameters, and values The following functions, parameters, and values are deprecated. Do not use them in ColdFusion applications. They might not work, and might cause an error, in releases later than ColdFusion MX.

PAGE 374

Abs Description Absolute-value function. The absolute value of a number is the number without its sign. Returns The absolute value of a number. Category Mathematical functions Function syntax Abs(number) See also Sgn Parameters Parameter Description number A number Example
Abs Example

The absolute value of the following numbers: 1,3,-4,-3.2,6 is #Abs(1)#,#Abs(3)#,#Abs(-4)#,#Abs(-3.2)#,#Abs(6)#
The absolute value of a number is the number without its sign.

PAGE 375

ACos Description Arccosine function. The arccosine is the angle whose cosine is number. Returns The arccosine, in radians, of a number. Category Mathematical functions Function syntax ACos(number) See also Cos, Sin, ASin, Tan, Atn, Pi Parameters Parameter Description number Cosine of an angle. The value must be between -1.0 and 1.0, inclusive. Usage The range of the result is 0 to π. To convert degrees to radians, multiply degrees by π/180. To convert radians to degrees, multiply radians by 180/π.

PAGE 376

ArrayAppend Description Appends an array element to an array. Returns True, on successful completion. Category Array functions Function syntax ArrayAppend(array, value) See also ArrayPrepend History ColdFusion MX: Changed behavior: this function can be used on XML objects.

PAGE 377

ArrayAvg Description Calculates the average of the values in an array. Returns Number. If the array parameter value is an empty array, returns zero. Category Array functions, Mathematical functions Function syntax ArrayAvg(array) See also ArraySum Parameters Parameter Description array Name of an array Usage The following example uses the ColdFusion built-in variable Form.fieldNames, which is available on the action page of a form.

PAGE 378

Number #LoopItem#

PAGE 379
ArrayClear Description Deletes the data in an array. Returns True, on successful completion. Category Array functions Function syntax ArrayClear(array) See also ArrayDeleteAt History ColdFusion MX: Changed behavior: this function can be used on XML objects.

PAGE 380

ArrayDeleteAt Description Deletes an element from an array. When an element is deleted, ColdFusion recalculates index positions. For example, in an array that contains the months of the year, deleting the element at position 5 removes the entry for May. After this, to delete the entry for June, you would delete the element at position 5 (not 6). Returns True, on successful completion.

PAGE 381

ArrayInsertAt Description Inserts a value into an array. Array elements whose indexes are greater than the new position are incremented by one. The array length increases by one. Returns True, on successful completion. Category Array functions Function syntax ArrayInsertAt(array, position, value) See also ArrayDeleteAt History ColdFusion MX: • Changed behavior: this function can be used on XML objects. • Changed thrown exceptions: this function can throw the InvalidArrayIndexException error.

PAGE 382

ArrayIsEmpty Description Determines whether an array is empty of data elements. Returns True, if the array is empty; otherwise, False. Category Array functions Function syntax ArrayIsEmpty(array) See also ArrayLen History ColdFusion MX: Changed behavior: this function can be used on XML objects.

PAGE 383

ArrayLen Description Determines the number of elements in an array. Returns The number of elements in an array. Category Array functions Function syntax ArrayLen(array) See also ArrayIsEmpty History ColdFusion MX: Changed behavior: this function can be used on child XML objects.

PAGE 384

ArrayMax Description Array maximum function. Returns The largest numeric value in an array. If the array parameter value is an empty array, returns zero. Category Array functions Function syntax ArrayMax(array) Parameters Parameter Description array Name of an array Example
ArrayMax Example

This example uses ArrayMax to find the largest number in an array.

PAGE 385

ArrayMin Description Array minimum function. Returns The smallest numeric value in an array. If the array parameter value is an empty array, returns zero. Category Array functions Function syntax ArrayMin(array) Parameters Parameter Description array Name of an array Example
ArrayMin Example

This example uses ArrayMin to find the smallest number in an array.

PAGE 386

ArrayNew Description Creates an array of 1–3 dimensions. Index array elements with square brackets: [ ]. ColdFusion arrays expand dynamically as data is added. Returns An array Category Array functions Function syntax ArrayNew(dimension) Parameters Parameter Description dimension Number of dimensions in new array.

PAGE 387

ArrayPrepend Description Inserts an array element at the beginning of an array. Returns True, on successful completion.

PAGE 388

ArrayResize Description Resets an array to a specified minimum number of elements. This can improve performance, if used to size an array to its expected maximum. For more than 500 elements, use ArrayResize immediately after using the ArrayNew tag. ColdFusion arrays expand dynamically as data is added. Returns True, on successful completion.

PAGE 389

ArraySet Description In a one-dimensional array, sets the elements in a specified index range to a value. Useful for initializing an array after a call to ArrayNew. Returns True, on successful completion. Category Array functions Function syntax ArraySet(array, start_pos, end_pos, value) See also ArrayNew History ColdFusion MX: Changed behavior: this function can be used on XML objects. Parameters Parameter Description array Name of an array. start_pos Starting index position of range to set.

PAGE 390

ArraySort Description Sorts array elements numerically or alphanumerically. Returns True, if sort is successful; False, otherwise. Category Array functions, List functions Function syntax ArraySort(array, sort_type [, sort_order ]) History ColdFusion MX: • Changed thrown exceptions: this function can throw the ArraySortSimpleValueException error and ValueNotNumeric error.

PAGE 391

Throws If an array element is other than a simple element, this function throws an ArraySortSimpleValueException error. If sort_type is numeric and an array element is not numeric, this function throws a ValueNotNumeric error.

PAGE 392

ArraySum Description Array sum function. Returns The sum of values in an array. If the array parameter value is an empty array, returns zero. Category Array functions, Mathematical functions Function syntax ArraySum(array) Parameters Parameter Description array Name of an array Example
ArraySum Example

This example uses ArraySum to add two numbers together.

PAGE 393

ArraySwap Description Swaps array values of an array at specified positions. This function is more efficient than multiple cfset tags. Returns True, on successful completion.

PAGE 394

ArrayToList Description Converts a one-dimensional array to a list. Returns Delimited list, as a string. Category Array functions, Conversion functions, List functions Function syntax ArrayToList(array [, delimiter ]) Parameters Parameter Description array Name of array delimiter Character or multi-character string to separate list elements. Default: comma.

PAGE 395

Asc Description Determines the value of a character. Returns The value of the first character of a string; if string is empty, returns zero. Category String functions Function syntax Asc(string) See also Chr History ColdFusion MX: Changed Unicode support: ColdFusion supports the Java UCS-2 representation of Unicode characters, up to a value of 65536. (Earlier releases supported 1-255.

PAGE 396

ASin Description Determines the arcsine of a number. The arcsine is the angle whose sine is number. Returns The arcsine, in radians, of a number. Category Mathematical functions Function syntax ASin(number) See also Sin, Cos, ACos, Tan, Atn, Pi Parameters Parameter Description number Sine of an angle. The value must be between -1 and 1, inclusive. Usage The range of the result is -π/2 to π/2 radians. To convert degrees to radians, multiply degrees by π/180.

PAGE 397

ASin 397

PAGE 398

Atn Description Arctangent function. The arctangent is the angle whose tangent is number. Returns The arctangent, in radians, of a number. Category Mathematical functions Function syntax Atn(number) See also Atn, Sin, ASin, Cos, ACos, Pi Parameters Parameter Description number Tangent of an angle Usage The range of the result is -π/2 to π/2 radians. To convert degrees to radians, multiply degrees by π/180. To convert radians to degrees, multiply radians by 180/π.

PAGE 399

AuthenticatedContext Description This function is obsolete. Use the newer security tools; see “Authentication functions” on page 367 and Chapter 16, “Securing Applications,” in Developing ColdFusion MX Applications. History ColdFusion MX: This function is obsolete. It does not work in ColdFusion MX and later ColdFusion releases.

PAGE 400

AuthenticatedUser Description This function is obsolete. Use the newer security tools; see “Authentication functions” on page 367 and Chapter 16, “Securing Applications,” in Developing ColdFusion MX Applications. History ColdFusion MX: This function is obsolete. It does not work in ColdFusion MX and later ColdFusion releases.

PAGE 401

BitAnd Description Performs a bitwise logical AND operation. Returns The bitwise AND of two long integers. Category Mathematical functions Function syntax BitAnd(number1, number2) See also BitNot, BitOr, BitXor Parameters Parameter Description number1 32-bit signed integer number2 32-bit signed integer Usage Bit functions operate on 32-bit signed integers, in the range -2147483648 – 2147483647. Example
BitAnd Example

Returns the bitwise AND of two long integers.

PAGE 402

BitMaskClear Description Performs a bitwise mask clear operation. Returns A number, bitwise cleared, with length bits beginning at start.

PAGE 403

BitMaskRead Description Performs a bitwise mask read operation. Returns An integer, created from length bits of number, beginning at start.

PAGE 404

BitMaskSet Description Performs a bitwise mask set operation. Returns A number, bitwise masked with length bits of mask beginning at start.

PAGE 405

BitNot Description Performs a bitwise logical NOT operation. Returns A number; the bitwise NOT of a long integer. Category Mathematical functions Function syntax BitNot(number) See also BitAnd, BitOr, BitXor Parameters Parameter Description number 32-bit signed integer Usage Bit functions operate on 32-bit signed integers, in the range -2147483648 – 2147483647. Example
BitNot Example

Returns the bitwise NOT of a long integer.

PAGE 406

BitOr Description Performs a bitwise logical OR operation. Returns A number; the bitwise OR of two long integers. Category Mathematical functions Function syntax BitOr(number1, number2) See also BitAnd, BitNot, BitXor Parameters Parameter Description number1 32-bit signed integer number2 32-bit signed integer Usage Bit functions operate on 32-bit signed integers, in the range -2147483648 – 2147483647. Example
BitOr Example

Returns the bitwise OR of two long integers.

PAGE 407

BitSHLN Description Performs a bitwise shift-left, no-rotation operation. Returns A number, bitwise shifted without rotation to the left by count bits. Category Mathematical functions Function syntax BitSHLN(number, count) See also BitSHRN Parameters Parameter Description number 32-bit signed integer count Integer, in the range 0-31, inclusive; number of bits to shift the number Usage Bit functions operate on 32-bit signed integers, in the range -2147483648 – 2147483647.

PAGE 408

BitSHRN Description Performs a bitwise shift-right, no-rotation operation. Returns A number, bitwise shifted, without rotation, to the right by count bits. Category Mathematical functions Function syntax BitSHRN(number, count) See also BitSHLN Parameters Parameter Description number 32-bit signed integer count Integer, in the range 0-31, inclusive. Number of bits to shift the number Usage Bit functions operate on 32-bit signed integers, in the range -2147483648 – 2147483647.

PAGE 409

BitXor Description Performs a bitwise logical XOR operation. Returns Bitwise XOR of two long integers. Category Mathematical functions Function syntax BitXor(number1, number2) See also BitAnd, BitNot, BitOr Parameters Parameter Description number1 32-bit signed integer number2 32-bit signed integer Usage Bit functions operate on 32-bit signed integers, in the range -2147483648 – 2147483647. Example
BitXOr Example

Returns the bitwise XOR of two long integers.

PAGE 410

Ceiling Description Determines the closest integer that is greater than a specified number. Returns The closest integer that is greater than a given number. Category Mathematical functions Function syntax Ceiling(number) See also Int, Fix, Round Parameters Parameter Description number A real number Example
Ceiling Example

The ceiling
The ceiling
The ceiling
The ceiling 410 of of of of 3.4 is #ceiling(3.4)# 3 is #ceiling(3)# 3.8 is #ceiling(3.8)# -4.

PAGE 411

Chr Converts a numeric value to a UCS-2 character. Returns A character with the specified UCS-2 character code. Category String functions Function syntax Chr(number) See also Asc History ColdFusion MX: Changed Unicode support: ColdFusion supports the Java UCS-2 representation of Unicode characters, up to a value of 65535. (Earlier releases supported 1-255.

PAGE 412

CJustify Description Centers a string in a field length. Returns String, center-justified by adding spaces before or after the input parameter. If length is less than the length of the input parameter string, the string is returned unchanged. Category Display and formatting functions, String functions Function syntax Cjustify(string, length) See also LJustify, RJustify Parameters Parameter Description string A string or a variable that contains one. May be empty.

PAGE 413

Compare Description Performs a case-sensitive comparison of two strings. Returns • -1, if string1 is less than string2 • 0, if string1 is equal to string2 • 1, if string1 is greater than string2 Category String functions Function syntax Compare(string1, string2) See also CompareNoCase, Find Parameters Parameter Description string1 A string or a variable that contains one string2 A string or a variable that contains one Usage Compares the values of corresponding characters in string1 and string2.

PAGE 414

String 1

String 2

414 Chapter 3: ColdFusion Functions

PAGE 415

CompareNoCase Description Performs a case-insensitive comparison of two strings.

PAGE 416

416 Chapter 3: ColdFusion Functions

PAGE 417

Cos Description Calculates the cosine of an angle that is entered in radians. Returns A number; the cosine of the angle. Category Mathematical functions Function syntax Cos(number) See also ACos, Sin, ASin, Tan, Atn, Pi Parameters Parameter Description number Angle, in radians, for which to calculate the cosine Usage The range of the result is -1 to 1. To convert degrees to radians, multiply degrees by π/180. To convert radians to degrees, multiply radians by 180/π.

PAGE 418

   418 Chapter 3: ColdFusion Functions

PAGE 419

CreateDate Description Creates a date/time object. Returns A date/time value. Category Date and time functions Function syntax CreateDate(year, month, day) See also CreateDateTime, CreateODBCDate Parameters Parameter Description year Integer in the range 0-9999. Integers in the range 0-29 are converted to 20002029. Integers in the range 30-99 are converted to 1930-1999. You cannot specify dates before AD 100.

PAGE 420

#DateFormat(CreateODBCDateTime(yourDate), "d/m/yy")# PAGE 421
CreateDateTime Description Creates a date-time object. Returns A date/time value. Category Date and time functions Function syntax CreateDateTime(year, month, day, hour, minute, second) See also CreateDate, CreateTime, CreateODBCDateTime, Now Parameters Parameter Description year Integer in the range 0-9999. Integers in the range 0-29 are converted to 20002029. Integers in the range 30-99 are converted to 1930-1999. You cannot specify dates before AD 100.

PAGE 422

Formatted with CreateODBCDate and DateFormat: #DateFormat(CreateODBCDate(yourDate), "mmmm d, yyyy")#
Formatted with CreateODBCDateTime and DateFormat: #DateFormat(CreateODBCDateTime(yourDate), "d/m/yy")# PAGE 423
CreateObject Description Creates a ColdFusion object, of a specified type. Returns An object, of the specified type. Note: You can enable and disable this function in the ColdFusion Administrator, ColdFusion Basic Security, Tag Restrictions page. Category Extensibility functions History ColdFusion MX: • Changed instantiation behavior: this function, and the cfobject tag, can instantiate • • ColdFusion components and web services.

PAGE 424

CreateObject: COM object Description The CreateObject function can create a Component Object Model (COM) object. To create a COM object, you must provide this information: • The object’s program ID or filename • The methods and properties available to the object through the IDispatch interface • The arguments and return types of the object's methods For most objects, you can get this information from the OLEView utility. Note: On UNIX, this function does not support COM objects. Returns A COM object.

PAGE 425

CreateObject: component object Description The CreateObject function can create an instance of a ColdFusion component (CFC) object. Returns A component object. Function syntax CreateObject(type, component-name) Parameters Parameter Description type Type of object to create. • com • corba • java • component • webservice component-name The CFC name; corresponds to the name of the file that defines the component; for example, use engineComp to specify the component defined in the engineComp.

PAGE 426

CreateObject: CORBA object Description The CreateObject function can call a method on a CORBA object. The object must be defined and registered for use. Returns A handle to a CORBA interface. Function syntax CreateObject(type, context, class, locale) History See the History section of the main CreateObject function page. Parameters Parameter Description type Type of object to create.

PAGE 427

myobj = CreateObject("corba", "Macromedia/Eng/CF", "nameservice", "visibroker") // uses nameservice myobj = CreateObject("corba", "d:\temp\tester.

PAGE 428

CreateObject: Java or EJB object Description The CreateObject function can create a Java object, and, by extension, an EJB object. Returns A Java object. Function syntax CreateObject(type, class) Parameters Parameter Description type Type of object to create. • com • corba • java • component • webservice class A Java class name Usage Any Java class available in the class path that is specified in the ColdFusion Administrator can be loaded and used from ColdFusion with the CreateObject function.

PAGE 429

CreateObject: web service object Description This function can create a web service object. Returns A web service object. Function syntax CreateObject(type, urltowsdl) Parameters Parameter Description type Type of object to create. • com • corba • java • component • webservice urltowsdl WSDL file URL; location of web service Usage You can use the CreateObject function to create a web service.

PAGE 430

CreateODBCDate Description Creates an ODBC date object. Returns A date object, in normalized ODBC date format. Category Date and time functions Function syntax CreateODBCDate(date) See also CreateDate, CreateODBCDateTime Parameters Parameter Description date Date or date/time object in the range 100 AD–9999 AD. Usage This function does not parse or validate values.

PAGE 431

PAGE 432
CreateODBCDateTime Description Creates an ODBC date-time object. Returns A date/time object, in ODBC timestamp format. Category Date and time functions Function syntax CreateODBCDateTime(date) See also CreateDateTime, CreateODBCDate, CreateODBCTime, Now Parameters Parameter Description date Date/time object in the range 100 AD–9999 AD. Usage When passing a date/time value as a string, you must enclose it in quotation marks.

PAGE 433

PAGE 434
CreateODBCTime Description Creates an ODBC time object. Returns A time object, in ODBC timestamp format. Category Date and time functions Function syntax CreateODBCTime(date) See also CreateODBCDateTime, CreateTime Parameters Parameter Description date Date/time object in the range 100 AD–9999 AD. Usage When passing a date/time value as a string, you must enclose it in quotation marks. Otherwise, it is interpreted as a number representation of a date/time object.

PAGE 435

CreateTime Description Creates a time variable. Returns A time variable. Category Date and time functions Function syntax CreateTime(hour, minute, second) See also CreateODBCTime, CreateDateTime Parameters Parameter Description hour Number in the range 0–23 minute Number in the range 0–59 second Number in the range 0–59 Usage CreateTime is a subset of CreateDateTime. A time variable is a special case of a date/time variable. The date part of a time variable is set to December 30, 1899.

PAGE 436

CreateTimeSpan Description Creates a date/time object that defines a time period. You can add or subtract it from other date/ time objects and use it with the cachedWithin attribute of cfquery. Returns A date/time object.

PAGE 437

Park Name Region State

#GetParks.

PAGE 438

CreateUUID Description Creates a Universally Unique Identifier (UUID). A UUID is a 35-character string representation of a unique 128-bit integer. Returns A ColdFusion format UUID, in the format xxxxxxxx-xxxx-xxxx-xxxxxxxxxxxxxxxx, where x is a hexadecimal digit (0-9 or A-F). (The character groups are 8-4-4-4-16.

PAGE 439

DateAdd Description Adds units of time to a date. Returns A date/time object. Category Date and time functions Function syntax DateAdd("datepart", number, "date") See also DateConvert, DatePart, CreateTimeSpan History ColdFusion MX 6.1: Added the datepart character L or l to represent milliseconds.

PAGE 440

SELECT UserName, Subject, Posted FROMMessages
This example uses DateAdd to determine when a message in the database will expire.

PAGE 441

DateCompare Description Performs a full date/time comparison of two dates. Returns • -1, if date1 is less than date2 • 0, if date1 is equal to date2 • 1, if date1 is greater than date2 Category Date and time functions Function syntax DateCompare("date1", "date2" [, "datePart"]) See also CreateDateTime, DatePart Parameters Parameter Description date1 Date/time object, in the range 100 AD–9999 AD. date2 Date/time object, in the range 100 AD–9999 AD. datePart Optional. String.

PAGE 442

#DateFormat(FORM.date1)# #TimeFormat(FORM.date1)# (Date to #DateFormat(FORM.date2)# #TimeFormat(FORM.date2)# (Date The dates are equal!
#DateFormat(FORM.date1)# #TimeFormat(FORM.date1)# (Date than #DateFormat(FORM.date2)# #TimeFormat(FORM.

PAGE 443

DateConvert Description Converts local time to Coordinated Universal Time (UTC), or UTC to local time. The function uses the daylight savings settings in the executing computer to compute daylight savings time, if required. Returns UTC- or local-formatted time object. Category Date and time functions Function syntax DateConvert("conversion-type", "date") See also GetTimeZoneInfo, CreateDateTime, DatePart Parameters Parameter Description conversion-type • local2Utc: Converts local time to UTC time.

PAGE 444

Your UTC date and time, converted back to local date and time: #DateConvert("utc2local", yourUTC)#.
Type the date and time, and press Enter to see the conversion.

PAGE 445
DateDiff Description Determines the integer number of units by which date1 is less than date2. Returns A number of units, of type datepart. Category Date and time functions Function syntax DateDiff("datepart", "date1", "date2") See also DateAdd, DatePart, CreateTimeSpan History ColdFusion MX: • Changed how negative date differences are calculated: this function calculates negative date differences correctly; its output may be different from that in earlier releases.

PAGE 446

Example
This example uses DateDiff to determine the difference in PAGE 447
Date 2 What kind of unit to show difference?

PAGE 448

DateFormat Description Formats a date value using U.S. date formats. For international date support, use LSDateFormat. Returns A text string representing the date formatted according to the mask. If no mask is specified, returns the value in dd-mmm-yy format.

PAGE 449

Date and time values in database query results can vary in sequence and formatting unless you use functions to format them. To ensure that application users correctly understand displayed dates and times, Macromedia recommends that you use this function and the LSDateFormat, TimeFormat, and LSTimeFormat functions to format resultset values. For more information and examples, see TechNote 22183, "ColdFusion Server (5 and 4.5.x) with Oracle: Formatting Date and Time Query Results," on our website at www.

PAGE 450

DatePart Description Extracts a part from a date value. Returns Part of a date, as an integer. Category Date and time functions Function syntax DatePart("datepart", "date") See also DateAdd, DateConvert History ColdFusion MX 6.1: Added the datepart character L or l to represent milliseconds.

PAGE 451

day: #DatePart("d", todayDate)#
weekday: #DatePart("w", todayDate)#
week: #DatePart("ww", todayDate)#
hour: #DatePart("h", todayDate)#
minute: #DatePart("n", todayDate)#
second: #DatePart("s", todayDate)# DatePart 451

PAGE 452

Day Description Determines the day of the month, in a date. Returns The ordinal for the day of the month, ranging from 1 to 31. Category Date and time functions Function syntax Day("date") See also DayOfWeek, DayOfWeekAsString, DayOfYear, DaysInMonth, DaysInYear, FirstDayOfMonth Parameters Parameter Description date Date/time object, in the range 100 AD–9999 AD. Usage When passing a date/time object as a string, you must enclose it in quotation marks.

PAGE 453

DayOfWeek Description Determines the day of the week, in a date. Returns The ordinal for the day of the week, as an integer in the range 1 (Sunday) to 7 (Saturday). Category Date and time functions Function syntax DayOfWeek("date") See also Day, DayOfWeekAsString, DayOfYear, DaysInMonth, DaysInYear, FirstDayOfMonth Parameters Parameter Description date Date/time object, in the range 100 AD–9999 AD. Usage When passing a date/time object as a string, you must enclose it in quotation marks.

PAGE 454

DayOfWeekAsString Description Determines the day of the week, in a date, as a string function. Returns The day of the week, as a string that corresponds to day_of_week. Category Date and time functions, String functions Function syntax DayOfWeekAsString(day_of_week) See also Day, DayOfWeek, DayOfYear, DaysInMonth, DaysInYear, FirstDayOfMonth Parameters Parameter Description day_of_week Integer, in the range 1 (Sunday) - 7 (Saturday). Example
DayOfWeekAsString Example

PAGE 455

DayOfYear Description Determines the day of the year, in a date. Returns The ordinal value of day of the year, as an integer. Category Date and time functions Function syntax DayOfYear("date") See also Day, DayOfWeek, DayOfWeekAsString, DaysInMonth, DaysInYear, FirstDayOfMonth Parameters Parameter Description date Date/time object, in the range 100 AD–9999 AD. Usage This function accounts for leap years. When passing a date/time object as a string, you must enclose it in quotation marks.

PAGE 456

DaysInMonth Description Determines the number of days in a month. Returns The number of days in the month in Date. Category Date and time functions Function syntax DaysInMonth("date") See also Day, DayOfWeek, DayOfWeekAsString, DayOfYear, DaysInYear, FirstDayOfMonth Parameters Parameter Description date Date/time object, in the range 100 AD–9999 AD. Usage When passing a date/time object as a string, you must enclose it in quotation marks.

PAGE 457

DaysInYear Description Determines the number of days in a year. Returns The number of days in a year. Category Date and time functions Function syntax DaysInYear("date") See also Day, DayOfWeek, DayOfWeekAsString, DayOfYear, DaysInMonth, DaysInYear, FirstDayOfMonth, IsLeapYear Parameters Parameter Description date • Date/time object, in the range 100 AD–9999 AD. Usage DaysInYear accounts for leap years. When passing a date/time object as a string, you must enclose it in quotation marks.

PAGE 458

DE Description Postpones evaluation of a string as an expression, when it is passed as a parameter to the IIf or Evaluate functions. Escapes any double quotation marks in the parameter and wraps the result in double quotation marks. This function is especially useful with the IIf function, to prevent the function from evaluating a string that is to be output. This applies to expressions that are not surrounded by pound signs.

PAGE 459

For more information and code examples, see Chapter 4, “Using Expressions and Pound Signs,” in Developing ColdFusion MX Applications. Example
DE Example

The Expression Result

PAGE 460

DecimalFormat Description Converts a number to a decimal-formatted string. Returns A number as a string formatted with two decimal places and a thousands separator. Category Display and formatting functions Function syntax DecimalFormat(number) See also DollarFormat, NumberFormat Parameters Parameter Description number Number to format Example
DecimalFormat Function

Returns a number to two decimal places.

PAGE 461

DecrementValue Description Decrements the integer part of a number. Returns Integer part of number, decremented by one. Category Mathematical functions Function syntax DecrementValue(number) See also IncrementValue Parameters Parameter Description number Number to decrement Example
DecrementValue Example

Returns the integer part of a number decremented by one.

PAGE 462

Decrypt Description Decrypts a string that is encrypted with the Encrypt function. Returns String, unencrypted. Category Other functions, String functions Function syntax Decrypt(encrypted_string, seed) See also Duplicate, Encrypt Parameters Parameter Description encrypted_string String or a variable that contains one. String to decrypt seed String. The 32-bit key that was used to encrypt the string.

PAGE 463

DeleteClientVariable Description Deletes a client variable. (To test for the existence of a variable, use IsDefined.) Returns True, if the variable is successfully deleted; false, otherwise. Category Other functions Function syntax DeleteClientVariable("name") See also GetClientVariablesList History ColdFusion MX: Changed behavior: if the variable is not present, this function now returns False. (In earlier releases, it threw an error.

PAGE 464

DirectoryExists Description Determines whether a directory exists. Returns Yes, if the specified directory exists; No, otherwise. Category System functions Function syntax DirectoryExists(absolute_path) See also FileExists Parameters Parameter Description absolute_path An absolute path Example
DirectoryExists Example

Enter a directory to check for existence.
PAGE 465
DollarFormat Description Formats a string in U.S. format. (For other currencies, use LSCurrencyFormat or LSEuroCurrencyFormat.) Returns A number as a string, formatted with two decimal places, thousands separator, and dollar sign. If number is negative, the return value is enclosed in parentheses. If number is an empty string, returns zero.

PAGE 466

Duplicate Description Returns a clone, also known as a deep copy, of a variable. There is no reference to the original variable. Returns A clone of a variable. Category Structure functions, System functions Function syntax Duplicate(variable_name) See also StructCopy, other Structure functions History ColdFusion MX: Changed behavior: this function can be used on XML objects.

PAGE 467

Encrypt Description Encrypts a string. Uses a symmetric key-based algorithm, in which the same key is used to encrypt and decrypt a string. The security of the encrypted string depends on maintaining the secrecy of the key. Uses an XOR-based algorithm that uses a pseudo-random 32-bit key, based on a seed passed by the user as a function parameter. Returns String; can be much longer than the original string.

PAGE 468

Evaluate Description Evaluates one or more string expressions, dynamically, from left to right. (The results of an evaluation on the left can have meaning in an expression to the right.) Returns the result of evaluating the rightmost expression. Returns An object; the result of the evaluation(s). Category Dynamic evaluation functions Function syntax Evaluate(string_expression1 [, string_expression2 [, … ] ] ) See also DE, IIf Parameters Parameter Description string_expression1, string_expression2...

PAGE 469

Exp Description Calculates the exponent whose base is e that represents number. The constant e equals 2.71828182845904, the base of the natural logarithm. This function is the inverse of Log, the natural logarithm of number. Returns The constant e, raised to the power of number.

PAGE 470

ExpandPath Description Creates an absolute, platform-appropriate path that is equivalent to the value of relative_path, appended to the base path. This function (despite its name) can accept an absolute or relative path in the relative_path attribute The base path is the currently executing page’s directory path. It is stored in pageContext.getServletContext(). Returns A string. If the relative path contains a trailing forward slash or backward slash, the return value contains the same trailing character.

PAGE 471

The current directory is: #GetDirectoryFromPath(thisPath)#
Your file exists in this directory.

PAGE 472

FileExists Description Determines whether a file exists. Returns Yes, if the file specified in the parameter exists; No, otherwise. Category System functions, Decision functions Function syntax FileExists(absolute_path) See also DirectoryExists, ExpandPath, GetTemplatePath Parameters Parameter Description absolute_path An absolute path Example
FileExists Example

PAGE 473

Find Description Finds the first occurrence of a substring in a string, from a specified start position. The search is case-sensitive. Returns A number; the position of substring in string; or 0, if substring is not in string. Category String functions Function syntax Find(substring, string [, start ]) See also FindNoCase, Compare, FindOneOf, REFind, Replace Parameters Parameter Description substring A string or a variable that contains one. String for which to search.

PAGE 474

FindNoCase Description Finds the first occurrence of a substring in a string, from a specified start position. If substring is not in string, returns zero. The search is case-insensitive. Returns The position of substring in string; or 0, if substring is not in string. Category String functions Function syntax FindNoCase(substring, string [, start ]) See also Find, CompareNoCase, FindOneOf, REFind, Replace Parameters Parameter Description substring A string or a variable that contains one.

PAGE 475

FindOneOf Description Finds the first occurrence of any one of a set of characters in a string, from a specified start position. The search is case-sensitive. Returns The position of the first member of set found in string; or 0, if no member of set is found in string. Category String functions Function syntax FindOneOf(set, string [, start ]) See also Find, Compare, REFind Parameters Parameter Description set A string or a variable that contains one.

PAGE 476

FirstDayOfMonth Description Determines the ordinal (day number, in the year) of the first day of the month in which a given date falls. Returns A number corresponding to a day-number in a year. Category Date and time functions Function syntax FirstDayOfMonth(date) See also Day, DayOfWeek, DayOfWeekAsString, DayOfYear, DaysInMonth, DaysInYear Parameters Parameter Description date Date/time object, in the range 100 AD–9999 AD.

PAGE 477

Fix Description Converts a real number to an integer. Returns If number is greater than or equal to 0, the closest integer less than number. If number is less than 0, the closest integer greater than number. Category Mathematical functions Function syntax Fix(number) See also Ceiling, Int, Round Parameters Parameter Description number A number Example
Fix Example

Fix returns the closest integer less than the number if the number is greater than or equal to 0.

PAGE 478

FormatBaseN Description Converts number to a string, in the base specified by radix. Returns String that represents number, in the base radix. Category Display and formatting functions, Mathematical functions, String functions Function syntax FormatBaseN(number, radix) See also InputBaseN Parameters Parameter Description number Number to convert radix Base of the result Example
FormatBaseN Example

Converts a number to a string in the base specified by Radix.

PAGE 479

GetAuthUser Description Gets the name of an authenticated user. Returns The name of an authenticated user. Category Authentication functions Function syntax GetAuthUser() See also IsUserInRole, cflogin, cfloginuser, Chapter 16, “Securing Applications,” in Developing ColdFusion MX Applications History ColdFusion MX: Added this function. Usage This function works with cflogin authentication or web server authentication.

PAGE 480

GetBaseTagData Description Used within a custom tag. Finds calling (ancestor) tag by name and accesses its data. Returns An object that contains data (variables, scopes, and so on) from an ancestor tag. If there is no ancestor by the specified name, or if the ancestor does not expose data (for example, cfif ), an exception is thrown.

PAGE 481

GetBaseTagList Description Gets ancestor tag names, starting with the parent tag. Returns A comma-delimited list of uppercase ancestor tag names, as a string. The first list element is the current tag. If the current tag is nested, the next element is the parent tag. If the function is called for a top-level tag, it returns an empty string. If an ancestor does not expose data (see GetBaseTagData), its name might not be returned.

PAGE 482

GetBaseTemplatePath Description Gets the absolute path of an application’s base page. Returns The absolute path of the application base page, as a string.

PAGE 483

GetClientVariablesList Description Finds the client variables to which a page has write access. Returns Comma-delimited list of non-read-only client variables, as a string. Category List functions, Other functions Function syntax GetClientVariablesList() See also DeleteClientVariable Usage The list of variables returned by this function is compatible with ColdFusion list functions.

PAGE 484

GetCurrentTemplatePath Description Gets the path of the page that calls this function. Returns The absolute path of the page that contains the call to this function, as a string. Category System functions Function syntax GetCurrentTemplatePath() See also GetBaseTemplatePath, FileExists, ExpandPath Usage If the function call is made from a page included with a cfinclude tag, this function returns the page path of an included page.

PAGE 485

GetDirectoryFromPath Description Extracts a directory from an absolute path. Returns Absolute path, without the filename. The last character is a forward or backward slash, depending on the operating system. Category System functions Function syntax GetDirectoryFromPath(path) See also ExpandPath, GetFileFromPath Parameters Parameter Description path Absolute path (drive, directory, filename, and extension) Example
GetDirectoryFromPath Example

PAGE 486

---> 486 Chapter 3: ColdFusion Functions

PAGE 487

GetEncoding Description Returns the encoding (character set) of the Form or URL scope. Returns String; the character encoding of the specified scope. Category International functions, System functions Function syntax GetEncoding(scope_name) See also SetEncoding, cfcontent, cfprocessingdirective, URLDecode, URLEncodedFormat History ColdFusion MX: Added this function. Parameters Parameter Description scope_name • Form • URL.

PAGE 488

GetException Description Used with the cftry and cfcatch tags. Retrieves a Java exception object from a Java object. Returns Any Java exception object raised by a previous method call on the Java object. Category System functions Syntax getException(object) Parameters Parameter Description object A Java object. Usage ColdFusion stores a Java exception object for each method call on a Java object. Subsequent method calls reset the exception object.

PAGE 489

GetFileFromPath Description Extracts a filename from an absolute path. Returns Filename, as a string. Category System functions Function syntax GetFileFromPath(path) See also ExpandPath, GetCurrentTemplatePath Parameters Parameter Description path Absolute path (drive, directory, filename, and extension) Example
GetFileFromPath Example

PAGE 490

GetFunctionList Description Displays a list of the functions that are available in ColdFusion. Returns A structure of functions. Category System functions Function syntax GetFunctionList() Example

PAGE 513

Hash Description Converts a variable-length string to a 32-byte, hexadecimal string, using the MD5 algorithm. (It is not possible to convert the hash result back to the source string.) Returns 32-byte, hexadecimal string Category Conversion functions, Other functions, String functions Function syntax Hash(string) Parameters Parameter Description string A string or a variable that contains one. Usage The result is useful for comparison and validation.

PAGE 514

Hour Description Gets the current hour of the day. Returns Ordinal value of the hour, in the range 0 - 23. Category Date and time functions Function syntax Hour(date) See also DatePart, Minute, Second Parameters Parameter Description date Date/time object, in the range 100 AD–9999 AD. Usage When passing a date/time value as a string, you must enclose it in quotation marks. Otherwise, it is interpreted as a number representation of a date/time object.

PAGE 515

HTMLCodeFormat Description Replaces special characters in a string with their HTML-escaped equivalents and inserts
and
tags at the beginning and end of the string. Returns HTML-escaped string string, enclosed in
and
tags. Returns are removed from string. Special characters (> < " &) are escaped.

PAGE 516

HTMLEditFormat Description Replaces special characters in a string with their HTML-escaped equivalents. Returns HTML-escaped string string. Returns are removed from string. Special characters (for example, < " &) are escaped. Category Display and formatting functions Function syntax HTMLEditFormat(string [, version ]) See also HTMLCodeFormat Parameters Parameter Description string A string or a variable that contains one. version HTML version to use. currently ignored.

PAGE 517

IIf Description Evaluates a Boolean conditional dynamic expression. Depending on whether the expression is true or false, dynamically evaluates one of two string expressions and returns the result. This function is convenient for incorporating a cfif tag in-line in HTML. For general conditional processing, see cfif. For error handling, see cftry. For more information, see Developing ColdFusion MX Applications.

PAGE 518

Note: If you use pound signs (#) in string_expression1 or string_expression2, ColdFusion evaluates the part of the expression in pound signs first. If you misuse the pound signs, you can cause unexpected results from the IIf function.

PAGE 519

IIf 519

PAGE 520

IncrementValue Description Adds one to an integer. Returns The integer part of number, incremented by one. Category Mathematical functions Function syntax IncrementValue(number) See also DecrementValue Parameters Parameter Description number Number to increment Example
IncrementValue Example

Returns the integer part of a number incremented by one.

PAGE 521

InputBaseN Description Converts string, using the base specified by radix, to an integer. Returns A number in the range 2-36, as a string. Category Mathematical functions Function syntax InputBaseN(string, radix) See also FormatBaseN Parameters Parameter Description string A string or a variable that contains one. String that represents a number, in the base specified by radix. radix Base of the number represented by string, in the range 2 — 36.

PAGE 522

Insert Description Inserts a substring in a string after a specified character position. If position = 0, prefixes the substring to the string. Returns A string. Category String functions Function syntax Insert(substring, string, position) See also RemoveChars, Len Parameters Parameter Description substring A string or a variable that contains one. String to insert. string A string or a variable that contains one. String into which to insert substring.

PAGE 523

Int Description Calculates the closest integer that is smaller than number. Returns An integer, as a string. Category Mathematical functions Function syntax Int(number) See also Ceiling, Fix, Round Parameters Parameter Description number Real number to round down to an integer Example
Int Example

Int returns the closest integer smaller than a number.
Int(11.7) : #Int(11.7)#
Int(-11.7) : #Int(-11.

PAGE 524

IsArray Description Determines whether a value is an array. Returns True, if value is an array, or a query column object. Category Array functions, Decision functions Function syntax IsArray(value [, number ]) See also Array functions History ColdFusion MX: • Changed behavior: if the value attribute contains a reference to a query result column, this • function now returns True. For example: isArray(MyQuery[’Column1’]) returns True. (In earlier releases, it returns False.

PAGE 525

IsAuthenticated Description This function is obsolete. Use the newer security tools; see “Authentication functions” on page 367 and Chapter 16, “Securing Applications,” in Developing ColdFusion MX Applications. History ColdFusion MX: This function is obsolete. It does not work in ColdFusion MX and later ColdFusion releases.

PAGE 526

IsAuthorized Description This function is obsolete. Use the newer security tools; see “Authentication functions” on page 367 and Chapter 16, “Securing Applications,” in Developing ColdFusion MX Applications History ColdFusion MX: This function is obsolete. It does not work in ColdFusion MX and later releases.

PAGE 527

IsBinary Description Determines whether a value is stored as binary data. Returns True, if the value is binary; False, otherwise. Category Decision functions Function syntax IsBinary(value) See also ToBinary, ToBase64, IsNumeric, YesNoFormat Parameters Parameter Description value Number or string Example IsStruct 547

PAGE 548

IsUserInRole Description Determines whether an authenticated user belongs to the specified Role. Returns True, if the authenticated user, belongs to the specified Role; False, otherwise. Category Authentication functions, Decision functions Function syntax IsUserInRole("role_name") See also GetAuthUser, cflogin, cfloginuser, Chapter 16, “Securing Applications,” in Developing ColdFusion MX Applications History ColdFusion MX: Added this function.

PAGE 549

IsWDDX Description Determines whether a value is a well-formed WDDX packet. Returns True, if the value is a well-formed WDDX packet; False, otherwise. Category Decision functions, XML functions Syntax IsWDDX(value) History ColdFusion MX: Changed behavior: if the value parameter is not a WDDX packet, ColdFusion returns False. (In earlier releases, ColdFusion threw an error.

PAGE 550

IsWDDX() returns #IsWDDX(packet)#
550 Chapter 3: ColdFusion Functions

PAGE 551

IsXmlDoc Description Determines whether a function parameter is an Extended Markup language (XML) document object. Returns True, if the function argument is an XML document object; False, otherwise. Category Decision functions, XML functions Function syntax IsXmlDoc(value) See also IsXmlElem, IsXmlRoot, XmlChildPos, XmlNew, XmlParse, XmlSearch, XmlTransform History ColdFusion MX: Added this function.

PAGE 552

IsXmlElem Description Determines whether a function parameter is an Extended Markup language (XML) document object element. Returns True, if the function argument is an XML document object element; False, otherwise. Category Decision functions, XML functions Function syntax IsXmlElem(value) See also IsXmlDoc, IsXmlRoot, XmlChildPos, XmlNew, XmlParse, XmlSearch, XmlTransform History ColdFusion MX: Added this function.

PAGE 553

IsXmlRoot Description Determines whether a function parameter is the root element of an Extended Markup language (XML) document object. Returns True, if the function argument is the root object of an XML document object; False, otherwise. Category Decision functions, XML functions Function syntax IsXmlRoot(value) See also IsXmlDoc, IsXmlElem, XmlChildPos, XmlNew, XmlParse, XmlSearch, XmlTransform History ColdFusion MX: Added this function.

PAGE 554

JavaCast Description Converts the data type of a ColdFusion variable to pass as an argument to an overloaded method of a Java object. Use only for scalar and string arguments. Returns The variable, as type type.

PAGE 555

} Within ColdFusion, you use the following code: Perform an explicit cast to an int and call fooMethod:
#obj.fooMethod(myInt)#

Perform an explicit cast to a string and call fooMethod:
#obj.

PAGE 556

JSStringFormat Description Escapes special JavaScript characters, such as single quotation mark, double quotation mark, and newline. Returns A string that is safe to use with JavaScript. Category String functions Function syntax JSStringFormat(string) Parameters Parameter Description string A string or a variable that contains one. Usage Escapes special JavaScript characters, so you can put arbitrary strings safely into JavaScript.

PAGE 557

LCase Description Converts the alphabetic characters in a string to lowercase. Returns A string, converted to lowercase. Category String functions Function syntax LCase(string) See also UCase Parameters Parameter Description string A string or a variable that contains one Example
LCase Example

Your text, #FORM.sampleText#, returned in lowercase is #LCase(FORM.sampleText)# .

PAGE 558

Left Description Returns the leftmost count characters in a string. Returns String; the first count characters in the string parameter. Category String functions Function syntax Left(string, count) See also Right, Mid, Len Parameters Parameter Description string A string or a variable that contains one. count A positive integer or a variable that contains one. Number of characters to return. Example
Left Example

PAGE 559

PAGE 560

Len Description Determines the length of a string or binary object. Returns Number; length of a string or a binary object. Category String functions Function syntax Len(string or binary object) See also ToBinary, Left, Right, Mid History ColdFusion MX: Changed Unicode support: ColdFusion supports the Java UCS-2 representation of Unicode character values 0–65535. (ColdFusion 5 and earlier releases supported ASCII values 1–255.

PAGE 561

ListAppend Description Concatenates a list or element to a list. Returns A copy of the list, with value appended. If delimiter = "", returns a copy of the list, unchanged. Category List functions Function syntax ListAppend(list, value [, delimiters ]) See also ListPrepend, ListInsertAt, ListGetAt, ListLast, ListSetAt Parameters Parameter Description list A list or a variable that contains one. value An element or a list of elements. delimiters A string or a variable that contains one.

PAGE 562

SELECT PARKNAME,CITY,STATE FROM PARKS WHERE PARKNAME LIKE ‘AL%’
The original list: #temp# ...

PAGE 563

ListChangeDelims Description Changes a list delimiter. Returns A copy of the list, with each delimiter character replaced by new_delimiter. Category List functions Function syntax ListChangeDelims(list, new_delimiter [, delimiters ]) See also ListFirst, ListQualify Parameters Parameter Description list A list or a variable that contains one. new_delimiter Delimiter string or a variable that contains one. Can be an empty string. ColdFusion processes the string as one delimiter.

PAGE 564

ListContains Description Determines the index of the first list element that contains a specified substring. Returns Index of the first list element that contains substring. If not found, returns zero. Category List functions Function syntax ListContains(list, substring [, delimiters ]) See also ListContainsNoCase, ListFind Parameters Parameter Description list A list or a variable that contains one. substring A string or a variable that contains one. The search is case-sensitive.

PAGE 565

The string "two" is in element #ListFind(aList, "two")# of the list.

PAGE 566

ListContainsNoCase Description Determines the index of the first list element that contains a specified substring. Returns Index of the first list element that contains substring, regardless of case. If not found, returns zero. Category List functions Function syntax ListContainsNoCase(list, substring [, delimiters ]) See also ListContains, ListFindNoCase Parameters Parameter Description list A list or a variable that contains one. substring A string or a variable that contains one.

PAGE 567

ListDeleteAt Description Deletes an element from a list. Returns A copy of the list, without the specified element. Category List functions Function syntax ListDeleteAt(list, position [, delimiters ]) See also ListGetAt, ListSetAt, ListLen Parameters Parameter Description list A list or a variable that contains one. position A positive integer or a variable that contains one. Position at which to delete element. The first list position is 1. delimiters A string or a variable that contains one.

PAGE 568

The changed list: #temp2#
This list element:
#deleted_element#
is no longer present at position three of the list.

PAGE 569

ListFind Description Determines the index of the first list element in which a specified value occurs. Case-sensitive. Returns Index of the first list element that contains value, with matching case. If not found, returns zero. The search is case-sensitive.

PAGE 570

An employee with that exact last name was not found

Employee #ListGetAt(ValueList(SearchEmpLastName.FirstName), temp)# #ListGetAt(ValueList(SearchEmpLastName.LName), temp)#, of the #ListGetAt(ValueList(SearchEmpLastName.Department), temp)# Department, can be reached at #ListGetAt(ValueList(SearchEmpLastName.

PAGE 571

ListFindNoCase Description Determines the index of the first list element in which a specified value occurs. Returns Index of the first list element that contains value. If not found, returns zero. The search is caseinsensitive. Category List functions Function syntax ListFindNoCase(list, value [, delimiters ]) See also ListContains, ListFind Parameters Parameter Description list A list or a variable that contains one. value Number or string for which to search. The search is case-insensitive.

PAGE 572

An employee with that exact last name was not found

Employee #ListGetAt(ValueList(SearchEmpLastName.FirstName), temp)# #ListGetAt(ValueList(SearchEmpLastName.LName), temp)#, of the #ListGetAt(ValueList(SearchEmpLastName.Department), temp)# Department, can be reached at #ListGetAt(ValueList(SearchEmpLastName.Phone), temp)#.

PAGE 573

ListFirst Description Gets the first element of a list. Returns The first element of a list. If the list is empty, returns an empty string. Category List functions Function syntax ListFirst(list [, delimiters ]) See also ListGetAt, ListLast, ListQualify Parameters Parameter Description list A list or a variable that contains a list. delimiters A string or a variable that contains one. Character(s) that separate list elements. Default: comma.

PAGE 574

ListGetAt Description Gets a list element at a specified position. Returns Index of the list element at position position. Category List functions Function syntax ListGetAt(list, position [, delimiters ]) See also ListFirst, ListLast, ListQualify, ListSetAt Parameters Parameter Description list A list or a variable that contains one. position A positive integer or a variable that contains one. Position at which to get element. The first list position is 1.

PAGE 575

Username #Counter#: #ListGetAt(temp, Counter)# ListGetAt 575

PAGE 576

ListInsertAt Description Inserts an element in a list. Returns A copy of the list, with value inserted at the specified position. Category List functions Function syntax ListInsertAt(list, position, value [, delimiters ]) See also ListDeleteAt, ListAppend, ListPrepend, ListSetAt Parameters Parameter Description list A list or a variable that contains one. position A positive integer or a variable that contains one. Position at which to insert element. The first list position is 1.

PAGE 577

ListLast Description Gets the last element of a list. Returns The last element of the list. Category List functions Function syntax ListLast(list [, delimiters ]) See also ListGetAt, ListFirst Parameters Parameter Description list A list or a variable that contains a list. delimiters A string or a variable that contains one. Character(s) that separate list elements. Default: comma.

PAGE 578

(Users who posted more than once are listed more than once.

PAGE 579

ListLen Description Determines the number of elements in a list. Integer; the number of elements in a list. Category List functions Function syntax ListLen(list [, delimiters ]) See also ListAppend, ListDeleteAt, ListInsertAt, ListPrepend Parameters Parameter Description list A list or a variable that contains one. delimiters A string or a variable that contains one. Character(s) that separate list elements. Default: comma.

PAGE 580

ListPrepend Description Inserts an element at the beginning of a list. Returns A copy of the list, with value inserted at the first position. Category List functions Function syntax ListPrepend(list, value [, delimiters ]) See also ListAppend, ListInsertAt, ListSetAt Parameters Parameter Description list A list or a variable that contains one. value An element or a list of elements. delimiters A string or a variable that contains one. Character(s) that separate list elements. Default: comma.

PAGE 581

The original list: #temp# ListPrepend 581

PAGE 582

ListQualify Description Inserts a string at the beginning and end of list elements. Returns A copy of the list, with qualifier before and after the specified element(s). Category List functions Function syntax ListQualify(list, qualifier [, delimiters ] [, elements ]) History ColdFusion MX: Changed behavior: as the elements parameter value, you must specify "all" or "char"; otherwise, ColdFusion throws an exception.

PAGE 583

The contents of the unqualified list are as follows:
#myList#
There are no employees in #FORM.departmentName#

There is only one person in #FORM.departmentName#.

PAGE 594

LJustify Description Left justifies characters in a string of a specified length. Returns A copy of a string, left-justified.

PAGE 595

Log Description Calculates the natural logarithm of a number. Natural logarithms are based on the constant e (2.71828182845904). Returns The natural logarithm of a number. Category Mathematical functions Function syntax Log(number) See also Exp, Log10 Parameters Parameter Description number Positive real number for which to calculate the natural logarithm Example
Log Example

Your number, #FORM.number#
#FORM.

PAGE 596

Log10 Description Calculates the logarithm of number, to base 10. Returns Number; the logarithm of number, to base 10. Category Mathematical functions Function syntax Log10(number) See also Exp, Log Parameters Parameter Description number Positive real number for which to calculate the logarithm Example
Log10 Example

Your number, #FORM.number#
#FORM.number# raised to the E power: #exp(FORM.number)#

PAGE 597

LSCurrencyFormat Description Formats a number in a locale-specific currency format. For countries that use the euro, the result depends on the JVM. Returns A formatted currency value.

PAGE 598

Locale Type = Local Type = International Type = None Chinese (Taiwan) NT$100,000.00 TWD100,000.00 100,000.00 Dutch (Belgian) 100.000,00 ¤ 100.000,00 BF BEF100.000,00 EUR100.000,00 100.000,00 Dutch (Standard) ¤ 100.000,00 fl 100.000,00 NLG100.000,00 EUR100.000,00 100.000,00 English (Australian) $100,000.00 AUD100,000.00 100,000.00 English (Canadian) $100,000.00 CAD100,000.00 100,000.00 English (New Zealand) $100,000.00 NZD100,000.00 100,000.00 English (UK) £100,000.

PAGE 599

Note: ColdFusion maps Spanish (Modern) to the Spanish (Standard) format. To set the default display format of date, time, number, and currency values, use the SetLocale function. Example
LSCurrencyFormat Example

LSCurrencyFormat returns a currency value using the locale convention. Default value is "local." PAGE 600
LSDateFormat Description Formats the date part of a date/time value in a locale-specific format. Returns A formatted date/time value. If no mask is specified, the value is formatted according to the locale setting of the client computer.

PAGE 601

When passing date/time value as a string, enclose it in quotation marks. Otherwise, it is interpreted as a number representation of a date/time object. To calculate a difference between time zones, use the GetTimeZoneInfo function. Example
LSDateFormat Example

LSDateFormat formats the date part of a date/time value using the locale convention. PAGE 602
LSEuroCurrencyFormat Description Formats a number in a locale-specific currency format. Returns A formatted currency value. For countries in the Euro currency zone, the function uses the locale’s rule’s for formatting currency in euros.

PAGE 603

Currency output The following table shows examples of currency output: Locale Type = Local Type = International Type = None Chinese (China) ¥100,000.00 CNY100,000.00 100,000.00 Chinese (Hong Kong) HK$100,000.00 HKD100,000.00 100,000.00 Chinese (Taiwan) NT$100,000.00 TWD100,000.00 100,000.00 Dutch (Belgian) 100.000,00 ¤ EUR100.000,00 100.000,00 Dutch (Standard) ¤ 100.000,00 EUR100.000,00 100.000,00 English (Australian) $100,000.00 AUD100,000.00 100,000.

PAGE 604

The following example shows how the function formats negative values. The format includes a negative sign before the value, or parentheses around the value, according to the formatting rules of the current locale. Input value Output if locale = French (Standard) Output if locale = English (US) -1234.56 -1 234,56 ¤ ($1,234.56) Example
LSEuroCurrencyFormat Example

LSEuroCurrencyFormat returns a currency value using the locale convention. Default value is "local.

PAGE 605

LSIsCurrency Description Determines whether a string is a valid representation of a currency amount in the current locale. Returns True, if the parameter is formatted as a valid currency amount, including the appropriate currency indicator. Returns True for amounts in the local, international, or none currency formats.

PAGE 606

PAGE 607
LSIsDate Description Determines whether a string is a valid representation of a date/time value in the current locale. Returns True, if the string can be formatted as a date/time value in the current locale; False, otherwise.

PAGE 608

608 Chapter 3: ColdFusion Functions

PAGE 609

LSIsNumeric Description Determines whether a string is a valid representation of a number in the current locale. Returns True, if the string represents a number the current locale; False, otherwise. Category Decision functions, International functions, String functions Function syntax LSIsNumeric(string) See also GetLocale, SetLocale History ColdFusion MX: Changed formatting behavior: this function might return a different result than in earlier releases.

PAGE 610

LSNumberFormat Description Formats a number in a locale-specific format. Returns A formatted number. • • • • If no mask is specified, it returns the number formatted as an integer If no mask is specified, truncates the decimal part; for example, it truncates 34.57 to 35 If the specified mask cannot correctly mask a number, it returns the number unchanged If the parameter value is "" (an empty string), it returns 0.

PAGE 611

Character Meaning - Puts space before positive number; minus sign before negative number. , Separates every third decimal place with a comma (or locale-appropriate symbol). L,C Left-justifies or center-justifies number within width of mask column. First character of mask must be L or C. Default: right-justified. $ Puts a dollar sign (or locale-appropriate symbol) before formatted number. First character of mask must be the dollar sign ($). ^ Separates left and right formatting.

PAGE 612

Number Mask Result 3.21 C(__^)__ "( 3.21) " 3.21 C__(^)__ " (3.21) " To set the default display format of date, time, number, and currency values, use the SetLocale function. When converting from string to double, to prevent rounding errors, this function adds a rounding factor of 1.5543122344752E-014 to the converted number. For example, without adding the rounding factor, converting the string value 1.275 to double with two digits of precision results in a value of 1.

PAGE 613

LSParseCurrency Description Converts a locale-specific currency string into a formatted number. Attempts conversion by comparing the string with each the three supported currency formats (none, local, international) and using the first that matches. Returns A formatted number (string representation of a number) that matches the value of the parameter.

PAGE 614

#locale#
Local: #LSCurrencyFormat(123456.78, "local")#
Parsed local Currency: #LSParseCurrency(LSCurrencyFormat(123456,"local"))#
International: #LSCurrencyFormat(123456.

PAGE 615

LSParseDateTime Description Converts a string that is a valid date/time representation in the current locale into a date/time object. Returns A date/time object.

PAGE 616

Valid dates are in the range 100 AD–9999 AD. Two digit years in the range 00-29 are interpreted as being 2000-2029. Two digit years in the range 30-99 are interpreted as being 1930-1999 This function corrects for differences between the current time zone and any time zone specified in the input parameter. • If a time zone specified in the date/time-string parameter is different from the time zone • setting of the computer, ColdFusion adjusts the time value to its equivalent in the computer time zone.

PAGE 617

LSParseEuroCurrency Description Formats a locale-specific currency string as a number. Attempts conversion through each of the default currency formats (none, local, international). Ensures correct handling of euro currency for Euro zone countries. Returns A formatted number that matches the value of the string.

PAGE 618

Value with International currency formatting: #IntlCurrency#
Parsed using LSParseEuroCurrency: #LSParseEuroCurrency(IntlCurrency)#
Value with no currency formatting: #currency#
Parsed using LSParseEuroCurrency: #LSParseEuroCurrency(Currency)#

618 Chapter 3: ColdFusion Functions

PAGE 619

LSParseNumber Description Converts a string that is a valid numeric representation in the current locale into a formatted number. Returns A formatted number that matches the value of the string. Category International functions, String functions Function syntax LSParseNumber(string) See also LSParseDateTime, SetLocale History ColdFusion MX: Changed formatting behavior: this function might return different formatting than in earlier releases.

PAGE 620

620 Chapter 3: ColdFusion Functions

PAGE 621

LSTimeFormat Description Formats the time part of a date/time string into a string in a locale-specific format. Returns A string representing the time value. Category Date and time functions, Display and formatting functions, International functions Function syntax LSTimeFormat(time [, mask ]) See also LSParseDateTime, LSDateFormat, TimeFormat History ColdFusion MX 6.1: Added the mask character L or l to represent milliseconds.

PAGE 622

Usage This function uses Java standard locale formatting rules on all platforms. When passing date/time value as a string, enclose it in quotation marks. Otherwise, it is interpreted as a number representation of a date/time object. To calculate a difference between time zones, use the GetTimeZoneInfo function. To set the default display format of date, time, number, and currency values, use the SetLocale function.

PAGE 623

LTrim Description Removes leading spaces from a string. Returns A copy of the string, without leading spaces. Category Display and formatting functions, String functions Function syntax LTrim(string) See also RTrim, ToBase64 Parameters Parameter Description string A string or a variable that contains one Example
LTrim Example

Your string:"#FORM.myText#" Your string:"#LTrim(FORM.

PAGE 624

Max Description Determines the greater of two numbers. Returns The greater of two numbers. Category Mathematical functions Function syntax Max(number1, number2) See also Min Parameters Parameter Description number1, number2 Numbers Example
Max Example

The maximum of the two numbers is #Max(FORM.myNum1, FORM.myNum2)#
The minimum of the two numbers is #Min(FORM.

PAGE 625

Mid Description Extracts a substring from a string. Returns A string; the set of characters from string, beginning at start, of length count. Category String functions Function syntax Mid(string, start, count) See also Left, Len, Right Parameters Parameter Description string A string or a variable that contains one. Must be single-quote or double-quote delimited. start A positive integer or a variable that contains one. Position at which to start count. Positions start with 1, not 0.

PAGE 626

Min Description Determines the lesser of two numbers. Returns The lesser of two numbers. Category Mathematical functions Function syntax Min(number1, number2) See also Max Parameters Parameter Description number1, number2 Numbers Example
Min Example

The maximum of the two numbers is #Max(FORM.myNum1, FORM.myNum2)#
The minimum of the two numbers is #Min(FORM.

PAGE 627

Minute Description Extracts the minute value from a date/time object. Returns The ordinal value of the minute, in the range 0–59. Category Date and time functions Function syntax Minute(date) See also DatePart, Hash, Second Parameters Parameter Description date • A date/time object, in the range 100 AD–9999 AD. Usage When passing a date/time value as a string, you must enclose it in quotation marks. Otherwise, it is interpreted as a number representation of a date/time object.

PAGE 628

Month Description Extracts the month value from a date/time object. Returns The ordinal value of the month, in the range 1 (January) – 12 (December). Category Date and time functions Function syntax Month(date) See also DatePart, MonthAsString, Quarter Parameters Parameter Description date Date/time object, in the range 100 AD–9999 AD. Usage When passing a date/time value as a string, you must enclose it in quotation marks.

PAGE 629

MonthAsString Description Determines the name of the month that corresponds to month_number. Returns A string; the name of a month. Category Date and time functions, String functions Function syntax MonthAsString(month_number) See also DatePart, Month, Quarter Parameters Parameter Description month_number An integer in the range 1 – 12. Example
MonthAsString Example

More information about your date:

PAGE 630

Now Description Gets the current date and time of the computer running the ColdFusion server. The return value can be passed as a parameter to date functions such as DaysInYear or FirstDayOfMonth. Returns A date/time object; the current date and time of the computer running the ColdFusion server. Category Date and time functions Function syntax Now() See also CreateDateTime, DatePart Example
Now Example

Now returns the current date and time as a valid date/time object.

PAGE 631

NumberFormat Description Creates a custom-formatted number value. Supports the numeric formatting used in the U.S. For international number formatting, see LSNumberFormat. Returns A formatted number value: • If no mask is specified, returns the value as an integer with a thousands separator. • If the parameter value is "" (an empty string), returns 0.

PAGE 632

Mask character Meaning $ Puts a dollar sign before formatted number. First character of mask must be the dollar sign ($). ^ Separates left and right formatting. Note: If you do not specify a sign for the mask, positive and negative numbers do not align in columns. To put a plus sign or space before positive numbers and a minus sign before negative numbers, use the plus or minus sign, respectively. Usage This function uses Java standard locale formatting rules on all platforms.

PAGE 633

When converting from string to double, to prevent rounding errors, this function adds a rounding factor of 1.5543122344752E-014 to the converted number. For example, without adding the rounding factor, converting the string value 1.275 to double with two digits of precision results in a value of 1.27499999999999999, which would be rounded up to 1.27. By adding the rounding factor, the conversion correctly results in a value of 1.28. If you round off a double such as 1.

PAGE 634

ParagraphFormat Description Replaces characters in a string: • Single newline characters (CR/LF sequences) with spaces • Double newline characters with HTML paragraph tags (
) Returns A copy of the string, with characters converted.

PAGE 635

ParameterExists Description This function is deprecated. Use the IsDefined function. Determines whether a parameter exists. ColdFusion does not evaluate the argument. History ColdFusion MX: Deprecated this function. It might not work, and might cause an error, in later releases.

PAGE 636

ParseDateTime Description Parses a date/time string according to the English (U.S.) locale conventions. (To format a date/ time string for other locales, use the LSParseDateTime function.

PAGE 637

Enter an expression, and discover if it can be evaluated to a date value.

PAGE 638

Pi Description Gets the mathematical constant π, accurate to 15 digits. Returns The number 3.14159265358979. Category Mathematical functions Function syntax Pi() See also ASin, Cos, Sin, Tan Example
Pi Example
The Pi function Returns the number #NumberFormat(Pi(), "_._______________")#, the mathematical constant pi, accurate to 15 digits.

PAGE 639

PreserveSingleQuotes Description Prevents ColdFusion from automatically escaping single quotation mark characters that are contained in a variable. ColdFusion does not evaluate the argument. Returns (None) Category Other functions Function syntax PreserveSingleQuotes(variable) History ColdFusion MX: Changed behavior: ColdFusion automatically escapes simple-variable, arrayvariable, and structure-variable references within a cfquery tag body or block.

PAGE 640

This function ensures that ColdFusion evaluates the code as follows: '1', '2', '3' Example
PreserveSingleQuotes Example
This is a useful function for creating lists of information to return from a query. In this example, we pick the list of Centers in Suisun, San Francisco, and San Diego, using the SQL grammar IN to modify a WHERE clause, rather than looping through the result set after the query is run.

PAGE 641

Quarter Description Calculates the quarter of the year in which a date falls. Returns An integer, 1–4. Category Date and time functions Function syntax Quarter(date) See also DatePart, Month Parameters Parameter Description date A date/time object in the range 100 AD–9999 AD. Usage When passing a date/time value as a string, you must enclose it in quotation marks. Otherwise, it is interpreted as a number representation of a date/time object.

PAGE 642

QueryAddColumn Description Adds a column to a query and populates its rows with the contents of a one-dimensional array. Pads query columns, if necessary, to ensure that all columns have the same number of rows. Returns The number of the column that was added.

PAGE 643

PAGE 644

QueryAddRow Description Adds a specified number of empty rows to a query. Returns The number of rows in the query Category Query functions Function syntax QueryAddRow(query [, number ]) See also QueryAddColumn, QueryAddRow, QuerySetCell, QueryNew Parameters Parameter Description query Name of an executed query. number Number of rows to add to the query. Default: 1.

PAGE 645

QueryNew Description Creates an empty query (query object). Returns An empty query with a set of named columns, or an empty query. Category Query functions Function syntax QueryNew(columnlist) See also QueryAddColumn, QueryAddRow, QuerySetCell Parameters Parameter Description columnlist A string or a variable that contains one. Delimited list of column names, or an empty string.

PAGE 646

QuerySetCell Description Sets a cell to a value. If no row number is specified, the cell on the last row is set. Returns True, if successful; False, otherwise. Category Query functions Function syntax QuerySetCell(query, column_name, value [, row_number ]) See also QueryAddColumn, QueryAddRow, QueryNew Parameters Parameter Description query Name of an executed query column_name Name of a column in the query value Value to set in the cell row_number Row number. Default: last row.

PAGE 647

QuotedValueList Description Gets the values of each record returned from an executed query. ColdFusion does not evaluate the arguments. Returns A delimited list of the values of each record returned from an executed query. Each value is enclosed in single quotation marks. Category Query functions Function syntax QuotedValueList(query.column [, delimiter ]) See also ValueList Parameters Parameter Description query.column Name of an executed query and column.

PAGE 648

Rand Description Generates a random number. Returns A random decimal number, in the range 0 – 1. Category Mathematical functions Function syntax Rand() See also Randomize, RandRange Usage To ensure greater randomness, call the Randomize function before calling Rand. Example
Rand Example

Rand() returns a random number in the range 0 to 1.
Rand() returned: #Rand()#
PAGE 649
Randomize Description Seeds the ColdFusion random number generator with an integer number. Seeding the generator helps ensure that the Rand function generates highly random numbers. Returns A non-random decimal number, in the range 0 – 1. Category Mathematical functions Function syntax Randomize(number) See also Rand, RandRange Parameters Parameter Description number A number Usage Call this function before calling Rand. Although this function returns a decimal number, it is not a random number.

PAGE 650

RandRange Description Generates a random integer between two specified numbers. Requests for random integers that are greater than 100,000,000 result in non-random numbers, to prevent overflow during internal computations.

PAGE 651

REFind Description Uses a regular expression (RE) to search a string for a pattern. The search is case sensitive. For more information on regular expressions, including escape sequences, anchors, and modifiers, see Chapter 7, “Using Regular Expressions in Functions,” in Developing ColdFusion MX Applications.

PAGE 652

Parameter Description start Optional. A positive integer, or a variable that contains one. Position in the string at which to start search. Default: 1. returnsubexpressions Optional. Boolean. Whether to return substrings of reg_expression, in arrays named len and pos: • True: if the regular expression is found, the first array element contains the length and position, respectively, of the first match.

PAGE 653

The number of elements in each array: #ArrayLen(st.pos)#.

The number of elements in the pos and len arrays is always one if you do not use parentheses in the regular expression.

The value of st.pos[1] is: #st.pos[1]#.

The value of st.len[1] is: #st.len[1]#.

Substring is [#Mid(testString,st.pos[1],st.

PAGE 654

REFindNoCase Description Uses a regular expression (RE) to search a string for a pattern, starting from a specified position. The search is case-insensitive. For more information on regular expressions, including escape sequences, anchors, and modifiers, see Chapter 7, “Using Regular Expressions in Functions,” in Developing ColdFusion MX Applications.

PAGE 655

Parameter Description start Optional. A positive integer or a variable that contains one. Position at which to start search. Default: 1. returnsubexpressions Optional. Boolean. Whether to return substrings of reg_expression, in arrays named len and pos: • True: if the regular expression is found, the first array element contains the length and position, respectively, of the first match.

PAGE 656

The number of elements in each array: #ArrayLen(st.pos)#.

The number of elements in the pos and len arrays will always be one, if you do not use parentheses to denote subexpressions in the regular expression.

The value of st.pos[1] is: #st.pos[1]#.

The value of st.len[1] is: #st.len[1]#.

Substring is [#Mid(testString,st.

PAGE 657

ReleaseComObject Description Releases a COM Object and frees up resources that it used. Returns Nothing. Category Extensibility functions Function syntax ReleaseComObject(objectName) See also CreateObject, cfobject History ColdFusion MX 6.1: Added this function. Parameters Parameter Description objectName Variable name of a COM object that was created using the CreateObject function or cfobject tag.

PAGE 658

RemoveChars Description Removes characters from a string. Returns A copy of the string, with count characters removed from the specified start position. If no characters are found, returns zero. Category String functions Function syntax RemoveChars(string, start, count) See also Insert, Len Parameters Parameter Description string A string or a variable that contains one. String in which to search. start A positive integer or a variable that contains one. Position at which to start search.

PAGE 659

RepeatString Description Creates a string that contains a specified number of repetitions of the specified string. Returns A string. Category String functions Function syntax RepeatString(string, count) See also CJustify, LJustify, RJustify Parameters Parameter Description string A string or a variable that contains one count Number of repeats Example
RepeatString Example

RepeatString returns a string created from string, repeated a specified number of times.

PAGE 660

Replace Description Replaces occurrences of substring1 in a string with substring2, in a specified scope. The search is case-sensitive. Returns The string, after making replacements. Category String functions Function syntax Replace(string, substring1, substring2 [, scope ]) See also Find, REFind, ReplaceNoCase, ReplaceList, REReplace Parameters Parameter Description string A string or a variable that contains one. String in which to search substring1 A string or a variable that contains one.

PAGE 661

ReplaceList Description Replaces occurrences of the elements from a delimited list in a string with corresponding elements from another delimited list. The search is case-sensitive. Returns A copy of the string, after making replacements.

PAGE 662

#replacelist(stringtoreplace,"dog,brown,fox,black", "cow,black,ferret,white")# 662 Chapter 3: ColdFusion Functions

PAGE 663

ReplaceNoCase Description Replaces occurrences of substring1 with substring2, in the specified scope. The search is caseinsensitive. Returns A copy of the string, after making replacements.

PAGE 664

REReplace Description Uses a regular expression (RE) to search a string for a string pattern and replace it with another. The search is case-sensitive. Returns If the scope attribute is set to one, returns a string with the first occurrence of the regular expression replaced by the value of substring. If the scope attribute is set to all, returns a string with all occurrences of the regular expression replaced by the value of substring.

PAGE 665

Example
The REReplace function returns string with a regular expression replaced with substring in the specified scope. Case-sensitive search.

PAGE 666

REReplaceNoCase Description Uses a regular expression to search a string for a string pattern and replace it with another. The search is case-insensitive. Returns • If scope • • = "one": returns a string with the first occurrence of the regular expression replaced by the value of substring. If scope = "all": returns a string with all occurrences of the regular expression replaced by the value of substring. If the function finds no matches: returns a copy of the string, unchanged.

PAGE 667

#REReplaceNoCase("I LOVE JELLIES","jell(y|ies)","cookies")#
REReplaceNoCase("I LOVE JELLY","jell(y|ies)","cookies"): #REReplaceNoCase("I LOVE JELLY","jell(y|ies)","cookies")# REReplaceNoCase 667

PAGE 668

Reverse Description Reverses the order of items, such as the characters in a string, the digits in a number, or the elements in an array. Returns A copy of string, with the characters in reverse order.

PAGE 669

Right Description Gets a specified number of characters from a string, beginning at the right.

PAGE 670

RJustify Description Right justifies characters of a string. Returns A copy of a string, right-justified in the specified field length. Category Display and formatting functions, String functions Function syntax RJustify(string, length) See also CJustify, LJustify Parameters Parameter Description string A string enclosed in quotation marks, or a variable that contains one. length A positive integer or a variable that contains one. Length of field in which to justify string.

PAGE 671

Round Description Rounds a number to the closest integer. Returns An integer. Category Mathematical functions Function syntax Round(number) See also Ceiling, Fix, Int Parameters Parameter Description number Number to round Example
Round Example

This function rounds a number to the closest integer.

Round(7.49) : #Round(7.49)#
Round(7.5) : #Round(7.5)#
Round(-10.775) : #Round(-10.775)#
Round(1.

PAGE 672

RTrim Description Removes spaces from the end of a string. Returns A copy of string, after removing trailing spaces. Category String functions Function syntax RTrim(string) See also LTrim, Trim Parameters Parameter Description string A string or a variable that contains one Example
RTrim Example

Your string:"#FORM.myText#" Your string:"#RTrim(FORM.myText)#" (right trimmed)
PAGE 673
Second Description Extracts the ordinal for the second from a date/time object. Returns An integer in the range 0–59. Category Date and time functions Function syntax Second(date) See also DatePart, Hash, Minute Parameters Parameter Description date A date/time object Usage When passing a date/time object as a string, you must enclose it in quotation marks. Otherwise, it is interpreted as a number representation of a date/time object.

PAGE 674

SetEncoding Description Sets the character encoding (character set) of Form and URL scope variable values; used when the character encoding of the input to a form, or the character encoding of a URL, is not in UTF-8 encoding. Returns None Category International functions, System functions Function syntax SetEncoding(scope_name,charset) See also GetEncoding, cfcontent, cfprocessingdirective, URLDecode, URLEncodedFormat History ColdFusion MX: Added this function.

PAGE 675

• www.iana.org/assignments/character-sets is a complete list of character sets names used on the Internet, maintained by the Internet Assigned Numbers Authority. • java.sun.com/j2se/1.4.1/docs/guide/intl/encoding.doc.html lists the character encoding that Java 1.4.1, and therefore the default ColdFusion configuration, can interpret. If you use a JVM that does not conform to the Sun Java 2 Platform, Standard Edition, v 1.4.1, the supported locales may differ.

PAGE 676

SetLocale Description Sets the country/language locale for ColdFusion processing and the page returned to the client. The locale value determines the default format of date, time, number, and currency values, according to language and regional conventions. Returns The locale value prior to setting the new locale, as a string.

PAGE 677

ColdFusion determines the locale value as follows: • By default, ColdFusion uses the JVM locale, and the default JVM locale is the operating system locale. You can set JVM locale value explicitly in ColdFusion MX in the ColdFusion Administrator Java and JVM Settings page JVM Arguments field; for example: Duser.language=de -Duser.region=DE. • A locale set using the SetLocale function persists for the current request or until it is reset by another SetLocale function in the request.

PAGE 678

SetProfileString Description Sets the value of a profile entry in an initialization file. Returns An empty string, upon successful execution; otherwise, an error message.

PAGE 679

The timeout value in your initialization file is already #MyTimeout#.

Boot Loader

Timeout is set to: #timeout#.

Default directory is: #default#.
PAGE 680
SetVariable Description This function is no longer required in well-formed ColdFusion pages. Sets a variable in the name parameter to the value of the value parameter. Returns The new value of the variable.

PAGE 681

Your variable, #varName#
The value of #varName# is #varNameValue# SetVariable 681

PAGE 682

Sgn Description Determines the sign of a number. Returns • 1, if number is positive. • 0, if number is 0. • -1, if number is negative. Category Mathematical functions Function syntax Sgn(number) See also Abs Parameters Parameter Description number A number Example
Sgn Example

Sgn determines the sign of a number. Returns 1 if number is positive; 0 if number is 0; -1 if number is negative.
Sgn(14): #Sgn(14)#
Sgn(21-21): #Sgn(21-21)#
Sgn(-0.

PAGE 683

Sin Description Calculates the sine of an angle that is entered in radians. Returns A number; the sine of the angle. Category Mathematical functions Function syntax Sin(number) See also ASin, Cos, ACos, Tan, Atn, Pi Parameters Parameter Description number Angle, in radians for which to calculate the sine. Usage The range of the result is -1 to 1. To convert degrees to radians, multiply degrees by π/180. To convert radians to degrees, multiply radians by 180/π.

PAGE 684

   684 Chapter 3: ColdFusion Functions

PAGE 685

SpanExcluding Description Gets characters from a string, from the beginning to a character that is in a specified set of characters. The search is case-sensitive. Returns A string; characters from string, from the beginning to a character that is in set. Category String functions Function syntax SpanExcluding(string, set) See also GetToken, SpanIncluding Parameters Parameter Description string A string or a variable that contains one set A string or a variable that contains one.

PAGE 686

SpanIncluding Description Gets characters from a string, from the beginning to a character that is not in a specified set of characters. The search is case-sensitive. Returns A string; characters from string, from the beginning to a character that is not in set. Category String functions Function syntax SpanIncluding(string, set) See also GetToken, SpanExcluding Parameters Parameter Description string A string or a variable that contains the search string.

PAGE 687

Sqr Description Calculates the square root of a number. Returns Number; square root of number. Category Mathematical functions Function syntax Sqr(number) See also Abs Parameters Parameter Description number A positive integer or a variable that contains one. Number whose square root to get. Usage The value in number must be greater than or equal to 0. Example
Sqr Example

Returns the square root of a positive number.

PAGE 688

StripCR Description Deletes return characters from a string. Returns A copy of string, after removing return characters. Category Display and formatting functions, Other functions, String functions Function syntax StripCR(string) See also ParagraphFormat Parameters Parameter Description string A string or a variable that contains one Usage Useful for preformatted (between
and
tags) HTML display of data entered in textarea fields.

PAGE 689

StructAppend Description Appends one structure to another. Returns True, upon successful completion; False, otherwise. Category Structure functions Function syntax StructAppend(struct1, struct2, overwriteFlag) See also Structure functions History ColdFusion MX: Changed behavior: this function can be used on XML objects. Parameters Parameter Description struct1 Structure to append.

PAGE 690

The person struct before the Append call:
#myItem#

The person struct after the Append call:
#myItem#
690 Chapter 3: ColdFus

PAGE 691

StructClear Description Removes all data from a structure. Returns True, on successful execution; False, otherwise. Category Structure functions Function syntax StructClear(structure) See also Structure functions History ColdFusion MX: Changed behavior: this function can be used on XML objects. Parameters Parameter Description structure Structure to clear Usage Do not call this function on a session variable. For more information, see TechNote 14143, "ColdFusion 4.

PAGE 692

StructClear(employee); 692 Chapter 3: ColdFusion Functions

PAGE 693

StructCopy Description Copies a structure. Copies top-level keys, values, and arrays in the structure by value; copies nested structures by reference. Returns A copy of a structure, with the same keys and values; if structure does not exist, throws an exception.

PAGE 694

Variable type Assigned by structure.object Reference structure.query Reference Example // This script creates a structure that StructCopy copies by value.
// Create elements. s = StructNew(); s.array = ArrayNew(2); // Assign simple values to original top-level structure fields. s.number = 99; s.string = "hello tommy"; // Assign values to original top-level array. s.array[1][1] = "one one"; s.

PAGE 695

copied.string = #copied.string#
// Array value
copied.array[1][1] = #copied.array[1][1]#
copied.array[1][2] = #copied.array[1][2]#
// This script creates a structure that StructCopy copies by reference. // Create elements. s = StructNew(); s.nested = StructNew(); s.nested.array = ArrayNew(2); // Assign simple values to nested structure fields. s.nested.number = 99; s.nested.string = "hello tommy"; // Assign values to nested array. s.nested.array[1][1] = "one one"; s.

PAGE 696

copied.nested.number = #copied.nested.number#
copied.nested.string = #copied.nested.string#
// Array values
copied.nested.array[1][1] = #copied.nested.array[1][1]#
copied.nested.array[1][2] = #copied.nested.array[1][2]#

Duplicated structure values should remain unchanged.
// Simple values
duplicated.nested.number = #duplicated.nested.number#
duplicated.nested.string = #duplicated.nested.string#
// Array value
duplicated.nested.

PAGE 697

StructCount Description Counts the keys in a structure. Returns A number; if structure does not exist, throws an exception. Category Structure functions Function syntax StructCount(structure) See also Structure functions History ColdFusion MX: Changed behavior: this function can be used on XML objects. Parameters Parameter Description structure Structure to access Example
This file is similar to addemployee.

PAGE 698

StructDelete Description Removes an element from a structure. Returns Boolean value. The value depends on the indicatenotexisting parameter value. Category Structure functions Function syntax StructDelete(structure, key [, indicatenotexisting ]) See also Structure functions History ColdFusion MX: Changed behavior: this function can be used on XML objects. Parameters Parameter Description structure Structure or a variable that contains one.

PAGE 699

Did I delete the field "#form.field#"? The code indicates: #rc#
The structure now looks like this:

PAGE 700
StructFind Description Determines the value associated with a key in a structure. Returns The value associated with a key in a structure; if structure does not exist, throws an exception. Category Structure functions Function syntax StructFind(structure, key) See also Structure functions Parameters Parameter Description structure Structure that contains the value to return key Key whose value to return Usage A structure’s keys are unordered.

PAGE 701

StructFindKey Description Searches recursively through a substructure of nested arrays, structures, and other elements, for structures whose values match the search key in the value parameter. Returns An array that contains structures with values that match value. Category Structure functions Function syntax StructFindKey(top, value, scope) See also Structure functions Parameters Parameter Description top ColdFusion object (structure or array) from which to start search.

PAGE 702

StructFindValue Description Searches recursively through a substructure of nested arrays, structures, and other elements for structures with values that match the search key in the value parameter. Returns An array that contains structures with values that match the search key value. If none are found, returns an array of size 0.

PAGE 703

StructGet Description Gets a structure(s) from a specified path. Returns An alias to the variable in the pathDesired parameter. If necessary, StructGet creates structures or arrays to make pathDesired a valid variable "path." Category Structure functions Function syntax StructGet(pathDesired) See also Structure functions History ColdFusion MX: • Changed behavior: this function can be used on XML objects.

PAGE 704

#request.myscope[1].test.foo#
#request.myscope[1].test[2].

PAGE 705

StructInsert Description Inserts a key-value pair into a structure. Returns True, upon successful completion. If structure does not exist, or if key exists and allowoverwrite = "False", ColdFusion throws an exception. Category Structure functions Function syntax StructInsert(structure, key, value [, allowoverwrite ]) See also Structure functions History ColdFusion MX: Changed behavior: this function can be used on XML objects.

PAGE 706

First name is #StructFind(employee, "firstname")#

Last name is #StructFind(employee, "lastname")#

EMail is #StructFind(employee, "email")#

Phone is #StructFind(employee, "phone")#

Department is #StructFind(employee, "department")#

PAGE 707
StructIsEmpty Description Determines whether a structure contains data. Returns True, if structure is empty; if structure does not exist, ColdFusion throws an exception. Category Decision functions, Structure functions Function syntax StructIsEmpty(structure) See also Structure functions History ColdFusion MX: Changed behavior: this function can be used on XML objects. Parameters Parameter Description structure Structure to test Example
Add New Employees
PAGE 714
StructSort Description Returns a sorted array of the top level keys in a structure. Sorts using alphabetic or numeric sorting, and can sort based on the values of any structure element. Returns An array of top-level key names (strings), sorted by the value of the specified subelement.

PAGE 715

departments["department#i#"] = StructNew() ; departments["department#i#"].

PAGE 716

StructUpdate Description Updates a key with a value. Returns True, on successful execution; if the structure does not exist, ColdFusion throws an error. Category Structure functions Function syntax StructUpdate(structure, key, value) See also Structure functions History ColdFusion MX: Changed behavior: this function can be used on XML objects.

PAGE 717

Tan Description Calculates the tangent of an angle that is entered in radians. Returns A number; the tangent of an angle. Category Mathematical functions Function syntax Tan(number) See also Atn, Cos, ACos, Sin, ASin, Pi Parameters Parameter Description number Angle, in radians, for which to calculate the tangent. Usage To convert degrees to radians, multiply degrees by π/180. To convert radians to degrees, multiply radians by 180/π.

PAGE 718

   718 Chapter 3: ColdFusion Functions

PAGE 719

TimeFormat Description Formats a time value using US English time formatting conventions. Returns A custom-formatted time value. If no mask is specified, returns a time value using the hh:mm tt format. For international time formatting, see LSTimeFormat. Category Date and time functions, Display and formatting functions Function syntax TimeFormat(time [, mask ]) See also CreateTime, Now, ParseDateTime, LSTimeFormat, DateFormat History ColdFusion MX 6.

PAGE 720

Parameters Parameter Description time A date/time value or string to convert mask Masking characters that determine the format: • h: Hours; no leading zero for single-digit hours (12-hour clock) • hh: Hours; leading zero for single-digit hours (12-hour clock) • H: Hours; no leading zero for single-digit hours (24-hour clock) • HH: Hours; leading zero for single-digit hours (24-hour clock) • m: Minutes; no leading zero for single-digit minutes • mm: Minutes; a leading zero for single-digit minutes • s:

PAGE 721

ToBase64 Description Calculates the Base64 representation of a string or binary object. The Base64 format uses printable characters, allowing binary data to be sent in forms and e-mail, and stored in a database or file. The Base64 representation of a string or binary object.

PAGE 722

Base64 lets you store binary objects in a database. Note: To reverse Base64 encoding of a string, you can convert it to a binary object, then convert the binary object to a string, using the toString function. Example
ToBase64 Example

The following string is the concatenation of characters (32 to 255) from the ASCII table.
#charData#