Macromedia CFML Language Reference User Manual
CFML Language
Reference
ColdFusion 4.5
Allaire Corporation
Copyright Notice
© 1999 Allaire Corporation. All rights reserved.
This manual, as well as the software described in it, is furnished under license and may
be used or copied only in accordance with the terms of such license. The content of
this manual is furnished for informational use only, is subject to change without
notice, and should not be construed as a commitment by Allaire Corporation. Allaire
Corporation 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 Allaire
Corporation.
ColdFusion and HomeSite are federally registered trademarks of Allaire Corporation.
HomeSite, the ColdFusion logo and the Allaire logo are trademarks of Allaire
Corporation in the USA and other countries. Microsoft, Windows, Windows NT,
Windows 95, Microsoft Access, and FoxPro are registered trademarks of Microsoft
Corporation. All other products or name brands are the trademarks of their respective
holders. Solaris is a trademark of Sun Microsystems Inc. UNIX is a trademark of The
Open Group. PostScript is a trademark of Adobe Systems Inc.
Part number: AA-45LNG-RK
Contents
Preface: Welcome To ColdFusion ................................................................xiii
Intended Audience.........................................................................................................................xiv
Welcome to the ColdFusion 4.5 Web Application Server...........................................................xiv
Products and System Requirements ............................................................................................xiv
New features in ColdFusion 4.5 .....................................................................................................xv
New visual tools......................................................................................................................xvi
Enhancements to CFML ........................................................................................................xvi
Better reliability ......................................................................................................................xvi
Improved performance.........................................................................................................xvii
Enterprise connectivity features ..........................................................................................xvii
Security enhancements....................................................................................................... xviii
Language Reference Features.......................................................................................................xix
Using Examples ......................................................................................................................xix
Using Code Snippets..............................................................................................................xix
Using End Tags................................................................................................................................xx
Developer Resources ......................................................................................................................xx
About ColdFusion Documentation..............................................................................................xxi
Documentation updates........................................................................................................xxi
ColdFusion manuals ..............................................................................................................xxi
ColdFusion Server online documentation..........................................................................xxii
Printing ColdFusion documentation...................................................................................xxii
Documentation conventions.............................................................................................. xxiii
Getting Answers .......................................................................................................................... xxiii
Contacting Allaire................................................................................................................ xxiii
Chapter 1: ColdFusion Tags.............................................................................1
Alphabetical List of ColdFusion Tags ............................................................................................. 2
New Tags in ColdFusion 4.5............................................................................................................ 5
ColdFusion Forms Tags................................................................................................................... 6
Database Manipulation Tags.......................................................................................................... 6
Data Output Tags............................................................................................................................. 6
Exception Handling Tags ................................................................................................................ 6
Extensibility Tags ............................................................................................................................. 7
File Management Tags..................................................................................................................... 7
iv CFML Language Reference
Flow-Control Tags ............................................................................................................................7
Internet Protocol Tags......................................................................................................................7
Java Servlet and Java Object Tags....................................................................................................8
Variable Manipulation Tags.............................................................................................................8
Web Application Framework Tags ..................................................................................................8
Other Tags .........................................................................................................................................8
CFABORT...........................................................................................................................................9
CFAPPLET........................................................................................................................................11
CFAPPLICATION ............................................................................................................................13
CFASSOCIATE.................................................................................................................................16
CFAUTHENTICATE........................................................................................................................17
CFBREAK .........................................................................................................................................19
CFCACHE ........................................................................................................................................20
CFCOL..............................................................................................................................................23
CFCOLLECTION .............................................................................................................................25
CFCONTENT...................................................................................................................................28
CFCOOKIE.......................................................................................................................................30
CFDIRECTORY................................................................................................................................33
CFERROR.........................................................................................................................................36
CFERROR Error Variables.......................................................................................................37
CFEXECUTE ....................................................................................................................................40
CFEXIT.............................................................................................................................................42
CFFILE .............................................................................................................................................45
CFFILE ACTION attributes.....................................................................................................46
CFFILE ACTION="Upload"............................................................................................................47
Evaluating the results of a file upload....................................................................................49
CFFILE ACTION="Move"...............................................................................................................51
CFFILE ACTION="Rename" ..........................................................................................................52
CFFILE ACTION="Copy" ...............................................................................................................53
CFFILE ACTION="Delete" .............................................................................................................54
CFFILE ACTION="Read"................................................................................................................54
CFFILE ACTION="ReadBinary".....................................................................................................55
CFFILE ACTION="Write"...............................................................................................................55
CFFILE ACTION="Append"...........................................................................................................58
CFFORM ..........................................................................................................................................59
Incorporating HTML form tags..............................................................................................60
CFFTP ..............................................................................................................................................63
Establishing a Connection with CFFTP.................................................................................63
File and Directory Operations with CFFTP...........................................................................66
CFFTP.ReturnValue Variable..................................................................................................70
Accessing the Columns in a Query Object ............................................................................70
Connection Caching ...............................................................................................................71
CFGRID............................................................................................................................................73
Select mode and form variables.............................................................................................78
Using SELECTMODE="Edit"..................................................................................................78
Using the HREF attribute........................................................................................................78
CFGRIDCOLUMN...........................................................................................................................81
CFGRIDROW...................................................................................................................................86
CFGRIDUPDATE.............................................................................................................................87
Contents v
CFHEADER......................................................................................................................................90
CFHTMLHEAD................................................................................................................................91
CFHTTP ...........................................................................................................................................92
CFHTTPPARAM ..............................................................................................................................98
CFIF/CFELSEIF/CFELSE..............................................................................................................100
CFIMPERSONATE.........................................................................................................................102
CFINCLUDE..................................................................................................................................104
CFINDEX .......................................................................................................................................105
CFINPUT .......................................................................................................................................109
CFINSERT......................................................................................................................................112
CFLDAP..........................................................................................................................................115
CFLOCATION................................................................................................................................121
CFLOCK .........................................................................................................................................122
CFLOOP .........................................................................................................................................129
Index Loops............................................................................................................................129
Conditional Loops.................................................................................................................130
Looping over a Query............................................................................................................131
Looping over a List................................................................................................................132
Looping over a COM Collection or Structure......................................................................133
CFMAIL..........................................................................................................................................135
CFMAILPARAM.............................................................................................................................138
CFMODULE ..................................................................................................................................140
CFOBJECT .....................................................................................................................................143
CFOBJECT TYPE attributes...................................................................................................143
CFOBJECT Type="COM" .............................................................................................................144
CFOBJECT Type="CORBA"..........................................................................................................146
CFOBJECT Type="JAVA"..............................................................................................................147
CFOUTPUT ...................................................................................................................................149
CFPARAM ......................................................................................................................................151
CFPOP............................................................................................................................................154
CFPROCESSINGDIRECTIVE........................................................................................................159
CFPROCPARAM............................................................................................................................160
CFPROCRESULT...........................................................................................................................163
CFQUERY ......................................................................................................................................165
CFQUERYPARAM .........................................................................................................................170
CFREGISTRY .................................................................................................................................174
CFREGISTRY ACTION attributes.........................................................................................174
CFREGISTRY ACTION="GetAll"..................................................................................................175
CFREGISTRY ACTION="Get".......................................................................................................176
CFREGISTRY ACTION="Set".......................................................................................................177
CFREGISTRY ACTION="Delete" .................................................................................................178
CFREPORT.....................................................................................................................................180
CFRETHROW ................................................................................................................................182
CFSCRIPT ......................................................................................................................................184
CFSEARCH.....................................................................................................................................185
CFSELECT......................................................................................................................................189
CFSERVLET ...................................................................................................................................192
CFSERVLETPARAM ......................................................................................................................194
CFSET.............................................................................................................................................197
vi CFML Language Reference
Arrays......................................................................................................................................197
Dynamic variable names ......................................................................................................197
COM objects ..........................................................................................................................197
CFSETTING ...................................................................................................................................199
CFSILENT ......................................................................................................................................201
CFSLIDER......................................................................................................................................202
CFSTOREDPROC ..........................................................................................................................207
CFSWITCH/CFCASE/CFDEFAULTCASE....................................................................................210
CFTABLE........................................................................................................................................212
CFTEXTINPUT..............................................................................................................................214
CFTHROW.....................................................................................................................................218
CFTRANSACTION.........................................................................................................................220
CFTREE..........................................................................................................................................223
CFTREEITEM ................................................................................................................................228
CFTRY/CFCATCH.........................................................................................................................232
CFUPDATE....................................................................................................................................236
CFWDDX .......................................................................................................................................239
Chapter 2: ColdFusion Functions................................................................241
Alphabetical List of ColdFusion Functions.................................................................................242
New Functions in ColdFusion 4.5 ...............................................................................................245
Array Functions.............................................................................................................................245
Authentication Functions............................................................................................................245
Date and Time Functions.............................................................................................................246
Decision Functions.......................................................................................................................246
Display and Formatting Functions..............................................................................................247
Dynamic Evaluation Functions...................................................................................................247
International Functions ...............................................................................................................247
List Functions................................................................................................................................248
Mathematical Functions..............................................................................................................248
Query Functions ...........................................................................................................................249
String Functions............................................................................................................................249
Structure Functions......................................................................................................................250
System Functions..........................................................................................................................250
Other Functions............................................................................................................................250
Abs..................................................................................................................................................251
ACos ...............................................................................................................................................252
ArrayAppend .................................................................................................................................254
ArrayAvg.........................................................................................................................................255
ArrayClear......................................................................................................................................257
ArrayDeleteAt................................................................................................................................258
ArrayInsertAt.................................................................................................................................259
ArrayIsEmpty.................................................................................................................................260
ArrayLen ........................................................................................................................................261
ArrayMax .......................................................................................................................................262
ArrayMin........................................................................................................................................264
ArrayNew.......................................................................................................................................266
ArrayPrepend ................................................................................................................................267
Contents vii
ArrayResize....................................................................................................................................268
ArraySet..........................................................................................................................................269
ArraySort........................................................................................................................................270
ArraySum.......................................................................................................................................271
ArraySwap......................................................................................................................................273
ArrayToList ....................................................................................................................................274
Asc ..................................................................................................................................................275
ASin ................................................................................................................................................276
Atn..................................................................................................................................................278
AuthenticatedContext ..................................................................................................................279
AuthenticatedUser........................................................................................................................280
BitAnd ............................................................................................................................................281
BitMaskClear.................................................................................................................................282
BitMaskRead .................................................................................................................................283
BitMaskSet.....................................................................................................................................284
BitNot.............................................................................................................................................285
BitOr...............................................................................................................................................286
BitSHLN.........................................................................................................................................287
BitSHRN.........................................................................................................................................288
BitXor .............................................................................................................................................289
Ceiling............................................................................................................................................290
Chr..................................................................................................................................................291
CJustify...........................................................................................................................................292
Compare ........................................................................................................................................293
CompareNoCase...........................................................................................................................295
Cos..................................................................................................................................................296
CreateDate.....................................................................................................................................297
CreateDateTime............................................................................................................................299
CreateObject..................................................................................................................................301
Object Types ..........................................................................................................................301
COM...............................................................................................................................................301
CORBA ...........................................................................................................................................302
JAVA................................................................................................................................................303
CreateODBCDate..........................................................................................................................305
CreateODBCDateTime.................................................................................................................307
CreateODBCTime.........................................................................................................................309
CreateTime....................................................................................................................................311
CreateTimeSpan ...........................................................................................................................313
CreateUUID...................................................................................................................................314
DateAdd.........................................................................................................................................315
DateCompare................................................................................................................................317
DateConvert ..................................................................................................................................320
DateDiff .........................................................................................................................................323
DateFormat ...................................................................................................................................325
DatePart.........................................................................................................................................327
Day .................................................................................................................................................329
DayOfWeek....................................................................................................................................330
DayOfWeekAsString .....................................................................................................................331
DayOfYear......................................................................................................................................332
viii CFML Language Reference
DaysInMonth ................................................................................................................................333
DaysInYear ....................................................................................................................................334
DE...................................................................................................................................................335
DecimalFormat .............................................................................................................................336
DecrementValue ...........................................................................................................................337
Decrypt ..........................................................................................................................................338
DeleteClientVariable ....................................................................................................................339
DirectoryExists..............................................................................................................................340
DollarFormat.................................................................................................................................341
Encrypt...........................................................................................................................................342
Evaluate .........................................................................................................................................343
Exp..................................................................................................................................................344
ExpandPath ...................................................................................................................................345
FileExists........................................................................................................................................346
Find ................................................................................................................................................347
FindNoCase...................................................................................................................................348
FindOneOf.....................................................................................................................................349
FirstDayOfMonth..........................................................................................................................350
Fix...................................................................................................................................................351
FormatBaseN.................................................................................................................................352
GetBaseTagData............................................................................................................................353
GetBaseTagList..............................................................................................................................354
GetBaseTemplatePath..................................................................................................................355
GetClientVariablesList..................................................................................................................356
GetCurrentTemplatePath.............................................................................................................357
GetDirectoryFromPath.................................................................................................................358
GetFileFromPath...........................................................................................................................359
GetFunctionList ............................................................................................................................360
GetLocale.......................................................................................................................................361
GetMetricData...............................................................................................................................363
GetProfileString.............................................................................................................................365
GetTempDirectory........................................................................................................................367
GetTempFile..................................................................................................................................368
GetTemplatePath..........................................................................................................................369
GetTickCount................................................................................................................................370
GetTimeZoneInfo .........................................................................................................................371
GetToken .......................................................................................................................................372
Hour ...............................................................................................................................................373
HTMLCodeFormat .......................................................................................................................374
HTMLEditFormat .........................................................................................................................376
IIf ....................................................................................................................................................378
IncrementValue ............................................................................................................................381
InputBaseN....................................................................................................................................382
Insert..............................................................................................................................................383
Int ...................................................................................................................................................384
IsArray............................................................................................................................................385
IsAuthenticated.............................................................................................................................386
IsAuthorized..................................................................................................................................387
IsBinary..........................................................................................................................................390
Contents ix
IsBoolean.......................................................................................................................................391
IsDate.............................................................................................................................................392
IsDebugMode................................................................................................................................393
IsDefined .......................................................................................................................................394
IsLeapYear .....................................................................................................................................395
IsNumeric......................................................................................................................................396
IsNumericDate..............................................................................................................................397
IsProtected.....................................................................................................................................398
IsQuery...........................................................................................................................................401
IsSimpleValue................................................................................................................................402
IsStruct...........................................................................................................................................403
JSStringFormat..............................................................................................................................404
LCase..............................................................................................................................................405
Left .................................................................................................................................................406
Len..................................................................................................................................................407
ListAppend ....................................................................................................................................408
ListChangeDelims.........................................................................................................................409
ListContains ..................................................................................................................................410
ListContainsNoCase.....................................................................................................................412
ListDeleteAt...................................................................................................................................413
ListFind..........................................................................................................................................414
ListFindNoCase.............................................................................................................................416
ListFirst ..........................................................................................................................................417
ListGetAt ........................................................................................................................................418
ListInsertAt ....................................................................................................................................419
ListLast...........................................................................................................................................420
ListLen ...........................................................................................................................................421
ListPrepend ...................................................................................................................................422
ListQualify .....................................................................................................................................423
ListRest...........................................................................................................................................425
ListSetAt.........................................................................................................................................426
ListSort...........................................................................................................................................428
ListToArray ....................................................................................................................................430
ListValueCount..............................................................................................................................431
ListValueCountNoCase ................................................................................................................433
LJustify ...........................................................................................................................................435
Log..................................................................................................................................................436
Log10..............................................................................................................................................437
LSCurrencyFormat .......................................................................................................................438
LSDateFormat...............................................................................................................................441
LSEuroCurrencyFormat ...............................................................................................................443
LSIsCurrency.................................................................................................................................447
LSIsDate.........................................................................................................................................448
LSIsNumeric..................................................................................................................................449
LSNumberFormat.........................................................................................................................450
LSParseCurrency...........................................................................................................................453
Currency output ....................................................................................................................453
LSParseDateTime..........................................................................................................................456
LSParseEuroCurrency ..................................................................................................................458
x CFML Language Reference
LSParseNumber ............................................................................................................................460
LSTimeFormat ..............................................................................................................................461
LTrim..............................................................................................................................................463
Max.................................................................................................................................................464
Mid .................................................................................................................................................465
Min.................................................................................................................................................466
Minute............................................................................................................................................467
Month ............................................................................................................................................468
MonthAsString..............................................................................................................................469
Now................................................................................................................................................470
NumberFormat.............................................................................................................................471
ParagraphFormat..........................................................................................................................474
ParameterExists ............................................................................................................................475
ParseDateTime..............................................................................................................................476
Pi.....................................................................................................................................................478
PreserveSingleQuotes...................................................................................................................479
Quarter...........................................................................................................................................480
QueryAddColumn.........................................................................................................................481
QueryAddRow ...............................................................................................................................483
QueryNew......................................................................................................................................484
QuerySetCell..................................................................................................................................485
QuotedValueList ...........................................................................................................................487
Rand...............................................................................................................................................488
Randomize.....................................................................................................................................489
RandRange ....................................................................................................................................490
REFind ...........................................................................................................................................491
REFindNoCase ..............................................................................................................................494
RemoveChars ................................................................................................................................497
RepeatString..................................................................................................................................498
Replace...........................................................................................................................................499
ReplaceList ....................................................................................................................................500
ReplaceNoCase .............................................................................................................................502
REReplace......................................................................................................................................503
REReplaceNoCase.........................................................................................................................504
Reverse...........................................................................................................................................505
Right...............................................................................................................................................506
RJustify...........................................................................................................................................507
Round.............................................................................................................................................508
RTrim .............................................................................................................................................509
Second ...........................................................................................................................................510
SetLocale........................................................................................................................................511
Locale support.......................................................................................................................511
SetProfileString .............................................................................................................................513
SetVariable.....................................................................................................................................515
Sgn..................................................................................................................................................516
Sin...................................................................................................................................................517
SpanExcluding ..............................................................................................................................518
SpanIncluding...............................................................................................................................519
Sqr ..................................................................................................................................................520
Contents xi
StripCR...........................................................................................................................................521
StructClear.....................................................................................................................................522
StructCopy.....................................................................................................................................523
StructCount ...................................................................................................................................524
StructDelete...................................................................................................................................525
StructFind......................................................................................................................................527
StructInsert....................................................................................................................................528
StructIsEmpty................................................................................................................................530
StructKeyArray ..............................................................................................................................531
StructKeyExists..............................................................................................................................534
StructKeyList .................................................................................................................................535
StructNew......................................................................................................................................538
StructUpdate.................................................................................................................................539
Tan .................................................................................................................................................540
TimeFormat...................................................................................................................................541
ToBase64........................................................................................................................................543
ToBinary ........................................................................................................................................545
ToString .........................................................................................................................................547
Trim................................................................................................................................................549
UCase.............................................................................................................................................550
URLDecode ...................................................................................................................................551
URLEncodedFormat.....................................................................................................................552
Val...................................................................................................................................................553
ValueList ........................................................................................................................................554
Week...............................................................................................................................................555
WriteOutput ..................................................................................................................................556
XMLFormat ...................................................................................................................................557
Year ................................................................................................................................................558
YesNoFormat.................................................................................................................................559
Chapter 3: WDDX JavaScript Objects .........................................................561
WddxSerializer Object..................................................................................................................562
serialize ..................................................................................................................................562
serializeVariable ....................................................................................................................562
serializeValue.........................................................................................................................563
write........................................................................................................................................564
WddxRecordset Object.................................................................................................................565
addColumn............................................................................................................................565
addRows.................................................................................................................................566
getField...................................................................................................................................566
getRowCount.........................................................................................................................567
setField...................................................................................................................................568
wddxSerialize.........................................................................................................................568
Chapter 4: ColdFusion Expressions: Operators and Other Constructs....571
Elements of ColdFusion Expressions..........................................................................................572
Notes on date-and-time values............................................................................................574
xii CFML Language Reference
Notes on using variables.......................................................................................................575
Operators.......................................................................................................................................576
Arithmetic operators.............................................................................................................576
String operators.....................................................................................................................577
Decision, or comparison, operators....................................................................................577
Boolean operators.................................................................................................................579
Operator Precedence....................................................................................................................579
Function Syntax ............................................................................................................................580
Optional arguments in functions.........................................................................................580
Pound Signs...................................................................................................................................581
Pound signs inside CFOUTPUT tags ...................................................................................581
Pound signs inside strings....................................................................................................582
Pound signs inside tag attribute values...............................................................................583
Nested pound signs...............................................................................................................583
Pound signs in general expressions.....................................................................................584
Preface Welcome To ColdFusion
ColdFusion is a rapid application development system for professional developers
who want to create dynamic Web applications and interactive Web sites. It provides
the fastest way to integrate browser, server, and database technologies into powerful
Web applications. With ColdFusion, you can build everything from online stores to
sophisticated business systems.
Developing applications with ColdFusion does not require coding in a traditional
programming language; instead, you build applications by combining standard
HTML with a straightforward server-side markup language, the ColdFusion Markup
Language (CFML). This manual documents CFML.
Contents
• Intended Audience.......................................................................................... xiv
• Welcome to the ColdFusion 4.5 Web Application Server............................. xiv
• Products and System Requirements.............................................................. xiv
• New features in ColdFusion 4.5 ...................................................................... xv
• Language Reference Features......................................................................... xix
• Using End Tags ..................................................................................................xx
• Developer Resources.........................................................................................xx
• About ColdFusion Documentation ............................................................... xxi
• Getting Answers ............................................................................................xxiii
xiv CFML Language Reference
Intended Audience
This reference is intended for web developers who have a working knowledge of
ColdFusion; that is, you know how to use tags and functions, but you need a
comprehensive reference that provides an in-depth description of each tag and
function, and examples of how tags and functions are used in the context of an HTML/
CFML page.
Welcome to the ColdFusion 4.5 Web Application Server
The ColdFusion 4.5 release focuses on fundamentals — the fundamentals of delivering
your e-business: faster development, better reliability, enhanced scalability, expanded
integration, and stronger security.
At the center of the ColdFusion 4.5 release is an application server platform that's been
highly optimized with new functionality and native support for UNIX. As a result, your
e-business systems will run better and do more. With this release we're launching a
new edition of ColdFusion Server for Linux so you can take advantage of the reliability
and performance of the hottest new Internet server operating system.
While optimizing the core server, we also enhanced fundamental features including
email integration, server-side FTP and HTTP, advanced security, scheduling, and
database connectivity — again giving you more reliability and new functionality.
The focus on fundamentals extends to new features. As part of a broad new
commitment to Java, ColdFusion 4.5 has a range of new Java integration options from
Java CFXs to Java Servlet support to Java object and EJB connectivity. In ColdFusion
Studio 4.5, we added new tools to make you more productive including a flexible new
project architecture that makes managing and deploying complex Web applications a
snap. On the server, we focused on reliability, performance and security with features
such as service-level fail-over, Cisco Local Director integration, and OS security
integration.
Whether you're revolutionizing your company's HR operations, building the next
generation of your firm's global intranet, or launching the next killer .COM company,
you'll find the speed, scalability, connectivity, and security you need in ColdFusion 4.5.
Products and System Requirements
ColdFusion has been fully tested on the following platforms and with the following
configurations.
ColdFusion Server 4.5 Enterprise Edition for Windows
• Windows NT 4.0 SP4+
• Intel Pentium or above
• 150 MB hard disk space
Preface xv
• 128 MB RAM (256 MB recommended for clustering)
ColdFusion Server 4.5 Enterprise Edition for Solaris
• SPARC Solaris 2.5.1, 2.6, or 7 (patch 103582-1B or higher)
• 128 MB RAM (256 MB recommended for clustering)
• 200 MB hard disk space
ColdFusion Server 4.5 Enterprise Edition for Linux
• Red Hat Linux 6.0 or 6.1
• Intel Pentium or above
• 128 MB RAM (256 MB recommended for clustering)
• 150 MB hard disk space
ColdFusion Server 4.5 Professional Edition for Windows
• Windows 95/98 or Windows NT 4.0
• Intel Pentium or above
• 50 MB hard disk space
• 32 MB RAM (128 MB recommended)
ColdFusion Server 4.5 Professional Edition for Linux
• Red Hat Linux 6.0 or 6.1
• Intel Pentium or above
• 64 MB RAM (128 MB recommended)
• 100 MB hard disk space
ColdFusion Studio 4.5
• Windows 95/98/NT4
• Intel Pentium or above
• 35 MB hard disk space
• 32 MB RAM (64 MB recommended)
New features in ColdFusion 4.5
A wide range of new features are available in ColdFusion 4.5.
xvi CFML Language Reference
New visual tools
Universal File Browser — Access all your files from a single explorer that integrates
access to the Windows file system, ColdFusion RDS servers, and FTP servers. Dragand-drop between any of these services all in an integrated file browser.
Advanced Project Management — Manage your complex Web application
development projects with a new project architecture that gives you more flexibility
and control using physical, virtual, and auto-inclusive project folders as well as project
resource browsing.
Scriptable Deployment — Deploy applications to complex server configurations with
FTP or ColdFusion Remote Development Services (RDS). Use VBScript or Java Script to
fully script deployment of projects with granular control over how files uploaded.
Setup deployment scripts using a powerful wizard and save scripts for re-use.
Collapsible Code — Work with large, complex scripts and pages more easily by
collapsing sections of the code in the editor so you can build sophisticated
applications more quickly.
Function Insight — Find the parameters and format for functions instantly and inline
as you code.
Image Map Editor — Create image maps right in ColdFusion Studio with a new easyto-use visual tool.
Configuration Wizard — Setup your work environment so it meets all your needs
using any of more than dozen common configurations.
TopStyle CSS Editor — Create and edit standards-compliant cascading style sheets to
easily control the look and feel of your web applications.
WML Support — Build wireless Web applications quickly and easily with the complete
set of Wireless Markup Language (WML) visual tools.
Enhancements to CFML
Object Scripting — Instantiate and script objects using CFML script in addition to the
CFOBJECT tag easier integration with distributed object middleware such as COM and
CORBA.
Structured Exception Handling — Exception handling now offers hierarchical
exception handling that supports both greater customization and greater access to
internal exceptions.
String Conversion Functions — Convert strings quickly and easily to be compatible
with Java Script and XML standards.
Better reliability
Server Probes — Guarantee high availability by automatically detecting when a
ColdFusion Server or Web server hangs or stops, failing-over to a new machine in a
ColdFusion cluster, and restarting the server with problems. (Enterprise Edition only)
Preface xvii
Improved Automatic Server Recovery — Monitor and automatically restart server
process in case of failures or critical errors on individual servers not deployed in a
cluster.
Clustering Support for Apache — Setup ColdFusion clusters on Linux and Solaris
using the Apache Web Server. (Enterprise Edition only)
Automatic Shared Variable Locking — Lock user and session variable reads
automatically at the server level to prevent destabilizing conflicts and control thread
write contentions. Configure variable locking to meet the specific needs of your
applications.
Individual Data Source Control — Enable and disable individual data sources
individually without affecting server availability for runtime data source maintenance
without server restarts.
Improved performance
Cisco Local Director Integration — Deliver very large scale sites with Cisco Local
Director intelligently balancing load based on the load metrics provided by the
ColdFusion Servers in a cluster. (Enterprise Edition only)
Client-Side Page Caching — Leverage browser page caching to avoid unnecessary
downloads of unchanged pages and improve overall site performance.
Programmatically control refresh of client-side cache to ensure users see most up-todate output.
White Space Removal — Reduce white space left by processed code in application
pages to make the pages smaller and faster. Control white space removal
programmatically or administratively.
Scriptable Performance Metrics — Track key server metrics at run time through your
own scripts for intelligent diagnosis of performance bottlenecks of stability problems
in your applications.
Performance Debugging Data — Access detailed debugging information on the
performance of each individual page included in an application page that is being
debugged.
Enterprise connectivity features
Transaction Commit and Rollback — Control database transactions with
programmable commit and rollback support for more reliable and better-managed
database interactions.
Java Object and EJB Connectivity — Connect to any Java object or Enterprise JavaBean
(EJB) hosted by any major EJB server to extend ColdFusion and access complex
business logic or third party distributed components.
Java Servlets — Call Java Servlets hosted by a Servlet Engine such as Allaire JRun from
within a ColdFusion application to access extended functionality
xviii CFML Language Reference
Java-based ColdFusion Extensions (CFX) — Extend ColdFusion with new
functionality through CFXs created with Java.
Binary Object Support — Use Character Large Binary Object (CLOB) support to
encoded binary objects, transmit them via XML, and store them in databases or files.
SQL Bind Parameters — Improve query performance, security and flexibility with
explicitly typed query parameters.
WDDX 1.0 — Exchange complex data, including encoded images, between servers and
with other programming environments even faster using the latest version of Web
Distributed Data Exchange ( WDDX).
OS Command Execution — Execute OS shell scripts, services, executables and batch
files from within ColdFusion applications.
LDAP 3.0 — Use all the power of LDAP 3.0 for directory access including file filtering,
SSL encryption, and Microsoft Active Directory integration.
Enhanced Mail Integration — Develop more sophisticated and robust email
applications with new support for controlling mail headers, BCC, and multiple file
attachments.
Improved Server-Side HTTP — Use URL redirection, SSL, cookies, return headers, and
more robust server-side HTTP support for building distributed Web applications.
Security enhancements
General OS Security Integration — Secure entire Web applications and control access
to files and objects through your existing Windows NT security architecture.
Authenticated users in your applications can be limited to privileges authorized
through Windows security. (Windows NT Only)
OS Server Sandbox Security — Secure shared hosting environments more easily by
creating Server Sandboxes with Windows NT security. OS Server Sandboxes process all
requests under the privileges of a designated Windows NT user account (Enterprise
Edition for Windows only).
Enhanced Advanced Security — Secure CFML functions and enable CFML code
segments to be executed using the run-time security permissions of a designated user.
New Advanced Security Interface — Manage Advanced Security configuration more
quickly and easily with a completely redesigned browser-based resource view.
Scriptable Advanced Security Administration — Configure ColdFusion Advanced
Security through your own CFML scripts for easier maintenance of ColdFusion
Servers.
Preface xix
Language Reference Features
The CFML Language Reference provides descriptions, syntax, usage, and code
examples for:
• CFML Tags
• CFML Functions
• JavaScript objects used when implementing web distributed data exchange
(WDDX)
The CFML Language Reference also provides a chapter on expressions, operators, and
other CFML constructs.
Using Examples
Each tag and function features a runnable example, using code drawn from the
snippets directory (found in webroot\cfdocs\snippets). The display and usage for these
examples differs depending on the delivery mechanism:
• Printed and PDF documentation — Whenever possible, the printed
documentation displays a complete example. In some cases, extraneous code
has been removed to maintain clarity and to conserve space.
• HTML documentation — Each tag or function displays an examples button
that you click to execute that element. The online example displays two frames:
one that runs the example, and one that displays the associated code. In some
cases, code examples are view-only due to logistic, administrative, or security
reasons.
The examples button uses a relative reference to access the page that runs the
code snippet. Snippets will not run if files have been moved or if ColdFusion
Server is not running.
When running examples using ColdFusion Studio on a workstation that isn’t
running ColdFusion Server, you will need to specify the ColdFusion Server
location using the Browse tab on the Settings dialog box.
Using Code Snippets
The snippets directory contains example code for every CFML tag and function. You
can browse this directory to find examples of CFML tag and function usage in many
different contexts.
xx CFML Language Reference
Using End Tags
Except where noted in the syntax, CFML tags do not require an end tag. However, all
CFML tags (except CFELSE and CFELSEIF) can accept an optional end tag, as follows:
• Shorthand — You can use shorthand notation to include the end tag with the
base tag. For example:
<CFABORT/>
• Explicit specification — You can specify an end tag explicitly. However, there
can be no white space between the start and end tags. For example:
<CFABORT></CFABORT>
<!--- The following will produce a validation error
<CFABORT>
</CFABORT> --->
You do not typically code optional end tags.
Developer Resources
Allaire Corporation is committed to setting the standard for customer support in
developer education, technical support, and professional services. Our Web site is
designed to give you quick access to the entire range of online resources.
Allaire Developer Services
Resource Description
Allaire Web site
www.allaire.com
Technical Support
www.allaire.com/support
Training and Consulting
www.allaire.com/services
Developer Community
www.allaire.com/developer
Allaire Partners
www.allaire.com/partners
General information about Allaire products and
services.
Allaire offers a wide range of professional support
programs. This page explains all of the available
options.
Information about training classes, online
courses, and consulting services offered by
Allaire.
All of the resources you need to stay on the
cutting edge of ColdFusion development,
including online discussion groups, Knowledge
Base, Component Exchange, Resource Library,
technical papers and more.
The Allaire Alliance is a network of solution
providers, application developers, resellers, and
hosting services creating solutions with
ColdFusion.
Preface xxi
About ColdFusion Documentation
ColdFusion documentation is designed to provide support for all components of the
ColdFusion development system. Both the print and online versions are organized to
allow you to quickly locate the information you need.
In addition to the book set, the documentation is provided in two other formats:
• HTML — Browser-based Help references.
• Adobe Acrobat (PDF) — Available from the root level on the product CD-ROM
and from the Developer area of Allaire’s Web site at http://www.allaire.com/
developer
Documentation updates
Late additions and corrections to ColdFusion printed documentation are listed in the
Documentation Updates page. To reach this page, open the Welcome to ColdFusion
page installed with ColdFusion, where you’ll find links to the update page as well as
links to other pages containing useful information about ColdFusion, Allaire support
options, and Allaire products and services.
For ColdFusion Studio users, you can access the documentation update page by
clicking on the Help resource tab and browsing your way through the online help tree
to the Allaire Support folder.
.
ColdFusion manuals
The core ColdFusion documentation set consists of the following titles.
Administering ColdFusion Server
Includes instructions for installing ColdFusion Server. Describes configuration options
for maximizing performance, managing data sources, setting security levels, and a
range of development and site management tasks. If you are administering a
ColdFusion site, you’ll need this book to help plan and implement ColdFusion
security, load balancing, and for details about tuning the ColdFusion application
server.
Developing Web Applications with ColdFusion
Presents the fundamentals of ColdFusion application development and deployment.
Also includes detailed information about ColdFusion data sources, user interfaces,
and Web technologies.
CFML Language Reference
Provides the complete syntax, with example code, of all CFML tags and functions.
xxii CFML Language Reference
Using ColdFusion Studio
Documents everything you need to know about using ColdFusion Studio, including
features like projects, source control integration, as well as the Studio workspace and
interface.
ColdFusion Quick Reference Guide
A valuable quick reference to CFML tags, functions, and variables.
ColdFusion Server online documentation
To view the HTML documentation, open the following URL: http://127.0.0.1/
cfdocs/dochome.htm
Note that because the Verity search libraries are not available on Linux for this release,
the online documentation search facility is not functional on Linux. If you try to open
the search page, a message box opens to explain why the facility is not available.
Acrobat versions of all ColdFusion documentation are available from the root level on
the product CD. If you don’t have a product CD, you can download ColdFusion
documentation from the Allaire web site by visiting
developer
and clicking the Documentation link.
.
http://www.allaire.com/
ColdFusion Studio online documentation
Click the Help resource tab in ColdFusion Studio to view online Help pages. The help
tree contains ColdFusion documentation and a number of additional developer
resources. Studio online documentation is searchable and individual pages can be
bookmarked.
Printing ColdFusion documentation
If you are working with an evaluation version of ColdFusion and would like printed
documentation, access the Adobe Acrobat files found from the root level on the
product CD. If you do not have access to a product CD, you can download the Acrobat
files from the Allaire web site:
Documentation link.
The Acrobat files offer excellent print output. You can print an entire manual,
individual sections, or page ranges of your choice. To get the Acrobat reader, visit:
http://www.acrobat.com.
http://www.allaire.com/developer, click the
Preface xxiii
Documentation conventions
When reading, please be aware of these formatting cues:
• Code samples, filenames, and URLs are set in a
• Notes and tips are identified by bold type
• Bulleted lists present options and features
• Numbered steps indicate procedures
• Tool button icons are generally shown with procedure steps
• Menu levels are separated by the greater than (>) sign
• Text for you to type in is set in italics
monospaced font
Getting Answers
One of the best ways to solve particular programming problems is to tap into the vast
expertise of the ColdFusion developer community on the Allaire Forums. Other
ColdFusion developers on the forum can help you figure out how to do just about
anything with ColdFusion. The search facility can also help you search messages going
back 12 months, allowing you to learn how others have solved a problem you may be
facing. The Forums is a great resource for learning ColdFusion, but it’s also a great
place to see the ColdFusion developer community in action.
Contacting Allaire
Corporate headquarters
Allaire Corporation
One Alewife Center
Cambridge, MA 02140
Tel: 617.761.2000
Fax: 617.761.2001
http://www.allaire.com
xxiv C FML Language Reference
Technical support
Telephone support is available Monday through Friday 8 A.M. to 8 P.M. Eastern time
(except holidays)
Toll Free: 888.939.2545 (U.S. and Canada)
Tel: 617.761.2100 (outside U.S. and Canada)
For complete details about Allaire Product Support options, please refer to the Allaire
Support pages on the Allaire web site:
Postings to the ColdFusion Support Forum (
made any time.
http://www.allaire.com/support.
http://forums.allaire.com) can be
Sales
Toll Free: 888.939.2545
Tel: 617.761.2100
Fax: 617.761.2101
Email: sales@allaire.com
Web :
http://www.allaire.com/store
C HAPTER 1
Chapter 1 ColdFusion Tags
This chapter describes each of the tags in the ColdFusion Markup Language (CFML).
The introduction contains an alphabetical summary of ColdFusion tags, a list of new
tags in ColdFusion 4.5, and a list of tags by category. The remainder of this chapter
provides complete descriptions of each tag, listed alphabetically.
Contents
• Alphabetical List of ColdFusion Tags................................................................ 2
• New Tags in ColdFusion 4.5...............................................................................5
• ColdFusion Forms Tags ..................................................................................... 6
• Database Manipulation Tags.............................................................................6
• Data Output Tags................................................................................................6
• Exception Handling Tags................................................................................... 6
• Extensibility Tags................................................................................................ 7
• File Management Tags....................................................................................... 7
• Flow-Control Tags .............................................................................................. 7
• Internet Protocol Tags........................................................................................ 7
• Java Servlet and Java Object Tags...................................................................... 8
• Variable Manipulation Tags............................................................................... 8
• Web Application Framework Tags .................................................................... 8
• Other Tags ........................................................................................................... 8
2 CFML Language Reference
Alphabetical List of ColdFusion Tags
The ColdFusion Markup Language (CFML) consists of a set of tags you use in your
ColdFusion pages to interact with data sources, manipulate data, and display output.
Using CFML tags is very simple; tag syntax is much like HTML element syntax.
The following table provides brief descriptions of each CFML tag.
CFML Tag Summary
CFML Tag Description
CFABORT Stops processing of a ColdFusion page at the tag
location.
CFAPPLET Embeds Java applets in a CFFORM.
CFAPPLICATION Defines application name, activates client variables.
CFASSOCIATE Enables sub-tag data to be saved with the base tag.
CFAUTHENTICATE Authenticates a user and sets the security context for an
application.
CFBREAK Breaks out of a CFML looping construct.
CFCACHE Caches ColdFusion pages.
CFCOL Defines table column header, width, alignment, and text.
CFCOLLECTION Creates and administers Verity collections.
CFCONTENT Defines the content type and, optionally, the filename of
a file to be downloaded by the current page.
CFCOOKIE Defines and sets cookie variables.
CFDIRECTORY Performs typical directory-handling tasks from within
your ColdFusion application.
CFERROR Displays customized HTML error pages when errors
occur.
CFEXECUTE Executes any developer-specified process on the server
machine.
CFEXIT Aborts processing of currently executing CFML custom
tag.
CFFILE Performs typical file-handling tasks from within your
ColdFusion application.
Chapter 1: ColdFusion Tags 3
CFML Tag Summary (Continued)
CFML Tag Description
CFFORM Builds an input form and performs client-side input
validation.
CFFTP Permits FTP file operations.
CFGRID Used in CFFORM to create a grid control for tabular data.
CFGRIDCOLUMN Used in CFFORM to define the columns used in a CFGRID.
CFGRIDROW Used with CFGRID to define a grid row.
CFGRIDUPDATE Performs updates directly to ODBC data source from
edited grid data.
CFHEADER Generates HTTP headers.
CFHTMLHEAD Writes text, including HTML, to the HEAD section of a
specified page.
CFHTTP Used to perform GET and POST to upload files or post a
form, cookie, query, or CGI variable directly to a specified
server.
CFHTTPPARAM Used with CFHTTP to specify parameters necessary for a
CFHTTP POST operation.
CFIF/CFELSEIF/CFELSECFIF/CFELSEIF/CFELSE Used to create IF-THEN-ELSE constructs.
CFIMPERSONATE Allows you to impersonate a user defined in a security
context defined in Advanced Security.
CFINCLUDE Embeds references to ColdFusion pages.
CFINDEX Used to create Verity search indexes.
CFINPUT Used in CFFORM to create input elements such as radio
buttons, checkboxes, and text entry boxes.
CFINSERT Inserts records in an ODBC data source.
CFLDAP Provides access to LDAP directory servers.
CFLOCATION Opens a ColdFusion page or HTML file.
CFLOCK Ensures data integrity and synchronizes the execution of
CFML code.
CFLOOP Repeats a set of instructions based on a set of conditions.
CFMAIL Assembles and posts an email message.
4 CFML Language Reference
CFML Tag Summary (Continued)
CFML Tag Description
CFMAILPARAM Attaches a file or adds a header to an email message.
CFMODULE Invokes a custom tag for use in your ColdFusion
application pages.
CFOBJECT Creates and uses COM, CORBA, or JAVA objects.
CFOUTPUT Displays output of database query or other operation.
CFPARAM Defines a parameter and its initial default value.
CFPOP Retrieves messages from a POP mail server.
CFPROCESSINGDIRECTIVE Suppresses extraneous white space, and other
output.
CFPROCPARAM Specifies parameter information for a stored procedure.
CFPROCRESULT Specifies a result set name that other ColdFusion tags use
to access the result set from a stored procedure.
CFQUERY Passes SQL to a database.
CFQUERYPARAM Reads, writes, and deletes keys and values in the system
registry.
CFREGISTRY Reads, writes, and deletes keys and values in the system
registry.
CFREPORT Embeds a Crystal Reports report.
CFRETHROW Rethrows the currently active exception.
CFSCRIPT Encloses a set of CFScript statements.
CFSEARCH Executes searches against data indexed in Verity
collections using CFINDEX.
CFSELECT Used in CFFORM to create a drop-down list box form
element.
CFSERVLET Executes a Java servlet on a JRun engine.
CFSERVLETPARAM Used to pass data to the Java servlet. CFSERVLETPARAM
is a child tag of CFSERVLET.
CFSET Defines a variable.
CFSETTING Define and control a variety ColdFusion settings.
Chapter 1: ColdFusion Tags 5
CFML Tag Summary (Continued)
CFML Tag Description
CFSILENT Suppresses all output that is produced by the CFML
within the tag’s scope.
CFSLIDER Used in CFFORM to create a slider control element.
CFSTOREDPROC Specifies database connection information and identifies
the stored procedure to be executed.
CFSWITCH/CFCASE/CFDEFAULTCASE Evaluates a passed expression and passes control to the
CFCASE tag that matches the expression result.
CFTABLE Builds a table.
CFTEXTINPUT Places a single-line text entry box in a CFFORM.
CFTHROW Raises a developer-specified exception.
CFTRANSACTION Groups CFQUERYs into a single transaction; performs
rollback processing.
CFTREE Used in CFFORM to create a tree control element.
CFTREEITEM Used with CFTREE to populate a tree control element in a
CFFORM.
CFTRY/CFCATCH Allows developers to catch and process exceptions in
ColdFusion pages.
CFUPDATE Updates rows in a database data source.
CFWDDX Serializes and de-serializes CFML data structures to the
XML-based WDDX format.
New Tags in ColdFusion 4.5
CFEXECUTE CFQUERYPARAM
CFHTTPPARAM CFRETHROW
CFIMPERSONATE CFSERVLET
CFMAILPARAM CFSERVLETPARAM
CFPROCESSINGDIRECTIVE CFSILENT
6 CFML Language Reference
ColdFusion Forms Tags
CFAPPLET CFINPUT
CFFORM CFSELECT
CFGRID CFSLIDER
CFGRIDCOLUMN CFTEXTINPUT
CFGRIDROW CFTREE
CFGRIDUPDATE CFTREEITEM
Database Manipulation Tags
CFINSERT CFQUERYPARAM
CFPROCPARAM CFSTOREDPROC
CFPROCRESULT CFTRANSACTION
CFQUERY CFUPDATE
Data Output Tags
CFCOL CFOUTPUT
CFCONTENT CFTABLE
CFHEADER
Exception Handling Tags
CFERROR
CFRETHROW
CFTHROW
CFTRY/CFCATCH
Loading...