MACROMEDIA COLDFUSION MX 61-DEVELOPING COLDFUSION MX User manual

Developing ColdFusion MX Applications

Trademarks
Afterburner, AppletAce, Attain, Attain Enterprise Learning System, Attain Essentials, Attain Objects for Dreamweaver,
Authorware, Authorware Attain, Authorware Interactive Studio, Authorware Star, Authorware Synergy, Backstage, Backstage
Designer, Backstage Desktop Studio, Backstage Enterprise Studio, Backstage Internet Studio, ColdFusion, Design in Motion,
Director, Director Multimedia Studio, Doc Around the Clock, Dreamweaver, Dreamweaver Attain, Drumbeat, Drumbeat 2000,
Extreme 3D, Fireworks, Flash, Fontographer, FreeHand, FreeHand Graphics Studio, Generator, Generator Developer's Studio,
Generator Dynamic Graphics Server, JRun, Knowledge Objects, Knowledge Stream, Knowledge Track, Lingo, Live Effects,
Macromedia, Macromedia M Logo & Design, Macromedia Flash, Macromedia Xres, Macromind, Macromind Action, MAGIC,
Mediamaker, Object Authoring, Power Applets, Priority Access, Roundtrip HTML, Scriptlets, SoundEdit, ShockRave,
Shockmachine, Shockwave, Shockwave Remote, Shockwave Internet Studio, Showcase, Tools to Power Your Ideas, Universal
Media, Virtuoso, Web Design 101, Whirlwind and Xtra are trademarks of Macromedia, Inc. and may be registered in the United
States or in other jurisdictions including internationally. Other product names, logos, designs, titles, words or phrases mentioned
within this publication may be trademarks, servicemarks, or tradenames of Macromedia, Inc. or other entities and may be
registered in certain jurisdictions including internationally.
This product includes code licensed from RSA Data Security.
This guide contains links to third-party websites that are not under the control of Macromedia, and Macromedia is not
responsible for the content on any linked site. If you access a third-party website mentioned in this guide, then you do so at your
own risk. Macromedia provides these links only as a convenience, and the inclusion of the link does not imply that Macromedia
endorses or accepts any responsibility for the content on those third-party sites.
Apple Disclaimer
APPLE COMPUTER, INC. MAKES NO WARRANTIES, EITHER EXPRESS OR IMPLIED, REGARDING THE
ENCLOSED COMPUTER SOFTWARE PACKAGE, ITS MERCHANTABILITY OR ITS FITNESS FOR ANY
PARTICULAR PURPOSE. THE EXCLUSION OF IMPLIED WARRANTIES IS NOT PERMITTED BY SOME STATES.
THE ABOVE EXCLUSION MAY NOT APPLY TO YOU. THIS WARRANTY PROVIDES YOU WITH SPECIFIC LEGAL
RIGHTS. THERE MAY BE OTHER RIGHTS THAT YOU MAY HAVE WHICH VARY FROM STATE TO STATE.
Copyright © 1999–2003 Macromedia, Inc. All rights reserved. This manual may not be copied, photocopied, reproduced,
translated, or converted to any electronic or machine-readable form in whole or in part without prior written approval of
Macromedia, Inc.
Part Number ZCF61M800
Acknowledgments
Project Management: Randy Nielsen
Writing: Hal Lichtin, Randy Nielsen
Editing: Linda Adler, Noreen Maher
First Edition: May 2002
Second Edition: August 2003
Macromedia, Inc.
600 Townsend St.
San Francisco, CA 94103

3
CONTENTS
INTRODUCTION . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
Using this book . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
About Macromedia ColdFusion MX documentation . . . . . . . . . . . . . . . . . . . . . . 26
CHAPTER 1: Introduction to ColdFusion MX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
About Internet applications and web application servers . . . . . . . . . . . . . . . . . . . . 28
About web pages and Internet applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
About web application servers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
About ColdFusion MX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
The ColdFusion scripting environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
ColdFusion Markup Language . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
ColdFusion application services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
ColdFusion MX Administrator. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
Using ColdFusion MX with Macromedia Flash MX . . . . . . . . . . . . . . . . . . . . . . . 32
About J2EE and the ColdFusion architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
About ColdFusion MX and the J2EE platform. . . . . . . . . . . . . . . . . . . . . . . . . 33
ColdFusion features described in this book . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
PART I: The CFML Programming Language
CHAPTER 2: Elements of CFML . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
Character case . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
Tags. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
Tag syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
Built-in tags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
Custom tags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
Built-in functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
User-defined functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
Constants . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
Variable scopes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44

4 Contents
Data types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
ColdFusion components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
CFScript . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
Flow control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
cfif, cfelseif, and cfelse. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
cfswitch, cfcase, and cfdefaultcase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
cfloop and cfbreak . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
cfabort and cfexit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
Comments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
Special characters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
Reserved words . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
CHAPTER 3: Using ColdFusion Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
Creating variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
Variable naming rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
Variable characteristics. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
Data types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
Numbers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
Strings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
Boolean values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58
Date-Time values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58
Binary data type and Base64 encoding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
Complex data types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
Using periods in variable references . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
Understanding variables and periods. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
Creating variables with periods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
Data type conversion. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67
Operation-driven evaluation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67
Conversion between types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67
Evaluation and type conversion issues. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69
Examples of type conversion in expression evaluation . . . . . . . . . . . . . . . . . . . . 71
About scopes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
Scope types. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
Creating and using variables in scopes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75
Using scopes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77
Ensuring variable existence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78
Testing for a variable’s existence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79
Using the cfparam tag. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79
Validating data types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80
Using the cfparam tag to validate the data type. . . . . . . . . . . . . . . . . . . . . . . . . 81
Passing variables to custom tags and UDFs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82
Passing variables to CFML tags and UDFs . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82
Passing variables to CFX tags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82

Contents 5
CHAPTER 4: Using Expressions and Pound Signs . . . . . . . . . . . . . . . . . . . . . . . . 83
Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84
Operator types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84
Operator precedence and evaluation ordering. . . . . . . . . . . . . . . . . . . . . . . . . . 87
Using functions as operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
Using pound signs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89
Using pound signs in ColdFusion tag attribute values. . . . . . . . . . . . . . . . . . . . 89
Using pound signs in tag bodies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90
Using pound signs in strings. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90
Nested pound signs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91
Using pound signs in expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91
Dynamic expressions and dynamic variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92
About dynamic variables. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92
About dynamic expressions and dynamic evaluation. . . . . . . . . . . . . . . . . . . . . 92
Dynamic variable naming without dynamic evaluation . . . . . . . . . . . . . . . . . . 93
Using dynamic evaluation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94
Using the IIF function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98
Example: a dynamic shopping cart . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99
CHAPTER 5: Using Arrays and Structures. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103
About arrays . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104
Basic array concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104
About ColdFusion arrays . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104
Basic array techniques . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106
Referencing array elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106
Creating arrays . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106
Adding elements to an array . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108
Deleting elements from an array . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109
Copying arrays . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109
Populating arrays with data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110
Populating an array with the ArraySet function . . . . . . . . . . . . . . . . . . . . . . . 110
Populating an array with the cfloop tag. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110
Populating an array from a query . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112
Array functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113
About structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113
Structure notation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114
Referencing complex structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114
Creating and using structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116
Creating structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116
Adding data elements to structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117
Updating values in structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117
Getting information about structures and keys . . . . . . . . . . . . . . . . . . . . . . . . 117
Copying structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119
Deleting structure elements and structures . . . . . . . . . . . . . . . . . . . . . . . . . . . 121
Looping through structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121
Structure example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122
Structure functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125

6 Contents
CHAPTER 6: Extending ColdFusion Pages with CFML Scripting. . . . . . . . . . . . 127
About CFScript. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128
Comparing tags and CFScript . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128
The CFScript language . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129
Identifying CFScript. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129
Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129
Expressions and operators. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129
Statements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129
Statement blocks. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130
Comments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130
Reserved words. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131
Differences from JavaScript . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131
CFScript limitation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131
CFScript functional equivalents to ColdFusion tags . . . . . . . . . . . . . . . . . . . . 131
Using CFScript statements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132
Using assignment statements and functions . . . . . . . . . . . . . . . . . . . . . . . . . . 132
Using conditional processing statements. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132
Using looping statements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134
Handling exceptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139
CFScript example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140
CHAPTER 7: Using Regular Expressions in Functions . . . . . . . . . . . . . . . . . . . . 143
About regular expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144
Using ColdFusion regular expression functions. . . . . . . . . . . . . . . . . . . . . . . . 144
Basic regular expression syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145
Regular expression syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145
Using character sets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145
Finding repeating characters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146
Case sensitivity in regular expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147
Using subexpressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147
Using special characters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147
Using escape sequences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150
Using character classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151
Using backreferences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152
Using backreferences in replacement strings . . . . . . . . . . . . . . . . . . . . . . . . . . 153
Omitting subexpressions from backreferences. . . . . . . . . . . . . . . . . . . . . . . . . 154
Returning matched subexpressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154
Specifying minimal matching . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157
Regular expression examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158
Regular expressions in CFML. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159
Types of regular expression technologies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159

Contents 7
PART II: Reusing CFML Code
CHAPTER 8: Reusing Code in ColdFusion Pages . . . . . . . . . . . . . . . . . . . . . . . . 163
About reusable CFML elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164
Including pages with the cfinclude tag. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164
Using the cfinclude tag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165
Recommended uses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166
Calling user-defined functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166
Calling UDFs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166
Recommended uses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166
For more information. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167
Using custom CFML tags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167
Calling custom CFML tags. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168
Recommended uses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169
For more information. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169
Using CFX tags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169
Calling CFX tags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169
Recommended uses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170
For more information. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170
Using ColdFusion components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170
Creating and using ColdFusion components . . . . . . . . . . . . . . . . . . . . . . . . . 170
Recommended uses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171
For more information. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171
Selecting among ColdFusion code reuse methods . . . . . . . . . . . . . . . . . . . . . . . . 171
CHAPTER 9: Creating and Using Custom CFML Tags . . . . . . . . . . . . . . . . . . . . 173
Creating custom tags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174
Creating and calling custom tags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174
Securing custom tags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177
Accessing existing custom tags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177
Passing data to custom tags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177
Passing values to and from custom tags. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177
Using tag attributes summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178
Custom tag example with attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179
Passing custom tag attributes using CFML structures . . . . . . . . . . . . . . . . . . . 180
Managing custom tags. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181
Securing custom tags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181
Encoding custom tags. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181
Executing custom tags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182
Accessing tag instance data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182
Handling end tags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183
Processing body text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185
Terminating tag execution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185
Nesting custom tags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186
Passing data between nested custom tags . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187
Variable scopes and special variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187
High-level data exchange . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 188

8 Contents
CHAPTER 10: Writing and Calling User-Defined Functions . . . . . . . . . . . . . . . . 191
About user-defined functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192
Calling user-defined functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192
Creating user-defined functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193
Creating functions using CFScript . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193
Creating functions using tags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193
Rules for function definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194
Defining functions in CFScript . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198
Defining functions using the cffunction tag . . . . . . . . . . . . . . . . . . . . . . . . . . 200
Calling functions and using variables. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202
Passing arguments. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202
Referencing caller variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203
Using function-only variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203
Using arguments. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204
A User-defined function example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204
Defining the function using CFScript. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204
Defining the function using the cffunction tag . . . . . . . . . . . . . . . . . . . . . . . . 205
Using UDFs effectively . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 206
Using Application.cfm and function include files . . . . . . . . . . . . . . . . . . . . . . 206
Specifying the scope of a function. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 206
Using the Request scope for static variables and constants . . . . . . . . . . . . . . . 208
Using function names as function arguments . . . . . . . . . . . . . . . . . . . . . . . . . 208
Handling query results using UDFs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 208
Identifying and checking for UDFs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 209
Using the Evaluate function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 210
Passing complex data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 210
Using recursion. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212
Handling errors in UDFs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212
CHAPTER 11: Building and Using ColdFusion Components . . . . . . . . . . . . . . . . 219
About ColdFusion components. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 220
Basic component concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 220
ColdFusion component features and use . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222
Using ColdFusion components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 224
Instantiating CFCs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 225
CFC invocation techniques . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 225
Invoking CFC methods with the cfinvoke tag . . . . . . . . . . . . . . . . . . . . . . . . 226
Using components directly in CFScript and CFML . . . . . . . . . . . . . . . . . . . . 229
Invoking CFC methods using forms and URLs . . . . . . . . . . . . . . . . . . . . . . . 230
Accessing CFCs from outside ColdFusion and basic HTML . . . . . . . . . . . . . 232
Invoking components as web services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232
Introspection: getting information about components . . . . . . . . . . . . . . . . . . 233
Building ColdFusion components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235
Initializing instance data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 236
Defining component methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 236
Providing results . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 239
CFC variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 242
Structuring and reusing code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 244
Building secure ColdFusion components . . . . . . . . . . . . . . . . . . . . . . . . . . . . 248

Contents 9
CHAPTER 12: Building Custom CFXAPI Tags. . . . . . . . . . . . . . . . . . . . . . . . . . . 251
What are CFX tags?. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 252
Before you begin developing CFX tags in Java. . . . . . . . . . . . . . . . . . . . . . . . . . . 252
Sample Java CFX tags. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 252
Setting up your development environment to develop CFX tags in Java . . . . . 253
Customizing and configuring Java . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 253
Writing a Java CFX tag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 253
Calling the CFX tag from a ColdFusion page . . . . . . . . . . . . . . . . . . . . . . . . . 254
Processing requests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 255
Loading Java CFX classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 256
Automatic class reloading . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 257
Life cycle of Java CFX tags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 257
ZipBrowser example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 257
Approaches to debugging Java CFX tags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 259
Outputting debugging information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 259
Debugging in a Java IDE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 259
Using the debugging classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 260
Developing CFX tags in C++ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 261
Sample C++ CFX tags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 261
Setting up your C++ development environment . . . . . . . . . . . . . . . . . . . . . . . 261
Compiling C++ CFX tags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 262
Locating your C++ library files on UNIX . . . . . . . . . . . . . . . . . . . . . . . . . . . . 262
Implementing C++ CFX tags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 262
Debugging C++ CFX tags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 262
Registering CFX tags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 263
PART III: Developing CFML Applications
CHAPTER 13: Designing and Optimizing a ColdFusion Application . . . . . . . . . . 267
About applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 268
Elements of a ColdFusion application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 268
The application framework. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 268
Application-level settings and functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 269
Reusable application elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 269
Shared variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 270
Application security and user identification . . . . . . . . . . . . . . . . . . . . . . . . . . 270
Mapping an application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 270
Processing the Application.cfm and OnRequestEnd.cfm pages. . . . . . . . . . . . 271
Defining the directory structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 271
Creating the Application.cfm page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 272
Naming the application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 273
Setting the client, application, and session variables options . . . . . . . . . . . . . . 273
Defining page processing settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 274
Setting application default variables and constants . . . . . . . . . . . . . . . . . . . . . 274
Processing logins. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 274
Handling errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 274
Example: an Application.cfm page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 275

10 Contents
Optimizing ColdFusion applications. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 277
Caching ColdFusion pages that change infrequently. . . . . . . . . . . . . . . . . . . . 277
Caching parts of ColdFusion pages. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 278
Optimizing database use. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 281
Providing visual feedback to the user . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 284
CHAPTER 14: Handling Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 285
About error handling in ColdFusion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 286
Understanding errors. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 286
About error causes and recovery . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 286
ColdFusion error types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 287
About ColdFusion exceptions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 288
How ColdFusion handles errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 290
Error messages and the standard error format . . . . . . . . . . . . . . . . . . . . . . . . . . . 291
Determining error-handling strategies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 292
Handling missing template errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 292
Handling form field validation errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 292
Handling compiler exceptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 293
Handling runtime exceptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 293
Specifying custom error messages with cferror . . . . . . . . . . . . . . . . . . . . . . . . . . . 294
Specifying a custom error page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 294
Creating an error application page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 295
Logging errors with the cflog tag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 297
Handling runtime exceptions with ColdFusion tags . . . . . . . . . . . . . . . . . . . . . . 299
Exception-handling tags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 299
Using cftry and cfcatch tags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 299
Using cftry: an example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 303
Using the cfthrow tag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 307
Using the cfrethrow tag. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 309
Example: using nested tags, cfthrow, and cfrethrow . . . . . . . . . . . . . . . . . . . . 309
CHAPTER 15: Using Persistent Data and Locking . . . . . . . . . . . . . . . . . . . . . . . 315
About persistent scope variables. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 316
ColdFusion persistent variables and ColdFusion structures. . . . . . . . . . . . . . . 316
ColdFusion persistent variable issues. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 317
Managing the client state. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 318
About client and session variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 318
Maintaining client identity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 319
Configuring and using client variables. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 321
Enabling client variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 321
Using client variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 323
Configuring and using session variables. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 326
What is a session? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 326
Configuring and enabling session variables . . . . . . . . . . . . . . . . . . . . . . . . . . . 327
Storing session data in session variables. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 328
Standard session variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 328
Getting a list of session variables. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 329
Creating and deleting session variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 329

Contents 11
Accessing and changing session variables. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 330
Ending a session . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 330
Configuring and using application variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . 330
Configuring and enabling application variables . . . . . . . . . . . . . . . . . . . . . . . 331
Storing application data in application variables . . . . . . . . . . . . . . . . . . . . . . . 331
Using application variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 331
Using server variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 332
Locking code with cflock. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 333
Sample locking scenarios . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 334
Using the cflock tag with write-once variables. . . . . . . . . . . . . . . . . . . . . . . . . 335
Using the cflock tag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 335
Considering lock granularity. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 338
Nesting locks and avoiding deadlocks. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 338
Examples of cflock. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 340
CHAPTER 16: Securing Applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 345
ColdFusion security features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 346
About resource and sandbox security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 346
Resource control. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 347
Sandbox security. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 347
About user security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 348
Authenticating users . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 350
Using ColdFusion security tags and functions . . . . . . . . . . . . . . . . . . . . . . . . . . . 352
Using the cflogin tag. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 353
Getting the user ID and password . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 353
Logging a user in using Flash Remoting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 354
Logging users out . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 354
Security scenarios . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 355
A web server authentication security scenario . . . . . . . . . . . . . . . . . . . . . . . . . 355
An application authentication security scenario . . . . . . . . . . . . . . . . . . . . . . . 356
Implementing user security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 358
Web-server–based authentication user security example . . . . . . . . . . . . . . . . . 358
Application-based user security example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 360
Using an LDAP Directory for security information . . . . . . . . . . . . . . . . . . . . 366
CHAPTER 17: Developing Globalized Applications . . . . . . . . . . . . . . . . . . . . . . . 371
Introduction to globalization. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 372
Defining globalization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 372
Importance of globalization in ColdFusion applications . . . . . . . . . . . . . . . . . 373
How ColdFusion MX supports globalization . . . . . . . . . . . . . . . . . . . . . . . . . 373
Character sets, character encodings, and locales . . . . . . . . . . . . . . . . . . . . . . . 373
About character encodings. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 374
The Java Unicode character encoding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 375
Character encoding conversion issues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 375
Locales . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 376
Setting the locale . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 376
Using the locale . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 376

12 Contents
Processing a request in ColdFusion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 377
Determining the character encoding of a ColdFusion page. . . . . . . . . . . . . . . 378
Determining the page encoding of server output . . . . . . . . . . . . . . . . . . . . . . 379
Tags and functions for globalizing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 379
Tags and functions for controlling character encoding . . . . . . . . . . . . . . . . . . 380
Functions for controlling and using locales. . . . . . . . . . . . . . . . . . . . . . . . . . . 381
Additional globalization tags and functions . . . . . . . . . . . . . . . . . . . . . . . . . . 382
Handling data in ColdFusion MX. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 382
General character encoding issues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 383
Locale-specific content . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 383
Input data from URLs and HTML forms. . . . . . . . . . . . . . . . . . . . . . . . . . . . 383
File data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 385
Databases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 385
E-mail . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 386
HTTP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 386
LDAP. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 386
WDDX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 386
COM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 386
CORBA . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 386
Searching and indexing. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 387
CHAPTER 18: Debugging and Troubleshooting Applications . . . . . . . . . . . . . . . 389
Configuring debugging in the ColdFusion MX Administrator . . . . . . . . . . . . . . 390
Debugging Settings page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 390
Debugging IP addresses page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 392
Using debugging information from browser pages. . . . . . . . . . . . . . . . . . . . . . . . 392
General debugging information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 393
Execution Time . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 394
Database Activity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 396
Exceptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 397
Trace points . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 398
Scope variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 398
Using the dockable.cfm output format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 399
Controlling debugging information in CFML. . . . . . . . . . . . . . . . . . . . . . . . . . . 400
Generating debugging information for an individual query . . . . . . . . . . . . . . 400
Controlling debugging output with the cfsetting tag. . . . . . . . . . . . . . . . . . . . 400
Using the IsDebugMode function to run code selectively . . . . . . . . . . . . . . . . 400
Using the cftrace tag to trace execution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 401
About the cftrace tag. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 401
Using tracing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 403
Calling the cftrace tag. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 404
Using the Code Compatibility Analyzer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 405
Troubleshooting common problems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 406
CFML syntax errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 406
Data source access and queries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 407
HTTP/URL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 407

Contents 13
PART IV: Accessing and Using Data
CHAPTER 19: Introduction to Databases and SQL . . . . . . . . . . . . . . . . . . . . . . . 411
What is a database? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 412
Using multiple database tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 413
Database permissions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 414
Commits, rollbacks, and transactions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 414
Database design guidelines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 415
Using SQL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 415
SQL example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 415
Basic SQL syntax elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 416
Reading data from a database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 418
Modifying a database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 420
Writing queries using an editor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 422
Writing queries using Dreamweaver MX . . . . . . . . . . . . . . . . . . . . . . . . . . . . 422
Writing queries using Macromedia HomeSite+. . . . . . . . . . . . . . . . . . . . . . . . 424
CHAPTER 20: Accessing and Retrieving Data . . . . . . . . . . . . . . . . . . . . . . . . . . 427
Working with dynamic data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 428
Retrieving data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 428
The cfquery tag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 429
The cfquery tag syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 429
Building queries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 430
Outputting query data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 431
Query output notes and considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 433
Getting information about query results . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 433
Query variable notes and considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 434
Enhancing security with cfqueryparam . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 435
About query string parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 435
Using cfqueryparam . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 435
CHAPTER 21: Updating Your Database. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 437
About updating your dataSbase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 438
Inserting data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 438
Creating an HTML insert form . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 438
Data entry form notes and considerations. . . . . . . . . . . . . . . . . . . . . . . . . . . . 440
Creating an action page to insert data. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 440
Updating data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 442
Creating an update form. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 443
Creating an action page to update data. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 445
Deleting data. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 448
Deleting a single record . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 448
Deleting multiple records . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 450

14 Contents
CHAPTER 22: Using Query of Queries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 451
About record sets. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 452
Referencing queries as objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 452
Creating a record set . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 452
Creating a record set with a function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 453
About Query of Queries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 454
Benefits of Query of Queries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 454
Performing a Query of Queries. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 455
Query of Queries user guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 462
Using dot notation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 462
Using joins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 462
Using unions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 463
Using conditional operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 465
Using aggregate functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 468
Using group by and having expressions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 469
Using ORDER BY clauses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 469
Using aliases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 470
Handling null values. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 471
Escaping reserved keywords . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 471
Using Queries of Queries with numeric dates . . . . . . . . . . . . . . . . . . . . . . . . . 473
Understanding Query of Queries performance . . . . . . . . . . . . . . . . . . . . . . . . 473
BNF for Query of Queries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 474
CHAPTER 23: Managing LDAP Directories . . . . . . . . . . . . . . . . . . . . . . . . . . . . 477
About LDAP. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 478
The LDAP information structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 479
Entry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 480
Attribute. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 480
Distinguished name (DN) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 480
Schema. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 481
Using LDAP with ColdFusion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 482
Querying an LDAP directory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 483
Scope . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 483
Search filter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 483
Getting all the attributes of an entry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 485
Example: querying an LDAP directory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 485
Updating an LDAP directory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 488
Adding a directory entry. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 489
Deleting a directory entry. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 493
Updating a directory entry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 495
Adding and deleting attributes of a directory entry . . . . . . . . . . . . . . . . . . . . . 496
Changing a directory entry’s DN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 497
Advanced topics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 497
Specifying an attribute that includes a comma or semicolon . . . . . . . . . . . . . . 497
Using cfldap output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 498
Viewing a directory schema . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 498
Referrals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 502
Managing LDAP security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 503

Contents 15
CHAPTER 24: Building a Search Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 505
About Verity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 506
Using Verity with ColdFusion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 506
Advantages of using Verity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 507
Supported file types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 507
Support for international languages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 509
Creating a search tool for ColdFusion applications . . . . . . . . . . . . . . . . . . . . . . . 511
Creating a collection with the ColdFusion MX Administrator . . . . . . . . . . . . 512
About indexing a collection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 513
Indexing and building a search interface with the Verity Wizard. . . . . . . . . . . 514
Creating a ColdFusion search tool programmatically . . . . . . . . . . . . . . . . . . . 518
Using the cfsearch tag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 523
Working with record sets. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 526
Indexing database record sets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 526
Indexing cfldap query results . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 530
Indexing cfpop query results. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 531
Using database-directed indexing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 532
CHAPTER 25: Using Verity Search Expressions. . . . . . . . . . . . . . . . . . . . . . . . . 535
About Verity query types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 536
Using simple queries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 536
Stemming in simple queries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 537
Preventing stemming . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 538
Using explicit queries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 539
Using AND, OR, and NOT. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 539
Using wildcards and special characters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 540
Composing search expressions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 542
Case sensitivity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 542
Prefix and infix notation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 542
Commas in expressions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 542
Precedence rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 543
Delimiters in expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 543
Operators and modifiers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 543
Refining your searches with zones and fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . 552
PART V: Requesting and Presenting Information
CHAPTER 26: Retrieving and Formatting Data. . . . . . . . . . . . . . . . . . . . . . . . . . 559
Using forms to specify the data to retrieve . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 560
HTML form tag syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 560
Form controls. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 561
Form notes and considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 563
Working with action pages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 564
Processing form variables on action pages . . . . . . . . . . . . . . . . . . . . . . . . . . . . 564
Dynamically generating SQL statements . . . . . . . . . . . . . . . . . . . . . . . . . . . . 564
Creating action pages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 565
Testing for a variable's existence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 566

16 Contents
Requiring users to enter values in form fields . . . . . . . . . . . . . . . . . . . . . . . . . 566
Form variable notes and considerations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 567
Working with queries and data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 567
Using HTML tables to display query results. . . . . . . . . . . . . . . . . . . . . . . . . . 567
Formatting individual data items . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 569
Building flexible search interfaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 569
Returning results to the user . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 570
Handling no query results . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 571
Returning results incrementally . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 572
Dynamically populating list boxes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 574
Creating dynamic check boxes and multiple-selection
list boxes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 576
Check boxes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 576
Multiple selection lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 578
Validating form field data types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 579
CHAPTER 27: Building Dynamic Forms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 583
Creating forms with the cfform tag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 584
Using HTML and cfform . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 584
The cfform controls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 584
Preserving input data with preservedata . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 585
Browser considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 585
Building tree controls with cftree. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 586
Grouping output from a query . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 587
The cftree form variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 589
Input validation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 589
Structuring tree controls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 590
Image names in a cftree . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 591
Embedding URLs in a cftree. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 592
Specifying the tree item in the URL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 593
Building drop-down list boxes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 593
Building text input boxes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 594
Building slider bar controls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 595
Creating data grids with cfgrid . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 595
Working with a data grid and entering data . . . . . . . . . . . . . . . . . . . . . . . . . . 596
Creating an editable grid. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 599
Embedding Java applets. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 606
Registering a Java applet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 606
Using cfapplet to embed an applet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 608
Handling form variables from an applet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 609
Input validation with cfform controls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 609
Validating with regular expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 610
Input validation with JavaScript . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 613
Handling failed validation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 614
Example: validating an e-mail address. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 615

Contents 17
CHAPTER 28: Charting and Graphing Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . 617
Creating a chart. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 618
Chart types. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 618
Creating a basic chart . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 619
Administering charts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 620
Charting data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 621
Charting a query . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 621
Charting individual data points . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 624
Combining a query and data points . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 625
Charting multiple data collections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 625
Writing a chart to a variable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 627
Controlling chart appearance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 629
Common chart characteristics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 629
Setting x-axis and y-axis characteristics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 631
Creating a bar chart . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 631
Setting pie chart characteristics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 632
Creating an area chart. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 634
Setting curve chart characteristics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 636
Linking charts to URLs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 636
Dynamically linking from a pie chart . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 637
Linking to JavaScript from a pie chart . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 639
CHAPTER 29: Using the Flash Remoting Service . . . . . . . . . . . . . . . . . . . . . . . 641
About using the Flash Remoting service with ColdFusion. . . . . . . . . . . . . . . . . . 642
Planning your Flash application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 642
Using the Flash Remoting service with ColdFusion pages . . . . . . . . . . . . . . . . . . 643
Using Flash with ColdFusion components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 646
Using the Flash Remoting service with server-side ActionScript . . . . . . . . . . . . . 648
Using the Flash Remoting service with ColdFusion Java objects . . . . . . . . . . . . . 649
Handling errors with ColdFusion and Flash . . . . . . . . . . . . . . . . . . . . . . . . . . . . 650
CHAPTER 30: Using Server-Side ActionScript . . . . . . . . . . . . . . . . . . . . . . . . . 651
About server-side ActionScript . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 652
Client-side ActionScript requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 652
Server-side requirements. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 653
Software requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 653
Location of server-side ActionScript files . . . . . . . . . . . . . . . . . . . . . . . . . . . . 653
Benefits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 653
What to do next . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 654
Connecting to the Flash Remoting service. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 654
Using server-side ActionScript functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 655
Using the function results in ActionScript . . . . . . . . . . . . . . . . . . . . . . . . . . . 655
Global and request scope objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 656
About the Cf.query function and data sources. . . . . . . . . . . . . . . . . . . . . . . . . . . 657
Publishing dynamic data. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 657
About ColdFusion MX data sources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 657

18 Contents
Using the CF.query function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 658
About CF.query function syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 658
About the CF.query record set . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 659
Building a simple application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 660
Writing the server-side ActionScript function . . . . . . . . . . . . . . . . . . . . . . . . . 661
Creating the Flash movie interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 661
Submitting user data to the Flash Remoting service . . . . . . . . . . . . . . . . . . . . 662
Capturing Flash Remoting service results . . . . . . . . . . . . . . . . . . . . . . . . . . . . 662
Checking for a Flash Remoting service connection . . . . . . . . . . . . . . . . . . . . . 663
About the CF.http function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 663
Using the CF.http function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 664
Referencing HTTP Post parameters in the CF.http function . . . . . . . . . . . . . 665
Using the CF.http Post method. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 665
Using the CF.http Get method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 666
PART VI: Using Web Elements and External Objects
CHAPTER 31: Using XML and WDDX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 669
About XML and ColdFusion. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 670
The XML document object. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 671
A simple XML document . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 671
Basic view. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 671
DOM node view . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 672
XML document structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 673
ColdFusion XML tag and functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 676
Using an XML object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 677
Referencing the contents of an XML object . . . . . . . . . . . . . . . . . . . . . . . . . . 677
Assigning data to an XML object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 678
Creating and saving an XML document object . . . . . . . . . . . . . . . . . . . . . . . . . . 680
Creating a new XML document object using the cfxml tag. . . . . . . . . . . . . . . 680
Creating a new XML document object using the XmlNew function. . . . . . . . 680
Creating an XML document object from existing XML . . . . . . . . . . . . . . . . . 681
Saving and exporting an XML document object . . . . . . . . . . . . . . . . . . . . . . . 681
Modifying a ColdFusion XML object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 681
Functions for XML object management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 682
Treating elements with the same name as an array . . . . . . . . . . . . . . . . . . . . . 683
XML document object management reference . . . . . . . . . . . . . . . . . . . . . . . . 683
Adding, deleting, and modifying XML elements . . . . . . . . . . . . . . . . . . . . . . 685
Using XML and ColdFusion queries. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 690
Transforming documents with XSLT. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 691
Extracting data with XPath . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 692
Example: using XML in a ColdFusion application . . . . . . . . . . . . . . . . . . . . . . . 692
Moving complex data across the web with WDDX . . . . . . . . . . . . . . . . . . . . . . . 697
Uses of WDDX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 698
How WDDX works . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 699

Contents 19
Using WDDX. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 702
Using the cfwddx tag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 702
Validating WDDX data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 702
Using JavaScript objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 702
Converting CFML data to a JavaScript object . . . . . . . . . . . . . . . . . . . . . . . . 703
Transferring data from the browser to the server . . . . . . . . . . . . . . . . . . . . . . . 703
Storing complex data in a string . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 706
CHAPTER 32: Using Web Services. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 707
Web services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 708
Accessing a web service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 708
Basic web service concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 709
Working with WSDL files. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 710
Creating a WSDL file. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 710
Viewing a WSDL file using Dreamweaver MX. . . . . . . . . . . . . . . . . . . . . . . . 711
Reading a WSDL file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 711
Consuming web services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 713
About the examples in this section . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 713
Passing parameters to a web service. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 713
Handling return values from a web service . . . . . . . . . . . . . . . . . . . . . . . . . . . 714
Using cfinvoke to consume a web service . . . . . . . . . . . . . . . . . . . . . . . . . . . . 714
Using CFScript to consume a web service. . . . . . . . . . . . . . . . . . . . . . . . . . . . 716
Consuming web services that are not generated by ColdFusion MX. . . . . . . . 717
Calling web services from a Flash client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 717
Catching errors when consuming web services . . . . . . . . . . . . . . . . . . . . . . . . 717
Handling inout and out parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 718
Configuring web services in the ColdFusion MX Administrator. . . . . . . . . . . 718
Data conversions between ColdFusion and WSDL data types . . . . . . . . . . . . 719
Consuming ColdFusion web services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 719
Publishing web services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 721
Creating components for web services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 721
Specifying data types of function arguments and return values . . . . . . . . . . . . 721
Producing WSDL files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 722
Using ColdFusion components to define data types for web services . . . . . . . 724
Securing your web services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 726
Best practices for publishing web services . . . . . . . . . . . . . . . . . . . . . . . . . . . . 728
Handling complex data types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 728
Consuming web services that use complex data types . . . . . . . . . . . . . . . . . . . 728
Publishing web services that use complex data types . . . . . . . . . . . . . . . . . . . . 731
CHAPTER 33: Integrating J2EE and Java Elements in CFML Applications . . . 735
About ColdFusion, Java, and J2EE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 736
About ColdFusion and client-side JavaScript and applets . . . . . . . . . . . . . . . . 736
About ColdFusion and JSP. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 736
About ColdFusion and Servlets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 737
About ColdFusion and Java objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 737
About CFML variables and Java variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . 738

20 Contents
Using JSP tags and tag libraries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 739
Using a JSP tag in a ColdFusion page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 739
Example: using the random tag library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 740
Interoperating with JSP pages and servlets. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 740
Integrating JSP and servlets in a ColdFusion application . . . . . . . . . . . . . . . . 740
Examples: using JSP with CFML . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 742
Using Java objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 746
Using basic object techniques . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 746
Creating and using a simple Java class. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 748
Java and ColdFusion data type conversions. . . . . . . . . . . . . . . . . . . . . . . . . . . 751
Handling Java exceptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 753
Examples: using Java with CFML. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 754
CHAPTER 34: Integrating COM and CORBA Objects in CFML Applications . . 761
About COM and CORBA . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 762
About objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 762
About COM and DCOM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 762
About CORBA. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 762
Creating and using objects. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 763
Creating objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 763
Using properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 763
Calling methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 764
Calling nested objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 764
Getting started with COM and DCOM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 764
COM Requirements. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 765
Registering the object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 765
Finding the component ProgID and methods. . . . . . . . . . . . . . . . . . . . . . . . . 765
Creating and using COM objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 767
Connecting to COM objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 768
Setting properties and invoking methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . 768
General COM object considerations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 769
Accessing Complex COM Objects using Java proxies . . . . . . . . . . . . . . . . . . . 771
Using the Application Scope to improve COM performance . . . . . . . . . . . . . 774
Getting started with CORBA . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 777
Creating and using CORBA objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 777
Creating CORBA objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 777
Using CORBA objects in ColdFusion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 778
Handling exceptions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 783
CORBA example. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 784