User Guide

Manuals Brands Macromedia Manuals Other COLDFUSION 4.5-CFML LANGUAGE REFERENCE

Allaire Corporation

CFML Language

Reference

ColdFusion 4.5

Summary of content (608 pages)

PAGE 1

CFML Language Reference ColdFusion 4.
PAGE 2

Copyright Notice © 1999 Allaire Corporation. All rights reserved. This manual, as well as the software described in it, is furnished under license and may be used or copied only in accordance with the terms of such license. The content of this manual is furnished for informational use only, is subject to change without notice, and should not be construed as a commitment by Allaire Corporation.
PAGE 3

Contents Preface: Welcome To ColdFusion ................................................................xiii Intended Audience.........................................................................................................................xiv Welcome to the ColdFusion 4.5 Web Application Server ...........................................................xiv Products and System Requirements ............................................................................................
PAGE 4

iv CFML Language Reference Flow-Control Tags ............................................................................................................................7 Internet Protocol Tags ......................................................................................................................7 Java Servlet and Java Object Tags ....................................................................................................8 Variable Manipulation Tags..................................
PAGE 5

Contents CFHEADER ......................................................................................................................................90 CFHTMLHEAD................................................................................................................................91 CFHTTP ...........................................................................................................................................92 CFHTTPPARAM ......................................................
PAGE 6

vi CFML Language Reference Arrays......................................................................................................................................197 Dynamic variable names ......................................................................................................197 COM objects ..........................................................................................................................197 CFSETTING ..............................................................
PAGE 7

Contents ArrayResize ....................................................................................................................................268 ArraySet..........................................................................................................................................269 ArraySort........................................................................................................................................270 ArraySum ..............................................
PAGE 8

viii CFML Language Reference DaysInMonth ................................................................................................................................333 DaysInYear ....................................................................................................................................334 DE...................................................................................................................................................335 DecimalFormat .......................
PAGE 9

Contents IsBoolean .......................................................................................................................................391 IsDate .............................................................................................................................................392 IsDebugMode................................................................................................................................393 IsDefined ................................................
PAGE 10

x CFML Language Reference LSParseNumber ............................................................................................................................460 LSTimeFormat ..............................................................................................................................461 LTrim..............................................................................................................................................463 Max.............................................
PAGE 11

Contents StripCR...........................................................................................................................................521 StructClear.....................................................................................................................................522 StructCopy.....................................................................................................................................523 StructCount .............................................
PAGE 12

xii CFML Language Reference Notes on using variables.......................................................................................................575 Operators .......................................................................................................................................576 Arithmetic operators .............................................................................................................576 String operators ...................................................
PAGE 13

Preface Welcome To ColdFusion ColdFusion is a rapid application development system for professional developers who want to create dynamic Web applications and interactive Web sites. It provides the fastest way to integrate browser, server, and database technologies into powerful Web applications. With ColdFusion, you can build everything from online stores to sophisticated business systems.
PAGE 14

xiv CFML Language Reference Intended Audience This reference is intended for web developers who have a working knowledge of ColdFusion; that is, you know how to use tags and functions, but you need a comprehensive reference that provides an in-depth description of each tag and function, and examples of how tags and functions are used in the context of an HTML/ CFML page. Welcome to the ColdFusion 4.5 Web Application Server The ColdFusion 4.
PAGE 15

Preface xv • 128 MB RAM (256 MB recommended for clustering) ColdFusion Server 4.5 Enterprise Edition for Solaris • SPARC Solaris 2.5.1, 2.6, or 7 (patch 103582-1B or higher) • 128 MB RAM (256 MB recommended for clustering) • 200 MB hard disk space ColdFusion Server 4.5 Enterprise Edition for Linux • Red Hat Linux 6.0 or 6.1 • Intel Pentium or above • 128 MB RAM (256 MB recommended for clustering) • 150 MB hard disk space ColdFusion Server 4.
PAGE 16

xvi CFML Language Reference New visual tools Universal File Browser — Access all your files from a single explorer that integrates access to the Windows file system, ColdFusion RDS servers, and FTP servers. Dragand-drop between any of these services all in an integrated file browser.
PAGE 17

Preface xvii Improved Automatic Server Recovery — Monitor and automatically restart server process in case of failures or critical errors on individual servers not deployed in a cluster. Clustering Support for Apache — Setup ColdFusion clusters on Linux and Solaris using the Apache Web Server. (Enterprise Edition only) Automatic Shared Variable Locking — Lock user and session variable reads automatically at the server level to prevent destabilizing conflicts and control thread write contentions.
PAGE 18

xviii CFML Language Reference Java-based ColdFusion Extensions (CFX) — Extend ColdFusion with new functionality through CFXs created with Java. Binary Object Support — Use Character Large Binary Object (CLOB) support to encoded binary objects, transmit them via XML, and store them in databases or files. SQL Bind Parameters — Improve query performance, security and flexibility with explicitly typed query parameters. WDDX 1.
PAGE 19

Preface xix Language Reference Features The CFML Language Reference provides descriptions, syntax, usage, and code examples for: • CFML Tags • CFML Functions • JavaScript objects used when implementing web distributed data exchange (WDDX) The CFML Language Reference also provides a chapter on expressions, operators, and other CFML constructs. Using Examples Each tag and function features a runnable example, using code drawn from the snippets directory (found in webroot\cfdocs\snippets).
PAGE 20

xx CFML Language Reference Using End Tags Except where noted in the syntax, CFML tags do not require an end tag. However, all CFML tags (except CFELSE and CFELSEIF) can accept an optional end tag, as follows: • Shorthand — You can use shorthand notation to include the end tag with the base tag. For example: • Explicit specification — You can specify an end tag explicitly. However, there can be no white space between the start and end tags.
PAGE 21

Preface xxi About ColdFusion Documentation ColdFusion documentation is designed to provide support for all components of the ColdFusion development system. Both the print and online versions are organized to allow you to quickly locate the information you need. In addition to the book set, the documentation is provided in two other formats: • HTML — Browser-based Help references.
PAGE 22

xxii CFML Language Reference Using ColdFusion Studio Documents everything you need to know about using ColdFusion Studio, including features like projects, source control integration, as well as the Studio workspace and interface. ColdFusion Quick Reference Guide A valuable quick reference to CFML tags, functions, and variables. ColdFusion Server online documentation To view the HTML documentation, open the following URL: http://127.0.0.1/ cfdocs/dochome.htm.
PAGE 23

Preface xxiii Documentation conventions When reading, please be aware of these formatting cues: • Code samples, filenames, and URLs are set in a monospaced font • Notes and tips are identified by bold type • Bulleted lists present options and features • Numbered steps indicate procedures • Tool button icons are generally shown with procedure steps • Menu levels are separated by the greater than (>) sign • Text for you to type in is set in italics Getting Answers One of the best ways to solve particular p
PAGE 24

xxiv CFML Language Reference Technical support Telephone support is available Monday through Friday 8 A.M. to 8 P.M. Eastern time (except holidays) Toll Free: 888.939.2545 (U.S. and Canada) Tel: 617.761.2100 (outside U.S. and Canada) For complete details about Allaire Product Support options, please refer to the Allaire Support pages on the Allaire web site: http://www.allaire.com/support. Postings to the ColdFusion Support Forum (http://forums.allaire.com) can be made any time. Sales Toll Free: 888.939.
PAGE 25

CHAPTER 1 Chapter 1 ColdFusion Tags This chapter describes each of the tags in the ColdFusion Markup Language (CFML). The introduction contains an alphabetical summary of ColdFusion tags, a list of new tags in ColdFusion 4.5, and a list of tags by category. The remainder of this chapter provides complete descriptions of each tag, listed alphabetically. Contents • Alphabetical List of ColdFusion Tags................................................................ 2 • New Tags in ColdFusion 4.5........
PAGE 26

2 CFML Language Reference Alphabetical List of ColdFusion Tags The ColdFusion Markup Language (CFML) consists of a set of tags you use in your ColdFusion pages to interact with data sources, manipulate data, and display output. Using CFML tags is very simple; tag syntax is much like HTML element syntax. The following table provides brief descriptions of each CFML tag. CFML Tag Summary CFML Tag Description CFABORT Stops processing of a ColdFusion page at the tag location.
PAGE 27

Chapter 1: ColdFusion Tags 3 CFML Tag Summary (Continued) CFML Tag Description CFFORM Builds an input form and performs client-side input validation. CFFTP Permits FTP file operations. CFGRID Used in CFFORM to create a grid control for tabular data. CFGRIDCOLUMN Used in CFFORM to define the columns used in a CFGRID. CFGRIDROW Used with CFGRID to define a grid row. CFGRIDUPDATE Performs updates directly to ODBC data source from edited grid data. CFHEADER Generates HTTP headers.
PAGE 28

4 CFML Language Reference CFML Tag Summary (Continued) CFML Tag Description CFMAILPARAM Attaches a file or adds a header to an email message. CFMODULE Invokes a custom tag for use in your ColdFusion application pages. CFOBJECT Creates and uses COM, CORBA, or JAVA objects. CFOUTPUT Displays output of database query or other operation. CFPARAM Defines a parameter and its initial default value. CFPOP Retrieves messages from a POP mail server.
PAGE 29

Chapter 1: ColdFusion Tags 5 CFML Tag Summary (Continued) CFML Tag Description CFSILENT Suppresses all output that is produced by the CFML within the tag’s scope. CFSLIDER Used in CFFORM to create a slider control element. CFSTOREDPROC Specifies database connection information and identifies the stored procedure to be executed. CFSWITCH/CFCASE/CFDEFAULTCASE Evaluates a passed expression and passes control to the CFCASE tag that matches the expression result. CFTABLE Builds a table.
PAGE 30

6 CFML Language Reference ColdFusion Forms Tags CFAPPLET CFINPUT CFFORM CFSELECT CFGRID CFSLIDER CFGRIDCOLUMN CFTEXTINPUT CFGRIDROW CFTREE CFGRIDUPDATE CFTREEITEM Database Manipulation Tags CFINSERT CFQUERYPARAM CFPROCPARAM CFSTOREDPROC CFPROCRESULT CFTRANSACTION CFQUERY CFUPDATE Data Output Tags CFCOL CFOUTPUT CFCONTENT CFTABLE CFHEADER Exception Handling Tags CFERROR CFRETHROW CFTHROW CFTRY/CFCATCH
PAGE 31

Chapter 1: ColdFusion Tags 7 Extensibility Tags CFCOLLECTION CFSEARCH CFEXECUTE CFSERVLET CFINDEX CFSERVLETPARAM CFOBJECT CFWDDX CFREPORT File Management Tags CFDIRECTORY CFFILE Flow-Control Tags CFABORT CFLOOP CFBREAK CFSWITCH/CFCASE/CFDEFAULTCASE CFEXECUTE CFTHROW CFIF/CFELSEIF/CFELSE CFTRY/CFCATCH CFLOCATION Internet Protocol Tags CFFTP CFMAIL CFHTTP CFMAILPARAM CFHTTPPARAM CFPOP CFLDAP
PAGE 32

8 CFML Language Reference Java Servlet and Java Object Tags CFOBJECT CFSERVLETPARAM CFSERVLET Variable Manipulation Tags CFCOOKIE CFSCRIPT CFPARAM CFSET Web Application Framework Tags CFAPPLICATION CFERROR CFASSOCIATE CFLOCK CFAUTHENTICATE Other Tags CFASSOCIATE CFREPORT CFCACHE CFSETTING CFHTMLHEAD CFSILENT CFINCLUDE CFWDDX CFLOCK
PAGE 33

Chapter 1: ColdFusion Tags 9 CFABORT The CFABORT tag stops processing of a page at the tag location. ColdFusion simply returns everything that was processed before the CFABORT tag. CFABORT is often used with conditional logic to stop processing a page because of a particular condition. Syntax SHOWERROR Optional. Specify the error you want to display when CFABORT executes. This error message appears in the standard ColdFusion error page.
PAGE 34

10 CFML Language Reference
The value of myVariable after incrementing through the loop #Counter# times is: #myVariable#
Example B: Use CFABORT to halt the instruction

#CFCATCH.message# ...
PAGE 43

Chapter 1: ColdFusion Tags 19 CFBREAK Used to break out of a CFLOOP. See Breaking out of a loop, later in this chapter, for more information.
PAGE 44

20 CFML Language Reference CFCACHE CFCACHE allows you to speed up pages considerably in cases where the dynamic content doesn’t need to be retrieved each time a user accesses the page. To accomplish this, it creates temporary files that contain the static HTML returned from a particular run of the ColdFusion page. You can use CFCACHE for simple URLs and URLs that contain URL parameters.
PAGE 45

Chapter 1: ColdFusion Tags 21 CACHEDIRECTORY Optional. Specifies the fully qualified path of the directory where the pages are to be cached. The default is the directory of the current page. EXPIREURL Optional. Used with ACTION=FLUSH. EXPIREURL takes a wildcarded URL reference that ColdFusion matches against all mappings in the cfcache.map file. The default is to flush all mappings. For example, "foo.cfm" matches "foo.cfm"; "foo.cfm?*" matches "foo.cfm?x=5" and "foo.cfm?x=9". PORT Optional.
PAGE 46

22 CFML Language Reference You can refresh the cache in the following ways: • TIMEOUT attribute — ColdFusion tests the timestamp of the cached file against the TIMEOUT attribute. If the cached file’s timestamp is older than TIMEOUT, the old file is deleted and a new one created. You can use fixed dates if necessary, but it's preferable to use relative dates. This is the preferred technique and it works for seconds, hours, days, weeks, years, etc.
PAGE 47

Chapter 1: ColdFusion Tags 23 CFCOL Defines table column header, width, alignment, and text. Only used inside a CFTABLE. Syntax HEADER The text to use for the column’s header. WIDTH The width of the column in characters (the default is 20). If the length of the data displayed exceeds the width value, the data is truncated to fit. ALIGN Column alignment, Left, Right, or Center.
PAGE 48

24 CFML Language Reference as well as specifying the header information and the text/CFML with which to fill the cell --->
PAGE 49

Chapter 1: ColdFusion Tags 25 CFCOLLECTION The CFCOLLECTION tag allows you to create and administer Verity collections. Syntax ACTION Required. Specifies the action to perform: • CREATE — Creates a new collection using the specified path and optionally specified language. • REPAIR — Fixes data corruption in the collection. • DELETE — Destroys the collection.
PAGE 50

26 CFML Language Reference LANGUAGE Optional for CREATE. To use the LANGUAGE attribute you must have the ColdFusion International Search Pack installed. Valid entries are: • English (default) • German • Finnish • French • Danish • Dutch • Italian • Norwegian • Portuguese • Spanish • Swedish Usage CFCOLLECTION works at the collection level only. To add content to a collection, use CFINDEX.
PAGE 51

Chapter 1: ColdFusion Tags COLLECTION="#FORM.CollectionName#" PATH="C:\CFUSION\Verity\Collections\">
Collection created.

Collection repaired.

Collection optimized.
PAGE 52
28 CFML Language Reference CFCONTENT Defines the MIME type returned by the current page. Optionally, allows you to specify the name of a file to be returned with the page. Note Syntax The ColdFusion Server Basic security settings may prevent CFCONTENT from executing. These settings are managed using the ColdFusion Administrator Basic Security page. In order for CFCONTENT to execute, it needs to be enabled on the Basic Security page.
PAGE 53

Chapter 1: ColdFusion Tags 29
CFCONTENT Example

The last AOL visitor to view this site was #Cookie.LastAOLVisitor#, on #DateFormat(COOKIE.TimeVisited)#
Hide my tracks
No AOL Visitors have viewed the site lately.
PAGE 57

Chapter 1: ColdFusion Tags 33 CFDIRECTORY Use the CFDIRECTORY tag to handle all interactions with directories. Note The ColdFusion Server Basic security settings may prevent CFDIRECTORY from executing. These settings are managed using the ColdFusion Administrator Basic Security page. In order for CFDIRECTORY to execute, it needs to be enabled on the Basic Security page.
PAGE 58

34 CFML Language Reference Optional. Used with ACTION="Create" to define the permissions for a directory on Solaris or HP-UX. Ignored in Windows. Valid entries correspond to the octal values (not symbolic) of the UNIX chmod command. Permissions are assigned for owner, group, and other, respectively. For example: MODE=644 Assigns all, owner read/write permission, group and other read/write permissions. MODE=666 Assigns read/write permissions for owner, group, and other.
PAGE 59

Chapter 1: ColdFusion Tags Example 35 CFERROR Example
CFERROR Example

CFERROR provides the ability to display customized HTML pages when errors occur. This allows you to maintain a consistent look and feel within your application even when errors occur. Note that no CFML can be displayed in the resulting templates except for the specialized error variables.
PAGE 64

40 CFML Language Reference CFEXECUTE Enables ColdFusion developers to execute any process on the server machine. Syntax PAGE 65
Chapter 1: ColdFusion Tags 41 Usage CFEXECUTE is available on Windows NT 4.0 and UNIX platforms. Do not put any other ColdFusion tags or functions between the start and the end tags of CFEXECUTE. Also, CFEXECUTE tags cannot be nested. Exception CFEXECUTE throws the following exceptions: • If the application name is not found, an Application File Not Found exception will be thrown. • If the output file cannot be opened, an Output File Cannot be opened will be thrown.
PAGE 66

42 CFML Language Reference CFEXIT CFEXIT can be used to: • Abort the processing of the currently executing CFML custom tag. • Exit the template within the currently executing CFML custom tag. • Reexecute a section of code within the currently executing CFML custom tag. Syntax METHOD Optional. Specifies one of the following: • ExitTag (default) — Aborts processing of the currently executing CFML custom tag.
PAGE 67

Chapter 1: ColdFusion Tags Example CFEXIT Example
CFEXIT Example

CFEXIT can be used to abort the processing of the currently executing CFML custom tag. Execution will resume immediately following the invocation of the custom tag in the page that called the tag.
PAGE 68

44 CFML Language Reference
If CFEXIT is used outside of a custom tag, it functions like a CFABORT. For example, the text after this message will not be processed:
This text will not be executed due to the existence of the CFEXIT tag above it.
PAGE 69

Chapter 1: ColdFusion Tags 45 CFFILE Use the CFFILE tag to handle all interactions with files. The attributes you use with CFFILE depend on the value of the ACTION attribute. For example, if the ACTION is "Write, " ColdFusion expects the attributes associated with writing a text file. See the individual CFFILE topics below for details about which attributes apply to which ACTIONs. Note The Basic Security settings may prevent CFFILE from executing.
PAGE 70

46 CFML Language Reference CFFILE ACTION attributes Depending on the value you assign to the ACTION attribute of CFFILE, there are several additional attributes you can set. This table shows which attributes you can use with each CFFILE ACTION.
PAGE 71

Chapter 1: ColdFusion Tags 47 CFFILE ACTION="Upload" Use CFFILE with the Upload action to upload a file specified in a form field to a directory on the Web server. Note Syntax The MODE attribute applies to ColdFusion on Solaris and HP-UX, only. FILEFIELD Required. The name of the form field that was used to select the file.
PAGE 72

48 CFML Language Reference Note that the browser uses the file extension to determine file type. MODE Optional. Defines permissions for an uploaded file on Solaris or HP-UX. Ignored in Windows. Valid entries correspond to the octal values (not symbolic) of the UNIX chmod command. Permissions are assigned for owner, group, and other, respectively. For example: MODE=644 Assigns the owner read/write permissions and group/other read permission.
PAGE 73

Chapter 1: ColdFusion Tags 49 Evaluating the results of a file upload After a file upload is completed, you can retrieve status information using file upload parameters. This status information includes a wide range of data about the file, such as the file’s name and the directory where it was saved. File upload status parameters use the "File " prefix, for example, File.ClientDirectory. The file status parameters can be used anywhere other ColdFusion parameters can be used.
PAGE 74

50 CFML Language Reference File Upload Parameters (Continued) Parameter Description FileWasRenamed Indicates (Yes or No) whether or not the uploaded file was renamed to avoid a name conflict. FileWasSaved Indicates (Yes or No) whether or not Cold Fusion saved a file. OldFileSize Size of a file that was overwritten in the file upload operation. ServerDirectory Directory of the file actually saved on the server. ServerFile Filename of the file actually saved on the server.
PAGE 75

Chapter 1: ColdFusion Tags 51 The next example uploads a file and gives it rwx-rw-rw permissions (owner/group/ other=read/write). CFFILE ACTION="Upload" FILEFIELD="fieldname" DESTINATION="/tmp/program.exe" MODE=755> CFFILE ACTION="Move" The CFFILE MOVE action can be used to move a file from one location on the server to another.
PAGE 76

52 CFML Language Reference Example The following example moves the keymemo.doc file from the c:\files\upload\ directory to the c:\files\memo\ directory on Windows: Note On Windows, you must include the backward slash (\) after the destination directory name if you do not specify a file name. In this example, the specified destination directory is "memo.
PAGE 77

Chapter 1: ColdFusion Tags 53 Example The following example renames the file keymemo.doc to oldmemo.doc: CFFILE ACTION="Copy" The CFFILE tag can be used to copy a file from one directory to another on the server. Syntax SOURCE Required. The full path name of the file to copy. DESTINATION Required.
PAGE 78

54 CFML Language Reference Note On Windows, you must include the backward slash (\) after the destination directory name if you do not specify a file name. In this example, the specified destination directory is "backup. " CFFILE ACTION="Delete" The CFFILE tag can be used to delete a file on the server. Syntax FILE Required. The full path name of the file to delete.
PAGE 79

Chapter 1: ColdFusion Tags 55 #Message# ColdFusion supports a number of powerful functions for manipulating the contents of text files. You can also use variable created by a CFFILE Read operation in ArrayToList and ListToArray functions. See String Functions and Array Functions for more information about working with strings and arrays. CFFILE ACTION="ReadBinary" You can use the CFFILE tag to read an existing binary file, such as an executable or image file.
PAGE 80

56 CFML Language Reference FILE Required. The full path name of the file to be created. OUTPUT Required. The content of the file to be created. MODE Optional. Defines permissions for a file on Solaris or HP-UX. Ignored in Windows. Valid entries correspond to the octal values (not symbolic) of the Unix chmod command. Permissions are assigned for owner, group, and other, respectively. For example: MODE=644 Assigns the owner read/write permissions and group/other read permission.
PAGE 81

Chapter 1: ColdFusion Tags 57 Example The following example creates a file with the information a user entered into an HTML insert form: If the user submitted a form where: UpdateTitle="FieldWork" FullName="World B. Frueh" Date="10/30/98" Content="We had a wonderful time in Cambridgeport." ColdFusion would create a file named FieldWork.
PAGE 82

58 CFML Language Reference CFFILE ACTION="Append" Use CFFILE with the Append action to append additional text to the end of an existing text file, for example, when creating log files. Syntax FILE Required. The full path name of the file to which the content of the OUTPUT attribute is appended. OUTPUT Required. The string to be appended to the file designated in the DESTINATION attribute. ADDNEWLINE Optional.
PAGE 83

Chapter 1: ColdFusion Tags 59 CFFORM CFFORM allows you to build a form with CFML custom control tags that provide much greater functionality than standard HTML form input elements. Syntax ... NAME Optional. A name for the form you are creating. ACTION Required.
PAGE 84

60 CFML Language Reference code that is generated for the CFINPUT tag. See the Usage section for more information about specifying values. Usage The following custom control tags are available: • CFINPUT — Creates a form input element (radio button, text box, or checkbox) and can validate form input. • CFSELECT — Creates a drop down listbox. • CFSLIDER — Creates a slider control. • CFTEXTINPUT — Creates a text input box. • CFTREE — Creates a tree control.
PAGE 85

Chapter 1: ColdFusion Tags Example 61 CFFORM Example
CFFORM Example

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

62 CFML Language Reference
This example shows a client-side validation for CFINPUT text boxes.

(This item is optional)
Please enter a credit card number:
This example shows the use of the CFSLIDER tag.
PAGE 87

Chapter 1: ColdFusion Tags 63 CFFTP CFFTP allows users to implement File Transfer Protocol operations. By default, CFFTP caches an open connection to an FTP server. Note The CFFTP tag is for moving files between a ColdFusion server and an FTP server. CFFTP cannot move files between a ColdFusion server and a browser (client). Use CFFILE ACTION="UPLOAD" to transfer files from the client to a ColdFusion server; use CFCONTENT to transfer files from a ColdFusion server to the browser.
PAGE 88

64 CFML Language Reference PORT="port" CONNECTION="name" PROXYSERVER="proxyserver" PROXYBYPASS="proxybypass" RETRYCOUNT="number" STOPONERROR="Yes/No" PASSIVE="Yes/No"> ACTION Required. Determines the FTP operation to perform. To create an FTP connection, use Open. To terminate an FTP connection, use Close. See Connection Caching for more information. USERNAME Required for Open. User name to pass in the FTP operation. PASSWORD Required for Open. Password to log the user. SERVER Required for Open.
PAGE 89

Chapter 1: ColdFusion Tags 65 RETRYCOUNT Optional. Number of retries until failure is reported. Default is one (1). STOPONERROR Optional. Yes or No. When Yes, halts all processing and displays an appropriate error. Default is Yes. When No, three variables are populated: • CFFTP.Succeeded – Yes or No. • CFFTP.ErrorCode – Error number • CFFTP.ErrorText – Message text explaining error type PASSIVE Optional. Boolean indicating whether to enable passive mode. By default, passive mode is disabled.
PAGE 90

66 CFML Language Reference CONNECTION="my_query"> #name#

Close the connection:
Did it succeed? #CFFTP.Succeeded# ---> File and Directory Operations with CFFTP Use this form of the CFFTP tag to perform file and directory operations with CFFTP.
PAGE 91

Chapter 1: ColdFusion Tags 67 • CreateDir • ListDir • GetFile • PutFile • Rename • Remove • GetCurrentDir • GetCurrentURL • ExistsDir • ExistsFile • Exists Note: Names of objects (files and directories) are case-sensitive; thus, using ListDir on "test.log " will not find a file named "test.LOG. " When ACTION="ListDir", the Attributes column returns either "Directory" or "Normal." Other platform-specific values, such as "Hidden" and "System" are no longer supported.
PAGE 92

68 CFML Language Reference NAME Required for ACTION="ListDir". Specifies the query name to hold the directory listing. See Usage for more information. SERVER Required if the FTP connection is not already cached. If connection caching is used, the SERVER attribute is not required. The FTP server to connect to. TIMEOUT Optional. Value in seconds for the timeout of all operations, including individual data request operations. Defaults to 30 seconds. PORT Optional. The remote port to connect to.
PAGE 93

Chapter 1: ColdFusion Tags 69 ITEM Required for ACTION=Exists, and Remove. Specifies the object, file or directory, of these actions. EXISTING Required for ACTION=Rename. Specifies the current name of the file or directory on the remote server. NEW Required for ACTION=Rename. Specifies the new name of the file or directory on the remote server. RETRYCOUNT Optional. Number of retries until failure is reported. Default is one (1). STOPONERROR Optional. Yes or No.
PAGE 94

70 CFML Language Reference CFFTP.ReturnValue Variable The value of the CFFTP.ReturnValue variable is determined by the results of the ACTION attribute used in CFFTP. CFFTP.ReturnValue Variable CFFTP Action Value of CFFTP.
PAGE 95

Chapter 1: ColdFusion Tags 71 CFFTP Query Object Columns (Continued) Column Description Attributes String indicating attributes of the current element IsDirectory Boolean value indicating whether object is a file or directory Connection Caching Once you’ve established a connection with CFFTP, you can reuse the connection to perform additional FTP operations. To do this, you use the CONNECTION attribute to define and name an FTP connection object that stores information about the connection.
PAGE 96

72 CFML Language Reference PAGE 97
Chapter 1: ColdFusion Tags 73 CFGRID Used inside CFFORM, CFGRID allows you to place a grid control in a ColdFusion form. A grid control is a table of data divided into rows and columns. CFGRID column data is specified with individual CFGRIDCOLUMN tags. See also CFGRIDROW and CFGRIDUPDATE tags.
PAGE 98

74 CFML Language Reference DELETEBUTTON="text" SORTASCENDINGBUTTON="text" SORTDESCENDINGBUTTON="text"> NAME Required. A name for the grid element. HEIGHT Optional. Height value of the grid control in pixels. WIDTH Optional. Width value of the grid control in pixels. VSPACE Optional. Vertical margin spacing above and below the grid control in pixels. HSPACE Optional. Horizontal margin spacing to the left and right of the grid control in pixels. ALIGN Optional. Alignment value.
PAGE 99

Chapter 1: ColdFusion Tags 75 ITALIC Optional. Yes or No. Yes presents all grid control text in italic. Default is No. BOLD Optional. Yes or No. Yes presents all grid control text in boldface. Default is No. HREF Optional. URL to associate with the grid item or a query column for a grid that is populated from a query. If HREF is a query column, then the HREF value that is displayed is populated by the query.
PAGE 100

76 CFML Language Reference TYPE="Image", you can use ROWHEIGHT to define enough room for graphics you want to display in the row. ROWHEADER Optional. Yes or No. Yes displays row labels in the grid control. Defaults to Yes. ROWHEADERALIGN Optional. Enter Left, Right, or Center to position data within a row header. Default is Left. ROWHEADERFONT Optional. Font to use for the row label. ROWHEADERFONTSIZE Optional. Size font for row label text in the grid control, measured in points. ROWHEADERITALIC Optional.
PAGE 101

Chapter 1: ColdFusion Tags 77 A hex value can be entered in the form: BGCOLOR="##xxxxxx" where x is 0-9 or A-F. Use either two pound signs or no pound signs. SELECTCOLOR Optional. Background color for a selected item. See BGCOLOR for color options. SELECTMODE Optional. Selection mode for items in the grid control. Valid entries are: • Edit — Users can edit grid data. • Single — User selections are confined to the selected cell.
PAGE 102

78 CFML Language Reference Usage You can populate a CFGRID with data from a CFQUERY. If you do not specify any CFGRIDCOLUMN entries, a default set of columns is generated. Each column in the query is included in the default column list. In addition, a default header for each column is created by replacing any hyphen (-) or underscore (_) characters in the table column name with spaces. The first character and any character after a space is changed to uppercase; all other characters are lowercase.
PAGE 103

Chapter 1: ColdFusion Tags 79 If the APPENDKEY attribute is set to No, then no grid values are appended to the URL. The value of selection is determined by the value of the SELECTMODE attribute: • When SELECTMODE="Single", selection is the value of the column clicked. • When SELECTMODE="Row", selection is a comma-separated list of column values in the clicked row, beginning with the value of the first cell in the selected row.
PAGE 104

80 CFML Language Reference
PAGE 105

Chapter 1: ColdFusion Tags 81 CFGRIDCOLUMN Used with CFGRID in a CFFORM, you use CFGRIDCOLUMN to specify individual column data in a CFGRID control. Font and alignment attributes used in CFGRIDCOLUMN override any global font or alignment settings defined in CFGRID.
PAGE 106

82 CFML Language Reference BOLD Optional. Yes or No. Yes presents text in the column in boldface. Default is No. HREF Optional. URL to associate with the grid item. You can specify a URL that is relative to the current page: ../mypage.cfm Or an absolute URL: http://myserver.com/mydir/mypage.cfm. HREFKEY Optional. The name of a valid query column when the grid uses a query. The column specified becomes the Key no matter what the select mode is for the grid. TARGET Optional.
PAGE 107

Chapter 1: ColdFusion Tags 83 When TYPE="Numeric", data in the grid can be sorted by the end user as numeric data rather than as simple character text. When TYPE="String_NoCase", data in the grid can be sorted by the end user as case insensitive text data like an Excel spreadsheet rather than as case sensitive character text. HEADERFONT Optional. Font to use for the column header. Defaults to browser-specified font. HEADERFONTSIZE Optional. Font size to use for the column header in pixels.
PAGE 108

84 CFML Language Reference NumberFormat Mask Characters (Continued) Example Character Meaning () Places parentheses around the mask if the number is less than 0. + Places + in front of positive numbers, - (minus sign) in front of negative numbers. - Place " " (space) in front of positive, - (minus sign) in front of negative numbers. , Separates thousands with commas. L,C Specifies left-justify or center-justify a number within the width of the mask column.
PAGE 109

Chapter 1: ColdFusion Tags HEADERBOLD="No" HEADERITALIC="No"> ...
PAGE 110

86 CFML Language Reference CFGRIDROW CFGRIDROW allows you to 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. Syntax DATA Required. A comma-separated list of column values. If a column value contains a comma character, it must be escaped with a second comma character. Example ...
PAGE 111

Chapter 1: ColdFusion Tags 87 CFGRIDUPDATE Used in a CFGRID, CFGRIDUPDATE allows you to perform updates to data sources directly from edited grid data. CFGRIDUPDATE provides a direct interface with your data source. CFGRIDUPDATE first applies DELETE row actions followed by INSERT row actions and finally UPDATE row actions. Row processing stops if any errors are encountered.
PAGE 112

88 CFML Language Reference DBSERVER Optional. For native database drivers and the SQLOLEDB provider, specifies the name of the database server machine. If specified, DBSERVER overrides the server specified in the data source. DBNAME Optional. The database name (Sybase System 11 driver and SQLOLEDB provider only). If specified, DBNAME overrides the default database specified in the data source. TABLENAME Required. The name of the table you want to update.
PAGE 113

Chapter 1: ColdFusion Tags Example ...
PAGE 114

90 CFML Language Reference CFHEADER CFHEADER generates custom HTTP response headers to return to the client. Syntax or NAME Required if you do not specify the STATUSCODE attribute. A name for the header. VALUE Optional. A value for the HTTP header. This attribute is used in conjunction with the NAME attribute. STATUSCODE Required if you do not specify the NAME attribute.
PAGE 115

Chapter 1: ColdFusion Tags 91 CFHTMLHEAD CFHTMLHEAD writes the text specified in the TEXT attribute to the section of a generated HTML page. CFHTMLHEAD can be useful for embedding JavaScript code, or placing other HTML tags such as META, LINK, TITLE, or BASE in an HTML page header. Syntax TEXT The text you want to add to the area of an HTML page. Everything inside the quotation marks is placed in the section.
PAGE 116

92 CFML Language Reference CFHTTP The CFHTTP tag allows you to execute POST and GET operations on files. Using CFHTTP, you can execute standard GET operations as well as create a query object from a text file. POST operations allow you to upload MIME file types to a server, or post cookie, formfield, URL, file, or CGI variables directly to a specified server.
PAGE 117

Chapter 1: ColdFusion Tags 93 PASSWORD Optional. When required by a server, a valid password. NAME Optional. The name to assign to a query when a query is to be constructed from a file. COLUMNS Optional. The column names for a query. If no column names are specified, the query returns all rows in the query except for the first row. To get all the rows in a query, you must specify column names. PATH Optional. The path to the directory in which a file is to be stored.
PAGE 118

94 CFML Language Reference • FRAME SRC • BGSOUND SRC • OBJECT DATA • OBJECT CLASSID • OBJECT CODEBASE • OBJECT USEMAP PROXYSERVER Optional. Host name or IP address of a proxy server. PROXYPORT Optional. The port number on the proxy server from which the object is being requested. Default is 80. When used with RESOLVEURL, the URLs of retrieved documents that specify a port number are automatically resolved to preserve links in the retrieved document. USERAGENT Optional. User agent request header.
PAGE 119

Chapter 1: ColdFusion Tags 95 If there is no timeout set on the URL in the browser, no timeout set in the ColdFusion Administrator, and no timeout set with the TIMEOUT attribute, ColdFusion processes requests synchronously; thus, ColdFusion waits indefinitely for the CFHTTP request to process. Note that you must enable the timeout set in the ColdFusion Administrator in order for the ColdFusion Administrator timeout and the URL timeout to take effect.
PAGE 120

96 CFML Language Reference • Encryption — CFHTTP is capable of using Secure Sockets Layer (SSL) for negotiating secured transactions over the wire. • CFHTTP.StatusCode— CFHTTP throws an error and provides the CFHTTP.StatusCode variable for access to the HTTP error string associated with the error if the THROWONERROR attribute is set to YES. See the following table for all the variables returned by CFHTTP. CFHTTP Variables Example Variable Names Description #CFHTTP.
PAGE 121

Chapter 1: ColdFusion Tags

#cfhttp.filecontent#

The mime-type:

#cfhttp.mimetype#

The Status Code:

#cfhttp.statuscode#

The Raw Header:

#cfhttp.header#

Output the Response Headers:

PAGE 122

98 CFML Language Reference CFHTTPPARAM Required for CFHTTP POST operations, CFHTTPPARAM is used to specify the parameters necessary to build a CFHTTP POST. Syntax NAME Required. A variable name for the data being passed. TYPE Required. The transaction type. Valid entries are: • URL • FormField • Cookie • CGI • File VALUE Optional for TYPE="File".

PAGE 123

Chapter 1: ColdFusion Tags 99 Sample Page

Output the passed variables

Form variable: ##form.form_test##
URL variable: ##URL.url_test##
Cookie variable: ##Cookie.cookie_test##
CGI variable: ##CGI.cgi_test## ")#

For CFHTTPPARAM code, see right frame

...

PAGE 133

Chapter 1: ColdFusion Tags 109 CFINPUT CFINPUT is used inside CFFORM to place radio buttons, checkboxes, or text boxes. Provides input validation for the specified control type.

PAGE 134

110 CFML Language Reference • date — Verifies US date entry in the form mm/dd/yyyy. • eurodate — Verifies valid European date entry in the form dd/mm/yyyy. • time — Verifies a time entry in the form hh:mm:ss. • float — Verifies a floating point entry. • integer — Verifies an integer entry. • telephone — Verifies a telephone entry. Telephone data must be entered as ######-####. The hyphen separator (-) can be replaced with a blank. The area code and exchange must begin with a digit between 1 and 9.

PAGE 135

Chapter 1: ColdFusion Tags 111 If you specify a value in quotation marks, you must escape the quotation marks by doubling them, for example, PASSTHROUGH= "readonly= " "YES " " " Example CFINPUT Example

CFINPUT Example

PAGE 136

112 CFML Language Reference CFINSERT CFINSERT inserts new records in data sources. Syntax DATASOURCE Required. Name of the data source that contains your table. DBTYPE Optional.

PAGE 137

Chapter 1: ColdFusion Tags 113 TABLENAME Required. Name of the table you want the form fields inserted in. Note the following: • ORACLE drivers — This specification must be in uppercase. • Sybase driver — This specification is case-sensitive and must be in the same case as that used when the table was created TABLEOWNER Optional. For data sources that support table ownership (such as SQL Server, Oracle, and Sybase SQL Anywhere), use this field to specify the owner of the table. TABLEQUALIFIER Optional.

PAGE 138

114 CFML Language Reference SELECT CommentID, EMail, FromUser, Subject, CommtType, MessText, Posted, Processed FROM Comments CFINSERT Example

CFINSERT Example

First, we’ll show a list of the available comments in the cfsnippets datasource.

PAGE 139

Chapter 1: ColdFusion Tags 115 CFLDAP CFLDAP provides an interface to LDAP (Lightweight Directory Access Protocol) directory servers like the Netscape Directory Server. For complete examples of CFLDAP usage, refer to Developing Web Applications with ColdFusion.

PAGE 140

116 CFML Language Reference • Modify — Modifies LDAP entries on an LDAP server with the exception of the distinguished name ("DN") attribute. Requires DN, ATTRIBUTES. See the MODIFYTYPE attribute for additional controls. • ModifyDN — Modifies the distinguished name attribute for LDAP entries on an LDAP server. Requires DN, ATTRIBUTES. • Delete — Deletes LDAP entries on an LDAP server. Requires DN. NAME Required for ACTION="Query". The name you assign to the LDAP query. TIMEOUT Optional.

PAGE 141

Chapter 1: ColdFusion Tags 117 FILTERFILE Optional. Specifies the name of a filter file and the name of the stanza tag within that file that contains the LDAP filter string specification. You can specify either an absolute path name or a simple file name to identify the file. If you use a simple file name, CFLDAP looks for it in ColdFusion’s default LDAP directory. The default LDAP directory is C:\cfusion\ldap. The filter file must be in LDAP filter file format as defined in RCF-1558. SORT Optional.

PAGE 142

118 CFML Language Reference SECURE Optional. Identifies the type of security to employ, CFSSL_BASIC or CFSSL_CLIENT_AUTH, and additional information that is required by the specified security type. SECURE="CFSSL_BASIC,certificate_db" or SECURE="CFSSL_CLIENT_AUTH,certificate_db,certificate_name, key_db,key_password" These fields have the following values: certificate_db: The name of the certificate database file (in Netscape cert7.db format). You can specify either an absolute path or a simple file name.

PAGE 143

Chapter 1: ColdFusion Tags 119 The CFSSL_BASIC type of security provides V2 SSL, and the CFSSL_CLIENT_AUTH type of security provides V3 SSL. V2 SSL provides encryption and server authentication. V3 SSL adds to this certificate-based client authentication. Both forms of security encrypt the conversation, and the server always sends a digital certificate to confirm that it is the right server. For CFSSL_BASIC, you must also specify the CFLDAP attributes USERNAME and PASSWORD to authenticate yourself.

PAGE 144

120 CFML Language Reference Name Organization Location E-Mail Phone #cn# #o# #l#, #st#, #c# #mail# #telephonenumber# <

PAGE 145

Chapter 1: ColdFusion Tags 121 CFLOCATION CFLOCATION opens a specified ColdFusion page or HTML file. For example, you might use CFLOCATION to specify a standard message or response that you use in several different ColdFusion applications. Use the ADDTOKEN attribute to verify client requests. Syntax URL The URL of the HTML file or CFML page you want to open. ADDTOKEN Optional. Yes or No. CLIENTMANAGEMENT must be enabled (see CFAPPLICATION).

PAGE 146

122 CFML Language Reference CFLOCK The CFLOCK tag provides two types of locks to ensure the integrity of shared data: • exclusive lock • read-only lock An exclusive lock single-threads access to the CFML constructs in its body. Singlethreaded access implies that the body of the tag can be executed by at most one request at a time. A request executing inside a CFLOCK tag has an "exclusive lock" on the tag.

PAGE 147

Chapter 1: ColdFusion Tags 123 THROWONTIMEOUT Optional. Yes or No. Specifies how timeout conditions should be handled. If the value is Yes an exception will be generated to provide notification of the timeout. If the value is No execution continues past the tag. Default is Yes. TYPE Optional. ReadOnly or Exclusive. Specifies the type of lock: read-only or exclusive. Default is Exclusive. A read-only lock allows more than one request to read shared data.

PAGE 148

124 CFML Language Reference following table shows which features are available for Server, Application, and Session scope. Features Server Application Session No automatic checking or locking Yes Yes Yes Full checking Yes Yes Yes Automatic read locking Yes Yes Yes Single Threaded Sessions Yes Each feature that you select has tradeoffs. • No automatic checking or locking. If you select this button, no reads or writes are locked or checked for correct protection.

PAGE 149

Chapter 1: ColdFusion Tags 125 Thus, all requests to the protected section of the page are blocked until there is a timeout. The following tables show two scenarios that cause deadlocks. Deadlock Scenario with Two Users User 1 User 2 Locks the session scope . Locks the application scope. Deadlock: Tries to lock application scope, but application scope already is locked by User 2. Deadlock: Tries to lock the session scope, but session scope already is locked by User 1.

PAGE 150

126 CFML Language Reference Note 2. Lock the application scope. In the CFLOCK tag, indicate scope by specifying "APPLICATION" as the value of the SCOPE attribute. 3. Lock the server scope. In the CFLOCK tag, indicate the scope by specifying "SERVER" as the value of the SCOPE attribute. 4. Unlock the server scope. 5. Unlock the application scope. 6. Unlock the session scope. You can take out any pair of lock/unlock steps if you do not need to lock a particular scope.

PAGE 151

Chapter 1: ColdFusion Tags 127

Congratulations! You have just selected the longest wearing, most comfortable turtleneck in the world. Please indicate the color and size that you wish to buy.

Select a color. PAGE 153 Chapter 1: ColdFusion Tags 129 CFLOOP Looping is a very powerful programming technique that lets you repeat a set of instructions or display output over and over until one or more conditions are met. CFLOOP supports five different types of loops: • Index Loops • Conditional Loops • Looping over a Query • Looping over a List • Looping over a COM Collection or Structure The type of loop is determined by the attributes of the CFLOOP tag. PAGE 154 130 CFML Language Reference FROM="1" TO="5"> The loop index is #LoopCount#. The result of this loop in a browser looks like this: The The The The The loop loop loop loop loop index index index index index is is is is is 1. 2. 3. 4. 5. In this example, the STEP value has a default value of 1. But you can set the STEP value to change the way the INDEX value is incremented. PAGE 155 Chapter 1: ColdFusion Tags 131 The loop index is #CountVar#. The result of this loop in a browser would look something like: The The The The The loop loop loop loop loop index index index index index is is is is is 1. 2. 3. 4. 5. Looping over a Query A loop over a query repeats for every record in the query record set. The CFLOOP results are just like a CFOUTPUT. PAGE 156 132 CFML Language Reference The following example loops from the tenth through the twentieth record returned by "MyQuery ": #MyQuery.MyColName# The loop is done when there are no more records or when the current record is greater than the value of the ENDROW attribute. PAGE 157 Chapter 1: ColdFusion Tags 133 DELIMITERS Optional. Specifies the delimiter characters used to separate items in the LIST. Example This loop will display the names of each of the Beatles: #ListElement# Although CFLOOP expects elements in the list to be separated by commas by default, you are free to specify your own element boundaries in the DELIMITER attribute. PAGE 158 134 CFML Language Reference Examples This example employs a COM object to output a list of files. In this example, FFUNC is a collection of file2 objects. FFunc.Mask = "." > FFunc.attributes = 16 > x=FFunc.GetFileList()> #file2.name# This example loops through a structure (used as an associative array): ... PAGE 159 Chapter 1: ColdFusion Tags 135 CFMAIL CFMAIL allows you to send email messages via an SMTP server. See also CFMAILPARAM. Syntax TO Required. The name of the recipient(s) of the email message. PAGE 160 136 CFML Language Reference TYPE Optional. Specifies extended type attributes for the message. Currently, the only valid value for this attribute is "HTML". Specifying TYPE= "HTML" informs the receiving email client that the message has embedded HTML tags that need to be processed. This is only useful when sending messages to mail clients that understand HTML (such as Netscape 2.0 and above email clients). MAXROWS Optional. Specifies the maximum number of email messages you want to send. PAGE 161 Chapter 1: ColdFusion Tags 137 TIMEOUT Optional. The number of seconds to wait before timing out the connection to the SMTP server. Example CFMAIL Example CFMAIL Example This view-only example shows the use of CFMAIL. If your CFAS mail settings are configured successfully and the comments are removed, you will be able to use this code to send simple email. PAGE 162 138 CFML Language Reference CFMAILPARAM CFMAILPARAM can either attach a file or add a header to a message. If you use CFMAILPARAM, it is nested within a CFMAIL tag. You can use more than one CFMAILPARAM tags within a CFMAIL tag in order to attach one or more files and headers. See also CFMAIL. Syntax or ... PAGE 163 Chapter 1: ColdFusion Tags 139 Please read the text file and view the new logo, and let us know what you think. PAGE 164 140 CFML Language Reference CFMODULE Use CFMODULE to invoke a custom tag for use in your ColdFusion application pages. CFMODULE can help deal with any custom tag name conflicts that might arise. Use the TEMPLATE attribute to name a ColdFusion page containing the custom tag definition, including its path. Use the NAME attribute to refer to the custom tag using a dot notation scheme indicating the location of the custom tag in the ColdFusion installation directory. PAGE 165 Chapter 1: ColdFusion Tags 141 Likewise, if the custom tag uses a CFASSOCIATE tag to save its attributes, the attributes passed with ATTRIBUTECOLLECTION are saved as independent attribute values with no indication that the attributes are grouped into a structure by the custom tag’s caller. PAGE 166 142 CFML Language Reference attributeCollection=##attrCollection1## Y=4>")# The result: #result# Here is another way to invoke the custom tag, using the NAME attribute. PAGE 167 Chapter 1: ColdFusion Tags 143 CFOBJECT The CFOBJECT tag allows you to call methods in COM, CORBA, and JAVA objects. Note ColdFusion administrators can disable the CFOBJECT tag in the ColdFusion Administrator Basic Security page. On UNIX, COM objects are not currently supported by CFOBJECT. PAGE 168 144 CFML Language Reference CFOBJECT Type="COM" CFOBJECT allows you to create and use COM (Component Object Model) objects. Any automation server object type that is currently registered on a machine can be invoked. You can use a utility like Microsoft’s OLEView to browse COM objects. OLEView, as well as information about COM and DCOM, can be found at Microsoft’s OLE Development web site http://www.microsoft.com/oledev/. PAGE 169 Chapter 1: ColdFusion Tags Example CFOBJECT (COM) Example CFOBJECT (COM) Example PAGE 170 146 CFML Language Reference Last name: #file2.lastname# ... CFOBJECT Type="CORBA" CFOBJECT allows you to call methods in CORBA objects. These CORBA objects must already have been defined and registered for use. Syntax CONTEXT Required. PAGE 171 Chapter 1: ColdFusion Tags 147 Note that each type-value pair has to start with a leading "-". Usage ColdFusion Enterprise version 4.0 and above supports CORBA through the Dynamic Invocation Interface (DII). To use CFOBJECT with CORBA objects, you need to know either the name of the file containing a stringified version of the IOR or the object’s naming context in the naming service. You also need to know the object’s attributes, method names and method signatures. PAGE 172 148 CFML Language Reference 1. Call CFOBJECT to load the class. See Example. 2. Use the init method with appropriate arguments to call a constructor explicitly. For example: Calling a public method on the object without first calling the "init" method results in an implicit call to the default constructor. Arguments and return values can be any valid Java type (simple, arrays, objects). PAGE 173 Chapter 1: ColdFusion Tags 149 CFOUTPUT Displays the results of a database query or other operation. If you need to nest CFOUTPUT tags, please read the "Usage" section. Syntax QUERY Optional. The name of the CFQUERY from which you want to draw data for the output section. GROUP Optional. Specifies the query column to use when you group sets of records together. PAGE 174 150 Example CFML Language Reference SELECT Dept_ID, CorName, CorLevel FROM courseList ORDER by Dept_ID, CorLevel, CorName CFOUTPUT CFOUTPUT Example CFOUTPUT simply tells ColdFusion Server to begin processing, and then to hand back control of page rendering to the web server. PAGE 175 Chapter 1: ColdFusion Tags 151 CFPARAM CFPARAM is used to test for a parameter’s existence, and optionally test its data type, and provide a default value if one is not assigned. Syntax DEFAULT="value"> NAME The name of the parameter you are testing (such as "Client.Email " or "Cookie.BackgroundColor "). If you omit the DEFAULT attribute, an error occurs if the specified parameter does not exist. TYPE Optional. The type of parameter that is required. PAGE 176 152 CFML Language Reference Usage There are three ways to use CFPARAM: • Test for a required variable — Use CFPARAM with only the NAME attribute to test that a required variable exists. If the variable does not exist, ColdFusion server stops processing the page and returns an error. • Test for a required variable and for the type of variable — Use CFPARAM with the NAME attribute and the TYPE attribute to test that a required variable exists, and that it is of the specified type. PAGE 177 Chapter 1: ColdFusion Tags PAGE 178 154 CFML Language Reference CFPOP CFPOP retrieves and deletes email messages from a POP mail server. See also CFMAIL. Syntax SERVER Required. Host name (biff.upperlip.com) or IP address (192.1.2.225) of the POP server. PORT Optional. PAGE 179 Chapter 1: ColdFusion Tags 155 NAME Optional. The name you assign to the index query. Required for ACTION="GetHeaderOnly" and ACTION="GetAll". MESSAGENUMBER Optional. Specifies the message number(s) for the given action. MESSAGENUMBER is required for ACTION="Delete". If it is provided for ACTION="GetHeaderOnly" or ACTION="GetAll", only referenced messages will be retrieved. If it is omitted for ACTION="GetHeaderOnly"or ACTION="GetAll", all messages available on the server are returned. PAGE 180 156 CFML Language Reference CFPOP Query Variables (Continued) Message Header and Body Columns Variable Names Description queryname.CurrentRow The current row of the query being processed by CFOUTPUT. queryname.ColumnList The list of the column names in the query. The following table lists the message header and body columns that are returned by CFPOP when you specify the ACTION attribute to be either GetHeaderOnly or GetAll. PAGE 181 Chapter 1: ColdFusion Tags 157 Usage 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 to determine what to do. Date-Time Parsing According to Locale Locale What to do? English (US) locale Use the ParseDateTime function and specify the POP attribute, which converts the date-time value to Greenwich Meantime. PAGE 182 158 CFML Language Reference Row: #CurrentRow#: From: #From# -- Subject: #Subject# PAGE 183 Chapter 1: ColdFusion Tags 159 CFPROCESSINGDIRECTIVE Suppresses extraneous white space, and other output, produced by the CFML within the tag’s scope. Syntax … any CFML tags here … SUPPRESSWHITESPACE Required. Boolean indicating whether to suppress the white space and other output generated by the CFML tags within the CFPROCESSINGDIRECTIVE block. PAGE 184 160 CFML Language Reference CFPROCPARAM The CFPROCPARAM tag is nested within a CFSTOREDPROC tag. You use it to specify parameter information, including type, name, value, and length. Syntax TYPE Optional. Indicates whether the passed variable is an input, output or input/ output variable. Default is IN. PAGE 185 Chapter 1: ColdFusion Tags 161 MAXLENGTH Optional. Maximum length of the parameter. SCALE Optional. Number of decimal places of the parameter. NULL Optional. Specify Yes or No. Indicates whether the parameter is passed as a NULL. If you specify Yes, the tag ignores the VALUE attribute. Usage Use this tag to identify stored procedure parameters and their data type. Code one CFPROCPARAM tag for each parameter. The parameters you code vary, based on parameter type and DBMS. PAGE 186 162 CFML Language Reference The Results Information #NAME#,#DATE_COL# Record Count: #RS1.RecordCount# >p>Columns: #RS1.ColumnList# #col1#,#col2#,#col3# Record Count: #RS3.RecordCount# Columns: #RS3.ColumnList# The return code for the stored procedure is: ’#CFSTOREDPROC.STATUSCODE#’ ... PAGE 187 Chapter 1: ColdFusion Tags 163 CFPROCRESULT The CFPROCRESULT tag is nested within a CFSTOREDPROC tag. This tag’s NAME parameter specifies a result set name that other ColdFusion tags, such as CFOUTPUT and CFTABLE, use to access the result set. It also allows you to optionally identify which of the stored procedure’s result sets to return. Syntax NAME Required. Name for the query result set. RESULTSET Optional. PAGE 188 164 CFML Language Reference The output param value: ’#foo#’ The Results Information #NAME#,#DATE_COL# Record Count: #RS1.RecordCount# >p>Columns: #RS1.ColumnList# #col1#,#col2#,#col3# Record Count: #RS3.RecordCount# Columns: #RS3.ColumnList# The return code for the stored procedure is: ’#CFSTOREDPROC. PAGE 189 Chapter 1: ColdFusion Tags 165 CFQUERY CFQUERY passes SQL statements for any purpose to your data source. Not limited to queries. Syntax SQL statements NAME Required. PAGE 190 166 CFML Language Reference • DB2 —DB2 5.2 native database driver. • Informix73 —Informix73 native database driver. DBSERVER Optional. For native database drivers and the SQLOLEDB provider, specifies the name of the database server machine. If specified, DBSERVER overrides the server specified in the data source. DBNAME Optional. The database name (Sybase System 11 driver and SQLOLEDB provider only). If specified, DBNAME overrides the default database specified in the data source. USERNAME Optional. PAGE 191 Chapter 1: ColdFusion Tags 167 When specifying a date value as a string, make sure it is enclosed in quotes. CACHEDWITHIN Optional. Enter a timespan using the ColdFusion CreateTimeSpan function. Cached query data will be used if the original query date falls within the time span you define. The CreateTimeSpan function is used to define a period of time from the present backwards. Effective only if query caching has been enabled in the ColdFusion Administrator. PAGE 192 168 Example CFML Language Reference CFQUERY Example CFQUERY Example SELECT PARKNAME, REGION, STATE FROM Parks ORDER by ParkName, State
PAGE 194 170 CFML Language Reference CFQUERYPARAM CFQUERYPARAM checks the data type of a query parameter. The CFQUERYPARAM tag is nested within a CFQUERY tag. More specifically, it is embedded within the query SQL statement. If you specify its optional parameters, CFQUERYPARAM also performs data validation. Note For data, you must specify the MAXLENGTH attribute in order to ensure that maximum length validation is enforced. See the Usage section for details. PAGE 195 Chapter 1: ColdFusion Tags 171 MAXLENGTH Optional. Maximum length of the parameter. The default value is the length of the string specified in the VALUE attribute. SCALE Optional. Number of decimal places of the parameter. The default value is zero. Applicable for CF_SQL_NUMERIC and CF_SQL_DECIMAL. NULL Optional. Specify Yes or No. Indicates whether the parameter is passed as a NULL. If you specify Yes, the tag ignores the VALUE attribute. The default value is No. PAGE 196 172 CFML Language Reference For a Sybase11 data source, the syntax of the SQL statement is as follows: SELECT * FROM courses WHERE col1=10 Example CFREGISTRY ACTION="GetAll" CFREGISTRY ACTION="GetAll" PAGE 201 Chapter 1: ColdFusion Tags 177 VARIABLE Required. Variable into which CFREGISTRY places the value. Usage CFREGISTRY does not create the variable if the value does not exist. PAGE 202 178 CFML Language Reference VALUE Optional. The value data to be set. If you omit this attribute, CFREGISTRY creates default value data, as follows: • String — Default value is an empty string: "" • DWord — Default value is 0 (zero) Usage CFREGISTRY creates the key or value if it does not exist. PAGE 203 Chapter 1: ColdFusion Tags 179 Usage If you delete a key, CFREGISTRY also deletes values and subkeys defined beneath the key. PAGE 204 180 CFML Language Reference CFREPORT CFREPORT runs a predefined Crystal Reports report. Syntax REPORT Required. Specifies the path of the report. Store your Crystal Reports files in the same directories that you store your ColdFusion page files. ORDERBY Optional. Orders results according to your specifications. USERNAME Optional. PAGE 205 Chapter 1: ColdFusion Tags The CFREPORT tag requires the name of the report to run; CFREPORT can also pass information to the report file being displayed to change the output conditions. This example would run a report called “monthlysales.rpt " and pass it an optional filter condition to show only the information for a certain subset of the report. {Departments. PAGE 206 182 CFML Language Reference CFRETHROW Rethrows the currently active exception. preserves the exception’s CFCATCH.TYPE and CFCATCH.TAGCONTEXT information. See also CFTRY/CFCATCH. Syntax Usage Use the tag within a block. This tag is useful in error handling code when the error handler is not able to successfully handle the thrown error. PAGE 207 Chapter 1: ColdFusion Tags 183 PAGE 208 184 CFML Language Reference CFSCRIPT The CFSCRIPT tag encloses a code segment containing CFScript. Syntax CFScript code goes here Usage Use CFSCRIPT to perform processing in CFScript instead of CFML. Note the following regarding CFScript: • CFScript uses ColdFusion functions, expressions, and operators • You can read and write ColdFusion variables inside of CFScript One use of CFSCRIPT is to wrap a series of assignment functions that would otherwise require CFSET statements. PAGE 209 Chapter 1: ColdFusion Tags 185 CFSEARCH Use the CFSEARCH tag to execute searches against data indexed in Verity collections. Collections can be created by calling the CFCOLLECTION tag, by using the ColdFusion Administrator, or through native Verity indexing tools. Collections are populated with data either with the CFINDEX tag, or externally, using native Verity indexing tools. Collections must be created and populated before any searches can be executed. PAGE 210 186 CFML Language Reference STARTROW Optional. Specifies the first row number to be retrieved. Default is 1. EXTERNAL Optional. Yes or No. Yes indicates that the collection you are searching was created outside of ColdFusion using native Verity indexing tools. The default is No. LANGUAGE Optional. To use the LANGUAGE attribute you must have the ColdFusion International Search Pack installed. PAGE 211 Chapter 1: ColdFusion Tags 187 • SUMMARY — Returns the contents of the automatic summary generated by CFINDEX. The default summarization selects the best three matching sentences, up to a maximum of 500 characters. • RECORDCOUNT — Returns the number of records returned in the record set. • CURRENTROW — Returns the current row being processed by CFOUTPUT. • COLUMNLIST — Returns the list of the column names within the record set. • RECORDSSEARCHED— Returns the number of records searched. PAGE 212 188 CFML Language Reference #SearchSnippets.RecordCount# "hit s" found out of #SearchSnippets.RecordsSearched# total record s searched. #form.maxrows# records returned ... PAGE 213 Chapter 1: ColdFusion Tags 189 CFSELECT Used inside CFFORM, CFSELECT allows you to construct a drop-down list box form control. You can populate the drop-down list box from a query, or using the OPTION tag. Use OPTION elements to populate lists. Syntax for the OPTION tag is the same as for its HTML counterpart. PAGE 214 190 CFML Language Reference VALUE Optional. The query column value for the list element. Used with the QUERY attribute. DISPLAY Optional. The query column displayed. Defaults to the value of VALUE. Used with the QUERY attribute. PASSTHROUGH Optional. HTML attributes that are not explicitly supported by CFSELECT. If you specify an attribute and its value, the attribute and its value are passed to the HTML code that is generated for the CFSELECT tag. PAGE 215 Chapter 1: ColdFusion Tags 191 CFSELECT Example CFSELECT Example CFSELECT Presentation of Data Click on an employee’s last name and hit "see information for this employee" to see expanded information. PAGE 216 192 CFML Language Reference CFSERVLET Executes a Java servlet on a JRun engine. This tag is used in conjunction with the CFSERVLETPARAM tag, which passes data to the servlet. Syntax ... CODE Required. The class name of the Java servlet to execute. JRUNPROXY Optional. PAGE 217 Chapter 1: ColdFusion Tags 193 Usage The syntax of the CFSERVLET tag is designed to be consistent with the HTML markup and used by some web servers to invoke Java servlets from .shtml pages in what is known as SSI, Server-Side Includes. CFSERVLET Variables Variable Name Description CFSERVLET.Output Inline text output of the servlet is directed to this structure if the WRITEOUTPUT attribute is set to No. CFSERVLET. PAGE 218 194 CFML Language Reference CFSERVLETPARAM The CFSERVLETPARAM is a child of CFSERVLET. It is used to pass data to the servlet. Each CFSERVLETPARAM tag within the CFSERVLET block passes a separate piece of data to the servlet. See also CFSERVLET. Syntax ... ... PAGE 219 Chapter 1: ColdFusion Tags 195 The first passes name-value pairs by value. This method uses the attributes NAME and VALUE to pass a simple name-value string pair to the servlet. The NAME attribute represents the name of the servlet parameter from which the string specified in the VALUE attribute can be retrieved. Although the servlet can use these parameters as input, it cannot change their values in the ColdFusion template. The second passes a ColdFusion variable to the servlet by reference. PAGE 220 196 Example CFML Language Reference PAGE 221 Chapter 1: ColdFusion Tags 197 CFSET Use the CFSET tag to define a ColdFusion variable. If the variable already exists, CFSET resets it to the specified value. Syntax Arrays The following example assigns a new array to the variable "months". This example creates a variable "Array_Length" that resolves to the length of the array "Scores". PAGE 222 198 Example CFML Language Reference SELECT * FROM Messages CFSET Example CFSET Example CFSET allows you to set and reassign values to local or global variables within a CF template. PAGE 223 Chapter 1: ColdFusion Tags 199 CFSETTING CFSETTING is used to control various aspects of page processing, such as controlling the output of HTML code in your pages. One benefit of this option is managing whitespace that can occur in output pages that are served by ColdFusion. Syntax ENABLECFOUTPUTONLY Required. Yes or No. PAGE 224 200 CFML Language Reference Text within CFOUTPUT is always shown PAGE 225 Chapter 1: ColdFusion Tags 201 CFSILENT CFSILENT suppresses all output that is produced by the CFML within the tag’s scope. See also CFSETTING. Syntax Example CFSILENT CFSILENT #c# ... PAGE 226 202 CFML Language Reference CFSLIDER Used inside CFFORM, CFSLIDER allows you to place a slider control in a ColdFusion form. A slider control is like a sliding volume control. The slider groove is the area over which the slider moves. Note Syntax CFSLIDER incorporates a Java applet, so a browser must be Java-enabled for CFSLIDER to work properly. PAGE 227 Chapter 1: ColdFusion Tags 203 IMGSTYLE Optional. Style of the image to appear in the slider groove. Valid entries are: • Centered • Tiled • Scaled Default is Scaled. RANGE Optional. Determines the values of the left and right slider range. The slider value appears as the slider is moved. Separate values by a comma, for example: RANGE="1,100" Default is "0,100". Valid only for numeric data. SCALE Optional. An unsigned integer. SCALE defines the slider scale within the value of RANGE. PAGE 228 204 CFML Language Reference ALIGN Optional. Alignment value. Valid entries are: • Top • Left • Bottom • Baseline • TextTop • AbsBottom • Middle • AbsMiddle • Right GROOVECOLOR Optional. Color value of the slider groove. The slider groove is the area in which the slider box moves. Valid entries are: • black • magenta • cyan • orange • darkgray • pink • gray • white • lightgray • yellow A hex value can be entered in the form: GROOVECOLOR="##xxxxxx" Where x is 0–9 or A–F. PAGE 229 Chapter 1: ColdFusion Tags 205 FONTSIZE Optional. Font size for label text measured in points. ITALIC Optional. Enter Yes for italicized label text, No for normal text. Default is No. BOLD Optional. Enter Yes for bold label text, No for medium text. Default is No. NOTSUPPORTED Optional. The text you want to display if the page containing a Java applet-based CFFORM control is opened by a browser that does not support Java or has Java support disabled. PAGE 230 206 CFML Language Reference MESSAGE="Slide the bar to get a value between 1 and 100" HEIGHT="20" WIDTH="150" FONT="Verdana" BGCOLOR="Silver" GROOVECOLOR="Lime" BOLD="No" ITALIC="Yes" REFRESHLABEL="Yes"> 100 PAGE 231 Chapter 1: ColdFusion Tags 207 CFSTOREDPROC The CFSTOREDPROC tag is the main tag used for executing stored procedures via an ODBC or native connection to a server database. It specifies database connection information and identifies the stored procedure. PAGE 232 208 CFML Language Reference PROVIDERDSN Optional. Data source name for the COM provider (OLE-DB only). DEBUG Optional. Yes or No. Specifies whether debug info will be listed on each statement. Default is No. RETURNCODE Optional. Yes or No. Specifies whether the tag populates CFSTOREDPROC.STATUSCODE with the status code returned by the stored procedure. Default is No. Usage Within a CFSTOREDPROC tag, you code CFPROCRESULT and CFPROCPARAM tags as necessary. PAGE 233 Chapter 1: ColdFusion Tags The output param value: ’#foo#’ The Results Information #NAME#,#DATE_COL# Record Count: #RS1.RecordCount# >p>Columns: #RS1.ColumnList# #col1#,#col2#,#col3# Record Count: #RS3.RecordCount# Columns: #RS3.ColumnList# The return code for the stored procedure is: ’#CFSTOREDPROC.STATUSCODE#’ ... PAGE 234 210 CFML Language Reference CFSWITCH/CFCASE/CFDEFAULTCASE Used with CFCASE and CFDEFAULTCASE, the CFSWITCH tag evaluates a passed expression and passes control to the CFCASE tag that matches the expression result. You can optionally code a CFDEFAULTCASE tag, which receives control if there is no matching CFCASE tag value. PAGE 235 Chapter 1: ColdFusion Tags Example SELECT Emp_ID, FirstName, LastName, EMail, Phone, Department FROM Employees CFSWITCH Example CFSWITCH Example CFTRANSACTION Example CFTRANSACTION Example CFTRANSACTION can be used to group multiple queries using CFQUERY into a single business event. Changes to data requested by these queries can be committed on the basis of the success or failure of the query by using the actions COMMIT and ROLLBACK, respectively. PAGE 246 222 CFML Language Reference CorName, CorLevel, LastUpdate) VALUES (’#myNumber#’, ’#myDescription#’, ’#myDepartment#’, ’#myDescription#’, ’#myCorLevel#’, #Now()#) CFSELECT Presentation of Data Click on an employee’s last name and hit "see information for this employee" to see expanded information. PAGE 251 Chapter 1: ColdFusion Tags EXPAND="No" QUERYASROOT="No"> ... PAGE 252 228 CFML Language Reference CFTREEITEM Use CFTREEITEM to populate a tree control created with CFTREE with individual elements. You can use the IMG values supplied with ColdFusion or reference your own icons. Note Syntax CFTREEITEM incorporates a Java applet, so a browser must be Javaenabled for CFTREE to work properly. PAGE 253 Chapter 1: ColdFusion Tags 229 • folder • floppy • fixed • remote Use commas to separate image names corresponding to tree level, for example: IMG="folder,document" IMG=",document To specify your own custom image, specify the path and file extension: IMG="../images/page1.gif" IMGOPEN Optional. Icon displayed with open tree item. You can specify the icon filename using a relative path. As with IMG, you can use an image supplied with ColdFusion. HREF Optional. PAGE 254 230 CFML Language Reference #CFCATCH.message# Caught an exception, type = #CFCATCH.TYPE# The contents of the tag stack are: PAGE 260 236 CFML Language Reference CFUPDATE The CFUPDATE tag updates existing records in data sources. Syntax DATASOURCE Required. Name of the data source that contains your table. DBTYPE Optional. PAGE 261 Chapter 1: ColdFusion Tags 237 TABLENAME Required. Name of the table you want to update. Note the following: • ORACLE drivers — This specification must be in uppercase. • Sybase driver — This specification is case-sensitive and must be in the same case as that used when the table was created TABLEOWNER Optional. For data sources that support table ownership (for example, SQL Server, Oracle, and Sybase SQL Anywhere), use this field to specify the owner of the table. TABLEQUALIFIER Optional. PAGE 262 238 CFML Language Reference ---> SELECT Number, Course_ID, Descript FROM Courses WHERE Course_ID = #url.course_ID# ORDER by Number CFUPDATE Example CFUPDATE Example PAGE 263 Chapter 1: ColdFusion Tags 239 CFWDDX The CFWDDX tag serializes and de-serializes CFML data structures to the XML-based WDDX format. You can also use it to generate JavaScript statements instantiating JavaScript objects equivalent to the contents of a WDDX packet or some CFML data structures. Syntax ACTION Specifies the action taken by the CFWDDX tag. PAGE 264 240 CFML Language Reference For complete information on WDDX, see the "Programming with XML " chapter in Developing Web Applications with ColdFusion. Example CFWDDX Tag select Message_Id, Thread_id, Username from messages The recordset data is:... PAGE 265 CHAPTER 2 Chapter 2 ColdFusion Functions This chapter describes each of the functions in the ColdFusion Markup Language (CFML). The introduction contains an alphabetical summary of ColdFusion functions, a list of new functions in ColdFusion 4.5, and a list of functions by category. The remainder of this chapter provides complete descriptions of each function, listed alphabetically. Contents • Alphabetical List of ColdFusion Functions.................................................. PAGE 266 242 CFML Language Reference Alphabetical List of ColdFusion Functions Abs BitMaskRead DatePart GetBaseTagList ACos BitMaskSet Day GetBaseTemplatePath ArrayAppend BitNot DayOfWeek GetClientVariablesList ArrayAvg BitOr DayOfWeekAsString GetCurrentTemplatePath ArrayClear BitSHLN DayOfYear GetDirectoryFromPath ArrayDeleteAt BitSHRN DaysInMonth GetFileFromPath ArrayInsertAt BitXor DaysInYear GetFunctionList ArrayIsEmpty Ceiling DE GetLocale ArrayLen Chr DecimalFormat GetMetri PAGE 267 Chapter 2: ColdFusion Functions 243 IsAuthorized ListLen Minute REReplaceNoCase IsBinary ListPrepend Month Reverse IsBoolean ListQualify MonthAsString Right IsDate ListRest Now RJustify IsDebugMode ListSetAt NumberFormat Round IsDefined ListSort NumberFormat RTrim IsLeapYear ListToArray ParagraphFormat Second IsNumeric ListValueCount ParameterExists SetLocale IsNumericDate ListValueCountNoCase ParseDateTime SetProfileString IsProtected LJustify Pi SetVariable IsQuer PAGE 268 244 CFML Language Reference Tan ToString URLEncodedFormat WriteOutput TimeFormat Trim Val XMLFormat ToBase64 UCase ValueList Year ToBinary URLDecode Week YesNoFormat PAGE 269 Chapter 2: ColdFusion Functions 245 New Functions in ColdFusion 4. PAGE 270 246 CFML Language Reference Date and Time Functions CreateDate DatePart IsLeapYear CreateDateTime Day IsNumericDate CreateODBCDate DayOfWeek Minute CreateODBCDateTime DayOfWeekAsString Month CreateODBCTime DayOfYear MonthAsString CreateTime DaysInMonth Now CreateTimeSpan DaysInYear ParseDateTime DateCompare FirstDayOfMonth Quarter DateConvert GetTimeZoneInfo Second DateDiff Hour Week DateFormat IsDate XMLFormat Decision Functions IsArray IsNumericDate IsAuthenticated Is PAGE 271 Chapter 2: ColdFusion Functions 247 Display and Formatting Functions DateFormat LSEuroCurrencyFormat DecimalFormat LSNumberFormat DollarFormat LSTimeFormat FormatBaseN NumberFormat HTMLCodeFormat ParagraphFormat HTMLEditFormat TimeFormat LSCurrencyFormat YesNoFormat LSDateFormat Dynamic Evaluation Functions DE IIf Evaluate SetVariable International Functions DateConvert LSIsNumeric GetLocale LSNumberFormat GetTimeZoneInfo LSParseCurrency LSCurrencyFormat LSParseDateTime LSDateFo PAGE 272 248 CFML Language Reference List Functions ArrayToList ListLast ListAppend ListLen ListChangeDelims ListPrepend ListContains ListQualify ListContainsNoCase ListRest ListDeleteAt ListSetAt ListFind ListSort ListFindNoCase ListToArray ListFirst ListValueCount ListGetAt ListValueCountNoCase ListInsertAt Mathematical Functions Abs BitXor Max ACos Ceiling Min ASin Cos Pi Atn DecrementValue Rand BitAnd Exp Randomize BitMaskClear Fix RandRange BitMaskRead IncrementValue R PAGE 273 Chapter 2: ColdFusion Functions 249 Query Functions IsQuery QuerySetCell QueryAddColumn QuotedValueList QueryAddRow ValueList QueryNew String Functions Asc LJustify Replace Chr ListValueCount ReplaceList CJustify ListValueCountNoCase ReplaceNoCase Compare LSParseCurrency REReplace CompareNoCase LSParseDateTime REReplaceNoCase DayOfWeekAsString LSParseEuroCurrency Reverse FormatBaseN LSParseNumber Right Find LTrim RJustify FindNoCase Mid RTrim FindOneOf MonthAsString Spa PAGE 274 250 CFML Language Reference Structure Functions IsStruct StructIsEmpty StructClear StructKeyArray StructCopy StructKeyExists StructCount StructKeyList StructDelete StructNew StructFind StructUpdate StructInsert System Functions DirectoryExists GetFileFromPath ExpandPath GetMetricData FileExists GetTempFile GetCurrentTemplatePath GetTemplatePath GetDirectoryFromPath SetProfileString Other Functions CreateObject GetClientVariablesList CreateUUID GetTickCount Decrypt PreserveSingl PAGE 275 Chapter 2: ColdFusion Functions 251 Abs Returns the absolute value of a number. The absolute value of a number is the number without its sign. See also Sgn. Syntax Abs(number) number Any number. Examples Abs 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. PAGE 276 252 CFML Language Reference ACos Returns the arccosine of a number in radians. The arccosine is the angle whose cosine is number. See also Cos, Sin, ASin, Tan, and Pi. Syntax ACos(number) number Cosine of the angle that is to be calculated. This value must be between -1 and 1, 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 277 Chapter 2: ColdFusion Functions Type in a number to get its arccosine in Radians and Degrees. PAGE 278 254 CFML Language Reference ArrayAppend Appends an array index to the end of the specified array. Returns a Boolean TRUE on successful completion. See also ArrayPrepend. Syntax ArrayAppend(array, value) array Name of the array to which you want to append an index. value The value you want to place into the specified array in the last index position. PAGE 279 Chapter 2: ColdFusion Functions 255 ArrayAvg Returns the average of the values in the specified array. Syntax ArrayAvg(array) array Name of the array containing values you want to average. Example PAGE 281 Chapter 2: ColdFusion Functions ArrayClear Deletes all data in the specified array. Returns a Boolean TRUE on successful completion. See also ArrayDeleteAt. Syntax ArrayClear(array) array Name of the array in which you want to delete data. PAGE 282 258 CFML Language Reference ArrayDeleteAt Deletes data from the specified array at the specified index position. Note that when an array index is deleted, index positions in the array are recalculated. For example, in an array containing the months of the year, deleting index position [5] removes the entry for May. If you then want to delete the entry for November, you delete index position [10], not [11], since the index positions were recalculated after index position [5] was removed. PAGE 283 Chapter 2: ColdFusion Functions 259 ArrayInsertAt Inserts data in the specified array at the specified index position. All array elements with indexes greater than the new position are shifted right by one. The length of the array increases by one index. Returns a Boolean TRUE on successful completion. See also ArrayDeleteAt. Syntax ArrayInsertAt(array, position, value) array Name of the array in which you want to insert data. PAGE 284 260 CFML Language Reference ArrayIsEmpty Determines whether the specified array is empty of data. Returns a Boolean TRUE if specified array is empty, FALSE if not empty. See also ArrayLen. Syntax ArrayIsEmpty(array) array Name of the array you want to check for data. PAGE 285 Chapter 2: ColdFusion Functions ArrayLen Returns the length of the specified array. See also ArrayIsEmpty. Syntax ArrayLen(array) array Name of the array whose length you want to return. PAGE 286 262 CFML Language Reference ArrayMax Returns the largest numeric value in the specified array. Syntax ArrayMax(array) array Name of the array from which you want to return the largest numeric value. Example ArrayMax Example ArrayMax Example This example uses ArrayMax to find the largest number that you have entered into an array. PAGE 287 Chapter 2: ColdFusion Functions 263 PAGE 288 264 CFML Language Reference ArrayMin Returns the smallest numeric value in the specified array. Syntax ArrayMin(array) array Name of the array from which you want to return the smallest numeric value. Example ArrayMin Example ArrayMin Example This example uses ArrayMin to find the smallest number that you have entered into an array. PAGE 289 Chapter 2: ColdFusion Functions 265 PAGE 290 266 CFML Language Reference ArrayNew Creates an array of between 1 and 3 dimensions. Array elements are indexed with square brackets: [ ]. Note that ColdFusion arrays expand dynamically as data is added. Syntax ArrayNew(dimension) dimension An integer value between 1 and 3. PAGE 291 Chapter 2: ColdFusion Functions 267 ArrayPrepend Adds an array element to the beginning of the specified array. Returns a Boolean TRUE on successful completion. See also ArrayAppend. Syntax ArrayPrepend(array, value) array Name of the array to which you want to prepend data. value The value you want to add to the beginning of the specified array. PAGE 292 268 CFML Language Reference ArrayResize Resets an array to a specified minimum number of elements. ArrayResize can provide some performance gains if used to size an array to its expected maximum. Use ArrayResize immediately after creating an array with ArrayNew for arrays greater than 500 elements. Note that ColdFusion arrays expand dynamically as data is added. Returns a Boolean TRUE on successful completion. Syntax ArrayResize(array, minimum_size) array Name of the array you want to resize. PAGE 293 Chapter 2: ColdFusion Functions 269 ArraySet In a one-dimensional array, sets the elements in a specified range to the specified value. Useful in initializing an array after a call to ArrayNew. Returns a Boolean TRUE on successful completion. See also ArrayNew. Syntax ArraySet(array, start_pos, end_pos, value) array Name of the array you want to change. start_pos Starting position in the specified array. end_pos Ending position in the specified array. PAGE 294 270 CFML Language Reference ArraySort Returns the specified array with elements numerically or alphanumerically sorted. Syntax ArraySort(array, sort_type [, sort_order ]) array Name of the array you want to sort. sort_type The type of sort to execute. PAGE 295 Chapter 2: ColdFusion Functions 271 ArraySum Returns the sum of values in the specified array. Syntax ArraySum(array) array Name of the array containing values you want to add together. Example ArraySum Example ArraySum Example This example uses ArraySum to add two numbers together. PAGE 296 272 CFML Language Reference PAGE 297 Chapter 2: ColdFusion Functions 273 ArraySwap Swaps array values for the specified array at the specified positions. ArraySwap can be used with greater efficiency than multiple CFSETs. Returns a Boolean TRUE on successful completion. Syntax ArraySwap(array, position1, position2) array Name of the array whose elements you want to swap. position1 Position of the first element you want to swap. position2 Position of the second element you want to swap. PAGE 298 274 CFML Language Reference ArrayToList Converts the specified one dimensional array to a list, delimited with the character you specify. Syntax ArrayToList(array [, delimiter ]) array Name of the array containing elements you want to use to build a list. delimiter Specify the character(s) you want to use to delimit elements in the list. Default is comma ( , ). PAGE 299 Chapter 2: ColdFusion Functions 275 Asc Returns the ASCII value (character code) of the first character of a string. Returns 0 if string is empty. See also Chr. Syntax Asc(string) string Any string. Examples Asc Example Asc Example #Left(FORM. PAGE 300 276 CFML Language Reference ASin Returns the arcsine of a number in radians. The arcsine is the angle whose sine is number. See also Sin, Cos, Pi, and Tan. Syntax ASin(number) number Sine of the angle that is to be calculated. This value must be between 1 and -1. 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 301 Chapter 2: ColdFusion Functions 277 Please enter the sine of the angle that is to be calculated in degrees and radians. This value must be between 1 and -1, inclusive. Type in a number to get its arcsine in Radians and Degrees. PAGE 302 278 CFML Language Reference Atn Returns the arctangent of a number. The arctangent is the angle whose tangent is number. See also Tan, Sin, Cos, and Pi. Syntax Atn(number) number Tangent of the angle you want. 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 303 Chapter 2: ColdFusion Functions 279 AuthenticatedContext Returns the name of the security context. See also IsAuthenticated, AuthenticatedUser, IsAuthorized, and CFAUTHENTICATE. Syntax AuthenticatedContext() Examples AuthenticatedContext Example AuthenticatedContext Example Secure context is: AuthenticatedContext() . . . PAGE 304 280 CFML Language Reference AuthenticatedUser Returns the name of the authenticated user. See also IsAuthenticated, AuthenticatedContext, and CFAUTHENTICATE. Syntax AuthenticatedUser() Examples AuthenticatedUser Example AuthenticatedUser Example Authenticated User: AuthenticatedUser() . . . PAGE 305 Chapter 2: ColdFusion Functions BitAnd Returns the bitwise AND of two long integers. See also BitNot, BitOr, and BitXor. Syntax BitAnd(number1, number2) number1, number2 Any long integers. Usage Bit functions operate on 32-bit integers. Examples BitAnd Example BitAnd Example Returns the bitwise AND of two long integers. PAGE 306 282 CFML Language Reference BitMaskClear Returns number bitwise cleared with length bits beginning from start. See also BitMaskRead and BitMaskSet. Syntax BitMaskClear(number, start, length) number Long integer to be masked. start Integer specifying the starting bit for masking. length Integer specifying the length of mask. Usage Parameters start and length must be in the range from 0 to 31. Bit functions operate on 32-bit integers. PAGE 307 Chapter 2: ColdFusion Functions 283 BitMaskRead Returns the integer created from length bits of number beginning from start. See also BitMaskClear and BitMaskSet. Syntax BitMaskRead(number, start, length) number Long integer to be masked. start Integer specifying the starting bit for reading. length Integer specifying the length of mask. Usage Parameters start and length must be in the range from 0 to 31. Bit functions operate on 32-bit integers. PAGE 308 284 CFML Language Reference BitMaskSet Returns number bitwise masked with length bits of mask beginning from start. See also BitMaskClear and BitMaskRead. Syntax BitMaskSet(number, mask, start, length) number Long integer to be masked. mask Long integer specifying the mask. start Integer specifying the starting bit in number for masking. length Integer specifying the length of mask. Usage Parameters start and length must be in the range from 0 to 31. Bit functions operate on 32-bit integers. PAGE 309 Chapter 2: ColdFusion Functions BitNot Returns the bitwise NOT of a long integer. See also BitAnd, BitOr, and BitXor. Syntax BitNot(number) number Any long integer. Usage Bit functions operate on 32-bit integers. Examples BitNot Example BitNot Example Returns the bitwise NOT of a long integer. PAGE 310 286 CFML Language Reference BitOr Returns the bitwise OR of two long integers See also BitAnd, BitNot, and BitXor. Syntax BitOr(number1, number2) number1, number2 Any long integers. Usage Bit functions operate on 32-bit integers. Examples BitOr Example BitOr Example Returns the bitwise OR of two long integers. PAGE 311 Chapter 2: ColdFusion Functions BitSHLN Returns number bitwise shifted without rotation to the left by count bits. See also BitSHRN. Syntax BitSHLN(number, count) number Long integer to be shifted to the left. count Integer specifying number of bits the number should be shifted. Usage Parameter count must be in the range from 0 to 31. Bit functions operate on 32-bit integers. PAGE 312 288 CFML Language Reference BitSHRN Returns number bitwise shifted without rotation to the right by count bits. See also BitSHLN. Syntax BitSHRN(number, count) number Long integer to be shifted to the right. count Integer specifying number of bits the number should be shifted. Usage Parameter count must be in the range from 0 to 31. Bit functions operate on 32-bit integers. PAGE 313 Chapter 2: ColdFusion Functions BitXor Returns bitwise XOR of two long integers. See also BitAnd, BitNot, and BitOr. Syntax BitXor(number1, number2) number1, number2 Any long integers. Usage Bit functions operate on 32-bit integers. Examples BitXOr Example BitXOr Example Returns the bitwise XOR of two long integers. PAGE 314 290 CFML Language Reference Ceiling Returns the closest integer greater than a given number. See also Int, Fix, and Round. Syntax Ceiling(number) number Any real number. Examples Ceiling Example Ceiling Example The ceiling The ceiling The ceiling The ceiling of of of of 3.4 is #ceiling(3.4)# 3 is #ceiling(3)# 3. PAGE 315 Chapter 2: ColdFusion Functions 291 Chr Returns a character of a given ASCII value (character code). See also Asc. Syntax Chr(number) number Any ASCII value (a number in the range 0 to 255 inclusive). Usage Numbers from 0 to 31 are the standard, nonprintable ASCII codes. For example, Chr(10) returns a linefeed character and Chr(13) returns a carriage return character. Therefore, the two-character string Chr(13) & Chr(10) is the newline string. PAGE 316 292 CFML Language Reference CJustify Centers a string in the specified field length. See also LJustify and RJustify. Syntax Cjustify(string, length) string Any string to be centered. length Length of field. Examples PAGE 317 Chapter 2: ColdFusion Functions 293 Compare Performs a case-sensitive comparison of two strings. Returns a negative number if string1 is less than string2; 0 if string1 is equal to string2; or a positive number if string1 is greater than string2. See also CompareNoCase and Find. Syntax Compare(string1, string2) string1, string2 Strings to be compared. Usage The comparison is performed on the ASCII values (character codes) of corresponding characters in string1 and string2. PAGE 318 294 CFML Language Reference PAGE 319 Chapter 2: ColdFusion Functions 295 CompareNoCase Performs a case-insensitive comparison of two strings. Returns a negative number if string1 is less than string2; 0 if string1 is equal to string2; or a positive number if string1 is greater than string2. See also Compare and FindNoCase. Syntax CompareNoCase(string1, string2) string1, string2 Strings to be compared. PAGE 320 296 CFML Language Reference Cos Returns the cosine of a given angle in radians. See also Sin, Tan, and Pi. Syntax Cos(number) number Angle in radians for which you want 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 321 Chapter 2: ColdFusion Functions 297 CreateDate Returns a valid date/time object. See also CreateDateTime and CreateODBCDate. Syntax CreateDate(year, month, day) year Number representing the year in the range 100–9999. Years from 0 to 29 are interpreted as 21st century values. Years 30 to 99 are interpreted as 20th century values. month Number representing the month of the year, ranging from 1 (January) to 12 (December). day Number representing the day of the month, ranging from 1 to 31. PAGE 322 298 CFML Language Reference Built with CreateDateTime: #CreateDateTime(FORM.year, FORM.month, FORM.day, 12,13,0)# Built with CreateODBCDate: #CreateODBCDate(yourDate)# Built with CreateODBCDateTime: #CreateODBCDateTime(yourDate)# The same value can be formatted with dateFormat: Built with CreateDate: #DateFormat(CreateDate(FORM.year, FORM.month, FORM.day), "mmm-dd-yyyy")# Built with CreateDateTime: #DateFormat(CreateDateTime(FORM.year, FORM.month, FORM. PAGE 323 Chapter 2: ColdFusion Functions 299 CreateDateTime Returns a valid date/time object. See also CreateDate, CreateTime, CreateODBCDateTime, and Now. Syntax CreateDateTime(year, month, day, hour, minute, second) year Number representing the year in the range 100–9999. month Number representing the month of the year, ranging from 1 (January) to 12 (December). day Number representing the day of the month, ranging from 1 to 31. hour Number representing the hour, ranging from 0 to 23. PAGE 324 300 CFML Language Reference Built with CreateDateTime: #CreateDateTime(form.year, form.month, form.day, form.hour, form.minute,form.second)# Built with CreateODBCDate: #CreateODBCDate(yourDate)# Built with CreateODBCDateTime: #CreateODBCDateTime(yourDate)# The same value can be formatted with dateFormat: Built with CreateDate: #DateFormat(CreateDate (form.year,form.month,form.day), "mmm-dd-yyyy")# Built with CreateDateTime: #DateFormat(CreateDateTime (form.year, form. PAGE 325 Chapter 2: ColdFusion Functions 301 CreateObject Allows you tocreate COM, CORBA, and JAVA objects. Note ColdFusion administrators can disable the CFOBJECT tag in the ColdFusion Administrator Basic Security page, which also disables this function. Note On UNIX, COM objects are not currently supported by CreateObject. CreateObject topics • COM • CORBA • JAVA Object Types Depending on the value of the type parameter, there are several additional parameters you can use. PAGE 326 302 CFML Language Reference OLEView, as well as information about COM and DCOM, can be found at Microsoft’s OLE Development web site http://www.microsoft.com/oledev/. To create COM objects, you need to know the program ID or filename of the object, the methods and properties available through the IDispatch interface, and the arguments and return types of the object’s methods. The OLEView utility can give you this information for most COM objects. PAGE 327 Chapter 2: ColdFusion Functions 303 • "IOR" — ColdFusion uses the Interoperable Object Reference (IOR) to access the CORBA server. • "NameService" — ColdFusion uses the naming service to access server. "NameService" is only valid with the InitialContext of a VisiBroker Orb. locale Optional. Sets arguments for a call to init_orb(..). Use of this attribute is specific to VisiBroker orbs, and is currently available on C++, Version 3.2. The value should be of the form: " -ORBagentAddr 199.99.129. PAGE 328 304 CFML Language Reference valid Java type (simple, arrays, objects). ColdFusion does the appropriate conversions when strings are passed as arguments, but not when they are received as return values. Overloaded methods are supported as long as the number of arguments are different. Future enhancements will let you use cast functions that will allow method signatures to be built more accurately. PAGE 329 Chapter 2: ColdFusion Functions 305 CreateODBCDate Returns a date in ODBC date format. See also CreateDate and CreateODBCDateTime. Syntax CreateODBCDate(date) date Date/time object in the period from 100 AD to 9999 AD. Years from 0 to 29 are interpreted as 21st century values. Years 30 to 99 are interpreted as 20th century values. PAGE 330 306 CFML Language Reference (FORM.year, FORM.month, FORM.day), "mmm-dd-yyyy")# Built with CreateDateTime: #DateFormat(CreateDateTime (FORM.year, FORM.month, FORM.day, FORM.hour, FORM.minute,FORM.second))# Built with CreateODBCDate: #DateFormat(CreateODBCDate(yourDate), "mmmm d, yyyy")# Built with CreateODBCDateTime: #DateFormat(CreateODBCDateTime(yourDate), "d/m/yy")# PAGE 331 Chapter 2: ColdFusion Functions 307 CreateODBCDateTime Returns a date/time object in ODBC timestamp format. See also CreateDateTime, CreateODBCDate, CreateODBCTime, and Now. Syntax CreateODBCDateTime(date) date Date/time object in the period from 100 AD to 9999 AD. Years from 0 to 29 are interpreted as 21st century values. Years 30 to 99 are interpreted as 20th century values. Usage When passing a date/time value as a string, make sure it is enclosed in quotes. PAGE 332 308 CFML Language Reference Built with CreateDateTime: #DateFormat(CreateDateTime (FORM.year, FORM.month, FORM.day, FORM.hour, FORM.minute, FORM.second))# Built with CreateODBCDate: #DateFormat(CreateODBCDate(yourDate), "mmmm d, yyyy")# Built with CreateODBCDateTime: #DateFormat(CreateODBCDateTime(yourDate), "d/m/yy")# PAGE 333 Chapter 2: ColdFusion Functions 309 CreateODBCTime Returns a time object in ODBC time format. See also CreateODBCDateTime and CreateTime. Syntax CreateODBCTime(date) date Date/time object in the period from 100 AD to 9999 AD. Usage When passing a date/time value as a string, make sure it is enclosed in quotes. Otherwise, it is interpreted as a number representation of a date/time object, returning undesired results. PAGE 334 310 CFML Language Reference MESSAGE="You must enter a minute value (0-59)" VALIDATE="integer" REQUIRED="Yes"> Second PAGE 335 Chapter 2: ColdFusion Functions CreateTime Returns a valid time variable in ColdFusion. See also CreateODBCTime and CreateDateTime. Syntax CreateTime(hour, minute, second) hour Number representing the hour, ranging from 0 to 23. minute Number representing the minute, ranging from 0 to 59. second Number representing the second, ranging from 0 to 59. Usage CreateTime is a subset of CreateDateTime. Time variables are special cases of date/time variables. PAGE 336 312 CFML Language Reference PAGE 337 Chapter 2: ColdFusion Functions 313 CreateTimeSpan Creates a date/time object for adding and subtracting other date/time objects. See also CreateDateTime, DateAdd, and DateConvert. Syntax CreateTimeSpan(days, hours, minutes, seconds) days Number representing the number of days. hours Number representing the number of hours. minutes Number representing the number of minutes. seconds Number representing the number of seconds. PAGE 338 314 CFML Language Reference CreateUUID Returns a Universally Unique Identifier (UUID) formatted as ‘XXXXXXXX-XXXX-XXXXXXXXXXXXXXXXXXX’ where ‘X’ stands for a hexadecimal digit (0-9 or A-F). Syntax CreateUUID() Usage Each UUID returned by the CreateUUID function is a 35-character-string representation of a unique 128-bit integer. Use the CreateUUID function when you need a unique string that you will use as a persistent identifier in a distributed environment. PAGE 339 Chapter 2: ColdFusion Functions 315 DateAdd Returns a date to which a specified time interval has been added. See also DateConvert, DatePart, and CreateTimeSpan. Syntax DateAdd(datepart, number, date) datepart One of the following strings: • yyyy — Year • q — Quarter • m — Month • y — Day of year • d — Day • w — Weekday • ww — Week • h — Hour • n — Minute • s — Second number Number of units of datepart to add to date (positive to get dates in the future or negative to get dates in the past). PAGE 340 316 CFML Language Reference This example uses DateAdd to determine when a message in the database will expire. PAGE 341 Chapter 2: ColdFusion Functions 317 DateCompare Performs a full date/time comparison of two dates. Returns -1 if date1 is less than date2; returns 0 if date1 is equal to date2; returns 1 if date1 is greater than date2. See the description of datePart for information on specifying the precision of the comparison. See also CreateDateTime and DatePart. Syntax DateCompare(date1, date2 [, datePart]) date1 Date/time object in the period from 100 AD to 9999 AD. PAGE 342 318 CFML Language Reference The datecompare function compares two date/time values. #DateFormat(FORM.date1)# #TimeFormat(FORM.date1)# (Date 1) is earlier than #DateFormat(FORM.date2)# #TimeFormat(FORM. PAGE 343 Chapter 2: ColdFusion Functions 319 Specify precision to the: PAGE 344 320 CFML Language Reference DateConvert Converts local time to Universal Coordinated Time (UTC ) or UTC to local time based on the specified parameters. This function uses the daylight savings settings in the executing machine to compute daylight savings time, if required. See also GetTimeZoneInfo, CreateDateTime, and DatePart. Syntax DateConvert(conversion-type, date) conversion-type There are two conversion types: “local2Utc” and “utc2Local.” The former converts local time to UTC time. PAGE 345 Chapter 2: ColdFusion Functions 321 Your date value, presented as a ColdFusion date-time string:#yourdate#. Your date and time value, converted into Universal Coordinated Time (UTC): #yourUTC#. PAGE 346 322 CFML Language Reference

PAGE 347

Chapter 2: ColdFusion Functions 323 DateDiff Returns the number of intervals in whole units of type Datepart by which Date1 is less than Date2. See also DateAdd, DatePart, and CreateTimeSpan. Syntax DateDiff(datepart, date1, date2) datepart One of the following strings: • yyyy — Year • q — Quarter • m — Month • y — Day of year • d — Day • w — Weekday • ww — Week • h — Hour • n — Minute • s — Second date1 Date/time object in the period from 100 AD to 9999 AD.

PAGE 348

324 CFML Language Reference Years from 0 to 29 are interpreted as 21st century values. Years 30 to 99 are interpreted as 20th century values. Examples ...

PAGE 349

Chapter 2: ColdFusion Functions 325 DateFormat Returns a formatted date/time value. If no mask is specified, DateFormat function returns date value using the dd-mmm-yy format. See also Now, CreateDate, and ParseDateTime. Syntax DateFormat(date [, mask ]) date Date/time object in the period from 1601 AD to 9999 AD. mask Set of characters that are used to show how ColdFusion should display the date: • d — Day of the month as digits with no leading zero for single-digit days.

PAGE 350

326 Examples CFML Language Reference DateFormat Example

DateFormat Example

Today’s date is #todayDate#.

PAGE 351

Chapter 2: ColdFusion Functions 327 DatePart Returns the specified part of a date as an integer. See also DateAdd and DateConvert. Syntax DatePart(datepart, date) datepart One of the following strings: • yyyy — Year • q — Quarter • m — Month • y — Day of year • d — Day • w — Weekday • ww — Week • h — Hour • n — Minute • s — Second date Any date. Usage Years from 0 to 29 are interpreted as 21st century values. Years 30 to 99 are interpreted as 20th century values.

PAGE 352

328 CFML Language Reference

Using datepart, we can extract an integer representing the various dateparts from that value

year: #DatePart("yyyy", todayDate)#
quarter: #DatePart("q", todayDate)#
month: #DatePart("m", todayDate)#
day of year: #DatePart("y", todayDate)#
day: #DatePart("d", todayDate)#
weekday: #DatePart("w", todayDate)#
week: #DatePart("ww", todayDate)#
hour: #DatePart("h", todayDate)#
minute: #DatePart("n", todayDate)#
second: #DateP
PAGE 353

Chapter 2: ColdFusion Functions 329 Day Returns the ordinal for the day of the month, ranging from 1 to 31. See also DayOfWeek, DayOfWeekAsString, DayOfYear, DaysInMonth, DaysInYear, and FirstDayOfMonth. Syntax Day(date) date Any date. Usage Years from 0 to 29 are interpreted as 21st century values. Years 30 to 99 are interpreted as 20th century values. When passing a date/time value as a string, make sure it is enclosed in quotes.
PAGE 354

330 CFML Language Reference DayOfWeek Returns the ordinal for the day of the week. The day is given as an integer ranging from 1 (Sunday) to 7 (Saturday). See also Day, DayOfWeekAsString, DayOfYear, DaysInMonth, DaysInYear, and FirstDayOfMonth. Syntax DayOfWeek(date) date Any date. Usage Years from 0 to 29 are interpreted as 21st century values. Years 30 to 99 are interpreted as 20th century values. When passing a date/time value as a string, make sure it is enclosed in quotes.
PAGE 355

Chapter 2: ColdFusion Functions 331 DayOfWeekAsString Returns the day of the week corresponding to day_of_week, an integer ranging from 1 (Sunday) to 7 (Saturday). See also Day, DayOfWeek, DayOfYear, DaysInMonth, DaysInYear, and FirstDayOfMonth. Syntax DayOfWeekAsString(day_of_week) day_of_week Integer representing the day of the week, where 1 is Sunday, 2 is Monday, and so on. Usage Years from 0 to 29 are interpreted as 21st century values. Years 30 to 99 are interpreted as 20th century values.
PAGE 356

332 CFML Language Reference DayOfYear Returns the ordinal for the day of the year. See also Day, DayOfWeek, DayOfWeekAsString, DaysInMonth, DaysInYear, and FirstDayOfMonth. Syntax DayOfYear(date) date Any date. Usage DayofYear is aware of leap years. Years from 0 to 29 are interpreted as 21st century values. Years 30 to 99 are interpreted as 20th century values. When passing a date/time value as a string, make sure it is enclosed in quotes.
PAGE 357

Chapter 2: ColdFusion Functions 333 DaysInMonth Returns the number of days in the specified month (Date). See also Day, DayOfWeek, DayOfWeekAsString, DayOfYear, DaysInYear, and FirstDayOfMonth. Syntax DaysInMonth(date) date Any date. Usage Years from 0 to 29 are interpreted as 21st century values. Years 30 to 99 are interpreted as 20th century values. When passing a date/time value as a string, make sure it is enclosed in quotes.
PAGE 358

334 CFML Language Reference DaysInYear Returns the number of days in a year. See also Day, DayOfWeek, DayOfWeekAsString, DayOfYear, DaysInMonth, DaysInYear, FirstDayOfMonth, and IsLeapYear. Syntax DaysInYear(date) date Any date. Usage DaysInYear is aware of leap years. Years from 0 to 29 are interpreted as 21st century values. Years 30 to 99 are interpreted as 20th century values. When passing a date/time value as a string, make sure it is enclosed in quotes.
PAGE 359

Chapter 2: ColdFusion Functions DE Returns its argument with double quotes wrapped around it and all double quotes inside it escaped. The DE (Delay Evaluation) function prevents the evaluation of a string as an expression when it is passed as an argument to IIf or Evaluate. See also Evaluate and IIf. Syntax DE(string) string String to be evaluated with delay.
PAGE 360

336 CFML Language Reference DecimalFormat Returns number as a string formatted with two decimal places and thousands separator. See also DollarFormat and NumberFormat. Syntax DecimalFormat(number) number Number being formatted. Examples DecimalFormat Example
DecimalFormat Function

Returns a number to two decimal places.
PAGE 361

Chapter 2: ColdFusion Functions 337 DecrementValue Returns integer part of number decremented by one. See also IncrementValue. Syntax DecrementValue(number) number Number being decremented. Examples DecrementValue Example
DecrementValue Example

Returns the integer part of a number decremented by one.
PAGE 362

338 CFML Language Reference Decrypt Decrypts an encrypted string. See also Encrypt. Syntax Decrypt(encrypted_string, key) encrypted_string String to be decrypted. key String specifying the key used to encrypt encrypted_string. Examples Decrypt Example
Decrypt Example

This function allows for the encryption and decryption of a string.
PAGE 363

Chapter 2: ColdFusion Functions 339 DeleteClientVariable Deletes the client variable specified by name. Returns a Boolean TRUE when variable is successfully deleted, even if variable did not previously exist. To test for the existence of a variable, use IsDefined. See also GetClientVariablesList. Syntax DeleteClientVariable("name") name Name of a client variable to be deleted, surrounded by double quotes. Usage If the client variable specified by name does not exist, an error is returned.
PAGE 364

340 CFML Language Reference DirectoryExists Returns YES if the directory specified in the argument does exist; otherwise, it returns NO. See also FileExists. Syntax DirectoryExists(absolute_path) absolute_path Any absolute path. Examples DirectoryExists Example
DirectoryExists Example
PAGE 365

Chapter 2: ColdFusion Functions 341 DollarFormat Returns number as a string formatted with two decimal places, thousands separator, dollar sign. Parentheses are used if number is negative. See also DecimalFormat and NumberFormat. Syntax DollarFormat(number) number Number being formatted.
PAGE 366

342 CFML Language Reference Encrypt Encrypts a string. See also Decrypt. Syntax Encrypt(string, key) string String to be encrypted. key String specifying the key used to encrypt string. Examples Encrypt Example
Encrypt Example

This function allows for the encryption and decryption of a string.
PAGE 367

Chapter 2: ColdFusion Functions 343 Evaluate The function evaluates all of its arguments, left to right, and returns the result of evaluating the last argument. See also DE and IIf. Syntax Evaluate(string_expression1 [, string_expression2 [, … ] ] ) string_expression1, string_expression2 Valid expressions to be evaluated. Usage String expressions can be arbitrarily complex. Note, however, that they are somewhat more complicated to write because they are inside a string.
PAGE 368

344 CFML Language Reference Exp Returns e raised to the power of number. The constant e equals 2.71828182845904, the base of the natural logarithm. See also Log and Log10. Syntax Exp(number) number Exponent applied to the base e. Usage To calculate powers of other bases, use ^ (the exponentiation operator). Exp is the inverse of Log, the natural logarithm of number.
PAGE 369

Chapter 2: ColdFusion Functions 345 ExpandPath Returns a path equivalent to the relative_path appended to the base template path. Note the following: • ExpandPath creates a platform-appropriate path. You can use either a slash (/) or a back slash (\) in the specified relative path. • The return value contains a trailing slash (or back slash) if the specified relative path contains a trailing slash (or back slash). See also FileExists, GetCurrentTemplatePath, and GetFileFromPath.
PAGE 370

346 CFML Language Reference FileExists Returns YES if the file specified in the argument does exist; otherwise, it returns NO. See also DirectoryExists, ExpandPath, and GetTemplatePath. Syntax FileExists(absolute_path) absolute_path Any absolute path. Examples FileExists Example
FileExists Example
PAGE 371

Chapter 2: ColdFusion Functions Find Returns the first index of an occurrence of a substring in a string from a specified starting position. Returns 0 if substring is not in string. The search is case-sensitive. See also FindNoCase, Compare, FindOneOf, REFind, and Replace. Syntax Find(substring, string [, start ]) substring String being sought. string String being searched. start Starting position for the search. Examples ...
PAGE 372

348 CFML Language Reference FindNoCase Returns the first index of an occurrence of a substring in a string from a specified starting position. Returns 0 if substring is not in string. The search is case-insensitive. See also Find, CompareNoCase, FindOneOf, REFind, and Replace functions. Syntax FindNoCase(substring, string [, start ]) substring String being sought. string String being searched. start Starting position for the search. Examples ...
PAGE 373

Chapter 2: ColdFusion Functions 349 FindOneOf Return the first index of the occurrence of any character from set in string. Returns 0 if no characters are found. The search is case-sensitive. See also Find, Compare, and REFind functions. Syntax FindOneOf(set, string [, start ]) set String containing one or more characters being sought. string String being searched. start Starting position for the search. Examples ...
PAGE 374

350 CFML Language Reference FirstDayOfMonth Returns the ordinal (the day’s number in the year) for the first day of the specified month. See also Day, DayOfWeek, DayOfWeekAsString, DayOfYear, DaysInMonth, and DaysInYear. Syntax FirstDayOfMonth(date) date Any date. Usage Years from 0 to 29 are interpreted as 21st century values. Years 30 to 99 are interpreted as 20th century values. When passing a date/time value as a string, make sure it is enclosed in quotes.
PAGE 375

Chapter 2: ColdFusion Functions 351 Fix Returns the closest integer less than number if number is greater than or equal to 0. Returns the closest integer greater than number if number is less than 0. See also Ceiling, Int, and Round. Syntax Fix(number) number Any number. Examples Fix Example
Fix Example

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

352 CFML Language Reference FormatBaseN Converts a number to a string in the base specified by radix. See also InputBaseN. Syntax FormatBaseN(number, radix) number Number to be converted. radix Base of the result. Examples FormatBaseN Example
FormatBaseN Example

FormatBaseN converts a number to a string in the base specified by Radix.
PAGE 377

Chapter 2: ColdFusion Functions 353 GetBaseTagData Returns an object that contains data (variables, scopes, etc.) from a specified ancestor tag. By default the closest ancestor is returned. If there is no ancestor by the specified name, or if the ancestor does not expose any data (for example, CFIF), an exception will be thrown. See also GetBaseTagList. Syntax GetBaseTagData(tagname [, instancenumber ] ) tagname Required. Specifies the ancestor tag name for which the function returns data.
PAGE 378

354 CFML Language Reference GetBaseTagList Returns a comma-delimited list of uppercase ancestor tag names. The first element of the list is the parent tag. If you call this function for a top-level tag, it returns an empty string. See also GetBaseTagData. Syntax GetBaseTagList() Example ...
PAGE 379

Chapter 2: ColdFusion Functions GetBaseTemplatePath Returns the fully specified path of the base template. See also GetCurrentTemplatePath, FileExists and ExpandPath.
PAGE 380

356 CFML Language Reference GetClientVariablesList Returns a comma-delimited list of non-readonly client variables available to a template. See also DeleteClientVariable.
PAGE 381

Chapter 2: ColdFusion Functions 357 GetCurrentTemplatePath Returns the fully specified path of the template containing the call to this function. See also GetBaseTemplatePath, FileExists and ExpandPath.
PAGE 382

358 CFML Language Reference GetDirectoryFromPath Extracts the directory (with a \ (backslash)) from a fully specified path. See also ExpandPath and GetFileFromPath. Syntax GetDirectoryFromPath(path) path Fully specified path (drive, directory, filename, and extension). Examples GetDirectoryFromPath Example
GetDirectoryFromPath Example
PAGE 383

Chapter 2: ColdFusion Functions GetFileFromPath Extracts the filename from a fully specified path. See also ExpandPath and GetCurrentTemplatePath. Syntax GetFileFromPath(path) path Fully qualified path (drive, directory, filename, and extension). Examples GetFileFromPath Example
GetFileFromPath Example

PAGE 384

360 CFML Language Reference GetFunctionList Returns a structure of functions that are available in ColdFusion. Syntax GetFunctionList() Examples

Timeout is set to: #timeout#.

"; for (i = 0; i < colNames.length; ++i) { o += "

Full Path of Init File

PAGE 391

Chapter 2: ColdFusion Functions 367 GetTempDirectory Returns the full path name of a directory, including the trailing slash. The directory that is returned depends on the account under which ColdFusion is running as well as a variety of other factors. Before using this function in an application, test to see the directory it returns under your account. See also GetTempFile.

PAGE 392

368 CFML Language Reference GetTempFile Creates and returns the name of a temporary file in a directory whose name starts with (at most) the first three characters of prefix. See also GetTempDirectory. Syntax GetTempFile(dir, prefix) dir Directory name. prefix Prefix of a temporary file to be created in the directory specified by dir.

PAGE 393

Chapter 2: ColdFusion Functions GetTemplatePath Returns the fully specified path of the base template. Note For backward compatibility, GetTemplatePath is still supported. However, GetBaseTemplatePath supersedes this function, and should be used in place of it in all code written after the release of ColdFusion 4.0. See also GetBaseTemplatePath, FileExists and ExpandPath.

PAGE 394

370 CFML Language Reference GetTickCount Returns a millisecond clock counter that can be used for timing sections of CFML code or any other aspects of page processing. Syntax GetTickCount() Usage The absolute value of the counter has no meaning. Generate useful timing values by taking differences between the results of GetTickCount() at specified points during page processing.

PAGE 395

Chapter 2: ColdFusion Functions 371 GetTimeZoneInfo Returns a structure containing time zone information for the machine on which this function is executed. The structure contains four elements with the following keys. • utcTotalOffset — total offset of the local time in minutes from UTC (Universal Coordinated Time). A plus sign (+) indicates that a time zone is west of UTC, such as all of the time zones in North and South America.

PAGE 396

372 CFML Language Reference GetToken Returns the specified token in a string. Default delimiters are spaces, tabs, and newline characters. If index is greater than the number of tokens in string, GetToken returns an empty string. See also Left, Right, Mid, SpanExcluding, and SpanIncluding. Syntax GetToken(string, index [, delimiters ]) string Any string. index Any integer > 0 that indicates position of a token. delimiters String containing sets of delimiters.

PAGE 397

Chapter 2: ColdFusion Functions 373 Hour Returns the ordinal value for the hour, ranging from 0 to 23. See also DatePart, Minute, and Second. Syntax Hour(date) date Any date. Usage Years from 0 to 29 are interpreted as 21st century values. Years 30 to 99 are interpreted as 20th century values. When passing a date/time value as a string, make sure it is enclosed in quotes. Otherwise, it is interpreted as a number representation of a date/time object, returning undesired results.

PAGE 398

374 CFML Language Reference HTMLCodeFormat Returns HTML escaped string enclosed in

and

tags. All carriage returns are removed from string, and all special characters (> < " &) are escaped. See also HTMLEditFormat. Syntax HTMLCodeFormat(string [, version ]) string String being HTML escaped and preformatted. version The specific HTML version to use in replacing special characters with their entity references. Valid entries are: • -1 — The latest implementation of HTML • 2.0 — For HTML 2.

PAGE 399

Chapter 2: ColdFusion Functions 375

because you entered no url or an empty string, the tag will return the following address: http://localhost/cfdocs/ index.htm

PAGE 400

376 CFML Language Reference HTMLEditFormat Returns HTML escaped string. All carriage returns are removed from string, and all special characters (> < " &) are escaped. See also HTMLCodeFormat. Syntax HTMLEditFormat(string [, version ]) string String being HTML escaped. version The specific HTML version to use in replacing special characters with their entity references. Valid entries are: • -1 – The latest implementation of HTML • 2.0 – For HTML 2.0 (Default) • 3.2 – For HTML 3.

PAGE 401

Chapter 2: ColdFusion Functions 377

because you entered no url or an empty string, the tag will return the following address: http://localhost/cfdocs/index.

PAGE 402

378 CFML Language Reference IIf The function evaluates its condition as a Boolean. If the result is TRUE, it returns the value of Evaluate(string_expression1); otherwise, it returns the value of Evaluate(string_expression2). Prior to using IIf, please read the Usage section and Note carefully. The IIf function is primarily intended for the conditional processing of dynamic expressions. For general conditional processing, see CFIF/CFELSEIF/CFELSE. For error handling, see CFTRY/CFCATCH.

PAGE 403

Chapter 2: ColdFusion Functions 379 error ’Error Resolving Parameter’ if there is an undefined variable in string_expression1. For example, “LocalVar” is undefined, however, the following logic functions as you would expect if you do not use pound signs around “LocalVal”: #IIf(IsDefined(“LocalVar”), “LocalVar”, DE(“The variable is not defined.”))# The output is: The variable is not defined.

PAGE 404

380 CFML Language Reference DE("It is morning"))#

PAGE 405

Chapter 2: ColdFusion Functions 381 IncrementValue Returns integer part of number incremented by one. See also DecrementValue. Syntax IncrementValue(number) number Number being incremented. Examples IncrementValue Example

IncrementValue Example

Returns the integer part of a number Incremented by one.

PAGE 406

382 CFML Language Reference InputBaseN Returns the number obtained by converting string using the base specified by radix, an integer ranging from 2 to 36. See also FormatBaseN. Syntax InputBaseN(string, radix) string Any string representing number in base specified by radix. radix Base of number represented by string ranging from 2 to 36.

PAGE 407

Chapter 2: ColdFusion Functions 383 Insert Inserts a substring in a string after a specified character position. Prepends the substring if position is equal to 0. See also RemoveChars and Len. Syntax Insert(substring, string, position) substring String to be inserted. string String to be inserted into. position Integer that indicates the character position in string where the substring will be inserted.

PAGE 408

384 CFML Language Reference Int Returns the closest integer smaller than a number. See also Ceiling, Fix, and Round. Syntax Int(number) number Real number you want to round down to an integer. Examples Int Example

Int Example

Int returns the closest integer smaller than a number.

Int(11.7) : #Int(11.7)#

Int(-11.7) : #Int(-11.

PAGE 409

Chapter 2: ColdFusion Functions IsArray Returns TRUE if value is an array. See also “Array Functions” on page 245. Syntax IsArray(value [, number ]) value Variable name or array name. number Tests if the array has exactly the specified dimension.

PAGE 410

386 CFML Language Reference IsAuthenticated Returns TRUE if the user has been authenticated for any ColdFusion security context. If you specify the name of the security context, IsAuthenticated returns TRUE if the user has been authenticated for the specified ColdFusion security context. See also CFAUTHENTICATE, AuthenticatedContext, AuthenticatedUser, and IsAuthorized. Syntax IsAuthenticated([security-context-name ]) security-context-name The security context name.

PAGE 411

Chapter 2: ColdFusion Functions 387 IsAuthorized Returns TRUE if the user is authorized to perform the specified action on the specified ColdFusion resource. See also IsAuthenticated. Syntax IsAuthorized(resourcetype, resourcename [, action ]) resourcetype String specifying the type of resource: • Application • CFML • File • DataSource • Component • Collection • CustomTag • UserObject resourcename String specifying the name of the resource.

PAGE 412

388 CFML Language Reference action String specifying the action for which authorization is requested. Do not specify this parameter for COMPONENT and CUSTOMTAG. For all other resource types, this parameter is required.

PAGE 413

Chapter 2: ColdFusion Functions #Customer# - #BalanceDue#
389

PAGE 414

390 CFML Language Reference IsBinary Returns TRUE if value is binary; otherwise, the function returns FALSE. See also ToBinary, ToBase64, IsNumeric and YesNoFormat. Syntax IsBinary(value) value Any value. Examples IsBoolean Example

IsBoolean Example

The expression #DE(FORM.

PAGE 416

392 CFML Language Reference IsDate Returns TRUE if string can be converted to a date/time value; otherwise, FALSE. Note that ColdFusion converts the Boolean return value to its string equivalent, "Yes" and "No." See also ParseDateTime, CreateDateTime, and IsNumericDate. Syntax IsDate(string) string Any string value. Usage Years from 0 to 29 are interpreted as 21st century values. Years 30 to 99 are interpreted as 20th century values.

PAGE 417

Chapter 2: ColdFusion Functions 393 IsDebugMode Returns TRUE if debugging mode was set via the ColdFusion Administrator and FALSE if debugging mode is disabled.

PAGE 418

394 CFML Language Reference IsDefined Evaluates a string value to determine if the variable named in the string value exists. IsDefined returns TRUE if the specified variable is found, FALSE if not found. IsDefined provides an alternative to the ParameterExists function, eliminating the need for cumbersome expressions used to test for the existence of a variable: Evaluate("ParameterExists(#var_name#)") See also Evaluate.

PAGE 419

Chapter 2: ColdFusion Functions IsLeapYear Returns TRUE if the year is a leap year; otherwise, FALSE. See also DaysInYear. Syntax IsLeapYear(year) year Number representing the year. Examples IsLeapYear Example

IsLeapYear Example

The year value #DE(FORM.

PAGE 420

396 CFML Language Reference IsNumeric Returns TRUE if string can be converted to a number; otherwise, FALSE. See also IsBinary. Syntax IsNumeric(string) string Any string value. Examples IsNumeric Example

IsNumeric Example

The string #DE(FORM.

PAGE 421

Chapter 2: ColdFusion Functions 397 IsNumericDate Evaluates "real value" of date/time object. Returns TRUE if the number represents "real value" of the date/time object; otherwise, FALSE. See also IsDate and ParseDateTime. Syntax IsNumericDate(number) number Real number. Examples IsNumericDate Example

IsNumericDate Example

PAGE 422

398 CFML Language Reference IsProtected Returns TRUE if the resource is protected in the security context of the authenticated user. See also IsAuthorized. Syntax IsProtected(resourcetype, resourcename [, action]) resourcetype String specifying the type of resource: • Application • CFML • File • DataSource • Component • CustomTag • UserObject resourcename String specifying the name of the resource.

PAGE 423

Chapter 2: ColdFusion Functions 399 action String specifying the action for which authorization is requested. Do not specify this parameter for COMPONENT and CUSTOMTAG. For all other resource types, this parameter is required.

PAGE 424

400 CFML Language Reference SELECT * FROM Orders Authorization Succeeded.

PAGE 425

Chapter 2: ColdFusion Functions IsQuery Returns TRUE if value is a query. See also QueryAddRow. Syntax IsQuery(value) value Query variable.

PAGE 426

402 CFML Language Reference IsSimpleValue Returns TRUE if value is a string, number, Boolean, or date/time value. Syntax IsSimpleValue(value) value Variable or expression.

PAGE 427

Chapter 2: ColdFusion Functions IsStruct Returns TRUE if variable is a structure. See also “Structure Functions” on page 250. Syntax IsStruct(variable ) variable Variable name. Examples

This file is similar to addemployee.cfm, which is called by StructNew, StructClear, and StructDelete. It is an example of a custom tag used to add employees. Employee information is passed through the employee structure (the EMPINFO attribute).

PAGE 428

404 CFML Language Reference JSStringFormat Returns a string that is safe to use with JavaScript. Syntax JSStringFormat(string) string Any string. Usage JSStringFormat escapes special JavaScript characters, such as the single quote (’), double quotes ("), and newline character so that you can put arbitrary strings safely into JavaScript. Examples LCase Example

LCase Example

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

PAGE 430

406 CFML Language Reference Left Returns the count of characters from the beginning of a string argument. See also Right, Mid, and Len. Syntax Left(string, count) string String from which the leftmost characters are retrieved. count Positive integer indicating how many characters to return. Examples Left Example

Left Example

PAGE 431

Chapter 2: ColdFusion Functions Len Returns the length of a string or a binary object. See also ToBinary, Left, Right, and Mid. Syntax Len(string or binary object) string Any string or binary object. Examples Len Example

Len Example

Your string, "#FORM.

PAGE 432

408 CFML Language Reference ListAppend Returns list with value appended behind its last element. See also ListPrepend, ListInsertAt, and ListSetAt. Syntax ListAppend(list, value [, delimiters ]) list Any list. value Number or list being appended. delimiters Set of delimiters used in list. Usage When appending an element into a list, ColdFusion needs to insert a delimiter.

PAGE 433

Chapter 2: ColdFusion Functions ListChangeDelims Returns list with all delimiter characters changed to new_delimiter string. See also ListFirst and ListQualify. Syntax ListChangeDelims(list, new_delimiter [, delimiters ]) list List of delimiters being changed. new_delimiter String being used as a new delimiter. delimiters Set of delimiters used in list.

PAGE 434

410 CFML Language Reference ListContains Returns the index of the first item that contains the specified substring. The search is case-sensitive. If the substring is not found in any of the list items, it returns zero (0). See also ListContainsNoCase and ListFind. Syntax ListContains(list, substring [, delimiters ]) list List being searched. substring String being sought in elements of list. delimiters Set of delimiters used in list.

PAGE 435

Chapter 2: ColdFusion Functions 411

However, if you specify the entire string two, both ListContains and ListFind will find it in the second item in the list.
ListContains
The string "two" is in Item #ListContains(aList, "two")# of the list.
ListFind
The string "two" is in Item #ListFind(aList, "two")# of the list.

PAGE 436

412 CFML Language Reference ListContainsNoCase Returns the index of the first element of a list that contains the specified substring within elements. The search is case-insensitive. If no element is found, returns 0. See also ListContains and ListFindNoCase. Syntax ListContainsNoCase(list, substring [, delimiters ]) list List being searched. substring String being sought in elements of list. delimiters Set of delimiters used in list.

PAGE 437

Chapter 2: ColdFusion Functions 413 ListDeleteAt Returns list with element deleted at the specified position. See also ListGetAt, ListSetAt, and ListLen. Syntax ListDeleteAt(list, position [, delimiters ]) list Any list. position Positive integer indicating the position of the element being deleted. The starting position in a list is denoted by the number 1, not 0. delimiters Set of delimiters used in list.

PAGE 438

414 CFML Language Reference ListFind Returns the index of the first occurrence of a value within a list. Returns 0 if no value is found. The search is case-sensitive. See also ListContains and ListFindNoCase. Syntax ListFind(list, value [, delimiters ]) list List being searched. value Number or string that is to be found in the items of the list. delimiters Set of delimiters used in the list.

PAGE 439

Chapter 2: ColdFusion Functions 415

PAGE 440

416 CFML Language Reference ListFindNoCase Returns the index of the first occurrence of a value within a list. Returns 0 if no value was found. The search is case-insensitive. See also ListContains and ListFind. Syntax ListFindNoCase(list, value [, delimiters ]) list List being searched. value Number or string being sought among elements of list. delimiters Set of delimiters used in list. Examples ...

PAGE 441

Chapter 2: ColdFusion Functions ListFirst Returns the first element of the list. See also ListGetAt, ListLast, and ListQualify. Syntax ListFirst(list [, delimiters ]) list List whose first element is being retrieved. delimiters Set of delimiters used in list.

PAGE 442

418 CFML Language Reference ListGetAt Returns the element at a given position. See also ListFirst, ListLast, ListQualify, and ListSetAt. Syntax ListGetAt(list, position [, delimiters ]) list List whose element is being retrieved. position Positive integer indicating the position of the element being retrieved. delimiters Set of delimiters used in list. Usage The first position in a list is denoted by the number 1, not 0.

PAGE 443

Chapter 2: ColdFusion Functions 419 ListInsertAt Returns list with value inserted at the specified position. See also ListDeleteAt, ListAppend, ListPrepend, and ListSetAt. Syntax ListInsertAt(list, position, value [, delimiters ]) list Any list. position Position where the value is being inserted. The first position in a list is denoted by the number 1, not 0. value Number or list being inserted. delimiters Set of delimiters used in list.

PAGE 444

420 CFML Language Reference ListLast Returns the last element of the list. See also ListGetAt and ListFirst. Syntax ListLast(list [, delimiters ]) list List whose last element is being retrieved. delimiters Set of delimiters used in list.

PAGE 445

Chapter 2: ColdFusion Functions ListLen Returns the number of elements in the list. See also ListAppend, ListDeleteAt, ListInsertAt, and ListPrepend. Syntax ListLen(list [, delimiters ]) list Any list. delimiters Set of delimiters used in list.

PAGE 446

422 CFML Language Reference ListPrepend Returns list with value inserted at the first position, shifting all other elements one to the right. See also ListAppend, ListInsertAt, and ListSetAt. Syntax ListPrepend(list, value [, delimiters ]) list Any list. value Number or list being prepended. delimiters Set of delimiters used in list. Usage When prepending an element to a list, ColdFusion needs to insert a delimiter.

PAGE 447

Chapter 2: ColdFusion Functions 423 ListQualify Returns a list with a qualifying character around each item in the list, such as double or single quotes. See the List Functions table. Syntax ListQualify(list, qualifier [, delimiters ] [, elements ]) list Any list of items or a variable that names a list. qualifier The character that is to be placed at the beginning and end of each item in the list. delimiters Set of delimiters used in list. elements Either the keyword “ALL” or “CHAR.

PAGE 448

424 CFML Language Reference

The contents of the unqualified list are as follows:

#myList#

There are no employees in #FORM.

PAGE 457

Chapter 2: ColdFusion Functions 433 ListValueCountNoCase Returns the number of instances of a specified value in a list. The underlying search that finds the instances is not case-sensitive. See also ListValueCount. Syntax ListValueCountNoCase(list, value [, delimiters ]) list A list or the name of a list that is to be searched. value The string or number that the function is to find and count. delimiter Optional. Specify the character(s) used to delimit elements in the list.

PAGE 458

434 CFML Language Reference

There are no employees in #FORM.

PAGE 459

Chapter 2: ColdFusion Functions LJustify Returns left-justified string of the specified field length. See also CJustify and RJustify. Syntax LJustify(string, length) string String to be left-justified. length Length of field. Example

PAGE 460

436 CFML Language Reference Log Returns the natural logarithm of a number. Natural logarithms are based on the constant e (2.71828182845904). See also Exp and Log10. Syntax Log(number) number Positive real number for which you want the natural logarithm. Examples Log Example

Log Example

Your number, #FORM.number#
#FORM.

PAGE 461

Chapter 2: ColdFusion Functions 437 Log10 Returns the logarithm of number to base 10. See also Exp and Log. Syntax Log10(number) number Positive real number for which you want the logarithm. Examples Log10 Example

Log10 Example

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

PAGE 462

438 CFML Language Reference LSCurrencyFormat Returns a currency value using the locale convention. Default value is "local." See, also, LSEuroCurrencyFormat. Syntax LSCurrencyFormat(number [, type ]) number The currency value. type Currency type. Valid arguments are: • none — (For example, 10.00) • local — (Default. For example, $10.00) • international — (For example, USD10.

PAGE 463

Chapter 2: ColdFusion Functions 439 Locale Format Type Output (Continued) English (US) Local: $100,000.00 International: USD100,000.00 None: 100,000.00 French (Belgian) Local: 100.000,00 FB International: BEF100.000,00 None: 100.000,00 French (Canadian) Local: 100 000,00 $ International: CAD100 000,00 None: 100 000,00 French (Standard) Local: 100 000,00 F International: FRF100 000,00 None: 100 000,00 French (Swiss) Local: SFr. 100’000.00 International: CHF100’000.00 None: 100’000.

PAGE 464

440 Example CFML Language Reference Locale Format Type Output (Continued) Spanish (Mexican) Local: $100,000.00 International: MXN100,000.00 None: 100,000.00 Spanish (Modern) Local: 10.000.000 Pts International: ESP10.000.000 None: 10.000.000 Spanish (Standard) Local: 10.000.000 Pts International: ESP10.000.000 None: 10.000.000 Swedish Local: 100.000,00 kr International: SEK100.000,00 None: 100.

PAGE 465

Chapter 2: ColdFusion Functions 441 LSDateFormat Formats the date portion of a date/time value using the locale convention. Like DateFormat LSDateFormat returns a formatted date/time value. If no mask is specified, LSDateFormat returns a date value using the locale-specific format. Syntax LSDateFormat(date [, mask ]) date Date/time object in the period from 100 AD to 9999 AD.

PAGE 466

442 CFML Language Reference PAGE 467

Chapter 2: ColdFusion Functions 443 LSEuroCurrencyFormat Returns a currency value using the convention of the locale and the Euro as the currency symbol. Default value is "local." Note The locale is set with the SetLocale function. See, also, LSParseEuroCurrency, LSCurrencyFormat, and SetLocale. Syntax LSEuroCurrencyFormat(currency-number [, type ]) currency-number The currency value. type Currency type. Valid arguments are: • none — (For example, 10.00) • local — (Default. For example, 10.

PAGE 468

444 CFML Language Reference Currency Output by Locale (Continued) Locale Format Type Output English (Australian) Local: €100,000.00 International: EUR100,000.00 None: 100,000.00 English (Canadian) Local: €100,000.00 International: EUR100,000.00 None: 100,000.00 English (New Zealand) Local: €100,000.00 International: EUR100,000.00 None: 100,000.00 English (UK) Local: €100,000.00 International: EUR100,000.00 None: 100,000.00 English (US) Local: €100,000.00 International: EUR100,000.

PAGE 469

Chapter 2: ColdFusion Functions 445 Currency Output by Locale (Continued) Example Locale Format Type Output Italian (Swiss) Local: € 100’000.00 International: EUR100’000.00 None: 100’000.00 Norwegian (Bokmal) Local: € 100 000,00 International: EUR100 000,00 None: 100 000,00 Norwegian (Nynorsk) Local: € 100 000,00 International: EUR100 000,00 None: 100 000,00 Portuguese (Brazilian) Local: €100.000,00 International: EUR100.000,00 None: 100.000,00 Portuguese (Standard) Local: €100.

PAGE 470

446 CFML Language Reference PAGE 471

Chapter 2: ColdFusion Functions 447 LSIsCurrency Checks whether a string is a locale-specific currency string. Returns TRUE if string is a currency string, FALSE otherwise. Syntax LSIsCurrency(string) string The locale-specific currency string. Example LSIsCurrency Example

LSIsCurrency Example

PAGE 472

448 CFML Language Reference LSIsDate Like the IsDate function, LSIsDate returns TRUE if string can be converted to a date/ time value in the current locale, FALSE otherwise. Syntax LSIsDate(string) string Any string value. Usage Years less than 100 are interpreted as 20th century values. Examples LSIsDate Example

LSIsDate Example

PAGE 473

Chapter 2: ColdFusion Functions 449 LSIsNumeric Like the IsNumeric function, LSIsNumeric returns TRUE if string can be converted to a number in the current locale; otherwise, FALSE. Syntax LSIsNumeric(string) string Any string value. Examples LSIsNumeric Example

LSIsNumeric Example

PAGE 474

450 CFML Language Reference LSNumberFormat Formats a number using the locale convention. If mask is omitted, the number is formatted as an integer. Syntax LSNumberFormat(number [, mask ]) number The number you want to format. mask All LSNumberFormat mask characters apply except that ($) dollar, (,) comma, and (.) dot are mapped to their locale-specific counterparts. LSNumberFormat Mask Characters Character Meaning _ (underscore) Optional digit placeholder. 9 Optional digit placeholder.

PAGE 475

Chapter 2: ColdFusion Functions 451 and negative numbers in your application, use either the space or use (hyphen) to force a space in front of positive numbers and a minus sign in front of negative numbers. Usage The position of codes in format masks determines where those codes will have effect. For example, if you place a dollar sign character at the far left of a format mask, ColdFusion displays a dollar sign at the very left edge of the formatted number.

PAGE 476

452 Examples CFML Language Reference Number Mask Result 3.21 C(__^)__ "( 3.21) " 3.21 C__(^)__ " (3.21) " 12345678 12345678 LSNumberFormat Example

LSNumberFormat Example

LSNumberFormat returns a number value using the locale convention. PAGE 477

Chapter 2: ColdFusion Functions 453 LSParseCurrency Converts a locale-specific currency string to a number. Attempts conversion through each of the three default currency formats (none, local, international). Returns the number matching the value of string. See, also, LSCurrencyFormat and LSParseEuroCurrency. Syntax LSParseCurrency(string) string The locale-specific string you want to convert to a number.

PAGE 478

454 CFML Language Reference Currency Output by Locale (Continued) Locale Format Type Output French (Belgian) Local: 100.000,00 FB International: BEF100.000,00 None: 100.000,00 French (Canadian) Local: 100 000,00 $ International: CAD100 000,00 None: 100 000,00 French (Standard) Local: 100 000,00 F International: FRF100 000,00 None: 100 000,00 French (Swiss) Local: SFr. 100’000.00 International: CHF100’000.00 None: 100’000.00 German (Austrian) Local: öS 100.000,00 International: ATS100.

PAGE 479

Chapter 2: ColdFusion Functions 455 Currency Output by Locale (Continued) Example Locale Format Type Output Spanish (Mexican) Local: $100,000.00 International: MXN100,000.00 None: 100,000.00 Spanish (Modern) Local: 10.000.000 Pts International: ESP10.000.000 None: 10.000.000 Spanish (Standard) Local: 10.000.000 Pts International: ESP10.000.000 None: 10.000.000 Swedish Local: 100.000,00 kr International: SEK100.000,00 None: 100.

PAGE 480

456 CFML Language Reference LSParseDateTime A locale-specific version of the ParseDateTime function, except that there is no option for POP date/time object parsing. Returns a date/time object. See also ParseDateTime and SetLocale. Syntax LSParseDateTime(date-time-string) date-time-string String being converted to date/time object. This string must be in a form that is readable in the current locale setting. By default the locale is set to English (US).

PAGE 481

Chapter 2: ColdFusion Functions 457

LSParseDateTime returns a locale-specific date/time object. PAGE 482

458 CFML Language Reference LSParseEuroCurrency Converts a locale-specific currency string that contains the Euro symbol (€) or sign (EUR) to a number. Attempts conversion through each of the three default currency formats (none, local, international). Returns the number matching the value of string. See, also, LSParseCurrency, LSEuroCurrencyFormat and SetLocale. Syntax LSParseEuroCurrency(currency-string) currency-string The locale-specific string you want to convert to a number.

PAGE 483

Chapter 2: ColdFusion Functions 459

PAGE 484

460 CFML Language Reference LSParseNumber Converts a locale-specific string to a number. Returns the number matching the value of string. Syntax LSParseNumber(string) string String being converted to a number. Examples LSParseNumber Example

LSParseNumber Example

LSParseNumber converts a locale-specific string to a number. Returns the number matching the value of string.

PAGE 485

Chapter 2: ColdFusion Functions 461 LSTimeFormat Returns a custom-formatted time value using the locale convention. See also LSParseDateTime. Syntax LSTimeFormat(time [, mask ]) string Any date/time value or string convertible to a time value. mask A set of masking characters determining the format: • h — Hours with no leading zero for single-digit hours. (Uses a 12-hour clock.) • hh — Hours with a leading zero for single-digit hours. (Uses a 12-hour clock.

PAGE 486

462 CFML Language Reference INDEX="locale" DELIMITERS=",">

#locale#
#LSTimeFormat(Now())#
#LSTimeFormat(Now(), ‘hh:mm:ss’)#
#LSTimeFormat(Now(), ‘hh:mm:sst’)#
#LSTimeFormat(Now(), ‘hh:mm:sstt’)#
#LSTimeFormat(Now(), ‘HH:mm:ss’)#

PAGE 487

Chapter 2: ColdFusion Functions LTrim Returns string with leading spaces removed. See also RTrim and ToBase64. Syntax LTrim(string) string String being left-trimmed. Examples LTrim Example

LTrim Example

 Your string:"#FORM.myText#" Your string:"#Ltrim(FORM.myText)#" (left trimmed)

PAGE 489

Chapter 2: ColdFusion Functions 465 Mid Returns count characters from string beginning at start position. See also Left, Len, and Right. Syntax Mid(string, start, count) string Any string. start Starting position for count. count Number of characters being returned. Examples Mid Example

Mid Example

PAGE 490

466 CFML Language Reference Min Returns the minimum, or smaller, value of two numbers. See also Max. Syntax Min(number1, number2) number1, number2 Any numbers. Examples Min Example

Min Example

The maximum of the two numbers is #Max(FORM.myNum1, FORM.

PAGE 491

Chapter 2: ColdFusion Functions 467 Minute Returns the ordinal for the minute, ranging from 0 to 59. See also DatePart, Hour, and Second. Syntax Minute(date) date Any date. Usage Years from 0 to 29 are interpreted as 21st century values. Years 30 to 99 are interpreted as 20th century values. When passing a date/time value as a string, make sure it is enclosed in quotes. Otherwise, it is interpreted as a number representation of a date/time object, returning undesired results.

PAGE 492

468 CFML Language Reference Month Returns the ordinal for the month, ranging from 1 (January) to 12 (December). See also DatePart, MonthAsString, and Quarter. Syntax Month(Date) date Any date. Usage Years from 0 to 29 are interpreted as 21st century values. Years 30 to 99 are interpreted as 20th century values. When passing a date/time value as a string, make sure it is enclosed in quotes. Otherwise, it is interpreted as a number representation of a date/time object, returning undesired results.

PAGE 493

Chapter 2: ColdFusion Functions MonthAsString Returns the name of the month corresponding to month_number. See also DatePart, Month, and Quarter. Syntax MonthAsString(month_number) month_number An integer ranging from 1 to 12. Examples MonthAsString Example

MonthAsString Example

More information about your date:

PAGE 494

470 CFML Language Reference Now Returns the current date and time as a valid date time object. See also CreateDateTime and DatePart. Syntax Now() Examples Now Example

Now Example

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

PAGE 495

Chapter 2: ColdFusion Functions 471 NumberFormat Creates a custom-formatted number value. If no mask is specified, returns the value as an integer with a thousands separator. See also DecimalFormat, DollarFormat, and IsNumeric. Syntax NumberFormat(number [, mask ]) number The number you want to format. mask Set of characters that are used to show how ColdFusion should display the number. Mask characters Character Meaning _ (underscore) Optional digit placeholder. 9 Optional digit placeholder.

PAGE 496

472 CFML Language Reference Note If you do not specify a sign for the mask, positive and negative numbers will not align in columns. As a result, if you expect to display both positive and negative numbers in your application, use either the space or use (minus sign) to force a space in front of positive numbers and a minus sign in front of negative numbers. Usage The position of codes in format masks determines where those codes will have effect.

PAGE 497

Chapter 2: ColdFusion Functions 473 of fields they are located in. The following example shows how to use the field to determine exactly where to place parentheses to display negative numbers: Examples Number Mask Result 3.21 C(__^__) "( 3.21 )" 3.21 C__(^__) " (3.21 )" 3.21 C(__^)__ "( 3.21) " 3.21 C__(^)__ " (3.

PAGE 498

474 CFML Language Reference ParagraphFormat Returns string with converted single newline characters (CR/LF sequences) into spaces and double newline characters into HTML paragraph markers (

). See also StripCR. Syntax ParagraphFormat(string) string String being converted to the HTML paragraph format. Usage ParagraphFormat is useful for displaying data entered into TEXTAREA fields.

PAGE 499

Chapter 2: ColdFusion Functions 475 ParameterExists Returns True if the specified parameter has been passed to the current template or has already been created during execution of the current template. Otherwise returns NO. This function is provided for backward compatibility with previous versions of ColdFusion. You should use the function IsDefined instead. See also GetClientVariablesList and IsDefined. Syntax ParameterExists(parameter) parameter Any syntactically valid parameter name.

PAGE 500

476 CFML Language Reference ParseDateTime Returns a date/time object from a string. See also LSParseDateTime, IsDate and IsNumericDate. Syntax ParseDateTime(date-time-string [, pop-conversion ] ) date-time-string String being converted to date/time object. pop-conversion POP or STANDARD. If you specify POP, the function takes the date/time string passed from a POP mail server and converts it to GMT (Greenwich Mean Time) for the English (US) locale.

PAGE 501

Chapter 2: ColdFusion Functions

The expression #DE(FORM.theTestValue)# is a valid date

The date, parsed for use as a date/time value: #ParseDateTime(FORM.theTestValue)# ...

PAGE 502

478 CFML Language Reference Pi Returns the number 3.14159265358979, the mathematical constant π, accurate to 15 digits. See also ASin, Cos, Sin, and Tan. Syntax Pi() Examples Pi Example

Pi Example

Returns the number #NumberFormat(Pi(), ‘_._______________’)# , the mathematical constant pi, accurate to 15 digits.

PAGE 503

Chapter 2: ColdFusion Functions PreserveSingleQuotes Prevents ColdFusion from automatically “escaping” single quotes contained in variable. Syntax PreserveSingleQuotes(variable) variable Variable containing the string for which single quotes are preserved. Usage PreserveSingleQuotes is useful in SQL statements.

PAGE 504

480 CFML Language Reference Quarter Returns the number of the quarter, an integer ranging from 1 to 4. See also DatePart and Month. Syntax Quarter(date) date Any date. Usage Years from 0 to 29 are interpreted as 21st century values. Years 30 to 99 are interpreted as 20th century values. When passing a date/time value as a string, make sure it is enclosed in quotes. Otherwise, it is interpreted as a number representation of a date/time object, returning undesired results.

PAGE 505

Chapter 2: ColdFusion Functions 481 QueryAddColumn Adds a new column to a specified query and populates the column’s rows with the contents of a one-dimensional array. Returns the query object with the additional column. Padding is added, if necessary, on the query columns to ensure that all columns have the same number of rows. See also CFQUERY, QueryNew, QueryAddRow and QuerySetCell. Syntax QueryAddColumn(query, column-name, array-name) query Name of a query that was created with QueryNew.

PAGE 506

482 CFML Language Reference

After populating the query, the example shows, in tabular format, the contents of the columns.

PAGE 507

Chapter 2: ColdFusion Functions QueryAddRow Adds a specified number of empty rows to the specified query. Returns the total number of rows in the query that you are adding rows to. See also QueryNew, QueryAddColumn and QuerySetCell. Syntax QueryAddRow(query [, number ]) query Name of the query already executed. number Number of rows to add to the query. Default is 1.

PAGE 508

484 CFML Language Reference QueryNew Returns an empty query with a set of columns or an empty query with no columns. See Usage for more information. See also QueryAddColumn, QueryAddRow and QuerySetCell. Syntax QueryNew(columnlist) columnlist Comma-separated list of columns you want to add to the new query or an empty string. Usage If you specify an empty string, you can add a new column to the query and populate its rows with the contents of a one-dimensional array using QueryAddColumn.

PAGE 509

Chapter 2: ColdFusion Functions 485 QuerySetCell Sets the cell in a specified column to a specified value. If no row number is specified, the cell on the last row will be set. Returns TRUE. See also QueryAddColumn and QueryAddRow. Syntax QuerySetCell(query, column_name, value [, row_number ]) query Name of the query already executed. column_name Name of the column in the query. value Value to set in the specified cell. row_number Number of the row. Defaults to last row.

PAGE 510

486 CFML Language Reference "Description of variable #Countvar#")>

After the QueryAddRow action, the query has #GetCourses.RecordCount# records.

PAGE 511

Chapter 2: ColdFusion Functions QuotedValueList Returns a comma-separated list of the values of each record returned from a previously executed query. Each value in the list is enclosed in single quotes. See also ValueList. Syntax QuotedValueList(query.column [, delimiter ]) query.column Name of an already executed query and column. Separate query name and column name with a period ( . ). delimiter A string delimiter to separate column data.

PAGE 512

488 CFML Language Reference Rand Returns a random decimal number in the range 0 to 1. See also Randomize and RandRange. Syntax Rand() Usage To ensure even greater randomness, call Randomize before calling Rand. Example Rand Example

Rand Example

Rand() returns a random number in the range 0 to 1.

Rand() returned: #Rand()#

PAGE 513

Chapter 2: ColdFusion Functions 489 Randomize Seeds the random number generator in ColdFusion with the integer part of a number. By seeding the random number generator with a variable value, you help to ensure that the Rand function generates highly random numbers. See also Rand and RandRange. Syntax Randomize(number) number Any number. Usage Call this function before calling Rand. Although this function returns a decimal number in the range 0 to 1, it is not a random number and you should not use it.

PAGE 514

490 CFML Language Reference RandRange Returns a random integer between two specified numbers. Note that requests for random integers greater than 100,000,000 will result in non-random behavior. This restriction prevents overflow during internal computations. See also Rand and Randomize. Syntax RandRange(number1, number2) number1, number2 Integer numbers less than 100,000,000.

PAGE 515

Chapter 2: ColdFusion Functions 491 REFind Returns the position of the first occurrence of a regular expression in a string starting from the specified position. Returns 0 if no occurrences are found. This search is case sensitive. Returns the position and length of the first occurrence of a regular expression in a string if the returnsubexpressions parameter is set to True. See the description of the returnsubexpressions parameter and the “Usage” section for details.

PAGE 516

492 CFML Language Reference length of the first instance of each subexpression within the regular expression are returned in subsequent elements of the arrays. Examples REFind Example

REFind Example

This example demonstrates the use of the REFind function with and without the returnsubexpressions parameter set to True.

PAGE 517

Chapter 2: ColdFusion Functions 493

In order to create this structure you can use a CFSET statement, for example:

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 in the regular expression.

The value of st.

PAGE 518

494 CFML Language Reference REFindNoCase Returns the position of the first occurrence of a regular expression in a string starting from the specified position if the returnsubexpressions parameter is not set to True. Returns 0 if no occurrences are found.The search is case-insensitive. Returns the position and length of the first occurrence of a regular expression in a string if the returnsubexpressions parameter is set to True.

PAGE 519

Chapter 2: ColdFusion Functions 495 length of the first instance of each subexpression within the regular expression are returned in subsequent elements of the arrays. Examples REFindNoCase Example

REFindNoCase Example

This example demonstrates the use of the REFindNoCase function with and without the returnsubexpressions parameter set to True.

PAGE 520

496 CFML Language Reference

In order to create this structure you can use a CFSET statement, for example:

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.

PAGE 521

Chapter 2: ColdFusion Functions 497 RemoveChars Returns string with count characters removed from the specified starting position. Return 0 if no characters are found. See also Insert and Len. Syntax RemoveChars(string, start, count) string Any string. start Starting position for the search. count Number of characters being removed.

PAGE 522

498 CFML Language Reference RepeatString Returns a string created from string being repeated a specified number of times. See also CJustify, LJustify, and RJustify. Syntax RepeatString(string, count) string String being repeated. count Number of repeats.

PAGE 523

Chapter 2: ColdFusion Functions Replace Returns string with occurrences of substring1 being replaced with substring2 in the specified scope. See also Find, ReplaceNoCase, ReplaceList, and REReplace. Syntax Replace(string, substring1, substring2 [, scope ]) string Any string. substring1 String to be replaced. substring2 String that should replace occurrences of substring1. scope Defines how to complete the replace operation: • ONE — Replace only the first occurrence (default).

PAGE 524

500 CFML Language Reference ReplaceList Returns string with all occurrences of the elements from the specified commadelimited list being replaced with their corresponding elements from another commadelimited list. The search is case-sensitive. See also Find, Replace, and REReplace. Syntax ReplaceList(string, list1, list2) string Any string. list1 Comma-delimited list of substrings to be replaced. list2 Comma-delimited list of replace substrings.

PAGE 525

Chapter 2: ColdFusion Functions 501
String 1

Substring 1 (find this list of substrings)

Substring 2 (replace with this list of substrings)

PAGE 526

502 CFML Language Reference ReplaceNoCase Returns string with occurrences of substring1 being replaced regardless of case matching with substring2 in the specified scope. See also Find, Replace, ReplaceList, and REReplace. Syntax ReplaceNoCase(string, substring1, substring2 [, scope ]) string Any string. substring1 String to be replaced. substring2 String that should replace occurrences of substring1.

PAGE 527

Chapter 2: ColdFusion Functions 503 REReplace Returns string with a regular expression being replaced with substring in the specified scope. This is a case-sensitive search. See also REFind, Replace, ReplaceList, and REReplaceNoCase. Syntax REReplace(string, reg_expression, substring [, scope ]) string Any string. reg_expression Regular expression to be replaced. This regular expression can include POSIXspecified character classes (for example, [:alpha:], [:digit:], [:upper:], and [:lower:]).

PAGE 528

504 CFML Language Reference REReplaceNoCase Returns string with a regular expression being replaced with substring in the specified scope. The search is case-insensitive. See also REFind, REFindNoCase, Replace, and ReplaceList. Syntax REReplaceNoCase(string, reg_expression, substring [, scope ]) string Any string. reg_expression Regular expression to be replaced. This regular expression can include POSIXspecified character classes (for example, [:alpha:], [:digit:], [:upper:], and [:lower:]).

PAGE 529

Chapter 2: ColdFusion Functions Reverse Returns string with reversed order of characters. See also Left, Mid, and Right. Syntax Reverse(string) string String being reversed. Examples Reverse Example
Reverse Example

Reverse returns your string with the positions of the characters reversed.

PAGE 530

506 CFML Language Reference Right Returns the rightmost count characters of a string. See also Left, Len, and Mid. Syntax Right(string, count) string String from which the rightmost characters are retrieved. count Integer indicating how many characters to return. Examples Right Example
Right Example

PAGE 531

Chapter 2: ColdFusion Functions RJustify Returns right-justified string in the specified field length. See also CJustify and LJustify. Syntax RJustify(string, length) string String to be right-justified. length Length of field. Example

PAGE 532

508 CFML Language Reference Round Rounds a number to the closest integer. See also Ceiling, Fix, and Int. Syntax Round(number) number Number being rounded. Examples 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.

PAGE 533

Chapter 2: ColdFusion Functions 509 RTrim Returns string with removed trailing spaces. See also LTrim and Trim. Syntax RTrim(string) string String being right-trimmed. Examples RTrim Example
RTrim Example

Your string:"#FORM.myText#" Your string:"#Rtrim(FORM.myText)#" (right trimmed)

PAGE 534
510 CFML Language Reference Second For a date/time value, returns the ordinal for the second, an integer from 0 to 59. See also DatePart, Hour, and Minute. Syntax Second(date) date Any date. Usage When passing a date/time value as a string, make sure it is enclosed in quotes. Otherwise, it is interpreted as a number representation of a date/time object, returning undesired results.

PAGE 535

Chapter 2: ColdFusion Functions 511 SetLocale Sets the locale to the specified new locale for the current session. Note SetLocale returns the old locale in case it needs to be restored. See also GetLocale. Syntax SetLocale(new_locale) new_locale The name of the locale you want to set.

PAGE 536

512 CFML Language Reference
SetLocale Example

SetLocale sets the locale to the specified new locale for the current session.
A locale is an encapsulation of the set of attributes that govern the display and formatting of international date, time, number, and currency values.

PAGE 537

Chapter 2: ColdFusion Functions 513 SetProfileString Sets the value of a profile entry in an initialization file. This function returns an empty string if the operation succeeds or an error message if the operation fails. See also GetProfileString. Syntax SetProfileString(iniPath, section, entry, value) iniPath Fully qualified path (drive, directory, filename, and extension) of the initialization file. section The section of the initialization file in which the entry is to be set.

PAGE 538

514 CFML Language Reference

Setting the timeout value to #MyTimeout#

Value returned from SetProfileString: #code#

Timeout value should be greater than zero in order to provide time for user response.

PAGE 539

Chapter 2: ColdFusion Functions 515 SetVariable The function sets the variable specified by name to value and returns the new value of the variable. See also DeleteClientVariable and GetClientVariablesList. Syntax SetVariable(name, value) name Valid variable name. value String or number assigned to the variable.

PAGE 540

516 CFML Language Reference Sgn Determines the sign of a number. Returns 1 if number is positive; 0 if number is 0; and -1 if number is negative. See also Abs. Syntax Sgn(number) number Any number. Examples Sgn Example
Sgn Example

Sgn determines the sign of a number. Returns 1 if number is positive; 0 if number is 0; and -1 if number is negative.

PAGE 541

Chapter 2: ColdFusion Functions 517 Sin Returns the sine of the given angle. See also ASin, Atn, Cos, Pi, and Tan. Syntax Sin(number) number Angle in radians for which you want the sine. If the angle is in degrees, multiply it by PI()/180 to convert it to radians. Examples Sin Example
Sin Example

PAGE 542

518 CFML Language Reference SpanExcluding Returns all characters from string from its beginning until it reaches a character from the set of characters. The search is case-sensitive. See also GetToken and SpanIncluding. Syntax SpanExcluding(string, set) string Any string. set String containing one or more characters being sought.

PAGE 543

Chapter 2: ColdFusion Functions 519 SpanIncluding Returns all characters from string from its beginning until it reaches a character that is not included in the specified set of characters. The search is case-sensitive. See also GetToken and SpanExcluding. Syntax SpanIncluding(string, set) string Any string. set String containing one or more characters being sought.

PAGE 544

520 CFML Language Reference Sqr Returns a positive square root. See also Abs. Syntax Sqr(number) number Number for which you want the square root. Usage Number must be greater than or equal to 0. Examples Sqr Example
Sqr Example

Returns a positive square root for a number.

PAGE 545

Chapter 2: ColdFusion Functions 521 StripCR Returns string with all carriage return characters removed. See also ParagraphFormat. Syntax StripCR(string) string String being formatted. Usage Function StripCR is useful for preformatted HTML display of data (PRE) entered into TEXTAREA fields.

PAGE 546

522 CFML Language Reference StructClear Removes all data from the specified structure. Always returns Yes. See also StructDelete, StructFind, StructInsert, StructIsEmpty, StructKeyArray, StructCount, StructKeyArray, and StructUpdate. Syntax StructClear(structure) structure Structure to be cleared. Example
This file is similar to addemployee.

PAGE 548

524 CFML Language Reference StructCount Returns the number of keys in the specified structure. See also StructClear, StructDelete, StructFind, StructInsert, StructIsEmpty, StructKeyArray, StructKeyArray, and StructUpdate. Syntax StructCount(structure) structure Structure to be accessed. Usage This function throws an exception if structure does not exist. Example
This file is similar to addemployee.

PAGE 549

Chapter 2: ColdFusion Functions 525 StructDelete Removes the specified item from the specified structure. See also StructClear, StructFind, StructInsert, StructIsEmpty, StructKeyArray, StructCount, StructKeyArray, and StructUpdate. Syntax StructDelete(structure, key [, indicatenotexisting ]) structure Structure containing the item to be removed. key Item to be removed. indicatenotexisting Indicates whether the function returns FALSE if key does not exist.

PAGE 550

526 CFML Language Reference employee is a structure: #IsStruct(employee)#
Did I delete the field "#form.field#"? The code indicates: #rc#
PAGE 551
Chapter 2: ColdFusion Functions StructFind Returns the value associated with the specified key in the specified structure. See also StructClear, StructDelete, StructInsert, StructIsEmpty, StructKeyArray, StructCount, StructKeyArray, and StructUpdate. Syntax StructFind(structure, key) structure Structure containing the value to be returned. key Key whose value is returned. Usage This function throws an exception if structure does not exist.

PAGE 552

528 CFML Language Reference StructInsert Inserts the specified key-value pair into the specified structure. Returns Yes if the insert was successful and No if an error occurs. See also StructClear, StructDelete, StructFind, StructIsEmpty, StructKeyArray, StructCount, StructKeyArray, and StructUpdate. Syntax StructInsert(structure, key, value [, allowoverwrite ]) structure Structure to contain the new key-value pair. key Key that contains the inserted value. value Value to be added.

PAGE 553

Chapter 2: ColdFusion Functions StructInsert(employee, StructInsert(employee, StructInsert(employee, StructInsert(employee, 529 "lastname", FORM.lastname); "email", FORM.email); "phone", FORM.phone); "department", FORM.

PAGE 554

530 CFML Language Reference StructIsEmpty Indicates whether the specified structure contains data. Returns TRUE if structure is empty and FALSE if it contains data. See also StructClear, StructDelete, StructFind, StructInsert, StructKeyArray, StructCount, StructKeyArray, and StructUpdate. Syntax StructIsEmpty(structure) structure Structure to be tested. Usage This function throws an exception if structure does not exist. Example Tan Example
Tan Example

Returns the tangent of a given angle.

PAGE 565

Chapter 2: ColdFusion Functions 541 TimeFormat Returns a custom-formatted time value. If no mask is specified, the TimeFormat function returns time value using the hh:mm tt format. See also CreateTime, Now, and ParseDateTime. Syntax TimeFormat(time [, mask ]) time Any date/time value or string convertible to a time value. mask A set of masking characters determining the format: • h — Hours with no leading zero for single-digit hours. (Uses a 12-hour clock.

PAGE 566

542 CFML Language Reference
Using Timeformat, we can display that date/time value in a number of different ways:

#TimeFormat(todayDate)#
#TimeFormat(todayDate, "hh:mm:ss")#
#TimeFormat(todayDate, "hh:mm:sst")#
#TimeFormat(todayDate, "hh:mm:sstt")#
#TimeFormat(todayDate, "HH:mm:ss")#

PAGE 567

Chapter 2: ColdFusion Functions 543 ToBase64 Returns the Base 64 representation of the string or binary object. Base64 is a format that uses printable characters, allowing binary data to be sent in forms and Email, and stored in a database or file. See also CFFILE for information about loading and reading binary data, CFWDDX for information about serializing and deserializing binary data, and IsBinary and ToBinary for checking for binary data and converting a Base 64 object to binary form.

PAGE 568

544 CFML Language Reference #charData#
Trim Example
Trim Example

Your string:"#FORM.myText#" Your string:"#trim(FORM.myText)#" (trimmed on both sides)
PAGE 574
550 CFML Language Reference UCase Returns string converted to uppercase. See also LCase. Syntax UCase(string) string String being converted to uppercase. Examples UCase Example
UCase Example

Your text, #FORM.sampleText#, returned in uppercase is #UCase(FORM.sampleText)# .

PAGE 575

Chapter 2: ColdFusion Functions 551 URLDecode Decodes a URL-encoded string. See also URLEncodedFormat. Syntax 85/'HFRGH XUO(QFRGHG6WULQJ urlEncodedString A string that has been URL-encoded. Usage URL encoding refers to a data format where all high ASCII and non-alphanumeric characters are encoded using a percent sign followed by the two character hexadecimal representation of the character code. For example, a character with code 129 will be encoded as %81.

PAGE 576

552 CFML Language Reference URLEncodedFormat Returns a URL-encoded string. Spaces are replaced with + and all non-alphanumeric characters with equivalent hexadecimal escape sequences. This function enables you to pass arbitrary strings within a URL, because ColdFusion automatically decodes all URL parameters that are passed to the template. See also URLDecode. Syntax URLEncodedFormat(string) string String being URL encoded.

PAGE 577

Chapter 2: ColdFusion Functions Val Returns a number that the beginning of a string can be converted to. Returns 0 if conversion is not possible. See also IsNumeric. Syntax Val(string) string Any string. Examples Val Example
Val Example

The string #DE(FORM.

PAGE 578

554 CFML Language Reference ValueList Returns a comma-separated list of the values of each record returned from a previously executed query. See also QuotedValueList. Syntax ValueList(query.column [, delimiter ]) query.column Name of an already executed query and column. Separate query name and column name with a period ( . ). delimiter A string delimiter to separate column data.

PAGE 579

Chapter 2: ColdFusion Functions 555 Week Returns the ordinal for the week number in a year; an integer ranging from 1 to 53. See also DatePart. Syntax Week(date) date Any date/time value or string convertible to date. Usage Years from 0 to 29 are interpreted as 21st century values. Years 30 to 99 are interpreted as 20th century values. When passing date as a string, make sure it is enclosed in quotes. Otherwise, it is interpreted as a number representation of a date returning undesired results.

PAGE 580

556 CFML Language Reference WriteOutput Appends text to the page output stream. Although you can call this function anywhere within a page, it is most useful inside a CFSCRIPT block. Note When within the CFQUERY and CFMAIL tags, the WriteOutput function does not output to the current page, but instead writes to the current SQL statement or mail text. Do not use WriteOutput within CFQUERY and CFMAIL.

PAGE 581

Chapter 2: ColdFusion Functions 557 XMLFormat Returns a string that is safe to use with XML. Syntax XMLFormat(string) string Any string. Usage XMLFormat escapes special XML characters so that you can put arbitrary strings safely into XML.

PAGE 582

558 CFML Language Reference Year Returns the year corresponding to date. See also DatePart and IsLeapYear. Syntax Year(date) date Any date/time value or string convertible to date. Usage Years from 0 to 29 are interpreted as 21st century values. Years 30 to 99 are interpreted as 20th century values. When passing a date as a string, make sure it is enclosed in quotes. Otherwise, it is interpreted as a number representation of a date returning, undesired results.

PAGE 583

Chapter 2: ColdFusion Functions 559 YesNoFormat Returns Boolean data as YES or NO. See also IsBinary and IsNumeric. Syntax YesNoFormat(value) value Any number or Boolean value. Usage The YesNoFormat function returns all non-zero values as YES and zero values as NO. Examples YesNoFormat Example
YesNoFormat Example

The YesNoFormat function returns all non-zero values as "YES" and zero values as "NO".

PAGE 584

560 CFML Language Reference

PAGE 585

CHAPTER 3 Chapter 3 WDDX JavaScript Objects This chapter provides information about JavaScript objects and functions used when implementing WDDX in a ColdFusion application. Contents • WddxSerializer Object.................................................................................... 562 • WddxRecordset Object...................................................................................

PAGE 586

562 CFML Language Reference WddxSerializer Object The WddxSerializer object includes functions that serialize any JavaScript data structure. The only function that developers typically call is serialize. serialize Creates a WDDX packet for a passed WddxRecordset instance. Syntax object.serialize( rootobj ) object Instance name of the WddxSerializer object. rootobj JavaScript data structure to be serialized. Return String.

PAGE 587

Chapter 3: WDDX JavaScript Objects 563 object Instance name of the WddxSerializer object. name Property to be serialized. obj Instance name of the value to be serialized. Return Boolean. Returns True if serialization was successful and False if an error occurs. value Usage Internal. You do not typically call this function. Example This example is from the WddxSerializer serializeValue function: ... // Some generic object; treat it as a structure this.

PAGE 588

564 CFML Language Reference object Instance name of the WddxSerializer object. obj Instance name of the WddxRecordset object to be serialized. Return Boolean. Returns True if obj was serialized successfully and False if an error occurs. value Usage Internal. You do not typically call this function. Example This example is from the WddxSerializer serialize function: ... this.wddxPacket = ""; this.write("
"); bSuccess = this.serializeValue(rootObj); this.

PAGE 589

Chapter 3: WDDX JavaScript Objects 565 ... else if (typeof(obj) == "number") { // Number value this.write("" + obj + ""); } else if (typeof(obj) == "boolean") { // Boolean value this.write(""); } ... WddxRecordset Object The WddxRecordset object includes functions that you call as needed when constructing a WDDX recordset. addColumn Adds the specified column to all rows in the WddxRecordset instance. Syntax object.

PAGE 590

566 CFML Language Reference // newValue is a previously defined variable rs.setField(0, "NewColumn", newValue); addRows Adds the specified number of rows to all columns in the WddxRecordset instance. Syntax object.addRows( n ) object Instance name of the WddxRecordset object. n Integer specifying the number of rows to add. Return None. value Usage This function adds the specified number of rows to every column of the WDDX record set. Initially, the row/column values are set to NULL.

PAGE 591

Chapter 3: WDDX JavaScript Objects 567 col Integer or string specifying the column of the value to be returned. Return Returns the value in the specified row/column position. value Usage Call this function to access a value in a WDDX record set. Example This example calls the getField function (the variable r is a reference to a WddxRecordset instance): for (row = 0; row < nRows; ++row) { o += "

" + r.

PAGE 592

568 CFML Language Reference setField Sets the element in the specified row/column position. Syntax object.setField( row, col, value ) object Instance name of the WddxRecordset object. row Integer specifying the row containing the element to be set. col Integer or string specifying the column containing the element to be set. value Value to be set. Return None. value Usage Call this function to set a value in a WddxRecordset instance.

PAGE 593

Chapter 3: WDDX JavaScript Objects WddxSerializer instance. Return Boolean. Returns True if serialization was successful and False if an error occurs. value Usage Internal. You do not typically call this function. Example This example is from the WddxSerializer serializeValue function: ... else if (typeof(obj) == "object") { if (obj == null) { // Null values become empty strings this.write(""); } else if (typeof(obj.

PAGE 594

570 CFML Language Reference

PAGE 595

CHAPTER 4 Chapter 4 ColdFusion Expressions: Operators and Other Constructs This chapter describes ColdFusion expressions — language constructs that allow you to create sophisticated applications. Contents • Elements of ColdFusion Expressions ........................................................... 572 • Operators ........................................................................................................ 576 • Operator Precedence .......................................................

PAGE 596

572 CFML Language Reference Elements of ColdFusion Expressions The following objects can be used to build expressions: Objects Used to Build ColdFusion Expressions Type Description Integers Numbers with no decimal point. Real numbers Numbers with a decimal part. Also known as floating point numbers. The range of ColdFusion numbers is approximately ±10300, or ±1 with 300 zeros after it. Most operations are accurate to 12 digits after the decimal point. ColdFusion supports scientific notation.

PAGE 597

Chapter 4: ColdFusion Expressions: Operators and Other Constructs 573 Objects Used to Build ColdFusion Expressions Type Description Time values You can directly enter a date-and-time object in any of the following formats: "October "October "October "October "October 30, 30, 30, 30, 30, 1999 1999 1999 1999 1999 02:34:12" 2:34a" 2:34am" 02:34am" 2am" The time part of the object is accurate to the second. Lists Lists are a special kind of string, made up of elements separated by delimiters.

PAGE 598

574 CFML Language Reference Objects Used to Build ColdFusion Expressions Type Description Queries ColdFusion queries can be referenced as objects by assigning a query to a variable: In this case (unlike the same operation with arrays) the query is not copied.

PAGE 599

Chapter 4: ColdFusion Expressions: Operators and Other Constructs 575 21st century dates Two-digit years from 00 to 29 are treated as 21st century dates; 30 to 99 are treated as 20th century dates. "October 30, 2015" "October 30, 15" Note Internally to ColdFusion, date-and-time values are represented on a time line as a subset of the real numbers. This is done for efficiency in evaluation and because it directly mimics the method used by many popular database systems, including Microsoft Access.

PAGE 600

576 CFML Language Reference (Client.MyVariable). Qualifiers are also known as scopes. Thus MyVariable is said to belong to the Form scope. In some cases, a variable must have pounds signs around it to allow ColdFusion to distinguish it from string or HTML text and to insert its value as opposed to its name. For more information on how to use pound signs in expressions see Pound Signs.

PAGE 601

Chapter 4: ColdFusion Expressions: Operators and Other Constructs Arithmetic Operators (Continued) Operator Description \ Divides two integer values. Use the \ (trailing slash) to separate the integers. The right operand cannot be zero. For example, 9 \ 4 is 2. ^ Returns the result of a number raised to a power (exponent). Use the ^ (caret) to separate the number from the power. The left operand cannot be zero. For example, 2 ^ 3 is 8.

PAGE 602

578 CFML Language Reference Decision Operators (Continued) Operator Description GREATER THAN OR EQUAL TO Checks to see if the value on the left is greater than or equal to the value on the right and returns true if it is. LESS THAN OR EQUAL TO Checks to see if the value on the left is less than or equal to the value on the right and returns true if it is.

PAGE 603

Chapter 4: ColdFusion Expressions: Operators and Other Constructs 579 Boolean operators Boolean, or Logical, operators perform logical connective and negation operations. The operands of Boolean operators are Boolean (TRUE/FALSE) values. Boolean Operators Operator Description NOT Reverses the value of an argument. For example, NOT TRUE is FALSE and vice versa. AND Returns TRUE if both arguments are TRUE; returns FALSE otherwise. For example, TRUE AND TRUE is TRUE, but TRUE AND FALSE is FALSE.

PAGE 604

580 CFML Language Reference XOR EQV IMP To enforce a specific non-standard order of evaluation, you must parenthesize expressions. For example: • 6 - 3 * 2 is equal to 0 • (6 - 3) * 2 is equal to 6 Parenthesized expressions can be arbitrarily nested. When in doubt about the order in which operators in an expression will be evaluated, always use parentheses. Function Syntax The following table illustrates function syntax and usage guidelines.

PAGE 605

Chapter 4: ColdFusion Expressions: Operators and Other Constructs 581 Pound Signs Pound signs (#) have special meaning in ColdFusion. When a CFML application page is processed, ColdFusion treats text delimited by pound signs differently from plain text. Two simple and very important points about pound signs in CFML are: • Use pound signs to distinguish expressions from plain text. • When expressions are evaluated, the resulting value is substituted for the expression text.

PAGE 606

582 CFML Language Reference Complex expressions Complex expressions involving one or more operators cannot be inserted inside CFOUTPUT tags. The following example will produce an error.

PAGE 607

Chapter 4: ColdFusion Expressions: Operators and Other Constructs 583 To insert the value of a complex expression inside a string, use CFSET to set some variable to the value of the expression and use that variable inside the string, or use the string concatenation operator: To insert the pound character inside a string, use two pound signs as shown below: PAGE 608

584 CFML Language Reference All of the above statements result in errors. As a general rule, never put pound signs around function arguments. Pound signs in general expressions Allaire recommends that pound signs be used only where necessary. The following example demonstrates the preferred method for referencing variables. It is a cleaner and more efficient method.