Macromedia COLFUSION MX 7 User Manual

COLDFUSION®MX 7

ColdFusion MX Developer’s Guide

Trademarks

1 Step RoboPDF, ActiveEdit, ActiveTest, Authorware, Blue Sky Software, Blue Sky, Breeze, Breezo, Captivate, Central, ColdFusion, Contribute, Database Explorer, Director, Dreamweaver, Fireworks, Flash, FlashCast, FlashHelp, Flash Lite, FlashPaper, Flex, Flex Builder, Fontographer, FreeHand, Generator, HomeSite, JRun, MacRecorder, Macromedia, MXML, RoboEngine, RoboHelp, RoboInfo, RoboPDF, Roundtrip, Roundtrip HTML, Shockwave, SoundEdit, Studio MX, UltraDev, and WebHelp are either registered trademarks or trademarks of Macromedia, Inc. and may be registered in the United States or in other jurisdictions including internationally. Other product names, logos, designs, titles, words, or phrases mentioned within this publication may be trademarks, service marks, or trade names of Macromedia, Inc. or other entities and may be registered in certain jurisdictions including internationally.

This product includes code licensed from RSA Data Security.

Third-Party Information

This guide contains links to third-party websites that are not under the control of Macromedia, and Macromedia is not responsible for the content on any linked site. If you access a third-party website mentioned in this guide, then you do so at your own risk. Macromedia provides these links only as a convenience, and the inclusion of the link does not imply that Macromedia endorses or accepts any responsibility for the content on those third-party sites.

Copyright © 1999–2005 Macromedia, Inc. All rights reserved. U.S. Patents Pending. This manual may not be copied, photocopied, reproduced, translated, or converted to any electronic or machine-readable form in whole or in part without written approval from Macromedia, Inc. Notwithstanding the foregoing, the owner or authorized user of a valid copy of the software with which this manual was provided may print out one copy of this manual from an electronic version of this manual for the sole purpose of such owner or authorized user learning to use such software, provided that no part of this manual may be printed out, reproduced, distributed, resold, or transmitted for any other purposes, including, without limitation, commercial purposes, such as selling copies of this documentation or providing paid-for support services. Part Number ZCF70M500

Acknowledgments

Project Management: Randy Nielsen

Writing: Hal Lichtin, Randy Nielsen, Robert Berry, Chris Bedford, Anne Sandstrom

Editing: Linda Adler, Noreen Maher

Production Management: Patrice O’Neill

Media Design and Production: John Francis, Adam Barnett

Special thanks to Sawako Gensure, Seungmin Lee, Takashi Koto, Nozomi Kugita, Masayo Noda, Hiroshi Okugawa, Bowne Global Solutions

First Edition: January 2005 Macromedia, Inc.

600 Townsend St. San Francisco, CA 94103

INTRODUCTION: About ColdFusion MX Documentation . . . . . . . . . . . . . . . . . . 13

Using this manual . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

CHAPTER 1: Introducing ColdFusion MX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

About Internet applications and web application servers . . . . . . . . . . . . . . . . . . . . 19

About ColdFusion MX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22

About J2EE and the ColdFusion architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24

PART I: The CFML Programming Language

CHAPTER 2: Elements of CFML . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

CFML Basics. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28

Comments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28

Tags. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29

Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31

ColdFusion components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32

Constants . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32

Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33

Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34

Data types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35

Flow control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35

Character case . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39

Special characters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39

Reserved words . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39

CFScript . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40

CHAPTER 3: Using ColdFusion Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43

Creating variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44

Variable characteristics. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45

Data types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45

Strings. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47

Using periods in variable references . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56

Data type conversion. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59

About scopes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64

Ensuring variable existence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70

Validating data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73

Passing variables to custom tags and UDFs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73

CHAPTER 4: Using Expressions and Number Signs . . . . . . . . . . . . . . . . . . . . . . 75

Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75

Using number signs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81

Dynamic expressions and dynamic variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84

CHAPTER 5: Using Arrays and Structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97

About arrays . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97

Basic array techniques . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100

Populating arrays with data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105

Array functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108

About structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108

Creating and using structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111

Structure examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117

Structure functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121

CHAPTER 6: Extending ColdFusion Pages with CFML Scripting . . . . . . . . . . . 123

About CFScript. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123

The CFScript language . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125

Using CFScript statements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128

Handling exceptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136

CFScript example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137

CHAPTER 7: Using Regular Expressions in Functions . . . . . . . . . . . . . . . . . . . . 141

About regular expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141

Regular expression syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143

Using backreferences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150

Returning matched subexpressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153

Regular expression examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157

Types of regular expression technologies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158

PART II: Building Blocks of ColdFusion Applications

CHAPTER 8: Creating ColdFusion Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . 161

About CFML elements you create . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161

Including pages with the cfinclude tag. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162

About user-defined functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164

Using ColdFusion components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165

Using custom CFML tags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166

Using CFX tags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167

Selecting among ColdFusion code reuse methods . . . . . . . . . . . . . . . . . . . . . . . . 169

4 Contents

CHAPTER 9: Writing and Calling User-Defined Functions. . . . . . . . . . . . . . . . . 171

About user-defined functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171

Creating user-defined functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172

Calling user-defined functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178

Working with arguments and variables in functions . . . . . . . . . . . . . . . . . . . . . . 178

Handling errors in UDFs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186

A user-defined function example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192

Using UDFs effectively . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194

CHAPTER 10: Building and Using ColdFusion Components . . . . . . . . . . . . . . . 201

About ColdFusion components. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201

Creating ColdFusion components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204

Using ColdFusion components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 216

Passing parameters to methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 225

CFC variables and scope . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 227

Using CFCs effectively . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 230

ColdFusion component example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 239

CHAPTER 11: Creating and Using Custom CFML Tags . . . . . . . . . . . . . . . . . . . 241

Creating custom tags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 241

Passing data to custom tags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 245

Managing custom tags. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 249

Executing custom tags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 250

Nesting custom tags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 253

CHAPTER 12: Building Custom CFXAPI Tags . . . . . . . . . . . . . . . . . . . . . . . . . . 259

What are CFX tags?. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 259

Before you begin developing CFX tags in Java. . . . . . . . . . . . . . . . . . . . . . . . . . . 260

Writing a Java CFX tag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 261

ZipBrowser example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 264

Approaches to debugging Java CFX tags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 266

Developing CFX tags in C++ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 269

PART III: Developing CFML Applications

CHAPTER 13: Designing and Optimizing a ColdFusion Application . . . . . . . . . 275

About applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 275

Elements of a ColdFusion application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 276

Structuring an application. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 279

Defining the application and its event handlers in Application.cfc. . . . . . . . . . . . 282

Migrating from Application.cfm to Application.cfc. . . . . . . . . . . . . . . . . . . . . . . 294

Using an Application.cfm page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 295

Optimizing ColdFusion applications. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 298

Contents 5

CHAPTER 14: Handling Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 307

About error handling in ColdFusion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 307

Understanding errors. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 308

Error messages and the standard error format . . . . . . . . . . . . . . . . . . . . . . . . . . . 314

Determining error-handling strategies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 314

Specifying custom error messages with the cferror tag . . . . . . . . . . . . . . . . . . . . . 317

Logging errors with the cflog tag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 321

Handling runtime exceptions with ColdFusion tags . . . . . . . . . . . . . . . . . . . . . . 322

CHAPTER 15: Using Persistent Data and Locking . . . . . . . . . . . . . . . . . . . . . . . 339

About persistent scope variables. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 340

Managing the client state. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 342

Configuring and using client variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 346

Configuring and using session variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 352

Configuring and using application variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . 357

Using server variables. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 359

Locking code with cflock. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 360

Examples of cflock. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 368

CHAPTER 16: Securing Applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 373

ColdFusion security features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 374

About resource and sandbox security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 375

About user security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 376

Using ColdFusion security tags and functions . . . . . . . . . . . . . . . . . . . . . . . . . . . 381

Security scenarios . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 386

Implementing user security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 388

CHAPTER 17: Developing Globalized Applications . . . . . . . . . . . . . . . . . . . . . . 403

Introduction to globalization. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 403

About character encodings. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 406

Locales . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 408

Processing a request in ColdFusion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 410

Tags and functions for globalizing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 413

Handling data in ColdFusion MX. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 416

CHAPTER 18: Debugging and Troubleshooting Applications . . . . . . . . . . . . . . 423

Configuring debugging in the ColdFusion MX Administrator . . . . . . . . . . . . . . 423

Using debugging information from browser pages. . . . . . . . . . . . . . . . . . . . . . . . 426

Controlling debugging information in CFML . . . . . . . . . . . . . . . . . . . . . . . . . . . 434

Using the cftrace tag to trace execution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 436

Using the cftimer tag to time blocks of code . . . . . . . . . . . . . . . . . . . . . . . . . . . . 440

Using the Code Compatibility Analyzer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 442

Troubleshooting common problems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 443

6 Contents

PART IV: Accessing and Using Data

CHAPTER 19: Introduction to Databases and SQL . . . . . . . . . . . . . . . . . . . . . . 447

What is a database? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 447

Using SQL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 452

Writing queries using an editor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 460

CHAPTER 20: Accessing and Retrieving Data . . . . . . . . . . . . . . . . . . . . . . . . . 465

Working with dynamic data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 465

Retrieving data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 466

Outputting query data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 469

Getting information about query results . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 471

Enhancing security with cfqueryparam . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 472

CHAPTER 21: Updating Your Database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 475

About updating your database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 475

Inserting data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 475

Updating data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 480

Deleting data. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 487

CHAPTER 22: Using Query of Queries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 489

About record sets. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 489

About Query of Queries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 491

Query of Queries user guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 497

CHAPTER 23: Managing LDAP Directories. . . . . . . . . . . . . . . . . . . . . . . . . . . . 515

About LDAP. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 516

The LDAP information structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 517

Using LDAP with ColdFusion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 520

Querying an LDAP directory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 521

Updating an LDAP directory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 527

Advanced topics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 538

CHAPTER 24: Building a Search Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . 547

About Verity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 547

Creating a search tool for ColdFusion applications . . . . . . . . . . . . . . . . . . . . . . . 553

Creating a search page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 561

Enhancing search results . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 564

Working with data returned from a query . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 572

Contents 7

CHAPTER 25: Using Verity Search Expressions . . . . . . . . . . . . . . . . . . . . . . . . 581

About Verity query types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 581

Using simple queries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 582

Using explicit queries. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 583

Using natural queries. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 587

Using Internet queries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 587

Composing search expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 591

Refining your searches with zones and fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . 601

PART V: Requesting and Presenting Information

CHAPTER 26: Introduction to Retrieving and Formatting Data . . . . . . . . . . . . . 609

Using forms in ColdFusion MX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 609

Working with action pages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 613

Working with queries and data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 617

Returning results to the user . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 621

Dynamically populating list boxes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 625

Creating dynamic check boxes and multiple-selection list boxes . . . . . . . . . . . . . 627

CHAPTER 27: Building Dynamic Forms with cfform Tags . . . . . . . . . . . . . . . . . 631

Creating custom forms with the cfform tag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 631

Building tree controls with the cftree tag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 634

Building drop-down list boxes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 642

Building slider bar controls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 643

Creating data grids with the cfgrid tag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 644

Embedding Java applets. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 655

CHAPTER 28: Validating Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 659

About ColdFusion MX validation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 659

Validating form fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 667

Handling invalid data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 669

Masking form input values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 670

Validating form data with regular expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . 671

Validating form data using hidden fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 675

Validating form input and handling errors with JavaScript . . . . . . . . . . . . . . . . . 680

Validating data with the IsValid function and the cfparam tag. . . . . . . . . . . . . . . 683

CHAPTER 29: Creating Forms in Macromedia Flash. . . . . . . . . . . . . . . . . . . . . 687

About Flash forms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 687

Building Flash forms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 689

Binding data in Flash forms. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 699

Setting styles and skins in Flash forms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 700

Using ActionScript in Flash forms. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 704

Best practices for Flash forms. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 707

8 Contents

CHAPTER 30: Creating Skinnable XML Forms . . . . . . . . . . . . . . . . . . . . . . . . . 709

About XML skinnable forms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 709

Building XML skinnable forms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 712

ColdFusion XML format. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 715

Creating XSLT skins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 728

CHAPTER 31: Creating Charts and Graphs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 733

About charts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 733

Creating a basic chart . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 734

Charting data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 735

Controlling chart appearance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 743

Creating charts: examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 751

Administering charts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 756

Writing a chart to a variable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 756

Linking charts to URLs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 758

CHAPTER 32: Creating Reports for Printing . . . . . . . . . . . . . . . . . . . . . . . . . . . 763

About printable output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 763

Creating PDF and FlashPaper output with the cfdocument tag. . . . . . . . . . . . . . 764

Creating reports with the ColdFusion MX 7 reporting . . . . . . . . . . . . . . . . . . . . 770

Font management with printable reports. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 804

Creating reports with Crystal Reports (Windows only) . . . . . . . . . . . . . . . . . . . . 805

CHAPTER 33: Using the Flash Remoting Service . . . . . . . . . . . . . . . . . . . . . . . 807

About using the Flash Remoting service with ColdFusion . . . . . . . . . . . . . . . . . . 807

Configuring the Flash Remoting Gateway. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 809

Using the Flash Remoting service with ColdFusion pages . . . . . . . . . . . . . . . . . . 812

Using Flash with CFCs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 817

Using the Flash Remoting service with ColdFusion Java objects . . . . . . . . . . . . . 819

Handling errors with ColdFusion and Flash . . . . . . . . . . . . . . . . . . . . . . . . . . . . 820

CHAPTER 34: Using Server-Side ActionScript . . . . . . . . . . . . . . . . . . . . . . . . . 823

About server-side ActionScript . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 823

Connecting to the Flash Remoting service. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 826

Using server-side ActionScript functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 827

Global and request scope objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 829

About the CF.query function and data sources . . . . . . . . . . . . . . . . . . . . . . . . . . 829

Using the CF.query function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 831

Building a simple application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 833

About the CF.http function. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 836

Using the CF.http function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 837

Contents 9

PART VI: Using Web Elements and External Objects

CHAPTER 35: Using XML and WDDX. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 843

About XML and ColdFusion. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 843

The XML document object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 844

ColdFusion XML tag and functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 850

Using an XML object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 852

Creating and saving an XML document object . . . . . . . . . . . . . . . . . . . . . . . . . . 856

Modifying a ColdFusion XML object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 858

Validating XML documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 868

Transforming documents with XSLT. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 869

Extracting data with XPath . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 869

Example: using XML in a ColdFusion application . . . . . . . . . . . . . . . . . . . . . . . 870

Moving complex data across the web with WDDX . . . . . . . . . . . . . . . . . . . . . . . 875

Using WDDX. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 879

CHAPTER 36: Using Web Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 885

Web services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 885

Working with WSDL files. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 888

Consuming web services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 891

Publishing web services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 898

Using request and response headers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 907

Handling complex data types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 909

Troubleshooting SOAP requests and responses . . . . . . . . . . . . . . . . . . . . . . . . . . 914

CHAPTER 37: Integrating J2EE and Java Elements in

CFML Applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 917

About ColdFusion, Java, and J2EE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 917

Using JSP tags and tag libraries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 921

Interoperating with JSP pages and servlets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 922

Using Java objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 928

CHAPTER 38: Integrating COM and CORBA Objects in

CFML Applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 945

About COM and CORBA . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 945

Creating and using objects. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 947

Getting started with COM and DCOM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 948

Creating and using COM objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 951

Getting started with CORBA . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 961

Creating and using CORBA objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 961

CORBA example. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 969

10 Contents

PART VII: Using External Resources

CHAPTER 39: Sending and Receiving E-Mail . . . . . . . . . . . . . . . . . . . . . . . . . . 973

Using ColdFusion with mail servers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 973

Sending e-mail messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 974

Sample uses of the cfmail tag. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 977

Using the cfmailparam tag. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 981

Receiving e-mail messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 983

Handling POP mail . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 985

CHAPTER 40: Interacting with Remote Servers . . . . . . . . . . . . . . . . . . . . . . . . 991

About interacting with remote servers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 991

Using cfhttp to interact with the web . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 992

Creating a query object from a text file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 994

Using the cfhttp Post method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 996

Performing file operations with cfftp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 999

CHAPTER 41: Managing Files on the Server . . . . . . . . . . . . . . . . . . . . . . . . . . 1003

About file management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1003

Using cffile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1003

Using cfdirectory. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1012

Using cfcontent. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1014

CHAPTER 42: Using Event Gateways . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1019

About event gateways . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1020

Event gateway facilities and tools. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1024

Structure of an event gateway application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1027

Configuring an event gateway instance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1028

Developing an event gateway application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1029

Deploying event gateways and applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1037

Using the CFML event gateway for asynchronous CFCs. . . . . . . . . . . . . . . . . . 1038

Using the example event gateways and gateway applications . . . . . . . . . . . . . . . 1040

CHAPTER 43: Using the Instant Messaging Event Gateways . . . . . . . . . . . . . 1047

About ColdFusion and instant messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1047

Configuring an IM event gateway . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1050

Handling incoming messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1052

Sending outgoing messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1053

Sample IM message handling application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1054

Using the GatewayHelper object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1058

Contents 11

CHAPTER 44: Using the SMS Event Gateway . . . . . . . . . . . . . . . . . . . . . . . . 1065

About SMS and ColdFusion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1065

Configuring an SMS event gateway. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1071

Handling incoming messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1073

Sending outgoing messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1075

ColdFusion MX SMS development tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1080

Sample SMS application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1082

CHAPTER 45: Creating Custom Event Gateways . . . . . . . . . . . . . . . . . . . . . . 1085

Event gateway architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1085

Event gateway elements. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1086

Building an event gateway . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1092

Deploying an event gateway . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1100

INDEX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1103

12 Contents

INTRODUCTION

About ColdFusion MX Documentation

ColdFusion MX Developer’s Guide provides the tools needed to develop Internet applications using Macromedia ColdFusion MX. This manual is intended for web application programmers who are learning ColdFusion MX or wish to extended their ColdFusion MX programming knowledge. It provides a solid grounding in the tools that ColdFusion MX provides to develop web applications.

Because of the power and flexibility of ColdFusion MX, you can create many different types of web applications of varying complexity. As you become more familiar with the material presented in this manual, and begin to develop your own applications, you will want to refer to CFML Reference for details about various tags and functions.

Using this manual . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

Accessing the ColdFusion MX documentation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18

Using this manual

This manual can to help anyone with a basic understanding of HTML learn to develop ColdFusion MX applications. However, this manual is most useful if you have basic ColdFusion experience, or have read Getting Started Building ColdFusion MX Applications. The Getting Started Building ColdFusion MX Applications manual provides an introduction to ColdFusion and helps you develop the basic knowledge that will make using this manual easier.

Approaches to using this manual

This section describes approaches to using this manual for beginning ColdFusion developers, developers with some experience who want to develop expertise, and advanced developers who want to learn about the new and enhanced features of ColdFusion MX.

Beginning with ColdFusion

If you are learning ColdFusion, it might be most effective to read this manual in the following order:

Chapter 1, “Introducing ColdFusion MX” through Chapter 4, “Using Expressions and Number Signs” to learn the basics of CFML.

Chapter 19, “Introduction to Databases and SQL” through Chapter 21, “Updating Your Database” to learn about using databases.

Chapter 26, “Introduction to Retrieving and Formatting Data” and Chapter 27, “Building Dynamic Forms with cfform Tags” to learn about requesting data from users.

After you read these chapters, you should have a basic understanding of the basic elements of ColdFusion, and be able to create simple ColdFusion applications. To learn to produce more complete and robust applications, you could proceed with the following chapters:

Chapter 13, “Designing and Optimizing a ColdFusion Application” through Chapter 18, “Debugging and Troubleshooting Applications” to learn how to build a complete ColdFusion

application.

Chapter 22, “Using Query of Queries” to learn how to use queries effectively.

Chapter 5, “Using Arrays and Structures” through Chapter 10, “Building and Using ColdFusion Components” to learn to use more advanced features of CFML, including ways to

reuse code.

You can then read the remaining chapters as you add new features to your ColdFusion application.

Developing an in-depth knowledge of ColdFusion

If you have a basic understanding of ColdFusion as presented in Getting Started Building ColdFusion MX Applications or the Fast Track to ColdFusion course, you might want to start at

Chapter 1 and work through to the end of the book, skipping any specialized chapters that you are unlikely to need.

Learning about new and modified ColdFusion features

If you are an advanced ColdFusion developer, you might want to learn about new or changed ColdFusion features. The following chapters document features that are new or substantially enhanced in ColdFusion MX 7:

• Chapter 24, “Building a Search Interface”

• Chapter 25, “Using Verity Search Expressions”

• Chapter 27, “Building Dynamic Forms with cfform Tags”

• Chapter 28, “Validating Data”

• Chapter 29, “Creating Forms in Macromedia Flash”

• Chapter 30, “Creating Skinnable XML Forms”

• Chapter 32, “Creating Reports for Printing”

14 Introduction: About ColdFusion MX Documentation

• Chapter 42, “Using Event Gateways”

• Chapter 43, “Using the Instant Messaging Event Gateways”

• Chapter 44, “Using the SMS Event Gateway”

• Chapter 45, “Creating Custom Event Gateways”

Nearly all chapters contain information that is new in ColdFusion MX 7, so you should also review all other chapters for useful information. The index and the table of contents are useful tools for finding new features or changed documentation.

Note: If you are moving from ColdFusion 4.5 or 5, start by reading Migrating ColdFusion 5 Applications, available on the Macromedia website.

ColdFusion features described in this manual

ColdFusion provides a comprehensive set of features for developing and managing Internet applications. These features enhance speed and ease-of-development, and let you dynamically deploy your applications, integrate new and legacy technologies, and build secure applications.

The following table describes the primary ColdFusion features that are discussed in this manual, and lists the chapters that describe them. This table is only a summary of major CFML features; this manual also includes information about other features. Also, this table does not include features that are described in other manuals.

Feature Description Chapters

CFML CFML is a fully featured tag-oriented Internet application language.

It includes a wide range of tags, functions, variables, and expressions.

CFScript CFScript is a server-side scripting language that provides a subset

of ColdFusion functionality in script syntax.

Regular expressions

Reusable elements

User-defined functions (UDFs)

ColdFusion components

Custom CFML tags

ColdFusion extension (CFX) tags

ColdFusion provides several functions that use regular expressions for string manipulation. It also lets you use regular expressions in text input tags.

ColdFusion lets you create several types of elements, such as userdefined functions and ColdFusion components, that you write once and can use many times.

You can use CFScript or the functions. These functions can incorporate all of the built-in ColdFusion tags and functions, plus other extensions.

ColdFusion components encapsulate multiple functions and related data in a single logical unit. ColdFusion components can have many uses, and are particularly useful in creating web services and Flash interfaces for your application.

You can create custom ColdFusion tags using CFML. These tags can have bodies and can call other custom tags.

You can create custom tags in Java or C++. These tags can use features that are only available when using programming languages. However, CFX tags cannot have tag bodies.

cffunction tag to create your own

2–5

7, 28

8–12

Using this manual 15

Feature Description Chapters

ColdFusion application structure

ColdFusion supports many ways of building an application, and includes specific features, such as the Application.cfc file or Application.cfm page, built-in security features, and shared scopes,

13–17

that help you optimize your application structure.

Error handling mechanisms

Shared and persistent variable scopes

Code locking You lock sections of code that access in-memory shared scopes or

ColdFusion provides several mechanisms for handling data, including custom error pages and exception-handling tags and functions, such as

cftry and cfcatch.

Using shared and persistent scopes, you can make data available to a single user over one or many browser sessions, or to multiple users of an application or server.

15 use external resources that are not safe for multiple simultaneous access.

Application security

ColdFusion provides mechanisms, including the

cflogin tag, for

authenticating users and authorizing them to access specific

sections of your application. You can also use resource security, which secures access to ColdFusion resources based on the ColdFusion page location.

Application globalization

ColdFusion supports global applications that use different character sets and locales, and provides tags and functions

designed to support globalizing your applications.

Debugging tools Using debugging output, the

cftrace tag, logging features, and the

18 Code Analyzer, you can locate and fix coding errors.

Database access and management

ColdFusion can access SQL databases to retrieve, add, and modify data. This feature is one of the core functions of many dynamic

19–21

applications.

Queries of Queries You can use a subset of standard SQL within ColdFusion to

22 manipulate any data that is represented as a record set, including database query results, LDAP (Lightweight Directory Access Protocol) directory information, and other data.

LDAP directory access and management

Indexing and searching data

ColdFusion applications can access and manipulate data in LDAP directory services. These directories are often used for security validation data and other directory-like information.

ColdFusion applications can provide full-text search capabilities for documents and data sources using the Verity search engine.

Dynamic forms With ColdFusion, you can use HTML and forms to control the data

displayed by a dynamic web page. You can also use the

cfform tag

24–25

26–30

to enrich your forms with sophisticated graphical controls, and perform input data validation.

Validating data ColdFusion provides several ways to validate data in forms and in

28 CFML variables.

Flash forms ColdFusion can display forms using Macromedia Flash, which

29 presents a pleasing appearance and includes features such as accordion and tab navigators.

16 Introduction: About ColdFusion MX Documentation

Feature Description Chapters

XML skinnable forms

Data graphing You can use the

Reports and printable output

ColdFusion can convert your CFML forms into XML and format the XML using XSLT skins and style sheets.

cfchart tag to display your data graphically. 31

You can create output that is formatted for print as PDF or FlashPaper documents. You can also use ColdFusion reporting to

create banded reports for display or printing.

Macromedia Flash integration

Server-side ActionScript

You can use native Flash connectivity built into ColdFusion to help build dynamic Flash user interfaces for ColdFusion applications.

Macromedia Flash Remoting lets Macromedia Flash MX developers create server-side ActionScript. ActionScript files can

directly access ColdFusion query and HTTP features through two

XML document processing and creation

functions:

ColdFusion applications can create, use, and manipulate XML (Extensible Markup Language) documents. ColdFusion also provides tools to use WDDX (Web Distributed Data Exchange), an

CF.query and CF.http.

XML dialect for transmitting structured data.

Web services ColdFusion applications can use available SOAP (Simple Object

36 Access Protocol)-based web services, including Microsoft .NET services. ColdFusion applications can also use ColdFusion components to provide web services to other applications over the Internet.

Java and J2EE integration

You can integrate J2EE elements, including JSP (JavaServer Pages) pages, JSP tag libraries, and Java objects, including EJBs

(Enterprise JavaBeans), into your ColdFusion application.

COM and CORBA objects

The

cfobject tag lets you use COM (Component Object Model) or

DCOM (Distributed Component Object Model) and CORBA

(Common Object Request Broker) objects in your ColdFusion applications.

E-mail messages You can add interactive e-mail features to your ColdFusion

applications using the

HTTP and FTP The

cfhttp and cfftp tags provide simple methods of using HTTP

cfmail and cfpop tags.

40 (Hypertext Transfer Protocol) and FTP (File Transfer Protocol) communications in your application.

File and directory access

Event gateways ColdFusion event gateways let ColdFusion applications

You can use the

cffile, cfdirectory, and cfcontent tags to read,

write, and manage files and directories on the server.

42–45 asynchronously react to or generate external events or messages.

Instant messaging event gateways

Your ColdFusion application can communicate with XMPP (Jabber) or IBM Sametime instant messaging clients using the

ColdFusion IM gateways.

Using this manual 17

Feature Description Chapters

SMS event gateway

Creating gateways You can write your own event gateways in Java and integrate them

Your ColdFusion MX application can communicate with short message service (SMS) devices, such as mobile phones, using the ColdFusion SMS event gateway.

into ColdFusion MX.

Accessing the ColdFusion MX documentation

The ColdFusion MX documentation is designed to provide support for the complete spectrum of participants.

Documentation set

The ColdFusion MX 7 documentation set includes the following titles:

Book Description

Installing and Using ColdFusion MX

Configuring and Administering ColdFusion MX

ColdFusion MX Developer’s Guide

Getting Started Building ColdFusion MX Applications

CFML Reference Provides descriptions, syntax, usage, and code examples for all ColdFusion

CFML Quick Reference Provides a brief guide that shows the syntax of ColdFusion tags, functions,

Describes system installation and basic configuration for Windows, Solaris, and Linux. To see this manual, go to www.macromedia.com/go/

livedocs_cfmx7docs_installing.

Part I describes how to manage the ColdFusion environment, including connecting to your data sources and configuring security for your applications. Part II describes Verity search tools and utilities that you can use for configuring the Verity Search Server engine, as well as creating, managing, and troubleshooting Verity collections. To see this manual, go to

www.macromedia.com/go/livedocs_cfmx7docs_configadmin.

Describes how to develop your dynamic web applications, including retrieving and updating your data, using structures, and forms. This manual includes two volumes. To see this manual, go to www.macromedia.com/go/

livedocs_cfmx7docs_dev.

Contains an overview of ColdFusion features and application development procedures. Includes a tutorial that guides you through the process of developing an example ColdFusion application. To see this manual, go to

www.macromedia.com/go/livedocs_cfmx7docs_gs.

tags, functions, and variables. This manual includes two volumes. To see this manual, go to www.macromedia.com/go/

livedocs_cfmx7docs__cfml_reference.

and variables.

Viewing online documentation

All ColdFusion MX documentation is available online in HTML and Adobe Acrobat Portable Document Format (PDF) files. Go to the documentation home page for ColdFusion MX on the Macromedia website: www.macromedia.com.

18 Introduction: About ColdFusion MX Documentation

CHAPTER 1

Introducing ColdFusion MX

This chapter describes Macromedia ColdFusion MX and the role it plays in developing dynamic Internet applications. This chapter also introduces the topics discussed in this manual.

About Internet applications and web application servers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

About ColdFusion MX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22

About J2EE and the ColdFusion architecture. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24

About Internet applications and web application servers

With ColdFusion MX, you develop Internet applications that run on web application servers. The following sections introduce Internet applications and web application servers. Later sections explain the specific role that ColdFusion MX plays in this environment.

About web pages and Internet applications

The Internet has evolved from a collection of static HTML pages to an application deployment platform. First, the Internet changed from consisting of static web pages to providing dynamic, interactive content. Rather than providing unchanging content where organizations merely advertise goods and services, dynamic pages enable companies to conduct business ranging from e-commerce to managing internal business processes. For example, a static HTML page lets a bookstore publish its location, list services such as the ability to place special orders, and advertise upcoming events like book signings. A dynamic website for the same bookstore lets customers order books online, write reviews of books they read, and even get suggestions for purchasing books based on their reading preferences.

More recently, the Internet has become the underlying infrastructure for a wide variety of applications. With the arrival of technologies such as XML, web services, J2EE (Java 2 Platform, Enterprise Edition), and Microsoft .NET, the Internet has become a multifaceted tool for integrating business activities. Now, enterprises can use the Internet to integrate distributed activities, such as customer service, order entry, order fulfillment, and billing.

ColdFusion MX is a rapid application development environment that lets you build dynamic websites and Internet applications quickly and easily. It lets you develop sophisticated websites and Internet applications without knowing the details of many complex technologies, yet it lets advanced developers take advantage of the full capabilities of many of the latest Internet technologies.

About web application servers

To understand ColdFusion, you must first understand the role of web application servers. Typically, web browsers make requests, and web servers, such as Microsoft Internet Information Server (IIS) and the Apache web server, fulfill those requests by returning the requested information to the browser. This information includes, but is not limited to, HTML and Macromedia Flash files.

A web server’s capabilities are limited because all it does is wait for requests to arrive and attempt to fulfill those requests as soon as possible. A web server does not let you do the following tasks:

• Interact with a database, other resource, or other application.

• Serve customized information based on user preferences or requests.

• Validate user input.

A web server, basically, locates information and returns it to a web browser.

To extend the capabilities of a web server, you use a web application server, a software program that extends the web server’s capabilities to do tasks such as those in the preceding list.

20 Chapter 1: Introducing ColdFusion MX

How a web server and web application server work together

The following steps explain how a web server and web application server work together to process a page request:

The user requests a page by typing a URL in a browser, and the web server receives the request.

The web server looks at the file extension to determine whether a web application server must process the page. Then, one of the following actions occur:

■ If the user requests a file that is a simple web page (often one with an HTM or HTML

extension), the web server fulfills the request and sends the file to the browser.

■ If the user requests a file that is a page that a web application server must process (one with

a CFM, CFML, or CFC extension for ColdFusion requests), the web server passes the request to the web application server. The web application server processes the page and sends the results to the web server, which returns those results to the browser. The following figure shows this process:

Web browser

requests

a web page.

Web server receives the

page request.

Web server instructs

application server

to process the page.

The application server

processes the page

and generates output.

The web server

sends the output

to the browser.

Because web application servers interpret programming instructions and generate output that a web browser can interpret, they let web developers build highly interactive and data-rich websites, which can do tasks such as the following:

• Query other database applications for data.

• Dynamically populate form elements.

• Dynamically generate Flash application data.

• Provide application security.

• Integrate with other systems using standard protocols such as HTTP, FTP, LDAP, POP,

and SMTP.

• Create shopping carts and e-commerce websites.

• Respond with an e-mail message immediately after a user submits a form.

• Return the results of keyword searches.

About Internet applications and web application servers 21

About ColdFusion MX

ColdFusion MX is a rapid scripting environment server for creating dynamic Internet Applications. ColdFusion Markup Language (CFML) is an easy-to-learn tag-based scripting language, with connectivity to enterprise data and powerful built-in search and charting capabilities. ColdFusion MX enables developers to easily build and deploy dynamic websites, content publishing systems, self-service applications, commerce sites, and more.

ColdFusion MX consists of the following core components:

• ColdFusion scripting environment

• CFML

• ColdFusion MX Administrator

• Verity Search Server

The following sections describe these core components in more detail.

The ColdFusion scripting environment

The ColdFusion scripting environment provides an efficient development model for Internet applications. At the heart of the ColdFusion scripting environment is the ColdFusion Markup Language (CFML), a tag-based programming language that encapsulates many of the low-level details of web programming in high-level tags and functions.

ColdFusion Markup Language

ColdFusion Markup Language (CFML) is a tag-based language, similar to HTML, that uses special tags and functions. With CFML, you can enhance standard HTML files with database commands, conditional operators, high-level formatting functions, and other elements to rapidly produce easy-to-maintain web applications. However, CFML is not limited to enhancing HTML. For example, you can create Macromedia Flash MX applications that consist entirely of Flash elements and CFML. Similarly, you can use CFML to create web services for use by other applications.

The following sections briefly describe basic CFML elements. For more information, see

Chapter 2, “Elements of CFML,” on page 27.

CFML tags

CFML looks similar to HTML—it includes starting and, in most cases, ending tags, and each tag is enclosed in angle brackets. All ending tags are preceded with a forward slash (/) and all tag names are preceded with

tag body text and CFML

</cftagname>

cf; for example:

CFML increases productivity by providing a layer of abstraction that hides many low-level details involved with Internet application programming. At the same time, CFML is extremely powerful and flexible. ColdFusion lets you easily build applications that integrate files, databases, legacy systems, mail servers, FTP servers, objects, and components.

22 Chapter 1: Introducing ColdFusion MX

CFML includes approximately 110 tags. ColdFusion tags serve many functions. They provide programming constructs, such as conditional processing and loop structures. They also provide services, such as charting and graphing, full-text search, access to protocols such as FTP, SMTP/ POP, and HTTP, and much more. The following table lists a few examples of commonly used ColdFusion tags:

Tag Purpose

cfquery

cfoutput

cfset

cfmail

cfchart

cfobject

Establishes a connection to a database (if one does not exist), executes a query, and returns results to the ColdFusion environment.

Displays output that can contain the results of processing ColdFusion functions, variables, and expressions.

Sets the value of a ColdFusion variable.

Lets an application send SMTP mail messages using application variables, query results, or server files. (Another tag,

Converts application data or query results into graphs, such as bar charts or pie charts, in Flash, JPG, or PNG format.

Invokes objects written in other programming languages, including COM (Component Object Model) components, Java objects such as Enterprise JavaBeans, or Common CORBA (Object Request Broker Architecture) objects.

cfpop, gets mail.)

CFML Reference describes the CFML tags in detail.

CFML functions and CFScript

CFML includes approximately 280 built-in functions. These functions perform a variety of roles, including string manipulation, data management, and system functions. CFML also includes a built-in scripting language, CFScript, that lets you write code in a manner that is familiar to programmers and JavaScript writers.

CFML extensions

You can extend CFML further by creating custom tags or user-defined functions (UDFs), or by integrating COM, C++, and Java components (such as JSP tag libraries). You can also create ColdFusion components (CFCs), which encapsulate related functions and properties and provide a consistent interface for accessing them.

All these features let you easily create reusable functionality that is customized to the types of applications or websites that you are building.

CFML development tools

Macromedia Dreamweaver MX 2004 helps you develop ColdFusion applications efficiently. It includes many features that simplify and enhance ColdFusion development, including tools for debugging CFML. Because CFML is written in an HTML-like text format, and you often use HTML in ColdFusion pages, you can also use an HTML editor or a text editor, such as Notepad, to write ColdFusion applications.

About ColdFusion MX 23

Verity Search Server

The Verity Search Server (also called the Verity search engine) provides full text search capability for documents and data on a ColdFusion MX site.

ColdFusion MX Administrator

ColdFusion MX Administrator configures and manages the ColdFusion application server. It is a secure web-based application that you can access using any web browser, from any computer with an Internet connection.

For more information about ColdFusion MX Administrator, see Configuring and Administering ColdFusion MX.

About J2EE and the ColdFusion architecture

As the Internet software market has matured, the infrastructure services required by distributed Internet applications, including ColdFusion applications, have become increasingly standardized. The most widely adopted standard today is the Java 2 Platform, Enterprise Edition (J2EE) specification. J2EE provides a common set of infrastructure services for accessing databases, protocols, and operating system functionality, across multiple operating systems.

About ColdFusion MX and the J2EE platform

ColdFusion MX is implemented on the Java technology platform and uses a J2EE application server for many of its base services, including database connectivity, naming and directory services, and other runtime services. ColdFusion MX can be configured to use an embedded J2EE server (in the server configuration) or it can be deployed as a J2EE application on an independent J2EE application server (in the multiserver configuration or the J2EE configuration). ColdFusion MX Enterprise includes a fully featured version of the Macromedia JRun J2EE application server, or can be deployed on third-party J2EE servers such as IBM WebSphere and BEA WebLogic.

For more information on ColdFusion MX configurations, see Installing and Using ColdFusion MX.

By implementing the ColdFusion scripting environment on top of the J2EE platform, ColdFusion MX takes advantage of the power of the J2EE platform while also providing an easyto-use scripting environment and built-in services. Moreover, because ColdFusion is built on a J2EE platform, you can easily integrate J2EE and Java functionality into your ColdFusion application. As a result, ColdFusion pages can do any of the following:

• Share session data with JSPs (Java Server Pages) and Java servlets.

• Import custom JSP tag libraries and use them like ColdFusion custom tags.

• Integrate with Java objects, including the J2EE Java API, JavaBeans, and Enterprise JavaBeans.

For more information on using J2EE features in ColdFusion, see Chapter 37, “Integrating J2EE

and Java Elements in CFML Applications,” on page 917.

24 Chapter 1: Introducing ColdFusion MX

PART I

The CFML Programming Language

This part describes the elements of the CFML programming language. It tells you how to use CFML tags, functions, variables and expressions, the CFScript scripting language, and regular expressions.

The following chapters are included:

Chapter 2: Elements of CFML. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

Chapter 3: Using ColdFusion Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43

Chapter 4: Using Expressions and Number Signs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75

Chapter 5: Using Arrays and Structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97

Chapter 6: Extending ColdFusion Pages with CFML Scripting . . . . . . . . . . . . . . . . . . . . . . . 123

Chapter 7: Using Regular Expressions in Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141

PART I

CHAPTER 2

Elements of CFML

This chapter provides an overview of the basic elements of CFML, including tags, functions, constants, variables, expressions, and CFScript. The chapters in Part I of this manual describe these topics in detail.

CFML Basics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28

Comments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28

Tags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29

Functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31

ColdFusion components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32

Constants. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32

Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33

Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34

Data types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35

Flow control. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35

Character case . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39

Special characters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39

Reserved words . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39

CFScript . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40

CFML Basics

This chapter introduces and describes the basic elements of CFML. These elements make CFML a powerful tool for developing interactive web applications. Because CFML is a dynamic application development tool, it has many of the features of a programming language, including the following:

• Functions

• Expressions

• Variables and constants

• Flow-control constructs such as if-then and loops

CFML also has a “language within a language,” CFScript, which enables you to use a syntax similar to JavaScript for many operations.

This chapter introduces these elements and other basic CFML entities such as comments, data types, escape characters, and reserved words.

The remainder of Part I of this manual provides more detailed information on many of the basic CFML elements. The rest of this manual helps you use these elements effectively in your applications.

Comments

ColdFusion comments have a similar format to HTML comments. However, they use three dash characters instead of two; for example:

The ColdFusion server removes all ColdFusion comments from the page before returning it to the web server. As a result, the page that a user browser receives does not include the comment, and users cannot see it even if they view the page source.

You can embed CFML comments in begin tags (not just tag bodies), functions calls, and variable text in number signs. ColdFusion ignores the text in comments such as the following:

<cfset MyVar = var1 > <cfoutput>#Dateformat(now() )#</cfoutput>

This technique can be useful if you want to temporarily comment out parts of expressions or optional attributes or arguments.

You can also nest comments, as the following example shows:

<cfset errormessage1="Oops!"> <cfoutput> #errormessage1# </cfoutput>

--->

This is useful if you want to temporarily disable a section of code while you test your application.

You can embed comments within comments, however, you should use this technique carefully.

28 Chapter 2: Elements of CFML

Note: You cannot embed comments inside a tag name or function name, such as

<cf_MyCustomTag>. You also cannot embed comments inside strings, as in the

following example:

IsDefined("MyVariable").

Functions

Functions typically manipulate data and return a result. CFML includes over 280 built-in functions. You can also create user-defined functions (UDFs), sometimes referred to as custom functions.

Functions have the following general form:

functionName([argument1[, argument2]]...)

Some functions, such as the Now function take no arguments. Other functions require one or more comma-separated arguments and can have additional optional arguments. All ColdFusion functions return a value. For example,

Built-in functions

ColdFusion built-in functions perform a variety of tasks, including, but not limited to, the following:

Round(3.14159) returns the value 3.

• Creating and manipulating complex data variables, such as arrays, lists, and structures

• Creating and manipulating queries

• Creating, analyzing, manipulating, and formatting strings and date and time values

• Evaluating the values of dynamic data

• Determining the type of a variable value

• Converting data between formats

• Performing mathematical operations

• Getting system information and resources

For alphabetical and categorized lists of ColdFusion functions, see Chapter 3, “ColdFusion Functions” in CFML Reference.

You use built-in functions throughout ColdFusion pages. Built-in functions are frequently used in a

cfset or cfoutput tag to prepare data for display or further use. For example, the following

line displays today’s date in the format October 12, 2001:

<cfoutput>#DateFormat(Now(), "mmmm d, yyyy")#</cfoutput>

Note that this code uses two nested functions. The Now function returns a ColdFusion date-time value representing the current date and time. The by the

Now function and converts it to the desired string representation.

Functions are also valuable in CFScript scripts. ColdFusion does not support ColdFusion tags in CFScript, so you must use functions to access ColdFusion functionality in scripts.

DateFormat function takes the value returned

Functions 31

User-defined functions

You can write your own functions, user-defined functions (UDFs). You can use these functions in ColdFusion expressions or in CFScript. You can call a user-defined function anywhere you can use a built-in CFML function. You create UDFs using the

function statement. UDFs that you create using the cffunction tag can include ColdFusion

tags and functions. UDFs that you create in CFScript can only include functions. You can create stand-alone UDFs or encapsulate them in a ColdFusion component.

User-defined functions let you encapsulate logic and operations that you use frequently in a single unit. This way, you can write the code once and use it multiple times. UDFs ensure consistency of coding and enable you to structure your CFML more efficiently.

Typical user-defined functions include mathematical routines, such as a function to calculate the logarithm of a number; string manipulation routines, such as a function to convert a numeric monetary value to a string such as “two dollars and three cents”; and can even include encryption and decryption routines.

Note: The Common Function Library Project at www.cflib.org includes a number of free libraries of user-defined functions.

For more information on user-defined functions, see Chapter 9, “Writing and Calling User-

Defined Functions,” on page 171.

cffunction tag or the CFScript

ColdFusion components

ColdFusion components encapsulate multiple, related, functions. A ColdFusion component is essentially a set of related user-defined functions and variables, with additional functionality to provide and control access to the component contents. ColdFusion components can make their data private, so that it is available to all functions (also called methods) in the component, but not to any application that uses the component.

ColdFusion components have the following features:

• They are designed to provide related services in a single unit.

• They can provide web services and make them available over the Internet.

• They can provide ColdFusion services that Flash clients can call directly.

• They have several features that are familiar to object-oriented programmers, including data

hiding, inheritance, packages, and introspection.

For more information on ColdFusion components, see Chapter 10, “Building and Using

ColdFusion Components,” on page 201.

Constants

The value of a constant does not change during program execution. Constants are simple scalar values that you can use within expressions and functions, such as “Robert Trent Jones” and

123.45. Constants can be integers, real numbers, time and date values, Boolean values, or text strings. ColdFusion does not allow you to give names to constants.

32 Chapter 2: Elements of CFML

Variables

Var ia bl es are the most frequently used operands in ColdFusion expressions. Variable values can be set and reset, and can be passed as attributes to CFML tags. Variables can be passed as parameters to functions, and can replace most constants.

ColdFusion has a number of built-in variables that provide information about the server and are returned by ColdFusion tags. For a list of the ColdFusion built-in variables, see Chapter 1, “Reserved Words and Variables” in CFML Reference.

The following two characteristics classify a variable:

• The scope of the variable, which indicates where the information is available and how long the

variable persists

• The data type of the variable’s value, which indicates the kind of information a variable

represents, such as number, string, or date

The following section lists and briefly describes the variable scopes. “Data types” on page 35 lists data types (which also apply to constant values). For detailed information on ColdFusion variables, including data types, scopes, and their use, see Chapter 3, “Using ColdFusion

Variables,” on page 43.

Variable scopes

The following table describes ColdFusion variable scopes:

Scope Description

Variables (local)

Form The variables passed from a form page to its action page as the result of submitting

URL The parameters passed to the current page in the URL that is used to call it.

Attributes The values passed by a calling page to a custom tag in the custom tag’s attributes.

Caller A reference, available in a custom tag, to the Variables scope of the page that calls

ThisTag Variables that are specific to a custom tag, including built-in variables that provide

Request Variables that are available to all pages, including custom tags and nested custom

CGI Environment variables identifying the context in which a page was requested. The

Cookie Variables maintained in a user’s browser as cookies.

The default scope for variables of any type that are created with the

cfparam tags. A local variable is available only on the page on which it is created and

any included pages.

the form.

Used only in custom tag pages.

the tag. Used only in custom tag pages.

information about the tag. Used only in custom tag pages. A nested custom tag can use the

cfassociate tag to return values to the calling tag’s ThisTag scope.

tags, that are processed in response to an HTTP request. Used to hold data that must be available for the duration of one HTTP request.

variables available depend on the browser and server software.

cfset and

Variables 33

Scope Description

Client Variables that are associated with one client. Client variables let you maintain state

Session Variables that are associated with one client and persist only as long as the client

Application Variables that are associated with one, named, application on a server. The

Server Variables that are associated with the current ColdFusion server. This scope lets

Flash Variables sent by a Macromedia Flash movie to ColdFusion and returned by

Arguments Variables passed in a call to a user-defined function or ColdFusion component

This Variables that are declared inside a ColdFusion component or in a

function local Variables that are declared in a user-defined function and exist only while the

as a user moves from page to page in an application and are available across browser sessions.

maintains a session.

Application.cfc initialization code or the the application name.

you define variables that are available to all your ColdFusion pages, across multiple applications.

ColdFusion to the movie.

method.

that is not part of a ColdFusion component.

function executes.

cfapplication tag name attribute specifies

cffunction tag

Expressions

ColdFusion expressions consist of operands and operators. Operands are comprised of constants and variables, such as "Hello" or MyVariable. Operators, such as the string concatenation operator (&) or the division operator (/) are the verbs that act on the operands. ColdFusion functions also act as operators.

The simplest expression consists of a single operand with no operators. Complex expressions consist of multiple operands and operators. For example, the following statements are all ColdFusion expressions:

12 MyVariable (1 + 1)/2 "father" & "Mother" Form.divisor/Form.dividend Round(3.14159)

For detailed information on using variables, see Chapter 3, “Using ColdFusion Variables,” on

page 43. For detailed information on expressions and operators, see Chapter 4, “Using Expressions and Number Signs,” on page 75.

34 Chapter 2: Elements of CFML

Data types

ColdFusion is considered typeless because you do not explicitly specify variable data types.

However, ColdFusion data, the constants and the data that variables represent, do have data types, which correspond to the ways the data is stored on the computer.

ColdFusion data belongs to the following type categories:

Category Description and types

Simple Represents one value. You can use simple data types directly in

Complex A container for data. Complex variables generally represent more than one

Binary Raw data, such as the contents of a GIF file or an executable program file

Object COM, CORBA, Java, web services, and ColdFusion Component objects:

ColdFusion expressions. ColdFusion simple data types are:

• strings A sequence of alphanumeric characters enclosed in single or double quotation marks, such as “This is a test.”

• integers A sequence of numbers written without quotation marks, such as 356.

• real numbers, such as -3.14159

• Boolean values Use True, Yes, or 1 for true and False, No, or 0 for false.

Boolean values are not case-sensitive.

• date-time values ColdFusion supports a variety of data formats. For more information, see “Date-Time values” on page 49.

value. ColdFusion built-in complex data types are:

• arrays

• structures

• queries

Complex objects that you create and access using the other specialized tags.

cfobject tag and

For more information on ColdFusion data types, see Chapter 3, “Using ColdFusion Variables,”

on page 43.

Flow control

ColdFusion provides several tags that let you control how a page gets executed. These tags generally correspond to programming language flow control statements, such as if, then, and else. The following tags provide ColdFusion flow control:

Tags Purpose

cfif, cfelseif, cfelse Select sections of code based on whether expressions are True or False.

cfswitch, cfcase, cfdefaultcase

cfloop, cfbreak Loop through code based on any of the following values: entries in a list,

cfabort, cfexit End processing of a ColdFusion page or custom tag.

Select among sections of code based on the value of an expression. Case processing is not limited to True and False conditions.

keys in a structure or external object, entries in a query column, an index, or the value of a conditional expression.

Flow control 35

This section provides a basic introduction to using flow-control tags. CFScript also provides a set of flow-control statements. For information on using flow-control statements in CFScript, see

Chapter 6, “Extending ColdFusion Pages with CFML Scripting,” on page 123. For more details

on using flow-control tags, see the reference pages for these tags in CFML Reference.

cfif, cfelseif, and cfelse

The

cfif, cfelseif, and cfelse tags provide if-then-else conditional processing, as follows:

The cfif tag tests a condition and executes its body if the condition is True.

If the preceding cfif (or cfelseif) test condition is False, the cfelseif tag tests another condition and executes its body if that condition is True.

The cfelse tag can optionally follow a cfif tag and zero or more cfelseif tags. Its body executes if all the preceding tags’ test conditions are False.

The following example shows the use of the

cfif, cfelseif, and cfelse tags. If the value of the

type variable is “Date,” the date displays; if the value is “Time,” the time displays; otherwise, both the time and date display.

<cfoutput>#DateFormat(Now())#</cfoutput>

<cfoutput>#TimeFormat(Now())#</cfoutput>

<cfoutput>#TimeFormat(Now())#, #DateFormat(Now())#</cfoutput>

</cfif>

cfswitch, cfcase, and cfdefaultcase

The

cfswitch, cfcase, and cfdefaultcase tags let you select among different code blocks

based on the value of an expression. ColdFusion processes these tags as follows:

The cfswitch tag evaluates an expression. The cfswitch tag body contains one or more

cfcase tags and optionally includes cfdefaultcase tag.

Each cfcase tag in the cfswitch tag body specifies a value or set of values. If a value matches the value determined by the expression in the body of the

cfcase tag and then exits the cfswitch tag. If two cfcase tags have the same

cfswitch tag, ColdFusion runs the code in the

condition, ColdFusion generates an error.

If none of the cfcase tags match the value determined by the cfswitch tag, and the cfswitch tag body includes a

cfdefaultcase tag, ColdFusion runs the code in the cfdefaultcase tag

body.

Note: Although the cfdefaultcase tag does not have to follow all cfcase tags, it is good programming practice to put it at the end of the

cfswitch statement.

The cfswitch tag provides better performance than a cfif tag with multiple cfelseif tags, and is easier to read. Switch processing is commonly used when different actions are required based on a a string variable such as a month or request identifier.

36 Chapter 2: Elements of CFML

The following example shows switch processing:

#FirstName# #LastName# is in Sales </cfcase> <cfcase value = "Accounting">

#FirstName# #LastName# is in Accounting </cfcase> <cfcase value = "Administration">

#FirstName# #LastName# is in Administration </cfcase> <cfdefaultcase>#FirstName# #LastName# is not in Sales,

Accounting, or Administration. </cfdefaultcase>

</cfswitch> </cfoutput>

cfloop and cfbreak

The

cfloop tag loops through the tag body zero or more times based on a condition specified by

the tag attributes. The

cfbreak tag exits a cfloop tag.

cfloop

The

cfloop tag provides five types of loops:

Loop type Description

Index Loops through the body of the tag and increments a counter variable by a

specified amount after each loop until the counter reaches a specified value.

Conditional Checks a condition and runs the body of the tag if the condition is True.

Query Loops through the body of the tag once for each row in a query.

List Loops through the body of the tag once for each entry in a list.

Collection Loops through the body of the tag once for each key in a ColdFusion structure or

item in a COM/DCOM object.

The following example shows a simple index loop:

<cfloop index = "LoopCount" from = 1 to = 5> The loop index is <cfoutput>#LoopCount#</cfoutput>. </cfloop>

The following example shows a simple conditional loop. The code does the following:

Sets up a ten-element array with the word “kumquats” in the fourth entry.

Loops through the array until it encounters an array element containing “kumquats” or it reaches the end of the array.

Prints out the value of the Boolean variable that indicates whether it found the word kumquats and the array index at which it exited the loop.

Flow control 37

</cfloop> <cfoutput> i is #i# foundit is #foundit# </cfoutput>

Note: You can get an infinite conditional loop if you do not force an end condition. In this example, the loop is infinite if you omit the ColdFusion application server.

<cfset i = i + 1> statement. To end an infinite loop, stop the

cfbreak

The

cfbreak tag exits the cfloop tag. You typically use it in a cfif tag to exit the loop if a

particular condition occurs. The following example shows the use of a

cfbreak tag in a query

loop:

<cfoutput>You cannot order kumquats! </cfoutput>

<cfbreak> </cfif> <cfoutput>You have ordered #quantity# #fruit#. </cfoutput>

</cfloop>

cfabort and cfexit

The

cfabort tag stops processing of the current page at the location of the cfabort tag.

ColdFusion returns to the user or calling tag everything that was processed before the tag. You can optionally specify an error message to display. You can use the body of a

The

cfif tag to stop processing a page when a condition, typically an error, occurs.

cfexit tag controls the processing of a custom tag, and can only be used in ColdFusion

cfabort tag as the

custom tags. For more information see, “Terminating tag execution” on page 253 and CFML Reference.

38 Chapter 2: Elements of CFML

cfabort

Character case

ColdFusion is case-insensitive. For example, the following all represent the cfset tag: cfset,

CFSET, CFSet, and even cfsEt. However, you should get in the habit of consistently using the

same case rules in your programs; for example:

• Develop consistent rules for case use, and stick to them. If you use lowercase characters for

some tag names, use them for all tag names.

• Always use the same case for a variable. For example, do not use both myvariable and

MyVariable to represent the same variable on a page.

Follow these rules to prevent errors on application pages where you use both CFML and casesensitive languages, such as JavaScript.

Special characters

The double-quotation marks ("), single-quotation mark ('), and number sign (#) characters have special meaning to ColdFusion. To include any of them in a string, double the character; for example, use ## to represent a single # character.

The need to escape the single- and double-quotation marks is context-sensitive. Inside a doublequoted string, you do not need to escape single-quotation mark (apostrophe) characters. Inside a single-quoted string, you do not escape double-quotation mark characters.

The following example illustrates escaping special characters, including the use of mixed singleand double-quotation marks:

#mystring# #mystring2# Here is a number sign: ##

</cfoutput>

The output looks like this:

We all said "For He's a jolly good fellow." Then we said "For She's a jolly good fellow." Here is a number sign: #

Reserved words

As with any programming tool, you cannot use just any word or name for ColdFusion variables, UDFs and custom tags. You must avoid using any name that can be confused with a ColdFusion element. In some cases, if you use a word that ColdFusion uses—for example, a built-in structure name—you can overwrite the ColdFusion data.

The following list indicates words you must not use for ColdFusion variables, user-defined function names, or custom tag names. While some of these words can be used safely in some situations, you can prevent errors by avoiding them entirely. For a complete list of reserved words, see CFML Reference.

Reserved words 39

• Built-in function names, such as Now or Hash

• Scope names, such as Form or Session

• Any name starting with cf. However, when you call a CFML custom tag directly, you prefix the

custom tag page name with cf_.

• Operators, such as NE or IS

• The names of any built-in data structures, such as Error or File

• The names of any built-in variables, such as RecordCount or CGI variable names

• CFScript language element names such as for, default, or continue

You must also not create form field names ending in any of the following, except to specify a form field validation rule using a hidden form field name. (For more information on form field validation, see Chapter 26, “Introduction to Retrieving and Formatting Data,” on page 609.)

• _integer

• _float

• _range

• _date

• _time

• _eurodate

Remember that ColdFusion is not case-sensitive. For example, all of the following are reserved words: IS, Is, iS, and is.

CFScript

CFScript is a language within a language. CFScript is a scripting language that is similar to JavaScript but is simpler to use. Also, unlike JavaScript, CFScript only runs on the ColdFusion server; it does not run on the client system. A CFScript script can use all ColdFusion functions and all ColdFusion variables that are available in the script’s scope.

CFScript provides a compact and efficient way to write ColdFusion logic. Typical uses of CFScript include:

• Simplifying and speeding variable setting

• Building compact flow control structures

• Encapsulating business logic in user-defined functions

The following sample script populates an array and locates the first array entry that starts with the word “key”. It shows several of the elements of CFScript, including setting variables, loop structures, script code blocks, and function calls. Also, the code uses a results. Although you can use CFScript for output, the

<cfscript> strings = ArrayNew(1); strings[1]="the"; strings[2]="key to our"; strings[4]="idea"; for( i=1 ; i LE 4 ; i = i+1 )

40 Chapter 2: Elements of CFML

cfoutput tag is usually easier to use.

cfoutput tag to display its

{

if(Find("key",strings[i],1))

break; }

</cfscript> <cfoutput>Entry #i# starts with "key"</cfoutput>

You use CFScript to create user-defined functions.

For more information on CFScript, see Chapter 6, “Extending ColdFusion Pages with CFML

Scripting,” on page 123. For more information on user-defined functions, see Chapter 9, “Writing and Calling User-Defined Functions,” on page 171.

CFScript 41

42 Chapter 2: Elements of CFML

CHAPTER 3

Using ColdFusion Variables

Macromedia ColdFusion variables are the most frequently used operands in ColdFusion expressions. Variable values can be set and reset, and can be passed as attributes to CFML tags. Variables can be passed as parameters to functions, and can replace most constants.

This chapter describes how to create and use ColdFusion variables. It includes the following information:

• How variables can represent different types of data

• How the data types get converted

• How variables exist in different scopes

• How the scopes are used

• How to use variables correctly

Creating variables. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44

Variable characteristics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45

Data types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45

Using periods in variable references . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56

Data type conversion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59

About scopes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64

Ensuring variable existence. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70

Validating data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73

Passing variables to custom tags and UDFs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73

Creating variables

You create most ColdFusion variables by assigning them values. (You must use the ArrayNew function to create arrays.) Most commonly, you create variables by using the also use the also create variables. For example, the

ColdFusion automatically creates some variables that provide information about the results of certain tags or operations. ColdFusion also automatically generates variables in certain scopes, such as Client and Server. For information on these special variables, see Chapter 1, “Reserved Words and Variables” in CFML Reference and the documentation of the CFML tags that create these variables.

ColdFusion generates an error when it tries to use a variable before it is created. This can happen, for example, when processing data from an incompletely filled form. To prevent such errors, test for the variable’s existence before you use it. For more information on testing for variable existence, see “Ensuring variable existence” on page 70.

For more information on how to create variables, see “Creating and using variables in scopes”

on page 67.

Variable naming rules

ColdFusion variable names, including form field names and custom function and ColdFusion component argument names, must conform to Java naming rules and the following guidelines:

cfparam tag, and assignment statements in CFScript. Tags that create data objects

cfquery tag creates a query object variable.

cfset tag. You can

• A variable name must begin with a letter, underscore, or Unicode currency symbol.

• The initial character can by followed by any number of letters, numbers, underscore characters,

and Unicode currency symbols.

• A variable name cannot contain spaces.

• A query result is a type of variable, so it overwrites a local variable with the same name.

• ColdFusion variables are not case-sensitive. However, consistent capitalization makes the code

easier to read.

• When creating a form with fields that are used in a query, match form field names with the

corresponding database field names.

• Periods separate the components of structure or object names. They also separate a variable

scope from the variable name. You cannot use periods in simple variable names, with the exception of variables in the Cookie and Client scopes. For more information on using periods, see “Using periods in variable references” on page 56.

The following rule applies to variable names, but does not apply to form field and argument names:

• Prefix each variable’s name with its scope. Although some ColdFusion programmers do not use

the Variables prefix for local variable names, you should use prefixes for all other scopes. Using scope prefixes makes variable names clearer and increases code efficiency. In many cases, you must prefix the scope. For more information, see “About scopes” on page 64.

44 Chapter 3: Using ColdFusion Variables

Note: In some cases, when you use an existing variable name, you must enclose it with number signs (#) to allow ColdFusion to distinguish it from string or HTML text, and to insert its value, as opposed to its name. For more information, see Chapter 4, “Using number signs,” on page 81.

Variable characteristics

You can classify a variable using the following characteristics:

• The data type of the variable value, which indicates the kind of information a variable

represents, such as number, string, or date

• The scope of the variable, which indicates where the information is available and how long the

variable persists

The following sections provide detailed information on Data types and scopes.

Data types

ColdFusion is often referred to as typeless because you do not assign types to variables and ColdFusion does not associate a type with the variable name. However, the data that a variable represents does have a type, and the data type affects how ColdFusion evaluates an expression or function argument. ColdFusion can automatically convert many data types into others when it evaluates expressions. For simple data, such as numbers and strings, the data type is unimportant until the variable is used in an expression or as a function argument.

ColdFusion variable data belongs to one of the following type categories:

• Simple One value. Can use directly in ColdFusion expressions. Include numbers, strings,

Boolean values, and date-time values.

• Complex A container for data. Generally represent more than one value. ColdFusion built-

in complex data types include arrays, structures, queries, and XML document objects.

You cannot use a complex variable, such as an array, directly in a ColdFusion expression, but you can use simple data type elements of a complex variable in an expression.

For example, with a one-dimensional array of numbers called myArray, you cannot use the expression myArray * 5. However, you could use an expression myArray[3] * 5 to multiply the third element in the array by five.

• Binary Raw data, such as the contents of a GIF file or an executable program file.

• Objects Complex constructs. Often encapsulate both data and functional operations. The

following table lists the types of objects that ColdFusion can use, and identifies the chapters that describe how to use them:

Object type See

Component Object Model (COM) Chapter 38, “Integrating COM and CORBA Objects in CFML

Applications,” on page 945

Common Object Request Broker Architecture (CORBA)

Java Chapter 37, “Integrating J2EE and Java Elements in CFML

Chapter 38, “Integrating COM and CORBA Objects in CFML Applications,” on page 945

Applications,” on page 917

Data types 45

Object type See

ColdFusion component Chapter 10, “Building and Using ColdFusion Components,”

Web service Chapter 36, “Using Web Services,” on page 885

Data type notes

Although ColdFusion variables do not have types, it is often convenient to use “variable type” as a shorthand for the type of data that the variable represents.

ColdFusion can validate the type of data contained in form fields and query parameters. For more information, see Chapter 26, “SELECT * FROM Departmt WHERE Dept_Name IN

('Marketing','Sales'),” on page 630 and Chapter 20, “Using cfqueryparam,” on page 473.

The

cfdump tag displays the entire contents of a variable, including ColdFusion complex data

structures. It is an excellent tool for debugging complex data and the code that handles it.

ColdFusion provides the following functions for identifying the data type of a variable:

on page 201

• IsArray

• IsBinary

• IsBoolean

• IsObject

• IsQuery

• IsSimpleValue

• IsStruct

• IsXmlDoc

ColdFusion also includes the following functions for determining whether a string can be represented as or converted to another data type:

• IsDate

• IsNumeric

• IsXML

ColdFusion does not use a null data type. However, if ColdFusion receives a null value from an external source such as a database, a Java object, or some other mechanism, it maintains the null value until you use it as a simple value. At that time, ColdFusion converts the null to an empty string (""). Also, you can use the ColdFusion empty string to a Java null.

Numbers

ColdFusion supports integers and real numbers. You can intermix integers and real numbers in expressions; for example, 1.2 + 3 evaluates to 4.2.

46 Chapter 3: Using ColdFusion Variables

JavaCast function in a call to a Java object to convert a

Integers

ColdFusion supports integers between -2,147,483,648 and 2,147,483,647 (32-bit signed integers). You can assign a value outside this range to a variable, but ColdFusion initially stores the number as a string. If you use it in an arithmetic expression, ColdFusion converts it into a floating point value, preserving its value, but losing precision as the following example shows:

<cfset mybignum=12345678901234567890> <cfset mybignumtimes10=(mybignum * 10)> <cfoutput>mybignum is: #mybignum#</cfoutput> <cfoutput>mybignumtimes10 is: #mybignumtimes10# </cfoutput>

This example generates the following output:

mybignum is: 12345678901234567890

mybignumtimes10 is: 1.23456789012E+020

Real numbers

Real numbers, numbers with a decimal part, are also known as floating point numbers. ColdFusion real numbers can range from approximately -10

300

to approximately 10

300

number can have up to 12 significant digits. As with integers, you can assign a variable a value with more digits, but the data is stored as a string. The string is converted to a real number, and can lose precision, when you use it in an arithmetic expression.

You can represent real numbers in scientific notation. This format is xEy, where x is a positive or negative real number in the range 1.0 (inclusive) to 10 (exclusive), and y is an integer. The value of a number in scientific notation is x times 10 equals 400. Similarly, 2.5E-2 is 2.5 times 10

. For example, 4.0E2 is 4.0 times 102, which

-2

, which equals 0.025. Scientific notation is useful

for writing very large and very small numbers.

. A real

Strings

In ColdFusion, text values are stored in strings. You specify strings by enclosing them in either single- or double-quotation marks. For example, the following two strings are equivalent:

"This is a string"

'This is a string'

You can write an empty string in the following ways:

• "" (a pair of double-quotation marks with nothing in between)

• '' (a pair of single-quotation marks with nothing in between)

Strings can be any length, limited by the amount of available memory on the ColdFusion server. However, the default size limit for long text retrieval (CLOB) is 64K. The ColdFusion MX Administrator lets you increase the limit for database string transfers, but doing so can reduce server performance. To change the limit, select the Enable retrieval of long text option on the Advanced Settings page for the data source.

Strings 47

Escaping quotation marks and number signs

To include a single-quotation character in a string that is single-quoted, use two single-quotation marks (known as escaping the single-quotation mark). The following example uses escaped singlequotation marks:

<cfset myString='This is a single-quotation mark: '' This is a double-quotation

mark: "'>

<cfoutput>#mystring#</cfoutput>

To include a double-quotation mark in a double-quoted string, use two double-quotation marks (known as escaping the double-quotation mark). The following example uses escaped doublequotation marks:

<cfset myString="This is a single-quotation mark: ' This is a double-quotation

mark: """>

<cfoutput>#mystring#</cfoutput>

Because strings can be in either double-quotation marks or single-quotation marks, both of the preceding examples display the same text:

This is a single-quotation mark: ' This is a double-quotation mark: "

To insert a number sign (#) in a string, you must escape the number sign, as follows:

"This is a number sign ##"

Lists

ColdFusion includes functions that operate on lists, but it does not have a list data type. In ColdFusion, a list is just a string that consists of multiple entries separated by delimiter characters.

The default delimiter for lists is the comma. If you use any other character to separate list elements, you must specify the delimiter in the list function. You can also specify multiple delimiter characters. For example, you can tell ColdFusion to interpret a comma or a semicolon as a delimiter, as the following example shows:

<cfset MyList="1,2;3,4;5"> <cfoutput> List length using ; and , as delimiters: #listlen(Mylist, ";,")# List length using only , as a delimiter: #listlen(Mylist)# </cfoutput>

This example displays the following output:

List length using ; and , as delimiters: 5

List length using only , as a delimiter: 3

Each delimiter must be a single character. For example, you cannot tell ColdFusion to require two hyphens in a row as a delimiter.

If a list has two delimiters in a row, ColdFusion ignores the empty element. For example, if MyList is "1,2,,3,,4,,,5" and the delimiter is the comma, the list has five elements and list functions treat it the same as "1,2,3,4,5".

48 Chapter 3: Using ColdFusion Variables

Boolean values

A Boolean value represents whether something is true or false. ColdFusion has two special constants—True and False—to represent these values. For example, the Boolean expression 1 IS 1 evaluates to True. The expression

"Monkey" CONTAINS "Money" evaluates to False.

You can use Boolean constants directly in expressions, as in the following example:

In Boolean expressions, True, nonzero numbers, and the string “Yes” are equivalent, and False, 0, and the string “No” are equivalent.

In Boolean expressions, True, nonzero numbers, and the strings “Yes”, “1|”, “True” are equivalent; and False, 0, and the strings “No”, “0”, and “False” are equivalent.

Boolean evaluation is not case-sensitive. For example, True, TRUE, and true are equivalent.

Date-Time values

ColdFusion can perform operations on date and time values. Date-time values identify a date and time in the range 100 AD to 9999 AD. Although you can specify just a date or a time, ColdFusion uses one data type representation, called a date-time object, for date, time, and date and time values.

ColdFusion provides many functions to create and manipulate date-time values and to return all or part of the value in several different formats.

You can enter date and time values directly in a

cfset tag with a constant, as follows:

When you do this, ColdFusion stores the information as a string. If you use a date-time function, ColdFusion stores the value as a date-time object, which is a separate simple data type. When possible, use date-time functions such as

CreateDate and CreateTime to specify dates and times,

because these functions can prevent you from specifying the date or time in an invalid format and they create a date-time object immediately.

Strings 49

Date and time formats

You can directly enter a date, time, or date and time, using standard U.S. date formats. ColdFusion processes the two-digit-year values 0 to 29 as twenty-first century dates; it processes the two-digit-year values 30 to 99 as twentieth century dates. Time values can include units down to seconds. The following table lists valid date and time formats:

To specify Use these formats

Date October 30, 2003

Time 02:34:12

Date and Time Any combination of valid date and time formats, such as these:

Oct 30, 2003 Oct. 30, 2003 10/30/03 2003-10-30

10-30-2003

2:34a 2:34am 02:34am 2am

October 30, 2003 02:34:12 Oct 30, 2003 2:34a Oct. 30, 2001 2:34am 10/30/03 02:34am 2003-10-30 2am 10-30-2003 2am

Locale-specific dates and times

ColdFusion provides several functions that let you input and output dates and times (and numbers and currency values) in formats that are specific to the current locale. A locale identifies a language and locality, such as English (US) or French (Swiss). Use these functions to input or output dates and times in formats other than the U.S. standard formats. (Use the

SetLocale

function to specify the locale.) The following example shows how to do this:

<cfset oldlocale = SetLocale("French (Standard)")> <cfoutput>#LSDateFormat(Now(), "ddd, dd mmmm, yyyy")#</cfoutput>

This example outputs a line like the following:

mar., 03 juin, 2003

For more information on international functions, see Chapter 17, “Developing Globalized

Applications,” on page 403 and CFML Reference.

50 Chapter 3: Using ColdFusion Variables

How ColdFusion stores dates and times

ColdFusion stores and manipulates dates and times as date-time objects. Date-time objects store data on a time line as real numbers. This storage method increases processing efficiency and directly mimics the method used by many popular database systems. In date-time objects, one day is equal to the difference between two successive integers. The time portion of the date-andtime value is stored in the fractional part of the real number. The value 0 represents 12:00 AM 12/30/1899.

Although you can use arithmetic operations to manipulate date-and-time values directly, this method can result in code that is difficult to understand and maintain. Use the ColdFusion datetime manipulation functions instead. For information on these functions, see the CFML Reference.

Binary data type and binary encoding

Binary data (also referred to as a binary object) is raw data, such as the contents of a GIF file or an executable program file. You do not normally use binary data directly, but you can use the tag to read a binary file into a variable, typically for conversion to a string binary encoding before transmitting the file using e-mail.

A string binary encoding represents a binary value in a string format that can be transmitted over the web. ColdFusion MX supports three binary encoding formats:

Encoding Format

Base64 Encodes the binary data in the lowest six bits of each byte. It ensures that binary

data and non-ANSI character data can be transmitted using e-mail without corruption. The Base64 algorithm is specified by IETF RFC 2045, at

www.ietf.org/rfc/rfc2045.txt.

Hex Uses two characters in the range 0-9 and A-F represent the hexadecimal value of

each byte; for example, 3A.

UU Uses the UNIX UUencode algorithm to convert the data.

cffile

ColdFusion provides the following functions that convert among string data, binary data, and string encoded binary data:

Function Description

BinaryDecode Converts a string that contains encoded binary data to a binary object.

BinaryEncode Converts binary data to an encoded string.

CharsetDecode Converts a string to binary data in a specified character encoding.

CharsetEncode Converts a binary object to a string in a specified character encoding.

ToBase64

Converts string and binary data to Base64 encoded data Macromedia recommends using the binary data to Base64 in new applications.

BinaryEncode function, instead of this function, to convert

Strings 51

Function Description

ToBinary

ToString

Converts Base64 encoded data to binary data. Macromedia recommends using the

BinaryDecode function, instead of this function, in new applications.

Converts most simple data types to string data. It can convert numbers, date-time objects, and boolean values. (It converts date-time objects to ODBC timestamp strings.) Macromedia recommends that you use the CharsetEncode function to convert binary data to a string in new applications.

Complex data types

Arrays, structures, and queries are ColdFusion built-in complex data types. Structures and queries are sometimes referred to as objects, because they are containers for data, not individual data values.

For details on using arrays and structures, see Chapter 5, “Using Arrays and Structures,” on

page 97.

Arrays

Arrays are a way of storing multiple values in a table-like format that can have one or more dimensions. To create an array and specify its initial dimensions, use the ColdFusion function. For example, the following line creates an empty two-dimensional array:

You reference elements using numeric indexes, with one index for each dimension. For example, the following line sets one element of a two-dimensional array to the current date and time:

The ArrayNew function can create arrays with up to three dimensions. However, there is no limit on array size or maximum dimension. To create arrays with more than three dimensions, create arrays of arrays.

ArrayNew

After you create an array, you can use functions or direct references to manipulate its contents.

When you assign an existing array to a new variable, ColdFusion creates a new array and copies the old array’s contents to the new array. The following example creates a copy of the original array:

For more information on using arrays, see Chapter 5, “Using Arrays and Structures,” on page 97.

Structures

ColdFusion structures consist of key-value pairs, where the keys are text strings and the values can be any ColdFusion data type, including other structures. Structures let you build a collection of related variables that are grouped under a single name. To create a structure, use the ColdFusion

StructNew function. For example, the following line creates a new, empty, structure called depts:

52 Chapter 3: Using ColdFusion Variables

You can also create a structure by assigning a value in the structure. For example, the following line creates a new structure called MyStruct with a key named MyValue, equal to 2:

Note: In previous ColdFusion versions, this line created a Variables scope variable named "MyStruct.MyValue" with the value 2.

After you create a structure, you can use functions or direct references to manipulate its contents, including adding key-value pairs.

You can use either of the following methods to reference elements stored in a structure:

• StructureName.KeyName

• StructureName["KeyName"]

The following examples show these methods:

depts.John="Sales" depts["John"]="Sales"

When you assign an existing structure to a new variable, ColdFusion does not create a new structure. Instead, the new variable accesses the same data (location) in memory as the original structure variable. In other words, both variables are references to the same object.

For example, the following line creates a new variable, myStructure2, that is a reference to the same structure as the myStructure variable:

When you change the contents of myStructure2, you also change the contents of myStructure. To copy the contents of a structure, use the ColdFusion contents of structures and other complex data types.

Duplicate function, which copies the

Structure key names can be the names of complex data objects, including structures or arrays. This lets you create arbitrarily complex structures.

For more information on using structures, see Chapter 5, “Using Arrays and Structures,” on

page 97.

Queries

A query object, sometimes referred to as a query, query result, or record set, is a complex ColdFusion data type that represents data in a set of named columns, similar to the columns of a database table. The following ColdFusion tags can create query objects:

• cfquery

• cfdirectory

• cfhttp

• cfldap

• cfpop

• cfprocresult

In these tags, the name attribute specifies the query object’s variable name. The QueryNew function also creates query objects.

Strings 53

When you assign a query to a new variable, ColdFusion does not copy the query object. Instead, both names point to the same record set data. For example, the following line creates a new variable, myQuery2, that references the same record set as the myQuery variable:

If you make changes to data in myQuery, myQuery2 also shows those changes.

You reference query columns by specifying the query name, a period, and the column name; for example:

myQuery.Dept_ID

When you reference query columns inside tags, such as cfoutput and cfloop, in which you specify the query name in a tag attribute, you do not have to specify the query name.

You can access query columns as if they are one-dimensional arrays. For example, the following line assigns the contents of the Employee column in the second row of the myQuery query to the variable myVar:

Note: You cannot use array notation to refer to a row (of all columns) of a query. For example, myQuery[2] does not refer to the second row of the myQuery query object.

Working with structures and queries

Because structure variables and query variables are references to objects, the rules in the following sections apply to both types of data.

Multiple references to an object

When multiple variables refer to a structure or query object, the object continues to exist as long as at least one reference to the object exists. The following example shows how this works:

<cfscript> depts = structnew();</cfscript> <cfset newStructure=depts> <cfset depts.John="Sales"> <cfset depts=0> <cfoutput>

#newStructure.John# #depts#

</cfoutput>

This example displays the following output:

Sales

After the

<cfset depts=0> tag executes, the depts variable does not refer to a structure; it is a

simple variable with the value 0. However, the variable newStructure still refers to the original structure object.

54 Chapter 3: Using ColdFusion Variables

Assigning objects to scopes

You can give a query or structure a different scope by assigning it to a new variable in the other scope. For example, the following line creates a server variable, Server.SScopeQuery, using the local myquery variable:

To clear the server scope query variable, reassign the query object, as follows:

This deletes the reference to the object from the server scope, but does not remove any other references that might exist.

Copying and duplicating objects

You can use the Duplicate function to make a true copy of a structure or query object. Changes to the copy do not affect the original.

Using a query column

When you are not inside a cfloop, cfoutput, or cfmail tag that has a query attribute, you can treat a query column as an array. However, query column references do not always behave as you might expect. This section explains the behavior of references to query columns using the results of the following

SELECT FirstName, LastName FROM Employee

</cfquery>

cfquery tag in its examples:

To reference elements in a query column, use the row number as an array index. For example, both of the following lines display the word "ben":

<cfoutput> #myQuery.Firstname[1]# </cfoutput> <cfoutput> #myQuery["Firstname"][1]# </cfoutput>

ColdFusion behavior is less straightforward, however, when you use the query column references myQuery.Firstname and myQuery["Firstname"] without using an array index. The two reference formats produce different results.

If you refer to myQuery.Firstname, ColdFusion automatically converts it to the first row in the column. For example, the following lines print the word "ben":

<cfset myCol = myQuery.Firstname > <cfoutput>#mycol#</cfoutput>

But the following lines display an error message:

<cfset myCol = myQuery.Firstname > <cfoutput>#mycol[1]#</cfoutput>

If you refer to Query["Firstname"], ColdFusion does not automatically convert it to the first row of the column. For example, the following line results in an error message indicating that ColdFusion cannot convert a complex type to a simple value:

<cfoutput> #myQuery['Firstname']# </cfoutput>

Strings 55

Similarly, the following lines print the name "marjorie", the value of the second row in the column:

<cfset myCol = myQuery["Firstname"]> <cfoutput>#mycol[2]#</cfoutput>

However, when you make an assignment that requires a simple value, ColdFusion automatically converts the query column to the value of the first row. For example, the following lines display the name "ben" twice:

<cfoutput> #myQuery.Firstname# </cfoutput> <cfset myVar= myQuery['Firstname']> <cfoutput> #myVar# </cfoutput>

Using periods in variable references

ColdFusion uses the period (.) to separate elements of a complex variable such as a structure, query, XML document object, or external object, as in MyStruct.KeyName. A period also separates a variable scope identifier from the variable name, as in Variables.myVariable or CGI.HTTP_COOKIE.

With the exception of Cookie and Client scope variables, which must always be simple variable types, you cannot normally include periods in simple variable names. However, ColdFusion makes some exceptions that accommodate legacy and third-party code that does not conform to this requirement.

For more information, see “About scopes” on page 64, Chapter 5, “Using Arrays and Structures,”

on page 97, and Chapter 35, “Using XML and WDDX,” on page 843.

Understanding variables and periods

The following descriptions use a sample variable named MyVar.a.b to explain how ColdFusion uses periods when getting and setting the variable value.

Getting a variable

ColdFusion can correctly get variable values even if the variable name includes a period. For example, the following set of steps shows how ColdFusion gets MyVar.a.b, as in

myVar.a.b>

Looks for myVar in an internal table of names (the symbol table).

If myVar is the name of a complex object, including a scope, looks for an element named a in

or IsDefined(myVar.a.b):

<cfset Var2 =

the object.

If myVar is not the name of a complex object, checks whether myVar.a is the name of a complex object and skips step 3.

If myVar is the name of a complex object, checks whether a is a complex object.

56 Chapter 3: Using ColdFusion Variables

If a or myVar.a is the name of a complex object, checks whether b is the name of a simple variable, and returns the value of b.

If myVar is a complex object but a is not a complex object, checks whether a.b is the name of a simple variable and returns its value.

If myVar.a is not a complex object, checks whether myVar.a.b is the name of a simple variable and returns its value.

This way, ColdFusion correctly resolves the variable name and can get its value.

You can also use array notation to get a simple variable with a name that includes periods. In this form of array notation, you use the scope name (or the complex variable that contains the simple variable) as the “array” name. You put the simple variable name, in single- or double-quotation marks, inside the square brackets.

Using array notation is more efficient than using plain dot notation because ColdFusion does not have to analyze and look up all the possible key combinations. For example, both of the following lines write the value of myVar.a.b, but the second line is more efficient than the first:

<cfoutput>myVar.a.b is: #myVar.a.b# </cfoutput> <cfoutput>myVar.a.b is: #Variables["myVar.a.b"]# </cfoutput>

Setting a variable

ColdFusion cannot be as flexible when it sets a variable value as when it gets a variable, because it must determine the type of variable to create or set. Therefore, the rules for variable names that you set are stricter. Also, the rules vary depending on whether the first part of the variable name is the Cookie or Client scope identifier.

For example, assume you have the following code:

If a variable myVar does not exist, it does the following:

Creates a structure named myVar.

Creates a structure named a in the structure myVar.

Creates a key named b in myVar.a.

Gives it the value "This is a test".

If either myVar or myVar.a exist and neither one is a structure, ColdFusion generates an error.

In other words, ColdFusion uses the same rules as for getting a variable to resolve the variable name until it finds a name that does not exist yet. It then creates any structures that are needed to create a key named b inside a structure, and assigns the value to the key.

Using periods in variable references 57

However, if the name before the first period is either Cookie or Client, ColdFusion uses a different rule. It treats all the text (including any periods) that follow the scope name as the name of a simple variable, because Cookie and Client scope variables must be simple. If you have the following code, you see that ColdFusion creates a single, simple Client scope variable named myVar.a.b:

Creating variables with periods

You should avoid creating the names of variables (except for dot notation in structures) that include periods. However, ColdFusion provides mechanisms for handling cases where you must do so, for example, to maintain compatibility with names of variables in external data sources or to integrate your application with existing code that uses periods in variable names. The following sections describe how to create simple variable names that include periods.

Using brackets to create variables with periods

You can create a variable name that includes periods by using associative array structure notation, as described in Chapter 5, “Structure notation,” on page 109. To do so, you must do the following:

• Refer to the variable as part of a structure. You can always do this, because ColdFusion

considers all scopes to be structures. For more information on scopes, see “Ab o ut s cop e s”

on page 64.

• Put the variable name that must include a period inside square brackets and single- or double-

quotation marks.

The following example shows this technique:

My.Variable.With.Periods is: #My.Variable.With.Periods# Request.Another.Variable.With.Periods is:

#Request.Another.Variable.With.Periods#

</cfoutput>

Creating Client and Cookie variables with periods

To create a Client or Cookie variable with a name that includes one or more periods, simply assign the variable a value. For example, the following line creates a Cookie named User.Preferences.CreditCard:

58 Chapter 3: Using ColdFusion Variables

Data type conversion

ColdFusion automatically converts between data types to satisfy the requirements of an expression’s operations, including a function’s argument requirements. As a result, you generally don’t need to be concerned about compatibility between data types and the conversions from one data type to another. However, understanding how ColdFusion evaluates data values and converts data between types can help you prevent errors and create code more effectively.

Operation-driven evaluation

Conventional programming languages enforce strict rules about mixing objects of different types in expressions. For example, in a language such as C++ or Basic, the expression produces an error because the multiplication operator requires two numerical operands and "8" is a string. When you program in such languages, you must convert between data types to ensure error-free program execution. For example, the previous expression might have to be written as

(ToNumber("8") * 10).

In ColdFusion, however, the expression

("8" * 10) evaluates to the number 80 without

generating an error. When ColdFusion processes the multiplication operator, it automatically attempts to convert its operands to numbers. Since "8" can be successfully converted to the number 8, the expression evaluates to 80.

ColdFusion processes expressions and functions in the following sequence:

For each operator in an expression, it determines the required operands. (For example, the multiplication operator requires numeric operands and the CONTAINS operator requires string operands.)

For functions, it determines the type required for each function argument. (For example, the

Min function requires two numbers as arguments and the Len function requires a string.)

It evaluates all operands or function arguments.

It converts all operands or arguments whose types differ from the required type. If a conversion fails, it reports an error.

("8" * 10)

Conversion between types

Although the expression evaluation mechanism in ColdFusion is very powerful, it cannot automatically convert all data. For example, the expression

"eight" * 10 produces an error

because ColdFusion cannot convert the string "eight" to the number 8. Therefore, you must understand the rules for conversion between data types.

The following table explains how conversions are performed. The first column shows values to convert. The remaining columns show the result of conversion to the listed data type.

Value As Boolean As number As date-time As string

"Yes" True 1 Error "Yes"

"No" False 0 Error "No"

True True 1 Error "Yes"

Data type conversion 59

Value As Boolean As number As date-time As string

False False 0 Error "No"

Number True if Number

is not 0; False otherwise.

String If "Yes", True

If "No", False If it can be converted to 0,

False If it can be

converted to any other number, True

Date Error The numeric value

Number See “Date-time values”

If it represents a number (for example, "1,000" or "12.36E-12"), it is converted to the corresponding number. If it represents a datetime (see next column), it is converted to the numeric value of the corresponding date-time object.

of the date-time object.

earlier in this chapter.

If it is an ODBC date, time, or timestamp (for example "{ts '2001-06-14 11:30:13'}", or if it is expressed in a standard U.S. date or time format, including the use of full or abbreviated month names, it is converted to the corresponding date-time value. Days of the week or unusual punctuation result in an error. Dashes, forward-slashes, and spaces are generally allowed.

Date An ODBC timestamp.

String representation of the number (for example, “8”).

String

ColdFusion cannot convert complex types, such as arrays, queries, and COM objects, to other types. However, it can convert simple data elements of complex types to other simple data types.

Type conversion considerations

The following sections detail specific rules and considerations for converting between types.

The cfoutput tag

The cfoutput tag always displays data as a string. As a result, when you display a variable using the

cfoutput tag, ColdFusion applies the type conversion rules to any non-string data before

displaying it. For example, the

cfoutput tag displays a date-time value as an ODBC timestamp.

Case-insensitivity and Boolean conversion

Because ColdFusion expression evaluation is not case-sensitive, Yes, YES, and yes are equivalent; False, FALSE, and false are equivalent; No, NO, and no are equivalent; and True, TRUE, and true are equivalent.

Converting binary data

ColdFusion cannot automatically convert binary data to other data types. To convert binary data, use the

ToBase64 and ToString functions. For more information, see “Binary data type and

binary encoding” on page 51.

60 Chapter 3: Using ColdFusion Variables

Converting date and time data

To ensure that a date and time value is expressed as a real number, add zero to the variable. The following example shows this:

<cfset mynow = now()> Use cfoutput to display the result of the now function: <cfoutput>#mynow#</cfoutput> Now add 0 to the result and display it again: <cfset mynow = mynow + 0> <cfoutput>#mynow#</cfoutput>

At 1:06 PM on June 6, 2003, its output looked like this:

Use cfoutput to display the result of the now function: {ts '2003-06-03 13:06:44'} Now add 0 to the result and display it again:

37775.5463426

Converting numeric values

When ColdFusion evaluates an expression that includes both integers and real numbers, the result is a real number. To convert a real number to an integer, use a ColdFusion function. The

Round, Fix, and Ceiling functions convert real numbers to integers, and differ in their treatment

Int,

of the fractional part of the number.

If you use a hidden form field with a name that has the suffix

_integer or _range to validate a

form input field, ColdFusion truncates real numbers entered into the field and passes the resulting integer to the action page.

If you use a hidden form field with a name that has the suffix

_integer, _float, or _range to

validate a form input field, and the entered data contains a dollar amount (including a dollar sign) or a numeric value with commas, ColdFusion considers the input to be valid, removes the dollar sign or commas from the value, and passes the resulting integer or real number to the action page.

Evaluation and type conversion issues

The following sections explain several issues that you might encounter with type evaluation and conversion.

Comparing variables to True or False

You might expect the following two cfif tag examples to produce the same results:

<cfoutput>myVariable equals #myVariable# and is True </cfoutput>

</cfif> <cfif myVariable IS True>

<cfoutput>myVariable equals #myVariable# and is True </cfoutput>

</cfif>

Data type conversion 61

However, if myVariable has a numeric value such as 12, only the first example produces a result. In the second case, the value of myVariable is not converted to a Boolean data type, because the IS operator does not require a specific data type and just tests the two values for identity. Therefore, ColdFusion compares the value 12 with the constant True. The two are not equal, so nothing is printed. If myVariable is 1, "Yes", or True, however, both examples print the same result, because ColdFusion considers these to be identical to Boolean True.

If you use the following code, the output statement does display, because the value of the variable, 12, is not equal to the Boolean value False:

<cfoutput>myVariable equals #myVariable# and IS NOT False </cfoutput>

</cfif>

As a result, you should use the test <cfif testvariable>, and not use the IS comparison operator when testing whether a variable is True or False. This issue is a case of the more general problem of ambiguous type expression evaluation, described in the following section.

Ambiguous type expressions and strings

When ColdFusion evaluates an expression that does not require strings, including all comparison operations, such as

IS or GT, it checks whether it can convert each string value to a number or

date-time object. If so, ColdFusion converts it to the corresponding number or date-time value (which is stored as a number). It then uses the number in the expression.

Short strings, such as 1a and 2P, can produce unexpected results. ColdFusion can interpret a single "a" as AM and a single "P" as PM. This can cause ColdFusion to interpret strings as datetime values in cases where this was not intended.

Similarly, if the strings can be interpreted as numbers, you might get unexpected results.

For example, ColdFusion interprets the following expressions as shown:

Expression Interpretation

If 1:00am is 1:00am.

If 1:00pm is later than 2:00am.

Treat the variable age as 4:00 am, convert it to the date-time value 0.16666666667, and add 7 to make it 7.16666666667.

If 0 is 0.

To prevent such ambiguities when you compare strings, use the ColdFusion string comparison functions

You can also use the

Compare and CompareNoCase, instead of the comparison operators.

IsDate function to determine whether a string can be interpreted as a date-

time value, or to add characters to a string before comparison to avoid incorrect interpretation.

62 Chapter 3: Using ColdFusion Variables

Date-time functions and queries when ODBC is not supported

Many CFML functions, including the Now, CreateDate, CreateTime, and CreateDateTime functions, return date-time objects. ColdFusion creates Open Database Connectivity (ODBC) timestamp values when it converts date-time objects to strings. As a result, you might get unexpected results when using dates with a database driver that does not support ODBC escape sequences, or when you use SQL in a query of queries.

If you use SQL to insert data into a database or in a WHERE clause to select data from a database, and the database driver does not support ODBC-formatted dates, use the

DateFormat

function to convert the date-time value to a valid format for the driver. This rule also applies to queries of queries.

For example, the following SQL statement uses the

DateFormat function in a query of queries to

select rows that have MyDate values in the future:

<cfquery name="MyQofQQ" dbtype="query"> SELECT * FROM DateQuery WHERE MyDate >= '#DateFormat(Now())#' </cfquery>

The following query of queries fails with the error message “Error: {ts is not a valid date,” because the ColdFusion

<cfquery name="MyQofQQ" dbtype="query"> SELECT * FROM DateQuery WHERE MyDate >= '#now()#' </cfquery>

Now function returns an ODBC timestamp:

Using JavaCast with overloaded Java methods

You can overload Java methods so a class can have several identically named methods that differ only in parameter data types. At runtime, the Java virtual machine attempts to resolve the specific method to use, based on the types of the parameters passed in the call. Because ColdFusion does not use explicit types, you cannot predict which version of the method the virtual machine will use.

The ColdFusion

JavaCast function helps you ensure that the right method executes by

specifying the Java type of a variable, as in the following example:

The JavaCast function takes two parameters: a string representing the Java data type and the variable whose type you are setting. You can specify the following Java data types: bool, int, long, float, double, and String.

For more information on the

JavaCast function, see CFML Reference.

Data type conversion 63

Using quotation marks

To ensure that ColdFusion properly interprets string data, surround strings in single- or doublequotation marks. For example, ColdFusion evaluates “10/2/2001” as a string that can be converted into a date-time object. However, it evaluates 10/2/2001 as a mathematical expression, 5/2001, which evaluates to 0.00249875062469.

Examples of type conversion in expression evaluation

The following examples demonstrate ColdFusion expression evaluation.

Example 1

2 * True + "YES" - ('y' & "es")

Result value as string: "2"

Explanation: (2*True) is equal to 2; ("YES"- "yes") is equal to 0; 2 + 0 equals 2.

Example 2

"Five is " & 5

Result value as string: "Five is 5"

Explanation: 5 is converted to the string "5".

Example 3

DateFormat("October 30, 2001" + 1)

Result value as string: "31-Oct-01"

Explanation: The addition operator forces the string "October 30, 2001" to be converted to a date-time object, and then to a number. The number is incremented by one. The DateFormat function requires its argument to be a date-time object; thus, the result of the addition is converted to a date-time object. One is added to the date-time object, moving it ahead by one day to October 31, 2001.

About scopes

Variables differ in how they are set (by your code or by ColdFusion), the places in your code where they are meaningful, and how long their values persist. These considerations are generally referred to as a variable’s scope. Commonly used scopes include the Variables scope, the default scope for variables that you create, and the Request scope, which is available for the duration of an HTTP request.

Note: User-defined functions also belong to scopes. For more information, see Chapter 9,

“Specifying the scope of a function,” on page 194.

64 Chapter 3: Using ColdFusion Variables

Scope types

The following table describes ColdFusion scopes:

Scope Description

Variables (local)

Form Contains variables passed from a Form page to its action page as the result of

URL Contains parameters passed to the current page in the URL that is used to call it.

Attributes Used only in custom tag pages. Contains the values passed by the calling page in

Caller Used only in custom tag pages. The custom tag’s Caller scope is a reference to the

ThisTag Used only in custom tag pages. The ThisTag scope is active for the current

Request Used to hold data that must be available for the duration of one HTTP request. The

CGI Contains environment variables identifying the context in which a page was

The default scope for variables of any type that are created with the

cfparam tags. A local variable is available only on the page on which it is created and

cfset and

any included pages (see also the Caller scope).

submitting the form. (If you use the HTML

form tag, you must use method="post".)

For more information, see Chapter 26, “Introduction to Retrieving and Formatting

Data,” on page 609.

The parameters are appended to the URL in the format ?variablename = value[&variablename=value...]; for example www.MyCompany.com/ inputpage.cfm?productCode=A12CD1510&quantity=3.

Note: If a URL includes multiple parameters with the same name, the resulting variable in the ColdFusion URL scope consists of all parameter values separated by commas. For example, a URL of the form http://localhost/urlparamtest.cfm? param=1¶m=2¶m=3 results in a URL.param variable value of 1,2,3 on the ColdFusion page.

the custom tag’s attributes. For more information, see Chapter 11, “Creating and

Using Custom CFML Tags,” on page 241.

calling page’s Variables scope. Any variables that you create or change in the custom tag page using the Caller scope are visible in the calling page’s Variables scope. For more information, see Chapter 11, “Creating and Using Custom CFML

Tags,” on page 241.

invocation of the tag. If a custom tag contains a nested tag, any ThisTag scope values you set before calling the nested tag are preserved when the nested tag returns to the calling tag. The ThisTag scope includes three built-in variables that identify the tag’s execution mode, contain the tag’s generated contents, and indicate whether the tag has an end tag.

A nested custom tag can use the

cfassociate tag to return values to the calling tag’s

ThisTag scope. For more information, see “Accessing tag instance data”

on page 250.

Request scope is available to all pages, including custom tags and nested custom tags, that are processed in response to the request. This scope is useful for nested (child/parent) tags. This scope can often be used in place of the Application scope, to avoid the need for locking variables. Several chapters discuss using the Request scope.

requested. The variables available depend on the browser and server software. For a list of the commonly used CGI variables, see Chapter 1, “Reserved Words and Variables,” in CFML Reference.

About scopes 65

Scope Description

Cookie Contains variables maintained in a user’s browser as cookies. Cookies are typically

stored in a file on the browser, so they are available across browser sessions and applications. You can create memory-only Cookie variables, which are not available after the user closes the browser. Cookie scope variable names can include periods.

Client Contains variables that are associated with one client. Client variables let you

maintain state as a user moves from page to page in an application, and are available across browser sessions. By default, Client variables are stored in the system registry, but you can store them in a cookie or a database. Client variables cannot be complex data types and can include periods in their names. For more information, see Chapter 15, “Using Persistent Data and Locking,” on page 339.

Session Contains variables that are associated with one client and persist only as long as the

client maintains a session. They are stored in the server’s memory and can be set to time out after a period of inactivity. For more information, see Chapter 15, “Using

Persistent Data and Locking,” on page 339.

Application Contains variables that are associated with one, named application on a server. The

cfapplication tag name attribute or the Application.cfc This.name variable setting

specifies the application name. For more information, see Chapter 15, “Using

Persistent Data and Locking,” on page 339.

Server Contains variables that are associated with the current ColdFusion server. This

scope lets you define variables that are available to all your ColdFusion pages, across multiple applications. For more information, see Chapter 15, “Using

Persistent Data and Locking,” on page 339.

Flash Variables sent by a Macromedia Flash movie to ColdFusion and returned by

ColdFusion to the movie. For more information, see Chapter 33, “Using the Flash

Remoting Service,” on page 807.

Arguments Variables passed in a call to a user-defined function or ColdFusion component

method. For more information, see “About the Arguments scope” on page 181.

This Exists only in ColdFusion components or

cffunction tags that are part of a

containing object such as a ColdFusion Struct. Exists for the duration of the component instance or containing object. Data in the This scope is accessible from outside the component or container by using the instance or object name as a prefix.

function local Contains variables that are declared inside a user-defined function or ColdFusion

component method and exist only while a function executes. For more information, see Chapter 9, “Writing and Calling User-Defined Functions,” on page 171.

Caution: To prevent data corruption, you lock code that uses Session, Application, or Server scope variables. For more information, see Chapter 15, “Using Persistent Data and Locking,” on page 339.

66 Chapter 3: Using ColdFusion Variables

Creating and using variables in scopes

The following table shows how you create and refer to variables in different scopes in your code. For more information on the mechanisms for creating variables in most scopes, see “Creating

variables” on page 44.

Scope prefix (type)

Variables (Local)

Form No On the action page of a form

URL No On the target page of the

Attributes Yes On the custom tag page. The calling page passing the values

Caller On the custom

ThisTag Yes On the custom tag page. Specifying the prefix ThisTag when

Request Yes On the creating page and in

Prefix

Where available Created by

required to reference

No On the current page. Cannot

be accessed by a form’s action page (unless the form page is also the action page). Variables in this scope used on a page that calls a custom tag can be accessed in the custom tag by using its Caller scope; however, they are not available to any nested custom tags.

and in custom tags called by the action page; cannot be used on a form page that is not also the action page.

URL.

On the custom tag page, by

tag page, Yes. On the calling

page, No (Variables prefix

using the Caller scope prefix. On the page that calls the

custom tag, as local variables (Variables scope).

is optional).

any pages invoked during the current HTTP request after the variable is created, including in custom tags and nested custom tags.

Specifying the prefix Variables, or using no prefix, when you create the variable.

form or cfform tag. Contains the

values of form field tags (such as input) in the form body when the form is submitted. The variable name is the name of the form field.

The system. Contains the parameters passed in the URL query string used to access the page.

to a custom tag page in the custom tag’s attributes.

On the custom tag page, by specifying the prefix Caller when you create the variable.

On the calling page, by specifying the prefix Variables, or using no prefix, when you create the variable.

you create the variable in the tag or using the

cfassociate tag in a

nested custom tag.

Specifying the prefix Request when you create the variable.

About scopes 67

Scope prefix (type)

Prefix required to reference

Where available Created by

CGI No On any page. Values are

specific to the latest browser request.

Cffile Yes Following an invocation of

cffile.

Cookie No For one client in one or more

applications and pages, over multiple browser sessions.

Client No For one client in one

application, over multiple browser sessions.

Session Yes For one client in one

application and one browser session. Surround code that uses Session scope variables in

cflock blocks.

Application Yes For multiple clients in one

application over multiple browser sessions. Surround code that uses application variables in

cflock blocks.

Server Yes To any page on the

ColdFusion server. Surround all code that uses server variables in

cflock blocks.

Flash Yes A ColdFusion page or

ColdFusion component called by a Flash client.

Arguments No Within the body of a user-

defined function or ColdFusion component method.

The web server. Contains the server environment variables that result from the browser request.

cffile tag.

cfcookie tag. You can also set

memory-only cookies by specifying the prefix Cookie when you create the variable.

Specifying the prefix Client when you create the variable.

Specifying the prefix Session when you create the variable.

Specifying the prefix Application when you create the variable.

Specifying the prefix Server when you create the variable.

The ColdFusion Client access. You assign a value to Flash.You can assign values to the Flash.result and Flash.pagesize variables.

The calling page passing an argument in the function call.

68 Chapter 3: Using ColdFusion Variables

Scope prefix (type)

This Yes Within a ColdFusion

(function local, no prefix)

Prefix required to reference

Prohibited Within the body of a user-

Where available Created by

component or the body of a user-defined function that was created using the tag and put in an object, structure, or scope. In the containing page, through the component instance or containing object.

defined function or ColdFusion component method, only while the function executes.

cffunction

Within the component or function by specifying the prefix This when you create the variable.

In the containing page, by specifying the component instance or object that contains the function as a prefix when you create the variable.

In the function or method definition, a

var keyword in a cfset tag or a

CFScript

var statement.

Using scopes

The following sections provide details on how you can create and use variables in different scopes.

Evaluating unscoped variables

If you use a variable name without a scope prefix, ColdFusion checks the scopes in the following order to find the variable:

Function local (UDFs and CFCs only)

Arguments

Variables (local scope)

CGI

Cffile

URL

Form

Client

Because ColdFusion must search for variables when you do not specify the scope, you can improve performance by specifying the scope for all variables.

To access variables in all other scopes, you must prefix the variable name with the scope identifier.

Scopes and CFX tags

ColdFusion scopes do not apply to ColdFusion Extension (CFX) tags, custom tags that you write in a programming language such as C++ or Java. The ColdFusion page that calls a CFX tag must use tag attributes to pass data to the CFX tag. The CFX tag must use the Java Request and Response interfaces or the C++ Request class to get and return data.

About scopes 69

The Java setVariable Response interface method and C++ CCFX::SetVariable method return data to the Variables scope of the calling page. Therefore, they are equivalent to setting a Caller scope variable in a custom ColdFusion tag.

Using scopes as structures

ColdFusion makes all named scopes available as structures. You cannot access the function-local scope for user defined functions (UDFs) that you define using CFScript as a structure. (In ColdFusion 4.5 and 5, the following scopes are not available as structures: Variables, Caller, Client, and Server.)

You can reference the variables in named scopes as elements of a structure. To do so, specify the scope name as the structure name and the variable name as the key. For example, if you have a MyVar variable in the Request scope, you can refer to it in either of the following ways:

Request.MyVar Request["MyVar"]

Similarly, you can use CFML structure functions to manipulate the contents of the scope. For more information on using structures, see Chapter 5, “Using Arrays and Structures,” on page 97.

Caution: Do not call StructClear(Session) to clear session variables. This deletes the SessionID,

CFID, and CFtoken built-in variables, effectively ending the session. If you want to use StructClear to

delete your application variables, put those variables in a structure in the Session scope, and then clear that structure. For example, put all your application variables in Session.MyVars and then call

StructClear(Session.MyVars) to clear the variables.

Ensuring variable existence

ColdFusion generates an error if you try to use a variable value that does not exist. Therefore, before you use any variable whose value is assigned dynamically, you must ensure that a variable value exists. For example, if your application has a form, it must use some combination of requiring users to submit data in fields, providing default values for fields, and checking for the existence of field variable values before they are used.

There are several ways to ensure that a variable exists before you use it, including the following:

• You can use the IsDefined function to test for the variable’s existence.

• You c an u se the cfparam tag to test for a variable and set it to a default value if it does not exist.

• You can use a cfform input tag with a hidden attribute to tell ColdFusion to display a helpful

message to any user who does not enter data in a required field. For more information on this technique, see Chapter 26, “Requiring users to enter values in form fields,” on page 616.

Testing for a variable’s existence

Before relying on a variable’s existence in an application page, you can test to see if it exists by using the

StructKeyExists function.

70 Chapter 3: Using ColdFusion Variables

IsDefined function. To check whether a specific key exists in a structure, use the

For example, if you submit a form with an unsettled check box, the action page does not get a variable for the check box. The following example from a form action page makes sure the Contractor check box Form variable exists before using it:

<cfoutput>Contractor: #Form.Contractor#</cfoutput> </cfif>

You must always enclose the argument passed to the IsDefined function in double-quotation marks. For more information on the

IsDefined function, see CFML Reference.

If you attempt to evaluate a variable that you did not define, ColdFusion cannot process the page and displays an error message. To help diagnose such problems, turn on debugging in the ColdFusion MX Administrator or use the debugger in your editor. The Administrator debugging information shows which variables are being passed to your application pages.

Variable existence considerations

If a variable is part of a scope that is available as a structure, you might get a minor performance increase by testing the variable’s existence using the

IsDefined function.

StructKeyExists function instead of the

You can also determine which Form variables exist by inspecting the contents of the

Form.fieldnames built-in variable. This variable contains a list of all the fields submitted by the

form. Remember, however, that form text fields are always submitted to the action page, and might contain an empty string if the user did not enter data.

The

IsDefined function always returns False if you specify an array or structure element using

bracket notation. For example, element

myArray[3] has a value. To check for the existence of an array element, use cftry, as in

IsDefined("myArray[3]") always returns False, even if the array

the following example:

<cfset items=ArrayNew(2)> <cfset items[1][1] = "Dog"> <cfset items[2][2] = "Cat"> <cftry> <cfset temp=items[1][2]> <cfcatch type="any"> < cfoutput>Items[1][2] does not exist</cfoutput> </cfcatch> </cftry>

Using the cfparam tag

You can ensure that a variable exists by using the

cfparam tag, which tests for the variable’s

existence and optionally supplies a default value if the variable does not exist. The has the following syntax:

<cfparam name="VariableName"

type="data_type" default="DefaultValue">

Note: For information on using the

Reference.

type attribute to validate the parameter data type, see CFML

Ensuring variable existence 71

cfparam tag

There are two ways to use the cfparam tag to test for variable existence, depending on how you want the validation test to proceed:

• With only the name attribute to test that a required variable exists. If it does not exist, the

ColdFusion server stops processing the page and displays an error message.

• With the name and default attributes to test for the existence of an optional variable. If the

variable exists, processing continues and the value is not changed. If the variable does not exist, it is created and set to the value of the

default attribute, and processing continues.

The following example shows how to use the

cfparam tag to check for the existence of an

optional variable and to set a default value if the variable does not already exist:

Example: testing for variables

Using the

cfparam tag with the name attribute is one way to clearly define the variables that a

page or a custom tag expects to receive before processing can proceed. This can make your code more readable, as well as easier to maintain and debug.

For example, the following

cfparam tags indicate that this page expects two form variables named

StartRow and RowsToFetch:

If the page with these tags is called without either one of the form variables, an error occurs and the page stops processing. By default, ColdFusion displays an error message; you can also handle the error as described in Chapter 14, “Handling Errors,” on page 307.

Example: setting default values

The following example uses the

cfparam tag to see if optional variables exist. If they do exist,

processing continues. If they do not exist, the ColdFusion server creates them and sets them to the default values.

You can use the cfparam tag to set default values for URL and Form variables, instead of using conditional logic. For example, you could include the following code on the action page to ensure that a SelectedDepts variable exists:

72 Chapter 3: Using ColdFusion Variables

Validating data

It is often not sufficient that input data merely exists; it must also have the right format. For example, a date field must have data in a date format. A salary field must have data in a numeric or currency format. There are many ways to ensure the validity of data, including the following methods:

• Use the cfparam tag with the type attribute to validate a variable.

• Use the IsValid function to validate a variable.

• Use the cfqueryparam tag in a SQL WHERE clause to validate query parameters.

• Use cfform controls that have validation attributes.

• Use a form input tag with a hidden attribute to validate the contents of a form input field.

Note: Data validation using the cfparam, cfqueryparam, and form tags is done by the server. Validation using any data is sent to the server.

cfform tags and hidden fields is done using JavaScript in the user’s browser, before

For detailed information on validating data in forms and variables, see Chapter 28, “Validating

Data,” on page 659. For detailed information on validating query parameters, see “Using cfqueryparam” on page 473.

Passing variables to custom tags and UDFs

The following sections describe rules for how data gets passed to custom tags and user-defined functions that are written in CFML, and to CFX custom tags that are written in Java or C++.

Passing variables to CFML tags and UDFs

When you pass a variable to a CFML custom tag as an attribute, or to a user-defined function as an argument, the following rules determine whether the custom tag or function receives its own private copy of the variable or only gets a reference to the calling page’s variable:

• Simple variables and arrays are passed as copies of the data. If your argument is an expression

that contains multiple simple variables, the result of the expression evaluation is copied to the function or tag.

• Structures, queries, and cfobject objects are passed as references to the object.

If the tag or function gets a copy of the calling page’s data, changes to the variable in the custom tag or function do not change the value of the variable on the calling page. If the variable is passed by reference, changes to the variable in the custom tag or function also change the value of the variable in the calling page.

To pass a variable to a custom tag, you must enclose the variable name in number signs. To pass a variable to a function, do not enclose the variable name in number signs. For example, the following code calls a user-defined function using three Form variables:

<cfoutput> TOTAL INTEREST: #TotalInterest(Form.Principal, Form.AnnualPercent,

Form.Months)#

</cfoutput>

Passing variables to custom tags and UDFs 73

The following example calls a custom tag using two variables, MyString and MyArray:

<cf_testTag stringval=#MyString# arrayval=#MyArray#>

Passing variables to CFX tags

You cannot pass arrays, structures, or CFX tag by using the

query attribute when calling the tag. ColdFusion normally converts simple

cfobject objects to CFX tags. You can pass a query to a

data types to strings when passing them to CFX tags; however, the Java Request Interface

getIntAttribute method lets you get a passed integer value.

74 Chapter 3: Using ColdFusion Variables

CHAPTER 4

Using Expressions and Number Signs

This chapter discusses how to use expressions in CFML. It discusses the elements of Macromedia ColdFusion expressions and how to create expressions. It also describes the correct use of number signs to indicate expressions in ColdFusion tags such as Finally, it describes how to use variables in variable names and strings to create dynamic expressions, and dynamic variables.

Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75

Using number signs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81

Dynamic expressions and dynamic variables. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84

Expressions

ColdFusion expressions consist of operands and operators. Operands are comprised of constants and variables. Operators, such as the multiplication symbol, are the verbs that act on the operands; functions are a form of operator.

cfoutput, in strings, and in expressions.

The simplest expression consists of a single operand with no operators. Complex expressions have multiple operators and operands. The following are all ColdFusion expressions:

12 MyVariable (1 + 1)/2 "father" & "Mother" Form.divisor/Form.dividend Round(3.14159)

Operators act on the operands. Some operators, such as functions with a single argument, take a single operand. Many operators, including most arithmetic and logical operators, take two operands. The following is the general form of a two-operand expression:

Expression Operator Expression

Note that the operator is surrounded by expressions. Each expression can be a simple operand (variable or constant) or a subexpression consisting of more operators and expressions. Complex expressions are built up using subexpressions. For example, in the expression (1 + 1)/2, 1 + 1 is a subexpression consisting of an operator and two operands.

Operator types

ColdFusion has four types of operators:

• Arithmetic

• Boolean

• Decision (or comparison)

• String

Functions also can be viewed as operators because they act on operands.

Arithmetic operators

The following table describes the arithmetic operators:

Operator Description

+ - * / Basic arithmetic: Addition, subtraction, multiplication, and division. In division, the right

operand cannot be zero.

+ - Unary arithmetic: Set the sign of a number.

MOD Modulus: Return the remainder after a number is divided by a divisor. The result has the

same sign as the divisor. The right should be an integer; using a non-numeric value causes an error, and if you specify a real number, ColdFusion ignores the fractional part (for example, 11 MOD 4 is 3).

\ Integer division: Divide an integer by another integer. Use the backslash character (\) to

^ Exponentiation: Return the result of a number raised to a power (exponent). Use the

separate the integers. The right operand cannot be zero. For example, 9\4 is 2.

caret character (^) to separate the number from the power; for example, 2^3 is 8. Real and negative numbers are allowed for both the base and the exponent. However, any expression that equates to an imaginary number, such -1^.5 results in the string "-1.#IND. ColdFusion does not support imaginary or complex numbers.

Boolean operators

Boolean, or logical, operators perform logical connective and negation operations. The operands of Boolean operators are Boolean (True/False) values. The following table describes the Boolean operators:

Operator Description

NOT Reverse the value of an argument. For example, NOT True is False and vice versa.

AND Return True if both arguments are True; return False otherwise. For example, True AND

76 Chapter 4: Using Expressions and Number Signs

True is True, but True AND False is False.

Operator Description

OR Return True if any of the arguments is True; return False otherwise. For example, True

XOR Exclusive or: Return True if one of the values is True and the other is False. Return False

EQV Equivalence: Return True if both operands are True or both are False. The EQV operator

IMP Implication: The statement A IMP B is the equivalent of the logical statement “If A Then

OR False is True, but False OR False is False.

if both arguments are True or both are False. For example, True XOR True is False, but True XOR False is True.

is the opposite of the XOR operator. For example, True EQV True is True, but True EQV False is False.

B.” A IMP B is False only if A is True and B is False. It is True in all other cases.

Decision operators

The ColdFusion decision, or comparison, operators produce a Boolean True/False result. The following table describes the decision operators:

Operator Description

IS Perform a case-insensitive comparison of two values. Return

True if the values are identical.

IS NOT Opposite of IS. Perform a case-insensitive comparison of two

CONTAINS Return True if the value on the left contains the value on the

DOES NOT CONTAIN Opposite of CONTAINS. Return True if the value on the left

GREATER THAN Return True if the value on the left is greater than the value on

LESS THAN Opposite of GREATER THAN. Return True if the value on the

GREATER THAN OR EQUAL TO Return True if the value on the left is greater than or equal to

LESS THAN OR EQUAL TO Return True if the value on the left is less than or equal to the

values. Return True if the values are not identical.

right.

does not contain the value on the right.

the right.

left is smaller than the value on the right.

the value on the right.

value on the right.

Alternative notation for decision operators

You can replace some decision operators with alternative notations to make your CFML more compact, as shown in the following table:

Operator Alternative name(s)

IS EQUAL, EQ

IS NOT NOT EQUAL, NEQ

GREATER THAN GT

Expressions 77

Operator Alternative name(s)

LESS THAN LT

GREATER THAN OR EQUAL TO GTE, GE

LESS THAN OR EQUAL TO LTE, LE

Decision operator rules

The following rules apply to decision operators:

• When ColdFusion evaluates an expression that contains a decision operator other than

CONTAINS or DOES NOT CONTAIN, it first determines if the data can be converted to numeric values. If they can be converted, it performs a numeric comparison on the data. If they cannot be converted, it performs a string comparison. This can sometimes result in unexpected results. For more information on this behavior, see “Evaluation and type

conversion issues” on page 61.

• When ColdFusion evaluates an expression with CONTAINS or DOES NOT CONTAIN it

does a string comparison. The expression A CONTAINS B evaluates to True if B is a substring of A. Therefore an expression such as the following evaluates as True:

123.45 CONTAINS 3.4

• When a ColdFusion decision operator compares strings, it ignores the case. As a result, the

following expression is True:

"a" IS "A"

• When a ColdFusion decision operator compares strings, it evaluates the strings from left to

right, comparing the characters in each position according to their sorting order. The first position where the characters differ determines the relative values of the strings. As a result, the following expressions are True:

"ab" LT "aba" "abde" LT "ac"

String operators

There is one string operator, which is the concatenation operator.

Operator Description

& Concatenates strings.

Note: In a Query of Queries, you use || as the concatenation operator.

78 Chapter 4: Using Expressions and Number Signs

Operator precedence and evaluation ordering

The order of precedence controls the order in which operators in an expression are evaluated. The order of precedence is as follows:

Unary +, Unary ^ *, / \ MOD +, & EQ, NEQ, LT, LTE, GT, GTE, CONTAINS, DOES NOT CONTAIN NOT AND OR XOR EQV IMP

To enforce a 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

You can nest parenthesized expressions. When in doubt about the order in which operators in an expression will be evaluated, use parentheses to force the order of evaluation.

Using functions as operators

Functions are a form of operator. Because ColdFusion functions return values, you can use function results as operands. Function arguments are expressions. For example, the following are valid expressions:

• Rand()

• UCase("This is a text: ") & ToString(123 + 456)

Function syntax

The following table shows function syntax and usage guidelines:

Usage Example

No arguments

Basic format

Nested functions

Multiple arguments

String arguments

Arguments that are expressions

Function()

Function(Data)

Function1(Function2(Data))

Function(Data1, Data2, Data3) Function('This is a demo')

Function("This is a demo")

Function1(X*Y, Function2("Text"))

Expressions 79

All functions return values. In the following example, the cfset tag sets a variable to the value returned by the

Now function:

You can use the values returned by functions directly to create more complex expressions, as in the following example:

Abs(Myvar)/Round(3.14159)

For more information on how to insert functions in expressions, see “Using number signs”

on page 81.

Optional function arguments

Some functions take optional arguments after their required arguments. If omitted, all optional arguments default to a predefined value. For example:

• Replace("Eat and Eat", "Eat", "Drink") returns "Drink and Eat"

• Replace("Eat and Eat", "Eat", "Drink", "All") returns "Drink and Drink"

The difference in the results is because the

Replace function takes an optional fourth argument

that specifies the scope of replacement. The default value is “One,” which explains why only the first occurrence of “Eat” was replaced with “Drink” in the first example. In the second example, a fourth argument causes the function to replace all occurrences of “Eat” with “Drink”.

Expression evaluation and functions

It is important to remember that ColdFusion evaluates function attributes as expressions before it executes the function. As a result, you can use any ColdFusion expression as a function attribute. For example, consider the following lines:

When ColdFusion server executes the second line, it does the following:

Determines that there is an expression with a string concatenation.

Evaluates the firstVariable variable as the string "we all need".

Concatenates "we all need" with the string " more sleep!" to get "we all need more sleep!".

Passes the string "we all need more sleep!" to the UCase function.

Executes the UCase function on the string argument "we all need more sleep!" to get "WE ALL NEED MORE SLEEP!".

Assigns the string value "WE ALL NEED MORE SLEEP!" to the variable myStringVar.

ColdFusion completes steps 1-3 before invoking the function.

80 Chapter 4: Using Expressions and Number Signs

Using number signs

Number signs (#) have a special meaning in CFML. When the ColdFusion server encounters number signs in CFML text, such as the text in a

cfoutput tag body, it checks to see if the text

between the number signs is either a variable or a function.

Tip: Number signs are also called pound signs.

Is so, it replaces the text and surrounding number signs with the variable value or the result of the function. Otherwise, ColdFusion generates an error.

For example, to output the current value of a variable named

Form.MyFormVariable, you delimit

(surround) the variable name with number signs:

<cfoutput>Value is #Form.MyFormVariable#</cfoutput>

In this example, the variable Form.MyFormVariable is replaced with the value assigned to it.

Follow these guidelines when using number signs:

• Use number signs to distinguish variables or functions from plain text.

• Surround only a single variable or function in number signs; for example, #Variables.myVar#

or #Left(myString, position)#. (However, a function in number signs can contain nested functions, such as #Left(trim(myString), position)#.

• Do not put complex expressions, such as 1 + 2 in number signs. Although this is allowed in

a cfoutput block, such as <cfoutput>One plus one is #1 + 1#</cfoutput>, doing so mixes logic and presentation.

• Use number signs only where necessary, because unneeded number signs slow processing.

The following sections provide more details on how to use number signs in CFML. For a description of using number signs to create variable names, see “Using number signs to construct

a variable name in assignments” on page 85.

Using number signs in ColdFusion tag attribute values

You can put variables, functions, or expressions inside tag attributes by enclosing the variable or expression with number signs. For example, if the variable CookieValue has the value "MyCookie", the following line sets the

cfcookie value attribute to "The value is MyCookie":

You can optionally omit quotation marks around variables used as attribute values as shown in the following example:

However, surrounding all attribute values in quotation marks is more consistent with HTML coding style.

If you use string expressions to construct an attribute value, as shown in the following example, the strings inside the expression use single quotation marks (') to differentiate the quotation marks from the quotation marks that surround the attribute value.

Using number signs 81

Note: You do not need to use number signs when you use the cfset tag to assign one variable’s value to another value. For example, the following tag assigns the value of the variable,

newVar: <cfset newVar = oldVar>.

oldVar variable to the new

Using number signs in tag bodies

You can put variables or functions freely inside the bodies of the following tags by enclosing each variable or expression with number signs:

• cfoutput

• cfquery

• cfmail

For example:

Value is #Form.MyTextField#

</cfoutput>

The name is #FirstName# #LastName#.

</cfoutput>

The value of Cos(0) is #Cos(0)#

</cfoutput>

If you omit the number signs, the text, rather than the value, appears in the output generated by the

cfoutput statement.

Two expressions inside number signs can be adjacent to one another, as in the following example:

"Mo" and "nk" is #Left("Moon", 2)##Mid("Monkey", 3, 2)#

</cfoutput>

This code displays the following text:

"Mo" and "nk" is Monk

ColdFusion does not interpret the double number sign as an escaped # character.

Using number signs in strings

You can put variables or functions freely inside strings by enclosing each variable or expression with number signs; for example:

ColdFusion automatically replaces the text with the value of the variable or the value returned by the function. For example, the following pairs of

82 Chapter 4: Using Expressions and Number Signs

cfset statements produce the same result:

If number signs are omitted inside the string, the text, rather than the value, appears in the string. For example, the following pairs of

cfset statements produce the same result:

As with the cfoutput statement, two expressions can be adjacent to each other in strings, as in the following example:

The double-quotation marks around "Moon" and "Monkey" do not need to be escaped (as in ""Moon"" and ""Monkey""). This is because the text between the number signs is treated as an expression; it is evaluated before its value is inserted inside the string.

Nested number signs

In a few cases, you can nest number signs in an expression. The following example uses nested number signs:

<cfset Sentence = "The length of the full name is

#Len("#FirstName# #LastName#")#">

In this example, number signs are nested so that the values of the variables FirstName and LastName are inserted in the string whose length the

Len function calculates.

Nested number signs imply a complex expression that can typically be written more clearly and efficiently without the nesting. For example, you can rewrite the preceding code example without the nested number signs, as follows:

<cfset Sentence2 = "The length of the full name is #Len(FirstName & " "

& LastName)#">

The following achieves the same results and can further improve readability:

<cfset FullName = "#FirstName# #LastName#"> <cfset Sentence = "The length of the full name

is #Len(FullName)#">

A common mistake is to put number signs around the arguments of functions, as in:

These statements result in errors. As a general rule, never put number signs around function arguments.

Using number signs in expressions

Use number signs in expressions only when necessary, because unneeded number signs reduce clarity and can increase processing time. The following example shows the preferred method for referencing variables:

Using number signs 83

In contrast, the following example uses number signs unnecessarily and is less efficient than the previous statement:

Dynamic expressions and dynamic variables

This section discusses the advanced topics of dynamic expressions, dynamic evaluation, and dynamic variable naming. Many ColdFusion programmers never encounter or need to use dynamic expressions. However, dynamic variable naming is important in situations where the variable names are not known in advance, such as in shopping cart applications.

This section also discusses the use of the expressions. This function dynamically evaluates its arguments, and you must often use the function to prevent the evaluation. For more information on using the

the IIF function” on page 90

Note: This section uses several tools and techniques that are documented in later chapters. If you are unfamiliar with using ColdFusion forms, structures, and arrays, you should learn about these tools before reading this section.

About dynamic variables

Dynamic variables are variables that are named dynamically, typically by creating a variable name from a static part and a variable part. For example, the following example dynamically constructs the variable name from a variable prefix and a static suffix:

Using dynamic variables in this manner does not require dynamic evaluation.

IIf function, which is most often used without dynamic

IIF function, see “Using

About dynamic expressions and dynamic evaluation

In a dynamic expression, the actual expression, not just its variable values, is determined at execution time. In other words, in a dynamic expression the structure of the expression, such as the names of the variables, not just the values of the variables, gets built at runtime.

You create dynamic expressions using string expressions, which are expressions contained in strings, (that is, surrounded with quotation marks). Dynamic evaluation is the process of evaluating a string expression. The

Evaluate and IIf functions, and only these functions, perform dynamic

evaluation.

When ColdFusion performs dynamic evaluation it does the following:

Takes a string expression and treats it as a standard expression, as if the expression was not a string.

Parses the expression to determine the elements of the expression and validate the expression syntax.

Evaluates the expression, looking up any variables and replacing them with their values, calling any functions, and performing any required operations.

84 Chapter 4: Using Expressions and Number Signs

This process enables ColdFusion to interpret dynamic expressions with variable parts. However, it incurs a substantial processing overhead.

Dynamic expressions were important in early versions of ColdFusion, before it supported arrays and structures, and they still can be useful in limited circumstances. However, the ability to use structures and the ability to use associative array notation to access structure elements provide more efficient and easier methods for dynamically managing data. For information on using arrays and structures, see Chapter 5, “Using Arrays and Structures,” on page 97.

Selecting how to create variable names

The following two examples describes cases when you need dynamic variable names:

• Form applications where the number and names of fields on the form vary dynamically. In this

case, the form posts only the names and values of its fields to the action page. The action page does not know all the names of the fields, although it does know how the field names (that is, the variable names) are constructed.

• If the following are true:

■ ColdFusion calls a custom tag multiple times.

■ The custom tag result must be returned to different variables each time.

■ The calling code can specify the variable in which to return the custom tag result.

In this case, the custom tag does not know the return variable name in advance, and gets it as an attribute value.

In both cases, it might appear that dynamic expressions using the to construct the variable names. However, you can achieve the same ends more efficiently by using dynamic variable naming, as shown in “Example: a dynamic shopping cart” on page 92.

Evaluate function are needed

This does not mean that you must always avoid dynamic evaluation. However, given the substantial performance costs of dynamic evaluation, you should first ensure that one of the following techniques cannot serve your purpose:

• An array (using index variables)

• Associative array references containing expressions to access structure elements

• Dynamically generated variable names

Dynamic variable naming without dynamic evaluation

While ColdFusion does not always allow you to construct a variable name in-line from variable pieces, it does let you to do so in the most common uses, as described in the following sections.

Using number signs to construct a variable name in assignments

You can combine text and variable names to construct a variable name on the left side of a assignment. For example, the following code sets the value of the variable Product12 to the string "Widget":

Dynamic expressions and dynamic variables 85

cfset

To construct a variable name this way, all the text on the left side of the equal sign must be in quotation marks.

This usage is less efficient than using arrays. The following example has the same purpose as the previous one, but requires less processing:

Dynamic variable limitation

When you use a dynamic variable name in quotation marks on the left side of an assignment, the name must be either a simple variable name or a complex name that uses object.property notation (such as MyStruct.#KeyName#). You cannot use an array as part of a dynamic variable name. For example, the following code generates an error:

However, you can construct an array index value dynamically from variables without using quotation marks on the left side of an assignment. For example, the preceding sample code works if you replace the final line with the following line:

Dynamically constructing structure references

The ability to use associative array notation to reference structures provides a way for you to use variables to dynamically create structure references. (For a description of associative array notation, see “Structure notation” on page 109.) Associative array structure notation allows you to use a ColdFusion expression inside the index brackets. For example, if you have a productName structure with keys of the form product_1, product_2 and so on, you can use the following code to display the value of productName.product_3:

Product_3 Name: #ProductName["product_" & prodNo]#

For an example of using this format to manage a shopping cart, see “Example: a dynamic

shopping cart” on page 92.

86 Chapter 4: Using Expressions and Number Signs

Using dynamic evaluation

The following sections describe how to use dynamic evaluation and create dynamic expressions.

ColdFusion dynamic evaluation functions

The following table describes the functions that perform dynamic evaluation and are useful in evaluating dynamic expressions:

Function Purpose

DE Escapes any double-quotation marks in the argument and wraps the result in

double-quotation marks. The function, to prevent the function from evaluating a string to be output.

For an example of using the

function” on page 90.

Evaluate Takes one or more string expressions and dynamically evaluates their contents

as expressions from left to right. (The results of an evaluation to the left can have meaning in an expression to the right.) Returns the result of evaluating the rightmost argument.

For more information on this function see “About the Evaluate function”

on page 88.

IIf Evaluates a boolean condition expression. Depending on whether this

expression is True or False, dynamically evaluates one of two string expressions and returns the result of the evaluation. The incorporating a

For an example of using this function, see “Using the IIF function” on page 90.

SetVariable Sets a variable identified by the first argument to the value specified by the

second argument. This function is no longer required in well-formed ColdFusion pages; see “SetVariable function considerations” on page 90.

cfif tag in-line in HTML.

DE function is particularly useful with the IIF

DE function with the IIF function, see “Using the IIF

IIF function is convenient for

Function argument evaluation considerations

It is important to remember that ColdFusion always evaluates function arguments before the argument values are passed to a function:

For example, consider the following

DE function:

You might expect this line to display """1"" & ""2""". Instead, it displays “12”, because ColdFusion processes the line as follows:

Evaluates the expression "1" & "2" as the string “12”.

Passes the string "12" (without the quotation marks) to the DE function.

Calls the DE function, which adds literal quotation marks around the 12.

Similarly, if you use the expression DE(1 + 2), ColdFusion evaluates 1 + 2 as the integer 3 and passes it to the function. The function converts it to a string and surrounds the string in literal quotation marks: “3”.

Dynamic expressions and dynamic variables 87

About the Evaluate function

The

Evaluate function takes one or more string expressions, dynamically evaluates their contents

as expressions from left to right, and returns the result of evaluating the rightmost argument.

The following example shows the

Evaluate function and how it works with ColdFusion variable

processing:

#myVar2# #myVar# #Evaluate("myVar2")# #Evaluate("myVar")# #Evaluate(myVar2)# #Evaluate(myVar)#

</cfoutput>

Reviewing the code

The following table describes how ColdFusion processes this code:

Code Description

#myVar2# #myVar#

#Evaluate("myVar2")#

#Evaluate("myVar")#

#Evaluate(myVar2)#

#Evaluate(myVar)# </cfoutput>

Sets the two variables to the following strings: myVar 27/9

Displays the values assigned to the variables, myVar and 27/9, respectively.

Passes the string "myvar2" (without the quotation marks) to the Evaluate function, which does the following:

1 Evaluates it as the variable myVar2. 2 Returns the value of the myVar2 variable, the string "myvar" (without the quotation marks).

Passes the string "myvar" (without the quotation marks) to the Evaluate function, which does the following: 1 Evaluates it as the variable myVar.

2 Returns the value of the myVar variable, the string "27/9" (without the quotation marks).

Evaluates the variable myVar2 as the string "myVar" and passes the string (without the quotation marks) to the Evaluate function. The rest of the processing is the same as in the previous line.

Evaluates the variable myVar as the string "27/9" (without the quotation marks), and passes it to the Evaluate function, which does the following:

1 Evaluates the string as the expression 27/9 2 Performs the division. 3 Returns the resulting value, 3

88 Chapter 4: Using Expressions and Number Signs

As you can see, using dynamic expressions can result in substantial expression evaluation overhead, and the code can be confusing. Therefore, you should avoid using dynamic expressions wherever a simpler technique, such as using indexed arrays or structures can serve your purposes.

Avoiding the Evaluate function

Using the The following sections provide examples of cases where you might consider using the

Evaluate function increases processing overhead, and in most cases it is not necessary.

Evaluate

function.

Example 1

You might be inclined to use the Evaluate function in code such as the following:

<cfoutput>1 + 1 is #Evaluate(1 + 1)#</cfoutput>

Although this code works, it is not as efficient as the following code:

<cfset Result = 1 + 1> <cfoutput>1 + 1 is #Result#</cfoutput>

Example 2

This example shows how you can use an associative array reference in place of an Evaluate function. This technique is powerful because:

• Most ColdFusion scopes are accessible as structures.

• You can use ColdFusion expressions in the indexes of associative array structure references.

(For more information on using associative array references for structures, see “Structure

notation” on page 109.)

The following example uses the

<cfoutput> Product Name: #Evaluate("Form.product_#i#")# </cfoutput>

This code comes from an example where a form has entries for an indeterminate number of items in a shopping cart. For each item in the shopping cart there is a product name field. The field name is of the form product_1, product_2, and so on, where the number corresponds to the product’s entry in the shopping cart. In this example, ColdFusion does the following:

Replaces the variable i with its value, for example 1.

concatenates the variable value with "Form.product_", and passes the result (for Form.product_1) to the

Parses the variable product_1 and generates an executable representation of the variable. Because ColdFusion must invoke its parser, this step requires substantial processing, even for a simple variable.

Evaluates the representation of the variable, for example as "Air popper".

Returns the value of the variable.

Evaluate function to construct a variable name:

Evaluate function, which does the remaining steps.

Dynamic expressions and dynamic variables 89

The following example has the same result as the preceding example and is more efficient:

<cfoutput> ProductName: #Form["product_" & i]# </cfoutput>

In this code, ColdFusion does the following:

Evaluates the expression in the associative array index brackets as the string "product_" concatenated with the value of the variable i.

Determines the value of the variable i; 1.

Concatenates the string and the variable value to get product_1.

Uses the result as the key value in the Form structure to get Form[product_1]. This associative array reference accesses the same value as the object.attribute format reference Form.product_1; in this case, Air popper.

This code format does not use any dynamic evaluation, but it achieves the same effect, of dynamically creating a structure reference by using a string and a variable.

SetVariable function considerations

You can avoid using the

SetVariable function by using a format such as the following to set a

dynamically named variable. For example, the following lines are equivalent:

In the second line, enclosing the myVar#i# variable name in quotation marks tells ColdFusion to evaluate the name and process any text in number signs as a variable or function. ColdFusion replaces the #i# with the value of the variable i, so that if the value of i is 12, this code is equivalent to the line

For more information on this usage, see “Using number signs to construct a variable name in

assignments” on page 85.

Using the IIF function

IIf function is a shorthand for the following code:

The

</cfif>

The function returns the value of the result variable. It is comparable to the use of the JavaScript and Java ? : operator, and can result in more compact code. As a result, the

IIF function can be

convenient even if you are not using dynamic expressions.

90 Chapter 4: Using Expressions and Number Signs

The IIF function requires the DE function to prevent ColdFusion from evaluating literal strings, as the following example shows:

<cfoutput> #IIf(IsDefined("LocalVar"), "LocalVar", DE("The variable is not

defined."))#

</cfoutput>

If you do not enclose the string "The variable is not defined." in a DE function, the IIF function tries to evaluate the contents of the string as an expression and generates an error (in this case, an invalid parser construct error).

The

IIF function is useful for incorporating ColdFusion logic in-line in HTML code, but it

entails a processing time penalty in cases where you do not otherwise need dynamic expression evaluation.

The following example shows using and gray. It also shows the use of the

IIF to alternate table row background color between white DE function to prevent ColdFusion from evaluating the color

strings.

<td>

hello #i#

</td> </tr>

</cfloop> </table> </cfoutput>

This code is more compact than the following example, which does not use IIF or DE:

<td>

hello #i#

</td> </tr>

</cfloop> </table> </cfoutput>

Dynamic expressions and dynamic variables 91

Example: a dynamic shopping cart

The following example dynamically creates and manipulates variable names without using dynamic expression evaluation by using associative array notation.

You need to dynamically generate variable names in applications such as shopping carts, where the required output is dynamically generated and variable. In a shopping cart, you do not know in advance the number of cart entries or their contents. Also, because you are using a form, the action page only receives Form variables with the names and values of the form fields.

The following example shows the shopping cart contents and lets you edit your order and submit it. To simplify things, the example automatically generates the shopping cart contents using CFScript instead of having the user fill the cart. A more complete example would populate a shopping cart as the user selected items. Similarly, the example omits all business logic for committing and making the order.

To create the form:

Create a file in your editor.

<title>Shopping Cart</title> </head> <cfscript> CartItems=4; Cart = ArrayNew(1); for ( i=1; i LE cartItems; i=i+1) {

Cart[i]=StructNew();

Cart[i].ID=i;

Cart[i].Name="Product " & i;

Cart[i].SKU=i*100+(2*i*10)+(3*i);

Cart[i].Qty=3*i-2; } </cfscript>

<body> Your shopping cart has the following items. You can change your order quantities. If you don't want any item, clear the item's check box. When you are ready to order, click submit. <cfform name="ShoppingCart" action="ShoppingCartAction.cfm" method="post"> <table>

<tr>

<td>Order?</td>

<td>Product</td>

<td>Quantity</td>

</tr>

92 Chapter 4: Using Expressions and Number Signs

<cfset qtyname= "qty_" & Cart[i].ID> <td><cfinput type="checkbox" name="itemID" value="#Cart[i].ID#"

checked>

</td>

<td><cfinput type="text" name="#productName#" value="#Cart[i].Name#"

passThrough = "readonly = 'True'"></td>

<td><cfinput type="text" name="#skuName#" value="#Cart[i].SKU#"

passThrough = "readonly = 'True'"></td>

</td>

</tr>

</cfloop> </table> <input type="submit" name="submit" value="submit"> </cfform>

</body> </html>

Save the page as ShoppingCartForm.cfm.

Reviewing the code

The following table describes the code:

Code Description

<cfscript> CartItems=4; Cart = ArrayNew(1); for ( i=1; i LE #cartItems#; i=i+1) {

Cart[i]=StructNew(); Cart[i].ID=i; Cart[i].Name="Product " & i; Cart[i].SKU=i*100+(2*i*10)+(3*i);

Cart[i].Qty=3*i-2; } </cfscript>

<cfform name="ShoppingCart"

action="ShoppingCartAction.cfm" method="post">

<table>

<tr>

<td>Order?</td> <td>Product</td> <td>Code</td> <td>Quantity</td>

</tr>

Create a shopping cart as an array of structures, with each structure containing the cart item ID, product name, SKU number, and quantity ordered for one item in the cart. Populate the shopping cart by looping CartItems times and setting the structure variables to arbitrary values based on the loop counter. A real application would set the Name, SKU, and Quantity values on other pages.

Start the form and its embedded table. When the user clicks the submit button, post the form data to the ShoppingCartAction.cfm page.

The table formats the form neatly. The first table row contains the column headers. Each following row has the data for one cart item.

Dynamic expressions and dynamic variables 93

Code Description

<cfloop index="i" from="1"

to="#cartItems#">

<tr>

<cfset productName= "product_" &

Cart[i].ID> <cfset skuName= "sku_" & Cart[i].ID> <cfset qtyname= "qty_" & Cart[i].ID> <td><cfinput type="checkbox"

name="itemID" value="#Cart[i].ID#"

checked> </td> <td><cfinput type="text"

name="#productName#"

value="#Cart[i].Name#"

passThrough = "readonly = 'True'"> </td>

<td><cfinput type="text"

name="#skuName#"

value="#Cart[i].SKU#"

passThrough = "readonly = 'True'"> </td>

<td><cfinput type="text"

name="#qtyName#"

value="#Cart[i].Qty#"> </td>

</tr> </cfloop> </table>

<input type="submit" name="submit"

value="Submit"> </form>

Loop through the shopping cart entries to generate the cart form dynamically. For each loop, generate variables used for the form field name attributes by appending the cart item ID (Cart[i].ID) to a field type identifier, such as "sku_".

Use a single name, "itemID", for all check boxes. This way, the itemID value posted to the action page is a list of all the check box field values. The check box field value for each item is the cart item ID.

Each column in a row contains a field for a cart item structure entry. The product name and SKU fields to read-only; note the use of single-quotation marks. (For more information on the attribute, see CFML Reference.) The check boxes are selected by default.

Create the Submit button and end the form.

passthrough attribute sets the

cfinput tag passthrough

To create the Action page:

Create a file in your editor.

Enter the following text:

<title>Your Order</title> </head> <body> <cfif isDefined("Form.submit")>

You have ordered the following items: <cfloop index="i" list="#Form.itemID#">

ProductName: #Form["product_" & i]# Product Code: #Form["sku_" & i]# Quantity: #Form["qty_" & i]#

</cfloop>

</cfoutput> </cfif> </body> </html>

94 Chapter 4: Using Expressions and Number Signs

Save the file as ShoppingCartAction.cfm

Open ShoppingCartform.cfm in your browser, change the check box and quantity values, and click Submit.

Reviewing the code

The following table describes the code:

Code Description

<cfparam name="Form.itemID"

default="">

<cfoutput> You have ordered the following

items:

<cfloop index="i" list=

"#Form.itemID#">

ProductName:

#Form["product_" & i]#

Product Code:

#Form["sku_" & i]#

Quantity:

#Form["qty_" & i]#

</cfloop> </cfoutput> </cfif>

Run the CFML on this page only if it is called by submitting a form. This is not needed if there are separate form and action pages, but is required if the form and action page were one ColdFusion page.

Set the default Form.itemID to the empty string. This prevents ColdFusion from displaying an error if the user clears all check boxes before submitting the form (so no product IDs are submitted).

Display the name, SKU number, and quantity for each ordered item.

The form page posts Form.itemID as a list containing the value attributes of all the check boxes. These attributes contain the shopping cart item IDs for the selected cart items. Use the list values to index a loop that outputs each ordered item.

Use associative array notation to access the Form scope as a structure and use expressions in the array indexes to construct the form variable names. The expressions consist of a string containing the field name’s field type prefix (for example, "sku_"), concatenated with the variable i, which contains the shopping cart ItemID number (which is also the loop index variable).

Dynamic expressions and dynamic variables 95

96 Chapter 4: Using Expressions and Number Signs

CHAPTER 5

Using Arrays and Structures

Macromedia ColdFusion supports dynamic multidimensional arrays. This chapter explains the basics of creating and handling arrays. It also provides several examples showing how arrays can enhance your ColdFusion application code.

ColdFusion also supports structures for managing lists of key-value pairs. Because structures can contain other structures or complex data types as it values, they provide a flexible and powerful tool for managing complex data. This chapter explains the basics of creating and working with structures.

About arrays. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97

Basic array techniques . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100

Populating arrays with data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105

Array functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108

About structures. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108

Creating and using structures. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111

Structure examples. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117

Structure functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121

About arrays

Traditionally, an array is a tabular structure used to hold data, much like a spreadsheet table with clearly defined limits and dimensions.

In ColdFusion, you typically use arrays to temporarily store data. For example, if your site lets users order goods online, you can store their shopping cart contents in an array. This lets you make changes easily without committing the information, which the user can change before completing the transaction, to a database.

Basic array concepts

The following terms will help you understand subsequent discussions of ColdFusion arrays:

• Array dimension The relative complexity of the array structure.

• Index The position of an element in a dimension, ordinarily surrounded by square brackets:

my1Darray[1], my2Darray[1][1], my3Darray[1][1][1].

• Array element Data stored at an array index.

The simplest array is a one-dimensional array, similar to a row in a table. A one-dimensional array has a name (the variable name) and a numerical index. The index number references a single entry, or cell, in the array, as the following figure shows:

Thus, the following statement sets the value of the fifth entry in the one-dimensional array MyArray to “Robert”:

A basic two-dimensional (2D) array is like a simple table. A three-dimensional (3D) array is like a cube of data, and so on. ColdFusion lets you directly create arrays with up to three dimensions. You can use multiple statements to create arrays with more than three dimensions.

The syntax

my2darray[1][3]="Paul" is the same as saying 'My2dArray is a two-dimensional

array and the value of the array element index [1][3] is "Paul"'.

About ColdFusion arrays

ColdFusion arrays differ from traditional arrays, because they are dynamic. For example, in a conventional array, array size is constant and symmetrical, whereas in a ColdFusion array, you can have rows of differing lengths based on the data that has been added or removed.

The following figures show the differences between traditional arrays and ColdFusion arrays using 2D arrays. The differences between traditional and ColdFusion 3D arrays are similar, but much harder to show on a page.

98 Chapter 5: Using Arrays and Structures

A conventional 2D array is like a fixed-size table made up of individual cells, as the following figure shows:

The following figure represents a ColdFusion 2D array:

A ColdFusion 2D array is actually a one-dimensional array that contains a series of additional 1D arrays. Each of the arrays that make up a row can expand and contract independently of any other column. Similarly, a ColdFusion 3D array is essentially three nested sets of 1D arrays.

Dynamic arrays expand to accept data you add to them and contract as you remove data from them.

About arrays 99

Basic array techniques

The following sections describe how to reference array elements, create arrays, add and remove array elements, and copy arrays.

Referencing array elements

You reference array elements by enclosing the index with brackets: arrayName[x] where x is the index that you want to reference. In ColdFusion, array indexes are counted starting with position 1, which means that position 1 in the firstname array is referenced as firstname[1]. For 2D arrays, you reference an index by specifying two coordinates:

You can use ColdFusion variables and expressions inside the square brackets to reference an index, as the following example shows:

Note: The that might try to access an undefined array element in a try block and use a catch block to handle exceptions that arise if elements do not exist.

IsDefined function does not test the existence of array elements. Instead, put any code

Creating arrays

In ColdFusion, you declare an array by assigning a variable name to the new array and specifying its dimensions, as follows:

where x is the number of dimensions (from 1 to 3) in the array that you want to create.

Once you declare an array, you can add array elements, which you can then reference using the elements’ indexes.

myarray[1][1].

For example, suppose you declare a 1D array called firstname:

The array firstname holds no data and is of an unspecified length. Next you add data to the array:

After you add these names to the array, it has a length of 3.

Creating complex multidimensional arrays

ColdFusion supports dynamic multidimensional arrays. When you declare an array with the

ArrayNew function, you specify the number of dimensions. You can create an asymmetrical array

or increase an existing array’s dimensions by nesting arrays as array elements.

100 Chapter 5: Using Arrays and Structures

Macromedia COLFUSION MX 7 User Manual

Specifications and Main Features

Frequently Asked Questions

User Manual

CONTENTS

INTRODUCTION

About ColdFusion MX Documentation

Contents

Using this manual

Approaches to using this manual

Beginning with ColdFusion

Developing an in-depth knowledge of ColdFusion

Learning about new and modified ColdFusion features

ColdFusion features described in this manual

Accessing the ColdFusion MX documentation

Documentation set

Viewing online documentation

Introducing ColdFusion MX

Contents

About Internet applications and web application servers

About web pages and Internet applications

About web application servers

How a web server and web application server work together

About ColdFusion MX

The ColdFusion scripting environment

ColdFusion Markup Language

CFML tags

CFML functions and CFScript

CFML extensions

CFML development tools

Verity Search Server

ColdFusion MX Administrator

About J2EE and the ColdFusion architecture

About ColdFusion MX and the J2EE platform

The CFML Programming Language

Elements of CFML

Contents

CFML Basics

Comments

Tags

Tag syntax

Built-in tags

Custom tags

Functions

Built-in functions

User-defined functions

ColdFusion components

Constants

Variables

Variable scopes

Expressions

Data types

Flow control

cfif, cfelseif, and cfelse

cfswitch, cfcase, and cfdefaultcase

cfloop and cfbreak

cfloop

cfbreak

cfabort and cfexit

Character case

Special characters

Reserved words

CFScript

Using ColdFusion Variables

Contents

Creating variables

Variable naming rules

Variable characteristics

Data types

Numbers

Integers

Real numbers

Strings

Boolean values

Date-Time values

Date and time formats

Locale-specific dates and times

How ColdFusion stores dates and times

Binary data type and binary encoding

Complex data types