MACROMEDIA COLDFUSION 5 - CFML, COLDFUSION 5 Reference

CFML Reference

ColdFusion 5

Macromedia® Incorporated

may be used or copied only in accordance with the terms of such license. The content of this manual is furnished for informational use only, is subject to change without notice, and should not be construed as a commitment by Macromedia Incorporated. Macromedia Incorporated assumes no responsibility or liability for any errors or inaccuracies that may appear in this book.

Except as permitted by such license, no part of this publication may be reproduced, stored in a retrieval system, or transmitted in any form or by any means, electronic, mechanical, recording, or otherwise, without the prior written permission of Macromedia Incorporated.

ColdFusion and HomeSite are federally registered trademarks of Macromedia Incorporated. HomeSite, the ColdFusio n logo and the Allaire logo are trademarks of Macromedia Incorporated in the USA and other countries. M icrosoft, Windows, Windows NT, Windows 95, Microsoft Access, and FoxPro are registered trademarks of Microsoft Corporation. Solaris is a trademark of Sun Microsystems Inc. UNIX is a trademark of The Open Group. PostScript is a trademark of Adobe Systems Inc. All other products or name brands are the trademarks of their respective holders.

Part number: ZCF50MREF

Contents

About This Book . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xv

Intended Audience . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xvi

Developer Resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xvi

About ColdFusion Documentation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xvii

Printed and online documentation set . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xvii

Viewing online documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xvii

Printing ColdFusion documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xvii

Getting Answers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xviii

Contacting Macromedia . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xviii

Chapter 1 ColdFusion Expressions: Operands, Operators

and Other Constructs . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1

Elements of ColdFusion Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2

Operands: data types, constants, and variables . . . . . . . . . . . . . . . . . . . . . . . . 2

Data types of constants and variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2

Notes on date-and-time values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

Constants . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

Variable naming conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

ColdFusion variable types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

CGI Environment Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

Testing for CGI variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

CGI server variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

CGI client variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

CGI client certificate variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

Operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

Arithmetic operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

Boolean operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

Decision operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

Shorthand notation for decision operators . . . . . . . . . . . . . . . . . . . . . . . . . . 17

String operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18

Operator precedence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18

Functions as Operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

iv Contents

Function syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

Optional function arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

Pound Signs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

Pound signs in cfoutput tags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

Pound signs in strings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

Pound signs in tag attribute values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22

Pound signs in custom tag attribute values . . . . . . . . . . . . . . . . . . . . . . . . . . 22

Nested pound signs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22

Pound signs in general expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

Chapter 2 ColdFusion Tags . . . . . . . . . . . . . . . . . . . . . 25

Alphabetical List of ColdFusion Tags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26

New tags in ColdFusion 5 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30

Forms tags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30

Database manipulation tags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30

Data output tags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30

Exception handling tags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30

Extensibility tags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31

File management tags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31

Flow-control tags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31

Internet Protocol tags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31

Java servlet and Java object tags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31

Page processing tags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31

Variable manipulation tags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32

Web application framework tags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32

cfabort . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33

cfapplet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35

cfapplication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37

cfassociate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40

cfauthenticate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41

cfbreak . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43

cfcache . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44

cfcol . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47

cfcollection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49

cfcontent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52

cfcookie . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54

cfdirectory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57

cfdump . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60

cferror . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61

cfexecute . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65

cfexit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67

cffile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70

cfform . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85

cfflush . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89

cfftp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91

cfgraph . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .102

cfgraphdata . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118

cfgrid . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119

Contents v

How data is returned from cfgrid . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124

Using the href attribute . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126

cfgridcolumn . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129

cfgridrow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136

cfgridupdate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137

cfheader . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140

cfhtmlhead . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141

cfhttp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142

cfhttpparam . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148

cfif/cfelseif/cfelse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150

cfimpersonate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152

cfinclude . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154

cfindex . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .155

cfinput . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .159

cfinsert . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .163

cfldap . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .167

cflocation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173

cflock . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174

cflog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181

cfloop . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .183

cfmail . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .192

cfmailparam . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195

cfmodule . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197

cfobject . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .200

cfoutput . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 207

cfparam . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 209

cfpop . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .211

cfprocessingdirective . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215

cfprocparam . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 216

cfprocresult . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 220

cfquery . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .222

cfqueryparam . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 228

cfregistry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .233

cfreport . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .239

cfrethrow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 241

cfsavecontent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 243

cfschedule . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 244

cfscript . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .247

cfsearch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 249

cfselect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .253

cfservlet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .256

cfservletparam . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 258

cfset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 260

cfsetting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .262

cfsilent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .264

cfslider . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .265

cfstoredproc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 270

cfswitch/cfcase/cfdefaultcase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 274

cftable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .276

vi Contents

cftextinput . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 278

cfthrow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 282

cftransaction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 284

cftree . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 287

cftreeitem . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 292

cftry cfcatch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 296

cfupdate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 301

cfwddx . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 305

Chapter 3 ColdFusion Functions . . . . . . . . . . . . . . . . 307

Alphabetical List of ColdFusion Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 308

New functions in ColdFusion 5 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 310

Array functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 310

Authentication functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 310

Conversion functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 310

Date and time functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 311

Decision functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 311

Display and formatting functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 311

Dynamic evaluation functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 312

International functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 312

List functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 312

Mathematical functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 312

Query functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 313

String functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 313

Structure functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 314

System functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 314

Other functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 314

Abs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 315

ACos . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .316

ArrayAppend . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 318

ArrayAvg . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 319

ArrayClear . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 321

ArrayDeleteAt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 322

ArrayInsertAt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 323

ArrayIsEmpty . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 324

ArrayLen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 325

ArrayMax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 326

ArrayMin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 328

ArrayNew . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 330

ArrayPrepend . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 331

ArrayResize . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 332

ArraySet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 333

ArraySort . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 334

ArraySum . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 335

ArraySwap . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 337

ArrayToList . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 338

Asc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 339

ASin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 340

Contents vii

Atn . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 342

AuthenticatedContext . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 343

AuthenticatedUser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 344

BitAnd . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .345

BitMaskClear . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 346

BitMaskRead . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 347

BitMaskSet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 348

BitNot . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .349

BitOr . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 350

BitSHLN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 351

BitSHRN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 352

BitXor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .353

Ceiling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .354

Chr . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 355

CJustify . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .356

Compare . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 357

CompareNoCase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 359

Cos . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 360

CreateDate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 361

CreateDateTime . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 363

CreateObject . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 365

CreateODBCDate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 369

CreateODBCDateTime . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 371

CreateODBCTime . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 373

CreateTime . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 375

CreateTimeSpan . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 376

CreateUUID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 378

DateAdd . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 379

DateCompare . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 381

DateConvert . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 384

DateDiff . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 387

DateFormat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 389

DatePart . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 391

Day . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 393

DayOfWeek . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 395

DayOfWeekAsString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 397

DayOfYear . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 398

DaysInMonth . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 400

DaysInYear . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 401

DE (Delay Evaluation) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 402

DecimalFormat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 403

DecrementValue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 404

Decrypt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 405

DeleteClientVariable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 406

DirectoryExists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 407

DollarFormat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 408

Duplicate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 409

Encrypt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 410

Evaluate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 412

viii Contents

Exp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 413

ExpandPath . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 414

FileExists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 415

Find . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 416

FindNoCase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 417

FindOneOf . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 418

FirstDayOfMonth . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 419

Fix . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 420

FormatBaseN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 421

GetBaseTagData . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 422

GetBaseTagList . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 423

GetBaseTemplatePath . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 424

GetClientVariablesList . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 425

GetCurrentTemplatePath . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 426

GetDirectoryFromPath . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 427

GetException . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 428

GetFileFromPath . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 429

GetFunctionList . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 430

GetHttpRequestData . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 431

GetHttpTimeString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 433

GetLocale . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 434

GetMetricData . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 436

GetProfileString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 438

GetTempDirectory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 440

GetTempFile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 441

GetTemplatePath . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 442

GetTickCount . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 443

GetTimeZoneInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 444

GetToken . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 445

Hash . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .446

Hour . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .447

HTMLCodeFormat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 448

HTMLEditFormat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 450

IIf . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 452

IncrementValue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 454

InputBaseN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 455

Insert . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 456

Int . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 457

IsArray . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .458

IsAuthenticated . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 459

IsAuthorized . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 460

IsBinary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 462

IsBoolean . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 463

IsCustomFunction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 64

IsDate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .466

IsDebugMode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 467

IsDefined . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 468

IsLeapYear . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 469

IsNumeric . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 470

Contents ix

IsNumericDate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 471

IsProtected . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 472

IsQuery . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 475

IsSimpleValue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 476

IsStruct . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .477

IsWDDX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 478

JavaCast . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 480

JSStringFormat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 481

LCase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .482

Left . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 483

Len . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 484

ListAppend . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 485

ListChangeDelims . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 486

ListContains . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 487

ListContainsNoCase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 489

ListDeleteAt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 490

ListFind . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .491

ListFindNoCase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 493

ListFirst . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .494

ListGetAt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 495

ListInsertAt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 496

ListLast . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .497

ListLen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .498

ListPrepend . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 499

ListQualify . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 500

ListRest . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .502

ListSetAt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 503

ListSort . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .505

ListToArray . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 507

ListValueCount . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 508

ListValueCountNoCase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 510

LJustify . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .512

Log . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 513

Log10 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .514

LSCurrencyFormat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 515

LSDateFormat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 518

LSEuroCurrencyFormat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 520

LSIsCurrency . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 523

LSIsDate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 524

LSIsNumeric . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 525

LSNumberFormat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 526

LSParseCurrency . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 529

LSParseDateTime . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 532

LSParseEuroCurrency . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 534

LSParseNumber . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 536

LSTimeFormat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 537

LTrim . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .539

Max . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 540

Mid . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 541

x Contents

Min . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 542

Minute . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 543

Month . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 544

MonthAsString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 545

Now . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .546

NumberFormat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 547

ParagraphFormat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 550

ParameterExists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 551

ParseDateTime . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 552

Pi . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 554

PreserveSingleQuotes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 555

Quarter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 556

QueryAddColumn . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 557

QueryAddRow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 559

QueryNew . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 560

QuerySetCell . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 561

QuotedValueList . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 563

Rand . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .564

Randomize . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 565

RandRange . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 566

REFind . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 567

REFindNoCase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 570

RemoveChars . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 573

RepeatString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 574

Replace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 575

ReplaceList . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 576

ReplaceNoCase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 578

REReplace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 579

REReplaceNoCase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 580

Reverse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 581

Right . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 582

RJustify . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .583

Round . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 584

RTrim . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .585

Second . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 586

SetLocale . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 587

SetProfileString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 589

SetVariable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 591

Sgn . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 593

Sin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 594

SpanExcluding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 595

SpanIncluding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 596

Sqr . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 597

StripCR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 598

StructAppend . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 599

StructClear . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 601

StructCopy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 602

StructCount . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 06

StructDelete . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 607

Contents xi

StructFind . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 609

StructFindKey . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 610

StructFindValue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 611

StructGet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 612

StructInsert . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 613

StructIsEmpty . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 615

StructKeyArray . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 616

StructKeyExists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 619

StructKeyList . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 20

StructNew . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 623

StructSort . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 624

StructUpdate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 626

Tan . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 627

TimeFormat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 628

ToBase64 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 630

ToBinary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 632

ToString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 634

Trim . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 636

UCase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .637

URLDecode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 638

URLEncodedFormat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 639

Val . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 640

ValueList . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 641

Week . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .642

WriteOutput . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 643

XMLFormat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 644

Year . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 645

YesNoFormat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 646

Chapter 4 ColdFusion C++ CFX Reference . . . . . . . . 647

C++ Class Overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 648

CCFXException Class. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 649

Class members . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 649

CCFXException::GetError . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 649

CCFXException::GetDiagnostics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 649

CCFXQuery Class. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 651

Class members . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 651

CCFXQuery::AddRow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 651

CCFXQuery::GetColumns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 652

CCFXQuery::GetData . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 652

CCFXQuery::GetName . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 653

CCFXQuery::GetRowCount . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 653

CCFXQuery::SetData . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 653

CCFXQuery::SetQueryString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 654

CCFXQuery::SetTotalTime . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 654

CCFXRequest Class. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 655

Class Members . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 655

xii Contents

CCFXRequest::AddQuery . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 656

CCFXRequest::AttributeExists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 656

CCFXRequest::CreateStringSet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 657

CCFXRequest::Debug . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 657

CCFXRequest::GetAttribute . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 658

CCFXRequest::GetAttributeList . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 658

CCFXRequest::GetCustomData . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 659

CCFXRequest::GetQuery . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 659

CCFXRequest::GetSetting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 659

CCFXRequest::ReThrowException . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 660

CCFXRequest::SetCustomData . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 661

CCFXRequest::SetVariable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 661

CCFXRequest::ThrowException . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 662

CCFXRequest::Write . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 662

CCFXRequest::WriteDebug . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 663

CCFXStringSet Class. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 664

Class members . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 664

CCFXStringSet::AddString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 664

CCFXStringSet::GetCount . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 664

CCFXStringSet::GetIndexForString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 665

CCFXStringSet::GetString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 665

Chapter 5 ColdFusion Java CFX Reference . . . . . . . 667

Overview Class Libraries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 668

CustomTag Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 669

Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 669

processRequest . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 669

Query Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 670

Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 670

addRow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 670

getColumnIndex . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 671

getColumns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 671

getData . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 672

getName . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 672

getRowCount . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 673

setData . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 673

Request Interface. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 675

Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 675

attributeExists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 675

debug . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 676

getAttribute . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 676

getAttributeList . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 677

getIntAttribute . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 677

getQuery . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 678

getSetting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 678

Response Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 680

Contents xiii

Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 680

addQuery . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 680

setVariable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 681

write . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 681

writeDebug . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 682

Debugging Classes Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 683

DebugRequest . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 683

DebugResponse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 683

DebugQuery . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 683

Chapter 6 WDDX JavaScript Objects . . . . . . . . . . . . . 685

JavaScript Object Overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 686

WddxSerializer Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 687

Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 687

serialize . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 687

serializeVariable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 688

serializeValue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 688

write . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 689

WddxRecordset Object. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 691

Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 691

addColumn . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 691

addRows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 692

getField . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 692

getRowCount . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 693

setField . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 693

wddxSerialize . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 694

xiv Contents

About This Book

The CFML Reference is your primary ColdFusion Markup Language (CFML) reference guide. Use this guide to learn about individual CFML tags and functions, as well as ColdFusion expressions, using JavaScript objects for WDDX in ColdFusion. You can also find detailed references for Java and C++ CFX interfaces.

Contents

• Intended Audience...................................................................................................xvi

• Developer Resources................................................................................................xvi

• About ColdFusion Documentation.................................................... ...................xvii

• Getting Answers .....................................................................................................xviii

• Contacting Macromedia........................................................................................x viii

xvi About This Book

Intended Audience

The CFML Reference is intended for ColdFusion developers building pages and writing CFML code.

Developer Resources

Macromedia C orpo r a tion is com mitte d to setting the standar d for custo me r sup port in developer education , tech nical supp o rt, and pro fes sio nal services . T he Web site is designed to give you quick access to the entire range of online resources, as the following table describes.

Resource Description URL

Macromedia W eb site

Information on ColdFusion

Technical Support

ColdFusion Support Forum

Installation Support

Professional Education

Developer Community

General information about Macromedia products and service s

Detailed product information on ColdFusion and related topics

Professional support programs that Macromedia offers.

Access to experienced ColdFusion developers through participation in the Online Forums, where you can post messages and read replies on many subjects relating to ColdFusion.

Support for installation-related issues for all Macromedia prod uc t s

Information about classes, on-site training, and online courses offered by Macromedia

All the resources that you need to stay on the cutting edge of ColdFusion development, including online discussion groups, Knowledge Base, technical papers and more

www.macromedia.com/

www.coldfusion.com/products/coldfusion/

www.coldfusion.com/support/

http://forums.coldfusion.com/ coldfusionconf/

www.coldfusion.com/support/installation/

www.coldfusion.com/developer/training.cfm

www.coldfusion.com/developer/

ColdFusion Dev Center

Macromedia Alliance

Development tips, articles, documentation, and white papers

Connection with the growing network of solution providers , appli ca tio n developers, resellers, and hosting services creating solutions with ColdFusion

www.allaire.com/developer/ coldfusionreferencedesk/

www.coldfusion.com/partners/

About ColdFusion Documentation xvii

About ColdFusion Documentation

ColdFusion documentation is designed to provide support for the complete spectrum of particip ant s . T he p rint and online ve rsio ns are organized to allow y ou t o quickly locate the information that you need. The C oldF usion online documentation is provided in HTML and Adobe Acrobat formats.

Printed and online documentation set

The ColdFusion documentation set consists of the following titles.

Book Description

Installing and Configuring ColdFusion Server

Advanced ColdFusion Admin ist rat ion Describes how to connect your data sources to the ColdFusion

Developing ColdFusion Applications Describes how to use ColdFusion Ser ver to develop your

CFML Reference Provides descriptions , syntax, usage , and code example s for all

CFML Quick Reference A brief guide that shows the syntax of ColdFusion tags,

Describes system installation and basic configuration for Windows NT, Windows 2000, Solaris, Linux, HP-UX.

Server , co nfi gure sec uri ty fo r you r appl ic ati ons , and how to us e ClusterCATS to manage scalability, clustering, and load-balancing fo r your site.

dynamic Web applications, including retrieving and updating your data, using structures, and forms.

ColdFusion tags, functions, and variables, including WDDX, and references for both coding Java and C++ CFXs.

functions, and variables.

Viewing online documentation

All ColdFusion documentation is available online in HTML and Adobe Acrobat PDF formats. To view the HTML documentation, open the following URL on the Web server running ColdFusion:

http://localhost/coldfusion/docs/dochome.htm.

To view and print ColdFusion documentation in Acrobat format, open the following URL on the Web server running ColdFusion: http://localhost/coldfusion/docs/

AcrobatDocs/index.htm

Printing ColdFusion documentation

To read printed documentation, locate the Adobe Acrobat PDF files on the product CD-ROM. The PDF files offer excellent print output. You can print an entire book or individual sections.

xviii About This Book

Getting Answers

One of the best ways to solve particular programming problems is to tap into the vast expertise of the ColdFusion developer communities on the ColdFusion Forums. Other deve loper s on the f orum ca n he lp y ou fig ur e o ut how to do just about anything with ColdFusion. The search facility can also help you search messages from the previous 12 months, allowing you to learn how others have solved a problem that you might be facing. The F o rums is a gr e at r es our ce for learning C o ldFu sion, bu t it is also a great place to see the ColdFusion developer community in action.

Contacting Macromedia

Corporate headquarters

Technical support

Sales

Macromedia, Inc. 600 Townsend Street San Francisco, CA 94103

Tel: 415.252.2000 Fax: 415.626.0554

Web: www. macromedia.com Telephone support is available Monday through Friday,

8 A.M. to 8 P.M. Eastern time (except holidays) Toll Free: 888.939.2545 (U.S. and Canada) Tel: 617.219.2100 (outside U.S. and Canada) Postings to the ColdFusion Support Forum (http://

forums.coldfusion.com/DevConf/index.cfm) can be made any time.

Toll Free: 888.939.2545 Tel: 617.219.2100

Fax: 617.219.2101 E-mail: sales@macromedia.comsales@macromedia.com

Web: http://commerce.coldfusion.com/purchase/ index.cfm

Chapter 1

ColdFusion Expressions: Operands, Operators and Other Constructs

This chapter describes ColdFusion expressions — language constructs that let you create sophisticated applications.

Contents

• Elements of ColdFusion Expressions........................................................................2

• Variables.......................................................................................................................6

• CGI Environment Variables......................................................................................13

• Operators...................................................................................................................16

• Functions as Operators.............................................................................................19

• Pound Signs...............................................................................................................20

2 Chapter 1 ColdFusion Expressions: Operands, Operators and Other Constructs

Elements of ColdFusion Expressions

ColdFusion expressions consist of operands and operators. Operands are comprised of constants and variables. Operators are the verbs that act on the op erands; functions are a form of operator. This chapter first describes the operands and then describes the operators.

Operands: data types, constants, and variables

The sections on operands provide detailed information on the following:

• Data types of ColdFusion operands

• ColdFusion constants

• ColdFusion variables: naming conventions, types, scoping, and other details

Data types of constants and variables

In ColdFusion, constants and variables have implied data types. The reason for the

term “implied” is that there are no variable declarations that define the scalar data type of a variable, as one finds in statically typed languages such as Pascal. Whenever you use a consta nt or se t the valu e o f a v ariable, the value yo u us e has a type, such as integer, real, or string. For example, if you use its value to 62, the implied data type is integer. In addition to these scalar types, ColdFusion also supports lists, structures, and arrays. T h e following t able describes the types of variables and consta nt s you can use in a Co ldFusion applicatio n page.

cfset to create a variable AGE and set

Type Description

Integer Numbers with no de cimal po int. The l ower limit for a sign ed integer is

-2,147,483,648, and the upper limit for a signed integer is 2,147,483,647.

If you specify an integer outside the limits, ColdFusion converts it to a floating point value to avoid overflow. In doing so, ColdFusion preserves the number’s magnitude. However, the conversion to floating point comes at the expense of precision, since ColdFusion has only a fixed number of bits to work with.

Real number Numbers with a decimal part. Also known as floating point numbers.

300

The range of ColdFusion numbers is approximately ±10 operations are accurate to 12 digits after the decimal point.

ColdFusion supports scientific notation; this means that you can enter numbers in the form 3 E 16 and perform calculations on them.

. Most

Elements of ColdFusion Expressions 3

Type Description

String Text values, which can be enc los ed in single (’) or double (") quotes.

String length is limited only by the amount of available memory on the ColdFusion server.

To use a single quote inside a string th at is si ngle qu oted, escape, or repeat, the single quote by using two single quotes. For example:

’the ’’best’’ software’

Similarly, you can escape a double quote inside a double quote-enclosed string.

To insert a pound sign in a string, the pound sign must be escaped by repeating it. For example:

"enter a pound sign (##) here"

Boolean value The result of a logical operation. The value can be TRUE or FALSE.

The numerical value of TRUE is 1. The numerical value of FALSE is

0. The string value of TRUE is "YES"; FALSE is "NO".

Date value Date-and-time valu es ide nti fy a date and time in the range 100AD to

9999AD. If no time part is specified, time is set to 12:00am. You can also enter a date object in the following formats:

"October 30, 1999" "Oct 30, 1999" "Oct. 30, 1999" "10/30/99" "1999-30-10"

Time value You can enter a date-and-time object in the following formats:

"October 30, 1999 02:34:12" "October 30, 1999 2:34a" "October 30, 1999 2:34am" "October 30, 1999 02:34am" "October 30, 1999 2am"

The time part of the object is accurate to the second.

Array Arrays are tables of objects or data that can be indexed. The

ArrayNew function only supports creating up to three-dimensional

arrays, there is no limit on array size or maximum dimension. Elements stored in an array are referenced as follows:

For more information, see Developing ColdFusion A pplications.

Structure You can use structures to create and maintain key-value pairs, to

refer to related string values as a unit rather than individually, or to create associative array s.

For more information, see Developing ColdFusion A pplications.

4 Chapter 1 ColdFusion Expressions: Operands, Operators and Other Constructs

Type Description

List Lists are a kind of string made up of elements separated by

delimiters. The default delimitin g character used by list pro cessing function s is a

comma. A list can have more than one delimiting character. You specify the allowable delimiters for a list in the

delimiters

parameter of ColdFusion list processing functions. White space is not cons ider ed a deli miter. However , when using li st s

where elements may be s eparated by white space as well as by other delimiters, add the white space characters to the list of delimiters. Delimiters before the first element and after the last element are ignored.

Lists cannot be nested into one another. Also, lists can contain no empty elements. A list can be empty, however. The empty list is equivalent to the empty string "".

Query ColdFusion queries can be referenced as objects by assigning a

query to a variable:

<cfquery name = "myquery"

datasource = "mydata" SELECT * FROM CUSTOMERS

</cfquery>

In this case the query is not copied. Both names point to the record set data, so that if you make changes to the table referenced in the query, the original query and the query object myquery2 both reflect these changes. If you perform this operation with an array, the array is copied.

Queries and var iab les cann ot h ave the same name at th e sam e time in the same application page.

COM object Component Object Model (COM) objects are non-visual components

that encapsu lat e functionality tha t yo u c an inv ok e in your application pages. ActiveX, OCX, CORBA, and ADO objects are examples of COM objects.

COM objects generally contain methods, like functions, that you can use to execute operations :

COM objects generally contain properties you can read and write using ColdFusion variables:

Properties can be invoked on either side of an assignment. For more information, see Developing ColdFusion A pplications.

Elements of ColdFusion Expressions 5

Notes on date-and-time values

This section contains information about how date and time variables are handled by ColdFusion.

How date and time values are stored

ColdFusion represents date-and-time values internally on a time line as a subset of the real numbers. This representation is optimized for efficiency in evaluation and because it is the method used by many popular database systems. In this model, one day is equal to the difference between two succe ssive integers. The time portion of the date-and-time value is stored in the fractional part of the real number.

Thus, you can use arithmetic ope ra tions to manipulate date-and-time values. For example, Now() + 1 evaluates to tomorrow at the same time. However, we strongly discourage ColdFusion developers from using this potentially troublesome method of manipulating date-and-time objects. Use the date-and-time manipulation functions instead.

21st century dates

Two-digit years from 00 to 29 are treated as 21st century dates; 30 to 99 are treated as

century dates. Thus, the following dates are equiva le nt :

"October 30, 2015" "October 30, 15"

Constants

The value of a constant does not change during program execution. Constants are simple scal ar v alue s that you ca n use w ithi n exp res sion s and fun ctio ns . They incl ude integers, r eal nu mber s , tim e an d dat e valu es , b oole a n valu es, string values, and lists.

6 Chapter 1 ColdFusion Expressions: Operands, Operators and Other Constructs

Variables

V ariables are the most frequ ently used oper ands. Variable values can be set and reset, and passed as attributes to CFML tags and JRun servlets. They can be passed as parameters to functions, and can replace most const ants.

For a list of the variables associated with ColdFusion, see the CFML Quick Reference.

Variable naming conventions

When naming ColdFusion variables and form fields, keep these guideline s in mind:

• Variable names must begin with a letter, which can be followed by any number of letters or numbers or the underscore character.

• Variable names must be one word.

• Do not use spaces in variable names.

• Use descriptive names not abbreviations.

• Queries and variables cannot have the same name in a ColdFusion application

page.

• Although ColdFusion variables are not case-sensitive, keep capitalization consistent in order to keep your code consistent.

• When writing queries and forms, match your form fi eld names with the corresponding database field name.

• In some cases, you must put a pounds signs around a variable name 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 “Pound Signs” on page 20.

ColdFusion variable types

The following table describes the types of variables you can use in a ColdFusion application page.

Variable Type Description

Query Result Results of a database query can be u sed as dyn am ic p ara me ters .

For example, if you create a query named LookupUser that finds the ID for a given u se r name, you can use th is ID in another query or in a call to cfoutput.

Local Variable The default scope for variables of any type created with the cfset

and cfparam tags. For example, A to 5. This variable is available only on the application page where it is created and any included pages.

URL Parameter Param eters app ended to a URL af ter the ap plicatio n page name in

the format variablename = value. URL parameters are stored in structures. For more information, see “Vari ables stored in

structures” on page 12.

<cfset A = 5> sets the variable

Variables 7

Variable Type Description

Form Field The most common way of passing parameters to a page. When a

user enters data in a form field, a parameter with the name of the form field is passed to the action page. Form fields are stored in structures. For more information, see “Vari ables stored in

structures” on page 12.

Client Variables associated with a particular client. Lets you maintain

state as a user m ove s fro m page to page in an ap plication. Stored in the system registry by default, but you can also store them in a cookie or in a database.

Client variables are part of the ColdFusion Web Application Framework. For more information, see Developing Cold Fus io n Applications.

Server Variables associated with the current Web server. Available to all

ColdFusion applications until the ColdFusion server is shut down. This server scope lets you define variables that all your ColdFusion application pages can reference.

Server variables are stored in structu res . For more informa t io n, see “Variables stored in structures ” on page 12.

For information on locking server variables, see the description of

cflock on page 174.

Session Variables tied to an individual client that persist for as long as that

Client ID maint ains a ses sion. Session variables , like curre nt client variables, require a client name and are available only to that one Client ID.

Unlike client varia bles, sessi on vari ables ar e stored in the ser ver’s memory and can be set to time-out after a precise period of inactivity.

Session variables are stored in structures. For more information, see “Variables stored in structures ” on page 12.

Session variables should be locked when accessed. For inform ation, see the description of cflock on page 174.

Session variables are part of the ColdFusion Web Application Framework. This means that they are used in the context of an

Application.cfm page. For more information, see Developing

ColdFusion Applications and the descr ipti on of cfapplication on

page 37.

8 Chapter 1 ColdFusion Expressions: Operands, Operators and Other Constructs

Variable Type Description

Application V ariab les ti ed to a n appl ication a s defi ned in the CFAPPLICATION

NAME attribute, typically used in the

Application.cfm file.

Application variables work only if an application name is defined. Application variables are stored in structures. For more

information, see “Variables stored in structures” on page 12. Application variables should be locked when accessed. For

inform ation, see the description of cflock on page 174. Application variables are part of the ColdFusion Web Application

Framework. This means that they are used in the context of an

Application.cfm page. For more information, see Developing ColdFusion Applications and the descr ipti on of cfapplication on

page 37.

Request Variables storing data that pertains to the processing of a request

to a single page. Request variables are convenient for storing data in a structure,

carried through ne sted t ags, suc h as Custo m Tags, and process ed at once.

Request variables are stored in structures. For more information, see “Variables stored in structures ” on page 12.

Caller Variable that lets you call and use variables from the calling

template in a ColdFusion custom tag.

HTTP Cookies Variables stored in the browser. Available every time the browser

makes a page request. You can create cookie variables with the

cfcookie tag.

File Read-only variables. Created when a cffile action = "upload"

operation is executed.

CGI Environment Every page request has several environment variables sent to it

that relate to the context in which it was requested. The variables available depend on the browser and server software. For a list of the commonly used CGI variables, see “CGI Environment

Variables” on page 13.

Note: CGI environment variables are created even when you are using a Web server that supports a server API.

Qualifying, or scoping, variable references

ColdFusion distinguishes between identically named parameters from different sources by using a different prefix for each source. Specifying a variable’s source is known as “scoping”the variable. For example, to specify a variable called S tate that is passed in a form submission, you would reference it as variable named State passed in a URL, you would reference it as

Form.State. To specify a

URL.State.

Variables 9

Although you are not required to use the scope prefix unless two variables in different scopes have the same name, it is recommended for readability and processing speed that you use prefixes. For example, the variable clearer than a variable called simply

lastname.

Form.lastname is

Tip

Specify the variable’s scope prefix for all Application, Session, Server, and Request variables.

Many CFML tags, such as

cferror and cfftp, have variables associated with them.

Typically, these variables use the tag name as the prefix. For a list of the variables, see the Quick Reference to CFML.

Note

Any variable that can be created using

cfset can also be created with an assignment

statement in cfscript.

Scopes and variables

The following table lists the types of variable scopes, and shows how you refer to them in your code. In addition to these scopes, there are a number of ColdFusion data structures that provide information about the results of a tag or operation. For information on special variables, see the CFML Quic k Reference and the documentation of the individual CFML tags that return these variables.

Prefix Required Availability Comment

Variables (Local)

No Cannot be accessed by a custom tag

called by the page or by an action page that di ffers f rom a form p age that creates the variables

Created by the by using a Variables prefix or no prefix

cfset or cfparam tag

Form No Can be used on the action page of a

form; cannot be used on a form page that is not also the action page

URL No The target page of a URL Contains the parameters passed in

Attributes Yes On the custom tag page only Contains the values passed in the

Caller No in calling

page. Y es in custom tag page.

As normal loc al v ari abl es o n t he p a ge calling the custom tag. Available on the custom tag page by using the Caller scope prefix.

Created by the

name attribute. Contains the values

form or cfform tag

of data tags (such as input) in the form body when the form is submitted.

the URL query string that ac cesses a page

custom tag ’s attributes by the calling page to a custom tag page

Created in a custom tag page or

cfparam tag by using a Caller

cfset

prefix. Created as local variables on the calling tag page.

10 Chapter 1 ColdFusion Expressions: Operands, Operators and Other Constructs

Prefix Required Availability Comment

Request Yes On the cr ea tin g page and in a ny t a gs ,

including nested tags, called after the variable is created

CGI No On any page; values are specific to

the latest browser request

Cookie No For one client, in one or many

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

Application Yes For multiple clients in one application

over multiple browser sessions

Server Yes On any page on the ColdFusion

server

Performance and scoping

Created by the

cfset or cfparam tag

by using a Request prefix

Created by the W eb server . Con tains the server environment variables that result from the browser request.

Created by the

cfcookie tag

cfset or cfparam tag

by using a Client prefix Created by the

cfset or cfparam tag

by using a Session prefix Created by the

cfset or cfparam tag

by using an Application prefix Created by the cfset or cfparam tag

by using a Server prefix

You can improve performance by qualifying variables with the proper scope. Adding variable scopes improves processing speed, but the trade-off is that it may reduce the ease of code reuse.

In the following example, both forms of the fullname variable are permitted. However, the example that includes a scoping prefix will be evaluated more quickly than the unscoped ex am p l e:

#Client.fullname# #fullname#

</cfoutput>

When a variable does not have a scope prefix, ColdFusion searches for it in the following sequence:

1 Local variables created using cfset and cfquery 2CGI 3File 4URL 5Form 6Cookie 7Client

Variables 11

Note

ColdFusion does not attempt to automatically find Application, Session, Server, Request, or CFML tag variables (except File variables). You must use prefixes with these variables.

The following scopes are exposed as ColdFusion structures:

• Form

• URL

• Attributes

• Request

• CGI

• Cookie

• Session

• Application

Note

Variables on one application page can be used on any other appl ication page that is included with the

cfinclude tag. Variables on the included page can also be

accessed by the including page.

Variables across application pages

Most ColdFusion variables apply only to a single application page. However, several types of variables can be used across multiple application p ages:

• Client variables store identifying information about an individual client. Client variables hold long-term information about an individual client. You can

store them in the system registry, a database, or a cookie named for the application.

• Server variables are valid for all ColdFusion applications on a server. Server variables store information (typically read-only) that does not change

often and can be shared across users and ColdFusion applications.

• Session variabl e s are valid for as long as an individual Client ID maintains a session.

Session variables are useful for storing short-term information needed for a single site visit or set of requests. They are specific to individual users.

• Application va riables are valid for an application. Application variables are available to individual, specified appli cations and to all

users of that ap plicatio n wh o acces s the C oldF usi on se rver. They are stored in the server’s memory and can be set to time out.

• Cal ler variables are valid for ColdFusion custom tags. Caller variables are available for passing information among application pages of

a ColdFusion custom tag.

12 Chapter 1 ColdFusion Expressions: Operands, Operators and Other Constructs

Note

When variables are available to several application pages, keep track of your variable names. For more information, see “Variable naming conventions” on page 6.

For information on setting up client state management using the clientManagement attribute in the

cfapplication tag, see the description of cfapplication on page 37.

For information about using Application, Client, and Session variables, see Developing ColdFusion Applications.

Variables stored in structures

As of ColdFusion 5, Form, Application, Session, Server, Request, and URL variables are stored in structures. Thus, you can reference all of the fields taken from a form as a structure, all parameters passed in a URL as a structure, and so forth.

You can access structures using any of the ColdFusion structure functions in the form structname.key, where each key represents a field name of a form or a variable name of a specific type. Because ColdFusion creates these structures whenever these variables are used, conversion to WDDX is straightforward.

For example:

<cfwddx action = "CFML2WDDX" input = "#form#" output = "formscope"> <cfoutput>#formScope#</cfoutput>

</cfif>

Note

Do not use

StructClear to clear session and application variables. This can cause

the loss of SessionID, CFID, CFTOKEN, and application variables. To prevent this loss, store session data in session.foo.* and then clear session.foo, and store application data in application.foo.* and then clear application.foo.

CGI Environment Variables 13

CGI Environment Variables

When a browser makes a request to a server, environment variables are created by the Web server and by the browser. In ColdFusion, these variables are referred to as CGI environment variables and they use the "CGI" prefix (even if your server uses a server API instead of CGI to communicate with the ColdFusion Server).

Environme nt variables contain da ta about the transaction between the browser and the server, such as the IP Address, browser type, and authenticated username. You can reference CGI environment variables for a given page request anywhere in the page. CGI variables are read-only.

Note

The environment variables available to your applications depend on the browser and server s oftware.

Testing for CGI variables

Because all CGI variables are not supported by all browsers, ColdFusion always returns TRUE when testing for the existence of a CGI variable, even if the variable is not supported by the client browser. To work around this, test for an empty string to determine if the CGI variable is available.

CGI variable exists <cfelse>

CGI variable does not exist </cfif>

CGI server variables

The following table describes common CGI environment variables created by a server (not all of these will be available with every server):

CGI Server Variable Description

SERVER_SOFTWARE Name and version of the information server software

SERVER_NAME Server’s hostname, DNS alias, or IP address as it appears

answering the request (and running the gateway). Format: name/version.

in self-referencing URLs.

GATEWAY_INTERFACE Revision of the CGI specification with which this server

SERVER_PROTOCOL Name and revision of the information protocol this request

SERVER_PORT Port number to which the request was sent.

complies. Format: CGI/revision.

came in with. Format: protocol/revision.

14 Chapter 1 ColdFusion Expressions: Operands, Operators and Other Constructs

CGI Server Variable Description

REQUEST_METHOD Method with which the re quest wa s made. For HTTP, this is

Get, Head, Post, and so on.

PATH_INFO Extra path information, as given by the client. Scripts can

be accessed by their virtual pathname, followed by extra information at the end of this path. The extra information is sent as PATH_INFO.

PATH_TRANSLATED Translated version of PATH_INFO after any

virtual-to-physical mapping.

SCRIPT_NAME Virtual path to the script being executed; used for

self-referencing URLs.

QUERY_STRING Query information that follows the ? in the URL that

referenced this script.

REMOTE_HOST Hostname making the request. If the server does not have

this information, it sets REMOTE_ADDR and does not set

REMOTE_HOST. REMOTE_ADDR IP address of the remote host making the request. AUTH_TYPE If the server supports user authentication, and the script is

REMOTE_USER AUTH_USER

REMOTE_IDENT If the HTTP server supports RFC 931 identification, this

CONTENT_TYPE For queries that have attached information, such as HTTP

CONTENT_LENGTH Length of the content as given by the client.

CGI client var ia ble s

The following table describes common CGI environment variables that are created by the browser and passed in the request header:

CGI Client Varia ble Description

protected, the pr otocol-spec ific authentica tion method us ed

to validate the user.

If the server supports user authentication, and the script is

protected, the username the user has authenticated as.

(Also available as AUTH_USER.)

variable is set to the remote username retrieved from the

server. Use this variable for logging only.

POST and PUT, this is the content type of the data.

HTTP_REFERER The referring document that linked to or submitted

form data.

CGI Environment Variables 15

CGI Client Varia ble Description

HTTP_USER_AGENT The browser that the client is currently using to send

the request. Format: software/version library/version.

HTTP_IF_MODIFIED_SINCE The last time the page was modified. The browser

determines whether to set this variable, usually in response to the server having sent the

LAST_MODIFIED HTTP header. It can be used to take advantage of browser-side caching.

CGI client certificate variables

ColdFusion makes available the following client certificate data. These var iables are available when running Microsoft IIS 4.0 or Netscape Enterprise under SSL if your Web server is configured to accept client certificates.

CGI Client Certificate Variable

CERT_SUBJECT Client-specific information provided by the web server.

CERT_ISSUER Information about the authority that provided the client

CLIENT_CERT_ENCODED The entire client certificate binary, base-64 encoded.

Description

This data typically includes the client’s name, e-mail address, etc. For example:

O = "V eriSign, Inc.", O U = V eriSign T rus t Network, OU = "www.verisign.com/repository/RPA Incorp. by Ref.,LIAB.LTD(c)98", OU = Persona Not Validated, OU = Digital ID Cla ss 1 - Microsof t, CN = Matthew Lun d, E = mlund@macromedia.com

certifi cate. For example: O = "V eriSign, Inc.", O U = V eriSign T rus t Network, OU =

"www.verisign.com/repository/RPA Incorp. By Ref.,LIAB.LTD(c)98", CN = VeriSign Class 1 CA Individual Subscribe r-Pers ona Not Validated

This data is typically of in terest to d evelopers integrati ng with other software that uses client certificates.

16 Chapter 1 ColdFusion Expressions: Operands, Operators and Other Constructs

Operators

Operators combine subexpressions to create complex expressions. Operators act on the operands. The general syntax for using operators is:

Expression Operator Expression

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 arithmetic operators are shown in the following table.

Operator Description

+ - * / The basic arithmetic ope rato rs: add iti on, subtraction, multipli ca tion, and

division. In division, the right operand cannot be zero. + - Unary arithmetic operators for setting the sign of a number. MOD Returns the remainder (modulus) after a number is divided by a divisor.

The result has the same sign as the divisor. The right operand cannot be

zero. For example, 11 MOD 4 is 3. \ Divide an integer by another integer. Use the \ (trailing slash) to separate

the integers. The right operand cannot be zero. For example, 9 \ 4 is 2. ^ Returns the result of a number raised to a power (exponent). Use the ^

(caret) to sepa rate the num be r fro m t he p ow er. The left operand can no t be

zero. For example, 2 ^ 3 is 8.

Boolean operators

Boolean, or logical, operators perform logical connective and negation operations. The operands of Boolean operators are Boolean (TRUE/FALSE) values.

Operator Description

NOT Reverses the value of an argument. For example, NOT TRUE is FALSE

and vice versa. AND Returns TRUE if both argume nt s ar e TRU E; re turn s FALSE otherwise. For

example, TRUE AND TRUE is TRUE, but TRUE AND FAL SE is FALSE. OR Returns TRUE if any of the arg um ents is TRUE; returns FALSE otherwise.

For example, TRUE OR FALSE is TRUE, but F ALSE OR FALSE is FALSE.

Operators 17

Operator Description

XOR Exclusive or —either, or, but not both. Returns TRUE if the truth values of

both arguments are different; returns FALSE otherwise. For example,

TRUE XOR TRUE is FALSE, but TRUE XOR FALSE is TRUE. EQV Equivalence both true or both false. The EQV operator is the opposite of

the XOR operator. For example, TRUE EQV TRUE is TRUE, but TRUE

EQV FALSE is FALSE. IMP Implication. A IM P B is the truth value o f the logic al st atement “If A Then B.”

A IMP B is FALSE only when A is TRUE and B is FALSE.

Decision operators

ColdFusion’s decision, or comparison, operators produce a Boolean TRUE/FALSE result. The decision operators are shown in the following table.

Operator Description

IS Performs a case-insensitive com p a ris on of two

values. Returns true if the values are identical. IS NOT Opposite of is. CONTAINS Determines whether the value on the left is

contained in the va lue on the right. Returns true if

it is. DOES NOT CONTAIN Oppos ite of contains. GREA TER THAN Determines whethe r the value on the lef t is grea ter

than the value on the right. Returns true if it is. LESS THAN Opposite of greater than. GREA TER THAN OR EQUAL TO Determ ines whethe r the value on the lef t is grea ter

than or equal to the value on the right. Returns

true if it is. LESS THAN OR EQUAL TO Determines whether the value on the left is less

than or equal to the value on the right. Returns

true if it is.

Shorthand notation for decision operators

You can replace some decision operators with shorthand 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

18 Chapter 1 ColdFusion Expressions: Operands, Operators and Other Constructs

Operator Alternative name(s)

GREATER THAN GT LESS THAN LT GREATER THAN OR EQUAL TO GTE, GE LESS THAN OR EQUAL TO LTE, LE

String operators

There is one string operator, which is the concatenation ope rator.

Operator Description

& Concatenates strings.

Operator precedence

The order of precedence controls the order in which operators on the same line are evaluated. The order of precedence is shown below:

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 evalua tion, you must parenthesi ze expressions. For example:

• 6 - 3 * 2 is equal to 0

• (6 - 3) * 2 is equal to 6

Parenthesized expressions can be nested. When in doubt about the order in which operators in an expression will be evaluated, use parentheses.

Functions as Operators 19

Functions as Operators

Functions are a form of operator. Because ColdFusion functions return basic objects, such as numbers, strings, Boolean values, date-and-time objects, lists, arrays, structures, queries, and COM objects, function results can be used as operands.

The following sections des cribe:

• function syntax

• optional function arguments

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

For more information on how to insert functions in expressions, see “Pound Signs”

on page 20.

Optional function arguments

Functions can take optional arguments after their required arguments. If omitted, all optional arguments default to a predefined value. For example:

Replace("FooFoo", "Foo", "Boo") returns "BooFoo" Replace("FooFoo", "Foo", "Boo", "ALL") returns "BooBoo"

The differ enc e in t he r esu lts is becau se th e Replace function ta kes a n opti onal fou rth argument that specifies the scope of replacement. The default value is "ONE" which explains why only the first occurrence of "Foo" was replaced with "Boo". In the second example, a fourth argument causes the function to re pla ce all occurrences of "Foo" with "Boo".

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"))

20 Chapter 1 ColdFusion Expressions: Operands, Operators and Other Constructs

Pound Signs

Pound signs (#) have a sp ecial meani ng in CFML. Co ldFu sion tr eats te xt delim ited b y pound signs diffe re ntly from pla in te xt. Wh en C oldF usion pr ocesses a n expression, it replaces the text of the expression and the two pound signs around it with its resulting value.

For example, to output the current value of a variable named you delimit the variable name with pound signs:

<cfoutput>Value is #Form.MyFormVariable#</cfoutput>

In the exampl e ab ove, the expression #Form.MyFormVariable# is replaced with whatever value has been assigned to it.

Follow these guidelines when using pound signs:

• Use pound signs to distinguish expressions from plain text.

• When expressions are evaluated, the resulting value is substituted for the

expression text.

• Use pound signs only where necessary. See “Pound signs in general expressions”

on page 23 before using them.

The following sections provide more details on how pound signs should be used in CFML.

Pound signs in cfoutput tags

Expressions that contain one variable or a single function can be used freely inside

cfoutput tags as long as they are enclosed in pound signs. <cfoutput>

Value is #Form.MyTextField#

</cfoutput>

Form.MyFormVariable,

The name is #FirstName# #LastName#.

</cfoutput>

Cos(0) is #Cos(0)#

</cfoutput>

If pounds are omitted, the expression text rather than the expression value appears in the output generated by the

Two expressions inside pound signs can be adjacent to one another, as in this example:

"Mo" and "nk" is #Left("Moon", 2)# #Mid("Monkey", 3, 2)#

</cfoutput>

cfoutput statement.

Pound Signs 21

Complex expressions and cfoutput tags

Complex expressions, which contain more that one vari able or function, cannot be inserted inside

cfoutput tags. The following example produces an error:

To insert the value of a complex expression in the output generated by a cfoutput statement, use variable inside the

<cfset Result = 1 + 1> <cfoutput>1 + 1 is #Result#</cfoutput>

cfset to set a variable to the value of the expression, and use the

cfoutput statement, as shown below:

Pound signs in strings

Expressions that contain one variable or function can be used inside strings if they are enclosed in pound signs.

ColdFusion automatically replaces the expression text with the value of the variable or the value returned by the function. For example, the following pairs of statements produce the same result:

If pound signs are omitted, the expression text, rather than the expression value, appears in the string. For example, the following pairs of the same result:

As with the cfoutput statement, in strings, two expressions can be adjacent to each other, as in the following example:

The double quotes around "Moon" and "Monkey" need not be escaped (as in ""Moon"" and ""Monkey""). This is because the text between the pound signs is treated as an expression, it is evaluated first before its value is inserted inside the string.

Inserting complex expressions in strings

cfset

cfset statements produce

Complex expressions that have one or more operators cannot be used inside strings. The following example produces an error:

22 Chapter 1 ColdFusion Expressions: Operands, Operators and Other Constructs

To insert the value of a complex expres sion inside a string, do one of the following:

• Use

cfset to set a variable to the value of the expression and use that variable

inside the string

• Use the string concatenation operator

Both techniques are shown in the following example;

To insert the pound character in a string, use two pound signs, as shown below:

Pound signs in tag attribute values

The rule s for using pound signs inside strings also apply to the use of pound si gns inside tag attribute values. The following example demonstrates the point:

<cfcookie name = "TestCookie"

value = "The value is #CookieValue#">

If the value of a tag attribute is a variable, function, or array element, use the following syntax:

<cfcookie name = "TestCookie"

value = #CookieValue#>

<cfcookie name = "TestCookie"

value = #CookieValueArray[Index]#>

This usage is more efficient than value = "#CookieValue#".

Pound signs in custom tag attribute values

The rules described in the previous section apply to custom tags. However, custom tags can also h ave c omplex o bjects pass ed as a ttribute value s, w hich C oldFu sion t ags cannot. Complex objects, such as arrays, structures, queries, and COM objects, are passed to custom tags surrounded by pound signs (#). For example:

Nested pound signs

There are few cases in which pound signs can be nested in an expression. The following example shows a valid use of nested pound signs:

Pound signs must be nested so that the values of the variables FirstName and LastName are inserted in the string whose length the

Len function calculates. Often,

Pound Signs 23

the existence of nested pounds implies a complex expression. For example, the above CFML code could be rewritten to improve its readability:

<cfset FullName = "#FirstName# #LastName#"> <cfset Sentence = "The length of the full name

is #Len(FullName)#">

A common mistake is to put pound signs around the arguments of functions, as in:

These statements result in errors. As a general rule, never put pound signs around function arguments.

Pound signs in general expressions

Macromedia recommends that you use pound signs only when necessary. The following example shows the preferred method for referencing variables.

In contrast, note the following example, which uses pound signs unnecessarily:

24 Chapter 1 ColdFusion Expressions: Operands, Operators and Other Constructs

Chapter 2

ColdFusion Tags

This chapter describes the ColdFusion Markup Language (CFML) tags. The introduction contains an alphabetical summary of ColdFusion tags, a list of new tags in ColdFusion 5, and a list of tags by category. The rest of this chapter describes each tag in detail.

Contents

• Alphabetical List of ColdFusion Tags.......................................................................26

• New tags in ColdFusion 5.........................................................................................30

• Forms tags..................................................................................................................30

• Database manipulation tags ....................................................................................30

• Data output tags........................................................................................................30

• Exceptio n handling tags.................................................. ....... ...... ............................30

• Extensibility tags .......................................................................................................31

• File management tags...............................................................................................31

• Flow-control tags.......................................................................................................31

• Internet P r otoc ol tags...................................................... ....... ...... ....... ...... ...............31

• Java servlet and Java object tags...............................................................................31

• Page processing tags.................................................................................................31

• Variable manipulation tags......................................................................................32

• Web application framework tags .............................................................................32

26 Chapter 2 ColdFusion Tags

Alphabetical List of ColdFusion Tags

ColdFusion Markup Language (CFML) consists of a set of tags you use in ColdFusion pages to interact with data sources, manipulate data, and display output. Using CFML tags is very simple; tag syntax is much like HTML element syntax.

The following table provides brief descriptions of the CFML tags.

CFML Tag Category Description

cfabort

cfapplet cfapplication

cfassociate

cfauthenticate

cfbreak cfcache cfcol

cfcollection cfcontent

cfcookie

cfdirectory

cfdump

cferror

cfexecute

cfexit

cffile

Flow-control Stops processing of a ColdFusion page at

the tag location. Form Embeds Java applets in a cfform tag. Web app.

framework Web app.

framework

Defines application name; activates client

variables.

Enables subtag data to be saved with a

base tag.

Authenticates a user and sets the security

context for an application. Flow-control Breaks out of a CFML looping construct.

Caches ColdFusion pages. Data output Defines table column header, width,

alignment, and text . Extensibility Creates and administers Verity collections. Data output Defines the content ty pe and , op tionally, the

filename of a file to be downloaded by the

current page. Variable

Defines and sets cookie variables. manipulation

File management

Variable

Performs typical directory-handling tasks

from within a ColdFusion application.

Outputs variables for debugging purposes.

manipulation Exception

handling,

Displays customized HTML error pages

when errors occur. web app. framework

Flow-control Executes a develop er-specif ied process on

the server computer. Flow-control Aborts pr ocessing of an executing CFML

custom tag. File

management

Performs typical file-handling tasks from

within a ColdFusion app lic ati on.

Alphabetical List of ColdFusion Tags 27

CFML Tag Category Description

cfflush cfform

Data output Flushes currently availa ble dat a to th e clien t. Form Builds an input form; performs client-side

input validation.

cfftp

Internet

Permits FTP file operations. protocol

cfgraph cfgraphdata

cfgrid

Data output Displays a graphical representation of data. Data output Specifies a data point to be displayed by a

cfgraph tag.

Form Used in cfform to create a grid control for

tabular data.

cfgridcolumn

cfgridrow cfgridupdate

Form Used in cfform to define the columns used

cfgrid.

in a Form Used with cfgrid to define a grid row. Form Performs updates directly to ODBC data

source from edited grid data.

cfheader cfhtmlhead

cfhttp

Data output Generates HTTP headers. Internet

protocol Internet

protocol

Writes text, including HTML, to the HEAD

section of a page.

Performs GET and POST to upload files or

post a form, cookie, query, or CGI variable

directly to a specified server.

cfhttpparam

cfif/cfelseif/cfelse cfimpersonate

cfinclude cfindex

Internet protocol

Used with cfhttp to specify parameters

necessary for a

cfhttp POST operation.

Flow-c ontrol Create IF-THEN-ELSE constructs. Web app.

framework

Impersonates a user that is defined in an

Advanced Security context. Flow-control Embeds references to ColdFusion pages. Exception

Creates Verity search indexes. handling

cfinput

Form Used in cfform to create input elements

such as radio buttons, checkboxes, and text

entry boxes.

cfinsert cfldap

Database Inserts records in an ODBC data source. Internet

Provides access to LDAP directory servers. protocol

cflocation cflock

cflog

Flow-control Opens a ColdFusion page or HTML file . Web app.

framework

Ensures data int egri ty and sy nc hro niz es th e

execution of CFML code. Other Writes a message to a log file.

28 Chapter 2 ColdFusion Tags

CFML Tag Category Description

cfloop

Flow-control Repeats a se t o f i nst ruc tio ns based on a se t

of conditions.

cfmail

Internet

Assembles and posts an e-mail message. protocol

cfmailparam

cfmodule

cfobject

cfoutput

Internet protocol

Web app. framework

extensibility, Java

Attaches a file o r adds a he ader t o a n e-m ail

message.

Invokes a custom tag for u se in ColdFusion

application pages.

Creates and use s COM, C O RBA, and J AV A

objects. Data output Displays output of database query or other

operation.

cfparam

Variable

Defines a parameter and its default value. manipulation

cfpop

cfprocessingdirective

Internet protocol

Retrieves messages from a POP mail

server. Data output Suppresses extraneous white space and

other output.

cfprocparam

Database Spec ifi es p a ram eter information for a s tored

procedure.

cfprocresult

Database Specifies a result set name that ColdFusion

tags use to access the result set from a

stored procedure.

cfquery cfqueryparam cfregistry

Database Passes SQL to a database. Database Checks the data type of a query parameter. Other Reads, writes, and deletes keys and values

in the system registry.

cfreport

Exception

Embeds a C rystal Reports report. handling

cfrethrow

Exception

Rethrows the currently active exception. handling

cfsavecontent

cfschedule

cfscript

Variable manipulation

Web app.

Saves generated content inside the tag

body in a variable.

Schedules page execution, optionally

produces static pages.

Encloses a set of cfscript statements. framework

cfsearch

Exception handling

Executes searches against data indexed in

Verity collections using

cfindex.

Alphabetical List of ColdFusion Tags 29

CFML Tag Category Description

cfselect

Form Used in cfform to create a drop-down list

box form element.

cfservlet

extensibility,

Executes a Java servlet on a JRun engine. Java

cfservletparam

cfset

extensibility, Java

Variable

Passes data to a Jav a se rvle t. A chi ld t ag of

cfservlet.

Defines a variable. manipulation

cfsetting cfsilent

Other Defines and controls ColdFusion settings. Data output Suppresses output produced by CFML

within the tag’s scope.

cfslider

Form Used in cfform to create a slider control

element.

cfstoredproc

Database Specifies database connection information;

identifies a stored procedure to execute.

cfswitch/cfcase/ cfdefaultcase

Flow-control Evaluat es a passed expression; passes

control to the

cfcase tag that matches the

expression result.

cftable cftextinput

cfthrow

Data output Builds a table. Form Places a sing le-line text entry box in a

cfform.

Exception

Throws a developer-specified exception. handling, flow-control

cftransaction

Database Groups multiple cfquery operations into a

single transaction; performs rollback

processing.

cftree

Form Used in cfform to create a tree control

element.

cftreeitem

cftry cfcatch

Form Used with cftree to populate a tree control

cfform.

Exception handling,

element in a

Lets developers catch and process

exceptions in ColdFusion pages. flow-control

cfupdate cfwddx

Database Updates rows in a database data source. Extensibility Serializes and de-serializes CFML data

structures to the XML-based WDDX format.

30 Chapter 2 ColdFusion Tags

New tags in ColdFusion 5

cfflush cfgraph cfgraphdata cflog cfsavecontent cfdump

Forms tags

cfapplet cfgridrow cfslider cfform cfgridupdate cftextinput cfgrid cfinput cftree cfgridcolumn cfselect cftreeitem

Database manipulation tags

cfinsert cfqueryparam cfprocparam cfstoredproc cfprocresult cftransaction cfquery cfupdate

Data output tags

cfcol cfoutput cfcontent cfprocessingdirective cflog cftable

Exception handling tags

cferror cfrethrow cfthrow cftry cfcatch

Alphabetical List of ColdFusion Tags 31

Extensibility tags

cfcollection cfreport cfexecute cfsearch cfgraph cfservlet cfindex cfservletparam cfobject cfwddx

File management tags

cfdirectory cffile

Flow-control tags

cfabort cfloop cfbreak cfrethrow cfexecute cfswitch/cfcase/cfdefaultcase cfexit cfthrow cfif/cfelseif/cfelse cftry cfcatch cflocation

Internet Protocol tags

cfftp cfmail cfhttp cfmailparam cfhttpparam cfpop cfldap

Java servlet and Java object tags

cfobject cfservlet cfservletparam

Page processing tags

cfcache cfinclude cfflush cfsetting

32 Chapter 2 ColdFusion Tags

cfheader cfhtmlhead

cfsilent

Variable manipulation tags

cfcookie cfsavecontent cfdump cfschedule cfparam cfset cfregistry

Web application framework tags

cfapplication cflock cfassociate cfmodule cfauthenticate cfscript cfimpersonate

Alphabetical List of ColdFusion Tags 33

cfabort

Description Stops processing of a page at the tag location. ColdFusion returns everythi ng that

was processed be fore th e logic to stop processing a page when a condition occurs.

Category Flow-control tags

cfabort tag. The cfabort tag is often used with condit ional

Syntax

See also cfbreak, cfexecute, cfexit, cfif/cfelseif/cfelse, c flocation, cfloop,

cfswitch/cfcase/cfdefaultcase, cfthrow, cftry cfcatch

Attributes

Parameter Description

showError Optional. The error t o dis play whe n

cfabort executes. The error

message displays in the standard ColdFusion error page.

Remember that when combining output to a specified page. The

cfabort tag does not contain a showError attribute value, processing stops

If the

cfabort and cferror, cferror is meant to re dire ct

cfabort tag halts processing immediately.

immediately and ColdFusion returns the page contents up to the line that contains

cfabort tag.

the When using

page using message defined in

In a page in which you’ve defined both an error page using tag using the specified in the

cfabort with the showError attribute alon e (w ith o ut defining an error

cferror), page processing stops when the cfabort tag is reached. The

showError is displayed to the client.

cferror and a cfabort

showError attribute, ColdFusion redirects output to the error page

cferror tag.

Example

<!--- this example demonstrates the use of cfabort

to stop the processing of a cfloop. Note that in the second example, where cfabort is used, the result never

displays ---> <html> <head> <title>cfabort Example</title> </head> <body bgcolor = FFFFFF>

<H1>cfabort Example</H1> <P> <H3>Example A: Let the instruction complete itself</H3>  <cfset myVariable = 3>  <cfloop from = "1" to = "4" index = "Counter">

</cfloop>

34 Chapter 2 ColdFusion Tags

<cfoutput> <P>The value of myVariable after incrementing through the loop

#Counter# times is: #myVariable#

</cfoutput>

<H3>Example B: Use cfabort to halt the instruction</H3>

<cfif Counter is 2>

</cfloop>

<cfoutput> <P>The value of myVariable after incrementing through the loop

#counter# times is: #myVariable#

</cfoutput>

</body> </html>

Alphabetical List of ColdFusion Tags 35

cfapplet

Description Used in a cfform tag, cfapplet lets you reference custom Java applets that you have

registered using the Co ldFu sion Admi nistr ato r. To register a Java applet, open the Cold Fusion Administrator and click Applets.

Category Forms tags

Syntax

<cfapplet appletSource = "applet_name"

name = "form_variable_name" height = "height_in_pixels" width = "width_in_pixels" vSpace = "space_above_and_below_in_pixels" hSpace = "space_on_each_side_in_pixels" align = "Left" or "Right" or "Bottom" or "Top" or "TextTop" or "Middle" or "AbsMiddle" or "Baseline" or "AbsBottom" notSupported = "message_to_display_for_nonJava_browser" param_1 = "applet_parameter_name" param_2 = "applet_parameter_name" param_n = "applet_parameter_name">

See also cfdirectory

Attributes

Attribute Description

fileField Required. The name of the form field that was used to select the file.

Note: Do not use pound signs (#) to specify the field name.

destination Required. The full pathname of the destination directory or full

pathname of the file on the Web server where the file is saved. A trailing slash must be included in the target directory. Use the backward slash (\) on Windows; use the forward slash (/) on UNIX.

Note: The directory does not have to be below the root of the Web server document directory.

nameConflict Optional. Default is Error. Determines how to handle the file if its

name conflicts with the name of a file that already exists in the directory. Options are:

• Error Default. The file is not saved, ColdFusion stops processing the page and returns an error.

• Skip Neither saves t he file nor throws an error. This setting allows custom behavior based on file properties.

• Overwrite Replaces an existing file, if it has the same name as the cffile destination.

• MakeUnique Generate a unique filename for the upload. The name is stored in the file object variable serverFile. You can use this variable to record the name used w hen the file w as sav ed.

accept Optional. Limit the file types accepted. Enter one or more

comma-delimited MIME types that you want to accept. For example, to allow uploads of GIF and Microsoft Word files, enter:

accept = "image/gif, application/msword"

The browser uses the file extension to determine file type.

72 Chapter 2 ColdFusion Tags

Attribute Description

mode Optional. Defi nes p ermissi ons fo r an up loa ded fi le on UNIX an d Linu x

platforms. Ign ored in Win dows . O pti on v al ues co rres pon d to the octal values ( not symbolic) of the UNIX

chmod command. Permissions are

assigned for owner, group, and other, respectively. For example:

•

mode = "644" Assigns read/write pe rmiss ions for th e own er, and

read permissions for the group and other.

mode = "666" Assigns read/write permissions for owner, group,

•

and other.

mode = "777" Assigns read, write, and execute permissions for

•

all.

attributes Optional. A comma-delimited list of file attributes to be set on the file

being uploaded. Options are:

• readOnly

• temporary

• archive

• hidden

• system

• normal

If attributes is not used, the file’s attributes are maintained. If

normal is specified with other attributes, normal is overridden by

whatever other attribute is specified. Individual attributes must be specified explicitly. For example, if you

specify only the

readOnly attribute, all other existing attributes are

overwritten.

Example The following example creates a uniq ue fi lename i f th ere is a name conflict when the

file is uploaded on Windows:

<cffile action = "upload"

fileField = "FileContents" destination = "c:\web\uploads\" accept = "text/html" nameConflict = "MakeUnique">

Note

On Windows, you must include the backward slash (\) after the destination directory name. On UNIX, you must include the forward slash (/) after the destination directory. In this example, the specified destination directory is "uploads."

Usage After a file upload is completed, you can retrieve status information using file upload

parameters. The status information includes data about the file, such as the file’s name and the directory where it was saved. File upload status parameters use the

cffile prefix; for example, cffile.clientDirectory. The file status parameters can

be used anywhere other ColdFusion parameters can be used.

Alphabetical List of ColdFusion Tags 73

Note

Although the

cffile prefix.

file prefix is still supported, it has been deprecated in favor of the

The following file upload status parameters are available after an upload.

Parameter Description

attemptedServerFile Initial name ColdFusion used when attempting to save a file clientDirectory Directory location of the file uploaded from the client’s

system

clientFile Name of the file uploaded from the client’s system clientFileExt Extension of the uploaded file on the client’s system without a

period, for example, txt not .txt

clientFileName Filename, without an extension, of the uploaded file on the

client’s system

contentSubType MIME content subtype of the saved file contentType MIME content type of the saved file dateLastAccessed Date and time the uploaded file was last accessed fileExisted Indicates (Yes or No) whether or not the file already existed

with the same path

fileSize Size of the uploaded file fileWasAppended Indicates (Yes or No) whether ColdFusion appends the

uploaded file to an existing file

fileWasOverwritten Indicates (Yes or No) whether ColdFusion overwrites a file fileWasRenamed Indicates (Yes or No) whether the uploaded file is renamed to

avoid a name conflict

fileWasSaved Indicates (Yes or No) whether Cold Fusion saves a file oldFileSize Size of a file that was overwritten in the file upload operation serverDirectory Directory of the file save d on the server serverFile Filename of the file saved on the server serverFileExt Extension of the uploaded file on the server, without a period serverFileName Filename, without an extension, of the uploaded file on the

server

timeCreated Time the uploaded file was created timeLastModified Date and time of the last modification to the uploaded file

74 Chapter 2 ColdFusion Tags

Tip

Use the

#cffile.fileExisted#.

cffile prefix to refer to these parameters; for example,

Note

File status parameters are read-only. They are set to the results of the most recent

cffile operation. (If two cffile tags execute, the results of the first are overwritten

by the subsequent cffile operation.)

Example UNIX The following three exampl es show the use of the mode attribute on UNIX. The first

example creates the file

write, group = read, other = read <cffile action = "write"

file = "/tmp/foo"

mode = 644>

/tmp/foo with permissions defined as: owner = read/

This example appends to the specified file and makes permissions read/write (rw) for all.

<cffile action = "append"

destination = "/home/tomj/testing.txt"

mode = 666 output = "Is this a test?">

This example uploads a file and sets permissions to owner/group/other = read/

write

/execute.

cffile action = "upload"

fileField = "fieldname"

destination = "/tmp/program.exe" mode = 777>

Alphabetical List of ColdFusion Tags 75

cffile action = "move"

Description Moves a file from one location on the server to another.

Category File management tags

Syntax

<cffile action = "move"

source = "full_path_name" destination = "full_path_name" attributes = "file_attributes">

See also cfdirectory

Attributes

Attribute Description

source Required. The full pathname of the file to move. destination Required. The full pathname of the directory or full pathname of the file

attributes O ptional. A comma-delimited list of file attributes to be set on the file

to which the file will be moved. If you do not specify the filename, a trailing slash must be inclu ded in the target when movin g a fil e. Use th e backward slash (\) on Windows; use the forward slash (/) on UNIX.

being moved. The following file attributes are supported:

• readOnly

• temporary

• archive

• hidden

• system

• normal

attributes is not used, the file’s attributes are maintained. If normal

If is specified with any other attributes,

normal is overridden by whatever

other attribute is specified. Individual attributes must be specified explicitly. For example, if you

specify only the

readOnly attribute, all other existing attributes are

overwritten.

Example The following exampl e moves the keymemo.doc file from the c:\files\upload\

directory to the

<cffile action = "move"

source = "c:\files\upload\keymemo.doc" destination = "c:\files\memo\">

Note

On Windows, you must include the backward slash (\) after the destination directory name if you do not specify a filename. In this example, the specified destination directory is "memo. "

c:\files\memo\ directory on Windows:

76 Chapter 2 ColdFusion Tags

cffile action = "rename"

Description Use cffile with the rename action to rename a file on the server.

Category File management tags

Syntax

<cffile action = "rename"

source = "full_path_name" destination = "full_path_name" attributes = "file_attributes">

See also cfdirectory

Attributes

Attribute Description

source Required. The full pathname of the file to rename. destination Required. The full pathname, including the new name, of the file. attributes O ptional. A comma-delimited list of file attributes to be set on the file

being renamed. The following file attributes are supported:

• readOnly

• temporary

• archive

• hidden

• system

• normal

attributes is not used, the file’s attributes are maintained. If normal

is specified with any other attributes,

normal is overridden by whatever

other attribute is specified. Individual attributes must be specified explicitly. For example, if you

specify only the

readOnly attribute, all other existing attributes are

overwritten.

Example The following example renames the file

<cffile action = "rename"

source = "c:\files\memo\keymemo.doc"

destination = "c:\files\memo\oldmemo.doc">

keymemo.doc to oldmemo.doc:

Alphabetical List of ColdFusion Tags 77

cffile action = "copy"

Description Copies a file from one directory to another on the server.

Category File management tags

Syntax

<cffile action = "copy"

source = "full_path_name" destination = "full_path_name" attributes = "file_attributes">

See also cfdirectory

Attributes

Attribute Description

source Required. The full pathname of the file to copy. destination Required. The full p athname of the direct ory or ful l p a thna me of

attributes Optional. A comma-delimited list of file attributes to be set on the

the file where the cop y of the file i s saved. If you do not s pecify a filename, you must include the trailing slash. Use the backward slash (\) on Windows; use the forward slash (/) on UNIX.

file bei ng renamed. The following file att ributes are supported:

• readOnly

• temporary

• archive

• hidden

• system

• normal

If attributes is not used, the file’s attributes are maintained. If

normal is specified with any other attributes, normal is

overridden by whatever other attribute is specified. Individual attributes must be specified explicitly. For example, if

you specify only the

readOnly attribute, all other existing

attributes are overwritten.

Usage On Windows, you must include the backward slash (\) after the destination directory

name if you do not specify a filename. In this example, the specified destination directory is "backup."

Example The following exa mple saves a cop y of the keymemo.doc file in the c:\files\backup\

directory:

<cffile action = "copy"

source = "c:\files\upload\keymemo.doc" destination = "c:\files\backup\">

78 Chapter 2 ColdFusion Tags

cffile action = "delete"

Description Deletes a file on the server.

Category File management tags

Syntax

<cffile action = "delete"

file = "full_path_name">

See also cfdirectory

Attributes

Attribute Description

file Required. The full pathname of the file to delete.

Example The following example deletes the specified file:

<cffile action = "delete"

file = "c:\files\upload\#Variables.DeleteFileName#">

Alphabetical List of ColdFusion Tags 79

cffile action = "read"

Description Reads a text file. The file is read into a dynamic parameter that you can use anywhere

in the page, like any other dynamic parameter. F or example, you could read a text file and then insert its contents into a database, or you could read a text file and then use the find and replace functions to modify its contents.

Note

Using not intended for use with extremely large files, such as log files, because they can bring down the server.

Category File management tags

cffile action = "READ" reads the entire text file into memory . Therefore , it is

Syntax

<cffile action = "read"

file = "full_path_name" variable = "var_name">

See also cfdirectory

Attributes

Attribute Description

file Required. The full pathname of the text file to be read. variable Required. The name of the variable that will contain the contents of the

text file after it has been read.

Example The following example creates a variable named "Message " to contain the contents

of the file message.txt.

<cffile action = "read"

file = "c:\web\message.txt" variable = "Message">

The variable "Message" could then be used in the page. For example, you could display the contents of the

<cfoutput>#Message#</cfoutput>

message.txt file in the final We b page:

ColdFusion supports a number of powerful functions for manipulating the contents of text files. You can also use the variable created by a

cffile action = "read"

operation in ArrayToList and ListToArray functions. For more information about working with strings and arrays, see “String functions”

on page 313 and “Array functions” on page 310.

80 Chapter 2 ColdFusion Tags

cffile action = "readBinary"

Description Read a binary file, such as an executable or image file. The file is read into a binary

object parameter you can use anywhere in the page, like any other parameter. To send it through a Web protocol, such as HTTP or SMTP, or store it in a database, first convert it to Base64 (see “ToBase64” on page 630).

Category File management tags

Syntax

<cffile action = "readBinary"

file = "full_path_name" variable = "var_name">

See also cfdirectory

Attributes

Attribute Description

file Required. The full pathname of the file to be read. variable Required. The name of the variable that will contain the contents of the

binary file after it has been read.

Usage You convert the binary file to Base64 to FTP it to another site for upload.

Example The following example creates a variable named "aBinaryObj " to contain the

ColdFusion Server executable.

<cffile action = "readBinary"

file = "c:\cfusion\bin\cfserver.exe" variable = "aBinaryObj">

Alphabetical List of ColdFusion Tags 81

cffile action = "write"

Description Writes a text file based on dynamic content. For example, you could create static

HTML files from this content, or log actions in a text file.

Category File management tags

Syntax

<cffile action = "write"

file = "full_path_name" output = "content" mode = "permission" addNewLine = "Yes" or "No" attributes = "file_attributes">

See also cfdirectory

Attributes

Attribute Description

file Required. The full pathname of the file to be created. output Required. The content of the file to be created. mode Optional. Defines permissions for a file on Solaris or HP-UX. Ignored

on Windows. Valid entries correspond to the octal values (not symbolic) of the Unix c hmod c ommand. Permis sions are ass igned for owner, group, and other, respectively.

For example:

mode = "644" Assigns read/write pe rmiss ions for th e own er, and

•

read permissions for the group and other.

•

mode = "666" Assigns read/write permissions for owner, group,

and other.

•

mode = "777" Assigns read, write, and execute permissions for

all.

addNewLine Optional. Yes or No. If Yes, a new line character is appended to the

text that is written to the fil e. If No, no n ew li ne c har act er is app end ed to the text. The default value is Yes.

82 Chapter 2 ColdFusion Tags

Attribute Description

attributes Optional. A comma-delimited list of file attributes to be set on the file

being written. The following file attributes are supported:

• readOnly

• temporary

• archive

• hidden

• system

• normal

attributes is not used, the file’s attributes are maintained. If

normal is specified with any other attributes, normal is overridden by

whatever other attribute is specified. Individual attributes must be specified explicitly. For example, if you

specify only the

readOnly attribute, all other existing attributes are

overwritten.

Example The following example creates a file with the information a user entered into an

HTML insert form:

<cffile action = "write"

file = "c:\files\updates\#Form.UpdateTitle#.txt"

output = "Created By: #Form.FullName# Date: #Form.Date# #Form.Content#">

If the user submitted a form with:

UpdateTitle = "FieldWork" FullName = "World B. Frueh"

Date = "10/30/98" Content = "We had a wonderful time in Cambridgeport."

ColdFusion would create a file named FieldWork.txt in the c:\files\updates\ directory and the file would contain the text:

Created By: World B. Frueh Date: 10/30/98

We had a wonderful time in Cambridgeport.

This following examples show the use of the mode attribute for UNIX. The first, creates the file

write, group = read, other = read)

/tmp/foo with permissions defined as rw-r—r-- (owner = read/

<cffile action = "write"

file = "/tmp/foo"

mode = 644>

This example appends to the file and sets permissions to read/write (rw) for all.

<cffile action = "append"

destination = "/home/tomj/testing.txt"

mode = 666 output = "Is this a test?">

MACROMEDIA COLDFUSION 5 - CFML, COLDFUSION 5 Reference

Specifications and Main Features

Frequently Asked Questions

User Manual