Adobe Cold Fusion 11.0 CFML Reference CF11 CFMLRef En

User Manual: adobe ColdFusion - 11.0 - CFML Reference Free User Guide for Adobe ColdFusion Software, Manual

Open the PDF directly: View PDF .
Page Count: 3053

Download
Open PDF In Browser	View PDF

Adobe ColdFusion Documentation
September 2014

1. Adobe ColdFusion CFML Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.1 CFML Reference (ColdFusion 11) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.2 Reserved Words and Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.2.1 Reserved words . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.2.1.1 Reserved words in forms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.2.1.2 Reserved words in queries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.2.2 Scope-specific built-in variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.2.2.1 Variable scope . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.2.2.2 Caller scope . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.2.2.3 CGI variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.2.2.4 Client variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.2.2.5 Server variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.2.2.6 Application and session variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.2.3 Custom tag variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.2.3.1 Request variable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.2.3.2 Form variable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.2.4 ColdFusion tag-specific variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.2.4.1 ColdFusion query variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.2.4.2 CFCATCH variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.2.4.3 CFDIRECTORY variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.2.4.4 CFERROR variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.2.4.5 CFFILE ACTION=Upload variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.2.4.6 CFFTP error variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.2.4.7 CFFTP ReturnValue variable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.2.4.8 CFFTP query object columns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.2.4.9 CFHTTP variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.2.4.10 CFLDAP variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.2.4.11 CFPOP variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.2.4.12 CFQUERY and CFSTOREDPROC variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.2.4.13 CFREGISTRY variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.2.4.14 CFSEARCH variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.2.5 CGI environment (CGI Scope) variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.2.5.1 Testing for CGI variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.2.5.2 CGI server variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.2.5.3 CGI client variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.2.5.4 CGI client certificate variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3 ColdFusion Tags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.1 Tags in ColdFusion 10 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.2 Tag summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.3 Tags by function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.3.1 Application framework tags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.3.2 Communications tags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.3.3 Database manipulation tags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.3.4 Data output tags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.3.5 Debugging tags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.3.6 Display management tags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.3.7 Exception handling tags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.3.8 Extensibility tags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.3.9 File management tags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.3.10 Flow-control tags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.3.11 Forms tags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.3.12 Internet protocol tags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.3.13 Page processing tags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.3.14 Security tags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.3.15 Variable manipulation tags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.3.16 Web Socket tags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.3.17 Other tags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.4 Tag changes since ColdFusion 5 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.4.1 New tags, attributes, and values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.4.2 Deprecated tags, attributes, and values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.4.3 Obsolete tags, attributes, and values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.5 Tags a-b . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.5.1 cfabort . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.5.2 cfajaximport . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.5.3 cfajaxproxy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.5.4 cfapplet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.5.5 cfapplication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.5.6 cfargument . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.5.7 cfassociate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

19
20
22
23
24
25
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
55
56
58
59
60
61
62
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
104
106
107
108
110
115
124
127
135
142

1.3.5.8 cfauthenticate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.5.9 cfbreak . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.6 Tags c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.6.1 cfcache . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.6.2 cfcalendar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.6.3 cfcase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.6.4 cfcatch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.6.5 cfchart . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.6.6 cfchartdata . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.6.7 cfchartseries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.6.8 cfcol . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.6.9 cfcollection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.6.10 cfcomponent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.6.11 cfcontent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.6.12 cfcontinue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.6.13 cfcookie . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.6.14 cfclient . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.6.15 cfclientsettings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.7 Tags d-e . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.7.1 cfdbinfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.7.2 cfdefaultcase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.7.3 cfdirectory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.7.4 cfdiv . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.7.5 cfdocument . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.7.6 cfdocumentitem . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.7.7 cfdocumentsection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.7.8 cfdump . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.7.9 cfelse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.7.10 cfelseif . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.7.11 cferror . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.7.12 cfexchangecalendar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.7.13 cfexchangeconnection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.7.14 cfexchangecontact . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.7.15 cfexchangeconversation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.7.16 cfexchangefilter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.7.17 cfexchangefolder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.7.18 cfexchangemail . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.7.19 cfexchangetask . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.7.20 cfexecute . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.7.21 cfexit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.8 Tags f . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.8.1 cffeed . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.8.2 cffile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.8.3 cffile action = "append" . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.8.4 cffile action = "copy" . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.8.5 cffile action = "delete" . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.8.6 cffile action = "move" . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.8.7 cffile action = "read" . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.8.8 cffile action = "readBinary" . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.8.9 cffile action = "rename" . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.8.10 cffile action = "upload" . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.8.11 cffile action = "uploadAll" . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.8.12 cffile action = "write" . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.8.13 cffileupload . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.8.14 cffinally . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.8.15 cfflush . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.8.16 cfformgroup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.8.17 cfformitem . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.8.18 cfftp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.8.19 cfftp: Opening and closing FTP server connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.8.20 cfftp: Opening and closing secure FTP server connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.8.21 cfftp: Connection: file and directory operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.8.22 cfftp action = "listDir" . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.8.23 cfform . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.8.24 cffunction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.9 Tags g-h . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.9.1 cfgraph . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.9.2 cfgraphdata . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.9.3 cfgrid . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.9.4 cfgridcolumn . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.9.5 cfgridrow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.9.6 cfgridupdate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

144
145
147
148
158
163
166
171
188
190
200
203
209
224
231
233
238
239
247
248
254
256
264
268
283
286
291
295
296
297
303
329
338
349
356
365
376
390
400
404
407
408
427
434
437
439
440
443
446
448
451
460
466
471
478
480
482
494
501
502
506
512
517
518
537
549
550
552
553
575
588
590

1.3.9.7 cfheader . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.9.8 cfhtmlhead . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.9.9 cfhtmltopdf . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.9.10 cfhtmltopdfitem . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.9.11 cfhttp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.9.12 cfhttpparam . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.10 Tags i . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.10.1 cfif . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.10.2 cfimage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.10.3 cfimap . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.10.4 cfimapfilter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.10.5 cfimpersonate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.10.6 cfimport . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.10.7 cfinclude . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.10.8 cfindex . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.10.9 cfinput . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.10.10 cfinsert . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.10.11 cfinterface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.10.12 cfinvoke . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.10.13 cfinvokeargument . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.11 Tags j-l . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.11.1 cflayout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.11.2 cflayoutarea . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.11.3 cfldap . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.11.4 cflocation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.11.5 cflock . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.11.6 cflog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.11.7 cflogin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.11.8 cfloginuser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.11.9 cflogout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.11.10 cfloop . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.11.11 cfloop: index loop . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.11.12 cfloop: conditional loop . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.11.13 cfloop: looping over a date or time range . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.11.14 cfloop: looping over a query . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.11.15 cfloop: looping over a list, a file, or an array . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.11.16 cfloop: looping over a COM collection or structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.12 Tags m-o . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.12.1 cfmail . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.12.2 cfmailparam . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.12.3 cfmailpart . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.12.4 cfmap . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.12.5 cfmapitem . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.12.6 cfmediaplayer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.12.7 cfmenu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.12.8 cfmenuitem . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.12.9 cfmessagebox . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.12.10 cfmodule . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.12.11 cfNTauthenticate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.12.12 cfoauth . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.12.13 cfobject . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.12.14 cfobject: .NET object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.12.15 cfobject: COM object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.12.16 cfobject: component object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.12.17 cfobject: CORBA object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.12.18 cfobject: Java or EJB object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.12.19 cfobject: web service object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.12.20 cfobjectcache . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.12.21 cfoutput . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.13 Tags p-q . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.13.1 cfparam . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.13.2 cfpdf . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.13.3 cfpdfform . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.13.4 cfpdfformparam . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.13.5 cfpdfparam . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.13.6 cfpdfsubform . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.13.7 cfpod . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.13.8 cfpop . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.13.9 cfpresentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.13.10 cfpresentationslide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.13.11 cfpresenter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.13.12 cfprint . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

593
595
596
603
607
627
632
633
636
653
663
674
675
679
682
695
716
721
727
736
738
739
749
765
773
777
785
788
791
793
795
796
799
800
802
804
807
809
810
823
827
830
838
841
848
852
856
862
867
871
876
877
882
885
887
889
891
895
896
901
902
907
956
968
970
973
975
980
987
996
1004
1007

1.3.13.13 cfprocessingdirective . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.13.14 cfprocparam . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.13.15 cfprocresult . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.13.16 cfprogressbar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.13.17 cfproperty . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.13.18 cfquery . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.13.19 cfqueryparam . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.14 Tags r-s . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.14.1 cfregistry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.14.2 cfreport . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.14.3 cfreportparam . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.14.4 cfrethrow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.14.5 cfreturn . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.14.6 cfsavecontent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.14.7 cfschedule . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.14.8 cfscript . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.14.9 cfsearch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.14.10 cfselect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.14.11 cfservlet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.14.12 cfservletparam . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.14.13 cfset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.14.14 cfsetting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.14.15 cfsharepoint . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.14.16 cfsilent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.14.17 cfslider . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.14.18 cfspreadsheet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.14.19 cfsprydataset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.14.20 cfstoredproc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.14.21 cfswitch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.15 Tags t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.15.1 cftable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.15.2 cftextarea . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.15.3 cftextinput . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.15.4 cfthread . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.15.5 cfthrow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.15.6 cftimer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.15.7 cftooltip . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.15.8 cftrace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.15.9 cftransaction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.15.10 cftree . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.15.11 cftreeitem . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.15.12 cftry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.16 Tags u-z . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.16.1 cfupdate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.16.2 cfwddx . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.16.3 cfwebsocket . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.16.4 cfwindow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.16.5 cfxml . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.16.6 cfzip . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.16.7 cfzipparam . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4 ColdFusion Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.1 New Functions in ColdFusion 10 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.2 Functions by category . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.2.1 Array functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.2.2 Cache functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.2.3 Conversion functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.2.4 Date and time functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.2.5 Data output functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.2.6 Debugging functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.2.7 Decision functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.2.8 Display and formatting functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.2.9 Dynamic evaluation functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.2.10 Exception handling functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.2.11 Extensibility functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.2.12 Flow control functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.2.13 Full-text search functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.2.14 Image functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.2.15 International functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.2.16 List functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.2.17 Mathematical functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.2.18 Microsoft office integration functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.2.19 ORM functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

1017
1020
1026
1028
1034
1042
1051
1057
1058
1065
1087
1091
1093
1095
1097
1105
1110
1120
1132
1133
1134
1138
1141
1149
1150
1157
1166
1169
1176
1178
1179
1182
1196
1197
1205
1209
1213
1216
1219
1225
1237
1245
1247
1248
1251
1255
1258
1268
1271
1286
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315

1.4.2.20 Other functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.2.21 Query functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.2.22 Security functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.2.23 Spreadsheet functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.2.24 String functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.2.25 Structure functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.2.26 System functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.2.27 Transaction functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.2.28 XML functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.2.29 Mobile Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.3 Function changes since ColdFusion 5 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.3.1 New functions, parameters, and values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.3.2 Deprecated functions, parameters, and values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.3.3 Obsolete functions, parameters, and values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.4 Functions a-b . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.4.1 Abs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.4.2 ACos . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.4.3 AddSOAPRequestHeader . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.4.4 AddSOAPResponseHeader . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.4.5 AjaxLink . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.4.6 AjaxOnLoad . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.4.7 ApplicationStop . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.4.8 ArrayAppend . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.4.9 ArrayAvg . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.4.10 ArrayClear . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.4.11 ArrayContains . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.4.12 ArrayDelete . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.4.13 ArrayDeleteAt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.4.14 ArrayEach . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.4.15 ArrayFilter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.4.16 ArrayFind . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.4.17 ArrayFindAll . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.4.18 ArrayFindAllNoCase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.4.19 ArrayFindNoCase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.4.20 ArrayInsertAt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.4.21 ArrayIsDefined . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.4.22 ArrayIsEmpty . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.4.23 arrayLen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.4.24 ArrayMap . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.4.25 ArrayMax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.4.26 ArrayMin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.4.27 ArrayNew . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.4.28 ArrayPrepend . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.4.29 ArrayReduce . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.4.30 ArrayResize . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.4.31 ArraySet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.4.32 ArraySlice . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.4.33 ArraySort . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.4.34 ArraySum . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.4.35 ArraySwap . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.4.36 ArrayToList . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.4.37 Asc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.4.38 ASin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.4.39 Atn . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.4.40 AuthenticatedContext . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.4.41 AuthenticatedUser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.4.42 BinaryDecode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.4.43 BinaryEncode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.4.44 BitAnd . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.4.45 BitMaskClear . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.4.46 BitMaskRead . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.4.47 BitMaskSet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.4.48 BitNot . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.4.49 BitOr . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.4.50 BitSHLN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.4.51 BitSHRN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.4.52 BitXor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.4.53 ArrayDeleteNoCase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.5 Functions c-d . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.5.1 CacheIdExists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.5.2 CacheGet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.5.3 CacheGetAllIds . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1335
1336
1337
1339
1340
1342
1344
1346
1347
1349
1351
1353
1356
1357
1359
1360
1362
1364
1365
1366
1367
1369
1371
1373
1375
1377
1379
1380
1381
1382
1383
1385
1387
1388
1390
1391
1394
1396
1397
1399
1401
1403
1405
1406
1407
1409
1411
1412
1413
1414
1415
1416
1417
1418
1419
1420
1421
1423
1425
1426

1.4.5.4 CacheGetMetadata . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.5.5 cacheGetSession . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.5.6 CachePut . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.5.7 CacheRegionExists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.5.8 CacheRegionNew . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.5.9 CacheRegionRemove . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.5.10 CacheRemove . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.5.11 CacheRemoveAll . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.5.12 CacheSetProperties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.5.13 CallStackGet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.5.14 CallStackDump . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.5.15 CacheGetProperties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.5.16 CanDeSerialize . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.5.17 Canonicalize . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.5.18 CanSerialize . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.5.19 Ceiling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.5.20 CharsetDecode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.5.21 CharsetEncode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.5.22 Chr . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.5.23 CJustify . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.5.24 Compare . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.5.25 CompareNoCase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.5.26 Cos . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.5.27 CreateDate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.5.28 CreateDateTime . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.5.29 CreateObject . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.5.30 CreateObject: .NET object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.5.31 CreateObject: COM object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.5.32 CreateObject: component object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.5.33 CreateObject: CORBA object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.5.34 CreateObject: Java or EJB object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.5.35 CreateObject: web service object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.5.36 CreateODBCDate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.5.37 CreateODBCDateTime . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.5.38 CreateODBCTime . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.5.39 CreateTime . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.5.40 CreateTimeSpan . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.5.41 CreateUUID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.5.42 CSRFGenerateToken . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.5.43 CSRFVerifyToken . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.5.44 DateAdd . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.5.45 DateCompare . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.5.46 DateConvert . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.5.47 DateDiff . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.5.48 DateFormat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.5.49 DateTimeFormat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.5.50 DatePart . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.5.51 Day . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.5.52 DayOfWeek . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.5.53 DayOfWeekAsString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.5.54 DayOfYear . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.5.55 DaysInMonth . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.5.56 DaysInYear . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.5.57 DE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.5.58 DecimalFormat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.5.59 DecodeForHTML . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.5.60 DecodeFromURL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.5.61 DecrementValue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.5.62 Decrypt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.5.63 DecryptBinary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.5.64 DeleteClientVariable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.5.65 DeserializeJSON . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.5.66 DirectoryCopy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.5.67 DirectoryCreate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.5.68 DirectoryDelete . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.5.69 DirectoryExists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.5.70 DirectoryList . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.5.71 DirectoryRename . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.5.72 DollarFormat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.5.73 DotNetToCFType . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.5.74 Duplicate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.5.75 Deserialize . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

1427
1429
1432
1434
1435
1437
1438
1440
1441
1443
1445
1447
1450
1451
1455
1456
1457
1460
1463
1465
1467
1469
1471
1473
1475
1477
1478
1481
1483
1485
1487
1488
1491
1493
1496
1498
1500
1503
1504
1505
1506
1510
1514
1517
1521
1524
1527
1529
1531
1533
1535
1537
1539
1541
1544
1545
1546
1547
1548
1553
1557
1559
1562
1563
1565
1567
1569
1573
1575
1576
1578
1580

1.4.5.76 DeserializeXML . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.6 Functions e-g . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.6.1 EncodeForCSS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.6.2 EncodeForHTML . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.6.3 EncodeForHTMLAttribute . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.6.4 EncodeForJavaScript . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.6.5 EncodeForURL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.6.6 EncodeForXML . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.6.7 Encrypt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.6.8 GetTempDirectory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.6.9 GetApplicationMetadata . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.6.10 EncryptBinary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.6.11 EntityDelete . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.6.12 EntityLoad . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.6.13 EntityLoadByExample . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.6.14 EntityLoadByPK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.6.15 EntityMerge . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.6.16 EntityNew . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.6.17 EntityReload . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.6.18 EntitySave . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.6.19 EntityToQuery . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.6.20 Evaluate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.6.21 Exp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.6.22 ExpandPath . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.6.23 FileClose . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.6.24 FileCopy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.6.25 FileDelete . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.6.26 FileExists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.6.27 FileGetMimeType . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.6.28 FileIsEOF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.6.29 FileMove . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.6.30 FileOpen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.6.31 FileRead . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.6.32 FileReadBinary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.6.33 FileReadLine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.6.34 FileSeek . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.6.35 FileSetAccessMode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.6.36 FileSetAttribute . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.6.37 FileSetLastModified . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.6.38 FileSkipBytes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.6.39 FileUpload . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.6.40 FileUploadAll . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.6.41 FileWrite . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.6.42 FileWriteLine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.6.43 Find . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.6.44 FindNoCase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.6.45 FindOneOf . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.6.46 FirstDayOfMonth . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.6.47 Fix . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.6.48 FormatBaseN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.6.49 GenerateSecretKey . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.6.50 GetAuthUser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.6.51 GetBaseTagData . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.6.52 GetBaseTagList . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.6.53 GetBaseTemplatePath . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.6.54 GetClientVariablesList . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.6.55 GetComponentMetaData . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.6.56 GetContextRoot . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.6.57 GetCPUUsage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.6.58 GetCurrentTemplatePath . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.6.59 GetDirectoryFromPath . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.6.60 GetEncoding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.6.61 GetException . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.6.62 GetFileFromPath . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.6.63 GetFileInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.6.64 GetFreeSpace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.6.65 GetFunctionCalledName . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.6.66 GetFunctionList . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.6.67 GetGatewayHelper . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.6.68 GetHttpRequestData . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.6.69 GetHttpTimeString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.6.70 GetK2ServerDocCount . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

1581
1582
1584
1586
1588
1590
1592
1594
1596
1603
1604
1606
1610
1611
1614
1615
1616
1617
1619
1620
1622
1624
1626
1628
1630
1632
1634
1636
1638
1640
1642
1644
1646
1648
1650
1651
1653
1655
1656
1657
1658
1660
1665
1667
1668
1670
1672
1674
1675
1676
1678
1682
1683
1685
1687
1688
1690
1691
1692
1693
1694
1696
1698
1699
1701
1703
1705
1707
1708
1710
1712
1713

1.4.6.71 GetK2ServerDocCountLimit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.6.72 GetLocale . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.6.73 GetLocaleDisplayName . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.6.74 GetLocalHostIP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.6.75 GetMetaData . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.6.76 GetMetricData . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.6.77 GeneratePBKDFKey . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.6.78 GetPageContext . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.6.79 GetPrinterInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.6.80 GetPrinterList . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.6.81 GetProfileSections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.6.82 GetProfileString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.6.83 GetReadableImageFormats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.6.84 GetSOAPRequest . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.6.85 GetSOAPRequestHeader . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.6.86 GetSOAPResponse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.6.87 GetSOAPResponseHeader . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.6.88 GetSystemFreeMemory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.6.89 GetSystemTotalMemory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.6.90 GetTempFile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.6.91 GetTemplatePath . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.6.92 GetTickCount . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.6.93 GetTimeZoneInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.6.94 GetToken . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.6.95 GetTotalSpace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.6.96 GetUserRoles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.6.97 GetVFSMetaData . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.6.98 GetWriteableImageFormats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.6.99 GetSafeHTML . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.6.100 EncodeForXMLAttribute . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.6.101 EncodeForXpath . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.7 Functions h-im . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.7.1 Hash . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.7.2 HMac . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.7.3 HQLMethods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.7.4 Hour . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.7.5 HTMLCodeFormat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.7.6 HTMLEditFormat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.7.7 IIf . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.7.8 ImageAddBorder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.7.9 ImageBlur . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.7.10 ImageClearRect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.7.11 ImageCopy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.7.12 ImageCreateCaptcha . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.7.13 ImageCrop . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.7.14 ImageDrawArc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.7.15 ImageDrawBeveledRect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.7.16 ImageDrawCubicCurve . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.7.17 ImageDrawLine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.7.18 ImageDrawLines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.7.19 ImageDrawOval . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.7.20 ImageDrawPoint . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.7.21 ImageDrawQuadraticCurve . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.7.22 ImageDrawRect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.7.23 ImageDrawRoundRect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.7.24 ImageDrawText . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.7.25 ImageFlip . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.7.26 ImageGetBlob . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.7.27 ImageGetBufferedImage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.7.28 ImageGetEXIFMetadata . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.7.29 ImageGetEXIFTag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.7.30 ImageGetHeight . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.7.31 ImageGetIPTCMetadata . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.7.32 ImageGetIPTCTag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.7.33 ImageGetWidth . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.7.34 ImageGrayscale . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.7.35 ImageInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.7.36 ImageMakeColorTransparent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.7.37 ImageMakeTranslucent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.7.38 ImageNegative . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.7.39 ImageNew . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.7.40 ImageOverlay . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

1714
1715
1717
1719
1720
1725
1728
1730
1732
1734
1735
1737
1739
1740
1742
1745
1747
1749
1750
1751
1752
1753
1754
1756
1760
1762
1763
1765
1766
1768
1770
1772
1774
1778
1780
1783
1784
1786
1788
1791
1794
1796
1798
1800
1802
1804
1806
1808
1810
1812
1814
1816
1818
1820
1822
1825
1828
1831
1833
1835
1837
1839
1840
1842
1843
1844
1846
1848
1849
1851
1853
1857

1.4.7.41 ImagePaste . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.7.42 ImageRead . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.7.43 ImageReadBase64 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.7.44 ImageResize . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.7.45 ImageRotate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.7.46 ImageRotateDrawingAxis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.7.47 ImageScaleToFit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.7.48 ImageSetAntialiasing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.7.49 ImageSetBackgroundColor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.7.50 ImageSetDrawingColor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.7.51 ImageSetDrawingStroke . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.7.52 ImageSetDrawingTransparency . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.7.53 ImageSharpen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.7.54 ImageShear . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.7.55 ImageShearDrawingAxis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.7.56 ImageTranslate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.7.57 ImageTranslateDrawingAxis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.7.58 ImageWrite . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.7.59 ImageWriteBase64 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.7.60 ImageXORDrawingMode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.7.61 ImageGetMetadata . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.8 Functions in-k . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.8.1 IncrementValue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.8.2 InputBaseN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.8.3 Insert . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.8.4 Int . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.8.5 Invoke . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.8.6 IsArray . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.8.7 IsAuthenticated . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.8.8 IsAuthorized . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.8.9 IsBinary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.8.10 IsBoolean . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.8.11 IsClosure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.8.12 IsCustomFunction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.8.13 IsDate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.8.14 IsDDX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.8.15 IsDebugMode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.8.16 IsDefined . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.8.17 IsImage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.8.18 IsImageFile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.8.19 IsInstanceOf . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.8.20 IsIPv6 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.8.21 IsJSON . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.8.22 IsK2ServerABroker . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.8.23 IsK2ServerDocCountExceeded . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.8.24 IsK2ServerOnline . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.8.25 IsLeapYear . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.8.26 IsLocalHost . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.8.27 IsNull . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.8.28 IsNumeric . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.8.29 IsNumericDate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.8.30 IsObject . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.8.31 isOnline . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.8.32 IsPDFFile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.8.33 IsPDFObject . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.8.34 IsProtected . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.8.35 IsQuery . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.8.36 IsSimpleValue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.8.37 IsSOAPRequest . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.8.38 IsSpreadsheetFile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.8.39 IsSpreadsheetObject . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.8.40 IsStruct . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.8.41 IsUserInAnyRole . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.8.42 IsUserInRole . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.8.43 IsUserLoggedIn . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.8.44 IsValid . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.8.45 IsWDDX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.8.46 IsXML . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.8.47 IsXmlAttribute . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.8.48 IsXmlDoc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.8.49 IsXmlElem . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.8.50 IsXmlNode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

1859
1861
1863
1865
1868
1870
1872
1875
1877
1879
1881
1885
1888
1890
1892
1894
1896
1898
1900
1902
1904
1905
1907
1908
1910
1912
1913
1914
1916
1917
1918
1920
1921
1924
1926
1928
1930
1931
1933
1934
1936
1938
1939
1941
1942
1943
1944
1945
1946
1947
1948
1950
1952
1953
1954
1955
1956
1958
1960
1962
1963
1964
1966
1967
1968
1969
1973
1975
1977
1979
1981
1983

1.4.8.51 IsXmlRoot . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.8.52 JavaCast . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.8.53 JSStringFormat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.8.54 isSafeHTML . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.8.55 InvalidateOauthAccesstoken . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.8.56 IsValidOauthAccesstoken . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.8.57 InvokeCFClientFunction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.9 Functions l . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.9.1 LCase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.9.2 Left . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.9.3 Len . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.9.4 ListAppend . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.9.5 ListChangeDelims . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.9.6 ListContains . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.9.7 ListContainsNoCase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.9.8 ListDeleteAt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.9.9 ListFilter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.9.10 ListFind . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.9.11 ListFindNoCase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.9.12 ListFirst . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.9.13 ListGetAt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.9.14 ListInsertAt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.9.15 ListLast . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.9.16 ListLen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.9.17 ListPrepend . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.9.18 ListQualify . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.9.19 ListRemoveDuplicates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.9.20 ListRest . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.9.21 ListSetAt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.9.22 ListSort . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.9.23 ListToArray . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.9.24 ListValueCount . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.9.25 ListValueCountNoCase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.9.26 LJustify . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.9.27 Location . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.9.28 Log . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.9.29 Log10 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.9.30 LSCurrencyFormat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.9.31 LSDateFormat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.9.32 LSDateTimeFormat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.9.33 LSEuroCurrencyFormat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.9.34 LSIsCurrency . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.9.35 LSIsDate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.9.36 LSIsNumeric . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.9.37 LSNumberFormat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.9.38 LSParseCurrency . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.9.39 LSParseDateTime . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.9.40 LSParseEuroCurrency . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.9.41 LSParseNumber . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.9.42 LSTimeFormat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.9.43 LTrim . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.9.44 ListEach . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.9.45 ListReduce . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.9.46 ListMap . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.10 Functions m-r . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.10.1 Max . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.10.2 Mid . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.10.3 Min . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.10.4 Minute . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.10.5 Month . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.10.6 MonthAsString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.10.7 Now . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.10.8 NumberFormat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.10.9 ObjectEquals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.10.10 ObjectLoad . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.10.11 ObjectSave . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.10.12 OnWSAuthenticate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.10.13 ORMClearSession . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.10.14 ORMCloseAllSessions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.10.15 ORMCloseSession . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.10.16 ORMEvictCollection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.10.17 ORMEvictEntity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

1985
1987
1991
1992
1994
1995
1996
1998
1999
2000
2002
2004
2006
2008
2010
2012
2014
2015
2017
2019
2021
2023
2025
2027
2029
2031
2033
2034
2036
2038
2041
2043
2045
2047
2049
2050
2052
2054
2058
2061
2063
2067
2069
2071
2073
2077
2079
2082
2084
2086
2089
2091
2093
2095
2096
2098
2099
2101
2102
2103
2105
2107
2108
2111
2112
2114
2116
2118
2119
2120
2121
2122

1.4.10.18 ORMEvictQueries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.10.19 ORMExecuteQuery . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.10.20 ORMFlush . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.10.21 ORMFlushall . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.10.22 ORMGetSession . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.10.23 ORMGetSessionFactory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.10.24 ORMIndex . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.10.25 ORMIndexPurge . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.10.26 ORMReload . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.10.27 ORMSearch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.10.28 ORMSearchOffline . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.10.29 ParagraphFormat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.10.30 ParameterExists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.10.31 ParseDateTime . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.10.32 Pi . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.10.33 PrecisionEvaluate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.10.34 Quarter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.10.35 PreserveSingleQuotes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.10.36 QueryAddColumn . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.10.37 QueryAddRow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.10.38 QueryNew . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.10.39 QueryConvertForGrid . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.10.40 QuerySetCell . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.10.41 QuotedValueList . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.10.42 Rand . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.10.43 Randomize . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.10.44 RandRange . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.10.45 ReEscape . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.10.46 REFind . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.10.47 REFindNoCase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.10.48 REMatch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.10.49 REMatchNoCase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.10.50 ReleaseComObject . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.10.51 RemoveCachedQuery . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.10.52 RemoveChars . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.10.53 RepeatString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.10.54 Replace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.10.55 ReplaceList . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.10.56 ReplaceNoCase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.10.57 REReplace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.10.58 REReplaceNoCase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.10.59 RestDeleteApplication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.10.60 RestSetResponse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.10.61 RestInitApplication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.10.62 Reverse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.10.63 Right . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.10.64 RJustify . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.10.65 Round . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.10.66 RTrim . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.10.67 QueryGetRow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.10.68 QueryExecute . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.11 Functions s . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.11.1 Second . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.11.2 SendGatewayMessage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.11.3 SerializeJSON . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.11.4 SessionInvalidate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.11.5 SessionRotate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.11.6 SessionGetMetaData . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.11.7 SetEncoding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.11.8 SetLocale . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.11.9 SetProfileString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.11.10 SetVariable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.11.11 Sgn . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.11.12 Sin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.11.13 Sleep . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.11.14 SpanExcluding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.11.15 SpanIncluding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.11.16 SpreadsheetAddColumn . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.11.17 SpreadsheetAddImage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.11.18 SpreadsheetAddFreezePane . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.11.19 SpreadsheetAddInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.11.20 SpreadsheetAddRow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

2123
2124
2126
2127
2128
2129
2130
2131
2132
2133
2136
2138
2140
2141
2144
2145
2147
2148
2150
2153
2155
2158
2160
2162
2164
2166
2168
2170
2171
2175
2179
2180
2181
2183
2184
2186
2187
2189
2191
2193
2195
2197
2198
2199
2200
2202
2204
2206
2207
2209
2210
2213
2215
2216
2218
2225
2227
2229
2230
2232
2235
2238
2240
2241
2243
2245
2247
2249
2251
2253
2255
2257

1.4.11.21 SpreadsheetAddRows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.11.22 SpreadsheetAddSplitPane . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.11.23 SpreadsheetCreateSheet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.11.24 SpreadsheetDeleteColumn . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.11.25 SpreadsheetDeleteColumns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.11.26 SpreadsheetDeleteRow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.11.27 SpreadsheetDeleteRows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.11.28 SpreadsheetFormatCell . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.11.29 SpreadsheetFormatColumn . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.11.30 SpreadsheetFormatCellRange . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.11.31 SpreadsheetFormatColumns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.11.32 SpreadsheetFormatRow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.11.33 SpreadsheetFormatRows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.11.34 SpreadsheetGetCellComment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.11.35 SpreadsheetGetCellFormula . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.11.36 SpreadsheetGetCellValue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.11.37 SpreadsheetInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.11.38 SpreadsheetMergeCells . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.11.39 SpreadsheetNew . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.11.40 SpreadsheetRead . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.11.41 SpreadsheetReadBinary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.11.42 SpreadsheetRemoveSheet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.11.43 SpreadsheetSetActiveSheet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.11.44 SpreadsheetSetActiveSheetNumber . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.11.45 SpreadsheetSetCellComment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.11.46 SpreadsheetSetCellFormula . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.11.47 SpreadsheetSetCellValue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.11.48 SpreadsheetSetColumnWidth . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.11.49 SpreadsheetSetFooter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.11.50 SpreadsheetSetHeader . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.11.51 SpreadsheetSetRowHeight . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.11.52 SpreadsheetShiftColumns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.11.53 SpreadsheetShiftRows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.11.54 SpreadsheetWrite . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.11.55 Sqr . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.11.56 StripCR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.11.57 StructAppend . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.11.58 StructClear . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.11.59 StructCopy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.11.60 StructCount . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.11.61 StructDelete . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.11.62 StructEach . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.11.63 StructFilter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.11.64 StructFind . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.11.65 StructFindKey . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.11.66 StructFindValue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.11.67 StructGet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.11.68 StructInsert . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.11.69 StructIsEmpty . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.11.70 StructKeyArray . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.11.71 StructKeyExists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.11.72 StructKeyList . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.11.73 StructNew . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.11.74 StructSort . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.11.75 StructUpdate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.11.76 SpreadSheetAddPagebreaks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.11.77 SpreadSheetAddAutofilter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.11.78 StructReduce . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.11.79 StructMap . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.11.80 Serialize . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.11.81 SerializeXML . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.12 Functions t-z . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.12.1 Tan . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.12.2 ThreadJoin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.12.3 ThreadTerminate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.12.4 Throw . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.12.5 TimeFormat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.12.6 ToBase64 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.12.7 ToBinary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.12.8 ToScript . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.12.9 ToString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.12.10 Trace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

2259
2261
2263
2265
2267
2269
2271
2273
2279
2281
2283
2285
2287
2289
2291
2293
2295
2297
2299
2301
2302
2303
2304
2306
2308
2312
2314
2316
2318
2320
2322
2324
2326
2328
2331
2332
2334
2336
2338
2343
2345
2347
2348
2349
2351
2353
2355
2357
2359
2361
2364
2366
2369
2371
2373
2375
2377
2379
2381
2382
2383
2384
2385
2387
2389
2390
2392
2395
2397
2399
2404
2407

1.4.12.11 Transactionandconcurrency . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.12.12 TransactionCommit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.12.13 TransactionRollback . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.12.14 TransactionSetSavePoint . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.12.15 Trim . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.12.16 UCase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.12.17 URLDecode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.12.18 URLEncodedFormat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.12.19 URLSessionFormat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.12.20 Val . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.12.21 ValueList . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.12.22 VerifyClient . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.12.23 Week . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.12.24 Wrap . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.12.25 WriteDump . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.12.26 WriteLog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.12.27 WriteOutput . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.12.28 WSGetAllChannels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.12.29 WSGetSubscribers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.12.30 WSPublish . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.12.31 WSSendMessage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.12.32 XmlChildPos . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.12.33 XmlElemNew . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.12.34 XmlFormat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.12.35 XmlGetNodeType . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.12.36 XmlNew . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.12.37 XmlParse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.12.38 XmlSearch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.12.39 XmlTransform . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.12.40 XmlValidate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.12.41 Year . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.12.42 YesNoFormat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.5 Ajax JavaScript Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.5.1 Function summary Ajax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.5.2 ColdFusion.Ajax.submitForm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.5.3 ColdFusion.Autosuggest.getAutosuggestObject . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.5.3.1 ColdFusion.Chart.getChartHandle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.5.3.2 ColdFusion.FileUpload.cancelUpload . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.5.3.3 ColdFusion.FileUpload.clearAllFiles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.5.3.4 Coldfusion.fileUpload.setUrl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.5.3.5 ColdFusion.FileUpload.startUpload . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.5.3.6 ColdFusion.getElementValue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.5.3.7 ColdFusion.grid.clearSelectedRows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.5.3.8 ColdFusion.Grid.getBottomToolbar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.5.3.9 ColdFusion.Grid.getGridObject . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.5.3.10 ColdFusion.grid.getSelectedRows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.5.3.11 ColdFusion.Grid.getTopToolbar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.5.3.12 ColdFusion.Grid.hideBottomToolbar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.5.3.13 ColdFusion.Grid.hideTopToolbar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.5.3.14 ColdFusion.Grid.refresh . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.5.3.15 ColdFusion.Grid.refreshBottomToolbar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.5.3.16 ColdFusion.Grid.refreshTopToolbar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.5.3.17 ColdFusion.Grid.showBottomToolbar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.5.3.18 ColdFusion.Grid.showTopToolbar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.5.3.19 ColdFusion.Grid.sort . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.5.3.20 ColdFusion.JSON.decode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.5.3.21 ColdFusion.JSON.encode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.5.3.22 ColdFusion.Layout.createTab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.5.3.23 ColdFusion.Layout.collapseArea . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.5.3.24 ColdFusion.Layout.collapseAccordion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.5.3.25 ColdFusion.Layout.createAccordionPanel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.5.3.26 ColdFusion.Layout.disableSourceBind . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.5.4 ColdFusion.Layout.enableSourceBind . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.5.4.1 ColdFusion.Layout.expandAccordion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.5.4.2 ColdFusion.Layout.disableTab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.5.4.3 ColdFusion.Layout.enableTab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.5.4.4 ColdFusion.Layout.expandArea . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.5.4.5 ColdFusion.Layout.getAccordionLayout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.5.4.6 ColdFusion.Layout.getBorderLayout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.5.4.7 ColdFusion.Layout.getTabLayout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.5.4.8 ColdFusion.Layout.hideAccordion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.5.4.9 ColdFusion.Layout.hideArea . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

2409
2411
2413
2414
2415
2416
2417
2419
2421
2423
2425
2427
2428
2430
2432
2434
2437
2438
2439
2440
2442
2443
2445
2447
2449
2451
2453
2457
2460
2463
2468
2470
2472
2473
2479
2481
2483
2484
2486
2488
2490
2492
2494
2499
2500
2501
2502
2503
2504
2505
2507
2511
2512
2513
2514
2515
2517
2518
2522
2523
2524
2527
2529
2531
2533
2535
2536
2537
2538
2539
2540
2542

1.5.4.10 ColdFusion.Layout.hideTab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.5.4.11 ColdFusion.Layout.selectAccordion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.5.4.12 ColdFusion.Layout.selectTab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.5.4.13 ColdFusion.Layout.showAccordion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.5.4.14 ColdFusion.Layout.showArea . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.5.4.15 ColdFusion.Layout.showTab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.5.4.16 ColdFusion.Log.debug . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.5.4.17 ColdFusion.Log.dump . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.5.4.18 ColdFusion.Log.error . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.5.4.19 ColdFusion.Log.info . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.5.4.20 ColdFusion.Map.addEvent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.5.4.21 ColdFusion.Map.addMarker . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.5.4.22 ColdFusion.Map.getLatitudeLongitude . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.5.4.23 ColdFusion.Map.getMapObject . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.5.4.24 ColdFusion.Map.hide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.5.4.25 ColdFusion.Map.refresh . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.5.4.26 ColdFusion.Map.setCenter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.5.4.27 ColdFusion.Map.setZoomlevel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.5.4.28 ColdFusion.Map.show . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.5.4.29 ColdFusion.MediaPlayer.getPlayer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.5.4.30 ColdFusion.Mediaplayer.getType . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.5.4.31 ColdFusion.Mediaplayer.logError . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.5.4.32 ColdFusion.Mediaplayer.resize . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.5.4.33 ColdFusion.Mediaplayer.setTitle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.5.4.34 ColdFusion.Mediaplayer.setMute . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.5.4.35 ColdFusion.Mediaplayer.setSource . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.5.4.36 ColdFusion.Mediaplayer.setVolume . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.5.4.37 ColdFusion.Mediaplayer.startPlay . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.5.4.38 ColdFusion.Mediaplayer.stopPlay . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.5.4.39 ColdFusion.MessageBox.create . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.5.4.40 ColdFusion.MessageBox.show . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.5.5 ColdFusion.MessageBox.getMessageBoxObject . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.5.6 ColdFusion.MessageBox.isMessageBoxDefined . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.5.6.1 ColdFusion.MessageBox.update . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.5.6.2 ColdFusion.MessageBox.updateMessage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.5.6.3 ColdFusion.MessageBox.updateTitle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.5.6.4 ColdFusion.navigate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.5.7 ColdFusion.ProgressBar.getProgressBarObject . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.5.7.1 ColdFusion.ProgressBar.hide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.5.7.2 ColdFusion.ProgressBar.reset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.5.7.3 ColdFusion.ProgressBar.show . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.5.7.4 ColdFusion.ProgressBar.start . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.5.7.5 ColdFusion.ProgressBar.stop . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.5.7.6 ColdFusion.ProgressBar.update . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.5.7.7 ColdFusion.ProgressBar.updatestatus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.5.7.8 ColdFusion.RichText.getEditorObject . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.5.7.9 ColdFusion.RichText.onComplete . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.5.7.10 ColdFusion.setGlobalErrorHandler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.5.7.11 ColdFusion.Slider.disable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.5.7.12 ColdFusion.Slider.enable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.5.7.13 ColdFusion.Slider.getSliderObject . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.5.7.14 ColdFusion.Slider.getValue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.5.7.15 ColdFusion.Slider.hide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.5.7.16 ColdFusion.Slider.setValue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.5.7.17 ColdFusion.Slider.show . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.5.7.18 ColdFusion.Tree.getTreeObject . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.5.7.19 ColdFusion.Tree.refresh . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.5.7.20 ColdFusion.Window.create . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.5.7.21 ColdFusion.Window.destroy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.5.7.22 ColdFusion.Window.getWindowObject . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.5.7.23 ColdFusion.Window.hide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.5.7.24 ColdFusion.Window.onHide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.5.7.25 ColdFusion.Window.onShow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.5.7.26 ColdFusion.Window.show . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.5.8 JavaScriptFunctionsinColdFusion9Update1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.6 Script Functions Implemented as CFCs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.6.1 Accessing the functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.6.2 Function summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.6.3 ftp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.6.4 http . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.6.5 mail . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.6.6 pdf . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

2543
2545
2547
2549
2550
2551
2552
2554
2556
2558
2560
2562
2564
2566
2568
2569
2571
2573
2575
2576
2577
2579
2580
2582
2584
2586
2588
2590
2592
2594
2598
2599
2600
2601
2604
2605
2606
2609
2610
2611
2612
2613
2614
2615
2616
2617
2618
2620
2621
2622
2624
2625
2627
2629
2631
2633
2634
2635
2639
2640
2641
2643
2645
2647
2648
2670
2671
2672
2673
2677
2683
2689

1.6.7 query . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.6.8 storedproc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.6.9 Script functions implemented as CFCs in ColdFusion 9 Update 1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.7 ColdFusion Flash Form Style Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.7.1 Styles valid for all controls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.7.2 Styles for cfform . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.7.3 Styles for cfformgroup with horizontal or vertical type attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.7.4 Styles for box-style cfformgroup elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.7.5 Styles for cfformgroup with accordion type attribute . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.7.6 Styles for cfformgroup with tabnavigator type attribute . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.7.7 Styles for cfformitem with hrule or vrule type attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.7.8 Styles for cfinput with radio, checkbox, button, image, or submit type attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.7.9 Styles for cftextarea tag and cfinput with text, password, or hidden type attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.7.10 Styles for cfselect with size attribute value of 1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.7.11 Styles for cfselect with size attribute value greater than 1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.7.12 Styles for cfcalendar tag and cfinput with dateField type attribute . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.7.13 Styles for the cfgrid tag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.7.14 Styles for the cftree tag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.8 Application.CFC Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.8.1 Application variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.8.2 Method summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.8.3 onAbort . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.8.4 onApplicationEnd . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.8.5 onApplicationStart . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.8.6 onCFCRequest . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.8.7 onError . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.8.8 onMissingTemplate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.8.9 onRequest . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.8.10 onRequestEnd . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.8.11 onRequestStart . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.8.12 onServerStart . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.8.13 onSessionEnd . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.8.14 onSessionStart . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.9 ColdFusion Event Gateway Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.9.1 addEvent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.9.2 CFEvent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.9.3 CFEventclass . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.9.4 Constructor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.9.5 Gateway development interfaces and classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.9.6 GatewayHelper interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.9.7 Gateway interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.9.8 GatewayServices class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.9.9 getCFCMethod . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.9.10 getCFCPath . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.9.11 setCFCTimeout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.9.12 getCFCTimeout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.9.13 getData . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.9.14 getGatewayID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.9.15 getGatewayID_1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.9.16 getGatewayServices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.9.17 getGatewayType . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.9.18 getHelper . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.9.19 getLogger . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.9.20 getMaxQueueSize . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.9.21 getOriginatorID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.9.22 setCFCMethod . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.9.23 setCFCPath . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.9.24 getQueueSize . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.9.25 getStatus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.9.26 outgoingMessage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.9.27 restart . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.9.28 setCFCListeners . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.9.29 setData . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.9.30 setGatewayID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.9.31 setGatewayType . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.9.32 setOriginatorID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.9.33 start . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.9.34 stop . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.9.35 Logger class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.9.36 debug . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.9.37 error . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.9.38 fatal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

2694
2700
2705
2721
2722
2726
2727
2728
2731
2732
2733
2734
2736
2737
2738
2739
2740
2741
2742
2743
2753
2754
2756
2758
2760
2762
2764
2766
2768
2770
2772
2773
2775
2776
2778
2780
2782
2783
2785
2786
2787
2788
2789
2790
2791
2793
2794
2796
2797
2798
2799
2800
2801
2803
2804
2806
2808
2810
2811
2812
2814
2815
2817
2819
2820
2822
2824
2826
2828
2829
2831
2833

1.9.39 info . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.9.40 warn . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.9.41 CFML CFEvent structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.9.42 IM gateway methods and commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.9.43 IM Gateway CFC incoming message methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.9.44 onAddBuddyRequest . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.9.45 onAddBuddyResponse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.9.46 onBuddyStatus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.9.47 onIMServerMessage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.9.48 onIncomingMessage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.9.49 IM Gateway GatewayHelper class methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.9.50 IM gateway message sending commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.9.51 addBuddy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.9.52 addDeny . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.9.53 addPermit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.9.54 getBuddyInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.9.55 getBuddyList . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.9.56 getCustomAwayMessage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.9.57 getDenyList . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.9.58 getName . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.9.59 getNickName . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.9.60 getPermitList . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.9.61 getPermitMode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.9.62 getProtocolName . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.9.63 getStatusAsString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.9.64 getStatusTimeStamp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.9.65 numberOfMessagesReceived . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.9.66 numberOfMessagesSent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.9.67 removeBuddy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.9.68 removeDeny . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.9.69 removePermit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.9.70 setNickName . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.9.71 setPermitMode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.9.72 setStatus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.9.73 SMS Gateway CFEvent structure and commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.9.74 SMS Gateway incoming message CFEvent structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.9.75 SMS gateway message sending commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.9.76 submit command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.9.77 submit Multi command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.9.78 data command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.9.79 CFML event gateway SendGatewayMessage data parameter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.10 ColdFusion C++ CFX Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.10.1 C++ class overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.10.2 Deprecated class methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.10.3 CCFXException class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.10.4 CCFXQuery class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.10.5 CCFXRequest class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.10.6 CCFXStringSet class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.11 ColdFusion Java CFX Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.11.1 Class libraries overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.11.2 Custom tag interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.11.3 Query interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.11.4 Request interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.11.5 Response interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.11.6 Debugging classes reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.12 WDDX JavaScript Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.12.1 JavaScript object overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.12.2 WddxRecordset object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.12.3 WddxSerializer object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.13 ColdFusion ActionScript Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.13.1 CF.http . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.13.2 CF.query . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.14 ColdFusion Mobile Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.14.1 Accelerometer Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.14.1.1 cfclient.accelerometer.clearWatch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.14.1.2 cfclient.accelerometer.getOptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.14.1.3 cfclient.accelerometer.setOptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.14.1.4 cfclient.accelerometer.watch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.14.2 Camera Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.14.2.1 cfclient.camera.cleanup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.14.2.2 cfclient.camera.getOptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.14.2.3 cfclient.camera.getPicture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

2834
2836
2838
2839
2840
2841
2844
2846
2849
2851
2853
2854
2855
2857
2858
2859
2862
2863
2864
2865
2866
2867
2868
2869
2870
2871
2872
2873
2874
2875
2876
2877
2878
2879
2881
2882
2884
2885
2887
2889
2891
2893
2894
2895
2896
2898
2903
2915
2919
2920
2921
2923
2929
2935
2939
2940
2941
2942
2950
2955
2956
2964
2967
2968
2969
2970
2971
2972
2974
2975
2976
2977

1.14.2.4 cfclient.camera.getPictureFromAlbum . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.14.2.5 cfclient.camera.getPictureFromPhotoLibrary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.14.2.6 cfclient.camera.setOptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.14.2.7 options Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.14.3 Connection Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.14.3.1 cfclient.connection.getType . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.14.3.2 cfclient.connection.onOffline . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.14.3.3 cfclient.connection.onOnline . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.14.4 Contact Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.14.4.1 Contact Creation Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.14.4.2 Contacts Searching Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.14.5 Event Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.14.5.1 cfclient.events.onBackButton . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.14.5.2 cfclient.events.onBatteryCritical . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.14.5.3 cfclient.events.onBatteryLow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.14.5.4 cfclient.events.onBatteryStatusChange . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.14.5.5 cfclient.events.onMenuButton . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.14.5.6 cfclient.events.onPause . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.14.5.7 cfclient.events.onResume . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.14.5.8 cfclient.events.onSearchButton . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.14.6 File System Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.14.6.1 cfclient.file.append . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.14.6.2 cfclient.file.copy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.14.6.3 cfclient.file.copyDirectory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.14.6.4 cfclient.file.createDirectory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.14.6.5 cfclient.file.directoryExists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.14.6.6 cfclient.file.download . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.14.6.7 cfclient.file.exists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.14.6.8 cfclient.file.get . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.14.6.9 cfclient.file.getDirectory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.14.6.10 cfclient.file.getWorkingDirectory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.14.6.11 cfclient.file.listDirectory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.14.6.12 cfclient.file.move . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.14.6.13 cfclient.file.moveDirectory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.14.6.14 cfclient.file.read . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.14.6.15 cfclient.file.readAsBase64 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.14.6.16 cfclient.file.remove . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.14.6.17 cfclient.file.removeDirectory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.14.6.18 cfclient.file.renameDirectory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.14.6.19 cfclient.file.setFileSystem . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.14.6.20 cfclient.file.setWorkingDirectory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.14.6.21 cfclient.file.upload . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.14.6.22 cfclient.file.write . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.14.6.23 DirectoryEntry Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.14.6.24 FileEntry Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.14.6.25 rename Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.14.7 Geolocation Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.14.7.1 cfclient.geolocation.clearWatch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.14.7.2 cfclient.geolocation.getCurrentPosition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.14.7.3 cfclient.geolocation.getOptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.14.7.4 cfclient.geolocation.setOptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.14.7.5 cfclient.geolocation.watchPosition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.14.8 Media and Capture Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.14.8.1 Audio Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.14.8.2 Video Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.14.9 Notification Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.14.9.1 cfclient.notification.alert . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.14.9.2 cfclient.notification.beep . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.14.9.3 cfclient.notification.confirm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.14.9.4 cfclient.notification.vibrate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.14.10 Splash Screen Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.14.10.1 cfclient.splashscreen.hide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.14.10.2 cfclient.splashscreen.show . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.14.11 Storage Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.14.11.1 cfclient.localstorage.clear . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.14.11.2 cfclient.localstorage.getItem . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.14.11.3 cfclient.localstorage.removeItem . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.14.11.4 cfclient.localstorage.setItem . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

2979
2980
2982
2983
2984
2985
2986
2987
2988
2989
2992
2995
2996
2997
2998
2999
3000
3001
3002
3003
3004
3005
3006
3007
3008
3009
3010
3011
3012
3013
3014
3015
3016
3017
3018
3019
3020
3021
3022
3023
3024
3025
3026
3027
3028
3029
3030
3031
3032
3033
3034
3035
3036
3037
3040
3041
3042
3043
3044
3045
3046
3047
3048
3049
3050
3051
3052
3053

Adobe ColdFusion Documentation

Adobe ColdFusion CFML Reference
The CFML Reference is your primary ColdFusion Markup Language (CFML) reference. Use this manual to learn
about CFML tags and functions, ColdFusion expressions, and using JavaScript objects for WDDX in Adobe
ColdFusion. It also provides detailed references for Java and C++ CFX interfaces.
CFML Reference (ColdFusion 11)
Reserved Words and Variables
ColdFusion Tags
ColdFusion Functions
Ajax JavaScript Functions
Script Functions Implemented as CFCs
ColdFusion Flash Form Style Reference
Application.CFC Reference
ColdFusion Event Gateway Reference
ColdFusion C++ CFX Reference
ColdFusion Java CFX Reference
WDDX JavaScript Objects
ColdFusion ActionScript Functions
ColdFusion Mobile Functions

© 2014 Adobe Systems Incorporated. All rights reserved.

19

Adobe ColdFusion Documentation

CFML Reference (ColdFusion 11)
New functions
The following new functions are added:
GetSafeHTML
isSafeHTML
ImageGetMetadata
GeneratePBKDFKey
SpreadSheetAddPagebreaks
SpreadSheetAddAutofilter
QueryExecute
QueryGetRow
ListMap
ListReduce
ListEach
ArrayMap
ArrayReduce
StructMap
StructReduce
Serialize
CanSerialize
SerializeXML
Deserialize
CanDeSerialize
DeserializeXML
InvalidateOauthAccesstoken
IsValidOauthAccesstoken
EncodeForXpath
EncodeForXMLAttribute
InvokeCFClientFunction

Changes in functions
The following functions are enhanced:
Canonicalize
cflocation
EncodeForCSS
EncodeForHTML
EncodeForHTMLAttribute
EncodeForJavaScript
EncodeForURL
EncodeForXML
SpreadsheetAddColumn
SpreadsheetWrite
SpreadsheetSetCellValue
SpreadsheetAddRows
SpreadsheetAddRow
GetProfileSections
SetProfileString
GetProfileString

© 2014 Adobe Systems Incorporated. All rights reserved.

20

Adobe ColdFusion Documentation

DirectoryList
SerializeJSON
DeserializeJSON
RestInitApplication
CacheRemove

New tags
The following tags have been added:
cfimapfilter
cfoauth
cfclient
cfclientsettings
cfhtmltopdf
cfhtmltopdfitem
cf_socialplugin

Changes in tags
The following tags are enhanced:
cfexchangecalendar
cffile action = "uploadAll"
cfmail
cfzip
cflogout
cflogin
cfspreadsheet
cfldap
cflocation
cfpdf
cfwebsocket

Mobile functions
See ColdFusion Mobile Functions

Other changes
For a list of other changes, see New in ColdFusion.

© 2014 Adobe Systems Incorporated. All rights reserved.

21

Adobe ColdFusion Documentation

Reserved Words and Variables
Adobe ColdFusion language includes reserved words and scope variables.
Reserved words
Scope-specific built-in variables
Custom tag variables
ColdFusion tag-specific variables
CGI environment (CGI Scope) variables

#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

22

Adobe ColdFusion Documentation

Reserved words
The following list indicates words you must not use for ColdFusion variables, user-defined function names, or
custom tag names. Although you can safely use some of these words in some situations, you can prevent errors by
avoiding them entirely.
Any name starting with cf. However, when you call a CFML custom tag directly, you prefix the custom tag
page name with cf_.
Built-in function names, such as Now or Hash
Scope names, such as Form or Session
Operators, such as NE or IS
The names of any built-in data structures, such as Error or File
The names of any built-in variables, such as RecordCount or CGI variable names
The following CFScript language element names:
for
default
continue
import
finally
local (inside function declaration)
interface
pageencoding
Remember that ColdFusion is not case sensitive. For example, all of the following are reserved words:
IS, Is, iS, and is.
Note
Keywords in the newly added statements, such as abort, rethrow, param, and so on
are not reserved.

© 2014 Adobe Systems Incorporated. All rights reserved.

23

Adobe ColdFusion Documentation

Reserved words in forms
Do not create form field names that end in any of the following, except to specify a form field validation rule by using
a hidden form field name.
_integer
_float
_range
_date
_time
_eurodate

© 2014 Adobe Systems Incorporated. All rights reserved.

24

Adobe ColdFusion Documentation

Reserved words in queries
The following table lists SQL keywords that are reserved in ColdFusion queries of queries. This list includes all
reserved words in the SQL standard. Avoid them in variables used in all queries. Do not use these keywords as
variable names in any queries.
Note
Many database management systems have additional reserved words that you cannot use as
variable names in queries to their databases. For a detailed list, see your DBMS documentation.

ABSOLUTE

ACTION

ADD

ALL

ALLOCATE

ALTER

AND

ANY

ARE

AS

ASC

ASSERTION

AT

AUTHORIZATION

AVG

BEGIN

BETWEEN

BIT

BIT_LENGTH

BOTH

BY

CASCADE

CASCADED

CASE

CAST

CATALOG

CHAR

CHARACTER

CHARACTER_LEN
GTH

CHAR_LENGTH

CHECK

CLOSE

COALESCE

COLLATE

COLLATION

COLUMN

COMMIT

CONNECT

CONNECTION

CONSTRAINT

CONSTRAINTS

CONTINUE

CONVERT

CORRESPONDING

COUNT

CREATE

CROSS

CURRENT

CURRENT_DATE

CURRENT_TIME

CURRENT_TIMEST
AMP

CURRENT_USER

CURSOR

DATE

DAY

DEALLOCATE

DEC

DECIMAL

DECLARE

DEFAULT

DEFERRABLE

DEFERRED

DELETE

DESC

DESCRIBE

DESCRIPTOR

DIAGNOSTICS

DISCONNECT

DISTINCT

DOMAIN

DOUBLE

DROP

ELSE

END

END-EXEC

ESCAPE

EXCEPT

EXCEPTION

EXEC

EXECUTE

EXISTS

EXTERNAL

EXTRACT

FALSE

FETCH

FIRST

FLOAT

FOR

FOREIGN

FOUND

© 2014 Adobe Systems Incorporated. All rights reserved.

25

Adobe ColdFusion Documentation

FROM

FULL

GET

GLOBAL

GO

GOTO

GRANT

GROUP

HAVING

HOUR

IDENTITY

IMMEDIATE

IN

INDICATOR

INITIALLY

INNER

INPUT

INSENSITIVE

INSERT

INT

INTEGER

INTERSECT

INTERVAL

INTO

IS

ISOLATION

JOIN

KEY

LANGUAGE

LAST

LEADING

LEFT

LEVEL

LIKE

LOCAL

LOWER

MATCH

MAX

MIN

MINUTE

MODULE

MONTH

NAMES

NATIONAL

NATURAL

NCHAR

NEXT

NO

NOT

NULL

NULLIF

NUMERIC

OCTET_LENGTH

OF

ON

ONLY

OPEN

OPTION

OR

ORDER

OUTER

OUTPUT

OVERLAPS

PAD

PARTIAL

POSITION

PRECISION

PREPARE

PRESERVE

PRIMARY

PRIOR

PRIVILEGES

PROCEDURE

PUBLIC

READ

REAL

REFERENCES

RELATIVE

RESTRICT

REVOKE

RIGHT

ROLLBACK

ROWS

SCHEMA

SCROLL

SECOND

SECTION

SELECT

SESSION

SESSION_USER

SET

SIZE

SMALLINT

SOME

SPACE

SQL

SQLCODE

SQLERROR

SQLSTATE

SUBSTRING

SUM

SYSTEM_USER

TABLE

TEMPORARY

THEN

TIME

TIMESTAMP

TIMEZONE_HOUR

TIMEZONE_MINUT
E

TO

TRAILING

TRANSACTION

TRANSLATE

TRANSLATION

TRIM

© 2014 Adobe Systems Incorporated. All rights reserved.

26

Adobe ColdFusion Documentation

TRUE

UNION

UNIQUE

UNKNOWN

UPDATE

UPPER

USAGE

USER

USING

VALUE

VALUES

VARCHAR

VARYING

VIEW

WHEN

WHENEVER

WHERE

WITH

WORK

WRITE

YEAR

ZONE

#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

27

Adobe ColdFusion Documentation

Scope-specific built-in variables
ColdFusion returns variables, such as those returned in a cfdirectory or cfftp operation. A variable is usually
referenced by scoping it according to its type: naming it according to the code context in which it is available; for
example, Session.varname, or Application.varname. For more information on ColdFusion scopes, see Using
ColdFusion Variables in the Developing ColdFusion Applications
You use the cflock tag to limit the scope of CFML constructs that modify shared data structures, files, and CFXs,
to ensure that modifications occur sequentially. For more information, see cflock, and Using Persistent Data and
Locking in the Developing ColdFusion Applications.

© 2014 Adobe Systems Incorporated. All rights reserved.

28

Adobe ColdFusion Documentation

Variable scope
ColdFusion supports the Variables scope. Unscoped variables created with the cfset tag acquire the Variables
scope by default. For example, the variable created by the statement  can be
referenced as{{#Variables.linguist#}}.

© 2014 Adobe Systems Incorporated. All rights reserved.

29

Adobe ColdFusion Documentation

Caller scope
History

ColdFusion MX: The Caller scope is accessible as a structure. (In earlier releases, it was not.)

© 2014 Adobe Systems Incorporated. All rights reserved.

30

Adobe ColdFusion Documentation

CGI variables
see CGI environment (CGI Scope) variables

© 2014 Adobe Systems Incorporated. All rights reserved.

31

Adobe ColdFusion Documentation

Client variables
The following client variables are reserved:

Client.CFID
Client.CFToken
Client.HitCount
Client.LastVisit
Client.TimeCreated
Client.URLToken

© 2014 Adobe Systems Incorporated. All rights reserved.

32

Adobe ColdFusion Documentation

Server variables
Use the Server prefix to reference server variables, as follows:

Server.ColdFusion.ProductName
Server.ColdFusion.ProductVersion
Server.ColdFusion.ProductLevel
Server.ColdFusion.SerialNumber
Server.ColdFusion.SupportedLocales
Server.ColdFusion.AppServer
Server.ColdFusion.Expiration
Server.ColdFusion.RootDir
Server.ColdFusion.UpdateLevel
Server.OS.Name
Server.OS.AdditionalInformation
Server.OS.Version
Server.OS.BuildNumber

© 2014 Adobe Systems Incorporated. All rights reserved.

33

Adobe ColdFusion Documentation

Application and session variables
To enable application and session variables, use the cfapplication tag or Application.cfc. Reference them as
follows:

Application.myvariable
Session.myvariable

To ensure that modifications to shared data occur in the intended sequence, use the cflock tag. For more
information, see cflock.
ColdFusion provides the following predefined application and session variables:

Application.ApplicationName
Session.CFID
Session.CFToken
Session.URLToken

#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

34

Adobe ColdFusion Documentation

Custom tag variables
A ColdFusion custom tag returns the following variables:

ThisTag.ExecutionMode
ThisTag.HasEndTag
ThisTag.GeneratedContent
ThisTag.AssocAttribs[index]

A custom tag can set a Caller variable to provide information to the caller. Set the Caller variable as follows:



The calling page can access the variable with the cfoutput tag, as follows:

#variable_name#

© 2014 Adobe Systems Incorporated. All rights reserved.

35

Adobe ColdFusion Documentation

Request variable
Request variables store data about the processing of one page request. Request variables store data in a structure
that can be passed to nested tags, such as custom tags, and processed once.
To provide information to nested tags, set a Request variable, as follows:




...

Each nested tag can access the variable with the cfoutput tag, as follows:

#Request.field_name1#

© 2014 Adobe Systems Incorporated. All rights reserved.

36

Adobe ColdFusion Documentation

Form variable
ColdFusion supports the Form variable FieldNames. FieldNames returns the names of the fields on a form. You use
it on the action page associated with a form, as follows:

Form.FieldNames

#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

37

Adobe ColdFusion Documentation

ColdFusion tag-specific variables
Some ColdFusion tags return data as variables. For example, the cffile tag returns file size information in the
FileSize variable, referenced as CFFILE.FileSize.
The following tags return data that you can reference in variables:

cfcatch
cfdirectory
cferror
cffile
cfftp
cfhttp
cfindex
cfldap
cfpop
cfquery
cfregistry
cfsearch
cfstoredproc

© 2014 Adobe Systems Incorporated. All rights reserved.

38

Adobe ColdFusion Documentation

ColdFusion query variables
A ColdFusion tag that returns a query object supports the following variables, where queryname is the value of the n
ame attribute:

queryname.CurrentRow
queryname.RecordCount
queryname.ColumnList

© 2014 Adobe Systems Incorporated. All rights reserved.

39

Adobe ColdFusion Documentation

CFCATCH variables
Within a cfcatch block, the active exception properties can be accessed as the following variables:

CFCATCH.Type
CFCATCH.Message
CFCATCH.Detail
CFCATCH.ErrNumber
CFCATCH.NativeErrorCode
CFCATCH.SQLState
CFCATCH.LockName
CFCATCH.LockOperation
CFCATCH.MissingFileName
CFCATCH.TagContext
CFCATCH.ErrorCode
CFCATCH.ExtendedInfo

Within a cfcatch block, database exception properties can be accessed as the following variables:

CFCATCH.QueryError
CFCATCH.SQL
CFCATCH.Where
CFCATCH.Datasource

Within a cfcatch block, undefined variable exception properties can be accessed as the following variable:

CFCATCH.Name

Within a cfcatch block, syntax and parsing exception properties can be accessed as the following variables:

CFCATCH.TokenText
CFCATCH.Snippet
CFCATCH.Column
CFCATCH.KnownColumn
CFCATCH.Line
CFCATCH.KnownLine

© 2014 Adobe Systems Incorporated. All rights reserved.

40

Adobe ColdFusion Documentation

CFDIRECTORY variables
The cfdirectory tag, with action=list, returns a query object as follows, where queryname is the name attribu
te value:

queryname.Name
queryname.Size
queryname.Type
queryname.DateLastModified
queryname.Attributes
queryname.Mode

© 2014 Adobe Systems Incorporated. All rights reserved.

41

Adobe ColdFusion Documentation

CFERROR variables
When cferror generates an error page, the following error variables are available if type="request" or "excep
tion".

Error.Diagnostics
Error.MailTo
Error.DateTime
Error.Browser
Error.GeneratedContent
Error.RemoteAddress
Error.HTTPReferer
Error.Template
Error.QueryString

The following error variables are available if type="validation".

Error.ValidationHeader
Error.InvalidFields
Error.ValidationFooter

Any cfcatch variable that applies to exception type can be accessed within the Error scope, as follows:

Error.Type
Error.Message
Error.Detail
Error.ErrNumber
Error.NativeErrorCode
Error.SQLState
Error.LockName
Error.LockOperation
Error.MissingFileName
Error.TagContext
Error.ErrorCode
Error.ExtendedInfo

Note
You can substitute the prefix CFERROR for Error, if type = "Exception"; for example, CFER
ROR.Diagnostics, CFERROR.Mailto, or CFERROR.DateTime.

© 2014 Adobe Systems Incorporated. All rights reserved.

42

Adobe ColdFusion Documentation

CFFILE ACTION=Upload variables
File variables are read-only. Use the CFFILE prefix to reference file variables, for example, CFFILE.ClientDirec
tory. The File prefix is deprecated in favor of the CFFILE prefix.

CFFILE.AttemptedServerFile
CFFILE.ClientDirectory
CFFILE.ClientFile
CFFILE.ClientFileExt
CFFILE.ClientFileName
CFFILE.ContentSubType
CFFILE.ContentType
CFFILE.DateLastAccessed
CFFILE.FileExisted
CFFILE.FileSize
CFFILE.FileWasAppended
CFFILE.FileWasOverwritten
CFFILE.FileWasRenamed
CFFILE.FileWasSaved
CFFILE.OldFileSize
CFFILE.ServerDirectory
CFFILE.ServerFile
CFFILE.ServerFileExt
CFFILE.ServerFileName
CFFILE.TimeCreated
CFFILE.TimeLastModified

© 2014 Adobe Systems Incorporated. All rights reserved.

43

Adobe ColdFusion Documentation

CFFTP error variables
When you use the cfftp stoponerror attribute, the following variables are populated:

CFFTP.Succeeded
CFFTP.ErrorCode
CFFTP.ErrorText

© 2014 Adobe Systems Incorporated. All rights reserved.

44

Adobe ColdFusion Documentation

CFFTP ReturnValue variable
Some cfftp file and directory operations provide a return value, in the variable CFFTP.ReturnValue. Its value is
determined by the results of the action attribute. When you specify any of the following actions, cfftp returns a
value:

GetCurrentDir
GetCurrentURL
ExistsDir
ExistsFile
Exists

© 2014 Adobe Systems Incorporated. All rights reserved.

45

Adobe ColdFusion Documentation

CFFTP query object columns
When you use the cfftp tag with the listdir action, cfftp returns a query object, where queryname is the nam
e attribute value, and row__ is the row number of each file or directory entry:

queryname.Name[row]
queryname.Path[row]
queryname.URL[row]
queryname.Length[row]
queryname.LastModified[row]
queryname.Attributes
queryname.IsDirectory
queryname.Mode

© 2014 Adobe Systems Incorporated. All rights reserved.

46

Adobe ColdFusion Documentation

CFHTTP variables
A cfhttp get operation can return text and binary files. Files are downloaded and the contents stored in a
variable or file, depending on the MIME type, as follows:

CFHTTP.FileContent
CFHTTP.MimeType
CFHTTP.Header
CFHTTP.ResponseHeader[http_hd_key]
CFHTTP.StatusCode

© 2014 Adobe Systems Incorporated. All rights reserved.

47

Adobe ColdFusion Documentation

CFLDAP variables
The cfldap action=query tag returns information about the LDAP query, as follows:

queryname.CurrentRow
queryname.RecordCount
queryname.ColumnList

© 2014 Adobe Systems Incorporated. All rights reserved.

48

Adobe ColdFusion Documentation

CFPOP variables
The cfpop tag returns the following result columns, depending on the action attribute value and the use of other
attributes, such as attachmentpath, where queryname is the name attribute value:

queryname.Date
queryname.From
queryname.Body
queryname.Header
queryname.MessageNumber
queryname.ReplyTo
queryname.Subject
queryname.CC
queryname.To
queryname.CurrentRow
queryname.RecordCount
queryname.ColumnList
queryname.Attachments
queryname.AttachmentFiles

© 2014 Adobe Systems Incorporated. All rights reserved.

49

Adobe ColdFusion Documentation

CFQUERY and CFSTOREDPROC variables
The cfquery tag returns information about the query in this variable:

CFQUERY.ExecutionTime

The cfquery tag uses the query name to scope the following data about the query:

queryname.CurrentRow
queryname.RecordCount
queryname.ColumnList

The cfstoredproc tag returns the following variables:

CFSTOREDPROC.ExecutionTime
CFSTOREDPROC.StatusCode

© 2014 Adobe Systems Incorporated. All rights reserved.

50

Adobe ColdFusion Documentation

CFREGISTRY variables
The cfregistry tag returns a query record set that you can reference after executing the GetAll action, as
follows, where queryname is the name attribute value:

queryname.Entry
queryname.Type
queryname.Value

© 2014 Adobe Systems Incorporated. All rights reserved.

51

Adobe ColdFusion Documentation

CFSEARCH variables
A cfsearch operation returns the following variables, where searchname is the name attribute value:

searchname.URL
searchname.Key
searchname.Title
searchname.Score
searchname.Custom1 and Custom2
searchname.Summary
searchname.RecordCount
searchname.CurrentRow
searchname.RecordsSearched
searchname.ColumnList

#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

52

Adobe ColdFusion Documentation

CGI environment (CGI Scope) variables
When a browser makes a request to a server, the web server and the browser create environment variables. In
ColdFusion, these variables are referred to as CGI environment variables. CGI Environment variables contain data
about the transaction between the browser and the server, such as the IP Address, browser type, and authenticated
username. The available CGI variables depend on the browser and server software.
The CGI variables are available to ColdFusion pages in the CGI scope. They take the CGI prefix regardless of
whether the server uses a server API or CGI to communicate with the ColdFusion server. You can reference CGI
environment variables for a given page request anywhere in the page. CGI variables are read-only.
By default, when you use the cfdump tag to display the CGI scope, or when you request debug output of the CGI
scope, ColdFusion attempts to display a fixed list of standard CGI environment variables. Because the available
variables depend on the server, browser, and the types of interactions between the two, not all variables are
normally available. They are represented by empty strings in the debug output. You can request any CGI variable in
your application code, including variables that are not in the list variables displayed by dump and debug output.
ColdFusion checks for the following variables for the cfdump tag and debug output:

© 2014 Adobe Systems Incorporated. All rights reserved.

53

Adobe ColdFusion Documentation

AUTH_PASSWORD
AUTH_TYPE
AUTH_USER
CERT_COOKIE
CERT_FLAGS
CERT_ISSUER
CERT_KEYSIZE
CERT_SECRETKEYSIZE
CERT_SERIALNUMBER
CERT_SERVER_ISSUER
CERT_SERVER_SUBJECT
CERT_SUBJECT
CF_TEMPLATE_PATH
CONTENT_LENGTH
CONTENT_TYPE
CONTEXT_PATH
GATEWAY_INTERFACE
HTTPS
HTTPS_KEYSIZE
HTTPS_SECRETKEYSIZE
HTTPS_SERVER_ISSUER
HTTPS_SERVER_SUBJECT
HTTP_ACCEPT
HTTP_ACCEPT_ENCODING
HTTP_ACCEPT_LANGUAGE
HTTP_CONNECTION
HTTP_COOKIE
HTTP_HOST
HTTP_REFERER
HTTP_USER_AGENT
QUERY_STRING
REMOTE_ADDR
REMOTE_HOST
REMOTE_USER
REQUEST_METHOD
SCRIPT_NAME
SERVER_NAME
SERVER_PORT
SERVER_PORT_SECURE
SERVER_PROTOCOL
SERVER_SOFTWARE
WEB_SERVER_API (This value is always blank; retained for compatibility.)

The following sections describe how to test for CGI environment variables and provide information on some of the
more commonly used CGI environment variables

© 2014 Adobe Systems Incorporated. All rights reserved.

54

Adobe ColdFusion Documentation

Testing for CGI variables
Because some browsers do not support some CGI variables, ColdFusion always returns true when it tests for the
existence of a CGI variable, regardless of whether the browser supports the variable. To determine if the CGI
variable is available, test for an empty string, as the following example shows:


CGI variable exists

CGI variable does not exist


© 2014 Adobe Systems Incorporated. All rights reserved.

55

Adobe ColdFusion Documentation

CGI server variables
The following table describes common CGI environment variables that the server creates (some variables are not
available with some servers):
CGI server variable

Description

SERVER_SOFTWARE

Name and version of the information server software
answering the request (and running the gateway).
Format: name/version.

SERVER_NAME

Server's hostname, DNS alias, or IP address as it
appears in self-referencing URLs.

GATEWAY_INTERFACE

CGI specification revision with which this server
complies. Format: CGI/revision.

SERVER_PROTOCOL

Name and revision of the information protocol this
request came in with. Format: protocol/revision.

SERVER_PORT

Port number to which the request was sent.

REQUEST_METHOD

Method with which the request was made. For HTTP,
this is Get, Head, Post, and so on.

PATH_INFO

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

PATH_TRANSLATED

Translated version of PATH_INFO after any
virtual-to-physical mapping.

SCRIPT_NAME

Virtual path to the script that is executing; used for
self-referencing URLs.

QUERY_STRING

Query information that follows the ? in the URL that
referenced this script.

REMOTE_HOST

Hostname making the request. If the server does not
have this information, it sets REMOTE_ADDR and does
not set REMOTE_HOST.

REMOTE_ADDR

IP address of the remote host making the request.

AUTH_TYPE

If the server supports user authentication, and the
script is protected, the protocol-specific authentication
method used to validate the user.

© 2014 Adobe Systems Incorporated. All rights reserved.

56

Adobe ColdFusion Documentation

REMOTE_USER AUTH_USER

If the server supports user authentication, and the
script is protected, the username the user has
authenticated as. (Also available as AUTH_USER.)

REMOTE_IDENT

If the HTTP server supports RFC 931 identification, this
variable is set to the remote username retrieved from
the server. Use this variable for logging only.

CONTENT_TYPE

For queries that have attached information, such as
HTTP POST and PUT, this is the content type of the
data.

CONTENT_LENGTH

Length of the content as given by the client.

© 2014 Adobe Systems Incorporated. All rights reserved.

57

Adobe ColdFusion Documentation

CGI client variables
The following table describes common CGI environment variables the browser creates and passes in the request
header:
CGI client variable

Description

HTTP_REFERER

The referring document that linked to or submitted form
data.

HTTP_USER_AGENT

The browser that the client is currently using to send
the request. Format: software/version library/version.

HTTP_IF_MODIFIED_SINCE

The last time the page was modified. The browser
determines whether to set this variable, usually in
response to the server having sent the LAST_MODIFIE
D HTTP header. It can be used to take advantage of
browser-side caching.

© 2014 Adobe Systems Incorporated. All rights reserved.

58

Adobe ColdFusion Documentation

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

Description

CERT_SUBJECT

Client-specific information provided by the web server.
This data typically includes the client's name, e-mail
address, and so on, for example:O = "VeriSign,
Inc.", OU = VeriSign Trust Network, OU =
"www.verisign.com/repository/RPA Incorp.
by Ref.,LIAB.LTD(c)98", OU = Persona Not
Validated, OU = Digital ID Class 1 Microsoft, CN = Matthew Lund, E =
mlund@.com

CERT_ISSUER

Information about the authority that provided the client
certificate, for example:O = "VeriSign, Inc.",
OU = VeriSign Trust Network, OU =
"www.verisign.com/repository/RPA Incorp.
By Ref.,LIAB.LTD(c)98", CN = VeriSign
Class 1 CA Individual Subscriber-Persona
Not Validated

© 2014 Adobe Systems Incorporated. All rights reserved.

59

Adobe ColdFusion Documentation

ColdFusion Tags
ColdFusion Markup Language (CFML) includes a set of tags that you use in ColdFusion pages to interact with data
sources, manipulate data, and display output. CFML tag syntax is similar to HTML element syntax.
Tags in ColdFusion 10
Tag summary
Tags by function
Tag changes since ColdFusion 5
Tags a-b
Tags c
Tags d-e
Tags f
Tags g-h
Tags i
Tags j-l
Tags m-o
Tags p-q
Tags r-s
Tags t
Tags u-z

#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

60

Adobe ColdFusion Documentation

Tags in ColdFusion 10
The following table briefly describes CFML tags added in ColdFusion 10:
CFML tag

Category

Description

cfexchangeconversation

Communications tags

Helps users organize and manage
conversations from a Microsoft
Exchange account.

cfexchangefolder

Communications tags

Allows you to perform various
actions on the mail folder, such as
get folder information, find folders,
or create, copy, modify, move,
delete, and empty the contents of a
folder.

cfwebsocket

Web Socket tags

Lets you create the WebSocket
object in your CFM template. The
tag creates a reference to the
WebSocket JavaScript object at the
client-side.

#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

61

Adobe ColdFusion Documentation

Tag summary
The following table briefly describes CFML tags:
CFML tag

Category

Description

cfabort

Flow-control tags

Stops the processing of a
ColdFusion page at the tag location

cfajaximport

Internet protocol tags

Controls importation of JavaScript
files used for ColdFusion
AJAX-based features

cfajaxproxy

Internet protocol tags

Generates an AJAX proxy class on
the client page for a ColdFusion
component

cfapplet

Forms tags

Embeds Java applets in a cfform t
ag

cfapplication

Application framework tags

Defines an application name;
activates client variables; specifies
client variable storage mechanism

cfargument

Extensibility tags

Creates a parameter definition
within a component definition;
defines a function argument

cfassociate

Application framework tags

Enables subtag data to be saved
with a base tag

cfbreak

Flow-control tags

Breaks out of a CFML looping
construct

cfcache

Page processing tags

Caches ColdFusion pages

cfcalendar

Forms tags

Provides a calendar from which to
select a date

cfcase

Flow-control tags

Used with the cfswitch and cfde
faultcase tags

cfcatch

Exception handling tags, Flow-contr
ol tags

Catches exceptions in ColdFusion
pages

cfchart

Data output tags

Generates and displays a chart

cfchartdata

Data output tags

Defines chart data points

© 2014 Adobe Systems Incorporated. All rights reserved.

62

Adobe ColdFusion Documentation

cfchartseries

Data output tags

Defines style in which chart data
displays

cfclient

The  tag is a marker tag
that instructs ColdFusion to
generate client-side code
(JavaScript) for ColdFusion code.

cfclientsettings

This tag is similar to
cfprocessingdirective and acts as a
compiler directive to include plugins
for various features (device
detection and device API).

cfcol

Data output tags

Defines table column header,
properties

cfcollection

Extensibility tags

Administers Solr collections

cfcomponent

Extensibility tags

Creates and defines a component
object

cfcontent

Data output tags, Page processing
tags

Defines content type and filename
of a file to be downloaded by the
current page

cfcontinue

Flow-control tags

Returns processing to the top of a
loop; used within a cfloop tag.

cfcookie

Variable manipulation tags

Defines and sets cookie variables,
including expiration and security
options

cfdbinfo

Database manipulation tags

Lets you retrieve information about
a data source

cfdefaultcase

Flow-control tags

Receives control if there is no
matching cfcase tag value

cfdirectory

File management tags

Performs typical directory-handling
tasks from within a ColdFusion
application

cfdiv

Display management tags

Creates an HTML tag with that is
populated using a bind expressions.

cfdocument

Data output tags

Creates PDF or Adobe FlashPaper
output from a text block that
contains CFML and HTML

© 2014 Adobe Systems Incorporated. All rights reserved.

63

Adobe ColdFusion Documentation

cfdocumentitem

Data output tags

Specifies action items, such as
header, footer, and page break, for
a PDF or FlashPaper document

cfdocumentsection

Data output tags

Divides a PDF or FlashPaper
document into sections

cfdump

Debugging tags, Variable
manipulation tags

Outputs variables for debugging

cfelse

Flow-control tags

Creates IF-THEN-ELSE constructs

cfelseif

Flow-control tags

Creates IF-THEN-ELSE constructs

cferror

Exception handling tags, Applicatio
n framework tags

Displays custom HTML error pages
when errors occur

cfexchangecalendar

Communications tags

Gets, creates, deletes, modifies, or
responds to Microsoft Exchange
calendar events

cfexchangeconnection

Communications tags

Opens or closes a persistent
connection with an Exchange
server

cfexchangecontact

Communications tags

Gets, creates, deletes, or modifies
Exchange contacts

cfexchangeconversation

Communications tags

Helps users organize and manage
conversations from a Microsoft
Exchange account.

cfexchangefolder

Communications tags

Allows you to perform various
actions on the mail folder, such as
get folder information, find folders,
or create, copy, modify, move,
delete, and empty the contents of a
folder.

cfexchangefilter

Communications tags

Sets filter conditions used in
Exchange tag get operations

cfexchangemail

Communications tags

Gets and deletes Exchange mail
messages and sets message
properties

cfexchangetask

Communications tags

Gets, creates, deletes, or modifies
an Exchange user task

© 2014 Adobe Systems Incorporated. All rights reserved.

64

Adobe ColdFusion Documentation

cfexecute

Flow-control tags, Extensibility tags

Executes developer-specified
process on server computer

cfexit

Flow-control tags

Aborts processing of executing
CFML tag

cffeed

Communications tags, Internet
protocol tags

Reads, creates, and converts, Atom
and RSS syndication feeds

cffile

File management tags

Performs typical file-handling tasks
from within ColdFusion application

cffileupload

File management tags Forms tags

Displays a dialog for uploading
multiple files from the user's
system.

cffinally

Exception handling tags

Used inside a cftry tag

cfflush

Data output tags, Page processing
tags

Flushes currently available data to
client

cfform

Forms tags

Builds input form; performs
client-side input validation

cfformgroup

Forms tags

Groups form control into a
containing object

cfformitem

Forms tags

Adds text and dividing rules to
Adobe Flash forms

cfftp

Forms tags, Extensibility tags, Inter
net protocol tags

Permits FTP file operations

cffunction

Extensibility tags

Defines function that you build in
CFML

cfgrid

Forms tags

Displays tabular grid control, in cff
orm tag

cfgridcolumn

Forms tags

Used in cfform; defines columns
in a cfgrid

cfgridrow

Forms tags

Defines a grid row; used with cfgr
id

cfgridupdate

Forms tags

Directly updates ODBC data source
from edited grid data

© 2014 Adobe Systems Incorporated. All rights reserved.

65

Adobe ColdFusion Documentation

cfheader

Data output tags, Page processing
tags

Generates HTTP headers

cfhtmlhead

Page processing tags

Writes text and HTML to HEAD
section of page

cfhtmltopdfcfhtmltopdf

Data output tags

 creates high quality
PDF output from a text block
containing CFML and HTML using
the PDF Service Manager.

cfhtmltopdfitem

Data output tags

The  specifies the
action items for a PDF document
created by the tag
.

cfhttp

Internet protocol tags

Performs GET and POST to upload
file or post form, cookie, query, or
CGI variable directly to server

cfhttpparam

Internet protocol tags

Specifies parameters required for a
cfhttp POST operation; used with
cfhttp

cfif

Flow-control tags

Creates IF-THEN-ELSE constructs

cfimage

Other tags

Creates a cfimage, a ColdFusion
data type that can be operated by
image functions.

cfimap

Communications tags, Internet
protocol tags

Retrieves and manages e-mails and
folders in IMAP servers

cfimapfilter

Communication tags

Specifies filter parameters that
control the actions of cfimap, get
operations.

cfimport

Application framework tags

Imports JSP tag libraries into a
CFML page

cfinclude

Flow-control tags

Embeds references to ColdFusion
pages

cfindex

Extensibility tags

Creates Solr search indexes

cfinput

Forms tags

Creates an input element (radio
button, check box, text entry box);
used in cfform

cfinsert

Database manipulation tags

Inserts records in a data source

© 2014 Adobe Systems Incorporated. All rights reserved.

66

Adobe ColdFusion Documentation

cfinterface

Application framework tags, Extensi
bility tags

Defines an interface that a
ColdFusion component can
implement

cfinvoke

Extensibility tags

Invokes component methods from a
ColdFusion page or component

cfinvokeargument

Extensibility tags

Passes a parameter to a
component method or a web
service

cflayout

Display management tags

Creates a region of its container
with a specific layout behavior

cflayoutarea

Display management tags

Defines a display region within a cf
layout tag body

cfldap

Internet protocol tags

Provides access to LDAP directory
servers

cflocation

Flow-control tags

Controls execution of a page

cflock

Application framework tags

Ensures data integrity and
synchronizes execution of CFML
code

cflog

Data output tags, Other tags

Writes a message to a log file

cflogin

Security tags

Defines a container for user login
and authentication code

cfloginuser

Security tags

Identifies an authenticated user to
ColdFusion

cflogout

Security tags

Logs the current user out

cfloop

Flow-control tags

Repeats a set of instructions based
on conditions

cfmail

Communications tags, Internet
protocol tags

Assembles and posts an e-mail
message

cfmailparam

Communications tags, Internet
protocol tags

Attaches a file or adds a header to
an e-mail message

cfmailpart

Communications tags, Internet
protocol tags

Contains one part of a multipart
mail message

© 2014 Adobe Systems Incorporated. All rights reserved.

67

Adobe ColdFusion Documentation

cfmap

Other tags

Embeds a Google map within a
ColdFusion web page

cfmapitem

Other tags

Creates markers on the map; a
child tag of the cfmap tag

cfmediaplayer

Other tags

Creates an in-built media player
that can play FLV files

cfmenu

Display management tags

Creates a top-level menu or a tool
bar.

cfmenuitem

Display management tags

Defines an entry in a menu,
including an item that is the head of
a submenu.

cfmessagebox

Application framework tags

Defines a control for displaying
pop-up messages

cfNTauthenticate

Security tags

Authenticates user information
against an NT domain

cfoauth

Communications tags, Internet
protocol tags

The  tag allows you to
easily integrate third-party Oauth 2
authentication provider

cfobject

Extensibility tags

Creates COM, component, CORBA,
Java, and web service objects

cfobjectcache

Database manipulation tags

Flushes the query cache

cfoutput

Data output tags

Displays the output of a database
query or other operation

cfparam

Variable manipulation tags

Defines a parameter and its default
value

cfpdf

Forms tags

Manipulates existing PDF
documents.

cfpdfform

Forms tags

Creates and manipulates PDF
forms.

cfpdfformparam

Forms tags

Creates interactive fields on a PDF
form.

© 2014 Adobe Systems Incorporated. All rights reserved.

68

Adobe ColdFusion Documentation

cfpdfparam

Forms tags

Child tag of the cfpdf tag. Used
only with the merge action to merge
multiple pages or PDF documents
into one file

cfpdfsubform

Forms tags

Creates subforms within a PDF
form.

cfpod

Display management tags

Creates a an area of the browser or
layout area with an optional title bar
and a body

cfpop

Communications tags, Internet
protocol tags

Gets and deletes messages from
POP mail server

cfpresentation

Data output tags

Creates a presentation dynamically
from an HTML page or SWF files

cfpresentationslide

Data output tags

Creates a slide dynamically from an
HTML page or SWF source files
(child tag of the cfpresentation
tag)

cfpresenter

Data output tags

Describes a presenter in a slide
presentation

cfprint

Data output tags

Prints PDF documents. Used for
automated print jobs

cfprocessingdirective

Data output tags

Suppresses white space and other
output

cfprocparam

Database manipulation tags

Holds parameter information for
stored procedure

cfprocresult

Database manipulation tags

Result set name that ColdFusion
tags use to access result set of a
stored procedure

cfprogressbar

Other tags

Defines a progress bar to indicate
the progress of an activity

cfproperty

Extensibility tags

Defines components

cfquery

Database manipulation tags

Passes SQL statements to a
database

cfqueryparam

Database manipulation tags

Checks data type of a query
parameter

© 2014 Adobe Systems Incorporated. All rights reserved.

69

Adobe ColdFusion Documentation

cfregistry

Other tags, Variable manipulation
tags

Reads, writes, and deletes keys
and values in a Windows system
registry

cfreport

Exception handling tags

Embeds a ColdFusion Report
Builder or Crystal Reports report

cfreportparam

Exception handling tags

Passes an input parameter to a
ColdFusion Report Builder report

cfrethrow

Exception handling tags

Rethrows currently active exception

cfreturn

Extensibility tags

Returns results from a component
method

cfsavecontent

Variable manipulation tags

Saves generated content inside tag
body in a variable

cfschedule

Variable manipulation tags

Schedules page execution;
optionally, produces static pages

cfscript

Application framework tags

Encloses a set of cfscript statem
ents

cfsearch

Extensibility tags

Executes searches against data
indexed in Solr collections, using cf
index

cfselect

Forms tags

Creates a drop-down list box form
element; used in cfform tag

cfset

Variable manipulation tags

Defines a variable

cfsetting

Other tags, Variable manipulation
tags

Defines and controls ColdFusion
settings

cfsharepoint

Extensibility tags

Invokes a SharePoint action from
ColdFusion

cfsilent

Data output tags, Page processing
tags

Suppresses CFML output within tag
scope

cfslider

Forms tags

Creates slider control; used in cffo
rm

cfspreadsheet

Extensibility tags

Manages Excel spreadsheet files

cfsprydataset

Internet protocol tags

Creates a spry data set

© 2014 Adobe Systems Incorporated. All rights reserved.

70

Adobe ColdFusion Documentation

cfstoredproc

Database manipulation tags

Holds database connection
information; identifies a stored
procedure to execute

cfswitch

Flow-control tags

Evaluates passed expression;
passes control to matching cfcase
tag

cftable

Data output tags

Builds a table in a ColdFusion page

cftextarea

Forms tags

Puts a multiline text box in a form

cfthread

Application framework tags

Creates and manages ColdFusion
threads, independent streams of
execution.

cfthrow

Exception handling tags, Flow-contr
ol tags

Throws a developer-specified
exception

cftimer

Debugging tags

Displays execution time for a block
of code

cftooltip

Display management tags

Specifies text to display when the
mouse pointer hovers over the tag
body elements

cftrace

Debugging tags

Displays and logs application
debugging data

cftransaction

Database manipulation tags

Groups cfquery operations into
one transaction; performs rollback
processing

cftree

Forms tags

Creates tree control element; used
in cfform

cftreeitem

Forms tags

Populates a tree control element in
a form; used with cftree

cftry

Exception handling tags, Flow-contr
ol tags

Catches exceptions in ColdFusion
pages

cfupdate

Database manipulation tags

Updates rows in a database data
source

© 2014 Adobe Systems Incorporated. All rights reserved.

71

Adobe ColdFusion Documentation

cfwebsocket

Web Socket tags

Lets you create the WebSocket
object in your CFM template. The
tag creates a reference to the
WebSocket JavaScript object at the
client-side.

cfwddx

Extensibility tags

Serializes and deserializes CFML
data structures to XML-based
WDDX format

cfwindow

Display management tags

Creates a pop-up window in the
browser

cfxml

Extensibility tags

Creates an XML document object

cfzip

File management tags

Manipulates ZIP and JAR files

cfzipparam

File management tags

Manipulates ZIP and JAR files

#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

72

Adobe ColdFusion Documentation

Tags by function
This section lists tags by their function or purpose.

© 2014 Adobe Systems Incorporated. All rights reserved.

73

Adobe ColdFusion Documentation

Application framework tags
cfapplication
cfassociate
cferror

cfimport
cfinterface
cflock

© 2014 Adobe Systems Incorporated. All rights reserved.

cfscript
cfthread

74

Adobe ColdFusion Documentation

Communications tags
cfexchangecalendar
cfexchangeconnectio
n
cfexchangecontact

cfexchangefilter
cfexchangemail
cfexchangetask

© 2014 Adobe Systems Incorporated. All rights reserved.

cffeed
cfmail
cfmailparam

cfmailpart
cfpopcfimap

75

Adobe ColdFusion Documentation

Database manipulation tags
cfdbinfo
cfinsert
cfobjectcache

cfprocparam
cfprocresult
cfquery

© 2014 Adobe Systems Incorporated. All rights reserved.

cfqueryparam
cfstoredproc
cftransaction

cfupdate

76

Adobe ColdFusion Documentation

Data output tags
cfchart
cfchartdata
cfchartseries
cfcol
cfcontent
cfdocument

cfdocumentitem
cfdocumentsection
cfflush
cfheader
cflog
cfoutput

© 2014 Adobe Systems Incorporated. All rights reserved.

cfpresentation
cfpresentationslide
cfpresenter
cfprocessingdirecti
ve
cfprint
cfreport

cfreportparam
cfsilent
cftable

77

Adobe ColdFusion Documentation

Debugging tags
cfdump

cftimer

© 2014 Adobe Systems Incorporated. All rights reserved.

cftrace

78

Adobe ColdFusion Documentation

Display management tags
cfdiv
cflayout
cflayoutarea
cfmap

cfmapitem
cfmediaplayer
cfmenu

© 2014 Adobe Systems Incorporated. All rights reserved.

cfmenuitem
cfmessagebox
cfpod

cfprogressbar
cftooltip
cfwindow

79

Adobe ColdFusion Documentation

Exception handling tags
cfcatch
cferror

cffinally
cfrethrow

© 2014 Adobe Systems Incorporated. All rights reserved.

cfthrow
cftry

80

Adobe ColdFusion Documentation

Extensibility tags
cfchart
cfchartdata
cfchartseries
cfcollection
cfcomponent
cfexecute

cfftp
cffunction
cfindex
cfinterface
cfinvoke
cfinvokeargument

© 2014 Adobe Systems Incorporated. All rights reserved.

cfobject
cfproperty
cfreport
cfreportparam
cfreturn
cfsearch

cfsharepoint
cfspreadsheet
cfwddx
cfxml

81

Adobe ColdFusion Documentation

File management tags
cfdirectory
cffile

cffileupload
cfftp

© 2014 Adobe Systems Incorporated. All rights reserved.

cfzip
cfzipparam

82

Adobe ColdFusion Documentation

Flow-control tags
cfabort
cfbreak
cfcase
cfcontinue
cfdefaultcase

cfelse
cfelseif
cfexecute
cfexit
cfif

© 2014 Adobe Systems Incorporated. All rights reserved.

cfinclude
cflocation
cfloop
cfrethrow
cfswitch

cfthrow
cftry

83

Adobe ColdFusion Documentation

Forms tags
cfapplet
cfcalendar
cffileupload
cfform
cfformgroup
cfformitem

cfgrid
cfgridcolumn
cfgridrow
cfgridupdate
cfinput
cfpdf

© 2014 Adobe Systems Incorporated. All rights reserved.

cfpdfform
cfpdfformparam
cfpdfparam
cfpdfsubform
cfselect
cfslider

cftextarea
cftree
cftreeitem

84

Adobe ColdFusion Documentation

Internet protocol tags
cfajaximport
cfajaxproxy
cfftp
cffeed

cfimap
cfhttp
cfhttpparam
cfldap

© 2014 Adobe Systems Incorporated. All rights reserved.

cfmail
cfmailparam
cfmailpart
cfpop

cfsprydataset

85

Adobe ColdFusion Documentation

Page processing tags
cfcache
cfcontent
cfflush

cfheader
cfhtmlhead
cfinclude

© 2014 Adobe Systems Incorporated. All rights reserved.

cfprocessingdirective
cfsetting
cfsilent

86

Adobe ColdFusion Documentation

Security tags
cflogin

cfloginuser

© 2014 Adobe Systems Incorporated. All rights reserved.

cflogout

cfNTauthenticate

87

Adobe ColdFusion Documentation

Variable manipulation tags
cfcookie
cfdump

cfparam
cfregistry

© 2014 Adobe Systems Incorporated. All rights reserved.

cfsavecontent
cfschedule

cfset
cfsetting

88

Adobe ColdFusion Documentation

Web Socket tags
cfwebsocket

© 2014 Adobe Systems Incorporated. All rights reserved.

89

Adobe ColdFusion Documentation

Other tags
cfimage

cflog

cfregistry

#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

90

Adobe ColdFusion Documentation

Tag changes since ColdFusion 5
The following section lists tags, attributes, and values that have changed since ColdFusion 5, and indicate the
specific release in which the change was made.

© 2014 Adobe Systems Incorporated. All rights reserved.

91

Adobe ColdFusion Documentation

New tags, attributes, and values
New and changed tags are also documented elsewhere, for the following releases:
New Tags in ColdFusion 9 (in the ColdFusion 9 version of this manual)
Tags in ColdFusion 10
New in ColdFusion 11
This table lists tags, attributes, and attribute values that have been added since the ColdFusion MX release:
Tag

Attribute or value

Added in this ColdFusion release

Multiple tags

attributeCollection

ColdFusion 8

cfajaximport

All

ColdFusion 8

cfajaxproxy

All

ColdFusion 8

cfapplication

scriptProtect

ColdFusion MX 7

loginStorage

ColdFusion MX 6.1

component value of type attribute

ColdFusion 8

xml value of type attribute

ColdFusion MX 7

All

ColdFusion MX

cfcache

cachedirectory, timespan attri
butes

ColdFusion MX

cfcalendar

onBlur and onFocus attributes

ColdFusion MX 7.01

All

ColdFusion MX 7

style , title attributes

ColdFusion MX 7

xAxisType, yAxisType attributes

ColdFusion MX 6.1

All

ColdFusion MX

cfchartdata

All

ColdFusion MX

cfchartseries

datalabelstyle attribute

ColdFusion MX 7

cfargument

cfchart

horizontalbar value of type attr
ibute
All

© 2014 Adobe Systems Incorporated. All rights reserved.

ColdFusion MX

92

Adobe ColdFusion Documentation

cfcollection

categories attribute

ColdFusion MX 7

New values of the language attrib
ute
list and categoryList values
of action attribute

cfcomponent

name attribute

ColdFusion MX

implements, serviceaddress a
ttributes

ColdFusion 8

component value of extends attri
bute
style, namespace, servicepor
tname, porttypename, wsdlfil
e, bindingname, and output attri
butes

ColdFusion MX 7

Extended functionality for the hint
and displayname attributes when
publishing document-literal style
web services
All

ColdFusion MX

cfcontent

variable attribute

ColdFusion MX 7

cfcontinue

All

ColdFusion 9

cfdbinfo

All

ColdFusion 8

cfdirectory

listinfo and type attributes

ColdFusion 8

recurse attribute for list and de
lete actions

ColdFusion MX 7

All

ColdFusion 8

cfdiv

© 2014 Adobe Systems Incorporated. All rights reserved.

93

Adobe ColdFusion Documentation

bookmark, authPassword, auth
User, localUrl, proxyHost, pr
oxyPassword, proxyPort, prox
yUser, saveAsName and userAge
nt attributes
totalsectionpagecount and cu
rrentsectionpagenumber scop
e variables

ColdFusion 8

src, srcfile, and mimetype attri
butes

ColdFusion MX 7.01

All

ColdFusion MX 7

cfdocumentitem

All

ColdFusion MX 7

cfdocumentsection

name, authPassword, authUser,
and userAgent attributes

ColdFusion 8

All

ColdFusion MX 7

cfdump

show, format, hide, keys, meta
info, output, and showUDFs attri
butes

ColdFusion 8

cfexchangecalendar

All

ColdFusion 8

cfexchangeconnection

All

ColdFusion 8

cfexchangecontact

All

ColdFusion 8

cfexchangefilter

All

ColdFusion 8

cfexchangemail

All

ColdFusion 8

cfexchangetask

All

ColdFusion 8

cfexecute

variable attribute

ColdFusion MX 6.1

cffeed

All

ColdFusion 8

cffile

result attribute for action="upl
oad" action

ColdFusion MX 7

cfdocument

fixnewline attribute for action=
"append" and action="write"
actions

© 2014 Adobe Systems Incorporated. All rights reserved.

94

Adobe ColdFusion Documentation

cffileupload

All

ColdFusion 9

cffinally

All

ColdFusion 9

cfform

onSuccess attribute support in
AJAX controls for the onError attri
bute

ColdFusion 8

name and action attributes are
optional

ColdFusion MX 7

accessible, format, height, w
idth , method, onError, onRese
t, preloader, scriptsrc, skin,
style, timeout, wMode attributes
cfformgroup

All

ColdFusion MX 7

cfformitem

script value of type attribute

ColdFusion MX 7.01

All

ColdFusion MX 7

fingerprint, key, paraphrase,
and secure attributes
quote, site, allo, and acct valu
es to the action attribute

ColdFusion 8

result attribute

ColdFusion MX 7

description attribute; the XML va
lue to the returntype attribute

ColdFusion MX 7

All

ColdFusion MX

bind, bindOnLoad, pageSize, p
reservePageOnSort, stripeRo
ws, stripeRowColor attributes,
and HTML value of format attribute
.

ColdFusion 8

onBlur and onFocus attributes

ColdFusion MX 7.01

format attribute and support for
Flash and XML output
enabled, onChange, style, too
ltip, visible attributes (Flash
format only)

ColdFusion MX 7

cfftp

cffunction

cfgrid

© 2014 Adobe Systems Incorporated. All rights reserved.

95

Adobe ColdFusion Documentation

cfgridcolumn

cfhttp

mask attribute

ColdFusion MX 7

currency value of type attribute

ColdFusion MX 7

clientCert and clientCertPa
ssword attributes

ColdFusion 8

never value of GetAsBinary attri
bute

ColdFusion MX 7.01

result attribute

ColdFusion MX 7

HEAD, PUT, DELETE, OPTIONS, and
TRACE values of method attribute

ColdFusion MX 6.1

multipart, getasbinary, prox
yUser, proxyPassword attributes

cfhttpparam

charset,firstrowasheaders at
tributes

ColdFusion MX

header and body values of type a
ttribute

ColdFusion MX 6.1

encoded, mimeType attributes
cfimage

All

ColdFusion 8

cfimport

All

ColdFusion MX

cfimap

All

ColdFusion 9

cfindex

prefix attribute

ColdFusion MX 7.01

custom3, custom4, category,
and categorytree attributes for u
pdate and refresh actions

ColdFusion MX 7

status attribute for update, refr
esh, delete, and purge actions
New values of the language attrib
ute

© 2014 Adobe Systems Incorporated. All rights reserved.

96

Adobe ColdFusion Documentation

cfinput

autosuggest, autosuggestBin
dDelay, autosuggestMinLengt
h, delimiter, maxResultsDisp
layed, showAutosuggestLoadi
ngIcon, sourceForTooltip, and
typeahead attributes.

ColdFusion 8

support for the bind attribute in
HTML forms and the bindAttribu
te, bindOnload, and onBindErr
or attributes.
datefield value of the type attrib
ute in HTML forms
height and width attributes (all
except checkbox and radiobutton)

ColdFusion MX 7

bind attribute (text and password)
label attribute (all but button,
image, reset, and submit)
mask attribute (text only)
validateAt attribute (all but
button, image, reset, and submit)
datefield, button, file, hidd
en, image, reset, and submit val
ues of type attribute
daynames and monthnames attrib
utes (type="datefield" only)
boolean, email, guid, maxleng
th, noblanks, range, submitOn
ce, URL, USdate, and uuid values
of the validate attribute
tooltip, visible, and enabled
attributes (Flash forms only)
src attribute (image only)
cfinterface

All

© 2014 Adobe Systems Incorporated. All rights reserved.

ColdFusion 8

97

Adobe ColdFusion Documentation

refreshWSDL, wsdl2java argum
ents

ColdFusion 8

servicePort attribute for web
services

ColdFusion MX 7

All

ColdFusion MX

cfinvokeargument

omit attribute

ColdFusion MX 7

All

ColdFusion MX

cflayout

All

ColdFusion 8

cflayoutarea

All

ColdFusion 8

cfldap

returnAsBinary attribute

ColdFusion MX 7

cflocation

statusCode attribute

ColdFusion 8

cflock

Request value of scope attribute

ColdFusion 8

cflogin

All

ColdFusion MX

cfloginuser

All

ColdFusion MX

cflogout

All

ColdFusion MX

cfloop

characters, file, and array att
ributes

ColdFusion 8

cfmail

prioirity, useSSL, and useTLS

ColdFusion 8

The cfmail tag no longer lets you
send multipart mail by embedding
the entire MIME-encoded message
in the tag body. Use the cfmailpa
rt tag, instead.

ColdFusion MX 7

charset, failto, replyTo, use
rName, password, wrapText attri
butes

ColdFusion MX 6.1

spoolEnable attribute

ColdFusion MX

contentID,
{{disposition}}attributes

ColdFusion MX 7

cfinvoke

cfmailparam

© 2014 Adobe Systems Incorporated. All rights reserved.

98

Adobe ColdFusion Documentation

type attribute

ColdFusion MX 6.1

cfmailpart

All

ColdFusion MX 6.1

cfmap

All

ColdFusion 9

cfmapitem

All

ColdFusion 9

cfmediaplayer

All

ColdFusion 9

cfmenu

All

ColdFusion 8

cfmenuitem

All

ColdFusion 8

cfmessagebox

All

ColdFusion 9

cfNTauthenticate

All

ColdFusion MX 7

cfobject

.net value of type attribute and
related assembly, port, protoco
l, and secure attributes

ColdFusion 8

password, proxyPassword, pro
xyPort, proxyServer, proxyUs
er, refreshWSDL, userName, ws
dl2JavaArgs, and wsportname a
ttributes for web services
component and webservice attri
butes

ColdFusion MX

cfobjectcache

All

ColdFusion MX

cfparam

min, max, pattern attributes

ColdFusion MX 7

creditcard, email, eurodate,
float, integer, range, regex, r
egular_expression, ssn, soci
al_security_number, time, UR
L, USdate, XML, zipcode values
of the type attribute

© 2014 Adobe Systems Incorporated. All rights reserved.

99

Adobe ColdFusion Documentation

cfpdf

action = "thumbnail" has the
following new attributes:

ColdFusion 9

hires
compresstiffs
maxlength
maxbreadth
maxscale
action = "optimize" (new
action with all new attributes)
action = "addheader" (new
action)
action = "addfooter" (new
action)
action =
"removeheaderfooter" (new
action)
action = "extracttext"
action = "extractimage"
action = "write" package
= "true"
action = "merge"
encodeall="true"
action = "write" name=
#PDF variable#
action = "transform" (new
action)
cfpdfform

All

ColdFusion 8

cfpdfformparam

All

ColdFusion 8

cfpdfparam

All

ColdFusion 8

cfpdfsubform

All

ColdFusion 8

cfpod

All

ColdFusion 8

cfpop

cids query variable

ColdFusion MX 7.01

cfpresentation

All

ColdFusion 8

cfpresentationslide

All

ColdFusion 8

cfpresenter

All

ColdFusion 8

cfprint

All

ColdFusion 8

cfprocessingdirective

pageEncoding attribute

ColdFusion MX

© 2014 Adobe Systems Incorporated. All rights reserved.

100

Adobe ColdFusion Documentation

cfprocparam

All

ColdFusion 9

cfprogressbar

All

ColdFusion 9

cfproperty

All

ColdFusion MX

cfquery

result attribute

ColdFusion MX 7

cfreturn

All

ColdFusion MX

cfreport

HTML, XML values of format attribu
te, resourceTimespan, style att
ributes

ColdFusion 8

RTF value of format attribute

ColdFusion MX 7.01

template, format, name, filen
ame, query, overwrite attribute

ColdFusion MX 7

cfreportparam

chart, query, series, style, su
breport attributes

ColdFusion 8

name, value attributes

ColdFusion MX 7

cfsearch

category, categoryTree, stat
us, suggestions, contextPass
ages, contextBytes, contextH
ighlightBegin, contextHighl
ightEnd, previousCriteria att
ributes

ColdFusion MX 7

natural, internet, and intern
et_basic values of type attribute
cfselect

support for the bind attribute in
HTML forms and the bindAttribu
te, bindOnload, and onBindErr
or attributes.

ColdFusion 8

Support for tooltips in HTML forms
including the sourceForTooltip
attribute
selected attribute can take a list

© 2014 Adobe Systems Incorporated. All rights reserved.

ColdFusion MX 7

101

Adobe ColdFusion Documentation

enabled, group, height, label,
onKeyUp, onKeyDown, onMouseU
p, onMouseDown, onChange, onC
lick, queryPosition, tooltip,
visible, and width attributes
cfsetting

requestTimeOut attribute

ColdFusion MX

cfsharepoint

All

ColdFusion 9

cfspreadsheet

All

ColdFusion 9

cfsprydataset

All

ColdFusion 8

cfstoredproc

result attribute

ColdFusion MX 7

cftextarea

Rich text editor support including
the following attributes (HTML
format only): richtext, basepath
, fontFormats, fontNames, fon
tSizes, skin, stylesXML, temp
latesXML, toolbar, toolbarOn
Focus, and support for the height
and width attributes in HTML
format

ColdFusion 8

support for the bind attribute and b
indAttribute, bindOnLoad, and
onBindError attributes in HTML
format
support for tooltips in HTML format
including tooltip and sourceFo
rToolTip attribute
html attribute

ColdFusion MX 7.01
All

ColdFusion MX 7

cfthread

All

ColdFusion 8

cfthrow

object attribute

ColdFusion MX

cftimer

All

ColdFusion MX 7

cftooltip

All

ColdFusion 8

© 2014 Adobe Systems Incorporated. All rights reserved.

102

Adobe ColdFusion Documentation

onBlur and onFocus attributes

ColdFusion MX 7.01

format, onChange, style attribut
es

ColdFusion MX 7

cftrace

All

ColdFusion MX

cfwindow

ALL

ColdFusion 8

cfxml

All

ColdFusion MX

cfzip

All

ColdFusion 8

cfzipparam

All

ColdFusion 8

cftree

© 2014 Adobe Systems Incorporated. All rights reserved.

103

Adobe ColdFusion Documentation

Deprecated tags, attributes, and values
The following tags, attributes, and attribute values are deprecated. Do not use them in ColdFusion applications.
They might not work, and might cause an error, in releases later than ColdFusion MX.
Updated information for ColdFusion 11
Please note that there is a new document for ColdFusion 11, located outside of this manual, with
additional and more details information about deprecated and removed/obsoleted features. See
Deprecated Features.

Tag

Attribute or value

Deprecated as of this ColdFusion
release

cfcache

cachedirectory, timeout attrib
utes

ColdFusion MX

cfcollection

map and repair options of the act
ion attribute

ColdFusion MX 7

cferror

monitor option of the exception
attribute

ColdFusion MX

cffile

system value for attributes attri
bute

ColdFusion MX

temporary value for attributes
attribute

ColdFusion MX

passthrough attribute

ColdFusion MX 7

enableCAB attribute

ColdFusion MX

cfftp

agentname attribute

ColdFusion MX

cfgraph

All

ColdFusion MX

cfgraphdata

All

ColdFusion MX

cfgridupdate

connectString, dbName, dbSer
ver, dbType, provider, provid
erDSN attributes

ColdFusion MX

cfinput

passthrough attribute

ColdFusion MX 7

cfinsert

connectString, dbName, dbSer
ver, dbType, provider, provid
erDSN attributes

ColdFusion MX

cfform

© 2014 Adobe Systems Incorporated. All rights reserved.

104

Adobe ColdFusion Documentation

cfldap

filterFile attribute

ColdFusion MX

cflog

date, thread, time attributes

ColdFusion MX

cfquery

connectString, dbName, dbSer
ver, provider, providerDSN, s
ql attributes

ColdFusion MX

The following dbType attribute
values:
dynamic, ODBC, Oracle73, Orac
le80, Sybase11, OLEDB, DB2

ColdFusion MX(The value query is
valid.)

cfregistry

All, on UNIX only

ColdFusion MX

cfsearch

external, language attributes

ColdFusion MX

cfselect

passthrough attribute

ColdFusion MX 7

cfservlet

All

ColdFusion MX

cfservletparam

All

ColdFusion MX

cfslider

img, imgStyle, grooveColor, r
efreshLabel, tickmarkimages,
tickmarklabels, tickmarkmaj
or, tickmarkminor attributes

ColdFusion MX

cfstoredproc

connectString, dbName, dbSer
ver, dbtype, provider, provid
erDSN attributes

ColdFusion MX

cftextinput

All

ColdFusion MX 7

cfupdate

connectString, dbName, dbSer
ver, dbtype, provider, provid
erDSN attributes

ColdFusion MX

© 2014 Adobe Systems Incorporated. All rights reserved.

105

Adobe ColdFusion Documentation

Obsolete tags, attributes, and values
The following tags, attributes, and attribute values are obsolete. Do not use them in ColdFusion applications. They
do not work, and might cause an error, in releases later than ColdFusion 5.
Updated information for ColdFusion 11
Please note that there is a new document for ColdFusion 11, located outside of this manual, with
additional and more details about deprecated and removed/obsoleted features. See Deprecated
Features.

Tag

Attribute or value

Obsolete as of this ColdFusion
release

cfauthenticate

All

ColdFusion MX

cfchart

rotated attribute

ColdFusion MX 7

cffile

attributes attribute value archi
ve

ColdFusion MX

cfimpersonate

All

ColdFusion MX

cfindex

action attribute value optimize

ColdFusion MX

external attribute
cfinternaladminsecurity

All

ColdFusion MXThis tag did not
appear in CFML Reference.

cfldap

filterConfig and filterFile
attributes

ColdFusion MX

cfnewinternaladminsecurity

All

ColdFusion MXThis tag did not
appear in CFML Reference.

cfsetting

catchExceptionsByPattern att
ribute

ColdFusion MX

#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

106

Adobe ColdFusion Documentation

Tags a-b

This section lists tags starting with alphabets A-B with their description.
cfabort
cfajaximport
cfajaxproxy
cfapplet
cfapplication
cfargument
cfassociate
cfauthenticate
cfbreak

© 2014 Adobe Systems Incorporated. All rights reserved.

107

Adobe ColdFusion Documentation

cfabort
Description

Stops the processing of a ColdFusion page at the tag location. ColdFusion returns everything that was processed
before the tag. The tag is often used with conditional logic to stop processing a page when a condition occurs.
Category

Flow-control tags
Syntax



Note
You can specify this tag's attributes in an attributeCollection whose value is a structure.
Specify the structure name in the attributeCollection and use the tag's attribute names as
structure keys.

See also

cfbreak, cfexecute, cfexit, cfif, cflocation, cfloop, cfswitch, cfthrow, cftry; cfabort and cfexit in
the Developing ColdFusion Applications
Attributes

Attribute

Req/Opt

showError

Optional

Default

Description
Error to display, in a
standard ColdFusion error
page, when tag executes.

Usage

When you use the cfabort and cferror tags together, the cfabort tag halts processing immediately; the cfer
ror tag redirects output to a specified page. If this tag does not contain a showError attribute value, processing
stops when the tag is reached and ColdFusion returns the page contents up to the line that contains the cfabort ta
g.
When you use this tag with the showError attribute, but do not define an error page using cferror, page
processing stops when the cfabort tag is reached. The message in showError displays to the client.When you
use this tag with the showError attribute and an error page using cferror, ColdFusion redirects output to the
error page specified in the cferror tag.
Note
When using cfabort, cflocation, or cfcontent tags, the OnAbort method is invoked
instead on OnRequestEnd.

© 2014 Adobe Systems Incorporated. All rights reserved.

108

Adobe ColdFusion Documentation
Example

This example shows the use of cfabort to stop processing. In the second example, where cfabort is used, the
result never displays.

Example A: Let the instruction complete itself







The value of myVariable after incrementing through the loop #Counter# times is:
#myVariable#

Example B: Use cfabort to halt the instructions with showmessage attribute and
cferror
















 The value of myVariable after incrementing through the loop#counter# times is:
#myVariable#


© 2014 Adobe Systems Incorporated. All rights reserved.

109

Adobe ColdFusion Documentation

cfajaximport
Description

Controls the JavaScript files that are imported for use on pages that use ColdFusion AJAX tags and features.
Category

Internet protocol tags
Syntax



Note
You can specify this tag's attributes in an attributeCollection whose value is a structure.
Specify the structure name in the attributeCollection and use the tag's attribute names as
structure keys.

See also

cfform, cfgrid, cfinput, cflayout, cfmenu, cfpod, cfsprydataset, cftextarea, cftooltip, cftree,
cfwindow, Specifying client-side support files in the Developing ColdFusion Applications
History

ColdFusion 8: Added this tag.
Attributes

Attribute

Req/Opt

© 2014 Adobe Systems Incorporated. All rights reserved.

Default

Description

110

Adobe ColdFusion Documentation

cssSrc

Optional

params

Optional

© 2014 Adobe Systems Incorporated. All rights reserved.

scriptsrc/ajax

Specifies the URL,
relative to the web root, of
the directory that contains
the CSS files used by
ColdFusion AJAX
features, with the
exception of the rich text
editor. This directory must
have the same directory
structure, and contain the
same CSS files, and
image files required by the
CSS files, as the web_roo
t/CFIDE/scripts/ajax/resou
rces directory.
This attribute lets you
create different custom
styles for ColdFusion
AJAX controls in different
applications.
This attribute allows you
to specify parameters for
the CFM page. Currently,
the only parameter that
you can specify is googl
emapkey. You can
specify the googlemapke
y as follows:

111

Adobe ColdFusion Documentation

scriptSrc

Optional

tags

Optional

scriptsrc setting in the
Administrator;default path
is /CFIDE/scripts/

Specifies the URL,
relative to the web root, of
the directory that contains
the client-side script files
used by ColdFusion. This
directory includes the
JavaScript files and the
default location of the
CSS files used for all
AJAX features. If you use
this attribute, the cfajax
import tag must precede
all other ColdFusion AJAX
tags on the page; that is,
all tags that rely on the
scripts.
You can have only one sc
riptsrc attribute on a
page, in a cfajaximpor
t tag or a cfform tag.
You can use a scriptsr
c attribute in a cfajaxim
port tag to apply its
value to all forms on a
page.
A comma-delimited list of
tags or tag-attribute
combinations for which to
import the supporting
JavaScript files on this
page.
If you use this attribute, it
must specify all
ColdFusion AJAX tags
that you use on the page
and on any pages
specified in tag source at
tributes.
For a list of valid attribute
values and their purposes,
see Usage.

Usage
Using the scriptsrc and cssSrc attributes

The scriptsrc attribute is useful if the JavaScript files are not in the default location. This attribute is required in
some hosting environments and configurations that block access to the /CFIDE directory. The default scriptsrc v
alue is determined by the Default CFFORM ScriptSrc Directory setting on the Server Settings > Settings page of the
ColdFusion Administrator. For cfform tags, the tag's scriptsrc attribute takes precedence over this attribute.

© 2014 Adobe Systems Incorporated. All rights reserved.

112

Adobe ColdFusion Documentation

You can use this attribute only if the cfajaximport tag is on a top-level page; that is, a page that the client directly
requests. You cannot use it, for example, on a page that is specified in a cfwindow tag source attribute.
When you use the cfajaximport tag with a scriptsrc attribute, the specified directory must have the same
structure as the /CFIDE/scripts directory. For example, if you specify scriptsrc="/resources/myScripts",
the JavaScript files used by AJAX must be in the /resources/myScripts/ajax directory. This attribute specifies the
folder that contains the ColdFusion client-side files for all subsequent tags on the current page, not just for
AJAX-based tags. Therefore, the directory tree must include all ColdFusion client-side files used by those tags. For
example, if a cfform tag on the page is in Flash or applet format, include the CF_RunActiveContent.js file in the
directory specified by the scriptsrc attribute.
You use the cssSrc attribute to specify the location of the CSS files required by ColdFusion AJAX features. This
attribute overrides the scriptsrc/ajax/resources directory for the current page. Therefore, if all pages that use a
custom scriptsrc directory also use a custom cssSrc directory, you do not have to include the ColdFusion AJAX
CSS files in the scriptsrc directory tree.
Using the tags attribute or no attribute

If you do not use the cfajaximport tag on a page that contains ColdFusion tags with AJAX UI features,
ColdFusion correctly imports the required JavaScript files in most cases. Use this tag to explicitly import JavaScript
files in these cases:
If you use a ColdFusion AJAX JavaScript function, such as ColdFusion.navigate, ColdFusion.Ajax.s
ubmitForm, or ColdFusion.Log.info on a page that does not otherwise import any AJAX JavaScript
functions, use the cfajaximport tag with no attribute to import the base JavaScript functions only. For
example, use this tag on a page that does not include any ColdFusion AJAX-based tags,
If the following conditions are true:
You use any source attributes in cflayoutarea, cfpod or cfwindow tags, or bind attribute in cfd
iv tag.
The file that the source or bind attribute specifies has any of the tags listed in the following table.
You do not use each of the listed tags on the top-level page.
If these conditions are true, the top-level page must use the cfajaximport tag with a tags attribute
that specifies the tags that only the other pages use. Otherwise, ColdFusion cannot identify that it will
be using the tags and does not import the necessary JavaScript files.
You can specify any or all the following tag attribute values:
Attribute value

Used for

cfdiv

cfdiv tags

cfform

Forms that are in cfpod, cfwindow, or cflayoutare
a tag bodies

cfgrid

AJAX format cfgrid tags

cfinput-autosuggest

cfinput tags that use the autosuggest attribute

cfinput-datefield

HTML format cfinput tags that use the datefield a
ttribute

cflayout-border

cflayout tags with a type attribute value of border

© 2014 Adobe Systems Incorporated. All rights reserved.

113

Adobe ColdFusion Documentation

cflayout-tab

cflayout tags with a type attribute value of tab

cfmenu

cfmenu tags

cfpod

cfpod tags

cfsprydataset-JSON

cfsprydataset tags that generate Spry JSON data
sets

cfsprydataset-XML

cfsprydataset tags that generate Spry XML data
sets

cftextarea

HTML format cftextarea tags

cftooltip

cftooltip tags

cftree

HTML format cftree tags

cfwindow

cfwindow tags

Example

The following cfajaximport tag example specifies separate custom locations for the scripts used for AJAX
features and for the AJAX CSS files. It also imports all JavaScript files used for cftree, and cftooltip.



© 2014 Adobe Systems Incorporated. All rights reserved.

114

Adobe ColdFusion Documentation

cfajaxproxy
Description

Creates a JavaScript proxy for a ColdFusion component, for use in an AJAX client. Alternatively, creates a proxy for
a single CFC method, JavaScript function, or URL that is bound to one or more control attribute values.
Category

Internet protocol tags
Syntax


OR


Note
You can specify this tag's attributes in an attributeCollection whose value is a structure.
Specify the structure name in the attributeCollection and use the tag's attribute names as
structure keys.

See also

DeserializeJSON, IsJSON, SerializeJSON, Using Ajax Data and Development Features in the Developing
ColdFusion Applications
History

ColdFusion 8: Added this tag
Attributes

Attribute

Req/Opt

© 2014 Adobe Systems Incorporated. All rights reserved.

Default

Description

115

Adobe ColdFusion Documentation

bind

A bind or cfc attribute is
required

A bind expression that
specifies a CFC method,
JavaScript function, or
URL to call. For detailed
information about
specifying bind
expressions, see Binding
data to form fields in the D
eveloping ColdFusion
Applications.
You cannot use this
attribute with the cfc attri
bute.

cfc

A bind or cfc attribute is
required

The CFC for which to
create a proxy. Specify a
dot-delimited path to the
CFC. The path can be an
absolute filepath, or
relative to location of the
CFML page. For example,
if the myCFC CFC is in
the cfcs subdirectory of
the ColdFusion page,
specify cfcs.myCFC. If the
CFC extends another
CFC, the extended CFC
methods are also
available to the JavaScript
proxy.On UNIX-based
systems, the tag searches
first for a file whose name
or path corresponds to the
specified name or path,
but is in all lowercase. If it
does not find it,
ColdFusion then searches
for a filename or path that
corresponds to the
attribute value exactly,
with identical character
casing.
This attribute cannot be
used with the bind attribu
te.

© 2014 Adobe Systems Incorporated. All rights reserved.

116

Adobe ColdFusion Documentation

jsclassname

Optional

The value of the cfc attri
bute

The name to use for the
JavaScript proxy class
that represents the CFC.
This attribute cannot be
used with a bind attribute
.

onError

Optional

The name of a JavaScript
function to invoke when a
bind, specified by the bin
d attribute fails. The
function must take two
arguments: an error code
and an error message.
This attribute cannot be
used with a cfc attribute.

onSuccess

Optional

The name of a JavaScript
function to invoke when a
bind, specified by the bin
d attribute succeeds. The
function must take one
argument, the bind functi
on return value. If the bind
function is a CFC function,
the return value is
automatically converted to
a JavaScript variable
before being passed to
the onSuccess function.
This attribute cannot be
used with a cfc attribute.

Usage

Make sure that the Enable HTTP Status Codes option on the Server Settings > Settings page of the ColdFusion
Administrator is selected. Otherwise, the proxy cannot determine if an error occurs in invoking the CFC function and
cannot call the error handler.A cfajaxproxy tag with a bind attribute does not refresh any control that is not
specified in the bind expression.
If you specify a URL in the bind attribute, the HTTP response must consist of a single JSON representation of an
object, array, or simple value, corresponding to the onSuccess argument.
Creating a CFC proxy

The cfajaxproxy tag with a cfc attribute generates a JavaScript proxy that represents a CFC on the web client.
The tag and the proxy it generates have the following characteristics:
The proxy provides one function that corresponds to each CFC remote function. Calling these functions in
your client-side JavaScript code remotely calls the CFC functions on the server.
The proxy provides several functions that you call to configure the interaction between the client and the
server. These functions set the HTTP method and synchronization mode of the XMLHttpRequest call that the
proxy uses to interact with the server. The functions also can specify a JavaScript callback handler and an

© 2014 Adobe Systems Incorporated. All rights reserved.

117

Adobe ColdFusion Documentation

error handler for asynchronous calls.
Because JavaScript is case sensitive, ensure that you match the case of the keys in any ColdFusion structure
or scope that you send to the client. By default, ColdFusion sets variable names and structure element
names to all-uppercase. (You can create structure element names with lowercase characters by specifying
the names in associative array notation, for example, myStruct"myElement"="value".) The keys for the
two arrays in the JSON object that the ColdFusion serializeJSON tag generates to represent a query are C
OLUMNS and DATA, for example, not columns and data.
For detailed information on using AJAX CFC proxies, see Using ColdFusion Ajax CFC proxies in Using Ajax
Data and Development Features in the Developing ColdFusion Applications.
Note
The proxy passes a _CF_NODEBUG Boolean argument to called CFC functions.
ColdFusion checks this value, and when it is true, does not append to the response any
debugging information that it normally would send. This behavior ensures that the JSON
responses to AJAX requests do not include any non-JSON (i.e., debug information) text.

CFC proxy utility functions

When you use the cfc option, the JavaScript proxy object provides the following functions that you can use to
control interaction with the server:
Function

Description

setAsyncMode()

Sets the call mode to asynchronous. The calling thread
(the Java thread of the client system that is processing
the page) is not blocked when you make a call to a
proxy function, so page processing can continue while
waiting for a response from the server. The proxy
invokes the function specified by the setCallbackHa
ndler function with the response from the server. If an
error occurs, the proxy invokes the error handler
specified by the setErrorHandler function.

setCallbackHandler(function)

Specifies the callback handler for an asynchronous call.
The function parameter is the JavaScript function to
invoke as an argument. The callback function must
take one parameter, the return value from the CFC that
the proxy has deserialized from JSON to a JavaScript
representation.
This method automatically sets the call mode to
asynchronous.

© 2014 Adobe Systems Incorporated. All rights reserved.

118

Adobe ColdFusion Documentation

setErrorHandler(function)

Sets the error handler that the proxy invokes if there is
an error in an asynchronous call. The function para
meter is the JavaScript function to invoke. The error
handler function must take two parameters:
An HTTP error code
A status message
This method automatically sets the call mode to
asynchronous.

setForm(ID)

Adds names and values of the fields in the form
specified by the ID attribute to the arguments passed
by a proxy function that is called immediately after this
function.
For more information, see Submitting data to a CFC in
the Developing ColdFusion Applications.

setHTTPMethod("method")

Sets the HTTP method to use for the call. The method
parameter is a case-insensitive string, and must have
one of the following values:
GET (the default method)
POST

setQueryFormat(format)

Specifies the JSON format in which to return
ColdFusion query data. The parameter must have one
of the following values:
row: (Default) Sends the data as a JSON object with
two entries: the column names and an array of row
arrays.
column: Sends the data as a JSON object that
represents WDDX query format. This object has
three entries: the number of rows, an array with the
column names, and an object where the keys are the
column names and the values are arrays containing
the column data.
For more information on query formats, see Serial
izeJSON.

© 2014 Adobe Systems Incorporated. All rights reserved.

119

Adobe ColdFusion Documentation

setReturnFormat(format)

Specifies the format in which the CFC function returns
the result. ColdFusion automatically converts the
function return value into the specified format before
returning it to the client.
The parameter must have one of the following values:
json (the default format if you don't use this
function)
plain
wddx
If you specify plain, and set the "content-type"
header on the response from the server to text/xm
l, the proxy returns an XML object to the caller or
callback function. If the content type is not set to tex
t/xml, the return value from the server is returned
as-is. This function is useful if you return XML or a
plain string to the browser.

setSyncMode()

Sets the call mode to synchronous (the default
synchronization mode). The calling thread remains
blocked until the call returns. If an error occurs, the
proxy throws an exception. In synchronous mode, the
methods in the CFC proxy return the CFC method
results directly to the caller.

Example

The following example uses a remote CFC method to populate a drop-down list of employees. When you select a
name from the list, it uses a call to the CFC method to get information about the employee, and displays the results.
The application page has the following lines:










List of Employees:   









© 2014 Adobe Systems Incorporated. All rights reserved.

122

Adobe ColdFusion Documentation




The following component, which gets the data from the data source, must be in a file named emp.cfc in the
components subdirectory of the application directory. The CFC uses the cfdocexamples data source that is installed
with ColdFusion if you install the documentation.






select * from Employees

where Emp_ID = #empid#






© 2014 Adobe Systems Incorporated. All rights reserved.

123

Adobe ColdFusion Documentation

cfapplet
Description

This tag references a registered custom Java applet. To register a Java applet, in the ColdFusion Administrator,
select Extensions > Java Applets. Using this tag within a cfform tag is optional. If you use it within cfform, and
the method attribute is defined in the Administrator, the return value is incorporated into the form.
Category

Forms tags
Syntax



Note
You can specify this tag's attributes in an attributeCollection whose value is a structure.
Specify the structure name in the attributeCollection and use the tag's attribute names as
structure keys.

See also

cfform, cfformgroup, cfformitem, cfgrid, cfinput, cfobject, cfselect, cfservlet, cfslider, cfte
xtarea, cftree
History

ColdFusion MX:
Removed the requirement that you use this tag within a cfform tag.
Changed the behavior when this tag is used within a cfform tag; if the method attribute is defined in the
Administrator, the return value of the applet's method is incorporated into the form.
Attributes

Attribute

Req/Opt

appletSource

Required

© 2014 Adobe Systems Incorporated. All rights reserved.

Default

Description
Name of registered
applet.

124

Adobe ColdFusion Documentation

name

Required

Form variable name for
applet.

align

Optional

Alignment:
Left
Right
Bottom
Top
TextTop
Middle
AbsMiddle
Baseline
AbsBottom

height

Optional

Height of applet, in pixels.

hSpace

Optional

Space on left and right of
applet, in pixels.

notSupported

Optional

param_n

Optional

Registered parameter for
applet. Specify only to
override values for applet
in ColdFusion
Administrator.

vSpace

Optional

Space above and below
applet, in pixels.

width

Optional

Width of applet, in pixels.

See description

Text to display if a page
that contains a Java
applet-based cfform con
trol is opened by a
browser that does not
support Java or has Java
support disabled, for
example:notSupported
= "Browser must
support Java to
view ColdFusion{{Java
Applets"}} Default
value: Browser
must support Java
to
 view
ColdFusion Java
Applets!

Usage

© 2014 Adobe Systems Incorporated. All rights reserved.

125

Adobe ColdFusion Documentation

You can specify the applet method attribute only in the Administrator, Java Applets view. For other attributes, you
can accept the default values in the Administrator view, or specify values in this tag and override the defaults. If Java
applet components are stored in a JAR file, enter the information in the J2EE Archives > ColdFusion Administrator.
For more information, see Embedding Java applets in the Developing ColdFusion Applications
Example

cfapplet lets you reference custom Java applets that have been
registered using the ColdFusion Administrator.
To register a Java applet, open the ColdFusion Administrator and
click "Applets" link under "extensions" section.
This example applet copies text that you type into a form. Type
some text, and then click "copy" to see the copied text.




© 2014 Adobe Systems Incorporated. All rights reserved.

126

Adobe ColdFusion Documentation

cfapplication
Description

Defines the scope of a ColdFusion application; enables and disables storage of Client variables; specifies the Client
variable storage mechanism; enables Session variables; and sets Application variable time-outs.
Category

Application framework tags
Syntax



Note
You can specify this tag's attributes in an attributeCollection whose value is a structure.
Specify the structure name in the attributeCollection and use the tag's attribute names as
structure keys.

See also

cfassociate, cferror, cflock, cfmessagebox; Application.CFC Reference; Designing and
Optimizing a ColdFusion Application and Integrating JEE and Java Elements in CFML
Applications in the Developing ColdFusion Applications
History

ColdFusion 11: Added attributes - compileextforinclude and strictnumbervalidation
ColdFusion 9: Added datasource, googleMapKey, and serverSideFormValidation attributeColdFusion
8: Added secureJSON and SecureJSONPrefix attributesColdFusion MX 7: Added scriptProtect attributeCol
dFusion MX 6.1: Added loginStorage attributeColdFusion MX:
Changed how persistent scopes are available: Server, Session, and Application scope variables are stored in
memory as structures. In earlier releases, only Session and Application scope variables were stored this way.
You cannot access the UDF function scope as a structure.
Changed the algorithm for setting the CFTOKEN variable value: if the registry key UUIDToken is a nonzero

© 2014 Adobe Systems Incorporated. All rights reserved.

127

Adobe ColdFusion Documentation

value, ColdFusion uses a number constructed from the UUID plus a random number. Otherwise, ColdFusion
sets the CFTOKEN variable default value using a positive random integer. (In earlier releases, ColdFusion
always used a number constructed from the UUID plus a random number.)
Attributes

Attribute

Req/Opt

Default

Description

authCookie

Optional

Struct containing
ColdFusion Authentication
cookie related properties

datasource

Optional

Name of the data source
from which the query
retrieves data.

name

See Description

Name of application. Up
to 64 characters.
For Application and
Session variables:
Required. For Client
variables: Optional

applicationTimeout

Optional

Specified in Variables
page of ColdFusion
Administrator

clientManagement

Optional

no

clientStorage

Optional

registry

Lifespan of application
variables. CreateTimeS
pan function and values in
days, hours, minutes, and
seconds, separated by
commas.
yes: enables client
variables.
no
How client variables are
stored:
datasource_name: in
ODBC or native data
source. Create storage
repository in the
Administrator.
registry: in the
system registry.
cookie: on client
computer in a cookie.
Scalable. If client
disables cookies in the
browser, client variables
do not work.

© 2014 Adobe Systems Incorporated. All rights reserved.

128

Adobe ColdFusion Documentation

exchangeServerVersi
on

Optional

2007

Specifies the Microsoft
Exchange Server version.
The values are:
2003
2007
2010
If you do not specify the
details, 2007 is taken
by default.

googleMapKey

Optional

The Google Maps API key
required to embed Google
Maps in your web pages.

loginStorage

Optional

cookie

scriptProtect

Optional

Determined by
ColdFusion Administrator
Enable Global Script
Protection setting

secureJSON

Optional

Administrator value

serverSideFormValid
ation

Optional

yes

© 2014 Adobe Systems Incorporated. All rights reserved.

cookie: store login
information in the
Cookie scope.
session: store login
information in the
Session scope.
Specifies whether to
protect variables from
cross-site scripting attacks
none: do not protect
variables
all: protect Form,
URL, CGI, and Cookie
variables
comma-delimited list of
ColdFusion scopes:
protect variables in the
specified scopes.
For more information,
see Usage.

If no, disables validation
on cfform fields when the
form is submitted.

129

Adobe ColdFusion Documentation

secureJSONPrefix

Optional

sessionCookie

Optional

sessionManagement

Optional

no

sessionTimeout

Optional

Specified in Variables
page of ColdFusion
Administrator

setClientCookies

Optional

yes

© 2014 Adobe Systems Incorporated. All rights reserved.

Administrator value

The security prefix to put
in front of the value that a
ColdFusion function
returns in JSON-format in
response to a remote call
if the secureJSON setting
is true. The default value
is the value of the Prefix
serialized JSON setting in
the Administrator Server
Settings > Settings page
(which defaults to //, the
JavaScript comment
character).
For more information see I
mproving security in the D
eveloping ColdFusion
Applications.
Struct containing
ColdFusion session
cookie related properties.
yes: enables session
variables.
no
Life span of session
variables. CreateTimeS
pan function and values in
days, hours, minutes, and
seconds, separated by
commas.
yes: enables client
cookies.
no: ColdFusion does
not automatically send
CFID and CFTOKEN
cookies to client
browser; you must
manually code CFID
and CFTOKEN on the
URL for every page that
uses Session or Client
variables.

130

Adobe ColdFusion Documentation

setDomainCookies

Optional

compileextforinclude

Optional

© 2014 Adobe Systems Incorporated. All rights reserved.

no

yes: uses domain
cookies for CFID and
CFTOKEN cookies and
for all Client variables
when using cookies for
client variable storage.
Required for
applications running on
clusters.
no: uses host-specific
cookies for CFID,
CFTOKEN, and all
client variable cookies.
Specify the list of allowed
file extensions (as a
comma separated list) for
the  tag.
Specifying a wildcard ('*')
in the list makes any file
included using the
 tag to be
compiled. If any file
included using the
 tag is not
found in this list, their
content will be statically
included. By default, files
with the extensions cfm
and cfml are always
compiled irrespective of
this setting. See cfinclude.

131

Adobe ColdFusion Documentation

strictnumbervalidation

Optional

true

In ColdFusion 10 and
earlier versions, the IsVali
d function allowed
currency symbols at the
start and commas inside
the number.
Starting from ColdFusion
11, this function evaluates
on a more strict basis.
Setting this value to false
makes the isValid function
to behave in the older
way. This setting effects cf
argument, cfparam and cff
orm tags wherever integer
& numeric validation is
used. Based on this
setting, the validation
reflects in those tags as
well.

Usage

This tag is typically used in the Application.cfm file, to set defaults for a ColdFusion application.
Note
You can also set the application defaults in the Application.cfc file. For more information, see Ap
plication variables.

This tag enables application variables, unless they are disabled in the ColdFusion Administrator. The Administrator
setting also overrides the sessionManagement attribute. For more information, see Configuring and Administering
ColdFusion. If ColdFusion is running on a cluster, specify clientStorage = "cookie" or a data source name;
you cannot specify "registry".ColdFusion generates an error if the application name is longer than 64
characters. The CFTOKEN variable is 8 bytes in length. Its range is 10000000 -99999999.
Note
If you specify ClientStorage=cookie, any Client scope variables set following a cfflush ta
g are not saved in the Client browser.

Protecting variables from cross-site scripting attacks

The ScriptProtect attribute lets you protect one or more variable scopes from cross-site scripting attacks, where
a client attempts to get your application to send malicious code back to a user's browser. In these attacks, user input
(for example, from form fields or from URL variables) sets a CF variable which is destined for user output. The
submitted data includes malicious code, such as JavaScript or an applet or object reference, which then executes
on the user's system.

© 2014 Adobe Systems Incorporated. All rights reserved.

132

Adobe ColdFusion Documentation

Note
The ColdFusion Administrator Settings page Enable Global Script Protection option determines
the default script protection setting. You can use the scriptProtect attribute to override the
Administrator setting. You can also use the Application.cfc initialization code to set the protection
value.

The ColdFusion cross-site scripting protection operation is done when ColdFusion processes the application
settings at the beginning of a request. Thus, it can process the URL, and Cookie, CGI, and Form variables in a
user's request. By default, it replaces occurrences of the following HTML tag names with the text InvalidTag: objec
t, embed, script, applet, and meta. It allows these names in plain text, and replaces the words if they are used
as tag names. You can specify any or all ColdFusion scopes for protection, but only the Form, URL, CGI, and
Cookie scopes have variables that are often provided by unknown sources. Also, protecting a scope requires
additional processing. For these reasons, the all attribute value applies protection to only the four scopes.
The script protection mechanism applies a regular expression that is defined in the cf_root/lib/neo-security.xml file in
the server configuration, or the cf_root/WEB-INF/cfusion/lib/neo-security.xml file in the JEE configuration to the
variable value. You can customize the patterns that ColdFusion replaces by modifying the regular expression in the
CrossSiteScriptPatterns variable.
Locking server, application, and session variables

When you set or update variables in the server, application, and session scopes, use the cflock tag with the scop
e attribute set to the following value:
For server variables, specify server
For application variables, specify application
For session variables, specify session
In some cases, you must also lock code that reads variables in these scopes. For information about locking
scopes, see cflock.
Example

© 2014 Adobe Systems Incorporated. All rights reserved.

133

Adobe ColdFusion Documentation


cfapplication Example
cfapplication defines scoping for a ColdFusion application and enables or
disables application and/or session variable storage. This tag is placed in a
special file called Application.cfm that automatically runs before any other CF page
in a directory (or subdirectory) where the Application.cfm file appears.












E-Turtleneck is proud to say that we have sold #application.number# turtlenecks to
date.



© 2014 Adobe Systems Incorporated. All rights reserved.

134

Adobe ColdFusion Documentation

cfargument
Description

Creates a parameter definition within a component definition. Defines a function argument. Used within a cffuncti
on tag.
Category

Extensibility tags
Syntax



See also

cfcomponent, cffunction, cfinterface, cfinvoke, cfinvokeargument, cfobject, cfproperty, cfret
urn
History

ColdFusion 10: Added the following REST attributes: restArgSource, restArgName}}
ColdFusion 8: Added {{component as a valid value for the ReturnType attribute.
ColdFusion MX 7: Added the xml value of type attribute.ColdFusion MX: Added this tag.
Attributes

Attribute

Req/Opt

name

Required

String; an argument
name.

default

Optional

If no argument is passed,
specifies a default
argument value.

displayname

Optional

© 2014 Adobe Systems Incorporated. All rights reserved.

Default

name attribute value

Description

Meaningful only for CFC
method parameters. A
value to display when
using introspection to
show information about
the CFC.

135

Adobe ColdFusion Documentation

hint

Optional

required

Optional

Meaningful only for CFC
method parameters. Text
to display when using
introspection to show
information about the
CFC. The hint attribute
value follows the displa
yname attribute value in
the parameter description
line. Use this attribute to
describe the purpose of
the parameter.
no

Note: All arguments are
required when invoked as
a web service,
irrespective of how they
are defined.Specifies
whether the parameter is
required to execute the
component method. The
parameter is not required
if you specify a default
attribute.
yes
no

restArgSource

Optional

One of the following:
path: Extracts
parameters from the
resource URL. URI path
parameters are
extracted from the
request URI, and the
parameter names
correspond to the URI
path template variable
names specified in the
restPath specified in
cffunction. The
default value cannot be
used with path param.

© 2014 Adobe Systems Incorporated. All rights reserved.

136

Adobe ColdFusion Documentation

query: Extracts
parameters from URL
query parameters.
Mostly used with HTTP
GET method. When
using GET method to
send data, the
parameters and values
are encoded into the
URL. QueryParam is
used to extract these
values and assign them
to the appropriate
variables.
form: Extracts
parameters from a form
submission. It is used
with HTTP POST metho
d.
cookie: Extracts
values form a cookie.
header: Extracts
parameters from HTTP
header.
matrix: Extracts
parameters from matrix
URI. For details, see htt
p://www.w3.org/DesignI
ssues/MatrixURIs.html.
If no value is specified,
parameters are taken
from the body of the
request.Using cfhttp,
you can send
arguments in either
form or body. For form
parameter, the
argument is consumed
if you specify form as
the value for restArgS
ource and for body
parameter, if you do not
specify restArgSourc
e.
While calling the
service, if you pass the
argument in body, in
some scenarios, it is
accepted as form. For
example, . This is
because, when you
pass the form
name-value pair
through cfhttp or the
body as "name=value
", the body content is
same, due to which
REST service is not
able to detect what is
passed.
In the service, if you
expect body argument
but while accessing the
service through cfhttp
, no argument in the
body is passed, you will
still receive the body
argument as empty
string.
If you use this attribute,
but do not specify the

© 2014 Adobe Systems Incorporated. All rights reserved.

138

Adobe ColdFusion Documentation

type attribute, string is
considered by default
as the type.
restArgName

Optional

type

Optional

© 2014 Adobe Systems Incorporated. All rights reserved.

The name that can be
mapped to the argument
name.
While calling functions,
arguments are extracted
from the incoming
request. If restArgName
is provided, it is searched
in the restArgSource s
cope of the request to
populate the argument. If
not specified, argument
name is searched.
If specified, then
argument name has no
impact. You can specify
correct argument name so
that it corresponds to the
appropriate parameter. If
the argument name
passed to a REST service
is not a valid Java
identifier, for example, the
name has hyphen (say ar
g-name), then you can
use this attribute to map
the argument name.
any

String; a type name; data
type of the argument.

139

Adobe ColdFusion Documentation

any
array
binary
boolean
component: the
argument must be a
ColdFusion component.
date
guid: the argument
must be a UUID or
GUID of the form xxxxx
xxx-xxxx-xxxx-xxxx-xxx
xxxxxxxxx where each_
x_ is a character
representing a
hexadecimal number
(0-9A-F).
numeric
query
string
struct
uuid: the argument
must be a ColdFusion
UUID of the form xxxxx
xxx-xxxx-xxxx-xxxxxxxx
xxxxxxxx where each_
x_ is a character
representing a
hexadecimal number
(0-9A-F).
variableName: a
string formatted
according to
ColdFusion variable
naming conventions.
xml: XML objects and
XML strings
a component name: if
the type attribute value
is not one of the
preceding items,
ColdFusion treats it as
the name of a
ColdFusion component.
When the function
executes, it generates
an error if the argument
that is passed in is not a
CFC with the specified
name.

Usage

© 2014 Adobe Systems Incorporated. All rights reserved.

140

Adobe ColdFusion Documentation

This tag must be in a cffunction tag, before any other tags in the cffunction tag body.Arguments that are
passed when a method is invoked can be accessed from the method body in the following ways:
With shorthand syntax: #myargument# (This example accesses the argument myargument.)
Using the arguments scope as an array: #arguments[1]# (This example accesses the first defined
argument in the cffunction.)
Using the arguments scope as a struct: #arguments.myargument# (This example accesses the argument
myargument in the array.)
Example







SELECT Descript
FROM Courses
WHERE Number = '#Course_Number#'





© 2014 Adobe Systems Incorporated. All rights reserved.

141

Adobe ColdFusion Documentation

cfassociate
Description

Allows subtag data to be saved with a base tag. Applies only to custom tags.
Category

Application framework tags
Syntax



Note
You can specify the attributes of this tag in an attributeCollection whose value is a
structure. Specify the structure name in the attributeCollection and use the tag's attribute
names as structure keys.

See also

cfapplication, cferror, cflock, cfmessagebox; High-level data exchange in Nesting custom tags in
the Developing ColdFusion Applications.
Attributes

Attribute

Req/Opt

baseTag

Required

dataCollection

Optional

Default

Description
Base tag name.

AssocAttribs

Structure in which base
tag stores subtag data.

Usage

Call this tag within a subtag, to save subtag data in the base tag.
When ColdFusion passes subtag attributes back to the base tag, it saves them in a structure whose default name is
AssocAttribs. To segregate subtag attributes (in a base tag that can have multiple subtags), specify a structure
name in the dataCollection attribute. The structure is appended to an array whose name is thistag.collectionNa
me.
In the custom tag code, the attributes passed to the tag by using the cfmodule tag attributeCollection attrib
ute are saved as independent values, with no indication that they are grouped into a structure by the custom tag's
caller. Therefore, in the called tag, if you assign a value to a specific attribute, it replaces the value passed in the at
tributeCollection attribute that you used when calling the subtag.
Example

© 2014 Adobe Systems Incorporated. All rights reserved.

142

Adobe ColdFusion Documentation








...

© 2014 Adobe Systems Incorporated. All rights reserved.

143

Adobe ColdFusion Documentation

cfauthenticate
Description

This tag is obsolete. Use the newer security tools; see Conversion functions and Securing Applications in the Develo
ping ColdFusion Applications.
History

ColdFusion MX: This tag is obsolete. It does not work in ColdFusion MX and later releases.

© 2014 Adobe Systems Incorporated. All rights reserved.

144

Adobe ColdFusion Documentation

cfbreak
Description

Used within a cfloop tag. Breaks out of a loop.
Category

Flow-control tags
Syntax



See also

cfabort, cfcontinue, cfexecute, cfif, cflocation, cfloop, cfthrow, cftry; cfloop and cfbreak in the D
eveloping ColdFusion Applications
Tag example


#i#






Script example

for (i=1; i <= 10; i++){
writeOutput("#i#
");
if (i >= 5){
break;
}
}

Either version of the code above outputs:

1
2
3
4
5

© 2014 Adobe Systems Incorporated. All rights reserved.

145

Adobe ColdFusion Documentation

© 2014 Adobe Systems Incorporated. All rights reserved.

146

Adobe ColdFusion Documentation

Tags c
This section lists tags starting with alphabet C with their description.
cfcache
cfcalendar
cfcase
cfcatch
cfchart
cfchartdata
cfchartseries
cfcol
cfcollection
cfcomponent
cfcontent
cfcontinue
cfcookie
cfclient
cfclientsettings

© 2014 Adobe Systems Incorporated. All rights reserved.

147

Adobe ColdFusion Documentation

cfcache
Description

Stores a copy of a page on the server and/or client computer, to improve page rendering performance. To do this,
the tag creates temporary files that contain the static HTML returned from a ColdFusion page.Use this tag if it is not
necessary to get dynamic content each time a user accesses a page. You can use this tag for simple URLs and for
URLs that contain URL parameters.
Category

Page processing tags
Syntax


useCache = "true|false"
usequerystring = "false|true"
username = "username"
value = "value">
The page fragment to be cached, if any.


Note
You can specify this tag's attributes in an attributeCollection attribute whose value is a
structure. Specify the structure name in the attributeCollection attribute and use the tag's
attribute names as structure keys.

See also

cfflush, cfheader, cfhtmlhead, cfsetting, cfsilent, Cache functions
History

ColdFusion 10: Added the attribute {{region}}ColdFusion 9:
Added support for the following features:

© 2014 Adobe Systems Incorporated. All rights reserved.

148

Adobe ColdFusion Documentation

Caching in memory. Memory is now the default cache location.
Caching page fragments.
Caching specific objects, including the ability to put, get, and flush cached objects.
Setting cache dependencies.
Setting an idle timeout.
Getting metadata about cached objects.
The ability to strip white space from cached page fragments.
The ability to throw an exception if an error occurs when flushing a cached object.
Added get and put values of the action attribute. These values support caching of objects.
Added dependsOn, id, idleTime, key, metadata, name, stripWhiteSpace, throwOnError, useCac
he, usequerystring, and value attributes.
ColdFusion MX:
Deprecated the cachedirectory and timeout attributes. They might not work, and might cause an error,
in later releases.
Added the timespan attribute.
Changed how pages are cached: the default action attribute value, cache, caches a page on the server
and the client. (In earlier releases, this option cached a page only on the server.)
Changed the source of the protocol and port values: the default protocol and port values are now
taken from the current page URL. (In earlier releases, they were "http" and "80", respectively.)
Changed how session state is handled when caching a page: this tag can cache pages that depend on
session state, including pages that are secured with a ColdFusion login. (In earlier releases, the session state
was cleared when caching the page, causing authentication to be lost.)
Changed how files are cached: this tag uses a hash() of the URL for the filename to cache a file. (In earlier
releases, ColdFusion used the cfcache.map file.)
Attributes

Attribute

Actions

© 2014 Adobe Systems Incorporated. All rights reserved.

Req/Opt

Default

Description

149

Adobe ColdFusion Documentation

action

All

Optional

dependsOn

cache, serverCac
he, optimal

Optional

directory

cache, serverCa
che, clientCach
e, optimal,
flush, put

Optional

© 2014 Adobe Systems Incorporated. All rights reserved.

serverCache

cache:
server-side and
client-side page
caching.
clientcache:
browser-side
page caching
only. To cache a
personalized
page, use this
option.
flush: remove
the current
versions of
cached pages,
fragments, or an
object from the
cache. The cache
is refreshed the
next time a user
accesses the
item. For more
information see
Description.
get: get an object
from the cache.
optimal: same
as cache.
put: Add an
object to the
cache.
serverCache:
server-side
caching only.
A comma separated
list of variables. If
any of the variable
values change,
ColdFusion updates
the cache. This
attribute can take an
expression that
returns a list of
variables.

Cache in memory

Absolute path of
cache directory.

150

Adobe ColdFusion Documentation

expireURL

flush

Optional

id

flush, get, put

See description

idleTime

cache, serverCa
che, clientCach
e, optimal,
flush, put

Optional

Flush all cached
pages

A URL reference.
Can include
wildcards, for
example: "/view.c
fm?id=".
ColdFusion flushes,
from the cache,
pages that match
the specified URL or
pattern.
The identifier for a
cached object. This
attribute can also
take a
comma-separated
list of identifiers.
This attribute is
required for the any
operation on an
object. Therefore it
is required for the g
et and put actions,
and to flush an
object. It is not
required to flush a
page.

No idle timeout

Flushes the cached
item if it is not
accessed for the
specified time span:
A decimal number
of days, for
example: ".25", for
one-fourth day (6
hours); "1", for
one day; "1.5", for
one and one half
days
A return value
from the CreateT
imeSpan function
, for example, "#C
reateTimeSpan
(0, 6, 0, 0)#".

© 2014 Adobe Systems Incorporated. All rights reserved.

151

Adobe ColdFusion Documentation

metadata

get

Optional

The name of a
structure variable in
which to put object
metadata. The get
operation returns
the following data:
timespan: The
time span during
which the cached
item is valid; the
value of the
timespan attribute
for the cached
item.
createdtime: The
time when the
cache was
created
lasthit: The time
when the cached
item was most
recently used.
hitnumber:
Number of times
the cached item
has been used.
missnumber:
Number of misses

name

get

Required

The name of the
variable in which to
put the retrieved
object.

password

cache, serverCa
che, clientCach
e, optimal,
flush

Optional

A password. Provide
this if the page
requires
authentication at the
web-server level.

© 2014 Adobe Systems Incorporated. All rights reserved.

152

Adobe ColdFusion Documentation

port

cache, serverCa
che, clientCach
e, optimal,
flush

Optional

The port for the
current page

Port number of the
web server from
which the URL for
the cached page is
requested. In the
internal call from cf
cache to cfhttp,
ColdFusion resolves
each URL variable
in the page; this
ensures that links in
the page remain
functional.

protocol

cache, serverCa
che, clientCach
e, optimal,
flush

Optional

The current page
protocol

Protocol that is used
to create URL from
cache.
http://
https://

Optional

region

Name that you
assign to a cache
region

stripWhiteSpace

cache, serverCa
che, optimal

Optional

false

Specifies whether to
strip any
unnecessary white
space characters
from a cached page
fragment. Does not
have any effect on
cached pages or
objects.

throwOnError

flush with id attrib
ute

Optional

false

A Boolean value
specifying whether
to throw an error if
the flush action
encounters an error.
Otherwise the action
does not generate
an error if it fails. If
this attribute is true
you can handle the
error in a cfcatch
block, for example, if
a specified id value
is invalid.

© 2014 Adobe Systems Incorporated. All rights reserved.

153

Adobe ColdFusion Documentation

timespan

useCache

cache, serverCa
che, clientCach
e, optimal,
flush, put

Optional

cache, serverCa
che, optimal,

Optional

© 2014 Adobe Systems Incorporated. All rights reserved.

See Description

The interval until the
item is flushed from
the cache.
A decimal number
of days, for
example: ".25", for
one-fourth day (6
hours); "1", for
one day; "1.5", for
one and one half
days
A return value
from the CreateT
imeSpan function
, for example, "#C
reateTimeSpan
(0, 6, 0, 0)#".
The default action
is to flush the item
when it is idle for
the time specified
by the idleTime
attribute, or cfca
che action = "
flush" executes.

true

Specifies whether to
use caching for a
page. This attribute
can be useful during
development. For
example, you could
use a function to
predict when to use
a cache, based on
the application state.

154

Adobe ColdFusion Documentation

Optional

usequerystring

false

If true, generates a
template cache ID
that includes the
query string. This
means that a new
template cache is
created whenever
the query string
changes.
If set to true, the
attribute dependso
n considers the URL
parameters defined
in the query string
as well to generate
template caches.
Also see the Usage
section

username

cache, serverCa
che, clientCach
e, optimal,
flush

Optional

A username.
Provide this if the
page being cached
or flushed requires
authentication at the
web server level.

value

put

Required

The object to cache.

Usage

Page fragments: To cache a page fragment, put the fragment in the body of the tag, between the begin tag and the
end tag. Do not use a tag body to cache full pages or objects.
flush: The flush action can have two formats: One uses the ExpireURL attribute to specify the page to flush, the
other uses the id attribute to specify the object to flush. When you flush an object, ColdFusion ignores errors by
default. If you specify a throwOnError attribute with a true value, the action throws the errors, and you can use a
catch block to handle them. This is useful to determine if you use invalid cache ID values.
User-defined cache: To create user-defined cache,
1. Add the following snippet to the ehcache.xml (in the _CF_root_lib):

© 2014 Adobe Systems Incorporated. All rights reserved.

155

Adobe ColdFusion Documentation



2. To reference the user-defined cache, use the key attribute as follows:


#now()#


By default, caching is memory-based and not disk-based. For each application, the default setting is 10000
object caches and 10000 template caches. It is important to note the limit imposed on the number of
objects/templates that can be cached.
Diskoverflow for caching by default is false. To enable disk caching, set overflowTodisk as true in the
ehcache.xml. To make the cached data available on server restart, set diskPersistent to true.
For further details of the properties in the ehcache.xml, refer to the documentation available at the following
URL:http://ehcache.org/
From ColdFusion 8 and earlier
The following remaining information for this tag also applied to previous releases.
Use this tag in pages whose content is not updated frequently. Taking this action can greatly improve the
performance of your application.
The output of a cached page is stored in a file on the client browser and/or the ColdFusion server. Instead of
regenerating and downloading the output of the page each time it is requested, ColdFusion uses the cached
output. ColdFusion regenerates and downloads the page only when the cache is flushed, as specified by the
timespan attribute, or by invoking cfcache action=flush.
To enable a simple form of caching, put a cfcache tag, specifying the timespan attribute, at the top of a
page. Each time the specified time span passes, ColdFusion flushes (deletes) the copy of the page from the
cache and caches a new copy for users to access.
You can specify client-side caching or a combination of client-side and server-side caching (the default),
using the action attribute. The advantage of client-side caching is that it requires no ColdFusion resources;
the browser stores pages in its own cache, improving performance. The advantage of combination caching is
that it optimizes server performance; if the browser does not have a cache of the page, the server can get
data from its own cache. (Adobe recommends that you use combination caching, and do not use server-side
only caching.)
If a page contains personalized content, use the action = "clientcache" option to avoid the possibility
of caching a personalized copy of a page for other users.
Debug settings have no effect on cfcache unless the application page enables debugging. When generating
a cached file, cfcache uses cfsetting showDebugOutput = "no".
The cfcache tag evaluates each unique URL, including URL parameters, as a distinct page, for caching
purposes. For example, the output of http://server/view.cfm?id=1 and the output of http://server/view.cfm?id=

© 2014 Adobe Systems Incorporated. All rights reserved.

156

Adobe ColdFusion Documentation

2 are cached separately.
The cfcache tag uses the cfhttp tag to get the contents of a page to cache. If there is an HTTP error
accessing the page, the contents are not cached. If a ColdFusion error occurs, the error is cached.
For more information, see Caching ColdFusion pages that change infrequently in Optimizing ColdFusion
applications in the Developing ColdFusion Applications.
Change in behaviour
Till ColdFusion 9, the request query string was automatically used as part of the page identifier, so that pages
with different query strings (URL parameters) are cached independent of each other. However, you must now
specify the new optional attribute usequerystring with value set to true, to achieve the older behavior.
Example




This is a test of some simple output

This page was generated at #now()#



The value of URL.x = # URL.x #

© 2014 Adobe Systems Incorporated. All rights reserved.

157

Adobe ColdFusion Documentation

cfcalendar
Description

Puts an interactive Flash format calendar in an HTML or Flash form. Not supported in XML format forms. The
calendar lets a user select a date for submission as a form variable.
Category

Forms tags
Syntax



Note
You can specify this tag's attributes in an attributeCollection attribute whose value is a
structure. Specify the structure name in the attributeCollection attribute and use the tag's
attribute names as structure keys.

See also

cfform, cfgrid, cfinput, cfselect, cfslider, cftextarea, cftree; About Flash form styles in the Develo
ping ColdFusion Applications.
History

ColdFusion MX 7.01: Added support for onBlur and onFocus events. ColdFusion MX 7: Added tag.
Attributes

Attribute

Req/Opt

name

Required

© 2014 Adobe Systems Incorporated. All rights reserved.

Default

Description
The name of the calendar.

158

Adobe ColdFusion Documentation

dayNames

Optional

S, M, T, W, Th, F,
S

A comma-delimited list
that sets the names of the
weekdays displayed in the
calendar. Sunday is the
first day and the rest of
the weekday names follow
in the normal order.

disabled

Optional

Not disabled

Disables all user input,
making the control
read-only. To disable
input, specify disabled
without an attribute or dis
abled="Yes" (or any
ColdFusion positive
boolean value, such as tr
ue). To enable input, omit
the attribute or specify di
sabled="No" (or any
ColdFusion negative
Boolean value, such as f
alse).

enabled

Optional

yes

Flash only: Boolean value
that specifies whether the
control is enabled. A
disabled control appears
in light gray. This is the
inverse of the disabled
attribute.

endRange

Optional

firstDayOfWeek

Optional

0

Integer in the range 0-6
specifying the first day of
the week in the calendar:
0 indicates Sunday; 6
indicates Saturday.

height

Optional

Determined by Flash

The vertical dimension of
the calendar specified in
pixels.

© 2014 Adobe Systems Incorporated. All rights reserved.

The end of a range of
dates that are disabled.
Users cannot select dates
from the date specified by
the startRange attribute
through this date.

159

Adobe ColdFusion Documentation

mask

Optional

MM/DD/YYYY

A pattern that specifies
the format of the
submitted date. Mask
characters are:
D = day; can use 0-2
mask characters
M = month; can use 0-4
mask characters
Y = year; can use 0, 2,
or 4 characters
E = day in week; can
use 0-4 characters
Any other character =
put the character in the
specified location
For more information on
masking, see "Masking
input data" in the cfin
put reference page.

monthNames

Optional

onBlur

Optional

ActionScript that runs
when the calendar loses
focus.

onChange

Optional

ActionScript that runs
when the user selects a
date.

onFocus

Optional

ActionScript that runs
when the calendar gets
focus.

selectedDate

Optional

© 2014 Adobe Systems Incorporated. All rights reserved.

January, February,
March, April, May,
June, July, August,
September, October,
November, December

None (Flash shows the
current month)

A comma-delimited list of
the month names that are
displayed at the top of the
calendar.

The date that is initially
selected. It is highlighted
in a color determined by
the form skin. Must be in
mm/dd/yyyy or
dd/mm/yyyy format,
depending on the current
locale. (Use the setloca
le function to set the
locale, if necessary.)

160

Adobe ColdFusion Documentation

startRange

Optional

The start of a range of
dates that are disabled.
Users cannot select dates
from this date through the
date specified by the end
Range attribute.

style

Optional

Flash ActionScript style or
styles to apply to the
calendar. For more
information, see Setting
styles and skins in Flash
forms in the Developing
ColdFusion Applications.

tooltip

Optional

Flash only: Text to display
when the mouse pointer
hovers over the control.

visible

Optional

yes

Flash only: Boolean value
that specifies whether to
show the control. Space
that would be occupied by
an invisible control is
blank.

width

Optional

Determined by Flash

The horizontal dimension
of the calendar specified
in pixels.

Usage

The cfcalendar tag displays a calendar month, showing the month, the year, a grid of the days of the month, and
headings for the days of the week. The calendar contains forward and back arrow buttons to let you change the
month and year that are displayed.
If you include a value for the selectedDate attribute, that date is highlighted in green and determines the month
and year that display initially. Changing the month and year display does not change the selected date. A user can
change the selected date by clicking a different date on the calendar. The onChange attribute can specify an
ActionScript event handler function that runs when the user selects a date.
The current date is highlighted in reverse (that is, a white number on a black background). If the selected date is in a
different month or year, however, the current date does not appear unless you move to it by clicking the forward or
back arrows.
The mask attribute lets you specify the format of the selected date that is returned to the application.
You can use the keyboard to access and select dates from a cfcalendar control:
Use the Up, Down, Left, and Right Arrow keys to change the selected date.
Use the Home and End keys to reach the first and last enabled date in a month, respectively.
Use the Page Up and Page Down keys to reach the previous and next month, respectively.

© 2014 Adobe Systems Incorporated. All rights reserved.

161

Adobe ColdFusion Documentation

Note
The cfcalendar tag is not supported in XML format forms.

Example

This example produces a 200-pixel by 150-pixel calendar with a Flash haloBlue skin. It displays abbreviated month
names and two-character days of the week. It initially displays today's date as determined by the selectedDate att
ribute. When you click the Save button, the form submits back to the current page, which displays the submitted
information.
The example also has three dateField controls that let the user change the initial selected date that displays on
the calendar and a blocked-out date range. The initial blocked-out date is a four-day period immediately preceding
today's date.
Note
This example must be modified to work in locales that do not use mm/dd/yyyy date formats. To
do so, use the LSDateFormat function in place of the DateFormat function and a mask that is
appropriate for your locale, such as dd/mm/yyyy.







You selected #Form.selectedDate#



Please select a date on the calendar and click Save.











© 2014 Adobe Systems Incorporated. All rights reserved.

162

Adobe ColdFusion Documentation

cfcase
Description

Used only inside the cfswitch tag body. Contains code to execute when the expression specified in the cfswitc
h tag has one or more specific values.
Category

Flow-control tags
Syntax



See also

cfdefaultcase, cfswitch; cfswitch, cfcase, and cfdefaultcase in the Developing ColdFusion Applications
History

ColdFusion 8: Changed the way ColdFusion parses cfcase values. Previously, cfcase tags with numeric value
dates did not return expected results. For example, \ and \

You can use the delimiter attribute to specify one or more delimiters to use in place of the comma. For example,
the following line matches "cargo, live", "cargo, liquid", and "cargo, solid":



Example

The following example displays a grade based on a 1-10 score. Several of the cfcase tags match more than one
score. For simplicity, the example sets the score to 7.

© 2014 Adobe Systems Incorporated. All rights reserved.

164

Adobe ColdFusion Documentation




















Your grade is #grade#


© 2014 Adobe Systems Incorporated. All rights reserved.

165

Adobe ColdFusion Documentation

cfcatch
Description

Used inside a cftry tag. Together, they catch and process exceptions in ColdFusion pages. Exceptions are events
that disrupt the normal flow of instructions in a ColdFusion page, such as failed database operations, missing
include files, and developer-specified events.
Category

Exception handling tags
Syntax


Exception processing code here 

See also

cftry, cferror, cffinally, cfrethrow, cfthrow, onError; Handling Errors in the Developing
ColdFusion Applications
History

ColdFusion 10: Added the sessionCookie and authCookie attributes.ColdFusion MX:
Changed SQLSTATE value behavior: the SQLSTATE return value in a cfcatchtag depends on the
database driver type:
Type 1 (JDBC-ODBC bridge): the value is the same as in ColdFusion 5.
Type 4 (100% Java, no native methods): the value might be different.
If your application depends on SQLSTATE values for flow control, the application might produce
unexpected behavior with ColdFusion MX.
Changed the behavior of this tag when type="any": it is not necessary, when you include a cfcatch tag
with type="any", to do so in the last cfcatch tag in the block, to ensure that all other tests are executed
before it. ColdFusion finds the best-match cfcatch block.
Changed the behavior of the cfscript tag: it includes try and catch statements that are equivalent to the
cftry and cfcatch tags.
Changed object modification: you cannot modify the object returned by cfcatch.
Changed thrown exceptions: the cfcollection, cfindex, and cfsearch tags can throw the
SEARCHENGINE exception. In earlier releases, an error in processing these tags threw only an UNKNOWN
exception.
Attributes

Attribute

Req/Opt

name

Optional

© 2014 Adobe Systems Incorporated. All rights reserved.

Default

Description
Variable name for cfcat
ch expression.

166

Adobe ColdFusion Documentation

Optional

type

Any

application: catches
application exceptions
database: catches
database exceptions
template: catches
ColdFusion page
exceptions
security: catches
security exceptions
object: catches object
exceptions
missingInclude:
catches missing include
file exceptions
expression: catches
expression exceptions
lock: catches lock
exceptions
custom_type: catches
the specified custom
exception type that is
defined in a cfthrow t
ag
searchengine:
catches Solr search
engine exceptions
any: catches all
exception types

Usage

You must code at least one cfcatch tag within a cftry block. Put cfcatch tags at the end of a cftry block.
ColdFusion tests cfcatch tags in the order in which they appear. This tag requires an end tag.
If type="any", ColdFusion catches exceptions from any CFML tag, data source, or external object. To get the
exception type use code such as the following:

#cfcatch.type#

Applications can use the cfthrow tag to throw developer-defined exceptions. Catch these exceptions with any of
these type options:
"custom_type"
"Application"
"Any"
The custom_type type is a developer-defined type specified in a cfthrow tag. If you define a custom type as
a series of strings concatenated by periods (for example, "MyApp.BusinessRuleException.InvalidAc
count"), ColdFusion can catch the custom type by its character pattern. ColdFusion searches for a cfcatc
h tag in the cftryblock with a matching exception type, starting with the most specific (the entire string), and
ending with the least specific. For example, you could define a type as follows:

© 2014 Adobe Systems Incorporated. All rights reserved.

167

Adobe ColdFusion Documentation



If you have the following cfcatchtag, it handles the exception:



Otherwise, if you have the following cfcatchtag, it handles the exception:



Finally, if you have the following cfcatchtag, it handles the exception:



You can code cfcatch tags in any order to catch a custom exception type.
If you specify type = "Application", the cfcatch tag catches only custom exceptions that have the Ap
plication type in the cfthrow tag that defines them.
The cfinclude, cfmodule, and cferror tags throw an exception of type = "template".
An exception that is thrown within a cfcatch block cannot be handled by the cftry block that immediately
encloses the cfcatch tag. However, you can rethrow the currently active exception with the cfrethrow tag.
The cfcatch variables provide the following exception information:
cfcatch variable

Content

cfcatch.type

Type: Exception type, as specified in cfcatch.

cfcatch.message

Message: Exception's diagnostic message, if provided;
otherwise, an empty string; in the cfcatch.message
variable.

cfcatch.detail

Detailed message from the CFML interpreter or
specified in a cfthrow tag. When the exception is
generated by ColdFusion (and not cfthrow), the
message can contain HTML formatting and can help
determine which tag threw the exception.

cfcatch.tagcontext

An array of tag context structures, each representing
one level of the active tag context at the time of the
exception.

© 2014 Adobe Systems Incorporated. All rights reserved.

168

Adobe ColdFusion Documentation

cfcatch.NativeErrorCode

Applies to type = "database". Native error code
associated with exception. Database drivers typically
provide error codes to diagnose failing database
operations. Default value is -1.

cfcatch.SQLState

Applies to type = "database". SQLState associated
with exception. Database drivers typically provide error
codes to help diagnose failing database operations.
Default value is 1.

cfcatch.Sql

Applies to type = "database". The SQL statement
sent to the data source.

cfcatch.queryError

Applies to type ="database". The error message as
reported by the database driver.

cfcatch.where

Applies to type= "database". If the query uses the c
fqueryparam tag, query parameter name-value pairs.

cfcatch.ErrNumber

Applies to type = "expression". Internal expression
error number.

cfcatch.MissingFileName

Applies to type = "missingInclude". Name of file
that could not be included.

cfcatch.LockName

Applies to type = "lock". Name of affected lock (if
the lock is unnamed, the value is "anonymous").

cfcatch.LockOperation

Applies to type = "lock". Operation that failed
(Timeout, Create Mutex, or Unknown).

cfcatch.ErrorCode

Applies to type = "custom". String error code.

cfcatch.ExtendedInfo

Applies to type = "application" and "custom".
Custom error message; information that the default
exception handler does not display.

Example

© 2014 Adobe Systems Incorporated. All rights reserved.

169

Adobe ColdFusion Documentation


cftry Example




SELECT *
FROM employees





You've Thrown a Database Error


#cfcatch.message#
Caught an exception, type = #CFCATCH.TYPE#
The contents of the tag stack are:





© 2014 Adobe Systems Incorporated. All rights reserved.

170

Adobe ColdFusion Documentation

cfchart
Description
Generates and displays a chart.
Category

Data output tags, Extensibility tags
Syntax




OR



© 2014 Adobe Systems Incorporated. All rights reserved.

172

Adobe ColdFusion Documentation

zoom = "JSON string representation"


Note
You can specify this tag's attributes in an attributeCollection attribute whose value is a
structure. Specify the structure name in the attributeCollection attribute and use the tag's
attribute names as structure keys.

See also

cfchartdata, cfchartseries, cfdocument, Controlling chart appearance in the Developing ColdFusion
Applications
History

ColdFusion 11:
The server-side charting introduced in ColdFusion 10 that allowed you to create highly interactive charts has been
further enhanced to produce visually more appealing charts.
Note that the new look and feel will not be available for the following tag attributes:
cfchart
labelFormat
seriesPlacement with percent as the value
sortXAxis
tipStlye
xAxisType
yAxisType
xOffset
yOffset

cfchartseries
markerStyle: letterx, mcross, snow, and rcross.
paintStyle

ColdFusion provides a utility to convert XML styles (used by the old charting system) to JSON styles (used by the
new charting system).
To perform this conversion, you need to use cfchart_xmltojson.bat (or cfchart_xmltojson.sh) available in
/bin folder:

cfchart_xmltojson.bat 

The converted JSON style will be created in the same location as the XML file.

© 2014 Adobe Systems Incorporated. All rights reserved.

173

Adobe ColdFusion Documentation

Also, in ColdFusion 11, the XML format style has been removed.

ColdFusion 10: Added the following new attributes: alpha, arrows, aspect3D, background, bevel,
border, crosshair, fill, format, height, ID, labels, legend, plot, plotarea, preview,
refresh, renderer, scales, type, tooltip, width, xaxis, axis2, xaxisvalues, yaxis,
yaxis2, yaxisvalues, zoom
ColdFusion 8:
Added the new attribute showLegend to the chart style files, which are the XML files located in the
charting\styles directory- This attribute displays an entry for each point and is applicable only to charts that
contain a single series. By default, the value of showLegend is set to true. To turn off this feature, you can
either modify the setting in all the chart style files, or use a custom style file.
ColdFusion MX 7.01: Changed documentation to state that the fontSize attribute can accept a number that is not
an integer.
ColdFusion MX 7:
Added style and title attributes.
Added support for eight-digit hexadecimal values to specify RGB color and transparency.
Removed the rotated attribute.
ColdFusion MX 6.1:
Added the xAxisType and yAxisType attributes.
Changed interpolation behavior: the tag now interpolates data points on line charts with multiple series.
ColdFusion MX: Added this tag.
Attributes

Attribute

Req/Opt

Default

alpha

Optional

Alpha (transparency) level
of the background. Valid
values range from 0
(transparent) to 1
(opaque).

arrows

Opt

© 2014 Adobe Systems Incorporated. All rights reserved.

Description

Creates an arrow for
pointing out data or other
chart items.JSON string
representation of array of
structs that contain values
such as to, from, size,
and label.

174

Adobe ColdFusion Documentation

aspect3D

Opt

JSON string
representation of struct
that defines the angle of
3D aspect. The valid
struct keys are angle and
depth.

background

Opt

A struct of keys related to
background such as
color: Sets the
background color(s)
color-1: Sets the first
background color for
the arrow
color-2: Sets the
second background
color for the arrow
(used with gradients)
transparent: Set the
transparency of a
background image so
that underlying colors or
chart can show.
fit: Defines the
width/height to fit area
of background.
repeat: Defines type
of image repeat.
image: Defines the
path to the background
image.
position: Defines the
position of the
background image.

backgroundColor

Optional

© 2014 Adobe Systems Incorporated. All rights reserved.

Color of the area between
the data background and
the chart border, around
labels and around the
legend. Hexadecimal
value or supported named
color; see the name list in
Usage. For a hexadecimal
value, use the form "##x
xxxxx" or "##xxxxxxxx
", where x = 0-9 or A-F;
use two number signs or
none.

175

Adobe ColdFusion Documentation

bevel

Opt

A struct of keys related to
bevel such as.
color: Defines the
color of the bevel.
blur-x: Defines the
sharpness/smoothness
of the bevel edges in
the x-direction.
blur-y: Defines the
sharpness/smoothness
of the bevel edges in
the y-direction.
angle: Defines the
angle of the bevel.
distance: Distance in
# | #px indicating the
distance from the object
the bevel should be
displayed.

border

Opt

A struct of keys related to
border such as:
color: Sets the color
of the border.
radius: Defines the
radius of rounded
corners.
width: Defines the
width of the border.

chartHeight

Optional

240

Chart height; integer
number of pixels.

chartWidth

Optional

320

Chart width; integer
number of pixels.

crosshair

Opt

A struct of keys related to
crosshair such as:
line-color: Sets the
color of the crosshair
lines.
alpha: Defines the
alpha transparency
level of the line.
line-style: Defines
the line style.

© 2014 Adobe Systems Incorporated. All rights reserved.

176

Adobe ColdFusion Documentation

dataBackgroundColor

Optional

fill

Opt

white

Color of area around chart
data.Hexadecimal value
or supported named color;
see the name list in the
Usage section.
For a hexadecimal value,
use the form "##xxxxxx
" or "##xxxxxxxx",
where x = 0-9 or A-F; use
two number signs or
none.
A struct of keys related to
fill such as:
angle: Sets the angle
at which a linear fill is
displayed. A fill angle of
zero displays a vertical
gradient from top
(background-color-1) to
bottom
(background-color-2).
offset-x: Set x-axis
offset for background
gradient.
offset-y: Set y-axis
offset for background
gradient..

format

Req

flash

Format of the chart to be
rendered. The supported
formats are html, flash,
jpg, and png.

font

Optional

arial

Name of text font:
arial
times
courier
arialunicodeMS.
This option is required,
if you are using a
double-byte character
set on UNIX, or using a
double-byte character
set in Windows with a
file type of Flash.

© 2014 Adobe Systems Incorporated. All rights reserved.

177

Adobe ColdFusion Documentation

fontBold

Optional

no

Whether to make the text
bold:
yes
no

fontItalic

Optional

no

Whether to make the text
italicized:
yes
no

fontSize

Optional

11

Font size. If the number is
not an integer, ColdFusion
rounds the number up to
the next integer.

foregroundColor

Optional

black

Color of text, grid lines,
and labels.Hexadecimal
value or supported named
color; see name list in the
Usage section.
For a hexadecimal value,
use the form "##xxxxxx
" or "##xxxxxxxx",
where x = 0-9 or A-F; use
two number signs or
none.

format

Optional

flash

File format in which to
save the graph:
flash
jpg
png

gridlines

Optional

height

Opt

Chart height; integer;
number of pixels.

ID

Opt

ID of the chart. Used to
get the underlying
chartobject.

© 2014 Adobe Systems Incorporated. All rights reserved.

10, including top and
bottom

Number of grid lines to
display on the value axis,
including axis; positive
integer.

178

Adobe ColdFusion Documentation

labels

Opt

labelFormat

Optional

An array of structs used to
display custom text or
images on the chart, for
example author or chart
information.
number

Format for y-axis labels:
number
currency
percent
date

legend

Opt

markerSize

Optional

name

Optional

pieSliceStyle

Optional

A struct used to define the
legend attributes, for
example,
background-color or
margin-top.
(Automatic)

Size of data point marker
in pixels; integer.
Page variable name;
string. Generates the
graph as binary data and
assigns it to the specified
variable. Suppresses
chart display. You can use
the name value in the cff
ile tag to write the chart
to a file.

sliced

Applies to the cfcharts
eries type attribute
value pie.
solid: displays pie as
if unsliced.
sliced: displays pie as
if sliced.

plot

Opt

A struct of keys such as a
nimation, aspect, mar
gin, and marker used to
style the plotting.

plotarea

Opt

A struct of keys such as p
osition and margin us
ed to style the plotarea.

© 2014 Adobe Systems Incorporated. All rights reserved.

179

Adobe ColdFusion Documentation

preview

Opt

A struct of keys such as v
isible and margin to
control chart preview.

refresh

Opt

A struct of keys such as t
ype, url, and interva
l to create dynamic
charts.

renderer

Opt

Specify the rendering
method. You must remove
the format=”html” setting
and then set the renderer
to “flash”. The supported
values are flash, svg, and
vml.

scaleFrom

Optional

scales

Opt

scaleTo

Optional

Determined by data

Y-axis maximum value;
integer.

seriesPlacement

Optional

default

Relative positions of
series in charts that have
more than one data
series.

Determined by data

Y-axis minimum value;
integer.
Comma-separated list of
axis against which to plot
the chart, for example, x,
y2.

default: ColdFusion
determines relative
positions, based on
graph types
cluster
stacked
percent
show3D

Optional

yes

Whether to display the
chart with
three-dimensional
appearance:
yes
no

© 2014 Adobe Systems Incorporated. All rights reserved.

180

Adobe ColdFusion Documentation

showBorder

Optional

no

Whether to display a
border around the chart:
yes
no

showLegend

Optional

yes

Whether to display the
legend if the chart
contains more than one
data series:
yes
no

showMarkers

Optional

yes

Whether to display
markers at data points in
line, curve, and scatter
graphs:
yes
no

showXGridlines

Optional

no

Whether to display x-axis
gridlines:
yes
no

showYGridlines

Optional

yes

Whether to display y-axis
gridlines:
yes
no

sortXAxis

Optional

no

Whether to display
column labels in
alphabetic order along the
x axis:
yes
no
Ignored if the xAxisTy
pe attribute is scale.

style

Optional

XML file or string to use to
specify the style of the
chart. In ColdFusion 11,
the XML format style has
been removed.

title

Optional

Title of the chart.

© 2014 Adobe Systems Incorporated. All rights reserved.

181

Adobe ColdFusion Documentation

tipbgcolor

Optional

white

Background color of tips.
Applies only to Flash
format graph files.
Hexadecimal value or
supported named color;
see the name list in the
Usage section.
For a hexadecimal value,
use the form "##xxxxxx
", where x = 0-9 or A-F;
use two number signs or
none.

tipStyle

Optional

mouseOver

Determines the action that
opens a pop-up window to
display information about
the current chart element.
mouseDown: display if
the user positions the
cursor at the element
and clicks the mouse.
Applies only to Flash
format graph files. (For
other formats, this
option functions the
same as mouseOver.)
mouseOver: displays if
the user positions the
cursor at the element.
none: suppresses
display.

tooltip

Optional

A struct of keys used to
style the tool tip such as b
ackground, font, or bo
rder.

type

Optional

Type of chart.

© 2014 Adobe Systems Incorporated. All rights reserved.

182

Adobe ColdFusion Documentation

url

Optional

URL to open if the user
clicks item in a data
series; the onClick desti
nation page.
You can specify variables
within the URL string;
ColdFusion passes
current values of the
variables.
$VALUE$: the value of
the selected row. If
none, the value is an
empty string.
$ITEMLABEL$: the
label of the selected
item. If none, the value
is an empty string.
$SERIESLABEL$: the
label of the selected
series. If none, the
value is an empty
string, for example: "so
mepage.cfm?item=$
ITEMLABEL$&series
=$SERIESLABEL$&va
lue=$VALUE$
"javascript:...":
executes a client-side
script.

width

Optional

xAxis

Optional

A struct of keys used to
style x axis such as form
at, guide, item, and la
bel.

xAxis2

Optional

A struct of keys used to
style second x axis such
as format, guide, item,
and label, which is on
the top of the chart.

xAxisTitle

Optional

Title that appears on the x
axis; text.

© 2014 Adobe Systems Incorporated. All rights reserved.

320

Width of the Chart in
pixels.

183

Adobe ColdFusion Documentation

xAxisType

Optional

category

Whether the x axis
indicates data or is
numeric:
category: The axis
indicates the data
category. Data is sorted
according to the sortX
Axis attribute.
scale: The axis is
numeric. All cfchartd
ata item attribute
values must be
numeric. The x axis is
automatically sorted
numerically.

xAxisvalues

Opt

xOffset

Optional

yaxis

Opt

A struct of keys used to
style y axis such as form
at, guide, item, and la
bel.

yaxis2

Opt

A struct of keys used to
style second y axis such
as format, guide, item,
and label, which is on
the top of the chart.

yAxisTitle

Optional

Title of the y axis; text.

yAxisType

Optional

yaxisvalues

Opt

© 2014 Adobe Systems Incorporated. All rights reserved.

An array of values to be
displayed on x axis.
0.1

category

Number of units by which
to display the chart as
angled, horizontally.
Applies if show3D="yes"
. The number can be
between 1 and 1, where
"-1" specifies 90 degrees
left and "1" specifies 90
degrees right.

Currently has no effect, as
the y axis is always used
for data values.
An array of values to be
displayed on y axis.

184

Adobe ColdFusion Documentation

yOffset

Optional

zoom

Opt

0.1

Number of units by which
to display the chart as
angled, vertically. Applies
if show3D="yes". The
number can be between 1
and 1, where "-1"
specifies 90 degrees left
and "1" specifies 90
degrees right.
A struct of keys to be
applied when you zoom
the chart such as alpha,
background, or bevel.

Usage

The cfchart tag defines a container in which a graph displays: its height, width, background color, labels, and so
on. The cfchartseries tag defines the chart style in which data displays: bar, line, pie, and so on. The cfchartd
ata tag defines a data point.Data is passed to the cfchartseries tag in the following ways:
As a query
As data points, using the cfchartdata tag
For the font attribute value ArialUnicodeMS, the following rules apply:
In Windows, to permit Flash charts (type = "flash") to render a double-byte character set, select this
value.
In UNIX, for all type values, to render a double-byte character set, select this value.
If this value is selected, the fontBold and fontItalic attributes have no effect.
The following table lists W3C HTML 4 named color value or hexadecimal values that the color attribute
accepts:
Color name

RGB value

Aqua

##00FFFF

Black

#000000

Blue

##0000FF

Fuchsia

##FF00FF

Gray

##808080

Green

##008000

Lime

##00FF00

Maroon

##800000

© 2014 Adobe Systems Incorporated. All rights reserved.

185

Adobe ColdFusion Documentation

Navy

##000080

Olive

##808000

Purple

##800080

Red

##FF0000

Silver

##C0C0C0

Teal

##008080

White

##FFFFFF

Yellow

##FFFF00

For all other color values, enter the hexadecimal value. You can enter a six-digit value, which specifies the RGB
value, or an eight-digit value, which specifies the RGB value and the transparency. The first two digits of an
eight-digit hexadecimal value specify the degree of transparency, with FF indicating opaque and 00 indicating
transparent. Values between 00 and FF are allowed.
For more color names that are supported by popular browsers, go to www.w3.org/TR/css3-color. You can specify
whether charts are cached in memory, the number of charts to cache, and the number of chart requests that
ColdFusion can process concurrently. To set these options in the ColdFusion Administrator, select Server
Settings>Charting.
For client-side charting, the following attributes are not supported: format, labelformat, seriesplacement wit
h percent as the value, sort, xaxis, tipsstlye, url, xAxisTYpe, xoffset, yaxistype, and yoffset.
Example

© 2014 Adobe Systems Incorporated. All rights reserved.

186

Adobe ColdFusion Documentation




SELECT Departmt.Dept_Name,
Employee.Dept_ID,
Employee.Salary
FROM Departmt, Employee
WHERE Departmt.Dept_ID = Employee.Dept_ID






SELECT Dept_Name,
AVG(Salary) AS avgSal,
SUM(Salary) AS sumSal
FROM GetSalaries
GROUP BY Dept_Name






Employee Salary Analysis







© 2014 Adobe Systems Incorporated. All rights reserved.

187

Adobe ColdFusion Documentation

cfchartdata
Description

Used with the cfchart and cfchartseries tags. This tag defines chart data points. Its data is submitted to the c
fchartseries tag.
Category

Data output tags, Extensibility tags
Syntax



Note
You can specify this tag's attributes in an attributeCollection attribute whose value is a
structure. Specify the structure name in the attributeCollection attribute and use the tag's
attribute names as structure keys.

See also

cfchart, cfchartseries; Creating Charts and Graphs in the _Developing ColdFusion
Applications_ColdFusion MX: Added this tag.
Attributes

Attribute

Req/Opt

Default

Description

item

Required

Data point name; string.

value

Required

Data point value; number
or expression.

Example

© 2014 Adobe Systems Incorporated. All rights reserved.

188

Adobe ColdFusion Documentation




SELECT Departmt.Dept_Name,
Employee.Dept_ID,
Employee.Salary
FROM Departmt, Employee
WHERE Departmt.Dept_ID = Employee.Dept_ID






SELECT Dept_Name,
AVG(Salary) AS avgSal,
SUM(Salary) AS sumSal
FROM GetSalaries
GROUP BY Dept_Name






Employee Salary Analysis









© 2014 Adobe Systems Incorporated. All rights reserved.

189

Adobe ColdFusion Documentation

cfchartseries
Description

Used with the cfchart tag. This tag defines the chart style in which the data displays: bar, line, pie, and so on.
Category

Data output tags, Extensibility tags
Syntax


toolTip = "JSON string representation"
zColumn = "query column"
type="type"
itemColumn="query column"
valueColumn="query column"
colorlist = "list"
dataLabelStyle="style"
markerStyle="style"
paintStyle="plain|raise|shade|light"
query="query name"
seriesColor="hexadecimal value|web color"
seriesLabel="label text">


Note
You can specify this tag's attributes in an attributeCollection attribute whose value is a
structure. Specify the structure name in the attributeCollection attribute and use the tag's
attribute names as structure keys.

© 2014 Adobe Systems Incorporated. All rights reserved.

190

Adobe ColdFusion Documentation

See also

cfchart, cfchartdata; Creating Charts and Graphs in the Developing ColdFusion Applications
History

ColdFusion 10: Added the following attributes: {{alpha, animate, aspect, background, bevel, border, marker, color,
label, hoverMarker, data, scales, shadow, tooltip, zcolumn}}ColdFusion MX 7:
Added the dataLabelStyle attribute.
Added the horizontalbar value of the type attribute.
ColdFusion MX 6.1: Changed interpolation behavior: the tag now interpolates data points on line charts with
multiple series.ColdFusion MX: Added this tag.
Attributes

Attribute

Req/Opt

alpha

Optional

Alpha (transparency) level
of the background.Valid
values range from 0 (tra
nsparent) to 1 (opaque)
.

animate

Opt

A struct of keys to define
the animation such as
effect and speed. An
empty struct results in
default animation with ap
pear effect.

aspect

Opt

Defines the variations of a
chart type, for example li
ne, area, and dots in a
radar chart.

© 2014 Adobe Systems Incorporated. All rights reserved.

Default

Description

191

Adobe ColdFusion Documentation

background

Opt

A struct of keys related to
background such as
color: Sets the
background color(s)
color-1: Sets the first
background color for
the arrow
color-2: Sets the
second background
color for the arrow
(used with gradients)
transparent: Set the
transparency of a
background image so
that underlying colors or
chart can show.
fit: Defines the
width/height to fit area
of background.
repeat: Defines type
of image repeat.
image: Defines the
path to the background
image.
position: Defines the
position of the
background image.

bevel

Opt

A struct of keys related to
bevel such as:
color: Defines the
color of the bevel.
blur-x: Defines the
sharpness/smoothness
of the bevel edges in
the x-direction.
blur-y: Defines the
sharpness/smoothness
of the bevel edges in
the y-direction.
angle: Defines the
angle of the bevel.
distance: Distance in
# | #px indicating the
distance from the object
the bevel should be
displayed.

© 2014 Adobe Systems Incorporated. All rights reserved.

192

Adobe ColdFusion Documentation

border

Opt

A struct of keys related to
border such as:
color: Sets the color
of the border.
radius: Defines the
radius of rounded
corners.
width: Defines the
width of the border.

marker

Opt

A struct of keys used to
style the marker such as s
ize, border, backgrou
nd, and bevel.

color

Opt

Color of the main element
(such as the bars) of a
chart.
For a pie chart, this is the
color of the first
slice.Hexadecimal value
or supported named color;
see the name list and
information about six- and
eight-digit hexadecimal
values in the Usage
section for the cfchart tag.
For a hexadecimal value,
use the form "##xxxxxx
" or "##xxxxxxxx",
where x = 0-9 or A-F;
use two number signs or
none.

label

Opt

Text of the data series
label.

hoverMarker

Opt

A struct of keys used to
style the marker on
mouse hover such as siz
e, border, background
, and bevel.

© 2014 Adobe Systems Incorporated. All rights reserved.

193

Adobe ColdFusion Documentation

data

Opt

The chart data. This is an
array of arrays.Specify the
data as follows: [ ["a",3],
["b",5]] or [["a",4,5
],["b",7,3]] for charts
with z parameter such as
bubble chart.

scales

Opt

Comma-separated list of
axis against which to plot
the series, for example,
x,y2.

shadow

Opt

tooltip

Opt

A struct of keys used to
style the tool tip such as b
ackground, font, or bo
rder.

zcolumn

Opt

The value of the
dimension. Applicable if
the chart takes a third
dimension in addition to x
and y.

type

Required

Sets the chart display
style:

false

Used to enable/disable
the shadow. The value
can either be yes|no or a
struct that takes the key
alpha.

bar
line
pyramid
area
horizontalbar
cone
curve
cylinder
step
scatter
pie
itemColumn

Required if query attribut
e is specified

© 2014 Adobe Systems Incorporated. All rights reserved.

Name of a column in the
query specified in the que
ry attribute; contains the
item label for a data point
to graph.

194

Adobe ColdFusion Documentation

valueColumn

Required if query attribut
e is specified

Name of a column in the
query specified in the que
ry attribute; contains data
values to graph.

colorlist

Optional

Sets colors for each data
point. Applies if the cfcha
rtseries type attribute
is pie, pyramid, area, h
orizontalbar, cone, c
ylinder, or step.
Comma-delimited list of
hexadecimal values or
supported, named web
colors; see the name list
and information about sixand eight-digit
hexadecimal values in the
cfchart Usage section.
For a hexadecimal value,
use the form "##xxxxxx
" or "##xxxxxxxx",
where x = 0-9 or A-F; use
two number signs or
none.

dataLabelStyle

Optional

none

Specifies the way in which
the color is applied to the
item in the series:
none: nothing is
printed.
value: the value of the
datapoint.
rowLabel: the row's
label.
columnLabel: the
column's label.
pattern: combination
of column label, value,
and aggregate
information, such as the
columnLabel value for
the percentage of total
graph, for example,
Sales 55,000 20% of
277,000.

© 2014 Adobe Systems Incorporated. All rights reserved.

195

Adobe ColdFusion Documentation

markerStyle

Optional

rectangle

Sets the icon that marks a
data point for
two-dimensional line,
curve, and scatter graphs:
rectangle
triangle
diamond
circle
letter
mcross
snow
rcross

paintStyle

Optional

plain

Sets the paint display
style of the data series:
plain: solid color.
raise: the appearance
of a button.
shade: gradient fill,
darker at the edges.
light: a lighter shade
of color; gradient fill.

query

Optional

Name of the ColdFusion
query from which to get
data to graph.

seriesColor

Optional

Color of the main element
(such as the bars) of a
chart. For a pie chart, the
color of the first
slice.Hexadecimal value
or supported named color;
see the name list and
information about six- and
eight-digit hexadecimal
values in the Usage
section for the cfchart t
ag.
For a hexadecimal value,
use the form "##xxxxxx
" or "##xxxxxxxx",
where x = 0-9 or A-F; use
two number signs or
none.

seriesLabel

Optional

Text of the data series
label

Usage

© 2014 Adobe Systems Incorporated. All rights reserved.

196

Adobe ColdFusion Documentation

The following attributes are not supported for Client side charting:paintStyle and the following values for marker
style: letterx, mcross, snow, and rcross.A new attribute zvalue added to cfchartdata: Applicable if chart
takes a third dimension in addition to x and y.
For a pie chart, ColdFusion sets pie slice colors as follows:
If the seriesColor attribute is omitted, ColdFusion automatically determines the colors of the slices.
If the seriesColor attribute is specified, ColdFusion automatically determines the colors of the slices after
the first one, starting with the specified color for the first slice.
Limitations

The following server-side charting features are not available with client-side charting:
Linking charts to URL
Writing charts to a variable
Example 1

© 2014 Adobe Systems Incorporated. All rights reserved.

197

Adobe ColdFusion Documentation




SELECT Departmt.Dept_Name,
Employee.Dept_ID,
Employee.Salary
FROM Departmt, Employee
WHERE Departmt.Dept_ID = Employee.Dept_ID






SELECT
Dept_Name,
AVG(Salary) AS avgSal,
SUM(Salary) AS sumSal
FROM GetSalaries
GROUP BY Dept_Name






Employee Salary Analysis





Example 2

The following is a basic example of using client side charting.

© 2014 Adobe Systems Incorporated. All rights reserved.

198

Adobe ColdFusion Documentation










Example 3

This example showcases how you can create a simple bubble chart by specifying zcolumn.





Example 4

This is an example that specifies labels as a struct.











© 2014 Adobe Systems Incorporated. All rights reserved.

199

Adobe ColdFusion Documentation

cfcol
Description

Defines table column header, width, alignment, and text. Used within a cftable tag.
Category

Data output tags
Syntax



Note
You can specify this tag's attributes in an attributeCollection attribute whose value is a
structure. Specify the structure name in the attributeCollection attribute and use the tag's
attribute names as structure keys.

See also

cfcontent, cfoutput, cftable; Performing file operations with cfftp in the Developing
ColdFusion Applications
History

ColdFusion MX: Added the ability to construct dynamic cfcol statements.
Attributes

Attribute

Req/Opt

header

Required

Column header text. To
use this attribute, you
must also use the cftabl
e colHeaders attribute.

text

Required

Double-quotation
mark-delimited text;
determines what to
display. Rules: same as
for cfoutput sections.
You can embed
hyperlinks, image
references, and input
controls.

© 2014 Adobe Systems Incorporated. All rights reserved.

Default

Description

200

Adobe ColdFusion Documentation

align

Optional

left

Column alignment:
left
right
center

width

Optional

20

Column width. If the
length of data displayed
exceeds this value, data is
truncated to fit. To avoid
this, use an HTML table
tag.
If the surrounding cftabl
e tag includes the htmlt
able attribute, width spe
cifies the percent of the
table width and it does not
truncate text; otherwise, w
idth specifies the
number of characters.

Usage

At least one cfcol tag is required within the cftable tag. You must put cfcol and cftable tags adjacent in a
page. The only tag that you can nest within the cftable tag is the cfcol tag. You cannot nest cftable tags.
To display the cfcol header text, specify the cfcol header and the cftable colHeader attribute. If you
specify either attribute without the other, the header does not display. No error is thrown.
Example

© 2014 Adobe Systems Incorporated. All rights reserved.

201

Adobe ColdFusion Documentation




SELECT Emp_ID, FirstName, LastName, EMail, Phone, Department
FROM Employees



cfcol Example








© 2014 Adobe Systems Incorporated. All rights reserved.

202

Adobe ColdFusion Documentation

cfcollection
Description

Creates and administers Solr search engine collections.
Category

Extensibility tags
Syntax

cfcollection supports script style syntax:
new collection().CREATE(collection="", engine="solr", path="");



Note
You can specify this tag's attributes in an attributeCollection attribute whose value is a
structure. Specify the structure name in the attributeCollection attribute and use the tag's
attribute names as structure keys.

See also

cfexecute, cfindex, cfobject, cfreport, cfsearch, cfwddx
History

ColdFusion 9: Added the engine attribute (required for Solr support).ColdFusion MX 7:
Starting with ColdFusion MX 7, you cannot use the cfcollection tag to create alias names for existing
collections. Because Verity maintains all the collection information, you cannot have two names point to the
same collection.
Removed reference to external collections.
Deprecated the map and repair options of the action attribute. They might not work, and might cause an
error, in later releases.
Added categories attribute and categorylist action.
Added CATEGORIES, SIZE, DOCCOUNT, and LASTMODIFIED to list of variables returned by the list acti
on.
Marked as obsolete the MAPPED, ONLINE, and REGISTERED variables returned by the list action.
ColdFusion MX:
Changed the requirements for the action attribute: it is now required.

© 2014 Adobe Systems Incorporated. All rights reserved.

203

Adobe ColdFusion Documentation

Added the action attribute list value. It is the default.
Changed the requirements for the action attribute value map: it is not necessary to specify the action attri
bute value map. (ColdFusion detects collections and creates maps collections as required.)
Changed acceptable collection naming: this tag accepts collection names that include spaces.
Changed Verity operations behavior: ColdFusion supports Verity operations on Acrobat PDF files.
Changed thrown exceptions: this tag can throw the SEARCHENGINE exception.
Attributes

Attribute

Req/Opt

Default

action

Required; see Usage

list

© 2014 Adobe Systems Incorporated. All rights reserved.

Description
categorylist:
Retrieves categories
from the collection and
indicates how many
documents are in each
one. Returns a structure
of structures in which
the category
representing each
substructure is
associated with a
number of documents.
For a category in a
category tree, the
number of documents is
the number at or below
that level in the tree.
create: registers the
collection with
ColdFusion. If the
collection is present, the
tag creates a map to it.
If the collection is not
present, the tag creates
it.
delete: unregisters a
collection and deletes
its directories.
list: returns a query
result set, named from
the name attribute
value, of the attributes
of the collections that
are registered by
ColdFusion. If you have
Solr collections and
omit the engine attribu
te, ColdFusion lists
information for both
types of collections.

204

Adobe ColdFusion Documentation

map: creates a map to a
collection. If the action
is create and the
collection exists,
ColdFusion also creates
a map to the collection.
optimize: optimizes
the structure and
contents of the
collection for searching;
recovers space. Causes
collection to be taken
offline, preventing
searches and indexing.
repair: deprecated.
Does nothing.
categories

See Usage

no

Used only for creating a
collection:
yes: this collection
includes support for
categories.
no: this collection does
not support categories.

collection

See Usage

engine

Optional

A collection name. The
name can include
spaces.
Solr

The search engine for the
collection:
solr: the Apache
Lucene open source
search engine
For the create and ma
p actions, the default is
Solr. For the list acti
on, the default is to list
all collections, Solr. For
all other actions
ColdFusion determines
the collection type.

language

See Usage

© 2014 Adobe Systems Incorporated. All rights reserved.

English

For a list of options, see
Usage.

205

Adobe ColdFusion Documentation

name

See Usage

Name for the query
results returned by the li
st and categorylist a
ctions.

path

See Usage

Absolute path to a
collection. To map an
existing collection, specify
a fully qualified path to the
collection (not including
the collection name); for
example, "C:\MyCollec
tions\".

Usage

With this tag you can
Create Solr collections.
Administer Solr collections created by this tag or the ColdFusion Administrator.
The following table shows the dependence relationships among this tag's attribute values:
This
attribute is
required,
optional,
or
unnecessa
ry (blank):

For this
action
attribute
value:

list

create

map

optimize

repair

delete

category
list

collecti
on

Required

Required

Required

Required

Required

Required

path

Required

Required

language

Optional

Optional

name

Required

Required

categori
es

The following examples show the structures returned by the categorylist action:
CATEGORIES

© 2014 Adobe Systems Incorporated. All rights reserved.

206

Adobe ColdFusion Documentation

blue

10

green

3

magenta

3

purple

2

CATEGORYTREES
a/

10

a/b

10

a/b/c

10

a/b/c/subdir

3

The list action returns the following information in a result set that contains one row per collection:
Column
CATEGORIES

Contents
yes: the collection has category support enabled.
no: the collection does not have category support
enabled.

CHARSET

The character set of the collection.

CREATED

The date and time that the collection was created.

DOCCOUNT

The number of documents in this collection.

EXTERNAL

yes: the collection is external.
no: the collection is not external.
not found: the collection is registered but is not
available in the defined path.

LANGUAGE

The locale setting of the collection. This information is
not available for K2Server collections.

LASTMODIFIED

The date and time that the collection was last changed.

MAPPED

Obsolete.

NAME

The name of the collection.

ONLINE

Obsolete.

© 2014 Adobe Systems Incorporated. All rights reserved.

207

Adobe ColdFusion Documentation

PATH

Absolute path to the collection.

REGISTERED

Obsolete.

SIZE

The size of the collection, expressed in kilobytes.

You can also specify uni to enable support for multiple languages.
To determine whether a collection exists, use code, such as the following, to execute a query of queries:



SELECT * from myCollections
WHERE myCollections.name = 'myCollectionName'






To determine whether a Solr collection exists, you must specifically add the attribute engine and provide the value
as solr. For example,{{}}To get a result set with
values for all the collections that are registered with the search server, use code such as the following:



#name#



To add content to a collection, use cfindex. To search a collection, use cfsearch.Restart the ColdFusion Search
Service for this change to take effect.
For Solr collections, the language attribute of this tag supports the following options:
Brazilian

cjk (Chinese, Japanese,
Korean)

French

Russian

Czech

Dutch

German

Thai

Chinese

English

Greek

© 2014 Adobe Systems Incorporated. All rights reserved.

208

Adobe ColdFusion Documentation

cfcomponent
Description

Creates and defines a component object; encloses functionality that you build in CFML and enclose in cffunction
tags. This tag contains one or more cffunction tags that define methods. Code within the body of this tag, other
than cffunction tags, is executed when the component is instantiated.A component file has the extension CFC
and is stored in any directory of an application.
A component method is invoked in the following ways:
In the cfinvoke tag in a ColdFusion page
In a URL that calls a CFC file and passes a method name as a URL parameter
In the cfscript tag
As a web service
From Flash code
Category

Extensibility tags
Syntax


variable declarations

...


...



See also

© 2014 Adobe Systems Incorporated. All rights reserved.

209

Adobe ColdFusion Documentation

cfargument, cffunction, cfinterface, cfinvoke, cfinvokeargument, cfobject, cfproperty, cfre
turn, IsInstanceOf, Building and Using ColdFusion Components in the Developing ColdFusion
Applications
History

ColdFusion 10: rest, restPath, httpMethod, produces, consumes, indexable, indexLanguage,
autoIndex, wsVersion}}ColdFusion 9.0.1: Added the attribute
{{mappedSuperClass}}ColdFusion 9: Added the attributes {{serializable and accessors.Cold
Fusion 8:
Added the implements and serviceaddress attributes.
Added support for the onMissingMethod function.
ColdFusion MX 7:
Added support for publishing document-literal style web services.
Added the style, namespace, serviceportname, porttypename, wsdlfile, bindingname, and out
put attributes.
Extended functionality for the hint and displayname attributes when publishing document-literal style web
services.
ColdFusion MX: Added this tag.
Attributes

Attribute

Req/Opt

Default

Description

accessors

Optional

yes (for persistent CFC)n
o for others

If set to yes, lets you
invoke implicit getters and
setters.
For persistent CFC, acce
ssors is always enabled.

alias

Optional

autoIndex

Optional

© 2014 Adobe Systems Incorporated. All rights reserved.

Specifies the type label
to give the object when it
is converted from CFML
to ActionScript 3. It
matches the alias attrib
ute of AS3 types. This is
attribute applies only to
Flash Remoting and
LiveCycle Data Services
value objects, and lets
you work with typed
objects in both
ColdFusion and Flash.
yes

If no, auto-indexing of
CFC does not occur. That
is, indexing occurs only in
offline mode.

210

Adobe ColdFusion Documentation

bindingname

Optional

consumes

optional

displayname

Optional

© 2014 Adobe Systems Incorporated. All rights reserved.

Specifies the binding att
ribute of the port elemen
t in the WSDL. If you don't
specify this attribute,
ColdFusion derives the
value from the CFC class
name.
/

Comma-separated list of
acceptable MIME types,
for example consumes="
text/plain,text/htm
l".Searches for the
Content-Type header in
the HTTP request; if the
value is, for example
HTML or XML,
ColdFusion finds the
appropriate method which
can handle the request
and invoke the
method.Used to specify
which MIME media types
of representation a
resource can accept or
consume, from the client.
If this attribute is used at
the component level (and
not at the function level),
all the response methods
accept the specified MIME
types by default.
If no function in a CFC
can consume the MIME
type in a client request,
the following error occurs:
415 Unsupported
Media Type.
If no value is specified, / i
s taken by default, which
means, all MIME types
are consumed.
A string that displays
when you use
introspection to show
information about the
CFC. The information
appears on the heading,
following the component
name.

211

Adobe ColdFusion Documentation

extends

Optional

WEB-INF.cftags.compone
nt

Name of parent
component from which to
inherit methods and
properties. You can use
the keyword component t
o specify the default
value.

hint

Optional

Text that displays when
you use introspection to
show information about
the CFC. The hint attrib
ute value appears below
the component name
heading. Use this attribute
to describe the purpose of
the parameter.

httpMethod

optional

The HTTP method to use,
must be one of the
following:
GET: Requests
information from the
server. Any data that
the server requires to
identify the requested
information must be in
the URL or in cfhttpp
aram type="URL" tag
.
POST: Sends
information to the
server for processing.
Requires one or more c
fhttpparam tags.
Often used for
submitting form-like
data.
PUT: Requests the
server to store the
message body at the
specified URL. Use this
method to send files to
the server.
DELETE: Requests the
server to delete the
specified URL.

© 2014 Adobe Systems Incorporated. All rights reserved.

212

Adobe ColdFusion Documentation

HEAD: Identical to the G
ET method, but the
server does not send a
message body in the
response. Use this
method for testing
hypertext links for
validity and
accessibility,
determining the type or
modification time of a
document, or
determining the type of
server. If you have not
specified HEAD, by
default, GET method is
called. However,
message body is not
sent in the response.

© 2014 Adobe Systems Incorporated. All rights reserved.

213

Adobe ColdFusion Documentation

OPTIONS: A request for
information about the
communication options
available for the server
or the specified URL.
This method enables
the ColdFusion
application to determine
the options and
requirements
associated with a URL,
or the capabilities of a
server, without
requesting any
additional activity by the
server. If you have not
specified OPTIONS,
then ColdFusion sends
a response.
Based on the request
method, the
corresponding function
is invoked. For
example, if a GET
request is sent to the
server, then a function
with httpMethod as GET
is invoked.
If this value is not
specified at the function
level, then the value
you define here is used.
So all functions for
which httpMethod is
not specified are
assigned this value.

© 2014 Adobe Systems Incorporated. All rights reserved.

214

Adobe ColdFusion Documentation

implements

Optional

indexable

Optional

no

If yes, enables indexing
for the component.

indexLanguage

Optional

english

Specify the language that
is used to index and
search.
The value you set
overrides the value
defined in the
Application.cfc.

mappedSuperClass

Optional

no

If set to yes on a
non-persistent CFC, child
CFCs can inherit its
properties. For example,
you can define a base
CFC with common
properties such as ID,
version, or createdOn
which all other persistent
CFCs would extend and
thus get one common
behavior.mappedSuperCl
ass cannot be set to yes
on a persistent CFC.

© 2014 Adobe Systems Incorporated. All rights reserved.

Name of the ColdFusion
interface or interfaces that
this component
implements. If the
component implements an
interface, it must define all
the functions in the
interface, and the function
definitions must conform
to the definitions specified
in the interface. For more
information, see cfinter
face.A component can
implement any number of
interfaces. To specify
multiple interfaces, use a
comma-delimited list with
the format interface1,
interface2.

215

Adobe ColdFusion Documentation

namespace

Optional

class name

Specifies the namespace
used in the WSDL for a
CFC that is invoked as a
web service. If you don't
specify this attribute,
ColdFusion derives the
value from the CFC class
name.

output

Optional

Component body
displayable text that is
processed as standard
CFML

Specifies whether
constructor code in the
component can generate
HTML output; does not
affect output in the body
of cffunction tags in
the component.
yes: Constructor code
is processed as if it
were within a cfoutpu
t tag. Variable names
surrounded by number
signs (#) are
automatically replaced
with their values.
no: Constructor code is
processed as if it were
within a cfsilent tag.
If you do not specify this
attribute, constructor
code is processed as
standard CFML. Any
variables must be in cf
output tags.

porttypename

Optional

© 2014 Adobe Systems Incorporated. All rights reserved.

Specifies the name attribu
te of the porttype eleme
nt in the WSDL. If you
don't specify this attribute,
ColdFusion derives the
value from the CFC class
name.

216

Adobe ColdFusion Documentation

produces

optional

/

Comma-separated list of
acceptable MIME types,
for example produces="
text/plain,text/htm
l". Searches for the
Accept header in the
HTTP request or
extension in the URL
(valid extensions are .xml
and .json); if the value is,
for example HTML, JSON,
or XML, ColdFusion finds
the appropriate method
that can handle the
request and invoke the
method.Used to specify
the MIME media types or
representations a CFC
can produce and send
back to the client.
If specified at the
component level (and not
at the function level) , all
the functions in a CFC
can produce the specified
MIME types by default. If
no methods in a CFC can
produce the MIME type in
a client request, the
following error occurs: 40
6 Not Acceptable.
If no value is specified, / i
s taken by default, which
means, all MIME types
are produced.

rest

Optional

true if RestPath is
specified

If true, the CFC is
REST-enabled.

restPath

Optional

© 2014 Adobe Systems Incorporated. All rights reserved.

217

Adobe ColdFusion Documentation

You can access the REST
resource either by
providing a REST path or
CFC path. So specify if
you want to use a path
other than the CFC path.
If rest="true" and you
do not specify this
attribute, path to the CFC
is used.Path to the CFC
should be from the
directory registered as a
REST service. Also, you
should include the CFC
name in the path. For
example, if you have a
folder college that is
registered as RestTest,
and you want to publish
student.cfc which is in a
sub-folder department (in
the folder college), then
the URL used to access
student.cfc is as follows:
http://localhost:8500/rest/
RestTest/department/stud
ent

© 2014 Adobe Systems Incorporated. All rights reserved.

218

Adobe ColdFusion Documentation

.
The restPath in this
case is department/st
udent.
The path is
case-sensitive. Also, it is
preferable to avoid special
character in the path.At
CFC level, specify the
path as follows:restPath
="restService" or
{{restPath="test/restServic
e"}}You
can specify templates as
value of restPath. For
example, restPath="{n
ame}". This means, all
URLs
in the format /rest// match
es the restPath. For
example,
http://localhost:8500/rest/s
ervice1/abc
.
The value in place of
template can be accessed
using the restargsourc
e value path. For details,
see the attribute details of
cfargument.
The attribute can have
complex expressions as
values. For example, res
tpath="customers/{f
irstname}-{lastname
}".
This matches URLs such
as "/customers/paulbensen" but
not "/customers/paul
bensen".Also restPath
can
include regular
expressions such as rest
path="/customers/{i
d : \d+}".

© 2014 Adobe Systems Incorporated. All rights reserved.

219

Adobe ColdFusion Documentation

Here, id is an integer that
can match "/customers
/123111" but
not "/customers/asd"
or "/customers/123/1
22".
If you have two methods
with different path
attribute values and if the
paths are ambiguous,
then there are precedence
rules for finding
the match. For example, r
estpath="/customers
/{id : .+}".
This expression matches
any stream of characters
after /customer.
It matches "/customers
/123", "/customers/a
sd",
and "/customers/123/
12/asdfa", but not "/c
ustomers".
You can also have
expressions such as rest
Path="/customers/{i
d : .+}/address", th
e
URL "/customers/123
/asd/address" is
matched with
both URLs. In such

© 2014 Adobe Systems Incorporated. All rights reserved.

220

Adobe ColdFusion Documentation

scenarios, the precedence
rules are used to find
the match.
serializable

Optional

true

Specifies whether this
component can be
serialized. If you set this
value to false, the
component and the data
in the component's This
and Variables scopes
cannot be serialized, so
they are not retained on
session replication, and
the component is in its
default state.

serviceaddress

Optional

URL of the CFC

Specifies the SOAP URL
of the web service. If you
don't specify this attribute,
ColdFusion uses the URL
of the CFC in the WSDL
service description. Use
this attribute to specify the
protocol, for example, by
specifying a URL that
starts with
https://
.
This attribute applies only
for web services.

serviceportname

Optional

© 2014 Adobe Systems Incorporated. All rights reserved.

Specifies the name attribu
te of the port element in
the WSDL. If you don't
specify this attribute,
ColdFusion derives the
value from the CFC class
name.

221

Adobe ColdFusion Documentation

style

Optional

rpc

Specifies whether a CFC
used for web services
uses RPC-encoded style
or document-literal style:
rpc: RPC-encoded
style
document:
Document-literal style
wrapped: If you are
setting wsVersion as
2, the default value is w
rapped and if it is 1,
then the default value is
rpc.

wsdlfile

Optional

A properly formatted
WSDL file to be used
instead of WSDL
generated by ColdFusion.

wsVersion

Optional

If you specify 2, CFC is
deployed using Axis 2
engine. The value you
specify overrides the
value you specify at
application or server level.

Usage

If you specify the extends attribute, the data and methods of the parent component are available to CFC methods
as if they were parts of the current component. If the managerCFC component extends the employeeCFC
component, and the employeeCFC component has a getEmployeeName method, you can call this method by
using the managerCFC, as follows:



This tag requires an end tag.
If you specify style="document", ColdFusion publishes the CFC as a document-literal style web service. For
more information, see Publishing document-literal style web services in the Developing ColdFusion Applications.CF
Cs support an onMissingMethod function. By defining an onMissingMethod function in the cfcomponent tag
body in the CFC, you can handle calls to methods that are not implemented in the CFC. If an application calls a
function that is not defined in the CFC, ColdFusion calls the onMissingMethod function and passes it the
requested method's name and arguments. If you do not define an onMissingMethod function, a call to a method
that is not defined in the CFC causes ColdFusion to throw an error that must be handled in the calling code.
The onMissingMethod function is useful for several purposes:
To handle errors directly in the component, instead of requiring that each instance of code that calls the

© 2014 Adobe Systems Incorporated. All rights reserved.

222

Adobe ColdFusion Documentation

component handles them.
To create a dynamic proxy, an object that can take arbitrary calls and dynamically determines the correct
action.
The onMissingMethodfunction must have the following format:




code to handle call to nonexistent method


Note
The argument name for onMissingMethod must not change.

Example 1




SELECT FIRSTNAME, LASTNAME, EMAIL
FROM tblEmployees





SELECT *
FROM tblDepartments





© 2014 Adobe Systems Incorporated. All rights reserved.

223

Adobe ColdFusion Documentation

cfcontent
Description

Does either or both of the following:
Sets the MIME content encoding header for the current page; if the encoding information includes a character
encoding, sets the character encoding of generated output.
Sends the contents of a file, or of a variable that contains binary data, as the page output.
To restrict this tag, use the settings in the ColdFusion Administrator > Security > Sandbox Security. For more
information, see the Administrator online Help.
Category

Data output tags
Syntax



Note
You can specify this tag's attributes in an attributeCollection attribute whose value is a
structure. Specify the structure name in the attributeCollection attribute and use the tag's
attribute names as structure keys.

See also

cfcol, cfheader, cfhttp, cfoutput, cftable
History

ColdFusion 8: Changed the behavior of the tag if the type attribute is not specified and the file attribute is
specified. Previously, ColdFusion assumed a default file type of text/html. Now, ColdFusion attempts to get the
content type from the file.ColdFusion MX 7: Added the variable attribute.
Attributes

Attribute

Req/Opt

© 2014 Adobe Systems Incorporated. All rights reserved.

Default

Description

224

Adobe ColdFusion Documentation

deleteFile

Optional

no

Applies only if you specify
a file with the file attribu
te.
yes: deletes the file on
the server after sending
its contents to the client.
no: leaves the file on
the server.

file

Optional

reset

Optional

Name of an on-disk or
in-memory file whose
contents provide the page
output. The filename must
start with a drive letter and
a colon, or a forward or
backward slash. When
using ColdFusion in a
distributed configuration,
the file attribute must
refer to a path on the
system on which the web
server runs. When you
use this attribute, any
other output on the
current CFML page is
ignored; only the contents
of the file are sent to the
client.
yes

If you specify a file or v
ariable attribute, this
attribute has no effect;
otherwise, it does the
following:
yes: discards output
that precedes call to cf
content
no: preserves output
that precedes call to cf
content. In this case,
all output is sent with
the specified type.

type

Optional

© 2014 Adobe Systems Incorporated. All rights reserved.

225

Adobe ColdFusion Documentation

The MIME content type of
the page, optionally
followed by a semicolon
and the character
encoding. By default,
ColdFusion sends pages
as text/html content type
in the UTF-8 character
encoding. However, if the
file attribute is
specified, ColdFusion
attempts to get the
content type from the file.
The content type
determines how the
browser or client
interprets the page
contents.
The following are some of
the content type values
that you can use:

© 2014 Adobe Systems Incorporated. All rights reserved.

226

Adobe ColdFusion Documentation

text/html
text/plain
application/x-sho
ckwave-flash
application/mswor
d
image/jpeg
The following list
includes commonly
used character
encoding values:
utf-8
iso-8859-1
windows-1252
us-ascii
shift_jis
iso-2022-jp
euc-jp
euc-kr
big5
euc-cn
utf-16
For example:

{{type =
"text/ht
ml"}}
{{type =
"text/ht
ml;
charset}
}{{=}}{{
ISO-8859
-1}}{{"}
}

© 2014 Adobe Systems Incorporated. All rights reserved.

227

Adobe ColdFusion Documentation

variable

Optional

Name of a ColdFusion
binary variable whose
contents can be displayed
by the browser, such as
the contents of a chart
generated by the cfchar
t tag or a PDF or Excel
file retrieved by a cffile
action="readBinary"
tag. When you use this
attribute, any other output
on the current CFML page
is ignored; only the
contents of the file are
sent to the client.

Usage

To set the character encoding (character set) of generated output, including the page HTML, use code such as the
following:



When ColdFusion processes an HTTP request, it determines the character encoding to use for the data it returns in
the HTTP response. By default, ColdFusion returns character data using the Unicode UTF-8 format, regardless of
the value of an HTML meta tag in the page. You can use the cfcontent tag to override the default character
encoding of the response. For example, to tell ColdFusion to return the page using Japanese EUC character
encoding, use the type attribute, as follows:



If you call the cfcontent tag from a custom tag, and you do not want the tag to discard the current page when it is
called from another application or custom tag, set reset = "no".
If a file delete operation is unsuccessful, ColdFusion throws an error.Do not use this tag after the cfflush tag on a
page, it has no effect or ColdFusion throws an error. The following tag can force most browsers to display a dialog
box that asks users whether they want to save the contents of the file specified by the cfcontent tag using the
filename specified by the filename value. If the user selects to open the file, most browsers open the file in the
related application, not the browser window.



Some file types, such as PDF documents, do not use executable code and can display directly in most browsers. To
request the browser to display the file directly, use a cfheader tag similar to the following:

© 2014 Adobe Systems Incorporated. All rights reserved.

228

Adobe ColdFusion Documentation



You can use any value for the filename part of the filename attribute, but the ext part must be the standard
Windows extension for the file type. For file types that might contain executable code, such as Microsoft Excel
documents, most browsers always ask before opening the document. For these file types, the inline content
disposition specification requests the browser to display the file directly if the user selects to open the file.
For more information on character encodings, see the following web pages:
The page atwww.w3.org/International/O-charset.html provides general information on character encodings
and the web, and has several useful links.
The page at www.iana.org/assignments/character-sets is a complete list of character sets names used on the
Internet, maintained by the Internet Assigned Numbers Authority.
ColdFusion uses the Java JCE for encoding support. The page at http://java.sun.com/javase/6/docs/technote
s/guides/intl/encoding.doc.html lists the character encodings that JCE 6, and therefore ColdFusion, can
interpret. This list uses Java internal names, not the IANA character encoding names that you use in the
SetEncoding charset parameter and other ColdFusion attributes and parameters.
For a complete list of media types used on the Internet, see www.iana.org/assignments/media-types/.
Note
When using cfabort, cflocation, or cfcontent tags, the OnAbort method is
invoked instead on OnRequestEnd.

Example

© 2014 Adobe Systems Incorporated. All rights reserved.

229

Adobe ColdFusion Documentation




This example shows how the Reset attribute changes output for text.
reset = "Yes": 123 
 456
This example shows how the Reset attribute changes output for text.
reset = "No": 123 
 456










Month
Quantity
$ Sales
January
80
$245
February
100
$699
March
230
$2036
Total
=Sum(B2..B4)
=Sum(C2..C4)


© 2014 Adobe Systems Incorporated. All rights reserved.

230

Adobe ColdFusion Documentation

cfcontinue
Description

Used within a cfloop tag. Returns processing to the top of a loop.
Category

Flow-control tags
Syntax



See also

cfabort, cfbreak, cfexecute, cfif, cflocation, cfloop, cfthrow, cftry; cfloop and cfbreak in the Devel
oping ColdFusion Applications
History

ColdFusion 9: Added the tag.
Tag example


#i# is

ODD



EVEN



Script example

for (i=1; i <= 5; i++){
writeOutput("#i# is ");
if (i mod 2){
writeOutput("ODD
");
continue;
}
writeOutput("EVEN
");
}

Either version of the code above outputs:

© 2014 Adobe Systems Incorporated. All rights reserved.

231

Adobe ColdFusion Documentation

1
2
3
4
5

is
is
is
is
is

ODD
EVEN
ODD
EVEN
ODD

© 2014 Adobe Systems Incorporated. All rights reserved.

232

Adobe ColdFusion Documentation

cfcookie
Description

Defines web browser cookie variables, including expiration and security options.
Category

Forms tags, Variable manipulation tags
Syntax



Note
You can specify this tag's attributes in an attributeCollection attribute whose value is a
structure. Specify the structure name in the attributeCollection attribute and use the tag's
attribute names as structure keys.

See also

cfdump, cfparam, cfregistry, cfsavecontent, cfschedule, cfset
History

ColdFusion 10: Added the preserveCase and encodeValue attributes.
ColdFusion MX 6.1:
Changed the expires attribute: it now accepts a date time object.
Cookie names can include all ASCII characters except commas, semicolons, or whitespace characters.
ColdFusion 9: Added the attribute httponly.
Attributes

Attribute

Req/Opt

© 2014 Adobe Systems Incorporated. All rights reserved.

Default

Description

233

Adobe ColdFusion Documentation

name

Required

Name of cookie variable.
ColdFusion converts
cookie names to
all-uppercase. Cookie
names set using this tag
can include any printable
ASCII characters except
commas, semicolons, or
white space characters.

domain

Required if path attribute
is specified. Optional
otherwise

Domain in which cookie is
valid and to which cookie
content can be sent from
the user's system. By
default, the cookie is only
available to the server that
set it. Use this attribute to
make the cookie available
to other servers.Must start
with a period. If the value
is a subdomain, the valid
domain is all domain
names that end with this
string. This attribute sets
the available subdomains
on the site on which the
cookie can be used.
For a domain value that
ends in a country code,
the specification must
contain at least three
periods; for example, ".m
ongo.state.us". For
top-level domains, two
periods are required; for
example, ".mgm.com".
You cannot use an IP
address as a domain.

encodevalue

Optional

Specify if cookie value
should be encoded

© 2014 Adobe Systems Incorporated. All rights reserved.

234

Adobe ColdFusion Documentation

expires

Optional

session only

Expiration of cookie
variable.
The cookie expires
when the user closes
the browser, that is, the
cookie is "session only".
A date or date/time
object (for example,
10/09/97).
A number of days (for
example, 10, or 100).
now: deletes cookie
from client cookie.txt file
(but does not delete the
corresponding variable
the Cookie scope of the
active page).
never: The cookie
expires in 30 years from
the time it was created
(effectively never in web
years).

httponly

Optional

If yes, sets cookie as
httponly so that it cannot
be accessed using
JavaScripts. Note that the
browser must have
httponly compatibility.

path

Optional

URL, within a domain, to
which the cookie applies;
typically a directory. Only
pages in this path can use
the cookie. By default, all
pages on the server that
set the cookie can access
the cookie.

path =
"/services
/login"

To specify multiple URLs,
use multiple cfcookie ta
gs. If you specify path,
also specify domain.

© 2014 Adobe Systems Incorporated. All rights reserved.

235

Adobe ColdFusion Documentation

preserveCase

Optional

secure

Optional

False

Specify if cookie name
should be case-sensitive.
If browser does not
support Secure Sockets
Layer (SSL) security, the
cookie is not sent. To use
the cookie, the page must
be accessed using the
https protocol.
yes: Variable must be
transmitted securely.
no

Optional

value

Value to assign to cookie
variable. Must be a string
or variable that can be
stored as a string.

Usage

If this tag specifies that a cookie is saved beyond the current browser session, the client browser writes or updates
the cookie in its local cookies file. Until the browser is closed, the cookie resides in browser memory. If the expires
attribute is not specified, the cookie is not written to the browser cookies file.
If you use this tag after the cfflush tag on a page, ColdFusion does not send the cookie to the browser; however,
the value you set is available to ColdFusion in the Cookie scope during the browser session.
Note
You can also create a cookie that expires when the current browser session expires by using the
cfset tag or a CFScript assignment statement to set a variable in the Cookie scope, as in . To get a cookie's value, refer to the cookie name in the
Cookie scope, as in .

You can use dots in cookie names, as the following examples show:




To access cookies, including cookies that you set and all cookies that are sent by the client, use the Cookie scope.
For example, to display the value of the person.name cookie set in the preceding code, use the following line:

#cookie.person.name#

Example

© 2014 Adobe Systems Incorporated. All rights reserved.

236

Adobe ColdFusion Documentation




SELECT EMail, FromUser, Subject, Posted
FROM Comments



cfcookie Example

















The last AOL visitor to view this site was
#Cookie.LastAOLVisitor#, on
#DateFormat(COOKIE.TimeVisited)#

Hide my tracks

No AOL Visitors have viewed the site lately.


#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

237

Adobe ColdFusion Documentation

cfclient
The  tag is a marker tag that instructs ColdFusion to generate client-side code (JavaScript) for ColdFusion
code. This tag does not have any attribute. To know more about this tag, read this document.

© 2014 Adobe Systems Incorporated. All rights reserved.

238

Adobe ColdFusion Documentation

cfclientsettings
Description

This tag is similar to cfprocessingdirective and acts as a compiler directive to include plugins for various features
(device detection and device API). You can use this tag to load all the required device plugins and device detection
plugins
Syntax



See also

cfclient
History

ColdFusion 11: Added this tag.
Attributes

Attribute

Req/Opt

Default

Description

enableDeviceAPI

Optional

false

Enable/disable the device
API.

detectDevice

Optional

false

Enable/disable the device
detection plugin.

© 2014 Adobe Systems Incorporated. All rights reserved.

239

Adobe ColdFusion Documentation

deviceTimeout

Optional

10

The timeout for loading
the plugins (in seconds).
If the plug-in takes more
than 10 seconds (default
timeout value) to load, you
will get an error. Try
increasing the timeout to
avoid this problem.
If you have specified
enableDeviceAPI as
"true", the device plugins
will be loaded. After the
device plugins are loaded,
ColdFusion waits for an
event "DeviceReady" to
be triggered. Once the
DeviceReady event is
triggered successfully, the
execution of CFML starts.
In a desktop browser, the
DeviceReady event will
not be triggered.
However, for a mobile
application (shell
application or packaged
application), the event is
triggered.
So if you are trying to run
a CFM where the device
APIs are enabled on a
desktop browser you will
get a blank page and in
the console you can see
an error message about
deviceTimeout.

Device detection

The device detection feature of CFML allows you to identify the device properties and characteristics, which can be
used to determine the best content, layout, mark-up or application to serve to the given device.
These characteristics include screen size, browser type and version, media support, and the level of support for
CSS, HTML, and JavaScript.
For getting the device features and capabilities, you need to specify an attribute detectdevice in the
 tag and set it to true:



© 2014 Adobe Systems Incorporated. All rights reserved.

240

Adobe ColdFusion Documentation

If the detectdevice attribute is set to true, ColdFusion automatically detects the features and capabilities of the
device (width, height, and orientation) on which the application is running.
The following example shows the usage of the device detection feature:











Canvas support -


Show canvas support


In the above example, we are trying to find if the device supports HTML5 Canvas. cfclient.canvas returns a boolean
value indicating the support for the HTML5 Canvas property.
In the above example, we are trying to find if the device supports HTML5 Canvas. cfclient.canvas returns a boolean
value indicating the support for the HTML5 Canvas property.
ColdFusion Server internally uses Modernizer JavaScript library (version 2.6.2) for the device detection feature.
The following table lists the supported device features with example usage:
Features

Syntax

Touch Events

cfclient.touch

Canvas Text

cfclient.canvastext

Canvas

cfclient.canvas

Geolocation

cfclient.geolocation

Web Sockets

cfclient.websockets

Drag ‘n Drop

cfclient.draganddrop

History

cfclient.history

© 2014 Adobe Systems Incorporated. All rights reserved.

241

Adobe ColdFusion Documentation

applicationCache

cfclient.applicationcache

localStorage

cfclient.localstorage

Width

cfclient.width

Height

cfclient.height

Device Width

cfclient.deviceWidth

Device Height

cfclient.deviceHeight

Orientation

cfclient.orientation

Device Group Name

cfclient.deviceGroupName

Device Group Descriptions

cfclient.deviceGroupDescription

CSS Animations

cfclient.cssanimations

CSS Columns

cfclient.csscolumns

CSS Generated Content

cfclient.generatedcontent

CSS Gradients

cfclient.cssgradients

CSS Reflections

cfclient.cssreflections

CSS 2D Transforms

cfclient.csstransforms

CSS 3D Transforms

cfclient.csstransforms3d

CSS Transitions

cfclient.csstransitions

Audio

cfclient.audio

Video

cfclient.video

Hash Change

cfclient.hashchange

IndexedDB

cfclient.indexeddb

Input Attributes

cfclient.input.* (* refers to attributes for input elements.
For possible values, see the Modernizr documentation)

Input Types

cfclient.inputtypes.* (* refers to input type attributes. For
possible values, see the Modernizr documentation)

© 2014 Adobe Systems Incorporated. All rights reserved.

242

Adobe ColdFusion Documentation

Post Message

cfclient.postmessage

Session Storage

cfclient.sessionstorage

Web Workers

cfclient.webworkers

Web SQL Database

cfclient.websqldatabase

For the description on all above mentioned features, see the Modernizr documentation.
Using media queries
Media queries allow you to apply changes to the page design based on the viewing size and capability of the device
on which your content is displayed. A media query consists of one or more logical expressions formed using the
detected device data that checks for certain conditions of media feature and based on the result of this expression
we can change the layout of the page dynamically.
If you are building a mobile application, you can easily detect the characteristics of the device and customize the
layout just for that device as shown in the following example:












In the above example, the web page is customized for different devices based on their screen sizes.
Handling orientation changes
For handling the device orientation changes, you can register a listener using the addOrientationListener() function:

© 2014 Adobe Systems Incorporated. All rights reserved.

243

Adobe ColdFusion Documentation




Orientation : 

Width : 

Height : 


















In the above example, addOrientationListener function is used to register a listener that monitors the orientation of
the device (landscape or portrait). When the orientation of the device changes, an orientationHandler call back
function is invoked.
You can use the removeOrientationListener to un-register the listener:





© 2014 Adobe Systems Incorporated. All rights reserved.

244

Adobe ColdFusion Documentation

You can also add multiple listeners:




When the device orientation changes, all the registered listener functions are invoked.
Handling window resizing events
For handling the window resizing events, you can register a listener using the addResizeListener() function:




Width :

Height :

Device width :

Device height :
















© 2014 Adobe Systems Incorporated. All rights reserved.

245

Adobe ColdFusion Documentation

You can also add multiple listeners:




When there is a change in window size all the registered resize listener functions are invoked. You can use
removeResizeListener() to un-register the handlers.





Setting device timeout
In the  tag, an attribute called deviceTimeOut can be specified. The default value of deviceTimeout
is 10 secs. When enableDeviceApi or detectDevice is set as true, the deviceTimeOut value will be honored. Time
will be provided for the required plugins to be loaded. After the specified time, an exception will be thrown.



© 2014 Adobe Systems Incorporated. All rights reserved.

246

Adobe ColdFusion Documentation

Tags d-e
This section lists tags starting with alphabets D-E with their description.
cfdbinfo
cfdefaultcase
cfdirectory
cfdiv
cfdocument
cfdocumentitem
cfdocumentsection
cfdump
cfelse
cfelseif
cferror
cfexchangecalendar
cfexchangeconnection
cfexchangecontact
cfexchangeconversation
cfexchangefilter
cfexchangefolder
cfexchangemail
cfexchangetask
cfexecute
cfexit

© 2014 Adobe Systems Incorporated. All rights reserved.

247

Adobe ColdFusion Documentation

cfdbinfo
Description

Lets you retrieve information about a data source, including details about the database, tables, queries, procedures,
foreign keys, indexes, and version information about the database, driver, and JDBC.
Category

Database manipulation tags
Syntax



Note
You can specify this tag's attributes in an attributeCollection attribute whose value is a
structure. Specify the structure name in the attributeCollection attribute and use the tag's
attribute names as structure keys.

See also

cfinsert, cfprocparam, cfprocresult, cfqueryparam, cfstoredproc, cftransaction, cfupdate; Opt
imizing database use in the Developing ColdFusion Applications.
History

ColdFusion 8: Added this tag.
Attributes

Attribute

Req/Opt

datasource

Optional

Datasource to use to
connect to the database.

name

Required

Name to use to refer to
the result.

© 2014 Adobe Systems Incorporated. All rights reserved.

Default

Description

248

Adobe ColdFusion Documentation

type

Required

Type of information to get:
dbnames: database
name and type
tables: name, type,
and remarks
columns: name, SQL
data type, size, decimal
precision, default value,
maximum length in
bytes of a character or
integer data type
column, whether nulls
are allowed, ordinal
position, remarks,
whether the column is a
primary key, whether
the column is a foreign
key, the table that the
foreign key refers to,
the key name the
foreign key refers to
version: database
product name and
version, driver name
and version, JDBC
major and minor version
procedures: name,
type, and remarks
foreignkeys: foreign
key name and table,
primary key name,
delete, and update rules
index: name, column
on which the index is
applied, ordinal
position, cardinality,
whether the row
represents a table
statistic or an index,
number of pages used
by the table or index,
whether the index
values are unique
ClientInfo: The
client information
metadata for the
specified data source.

© 2014 Adobe Systems Incorporated. All rights reserved.

249

Adobe ColdFusion Documentation

dbname

Optional

Name of the database.
Used only if the action
= "This overrides
the one mentioned
as a part of
datasource
definition."

password

Optional

Password to connect to
the database.

pattern

Optional

Used only if type =
"tables", type =
"columns", or type =
"procedures".
Specifies a filter to
retrieve information about
specific tables, columns,
or stored procedures. Use
an underline (_) to
represent a single
wildcard character and a
percent sign (%) to
represent a wildcard of
zero or more characters.

table

Required if type =
"columns" or type =
"foreignkeys" or
type = "index"

Name of the table from
which you retrieve
information.

username

Optional

no

User name to connect to
the database.

Usage

Use the cfdbinfo tag to return a query object that contains information about a database. The query object varies,
depending on the value that you specify in the type attribute. The following table lists the query object contents for
each type:
Type

Column name

Description

dbnames

DATABASE_NAME

Name of the database.

TYPE

Type of the database, whether
schema or catalog.

TABLE_NAME

Name of the table.

tables

© 2014 Adobe Systems Incorporated. All rights reserved.

250

Adobe ColdFusion Documentation

columns

version

TABLE_TYPE

Type of the table, including view,
table, synonym, and system table.

REMARKS

Remarks of the table.

COLUMN_NAME

Name of the column.

TYPE_NAME

SQL data type of the column.

IS_NULLABLE

Whether the column allows nulls.

IS_PRIMARYKEY

Whether the column is a primary
key.

IS_FOREIGNKEY

Whether the column is a foreign
key.

REFERENCED_PRIMARYKEY

If the column is a foreign key, the
name of the table it refers to.

REFERENCED_PRIMARYKEY_TA
BLE

If the column is a foreign key, the
key name it refers to.

COLUMN_SIZE

Size of the column

DECIMAL_DIGITS

Number of digits to the right of the
decimal point.

COLUMN_DEFAULT_VALUE

Default value of column.

CHAR_OCTET_LENGTH

Maximum length in bytes of a
character or integer data type
column.

ORDINAL_POSITION

Ordinal position of the column.

REMARKS

Remarks of the column.

DATABASE_VERSION

Version of the database
management system.

DATABASE_PRODUCTNAME

Name of the database management
system.

DRIVER_VERSION

Version of the database driver.

DRIVER_NAME

Name of the database driver.

© 2014 Adobe Systems Incorporated. All rights reserved.

251

Adobe ColdFusion Documentation

procedures

foreignkeys

index

JDBC_MAJOR_VERSION

Major version number of the driver.

JDBC_MINOR_VERSION

Minor version number of the driver.

PROCEDURE_NAME

Name of the stored procedure.

REMARKS

Remarks for the stored procedure.

PROCEDURE_TYPE

Procedure type, which indicates
whether the procedure returns a
result.

FKCOLUMN_NAME

Foreign key name.

FKTABLE_NAME

Foreign key table name.

PKCOLUMN_NAME

Primary key name.

DELETE_RULE

Specifies what action to take when
you delete a record that has
dependent records.

UPDATE_RULE

Specifies what action to take when
you update a record that has
dependent records.

INDEX_NAME

Name of the index, empty if type is
table statistic.

COLUMN_NAME

Name of the column on which the
index is applied, empty if the type is
table statistic.

ORDINAL_POSITION

Ordinal position.

CARDINALITY

Number of unique values if the type
is index, or number of rows if the
type is statistic

TYPE

Whether the row represents a table
statistic or an index. Index types are
clustered, hashed, or other.

PAGES

Number of pages used by the table
if the type is table statistic, or the
number of pages used by the index.

© 2014 Adobe Systems Incorporated. All rights reserved.

252

Adobe ColdFusion Documentation

NON_UNIQUE

Whether the index values are
unique.

Example




The #datasrc# data source has the following databases:





Database name
Type


#dbdata.DATABASE_NAME#
#dbdata.TYPE#




© 2014 Adobe Systems Incorporated. All rights reserved.

253

Adobe ColdFusion Documentation

cfdefaultcase
Description

Used only inside the cfswitch tag body. Contains code to execute when the expression specified in the cfswitc
h tag does not match the value specified by a cfcase tag.
Category

Flow-control tags
Syntax



See also

cfcase, cfswitch; cfswitch, cfcase, and cfdefaultcase in the Developing ColdFusion Applications
History

ColdFusion MX: Changed placement requirements: this tag does not have to follow all cfcase tags in the cfswitc
h tag body.
Usage

The contents of the cfdefaultcase tag body executes if the expression attribute of the cfswitch tag does not
match any of the values specified by the cfcase tags in the cfswitch tag body. The contents of the cfdefaultc
ase tag body can include HTML and text, and CFML tags, functions, variables, and expressions.
You can specify only one cfdefaultcase tag within a cfswitch tag. You can put the cfdefaultcase tag at
any position within a cfswitch statement; it is not required to be the last item, but it is good programming practice
to put it last.
Example

© 2014 Adobe Systems Incorporated. All rights reserved.

254

Adobe ColdFusion Documentation





















Your grade is #grade#


© 2014 Adobe Systems Incorporated. All rights reserved.

255

Adobe ColdFusion Documentation

cfdirectory
Description

Manages interactions with directories.
Category

File management tags
Syntax



Note
You can specify this tag's attributes in an attributeCollection attribute whose value is a
structure. Specify the structure name in the attributeCollection attribute and use the tag's
attribute names as structure keys.

See also

cffile
History

ColdFusion 10: Added the action copy and the attribute destination.
ColdFusion 9.0.1: Added the storeACL and storeLocation attributes.
ColdFusion 8: Added the listinfo and type attributes.
ColdFusion MX 7: Added the recurse attribute and directory result set column.
ColdFusion MX:
1. Changed behavior for action = "list":
On Windows, cfdirectory action = "list" no longer returns the directory entries "." (dot) or "
.." (dot dot), which represent "the current directory" and "the parent directory."
On Windows, cfdirectory action = "list" no longer returns the values of the Archive and
System attributes.

© 2014 Adobe Systems Incorporated. All rights reserved.

256

Adobe ColdFusion Documentation

On UNIX and Linux, cfdirectory action = "list" does not return any information in the mode c
olumn.
Attributes

Attribute

Req/Opt

directory

Required

Default

Description
Absolute pathname of
directory against which to
perform action. You can
use an IP address, as in
the following example:



action

Optional

destination

Required if action =
"copy"

Path of the destination
directory. If not an
absolute path, it is relative
to the source directory.

filter

Optional if action =
"list"

File extension filter
applied to returned
names, for example,
*.cfm. One filter can be
applied.

© 2014 Adobe Systems Incorporated. All rights reserved.

list

list: returns a query
record set of the files in
the specified directory.
The directory entries "."
(dot) and ".." (dot dot),
which represent the
current directory and
the parent directory, are
not returned.
create
delete
rename
copy

257

Adobe ColdFusion Documentation

listinfo

Optional

mode

Optional

all

all: includes all
information in the result
set.
name: includes only
filenames in the result
set.
Used with action =
"create". Permissions.
Applies only to UNIX and
Linux. Octal values of chm
od command. Assigned to
owner, group, and other,
respectively, for example:
644: assigns read/write
permission to owner;
read permission to
group and other.
777: assigns
read/write/execute
permission to all.

name

Required if action =
"list"

Name for output record
set.

newDirectory

Required if action =
"rename"

New name for directory.

recurse

Optional

no

Whether ColdFusion
performs the action on
subdirectories:
yes
no
Valid for action="lis
t" and action="dele
te".

© 2014 Adobe Systems Incorporated. All rights reserved.

258

Adobe ColdFusion Documentation

sort

Optional; used if action
= "list"

ASC

Query columns by which
to sort a directory listing.
Delimited list of columns
from query output. To
qualify a column, use one
of the following values:
asc: ascending (a to z)
sort order.
desc: descending (z to
a) sort order.
For example:

sort =
"directo
ry ASC,
size
DESC,
datelast
modified
"

storeACL

Optional; used if action
= "create"

StoreLocation

Optional; used if action
= "create"

US

Used to change the
location of the created
bucket. The location can
either be EU, US, or US-W
EST.
For details, see Using
Amazon S3 storage in Opt
imizing ColdFusion
applications.

type

Optional

all

file: includes only
filenames.
dir: includes only
directory names.
all: includes both
filenames and directory
names.

© 2014 Adobe Systems Incorporated. All rights reserved.

An array of struct where
each struct represents a
permission or grant.
For details, see Using
Amazon S3 storage in Opt
imizing ColdFusion
applications.

259

Adobe ColdFusion Documentation

storeLocation

Optional

Used to change the
location of the created
bucket. The location can
either be EU or US. The
default location is US.

storeACL

Optional

An array of struct where
each struct represents a
permission or grant.

Usage

If you put ColdFusion applications on a server that is used by multiple customers, you must consider the security of
files and directories that could be uploaded or otherwise manipulated with this tag by unauthorized users. For more
information about securing ColdFusion tags, see Configuring and Administering ColdFusion.
If action = "list", cfdirectory returns the following result columns, which you can reference in a cfoutput
tag:
name: Directory entry name. The entries "." and ".." are not returned.
directory: Directory that contains the entry.
size: Directory entry size.
type: File type: file, for a file; dir, for a directory.
dateLastModified: The date that an entry was last modified.
attributes: File attributes, if applicable.
mode: Empty column; retained for backward compatibility with ColdFusion 5 applications on UNIX.
Use the following result columns in standard CFML expressions, preceding the result column name with the
query name:

#mydirectory.name#
#mydirectory.directory#
#mydirectory.size#
#mydirectory.type#
#mydirectory.dateLastModified#
#mydirectory.attributes#
#mydirectory.mode#

Note
If the cfdirectory tag does not appear to work, for example, if a list operation returns
an empty result set, make sure that you have correct permissions to access the directory.
For example, if you run ColdFusion as a service on Windows, it operates by default as
System, and cannot access directories on a remote system or mapped drive; to resolve
this issue, do not run ColdFusion using the local system account.

The filter attribute specifies a pattern of one or more characters. All names that match that pattern are
included in the list. On Windows systems, pattern matching ignores text case, on UNIX and Linux, pattern
matches are case-sensitive. The following two characters have special meaning in the pattern and are called
metacharacters:
The asterisk (*) matches any zero or more characters.

© 2014 Adobe Systems Incorporated. All rights reserved.

260

Adobe ColdFusion Documentation

The question mark (?) matches any single character.
The following table shows examples of patterns and filenames that they match:
Pattern

Matches

foo.*

Any file called foo with any extension; for example,
foo.html, foo.cfm, and foo.xml.

*.html

All files with the suffix .html, but not files with the suffix
.htm.

??

All files with two-character names.

Example









The directory existed and the name has been changed to: #newDirectory#




Your directory has been created.










Files exist in this directory. Either delete the files or code
something to do so.






© 2014 Adobe Systems Incorporated. All rights reserved.

261

Adobe ColdFusion Documentation

The directory existed and has been deleted.




The directory did NOT exist.

















SELECT * FROM dirQuery
WHERE TYPE='Dir'

© 2014 Adobe Systems Incorporated. All rights reserved.

262

Adobe ColdFusion Documentation




Another example

The following example was contributed by Steve Blades:

component {
VARIABLES.instance.rootPath = "H:\Karaoke Library\";
/**
* @access remote
* @returnType struct
* @output false
*/
function GetSubordinates (string folder="", string parentage="") {
var retVal = {
'success':true,
'message':'',
'data':''
};
try {
// script version of cfdirectory
var dir = DirectoryList(VARIABLES.instance.rootPath &
ARGUMENTS.parentage & ARGUMENTS.folder, false, "query");
LOCAL.retVal.data = LOCAL.dir;
} catch (any err) {
LOCAL.retVal.success = false;
LOCAL.retVal.message = err.message;
LOCAL.retVal['errorCode'] = err.errorcode;
}
return LOCAL.retVal;
}
}

© 2014 Adobe Systems Incorporated. All rights reserved.

263

Adobe ColdFusion Documentation

cfdiv
Description

Creates an HTML div tag or other HTML container tag and lets you use asynchronous form submission or a bind
expression to dynamically control the tag contents.
Category

Display management tags
Syntax


OR

tag body contents


If the tag does not have a body and end tag, close it with /> character combination.
Note
You can specify this tag's attributes in an attributeCollection attribute whose value is a
structure. Specify the structure name in the attributeCollection attribute and use the tag's
attribute name as structure key.

See also

cfajaximport, cflayout, cfpod, cfwindow
History

ColdFusion 8: Added this tag
Attributes

The following table lists attributes that ColdFusion uses directly. The tag passes any other attributes that you specify
directly as tag attributes to the generated HTML tag.
Attribute

Req/Opt

© 2014 Adobe Systems Incorporated. All rights reserved.

Default

Description

264

Adobe ColdFusion Documentation

bind

Optional

bindOnLoad

Optional

ID

Optional

© 2014 Adobe Systems Incorporated. All rights reserved.

A bind expression that
returns the container
contents. If you specify
this attribute the cfdiv ta
g cannot have a body.
Note:: If a CFML page
specified in this attribute
contains tags that use
AJAX features, such as c
fform, cfgrid, and cfw
indow, you must use a c
fajaximport tag on the
page with the cfdiv tag.
For more information, see
cfajaximport.
true

true: executes the bin
d attribute expression
when first loading the
tag.
false: does not
execute the bind attrib
ute expression until the
first bound event.
To use this attribute,
also specify a bind attri
bute.
For more information,
see Using the
bindOnLoad attribute in
Using Ajax User
Interface Components
and Features in the Dev
eloping ColdFusion
Applications.
The HTML ID attribute
value to assign to the
generated container tag.

265

Adobe ColdFusion Documentation

onBindError

Optional

See Description

The name of a JavaScript
function to execute if
evaluating a bind
expression results in an
error. The function must
take two attributes: an
HTTP status code and a
message.
If you omit this attribute,
and have specified a
global error handler (by
using the ColdFusion.s
etGlobalErrorHandle
r function), it displays the
error message; otherwise
a default error pop-up
window appears.
To use this attribute, also
specify a bind attribute.

tagName

Optional

DIV

The HTML container tag
to create.

Usage

By default, the cfdiv tag creates a div HTML element. You can use standard HTML and CSS techniques to
control the position and appearance of the element and its contents.Use the tagName attribute to create and
populate an HTML content element, such as span or b. Use the cfdiv tag to create tags that can take HTML
markup content directly in the body, such as span, i, b, or p, and not for tags that cannot, such as input, option,
and frameset.
If you submit a form that is inside a cfdiv tag (including in HTML returned by a bind expression), the form submits
asynchronously, and the response from the form submission populates the cfdiv region.
If you specify a bind attribute, the tag dynamically populates the element using a bind expression. The bind
expression can specify a CFC function, a JavaScript function, a URL, or a string that contains bind parameters. An
animated icon and the text "Loading..." appears while the contents are being fetched. For detailed information on
using the bind attribute and bind expressions, see Using Ajax Data and Development Features in the Developing
ColdFusion Applications.
Example

The following simple example shows how you can use the cfdiv tag. It uses binding to display the contents of a
text input field in an HTML DIV region.
The cfdivtag.cfm file, the main application file, has the following contents.

© 2014 Adobe Systems Incorporated. All rights reserved.

266

Adobe ColdFusion Documentation









 using a div




The divsource.cfm file that defines the contents of the div region has the following code:

Echoing main page input:


#url.InputText#

No input



To test the code, run the cfdivtag.cfm page, enter some text, and tab out of the text box or click outside the text box.
The div region appears with a light blue background and red text, and when you exit the text box, it shows the text
you entered.

© 2014 Adobe Systems Incorporated. All rights reserved.

267

Adobe ColdFusion Documentation

cfdocument
Description

Creates PDF or FlashPaper output from a text block containing CFML and HTML.
Category

Data output tags
Syntax


HTML and CFML code


© 2014 Adobe Systems Incorporated. All rights reserved.

268

Adobe ColdFusion Documentation

Note
You can specify this tag's attributes in an attributeCollection attribute whose value is a
structure. Specify the structure name in the attributeCollection attribute and use the tag's
attribute names as structure keys.

See also

cfdocumentitem, cfdocumentsection, cfform, cfpdf, cfpdfform, cfpresentation, cfprint, cfrepor
t
History

ColdFusion 9: Add ppt support to the srcFile attribute. Added the following attributes to support conversion of a
Word document to PDF or HTML using OpenOffice libraries:
formfields attribute
formsType attribute
openpassword attribute
permissionspassword attribute
pdfa attribute
tagged attribute
ColdFusion 8: Added the following attributes and variables:
bookmark attribute
localUrl attribute
Ability to embed existing PDF forms by using the cfpdfform tag in the cfdocument tag.
ColdFusion determines the MIME type of a source file based on the source filename, if the mimeType attribut
e is not specified.
Ability to pass a PDF variable created with the cfdocument tag as the source for the cfpdf tag.
authPassword, authUser, proxyHost, proxyPassword, proxyPort, proxyUser, and userAgent attr
ibutes
saveAsName attribute
totalsectionpagecount and currentsectionpagenumber scope variables.

ColdFusion MX 7.01: Added the src, srcfile, and mimetype attributes.ColdFusion MX 7: Added this tag.
Attributes

Attribute

Req/Opt

© 2014 Adobe Systems Incorporated. All rights reserved.

Default

Description

269

Adobe ColdFusion Documentation

authPassword

Optional

Password sent to the
target URL for Basic
Authentication. Combined
with username to form a
base64 encoded string
that is passed in the
Authenticate header.
Does not provide support
for Integrated Windows,
NTLM, or Kerebos
authentication.

authUser

Optional

User name sent to the
target URL for Basic
Authentication. Combined
with password to form a
base64 encoded string
that is passed in the
Authenticate header.
Does not provide support
for Integrated Windows,
NTLM, or Kerebos
authentication.

backgroundVisible

Optional

no

Specifies whether the
background prints when
the user prints the
document:
yes: includes the
background when
printing.
no: does not includes
the background when
printing.

bookmark

Optional

no

Specifies whether
bookmarks are created in
the document:
yes: creates
bookmarks.
no: does not create
bookmarks.

encryption

Optional

none

(format="PDF" only)
Specifies whether the
output is encrypted:
128-bit
40-bit
none

© 2014 Adobe Systems Incorporated. All rights reserved.

270

Adobe ColdFusion Documentation

filename

Optional

fontEmbed

Optional

Pathname of a file to
contain the PDF or
FlashPaper output.
If you omit the filename
attribute, ColdFusion
displays the output in the
browser.
yes

Specifies whether
ColdFusion embeds fonts
in the output:
yes: embeds fonts.
no: does not embed
fonts.
selective: embed
sall fonts except Java
fonts and core fonts.

format

Required

Report format:
PDF
FlashPaper

formfields

Optional

yes

This attribute is available
only if you have integrated
OpenOffice with
ColdFusion.A Boolean
value that specifies if form
fields are exported as
widgets or only their fixed
print representation is
exported.

formstype

Optional

FDF

This attribute is available
only if you have integrated
OpenOffice with
ColdFusion.Specifies the
submitted format of a PDF
form. It can be one of the
following values:
FDF
PDF
HTML
XML

© 2014 Adobe Systems Incorporated. All rights reserved.

271

Adobe ColdFusion Documentation

localUrl

Optional

no

Specifies whether to
retrieve image files
directly from the local
drive:
yes: ColdFusion
retrieves image files
directly from the local
drive rather than by
using HTTP, HTTPS, or
proxy.
no: ColdFusion uses
HTTP, HTTPS, or proxy
to retrieve image files
even if the files are
stored locally.
For more information,
see the "Using an
image file URL" section.

marginBottom

Optional

Bottom margin in inches
(default) or centimeters.
To specify the bottom
margin in centimeters,
include the unit=cm attri
bute.

marginLeft

Optional

Left margin in inches
(default) or centimeters.
To specify the left margin
in centimeters, include the
unit=cm attribute.

marginRight

Optional

Right margin in inches
(default) or centimeters.
To specify the right
margin in centimeters,
include the unit=cm attri
bute.

marginTop

Optional

Top margin in inches
(default) or centimeters.
To specify the top margin
in centimeters, include the
unit=cm attribute.

© 2014 Adobe Systems Incorporated. All rights reserved.

272

Adobe ColdFusion Documentation

mimeType

Optional

text/html

MIME type of the source
document. Supported
MIME types are:
text/html
text/plain
application/xml
image/bmp
image/jpeg
image/png
image/gif
If you do not specify this
attribute explicitly,
ColdFusion uses the
filename to determine
the MIME type.

name

Optional

Name of an existing
variable into which the tag
stores the PDF or
FlashPaper output.

openpassword

Optional

This attribute is available
only if you have integrated
OpenOffice with
ColdFusion.Password
required to open a
password-protected
document.

orientation

Optional

portrait

Page orientation:
portrait
landscape

overwrite

Optional

ownerPassword

Optional

© 2014 Adobe Systems Incorporated. All rights reserved.

no

Specifies whether
ColdFusion overwrites an
existing file. Used in
conjunction with the file
name attribute.
(format="PDF" only)
Specifies the owner
password.Cannot be
same as userPassword.

273

Adobe ColdFusion Documentation

pageHeight

Optional

pageType

Optional

Page height in inches
(default) or centimeters.
This attribute is only valid
if pagetype=custom. To
specify page height in
centimeters, include the u
nit=cm attribute.
letter

Page type into which
ColdFusion generates the
report:
legal: 8.5 inches x 14
inches.
letter: 8.5 inches x
11 inches.
A4: 8.27 inches x 11.69
inches.
A5: 5.81 inches x 8.25
inches.
B4: 9.88 inches x 13.88
inches.
B5: 7 inches x 9.88
inches.
B4-JIS: 10.13 inches x
14.31 inches.
B5-JIS: 7.19 inches x
10.13 inches.
custom: custom height
and width. If you specify
custom, also specify the
pageHeight and page
Width attributes, can
optionally specify marg
in attributes and
whether the units are
inches or centimeters.

pageWidth

Optional

© 2014 Adobe Systems Incorporated. All rights reserved.

Page width in inches
(default) or centimeters.
This attribute is only valid
if pageType=custom. To
specify page width in
centimeters, include the u
nit=cm attribute.

274

Adobe ColdFusion Documentation

pdfa

Optional

no

This attribute is available
only if you have integrated
OpenOffice with
ColdFusion.A Boolean
value that specifies if you
need to create a PDF of
type PDF/A-1 (ISO
19005-1:2005) .

permissionpasswrd

Optional

This attribute is available
only if you have integrated
OpenOffice with
ColdFusion.Password
required to access
restricted permissions.
The restricted permissions
are specified using the
permissions attribute.

permissions

Optional

(format="PDF" only)
Sets one or more of the
following permissions:
AllowPrinting
AllowModifyConten
ts
AllowCopy
AllowModifyAnnota
tions
AllowFillIn
AllowScreenReader
s
AllowAssembly
AllowDegradedPrin
ting
Separate multiple
permissions with
commas.

proxyHost

Optional

Host name or IP address
of a proxy server to which
to send the request.

proxyPassword

Optional

Password required by the
proxy server.

proxyPort

Optional

proxyUser

Optional

© 2014 Adobe Systems Incorporated. All rights reserved.

80

The port to connect to on
the proxy server.
User name to provide to
the proxy server.

275

Adobe ColdFusion Documentation

scale

Optional

Calculated by ColdFusion

Scale factor as a
percentage. Use this
option to reduce the size
of the HTML output so
that it fits on that paper.
Specify a number less
than 100.

saveAsName

Optional

(format="PDF" only)
The filename that appears
in the SaveAs dialog
when a user saves a PDF
file written to the browser.

src

Optional

URL or the relative path to
the web root. You cannot
specify both the src and
srcfile attributes. The
file must be in a
browser-writable format
such as, HTML, HTM,
BMP, PNG, and so on.

srcfile

Optional

Absolute path of a file that
is on the server. You
cannot specify both the s
rc and srcfile attribute
s. The file must be a PPT
file, a Word file, or be in a
browser-writable format
such as, HTML, HTM,
BMP, PNG, and so on.

tagged

Optional

no

This attribute is available
only if you have integrated
OpenOffice with
ColdFusion.A Boolean
value that determines if
the PDF is created using
the Tagged PDF tag.

unit

Optional

in

Default unit for the pageH
eight, pageWidth, and
margin attributes:
in: inches.
cm: centimeters.

© 2014 Adobe Systems Incorporated. All rights reserved.

276

Adobe ColdFusion Documentation

userAgent

Optional

userPassword

Optional

ColdFusion

Text to put in the HTTP
User-Agent request
header field. Used to
identify the request client
software.
(format="PDF" only)
Specifies a user
password.Cannot be
same as ownerPasswor
d.

Usage

Use the cfdocument tag to render HTML and CFML output into PDF or FlashPaper format. ColdFusion does not
return HTML and CFML outside of the   pair.
The cfdocument tag can render HTML that supports the following standards:
HTML 4.01
XML 1.0
DOM Level 1 and 2
CSS1 and CSS2 (For more information, see the "Supported CSS styles" section).
The cfdocument tag does not support the Internet Explorer-specific HTML generated by Microsoft
Word.Use the following syntax in the filenameattribute to specify an in-memory file, which is not written to
disk. In-memory files speed processing of transient data.

ram:///filepath

The filepath can include directories, for example ram:///petStore/tracking/ordersummary.pdf.
Create the directories in the path before you specify the file. For more information on using in-memory files,
see Working with in-memory files in the Developing ColdFusion Applications.
You can use the src, srcfile, and mimeType attributes to create PDF or FlashPaper output from a
specified file or URL. Use the src and srcfile attributes instead of using the cfhttp tag to display the
result in the cfdocument tag. When you specify the src or srcfile attributes, do not include any other
content inside the cfdocument tag: ColdFusion ignores the additional content. The PDF or FlashPaper
document returned by the cfdocument tag overwrites any previous HTML in the input stream and ignores
any HTML after the  tag.
You cannot embed a cfreport tag in a cfdocumenttag.
Note
If you notice that the header text is cropped in the cfdocument tag output, increase the
value of the marginTop attribute.

Supported CSS styles

The cfdocument tag supports the following CSS styles:

© 2014 Adobe Systems Incorporated. All rights reserved.

277

Adobe ColdFusion Documentation

background

background-attachment

background-color

background-image

background-position

background-repeat

border

border-bottom

border-bottom-color

border-bottom-style (solid
border only)

border-bottom-width

border-color

border-left

border-left-color

border-left-style (solid
border only)

border-left-width

border-right

border-right-color

border-right-style (solid
border only)

border-right-width

border-spacing

border-style (solid border
only)

border-top

border-top-color

border-top-style (solid
border only)

border-top-width

border-width

bottom

clear

clip

color

content (strings, counters
only)

counter-increment

counter-reset

cursor

display

float

font

font-family

font-size

font-style

font-weight

height

left

letter-spacing

line-height

list-style-type

margin

margin-bottom

margin-left

margin-right

margin-top

outline

outline-color

outline-style (solid, dotted,
dashed only)

outline-width

padding

padding-bottom

padding-left

padding-right

padding-top

page-break-after

page-break-before

page-break-inside

position

right

text-align (left, right, and
center)

text-decoration

text-indent

top

unicode-bidi

vertical-align

visibility

white space (normal,
nowrap only)

width

z-index

Using an image file URL

© 2014 Adobe Systems Incorporated. All rights reserved.

278

Adobe ColdFusion Documentation

For optimal performance and reliability, Adobe recommends that you specify a local file URL for images stored on
the server. In the following example, the cfdocument tag requests the server for images over HTTP even though
the image files are stored locally:




bird



fruit



rose





Also, in some applications, the browser displays a Red X image error instead of the image in the browser. For better
performance, and to avoid Red X image errors, set the localUrl attribute to yes:




bird



fruit



rose





Scope variables

When you use the cfdocument tag, ColdFusion creates a scope named cfdocument. This scope contains the
following variables:
currentpagenumber
totalpagecount
totalsectionpagecount
currentsectionpagenumber
ColdFusion lets you use the scope variables inside any expression within a cfdocumentitem tag. For
example, you can use the currentpagenumbervariable to place the section name on even pages and the

© 2014 Adobe Systems Incorporated. All rights reserved.

279

Adobe ColdFusion Documentation

chapter name on odd pages in the header, as follows:




#cfdocument.totalpagecount#

#cfdocument.currentpagenumber#


...


If you define the cfdocumentsection tag within the cfdocument tag, then specify the totalsectionpagecou
ntvariable as follows:




#cfdocument.totalpagecount#

#cfdocument.currentpagenumber#

cfdocument.currentpagenumber
:#cfdocument.currentpagenumber#
cfdocument.totalpagecount :#cfdocument.totalpagecount#
cfdocument.totalsectionpagecount
:#cfdocument.totalsectionpagecount#
cfdocument.currentsectionpagenumber
:#cfdocument.currentsectionpagenumber#



if#cfdocument.totalpagecount#

else#cfdocument.currentpagenumber#


Example Text



Bookmarks

ColdFusion 9 supports bookmarks. In the cfdocument tag, set the bookmark attribute to yes. Then specify the
bookmark name for each cfdocumentsection tag.
The following example shows how to specify bookmarks for document sections:

© 2014 Adobe Systems Incorporated. All rights reserved.

280

Adobe ColdFusion Documentation











Example

Example 1



This is a document rendered by the cfdocument tag.


Name
Role


Bill
Lead


Susan
Principal Writer


Adelaide
Part Time Senior Writer


Thomas
Full Time for 6 months


Michael
Full Time for 4 months




Example 2

© 2014 Adobe Systems Incorporated. All rights reserved.

281

Adobe ColdFusion Documentation





#cfdocument.currentsectionpagenumber# of
#cfdocument.totalsectionpagecount#




#cfdocument.currentpagenumber# of
#cfdocument.totalpagecount#



Section 1

Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor
incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud
exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute
irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla
pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia
deserunt mollit anim id est laborum.




Section 2

Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor
incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud
exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute
irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla
pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia
deserunt mollit anim id est laborum.




Section 3

Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor
incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud
exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute
irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla
pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia
deserunt mollit anim id est laborum.





© 2014 Adobe Systems Incorporated. All rights reserved.

282

Adobe ColdFusion Documentation

cfdocumentitem
Description

Specifies action items for a PDF or FlashPaper document created by the cfdocument tag. Action items include the
following:
header
footer
pagebreak
Category

Data output tags
Syntax





Note
You can specify this tag's attributes in an attributeCollection attribute whose value is a
structure. Specify the structure name in the attributeCollection attribute and use the tag's
attribute names as structure keys.

See also

cfreport, cfdocument, cfdocumentsection
History

ColdFusion 9: Added the evalAtPrint attribute.
ColdFusion 8: Added support for cfdocument.currentpagenumber, cfdocument.totalpagecount
cfdocument.totalsectionpagecount, and cfdocument.currentsectionpagenumber scopevariables.
ColdFusion MX 7.01: Added the src, srcfile, and mimetype attributes.ColdFusion MX 7: Added this tag.
Attributes

Attribute

Req/Opt

© 2014 Adobe Systems Incorporated. All rights reserved.

Default

Description

283

Adobe ColdFusion Documentation

Required

type

Specifies the action:
pagebreak: starts a
new page at the
location of the tag.
header: uses the text
between the  and  tags as
the running header.
footer: uses the text
between the  and  tags as
the running footer.

evalAtPrint

Optional

false

A Boolean value that
determines if the contents
of the cfdocumentitem t
ag body has to be
evaluated at the time of
printing the document.
true: evaluates the
contents of the cfdocu
mentitem tag body
only at the time of
printing the document.
false: evaluates the
contents of the cfdocu
mentitem tag body
immediately.

Usage

Use the evalAtPrint tag to evaluate the contents of the document before printing and to also accept additional
attributes. Use the cfdocumentitem tag to control the formatting of a PDF or FlashPaper report. This tag must be
wrapped inside a   pair.
Write code for one cfdocumentitem tag for each page break, running header, or running footer. ColdFusion has
added support for cfdocument scope variables within the cfdocumentitem tag. You can use the cfdocument s
cope variable, cfdocument.currentpagenumber, to display the current page number in a header or footer. You
can also use {{cfdocument.totalpagecoun}}t to display the total number of pages, for example:

...

SELECT parkname, suptmgr from parks


National Parks Report


Page #cfdocument.currentpagenumber# of
#cfdocument.totalpagecount#

Park list



Park
Manager


#parkname#
#suptmgr#





© 2014 Adobe Systems Incorporated. All rights reserved.

285

Adobe ColdFusion Documentation

cfdocumentsection
Description

Divides a PDF or FlashPaper document into sections. By using this tag in conjunction with a cfdocumentitem tag,
each section can have unique headers, footers, and page numbers.
Category

Data output tags
Syntax



HTML, CFML, and cfdocumentitem tags



Note
You can specify this tag's attributes in an attributeCollection attribute whose value is a
structure. Specify the structure name in the attributeCollection attribute and use the tag's
attribute names as structure keys.

See also

cfreport, cfdocument, cfdocumentitem
History

ColdFusion 8: Added the name, authPassword, authUser, and userAgent attributes.ColdFusion MX 7.01:
Added the src, srcfile, and mimetype attributes.ColdFusion MX 7: Added this tag and the margintop, margin
bottom, marginleft, marginright attributes.
Attributes

Attribute

Req/Opt

© 2014 Adobe Systems Incorporated. All rights reserved.

Default

Description

286

Adobe ColdFusion Documentation

authPassword

Optional

Password sent to the
target URL for Basic
Authentication. Combined
with username to form a
base64 encoded string
that is passed in the
Authenticate header.
Does not provide support
for Integrated Windows,
NTLM, or Kerebos
authentication.

authUser

Optional

User name sent to the
target URL for Basic
Authentication. Combined
with password to form a
base64 encoded string
that is passed in the
Authenticate header.
Does not provide support
for Integrated Windows,
NTLM, or Kerebos
authentication.

marginBottom

Optional

Bottom margin in inches
(default) or centimeters.
To specify the bottom
margin in centimeters,
include the unit="cm" at
tribute in the parent cfdo
cument tag.

marginLeft

Optional

Left margin in inches
(default) or centimeters.
To specify the left margin
in centimeters, include the
unit="cm" attribute in
the parent cfdocument t
ag.

marginRight

Optional

Right margin in inches
(default) or centimeters.
To specify the right
margin in centimeters,
include the unit="cm" at
tribute in the parent cfdo
cument tag.

© 2014 Adobe Systems Incorporated. All rights reserved.

287

Adobe ColdFusion Documentation

marginTop

Optional

mimeType

Optional

Top margin in inches
(default) or centimeters.
To specify the top margin
in centimeters, include the
unit="cm" attribute in
the parent cfdocument t
ag.
text/html

MIME type of the source
document. Supported
MIME types are:
text/html
text/plain
application/xml
image/jpeg
image/png
image/gif
If you do not specify this
attribute explicitly,
ColdFusion uses the
filename to determine
the MIME type.

name

Optional

Bookmark name for the
section.

src

Optional

URL or the relative path to
the web root. You cannot
specify both the src and
srcfile attributes.

srcfile

Optional

Absolute path of an
on-disk or in-memory file
that is on the server. You
cannot specify both the s
rc and srcfile attribute
s.

userAgent

Optional

ColdFusion

Text to put in the HTTP
User-Agent request
header field. Used to
identify the request client
software.

Usage

Use the cfdocumentsection tag to divide a report into sections. Within each cfdocumentsection tag, you can
use one or more cfdocumentitem tags to specify unique headers and footers for each section.
When using cfdocumentsection, ColdFusion ignores HTML and CFML not enclosed within cfdocumentsecti
on tags.

© 2014 Adobe Systems Incorporated. All rights reserved.

288

Adobe ColdFusion Documentation

The margin attributes override margins specified in previous sections or in the parent cfdocument tag. If you
specify margin attributes, the units are controlled by the unit attribute of the parent cfdocument tag; the unit attr
ibute has a default value of inches. The cfdocumentsection tag forces a page break so that each section starts
on a new page.ColdFusion has added the name attribute to support bookmarks. Bookmarks defined at the documen
tsection tag level are children of the cfdocument root.
Example

Example 1


SELECT Emp_ID, firstname, lastname, e.dept_id, salary, d.dept_name
FROM employee e, departmt d
WHERE e.dept_id = d.dept_id
ORDER BY d.dept_name





Salary Report


Page #cfdocument.currentpagenumber#

#dept_name#








Employee
Salary



#empSalary.lastname#, #empSalary.firstname#


#DollarFormat(empSalary.salary)#



Total
#DollarFormat(deptTotal)#






© 2014 Adobe Systems Incorporated. All rights reserved.

289

Adobe ColdFusion Documentation

Example 2: Bookmarks











© 2014 Adobe Systems Incorporated. All rights reserved.

290

Adobe ColdFusion Documentation

cfdump
Description

Use the cfdump tag to get the elements, variables, and values of most kinds of ColdFusion objects. Useful for
debugging. You can display the contents of simple and complex variables, objects, components, user-defined
functions, and other elements. The cfdump now shows component properties defined by cfproperty when you
dump a CFC. A new key called PROPERTIES has been added in the component dump, which is expanded, by
default. The text format of cfdump also provides this information.
Category

Debugging tags, Variable manipulation tags
Syntax


label = "text"
metainfo = "yes|no"
top = "number of rows|number of levels"
show = "columns|keys"
hide = "columns|keys"
keys = "number of keys to display for structures"
expand = "yes|no"
showUDFs = "yes|no">

Note
You can specify this tag's attributes in an attributeCollection attribute whose value is a
structure. Specify the structure name in the attributeCollection attribute and use the tag's
attribute names as structure keys.

See also

cfcookie, cfparam, cfsavecontent, cfschedule, cfset, cftimer, cfwddx
History

ColdFusion 9: Added the attribute abort.
ColdFusion 8: Added the show, format, hide, keys, metainfo, output, and showUDFs attributes.
ColdFusion MX 7: Added the top attribute.
ColdFusion MX 6.1: Added the ability to dump COM objects; it displays the methods and Get and Put
properties typeinfo information for the object.
Attributes

Attribute

Req/Opt

© 2014 Adobe Systems Incorporated. All rights reserved.

Default

Description

291

Adobe ColdFusion Documentation

var

Required

Variable to display.
Enclose a variable name
in number signs. These
kinds of variables yield
meaningful cfdump outpu
t:
array
CFC
COM object
file object
Java object
simple
query
structure
UDF
wddx
xml

expand

Optional

yes

format

Optional

text

Use with the output attri
bute to specify whether to
save the results of a cfdu
mp to a file in text or
HTML format.

hide

Optional

all

For a query, this is a
column name or a
comma-delimited list of
column names. For a
structure, this is a key or a
comma-delimited list of
keys.
If you specify a structure
element that doesn't exist,
ColdFusion ignores it and
does not generate an
error.

keys

Optional

9999

For a structure, the
number of keys to display.

label

Optional

© 2014 Adobe Systems Incorporated. All rights reserved.

yes: in Internet
Explorer and Mozilla,
expands views.
no: contracts expanded
views.

A string; header for the
dump output. Ignored if
the value of the var
attribute is a simple types.

292

Adobe ColdFusion Documentation

metainfo

Optional

yes for query{{no}} for
persistence CFCs

For use with queries and
persistence CFCs.
Includes information about
the query in the cfdump
results, including whether
the query was cached, the
execution time, and the
SQL. Specify metainfo=
"no" to exclude this
information from the query
result. For persistence
CFCs, if metainfo="yes
", returns property
attributes such as getters
and setters.

output

Optional

browser

Where to send the results
of cfdump. The following
values are valid:
browser
console
filename
The filename must
include the full
pathname of the file.
You can specify an
absolute path, or a path
that is relative to the
ColdFusion temporary
directory. You can use
the GetTempDirector
y() function to
determine the
ColdFusion temporary
directory.

show

Optional

all

For a query, this is a
column name or a
comma-delimited list of
column names. For a
structure, this is a key or a
comma-delimited list of
keys.

showUDFs

Optional

yes

yes: includes UDFs,
with the methods
collapsed.
no: excludes UDFs.

© 2014 Adobe Systems Incorporated. All rights reserved.

293

Adobe ColdFusion Documentation

top

Optional

9999

The number of rows to
display. For a structure,
this is the number of
nested levels to display.

abort

Optional

false

If this attribute is set to
"true", it stops processing
the current page at the tag
location.

Usage

The expand/contract display capability is useful when working with large structures, such as XML document objects,
structures, and arrays.
To display a construct, use code such as the following, in which myDoc is a variable of type XmlDocument:





The tag output is color-coded according to data type.
If a table cell is empty, this tag displays "empty string".
Example




myfile = FileOpen("c:\temp\test1.txt", "read");

myfile refers to:


© 2014 Adobe Systems Incorporated. All rights reserved.

294

Adobe ColdFusion Documentation

cfelse
Description

Used as the last control block in a cfif tag block to handle any case not identified by the cfif tag or a cfelseif
tag.
Category

Flow-control tags
Syntax


HTML and CFML tags
HTML and CFML tags

HTML and CFML tags




See also

cfif, cfelseif, cfabort, cfbreak, cfexecute, cfexit, cflocation, cfloop, cfswitch, cfthrow, cftr
y
Usage

If the values of the expressions in the containing cfif tag and all cfelseif tags are no, ColdFusion processes the
code between this tag and the cfif end tag. This tag must be inside a cfif tag block. It does not require an end
tag. For more information and an example, see cfif.

© 2014 Adobe Systems Incorporated. All rights reserved.

295

Adobe ColdFusion Documentation

cfelseif
Description

Used as a control block in a cfif tag block to handle any case not identified by the cfif tag or a cfelseif tag.
Category

Flow-control tags
Syntax


HTML and CFML tags 
HTML and CFML tags

HTML and CFML tags 

See also

cfif, cfelse, cfabort, cfbreak, cfexecute, cfexit, cflocation, cfloop, cfswitch, cfthrow, cftry
Usage

If the value of the expression in this tag is yes, and the values of the expressions in the containing cfif tag and
preceding cfelseif tags are no, ColdFusion processes the code between this tag and a following cfelseif or c
felse tag, or the cfif end tag and then skips to the code following the cfif end tag. Otherwise, ColdFusion skips
the code.
This tag must be inside a cfif tag block. It does not require an end tag. For more information and an example, see
cfif.

© 2014 Adobe Systems Incorporated. All rights reserved.

296

Adobe ColdFusion Documentation

cferror
Description

Displays a custom HTML page when an error occurs. This lets you maintain a consistent look and feel among an
application's functional and error pages.
Category

Exception handling tags, Extensibility tags, Application framework tags
Syntax



Note
You can specify this tag's attributes in an attributeCollection attribute whose value is a
structure. Specify the structure name in the attributeCollection attribute and use the tag's
attribute names as structure keys.

See also

cfrethrow, cfthrow, cftry, Handling Errors in the Developing ColdFusion Applications.
History

ColdFusion MX: Deprecated the monitor option of the exception attribute. It might not work, and might cause an
error, in later releases.
Attributes

Attribute

Req/Opt

template

Required

© 2014 Adobe Systems Incorporated. All rights reserved.

Default

Description
Relative path to the
custom error page. (A
ColdFusion page was
formerly called a
template.)

297

Adobe ColdFusion Documentation

type

Required

Type of error that the
custom error page
handles. The type also
determines how
ColdFusion handles the
error page. For more
information, see Specifyin
g a custom error page in
Specifying custom error
messages with the cferror
tag in the Developing
ColdFusion Applications.
exception: an
exception of the type
specified by the excep
tion attribute.
validation: errors
recognized by
server-side type
validation.
request: any
encountered error.

© 2014 Adobe Systems Incorporated. All rights reserved.

298

Adobe ColdFusion Documentation

exception

Optional

any

Type of exception that the
tag handles:
application:
application exceptions.
database: database
exceptions.
template: ColdFusion
page exceptions.
security: security
exceptions.
object: object
exceptions.
missingInclude:
missing include file
exceptions.
expression:
expression exceptions.
lock: lock exceptions.
custom_type:
developer-defined
exceptions, defined in
the cfthrow tag.
any: all exception
types.
For more information on
exception types, see cf
try.

mailTo

Optional

An e-mail address. This
attribute is available on
the error page as the
variable error.mailto.
ColdFusion does not
automatically send
anything to this address.

Usage

Use this tag to provide custom error messages for pages in an application. This lets you maintain a consistent look
and feel within the application, even when errors occur. You generally embed this tag in your Application CFC or
Application.cfm file to specify error-handling responsibilities for an entire application. You must put it in one of these
files if you specify type="validation"; ColdFusion ignores it on any other page. The cftry and cfcatch tags
provide a more interactive way to handle ColdFusion errors within a ColdFusion page than the cferror tag, but the
cferror tag is a good safeguard against general errors. To ensure that error pages display successfully, avoid
using the cfencode utility to encode pages that include the cferror tag.
Page types

The following table describes the types of errors you can specify and code you can use on the pages that handle
these error type:

© 2014 Adobe Systems Incorporated. All rights reserved.

299

Adobe ColdFusion Documentation

Page type

Description

Use

Exception

Dynamically invoked by the CFML
language processor when it detects
an unhandled exception
condition.Uses the full range of
CFML tags. Error variables must be
in cfoutput tags.

Can handle specific exception types
or display general information for
exceptions.

Request

Includes the error variables
described in the Error variables
section. Cannot include CFML tags,
but you can display values of the
error variables by enclosing them in
number signs (#), as in #error.Ma
ilTo#.

Use as a backup error handler to
other error handling methods,
including exception type.

Validation

Handles data input validation errors
that occur when submitting a form
that uses hidden form-field
validation or onSubmit validation.
Cannot include CFML tags, but you
can display values of the error
variables by enclosing them in
number signs (#), as in #Error.In
validFields#.Specify the
validation error handler in the
Application.cfc or Application.cfm
file.

Handles hidden form-field or
onSubmit format validation errors
only.

Error variables

The exception-handling page specified in the cferror tag template attribute contains one or more error
variables. ColdFusion substitutes the value of the error variable when an error displays.
The following table lists error variables:
Page type

Error variable

Description

Validation only

error.validationHeader

Validation message header text.

error.invalidFields

Unordered list of validation errors.

error.validationFooter

Validation message footer text.

error.diagnostics

Detailed error diagnostics from
ColdFusion.

error.mailTo

E-mail address (same as value in c
ferror.MailTo).

Request and Exception

© 2014 Adobe Systems Incorporated. All rights reserved.

300

Adobe ColdFusion Documentation

Exception only

error.dateTime

Date and time when error occurred.

error.browser

Browser that was running when
error occurred.

error.remoteAddress

IP address of remote client.

error.HTTPReferer

Page from which client accessed
link to page where error occurred.

error.template

Page executing when error
occurred.

error.generatedContent

The content generated by the page
up to the point where the error
occurred.

error.queryString

URL query string of client's request.

error.message

Error message associated with the
exception.

error.rootCause

The root cause of the exception.
This structure contains the
information that is returned by a cf
catch tag. For example, for a
database exception, the SQL
statement that caused the error is in
the error.RootCause.Sql variable.
For Java exceptions, this variable
contains the Java servlet exception
reported by the JVM as the cause
of the "root cause" of the exception.

error.tagContext

Array of structures containing
information for each tag in the tag
stack. The tag stack consists of
each tag that is currently open.

error.type

Exception type.

Note
If type = "exception", you can substitute the prefix cferror for Error; for example, cfer
ror.diagnostics, cferror.mailTo, or cferror.dateTime.

Example

© 2014 Adobe Systems Incorporated. All rights reserved.

301

Adobe ColdFusion Documentation

cferror Example




select * from nothing







We're sorry -- An Error Occurred

If you continue to have this problem, please contact #error.mailTo#
with the following information:


Your Location: #error.remoteAddress#
Your Browser: #error.browser#
Date and Time the Error Occurred: #error.dateTime#
Page You Came From: #error.HTTPReferer#
Message Content:
#error.diagnostics#


© 2014 Adobe Systems Incorporated. All rights reserved.

302

Adobe ColdFusion Documentation

cfexchangecalendar
Description

Creates, deletes, modifies, gets, and responds to Microsoft Exchange calendar events, and gets calendar event
attachments.
History

ColdFusion 11: Added three new optional attributes to the cfexchangecalendar tag for managing secondary
calendars. These attributes are applicable for get and create actions only and valid for exchange server version
starting from 2010. Secondary calendars can be specified in the exchangecalendar tag either using secondary
calendar folder ID or using the calendar folder path
ColdFusion 10: getUserAvailability, getRooms, getRoomsList
Added the attribute serverVersion.
ColdFusion 8: Added this tag.
Category

Communications tags
Syntax

create

delete

deleteAttachments

get

getAttachments

generateUniqueFilenames = "no|yes"
getRooms

getRoomsList

getUserAvailability

modify

respond

notify = "yes|no">

Note
For all actions, see cfexchangeconnection for additional attributes that you use if you do not
specify the connection attribute. If you omit the connection attribute, create a temporary
connection by specifying cfexchangeconnection tag attributes in the cfexchangecalenda
r tag. In this case, ColdFusion closes the connection when the tag completes. For details, see
the cfexchangeconnection tag open action.

Note
You can specify this tag's attributes in an attributeCollection attribute whose value is a
structure. Specify the structure name in the attributeCollection attribute and use the tag's
attribute names as structure keys.

See also

cfexchangeconnection, cfexchangecontact, cfexchangefilter, cfexchangemail, cfexchangetask,
Working with meetings and appointments in the Developing ColdFusion Applications
Attributes

Attribute

Action

Req/Opt

action

N/A

Required

Default

Description
The action to take.
Must be one of the
following values:
create
delete
deleteAttachm
ents
get
getAttachment
s
getRooms
getRoomsList
getUserAvailabilit
y
modify
respond

© 2014 Adobe Systems Incorporated. All rights reserved.

305

Adobe ColdFusion Documentation

attachmentPath

getAttachments

Optional

The filepath of the
on-disk or
in-memory directory
in which to put the
attachments. If an
on-disk directory
does not exist,
ColdFusion creates
it.
Note: If you omit
this attribute,
ColdFusion does not
save any
attachments. If you
specify a relative
path, the path root is
the ColdFusion
temporary directory,
which is returned by
the GetTempDirec
tory function.

attendees

getUserAvailabi
lity

Required

Comma-separated
list of all attendees.

connection

all

Optional

The name of the
connection to the
Exchange server, as
specified in the cfe
xchangeconnecti
on tag. If you omit
this attribute, you
must create a
temporary
connection by
specifying
cfexchangeconnecti
on tag connection
attributes in the cfe
xchangecalendar
tag.

© 2014 Adobe Systems Incorporated. All rights reserved.

306

Adobe ColdFusion Documentation

dataRequestType

getUserAvailabi
lity

Required

emailAddress

getRooms

Optional

Defines the Simple
Mail Transfer
Protocol (SMTP)
address of a
mailbox user.

endDate

getUserAvailabi
lity

Required

A string that
ColdFusion can
interpret as a
date-time value.

event

createmodify

Required

A reference to the
structure that
contains the event
properties to be set
or changed, and
their values. Specify
this attribute in
number signs (#).
The event attribute
also supports the
categories key.
For more
information on the
event structure, see
Usage.

© 2014 Adobe Systems Incorporated. All rights reserved.

freeBusy:
Returns an array
of availability
details.
Suggestions:
Returns an array
of struct that
contains
suggestion
details.
freeBusyandSu
ggestions:
Returns both the
array of
suggestions and
an array of atten
deeavailabili
ty.
See the sections
on suggestion
struct and atten
deeavailabili
ty struct for
details.

307

Adobe ColdFusion Documentation

getOccurrence

TrueFalse

Optional

generateUnique
Filenames

getAttachments

Optional

message

deleterespond

Optional

© 2014 Adobe Systems Incorporated. All rights reserved.

If True, retrieves all
occurrences of a
recurring event
between specified s
tartDate and End
Date values and
also, any single
events. You can not
use cfExchangeFi
lter tag if you
specify
getOccurrence as
True.
no

A Boolean value
that specifies
whether to generate
unique filenames if
multiple attachments
have the same
filenames. If two or
more attachments
have the same
filename and this
option is yes,
ColdFusion appends
a number to the
filename body
(before the
extension) of any
conflicting
filenames. Thus, if
three attachments
have the name
myfile.txt,
ColdFusion saves
the attachments as
myfile.txt,
myfile1.txt, and
myfile2.txt.
The text of an
optional message to
send in the
response or deletion
notification.

308

Adobe ColdFusion Documentation

name

getAttachments

Required

The name of the
ColdFusion query
variable that
contains the
retrieved events or
information about
the attachments that
were retrieved. For
more information on
the returned data,
see Usage.

getUserAvailabi
lity
getRoomsListget
Rooms

notify

deleterespond

Optional

responseType

respond

Required

true

Boolean value that
specifies whether to
notify others of the
changes made to
the event.
Must be one of the
following values:
accept
decline
tentative

result

create

© 2014 Adobe Systems Incorporated. All rights reserved.

Optional

The name of a
variable that
contains the UID of
the event that is
created. You use
the UID value in the
uid attribute of
actions other than c
reate to identify
the event to be
acted on.

309

Adobe ColdFusion Documentation

Optional

serverVersion

2007

Specifies the
Microsoft Exchange
Server version. The
values are:
2003
2007
2010
If you do not
specify the
details, 2007 is
taken by default.
The value you
specify overrides
the value that you
specify at the
application level.

startDate

getUserAvailabi
lity

Required

A string that
ColdFusion can
interpret as a
date-time value.

uid

delete

Required

Case-sensitive
Exchange UID value
or values that
uniquely identify the
event or events on
which to perform the
action. For the dele
te action, this
attribute can be a
comma-delimited list
of UID values. The d
eleteAttachment
s, getAttachment
s, modify, and res
pond actions allow
only a single UID
value.

Optional

Specify the calendar
folder ID from which
the calendar items
need to be
managed. If the
folder ID is not a
valid calendar, an
error will be
reported.

getAttachments
modify
respond

folderid

© 2014 Adobe Systems Incorporated. All rights reserved.

310

Adobe ColdFusion Documentation

folderpath

Optional

Full path to the
calendar folder in
the mailbox store.
Path delimiter also
can be specified in
the tag by using the
pathdelimiter
attribute.
If both folderid and
folderpath are not
specified,
cfexchangecalendar
tag manages the
default user
calendar. If both
folderid and
folderpath are
specfied, folderid
will be considered.

pathdelimiter

Optional

/

Lets you specify the
delimiter that is used
to separate the
folders in the
folderpath attribute.

Usage

The cfexchangecalendar tag manages calendar events on the Exchange server. Use the cfexchangecalend
ar to do the following actions:
Create an appointment or meeting event. You can create all-day events.
Delete one or more events.
Get one or more events that conform to an optional set of filter specifications, such as the subject, sender or
recipient ID, time received, and so on.
Get the attachments for a specific event.
Modify an existing event.
Respond to an event.
To use this tag, you must have a connection to an Exchange server. If you are using multiple tags that
interact with the Exchange server, such as if you are creating several contact records, use the cfexchangec
onnection tag to create a persistent connection. Then specify the connection identifier in each cfexchang
ecalendar tag, or in any other ColdFusion Exchange tag, if you are also accessing tasks, contacts, or mail.
Doing this eliminates the overhead of creating and closing the connection for each tag. Alternatively, you can
create a temporary connection that lasts only for the time that ColdFusion processes the single cfexchange
calendar tag. To do this, specify the connection attributes directly in the cfexchangecontact tag. For
details on the connection attributes, see the cfexchangeconnectiontag.
Note
To create an Exchange calendar appointment, create a calendar event and do not specify
any required or optional attendees.

© 2014 Adobe Systems Incorporated. All rights reserved.

311

Adobe ColdFusion Documentation

The create action

When you specify the create action, the event attribute must specify a structure that contains the information that
defines the events. The structure can have the following entries:
Element

Default

Description

AllDayEvent

no

A Boolean value that indicates
whether this is an all-day event.

Attachments

One or more paths to the files to
send as attachments. Separate
filepaths with semicolons (;) for
Windows, and colons (:) for UNIX
and Linux. Paths to the attachments
must be absolute.
If you specify one or more
attachments for a modify action,
the specified attachments are
added to any existing attachments;
the pre-existing attachments are not
deleted.

Categories

A comma-delimited list of
categories. The filter searches for
events that match all the categories
in the list.

Duration

The duration of the event in
minutes.

EndTime

The end time of the event, in any
valid ColdFusion date-time format.

Importance

normal

One of the following values:
high
normal
low.

IsRecurring

A Boolean value that indicates
whether this event repeats. If yes
, specify a RecurrenceType ele
ment and elements to specify the
recurrence details. For
information on the recurrence
fields, see the next table.

Location

© 2014 Adobe Systems Incorporated. All rights reserved.

A string that specifies the location of
the event.

312

Adobe ColdFusion Documentation

Message

A string that contains a message
about the event. The string can
include HTML formatting.

OptionalAttendees

A comma-delimited list of mail IDs.

Organizer

A string that specifies the name of
the meeting organizer.

Reminder

The time, in minutes before the
event, at which to display a
reminder message.

RequiredAttendees

A comma-delimited list of mail IDs.

Resources

A comma-delimited list of mail IDs
for Exchange scheduling resources,
such as conference rooms and
display equipment.
The valid values are normal, com
pany-confidential, personal,
and private.

Sensitivity

StartTime

The start time of the event, in any
valid ColdFusion date-time format.
If you specify a date and time in this
attribute and specify a YEARLY Rec
urrenceType with no other
recurrence attributes, the event
recurs yearly at the day and time
specified in this attribute.

Subject

A string that describes the event
subject.

The following table lists the elements that you use to specify the event recurrence if you set the IsRecurring field
to a yes value. For a detailed description of how to specify event recurrence, see Specifying Calendar recurrence in
Working with meetings and appointments in the Developing ColdFusion Applications.
Element

Type

© 2014 Adobe Systems Incorporated. All rights reserved.

Default

Description

313

Adobe ColdFusion Documentation

RecurrenceType

all

DAILY

Used only if the structure
has a yes IsRecurring
element. Must be one of
the following values:
DAILY
WEEKLY
MONTHLY
YEARLY

RecurrenceNoEndDate

all

RecurrenceCount

all

The number of times the
event recurs. Cannot be
used with RecurrenceEn
dDate or RecurrenceNo
EndDate.

RecurrenceEndDate

all

The date of the last
recurrence. Cannot be
used with RecurrenceCo
unt or RecurrenceNoEn
dDate.

RecurrenceFrequency

DAILY, WEEKLY, MONTHL
Y

RecurEveryWeekDay

DAILY

© 2014 Adobe Systems Incorporated. All rights reserved.

yes

1

Boolean value; if yes, the
event recurs until you
change or delete the
event. Cannot be used
with RecurrenceCount
or RecurrenceEndDate.

The frequency of the
recurrence in days,
weeks, or months,
depending on the type.
For example, for DAILY re
currence, a Recurrence
Frequency of 3
schedules the event every
three days.
The recurrence of the
event on every week day,
but not on Saturday or
Sunday. Cannot be used
with RecurrenceFreque
ncy.

314

Adobe ColdFusion Documentation

RecurrenceDays

WEEKLY

The day or days of the
week on which the event
occurs. Must be one or
more of the following
values in a
comma-delimited list:MON,
TUE, WED, THU, FRI, SAT,
{{SUN}}If you omit this
field for a weekly
recurrence, the event
recurs on the day of the
week that corresponds to
the specified start date.

RecurrenceDay

MONTHLY, YEARLY

The day of the week on
which the event occurs.
Must be one of the
following values:
MON
TUE
WED
THU
FRI
SAT
SUN

RecurrenceWeek

MONTHLY, YEARLY

The week of the month or
year on which the event
recurs. The valid values
are:
first
second
third
fourth
last

RecurrenceMonth

YEARLY

The month of the year on
which the event recurs.
The valid values are JAN,
FEB, MAR, APR, MAY, JUN,
JUL, AUG, SEP, OCT, NOV,
and DEC.

The delete action

When you specify the delete action, specify a uid attribute with a comma-delimited list of one or more Exchange
UIDs that identify the events to delete. Use the get action, with an appropriate filter expression, to determine the
UID values to specify.
If all UIDs that you specify are invalid, the cfexchangecalendar tag generates an error. If at least one UID is
valid, the tag ignores any invalid UIDs and deletes the items specified by the valid UID.

© 2014 Adobe Systems Incorporated. All rights reserved.

315

Adobe ColdFusion Documentation
The get action

When you specify the get action, use child cfexchangefilter tags to specify the messages to get. For detailed
information on filters, see cfexchangefilter.
When the tag completes processing, the query object specified by the name attribute contains one record for each
retrieved message. Each record has the following columns:
AllDayEvent

Duration

EndTime

From

HasAttachment

HtmlMessage

Importance

IsRecurring

Location

Message

OptionalAttendees

Organizer

Reminder

RequiredAttendees

Resources

Sensitivity

StartTime

Subject

UID

Categories

The following table describes the From, HtmlMessage, Message, and UID fields. For detailed information on the
other fields, see the table in the create action description.
Column

Description

From

The Exchange ID of the person who created the event.

HtmlMessage

An HTML-formatted version of the message about the
event.

Message

A plain-text version of the message about the event.

UID

The Exchange unique identifier for the mail event. Use
this value to identify the event in the delete, getAtta
chments, and modify actions.

The getAttachments action

When you use the getAttachments action, specify a single UID and a name attribute. The cfexchangecalenda
r tag populates a query object with the specified name. Each record has the following information about an
attachment to the event specified by the UID:
Column

Description

attachmentFileName

The filename of the attachment.

attachmentFilePath

The absolute path of the attachment file on the server.
If you omit the attachmentPath attribute, this column
contains the empty string.

© 2014 Adobe Systems Incorporated. All rights reserved.

316

Adobe ColdFusion Documentation

CID

The content-ID of the attachment. Typically used in
HTML img tags to embed images in a message.

mimeType

The MIME type of the attachment, such as text/html.

isMessage

A Boolean value that specifies whether the attachment
is a message.

size

The attachment size in bytes.

The tag places the attachments in the directory specified by the attachmentPath attribute. If you omit the attach
mentPath attribute, ColdFusion does not get any attachments, it gets the information about the attachments. This
lets you determine the event's attachments without incurring the overhead of getting the attachment files.Use the
following syntax to specify an in-memory attachmentPath directory. In-memory files are not written to disk and
speed processing of transient data.

attachmentpath = "ram:///path"

The path can include multiple directories, for example ram:///petStore/orders/messageAttachments.
Create all directories in the path before you specify the file. For more information on using in-memory files, see Work
ing with in-memory files in Optimizing ColdFusion applications in the Developing ColdFusion Applications.
The getAttachments action works only if authentication for EWS (Exchange Web Services) is set to basic in the
server setup of Exchange. IWA (Integrated Windows Authentication) is not supported.
The modify action

When you specify the modify action, you select the event to modify by specifying a uid attribute with single event
UID; multiple UIDs are not allowed. You populate the event structure with only the fields that you are changing. For
a detailed description of the fields and their valid values, see the table in the create action.
If an event has attachments and you specify attachments when you modify the event, the new attachments are
added to the previous attachments; they do not replace them. Use the deleteAttachments action to remove any
attachments.
The respond action

You use the respond action to respond to a meeting notification that you received by using the cfexchangemail t
ag. A meeting does not appear in your calendar, and cannot be accessed by using the cfexchangecalendar tag,
until you respond to the mail message and accept or tentatively accept the request.
When you specify the respond action, specify the UID, from the notification mail message, of the event to which
you are responding. Also specify the response type; that is, whether you are accepting, rejecting, or tentatively
accepting the event. You can optionally specify a message to include in the response and set a flag whether to
notify the creator of the event of your response. For detailed information on using the respond action, see Working
with meetings and appointments in the Developing ColdFusion Applications.
Suggestions struct values

Struct values

© 2014 Adobe Systems Incorporated. All rights reserved.

Description

317

Adobe ColdFusion Documentation

date

Suggested day for the meeting.

quality

The quality of the suggested day, if Excellent, Good,
Fair or Poor.

TimeSuggestion

An array of struct that contains the following values:
MeetingDate: Suggested meeting time.
Quality: The quality of the time. It can be Excelle
nt, Good, Fair, or Poor.
array of conflicts: The conflicts at the suggested time.
This is a struct that contains the following values: Co
nflictType (the type of conflict, which can be ind
ividualAttendeeConflict, which is a conflict
with an attendee, GroupConflict which is a
conflict with at least one member of a group, GroupT
ooBigConflict which is a conflict with at least one
member of a group, but the group was too big for
detailed information to be returned, and UnknownAt
tendeeConflict which is a conflict with an
unresolvable attendee or an attendee that is not a
user, group, or contact).
FreeBusyStatus: Gets the free/busy status of the
conflicting attendee. Only meaningful when Conflic
tType is equal to IndividualAttendee. The
values are Free, Tentative, Busy, OOF (time slot
associated with the appointment appears as Out of
Office) or NoData (no free/busy status is associated
with the appointment).
NoOfMembers: Gets the number of users,
resources, and rooms in the conflicting group. Only
meaningful when ConflictType is equal to Confl
ictType GroupConflict.
NoOfMembersAvailable: Gets the number of
available members (whose status is Free) in the
conflicting group. Only meaningful when ConflictT
ype is equal to ConflictType GroupConflict.
NoOfMembersWithConflict: Gets the number of
members who have a conflict (whose status is Busy,
OOF, or Tentative) in the conflicting group. Only
meaningful when ConflictType is equal to Confl
ictType GroupConflict.
NoOfMembersWithNoData: Gets the number of
members who do not have published free/busy data
in the conflicting group. Only meaningful when Conf
lictType is equal to ConflictType GroupConflict
.
isWorkTime: If the suggested meeting happens in
the work hours.

© 2014 Adobe Systems Incorporated. All rights reserved.

318

Adobe ColdFusion Documentation
Values of the struct attendeeavailability

Struct values

Description

CalendarEvent

A struct that contains the following values:
startTime: The start date and time of the event.
endTime: The end date and time of the event.
freeBusyStatus: The free/busy status associated
with the event. It can have following values: Free, t
entative, busy , OOF (Out of Office), or NoData (n
o free/busy status is associated with the
appointment).
details: The details of the calendar event; detai
ls is null if the user who requests for details does
not have the appropriate rights. details is a struct
that contains the following values: location (calend
ar location), eventstoreId (store ID of the
calendar event), and Subject (can be isExceptio
n which is a boolean value that indicates if the
calendar event is an exception in a recurring series,
isMeeting which is a boolean value that indicates if
the calendar event is a meeting, isPrivate which
is a boolean value that indicates if the calendar event
is private, isRecurring which is a boolean value
that indicates if the calendar event is recurring, and i
sRemainderSet which is a boolean value that
indicates if the calendar event has a reminder set).

mergedFreeBusyStatus

An array of struct that contains status. The status can
be
Free : The time slot associated with the appointment
appears as Free.
Tentative : The time slot associated with the
appointment appears as Tentative.
Busy : The time slot associated with the appointment
appears as Busy
OOF: The time slot associated with the appointment
appears as Out of Office.
NoData: No free/busy status is associated with the
appointment.
result: The result associated with the response.
This can be success, warning, or error.

© 2014 Adobe Systems Incorporated. All rights reserved.

319

Adobe ColdFusion Documentation

viewType

The free/busy view type retrieved for the attendee. It
can have the following values:
None: No view is returned. This value cannot be
specified in a call to GetUserAvailability.
MergedOnly: An aggregated free/busy stream. If the
target user in one forest does not have an Availability
service configured, the Availability service of the
requestor retrieves the target user's free/busy
information from the free/busy public folder. Because
public folders only stores free/busy information in
merged form, MergedOnly is the only available
information.
FreeBusy: The legacy status information (free, bu
sy, tentative, and OOF). This also includes the
start/end times of the appointments. This view is
comprehensive than the legacy free/busy view
because individual meeting start and end times are
provided instead of an aggregated free/busy stream.
FreeBusyMerged: All the properties in FreeBusy w
ith a stream of merged free/busy availability
information.
Detailed: The legacy status information (free, bu
sy, tentative, and OOF, the start/end times of the
appointments; and various properties of the
appointment such as subject, location, and
importance). This requested view returns the
maximum amount of information for which the
requesting user is privileged. If merged free/busy
information only is available, as with requesting
information for users in a Microsoft Exchange Server
2003 forest, MergedOnly is returned. Otherwise, Fr
eeBusy or Detailed are returned.
DetailedMerged: Represents all the properties in
Detailed with a stream of merged free/busy
availability information. If, only merged free/busy
information is available, for example if the mailbox
exists on a computer running Exchange 2003, Merg
edOnly is returned. Otherwise, FreeBusyMerged o
r DetailedMerged is returned.

© 2014 Adobe Systems Incorporated. All rights reserved.

320

Adobe ColdFusion Documentation

workingHours

A struct that contains the following details:
startTime: The start date and time of the event.
endTime: The end date and time of the event.
daysOfTheWeek: An array of struct. The working
days of the attendees. It can have the following
values: Sunday, Monday, Tuesday, Wednesday, T
hursday, Friday, Saturday, Weekday, and Week
EndDayDay.
Timezone: A struct that contains the following
fields: id (ID of the time zone definition) and name (n
ame of this time zone definition).

Exchange UID value

For all the cfexchangecalendar actions, the value of the attribute uid is as follows:
If exchangeServerVersion is set to 2003 or 2007: The uid indicates the ID of the appointment in the
mailbox of the organizer.
If exchangeServerVersion is set to 2010: The uid indicates the ID of the received appointment in the
mailbox of the attendee.
In the case of interaction with Microsoft Exchange server 2003 or 2007, whenever an appointment is created,
the UID of the organizer can be used by the attendee for any operation such as responding, deleting, or
getting attachments. In the case of Microsoft Exchange server 2010, the behavior is different. If attendees
have to perform appointment-related actions, they have to first search for the appointment in their mailbox
and then use the UID of that appointment.
Example 1

The following example lets you create, and then modify a calendar event. When you first submit the form,
ColdFusion creates the calendar event and redisplays the form with the data you entered. Accept the event before
you modify the form and resubmit it. When you submit the form a second time, ColdFusion sends the modification
information. For more information, see Working with meetings and appointments in the Developing ColdFusion
Applications.
This example resends all the event data (to limit the example length), but you could change the example so that it
only sends modified data.








sEvent.AllDayEvent="no";
sEvent=StructNew();
sEvent.Subject=Form.subject;
if (IsDefined("Form.allDay")) {
sEvent.AllDayEvent="yes";
sEvent.StartTime=createDateTime(Year(Form.date), Month(Form.date),
Day(Form.date), 8, 0, 0);
}
else {

© 2014 Adobe Systems Incorporated. All rights reserved.

321

Adobe ColdFusion Documentation

sEvent.StartTime=createDateTime(Year(Form.date), Month(Form.date),
Day(Form.date), Hour(Form.startTime), Minute(Form.startTime), 0);
sEvent.EndTime=createDateTime(Year(Form.date), Month(Form.date),
Day(Form.date), Hour(Form.endTime), Minute(Form.endTime), 0);
}
sEvent.Location=Form.location;
sEvent.RequiredAttendees=Form.requiredAttendees;
sEvent.OptionalAttendees=Form.optionalAttendees;
//sEvent.Resources=Form.resources;
if (Form.reminder NEQ "") {
sEvent.Reminder=Form.reminder;
}
else {
sEvent.Reminder=0;
}
sEvent.Importance=Form.importance;
sEvent.Sensitivity=Form.sensitivity;
sEvent.message=Form.Message;







Event Added. UID is#theUID#





Event ID #Form.eventID# Updated.




















Normal
High
Low


Normal
Confidential
Personal
Private




© 2014 Adobe Systems Incorporated. All rights reserved.

323

Adobe ColdFusion Documentation




Example 2

The following example shows how you can get UserAvailability action:Application.cfm






























var eventInfo = structNew();
if(isdefined("AllDayEvent") EQ 1)
eventInfo.AllDayEvent = AllDayEvent;
if(isdefined("Duration") EQ 1)
eventInfo.Duration = Duration;
if(isdefined("EndTime") EQ 1)
eventInfo.EndTime = EndTime;
if(isdefined("From") EQ 1)
eventInfo.From = From;
if(isdefined("HasAttachment") EQ 1)
eventInfo.HasAttachment = HasAttachment;
if(isdefined("HtmlMessage") EQ 1)
eventInfo.HtmlMessage = HtmlMessage;
if(isdefined("Importance") EQ 1)
eventInfo.Importance = Importance;
if(isdefined("IsRecurring") EQ 1)

© 2014 Adobe Systems Incorporated. All rights reserved.

324

Adobe ColdFusion Documentation

eventInfo.IsRecurring = IsRecurring;
if(isdefined("Message") EQ 1)
eventInfo.Message = Message;
if(isdefined("OptionalAttendees") EQ 1)
eventInfo.OptionalAttendees = OptionalAttendees;
if(isdefined("Organizer") EQ 1)
eventInfo.Organizer = Organizer;
if(isdefined("Reminder") EQ 1)
eventInfo.Reminder = Reminder;
if(isdefined("RequiredAttendees") EQ 1)
eventInfo.RequiredAttendees = RequiredAttendees;
if(isdefined("Resources") EQ 1)
eventInfo.Resources = Resources;
if(isdefined("Sensitivity") EQ 1)
eventInfo.Sensitivity = Sensitivity;
if(isdefined("StartTime") EQ 1)
eventInfo.StartTime = StartTime;
if(isdefined("Subject") EQ 1)
eventInfo.Subject = Subject;
if(isdefined("UID") EQ 1)
eventInfo.UID = UID;
if(isdefined("Location") EQ 1)
eventInfo.Location = Location;











© 2014 Adobe Systems Incorporated. All rights reserved.

325

Adobe ColdFusion Documentation




Availability.cfm









sleep(15000);

sleep(15000);





The following example shows how you can use the actions getRooms and getRoomList.

© 2014 Adobe Systems Incorporated. All rights reserved.

326

Adobe ColdFusion Documentation







Example 3

Creating and getting an appointment in a secondary calendar using the folderId attribute:



eventStruct = structnew();
eventStruct.AllDayEvent = "yes";
eventStruct.Importance = "low";
eventstruct.RequiredAttendees = "testing@abc.com";
eventstruct.Subject = "Test Message";
eventStruct.StartTime = now();






Created Appointment Successfully in the given calendar




Created Appointment Successfully in the given calendar






© 2014 Adobe Systems Incorporated. All rights reserved.

328

Adobe ColdFusion Documentation

cfexchangeconnection
Description

Opens or closes a persistent connection to a Microsoft Exchange server, or gets information about mailbox
subfolders. You must have a persistent or temporary connection to use the cfexchangecalendar, cfexchangec
ontact, cfexchangemail, and cfexchangetask tags.
History

ColdFusion 10: Added the attribute serverVersion.
ColdFusion 8: Added this tag.
Category

Communications tags
Syntax

© 2014 Adobe Systems Incorporated. All rights reserved.

329

Adobe ColdFusion Documentation

open

server = "Exchange server ID"
username = "Exchange user ID">
optional
ExchangeApplicationName = "Application name"
ExchangeServerLanguage = "Language name"
formBasedAuthentication = "no|yes">
formBasedAuthenticationURL = "URL">
mailboxName = "Exchange mailbox">
password = "user password"
port = "IP port"
protocol = "http|https"
proxyHost = "proxy host URL"
proxyPort = "proxy IP port"
getSubfolders

name = "query name"
optional
folder = "Exchange folder path">
recurse = "no|yes">
OR

optional
ExchangeApplicationName = "Application name"
ExchangeServerLanguage = "Language name"
folder = "Exchange folder path">
formBasedAuthentication = "no|yes">
formBasedAuthenticationURL = "URL">
mailboxName = "Exchange mailbox">
password = "user password"
port = "IP port"
protocol = "http|https"
proxyHost = "proxy host URL"
proxyPort = "proxy IP port"
recurse = "no|yes">
close


© 2014 Adobe Systems Incorporated. All rights reserved.

330

Adobe ColdFusion Documentation

Note
You can specify this tag's attributes in an attributeCollection attribute whose value is a
structure. Specify the structure name in the attributeCollection attribute and use the tag's
attribute names as structure keys.

See also

cfexchangecalendar, cfexchangecontact, cfexchangefilter, cfexchangemail, cfexchangetask; Ma
naging connections to the Exchange server in the Developing ColdFusion Applications
Attributes

Attribute

Action

Req/Opt

action

all

Required

Default

Description
The action to take.
Must be one of the
following values:
open: Open a
new persistent
named connection
close: Close a
named connection
getSubfolders:
Get information
about the
subfolders of a
specific folder.

connection

all

Required for open a
nd close actions

ExchangeApplica
tionName

opengetSubfolde
rs

Optional

© 2014 Adobe Systems Incorporated. All rights reserved.

The name of the
connection. You can
specify this ID in any
tag that you use with
the open
connection.
exchange

The name of the
Exchange
application to use in
the URL that
accesses the server.
Specify this attribute
if your IIS server
does not use the
default name for
your Exchange
application.

331

Adobe ColdFusion Documentation

ExchangeServerL
anguage

opengetSubfolde
rs

Optional

english

The language of the
Exchange server. If
you are not sure,
you can specify the
empty string. For all
values except
english, including
the empty string, the
tag tries to get folder
names from the
server in the client's
local language. In
some cases, such
as when there is a
large amount of data
on the server, it
might take
significant time to
get folder names
from Exchange
server in the local
language.

folder

getSubfolders

Optional

The root of the
mailbox

The forward slash
delimited path from
the root of the
mailbox to the folder
for which to get
subfolders. If a
folder name
contains a forward
slash, use the xF8F
F escape sequence
to specify the
character in the
name.

© 2014 Adobe Systems Incorporated. All rights reserved.

332

Adobe ColdFusion Documentation

formBasedAuthen
tication

opengetSubfolde
rs

Optional

formBasedAuthen
ticationURL

opengetSubfolde
rs

Optional

no

A Boolean value
that specifies
whether to display a
login form and use
form based
authentication when
making the
connection. If the
attribute value is no
(the default), and
the Exchange server
returns a 440 error
status when
ColdFusion tries to
connect, ColdFusion
displays the login
form and attempts to
use form based
authentication.
Therefore, you can
safely omit this
attribute if you do
not know if the
server requires form
based
authentication.
The URL to which to
post the user ID and
password when an
Exchange server
uses form-based
authentication. Use
this attribute only if
your Exchange
server does not use
default URL for
form-based
authentication. The
default URL has the
form https://exc
hangeServer/exc
hweb/bin/auth/o
waauth.dll, for
example, {{
https://exchange.my
company.com/exch
web/bin/auth/owaau
th.dll
}}.

© 2014 Adobe Systems Incorporated. All rights reserved.

333

Adobe ColdFusion Documentation

mailboxName

opengetSubfolde
rs

Optional

The ID of the
Exchange mailbox
to use. Specify this
attribute to access a
mailbox whose
owner has
delegated access
rights to the account
specified in the use
rname attribute.

name

getSubfolders

Required

The name of the
ColdFusion query
variable that
contains information
about the
subfolders.

password

opengetSubfolde
rs

Optional

The user's
password for
accessing the
Exchange server.

port

opengetSubfolde
rs

Optional

80

The port the server
listens to, most
commonly port 80.

protocol

opengetSubfolde
rs

Optional

http

The protocol to use
for the connection.
Valid values are ht
tp and https.

proxyHost

opengetSubfolde
rs

Optional

The URL or IP
address of a proxy
host, if necessary
for access to the
network.

proxyPort

opengetSubfolde
rs

Optional

The port on the
proxy server to
connect to, most
commonly port 80.

© 2014 Adobe Systems Incorporated. All rights reserved.

334

Adobe ColdFusion Documentation

recurse

getSubfolders

Optional

false

A Boolean value:
true: get
information on the
immediate
subfolders of the
specified folder
only.
false: get
information on all
levels of
subfolders of the
specified folder.

server

opengetSubfolde
rs

Required

Optional

serverVersion

The IP address or
URL of the server
that is providing
access to
Exchange.
2007

Specifies the
Microsoft Exchange
Server version. The
values are:
2003
2007
2010
If you do not
specify the
details, 2007 is
taken by default.
The value you
specify overrides
the value that you
specify at the
application level.

username

opengetSubfolde
rs

Required

The Exchange user
ID.

Note
If you specify the getSubfolders action, you can specify the attributes that are listed as
working for both the open and getSubfolders actions only if you do not specify a connectio
n attribute.

Usage

The cfexchangeconnection tag can open or close a persistent connection with an Exchange server. If you use
the cfexchangeconnection to open a connection before you use any cfexchangecalendar, cfexchangecon

© 2014 Adobe Systems Incorporated. All rights reserved.

335

Adobe ColdFusion Documentation

tact, cfexchangemail, or cfexchangetask tags, you can use multiple tags to interact with the Exchange
server without incurring the overhead of creating a connection for each tag.
Note
To establish any connection, the Exchange server must grant you Outlook Web Access. For
information on how to enable this access, see Enabling access to the Exchange server in Manag
ing connections to the Exchange server in the Developing ColdFusion Applications. Also, you
cannot establish a connection to an Exchange server if you require a special authentication step,
such as requiring a VPN PIN or performing biometric authentication, on a server that is outside
your firewall, and the authentication server then routes the messages to your Exchange server
inside the firewall.

Use the cfexchangeconnection tag to close a persistent connection when you are finished accessing the
Exchange server. If you do not close the connection, it remains open and does not time out.
The cfexchangecalendar, cfexchangecontact, cfexchangemail, and cfexchangetask tags also let you
specify the open action connection attributes (but not the connection attribute) to create a temporary connection
that lasts for the duration of the single tag's activities, without requiring you to use the cfexchangeconnection ta
g to create the connection. In this case, ColdFusion automatically closes the connection when the tag completes
processing.
The getSubfolders action can get information about the immediate subfolders of a specified folder (or of the top
level of the mailbox), or information about all levels of subfolders. You must have a persistent connection to get the
subfolders.
The query returned by the getSubfolders action has the following columns:
Column

Contents

FOLDERNAME

The name of the subfolder, for example, ColdFusion.

FOLDERPATH

The forward slash
delimited path to the folder from
the mailbox root, including the folder name, for
example, Inbox/Marketing/ColdFusion.

FOLDERSIZE

Size of the folder in bytes.

Note
The ColdFusion exchange tags, including cfexchangeconnection use WebDAV to connect to
the exchange server. HTTP access must be enabled on the exchange server to use the tags.

Example

The following example opens a connection, gets all mail sent from spamsource.com, and deletes the messages
from the Exchange server:

© 2014 Adobe Systems Incorporated. All rights reserved.

336

Adobe ColdFusion Documentation










© 2014 Adobe Systems Incorporated. All rights reserved.

337

Adobe ColdFusion Documentation

cfexchangecontact
Description

Creates, deletes, modifies, and gets Microsoft Exchange contact records, and gets contact record attachments.
History

ColdFusion 10: Added the attribute serverVersion.
ColdFusion 8: Added this tag.
Category

Communications tags
Syntax

© 2014 Adobe Systems Incorporated. All rights reserved.

338

Adobe ColdFusion Documentation

create

delete

deleteAttachments

get

getAttachments

modify




Name





Address




CA
MA
WA


Phone



Email


© 2014 Adobe Systems Incorporated. All rights reserved.

346

Adobe ColdFusion Documentation








sContact.FirstName=Form.firstName;
sContact.Company=Form.company;
sContact.LastName=Form.lastName;
sContact.BusinessAddress.Street=Form.street;
sContact.BusinessAddress.City=Form.city;
sContact.BusinessAddress.State=Form.state;
sContact.BusinessAddress.Country=Form.country;
sContact.BusinessPhoneNumber=Form.businessPhone;
sContact.MobilePhoneNumber=Form.cellPhone;
sContact.BusinessFax=Form.fax;
sContact.Email1=Form.email;





Contact Added. UID is#theUID#

© 2014 Adobe Systems Incorporated. All rights reserved.

347

Adobe ColdFusion Documentation




© 2014 Adobe Systems Incorporated. All rights reserved.

348

Adobe ColdFusion Documentation

cfexchangeconversation
Description

Helps users organize and manage conversations from a Microsoft Exchange account. The following actions are
supported:
Finds the required conversations in folder/subfolders based on filters.
Status of the conversation; if read
Copy, move, or delete conversation
History

ColdFusion 10: Added this tag.
Category

Communications tags
Syntax

© 2014 Adobe Systems Incorporated. All rights reserved.

349

Adobe ColdFusion Documentation

get

setReadState

copy

move

delete




































© 2014 Adobe Systems Incorporated. All rights reserved.

355

Adobe ColdFusion Documentation

cfexchangefilter
Description

Specifies filter parameters that control the actions of cfexchangemail, cfexchangecalendar, cfexchangetas
k, and cfexchangecontact, get operations.
History

ColdFusion 8: Added this tag.
Category

Communications tags
Syntax


OR


Note
You can specify this tag's attributes in an attributeCollection attribute whose value is a
structure. Specify the structure name in the attributeCollection attribute and use the tag's
attribute names as structure keys.

See also

cfexchangecalendar, cfexchangeconnection, cfexchangecontact, cfexchangemail, cfexchangeta
sk, Getting Exchange items and attachments in the Developing ColdFusion Applications
Attributes

Attribute

Req/Opt

name

Required

© 2014 Adobe Systems Incorporated. All rights reserved.

Default

Description
The type of filter to use.

356

Adobe ColdFusion Documentation

from

Optional

The start date or date/time
combination of the range
to use for filtering. Cannot
be used with the value at
tribute. If you specify a fr
om attribute without a to a
ttribute, the filter selects
for all entries on or after
the specified date or time.
The value can be in any
date/time format
recognized by
ColdFusion, but must
correspond to a value that
is appropriate for the filter
type.

to

Optional

The end date or date/time
combination for the range
used for filtering. Cannot
be used with the value at
tribute. If you specify a to
attribute without a from at
tribute, the filter selects for
all entries on or before the
specified date or time.
The value can be in any
date/time format
recognized by
ColdFusion, but must
correspond to a value that
is appropriate for the filter
type.

© 2014 Adobe Systems Incorporated. All rights reserved.

357

Adobe ColdFusion Documentation

value

Optional

The filter value for all
filters that do not take a
date or time range.
Cannot be used with the f
rom and to attributes.Col
dFusion generates an
error if you specify this
attribute with an empty
contents. Therefore, you
cannot use the empty
string to search for empty
values.
If you set this attribute to
the empty string (""),
ColdFusion searches for
entries where the
specified field is empty.
6.07

The cfexchangeCalendar tag filters can have the following name attributes and associated value, or to and fr
om attributes that you use to specify the filter parameters for the specified action:
name attribute

Specification attributes

Valid specification attribute
values

maxRows

value

A positive integer specifying the
maximum number of matching rows
to return. By default, the maximum
number of rows is 100. You can
also specify -1; to return all
matching rows.

allDayEvent

value

A Boolean value.

duration

value

An integer number of minutes.

endTime

from to

A string that ColdFusion can
interpret as a date-time value.

fromID

value

An Exchange user ID.

hasAttachment

value

A Boolean value.

importance

value

One of the following values:
high
normal
low

isRecurring

value

© 2014 Adobe Systems Incorporated. All rights reserved.

A Boolean value.

358

Adobe ColdFusion Documentation

location

value

A string.

message

value

A string.

optionalAttendees

value

A comma-delimited list of Exchange
user IDs.

organizer

value

A string that identifies the organizer.
This value does not need to be an
Exchange ID or e-mail address.

requiredAttendees

value

A comma-delimited list of Exchange
user IDs.

sensitivity

value

One of the following values:
normal
personal
private
confidential

startTime

from to

A string that ColdFusion can
interpret as a date-time value.

subject

value

A string.

UID

value

A case-sensitive Exchange
message UID that uniquely
identifies one calendar entry.

The cfexchangecontact tag filters can have the following name attributes and associated value attributes.
Unlike other tags, you do not use from or to attributes.
name attribute

value attribute

maxRows

A positive integer that specifies the maximum number
of matching rows to return. By default, the maximum
number of rows is 100. You can also specify -1; to
return all matching rows.

assistant

A string.

businessAddress

A structure with the following fields: Street, City, State,
Zip, Country.

businessFax

A string.

businessPhoneNumber

A string.

© 2014 Adobe Systems Incorporated. All rights reserved.

359

Adobe ColdFusion Documentation

categories

A comma-delimited list of categories. The filter
searches for contacts that match all the categories in
the list.

company

A string.

description

A string.

displayAs

A string.

email1

A string.

email2

A string.

email3

A string.

firstName

A string.

hasAttachment

A Boolean value.

homeAddress

A structure with the following fields: Street, City, State,
Zip, Country.

homePhoneNumber

A string.

jobTitle

A string.

lastName

A string.

mailingAddressType

One of the following values: Home, Business, Other.

manager

A string.

middleName

A string.

mobilePhoneNumber

A string.

nickName

A string.

office

A string.

otherAddress

A structure with the following fields: Street, City, State,
Zip, Country.

otherPhoneNumber

A string.

pager

A string.

© 2014 Adobe Systems Incorporated. All rights reserved.

360

Adobe ColdFusion Documentation

profession

A string.

spouseName

A string.

webPage

A string.

The cfexchangemail tag filters can have the following name attributes and associated value, or to and from at
tributes that you use to specify the filter parameters for the specified action:
name attribute

Specification attributes

Specification attribute values

maxRows

value

A positive integer that specifies the
maximum number of matching rows
to return. By default, the maximum
number of rows is 100.
You can also specify -1; to return all
matching rows.

bcc

value

A comma-delimited list of Exchange
or web e-mail addresses.

cc

value

A comma-delimited list of Exchange
or web e-mail addresses.

folder

value

The forward slash delimited path
from the root of the Exchange
mailbox to the folder to search. By
default, the filter searches the top
level of the Inbox. The cfexchang
email tag searches only the
specified folder, and does not
search any subfolders. If a folder
name contains a forward slash, use
the xF8FF escape sequence to
specify the character in the name.
For the get and move actions, you
can use the cfexchangemail tag
folder attribute instead of this
field; however, this field takes
precedence over the value specified
in the folder attribute.

fromID

value

An Exchange or web e-mail
address.

hasAttachment

value

A Boolean value

© 2014 Adobe Systems Incorporated. All rights reserved.

361

Adobe ColdFusion Documentation

importance

value

One of the following values:
high
normal
low

isRead

value

A Boolean value.

message

value

A string.

MessageType

value

One of the following values: Mail,
Meeting, Meeting_Cancel, Mee
ting_Request, Meeting_Respo
nse, or All. If you omit this
attribute, the filter gets messages of
all types. The Meeting attribute
gets messages with Meeting_Can
cel, Meeting_Request, and Mee
ting_Response types.

MeetingUID

value

A case-sensitive Exchange
calendar event UID. Meeting UIDs
are used in Meeting_request or
Meeting_response message
types only. Do not specify this field
if you specify a MessageType field
value of Mail.

sensitivity

value

One of the following values:
normal
personal
private
confidential

subject

value

A string.

timeReceived

from to

A string that ColdFusion can
interpret as a date-time value.

timeSent

from to

A string that ColdFusion can
interpret as a date-time value.

toID

value

A comma-delimited list of Exchange
or web e-mail addresses.

uid

value

A case-sensitive Exchange
message UID.

The cfexchangetask tag filters can have the following name attributes and associated value, or to and from at

© 2014 Adobe Systems Incorporated. All rights reserved.

362

Adobe ColdFusion Documentation

tributes that you use to specify the filter parameters for the specified action:
name attribute

Specification attributes

Specification attribute values

maxRows

value

A positive integer specifying the
maximum number of matching rows
to return. By default, the maximum
number of rows is 100.
You can also specify -1; to return all
matching rows.

actualWork

value

A number representing the number
of hours. Use decimal numbers to
specify minutes.

billingInfo

value

A string.

companies

value

A string.

dateCompleted

value

A string that ColdFusion can
interpret as a date-time value.

dueDate

from to

A string that ColdFusion can
interpret as a date-time value.

mail_ID

value

A comma-delimited list of Exchange
mail IDs. This filter value is useful if
the connection user has delegate
rights for multiple users and you
want to select the tasks of a limited
number of those users.

message

value

A string.

mileage

value

A string.

percentCompleted

value

A number between 0 and 100.

priority

value

One of the following values:
high
normal
low

reminderDate

value

A string that ColdFusion can
interpret as a date-time value.

startDate

from to

A string that ColdFusion can
interpret as a date-time value.

© 2014 Adobe Systems Incorporated. All rights reserved.

363

Adobe ColdFusion Documentation

status

value

Must be one of the following values:
NOT_STARTED
IN_PROGRESS
COMPLETED
WAITING
DEFERRED

subject

value

A string.

totalWork

value

A number that represents the
number of hours. Use decimal
numbers to specify minutes.

UID

value

A case-sensitive Exchange UID.

Usage

The cfexchangefilter tag specifies the conditions to match when ColdFusion gets mail messages, calendar
entries, tasks, or contacts. Only those entries that match the specified filter conditions are returned in the structure
specified by the parent tag's name attribute. If the filter specifies a field that takes a text string, such as Message and
or Subject, ColdFusion returns items that contain the exact phrase that you specify in the value attribute.
The cfexchangefilter tag must be a child tag of a cfexchangecalendar, cfexchangecontact, cfexchan
gemail, or cfexchangetask tag with an action attribute value of get. If you specify multiple cfexchangefilt
er tags in the body of a ColdFusion exchange tag, such as cfexchangemail, the specified filters are cumulative,
and the selected records match the conditions specified in all the cfexchangefilter tags. If you specify multiple
cfexchangefilter tags with the same name attribute value, the last tag with that attribute specifies the filter
conditions.
Example

The following example gets the mail messages that were sent to a user during the last week from any e-mail
address that includes adobe.com. To focus on getting messages, rather than on displaying data, the example uses
the cfdump tag to show the results.









© 2014 Adobe Systems Incorporated. All rights reserved.

364

Adobe ColdFusion Documentation

cfexchangefolder
Description

Lets you perform various actions on the mail folder, such as get folder information, find folders, or create, copy,
modify, move, delete, and empty the contents of a folder.
History

ColdFusion 10: Added this tag.
Category

Communications tags
Syntax

getExtendedInfo

OR
getExtendedInfo

getlnfo

OR
getlnfo

findSubFolders

create

copy

connection = "connection_ID"
result = "variable for contact UID"/>
delete

connection = "connection_ID"/>
move

connection = "connection_ID"
result = "variable for contact UID"/>
modify

empty


© 2014 Adobe Systems Incorporated. All rights reserved.

366

Adobe ColdFusion Documentation

deleteSubFolder = "true|false"
connection = "connection_ID"/>

See also

cfexchangecalendar, cfexchangeconnection, cfexchangefilter, cfexchangemail, cfexchangetask
, Interacting with Microsoft Exchange Servers in the Developing ColdFusion Applications
Attributes

Attribute

Action

Req/Opt

action

N/A

Required

Default

Description
The action to take.
Must be one of the
following values:
getInfo
getExtendedIn
fo
findSubFolder
s
create
copy
delete
move
modify
empty

uid

getExtendedInfo
/ getInfo

Not required for get
ExtendedInfo and
getInfo, if folder
path is specified.

UID that is used to
identify the folder in
which the actions
are performed.

name

getExtendedInfo
/ getInfo / fin
dSubFolders

Required

The name of the
ColdFusion query
variable that
contains the
returned information
about the folder.

folderID

getExtendedInfo
/ getInfo / fin
dSubFolders / d
elete / modify
/ empty

Not required for get
ExtendedInfo an
d getInfo, if folder
path is specified.

UID that is used to
identify the folder in
which the actions
are performed.

© 2014 Adobe Systems Incorporated. All rights reserved.

367

Adobe ColdFusion Documentation

folderPath

getExtendedInfo
/ getInfo

Not required if fold
erID is specified.

pathDelimiter

getExtendedInfo
/ getInfo

Optional

parentFolderId

create

Required

UID that is used to
identify the folder in
which you create
subfolders.

connection

All actions

Required

The name of the
connection to the
Exchange server, as
specified in the cfe
xchangeconnecti
on tag. If you omit
this attribute, create
a temporary
connection by
specifying cfexcha
ngeconnection ta
g connection opena
ction attributes in
the cfexchangeco
ntact tag.

result

create / copy /
move

Required

A query variable that
contains the result
returned from the
exchange server
when one of the
action is performed.

destinationFold
erID

copy / move

Required

A case-sensitive
Exchange UID value
that uniquely
identifies the
destination folder.

© 2014 Adobe Systems Incorporated. All rights reserved.

Full path to the
folder where the
action has to be
performed.
If you do not specify
the path delimiter, /
is taken by default.
/

Lets you specify the
delimiter that is used
to separate the
folders.

368

Adobe ColdFusion Documentation

sourceFolderID

copy / move

Required

The UID that is used
to identify the folder
from which you copy
or move folders to
the destination
folder.

deleteType

delete / move

Optional

moveToDeletedIt
ems

deleteSubFolder
s

empty

Optional

False

folder

create / modify

Required

hardDelete:
Removes a folder
permanently from
the Exchange
server.
softDelete:
Moves a folder to
the dumpster in
Exchange server,
if dumpster is
enabled.
moveToDeleted
Items: Moves a
folder to the
deleted items
folder.
If true, deletes the
subfolder.
A struct that
contains the
required information
of the folder that has
to be created or
modified, such as
display name and
folder class.

Result struct values for cfexchangefolder action = "getExtendedInfo"

For the action getExtendedInfo, the result is a struct that contains the following fields:
Field

Description

ChildFolderCount

The number of child folders that the parent folder has.

displayName

The display name of the folder.

folderClass

The folder class.

FolderPath

Path to the exchange server folder.

© 2014 Adobe Systems Incorporated. All rights reserved.

369

Adobe ColdFusion Documentation

ManagedFolder

Struct that contains the following properties:
canDelete: Boolean value that indicates if the user
can delete objects in the folder.
canRenameOrMove: Boolean value that indicates if
the user can rename or move objects in the folder.
mustDisplayComment: Boolean value that
indicates if the client application must display the
comment property to the user.
HasQouta: Boolean value that indicates if the folder
has a quota.
IsManagedFoldersRoot: Boolean value that
indicates if the folder is the root of the managed
folder hierarchy.
ManagedFolderId: The ID of the managed folder.
comment: The comment that is associated with the
folder.
StorageQuota: The storage quota of the folder.
FolderSize: The size of the folder.
HomePage: The home page associated with the
folder.

mustDisplayComment

Boolean value that indicates if the client application
must display the comment property to the user.

ParentFolderId

The ID of the folder's parent folder.

Permission

List of permissions for the folder. This is an array of
permission structs with the following values:

© 2014 Adobe Systems Incorporated. All rights reserved.

370

Adobe ColdFusion Documentation

canCreateItems: Boolean value that indicates if
the user can create new items.
canCreateSubFolders: Boolean value that
indicates if the user can create sub-folders.
deleteItems: Indicates if/how the user can delete
existing items. The values are None (the user does
not have the associated permission), Owned (the
user has the associated permission on items that it
owns), and All (the user has the associated
permission on all items).
displayPermissionLevel: The permission level
that Outlook displays for this folder permission. It can
have the following values: None, Owner, Publishi
ngEditor, Editor, PublishingAuthor, Free
busytimeandsubjectandlocation, Freebusy
timeOnly, Author, NonEditingAuthor, Revei
wer, Contributor, and Custom.
EditItems: Indicates the items in a folder that the
user has permission to edit. Values are none, owned
, or all.
isFolderContact: Boolean value that indicates if
the user is a contact for the folder.
isFolderOwner: Boolean value that indicates if the
user owns the folder.
isFolderVisible: Boolean value that indicates if
the folder is visible to the user.
PermissionLevel: Represents the combination of
permissions that a user has on a folder. The values
are same as that of displayPermissionLevel ex
cept Freebusytimeandsubjectandlocation an
d FreebusytimeOnly.
readItems: The read item access permission. The
values are as follows: None (user has no read
access on the items in the folder), TimeOnly (user
can read the start and end date and time of
appointments; applies only to Calendar folders, Time
AndSubjectAndLocation (user can read the start
and end date and time, subject, and location of
appointments; applies only to calendar folders, and F
ullDetails (user has access to full details of
items).
UserIDDisplayName: Display name of the user.
UserIDprimarySMTPAddress: The primary SMTP
address of the user.
userIDSID: SID of the user.
UserIdstandardUser: Indicates the standard
user, if default (the default delegate user, used to
define default delegate permissions and Anonymous
(the anonymous delegate user, used to define
delegate permissions for unauthenticated users).

© 2014 Adobe Systems Incorporated. All rights reserved.

371

Adobe ColdFusion Documentation

TotalCount

Total number of items contained in the folder.

UnreadCount

Number of unread items in the folder.

Result struct values for cfexchangefolder action = "getInfo"

For the action getInfo, the result is a struct that contains the following fields:
Field

Description

ChildFolderCount

The number of child folders this folder has

displayName

The display name of the folder

folderClass

Folder class

folderPath

Path to the exchange server folder.

UID

ID of the folder

ParentFolderId

The Id of the current folder's parent folder

TotalCount

Total number of items contained in the folder

UnreadCount

The number of unread items in the folder

Filter parameters for cfexchangefolder action = "findSubFolders"

For the action findSubFolders, the result is a query that contains details of the subfolders. The values are same
as that of cfexchangefolder action = "getInfo".
Example

The following code shows how you can perform the actions getExtendedInfo, findSubFolders, getInfo, co
py, delete, modify, move, and create.










© 2014 Adobe Systems Incorporated. All rights reserved.

372

Adobe ColdFusion Documentation






sleep(1000);




sleep(1000);




































© 2014 Adobe Systems Incorporated. All rights reserved.

373

Adobe ColdFusion Documentation






© 2014 Adobe Systems Incorporated. All rights reserved.

374

Adobe ColdFusion Documentation



© 2014 Adobe Systems Incorporated. All rights reserved.

375

Adobe ColdFusion Documentation

cfexchangemail
Description

Gets mail messages and attachments, deletes messages, and sets properties for messages on a Microsoft
Exchange server.
History

ColdFusion 10: Added the attribute serverVersion and folderID.
ColdFusion 8: Added this tag.
Category

Communications tags
Syntax

delete

deleteAttachments

folder = "Exchange folder path">
get

folderID = "Exchange folder UID"


...

getAttachments

getMeetingInfo

move

folderID = "Exchange folder UID"


...

set

uid = "message UID">
optional
connection = "connection ID"

© 2014 Adobe Systems Incorporated. All rights reserved.

377

Adobe ColdFusion Documentation

folder = "Exchange folder path">
folderID = "Exchange folder UID"

Note
If you omit the connection attribute, create a temporary connection by specifying cfexchange
connection tag attributes in the cfexchangemail tag. In this case, ColdFusion closes the
connection when the tag completes. For details, see the cfexchangeconnection tag open ac
tion.
Note
You can specify this tag's attributes in an attributeCollection attribute whose value is a
structure. Specify the structure name in the attributeCollection attribute and use the tag's
attribute names as structure keys.

See also

cfexchangecalendar, cfexchangeconnection, cfexchangecontact, cfexchangefilter, cfexchange
task, Interacting with Microsoft Exchange Servers in the Developing ColdFusion Applications
Attributes

Note
If an attribute, such as folder or destinationFolder takes a folder path, and the folder
name contains forward slashes , specify the folder name by using the xF8FF escape character
to prevent exchange from interpreting the character as a path delimiter.

Attribute

Action

Req/Opt

action

all

Required

Default

Description
The action to take.
Must be one of the
following values:
delete
deleteAttachm
ents
get
getAttachment
s
getMeetingInf
o
move
set

© 2014 Adobe Systems Incorporated. All rights reserved.

378

Adobe ColdFusion Documentation

attachmentPath

getAttachments

Optional

The filepath of the
directory in which to
put the attachments.
If the directory does
not exist,
ColdFusion creates
it.
Note: If you omit
this attribute,
ColdFusion does not
save any
attachments. If you
specify a relative
path, the path root is
the ColdFusion
temporary directory,
which is returned by
the GetTempDirec
tory function.

connection

all

Optional

The name of the
connection to the
Exchange server, as
specified in the cfe
xchangeconnecti
on tag. If you omit
this attribute, create
a temporary
connection by
specifying cfexcha
ngeconnection ta
g open action
attributes in the cfe
xchangecalendar
tag.

destinationFold
er

move

Required

The forward slash
delimited path,
relative to the root of
the mailbox, of the
folder to which to
move the message
or messages.

© 2014 Adobe Systems Incorporated. All rights reserved.

379

Adobe ColdFusion Documentation

folder

all except getMeet
ingInfo

Optional

The forward slash
delimited path,
relative to the root of
the mailbox, of the
folder that contains
the message or
messages. The cfe
xchangemail tag
looks in the
specified folder only,
and does not search
subfolders.
For the get and mo
ve actions
specifying a cffexc
hangefilter child
tag with a name="f
older" attribute is
equivalent to setting
this attribute, and
takes precedence
over this attribute's
value.
If you omit this
attribute, or for get
and move actions, if
you do not use the
corresponding cfex
changefilter sett
ing, Exchange looks
in the top level of
the Inbox.

folderID

__ get, move,
set

Optional

A case-sensitive
Exchange UID value
that uniquely
identifies the folder.
If not specified,
folder is used. If
either folder or fo
lderID are not
specified, the inbox
is used as the
default folder to
perform the
operation.

© 2014 Adobe Systems Incorporated. All rights reserved.

380

Adobe ColdFusion Documentation

generateUniqueF
ilenames

getAttachments

Optional

mailUID

getMeetingInfo

Optional

The case-sensitive
UID of the mail
message that
contains the
meeting request,
response, or
cancellation
notification. Use this
attribute if there are
multiple messages
about a single
meeting.

meetingUID

getMeetingInfo

Required

The case-sensitive
UID of the meeting
for which you
received the
notification.

© 2014 Adobe Systems Incorporated. All rights reserved.

no

A Boolean value
that specifies
whether to generate
unique filenames if
multiple attachments
have the same
filenames. If two or
more attachments
have the same
filename and this
option is yes, Cold
Fusion appends a
number to the
filename body
(before the
extension) of any
conflicting
filenames. Thus, if
three attachments
have the name
myfile.txt,
ColdFusion saves
the attachments as
myfile.txt,
myfile1.txt, and
myfile2.txt.

381

Adobe ColdFusion Documentation

message

set

Required

A reference to a
structure that
contains the
properties to be set
and their values.
Specify this attribute
in number signs (#).
For more
information on the
message structure,
see Usage.

name

getgetAttachmen
tsgetMeetingInf
o

Required

The name of the
ColdFusion query
variable that
contains the
returned mail
messages or the
retrieved information
about the
attachments or
meeting. For more
information on the
returned data, see
Usage.

serverVersion

Optional

2007

Specifies the
Microsoft Exchange
Server version. The
values are:
2003
2007
2010
If you do not
specify the
details, 2007 is
taken by default.
The value you
specify overrides
the value that you
specify at the
application level.

© 2014 Adobe Systems Incorporated. All rights reserved.

382

Adobe ColdFusion Documentation

uid

deletegetAttach
mentsset

Required

The case-sensitive
UIDs of the
messages on which
to perform the
action. For the dele
te action, this
attribute can be a
comma-delimited list
of UID values. The d
eleteAttachment
s,
getAttachments,
and set actions
allow only a single
UID value.

Usage

The cfexchangemail tag performs mail actions on an Exchange server that you cannot do by using the cfmail t
ag. (You must use the cfmail tag to send, forward, and reply to mail messages.) Use the cfexchangemail tag to
perform the following actions:
Permanently delete one or more mail messages from the server.
Get the attachments for a specific message.
Get one or more messages that conform to an optional set of filter specifications, such as the subject, sender
or recipient ID, time received, and so on.
Get the attachments for a specific message.
Get detailed information about a meeting for which you have a notification, such as a meeting request or
cancellation notice.
Move one or more messages from one folder to another, including to the Deleted Items folder.
Set the properties of a specific mail message.
To use this tag, you must have a connection to an Exchange server. If you are using multiple tags that
interact with the exchange server, such as if you are creating several contact records, use the cfexchangec
onnection tag to create a persistent connection. You then specify the connection identifier in each cfexch
angemail tag, or any other ColdFusion Exchange tag, if you are also accessing tasks, contacts, or
connections. Doing this saves the overhead of creating and closing the connection for each tag. Alternatively,
you can create a temporary connection that lasts only for the time that ColdFusion processes the single cfex
changemail tag. To do this, you specify the connection attributes directly in the cfexchangemail tag. For
details on the connection attributes, see the cfexchangeconnection tag.
The delete action

The delete action permanently deletes a message from the server, and is equivalent to the Outlook Shift-Delete
keystroke action. Use the move action to move a message to the Deleted Items folder, which is equivalent to the
Outlook Delete keystroke action. When you specify the delete action you must specify a uid attribute with a
comma-delimited list of one or more Exchange UIDs that identify the tasks that you want to delete. You can use the
get action, with an appropriate filter expression, to determine the UID values to specify.
If all UIDs that you specify are invalid, the cfexchangemail tag generates an error. If at least one UID is valid, the
tag ignores any invalid UIDs and deletes the items specified by the valid UID.
The get action

© 2014 Adobe Systems Incorporated. All rights reserved.

383

Adobe ColdFusion Documentation

When you specify the get action, you use child cfexchangefilter tags to specify the messages to get. For
detailed information, see cfexchangefilter. When the tag completes processing, the query object specified by
the name attribute contains one record for each matching message that was found. Each record has the following
columns:
Column

Description

BCC

A comma-delimited list of Exchange user IDs or web
e-mail.

CC

A comma-delimited list of Exchange user IDs or web
e-mail addresses.

Folder

The forward slash delimited path from the root of the
Exchange mailbox to the mail folder containing the
message.

FromID

An Exchange user IDs or web e-mail addresses.

HasAttachment

A Boolean value that indicates whether the message
has at least one attachment.

HTMLMessage

A string containing a HTML-formatted version of the
message.

IsRead

A Boolean value.

Message

A string with a plain-text version of the message
contents.

MessageType

One of the following strings:
Mail
Meeting_Cancel
Meeting_Request
Meeting_Response

MeetingResponse

If the message type is Meeting_response, this
column contains the response code as one of the
following strings: Accept, Decline, or Tentative.
This field is not used for other message types.

MeetingUID

If the message type is Meeting_Cancel, Meeting_r
equest, or Meeting_response this column contains
the UID of the calendar event for which this message
was sent. Use this value in the cfexchangecalendar
tag to respond to a request. This field is not used for
the Mail message type.

© 2014 Adobe Systems Incorporated. All rights reserved.

384

Adobe ColdFusion Documentation

Sensitivity

One of the following strings:
public
private
normal
company-confidential

Subject

A string.

TimeReceived

A ColdFusion date-time object.

TimeSent

A Coldfusion date-time object.

ToId

A comma-delimited list of Exchange user IDs or web
mail IDs.

UID

The Exchange UID of the message.

Note
An invitation sender can get a meeting request message only if the sender is on the attendee list.

The getAttachments action

When you use the getAttachments action, specify a single UID and a name attribute. The cfexchangecontact
tag populates a query object specified by the name attribute with one record for each attachment. Each record has
the following information about the mail attachment specified by the UID:
Column name

Description

attachmentFileName

The filename of the attachment.

attachmentFilePath

The absolute path of the attachment file on the server.
If you omit the attachmentPath attribute, this column
contains the empty string.

CID

The content-ID of the attachment. Used in HTML img
tags to embed images in a message.

mimeType

The MIME type of the attachment, such as text/html.

isMessage

A Boolean value that specifies whether the attachment
is a message.

size

The attachment size in bytes.

The tag places the attachments in the directory specified by the attachmentPath attribute. If you omit the attach
mentPath attribute, ColdFusion does not get any attachments; it gets the information about the attachments. This
lets you determine the attachments without incurring the overhead of getting the attachment files.

© 2014 Adobe Systems Incorporated. All rights reserved.

385

Adobe ColdFusion Documentation

If a message has multiple attachments with the same name, the attachment information structure always lists the
attachments with their original, duplicate, names, even if you specify generateUniqueFilenames="yes". The g
enerateUniqueFilenames attribute only affects the names of the files on disk.Use the following syntax to specify
an in-memory attachmentPath directory. In-memory files are not written to disk and speed processing of transient
data.

attachmentpath = "ram:///path"

The path can include multiple directories, for example ram:///petStore/orders/messageAttachments.
Create all directories in the path before you specify the file. For more information on using in-memory files, see
Working with in-memory files in Optimizing ColdFusion applications in the Developing ColdFusion Applications.
The getAttachments action works only if authentication for EWS (Exchange Web Services) is set to basic in the
server setup of Exchange. IWA (Integrated Windows Authentication) is not supported.
The getMeetingInfo action

You use the getMeetingInfo action to get meeting-specific information, such as the meeting start and end times,
location, and so on, about a meeting for which you have received a notification message, such as an invitation
request or cancellation notice. This information is not available directly in the notification message query object that
is returned by the get action.
Note
At the time of publication, the following information does not completely reflect the behavior of
the getMeetingInfo action. For updated information, see cfexchangemail in the
ColdFusion documentation available online in HTML on the Adobe website.

When you specify the getMeetingInfo action, you specify a meetingUID attribute with the UID of the meeting.
You get this UID value from the query record that is returned by the get action. You can optionally specify a messa
geUID attribute with the UID of the specific message that contains the notification; if you receive multiple messages
about a single meeting, you can use this attribute to select a single notification message. When the tag completes
processing, the query object specified by the name attribute contains one record for each matching message that
was found. Each record has the following columns:
Field

Description

AllDayEvent

A Boolean value that indicates whether this is an all
day event.

Duration

The duration of the event in minutes.

EndTime

The end time of the event, in ColdFusion ODBC
date-time format.

From

The mail ID of the person who sent the meeting
notification.

© 2014 Adobe Systems Incorporated. All rights reserved.

386

Adobe ColdFusion Documentation

HasAttachment

A Boolean value that indicates whether this event has
attachments.

Importance

One of the following values:
high
normal
low

IsRecurring

A Boolean value that indicates whether this event
repeats.

Location

A string that specifies the location of the event.

MeetingUID

The UID of the event in the calendar.

Message

A string that contains a message about the event.

OptionalAttendees

A comma-delimited list of mail IDs.

Organizer

A string. This value is not necessarily an Exchange ID
or e-mail address.

Reminder

The time, in minutes before the event, at which to
display a reminder message.

RequiredAttendees

A comma-delimited list of mail IDs.

Resources

A comma-delimited list of mail IDs for Exchange
scheduling resources, such as conference rooms and
display equipment.

Sensitivity

One of the following values:
normal
company-confidential
personal
private

StartTime

The start time of the event, in ODBC date-time format.

Subject

A string describing the event subject.

TimeReceived

The time the message was received, in ODBC
date-time format.

UID

The UID of the message that contains the event
notification.

The move action

© 2014 Adobe Systems Incorporated. All rights reserved.

387

Adobe ColdFusion Documentation

Use the move action to move one or more messages from one folder to another folder. You can use this action to
move messages to the Deleted Items folder, which is equivalent to the Outlook Delete keystroke action. When you
specify the move action you specify the destination folder, and optionally the folder containing the messages to
move. (The default source folder is the Inbox). You use child cfexchangefilter tags to specify the messages to
get. For detailed information, see cfexchangefilter.
The set action

When you specify the set action, the structure specified by the message attribute contains key-value pairs that
specify the message properties to set. The following table lists the key names and their valid values:
Key name

Valid values

IsRead

yes, no

Importance

high, normal, low

Sensitivity

normal, company-confidential, personal, priv
ate

Example

The following example gets the attachments to all mail messages in the Inbox from docuser2 in the last week. It puts
each message's attachments in a directory with a unique name. It cannot use the UID as a filename because, for
each message with attachments, the UID can contain the application reports of the UID, directory path, subject,
date, and sender of the message, followed by a table that lists the message's attachments. The table includes the
attachment name, size, and MIME type.

© 2014 Adobe Systems Incorporated. All rights reserved.

388

Adobe ColdFusion Documentation


date range --->
= Now()>
= DateAdd("d","-7", rightNow)>










Message ID #weeksmail.uid# attachments are in the directory
C:\temp\cf_files\attachments\Msg_#i#



Message information:

Subject: #weeksmail.Subject#

Sent: #dateFormat(weeksmail.TimeSent)#

From: #weeksmail.FromID#



Attachments












© 2014 Adobe Systems Incorporated. All rights reserved.

389

Adobe ColdFusion Documentation

cfexchangetask
Description

Creates, deletes, modifies, and gets Microsoft Exchange tasks, and gets task attachments.
Note
For all actions, see cfexchangeconnection for additional attributes that you use if you do not
specify the connection attribute.

History

ColdFusion 10: Added the attribute serverVersion.ColdFusion 8: Added this tag.
Category

Communications tags
Syntax

© 2014 Adobe Systems Incorporated. All rights reserved.

390

Adobe ColdFusion Documentation

create

delete

deleteAttachments

get

getAttachments

modify

optional
connection = "connection ID">

© 2014 Adobe Systems Incorporated. All rights reserved.

391

Adobe ColdFusion Documentation

Note
If you omit the connection attribute, create a temporary connection by specifying cfexchange
connection tag attributes in the cfexchangetask tag. In this case, ColdFusion closes the
connection when the tag completes. For details, see the cfexchangeconnection tag open ac
tion.
Note
You can specify this tag's attributes in an attributeCollection attribute whose value is a
structure. Specify the structure name in the attributeCollection attribute and use the tag's
attribute names as structure keys.

See also

cfexchangecalendar, cfexchangeconnection, cfexchangecontact, cfexchangefilter, cfexchange
mail, Interacting with Microsoft Exchange Servers in the Developing ColdFusion Applications.
Attributes

The following table provides detailed information about each attribute. It lists the attribute name, the actions (actio
n attribute values) to which it apples, whether it is required or optional for those actions, and its default value, if any,
and provides a detailed description of the attribute and its valid values.
Attribute

Action

Req/Opt

action

all

Required

Default

Description
The action to take.
Must be one of the
following values:
create
delete
deleteAttachm
ents
get
getAttachment
s
modify

© 2014 Adobe Systems Incorporated. All rights reserved.

392

Adobe ColdFusion Documentation

attachmentPath

getAttachments

Optional

The filepath of the
directory in which to
put the attachments.
If the directory does
not exist,
ColdFusion creates
it.
Note: If you omit
this attribute,
ColdFusion does not
save any
attachments. If you
specify a relative
path, the path root is
the ColdFusion
temporary directory,
which is returned by
the GetTempDirec
tory function.

connection

all

Optional

The name of the
connection to the
Exchange server, as
specified in the cfe
xchangeconnecti
on tag. If you omit
this attribute, create
a temporary
connection by
specifying cfexcha
ngeconnection ta
g connection
attributes in the cfe
xchangetask tag.

© 2014 Adobe Systems Incorporated. All rights reserved.

393

Adobe ColdFusion Documentation

generateUniqueF
ilenames

getAttachments

Optional

name

getgetAttachmen
ts

Required

The name of the
ColdFusion query
variable that
contains the
returned task
records or
information about
the attachments that
were retrieved. For
more information on
the returned data,
see Usage.

result

create

Optional

The name of a
variable that
contains the UID of
the task that is
created. You use
this value in the uid
attribute of other
actions to identify
the task to be acted
on.

© 2014 Adobe Systems Incorporated. All rights reserved.

no

A Boolean value
that specifies
whether to generate
unique filenames if
multiple attachments
have the same
filenames. If two or
more attachments
have the same
filename and this
option is yes, Cold
Fusion appends a
number to the
filename body
(before the
extension) of any
conflicting
filenames. Thus, if
three attachments
have the name
myfile.txt,
ColdFusion saves
the attachments as
myfile.txt,
myfile1.txt, and
myfile2.txt.

394

Adobe ColdFusion Documentation

Optional

serverVersion

2007

Specifies the
Microsoft Exchange
Server version. The
values are:
2003
2007
2010
If you do not
specify the
details, 2007 is
taken by default.
The value you
specify overrides
the value that you
specify at the
application level.

task

createmodify

Required

A reference to the
structure that
contains the task
properties to be set
or changed and their
values. Specify this
attribute in number
signs (#).
For more
information on the
event structure, see
Usage.

uid

deletegetAttach
mentsmodify

Required

A case-sensitive
Exchange UID value
that uniquely
identifies the tasks
on which to perform
the action. For the d
elete action, this
attribute can be a
comma-delimited list
of UID values. The d
eleteAttachment
s,
getAttachments,
and modify actions
allow only a single
UID value.

When you specify the create or modify action, the task attribute must specify a structure that contains
information that defines the events. The structure can have the following fields. Include only the fields that you are
setting or changing.

© 2014 Adobe Systems Incorporated. All rights reserved.

395

Adobe ColdFusion Documentation

Column

Description

ActualWork

A number in minutes. Cannot be less than zero.

Attachments

The pathnames of any attachments to include in the
task. To specify multiple files, separate filepaths with
semicolons (;) for Windows, and colons (:) for UNIX
and Linux. Use absolute paths.
If you specify one or more attachments for a modify a
ction, these are added to any existing attachments; the
pre-existing attachments are not deleted.

Categories

A comma-delimited list of categories. The filter
searches for tasks that match all the categories in the
list.

BillingInfo

A string.

Companies

A string.

DateCompleted

A string in a date format that is valid in ColdFusion. If
you omit this field and set the Status field to complet
ed, or set the PercentCompleted field to 100, this
value is set to the current date. If you set this date, the
Status value is set to Completed and the PercentC
ompleted field is set to 100.

DueDate

A string in a date format that is valid in ColdFusion.

Message

A string containing the task description.

Mileage

A string.

PercentCompleted

A number in the range 0-100. If you set this field to 100,
The following values are set:
The Status value is set to Completed.
If the DateCompleted value is or was not set, it is
set to the current date.
If you set this value to a number with a value less
than 100, the following values are set:
If Status field is or was set to Completed, the Sta
tus is set to In_Progress.
The DateCompleted value is cleared.

Priority

One of the following values:
low
normal
high

© 2014 Adobe Systems Incorporated. All rights reserved.

396

Adobe ColdFusion Documentation

ReminderDate

A string in a date format that is valid in ColdFusion.

StartDate

A string in a date format that is valid in ColdFusion.
When you create a task, the default value defaults is
the current date.

Status

The following values are valid: Not_Started, In_Pro
gress, Completed, Waiting, or Deferred. If you
omit this field and the PercentCompleted value is
less than 100, the Status value it is set to In_Progr
ess.
If you set this field to Completed, the following values
are also set:
The PercentCompleted value is set to 100.
If the DateCompleted value is not set, it is set to
the current date.
If you set this field to a value other than Completed,
the following values are also set:
If the PercentCompleted field is or was 100, the P
ercentCompleted value is reset to 0.
The DateCompleted value is set to 0.

Subject

A String.

TotalWork

A number in minutes. Cannot be less than zero.

Usage

The cfexchangetask tag manages task records on the Exchange server. Use the cfexchangetask tag to
perform the following actions:
Create a task.
Delete one or more tasks.
Get one or more task records that conform to an optional set of filter specifications, such as the last name, job
title, or home phone number, and so on.
Get the attachments for a specific task record.
Modify an existing task
To use this tag, you must have a connection to an Exchange server. If you are using multiple tags that
interact with the exchange server, such as if you are creating several task records, use the cfexchangecon
nection tag to create a persistent connection. You then specify the connection identifier in each cfexchan
getask, or any other ColdFusion Exchange tag, if you are also accessing calendar entries, contacts, or mail.
Doing this saves the overhead of creating and closing the connection for each tag.Alternatively, you can
create a temporary connection that lasts only for the time that ColdFusion processes the single cfexchange
task tag. To do this, you specify the connection attributes directly in the cfexchangetask tag. For details
on the connection attributes, see the cfexchangeconnection tag.
The delete action

When you specify the delete action, specify a uid attribute with a comma-delimited list of one or more Exchange
UIDs that identify the tasks to delete. You can use the get action, with an appropriate filter expression, to determine

© 2014 Adobe Systems Incorporated. All rights reserved.

397

Adobe ColdFusion Documentation

the UID values to specify.
If all UIDs that you specify are invalid, the cfexchangetask tag generates an error. If at least one UID is valid, the
tag ignores any invalid UIDs and deletes the items specified by the valid UID.
The get action

When you specify the get action, the query object specified by the name attribute contains one record for each
retrieved task. The query object has columns with the same names and data formats as the fields listed for the task
attribute structure, with the following differences:
The query object has a Boolean HasAttachment column, and does not have an Attachments column. If
the HasAttachment field value is yes, use the getAttachments action to retrieve the attachments.
The query object has an additional UID column with the unique identifier for the task in the Exchange server.
You can use this value in the uid attribute of the getAttachments, delete, and modify actions to identify
the required task.
The query object has an additional HtmlMessage column. The Message column has a plain-text version of
the task description, and the HtmlMessage column text includes the description's HTML formatting.
You use child cfexchangefilter tags to specify the messages to get. For detailed information, see cfexc
hangefilter.
The getAttachments action

When you use the getAttachments action, specify a single UID and a name attribute. The cfexchangetask tag
populates a query object specified by the name attribute with the specified name. Each record has the following
information about an attachment to the specified task:
Column name

Description

attachmentFileName

The filename of the attachment.

attachmentFilePath

The absolute path of the attachment file on the server.
If you omit the attachmentPath attribute, this column
contains the empty string.

CID

The content-ID of the attachment. Typically used in
HTML img tags to embed images in a message.

mimeType

The MIME type of the attachment, such as text/html

isMessage

A Boolean value that specifies whether the attachment
is a message.

size

The attachment size, in bytes.

The tag places the attachments in the directory specified by the attachmentPath attribute. If you omit the attach
mentPath attribute, ColdFusion does not get any attachments, it gets the information about the attachments. This
lets you determine the attachments without incurring the overhead of getting the attachment files.Use the following
syntax to specify an in-memory attachmentPath directory. In-memory files are not written to disk and speed
processing of transient data.

© 2014 Adobe Systems Incorporated. All rights reserved.

398

Adobe ColdFusion Documentation

attachmentpath = "ram:///path"

The path can include multiple directories, for example ram:///petStore/orders/messageAttachments.
Create all directories in the path before you specify the file. For more information on using in-memory files, see Work
ing with in-memory files in Optimizing ColdFusion applications in the Developing ColdFusion Applications.
The getAttachments action works only if authentication for EWS (Exchange Web Services) is set to basic in the
server setup of Exchange. IWA (Integrated Windows Authentication) is not supported.
The modify action

If you specify the modify action, the uid attribute must specify a single Exchange UID. The task structure must
specify only the fields that you are changing. Any fields that you do not specify remain unchanged. For a detailed
description of the contents of the task structure, see the Attributes section.
If a task has attachments and you specify attachments when you modify the task, the new attachments are added to
the previous attachments, and do not replace them. Use the deleteAttachments action to remove any
attachments.
Example

The following example uses a transient connection to create a single task:



stask=StructNew();
stask.Priority="high";
stask.Status="Not_Started";
stask.DueDate="3:00 PM 09/14/2007";
stask.Subject="My New Task";
stask.PercentCompleted=0;
Message="Do this NOW!";






© 2014 Adobe Systems Incorporated. All rights reserved.

399

Adobe ColdFusion Documentation

cfexecute
Description

Executes a ColdFusion developer-specified process on a server computer.
Category

Extensibility tags, Flow-control tags
Syntax


...


Note
You can specify this tag's attributes in an attributeCollection attribute whose value is a
structure. Specify the structure name in the attributeCollection attribute and use the tag's
attribute names as structure keys.

See also

cfcollection, cfindex, cfobject, cfreport, cfsearch, cfwddx
History

ColdFusion MX 6.1:
Added the variable attribute.
Changed filepath behavior for the outputFile attribute: if you do not specify an absolute filepath in the out
putFile attribute, the path is relative to the ColdFusion temporary directory.
Attributes

Attribute

Req/Opt

name

Required

© 2014 Adobe Systems Incorporated. All rights reserved.

Default

Description
Absolute path of the
application to execute.On
Windows, specify an
extension, for example,
C:\myapp.exe.

400

Adobe ColdFusion Documentation

arguments

Optional

Command-line variables
passed to application. If
specified as string, it is
processed as follows:
Windows: passed to
process control
subsystem for parsing.
UNIX: tokenized into an
array of arguments. The
default token separator
is a space; you can
delimit arguments that
have embedded spaces
with double-quotation
marks.
If passed as array, it is
processed as follows:
Windows: elements are
concatenated into a
string of tokens,
separated by spaces.
Passed to process
control subsystem for
parsing.
UNIX: elements are
copied into an array of
exec() arguments.

outputFile

Optional

File to which to direct
program output. If no out
putfile or variable at
tribute is specified, output
is displayed on the page
from which it was called. If
not an absolute path
(starting with a drive letter
and a colon, or a forward
or backward slash), it is
relative to the ColdFusion
temporary directory, which
is returned by the GetTem
pDirectory function.

errorFile

Optional

File in which to direct error
output, if any exists.

© 2014 Adobe Systems Incorporated. All rights reserved.

401

Adobe ColdFusion Documentation

timeout

Optional

0

Length of time, in
seconds, that ColdFusion
waits for output from the
spawned program.
0: equivalent to
nonblocking mode.
A very high value:
equivalent to blocking
mode.
If the value is 0:
ColdFusion starts a
process and returns
immediately.
ColdFusion may return
control to the calling
page before any
program output
displays. To ensure that
program output
displays, set the value
to 2 or higher.
If the outputFile attri
bute is not specified,
any program output is
discarded

variable

Optional

Variable in which to put
program output. If no out
putfile or variable a
ttribute is specified,
output is displayed on
page from which it was
called.

errorVariable

Optional

Variable in which to put
error output, if any exists.

Usage

Do not put other ColdFusion tags or functions between the start and end tags of cfexecute. You cannot nest cfex
ecute tags.
Exceptions

Throws the following exceptions:
If the application name is not found: java.io.IOException
If the effective user of the ColdFusion executing thread does not have permissions to execute the process: a
security exception
The time-out values must be between zero and the longest time-out value supported by the operating system.
Example

© 2014 Adobe Systems Incorporated. All rights reserved.

402

Adobe ColdFusion Documentation

cfexecute
This example executes the Windows NT version of the netstat network monitoring
program, and places its output in a file.



© 2014 Adobe Systems Incorporated. All rights reserved.

403

Adobe ColdFusion Documentation

cfexit
Description

This tag aborts processing of the currently executing CFML custom tag, exits the page within the currently executing
CFML custom tag, or re-executes a section of code within the currently executing CFML custom tag.
Category

Debugging tags, Flow-control tags
Syntax



Note
You can specify this tag's attributes in an attributeCollection attribute whose value is a
structure. Specify the structure name in the attributeCollection attribute and use the tag's
attribute names as structure keys.

See also

cfabort, cfbreak, cfexecute, cfif, cflocation, cfloop, cfswitch, cfthrow, cftry; cfabort and cfexit i
n the Developing ColdFusion Applications
Attributes

Attribute

Req/Opt

Default

method

Optional

exitTag

Description
exitTag: aborts
processing of currently
executing tag.
exitTemplate: exits
page of currently
executing tag.
loop: re-executes body
of currently executing
tag.

Usage

If this tag is encountered outside the context of a custom tag, for example in the base page or an included page, it
executes in the same way as cfabort. The cfexit tag can help simplify error checking and validation logic in
custom tags. The cfexit tag function depends on its location and execution mode:
Method value

Location of cfexit call

Behavior

exitTag

Base page

Terminate processing

© 2014 Adobe Systems Incorporated. All rights reserved.

404

Adobe ColdFusion Documentation

exitTemplate

loop

Execution mode = Start

Continue after end tag

Execution mode = End

Continue after end tag

Base page

Terminate processing

Execution mode = Start

Continue from first child in body

Execution mode = End

Continue after end tag

Base page

Error

Execution mode = Start

Error

Execution mode = End

Continue from first child in body

Example

© 2014 Adobe Systems Incorporated. All rights reserved.

405

Adobe ColdFusion Documentation

cfexit Example
cfexit can be used to abort the processing of the currently executing CFML custom
tag. Execution resumes following the invocation of the custom tag in the page that
called the tag.
Usage of cfexit
cfexit is used primarily to perform a conditional stop of processing inside a
custom tag. cfexit returns control to the page that called that custom tag, or in
the case of a tag called by another tag, to the calling tag.








If cfexit is used outside a custom tag, it functions like a cfabort. For example,
the text after this message is not processed:

This text is not executed because of the cfexit tag above it.

#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

406

Adobe ColdFusion Documentation

Tags f
This section lists tags starting with alphabet F with their description.
cffeed
cffile
cffile action = "append"
cffile action = "copy"
cffile action = "delete"
cffile action = "move"
cffile action = "read"
cffile action = "readBinary"
cffile action = "rename"
cffile action = "upload"
cffile action = "uploadAll"
cffile action = "write"
cffileupload
cffinally
cfflush
cfformgroup
cfformitem
cfftp
cfftp: Opening and closing FTP server connections
cfftp: Opening and closing secure FTP server connections
cfftp: Connection: file and directory operations
cfftp action = "listDir"
cfform
cffunction

© 2014 Adobe Systems Incorporated. All rights reserved.

407

Adobe ColdFusion Documentation

cffeed
Description

Reads or creates an RSS or Atom syndication feed. This tag can read RSS versions 0.90, 0.91, 0.92, 0.93, 0.94,
1.0, and 2.0, and Atom 0.3 or 1.0. It can create RSS 2.0 or Atom 1.0 feeds.
Category

Communications tags, Internet protocol tags
Syntax

© 2014 Adobe Systems Incorporated. All rights reserved.

408

Adobe ColdFusion Documentation

create
required

escapeChars = "true|false">

outputFile = "path"

OR
required

read
required


Note
You can specify this tag's attributes in an attributeCollection attribute whose value is a
structure. Specify the structure name in the attributeCollection attribute and use the tag's
attribute names as structure keys.

History

© 2014 Adobe Systems Incorporated. All rights reserved.

409

Adobe ColdFusion Documentation

ColdFusion 8: Added this tag.
ColdFusion 9: The escapeChars attribute is newly added.
Attributes

Attribute

Req/Opt

Default

Description

action

Optional

read

The action to take, one of
the following values:
create: creates an
RSS 2.0 or Atom 1.0
feed XML document
and saves it in a
variable, writes it to a
file, or both.
read: parses an RSS
or Atom feed from a
URL or an XML file and
saves it in a structure or
query. You can also get
feed metadata in a
separate structure.

columnMap

Optional

© 2014 Adobe Systems Incorporated. All rights reserved.

Used only for the create
action with a query attrib
ute.A structure that
specifies a mapping
between the names of the
columns in the object
specified by the query att
ribute and the columns of
the ColdFusion feed
format (see the section
Query object rules.
The key for each field
must be a column name
(see the table in the
Query object rules
section). The value of the
field must be the name of
the corresponding column
in the query object used
as input to the create ac
tion.

410

Adobe ColdFusion Documentation

enclosureDir

Optional

escapeChars

Optional

© 2014 Adobe Systems Incorporated. All rights reserved.

Used only for the read ac
tion. Path to the directory
in which to save any
enclosures that are
available in the feed being
read. The path can be
absolute or relative to the
CFML file.
If the directory does not
exist, ColdFusion
generates an error. If you
omit this attribute,
ColdFusion does not save
enclosures. To specify the
directory that contains the
current page, set this
attribute to " ." (period).
false

Used only for the create
action. If this attribute is t
rue, escapes/replaces all
the invalid characters as
per W3C specification. No
te: Japanese characters
that are not part of UTF-8
encoding are replaced.
Non-UTF-8 Japanese
characters remain in the
feed as they are.
If this attribute is false,
does not escape invalid
characters and tries to
generate feed. If JDOM
fails to write the file with
these invalid characters,
the error message "Invalid
Character in Input" is
displayed.

411

Adobe ColdFusion Documentation

ignoreEnclosureErro
r

Optional

name

See Note

no

If this attribute is yes,
ColdFusion attempts to
save all enclosures. If it
encounters an error
downloading one
enclosure, it continues
downloading other
enclosures and writes the
error information in the
server log. If this attribute
is no, when ColdFusion
encounters an error
downloading an
enclosure, it stops
downloading all
enclosures and generates
an error.
Note: Enclosure errors
can occur if the specified
enclosure is of a type that
the web server does not
allow to be downloaded.
A structure that contains
complete feed data:
The output of a read ac
tion.
The input definition of
the feed to create.
When you specify the n
ame attribute for a crea
te action, enclose it in
number signs (#).
For more information,
see Name and
properties structure
rules section.

outputFile

See Note

© 2014 Adobe Systems Incorporated. All rights reserved.

Path of the file in which to
write the feed as XML
text.
The path can be absolute,
or relative to the CFML
file.

412

Adobe ColdFusion Documentation

overwrite

Optional

no

Whether to overwrite the
XML feed file if it exists. If
you do not set this
attribute to yes and the c
ffeed tag tries to write to
a file that exists,
ColdFusion generates an
error.

overwriteEnclosure

Optional

no

Used only for the read ac
tion. Whether to overwrite
files in the enclosure
directory if they exist. If
you do not set this
attribute to yes and the c
ffeed tag tries to write to
a file that exists,
ColdFusion generates an
error.

properties

See Note

A structure that contains
the feed metadata, the
information about the
entire feed. Can contain
either of the following:
The output of a read ac
tion.
Input to a create actio
n.
The properties and
query attributes
combined provide
complete feed
information.
When you specify the p
roperties attribute for
a create action,
enclose it in number
signs (#).
For more information,
see Name and
properties structure
rules section.

proxyPassword

Optional

proxyPort

Optional

© 2014 Adobe Systems Incorporated. All rights reserved.

Password required by the
proxy server.
80

The port to connect to on
the proxy server.

413

Adobe ColdFusion Documentation

proxyServer

Optional

Host name or IP address
of a proxy server to which
to send the request.

proxyUser

Optional

User name to provide to
the proxy server.

query

See Note

A query object that
contains the Atom entries
or RSS items in the feed.
Can contain either of the
following:
The output of a read ac
tion.
Input to a create actio
n.
The properties and
query attributes
combined provide
complete feed
information.
When you specify the q
uery attribute for a cre
ate action, enclose it in
number signs (#).
For more information,
see section Query
object rules.

source

Required

timeout

Optional

© 2014 Adobe Systems Incorporated. All rights reserved.

Used only for the read ac
tion. The URL of the feed
or the path to the XML file
that contains the feed
contents. A path can be
absolute, or relative to the
CFML file.
Request time-out

The number of seconds to
wait for a response from
the feed source. A value
of 0 specifies that the
request does not time out.
By default, ColdFusion
uses the request time-out
setting of the ColdFusion
Administrator Server
Settings > Settings page.

414

Adobe ColdFusion Documentation

userAgent

Optional

xmlVar

See Note

Cold Fusion

Text to put in the HTTP
User-Agent request
header field. Used to
identify the request client
software.
A variable in which to
save the read or created
feed as XML text.

Usage
Specifying file and directory attributes

Use the following syntax to specify an in-memory file or directory. In-memory files are not written to disk and speed
processing of transient data.

ram:///filepath

A filepath can include multiple directories, for example ram:///petStore/images/poodle.jpg. Create the
directories in the path before you specify the file. For more information on using in-memory files, see Working with
in-memory files in Optimizing ColdFusion applications in the Developing ColdFusion Applications.
Setting and getting feed information

The cffeed tag lets you specify and save feed data in many, flexible ways.
Usage

Use the following syntax to specify an in-memory file, which is not written to disk. In-memory files speed processing
of transient data.

ram:///filepath

The filepath can include directories, for example ram:///petStore/images/poodle.jpg. Create the directories
in the path before you specify the file. For more information on using in-memory files, see Working with in-memory
files in Optimizing ColdFusion applications in the Developing ColdFusion Applications.
When you create a feed
You specify the feed data in either of the following ways:
By putting all metadata and entry or item data in a single structure specified by the name attribute.
By putting the metadata in a structure specified by the properties structure and the entries or items
as rows in a query object specified by the query attribute.
You save the resulting feed XML in one or both of the following places:
A file specified by the OutputFile attribute. The cffeed tag saves the data in UTF-8 encoding.
An variable specified by the xmlVar attribute
When you read a feed You can save the feed data in any combination of the following forms:

© 2014 Adobe Systems Incorporated. All rights reserved.

415

Adobe ColdFusion Documentation

By saving all entry or item data and metadata in a single structure specified by the name attribute
By saving entries or items as rows in a query object specified by the query attribute
By saving the metadata in a structure specified by the properties structure
By writing the feed XML in a file specified by the OutputFile attribute. The cffeed tag saves the data in
UTF-8 encoding.
By saving the feed XML in a ColdFusion XML variable specified by the xmlVar attribute
When you save feed data, you do not have to save both the metadata and the entry or item data. You can
specify only the properties attribute, or only the query attribute.
Name and properties structure rules

The name and properties structures must conform to the following rules. For more information on requirements
for specific metadata entries, see the section Representing feed metadata.
All structure key names must be identical to the corresponding feed element names, with the exception of the
version and encoding fields. Also, the key names for Dublin Core and Apple iTunes extension elements
start with DC_ and ITUNES_ respectively.
The properties structure fields are identical to the metadata fields in the name structure.
When you read a feed, the structure contains only those elements and attribute values that exist in the feed.
For requirements for the create action, see the section Creating feeds.
If the feed can have multiple elements of the same type (such as entry, item, or link), the name or prope
rtystructure has a single entry that contains the data for all of the elements. The structure entry has the
following format:
The key is the element name (for example, item)
The value is an array of structures
Each structure in the array represents one element.
ColdFusion uses an array even if there is only a single element. If an Atom feed has only one link ele
ment, for example, you must specify that element in a nameattribute structure by using the following
format:

structureName.link[1]

For example, to specify a linkmetadata entry in an Atom 1.0 feed, you could use the following code:





If an element can have multiple attributes, or can have at least one attribute and a value, the element is
represented as a structure, even if the element specifies only one attribute or only a value.
If an element has one or more attributes and a value (body), the value is in a field of the element structure
named value. For example, the text of the summary element for the third entryin an Atom feed would go in
a field whose name has the following format:

structureName.entry[3].summary.value.

When the cffeed tag reads a feed, it reports dates as follows:Atom: W3C date format, such as

© 2014 Adobe Systems Incorporated. All rights reserved.

416

Adobe ColdFusion Documentation

2006-07-11T18:19:00Z.RSS: in RFC 822 Format, such as Thu, 05 Oct 2006 18:19:00 GMT.
When the cffeed tag creates a feed, you can use W3C or RFC 822 formats for both feed types. You can
also use any standard date or date/time format accepted by ColdFusion.
Query object rules

The query object specified by the query attribute conforms to the following rules:
The query object format supports multiple feed formats, and many feeds do not include all optional feed
attributes or elements. As a result:
When you read a feed, the returned query object contains entries for all standard RSS and Atom fields,
even for fields that are not supported by the feed type. Any columns that are not used by the feed
format, or are not used in that specific feed, contain empty strings or undefined values.
When you read a feed, the query object contains all iTunes extension fields if the feed contains any
iTunes extension elements, and the query object contains all Dublin Core extension fields if the feed
contains any Dublin Core extension elements. Otherwise, the query results do not contain any of the
extension fields.
When you create a feed, the query that you define requires only those columns that contain data for
your feed; you can omit unused columns.
If a feed entry or item has multiple child elements with the same name, the query column represents the
element values as a comma-delimited list. RSS 2.0 items can have multiple category elements. Atom 1.0
entries can have multiple category, author, contributor, and link elements. The Dublin Core
extensions allow all multiples of all element types.
Many entry or item elements that can have multiple instances have multiple attributes, not all of which are
required for any particular element instance. If an entry or item has multiple instances of an element, and any
of those elements omit attributes, ColdFusion represents the omitted attribute in the lists by a space. In XML,
an Atom entry, for example, might contain three author elements, as follows:


Anthony
http://www.MyCo.com
Tony@MyCo.com


Beverly


Cathy
cathy@MyCo.com


The ColdFusion query represents these columns as follows:
AUTHOR_PERSON

AUTHOR_URI

AUTHOR_EMAIL

Anthony,Beverly,Cathy

http://www.MyCo.com, ,

Tony@MyCo.com,
,cathy@MyCo.com

The following table lists the columns of the standard query object specified by the query attribute. If an RSS feed
includes either Dublin Core extensions or iTunes extensions, the query includes additional columns. For information
on these fields, see the sections Dublin Core Extensions and Apple iTunes Extensions.

© 2014 Adobe Systems Incorporated. All rights reserved.

417

Adobe ColdFusion Documentation

Column

Atom entry

RSS item

AUTHOREMAIL

author element email attribute

author item

AUTHORNAME

author element name attribute

Not used

AUTHORURI

author element uri attribute

Not used

CATEGORYLABEL

category element label attribute

category item value

CATEGORYSCHEME

category element scheme attribut
e

category item domain attribute

CATEGORYTERM

category element term attribute

Not used

COMMENTS

Not used

comments item value

CONTENT

content element value

description item value

CONTENTMODE

content element mode attribute
(Atom 0.3 only)

Not used

CONTENTSRC

content element src attribute

Not used

CONTENTTYPE

content element type attribute

Not used

CONTRIBUTOREMAIL

contributor element email attri
bute

Not used

CONTRIBUTORNAME

contributor element name attrib
ute

Not used

CONTRIBUTORURI

contributor element uri attribut
e

Not used

CREATEDDATE

created element value (Atom 0.3
only)

Not used

EXPIRATONDATE

Not used

expirationDate item value (RSS
0.93 only)

ID

id element value

guid item value

IDPERMALINK

Not used

guid item ispermalink attribute

LINKHREF

link element href attribute

enclosure item url attribute

© 2014 Adobe Systems Incorporated. All rights reserved.

418

Adobe ColdFusion Documentation

LINKHREFLANG

link element hreflang attribute

Not used

LINKLENGTH

link element length attribute

enclosure item length attribute

LINKREL

link element rel attribute

Not used

LINKTITLE

link element title attribute

Not used

LINKTYPE

link element type attribute

enclosure item type attribute

PUBLISHEDDATE

published element value (issue
d in Atom 0.3)

pubDate item value

RIGHTS

rights element value (copyrigh
t in Atom 0.3)

Not used

RSSLINK

Not used

link item value

SOURCE

Not used

source item value

SOURCEURL

Not used

source item url attribute

SUMMARY

summary element value

Not used

SUMMARYMODE

summary element mode attribute
(Atom 0.3 only)

Not used

SUMMARYSRC

Blank for all well-formed Atom
feeds. Contains data only if an
Atom 1.0 feed uses a content ele
ment format for the summary eleme
nt.

Not used

SUMMARYTYPE

summary element type attribute

Not used

TITLE

title element value

title item value

TITLETYPE

title element type attribute

Not used

UPDATEDDATE

updated element value (modifie
d in Atom 0.3)

Not used

URI

Not used

RSS 1.0 link item rdf:about attr
ibute

XMLBASE

content elemen{{t xml:base}}
attribute

Not used

© 2014 Adobe Systems Incorporated. All rights reserved.

419

Adobe ColdFusion Documentation

Representing feed metadata

When you create a feed, the name and properties structures can represent all standard metadata for RSS 2 or
Atom 1 feeds, in the format described in the Name and properties structure rules section. Similarly, when you read a
feed, the structures represent all received metadata. The following rules apply to specific feed metadata fields in the
name and properties structures:
The version field identifies or specifies the feed version in the form format_versionNumber. For the create
action, specify atom_1.0 or rss_2.0. When you read an RSS 0.91 feed, the version field value is rss_0.9
1U, not rss_0.91.
The feedExtension field identifies whether the feed includes iTunes or Dublin Core extension content.
Valid values are itunes and DublinCore. You do not have to specify this field when you create a feed with
iTunes extensions; ColdFusion automatically determines that you have specified extension fields. (You
cannot create a feed with Dublin Core extensions.)
For the read action, an encoding field identifies the XML encoding attribute, such as iso-8859-1. Do not
specify an encoding field for a create action. Currently, ColdFusion generates all feeds in UTF-8 format
and ignores any encoding value that you specify.
For RSS feeds, the skiphours field contains a comma-delimited list of up to 24 numbers in the range 0-23,
specifying hours of the day when aggregators should not read the feed. The hour beginning at midnight is
hour zero. Your application can use the field to decide when to read the feed.
For RSS feeds, the skipdays field contains a comma-delimited list of up to seven day-name values,
specifying days of the week when aggregators must not read the feed. The valid names are Monday, Tuesda
y, Wednesday, Thursday, Friday, Saturday and Sunday. Your application can use the field to decide
when to read the feed.
Dublin Core Extensions

Dublin Core extension elements provide additional metadata about the feed or an item. You can use the cffeed tag
to read feeds that include elements that conform to the Dublin Core Metadata Element Set specification as metadata
(channel elements) or as item elements. For detailed information Dublin Core extension elements, see the Dublin
Core Metadata Element Set specification. At the time this topic was written, this specification was available at http://
dublincore.org/documents/dces/.ColdFusion support for Dublin Core extensions has the following limitations:
You cannot create feeds containing these elements.
You cannot get Dublin Core extension elements that are contained in a top-level (metadata) image element.
ColdFusion ignores these elements.
ColdFusion supports only the Dublin Core Metadata Element Set. It does not support the additional Dublin
Core Metadata Initiative elements and element refinements.
When feed items include the Dublin Core extensions, the query specified by a query attribute includes all of
the columns listed in the following table. If the feed does not include any Dublin Core extension elements, the
query does not include the columns. With the exception of the DC_SUBJECT_TAXONOMURI and DC_SUBJECT
_VALUE columns, each column name (without the DC_ prefix) corresponds directly to a Dublin Core extension
element name.
Column

Description

DC_CONTRIBUTOR

The people or organizations responsible for
contributing to the resource

DC_COVERAGE

The extent of the content in the resource

© 2014 Adobe Systems Incorporated. All rights reserved.

420

Adobe ColdFusion Documentation

DC_CREATOR

The person or organization responsible for creating this
resource

DC_DATE

A date or date and time associated with this resource

DC_DESCRIPTION

A summary of the resource contents

DC_FORMAT

The file format, physical medium, or dimensions of the
resource

DC_IDENTIFIER

A string that can be used to unambiguously identify the
resource

DC_LANGUAGE

The language in which the resource is written

DC_PUBLISHER

The person or organization responsible for making the
resource available.

DC_RELATION

The identifier of a related resource, typically.

DC_RIGHT

Information about the property rights for the resource.

DC_SOURCE

A reference to the material from which this resource
was derived.

DC_SUBJECT_TAXONOMYURI

The taxonomy URI attribute of the Dublin Core subje
ct element

DC_SUBJECT_VALUE

The value of the Dublin Core subject element; a
string that defines the topic of the resource

DC_TITLE

A name to use for the resource

DC_TYPE

The nature or genre of the resource

When you get data for a feed that includes Dublin Core elements as a structure, the element names are identical to
the query column names listed above, with the exception of the representation of the Dublin Core subject element.
The structure format represents the subject element as a dc_subject entry, which consists of an array of
structures. The structures in the array have keys with the names value, for the element value, and taxononmyURI
, for the taxonomyURI attribute.
Apple iTunes Extensions

You can use the cffeed tag to create or read feeds that contain elements defined in the Apple iTunes RSS podcast
specification. For detailed information on iTunes extension format, see the Apple iTunes RSS specification. At the
time this topic was written, this specification was available at http://www.apple.com/itunes/store/podcaststechspecs.
html.
You can create feeds with only a subset of the iTunes RSS extensions. When you read a feed, ColdFusion ignores
all iTunes extension elements that are not in the supported subset. The following table lists the names of structure

© 2014 Adobe Systems Incorporated. All rights reserved.

421

Adobe ColdFusion Documentation

entries or query column names for the supported elements. (These names consist of the ITUNES_ prefix followed by
the iTunes extension element name.) The table also indicates which elements are used in the metadata, which are
used in the individual items, and which can be used in both:
Element

Used in

Description

ITUNES_AUTHOR

Both

Artist name

ITUNES_BLOCK

Both

a value of yes requests to prevent
the podcast or item (episode) from
appearing. When ColdFusion reads
a feed your application must
determine this field's value and take
any appropriate action.

ITUNES_DURATION

Item

The length of the item in second, or
in HH:MM:SS format.

ITUNES_EXPLICIT

Both

A string indicating whether the item
or items contain explicit material.
Valid values are yes, no, and clea
n.

ITUNES_KEYWORDS

Both

A comma-delimited list of words or
phrases used when searching in the
iTunes music store.

ITUNES_SUBTITLE

Both

Short description text, usually only a
few words.

ITUNES_SUMMARY

Both

A longer description (up to 4000
characters)/

You can also use the following channel elements in the name or properties structures.
Element

Description

itunes_category

A structure that specifies the iTunes Music Store
category. The structure has two fields:
category
subcategory
Notice that these element names do not have the it
unes_ prefix.

itunes_image

© 2014 Adobe Systems Incorporated. All rights reserved.

The URL of the artwork for the podcast.

422

Adobe ColdFusion Documentation

itunes_owner

A structure that contains contact information about the
owner of the podcast for communication. The structure
has two fields:
itunes_email
itunes_mail

Creating feeds

When you create a feed, you specify the feed contents in a name structure or in the combination of a query object
and a properties structure. The cffeed tag generates the feed XML and saves in to the variable specified by the
xmlVar attribute, the file specified by the outputFile attribute, or both. To create an RSS 2.0 feed you must
specify the following metadata fields in a name structure or in a properties structure. All other RSS2.0 metadata
fields, and all item fields, are optional.
title
link
description
version (must be "rss_2.0")
The cffeed tag does not enforce any rules on the Atom feed structure that it creates. You are responsible
for ensuring that the feed is valid.
In most cases, a database table uses column names that differ from the column names you must use to
create the feed. Therefore, use the columnmap attribute to map the input query column names to the
required column names. The attribute is a structure whose keys are the column names required by the cffe
edtag and whose values are the corresponding input query columns.
Note
Always capitalize the input query column names irrespective of whether the database
column names are capitalized or not.

The following example creates a feed using the cfartgallery data source's orders table. It maps the orders
table ORDERDATE column to the query publisheddate column, the ADDRESS column to the content column,
and so on. The sample code then displays the generated query XML to show the results.

© 2014 Adobe Systems Incorporated. All rights reserved.

423

Adobe ColdFusion Documentation



SELECT * FROM orders
















Reading feeds

The cffeed tag does not validate the feeds that it reads. It can read invalid or loosely formatted feeds, but ignores
some or all of the invalid content. For example, if you put more than one rights element in the Atom feed (which
invalidates the feed), the cffeed tag ignores the elements after the first one, and doesn't generate an error. Dates
and times in feeds that are being read must be in W3C or RFC 822 format. ColdFusion can also read iTunes
extension dates in the format normally used by the iTunes music store.
Example

The following example creates an RSS feed. Enter fields for the feed title, link, and description elements. Also enter
title, link, and description fields for one item. A second item is optional. The application saves the feed in a
createRSSOutput.xml file in the feedTest subdirectory of the directory that contains the CFML page.




// Create the feed data structure and add the metadata.
myStruct = StructNew();
mystruct.link = form.link;
myStruct.title = form.title;
mystruct.description = form.description;
mystruct.pubDate = Now();
mystruct.version = "rss_2.0";

© 2014 Adobe Systems Incorporated. All rights reserved.

424

Adobe ColdFusion Documentation

/* Add the feed items. A more sophisticated application would use dynamic
variables
and support varying numbers of items. */
myStruct.item = ArrayNew(1);
myStruct.item[1] = StructNew();
myStruct.item[1].description = StructNew();
myStruct.item[1].description.value = form.item1text;
myStruct.item[1].link = form.item1link;
myStruct.item[1].pubDate = Now();
myStruct.item[1].title = form.item1title;
myStruct.item[2] = StructNew();
myStruct.item[2].description = StructNew();
myStruct.item[2].description.value = form.item2text;
myStruct.item[2].link = form.item2link;
myStruct.item[2].pubDate = Now();
myStruct.item[2].title = form.item2title;






 Enter The Feed Metadata
 

 


 Enter Item 1
 

 

 

 Enter Item 2
 

 

 


© 2014 Adobe Systems Incorporated. All rights reserved.

425

Adobe ColdFusion Documentation




The following application is a simple feed reader that handles RSS and Atom feeds. It displays the feed title; for
each item or entry, it shows the title as a link, and shows the published date and the item or entry contents. To use
this example to read the feed created by the first application, enter the URL for the file the application created, for
example, http://localhost:8500/cffeed/feedTest/createRSSOutput.xml.






#myProps.title#



#title#
Published: #DateFormat(publisheddate)#

#title#
Published: #publisheddate#

#content#




Enter Feed URL:






© 2014 Adobe Systems Incorporated. All rights reserved.

426

Adobe ColdFusion Documentation

cffile
Description

Manages interactions with server files. The following sections describe the actions of the cffile tag:
cffile
cffile
cffile
cffile
cffile
cffile
cffile
cffile
cffile
cffile

action
action
action
action
action
action
action
action
action
action

=
=
=
=
=
=
=
=
=
=

"append"
"copy"
"delete"
"move"
"read"
"readBinary"
"rename"
"upload"
"uploadAll"
"write"

Note
To execute, this tag must be enabled in the ColdFusion Administrator. For more
information, see Configuring and Administering ColdFusion.

If your ColdFusion applications run on a server used by multiple customers, consider the security of the files
that could be uploaded or manipulated by cffile. For more information, see Configuring and Administering
ColdFusion.
Category

File management tags
Syntax

The tag syntax depends on the action attribute value. See the following sections.
See also

cfdirectory
History

ColdFusion 10: Modifications to the attribute accept}}
ColdFusion 9: {{uploadAll action
ColdFusion 8: Support for reading and writing cfimages.
ColdFusion MX 7:
Added the result attribute, which allows you to specify an alternate variable in which to receive result
parameters. Used for action = "upload" action.
Added the fixnewline attribute for action = "append" and action = "write" actions.
ColdFusion MX 6.1:
Changed file path requirements: if you do not specify an absolute file path, the path is relative to the
ColdFusion temporary directory, which is returned by the GetTempDirectory function.
Changed behavior for action="read": if the file starts with a byte order mark (BOM) ColdFusion uses it to

© 2014 Adobe Systems Incorporated. All rights reserved.

427

Adobe ColdFusion Documentation

determine the character encoding.
Changed behavior for action="upload" nameConflict="MakeUnique" ColdFusion now makes
filenames unique by appending a incrementing number, 1 for the first file, 2 for the second and so on, to the
name. In ColdFusion, filenames were made unique by appending an additional "1" for each file, as in 1, 11,
111, and so on.
ColdFusion MX:
Changed use of slashes in paths: you can use forward or backward slashes in paths on both UNIX and
Windows systems.
Changed file hierarchy requirements: ColdFusion does not require that you put files and directories that you
manipulate with this tag below the root of the web server document directory.
Changed directory path requirements for the destination attribute: a directory path that you specify in the
destination attribute does not require a trailing slash.
Deprecated the system value of the attributes attribute.
Deprecated the temporary value of the attributes attribute. In ColdFusion, it is a synonym for normal. It
might not work in later releases.
Changed the action attribute options read, write, append and move: they support a new attribute, chars
et.
The archive value of the attributes attribute is obsolete and has no effect.
Provide file content in the tag body

For cffile action = "append" and cffile action = "write", you can provide file content in the tag
body. If you provide file content in both the tag body and the output attribute, it results in an error. In the following
example, the text provided in the body is written to myfile.txt in the current directory.Now assume that the file does
not exist, then a new file myfile.txt is created. If the file exists, it is overwritten.





some tag body


File Length = #Len(content)#


#cfcatch.message#

#cfcatch.detail#






Similarly, if you use cffile action="append", the tag body content is appended to the contents of the file
myfile.txt. To create an empty file, you have to provide at least a blank line in the tag body as shown in the following
code:

© 2014 Adobe Systems Incorporated. All rights reserved.

428

Adobe ColdFusion Documentation





Modifications to the attribute accept in ColdFusion 10

The attribute accept takes comma-separated list of any or all extensions, MIME type, or list of MIME types as
values. Specify the extensions with a . prefix. That is, only .txt is supported and not txt, *.txt, or *.*.
However, you can use * as a wildcard to accept all files.
If you specify filename extension as value, the file is checked, only to ensure if it matches the list of
extensions you specified in comma-separated list. If it matches, the file is uploaded.
If the value is MIME type or list of MIME types and the attribute strict is set to true, then the first few
bytes of the file are read to determine the MIME type. If MIME type matches with what you have specified,
upload occurs, else results in an error. The default value of strict is false.
If you specify both filename extensions and MIME types and if strict is set to false, the verification is
based on the order in which you have specified the values. For example, if the first value is .txt, then the
.txt file is uploaded.
If strict is set to true, extensions are ignored.
Example: Using the attribute accept to verify the filename extension

upload.cfm






#cfhttp.filecontent#


#CFCATCH.message#

#CFCATCH.detail#






_upload.cfm

© 2014 Adobe Systems Incorporated. All rights reserved.

429

Adobe ColdFusion Documentation










#CFCATCH.message#

#CFCATCH.detail#







#qFileList.recordcount#
file(s) uploaded








In this example, accept is set to .txt and strict is not specified (and therefore is false by default). So, only files
with .txt extensions are considered for upload.Even if the file is originally a PDF ( sample.pdf) renamed as samp
le.txt, the file is uploaded (since strict is not set to true).
If you specify strict=true, then if the file is originally a .txt (and not renamed from some other type) the file is
uploaded only if the correct MIME type is specified. That is, strict=true requires MIME type to be specified in the
accept attribute. So, you should explicitly say accept="text/plain" in _upload.cfm.
Example 2: Using MIME type

Modify the Example 1 by specifying accept="application/pdf" in _upload.cfm as follows:



© 2014 Adobe Systems Incorporated. All rights reserved.

430

Adobe ColdFusion Documentation

Since strict = true, only files of type PDF are considered for upload. To use a different file, modify the the
following section of upload.cfm:



Example 3: Using both extension and MIME type

Modify the Example 1 by specifying the following in _upload.cfm:



Only PDF files are uploaded because strict = true. If you set strict as false, then both the files are uploaded.
To use a different file, modify the following snippet of upload.cfm:



Example
















© 2014 Adobe Systems Incorporated. All rights reserved.

431

Adobe ColdFusion Documentation















Type in some text to include in your file:
 


A file exists (foobar.txt, in #GetTempDirectory()#).
You may add to it, read from it, or delete it. 


<cfif readText is not "">
<cfoutput>#readText#</cfoutput>
</cfif>



Make new file


Add to existing file
Delete file
Read existing file




© 2014 Adobe Systems Incorporated. All rights reserved.

432

Adobe ColdFusion Documentation


 --->

© 2014 Adobe Systems Incorporated. All rights reserved.

433

Adobe ColdFusion Documentation

cffile action = "append"
Description

Appends text to a text file on the server.
Syntax



Note
You can specify this tag's attributes in an attributeCollection attribute whose value is a
structure. Specify the structure name in the attributeCollection attribute and use the tag's
attribute names as structure keys.

See also

cfdirectory
History

See the History section of the main cffile tag page.
Attributes

Attribute

Req/Opt

action

Required

Type of file manipulation
that the tag performs.

file

Required

Pathname of the file to
which to append content
of output attribute.
If not an absolute path
(starting with a drive letter
and a colon, or a forward
or backward slash), it is
relative to the ColdFusion
temporary directory, which
is returned by the GetTem
pDirectory function.

© 2014 Adobe Systems Incorporated. All rights reserved.

Default

Description

434

Adobe ColdFusion Documentation

output

Required

addNewLine

Optional

attributes

Optional

String to append to the
file.
yes

yes: appends newline
character to text written
to file.
no
Applies to Windows. A
comma-delimited list of
attributes to set on the file.
If omitted, the file's
attributes are
maintained.Each value
must be specified
explicitly. For example, if
you specify attributes
= "readOnly", all other
attributes are overwritten.
readOnly
hidden
normal

charset

Optional

JVM default file character
set

The character encoding in
which the file contents is
encoded. The following
list includes commonly
used values:
utf-8
iso-8859-1
windows-1252
us-ascii
shift_jis
iso-2022-jp
euc-jp
euc-kr
big5
euc-cn
utf-16
For more information
character encodings,
see www.w3.org/Intern
ational/O-charset.html.

© 2014 Adobe Systems Incorporated. All rights reserved.

435

Adobe ColdFusion Documentation

fixnewline

Optional

mode

Optional

No

yes: changes
embedded line-ending
characters in string
variables to
operating-system
specific line endings
no: (default) do not
change embedded
line-ending characters
in string variables.
For an example that
uses this attribute, see
cffile action =
"write".
Applies only to UNIX and
Linux. Permissions. Octal
values of UNIX chmod co
mmand. Assigned to
owner, group, and other,
respectively; for example:
644: assigns read/write
permission to owner;
read permission to
group and other.
777: assigns
read/write/execute
permission to all.

Example






© 2014 Adobe Systems Incorporated. All rights reserved.

436

Adobe ColdFusion Documentation

cffile action = "copy"
Description

Copies a file from one directory to another on the server.
Syntax



Note
You can specify this tag's attributes in an attributeCollection attribute whose value is a
structure. Specify the structure name in the attributeCollection attribute and use the tag's
attribute names as structure keys.

See also

cfdirectory
History

See the History section of the main cffile tag page.
Attributes

Attribute

Req/Opt

action

Required

Type of file manipulation
that the tag performs.

destination

Required

Pathname of a directory
or file on web server
where the file is copied. If
you specify a filename
without a directory path,
ColdFusion copies it
relative to the source
directory.

© 2014 Adobe Systems Incorporated. All rights reserved.

Default

Description

437

Adobe ColdFusion Documentation

source

Required

Pathname of the file to
copy. If not an absolute
path (starting with a drive
letter and a colon, or a
forward or backward
slash), it is relative to the
ColdFusion temporary
directory, which is
returned by the GetTemp
Directory function.

attributes

Optional

Applies to Windows. A
comma-delimited list of
attributes to set on the file.
If omitted, the file's
attributes are
maintained.Each value
must be specified
explicitly. For example, if
you specify attributes
= "readOnly", all other
attributes are overwritten.
readOnly
hidden
normal

Optional

mode

Applies only to UNIX and
Linux. Permissions. Octal
values of UNIX chmod co
mmand. Assigned to
owner, group, and other,
respectively; for example:
644: assigns read/write
permission to owner;
read permission to
group and other.
777: assigns
read/write/execute
permission to all.

Example

This example copies the keymemo.doc file to the c:\files\backup\ directory:



© 2014 Adobe Systems Incorporated. All rights reserved.

438

Adobe ColdFusion Documentation

cffile action = "delete"
Description

Deletes a file on the server.
Syntax



Note
You can specify this tag's attributes in an attributeCollection attribute whose value is a
structure. Specify the structure name in the attributeCollection attribute and use the tag's
attribute names as structure keys.

See also

cfdirectory
Attributes

Attribute

Req/Opt

Default

Description

action

Required

Type of file manipulation
that the tag performs.

file

Required

Pathname of the file to
delete. If not an absolute
path (starting with a drive
letter and a colon, or a
forward or backward
slash), it is relative to the
ColdFusion temporary
directory, which is
returned by the GetTemp
Directory function.

Example

The following example deletes the specified file:



© 2014 Adobe Systems Incorporated. All rights reserved.

439

Adobe ColdFusion Documentation

cffile action = "move"
Description

Moves a file from one location to another on the server.
Syntax



Note
You can specify this tag's attributes in an attributeCollection attribute whose value is a
structure. Specify the structure name in the attributeCollection attribute and use the tag's
attribute names as structure keys.

See also

cfdirectory
History

See the History section of the main cffile tag page.
Attributes

Attribute

Req/Opt

action

Required

Type of file manipulation
that the tag performs.

destination

Required

Pathname of the
destination directory or
file. If not an absolute
path, it is relative to the
source directory.

© 2014 Adobe Systems Incorporated. All rights reserved.

Default

Description

440

Adobe ColdFusion Documentation

source

Required

Pathname of the file to
move. If not an absolute
path (starting with a drive
letter and a colon, or a
forward or backward
slash), it is relative to the
ColdFusion temporary
directory, which is
returned by the GetTemp
Directory function.

attributes

Optional

Applies to Windows. A
comma-delimited list of
attributes to set on the file.
If omitted, the file's
attributes are
maintained.Each value
must be specified
explicitly. For example, if
you specify attributes
= "readOnly", all other
attributes are overwritten.
readOnly
hidden
normal

charset

Optional

JVM default file character
set

The character encoding in
which the file contents is
encoded. The following
list includes commonly
used values:
utf-8
iso-8859-1
windows-1252
us-ascii
shift_jis
iso-2022-jp
euc-jp
euc-kr
big5
euc-cn
utf-16
For more information
character encodings,
see www.w3.org/Intern
ational/O-charset.html.

© 2014 Adobe Systems Incorporated. All rights reserved.

441

Adobe ColdFusion Documentation

Optional

mode

Applies only to UNIX and
Linux. Permissions. Octal
values of UNIX chmod co
mmand. Assigned to
owner, group, and other,
respectively; for example:
644: assigns read/write
permission to owner;
read permission to
group and other.
777: assigns
read/write/execute
permission to all.

Example

The following example moves the keymemo.doc file from the c:\files\upload\ directory to the c:\files\memo\ directory
in Windows:



In this example, the destination directory is "memo."

© 2014 Adobe Systems Incorporated. All rights reserved.

442

Adobe ColdFusion Documentation

cffile action = "read"
Note
You can specify this tag's attributes in an attributeCollection attribute whose value is a
structure. Specify the structure name in the attributeCollection attribute and use the tag's
attribute names as structure keys.

Description

Reads a text file on the server. The file is read into a dynamic, local variable that you can use in the page. For
example:
Read a text file; insert the file's contents into a database
Read a text file; use the find and replace function to modify the file's contents
Note
This action reads the file into a variable in the local Variables scope. It is not intended for
use with large files, such as logs, because this can bring down the server.

Syntax



See also

cfdirectory
History

See the History section of the main cffile tag page.
Attributes

Attribute

Req/Opt

action

Required

© 2014 Adobe Systems Incorporated. All rights reserved.

Default

Description
Type of file manipulation
that the tag performs.

443

Adobe ColdFusion Documentation

file

Required

Pathname of the file to
read.
If not an absolute path
(starting with a drive letter
and a colon, or a forward
or backward slash), it is
relative to the ColdFusion
temporary directory, which
is returned by the GetTem
pDirectory function.

variable

Required

Name of variable to
contain contents of text
file.

charset

Optional

Character encoding
identified by the file's byte
order mark, if any;
otherwise, JVM default file
character set.

The character encoding in
which the file contents is
encoded. The following
list includes commonly
used values:
utf-8
iso-8859-1
windows-1252
us-ascii
shift_jis
iso-2022-jp
euc-jp
euc-kr
big5
euc-cn
utf-16
If the file starts with a
byte order mark and
you set this attribute to
a conflicting character
encoding, ColdFusion
generates an error.
For more information
character encodings,
see www.w3.org/Intern
ational/O-charset.html.

Usage

The following example creates a variable named Message for the contents of the file message.txt:



© 2014 Adobe Systems Incorporated. All rights reserved.

444

Adobe ColdFusion Documentation

The variable Message can be used in the page. For example, you could display the contents of the message.txt file
in the final web page as follows:

#Message#

ColdFusion supports functions for manipulating the contents of text files. You can also use the variable that is
created by a cffile action = "read" operation in the ArrayToList and ListToArray functions.
Note
If you use this tag to read a file that is encoded using the Windows Cp1252 (windows-1252)
encoding of the Latin-1 character set on a system whose default character encoding is Cp1252,
and the files has characters encoded in the Hex 8x or 9x range, specify charset="windows-1
252" attribute, even though this is the default encoding. Otherwise, some characters in the
Hex8x and 9x ranges that do not map correctly and display incorrectly.

© 2014 Adobe Systems Incorporated. All rights reserved.

445

Adobe ColdFusion Documentation

cffile action = "readBinary"
Note
You can specify this tag's attributes in an attributeCollection attribute whose value is a
structure. Specify the structure name in the attributeCollection attribute and use the tag's
attribute names as structure keys.

Description

Reads a binary file (such as an executable or image file) on the server, into a binary object parameter that you can
use in the page. To send it through a web protocol (such as HTTP or SMTP) or store it in a database, first convert it
to Base64 using the ToBase64 function.
Note
This action reads the file into a variable in the local Variables scope. It is not intended for use
with large files, such as logs, because they can bring down the server.

Syntax



See also

cfdirectory
Attributes

Attribute

Req/Opt

action

Required

Type of file manipulation
that the tag performs.

file

Required

Pathname of a binary fine
to read. If not an absolute
path (starting with a drive
letter and a colon, or a
forward or backward
slash), it is relative to the
ColdFusion temporary
directory, which is
returned by the GetTemp
Directory function.

© 2014 Adobe Systems Incorporated. All rights reserved.

Default

Description

446

Adobe ColdFusion Documentation

variable

Required

Name of variable to
contain contents of binary
file.

Usage

You convert the binary file to Base64 to transfer it to another site.ColdFusion supports reading an image file as a
binary and passing the result to a cfimage, for example:






Example

The following example reads the binary file somewhere.jpg, writes it to a different folder as somewhereB.jpg,
and then displays the new file:







© 2014 Adobe Systems Incorporated. All rights reserved.

447

Adobe ColdFusion Documentation

cffile action = "rename"
Description

Renames or moves a file on the server.
Syntax



Note
You can specify this tag's attributes in an attributeCollection attribute whose value is a
structure. Specify the structure name in the attributeCollection attribute and use the tag's
attribute names as structure keys.

See also

cfdirectory
History

See the History section of the main cffile tag page.
Attributes

Attribute

Req/Opt

action

Required

Type of file manipulation
that the tag performs.

destination

Required

Destination file or
directory. If not an
absolute path, it is relative
to the source directory.

source

Required

Pathname of file to
rename. If not an absolute
path (starting with a drive
letter and a colon, or a
forward or backward
slash), it is relative to the
ColdFusion temporary
directory, which is
returned by the GetTemp
Directory function.

© 2014 Adobe Systems Incorporated. All rights reserved.

Default

Description

448

Adobe ColdFusion Documentation

attributes

Optional

Applies to Windows. A
comma-delimited list of
attributes to set on the file.
If omitted, the file's
attributes are
maintained.Each value
must be specified
explicitly. For example, if
attributes = "readOn
ly", all other attributes
are overwritten.
readOnly
hidden
normal

Optional

mode

Applies only to UNIX and
Linux. Permissions. Octal
values of UNIX chmod co
mmand. Assigned to
owner, group, and other.
For example:
644: assigns read/write
permission to owner;
read permission to
group and other.
777: assigns
read/write/execute
permission to all.

Usage

The rename action renames or move a file. The destination attribute must be a pathname, not just a new name
for the file. If the destination is a directory, the file is moved and not renamed.
Example

Windows example:




UNIX example:

© 2014 Adobe Systems Incorporated. All rights reserved.

449

Adobe ColdFusion Documentation



© 2014 Adobe Systems Incorporated. All rights reserved.

450

Adobe ColdFusion Documentation

cffile action = "upload"
Description

Copies a file to a directory on the server.
Syntax



Note
You can specify this tag's attributes in an attributeCollection attribute whose value is a
structure. Specify the structure name in the attributeCollection attribute and use the tag's
attribute names as structure keys.

See also

cfdirectory, cffile action = "uploadAll", cffileupload
History

The strict attribute has been added in ColdFusion 10. See the History section of the main cffile tag page.
Attributes

Attribute

Req/Opt

action

Required

© 2014 Adobe Systems Incorporated. All rights reserved.

Default

Description
Type of file manipulation
that the tag performs.

451

Adobe ColdFusion Documentation

destination

Required

Pathname of directory in
which to upload the file. If
not an absolute path
(starting with a drive letter
and a colon, or a forward
or backward slash), it is
relative to the ColdFusion
temporary directory, which
is returned by the GetTem
pDirectory function.
If the destination you
specify does not exist,
ColdFusion creates a file
with the specified
destination name. For
example, if you specify
the destination, C:\XYZ,
ColdFusion creates a file
XYZ in the C: drive.

fileField

Optional

Name of form field used to
select the file. Do not use
number signs (#) to
specify the field name. If
omitted, it defaults to the
name of the first file field
submitted.

accept

Optional

Limits the MIME types to
accept. Comma-delimited
list. For example, the
following code permits
JPEG and Microsoft Word
file uploads:accept = {{"i
mage/jpg,
application/msword"}}The
browser uses the file
extension to determine file
type.

© 2014 Adobe Systems Incorporated. All rights reserved.

452

Adobe ColdFusion Documentation

attributes

Optional

Applies to Windows. A
comma-delimited list of
attributes to set on the file.
If omitted, the file's
attributes are
maintained.Each value
must be specified
explicitly. For example, if
you specify attributes
= "readOnly", all other
attributes are overwritten.
readOnly
hidden
normal (if you use this
option with other
attributes, it is
overridden by them)

mode

Optional

Applies only to UNIX and
Linux. Permissions. Octal
values of chmod comman
d. Assigned to owner,
group, and other,
respectively, for example:
644: assigns read/write
permission to owner;
read permission to
group and other.
777: assigns
read/write/execute
permission to all.

© 2014 Adobe Systems Incorporated. All rights reserved.

453

Adobe ColdFusion Documentation

nameConflict

Optional

Error

Action to take if filename
is the same as that of a
file in the directory.
Error: file is not saved.
ColdFusion stops
processing the page
and returns an error.
Skip: file is not saved.
This option permits
custom behavior based
on file properties.
Overwrite: replaces
file.
MakeUnique: forms a
unique filename for the
upload; name is stored
in the file object variable
serverFile.

result

Optional

strict

Optional

© 2014 Adobe Systems Incorporated. All rights reserved.

Lets you specify a name
for the variable in which c
ffile returns the result
(or status) parameters. If
you do not specify a value
for this attribute, cffile
uses the prefix cffile.
For more information, see
Usage.
true

When strict is true, only
MIME types or a
combination of MIME
types and extensions are
allowed in the accept
attribute. Since strict is
true by default, you should
specify MIME types for
the accept attribute. When
strict is false, either MIME
types or extensions or a
combination of both can
be specified as a value to
the accept attribute. For
more information, see this
blog entry.

454

Adobe ColdFusion Documentation

ContinueOnError

Optional

False

By default, when
uploading one of the files
fail, the remaining files will
not be uploaded. If this
value is set to true, file
upload continues evern
after encountering an
upload error. A file upload
error happens due to the
following reasons:
1. Empty file
2. Invalid file type
3. Invalid MIME or
extension
4. File already exists
In the case of an upload
failure, the error details
will be stored in the errors
attribute.

Errors

Optional

cffile.uploadAllErrors

The name of the variable
in which the file upload
errors will be stored.
Errors will be populated in
the specfied variable
name when
continueOnError is
true.After the file upload is
completed, this tag
creates an array of
structures that contains
upload failure information
for each upload failure.
The upload failure
information error structure
contains the following
fields:

© 2014 Adobe Systems Incorporated. All rights reserved.

455

Adobe ColdFusion Documentation

REASON - The reason
for the failure
DETAIL - File upload
failure detail
MESSAGE - A detailed
message depicting the
failure
CLIENTFILE - Name of
the file uploaded from
the client's system
CLIENTFILEEXT Extension of the
uploaded file on the
client system (without a
period)
CLIENTFILENAME Name of the uploaded
file on the client system
(without an extension)
INVALID_FILE_TYPE If the file mime type or
extension is not in the s
pecified accept
attribute. If the reason is
INVALID_FILE_TYPE,
two additional keys will
be available in the
structure.
ACCEPT: list of
mime types or
file extensions
given in the tag
MIMETYPE:
mime type of the
uploaded file
EMPTY_FILE - If the
uploaded file is an
empty file
FILE_EXISTS - If any
file with the given name
already exists in the
destination and the
overwritepolicy is error.
DEST - The destination
where file is copied
FORM_FILE_NOT_FO
UND - If the uploaded
file is not found on the
server

Usage

After a file upload is completed, you can get status information using file upload parameters. To refer to parameters,

© 2014 Adobe Systems Incorporated. All rights reserved.

456

Adobe ColdFusion Documentation

use either the cffile prefix or, if you specified an alternate name in the result attribute, the name you specified
there. For example, if you did not specify a name in the result attribute, access the fileExisted parameter as #
cffile.fileExisted#. If you set the result attribute to myResult, however, access fileExisted as #myRe
sult.fileExisted#. Status parameters can be used anywhere that other ColdFusion parameters can be used.
When you use a cfform tag or an HTML form tag to submit the form with the file to be uploaded, specify enctype
="multipart/form-data" in the tag, as shown in the example for this tag. By default, ColdFusion sends the
form with the encoding type of application/x-www-form-urlencoded, which causes an error in the cffile tag.
The result attribute allows functions or CFCs that get called from multiple pages at the same
time to avoid overwriting the results of one call with another.
Note
The file prefix is deprecated, in favor of the cffile prefix. Do not use the file prefix in new
applications.
If your page is uploading a file that was selected on a form or was otherwise sent to your page
via a multipart/form-data HTTP message, you can determine the approximate size of the file by
checking the value of the CGI.content_length variable. This variable includes the file length
plus the length of any other request content.

The following file upload status parameters are available after an upload:
Parameter

Description

attemptedServerFile

Initial name ColdFusion used when attempting to save
a file

clientDirectory

Directory location of the file uploaded from the client's
system

clientFile

Name of the file uploaded from the client's system

clientFileExt

Extension of the uploaded file on the client system
(without a period)

clientFileName

Name of the uploaded file on the client system (without
an extension)

contentSubType

MIME content subtype of the saved file

contentType

MIME content type of the saved file

dateLastAccessed

Date and time the uploaded file was last accessed

fileExisted

Whether the file existed with the same path (yes or no)

fileSize

Size of the uploaded file in bytes

© 2014 Adobe Systems Incorporated. All rights reserved.

457

Adobe ColdFusion Documentation

fileWasAppended

Whether ColdFusion appended uploaded file to a file (y
es or no)

fileWasOverwritten

Whether ColdFusion overwrote a file (yes or no)

fileWasRenamed

Whether uploaded file renamed to avoid a name
conflict (yes or no)

fileWasSaved

Whether ColdFusion saves a file (yes or no)

oldFileSize

Size of a file that was overwritten in the file upload
operation

serverDirectory

Directory of the file saved on the server

serverFile

Filename of the file saved on the server

serverFileExt

Extension of the uploaded file on the server (without a
period)

serverFileName

Name of the uploaded file on the server (without an
extension)

timeCreated

Time the uploaded file was created

timeLastModified

Date and time of the last modification to the uploaded
file

Note
File status parameters are read-only. They are set to the results of the most recent cffile oper
ation. If two cffile tags execute, the results of the second overwrite the first, unless you have
specified a different result variable in the result attribute.

Example

The following example creates a unique filename, if there is a name conflict when the file is uploaded on Windows:

© 2014 Adobe Systems Incorporated. All rights reserved.

458

Adobe ColdFusion Documentation








#cgi.script_name#
name="uploadForm" enctype="multipart/form-data">







© 2014 Adobe Systems Incorporated. All rights reserved.

459

Adobe ColdFusion Documentation

cffile action = "uploadAll"
Description

Copies all files sent to the page in an HTTP request to a directory on the server.
Syntax



Note
You can specify this tag's attributes in an attributeCollection attribute whose value is a
structure. Specify the structure name in the attributeCollection attribute and use the tag's
attribute names as structure keys.

See also

cffile action = "upload", cfdirectory
History

ColdFusion 11: Added the attributes ContinueOnError and Errors.
See the History section of the main cffile tag page.
Attributes

Attribute

Req/Opt

action

Required

© 2014 Adobe Systems Incorporated. All rights reserved.

Default

Description
Type of file manipulation
that the tag performs.

460

Adobe ColdFusion Documentation

destination

Required

Pathname of directory in
which to upload the file. If
not an absolute path
(starting with a drive letter
and a colon, or a forward
or backward slash), it is
relative to the ColdFusion
temporary directory, which
is returned by the GetTem
pDirectory function.

accept

Optional

Limits the MIME types to
accept. Comma-delimited
list. For example, the
following code permits
JPEG and Microsoft Word
file uploads:accept = {{"i
mage/jpg,
application/msword"}}The
browser uses the file
extension to determine file
type.

attributes

Optional

Applies to Windows. A
comma-delimited list of
attributes to set on the file.
If omitted, the file's
attributes are
maintained.Each value
must be specified
explicitly. For example, if
you specify attributes
= "readOnly", all other
attributes are overwritten.
readOnly
hidden
normal (if you use this
option with other
attributes, it is
overridden by them)

© 2014 Adobe Systems Incorporated. All rights reserved.

461

Adobe ColdFusion Documentation

mode

Optional

Applies only to UNIX and
Linux. Permissions. Octal
values of chmod comman
d. Assigned to owner,
group, and other,
respectively, for example:
644: assigns read/write
permission to owner;
read permission to
group and other.
777: assigns
read/write/execute
permission to all.

nameConflict

Optional

Error

Action to take if filename
is the same as that of a
file in the directory.
Error: file is not saved.
ColdFusion stops
processing the page
and returns an error.
Skip: file is not saved.
This option permits
custom behavior based
on file properties.
Overwrite: replaces
file.
MakeUnique: forms a
unique filename for the
upload. The name is
stored in the serverFi
le field of the result
structure for the file.

© 2014 Adobe Systems Incorporated. All rights reserved.

462

Adobe ColdFusion Documentation

ContinueOnError

Optional

False

By default, when
uploading one of the files
fail, the remaining files will
not be uploaded. If this
value is set to true, file
upload continues evern
after encountering an
upload error. A file upload
error happens due to the
following reasons:
1. Empty file
2. Invalid file type
3. Invalid MIME or
extension
4. File already exists
In the case of an upload
failure, the error details
will be stored in the errors
attribute.

Errors

Optional

cffile.uploadAllErrors

The name of the variable
in which the file upload
errors will be stored.
Errors will be populated in
the specfied variable
name when
continueOnError is
true.After the file upload is
completed, this tag
creates an array of
structures that contains
upload failure information
for each upload failure.
The upload failure
information error structure
contains the following
fields:

© 2014 Adobe Systems Incorporated. All rights reserved.

463

Adobe ColdFusion Documentation

REASON - The reason
for the failure
DETAIL - File upload
failure detail
MESSAGE - A detailed
message depicting the
failure
CLIENTFILE - Name of
the file uploaded from
the client's system
CLIENTFILEEXT Extension of the
uploaded file on the
client system (without a
period)
CLIENTFILENAME Name of the uploaded
file on the client system
(without an extension)
INVALID_FILE_TYPE If the file mime type or
extension is not in the s
pecified accept
attribute. If the reason is
INVALID_FILE_TYPE,
two additional keys will
be available in the
structure.
ACCEPT: list of
mime types or
file extensions
given in the tag
MIMETYPE:
mime type of the
uploaded file
EMPTY_FILE - If the
uploaded file is an
empty file
FILE_EXISTS - If any
file with the given name
already exists in the
destination and the
overwritepolicy is error.
DEST - The destination
where file is copied
FORM_FILE_NOT_FO
UND - If the uploaded
file is not found on the
server

© 2014 Adobe Systems Incorporated. All rights reserved.

464

Adobe ColdFusion Documentation

Optional

result

Lets you specify a name
for the variable in which c
ffile returns the result
(or status) parameters. If
you do not specify a value
for this attribute, cffile
uses the prefix cffile.
For more information, see
Usage.

Usage

Unlike cffile action="upload", which uploads only one file at a time cf fileaction="uploadall" upload
s multiple files thereby eliminating the need to code multiple cffile action="upload" statements. Use this tag
in the page specified by the action attribute of a cffileupload control. This tag uploads save the files that the c
ffileupload control sends when the user clicks the Save File button. After a file upload is completed, this tag
creates an array of structures specified by the result parameter. Each structure in the array contains upload result
information for one file. For information on the result structure contents, see cffile action = "upload".
Note
You can control the maximum file size of the upload by specifying the server Request Throttle
Threshold or the Settings page of the Administrator Server Settings section.

Example

The following example copies files uploaded by a cffileupload tag to a temp directory.














© 2014 Adobe Systems Incorporated. All rights reserved.

465

Adobe ColdFusion Documentation

cffile action = "write"
Description

Writes a text file on the server, based on dynamic content. You can create static HTML files from the content, or log
actions in a text file.
Syntax



Note
You can specify this tag's attributes in an attributeCollection attribute whose value is a
structure. Specify the structure name in the attributeCollection attribute and use the tag's
attribute names as structure keys.

See also

cfdirectory
History

See the History section of the main cffile tag page.
Attributes

Attribute

Req/Opt

action

Required

Type of file manipulation
that the tag performs.

file

Required

Pathname of the file to
write. If not an absolute
path (starting with a drive
letter and a colon, or a
forward or backward
slash), it is relative to the
ColdFusion temporary
directory, which is
returned by the GetTemp
Directory function.

© 2014 Adobe Systems Incorporated. All rights reserved.

Default

Description

466

Adobe ColdFusion Documentation

output

Required

addNewLine

Optional

attributes

Optional

Content of the file to be
created.
yes

yes: appends newline
character to text written
to file.
no
Applies to Windows. A
comma-delimited list of
attributes to set on the file.
If omitted, the file's
attributes are
maintained.Each value
must be specified
explicitly. For example, if
you specify attributes
= "readOnly", all other
attributes are overwritten.
readOnly
hidden
normal

charset

Optional

JVM default file character
set

The character encoding in
which the file contents is
encoded. The following
list includes commonly
used values:
utf-8
iso-8859-1
windows-1252
us-ascii
shift_jis
iso-2022-jp
euc-jp
euc-kr
big5
euc-cn
utf-16
For more information
character encodings,
see www.w3.org/Intern
ational/O-charset.html.

© 2014 Adobe Systems Incorporated. All rights reserved.

467

Adobe ColdFusion Documentation

fixnewline

Optional

mode

Optional

no

yes: changes
embedded line-ending
characters in string
variables to
operating-system
specific line endings.
no: does not change
embedded line-ending
characters in string
variables.
Applies only to UNIX and
Linux. Permissions. Octal
values of UNIX chmod
command. Assigned to
owner, group, and other,
respectively; for example:
644: assigns read/write
permission to owner;
read permission to
group and other.
777: assigns
read/write/execute
permission to all.

Example

This example creates a file with information a user entered in an HTML insert form:



If the user submitted a form with the following:

UpdateTitle = "FieldWork"
FullName = "World B. Frueh"
Date = "10/30/01"
Content = "We had a wonderful time in Cambridgeport."

ColdFusion would create a file named FieldWork.txt in the c:\files\updates\ directory and the file would contain the
following text:

© 2014 Adobe Systems Incorporated. All rights reserved.

468

Adobe ColdFusion Documentation

Created By: World B. Frueh
Date: 10/30/01
We had a wonderful time in Cambridgeport.

This example shows the use of the mode attribute for UNIX. It creates the file /tmp/foo with permissions rw-r-r(owner = read/write, group = read, other = read):



This example appends to the file and sets permissions to read/write (rw) for all:



This example uploads a file and gives it the permissions owner/group/other = read/write/execute):

cffile action = "upload"
fileField = "fieldname"
destination = "/tmp/program.exe"
mode = 777>

This example uses the fixnewline attribute to changes embedded line-ending characters in xmlString, which is
derived from xmlData, to operating-system specific line endings.

© 2014 Adobe Systems Incorporated. All rights reserved.

469

Adobe ColdFusion Documentation



This is some plain text












ColdFusion supports using cffile to write an image, for example:








© 2014 Adobe Systems Incorporated. All rights reserved.

470

Adobe ColdFusion Documentation

cffileupload
Description

Displays a dialog for uploading multiple files from the user's system. The enhanced dialog includes the following
features:
You can specify the maximum number of files and the maximum file size for the upload.
A progress bar to visually indicate the overall progress of the file upload task, and another progress bar to
indicate the upload progress of each individual file.
A success or failure message appears for each file upload and the overall upload task.
At any point during the upload task, you can cancel the upload.
Category

File management tags, Forms tags
Syntax


addbuttonlabel= "label"
align = align="center|left|right"
bgcolor = "color"
clearbuttonlabel = "label"
deletebuttonlabel = "label"
extensionfilter = "none|jpg,jpeg,png"
height= "number of pixels"
hideUploadButton = "true|false"
maxfileselect = "number of files"
maxuploadsize = "file size in mega bytes"
name = "File uploader name"
oncomplete = "JavaScript function name"
onerror = "JavaScript function name"
onUploadComplete = "JavaScript function name"
progressbar = "true|false"
stoponerror = "true|false"
style = "style specification"
title = "Title panel name"
uploadbuttonlabel = "label"
url = "URL"
width = "number of pixels"
wmode = "window|opaque|transparent"


Note
You can specify this tag's attributes in an attributeCollection attribute whose value is a
structure. Specify the structure name in the attributeCollection attribute and use the tag's
attribute names as structure keys.

See also

cffile action = "uploadAll"
History

© 2014 Adobe Systems Incorporated. All rights reserved.

471

Adobe ColdFusion Documentation

ColdFusion 9: Added this tag.
Attributes

Attribute

Req/Opt

Default

Description

addbuttonlabel

Optional

Add Files

Label of the Add button.

align

Optional

left

Specifies the default
alignment.
The following values are
valid:
center
left
right

bgcolor

Optional

The background color for
the file upload control. A
hexadecimal value without
"#" prefixed or a
recognized color name,
for example red.

clearbuttonlabel

Optional

Clear All

Label of the Clear button

deletebuttonlabel

Optional

Delete

Label of the Delete button

extensionfilter

Optional

none

Use this attribute to
specify the type of file that
you will allow to be
uploaded. For example, to
let only image files to be
uploaded, you can specify
file extensions such as
.jpg, .jpeg, or .png.
If set to none, files are
uploaded without any
extension filter.

height

Optional

300

Height of the file upload
control, in pixels.

hideUploadButton

Optional

false

A Boolean value that
specifies if the Upload
button should appear in
the file upload dialog:
true
false

© 2014 Adobe Systems Incorporated. All rights reserved.

472

Adobe ColdFusion Documentation

maxfileselect

Optional

The maximum number of
files allowed for upload.

maxuploadsize

Optional

name

Optional

Name of the file upload
component.

onComplete

Optional

The JavaScript function to
run when a file has
finished uploading.By
default, ColdFusion
passes a JavaScript
object as a parameter to
this function with the
following properties:

10MB

The maximum file size, in
Megabytes, allowed for
upload in an
operation.ColdFusion
throws an error if the
value of the attribute
maxuploadsize exceeds
the throttle/ post data size
settings specified in the
ColdFusion Administrator.

STATUS - numeric value
that is based on the
HTTP status code
MESSAGE - Passed or
Failed
FILENAME - Name of
the file selected for
upload
You can also pass the
JavaScript object by
creating a struct with
parameters "status" and
"message" and call
serializeJSON() on the
JavaScript object.

© 2014 Adobe Systems Incorporated. All rights reserved.

473

Adobe ColdFusion Documentation

onError

Optional

The JavaScript function to
run if the uploading of a
file fails. The error can be
a network error or
server-side error. By
default, ColdFusion
passes a JavaScript
object as a parameter to
this function with the
following properties:
STATUS - numeric
value that is based on
the HTTP status code
MESSAGE - Passed or
Failed
FILENAME - Name of
the file selected for
upload
You can also pass the
JavaScript object by
creating a struct with
parameters "status" and
"message" and call
serializeJSON() on the
JavaScript object.

onUploadComplete

Optional

progressbar

Optional

The JavaScript function to
run after uploading all the
files.
true

Whether to display a
progress bar while the
files upload:
true
false

stoponerror

Optional

true

Specifies whether to
ignore the exceptions for
this operation.
true - Stops uploading
and displays an
appropriate error.
false - Continues
uploading and displays
an appropriate error.

style

Optional

© 2014 Adobe Systems Incorporated. All rights reserved.

A CSS style specification
that defines layout styles.

474

Adobe ColdFusion Documentation

title

Optional

Title for the upload dialog.

uploadbuttonlabel

Optional

url

Optional

width

Optional

420

Width of the file upload
control, in pixels.

wmode

Optional

window

Specifies the absolute
positioning and layering
capabilities in your
browser:

Upload

Label of the Upload
button.
The URL to the server
where the files are
uploaded.
The attribute is optional
and it defaults to
cgi.script_name.

window: Plays the
media player in its own
rectangular window on
a web page
opaque: Hides
everything behind the
media player on the
web page
transparent: Lets the
background of the web
page show through the
transparent portions of
the media player

Usage

Use this tag to create a SWF file-based file upload control that lets a user upload multiple files to a server. To upload
files to the server, define a server-side template. The template that you define reads the upload request and uploads
the selected files to the server.
Enhancements made in ColdFusion 9.0.1

In ColdFusion 9.0.1, the fileupload control passes the session information implicitly to the target page if session
management is turned on either in Application.cfc or Application.cfm.Assume that fileupload control is defined
without a URL attribute. In this case, if the user chooses to upload data using the upload button, the control comes
back to the same page. Users can check for form.fieldnames to perform the upload as shown in the following
example:Upload.cfm

© 2014 Adobe Systems Incorporated. All rights reserved.

475

Adobe ColdFusion Documentation






In this case, url defaults to CGI.script_name.
To maintain sessions between the fileupload control and the URL, users must turn on session management. You
can do this by setting the this.sessionmanagement=true in Application.cfc. The setting ensures that CFID and
CFtoken are passed as part of the URL if Enable J2EE Session Variables (ColdFusion Administrator > Server
Settings > Memory Variables) is not selected. If it is selected, then JsessionID is passed as part of the URL.
Supported Styles

The following are the supported styles:
Style

Description

headercolors

Format: color; colors of the band at the top of the
DateChooser control. Specify two values, separated by
a comma. For a solid band, use the same color for both
values. The default value is ##E6EEEE,##FFFFFF.

textcolor

Color of text. Can be a hexadecimal value or a named
color. For a hexadecimal value, use the
form"##xxxxxx", where x = 0-9 or A-F; use two number
signs or none.

titletextalign

Aligns the title text. The recognized values are left,
right, and center. The default value is right.

titletextcolor

Color of the title text.

bgcolor

The background color for the file upload control. A
hexadecimal value without "#" prefixed or a recognized
color name, for example red.

rollovercolor

Displays values on mouse-over.

selectcolor

Background color for a selected item. Can be a
hexadecimal value or a named color.
For a hexadecimal value, use the form "##xxxxxx",
where x = 0-9 or A-F; use two number signs or none.
For a list of the supported named colors, see cfchart.

Example

© 2014 Adobe Systems Incorporated. All rights reserved.

476

Adobe ColdFusion Documentation

Instructions
Create a folder Upload in your C: drive

Try uploading files using the file upload component and check if the files have
been appropriately saved in the Upload folder.



uploadfiles.cfm is given below:


#serializeJSON({STATUS=200,MESSAGE='Passed'})#

This example sends user-specified files to the server-side template - uploadfiles.cfm. The template file that you
define can use the "upload" or "uploadall" action defined in the cffile tag.
Note
The filefield attribute of the upload action is optional.

Use the destination attribute in the cffile tag to define the location to save the files. For the uploadfiles.cfm
code, see cffile action = "uploadAll".

© 2014 Adobe Systems Incorporated. All rights reserved.

477

Adobe ColdFusion Documentation

cffinally
Description

Used inside a cftry tag. Code in the cffinally block is processed after the main cftry code and, if an
exception occurs, the cfcatch code. The cffinally block code always executes, whether or not there is an
exception.
Category

Exception handling tags
Syntax


try code 
catch code 
...

final code 


See also

cftry, cfcatch, cferror, cfrethrow, cfthrow, onError; Handling Errors in the Developing ColdFusion
Applications
History

ColdFusion 9: Added the tag
Usage

The cffinally tag is optional in a cftry block, and the block can have only one cffinally tag. Put the cffina
lly tag at the end of all cftry block, after any cfcatch blocks. This tag requires an end tag. You can nest
cftry/cfcatch/cffinally blocks.Use the cffinally tag for code that should execute whether or not an exception
occurs. For example, use it to free up resources.
Example

© 2014 Adobe Systems Incorporated. All rights reserved.

478

Adobe ColdFusion Documentation

cffinally Example


....

....


....

....


© 2014 Adobe Systems Incorporated. All rights reserved.

479

Adobe ColdFusion Documentation

cfflush
Description

Flushes currently available data to the client.
Category

Data output tags, Page processing tags
Syntax



Note
You can specify this tag's attributes in an attributeCollection attribute whose value is a
structure. Specify the structure name in the attributeCollection attribute and use the tag's
attribute names as structure keys.

See also

cfcache, cfheader, cfinclude, cfsetting, cfsilent
Attributes

Attribute

Req/Opt

interval

Optional

Default

Description
Integer. Flushes output
each time this number of
bytes becomes available.
HTML headers, and data
that is already available
when the tag is executed,
are omitted from the
count.

Usage

The first occurrence of this tag on a page sends back the HTML headers and any other available HTML.
Subsequent cfflush tags on the page send only the output that was generated after the previous flush.
When you flush data, ensure that enough information is available, as some browsers might not respond if you flush
only a small amount. Similarly, set the interval attribute for a few hundred bytes or more, but not thousands of
bytes.Use the interval attribute only when a large amount of output is sent to the client, such as in a cfloop or a
cfoutput of a large query. Using this form globally (such as in the Application.cfm file) might cause unexpected
errors when CFML tags that modify HTML headers are executed. Because the cfflush tag sends data to the
browser when it executes, it has several limitations, including the following:
Using any of the following tags or functions on a page anywhere after the cfflush tag can cause errors or
unexpected results: cfcontent, cfcookie, cfform, cfheader, cfhtmlhead, cflocation, and SetLo

© 2014 Adobe Systems Incorporated. All rights reserved.

480

Adobe ColdFusion Documentation

cale. Similarly, do not use any tags that use AJAX features, including cfdiv, cflayout, cflayoutarea,
cfpod, cfsprydataset, cftooltip, cfwindow, or HTML format cfgrid, cftree, cftextarea, or cfi
nput (using autosuggest or datefield attributes) tags. All of the preceding tags and functions normally
modify the HTML header, but cannot do so after a cfflush tag, because the cfflush sends the header.
Using the cfset tag to set a cookie anywhere on a page that has a cfflush tag does not set the cookie in
the browser.
Using the cfflush tag in the body of several tags, including cfsavecontent, cfquery, and custom tags,
causes errors.
If you save Client variables as cookies, any client variables that you set after a cfflushtag are not saved in
the browser.
Note
Normally, the cferror tag discards the current output buffer and replaces it with the
contents of the error page. The cfflush tag discards the current buffer. As a result, the E
rror.GeneratedContent variable resulting from a cferror tag after a cfflush cont
ains any contents of the output buffer that has not been flushed. This content is not sent to
the client. The content of the error page displays to the client after the bytes that have
been sent.

Example

The following example uses cfloop tags and the rand random number generating function to delay data display. It
simulates a page that is slow to generate data.

Your Magic numbers
It will take us a little while to calculate your ten magic numbers. It takes a
lot of work to find numbers that truly fit your personality. So relax for a minute
or so while we do the hard work for you.
We are sure you will agree it was worth the short wait!












Magic number #Myindex# is:  #RandRange
(100000, 999999)#





© 2014 Adobe Systems Incorporated. All rights reserved.

481

Adobe ColdFusion Documentation

cfformgroup
Description

Creates a container control for multiple form controls. Used in the cfform tag body of Adobe Flash and XML forms.
Ignored in HTML forms.
Category

Forms tags
Syntax


width = "pixels"
height = "pixels"
enabled = "yes|no"
visible = "yes|no"
onChange = "ActionScript expression"
tooltip = "text"
id = "unique identifier">
...ColdFusion forms controls...

OR

startrow = "row number"
...ColdFusion forms controls


Note
You can specify this tag's attributes in an attributeCollection attribute whose value is a
structure. Specify the structure name in the attributeCollection attribute and use the tag's
attribute names as structure keys.

See also

cfapplet, cfcalendar, cfform, cfformitem, cfgrid, cfinput, cfselect, cfslider, cftextarea, and c
ftree
History

ColdFusion MX 7: Added this tag.
Attributes

© 2014 Adobe Systems Incorporated. All rights reserved.

482

Adobe ColdFusion Documentation

The following table lists the attributes and their behavior in Flash forms. For XML, if not otherwise noted, the
attribute is passed to the XML but is not interpreted by the basic XSL style sheet provided with ColdFusion.
Note
Attributes that are not marked as supported in XML are not handled by the skins provided with
ColdFusion. They are, however, included in the generated XML.

Attribute

Req/Opt; formats

type

Required;Flash and XML

Default

Description
XML: Can be any XForms
group type defined in the
XSLT. The XSL skins
provided with ColdFusion
support the following
types:
horizontal: align
child tags horizontally
within a form and put
this tag's label attribut
e to the left of the
children.
vertical: align child
tags vertically within a
form and put this tag's l
abel attribute to the left
of the children.
fieldset:
corresponds to the
HTML fieldset tag,
which groups its
children, typically by
drawing a box around
them and replacing part
of the top line with
legend text. To specify
the legend, use the lab
el attribute. To specify
the box dimensions,
use the style attribute
with height and widt
h values. Explicitly use
cfformgroup type="
vertical" inside this
formgroup to align its
child tags vertically.

© 2014 Adobe Systems Incorporated. All rights reserved.

483

Adobe ColdFusion Documentation

Flash: Must be one of the
following:
repeater: dynamically
creates an instance of
the cfformgroup's
child tag or tags for
each row of a query
object, without requiring
ColdFusion to
recompile the Flash
SWF file when the
number of rows
changes.
horizontal: aligns
child tags horizontally
within a form and put
this tag's label attribut
e to the left of the
children. Use this tag to
arrange individual
controls horizontally.
vertical: aligns child
tags vertically within a
form and puts this tag's
label attribute to the
left of the children. Use
this tag to arrange
individual controls
vertically.
hbox: aligns children
horizontally. Use this
type to arrange groups
of form controls
horizontally. Do not use
this attribute to align
individual controls
horizontally, because
the child controls do not
align properly; use the
horizontal type instead.
vbox: aligns children
vertically. Use this type
to arrange groups of
controls vertically. Do
not use this attribute to
align individual controls
vertically, because the
child controls do not
align properly; use the
vertical type instead.

© 2014 Adobe Systems Incorporated. All rights reserved.

484

Adobe ColdFusion Documentation

hdividedbox: aligns
children horizontally.
Each child is in a box
with a border, and there
are dividers between
the boxes that users
can move to change the
relative sizes of the
children. Use a tag with
this attribute to arrange
groups of form controls
horizontally. You cannot
use this attribute to
align individual controls
horizontally.
vdividedbox: aligns
children vertically. Each
child is in a box with a
border, and there are
dividers between the
boxes that users can
move to change the
relative sizes of the
children. Use this type
to group form controls,
for example as a unit in
an hbox form group. Do
not use this attribute to
align individual tags
vertically.
panel: a container
consisting of a title bar
containing the label at
tribute text, a border,
and a content area with
vertically arranged
children.
tile: places the
children in a rectangular
grid.
accordion: places
each child in a pleat of
an expanding and
contracting accordion.
Define each pleat using
a cfformgroup
type="page" tag.

© 2014 Adobe Systems Incorporated. All rights reserved.

485

Adobe ColdFusion Documentation

tabnavigator: places
the children in a tabbed
dialog box. Define each
tab by using a cfformg
roup type="page" ta
g.
page: places the
children tags, aligned
vertically, in a single tab
of a parent tabnavigator
or pleat of an accordion
container.
query

Required for type=
repeater, ignored
otherwise;Flash

enabled

Optional;Flash

height

Optional; Flash

Height of the group
container, in pixels. If you
omit this attribute, Flash
automatically sizes the
container height. Ignored
for Flash repeater type.

id

Optional;Flash

Unique identifier for the
form group. When using
the tabnavigator or
accordion type, specify
the id attribute to
reference the controls
through custom
ActionScript.

© 2014 Adobe Systems Incorporated. All rights reserved.

The query to use with the
repeater. Flash creates an
instance of each of the cf
formgroup tag's child
tags for each row in the
query. You can use the b
ind attribute in the child
tags to use data from the
query row for the
instance.
yes

Boolean value that
specifies whether the
controls in the form group
are enabled. Disabled
controls appear in light
gray.

486

Adobe ColdFusion Documentation

label

Optional;Flash and XML

Label to apply to the form
group. In Flash, does the
following:
For a page or panel
form group, determines
the label to put on the
corresponding
accordion pleat, the
tabnavigator tab, or the
panel title bar. For a
Flash horizontal or
vertical form group,
specifies the label to put
to the left of the group.
Ignored in Flash for
repeater, hbox,
hdividedbox, vbox,
vdividedbox, tile,
accordion, and
tabnavigator types.

maxrows

Optional;Flash

Used only for the repeat
er type; ignored
otherwise.Specifies the
maximum number of
query rows to use in the
Flash form repeater. If the
query has more rows than
the sum of the startrow
attribute and this value,
the repeater does not use
the remaining rows.

onChange

Optional;Flash

Tabnavigator and
accordion types only:
ActionScript expression or
expressions to execute
when a new tab or
accordion page is
selected. Note: The onCh
ange event occurs when
the form first appears.

© 2014 Adobe Systems Incorporated. All rights reserved.

487

Adobe ColdFusion Documentation

selectedIndex

Optional; Flash only

startrow

Optional;Flash

style

Optional;Flash and XML

Flash: a Flash style
specification in CSS
format. For detailed
information on specifying
Flash styles, see Creating
Forms in Flash in the Dev
eloping ColdFusion
Applications.XML: an
inline CSS style
specification.

tooltip

Optional;Flash

Text to display when the
mouse pointer hovers in
the form group area. If a
control in the form group
also specifies a tooltip,
Flash displays the
control's tooltip when the
mouse pointer hovers
over the control.

visible

Optional;Flash

© 2014 Adobe Systems Incorporated. All rights reserved.

Used only for accordion
and tabnavigator types;
ignored otherwise.
Specifies the page control
to display as open, where
0 (not 1) specifies the first
page control defined in
the group.
0

yes

Used only for the repeat
er type; ignored
otherwise.Specifies the
row number of the first
row of the query to use in
the Flash form repeater.
This attribute is
zero-based: the first row is
row 0, not row 1 (as in
most ColdFusion tags).

Boolean value specifying
whether the controls in the
form group are visible. If
the controls are invisible,
the space that would be
occupied by visible
controls is blank.

488

Adobe ColdFusion Documentation

width

Optional;Flash and XML

Width of the group
container, in pixels. If you
omit this attribute, Flash
automatically sizes the
container width. Ignored
for Flash repeater type.

Usage

This tag requires an end tag. This tag is ignored if the cfform type is HTML; any tag body's contents are interpreted
as if the surrounding cfformgroup does not exist.
In Flash format forms, this tag organizes the contents of the form. It groups and arranges child tags. The body of this
tag can contain the following tags; all other tags and text are ignored:
cfformitem
cfcalendar
cfgrid
cfinput
cfselect
cftextarea
cftree

For more information on using this tag in Flash forms, see Creating Forms in Flash in the Developing ColdFusion
Applications. In XML format, ColdFusion passes the tag and its attributes to the XML; it is the responsibility of the
skin XSLT to handle the XML. The ColdFusion basic skin supports the horizontal, vertical, and dualselect
list styles only. For more information on using this tag in XML forms, see Creating Forms in Flash in the Developin
g ColdFusion Applications.
Example

For a simple example of an XML form that uses a single cfformgroup tag, see cfform.
The following example shows how to use the cfformgroup tag to arrange elements on a Flash form. It creates an
hdividedbox container that has a vbox container on each side. The left box has heading text and two radio buttons.
The right box has heading text and three check boxes.

© 2014 Adobe Systems Incorporated. All rights reserved.

489

Adobe ColdFusion Documentation

Simple cfformgroup Example




Pets:






Fruits:








The following more complex example shows more fully how you can use cfformgroup tags to arrange controls in
a Flash form. It also shows many of the text formatting features that you can use in a text cfformgroup body.
When you submit the form, the page dumps the contents of the Forms scope, to show you the submitted data.

cfformgroup Example

The form submitted the following information to ColdFusion:





A Flash form using cfformgroup tags




This form has two tabs, asking for the following:

contact information
preferences
Try entering information on both tabs

Submit the form and see what ColdFusion gets in the Forms scope.



This link displays the home page in a new browser window


 






© 2014 Adobe Systems Incorporated. All rights reserved.

490

Adobe ColdFusion Documentation







Flash fills the email field in automatically.
You can replace any of the text.








Tell us your preferences






Pets:









Fruits:


<--- Flash requires unique names for all controls --->









© 2014 Adobe Systems Incorporated. All rights reserved.

491

Adobe ColdFusion Documentation









© 2014 Adobe Systems Incorporated. All rights reserved.

492

Adobe ColdFusion Documentation




© 2014 Adobe Systems Incorporated. All rights reserved.

493

Adobe ColdFusion Documentation

cfformitem
Description

Inserts a horizontal line, a vertical line, a spacer, or text in a Flash form. Used in the cfform or cfformgroup tag
body for Flash and XML forms. Ignored in HTML forms.
Category

Forms tags
Syntax


OR

...text 

Note
You can specify this tag's attributes in an attributeCollection attribute whose value is a
structure. Specify the structure name in the attributeCollection attribute and use the tag's
attribute names as structure keys.

See also

cfapplet, cfform, cfformgroup, cfgrid, cfinput, cfselect, cfslider, cftextarea, cftree, Adding
text, images, rules, and space with the cfformitem tag in Building Flash forms in the Developing ColdFusion
Applications
History

ColdFusion MX 7.01: Added the "script" value for type attribute.
ColdFusion MX 7: Added tag
Attributes

The following table lists the attributes and their behavior in Flash forms. For XML format, if not otherwise noted, the

© 2014 Adobe Systems Incorporated. All rights reserved.

494

Adobe ColdFusion Documentation

attribute is passed to the XML but is not interpreted by the basic XSL style sheet provided with ColdFusion.
Note
Attributes that are marked as Flash only are not handled by the skins provided with ColdFusion.
They are, however, included in the generated XML in all controls except text and html types.

Attribute

Req/Opt; formats

© 2014 Adobe Systems Incorporated. All rights reserved.

Default

Description

495

Adobe ColdFusion Documentation

type

Required;Flash and XML

Flash:
html: place the text in
the body of this tag on
the form. For Flash
forms, you can use the
following text formatting
tags, most of which
correspond to HTML
tags, in the text: a, b, b
r, font, i, img, li, p,
textformat, and u.
For details on using
these formatting tags,
see the Flash
documentation. The st
yle attribute has no
effect on the format of
the text in type.
text: place the text in
the body of this tag on
the form verbatim,
without interpreting any
markup. You can
control the overall
appearance of the text
by using the style attri
bute.
spacer: places an
invisible spacer of the
specified height and
width on the form. Used
to place space between
form controls. This tag
must not have any
children.
hrule: places a
horizontal rule on the
form. This tag must not
have any children.
vrule: places a vertical
rule on the form. This
tag must not have any
children.
script: lets you create
functions in Flash
forms, which reduces
the possibility of
reaching the 64 KB
limit.

© 2014 Adobe Systems Incorporated. All rights reserved.

496

Adobe ColdFusion Documentation

XML:
html: puts the CFML
tag's body text in a
CDATA section in an
XML xf:output eleme
nt.
text: XML-formats
(escapes characters
such as <) the CFML
tag's body text and puts
it in a CDATA section in
an XML xf:output ele
ment.
hrule: puts an hr tag
in the output. Use the s
tyle attribute to
specify all rule
characteristics,
including height and
width. This tag must not
have any children.
Any other string:
generates an XML xf:
group element with the
type name as the appe
arance attribute. The
CFML tag body is put in
a CDATA section in a c
f:attribute name="
body" element. The
XSL transforms
provided with
ColdFusion ignore
these elements.

© 2014 Adobe Systems Incorporated. All rights reserved.

497

Adobe ColdFusion Documentation

bind

Optional;Flash

enabled

Optional;Flash

height

Optional;Flash

© 2014 Adobe Systems Incorporated. All rights reserved.

A Flash bind expression
that populates the field
with information from
other form fields. If you
use this attribute,
ColdFusion ignores any
text that you specify in the
body of the cftextitem
tag. This attribute can be
useful if the cfformitem
tag is in a cfformgroup
type="repeater" tag.
For more information, see
Flash form data binding in
the cfinput tag
description.
yes

Boolean value that
specifies whether the
control is enabled.
Disabled text appear in
light gray. Has no effect
on spacers and rules.
Height of the item, in
pixels. If you omit this
attribute, Flash
automatically sizes the
height. In ColdFusion XSL
skins, use the style attri
bute, instead.

498

Adobe ColdFusion Documentation

style

Optional;Flash and XML

Flash:
Must be a style
specification in CSS
format.
Ignored if the type attribu
te is html.
For detailed information
on specifying Flash styles,
see Creating Forms in
Flash in the Developing
ColdFusion Applications.
Not used with the spacer
type.
XML:
ColdFusion passes the
style attribute to the
XML. ColdFusion skins
include the style
attribute in the
generated HTML.

tooltip

Optional;Flash

visible

Optional;Flash

width

Optional;Flash

Text to display when the
mouse pointer hovers
over the control. Has no
effect on spacers.
yes

Boolean value that
specifies whether to show
the control. Space that
would be occupied by an
invisible control is blank.
Has no effect on spacers.
Width of the item, in
pixels. If you omit this
attribute, Flash
automatically sizes the
width. In ColdFusion XSL
skins, use the style attri
bute, instead.

Usage

This tag requires an end tag or a slash before the closing end character of the opening tag, as the following example
shows:



© 2014 Adobe Systems Incorporated. All rights reserved.

499

Adobe ColdFusion Documentation

For more information on using this tag in Flash forms, see Creating Forms in Flash in the Developing ColdFusion
Applications.
Example

The following example shows a simple Flash form by using horizontal rules and text:

cfformitem Example



This simple form has two hrule cfformitem tags around the cfformitem tag that
contains this text.




For a more complex form, see cfformgroup.

© 2014 Adobe Systems Incorporated. All rights reserved.

500

Adobe ColdFusion Documentation

cfftp
Description

Lets users implement File Transfer Protocol (FTP) operations.
Category

File management tags, Internet protocol tags
Syntax

The tag syntax depends on the action attribute value. See the following sections:
cfftp: Opening and closing FTP server connections
cfftp: Opening and closing secure FTP server connections
cfftp: Connection: file and directory operations
cfftp action = "listDir"
See also

cfhttp, cfldap, cfmail, cfpop; Performing file operations with cfftp in Interacting with Remote Servers in the De
veloping ColdFusion Applications
History

ColdFusion 8: Added the fingerprint, key, paraphrase, and secure attributes to support secure FTP. Added
the values ="quote", "site", "allo", and "acct" to the action attribute.ColdFusion MX 7: Added the res
ult attribute for file and directory operations.ColdFusion MX: Deprecated the agentname attribute. It might not
work, and might cause an error, in later releases.
Usage

Use this tag to move files between a ColdFusion server and an FTP server.
This tag does not move files between a ColdFusion server and a client browser. You do this as follows:
To transfer files from a client to a ColdFusion server: cffile action = "upload"
To transfer files from a ColdFusion server to a client: the cfcontent tag
Security settings

ColdFusion security settings can prevent the cfftp tag from executing. If you run ColdFusion applications on a
server that is used by multiple customers, consider the security of the files that the customer can move. For more
information, see the Administering ColdFusion Security section of Configuring and Administering ColdFusion.

© 2014 Adobe Systems Incorporated. All rights reserved.

501

Adobe ColdFusion Documentation

cfftp: Opening and closing FTP server connections
Description

To establish a connection with an FTP server, use the open action with a connection attribute.
Syntax



Note
You can specify this tag's attributes in an attributeCollection attribute whose value is a
structure. Specify the structure name in the attributeCollection attribute and use the tag's
attribute names as structure keys.

See also

cfhttp, cfldap, cfmail, cfpop
Attributes

Attribute

Req/Opt

© 2014 Adobe Systems Incorporated. All rights reserved.

Default

Description

502

Adobe ColdFusion Documentation

action

Required

FTP operation to perform.
open: creates an FTP
connection.
close: terminates an
FTP connection.
quote: sends a
command verbatim to
the FTP server.
site: executes a
site-specific command.
allo: allocates
memory for operations,
such as putting large
files, on the server.
acct: sends account
information on systems
that require it.

actionparam

Optional

Used only when action i
s quote, site, or acct.
Specifies the command
when action is quote or
site; specifies account
information when action
is acct.

buffersize

Optional

Buffer size in bytes.

connection

Optional, but always used
with open or close

Name of the FTP
connection. If you specify
the username, passwor
d, and server attributes,
and if no connection
exists for them,
ColdFusion creates one.
Calls to cfftp with the
same connection name
reuse the connection.

passive

Optional

password

Required if action =
"open"

port

Optional

© 2014 Adobe Systems Incorporated. All rights reserved.

no

yes: enables passive
mode.
no
Password to log in the
user.

21

Remote port to which to
connect.

503

Adobe ColdFusion Documentation

proxyServer

Optional

String. Name of proxy
server (or servers) to use,
if proxy access is
specified.

retryCount

Optional

server

Required if action =
"open"

stopOnError

Optional

yes

timeout

Optional

30

username

Required if action =
"open"

1

Number of retries until
failure is reported.
FTP server to which to
connect; for example, ftp
.myserver.com.
yes: halts processing,
displays an appropriate
error.
no: if secure="no",
populates these
variables:
cfftp.succeeded: y
es or no.
cfftp.errorCode:
error number. See the
IETF Network Working
Group RFC 959: File
Transfer Protocol (FTP)
at www.ietf.org/rfc/rfc09
59.txt.
cfftp.errorText:
Message text.
For conditional
operations, use cfftp.
errorCode. Do not
use cfftp.errorTex
t for this purpose.
Value in seconds for the
time-out of all operations,
including individual data
request operations.
User name to pass in the
FTP operation.

Usage

When you establish a connection with cfftp action="open" and specify a name in the connection attribute,
ColdFusion caches the connection so that you can reuse it to perform additional FTP operations. When you use a
cached connection for subsequent FTP operations, you do not have to specify the username, password, or serve
r connection attributes. The FTP operations that use the same connection name automatically use the
information stored in the cached connection. Using a cached connection helps save connection time and improves

© 2014 Adobe Systems Incorporated. All rights reserved.

504

Adobe ColdFusion Documentation

file transfer performance. You do not need to open a connection for single, simple, FTP operations, such as GetFil
e or PutFile.
With any action except close, you can set the internal buffer size by specifying buffersize. If you specify quote,
site, allo, or acct as the action and set secure="yes" an error is generated. You specify the command to
send to the FTP server in the actionparam attribute when you specify site or quote as the action. When site is
the action, you use the actionparam attribute to specify the site-specific information.
To keep a connection open throughout a session or longer, put the connection name in the Session or Application
scope; for example, specify connection="Session.FTPConnection". However, if you do this, you must specify
the full variable name in all FTP operations, and you must use the close action when you are finished. Keeping a
connection open prevents others from using the FTP server; so close a connection as soon as possible. If you do
not assign the connection name to Session or Application variable, the connection remains open for the current
page only, and you do not have to close it manually. Changes to a cached connection, such as changing retryCou
nt or timeout values, might require reestablishing the connection.
Example

cfftp lets users implement File Transfer Protocol operations. By default, cfftp
caches
an open connection to an FTP server.
cfftp operations are usually of two types:

Establishing a connection
Performing file and directory operations

This example opens and verifies a connection, lists the files in a directory, and
closes
the connection.
Open a connection

Did it succeed? #cfftp.succeeded#
List the files in a directory:


#name#


Close the connection:

Did it succeed? #cfftp.succeeded#

© 2014 Adobe Systems Incorporated. All rights reserved.

505

Adobe ColdFusion Documentation

cfftp: Opening and closing secure FTP server connections
Description

To establish a connection with a secure FTP server, use the open action with a connection attribute, specify that
secure = "yes", and specify the key, passphrase, and fingerprint as appropriate.


passphrase = "passphrase"
password = "password"
port = "port"
proxyServer = "proxy server"
retryCount = "number"
secure = "yes|no"
server = "server"
stopOnError = "yes|no"
timeout = "time-out in seconds"
username = "name">

Note
You can specify this tag's attributes in an attributeCollection attribute whose value is a
structure. Specify the structure name in the attributeCollection attribute and use the tag's
attribute names as structure keys.

See also

cfhttp, cfldap, cfmail, cfpop
Attributes

Attribute

Req/Opt

action

Required

Default

Description
FTP operation to perform.
open: creates an FTP
connection.
close: terminates an
FTP connection.

© 2014 Adobe Systems Incorporated. All rights reserved.

506

Adobe ColdFusion Documentation

connection

Optional, but always used
with open or close

Name of the FTP
connection. If you specify
the username, passwor
d, and server attributes,
and if no connection
exists for them,
ColdFusion creates one.
Calls to cfftp with the
same connection name
reuse the connection.

fingerprint

Optional. Used only when
server, username, and
password are supplied

Fingerprint of the host key
in the form ssh-dss.ssh
-rsa, which is a 16-byte
unique identifier for the se
rver attribute that you
specify, The fingerprin
t consists of eight pairs of
hexadecimal values in the
form hh:hh:hh:hh::hh
:hh:hh:hh. ColdFusion
checks the fingerprint
of the remote server only
if the fingerprint value
is specified.

key

Required if action="ope
n" (}}When
{{secure="yes", eithe
r password or key is
required.)

Public-key based
authentication. Refers to
the absolute path to the
private key of the user.
Possession of a private
key provides
authentication by sending
a signature created with a
private key. The server
must ensure that the key
is a valid authentication
for the user and that the
signature is valid. Both
must be valid to accept
the authentication.

passive

Optional

no

Valid only if secure="no
".
yes: enables passive
mode.
no

© 2014 Adobe Systems Incorporated. All rights reserved.

507

Adobe ColdFusion Documentation

passphrase

Optional. Used when key
is specified

Because private keys are
stored in an encrypted
form on the client host,
the user must supply a
passphrase to enable
generating the signature.

password

Required if action="ope
n" (}}When
{{secure="yes", either
password or key is
required.)

Password to log in the
user.

port

Optional

proxyServer

Optional

retryCount

Optional

1

secure

Optional

no

server

Required if action="ope
n"

© 2014 Adobe Systems Incorporated. All rights reserved.

21

Remote port to which to
connect.
String. Name of proxy
server (or servers) to use,
if proxy access is
specified.
Number of retries until
failure is reported.
yes: enables secure
FTP
no
FTP server to which to
connect; for example, ftp
.myserver.com.

508

Adobe ColdFusion Documentation

stopOnError

Optional

no

timeout

Optional

30

username

Required if action="ope
n"

yes: halts processing,
displays an appropriate
error.
no: if secure="yes",
populates the following
variables:
If ColdFusion fails to
connect to the secure
FTP server, it halts
processing and displays
the appropriate error
message
cfftp.succeeded: y
es or no
cfftp.errorCode:
error number
cfftp.errorText:
message text
For all file operations,
returns the following
error codes:
SSH-CONNECT 25
SSH_MSG_USERAUT
H_FAILURE 51
SSH_MSG_USERAUT
H_SUCCESS 52
SSH_MSG_REQUEST
_SUCCESS 81
SSH_MSG_REQUEST
_FAILURE 82For
conditional operations,
use cfftp.errorCod
e. Do not use cfftp.e
rrorText for this
purpose.
Value in seconds for the
time-out of all operations,
including individual data
request operations.
User name to pass in the
FTP operation.

Usage

The cfftp tag lets you open a connection to a Secure Shell (SSH) server by using either symmetric or asymmetric
encryption. To use symmetric encryption, you specify secure="yes", the user name, password, connection, and
fingerprint. To use asymmetric encryption, first generate private-public key pairs for each user authorized to have
access to the server. Each authorized user's public key is stored on the server; each user's private key is encrypted
and stored on that user's computer. To open a connection to the SSH server, you specify secure="yes", the user

© 2014 Adobe Systems Incorporated. All rights reserved.

509

Adobe ColdFusion Documentation

name, the password, or the private key and the passphrase that the server uses to decrypt the private key,
connection, and fingerprint. After you open the connection to the SSH server, you can use that connection for any
action supported by the cfftp tag. To keep a connection open throughout a session or longer, put the connection
name in the Session or Application scope; for example, specify connection="Session.FTPConnection".
However, if you do this, specify the full variable name in all FTP operations, and use the close action when you are
finished. Keeping a connection open prevents others from using the FTP server; so close a connection as soon as
possible. If you do not assign the connection name to Session or Application variable, the connection remains open
for the current page only, and you do not have to close it manually. Changes to a cached connection, such as
changing retryCount or timeout values, might require reestablishing the connection.
Example




Did it succeed? #cfftp.succeeded#








Did it succeed? #cfftp.succeeded#



Example

© 2014 Adobe Systems Incorporated. All rights reserved.

510

Adobe ColdFusion Documentation




Did it succeed? #cfftp.succeeded#











© 2014 Adobe Systems Incorporated. All rights reserved.

511

Adobe ColdFusion Documentation

cfftp: Connection: file and directory operations
Description

To perform file and directory operations with cfftp, use this form of the cfftp tag.
Syntax



Note
You can specify this tag's attributes in an attributeCollection attribute whose value is a
structure. Specify the structure name in the attributeCollection attribute and use the tag's
attribute names as structure keys.

See also

cfhttp, cfldap, cfmail, cfpop
Attributes

Attribute

Req/Opt

© 2014 Adobe Systems Incorporated. All rights reserved.

Default

Description

512

Adobe ColdFusion Documentation

action

Required if connection is
not cached

FTP operation to perform:
changedir
createDir
listDir
removeDir
getFile
putFile
rename
remove
getCurrentDir
getCurrentURL
existsDir
existsFile
exists

ASCIIExtensionList

Optional

connection

Required if action = "op
en" or "closed"

The name of the FTP
connection.Used to cache
a new FTP connection or
to reuse an existing
connection.

directory

Required if action =
"changedir", "create
Dir", "listDir", or "
existsDir"

Directory on which to
perform an operation.

existing

Required if action =
"rename"

Current name of the file or
directory on the remote
server.

failIfExists

Optional

item

Required if action =
"exists" or "remove"

Object of these actions:
file or directory.

localFile

Required if action =
"getFile" or "putFile
"

Name of the file on the
local file system. For more
information, see Usage.

name

Required if action =
"listDir"

Query name of directory
listing.

© 2014 Adobe Systems Incorporated. All rights reserved.

txt;htm;html; cfm;cf
ml;shtm;
shtml;css;asp;asa

yes

Delimited list of file
extensions that force
ASCII transfer mode, if tr
ansferMode = "auto".

yes: If a local file with
same name exists, the
getFile action fails.
no

513

Adobe ColdFusion Documentation

new

Required if action =
"rename"

New name of file or
directory on the remote
server.

passive

Optional

password

Required if action =
"open"

Password to log in the
user.

proxyServer

Optional

String. Name of the proxy
servers to use, if proxy
access is specified.

remoteFile

Required if action =
"getFile", "putFile",
or "existsFile"

Name of the file on the
FTP server file system.

result

Optional

Specifies a name for the
structure in which cfftp
stores the returnValue
variable. If set, this value
replaces cfftp as the
prefix to use when
accessing returnVaria
ble. For more
information, see Usage.

server

Required if FTP
connection is not cached

FTP server to which to
connect; for example, ftp
.myserver.com.

timeout

Optional

30 seconds

transferMode

Optional

auto

username

Required if connection is
not cached

no

yes: enables passive
mode.
no

The length of time, in
seconds, that ColdFusion
waits for a response from
the FTP server.Used with
action = "open" for a
cached connection.
ASCII FTP transfer
mode
Binary FTP transfer
mode
Auto FTP transfer mode
User name to pass in the
FTP operation.

Usage

© 2014 Adobe Systems Incorporated. All rights reserved.

514

Adobe ColdFusion Documentation

If you use connection caching to an active FTP connection, you do not have to respecify the username, password,
or server connection attributes.Changing a cached connection, such as changing retryCount or timeout value
s, might require reestablishing the connection. If action = "listDir", the attributes column returns direct
ory or normal. Other platform-specific values, such as hidden and system, are no longer supported.
If action = "listDir", a mode column is returned. The column contains an octal string representation of UNIX
permissions; for example, "777."The cfftp.returnValue variable provides the return value for these actions:
getCurrentDir
getCurrentURL
existsDir
existsFile
exists
For more information, see the Developing ColdFusion Applications.
For more information, see the section Performing file operations with cfftp in Developing ColdFusion
Applications.
localFile attribute

Use the following syntax to specify an in-memory file, which is not written to disk, as the local file. In-memory files
speed processing of transient data.

ram:///filepath

The filepath can include directories, for example ram:///petStore/images/poodle.jpg. Create the directories
in the path before you specify the file. For more information on using in-memory files, see Working with in-memory
files in Optimizing ColdFusion applications in the Developing ColdFusion Applications.
Action (cfftp.ReturnValue variable)

The results of an action determine the value of the returnValue variable, as the following table shows:
cfftp action

Value of cfftp.returnValue

getCurrentDir

String. Current directory.

getCurrentURL

String. Current URL.

existsDir

yes or no.

existsFile

yes or no.

exists

yes or no.

To access the returnValue variable, you must prefix it with either cfftp or the value specified by the result attr
ibute, if it is set. The result attribute provides a way for cfftp calls from multiple pages, possibly at the same
time, to avoid overwriting the results of one with another. If you set the result attribute to myResult, for example,
you would access the returnVariable variable as myResult.returnVariable. Otherwise, you would access
it as cfftp.returnVariable.

© 2014 Adobe Systems Incorporated. All rights reserved.

515

Adobe ColdFusion Documentation
Example

The following example opens a connection and gets a file that lists file or directory name, path, URL, length, and
modification date:

Open a connection

Did it succeed? #cfftp.succeeded#

FTP Directory Listing:









Move Image File to Remote Server:



Did it succeed? #cfftp.succeeded#
Close the connection:

Did it succeed? #cfftp.succeeded#

© 2014 Adobe Systems Incorporated. All rights reserved.

516

Adobe ColdFusion Documentation

cfftp action = "listDir"
Description

To access the columns in a query object, use this tag with action = "listDir".
Usage

When you use this action, specify a value for the name attribute. This value holds the results of the listDir action
in a query object. The query object consists of columns that you can reference, in the form queryname.columnam
erow, where queryname is the name of the query, specified in the name attribute; and columnname is a column
returned in the query object. The value row is the row number of each file/directory entry returned by the listDir o
peration. A separate row is created for each entry:
cfftp query object column

Description

Name

Filename of the current element.

Path

File path (without drive designation) of the current
element.

URL

Complete URL for the current element (file or
directory).

Length

File size of the current element.

LastModified

Unformatted date/time value of the current element.

Attributes

String. Attributes of the current element: normal or
Directory.

IsDirectory

Boolean. Whether object is a file or directory.

Mode

Applies only to UNIX and Linux. Permissions. Octal
string.

Note
Previously supported query column values that pertain to system-specific information are not
supported; for example, hidden and system.

© 2014 Adobe Systems Incorporated. All rights reserved.

517

Adobe ColdFusion Documentation

cfform
Description

Builds a form with CFML custom control tags; these provide more functionality than standard HTML form input
elements. You can include the resulting form on the client page as HTML or Adobe Flash content, and generate the
form by using XML and XSLT.
Category

Forms tags
Syntax



onSubmit =

...


Note
You can specify this tag's attributes in an attributeCollection attribute whose value is a
structure. Specify the structure name in the attributeCollection attribute and use the tag's
attribute names as structure keys.

See also

cfajaximport, cfapplet, cfcalendar, cfformgroup, cfformitem, cfgrid, cfinput, cfselect, cfslid
er, cftextarea, cftree; Requesting and Presenting Information in the Developing ColdFusion Applications
History

ColdFusion 8:

© 2014 Adobe Systems Incorporated. All rights reserved.

518

Adobe ColdFusion Documentation

Added support for adding interactive fields in PDF forms.
Added the onSuccess attribute and support in AJAX controls for the onError attribute

ColdFusion MX 7:
Added ability to set the default value of the scriptSrc attribute in the ColdFusion Administrator.
Deprecated the passthrough attribute. The tag now supports all HTML form tag attributes directly.
Added the method attribute and support for the GET method.
Added support for Flash and XML output, including the format, height, width, preloader, timeout, wM
ode, accessible, and skin attributes.
Added cfformgroup, cfformitem, and cftextarea child tags.
Added the onReset attribute.

ColdFusion MX:
Deprecated the enableCAB attribute. It might not work, and might cause an error, in later releases.
Changed the name and action attributes to optional.
Changed integer validation to require an integer value. In previous releases it would convert a floating point
value to an integer.
Attributes

The following table lists attributes that ColdFusion uses directly. For HTML format forms, this tag also supports the
standard HTML form tag attributes that are not on this list, and passes them directly to the browser. ColdFusion
also includes all supported HTML attributes in the XML.
Attribute

Applies to

Req/Opt

Default

Description

accessible

Flash

Opt

no

Specifies whether to
include support
screen readers in
the Flash form.
Screen reader
support adds
approximately 80
KB to the SWF file
sent to the client.

© 2014 Adobe Systems Incorporated. All rights reserved.

519

Adobe ColdFusion Documentation

action

FlashHTMLXML

Opt

See Description

Name of ColdFusion
page to execute
when the form is
submitted for
processing.
If you omit this
attribute and the
method is get, the
form posts to the
page identified by
the
CGI.SCRIPT_NAME
variable (the
requested page that
resulted in
displaying the form).
If the method is
post, the form posts
to the page
identified by the
CGI.QUERY_STRI
NG variables.

archive

applets in HTML
and XML

Opt

/CFIDE/classes/cfap
plets.jar

URL of
downloadable Java
classes for cfgrid,
cfslider, and cft
ree applet controls.

codeBase

applets in HTML
and XML

Opt

/CFIDE/classes/cf-j2
re-win.cab

URL of
downloadable JRE
plug-in for Internet
Explorer; used for c
fgrid, cfslider,
and cftree Java
applet controls.

© 2014 Adobe Systems Incorporated. All rights reserved.

520

Adobe ColdFusion Documentation

format

FlashHTMLXML

Opt

HTML

HTML: generates
an HTML form
and send it to the
client. cfgrid an
d cftree child
controls can be in
Flash or applet
format.
Flash: generates
a Flash form and
send it to the
client. All controls
are in Flash
format.
XML: generates
XForms-compliant
XML and save the
results in a
variable specified
by the name attrib
ute. By default,
ColdFusion also
applies an XSL
skin and displays
the result. For
more information,
see the skin attri
bute.

height

FlashXML

Opt

100%

The height of the
form. Use a number
to specify pixels. In
Flash, you can use
a percentage value,
such as "height=6
0%" to specify a
percentage of the
available width. The
displayed height
might be less than
the specified size.
Note: The width a
nd height attribute
s are required for
Flash forms, if they
are used inside of a
table.

name attribute value

the HTML id of the
form.

id

© 2014 Adobe Systems Incorporated. All rights reserved.

521

Adobe ColdFusion Documentation

method

FlashHTML XML

Opt

post

The method the
browser uses to
send the form data
to the server:
post: sends the
data using the
HTTP post
method. This
method sends the
data in a separate
message to the
server.
get: sends the
data using the
HTTP get method,
which puts the
form field contents
in the URL query
string.

name

FlashHTMLXML

© 2014 Adobe Systems Incorporated. All rights reserved.

Opt

CFForm_n

A name for the form.
In HTML format, if
you omit this
attribute and specify
an id attribute,
ColdFusion does not
include a name
attribute in the
HTML sent to the
browser; this
behavior lets you
use the cfform tag
to create
XHTML-compliant
forms. If you omit
the name attribute
and the id attribute,
ColdFusion
generates a name of
the form CFForm_n
where n is a number
that is assigned
serially to the forms
on a page.

522

Adobe ColdFusion Documentation

onError

FlashHTML

Opt

For Flash format
forms: Applies only
for onSubmit or
onBlur validation;
has no effect for
onServer validation.
An ActionScript
expression or
expressions to
execute if the user
submits a form with
one or more
validation errors.
For HTML format
forms: Applies only
to forms inside cfd
iv, cflayout, cfp
od, or cfwindow co
ntrols. The name of
a JavaScript
function that runs if
an asynchronous
form submission
fails. For more
information, see the
Usage section.

onLoad

HTMLXML

Opt

JavaScript to
execute when the
form loads.

onReset

HTMLXML

Opt

JavaScript to
execute when the
user clicks a reset
button.

onSubmit

FlashHTMLXML

Opt

JavaScript or
ActionScript function
to execute to
preprocess data
before form is
submitted. If any
child tags specify on
Submit field
validation,
ColdFusion does the
validation before
executing this
JavaScript.

© 2014 Adobe Systems Incorporated. All rights reserved.

523

Adobe ColdFusion Documentation

onSuccess

HTML

Opt

preloader

Flash

Opt

© 2014 Adobe Systems Incorporated. All rights reserved.

Applies only to
forms inside cfdiv,
cflayout, cfpod,
or cfwindow contro
ls. The name of a
JavaScript function
that runs when an
asynchronous form
submission
succeeds. For more
information see the
Usage section.
yes

Specifies whether to
display a progress
bar when loading
the Flash form.

524

Adobe ColdFusion Documentation

preserveData

HTMLXML

Opt

no

When the cfform a
ction attribute
posts back to the
page that contains
the form, this
attribute determines
whether to override
the control values
with the submitted
values.
no: uses values
specified in the
control tag
attributes.
yes: uses
corresponding
submitted values.
Applies to these
controls:
cfinput, cfsli
der, cftextinp
ut: overrides the
value attribute
value.
cfselect control
s that are
populated from
queries: overrides
the selected att
ribute. See cfsel
ect.
cftree controls:
overrides the cft
reeitem expand
attribute. If yes,
expands
previously-selecte
d elements. The c
ftree complete
Path attribute
must be set to ye
s.
cfgrid controls:
has no effect.
(This avoids
confusion as to
whether data has
been resubmitted
to the database
by the control.)

© 2014 Adobe Systems Incorporated. All rights reserved.

525

Adobe ColdFusion Documentation

scriptSrc

FlashHTMLXML

© 2014 Adobe Systems Incorporated. All rights reserved.

Opt

See Description

Specifies the URL,
relative to the web
root, of the directory
that contains
ColdFusion
JavaScript files,
including the
cfform.js file with the
client-side
JavaScript used by
this tag and its child
tags. For XML
format forms, this
directory is also the
default directory for
XSLT skins. When
you use this
attribute, the
specified directory
must have the same
structure as the
/CFIDE/scripts
directory. For
example, if you
specify scriptsrc
="/resources/my
Scripts", the
JavaScript files used
by ColdFusion AJAX
features must be in
the
/resources/myScript
s/ajax directory.
This attribute is
useful if the file is
not in the default
location. This
attribute may be
required in some
hosting
environments and
configurations that
block access to the
/CFIDE directory.
The location is set in
the ColdFusion
Administrator; by
default, it is
/CFIDE/scripts.
Notes: If you
specify this attribute,
copy the
CF_RunActiveConte

526

Adobe ColdFusion Documentation

nt.js file from the
CFIDE/scripts
directory to the
specified directory.
You can have only
one scriptsrc attr
ibute on a page,
including any cfaja
ximport tag scrip
tsrc}}attribute
. If you have
multiple
{{cfform tags, you
can specify the scr
iptsrc attribute in

© 2014 Adobe Systems Incorporated. All rights reserved.

527

Adobe ColdFusion Documentation

a cfajaximport ta
g and it applies to all
HTML format forms.
skin

FlashXML

Opt

Flash:
{{haloGreen}}XML:
default.xsl

Flash: Use a halo
color to stylize the
output. The skin
determines the color
used for highlighted
and selected
elements.
haloSilver
haloBlue
haloGreen
haloOrange
XML: Specifies
whether to apply
an XSL skin and
display the
resulting HTML to
the client. Can be
any of the
following:
ColdFusion skin
name: applies the
specified skin.
XSL file name:
applies the skin
located in the
specified path.
none: does not
apply an XSL
skin. Your CFML
page must
process the XML
that ColdFusion
saves in the
variable specified
by the name attrib
ute, and display
any results.
omitted or defau
lt: uses the
ColdFusion
default skin.
You can specify
the following
ColdFusion skins
(located in the cf_
webroot
x
basic

© 2014 Adobe Systems Incorporated. All rights reserved.

528

Adobe ColdFusion Documentation

basiccss
beige
blue
lightgray
red
silver
A filename can be
any of the
following:
absolute URL
URL relative to
the web root
absolute file path
name of a file in
the scripts folder
or a subdirectory
of the cf_webroot\
CFIDE\scripts
directory. In this
case, do not
specify the .xsl
suffix.
style

HTML, Flash, XML

© 2014 Adobe Systems Incorporated. All rights reserved.

Opt

Styles to apply to
the form. In HTML
or XML format,
ColdFusion passes
the style attribute to
the browser or XML.
In Flash format,
must be a style
specification in CSS
format. For detailed
information on
specifying Flash
styles, see Creating
Forms in Flash in
the Developing
ColdFusion
Applications.

529

Adobe ColdFusion Documentation

timeout

Flash

Opt

0

Integer number of
seconds for which to
keep the form data
in the Flash cache
on the server. A
value of 0 prevents
the data from being
cached. For more
information, see
Caching data in
Flash forms in Best
practices for Flash
forms in the Develo
ping ColdFusion
Applications.

width

FlashXML

Opt

100%

The width of the
form. Use a number
to specify pixels. In
Flash, you can use
a percentage value,
such as "width=60
%" to specify a
percentage of the
available
width.Note: The wid
th and height attri
butes are required
for Flash forms, if
they are used inside
of a table.

© 2014 Adobe Systems Incorporated. All rights reserved.

530

Adobe ColdFusion Documentation

Flash

wMode

Opt

window

Specifies how the
Flash form appears
relative to other
displayable content
that occupies the
same space on an
HTML page.
window: the
Flash form is the
topmost layer on
the page and
obscures anything
that would share
the space, such
as drop-down
dynamic HTML
lists.
transparent:
the Flash form
honors the
z-index of dhtml
so you can float
items above it. If
the Flash form is
above any item,
transparent
regions in the
form show the
content that is
below it.
opaque: the
Flash form honors
the z-index of
dhtml so you can
float items above
it. If the Flash
form is above any
item, it blocks any
content that is
below it.

Note
Attributes that are not marked as supported in XML are not handled by the skins provided with
ColdFusion. They are, however, included in the generated XML as html namespace attributes to
the form tag.

Usage

This tag requires an end tag.
You can use the following ColdFusion form control tags in the cfform tag:

© 2014 Adobe Systems Incorporated. All rights reserved.

531

Adobe ColdFusion Documentation

cfapplet: Used in HTML and XML format only; embeds a registered Java applet.
cfformgroup: Used in Flash and XML format only; groups and arranges child controls.
cfformitem: Used in Flash and XML format only; adds horizontal rules, vertical rules, and text to the form.
cfgrid: Creates a grid control to display tabular data.
cfinput: Creates and an input element.
cfselect: Creates a drop-down list box.
cfslider: Used in HTML and XML format only; creates a slider control.
cftextarea: Creates a multiline text input box.
cftree: Creates a tree control.

In HTML format, all tags, and in Flash format the cftree and cfgrid tags, require JavaScript support on
the browser. The cfapplet tag and applet format cfgrid, cfslider, and cftree tags require the client
to download a Java applet. If you specify Flash format in the cfform tag, ColdFusion ignores any HTML in
the form body. Use ColdFusion tags, such as cfinput, for all form controls. You can include individual Flash
format cfgrid and cftree controls in an HTML format cfform tag.
In Flash format, if your forms do not request sensitive data (such as credit card numbers), consider setting
the timeout attribute. This can prevent users from getting "The form data has expired. Please reload this
page in your browser" errors if they use the browser back button to return to the form. For more information, s
ee Caching data in Flash forms in Best practices for Flash forms in the Developing ColdFusion Applications.
Note
In Flash format, if you do not specify height and width attributes, Flash reserves
browser space equal to the area of the browser window. If any other output follows the
form, users must scroll to see it. Therefore, if you follow a Flash form with additional
output, specify the height and width values. The width and height attributes are
required for Flash forms, if they are used inside of a table.

If attribute value text must include quotation marks, escape them by doubling them.
Using the onError attribute in Flash forms

If you use onSubmit or onBlur validation, the onError attribute lets you specify ActionScript code to execute if the
user tries to submit a Flash form with validation errors, as follows:
If you specify one or more valid Flash expressions, Flash executes the expressions.
If you omit the attribute, Flash displays a dialog box with all applicable error messages.
If you specify onError="" (an empty string) Flash does not display any message, but does not submit the
form.
Your ActionScript can use the errors variable to determine the fields and errors. The errors object has the
following fields:
Field

Contents

name

The name attribute of the control's CFML tag.

field

The internal name used by Flash for the field name (for
example, _level0.field1).

value

The value in the field.

© 2014 Adobe Systems Incorporated. All rights reserved.

532

Adobe ColdFusion Documentation

message

The message attribute of the control's CFML tag.

The following example shows cfform tags with an onError attribute that selects the tab in an accordion or tab
navigator that contains a lastName field with an invalid entry:



Incorporating HTML form tags and attributes

In HTML format, the cfform tag lets you incorporate the following standard HTML elements. They are not available
in Flash format:
Standard HTML form tag attributes and values. The attributes and values are included in the form tag that c
fform outputs in the page. For example, you can use form tag attributes like target or onMouseOver with
cfform.
HTML tags that can ordinarily be put within the HTML form tag. For example, you can use the HTML input
tag to create a submit button in a cfform, without the other features of cfinput:





Using forms in cfdiv, cflayout, cffpod, and cfwindow controls

The cfdiv, cflayout, cffpod, and cfwindow tags create AJAX-based controls that can serve as containers for
interactive forms. When you use such a structure, you do not want submitting form information to cause a new page
to be displayed; instead, you want dynamic code to modify the existing page without causing a complete reload. You
can do this by using the onSuccess and onError attributes.
The function specified by the onSuccess attribute gets called if the form data is submitted successfully. This
function is responsible for updating the pod, layout, or window to reflect the results of the submission, for example,
to display additional data or pop up a confirmation window. This function must not take any argumentsThe function
specified by the onError attribute gets called if an error occurs when the form data is submitted. This function is
responsible for handling the error, such as displaying an error message. This function must take two arguments: an
error number and an error message.
Incorporating interactive fields in PDF forms

ColdFusion lets you use the cfform tag to create PDF forms that contain static and interactive form fields. The cff
orm tag must exist within a cfdocument tag (where format="pdf"). Only one cfform tag can exist within a cfd
ocument tag.Completed forms can be posted to the server as an HTTP Post, or the entire PDF can be submitted as
binary stream. If the PDF is submitted, you can use the cffile tag to save completed PDF form to a hard drive:}}The output can
be manipulated and extracted by using the tag. Only the following {{cfform attributes are
supported in generating PDF forms:
action
format

© 2014 Adobe Systems Incorporated. All rights reserved.

533

Adobe ColdFusion Documentation

method
name
onSubmit
skin
style
To embed an existing PDF form generated by LiveCycle Designer or Acrobat, use the tag.
Example

© 2014 Adobe Systems Incorporated. All rights reserved.

534

Adobe ColdFusion Documentation

cfform Example



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


Results of Checkbox Test

Your checkbox answer was yes

Your checkbox answer was no


Results of Credit Card Input
Your credit card number, #Form.textSample#,
was valid under the MOD 10 algorithm.



You gave this page a rating of #Form.sampleSlider#






This example displays radio button input type for cfinput.
Yes 
No 
This example displays checkbox input type for cfinput.

This shows client-side validation for cfinput text boxes.
(This item is optional)

Please enter a credit card number:

This example shows the use of the cfslider tag.
Rate your approval of this example from 1 to 10 by sliding control.

1  10




A simple XML form

The following example shows a simple XML-format form. It uses the default.xsl transform that is supplied with
ColdFusion to generate the HTML output for display:

© 2014 Adobe Systems Incorporated. All rights reserved.

535

Adobe ColdFusion Documentation










California
Utah
Iowa
New York


this is sample text.


A simple PDF form



...
...







...
...



© 2014 Adobe Systems Incorporated. All rights reserved.

536

Adobe ColdFusion Documentation

cffunction
Description

Defines a function that you can call in CFML. Required to define ColdFusion component methods.
History

ColdFusion 10: restPath, httpMethod, produces, {{consumes}}
ColdFusion 8:
Added returnformat, secureJSON, and verifyClient attributes
Added component as a valid value for the ReturnType attribute.
ColdFusion MX 7: Added the description attribute, and added the XML value to the returntype attribute
.ColdFusion MX: Added this tag.
Category

Extensibility tags
Syntax



See also

cfargument, cfcomponent, cfinterface, cfinvoke, cfinvokeargument, cfobject, cfproperty, cfret
urn, SerializeJSON
Attributes

Attribute

Req/Opt

name

Required

© 2014 Adobe Systems Incorporated. All rights reserved.

Default

Description
A string; a component
method that is used in the
cfcomponent tag.

537

Adobe ColdFusion Documentation

access

Optional

public

The client security context
from which the method
can be invoked. The
following values are valid:
private: available
only to the component
that declares the
method and any
components that extend
the component in which
it is defined.
package: available
only to the component
that declares the
method, components
that extend the
component, or any
other components in the
package. Methods are
available to the CFC
pages in the same
package.
public: available to a
locally executing page
or component method.
remote: available to a
locally or remotely
executing page or
component method, or
a remote client through
a URL, Flash, or a web
service. To publish the
function as a web
service, this option is
required.

description

Optional

Supplies a short text
description of the function.

displayname

Optional

Meaningful only for CFC
method parameters. A
value to be displayed in
parentheses following the
function name when using
introspection to show
information about the
CFC.

© 2014 Adobe Systems Incorporated. All rights reserved.

538

Adobe ColdFusion Documentation

hint

Optional

output

Optional

Meaningful only for CFC
method parameters. Text
to be displayed when
using introspection to
show information about
the CFC. The hint attrib
ute value follows the
syntax line in the function
description.
Function body is
processed as standard
CFML

Specifies under which
conditions the function
can generate HTML
output.
The following values are
valid:
yes: the entire function
body is processed as if
it were in a cfoutput t
ag. Variables names
surrounded by number
signs (#) are
automatically replaced
with their values.
no: the function is
processed as if it were
within a cfsilent tag.
If you do not specify this
attribute, the function
body is processed as
standard CFML. Any
variables must be in cf
output tags.

returnformat

© 2014 Adobe Systems Incorporated. All rights reserved.

Return as WDDX or XML;
see description.

The format in which to
return values to a remote
caller. This attribute has
no effect on values
returned to a local caller.
The following values are
valid:

539

Adobe ColdFusion Documentation

json: serialize the
return value into JSON
format before returning
it remotely.
wddx: serialize the
return value into WDDX
format before returning
it remotely.
plain: ensure that the
return value is a type
that ColdFusion can
convert directly to a
string, and return the
string value without
serialization. Valid types
include all simple types,
such as numbers, and
XML objects. If the
return value is a
complex type, such as
an array, or a binary
value, ColdFusion
generates an error. If
you specify a returnt
ype attribute, its value
must be any, boolean,
date, guid, numeric,
string, uuid, variab
lename, or XML;
otherwise, ColdFusion
generates an error.
By default, ColdFusion
serializes all return
types (including simple
return types), except
XML, into WDDX
format, and returns
XML data as XML text.
You can also use retu
rnformat as an HTTP
request parameter
when calling a remote
CFC function. This
parameter has the
same effect as the ret
urnformat attribute
and overrides any retu
rnformat attribute
value specified in the c
ffunction tag.

© 2014 Adobe Systems Incorporated. All rights reserved.

540

Adobe ColdFusion Documentation

returnType

Required for a web
service; Optional,
otherwise.

any

String; a type name; data
type of the function return
value:
any
array
binary
boolean
component: the return
value must be a
ColdFusion component.
date
guid: the argument
must be a UUID or
GUID of the form xxxxx
xxx-xxxx-xxxx-xxxx-xxx
xxxxxxxxx where each_
x_ is a character that
represents a
hexadecimal number
(0-9A-F).
numeric
query
string
struct
uuid: the argument
must be a ColdFusion
UUID of the form xxxxx
xxx-xxxx-xxxx-xxxxxxxx
xxxxxxxx where each_
x_ is a character that
represents a
hexadecimal number
(0-9A-F).
variableName: a
string formatted
according to
ColdFusion variable
naming conventions.
void: does not return a
value.
xml: allows web service
functions to return
CFML XML objects and
XML strings.

© 2014 Adobe Systems Incorporated. All rights reserved.

541

Adobe ColdFusion Documentation

A component name: If
the returntype attribu
te value is not one of
the preceding items,
ColdFusion treats it as
the name of a
ColdFusion component.
When the function
executes, it generates
an error if the value that
is returned is not a CFC
with the specified name.
Note: If a function does
not return a value and
the returnType value
is string, ColdFusion
generates an error;
ColdFusion does not
generate an error for
other types.
roles

Optional

© 2014 Adobe Systems Incorporated. All rights reserved.

"" (empty)

A comma-delimited list of
ColdFusion security roles
that can invoke the
method. Only users who
are logged in with the
specified roles can
execute the function. If
this attribute is omitted, all
users can invoke the
method.

542

Adobe ColdFusion Documentation

secureJSON

Optional

See Description

A Boolean value that
specifies whether to add a
security prefix in front of
any value that the function
returns in JSON-format in
response to a remote call.
The default value is the
value of any This.secur
eJSON variable in the
Application.cfc file or the s
ecureJSON attribute of
the cfapplication tag,
or if there is
no{{secureJSON}}
application setting, the
Prefix Serialized JSON
setting in the
Administrator Server
Settings > Settings page,
which defaults to false.
For more information see I
mproving security in Ajax
programming rules and
techniques in the Developi
ng ColdFusion
Applications.

verifyClient

Optional

no

A Boolean value that
specifies whether to
require remote function
calls to include an
encrypted security token.
For use with ColdFusion
AJAX applications only.
For more information see I
mproving security in Ajax
programming rules and
techniques in the Developi
ng ColdFusion
Applications.

© 2014 Adobe Systems Incorporated. All rights reserved.

543

Adobe ColdFusion Documentation

restPath

Optional

httpMethod

Specify to use a subresource path for the
CFC.
The path is
case-sensitive. Also, it is
preferable to avoid special
characters when you
specify the path. You can
include regular
expressions in the path.
For details of the
expressions that you can
specify, see the attribute r
estPath in cfcomponen
t.
The HTTP method to use,
must be one of the
following:
GET: Requests
information from the
server. Any data that
the server requires to
identify the requested
information must be in
the URL or in {{cfhttp
type="URL"}}tag.
POST: Sends
information to the
server for processing.
Requires one or more c
fhttpparam tags.
Often used for
submitting form-like
data.
PUT: Requests the
server to store the
message body at the
specified URL. Use this
method to send files to
the server.
DELETE: Requests the
server to delete the
specified URL.

© 2014 Adobe Systems Incorporated. All rights reserved.

544

Adobe ColdFusion Documentation

HEAD: Identical to the G
ET method, but the
server does not send a
message body in the
response. Use this
method for testing
hypertext links for
validity and
accessibility,
determining the type or
modification time of a
document, or
determining the type of
server. If you have not
specified HEAD, by
default, GET method is
called. However,
message body is not
sent in the response.
OPTIONS: A request for
information about the
communication options
available for the server
or the specified URL.
This method enables
the ColdFusion
application to determine
the options and
requirements
associated with a URL,
or the capabilities of a
server, without
requesting any
additional activity by the
server. If you have not
specified OPTIONS,
then ColdFusion sends
a response.
Overrides the value that
you specify at
component level.

© 2014 Adobe Systems Incorporated. All rights reserved.

545

Adobe ColdFusion Documentation

produces

Optional

© 2014 Adobe Systems Incorporated. All rights reserved.

/

Comma-separated list of
acceptable MIME types.
Used to specify the MIME
media type of
representation a resource
can produce, for example,
{{produces="text/plain,text
/html"}}If a resource can
produce more than one
MIME media type, the
function chosen
corresponds to the most
acceptable media type as
declared by the client.
If no value is specified, / i
s taken by default, which
means, all MIME types
are consumed. Overrides
the value that you specify
at the component level.

546

Adobe ColdFusion Documentation

consumes

Optional

/

Comma-separated list of
acceptable MIME types,
for example consumes="
text/plain,text/htm
l".Used to specify which
MIME media types of
representation a resource
can accept, or consume,
from the client. This
attribute overrides the
same attribute at the
component level.
If no value is specified, / i
s taken by default, which
means, all MIME types
are consumed. Adobe
recommends that you
avoid conflict scenarios
while specifying the
attributes produces and
consumes. For example,
avoid situations such as
the following: In function
1, you specify produces
as text/xml and consu
mes as text/ and in
function 2, produces as
text/ and consumes as
text/xml. Here, both the
functions are valid for the
request with accept =
text/xml and consume
s as text/xml.

Usage

The cffunction tag can define a function that you call in the same manner as a ColdFusion built-in function. To
define a ColdFusion component (CFC) method, use a cffunction tag. The following example shows cffunctio
n tag attributes for a simple CFC method that returns a ColdFusion Query object.



For detailed information on using the cffunction tag for ColdFusion components, see Building and Using
ColdFusion Components in the Developing ColdFusion Applications.

© 2014 Adobe Systems Incorporated. All rights reserved.

547

Adobe ColdFusion Documentation

If you specify returnformat="json" and the function returns a query, ColdFusion serializes the query into a
JSON Object with two entries, and array of column names, and an array of column data arrays. For more
information see SerializeJSON.
If you specify a roles attribute, the function executes only if a user is logged in and belongs to one of the specified
roles.
If you specify variableName for the returnType attribute, the function must return a string that is in ColdFusion
variable name format; that is, the function must return a string that starts with a letter, underscore, or Unicode
currency symbol, and consist of letters, numbers, and underscores (_), periods, and Unicode currency symbols,
only. ColdFusion does not check whether the value corresponds to an existing ColdFusion variable.
Example




SELECT FIRSTNAME, LASTNAME, EMAIL
FROM tblEmployees





SELECT *
FROM tblDepartments





#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

548

Adobe ColdFusion Documentation

Tags g-h
This section lists tags starting with alphabets G-H with their description.
cfgraph
cfgraphdata
cfgrid
cfgridcolumn
cfgridrow
cfgridupdate
cfheader
cfhtmlhead
cfhtmltopdf
cfhtmltopdfitem
cfhttp
cfhttpparam

© 2014 Adobe Systems Incorporated. All rights reserved.

549

Adobe ColdFusion Documentation

cfgraph
Description

This tag is deprecated. Use the cfchart, cfchartdata, and cfchartseries tags instead.Displays data
graphically.
History

ColdFusion 11: Removed this tag.
ColdFusion MX: Deprecated this tag. It works differently than it did in ColdFusion 5, and it might not work in later
releases.
The incompatibilities between the ColdFusion MX implementation and earlier implementations of this tag are as
follows:
cfgraph tag attribute

ColdFusion MX functionality

Title

Ignored.

Titlefont

Ignored.

Barspacing

Ignored.

Bordercolor

Color used for border, gridlines, and text displays.

Colorlist

List of colors to use for each data point for bar,
pyramid, area, horizontalbar, cone, cylinder, step, and
pie charts.

Valuelabelfont

Sets value label text font. If the Valuelabelfont, It
emlabelfont, and Legendfont values differ,
ColdFusion uses the last value that you specify in the
tag.Arial is not supported; it is mapped to Dialog.

Itemlabelfont

Sets item label text font. If the Valuelabelfont, Ite
mlabelfont, and Legendfont values differ,
ColdFusion uses the last value that you specify in the
tag.Arial is not supported; it is mapped to Dialog.

Legendfont

Sets legend text font. If the Valuelabelfont, Iteml
abelfont, and Legendfont values differ, ColdFusion
uses the last value that you specify in the tagArial is not
supported; it is mapped to Dialog.

ShowLegend

© 2014 Adobe Systems Incorporated. All rights reserved.

above, below, left, right: these options cause the
legend to display, but have no effect on its location.
none: prevents display of a legend.

550

Adobe ColdFusion Documentation

Valuelabelsize

Sets value label text size. If the Valuelabelsize and
Itemlabelsize values differ, ColdFusion uses the
last value that you specify in the tag.

Itemlabelsize

Sets item label text size.

Itemlabelorientation

Ignored. ColdFusion calculates best orientation based
on label and graph size.

Borderwidth

a nonzero number: default-width border, regardless
of number value.
0: no border.

Depth

0: displays graph with two-dimensional appearance.
any other value: displays graph with
three-dimensional appearance.

Linewidth
Showvaluelabel

Ignored.
yes: displays values on mouse-click.
no: suppresses value displays.
rollover: displays values on mouse-over.

Valuelocation

Ignored.

url

URL of page to open if any item in the graph is clicked.
The following variables may be used within the URL;
they are substituted with real values before the URL is
accessed:
"$value$": selected row/column value or an empty
string.
"$itemlabel$": selected item (column) value or
an empty string.
"$serieslabel$": selected series (row) value or
an empty string.
"javascript:...": executes client side scripts.

Urlcolumn

Ignored.

Type="HorizontalBar"

The (0,0) coordinate is located at the lower left.

ScaleFrom

If the smallest value in the data is less than scaleFro
m or the largest value in the data is greater than scale
To, the respective data value is used as the minimum
or maximum on the Y scale. Therefore, regardless of
the scaleFrom or scaleTo value, all data values
display.

© 2014 Adobe Systems Incorporated. All rights reserved.

551

Adobe ColdFusion Documentation

cfgraphdata
Description

This tag is deprecated. Use the cfchart, cfchartdata, and cfchartseries tags instead. Displays a data point
in a graph. Used within the cfgraph tag.
History

ColdFusion 11: Removed this tag.
ColdFusion MX: Deprecated this tag. It works differently than in ColdFusion 5 and might not work in later releases.

© 2014 Adobe Systems Incorporated. All rights reserved.

552

Adobe ColdFusion Documentation

cfgrid
Description

Used in the cfform tag. Puts a grid control (a table of data) in a ColdFusion form. To specify grid columns and row
data, use the cfgridcolumn and cfgridrow tags, or use the query attribute, with or without cfgridcolumn tag
s.
For CFC methods that returns numeric data with a leading zero, for example, zip code 02674, the zero is
interpreted by the bind expression as an octal number and its decimal equivalent (in this case 1468) even if you set
returnformat="string". To resolve this issue, for URL binds or binds routed by way of a JavaScript function
(for example, using cfajaxproxy), you can set returnformat=plain to retain the numeric value. Also, leading
zeros are stripped from the suggestion list for autosuggest controls.
Category

Forms tags
Syntax


zero or more cfgridcolumn and cfgridrow tags

© 2014 Adobe Systems Incorporated. All rights reserved.

554

Adobe ColdFusion Documentation



Note
You can specify this tag's attributes in an attributeCollection attribute whose value is a
structure. Specify the structure name in the attributeCollection attribute and use the tag's
attribute names as structure keys.

See also

cfajaximport, cfapplet, cfcalendar, cfgridcolumn, cfgridrow, cfgridupdate, cfform, cfformgrou
p, cfformitem, cfinput, cfselect, cfslider, cftextarea, cftree, Using HTML grids in the Developing
ColdFusion Applications
History

ColdFusion9.0.1: Added the attribute multirowselect, supported only in HTML grids.
ColdFusion 9:
Added collapsible, groupfield, onLoad, and title attributes, supported in HTML grids only.
Added ability to use the insert attribute in HTML grids.
ColdFusion 8: Added support for HTML format grids, including the html value of the format attribute and
the following attributes: bind, bindOnLoad, pageSize, preservePageOnSort, stripeRows, stripeRo
wColor.ColdFusion MX 7.01: Added support for the onBlur and onFocus events.ColdFusion MX 7:
Added the format attribute and support for Flash and XML output.
Added enabled, onChange, style, tooltip, and visible attributes (Flash format only).
ColdFusion MX: Changed the rowHeaderWidth attribute: ColdFusion does not use the rowHeaderWidth a
ttribute. You can omit it.
Attributes

Note
In XML format, ColdFusion passes all attributes to the XML. The supplied XSLT skins do not
handle or display XML format grids, but do display applet and Flash format grids.

Attribute

Req/Opt; formats

name

Required; all

© 2014 Adobe Systems Incorporated. All rights reserved.

Default

Description
Name of the grid control.

555

Adobe ColdFusion Documentation

align

Optional;applet

Alignment of the grid cell
contents:
Top
Left
Bottom
Baseline
Texttop
Absbottom
Middle
Absmiddle
Right

appendKey

Optional;HTML, applet

yes

yes: when used with hr
ef, appends "CFGRIDK
EY=" and information
about the selected
items. For details, see
the section Using the
href attribute.
no

autoWidth

Optional;HTML, applet

no

yes: sets column
widths so that all
columns display within
the grid width. Widths
are equal or the
proportions are
determined by the
relative cfgridcolumn
width attribute values.
Horizontal scroll bars
are not available.
no: sets columns to
equal widths or the
values specified in the c
fgridcolumn width a
ttributes.

© 2014 Adobe Systems Incorporated. All rights reserved.

556

Adobe ColdFusion Documentation

bgColor

Optional; all

Background color of the
control. For most formats,
can be a hexa-decimal
format or a named color.
For a hexadecimal value,
use the form "##xxxxxx
", where x = 0-9 or A-F;
use two number signs or
none. For a list of the
supported named colors,
see cfchart.
Limitations: for HTML
format, must be a valid
web color; for Flash
format, must be a
hexadecimal value.
Flash format only: to
specify background
colors for alternating
rows, separate the two
colors with a comma.

bind

Optional; HTML

© 2014 Adobe Systems Incorporated. All rights reserved.

A bind expression used to
fill the contents of the grid.
Cannot be used with the q
uery attribute. For more
information, see Binding
data to form fields in Usin
g Ajax Data and
Development Features in
the Developing
ColdFusion Applications.

557

Adobe ColdFusion Documentation

bindOnLoad

Optional; HTML

yes

yes: executes the bind
attribute expression
when first loading the
form.
no: does not execute
the bind attribute
expression until the first
bound event.
Ignored if there is no bi
nd attribute.
For more information,
see Using the
bindOnLoad attribute in
Using Ajax form
controls and features int
he Developing
ColdFusion Applications
.

bold

Optional; all

no

yes: displays text in
bold.
no

colHeaderAlign

Optional;applet

left

left: left-aligns the
column header text.
right: right-aligns the
column header text.
center: centers the
column header text.

colHeaderBold

Optional; all

no

yes: displays column
headers in bold.
no

colHeaderFont

Optional; all

Font of column header.

colHeaderFontSize

Optional; all

Size of column header
text, in points.

colHeaderItalic

Optional; all

no

yes: displays column
headers in italic.
no

colHeaders

Optional; Applet, Flash

yes

yes: displays column
headers.
no

© 2014 Adobe Systems Incorporated. All rights reserved.

558

Adobe ColdFusion Documentation

colHeaderTextColor

Optional; all

Color of column headers.
Options: same as for te
xtColor attribute.

collapsible

Optional; HTML

False

delete

Optional;HTML,applet

no

deleteButton

Optional;HTML, applet

Delete

Text for the Delete button;
takes effect only if selec
tmode="edit".

enabled

Optional;Flash

yes

Flash format only:
Boolean value that
specifies whether the
control is enabled. A
disabled control appears
in light gray.

font

Optional; all

Font of text.

fontSize

Optional; all

Size of text, in points.

© 2014 Adobe Systems Incorporated. All rights reserved.

A Boolean value
specifying whether the
user can collapse the
entire grid by clicking an
arrow on the title bar.
Specifying this attribute
adds a title bar to the grid.
yes: users can delete
row data from the grid;
takes effect only if sele
ctmode="edit".
no

559

Adobe ColdFusion Documentation

format

Optional; all

applet

applet: generates a
Java applet.
Flash: generates a
Flash grid control.
html: generates an
AJAX-based HTML grid
control that supports
data binding.
xml: generates an XML
representation of the
grid.
In XML format forms,
includes the generated
XML in the form.
In HTML format forms,
puts the XML in a string
variable with the name
specified by the name at
tribute.

gridDataAlign

Optional;applet

left

left: left-aligns data
within the column.
right: right-aligns data
within the column.
center: centers data
within the column.

gridLines

Optional; applet, Flash

yes

yes: enables row and
column rules.
no

© 2014 Adobe Systems Incorporated. All rights reserved.

560

Adobe ColdFusion Documentation

groupField

Optional; HTML

Don't group

Puts the grid rows into
groups, organized by the
column specified in this
attribute. Each group is
collapsible and has a
header with the column
name, group field value,
and number of entries in
the group.
If you set this option, the
column pull-down menu
shows two grouping
options: The show in
Groups option turns
column grouping on and
off. The Group By This
Field option sets the
grouping to use the
selected column. Users
display the pull-down
menu by moving the
mouse over a column
head and clicking the
down arrow that appears
You can use this attribute
with static grids only, do
not use it with dynamic
grids that get their data
using bind expressions.

height

Optional; all

300 (applet only)

Height of the control, in
pixels.
If you omit the attribute in
Flash format, the grid
sizes automatically.

highlightHref

Optional;applet

yes

href

Optional;HTML,. applet

© 2014 Adobe Systems Incorporated. All rights reserved.

yes: highlights links
associated with an hre
f attribute value.
no
URL or name of a query
column that contains
URLs to hyperlink each
grid cell with.

561

Adobe ColdFusion Documentation

hrefKey

Optional;HTML,. applet

A query column to use for
the value appended to the
href URL of each cell, if
appendKey="True". If
you use cfgridcolumn t
ags, the column must be
specified in one of these
tags.

hSpace

Optional;applet

Horizontal space to the
left and right of the
control, in pixels.

insert

Optional;applet, HTML

no

insertButton

Optional;applet

Insert

italic

Optional; all

no

maxRows

Optional; all

multirowselect

Optional; HTML

yes: users can insert
row data in the grid;
takes effect only if sele
ctmode="edit".
no
Text for the Insert button;
takes effect only if selec
tmode="edit".
yes: displays text in
italic.
no
Maximum number of rows
to display in the grid.

no

Allows selection of
multiple rows. This is
particularly useful in the
cases where batch
processing is required, for
example, moving multiple
records at a time.
If yes, a check box
appears as the first
column of the grid,
enabling selection of
multiple records. A Select
All/Deselect All option
also appears.
Note
If mul
tirow
selec
t="ye

© 2014 Adobe Systems Incorporated. All rights reserved.

562

Adobe ColdFusion Documentation

s",
then
row
data is
sent
as an
array
of
structs
as
oppos
ed to a
struct
if muti
rowse
lect=
"no".
Also, if
the
grid
data is
manip
ulated
by the
user,
for
examp
le,
using
JavaS
cript,
to
move
record
s when
a
button
is
clicked
, set
the
metho
d to
POST.
This is
require
d as a
GET
metho
d
impos
es
restrict

© 2014 Adobe Systems Incorporated. All rights reserved.

563

Adobe ColdFusion Documentation

ions
on the
amoun
t of
data

© 2014 Adobe Systems Incorporated. All rights reserved.

564

Adobe ColdFusion Documentation

that
can be
sent.

notSupported

Optional;applet

onBlur

Optional, Flash

ActionScript that runs
when the grid loses focus.

onChange

Optional;HTML, Flash

Flash format: ActionScrip
t to run when the control
changes due to user
action in the control.HTML
format: Required for
HTML format grids that
specify a bind attribute
and a selectMode value
of edit. A bind
expression that calls a
CFC method, JavaScript
function, or URL to update
the data source. If a URL
is called, since the data is
passed in JSON format to
the URL page, use the
function DeserializeJS
ON. The arguments cfgr
idrow and cfgridchan
ged must be serialized to
JSON strings if a
JavaScript bind is used to
pass these arguments to
a URL.

onError

Optional;HTML, applet

In HTML format grids,
name of a JavaScript
function to execute if an
error occurs.
In applet format grids,
name of a JavaScript
function to execute if
validation fails.

© 2014 Adobe Systems Incorporated. All rights reserved.

See Description

Text to display if the
browser does not support
Java or has Java support
disabled. Default: "
Browser must support
Java to view ColdFusion
Java Applets"

565

Adobe ColdFusion Documentation

onFocus

Optional,Flash

ActionScript that runs
when the grid gets focus.

onLoad

Optional

A custom JavaScript
function to execute when
the grid is loaded and
rendered.

onValidate

Optional;applet

A JavaScript function to
validate user input. The
form object, input object,
and input object value are
passed to the function,
which must return true if
validation succeeds; fals
e otherwise.

pageSize

Optional;HTML

10

The number of rows to
display per page for a
dynamic grid. If the
number of available rows
exceeds the page size,
the grid displays only the
specified number of
entries on a single page,
and the user navigates
between pages to show
all data. The grid retrieves
data for each page only
when it is required for
display.
This attribute is ignored if
you specify a query attrib
ute.

pictureBar

Optional;applet

no

yes: puts images (and
no text) on the Insert,
Delete, and Sort
buttons.
no: puts text (and no
images) on the Insert,
Delete, and Sort
buttons.

© 2014 Adobe Systems Incorporated. All rights reserved.

566

Adobe ColdFusion Documentation

preservePageOnSort

Optional; HTML

query

Optional; all

rowHeaderAlign

Optional;applet

left

left: left-aligns the
row header text.
right: right-aligns the
row header text.
center: centers the
row header text.

rowHeaderBold

Optional;applet

no

yes: displays row label
text in bold.
no

rowHeaderFont

Optional;applet

Font for the row labels.

rowHeaderFontSize

Optional;applet

Text size of the row
labels, in points.

rowHeaderItalic

Optional;applet

no

yes: displays row label
text in italic.
no

rowHeaders

Optional;applet

yes

yes: displays a column
of numeric row labels.
no

rowHeaderTextColor

Optional;applet

black

no

Specifies whether to
display the page with the
current page number, or
display page 1, after
sorting (or resorting) the
grid. If this attribute is yes
, selections are preserved
when the grid sorts.
Name of the query
associated with the
control. Cannot be used
with the bind attribute.

Text color of grid control
row headers.
Options: same as for
the textColor attribut
e.

rowHeight

Optional; Applet, Flash,
XML

© 2014 Adobe Systems Incorporated. All rights reserved.

Minimum row height, in
pixels. Used with cfgrid
column type = "Image"
; defines space for
graphics to display in row.

567

Adobe ColdFusion Documentation

selectColor

Optional; all

Background color for a
selected item.
Options: same as for te
xtColor attribute

selectMode

Optional; all

Applet format: Browse;HT
ML, Flash format: Row

Selection mode for items
in the control.
Edit: the user can edit
grid data. Selecting a
cell lets the user edit
the cell.
Row: user selections
automatically extend to
the row that contains
selected cell.
The following are used
in applet format only;
HTML and Flash
formats interpret these
as Row:
Single: user selections
are limited to the
selected cell.
Column: user selections
automatically extend to
the column that
contains selected cell.
Browse: the user can
only browse grid data.

selectOnLoad

Optional; HTML

© 2014 Adobe Systems Incorporated. All rights reserved.

yes

yes: selects the first
row of the grid when the
gird loads.
no: does not select any
rows when the grid
loads.

568

Adobe ColdFusion Documentation

sort

Optional;applet

no

Adds sort buttons to
perform simple text sorts
on a user-selected
column:
yes: put sort buttons on
the grid control.
no
Independent of this
setting, users can sort
columns by clicking the
column head. If select
Mode="browse", the
table cannot be sorted.

sortAscendingButton

Optional;applet

A > Z

Text for the Sort button.

sortDescendingButto
n

Optional;applet

Z > A

Text for the Sort button.

stripeRowColor

Optional; HTML

stripeRows

Optional; HTML

style

Optional;Flash

Must be a style
specification in CSS
format. Ignored for type=
"text".

target

Optional;HTML, applet

The target frame or
window in which to display
the href URL; for
example, "_blank".

© 2014 Adobe Systems Incorporated. All rights reserved.

The color to use for one of
the alternating stripes.
The bgColor setting
determines the other
color.
no

Boolean value that
indicates whether to make
the rows stripes in
alternating colors.

569

Adobe ColdFusion Documentation

textColor

OptionalFlash, applet

Color of text. Can be a
hexadecimal value or a
named color. For a
hexadecimal value, use
the form "##xxxxxx",
where x = 0-9 or A-F; use
two number signs or
none. For a list of the
supported named colors,
see cfchart.

title

Optional; HTML

Text to display as a title at
the top of the grid.
Specifying this attribute
adds a title bar to the grid.

tooltip

Optional;Flash

Flash format only: text to
display when the mouse
pointer hovers over the
control.

visible

Optional;Flash

vSpace

Optional;applet

width

Optional; all

yes

Flash format only:
Boolean value that
specifies whether to show
the control. Space that
would be occupied by an
invisible control is blank.
Vertical space above and
below the control, in
pixels.

300 (applet only)

Width of the control.
In Flash and applet
format, must be a number
of pixels. In HTML format,
can be in any valid CSS
measurement unit, and a
numeric-only value
specifies pixels.
If you omit the attribute in
Flash or HTML format; the
grid sizes automatically.

Usage

Most of the following paragraphs describe grid features that apply to all, or at least two, grid formats. For information
that is specific to Flash forms, see Creating Forms in Flash in the Developing ColdFusion Applications. For
information that is specific to HTML format grids, see Using HTML grids in the Developing ColdFusion Applications.
This tag must be in a cfform tag block. An applet format grid requires the client to download a Java applet. Also, if
the client does not have an up-to-date Java plug-in installed, the system might also have to download an updated

© 2014 Adobe Systems Incorporated. All rights reserved.

570

Adobe ColdFusion Documentation

Java plug-in to display an applet format grid. A Flash format grid generates a Flash control, and can be embedded in
an HTML format cfform tag. For this tag to work properly in either Flash or applet format, the browser must also be
JavaScript-enabled.
Note
If you specify Flash format for this tag in an HTML format form, and you do not specify height a
nd width attributes, Flash takes up more than the remaining visible area on the screen. If any
other output follows the grid, including any form controls, users must scroll to see it. Therefore, if
you follow a Flash grid in an HTML form with additional output, specify height and width value
s.

You can populate a cfgrid with data from a cfquery. If you do not specify any cfgridcolumn tags in the cfgri
d body, ColdFusion generates a grid with the following:
A column for each column in the query.
A default header for each column, created by replacing hyphen or underscore characters in the table column
name with spaces. The first character, and any character after a space, are changed to uppercase; all other
characters are lowercase.
This tag requires an end tag.
Note
Clicking the submit button while editing a grid cell occasionally causes the cell changes to
be lost. To ensure that changes are submitted properly, Adobe recommends that after
user updates data in a cell, they click another cell before submitting the form.

Returning cfgrid data to the action page

The following information applies to all cfgrid formats. Also, HTML format grids can dynamically get data by using
a bind expression. For more information, see Using HTML grids in the Developing ColdFusion Applications.
When a user submits a form, the cfgrid tag sends information about user actions by setting form variables in the
data submitted to the form's action page. Because the data can vary, depending on the tag's SelectMode attribute
value, the form variables that are returned also vary depending on this value. In general, the data returned falls into
one of these categories:
Simple data, returned from simple select operations
Complex data, returned from insert, update, and delete operations
Simple selection data (SelectMode = Single, Column, or Row)

The data that form variables return to the cfform's action page contains information about which cells the user
selected. In general, ColdFusion makes this data available in the action page, as ColdFusion variables in the Form
scope, with the naming convention form.#GridName#.#ColumnName#.}}Each {{SelectMode returns these
form variables:

© 2014 Adobe Systems Incorporated. All rights reserved.

571

Adobe ColdFusion Documentation

SelectMode="single"
form.#GridName#.#ColumnName# = "SelectedCellValue"
SelectMode="column"
form.#GridName#.#ColumnName# = "ValueOfCellRow1,
ValueOfCellRow2, ValueOfCellRowN"
SelectMode="row"
form.#GridName#.#Column1Name# = "ValueOfCellInSelectedRow"
form.#GridName#.#Column2Name# = "ValueOfCellInSelectedRow"
form.#GridName#.#ColumnNName# = "ValueOfCellInSelectedRow"

Complex update data (SelectMode = Edit)

The grid returns a large amount of data, to inform the action page of inserts, updates, or deletes that the user made
to the grid. In most cases, you can use the cfgridupdate tag to automatically gather the data from the form
variables; the tag collects data, writes SQL calls, and updates the data source. If you cannot use cfgridupdate (if,
for example, you must distribute the returned data to more than one data source), write code to read form variables.
In this mode, ColdFusion creates the following array variables in the Form scope for each cfgrid:

form.#GridName#.#ColumnName#
form.#GridName#.original.#ColumnName#
form.#GridName#.RowStatus.Action

Each table row that contains an update, insert, or deletion has a parallel entry in each of these arrays. To view all
the information for all the changes, you can traverse the arrays, as in this example. To make it work with a cfgrid
on a submitted cfform, set the GridName variable to the name of the grid and the ColNameList to a list of the grid
columns.

© 2014 Adobe Systems Incorporated. All rights reserved.

572

Adobe ColdFusion Documentation




form.#GridName#.#ColName#:





The form variable is not an array!




Result Array Size is #size#.

Contents:



The array is empty.









Loop Index
Action
Old Value
New Value


#LoopCount#
#Val_Action#
#Val_Orig#
#Val_New#







form.#GridName#.#ColName#: NotSet!




Using the href attribute

When specifying a URL with grid items using the href attribute, the selectMode attribute value determines
whether the appended key value is limited to one grid item or extends to a grid column or row. When a user clicks a
linked grid item, a cfgridkey variable is appended to the URL, in this form:

© 2014 Adobe Systems Incorporated. All rights reserved.

573

Adobe ColdFusion Documentation

http://myserver.com?cfgridkey=selection

If the appendKey attribute is set to no, no grid values are appended to the URL. The value of selection is
determined by the value of the selectMode and attribute:
If you specify a hrefKey attribute, selection is the field value of the column specified by the attribute.
Otherwise, it is one of the following:
If selectMode="Single", selection is the value of the column clicked.
If selectMode="Row", selection is a comma-delimited list of column values in the clicked row, beginning
with the value of the first cell in the row.
If selectMode="Column", selection is a comma-delimited list of row values in the clicked column,
beginning with the value of the first cell in the column.
When you use an href attribute, you can also specify a target attribute with any of the standard HTML
target specifiers, _blank, _parent, _self, and _top, or with a specific frame name.
Enhancements made in ColdFusion 9.0.1

In ColdFusion 9, data for the first row is available on form submission in a form with dynamic grid. In
ColdFusion 9.0.1, the data is not available.
If the type is Boolean and selectmode is browse, or select=false, the column is shown as a check box
where click does not take effect.
Example

The following example creates a Flash form that displays a set of available courses from the CourseList table in the
cfdocexamples database. For more complex examples that use the cfgrid tag, see cfgridcolumn, cfgridrow,
and cfgridupdate.



SELECT Course_ID, Dept_ID, CorNumber,
CorName, CorLevel
FROM CourseList
ORDER by Dept_ID ASC, CorNumber ASC

cfgrid Example
Currently available courses






© 2014 Adobe Systems Incorporated. All rights reserved.

574

Adobe ColdFusion Documentation

cfgridcolumn
Description

Used with the cfgrid tag in a cfform. Formats a column and optionally populates the column from a query. The f
ont and alignment attributes used in cfgridcolumn override global font or alignment settings defined in cfgri
d.
Category

Forms tags
Syntax



Note
You can specify this tag's attributes in an attributeCollection attribute whose value is a
structure. Specify the structure name in the attributeCollection attribute and use the tag's
attribute names as structure keys.

See also

© 2014 Adobe Systems Incorporated. All rights reserved.

575

Adobe ColdFusion Documentation

cfgrid, cfgridrow, cfgridupdate, cfform, cfapplet, cfinput, cfselect, cfslider, cftextarea, cft
ree
History

ColdFusion 9.0.1: Added the attributes autoExpand and headerMenu supported only in HTML grids.
ColdFusion 9: Added boolean, date, numeric, and string_noCase to the type attribute values supported in
HTML grids.
ColdFusion MX 7: Added the mask attribute, and the currency type attribute value.ColdFusion MX: Changed
behavior if select="no": a user cannot select and edit the cell data, regardless of the cfgrid selectmode attri
bute value. When clicked, the cell border (and, depending on the selectColor value, the cell background)
changes color, but the cell data cannot be edited.
Attributes

Note
In XML format, ColdFusion passes all attributes to the XML. The supplied XSLT skins do not
handle or display XML format grids, but do display applet and Flash format grids.

Attribute

Req/Opt; formats

Default

Description

autoExpand

Optional;HTML

yes for first column and n
o for remaining columns

On a particular column, it
lets you expand the
specified column. Setting
autoExpand="yes" for
multiple columns results in
error. Also, if the attribute
display is set to no,
then autoExpand cannot
be yes; else, it results in
error.

name

Required;all

Name of the grid column
element. If the grid uses a
query, this attribute must
be the name of the query
column that populates the
grid column.

bgColor

Optional;all

Color of background of
grid column.
Options: same as for
the textColor attribut
e.

bold

Optional;all

© 2014 Adobe Systems Incorporated. All rights reserved.

As specified by cfgrid

yes: displays grid
control text in bold.
no

576

Adobe ColdFusion Documentation

Optional;applet, Flash,
HTML

As specified by cfgrid

display

Optional;all

yes

font

Optional;all

As specified by cfgrid

Font of data in column.

fontSize

Optional;all

As specified by cfgrid

Size of text in column.

header

Optional;all

yes

Text for the column
header. Used only if the c
fgrid colHeaders attri
bute is yes. The default
value is yes.

headerAlign

Optional;applet

As specified by cfgrid

Column header text
alignment:

dataAlign

Column data alignment:
left
right
center
yes
no: hides the column.

left
right
center
headerBold

Optional;HTML, applet

As specified by cfgrid

headerFont

Optional;HTML, applet

As specified by cfgrid

Font for the column
header.

headerFontSize

Optional;HTML, applet

As specified by cfgrid

Size of text for the column
header, in pixels.

headerIcon

Optional

{{headerMenu}}Added in
ColdFusion 9.0.1

Optional;HTML

© 2014 Adobe Systems Incorporated. All rights reserved.

yes: displays header in
bold.
no

Location of an image file
to use as the icon for
header column of the grid.
no

Lets you turn on/off the
header menu of the grid
column.Header menu is
the drop-down list that
appears on grid header
columns on mouse hover.
The attribute is helpful
when you have images for
grid headers.

577

Adobe ColdFusion Documentation

headerItalic

Optional;HTML, applet

headerTextColor

Optional;HTML, applet

As specified by cfgrid

yes: displays column
header in italic.
no
Color of grid control
column header text.
Options: same as for
the textColor attribut
e.

href

Optional;HTML, applet

URL or query column
name that contains a URL
to hyperlink each grid
column with.

hrefKey

Optional;HTML, applet

The query column to use
for the value appended to
the href URL of each
column, instead of the
column's value.

italic

Optional;all

© 2014 Adobe Systems Incorporated. All rights reserved.

As specified by cfgrid

yes: displays grid
control text in italic.
no

578

Adobe ColdFusion Documentation

mask

Optional;Flash, HTML

A mask pattern that
controls the character
pattern that the form
displays or allows users to
input and sends to
ColdFusion.
For columns with the
currency type attribute,
the mask specifies the
currency symbol.
ColdFusion automatically
inserts the character
before the numeric value.
For columns with text or
numeric values, mask spe
cifies the format to display
or allow users to input, as
follows:
A = A-Za-z
X = A-Za-z0-9
9 = 0-9
? = Any character
All other characters =
ColdFusion inserts the
literal character.
If the column values are
dates or timestamps,
ColdFusion uses the
mask pattern to format
the selected date.
For details of the
date/time mask format,
see the section date/tim
e formats in mask
attribute.Masking
supports HTML grids.
The default format is m/
d/y, for example
05/06/75. where m is
month with leading
zeros, d is day with
leading zeros, and y is
two-digit representation
of year. For further
details, go to the
following URL:http://ww
w.extjs.com/deploy/dev/
docs/output/Date.html

© 2014 Adobe Systems Incorporated. All rights reserved.

579

Adobe ColdFusion Documentation

numberFormat

Optional;Applet

select

Optional;all

Format for displaying
numeric data in the grid.
See the following table of
numberFormat attribute
mask characters.
yes

Determines selection
behavior if the cfgrid se
lectmode attribute value
is column, edit, or sing
le; ignored for row or
browse values.
yes: users can select
the column or select or
edit cells in the column,
as specified by the sel
ectmode attribute.
no: users cannot select
the column or select or
edit cells in the column.

target

Optional;HTML, Applet

© 2014 Adobe Systems Incorporated. All rights reserved.

Frame or standard HTML
target in which to open
link specified in href.

580

Adobe ColdFusion Documentation

textColor

Optional;Applet, Flash,
HTML

Color of grid element text
in column as a
hexadecimal number or
text name.
To enter a hexadecimal
value, use the form "##xx
xxxx", where x = 0-9 or
A-F; use two number
signs or none. Limitations:
In HTML format, must
specify a valid HTML
color. In Applet format,
must be one of the
following:
Any color, in
hexadecimal format
Black
Red
Blue
Magenta
Cyan
Orange
Darkgray
Pink
Gray
White
Lightgray
Yellow

type

Optional;all

You can specify the
following values in all
formats:
boolean: column
displays as check box;
if cell is editable, user
can change the check
mark. In an onchange
event, for static and
dynamic grids, the data
that is passed is
converted to the format
in which the boolean
values are represented
in the database.
combobox: displays a
drop-down list with the
values you specify for
the attributes values
and valuedisplay as
options.

© 2014 Adobe Systems Incorporated. All rights reserved.

581

Adobe ColdFusion Documentation

numeric: user can sort
grid data numerically. In
HTML format, if the cell
is editable, the user can
enter numeric values
string_noCase: user
can sort grid data as
case-insensitive text. In
HTML format, if the cell
is editable, the user can
enter text values.
You can specify the
following value in applet
and Flash formats; it
does not work in HTML
format:
image: grid displays
the image specified by
the URL in the column.
If you use a relative
URL, the image must
be in the CFIDE\classes
directory or a
subdirectory. If the
image is larger than the
column cell, it is clipped
to fit. Flash images
must be JPEG files.
Applet images can be
JPEG or GIF files.
You can specify the
following value in applet
format; it does not work
in Flash or HTML
format.
image: you can use the
following built-in
ColdFusion image
names, in addition to
paths to image files, in
the column values: cd,
computer, document,
element, folder, floppy,
fixed, remote.
You can specify the
following value in Flash
format; it does not work
in applet or HTML
format:

© 2014 Adobe Systems Incorporated. All rights reserved.

582

Adobe ColdFusion Documentation

currency: formats the
column data as
currency, aligning it
around the decimal
point. If users sort the
grid by using this
column, it sorts
correctly for the
currency, Use the mask
attribute to specify a
currency symbol; the
default value is the
dollar sign ($).
You can specify the
following value in HTML
format; it does not work
in applet or Flash
format:
date: The column
contains date values. If
the grid selectMode at
tribute value is edit,
the cell is editable.
When you click an
editable cell, an icon
appears that you can
click to open a date
picker and select a
date.
values

Optional;HTML, applet

Formats cells in column
as drop-down list boxes;
specify items in
drop-down list, for
example:

{{values =
"arthur,
scott,
charles,
1-20,
mabel"}}

valuesDelimiter

Optional;HTML, applet

© 2014 Adobe Systems Incorporated. All rights reserved.

, (comma)

Delimiter in values and v
aluesDisplay attributes
.

583

Adobe ColdFusion Documentation

valuesDisplay

Optional;HTML, applet

width

Optional;all

Maps elements in the val
ues attribute to string to
display in the drop-down
list. Delimited strings
and/or numeric ranges.
Column head width

Column width, in pixels.

The following matrix describes the behavior of type="boolean".
Before

After

Y

N

T

F

1

0

true (for static grids)

false (for static grids)

true (for dynamic grids)

NO (for dynamic grids)

For non-boolean or null

Y

In applet format only, you can use the following numberFormat attribute mask characters to format output in U.S.
numeric and currency styles. For more information on using these mask characters, see NumberFormat. (The cfgr
idcolumn tag does not support international number formatting.)
Character

Meaning

_

(Underscore) Digit placeholder.

9

Digit placeholder.

.

(Period) Location of mandatory decimal point.

0

Located to left or right of mandatory decimal point;
pads with zeros.

()

Puts parentheses around mask if number is less than
0.

+

Puts plus sign before positive numbers, minus sign
before negative numbers.

-

Puts space before positive numbers, minus sign before
negative numbers.

© 2014 Adobe Systems Incorporated. All rights reserved.

584

Adobe ColdFusion Documentation

,

(Comma) Separates every third decimal-place with a
comma.

L,C

Left-justify or center-justify number within width of mask
column. First character of mask must be L or C.
Default: right-justified.

$

Puts dollar sign before formatted number. Must be the
first character of mask.

^

(Caret) Separates left from right formatting.

date/time formats in mask attribute

By default, Flash displays date/time values in grid columns with a format that shows values such as Oct 29 2004
11:03:21. Use the mask attribute to display the date or time in a different format, as described in the following table:
Pattern letter

Description

Y

Year. If the number of pattern letters is two, the year is
truncated to two digits; otherwise, it appears as four
digits. The year can be zero-padded, as the third
example shows in the following set of examples:
Examples:YY = 03YYYY = 2003YYYYY = 02003

M

Month in year. The format depends on the following
criteria:
If the number of pattern letters is one, the format is
interpreted as numeric in one or two digits.
If the number of pattern letters is two, the format is
interpreted as numeric in two digits.
If the number of pattern letters is three, the format is
interpreted as short text.
If the number of pattern letters is four, the format is
interpreted as full text.
Examples:M = 7MM= 07MMM=JulMMMM= July

D

© 2014 Adobe Systems Incorporated. All rights reserved.

Day in month. Examples:D=4DD=04DD=10

585

Adobe ColdFusion Documentation

E

Day in week. The format depends on the following
criteria:
If the number of pattern letters is one, the format is
interpreted as numeric in one or two digits.
If the number of pattern letters is two, the format is
interpreted as numeric in two digits.
If the number of pattern letters is three, the format is
interpreted as short text.
If the number of pattern letters is four, the format is
interpreted as full text.
Examples:E = 1EE = 01EEE = MonEEEE = Monday

A

AM/PM indicator.

J

Hour in day (0-23).

H

Hour in day (1-24).

K

Hour in am/pm (0-11).

L

Hour in am/pm (1-12).

N

Minute in hour. Examples:N = 3NN = 03

S

Second in minute.

Other text

You can add other text into the pattern string to further
format the string. You can use punctuation, numbers,
and all lowercase letters. Avoid upper case letters
because they may be interpreted as pattern
letters.Example:EEEE, MMM. D, YYYY at H:NN A =
Tuesday, Sept. 8, 2003 at 1:26 PM

Example

The following example lets you update certain fields of the CourseList table in the cfdocexamples database. It uses
cfgridcolumn tags to structure the table.

© 2014 Adobe Systems Incorporated. All rights reserved.

586

Adobe ColdFusion Documentation







SELECT Course_ID, Dept_ID, CorNumber,CorName, CorLevel, CorDesc
FROM CourseList
ORDER by Dept_ID ASC, CorNumber ASC






cfgrid Example
You can update the Name, Level, and Description information for courses.




















© 2014 Adobe Systems Incorporated. All rights reserved.

587

Adobe ColdFusion Documentation

cfgridrow
Description

Lets you define a cfgrid control that does not use a query as source for row data. If a query attribute is specified in
the cfgrid tag, the cfgridrow tags are ignored.
Category

Forms tags
Syntax



Note
You can specify this tag's attributes in an attributeCollection attribute whose value is a
structure. Specify the structure name in the attributeCollection attribute and use the tag's
attribute names as structure keys.

See also

cfgrid, cfgridcolumn, cfgridupdate, cfform, cfinput, cfselect, cfslider, cftextarea, cftree
Attributes

Attribute

Req/Opt

data

Required

delimiter

Optional

Default

Description
Delimited list of column
values. If a value contains
a delimiter character, it
must be escaped with
another delimiter
character.

, (comma)

Separator between
column values.

Example

The following example shows how you use the cfgridrow tag can populate a cfgrid tag from list data:

© 2014 Adobe Systems Incorporated. All rights reserved.

588

Adobe ColdFusion Documentation

















© 2014 Adobe Systems Incorporated. All rights reserved.

589

Adobe ColdFusion Documentation

cfgridupdate
Description

Used with a cfgrid tag. Updates data sources directly from edited grid data. This tag provides a direct interface
with your data source.
This tag applies delete row actions first, then insert row actions, then update row actions. If it encounters an
error, it stops processing rows.
Category

Forms tags
Syntax


password = "data source password"
tableOwner = "table owner"
tableQualifier = "qualifier"
username = "data source user name">

Note
You can specify this tag's attributes in an attributeCollection attribute whose value is a
structure. Specify the structure name in the attributeCollection attribute and use the tag's
attribute names as structure keys.

See also

cfgrid, cfgridcolumn, cfgridrow, cfform, cfapplet, cfinput, cfselect, cfslider, cftextinput, cf
tree
History

ColdFusion 10: Added the clientInfo attribute.ColdFusion MX: Deprecated the connectString, dbName, dbSe
rver, dbtype, provider, and providerDSN attributes. They do not work, and might cause an error, in releases
later than ColdFusion 5.
Attributes

Attribute

Req/Opt

clientInfo

Optional

© 2014 Adobe Systems Incorporated. All rights reserved.

Default

Description
Structure containing
properties of the client to
be set on the database
connection.

590

Adobe ColdFusion Documentation

grid

Required

Name of the cfgrid form
element that is the source
for the update action.

dataSource

Required

Name of the data source
for the update action.

tableName

Required

Name of the table to
update.
For ORACLE drivers,
entry must be upper-case.
For Sybase driver, entry is
case sensitive; must be
same case as used when
table was created.

keyOnly

no

Applies to the update act
ion:
yes: the WHERE
criteria are limited to the
key values.
no: the WHERE criteria
include key values and
the original values of
changed fields.

password

Optional

Overrides password valu
e specified in ODBC
setup.

tableOwner

Optional

Table owner, if supported.

tableQualifier

Optional

Table qualifier, if
supported. Purpose:
SQL Server and Oracle
driver: name of
database that contains
the table.
Intersolv dBASE driver:
directory of DBF files.

username

Optional

Overrides username valu
e specified in ODBC
setup.

Example

The following example lets you update a database by using a cfgrid tag to add and delete entire records or to
update the data in individual cells. The cfgridupdate tag processes the data from the submitted form and

© 2014 Adobe Systems Incorporated. All rights reserved.

591

Adobe ColdFusion Documentation

updates the database.







SELECT Course_ID, Dept_ID, CorNumber, CorName, CorLevel, CorDesc
FROM CourseList
ORDER by Dept_ID ASC, CorNumber ASC

cfgrid Example
Try adding a course to the database, and then deleting it.





...

© 2014 Adobe Systems Incorporated. All rights reserved.

592

Adobe ColdFusion Documentation

cfheader
Description

Generates custom HTTP response headers to return to the client.
Category

Data output tags, Page processing tags
Syntax


OR


Note
You can specify this tag's attributes in an attributeCollection attribute whose value is a
structure. Specify the structure name in the attributeCollection attribute and use the tag's
attribute names as structure keys.

See also

cfcache, cfflush, cfhtmlhead, cfinclude, cfsetting, cfsilent, cfcontent
History

ColdFusion MX 6.1: Changed behavior for the name attribute: cfheader name="Content-Disposition" uses the
default file character encoding to encode this header's value, so the name of a file can include characters in the
character encoding used in the file.
Attributes

Attribute

Req/Opt

© 2014 Adobe Systems Incorporated. All rights reserved.

Default

Description

593

Adobe ColdFusion Documentation

charset

Optional

UTF-8

The character encoding in
which to encode the
header value. The
following list includes
commonly used values:
utf-8
iso-8859-1
windows-1252
us-ascii
shift_jis
iso-2022-jp
euc-jp
euc-kr
big5
euc-cn
utf-16
For more information
about character
encodings, see www.w3
.org/International/O-cha
rset.html.

name

Required if statusCode
not specified

Header name.

statusCode

Required if name not
specified

Number. HTTP status
code.

statusText

Optional

Explains the status code.

value

Optional

HTTP header value.

Usage

If you use this tag after the cfflush tag on a page, an error is thrown.
Example

cfheader Example
cfheader generates custom HTTP response headers to return to the client.
This example forces browser client to purge its cache of requested file.


© 2014 Adobe Systems Incorporated. All rights reserved.

594

Adobe ColdFusion Documentation

cfhtmlhead
Description

Writes text to the head section of a generated HTML page.
Category

Page processing tags
Syntax



Note
You can specify this tag's attributes in an attributeCollection attribute whose value is a
structure. Specify the structure name in the attributeCollection attribute and use the tag's
attribute names as structure keys.

See also

cfcache, cfflush, cfheader, cfinclude, cfsetting, cfsilent
Attributes

Attribute

Req/Opt

text

Required

Default

Description
Text to add to the 
area of an HTML page.

Usage

Use this tag for embedding JavaScript code, or putting other HTML tags, such as meta, link, title, or base in
an HTML page header. If you use this tag after the cfflush tag on a page, an error is thrown.
Example




© 2014 Adobe Systems Incorporated. All rights reserved.

595

Adobe ColdFusion Documentation

cfhtmltopdf
 creates high quality PDF output from a text block containing CFML and HTML using the PDF Service
Manager.
The WebKit implementation for  is referred as PDFG (acronym of PDF Generator) which is shipped as
part of the Jetty installer. The component running inside the Jetty server is referred as the service manager, which
takes request for PDF conversion from one or many ColdFusion server/s. (In Windows, the service runs as the
ColdFusion 11 Add-on service, which processes both Solr and PDFG requests.)
The WebKit implementation for :
Encapsulates the PDF conversion library.
Performs HTML to PDF conversion in process.

When you generate a PDF using HTML or CFML, you have to ensure that XSS vulnerabilities cannot be exploited.
Hence, you must take relevant measures to protect your system against such vulnerabilities. Also, note that
ColdFusion provides encoding functions for XSS protection. See the following functions:
EncodeForHTML
Canonicalize
Category

Data output tags
See Also

cfhtmltopdfitem
Syntax

© 2014 Adobe Systems Incorporated. All rights reserved.

596

Adobe ColdFusion Documentation



Attributes

Attribute

Req/Opt

Default

Description

encryption

Optional

none

AES_128
RC4_40
RC4_128
RC4_128M
None

destination

Optional

© 2014 Adobe Systems Incorporated. All rights reserved.

Pathname of a file to
contain the PDF output. If
you omit the destinati
on attribute, ColdFusion
displays the output in the
browser.

597

Adobe ColdFusion Documentation

marginBottom

Optional

Bottom margin in inches
(default) or centimeters.
To specify the bottom
margin in centimeters,
include the unit=cm attri
bute.

marginLeft

Optional

Left margin in inches
(default) or centimeters.
To specify the left margin
in centimeters, include the
unit=cm attribute.

marginRight

Optional

Right margin in inches
(default) or centimeters.
To specify the right
margin in centimeters,
include the unit=cm attri
bute.

marginTop

Optional

Top margin in inches
(default) or centimeters.
To specify the top margin
in centimeters, include the
unit=cm attribute.

name

Optional

Name of an existing
variable into which the tag
stores the PDF.

orientation

Optional

portrait

Page orientation:
portrait
landscape

overwrite

Optional

ownerPassword

Optional

© 2014 Adobe Systems Incorporated. All rights reserved.

no

Specifies whether
ColdFusion overwrites an
existing file. Used in
conjunction with the dest
ination attribute.
Specifies the owner
password. Cannot be
same as userPassword.

598

Adobe ColdFusion Documentation

pageHeight

Optional

pageType

Optional

Page height in inches
(default) or centimeters.
This attribute is only valid
if pagetype=custom. To
specify page height in
centimeters, include the u
nit=cm attribute.
letter

Page type into which
ColdFusion generates the
report:

legal: 8.5 inches x 14
inches.
letter: 8.5 inches x 11
inches.
A4: 8.27 inches x 11.69
inches.
A5: 5.81 inches x 8.25
inches.
B4: 9.88 inches x 13.88
inches.
B5: 7 inches x 9.88
inches.
B4-JIS: 10.13 inches x
14.31 inches.
B5-JIS: 7.19 inches x
10.13 inches.
custom: custom height
and width.
If you specify custom, also
specify the pageHeight
and pageWidth attribute
s, can optionally specify m
argin attributes and
whether the units are
inches or centimeters.

© 2014 Adobe Systems Incorporated. All rights reserved.

599

Adobe ColdFusion Documentation

pageWidth

Optional

Page width in inches
(default) or centimeters.
This attribute is only valid
if pageType=custom. To
specify page width in
centimeters, include the u
nit=cm attribute.

permissions

Optional

(format="PDF" only)
Sets one or more of the
following permissions:
AllowPrinting
AllowModifyContents
AllowCopy
AllowModifyAnnotati
ons
AllowFillIn
AllowScreenReaders
AllowAssembly
AllowDegradedPrinti
ng
AllowSecure
All
None
Separate multiple
permissions with commas.

saveAsName

Optional

unit

Optional

The filename that appears
in the SaveAs dialog
when a user saves a PDF
file written to the browser.
in

Default unit for the pageH
eight, pageWidth, and
margin attributes:
in: inches.
cm: centimeters.

© 2014 Adobe Systems Incorporated. All rights reserved.

600

Adobe ColdFusion Documentation

userPassword

Optional

Specifies a user
password. Cannot be
same as ownerPasswor
d.

Note:  is added to support adding header/footer/pagebreak in the generated PDF. See The new
 tag.

Examples

The following example shows the most basic usage of , to create a PDF from CFML code, returning a
PDF for display:


This is a test #now()#


The following example shows the most basic usage of , to create a PDF from content returned from a
URL, returning a PDF for display:



The following example shows using options to control height, width, and save the content to a file instead of for
display. The file is saved (by default) into the same directory as the template containing the code:



The following example shows how you can set margins, and also adds code to display the resulting file to the user
using CFContent:

© 2014 Adobe Systems Incorporated. All rights reserved.

601

Adobe ColdFusion Documentation




The following example shows how you can protect the PDF, requiring the user to enter a password to open the file:



© 2014 Adobe Systems Incorporated. All rights reserved.

602

Adobe ColdFusion Documentation

cfhtmltopdfitem
 specifies the action items for a PDF document created by the < cfhtmltopdf> tag. The type
attribute takes the following values:
header
footer
pagebreak
Category

Data output tags
Syntax



Attributes
Attribute

Req/Opt

© 2014 Adobe Systems Incorporated. All rights reserved.

Default

Description

603

Adobe ColdFusion Documentation

type

Required

none

Specifies the action:
header: uses the
text/image specified
between the
 and
 tags
as the running header.
footer: uses the
text/image between the
 and
 tags
as the the running
footer.
pagebreak: can be used
to insert a pagebreak in
the generated PDF.
When  is
used as a service,
pagebreak will not work.
Note:
When
the
type is
"heade
r", the
margin
bottom
attribut
e will
not be
suppor
ted.
Similar
ly,
when
type is
"footer
", the
margin
top attr
ibute
will not
be
suppor
ted.

isBase64

Optional

© 2014 Adobe Systems Incorporated. All rights reserved.

Yes/No. Use this only
when the image attribute
is given a base64 image
string.

604

Adobe ColdFusion Documentation

showonprint

Optional

align

Optional

Center

Alignment of the text. Left,
Right, or Center.

marginleft

Optional

1.0

Left margin in inches
(default) or centimeters.
To specify the left margin
in centimeters, include the
unit=cm attribute.

marginright

Optional

1.0

Right margin in inches
(default) or centimeters.
To specify the left margin
in centimeters, include the
unit=cm attribute.

margintop

Optional

0.5

Top margin in inches
(default) or centimeters.
To specify the left margin
in centimeters, include the
unit=cm attribute.

marginbottom

Optional

0.5

Bottom margin in inches
(default) or centimeters.
To specify the bottom
margin in centimeters,
include the unit=cm attri
bute.

opacity

Optional

10

Opacity of the
header/footer. Specify a
valid number. A number
between 1 and 10.

numberformat

Optional

Numeric

The page number format
to be used.
LOWERCASEROMAN|N
UMERIC|UPPERCASER
OMAN

© 2014 Adobe Systems Incorporated. All rights reserved.

Show or hide
header/footer when the
document is printed.

605

Adobe ColdFusion Documentation

image

Optional

The image file name or
object to be used as
header or footer.
The following parameters
are supported:
A path to the image file
A Base-64 string
A byte array
A  object

Examples



Page: _PAGENUMBER of _LASTPAGENUMBER






You can access the following scope variables in  content:
_PAGENUMBER – Add current page number.
_LASTPAGENUMBER – Add last page number.

© 2014 Adobe Systems Incorporated. All rights reserved.

606

Adobe ColdFusion Documentation

cfhttp
Description

Generates an HTTP request and handles the response from the server.
Category

Internet protocol tags
Syntax


cfhttpparam tags [optional for some methods]


Note
You can specify this tag's attributes in an attributeCollection attribute whose value is a
structure. Specify the structure name in the attributeCollection attribute and use the tag's
attribute names as structure keys.

See also

© 2014 Adobe Systems Incorporated. All rights reserved.

607

Adobe ColdFusion Documentation

cfhttpparam, GetHttpRequestData, cfftp, cfldap, cfmail, cfpop
History

ColdFusion 11: Added support for NTLM authentication. Three attributes added - authType, domain, and
workstation. Also, this tag supports SNI (server name indication) only if ColdFusion is running on an Oracle 1.7+
JVM.
ColdFusion 8: Added the clientCert and clientCertPassword attributes.
ColdFusion MX 7.01: Added the "never" value of the getAsBinary attribute.
ColdFusion MX 7: Added the result attribute.
ColdFusion MX 6.1:
Added support for the following methods: HEAD, PUT, DELETE, OPTIONS, TRACE.
Added multipart, getAsBinary, proxyUser, and proxyPassword attributes.
Changed httpparam behavior: all operations can have httpparam tags.
Added the cfhttp.errorDetail return variable.
Modified response body content types considered to be text.
Changed behavior for multiple headers: multiple headers of the same type are returned in an array.
Added support for HTTPS proxy tunneling.
Fixed bugs in code and documentation.
ColdFusion MX:
Added the charset and firstrowasheaders attributes.
Changed Secure Sockets Layer (SSL) support: ColdFusion uses the Sun JSSE library, which supports
128-bit encryption, to support SSL.
Attributes

The following attributes control the HTTP transaction and can be used for all HTTP methods:
Attribute

Req/Opt

© 2014 Adobe Systems Incorporated. All rights reserved.

Default

Description

608

Adobe ColdFusion Documentation

url

Required

Uses the http protocol

Address of the resource
on the server that handles
the request. The URL
must include the
hostname or IP address.
If you do not specify the
transaction protocol
(http:// or
https://
), ColdFusion uses the
default protocol, http.
If you specify a port
number in this attribute, it
overrides any port attribu
te value.
The cfhttpparam tag U
RL attribute appends
query string
attribute-value pairs to the
URL.

charset

Optional

For request: UTF-8 For
response: charset speci
fied by response ContentType header, or UTF-8 if
response does not specify
charset.

The character encoding of
the request, including the
URL query string and form
or file data, and the
response. The following
list includes commonly
used values:
utf-8
iso-8859-1
windows-1252
us-ascii
shift_jis
iso-2022-jp
euc-jp
euc-kr
big5
euc-cn
utf-16
For more information
character encodings,
see www.w3.org/Intern
ational/O-charset.html.

clientCert

Optional

© 2014 Adobe Systems Incorporated. All rights reserved.

The full path to a PKCS12
format file that contains
the client certificate for the
request.

609

Adobe ColdFusion Documentation

clientCertPassword

Optional

Password used to decrypt
the client certificate.

compression

Optional

The target webserver's
compression status. The
only supported value is
none. If the target website
runs on IIS with HTTP
compression enabled, use
this attribute to avoid a
connection failure while
performing GET or POST
operations.

© 2014 Adobe Systems Incorporated. All rights reserved.

610

Adobe ColdFusion Documentation

getAsBinary

Optional

no

method

Optional

GET

© 2014 Adobe Systems Incorporated. All rights reserved.

no: if ColdFusion does
not recognize the
response body type as
text, converts it to a
ColdFusion object.
auto: if ColdFusion
does not recognize the
response body type as
text, converts it to
ColdFusion Binary type
data.
yes: always converts
the response body
content into ColdFusion
Binary type data, even if
ColdFusion recognizes
the response body type
as text.
never: prevents the
automatic conversion of
certain MIME types to
the ColdFusion Binary
type data; treats the
returned content as
text.
ColdFusion recognizes
the response body as
text if:
the header does not
specify a content type.
the content type starts
with "text".
the content type starts
with "message".
the content type is
"application/octet-strea
m".
If ColdFusion does not
recognize the body as
text and converts it to
an object, but the body
consists of text, the cfo
utput tag can display
it. The cfoutput tag
cannot display Binary
type data. (To convert
binary data to text, use
the ToString function.
)

611

Adobe ColdFusion Documentation

GET: requests
information from the
server. Any data that
the server requires to
identify the requested
information must be in
the URL or in cfhttp t
ype="URL" tags.
POST: sends
information to the
server for processing.
Requires one or more c
fhttpparam tags.
Often used for
submitting form-like
data.
PUT: requests the
server to store the
message body at the
specified URL. Use this
method to send files to
the server.
DELETE: requests the
server to delete the
specified URL.
HEAD: identical to the G
ET method, but the
server does not send a
message body in the
response. Use this
method for testing
hypertext links for
validity and
accessibility,
determining the type or
modification time of a
document, or
determining the type of
server.

© 2014 Adobe Systems Incorporated. All rights reserved.

612

Adobe ColdFusion Documentation

TRACE: requests that
the server echo the
received HTTP headers
back to the sender in
the response body.
Trace requests cannot
have bodies. This
method enables the
ColdFusion application
to see what is being
received at the server,
and use that data for
testing or diagnostic
information.
OPTIONS: a request for
information about the
communication options
available for the server
or the specified URL.
This method enables
the ColdFusion
application to determine
the options and
requirements
associated with a URL,
or the capabilities of a
server, without
requesting any
additional activity by the
server.
password

Optional

port

Optional

© 2014 Adobe Systems Incorporated. All rights reserved.

Use to pass a password
to the target URL for
Basic Authentication.
Combined with username
to form a base64 encoded
string that is passed in the
Authenticate header.
Does not provide support
for Integrated Windows,
NTLM, or Kerebos
authentication.
80 for http443 for https

Port number on the server
to which to send the
request. A port value in
the url attribute overrides
this value.

613

Adobe ColdFusion Documentation

proxyServer

Optional

Host name or IP address
of a proxy server to which
to send the request.

proxyPort

Optional

proxyUser

Optional

User name to provide to
the proxy server.

proxyPassword

Optional

Password to provide to
the proxy server.

redirect

Optional

80

yes

Port number to use on the
proxy server.

If the response header
includes a Location field
AND ColdFusion receives
a 300-series (redirection)
status code, specifies
whether to redirect
execution to the URL
specified in the field:
yes: redirects execution
to the specified page.
no: stops execution and
returns the response
information in the cfht
tp variable, or throws
an error if the throwOn
Error attribute is True.
The cfhttp.respons
eHeader.Location v
ariable contains the
redirection path.
ColdFusion follows a
maximum of four
redirects on a request.
If there are more,
ColdFusion functions as
if redirect = "no".
Note: The cflocatio
n tag generates an
HTTP 302 response
with the url attribute as
the Location header
value.

© 2014 Adobe Systems Incorporated. All rights reserved.

614

Adobe ColdFusion Documentation

resolveURL

Optional

result

Optional

© 2014 Adobe Systems Incorporated. All rights reserved.

no

no: does not resolve
URLs in the response
body. As a result, any
relative URL links in the
response body do not
work.
yes: resolves URLs in
the response body to
absolute URLs,
including the port
number, so that links in
a retrieved page remain
functional. Applies to
these HTML tags:
img
src
a href
form action
applet code
script src
embed src
embed pluginspace
body background
frame src
bgsound src
object data
object classid
object codebase
object usemap
Does not resolve URLs
if the file and path at
tributes are used.
Lets you specify an
alternate variable in which
to receive a result.

615

Adobe ColdFusion Documentation

throwOnError

Optional

timeout

Optional

© 2014 Adobe Systems Incorporated. All rights reserved.

no

yes: if the server
returns an error
response code, throws
an exception that can
be caught using the cf
try and cfcatch or
ColdFusion error pages.
no: does not throw an
exception if an error
response is returned. In
this case, your
application can use the
cfhttp.StatusCode
variable to determine if
there was an error and
its cause.
Value, in seconds, that is
the maximum time the
request can take. If the
time-out passes without a
response, ColdFusion
considers the request to
have failed. If the client
specifies a time-out in the
URL search parameter
(for example,
?RequestTime=120)
ColdFusion uses the
lesser of the URL time-out
and the timeout attribute
value; this ensures that
the request times out
before, or at the same
time as, the page.
If the URL does not
specify a time-out,
ColdFusion uses the
lesser of the Administrator
time-out and the timeout
attribute value.
If the time-out is not set in
any of these, ColdFusion
waits indefinitely for the c
fhttp request to
process.

616

Adobe ColdFusion Documentation

userAgent

Optional

username

Optional

authType

Optional

ColdFusion

Text to put in the user
agent request header.
Used to identify the
request client software.
Can make the ColdFusion
application appear to be a
browser.
Use to pass a user name
to the target URL for
Basic Authentication.
Combined with password
to form a base64 encoded
string that is passed in the
Authenticate header.
Does not provide support
for Integrated Windows,
NTLM, or Kerberos
authentication.

BASIC

The supported values are:
BASIC
NTLM
Note: For NTLM, to work,
the redirect attribute must
be set to false.

domain

Optional

The domain name for
authentication. (Use for
NTLM-based
authentication)

workstation

Optional

The workstation name for
authentication. (Use for
NTLM-based
authentication)

The following attribute is used with the PUT method to determine how to send data specified with httpparam
type="formField":
Attribute

Req/Opt

© 2014 Adobe Systems Incorporated. All rights reserved.

Default

Description

617

Adobe ColdFusion Documentation

multipart

Optional

no (Sends as multipart
only if request includes
File type data.)

Tells ColdFusion to send
all data specified by cfht
tpparam
type="formField" tag
s as multipart form data,
with a Content-Type of
multipart/form-data. By
default, ColdFusion sends
cfhttp requests that
contain only formField
data with a Content Type
of
application/x-www-form-ur
lencoded. (If the request
also includes File type
data, ColdFusion uses the
multipart/form-data
content type for all parts.)
If yes, ColdFusion also
sends the request's
charset in each
Content-Type description.
All form field data must be
encoded in this character
encoding, and ColdFusion
does not URLEncode the
data. (The field name
must be in ISO-88591-1
or ASCII.) Some http
parsers, including the one
used by previous versions
of ColdFusion, ignore the
multipart form field
character encoding
description.

The following attribute sets a multipart header field and is used, for example, for uploading videos on YouTube.
Attribute

Req/Opt

Default

Description

multipartType

Optional

form-data

Allows you to set the
multipart header field to r
elated or form-data.
By default, the value is fo
rm-data.

Example:




© 2014 Adobe Systems Incorporated. All rights reserved.

618

Adobe ColdFusion Documentation

























WithOutQuotes
Test Description
People

yourvideo


















© 2014 Adobe Systems Incorporated. All rights reserved.

619

Adobe ColdFusion Documentation




The following attribute allows you to specify the name of the variable in which you would like the results of the
operation returned. The name you specify replaces cfhttp as the prefix by which you access the returned
variables. For example, if you set the result attribute to myResult, you would access FileContent as #myResu
lt.FileContent#.
The result attribute allows functions or CFCs that are called from multiple pages at the same time to avoid
overwriting the results of one call with another. For information about the variables returned by a cfhttp get
operation, see the section Variables returned by a cfhttp get operation in the Usage section.
Attribute

Req/Opt

result

Optional

Default

Description
Specifies the name of the
variable in which you want
the result returned.

The following attributes tell ColdFusion to put the HTTP response body in a file. You can put the response body in a
file for GET, POST, PUT, DELETE, OPTIONS, and TRACE methods, but it is generally not useful with the DELETE
or OPTIONS method.
Attribute

Req/Opt

Default

Description

file

Required if path is
specified and not a GET
method

See Description

Name of the file in which
to store the response
body. For a GET
operation, the default is
the file requested in the
URL, if there is one. For
example, if the URL in a
GET method is
http:www.myco.com/test.h
tm, the default file is
test.htm. Do not specify
the path to the directory in
this attribute; use the pat
h attribute.

path

Required if file is
specified.

Tells ColdFusion to save
the HTTP response body
in a file. Contains the
absolute path to the
directory in which to store
the file.

Use the following syntax in the path attribute to specify an in-memory directory for your files. In-memory files speed
processing of transient data.

© 2014 Adobe Systems Incorporated. All rights reserved.

620

Adobe ColdFusion Documentation

ram:///filepath

The filepath can include multiple directories, for example ram:///petStore/images. Create the directories in the
path before you can use them. For more information on using in-memory files, see Working with in-memory files in
Optimizing ColdFusion applications in the Developing ColdFusion Applications.
The following attributes tell ColdFusion to convert the HTTP response body into a ColdFusion query object. They
can be used with the GET and POST methods only.
Attribute

Req/Opt

Default

Description

columns

Optional

First row of response
contains column names.

The column names for the
query, separated by
commas, with no spaces.
Column names must start
with a letter. The
remaining characters can
be letters, numbers, or
underscore characters (_).
If there are no column
name headers in the
response, specify this
attribute to identify the
column names. If you
specify this attribute, and
the firstrowasHeader
attribute is True (the
default), the column
names specified by this
attribute replace the first
line of the response. You
can use this behavior to
replace the column names
retrieved by the request
with your own names.
If a duplicate column
heading is encountered in
either this attribute or in
the column names from
the response, ColdFusion
appends an underscore to
the name to make it
unique.
If the number of columns
specified by this attribute
does not equal the
number of columns in the
HTTP response body,
ColdFusion generates an
error.

© 2014 Adobe Systems Incorporated. All rights reserved.

621

Adobe ColdFusion Documentation

delimiter

Optional

, (comma)

A character that separates
query columns. The
response body must use
this character to separate
the query columns.

firstrowasheaders

Optional

yes

Determines how
ColdFusion processes the
first row of the query
record set:
yes: processes the first
row as column heads. If
you specify a columns
attribute, ColdFusion
ignores the first row of
the file.
no: processes the first
row as data. If you do
not specify a columns
attribute, ColdFusion
generates column
names by appending
numbers to the word
"column"; for example,
"column_1".

name

Optional

textQualifier

Optional

Tells ColdFusion to create
a query object with the
given name from the
returned HTTP response
body.
" double-quotation mark

A character that,
optionally, specifies the
start and end of a text
column. This character
must surround any text
fields in the response
body that contain the
delimiter character as part
of the field value.
To include this character
in column text, escape it
by using two characters in
place of one. For
example, if the qualifier is
a double-quotation mark,
escape it as "".

Usage

© 2014 Adobe Systems Incorporated. All rights reserved.

622

Adobe ColdFusion Documentation

The cfhttp tag is a general-purpose tool for creating HTTP requests and handling the returned results. It enables
you to generate most standard HTTP request types. You use embedded cfhttpparam tags to specify request
headers and body content.
When ColdFusion receives a response to a cfhttp request, it can put the response body (if any) in a file or the cfh
ttp.FileContent string variable. If the body text is structured as a result set, ColdFusion can put the body text in
query object. You can also access the values of all returned headers and specify how to handle error status and
redirections, and specify a time-out to prevent requests from hanging.
The HTTP protocol is the backbone of the World Wide Web and is used for every web transaction. Because the cfh
ttp tag can generate most types of requests, it provides significant flexibility. Possible uses include:
Interacting with dynamic web sites and services that are not available as web services. (Use the cfinvoke t
ag to access SOAP web services.)
Getting the contents of an HTML page or other file such as an image on a web server for use in your CFML
page or storage in a file.
Sending a secure request to a server by specifying the https protocol in the url attribute.
Using the POST method to send a multipart/form-data style post to any URL that can handle such data and
return results, including CGI executables or even other ColdFusion pages.
Using the PUT method to upload files to a server that does not accept FTP requests.
This tag can, and for PUT and POST requests must, have a body that contains cfhttpparam tags. If this
tag has cfhttpparam tags, it must have a  end tag.
To use HTTPS with the cfhttp tag, you might need to manually import the certificate for each web server
into the keystore for the JRE that ColdFusion uses. This procedure should not be necessary if the certificate
is signed (issued) by an authority that the JSSE (Java Secure Sockets Extension) recognizes (for example,
Verisign); that is, if the signing authority is in the cacerts already. However, you might need to use the
procedure if you are issuing SSL (secure sockets layer) certificates yourself.
Manually import a certificate

1.
2.
3.
4.
5.
6.
7.

Go to a page on the SSL server in question.
Double-click the lock icon.
Click the Details tab.
Click Copy To File.
Select the base64 option and save the file.
Copy the CER file into C:\ColdFusion9\runtime\jre\lib\security (or whichever JRE ColdFusion is using).
Run the following command in the same directory (keytool.exe is located in C:\ColdFusion9\runtime\jre\bin):

keytool -import -keystore cacerts -alias giveUniqueName -file filename.cer

Variables returned by a cfhttp get operation

The cfhttp tag returns the following variables. If you set the result attribute, the name you assign replaces cfht
tp as the prefix. For additional information, see the result attribute.
Name

Description

cfhttp.charSet

Response character character set (character encoding)
specified by the response Content-Type header.

© 2014 Adobe Systems Incorporated. All rights reserved.

623

Adobe ColdFusion Documentation

cfhttp.errorDetail

If the connection to the HTTP server fails, contains
details about the failure. For instance: "Unknown host:
my.co.com"; otherwise, the empty string. recommends
that you check this variable for an error condition
before checking other variables.

cfhttp.fileContent

Response body; for example, the contents of an html
page retrieved by a GET operation. Empty if you save
the response in a file.

cfhttp.header

Raw response header containing all header information
in a single string. Contains the same information as the
cfhttp.responseHeader variable.

cfhttp.mimeType

MIME type specified by the response Content-Type
header; for example, text/html.

cfhttp.responseHeader

The response headers formatted into a structure. Each
element key is the header name, such as Content-Type
or Status_Code. If there is more than one instance of a
header type, the type values are put in an array. One
common technique is to dynamically access the
cfhttp.responseHeader structure as a dynamic array;
for example, #cfhttp.resonseHeaderfieldVaria
ble#.

cfhttp.statusCode

The HTTP status_code header value followed by the
HTTP Explanation header value; for example, "200
OK".

cfhttp.text

Boolean; true if the response body content type is
text. ColdFusion recognizes the response body as text
in the following situations:
if the header does not specify a content type
if the content type starts with "text"
if the content type starts with "message"
if the content type is "application/octet-stream"

Building a query from a delimited text file

The cfhttp tag can create a ColdFusion query object form the response body. To do so, the response body must
consist of lines of text, with each line having fields that are delimited by a character that identifies the column breaks.
The default delimiter is a comma (,). The response data can also use a text qualifier; the default is a
double-quotation mark ("). If you surround a string field in the text qualifier, the field can contain the delimiter
character. To include the text qualifier in field text, escape it by using a double character. The following line shows a
two-line request body that is converted into a query. It has three comma-delimited fields:

© 2014 Adobe Systems Incorporated. All rights reserved.

624

Adobe ColdFusion Documentation

Field1,Field2,Field3
"A comma, in text","A quote: ""Oh My!""",Plain text

Run the following code to show how ColdFusion treats this data:





Column names can be specified in three ways:
By default, ColdFusion uses the first row of the response as the column names.
If you specify a comma-delimited columns attribute, ColdFusion uses the names specified in the attribute as
the column names. Set firstRowAsHeaders="no" if the first row of the response contains data.
Otherwise, ColdFusion ignores the first row.
If you do not specify a columns attribute and set firstrowasheaders="no", ColdFusion generates
column names of the form Column_1, Column2, etc.
The cfhttp tag checks to ensure that column names in the data returned by the tag start with a letter and
contain only letters, numbers, and underscore characters ().ColdFusion checks for invalid column names.
Column names must start with a letter. The remaining characters can be letters, numbers, or underscores ( ).
If a column name is not valid, ColdFusion generates an error.
Notes

For the ColdFusion Administrator time-out and the URL time-out to take effect, enable the time-out in the
ColdFusion Administrator, Server Settings page. For more information, see Configuring and Administering
ColdFusion.
The cfhttp tag supports Basic Authentication for all operations.
The cfhttp tag uses SSL to negotiate secure transactions.
If you put the HTTP response body in a file, ColdFusion does not put it in the CFHTTP.FileContent variable or
generate a query object. If you do not put the response body in a file, ColdFusion puts it in the
CFHTTP.FileContent variable; if you specify a name attribute ColdFusion generates a query object.
The cfhttp tag does not support NTLM or Digest Authentication.
If you are using Microsoft IIS, there is no HTTP header size limit. To specify an HTTP header size limit, set it
in IIS.
Example

© 2014 Adobe Systems Incorporated. All rights reserved.

625

Adobe ColdFusion Documentation














#item.title.xmltext#

Author  #item.author.xmltext#

Applies to these products


#item.xmlChildren[i].xmlAttributes.Name#







© 2014 Adobe Systems Incorporated. All rights reserved.

626

Adobe ColdFusion Documentation

cfhttpparam
Description

Allowed inside cfhttp tag bodies only. Required for cfhttp POST operations. Optional for all others. Specifies
parameters to build an HTTP request.
Category

Internet protocol tags
Syntax



Note
You can specify this tag's attributes in an attributeCollection attribute whose value is a
structure. Specify the structure name in the attributeCollection attribute and use the tag's
attribute names as structure keys.

See also

cfhttp, GetHttpRequestData, cfftp, cfldap, cfmail, cfmailparam, cfpop
History

ColdFusion MX 6.1:
Added the header and body types.
Added the encoded and mimeType attributes.
Changed HTTP method behavior: all HTTP methods can have httpparam tags.
Changed the name attribute requirements: it is not required for all types.
Attributes

Attribute

Req/Opt

type

Required

Default

Description
Information type:
header: specifies an
HTTP header.
ColdFusion does not
URL encode the
header.

© 2014 Adobe Systems Incorporated. All rights reserved.

627

Adobe ColdFusion Documentation

CGI: specifies an HTTP
header. ColdFusion
URL encodes the
header by default.
body: specifies the
body of the HTTP
request. ColdFusion
does not automatically
set a content-type
header or URL encode
the body contents. To
specify the
content-type, use a
separate cfhttppara
m tag with type=heade
r.
XML: identifies the
request as having a
content-type of text/xml.
Specifies that the valu
e attribute contains the
body of the HTTP
request. Used to send
XML to the destination
URL. ColdFusion does
not URL encode the
XML data.
file: tells ColdFusion
to send the contents of
the specified file.
ColdFusion does not
URL encode the file
contents.
URL: specifies a URL
query string name-value
pair to append to the cf
http url attribute.
ColdFusion URL
encodes the query
string.
formField: specifies a
form field to send.
ColdFusion URL
encodes the Form field
by default.
cookie: specifies a
cookie to send as an
HTTP header.
ColdFusion URL
encodes the cookie.

© 2014 Adobe Systems Incorporated. All rights reserved.

628

Adobe ColdFusion Documentation

encoded

Optional

file

Required only if type="F
ile"

Applies to File type;
ignored for all other types.
The absolute path to the
file that is sent in the
request body.

mimeType

Optional

Applies to File type;
invalid for all other types.
Specifies the MIME media
type of the file contents.
The content type can
include an identifier for the
character encoding of the
file; for example, text/html;
charset=ISO-8859-1
indicates that the file is
HTML text in the ISO
Latin-1 character
encoding.

name

Required. Optional (and
ignored) for Body and
XML types

Variable name for data
that is passed. Ignored for
Body and XML types. For
File type, specifies the
filename to send in the
request.

value

Required. Optional (and
ignored) for File type

Value of the data that is
sent. Ignored for File type.
The value must contain
string data or data that
ColdFusion can convert to
a string for all type attrib
utes except Body. Body
types can have string or
binary values.

yes

Applies to FormField and
CGI types; ignored for all
other types. Specifies
whether to URL encode
the form field or header.

Usage

Specifies header or body data to send in the HTTP request. The type attribute identifies the information that the
parameter specifies. A cfhttp tag can have multiple cfhttpparam tags, subject to the following limitations:
An XML type attribute cannot be used with additional XML type attributes, or with body, file, or formFiel
d type attributes.
A body type attribute cannot be used with additional body type attributes, or with XML, file, or formFiel

© 2014 Adobe Systems Incorporated. All rights reserved.

629

Adobe ColdFusion Documentation

d type attributes.
The XML and body type attributes cannot be used with the cfhttp tag TRACE method.
The file type attribute is only meaningful**with the cfhttp tag POST and PUT methods.
The formField type attribute is only meaningful**with the cfhttp tag POST and GET methods.
If you send an HTTP request to a ColdFusion page, all HTTP headers, not just those sent using the CGI type,
are available as CGI scope variables, However, any custom variables (such as "myVar") do not appear in a
dump of the CGI scope.
When you send a file using the type="file" attribute, the file content is sent in the body of a
multipart/form-data request. If you send the file to a ColdFusion page, the Form scope of the receiving page
contains an entry with the name you specified in the cfhttpparam tag name attribute as the key. The value
of this variable is the path to a temporary file containing the file that you sent. If you also send Form field data,
the location of the filename in the form.fieldnames key list depends on the position of the cfhttpparam tag
with the file relative to the cfhttp tags with the form data.URL-encoding preserves special characters (such
as the ampersand) when they are passed to the server. For more information, see the function URLEncoded
Format. To send arbitrary data in a "raw" HTTP message, use a cfhttpparam tag with a type="body" attri
bute to specify the body content and use cfhttpparam tags with a type="header" attributes to specify
the headers.
Example

© 2014 Adobe Systems Incorporated. All rights reserved.

630

Adobe ColdFusion Documentation











#cfhttp.fileContent#



Output the passed variables

Form variable: #form.form_test#

URL variable: #URL.url_test#

Cookie variable: #Cookie.cookie_test#

CGI variable: #CGI.cgi_test#


Note that the CGI variable is URL encoded.


#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

631

Adobe ColdFusion Documentation

Tags i
This section lists tags starting with alphabet I with their description.
cfif
cfimage
cfimap
cfimapfilter
cfimpersonate
cfimport
cfinclude
cfindex
cfinput
cfinsert
cfinterface
cfinvoke
cfinvokeargument

© 2014 Adobe Systems Incorporated. All rights reserved.

632

Adobe ColdFusion Documentation

cfif
Description

Creates simple and compound conditional statements in CFML. Tests an expression, variable, function return value,
or string. Used, optionally, with the cfelse and cfelseif tags.
Category

Flow-control tags
Syntax


HTML and CFML tags
HTML and CFML tags

HTML and CFML tags




See also

cfelse, cfelseif, cfabort, cfbreak, cfexecute, cfexit, cflocation, cfloop, cfswitch, cfthrow, cf
try
Usage

If the value of the expression in the cfif tag is true, ColdFusion processes all the code that follows, up to any cfe
lseif or cfelse tag, and then skips to the cfif end tag. Otherwise, ColdFusion does not process the code that
immediately follows the cfif tag, and continues processing at any cfelseif or cfelse tag, or with the code that
follows the cfif end tag.
When testing the return value of a function that returns a Boolean, you do not have to define the True condition
explicitly. This example uses the IsArray function:



If successful, IsArray evaluates to yes, the string equivalent of the Boolean True. This is preferred over explicitly
defining the True condition this way:



This tag requires an end tag.
Example

In this example, variables are shown within number signs. This is not required.



© 2014 Adobe Systems Incorporated. All rights reserved.

633

Adobe ColdFusion Documentation



SELECT Center_ID, Name, Address1, Address2, City, State, Country, PostalCode,
Phone, Contact
FROM Centers
ORDER by City, State, Name

CFIF gives us the ability to perform conditional logic based on a condition
or set of conditions.
For example, we can output the list of Centers from the snippets datasource
by group and only display them IF City = San Diego.


The following centers are in San Diego:



Name/Address:#Name#, #Address1#, #City#, #State#

Contact: #Contact#





If we would like more than one condition to be the case, we can ask for a list of
the
centers in San Diego OR Santa Ana. If the center does not follow this
condition, we
can use CFELSE to show only the names and cities of the other centers.
Notice how a nested CFIF is used to specify the location of the
featured site (Santa Ana or San Diego).

Complete information is shown for centers in San Diego or Santa Ana.
All other centers are listed in italic:


Featured Center in

San Diego

Santa Ana

 Name/Address:#Name#, #Address1#, #City#, #State#

Contact: #Contact#



#Name#, #City#



Finally, we can use CFELSEIF to cycle through a number of conditions and
produce varying output. Note that you can use CFCASE and CFSWITCH for a more
elegant representation of this behavior.




#Name#, #City# (this one is in
San Diego
Santa Ana
)

© 2014 Adobe Systems Incorporated. All rights reserved.

634

Adobe ColdFusion Documentation



#Name#, #City# (this one is in San Francisco)


#Name#, #City# (this one is in Suisun)
 
#Name#
Not in a city we track



© 2014 Adobe Systems Incorporated. All rights reserved.

635

Adobe ColdFusion Documentation

cfimage
Description

Creates a ColdFusion image. You can use the cfimage tag to perform common image manipulation operations as
a shortcut to Image functions. You can use the cfimage tag independently or in conjunction with Image functions.
History

ColdFusion 10: Added the attribute interpolation to {{cfimage action = "resize"}}
ColdFusion 8: Added this tag.
Category

Other tag
Syntax

Add a border to an image

Create a CAPTCHA image

Convert an image file format

Retrieve information about an image

Read an image into memory

Resize an image

interpolation = "interpolation algorithm"
Rotate an image

Write an image to a file

Write an image to the browser


Note
You can specify this tag's attributes in an attributeCollection attribute whose value is a
structure. Specify the structure name in the attributeCollection attribute and use the tag's
attribute names as structure keys.

See also

ImageAddBorder, ImageCreateCaptcha, ImageInfo,
ImageNew, ImageRead, ImageReadBase64, ImageResi
ze, ImageRotate, ImageWrite, ImageWriteBase64,
Creating and Manipulating ColdFusion Images in
the Developing ColdFusion Applications
Attributes

Attribute

Action

Req/Opt

Default

Description

action

N/A

Optional

read

Action to take. Must
be one of the
following:
border
captcha
convert
info
read
resize
rotate
write
writeToBrowse
r
The default action
is read, which
you do not need
to specify
explicitly.

angle

rotate

© 2014 Adobe Systems Incorporated. All rights reserved.

Required

Angle in degrees to
rotate the
image.Specify an
integer for the value.

639

Adobe ColdFusion Documentation

color

border

© 2014 Adobe Systems Incorporated. All rights reserved.

Optional

black

Border
color.Hexadecimal
value or supported
named color; see
the name list in
Valid HTML named
colors section. For a
hexadecimal value,
use the form "##xx
xxxx" or "xxxxxx"
, where x = 0-9 or
A-F; use two
number signs or
none.

640

Adobe ColdFusion Documentation

destination

border captcha c
onvert resize ro
tate write

Optional (see
Description)

Absolute or relative
pathname where the
image output is
written. The image
format is determined
by the file extension.
The convert and w
rite actions
require a destinat
ion attribute. The b
order, captcha, r
esize, and rotate
actions require a na
me attribute or a de
stination attribut
e. You can specify
both. ColdFusion
supports only
CAPTCHA images
in PNG format.
Where the
CAPTCHA image is
placed depends on
the following:
If destination i
s specified, image
is written to the
file (based on the
absolute or
relative pathname
you specify).
If name is
specified, image
is written to the
image variable.
If neither destin
ation nor name i
s specified, image
is written to the
browser.

difficulty

captcha

Optional

low

Level of complexity
of the CAPTCHA
text. Specify one of
the following levels
of text distortion:
low
medium
high

© 2014 Adobe Systems Incorporated. All rights reserved.

641

Adobe ColdFusion Documentation

fonts

captcha

Optional

fontSize

captcha

Optional

24

Font size of the text
in the CAPTCHA
image.
The value must be
an integer.

format

writeToBrowser

Optional

PNG

Format of the image
displayed in the
browser. If you do
not specify a format,
the image is
displayed in PNG
format.
You cannot display
a GIF image in a
browser. GIF
images are
displayed in PNG
format.

height

captcha resize

Required

© 2014 Adobe Systems Incorporated. All rights reserved.

One or more valid
fonts to use for the
CAPTCHA text.
Separate multiple
fonts with commas.
If the specified font
is not available, falls
back to system
fonts.

Height in pixels of
the image.
For the resize attri
bute, you also can
specify the height as
a percentage (an
integer followed by
the percent (%)symb
ol).
When you resize an
image, if you specify
a value for the
width, you can let
ColdFusion
calculate the aspect
ratio by specifying ""
as the height.
If specified, the
value must be an
integer.

642

Adobe ColdFusion Documentation

interpolation

resize

Optional

highestQuality

Specify a specific
interpolation
algorithm by name
(for example, hammi
ng), by image
quality (for example,
mediumQuality),
or by performance
(for example, highe
stPerformance).
The following are
the valid values:
highestQualit
y
highQuality
mediumQuality
highestPerfor
mance
highPerforman
ce
mediumPerform
ance
nearest
bilinear
bicubic
bessel
blackman
hamming
hanning
hermite
lanczos
mitchell
quadratic

isBase64

border convert i
nfo read resize
rotate writewri
teToBrowser

© 2014 Adobe Systems Incorporated. All rights reserved.

Optional

no

Specifies whether
the source is a
Base64 string:
yes: the source is
a Base64 string.
no: the source is
not a Base64
string.

643

Adobe ColdFusion Documentation

name

borderconvertreadre
sizerotate

Optional(see
Description)

overwrite

bordercaptchaconve
rtreadresizerotate w
rite

Optional

Name of the
ColdFusion image
variable to create.
The read action
requires a name attri
bute.
The border, resi
ze, and rotate acti
ons require a name
attribute or a desti
nation attribute.
You can specify
both.
no

Valid only if the des
tination attribute
is specified. The ov
erwrite values
are:
yes: overwrites
the destination
file.
no: does not
overwrite the
destination file.
If the destination
file exists,
ColdFusion
generates an
error if the overw
rite action is not
set to yes.

quality

write

© 2014 Adobe Systems Incorporated. All rights reserved.

Optional

0.75

Quality of the JPEG
destination file.
Applies only to files
with an extension of
JPG or JPEG. Valid
values are fractions
that range from 0
through 1 (the lower
the number, the
lower the quality).

644

Adobe ColdFusion Documentation

source

border convert i
nfo read resize
rotate write wri
teToBrowser

Required

structName

info

Required

Name of the
ColdFusion
structure to be
created.

text

captcha

Required

Text string displayed
in the CAPTCHA
image. Use capital
letters for better
readability. Do not
include spaces
because users
cannot detect them
in the resulting
CAPTCHA image.

© 2014 Adobe Systems Incorporated. All rights reserved.

URL of the source
image; for
example, "{{ http://
www.google.com/i
mages/logo.gif }}"
Absolute
pathname or a
pathname relative
to the web root;
for example: "c:
\images\logo.
jpg"
ColdFusion image
variable
containing
another image,
BLOB, or byte
array; for
example, "#myIm
age#"
Base64 string; for
example,
"data:image/jpg;b
ase64,/9j/4AAQS
kZJRgABAQA......
........"

645

Adobe ColdFusion Documentation

thickness

border

Optional

width

captcha resize

Required

1

Border thickness in
pixels. The border is
added to the outside
edge of the source
image, increasing
the image area
accordingly.
The value must be
an integer.
Width in pixels of
the image.
For resize, you
also can specify the
width as a
percentage (an
integer followed by
the % symbol).
When you resize an
image, if you specify
a value for the
height, you can let
ColdFusion
calculate the aspect
ratio by specifying ""
as the width.
If specified, the
value must be an
integer.

Usage

ColdFusion provides the cfimage tag and the ColdFusion image, a construct native to ColdFusion that contains
image data. You can manipulate ColdFusion images in memory and write them to a file, a database, or directly to a
browser. You use the cfimage tag to create ColdFusion images from existing image files and perform simple image
actions, such as rotating or resizing. Alternatively, you can use the ImageNew function to create a ColdFusion image
from the beginning or from an existing image. You can use the Image functions to perform complex image
manipulation operations on ColdFusion images that you create with the cfimage tag or with the ImageNew function
.
You can perform the following tasks with ColdFusion images:
Convert an image from one file format to another. For example, you can convert a BMP file to a JPEG file or
a Base64 string to a GIF.
Enforce consistent sizes on files uploaded to the server.
Enforce size limits on JPEG images (by changing the quality of the image).
Save a ColdFusion image to a file or write the image directly to a browser.
Use the ImageGetBlob function within the cfquery tag to insert a ColdFusion image as a Binary Large
Object Bitmap (BLOB) in a database. Also, you can extract a BLOB from a database and generate a
ColdFusion image from it.
Create watermark images.
Create thumbnail images.
Create a Completely Automated Public Turing test to tell Computers and Humans Apart (CAPTCHA) image,

© 2014 Adobe Systems Incorporated. All rights reserved.

646

Adobe ColdFusion Documentation

a distorted text image that is human-readable, but not machine-readable, used in a challenge-response test
for preventing spam.
For more detailed examples, see Creating and Manipulating ColdFusion Images in the Developing
ColdFusion Applications.
File attributes

Use the following syntax to specify an in-memory file, which is not written to disk in the destination and source
attributes. In-memory files speed processing of transient data.

ram:///filepath

The filepath can include directories, for example ram:///petStore/images/poodle.jpg. Create the directories
in the path before you specify the file. For more information on using in-memory files, see Working with in-memory
files in Optimizing ColdFusion applications in the Developing ColdFusion Applications.
Supported image file formats

The cfimage tag operates on a number of different file formats. To list the formats that are supported on the server
where the ColdFusion application is deployed, use the GetReadableImageFormats function and the GetWritea
bleImageFormats function.ColdFusion supports the following default image formats on Macintosh, Windows, and
Unix operating systems:
JPEG
GIF
TIFF
PNG
BMP
ColdFusion does not support the following image formats:
Animated GIF
Multipage TIFF
PSD
AI
CMYK support

The cfimage tag supports reading and writing CMYK images, but does not support actions that require converting
the images. For example, you can use CMYK images with the read, write, writeToBrowser, resize, rotate,
and info actions. You cannot use CMYK images with the convert, captcha, and border actions. The same rule
applies to image functions. For example, the ImageNew, ImageRead, and ImageWrite functions support CMYK
images, but the ImageAddBorder function does not.
Valid HTML named colors

The following table lists the W3C HTML 4 named color value or hexadecimal values that the color attribute
accepts:
Color name

RGB value

Black

##000000

© 2014 Adobe Systems Incorporated. All rights reserved.

647

Adobe ColdFusion Documentation

Blue

##0000FF

Red

##FF0000

Gray

##808080

LightGray

##D3D3D3

DarkGray

##A9A9A9

Green

##008000

Pink

##FFC0CB

Cyan

##00FFFF

Magenta

##FF00FF

Orange

##FFA500

White

##FFFFFF

Yellow

##FFFF00

For all other color values, enter the hexadecimal value. Enter a six-digit value, which specifies the RGB value.
Values between 00 and FF are allowed.
Image quality

By default, the cfimage tag generates images with antialiasing turned on (to remove the appearance of jagged
edges). The interpolation method is set to highestQuality: this produces a high-quality image, but decreases
processing speed. To turn off antialiasing, use the ImageSetAntialiasing function. To change the interpolation
method or for more control over image attributes, use the following functions:
ImageResize
ImageRotate
ImageScaleToFit
ImageShear
ImageTranslate
border action Use the border action to create a rectangular border around the outer edge of an image. You
can control the thickness of the border and its color. For more control, use the ImageAddBorderfunction.
The following example shows how to set the thickness and color of a border:

© 2014 Adobe Systems Incorporated. All rights reserved.

648

Adobe ColdFusion Documentation




captcha action Use the captchaaction to create a distorted text image that is human-readable but not
machine-readable. When you create a CAPTCHA image, you specify the text that is displayed in the
CAPTCHA image; ColdFusion randomly distorts the text. You can specify the height and width of the text
area, which affects the spacing between letters, the font size, the fonts used for the CAPTCHA text, and the
level of difficulty, which affects readability. The following example shows how to write a CAPTCHA image
directly to the browser:



Note
For the CAPTCHA image to display, the width value must be greater than: fontSize ti
mes the number of characters specified in text times 1.08. In this example, the minimum
width is 162.

ColdFusion supports CAPTCHA images in PNG format only.
Note
Use unique names for the CAPTCHA image files so that when multiple users access the
CAPTCHA images, the files are not overwritten.

The following example shows how to create CAPTCHA images with a medium level of difficulty that are
written to files:





For a detailed example, see the Creating and Manipulating ColdFusion Images in the Developing ColdFusion
Applications.
convert action Use the convertaction to convert an image from one file format to another. For more
information on file formats, see the section Supported image file formats. The following example shows how

© 2014 Adobe Systems Incorporated. All rights reserved.

649

Adobe ColdFusion Documentation

to convert a JPEG file to a PNG file:




Note
Converting images between one file format to another is time-consuming. Also, image
quality can degrade; for example, PNG images support 24-bit color, but GIF images
support only 256 colors. Converting transparent images (images with alpha) can degrade
image quality.
info action Use the info action to create a ColdFusion structure that contains information about the image,
including the color model, height, width, and source of the image. The structure is the same as returned by
the ImageInfofunction. The following example shows how to retrieve all of the information about an image:






height: #viatoInfo.height# pixels
width: #viatoInfo.width# pixels
source: #viatoInfo.source#
transparency: #viatoInfo.colormodel.transparency#
pixel size: #viatoInfo.colormodel.pixel_size#
color model: #viatoInfo.colormodel.colormodel_type#
alpha channel support: #viatoInfo.colormodel.alpha_channel_support#
color space: #viatoInfo.colormodel.colorspace#


read action Use the read action to read an image from the specified local file pathname or URL, and create
a ColdFusion image in memory. You can use the ColdFusion image variable as the source for another cfima
ge tag or for Image functions. The read action performs the same operation as the ImageRead function.
The following example shows how to create a ColdFusion image from a JPEG file and manipulate it using the
ImageGrayscalefunction:

© 2014 Adobe Systems Incorporated. All rights reserved.

650

Adobe ColdFusion Documentation








resize action Use the resizeaction to resize an image to the specified height and width. You can specify
the height and width in pixels or as a percentage:








For more control of resize attributes, use the ImageResize function.
rotate action Use the rotateaction to rotate an image by degrees:






For more control of the rotate attributes, use the ImageRotate function.
write action Use the write action to write an image to the specified path. The new image is converted to the
file type specified in the destination attribute. The write action performs the same operation as the ImageWr
ite function. When you write an image to a JPEG file, the image quality is set to 75% of the original image
by default. To control the image size, use the quality attribute of the write action.
You can use the write action to change the quality of a JPEG image to reduce file size. The following example
shows how to change image quality to .5:

© 2014 Adobe Systems Incorporated. All rights reserved.

651

Adobe ColdFusion Documentation








writeToBrowser action Use the writeToBrowseraction to display one or more ColdFusion images directly
to the browser without writing them to files. Images are displayed in PNG format. The following example
shows how to reduce the size of an image and display it in the browser:





Example

This example shows how to create a ColdFusion image and manipulate it by using Image functions:










© 2014 Adobe Systems Incorporated. All rights reserved.

652

Adobe ColdFusion Documentation

cfimap
Description

Queries an IMAP server to retrieve and manage mails within multiple folders.
Category

Communications tags, Internet protocol tags
Syntax



See Also

cfmailparam, cfmailparam, cfmailpart, cfpop, cfftp, cfhttp, cfldap, Wrap; Using ColdFusion with mail
servers in Sending and Receiving E-Mail in the Developing ColdFusion Applications
History

New tag introduced in ColdFusion 9.
Attributes

Attribute

Req/Opt

© 2014 Adobe Systems Incorporated. All rights reserved.

Default

Description

653

Adobe ColdFusion Documentation

action

Optional

© 2014 Adobe Systems Incorporated. All rights reserved.

GetHeaderOnly

Returns the message
header information for all
retrieved mail. Other
values for this attribute
are:GetAll: Returns
mail. The information
includes the message
header information,
message text, and any
attachments. Set the
AttachmentPath attribute
to retrieve attachments. D
elete: Deletes
messages from a folder.O
pen: Initiates an open
session or connection with
the IMAP server.Close:
Terminates the open
session or connection with
the IMAP server.MarkRea
d: Marks all messages
read from a folder.Creat
eFolder: Creates a
folder in the Mailbox.Dele
teFolder: Deletes a
folder in the Mailbox.Rena
meFolder: Renames an
existing user-defined
folder.ListAllFolders:
Displays a list of all
existing folders in the
mailbox or under the
folder name defined by
the Folder attribute.MoveM
ail: Moves mail from one
folder to another.

654

Adobe ColdFusion Documentation

attachmentpath

Optional for GetAll action

Specifies the name of the
folder where ColdFusion
retrieves attachments. If
this folder does not exist,
ColdFusion creates. If you
do not specify the folder,
then the attachment is not
saved.Note: If you specify
a relative path, then
attachments are saved in
a temporary folder. This
folder is same as one
returned by the
GetTempDirectory
function.

Connection

Required for the following
actions: Open and Close

Specifies the variable
name for the
connection/session. If the
server attribute has an
invalid IP address or
invalid domain name, then
the connection fails and
ColdFusion returns an
error message.

Folder

Required for the following
actions: DeleteFolder,
CreateFolder, and
RenameFolderOptional
for LISTALLFOLDERS,
MOVEMAIL,
MARKREAD, GETALL,
GETHEADERONLY,
DELETE.

© 2014 Adobe Systems Incorporated. All rights reserved.

INBOX(For ListAllFolders
action, the default folder is
mailbox)

For mail actions: Specifies
the folder name where
messages are retrieved,
moved, or deleted. If
folder name is invalid,
ColdFusion defaults to
INBOX.
For folder actions:
Specifies the folder name
that is deleted
(DeleteFolder) or created
(CreateFolder) or
renamed
(RenameFolder).
When selecting a
subfolder, use the period
(.) character as
appropriate. For example,
when deleting mail in
folder Module in folder
Product.Version.Module,
define the Folder attribute
as
Product.Version.Module.

655

Adobe ColdFusion Documentation

GenerateUniqueFilen
ames

Optional

Ensures that unique file
names are generated for
each attachment file. The
goal is to avoid name
conflicts for attachments
that have the same
filename.

MaxRows

Optional

Specifies the number of
rows to be marked as
read, deleted, or moved
across folders. When the
value is 1, it signals the
row determined by
StartRow. Any
incremental value marks
rows starting from the
StartRow.
If you have specified the
UID or MessageNumber
attribute, then MaxRows
is ignored.

MessageNumber

Optional

Specifies the message
number or a comma
delimited list of message
numbers for retrieval,
deletion, marking mail as
read, or moving mails. If
you set an invalid
message number, then
the IMAP operation is
ignored. For example, if
you specify that cfimap
deletes a specified
message number, and if
that message number
does not exist, then the
operation is ignored. If
you have specified the
UID attribute, then
MessageNumber attribute
is ignored.

Name

OptionalRequired for the
following actions: GetAll,
GetHeaderOnly, and
ListAllFolders

Specifies the name for the
query object that contains
the retrieved message
information.

© 2014 Adobe Systems Incorporated. All rights reserved.

656

Adobe ColdFusion Documentation

NewFolder

OptionalRequired for the
following actions:
RenameFolder, MoveMail

Specifies the name of the
new folder when you
rename a folder or the
name of the destination
folder where all mails
move.

Password

OptionalRequired when
action="open" username
and password must be
specified.

Specifies the password for
assessing the users'
e-mail account.

Port

Optional

143 or 993

Specifies the IMAP port
number. Use 143 for
non-secure connections
and 993 for secured
connections.

Recurse

Optional

False

Specifies whether
ColdFusion runs the
CFIMAP command in
subfolders. Recurse
works for
action="ListAllFolders".
When recurse is set to
"true", ColdFusion parses
through all folders and
subfolders and returns
folder/subfolder names
and mail information.

Secure

Optional

False

Specifies whether the
IMAP server uses a
Secure Sockets Layer.

Server

OptionalRequired for the
Open action

Specifies the IMAP server
identifier. You can assign
a host name or an IP
address as the IMAP
server identifier.

StartRow

Optional

Defines the first row
number for reading or
deleting. If you have
specified the UID or
MessageNumber
attribute, then StartRow is
ignored. You can also
specify StartRow for
moving mails.

© 2014 Adobe Systems Incorporated. All rights reserved.

657

Adobe ColdFusion Documentation

StopOnError

Optional

True

Specifies whether to
ignore the exceptions for
this operation. When the
value is true, it stops
processing, displays an
appropriate error.

Timeout

Optional

60

Specifies the number of
seconds to wait before
timing out connection to
IMAP server. An error
message is displayed
when timeout occurs.

Uid

Optional

Specifies the unique ID or
a comma-delimited list of
Uids to retrieve, delete,
and move mails. If you set
invalid Uids, then they are
ignored.

Username

Optional

Specifies the user name.
Typically, the user name
is same the e-mail login.

Usage

Open a session or connection with an IMAP server. To open a session, define the server, user name, and password
attributes. You can open a connection with an IMAP server by specifying values for the server, user name,
password, and connection attributes. For a secure connection, specify secure="true". You can reuse the connection
attribute in subsequent CFIMAP tags, without having to specify the server, user name, or password attributes. Once
you have established a connection, you can perform the following actions:
Retrieve mail: Retrieve mail using the GetHeaderOnly or GetAll attributes and store the information in a query
object. Use the cfdump command to display the content of the query object. You can also download
attachments in temporary ColdFusion folder or a new folder as defined by the AttachmentPath attribute.
Delete any unnecessary mail or delete folders. You can delete any user-created folders. Standard folders,
such as INBOX, OUTBOX, SEND, cannot be deleted.
Mark multiple mail as read.
Manage mail folders by creating folders, renaming them or moving mail across folders. If you are using sub
folders, then use periods (.) to specify the exact path.
Once you have performed all actions, close the session or connection with the IMAP server. For example,
mail from your e-mail account in Gmail can be retrieved by setting a connection to the Gmail IMAP server.
You can define the login (user name) and set a secure connection. Next, you can quickly retrieve a top-level
snapshot of e-mails using the GetHeaderOnly attribute or access full information about e-mails using the
GetAll attribute.
Note
Gmail is not a complete IMAP implementation so some of the features of a regular IMAP
server may not work with Gmail.

© 2014 Adobe Systems Incorporated. All rights reserved.

658

Adobe ColdFusion Documentation

The following table lists the query information (column names) returned by various cfimap attributes.
Values for "action" attribute

Columns

GetHeaderOnly

ANSWERED, CC, DELETED, DRAFT, FLAGGED,
FROM, HEADER, LINES, MESSAGEID,
MESSAGENUMBER, RECENT, REPLYTO,
RXDDATE, SEEN, SENTDATE, SIZE, SUBJECT, TO,
UID

GetAll

ANSWERED, ATTACHMENTFILES, ATTACHMENTS,
BODY, CC, CIDS, DELETED, DRAFT, FLAGGED,
FROM, HEADER, HTMLBODY, LINES, MESSAGEID,
MESSAGENUMBER, RECENT, REPLYTO,
RXDDATE, SEEN,SENTDATE, SIZE, SUBJECT,
TEXTBODY, TO, UID.CID is used to find the correct
place of an image in an HTML e-mail message that the
CFIMAP tag retrieves. If the e-mail message contains
more than one embedded image, only the last
embedded image is available.

ListAllFolders

FULLNAME (specifies the entire directory structure),
NAME, NEW, TOTALMESSAGES, and UNREAD

Note
The cfimap command works best on IMAP4 revision1. IMAP4 revision1 is backwards compatible
with IMAP2 and IMAP2bis versions. Any previous versions are no more actively used.

You can get errors in following scenarios:
Accessing an invalid server connection is established. Check the network conditions and whether you are
using appropriate server IP address and domain names. Use valid e-mail user names and passwords.
Accessing non-existent folders: Check whether the folder you are accessing exists. Create or rename folders
with valid names. You cannot rename core folders. Move mail within existing folders.
Slow network: Verify if the timeout attribute needs a higher value. Actions such as CreateFolder may need
longer time to execute. In such cases, adjust the value of the timeout attribute.
Incorrect usage of cfimap attributes: Check if you are using the correct attribute. For example, if you have 15
e-mails in a folder and if the startrow or maxrow attribute has value of 18 then ColdFusion returns an error.
The e-mail client does not recognize IMAP access. Verify whether your e-mail is set up to allow IMAP access.
Complete the necessary IMAP access in connection settings section of your e-mail client.
Using incorrect syntax for attributes: Verify that all attributes are defined per syntax.
Example: 1

© 2014 Adobe Systems Incorporated. All rights reserved.

659

Adobe ColdFusion Documentation









username = "yourname"
action="open"
secure="yes"
password = "yourpassword"
connection = "test.cf.gmail">







Example: 2

© 2014 Adobe Systems Incorporated. All rights reserved.

660

Adobe ColdFusion Documentation





















Example: 3

© 2014 Adobe Systems Incorporated. All rights reserved.

661

Adobe ColdFusion Documentation












Folders in your Inbox #form.username#


#NAME# - #TOTALMESSAGES# (#UNREAD#)









Enter IMAP mail server



Enter your username



Enter your password











© 2014 Adobe Systems Incorporated. All rights reserved.

662

Adobe ColdFusion Documentation

cfimapfilter
Description

Specifies filter parameters that control the actions of cfimap, get operations.
History

ColdFusion 11: Added this tag.
Category

Communications tags
Syntax


OR


Note
You can specify this tag's attributes in an attributeCollection attribute whose value is a
structure. Specify the structure name in the attributeCollection attribute and use the tag's
attribute names as structure keys.

See also

cfimap, Getting Exchange items and attachments in the Developing ColdFusion Applications
Attributes

Attribute

Req/Opt

name

Required

Default

Description
The type of filter to use.
The supported filters in
ColdFusion 11 are:
Name

© 2014 Adobe Systems Incorporated. All rights reserved.

Possi
ble
Attrib
utes

Possi
ble
Value
s

663

Adobe ColdFusion Documentation

Subje
ct

Value

String
to
searc
h in
Subje
ct

From

Value

From
ID

To

Value

Rece
pient
ID

Flag

Value
F
l
a
g
v
a
l
u
e

© 2014 Adobe Systems Incorporated. All rights reserved.

D
e
s
c
r
i
p
t
i
o
n

664

Adobe ColdFusion Documentation

A
N
S
W
E
R
E
D

© 2014 Adobe Systems Incorporated. All rights reserved.

M
e
s
s
a
g
e
s
w
i
t
h
t
h
e
A
n
s
w
e
r
e
d
f
l
a
g
s
e
t
.

665

Adobe ColdFusion Documentation

F
L
A
G
G
E
D

© 2014 Adobe Systems Incorporated. All rights reserved.

M
e
s
s
a
g
e
s
w
i
t
h
t
h
e
F
l
a
g
g
e
d
f
l
a
g
s
e
t
.

666

Adobe ColdFusion Documentation

S
E
E
N

© 2014 Adobe Systems Incorporated. All rights reserved.

M
e
s
s
a
g
e
s
t
h
a
t
h
a
v
e
t
h
e
S
e
e
n
f
l
a
g
s
e
t
.

667

Adobe ColdFusion Documentation

U
N
A
N
S
W
E
R
E
D

© 2014 Adobe Systems Incorporated. All rights reserved.

M
e
s
s
a
g
e
s
t
h
a
t
d
o
n
o
t
h
a
v
e
t
h
e
A
n
s
w
e
r
e
d
f
l
a
g
s
e
t
.

668

Adobe ColdFusion Documentation

U
N
D
E
L
E
T
E
D

© 2014 Adobe Systems Incorporated. All rights reserved.

M
e
s
s
a
g
e
s
t
h
a
t
d
o
n
o
t
h
a
v
e
t
h
e
D
e
l
e
t
e
d
f
l
a
g
s
e
t
.

669

Adobe ColdFusion Documentation

U
N
D
R
A
F
T

© 2014 Adobe Systems Incorporated. All rights reserved.

M
e
s
s
a
g
e
s
t
h
a
t
d
o
n
o
t
h
a
v
e
t
h
e
D
r
a
f
t
f
l
a
g
s
e
t
.

670

Adobe ColdFusion Documentation

U
N
S
E
E
N

Time
Recei
ved

© 2014 Adobe Systems Incorporated. All rights reserved.

From,
To

M
e
s
s
a
g
e
s
t
h
a
t
d
o
n
o
t
h
a
v
e
t
h
e
S
e
e
n
f
l
a
g
s
e
t
.

Start
and
End
date
for
Time
Recei
ved

671

Adobe ColdFusion Documentation

Time
Sent

From,
To

Start
and
End
date
for
Time
Sent

from

Optional

The start date or date/time
combination of the range
to use for filtering. Cannot
be used with the value at
tribute. If you specify a fr
om attribute without a to a
ttribute, the filter selects
for all entries on or after
the specified date or time.
The value can be in any
date/time format
recognized by
ColdFusion, but must
correspond to a value that
is appropriate for the filter
type.

to

Optional

The end date or date/time
combination for the range
used for filtering. Cannot
be used with the value at
tribute. If you specify a to
attribute without a from at
tribute, the filter selects for
all entries on or before the
specified date or time.
The value can be in any
date/time format
recognized by
ColdFusion, but must
correspond to a value that
is appropriate for the filter
type.

© 2014 Adobe Systems Incorporated. All rights reserved.

672

Adobe ColdFusion Documentation

Optional

value

The filter value for all
filters that do not take a
date or time range.
Cannot be used with the f
rom and to attributes.Col
dFusion generates an
error if you specify this
attribute with an empty
contents. Therefore, you
cannot use the empty
string to search for empty
values.
If you set this attribute to
the empty string (""),
ColdFusion searches for
entries where the
specified field is empty.
6.07

Example





© 2014 Adobe Systems Incorporated. All rights reserved.

673

Adobe ColdFusion Documentation

cfimpersonate
Description

This tag is obsolete. Use the newer security tools; see Conversion functions and Securing Applications in the Develo
ping ColdFusion Applications.
History

ColdFusion MX: This tag is obsolete. It does not work in ColdFusion MX and later releases.

© 2014 Adobe Systems Incorporated. All rights reserved.

674

Adobe ColdFusion Documentation

cfimport
Description

You can use the cfimport tag to import either of the following:
All ColdFusion pages in a directory, as a tag custom tag library.
A Java Server Page (JSP) tag library. A JSP tag library is a packaged set of tag handlers that conform to the
JSP 1.1 tag extension API.
Category

Application framework tags
Syntax



See also

cfapplication
History

ColdFusion 9: Added the path attribute.
ColdFusion MX: Added this tag.
Attributes

Attribute

Req/Opt

© 2014 Adobe Systems Incorporated. All rights reserved.

Default

Description

675

Adobe ColdFusion Documentation

taglib

Required

Tag library URI. The path
must be relative to the
web root (and start with /),
the current page location,
or a directory specified in
the Administrator
ColdFusion mappings
page.
A directory in which
custom ColdFusion tags
are stored. In this case,
all the cfm pages in this
directory are treated as
custom tags in a tag
library.
A path to a JAR in a
web-application, for
example,
"/WEB-INF/lib/sometag
s.jar"
A path to a tag library
descriptor, for example,
"/sometags.tld"
Note: You must put
JSP custom tag
libraries in the
/WEB-INF/lib directory.
This limitation does not
apply to ColdFusion
pages.

prefix

Required

Prefix by which to access
the imported custom
CFML tags JSP tags. If
you import a CFML
custom tag directory and
specify an empty value, "
", for this attribute, you
can call the custom tags
without using a prefix.
Specify and use a prefix
for a JSP tag library.

path

Optional

Use this attribute to import
a CFC namespace.

Usage

The following example imports the tags from the directory myCustomTags:

© 2014 Adobe Systems Incorporated. All rights reserved.

676

Adobe ColdFusion Documentation






You can import multiple tag libraries using one prefix. If there are duplicate tags in a library, the first one takes
precedence.JSP tags have fixed attributes; however, if the tag supports runtime attribute expressions, most tag
libraries support the use of the syntax #expressions#. To reference a JSP tag in a CFML page, use the syntax 
. Set the prefix value in the prefix attribute.
Use JSP custom tags in a ColdFusion page

1. Put a JSP tag library JAR file (for example, myjsptags.jar) into the ColdFusion server directory
wwwroot/WEB-INF/lib. If the tag library has a separate TLD file, put it in the same directory as the JAR file.
2. At the top of a CFML page, insert code such as the following:



To reference a JSP tag from a JAR file, use the following syntax:





The cfimport tag must be on the page that uses the imported tags. For example, if you use a cfimport ta
g on a page that you include with the cfinclude call, you cannot use the imported tags on the page that has
the cfinclude tag. Similarly, if you have a cfimport tag on your Application.cfm page, the imported tags
are available on the Application.cfm page only, not on the other pages in the application. ColdFusion does not
throw an error in these situations, but the imported tags do not run. You cannot use the cfimport tag to
suppress output from a tag library.
For more information, see the Java Server Page 1.1 specification.
Example

© 2014 Adobe Systems Incorporated. All rights reserved.

677

Adobe ColdFusion Documentation

cfimport example
This example uses the random JSP tag library that is available from the
Jakarta Taglibs project, at http://jakarta.apache.org/taglibs/




Your password is #myPassword#



You can also instantiate a component using the new operator:



© 2014 Adobe Systems Incorporated. All rights reserved.

678

Adobe ColdFusion Documentation

cfinclude
Description

Embeds references to ColdFusion pages in CFML. You can embed cfinclude tags recursively. For another way
to encapsulate CFML, see cfmessagebox. (A ColdFusion page was formerly sometimes called a ColdFusion
template or a template.)
Category

Flow-control tags, Page processing tags
Syntax



Note
You can specify this tag's attributes in an attributeCollection attribute whose value is a
structure. Specify the structure name in the attributeCollection attribute and use the tag's
attribute names as structure keys.

See also

cfcache, cfflush, cfheader, cfhtmlhead, cfsetting, cfsilent
History

ColdFusion 11: The compileextforinclude attribute of the  tag affects the behavior of the 
tag.
By default only files with the cfm and cfml extensions get compiled when included using the  tag.
All other files when included using the cfinclude tag will not get compiled but their content will be statically
included. No error will be thrown.
A server-level setting and an application-level setting has been added to specify a list of file extensions that
can contain the CFM code. While processing the  tag, ColdFusion checks for this
Application-level/server-level setting to decide whether to compile the content or to statically include it. The
setting value is comma separated list of file extensions. If file extensions are specified at application-level, the
server-level file extension list will be ignored and the application-level file extension list will be used.
Specifying a special value wildcard (*) in the file extension list makes the cfinclude tag to compile any file.
The server-level setting can be modified using the ColdFusion Administrator. The setting can be found at
Server Settings > Settings page. A new key/tag attribute compileextforinclude added to the application
cfc/cfm to specify this file extension list.
ColdFusion 10: Added the attribute {{runOnce}}
ColdFusion MX: Changed error behavior: if you use this tag to include a CFML page whose length is zero bytes, you
do not get an error.
Attributes

© 2014 Adobe Systems Incorporated. All rights reserved.

679

Adobe ColdFusion Documentation

Attribute

Req/Opt

template

Required

runOnce

Optional

Default

Description
A logical path to a
ColdFusion page.

false

If set to true, the given
template (if already
processed) is not
processed again for a
given request.

Usage

ColdFusion searches for included files in the following locations:
1. In the directory of the current page or a directory relative to the current page
2. In directories mapped in the ColdFusion Administrator
You cannot specify an absolute URL or file system path for the file to include. You can only use paths relative
to the directory of the including page or a directory that is registered in the ColdFusion Administrator
Mappings. The following cfinclude statements work, assuming that the myinclude.cfmfile exists in the
specified directory:





But the following do not work:




The included file must be a syntactically correct and complete CFML page. For example, to output data from
within the included page, you must have a cfoutput tag, including the end tag, on the included page, not
the referring page. Similarly, you cannot span a cfif tag across the referring page and the included page; it
must be complete within the included page.
You can specify a variable for the templateattribute, as the following example shows:




Example

© 2014 Adobe Systems Incorporated. All rights reserved.

680

Adobe ColdFusion Documentation


This example includes the dochome.htm page from the CFDOCS directory. The images
do not
display, because they are located in a separate directory. However, the page
appears
fully rendered within the contents of this page.


© 2014 Adobe Systems Incorporated. All rights reserved.

681

Adobe ColdFusion Documentation

cfindex
Description

Populates a search engine collection with metadata and creates indexes for searching it. The engine (Solr) can
search physical files of various types or a database query. Indexing database columns that result from a query lets
users search the query data much faster than they could if you used multiple SQL queries to return the same data.
You must define a collection using the ColdFusion Administrator or the cfcollection tag before creating indexes
for the collection.
You also can index a collection using the ColdFusion Administrator. For more information on creating, indexing, and
searching a collection, see Building a Search Interface in the Developing ColdFusion Applications.
Category

Extensibility tags
Syntax

cfindex supports script style syntax:
new index(collection="");


Note
You can specify this tag's attributes in an attributeCollection attribute whose value is a
structure. Specify the structure name in the attributeCollection attribute and use the tag's
attribute names as structure keys.

See also

cfcollection, cfexecute, cfobject, cfreport, cfsearch, cfwddx

© 2014 Adobe Systems Incorporated. All rights reserved.

682

Adobe ColdFusion Documentation
History

ColdFusion 10:
Added new actions fullimport, deltaimport, status, abort
Added the attribute autoCommit, fieldBoost, docBoost

ColdFusion 9: Added Solr search engine support.
ColdFusion MX 7.0.1: Added the prefix attribute.
ColdFusion MX 7:
Added the category, categoryTree, custom3, and custom4 attributes for the update and refresh act
ions.
Added the status attribute for the update, refresh, delete, and purge actions.
Removed reference to external collections.
Removed suggested cflock usage.
ColdFusion MX:
The action attribute value optimize is obsolete. It does not work, and might cause an error, in ColdFusion
MX.
Changed the external attribute behavior: it is not necessary to specify the external attribute. (ColdFusion
automatically detects whether a collection is internal or external.)
Changed Verity operations behavior: ColdFusion supports Verity operations on Acrobat PDF files.
Changed thrown exceptions: this tag can throw the SEARCHENGINE exception.
Changed acceptable collection naming: this tag accepts collection names that include spaces.
Changed query result behavior: the cfindex tag can index the query results from a cfsearch tag.
Attributes

Attribute

Req/Opt

© 2014 Adobe Systems Incorporated. All rights reserved.

Default

Description

683

Adobe ColdFusion Documentation

action

Required

autoCommit

Optional

© 2014 Adobe Systems Incorporated. All rights reserved.

update: updates a
collection and adds key
to the index.
delete: removes
collection documents as
specified by the key att
ribute.
purge: deletes all of the
documents in a
collection. Causes the
collection to be taken
offline, preventing
searches.
refresh: deletes all of
the documents in a
collection, and then
performs an update.
fullimport:To index full
database. For instance,
when you index the
database for the first
time.
deltaimport:For partial
indexing. For instance,
for any updates in the
database, instead of a
full import, you can
perform delta import to
update your collection.
status: Provides the
status of indexing, such
as the total number of
documents processed
and status such as idle
or running.
abort: Aborts an
ongoing indexing task.
If yes, automatically
commit the changes to the
search server.
If no, indexed documents
are not committed unless
you specifically commit
using cfindex
action="commit". By
default, the value is set to
true.

684

Adobe ColdFusion Documentation

collection

Required

body

Required if type=custom

category

Optional

A string value that
specifies one or more
search categories for
which to index the data.
You can define multiple
categories, separated by
commas, for a single
index. If you use a query
for your indexed data, this
value can be the name of
a column.

categoryTree

Optional

A string value that
specifies a hierarchical
category or category tree
for searching. It is a series
of categories separated
by forward slashes ("/").
You can specify only one
category tree.

© 2014 Adobe Systems Incorporated. All rights reserved.

Name of a collection that
is registered by
ColdFusion; for example,
"personnel".
ASCII text to index.
Query column names, if
name is specified in
query.
You can specify
columns in a delimited
list, for example: "emp_
name, dept_name,
location".
This attribute is ignored
if type is file or path
, and is invalid if actio
n is delete.

685

Adobe ColdFusion Documentation

custom1

Optional

Use to index discrete
values in collection
records, which lets you
search for specific
records. By contrast,
values specified in the bo
dy attribute are
concatenated and
searched as a body of text
using the specified
criteria.
If type = custom, a
query column name. If ty
pe is file or path, a st
ring.

custom2

Optional

Usage is the same as for
custom1.

custom3

Optional

Usage is the same as for
custom1.

custom4

Optional

Usage is the same as for
custom1.

docBoost

Optional

Boost entire document
while indexing. docBoost
enhances the score of the
documents and thereby
the ranking in the search
results. .

extensions

Optional

© 2014 Adobe Systems Incorporated. All rights reserved.

htm, html,cfm, cfml, dbm,
dbml

Delimited list of file
extensions that
ColdFusion uses to index
files, if type = "Path". "
." returns files with no
extension. "." returns all
files.
For example, the following
code returns files with a
listed extension or no
extension: extensions
= ".htm, .html, .cfm,
.cfml, *."

686

Adobe ColdFusion Documentation

fieldBoost

Optional

htm, html,cfm, cfml, dbm,
dbml

Boost specific fields while
indexing.fieldBoost en
hances the score of the
fields and thereby the
ranking in the search
results. Multiple fields can
be boosted by specifying
the values as a
comma-separated list.

key

Required

(empty string)

The value specified for ke
y depends on the type at
tribute:
If type = "file", the
directory path and
filename for the file,
If type = "path", the
directory path for the
location of the files.
If type = "custom", a
unique identifier that
specifies the location of
the data, For a query,
the name of the column
that holds the primary
key, for example. If not
a query, an identifier
such as the URL for a
web page, for example.

language

Optional

prefix

Optional

Specifies the location of
files to index when the
computer that contains
the K2 Search Service is
not the computer on which
you installed ColdFusion,
and when you index files
with the type attribute set
to path.

query

Optional.

The name of the query
against which the
collection is generated.

© 2014 Adobe Systems Incorporated. All rights reserved.

English

For options, see cfcolle
ction.

687

Adobe ColdFusion Documentation

recurse

Optional

status

Optional

The name of the structure
into which ColdFusion
returns status information.

title

Optional

Provides a title for the
document if one cannot
be extracted from the
document.

type

Optional

URLpath

Optional

no

custom, if query attribut
e is specified. Otherwise,
file.

yes: if type = "path",
indexes qualified files in
directories below the
path specified in the key
attribute.
no

file: applies action
value to filename,
including path. Expects
a filename in the key at
tribute.
path: applies action t
o files in a directory
path that pass the exte
nsions filter. Expects a
directory name in the k
ey attribute.
dih: used for Data
Import Handler.
custom: applies actio
n to custom data; for
example, to data from a
query.
If type is file or path,
specifies the URL path.
During indexing, this
pathname is prefixed to
filenames and returned
from a search as the url.

Usage

The attributes settings that the cfindex tag requires depend on whether you set the query attribute. If you set the
query attribute to a valid query name, it specifies that cfindex is to index the data in the query rather than indexing
documents on a disk. If you do not set the query attribute, cfindex assumes that it is indexing a file (type =
file), a set of files in a directory path (type = path), or text that you provide in the body attribute (type = custo
m). If you set the query attribute to a valid query name, the cfindex tag creates indexes as specified by the
following attributes and their values:

© 2014 Adobe Systems Incorporated. All rights reserved.

688

Adobe ColdFusion Documentation

Type

Attribute values

File

The key attribute is the name of a column in the query
that contains a full filename (including path).

Path

The key attribute is the name of a column in the query
that contains a directory pathname.
The extensions and recurse attributes, if specified,
elaborate on which files are included. If the action is de
lete, cfindex deletes keys for the collection.

Custom

The key attribute specifies a column name that
contains anything you want; for example, the primary
key value in the database. It must be unique because
this is the primary key in the collection. If the action is
delete, the key attribute is the name of a column in the
query that contains the keys to delete.
The body attribute is required and is a
comma-delimited list of the names of the columns that
contain the text data to be indexed.

If you do not set the query attribute, the cfindex tag creates indexes as specified by the following attributes and
their values:
Type

Attribute values

File

The key attribute is required and is a full pathname to
a file.

Path

The key attribute is required and it is a directory
pathname.
The extensions and recurse attributes, if specified,
designate which types of files are included. If the action
is delete, both the keys and the document files are
deleted.

Custom

The key attribute is an identifier that specifies the key.
If the action is delete, the key attribute is the
document key to delete.
The body attribute is required and is the text to be
indexed.

If type is not specified but query is set, ColdFusion sets the type to the default value of custom. If neither type n
or query is set, ColdFusion sets type to the default value of file. If type equals custom, all attributes except for

© 2014 Adobe Systems Incorporated. All rights reserved.

689

Adobe ColdFusion Documentation

key and body can specify a literal value, not only a column name. This allows you to change a field to empty in the
collection.
Status attribute

The status attribute provides the following information and diagnostics about the result of a cfindex operation:
Key

Type

Description

BADKEYS

Struct

A structure of keys with diagnostic
messages about the indexing of
these keys. If there are no bad
keys, this key does not exist.

DELETED

Number

The number of keys deleted.

MESSAGES

Array

An array of diagnostic messages,
including nonfatal errors and
warnings. If there are no messages,
this key does not exist.

INSERTED

Number

The number of keys inserted into
the collection.

UPDATED

Number

The number of keys updated in the
collection.

Example







key=#mySearch.key#

title=#mySearch.title#

context=#mySearch.context#

url=#mySearch.url#



© 2014 Adobe Systems Incorporated. All rights reserved.

690

Adobe ColdFusion Documentation







key=#mySearch.key#

title=#mySearch.title#

context=#mySearch.context#

url=#mySearch.url#





SELECT * FROM COURSES


key is Course_ID in the Courses table. ---->
body specifies the columns to be indexed for searching. --->
custom1 specifies the value of the Course_Number column. --->


Indexing Complete





key=#mySearch.key#

title=#mySearch.title#

context=#mySearch.context#

url=#mySearch.url#





SELECT * FROM EMPLOYEE WHERE EMP_ID = 1





Indexing Complete


key=#mySearch.key#

title=#mySearch.title#

context=#mySearch.context#

url=#mySearch.url#





SELECT * FROM EMPLOYEE WHERE Emp_ID = 15





Indexing Complete


key=#getEmps.key#

title=#getEmps.title#

context=#getEmps.context#

url=#getEmps.url#









© 2014 Adobe Systems Incorporated. All rights reserved.

694

Adobe ColdFusion Documentation

cfinput
Description

Used within the cfform tag, to place input controls that support input validation on a form.
Category

Forms tags
Syntax

© 2014 Adobe Systems Incorporated. All rights reserved.

695

Adobe ColdFusion Documentation



Some attributes apply to only specific display formats. For details, see the Attributes table. In HTML format forms,
standard HTML input control attributes not listed above are passed to the HTML and have their normal effect.

© 2014 Adobe Systems Incorporated. All rights reserved.

696

Adobe ColdFusion Documentation

Note
You can specify this tag's attributes in an attributeCollection attribute whose value is a
structure. Specify the structure name in the attributeCollection attribute and use the tag's
attribute names as structure keys.

See also

cfajaximport, cfapplet, cfcalendar, cfform, cfformgroup, cfformitem, cfgrid, cfselect, cfslid
er, cftextarea, cftree, Using Ajax form controls and features in Using Ajax User Interface
Components and Features in the Developing ColdFusion Applications
History

ColdFusion 8
Added autosuggest, autosuggestBindDelay, autosuggestMinLength, delimiter, maxResultsD
isplayed, showAutosuggestLoadingIcon, and typeahead attributes.
Added support for the bind attribute in HTML forms and the bindAttribute and bindOnload, and onBin
dError attributes.
Added the sourceForTooltip attribute
Added support for datefield value of the type attribute in HTML forms.

ColdFusion MX 7:
Added support for button, file, hidden, image, reset, and submit controls.
Added support for generating Flash and XML controls (specified in the cfform tag).
Added datefield type (Flash forms only) and the supporting dayNames and monthNames attributes.
Added bind, enabled, height, label, tooltip, visible, and width attributes for use in Flash forms.
Added support for onBlur and onServer validation, including the validateAt attribute.
Added USdate, range, boolean, email, URL, uuid, guid, maxlength, noblanks, and submitOnce validate attr
ibute values.
Added support for preventing multiple submissions.
Added the mask attribute.
Deprecated the passthrough attribute. The tag now supports all HTML input tag attributes directly.

ColdFusion MX: Changed the cfform tag preserveData attribute behavior: if it is set to True, ColdFusion checks
radio and check box values only if their value matches the posted value for the control. (In earlier releases, if the
posted value did not match any of the cfinput check boxes or radio buttons for the control, the checked attribute
was used.
Attributes

The following table lists attributes that ColdFusion uses directly. The tag also supports all HTML form tag attributes
that are not on this list, and passes them directly to the browser.
Note
Attributes that are not marked as supported in All or XML are not handled by the skins provided
with ColdFusion. They are, however, included in the generated XML.

© 2014 Adobe Systems Incorporated. All rights reserved.

697

Adobe ColdFusion Documentation

Attribute

Req/Opt; formats

Default

Description

name

Required;all

Name for form input
element.

autosuggest

Optional, HTML

Specifies entry completion
suggestions to display as
the user types into a text
input. The user can select
a suggestion to complete
the text entry. The valid
value can be either of the
following:
A string that consists of
the suggestion values
separated by the
delimiter specified by
the delimiter attribut
e.
A bind expression that
gets the suggestion
values based on the
current input text. The
bind expression must
pass a cfautosugges
tvalue bind parameter
to represent the user
input.
Valid only for cfinput
type="text".
For more information,
see Using autosuggest
text input fields in the D
eveloping ColdFusion
Applications

© 2014 Adobe Systems Incorporated. All rights reserved.

698

Adobe ColdFusion Documentation

autosuggestBindDela
y

Optional, HTML

1 second

A nonzero integer that
specifies the minimum
time between autosugge
st bind expression
invocations, in seconds.
This value also specifies
the delay from when the
user first enters a
minimum-length entry in
the field until the
suggestion box appears.
Use this attribute to limit
the number of requests
that are sent to the server
when a user types.Valid
only for cfinput
type="text".
Note: The only way to get
the default behavior is to
omit the attribute.
Otherwise, the delay must
be a nonzero integer
value.

autosuggestMinLengt
h

Optional, HTML

1

The minimum number of
characters required in the
text box before invoking a
bind expression to return
items for suggestion.Valid
only for cfinput
type="text".

bind

Optional; HTML,Flash

bindAttribute

Optional;HTML

© 2014 Adobe Systems Incorporated. All rights reserved.

A bind expression that
dynamically sets an
attribute of the control. For
details, see Usage.
value

Specifies the HTML tag
attribute whose value is
set by the bind attribute.
You can only specify
attributes in the browser's
HTML DOM tree, not
ColdFusion-specific
attributes.
Ignored if there is no bin
d attribute.Valid only for c
finput type="text".

699

Adobe ColdFusion Documentation

bindOnLoad

Optional;HTML

no

A Boolean value that
specifies whether to
execute the bind attribute
expression when first
loading the form. Ignored
if there is no bind attribut
e.Valid only for cfinput
type="text".

checked

Optional;all

no

Selects a radio button or
check box control:
yes
no
For HTML format, you
can indicate that the
item is selected by
specifying the value as
checked or specifying
the attribute with no
value.

dayNames

Optional;all

S, M, T, W, T, F, S

Applies to datefield typ
e only. A
comma-delimited list that
sets the names of the
weekdays displayed in the
calendar. Sunday is the
first day; the rest of the
weekday names follow in
the normal order.

delimiter

Optional, HTML

comma (,)

The delimiter to use to
separate entries in a static
auto-suggest list. This
attribute is meaningful
only if the autosuggest
attribute is a string of
delimited values.

© 2014 Adobe Systems Incorporated. All rights reserved.

700

Adobe ColdFusion Documentation

disabled

Optional;all

not disabled

Disables user input,
making the control
read-only. The attribute
behavior depends on the
format of the form as
follows:
HTML format forms:
ColdFusion passes this
attribute directly to the
HTML. To disable input,
specify disabled with
out a value (HTML
format) or with the value
disabled (XHTML
compliant). To enable
input, omit this attribute.
Flash format forms: To
disable input, specify d
isabled without an
attribute, or disabled
="yes" (or any
ColdFusion positive
Boolean value, such as
true). To enable input,
omit the attribute or
specify disabled="no
" (or any ColdFusion
negative Boolean value,
such as false).

enabled

Optional; Flash

yes

Boolean value that
specifies whether the
control is enabled. A
disabled control appears
in light gray. The inverse
of the disabled attribute.

firstDayOfWeek

Optional;all

0

Applies to datefield typ
e only. Integer in the
range 0-6 that specifies
the first day of the week in
the calendar: 0 indicates
Sunday; 6 indicates
Saturday.

© 2014 Adobe Systems Incorporated. All rights reserved.

701

Adobe ColdFusion Documentation

height

Optional; see Description

Applies to most Flash
types, HTML image type
on some browsers. The
height of the control, in
pixels. The displayed
height might be less than
the specified size.

id

Optional;HTML

label

Optional; Flash, XML

Label to put next to the
control on a Flash form.
Not used for button,
hidden, image, reset, or
submit types.

mask

Optional;Flash, HTML

For tags with type="tex
t". A mask pattern that
controls the character
pattern that users can
enter, or that the form
sends to ColdFusion.
Mask characters and the
corresponding valid input
characters are:

name attribute value

The HTML ID of the form.

A = A-Za-z
X = A-Za-z0-9
9 = 0-9
? = Any character
All other characters =
insert the literal
character
For tags with type="d
atefield", a pattern
that controls the format
of dates that the user
selects in the calendar.
Mask characters are:
D = day; can use 0-2
mask characters.
M = month; can use 0-4
mask characters.
Y = year; can use 0, 2,
or 4 characters.
E = day in week; can
use 0-4 characters.
For more information,
see the Usage section.

© 2014 Adobe Systems Incorporated. All rights reserved.

702

Adobe ColdFusion Documentation

matchContains

Optional

maxLength

Optional;all

maxResultsDisplayed

Optional;HTML

message

Optional;all

monthNames

Optional;all

© 2014 Adobe Systems Incorporated. All rights reserved.

false

If true, the match
returned contains the
query string. By default,
the results that_ start
with_ the query string are
returned.
Maximum length of text
entered, if type = "Text
" or "password". For
complete length
validation, specify maxLe
ngth validation in a vali
date attribute; otherwise,
this attribute prevents
users from typing beyond
the specified length, but
does not prevent them
from pasting in a longer
value.

10

The maximum number
suggestions to display in
the auto-suggest list.Valid
only for cfinput
type="text".
Message text to display if
validation fails.

January, February,
March, April, May,
June, July, August,
September, October,
November, December

Applies to datefield typ
e only. A
comma-delimited list of
the month names that
display at the top of the
calendar.

703

Adobe ColdFusion Documentation

onBindError

Optional;HTML

onChange

Optional;all

JavaScript (HTML/XML)
or ActionScript (Flash) to
run when the control
changes due to user
action. In Flash, applies to
datefield, password, and
text types only.

onClick

Optional;all

JavaScript (HTML/XML)
or ActionScript (Flash) to
run when the user clicks
the control. In Flash,
applies to button,
checkbox, image, radio,
reset, and submit types
only.

onError

Optional;HTML, XML

Name of a custom
JavaScript function to
execute if validation fails.

onKeyDown

Optional;all

JavaScript (HTML/XML)
or ActionScript (Flash)
ActionScript to run when
the user presses a
keyboard key in the
control.

© 2014 Adobe Systems Incorporated. All rights reserved.

See Description

The name of a JavaScript
function to execute if
evaluating a bind
expression, including an
auto-suggest bind
expression, results in an
error. The function must
take two attributes: an
HTTP status code and a
message.
If you omit this attribute,
and have specified a
global error handler (by
using the ColdFusion.s
etGlobalErrorHandle
r function), it displays the
error message; otherwise
a default error pop-up
displays.

704

Adobe ColdFusion Documentation

onKeyUp

Optional;all

JavaScript (HTML/XML)
or ActionScript (Flash) to
run when the user
releases a keyboard key
in the control.

onMouseDown

Optional;all

JavaScript (HTML/XML)
or ActionScript (Flash) to
run when the user
releases a mouse button
in the control.

onMouseUp

Optional;all

JavaScript (HTML/XML)
or ActionScript (Flash) to
run when the user
presses a mouse button in
the control.

onValidate

Optional;HTML, XML

Name of a custom
JavaScript function to
validate user input. The
form object, input object,
and input object values
are passed to the routine,
which should return true
if validation succeeds, and
false otherwise. If used,
the validate attribute is
ignored.

pattern

Required if validate=
"regex";HTML, XML

JavaScript regular
expression pattern to
validate input. ColdFusion
uses this attribute only if
you specify regex in the v
alidate attribute.Omit
leading and trailing
slashes. For examples
and syntax, see Building
Dynamic Forms with
cfform Tags in the Develo
ping ColdFusion
Applications.

© 2014 Adobe Systems Incorporated. All rights reserved.

705

Adobe ColdFusion Documentation

range

Optional;all

Minimum and maximum
allowed numeric values.
ColdFusion uses this
attribute only if you
specify range in the vali
date attribute. If you
specify a single number or
a single number followed
by a comma, it is treated
as a minimum, with no
maximum. If you specify a
comma followed by a
number, the maximum is
set to the specified
number, with no minimum.
Note: ColdFusion does
not process the range att
ribute when you use onsu
bmit or onBlur validatio
n in XML format forms.

readonly

Optional; Flash, HTML

Applies to HTML and
Flash forms.Valid only for
cfinput type= "text".
ColdFusion ignores this
attribute for all other input
types.

required

Optional;all

no

showAutosuggestLoad
ingIcon

Optional; HTML

true

size

Optional;all

© 2014 Adobe Systems Incorporated. All rights reserved.

yes: the field must
contain data.
no: allows an empty
field.
A Boolean value that
specifies whether to
display an animated icon
when loading an
auto-suggest value for a
text input.
Size of input control.
Ignored, if type = "radi
o" or "checkbox". If
specified in a Flash form,
ColdFusion sets the
control width pixel value to
10 times the specified size
and ignores the width att
ribute.

706

Adobe ColdFusion Documentation

sourceForTooltip

Optional; HTML

The URL of a page to
display as a tool tip. The
page can include HTML
markup to control the
format, and the tip can
include images.
If you specify this
attribute, an animated
icon appears with the text
"Loading..." while the tip is
being loaded.

src

Optional;Flash, HTML

Applies to Flash button,
reset, submit, and image
types, and the HTML
image type. URL of an
image to use on the
button.

style

Optional;all

In HTML or XML format,
ColdFusion passes the
style attribute to the
browser or XML.
In Flash format, must be a
style specification in CSS
format. For detailed
information on specifying
Flash styles, see Creating
Forms in Flash in the Dev
eloping ColdFusion
Applications.
In XML format,
ColdFusion passes the
style attribute to the XML.

tooltip

Optional; Flash, HTML

Text to display when the
mouse pointer hovers
over the control.
Ignored if you specify a s
ourceForTooltip attrib
ute.

© 2014 Adobe Systems Incorporated. All rights reserved.

707

Adobe ColdFusion Documentation

type

Optional;all

text

The input control type to
create:
button: push button.
checkbox: check box.
datefield: HTML and
Flash only; date entry
field with an expanding
calendar from which
users select the date or
dates. In HTML format
only, users can also
enter the date by typing
in the field.
file: file selector; not
supported in Flash. Not
supported when you
use Ajax form
submission to submit
the form
asynchronously from
the page.
hidden: invisible
control.
image: clickable button
with an image.
password: password
entry control; hides
input values.
radio: radio button.
reset: form reset
button.
submit: form
submission button.
text: text entry box.
The attribute supports
all HTML 5 input types,
for example, email,
range, or date.

typeahead

Optional;HTML

© 2014 Adobe Systems Incorporated. All rights reserved.

no

A Boolean value that
specifies whether the
auto-suggest feature
should automatically
complete a user's entry
with the first result in the
suggestion list.Valid only
for cfinput
type="text".

708

Adobe ColdFusion Documentation

validate

Optional;all

validateAt

Optional;all

The type or types of
validation to do. Available
validation types and
algorithms depend on the
format. For details, see
Usage.
onSubmit

How to do the validation;
one or more of the
following values:
onSubmit
onServer
onBlur
The onBlur and
onSubmit values are
identical in Flash forms.
For multiple values, use
a comma-delimited list.
For details, see Usage.

value

depends on type
setting;all

visible

Optional; Flash

width

Optional; see Description

HTML: corresponds to the
HTML value attribute. Its
use depends on control
type.
Flash: optional; specifies
text for button type inputs:
button, submit, and
image.
yes

Boolean value that
specifies whether to show
the control. Space that
would be occupied by an
invisible control is blank.
Applies to most Flash
types, and HTML image
type on some browsers.
The width of the control, in
pixels. For Flash forms,
ColdFusion ignores this
attribute if you also
specify a size attribute
value.

Note
Attributes that are marked as not supported in XML are not handled by the skins provided with
ColdFusion. They are, however, included in the generated XML.

© 2014 Adobe Systems Incorporated. All rights reserved.

709

Adobe ColdFusion Documentation
Usage

For this tag to work properly. the browser must be JavaScript-enabled.
If the cfform preserveData attribute is true and the form posts back to the same page, the posted value of the
cfinput control is used, instead of its Value or Checked attribute.
You can use the keyboard to access and select dates from a datefield Flash input: press Tab to go to the field
and press the Spacebar to open the menu. Use the Up, Down, Left, and Right Arrow keys to change the selected
date. Use the Home and End keys to reach the first and last enabled date in a month, respectively. Use the Page Up
and Page Down keys to reach the previous and next month, respectively.
Note
To clear a datefield entry in Flash format forms, select the field to open the menu, and click the
selected date.

For more information, see cfform. For information on using JavaScript regular expressions with this tag, see Buildi
ng Dynamic Forms with cfform Tags in the Developing ColdFusion Applications.
Validation

The following sections describe how to do validation in cfinput tags.
Validation methods ColdFusion provides four methods of validation of cfinput text and password fields
. You can specify one or a combination of the following in the validateAtattribute:
onSubmit: The form page on the browser includes JavaScript functions that perform validation
before the form is submitted to the server. In Flash format forms, this option is identical to onBlur.
onBlur: In HTML format the form page on the browser includes JavaScript functions that perform
validation when the field loses the focus. In Flash format, the attribute is equivalent to onSubmit.
OnBlur validation uses the same algorithms as onSubmit validation. OnBlur validation was added in
ColdFusion MX 7.
onServer: ColdFusion performs the validation on the server. Some onServer algorithms vary from
the onSubmit algorithms. OnServer Date and Time validation allow more patterns than onSubmit
validation. OnServer validation was added in ColdFusion MX 7, and automatically generates hidden
fields to support the validation.
You can also omit a validate attribute and specify the type of validation for the field in a separate
hidden form field. This form of validation is equivalent to onServer validation, but it lets you specify
separate messages for each validation that you do on the field. It is backward compatible with previous
ColdFusion releases. For more information on hidden form field validation, see cfform and Validating
form data using hidden fields in Validating form data using hidden fields in the Developing ColdFusion
Applications.
Validation types Use the following values in the validate attribute to specify input validation for all
validation methods. Most attributes apply only to password or text fields. You can specify multiple validation
types in a comma-delimited list, but only some combinations are meaningful.
Type

Description

date

If validateAt="onServer", allows any date format
that returns true in the IsDate function; otherwise,
same as USdate.

© 2014 Adobe Systems Incorporated. All rights reserved.

710

Adobe ColdFusion Documentation

USdate

A US date of the format mm/dd/yy mm-dd-yy or
mm.dd.yy, with 1-2 digit days and months, 1-4 digit
years.

eurodate

A date of the format dd/mm/yy, with 1-2 digit days and
months, 1-4 digit years. The format can use /, -, or .
characters as delimiters.

time

Time format hh:mm:ss

float or numeric

A number; allows integers.

integer

An integer.

range

A numeric range.

boolean

A value that can be converted to a Boolean value: Yes,
No, True, False, or a number.

telephone

Standard U.S. telephone formats. Allows an initial 1
long-distance designator and up to 5-digit extensions,
optionally starting with x.

zipcode

U.S. 5- or 9-digit ZIP code format #####-####. The
separator can be a hyphen (-) or a space.

creditcard

Strips blanks and dashes; verifies number using mod10
algorithm. Number must have 13-16 digits.

ssn or social_security_number

US. Social Security number format, #########. The
separator can be a hyphen (-) or a space.

email

A valid e-mail address of the form
name@server.domain. ColdFusion validates the format
only; it does not check that entry is a valid active e-mail
address.

URL

A valid URL pattern; supports http, https, ftp file, mailto,
and news URLs.

guid

A unique identifier that follows the Microsoft/DCE
format, xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx, where
x is a hexadecimal number.

uuid

A universally unique identifier (UUID) that follows the
ColdFusion format,
xxxxxxxx-xxxx-xxxx-xxxxxxxxxxxxxxxx, where x is a
hexadecimal number.

© 2014 Adobe Systems Incorporated. All rights reserved.

711

Adobe ColdFusion Documentation

maxlength

Limits the input to a maximum number of characters.

noblanks

Does not allow fields that consist only of blanks.

regex or regular_expression

Matches input against the pattern attribute. Valid in
HTML and XML format only; ignored in Flash format.

SubmitOnce

Used only with submit and image types; prevents the
user from submitting the same form multiple times
before until the next page loads (for example,
submitting an order a second time before getting the
first order confirmation). Valid in HTML and XML format
only; ignored in Flash format.

Validation differencesThe preceding table describes the general validation behavior. The underlying
validation code must differ depending on the validation method and the form type. As a result, the algorithms
used vary in some instances, including the following:
The validation algorithms used for date/time values varies between onSubmit/OnBlur and OnServer.
The algorithms used for onSubmit/OnBlur validation in Flash vary from those used for HTML/XML
format, and generally follow simpler rules.
The table describes the onSubmit/OnBlur behavior in HTML format. For detailed information on the
OnServer validation algorithms, see Data validation types in About ColdFusion validation in the Develo
ping ColdFusion Applications. For more information on validation, including discussions of the
advantages and disadvantages of different validation types, see Validating data in the Developing
ColdFusion Applications.
Masking input data

In HTML and Flash forms, the mask attribute controls the format of data that can be entered into a text field or that is
selected in a datefield input control calendar. In HTML format, it does not prevent users from typing a date that does
not follow the mask into a datefield input control. You can combine masking and validation on a field.
In text fields, ColdFusion automatically inserts any literal mask characters, such as hyphen (-) characters in
telephone numbers. Users type only the variable part of the field.
The following pattern enforces entry of a part number of the format EB-1234-c1-098765, where the user starts the
entry by typing the first numeric character, such as 3. ColdFusion fills in the preceding EB prefix and all - characters.
The user must enters four numbers, followed by two alphanumeric characters, followed by six numbers.



Note
To force a pattern to be all-uppercase or all-lowercase, use the ColdFusion UCase or LCase fun
ctions in the action page.

For tags with type="datefield" (and cfcalendar tags), the number of pattern characters determines the format
of the output when the user selects a date in the calendar, as follows:
Mask

© 2014 Adobe Systems Incorporated. All rights reserved.

Pattern

712

Adobe ColdFusion Documentation

D

Single- or double-digit day of month, such as 1 or 28

DD

Double-digit day of month, such as 01 or 28

M

Single- or double-digit month, such as 1 or 12

MM

Double-digit month, such as 01 or 12

MMM

Abbreviated month name, such as Jan or Dec

MMMM

Full month name, such as January or December

YY

Two-character year, such as 05

YYYY

Four-character year, such as 2005

E

Single-digit day of week, such as 1 or 7

EEE

Abbreviated day of week name, such as Mon or Sun

EEEE

Full month day of week name, such as Monday or
Sunday

The following pattern specifies that the Flash forms sends the date selected by using a datefield input control to
ColdFusion as text in the format 04/29/2004:



Flash form data binding

The bind attribute lets you populate form fields by using the contents of other form fields. To specify text from
another field in a Flash format cfinput tag bind attribute, use the following format:{sourceTagName.text}For
example, the following line uses the values from the firstName and lastName fields to construct an e-mail address.
(The user can change or replace this value with a typed entry.)



HTML form data binding

The bind attribute lets you set cfinput attributes dynamically. For example, you can automatically fill an email
field text-input value based on name and domain field values. In HTML format, the bind attribute specifies a bind
expression, which can have any for the following forms:
A Bind parameter or string that contains
one or more bind parameters. A bind parameter specifies a form control

© 2014 Adobe Systems Incorporated. All rights reserved.

713

Adobe ColdFusion Documentation

value or other attribute and, optionally, an event. In its most
basic form, a bind parameter consists of the name or id attribute
of the control to which you are binding in braces ({ }) The value
of the control attributes specified in the bind parameters determine
the value of the cfinput control attribute.
A CFC or JavaScript function, or URL, typically using one or more bind parameters as function parameters.
The data returned by the function or URL sets the cfinput attribute value.
For details of using HTML form data binding, see Binding data to form fields in the Developing ColdFusion
Applications.
Note
To bind to a cfinput control with type attribute of button, specify a bind event setting
such as click in the bind expression of the control that binds to the button. The default
event, onChange, has no effect.

Example: without binding




Phone Number Validation (enter a properly formatted phone number): 


Required

Zip Code Validation (enter a properly formatted zip code):


Required

Range Validation (enter an integer from 1 to 5): 



Date Validation (enter a properly formatted date):





Example: with binding

© 2014 Adobe Systems Incorporated. All rights reserved.

714

Adobe ColdFusion Documentation

The following example uses binding to generate a default e-mail address based on input controls with a first, last
and domain names, and fills in the e-mail text-input field with the result.
The CFML page contains the following code:

CFC bind using onkeyup() event

When you type in the First Name field, the first initial appears in
the Email control.
Each key you enter in the Last Name and Domain fields appears in the
Email control.


First Name*:   


Last Name*:   


Domain*
:        








* indicates the field is required.


The bindFcns CFC contains the following code:










© 2014 Adobe Systems Incorporated. All rights reserved.

715

Adobe ColdFusion Documentation

cfinsert
Description

Inserts records in data sources from data in a ColdFusion form or form Scope.
Category

Database manipulation tags
Syntax



Note
You can specify this tag's attributes in an attributeCollection attribute whose value is a
structure. Specify the structure name in the attributeCollection attribute and use the tag's
attribute names as structure keys.

See also

cfprocparam, cfprocresult, cfquery, cfqueryparam, cfstoredproc, cftransaction, cfupdate
History

ColdFusion 10: Added the attribute fetchClientInfo and clientInfo.ColdFusion MX: Deprecated the connec
tString, dbName, dbServer, dbtype, provider, and providerDSN attributes. They do not work, and might
cause an error, in releases later than ColdFusion 5.
Attributes

Attribute

Req/Opt

dataSource

Required

Data source; contains
table.

clientInfo

Optional

Structure containing
properties of the client to
be set on the database
connection.

© 2014 Adobe Systems Incorporated. All rights reserved.

Default

Description

716

Adobe ColdFusion Documentation

tableName

Required

fetchClientInfo

Optional

false

If set true, returns a
struct with the key-value
pair passed by the last
query.

formFields

Optional

(all on form, except keys)

Comma-delimited list of
form fields to insert. If not
specified, all fields in the
form are included.
If a form field is not
matched by a column
name in the database,
ColdFusion throws an
error. The database table
key field must be present
in the form. It may be
hidden.

password

Optional

Overrides password
specified in ODBC setup.

tableOwner

Optional

For data sources that
support table ownership
(such as SQL Server,
Oracle, and Sybase SQL
Anywhere), use this field
to specify the owner of the
table.

tableQualifier

Optional

For data sources that
support table qualifiers,
use this field to specify
qualifier for table. The
purpose of table qualifiers
varies among drivers. For
SQL Server and Oracle,
qualifier refers to name of
database that contains
table. For Intersolv
dBASE driver, qualifier
refers to directory where
DBF files are located.

© 2014 Adobe Systems Incorporated. All rights reserved.

Table in which to insert
form fields.ORACLE
drivers: must be
uppercase.Sybase driver:
case-sensitive. Must be
the same case used when
table was created

717

Adobe ColdFusion Documentation

username

Optional

Overrides username
specified in ODBC setup.

Example





Your record was added to the database.







Your record was added to the database.
 


SELECT
CommentID, EMail, FromUser, Subject, CommtType, MessText, Posted, Processed
FROM
COMMENTS



cfinsert Example
First, show a list of the comments in the cfdocexamples datasource.




From User
Subject
Comment Type
Message
Date Posted


#FromUser#
#Subject#
#CommtType#
#Left(MessText, 125)#
#Posted#



Next, well offer the opportunity to enter a comment:



© 2014 Adobe Systems Incorporated. All rights reserved.

718

Adobe ColdFusion Documentation

Email:

From:

Subject: 
Message: 
Date Posted: #DateFormat(Now())#






Note
The cfinsert tag internally uses parameterized queries.

© 2014 Adobe Systems Incorporated. All rights reserved.

720

Adobe ColdFusion Documentation

cfinterface
Description

Defines an interface that consists of a set of signatures for functions. The interface does not include the full function
definitions; instead, you implement the functions in a ColdFusion component (CFC). The interfaces that you define
by using this tag can make up the structure of a reusable application framework.
History

ColdFusion 8: Added this tag.
Category

Application framework tags, Extensibility tags
Syntax





...


...

...


See also

cfargument, cfcomponent, cffunction, GetComponentMetaData, IsInstanceOf
Attributes

Attribute

Req/Opt

displayName

Optional

© 2014 Adobe Systems Incorporated. All rights reserved.

Default

Description
A value to be displayed
when using introspection
to show a descriptive
name for the interface.

721

Adobe ColdFusion Documentation

extends

Optional

A comma-delimited list of
one or more interfaces
that this interface extends.
Any CFC that implements
an interface must also
implement all the
functions in the interfaces
specified by this property.
If an interface extends
another interface, and the
child interface specifies a
function with the same
name as one in the parent
interface, both functions
must have the same
attributes; otherwise
ColdFusion generates an
error.

hint

Optional

Text to be displayed when
using introspection to
show information about
the interface. The hint at
tribute value follows the
syntax line in the function
description.

Usage

The cfinterface tag declares a set of related functions that any ColdFusion component (CFC) that implements
the interface must define. The interface specifies function signatures, but does not implement the functions; instead,
the CFC that implements the interface must contain the full function definitions.
For example, you could create a create, read, update, and delete (CRUD) interface that defines the basic signatures
of the four operations. All components that implement the interface must then conform to the interface signatures.
You can then implement the interface in different components to manage different types of data sources. Because
all the components implement the same interface, you can ensure that you can easily replace one component with
another, depending on the specific data source that an individual application requires.
You define an interface by creating a ColdFusion file with a .cfc extension and specifying the cfinterface tag as
the first and only top-level tag in the file. The filename determines the interface name, so myInterface.cfc defines the
myInterface interface. You can specify any attributes in the cfinterface tag; however, only the names listed in
the Attributes table are meaningful to ColdFusion. The filename must not contain commas, or any periods except for
the separator before the .cfc extension. Inside the cfinterface tag body, you specify the interface by declaring
the functions of the interface. The interface definition must follow these basic rules:
The cfinterface tag body can contain only cffunction tags and comments.
The cffunction tag bodies can contain only cfargument tags, which declare the function arguments, and
comments.
The cffunction tag body is optional.
The following example shows the general format of an interface definition:

© 2014 Adobe Systems Incorporated. All rights reserved.

722

Adobe ColdFusion Documentation












This interface extends the IBasicInterface interface, so any component that implements this interface must
also implement the methods of the IBasicInterface interface. This interface requires the component to
implement the following three functions:
A hello function that can optionally take a single string argument, which has a default value of "world".
A calculateTwo function that takes one required numeric argument, has an optional numeric argument with
a default value of 0, and must return a number.
A disclaimer function that takes no arguments and returns any type.
The CFC that implements an interface specifies the interface name in the cfcomponent tag's implements
attribute. It must implement all of the interface's methods as specified in the interface cffunction tags. The
order of function arguments in the interface definition and the component definition must be identical.
The following table lists the attributes that you can use in the cffunction and cfargument tags, and
describes the requirements and limitations on how you can use them in the interface definition and the
component implementation:
Attribute

Interface requirements

Implementation requirements

access

Optional; only public is allowed

Optional; can be public or remot
e.

description

Optional

Can differ from value in interface.

displayName

Optional

Can differ from value in interface.

hint

Optional

Can differ from value in interface.

name

Required

Must be identical to value in
interface.

cffunction

© 2014 Adobe Systems Incorporated. All rights reserved.

723

Adobe ColdFusion Documentation

output

Optional

Need not be identical to the value in
the interface. Even if you omit the
attribute in the interface, you can
use it in the implementation.
Similarly, you can use the attribute
in the interface and omit it in the
implementation.

returnType

Optional

Must be identical to value in
interface; however, an omitted typ
e option and an option value of any
are equivalent and ColdFusion
treats them as a match.

roles

Not allowed

Can be any valid value.

default

Optional

Must be identical to value in
interface.
If you omit this attribute in the
interface, you can specify any value
in the implementation.

displayName

Optional

Can differ from value in interface

hint

Optional

Can differ from value in interface

name

Required

Must be identical to value in
interface.

required

Optional

If the interface specifies yes, this
attribute must also specify yes. If
the interface specifies no or omits
this attribute, you can specify no or
omit the attribute.

type

Optional

Must be identical to value in
interface; however, an omitted typ
e option and an option value of any
are equivalent and ColdFusion
treats them as a match.

cfargument

A CFC can implement multiple interfaces.

© 2014 Adobe Systems Incorporated. All rights reserved.

724

Adobe ColdFusion Documentation

Note
If a CFC implements multiple interfaces and two or more of the interfaces define functions with
identical names, the signatures of these functions must be the same in all the interfaces;
ColdFusion does not support function overloading.

ColdFusion uses the same rules to locate interfaces as it does to locate components. You can use the GetCompone
ntMetaData function to get information about an interface.Adobe recommends that you use a consistent technique
for identifying interface names, for example, by always starting the file (and therefore interface) name with a capital
I. Any component that implements only that single interface could have a similar name, for example the same root
prefixed by a capital C. You could have an IresourceInfo.cfc interface file and a corresponding CresourceInfo.cfc
component file, for example.
Example

The following example defines an IBasicMath interface with add, subtract, multiply, and divide operations. The
integerMath CFC implements this interface by defining integer arithmetic versions of the operations. The
testMath.cfm application uses the integerMath functions to do arithmetic calculations on two decimal numbers (using
the values of pi and e). As an exercise, consider modifying the interface definition to take and return values of any
type, and then implement a second CFC that uses the PrecisionEvaluate function to calculate arbitrary
precision arithmetic and return the results. (These versions are omitted for brevity.)The IBasicMath.cfc file defines
the interface as follows:




















The integerMath.cfc file defines the integerMath component, which implements the IBasicMath interface, as follows:

© 2014 Adobe Systems Incorporated. All rights reserved.

725

Adobe ColdFusion Documentation
























The testMath.cfm file uses the integerMath component methods to calculate integer values, as follows:


arguments = StructNew();
arguments.first = pi();
arguments.second = "2.718281828459045235360287471352";



Function Arguments
argument 1: #arguments.first#

argument 2: #arguments.second#

Addition
#iMathObj.add(argumentCollection = arguments)#
Subtraction
#iMathObj.subtract(argumentCollection = arguments)#
Multiplication
#iMathObj.multiply(argumentCollection = arguments)#
Division
#iMathObj.divide(argumentCollection = arguments)#


© 2014 Adobe Systems Incorporated. All rights reserved.

726

Adobe ColdFusion Documentation

cfinvoke
Description

Does either of the following:
Invokes a component method from within a ColdFusion page or component.
Invokes a web service.
This tag works as follows:
Transiently instantiates a component or web service and invokes a method on it.
Invokes a method on an instantiated component or web service.
This tag can pass parameters to a method in the following ways:
With the cfinvokeargument tag
As named attribute-value pairs, one attribute per parameter
As a structure, in the argumentCollection attribute
Category

Extensibility tags
Syntax



OR


OR



© 2014 Adobe Systems Incorporated. All rights reserved.

727

Adobe ColdFusion Documentation

OR



component = "#name of instantiated component#"
method = "method name"
returnVariable = "variable name"
argumentCollection = "argument collection"
...>
OR




Note
You can specify this tag's attributes in an attributeCollection attribute whose value is a
structure. Specify the structure name in the attributeCollection attribute and use the tag's
attribute names as structure keys.

See also

cfargument, cfcomponent, cffunction, cfinvokeargument, cfobject, cfproperty, cfreturn, Creat
eObject
History

ColdFusion 10: Added the wsVersion attribute.
ColdFusion 8: Added the following attributes: refreshWSDL, wsdl2javaArgs attributes.
ColdFusion MX 7: Added the servicePort attribute.
ColdFusion MX 6.1: Added the following attributes: timeout, proxyServer, proxyPort, proxyUser, and prox
yPassword.
ColdFusion MX: Added this tag.
Attributes

Attribute

Req/Opt

argumentCollection

Optional

Name of a structure;
associative array of
arguments to pass to the
method.

component

See Usage.

String or component
object; a reference to a
component, or component
to instantiate.

Description

Input parameters. For
each named input
parameter specify param
Name=paramValue.

input_params ...

method

Default

See Usage.

© 2014 Adobe Systems Incorporated. All rights reserved.

Name of a method. For a
web service, the name of
an operation.

729

Adobe ColdFusion Documentation

password

Optional

Password set in the
Administrator, if any

The password to use to
access the web service. If
the webservice attribute
specifies a web service
name configured in the
Administrator, overrides
any user name specified
in the Administrator entry.

proxyPassword

Optional

http.proxyPassword
system property, if any

The user's password on
the proxy server.

proxyPort

Optional

http.proxyPort system
property, if any.

The port to use on the
proxy server.

proxyServer

Optional

http.proxyHost system
property, if any.

The proxy server required
to access the webservice
URL.

proxyUser

Optional

http.proxyUser system
property, if any

The user ID to send to the
proxy server.

refreshWSDL

Optional

no

returnVariable

Optional

servicePort

Optional

First port found in the
WSDL

The port name for the web
service. This value is case
sensitive and corresponds
to the port element's na
me attribute under the ser
vice element.Specify this
attribute if the web service
contains multiple ports.

timeout

Optional

0 (no timeout)

The time-out for the web
service request, in
seconds.

© 2014 Adobe Systems Incorporated. All rights reserved.

yes: reload the WSDL
file and regenerate the
artifacts used to
consume the web
service
no
Name of a variable for the
invocation result.

730

Adobe ColdFusion Documentation

username

Optional

webservice

See Usage

User name set in the
Administrator, if any

The user name to use to
access the web service. If
the webservice attribute
specifies a web service
name configured in the
Administrator, overrides
any user name specified
in the Administrator entry.
One of the following:
The absolute URL of
the web service WSDL.
The Name (string)
assigned in the
ColdFusion
Administrator to the
web service.

wsdl2javaArgs

See Usage

A string that contains a
space-delimited list of
arguments to pass to the
WSDL2Java tool that
generates Java stubs for
the web services. Useful
arguments include the
following:
W or -noWrapped:
Turns off the special
treatment of wrapped
document/literal style
operations.
a or -all: Generates
code for all elements in
the WSDL, even
unreferenced ones.
w or -wrapArrays:
Prefers building beans
to straight arrays for
wrapped XML array
types. This switch is not
in included in the Axis
documentation.
For detailed information
on valid arguments, see
the Apache Axis
WSDL2Java Reference.

© 2014 Adobe Systems Incorporated. All rights reserved.

731

Adobe ColdFusion Documentation

Optional

wsVersion

Specifies version of the
axis to be used. If the wsv
ersion is specified as "1"
then axis 1 will be used
for Consuming. If it is "2"
then axis 2 will be used.

Note
If you do not specify any attributes of the proxy server, and a corresponding system property is
set (typically in the JVM startup arguments) ColdFusion uses the system property value.

Usage

The following table shows when you can use each attribute:
This attribute is
required,
optional,
ignored, or
invalid:

For this
cfinvoke tag
syntax:

Syntax 1

Syntax 2

Syntax 3

Syntax 4A

Syntax 4B

argumentColl
ection

Optional

Optional

Optional

Optional

Optional

component

Required

Optional

Invalid

Required

Invalid

input_params
...

Optional

Optional

Optional

Optional

Optional

method

Required

Required

Required

Required

Required

password

Ignored

Ignored

Optional

Ignored

Optional

proxyPasswor
d

Invalid

Invalid

Optional

Invalid

Optional

proxyPort

Invalid

Invalid

Optional

Invalid

Optional

proxyServer

Invalid

Invalid

Optional

Invalid

Optional

proxyUser

Invalid

Invalid

Optional

Invalid

Optional

returnVariab
le

Optional

Optional

Optional

Optional

Optional

© 2014 Adobe Systems Incorporated. All rights reserved.

732

Adobe ColdFusion Documentation

servicePort

Invalid

Invalid

Optional

Invalid

Optional

timeout

Invalid

Invalid

Optional

Invalid

Optional

username

Ignored

Ignored

Optional

Ignored

Optional

webservice

Invalid

Invalid

Required

Invalid

Required

wsdl2javaArg
s

Invalid

Invalid

Optional

Invalid

Optional

If the component attribute specifies a component name, the component with the corresponding name is
instantiated, the requested method is invoked, and then the component instance is immediately destroyed. If the
attribute contains a reference to an instantiated component object, no instantiation or destruction of the component
occurs.On UNIX systems, ColdFusion searches first for a file with a name that matches the specified component
name, but is all lower case. If it does not find the file, it looks for a file name that matches the component name
exactly, with the identical character casing.Method arguments can be passed in any of the following ways. If an
argument is passed in more than one way with the same name, this order of precedence applies:
1. Using the cfinvokeargument tag
2. Passing directly as attributes of the cfinvoke tag (they cannot have the same name as a registered cfinvo
ke attribute: method, component, webservice, returnVariable)
3. Passing as struct keys, using the argumentCollection attribute
For example, the params struct contains three keys: a=1, b=1, c=1. The following call is evaluated as if the
arguments were passed to the method in the order a=3, b=2, c=1:





Note
The following cfinvoke tag attribute names are reserved; they cannot be used for
argument names: component, method, argumentCollection, and result.

Example1

This example uses Syntax 1.

© 2014 Adobe Systems Incorporated. All rights reserved.

733

Adobe ColdFusion Documentation





#res#

Example2

This example uses Syntax 1.





#res#

Example3

This example uses Syntax 2.




Example4

This example uses Syntax 3.





The temperature at zip code 55987 is #aTemp#

© 2014 Adobe Systems Incorporated. All rights reserved.

734

Adobe ColdFusion Documentation

For more information on web services, see Using Web Services in the Developing ColdFusion Applications.
Example5

This example uses Syntax 4A.




#res#

#res#

© 2014 Adobe Systems Incorporated. All rights reserved.

735

Adobe ColdFusion Documentation

cfinvokeargument
Description

Passes the name and value of a parameter to a component method or a web service. This tag is used in the cfinv
oke tag.
Category

Extensibility tags
Syntax



Note
You can specify this tag's attributes in an attributeCollection attribute whose value is a
structure. Specify the structure name in the attributeCollection attribute and use the tag's
attribute names as structure keys.

See also

cfargument, cfcomponent, cffunction, cfinvoke, cfobject, cfproperty, cfreturn
History

ColdFusion MX 7: Added the omit attribute.ColdFusion MX: Added this tag.
Attributes

Attribute

Req/Opt

name

Required

Argument name.

value

Required

Argument value.

omit

Optional

© 2014 Adobe Systems Incorporated. All rights reserved.

Default

no

Description

Enables you to omit a
parameter when invoking
a web service. It is an
error to specify omit="ye
s" if the cfinvoke webs
ervice attribute is not
specified.yes: omit this
parameter when invoking
a web service.no: do not
omit this parameter when
invoking a web service.

736

Adobe ColdFusion Documentation

Usage

You can have multiple cfinvokeargument tags in a cfinvoke tag body.
You can use cfinvokeargument tag to dynamically determine the arguments to be passed. For example, you can
use conditional processing to determine the argument name, or you can use a cfif tag to determine whether to
execute the cfinvokeargument tag. If you are invoking a web service, you can omit a parameter by setting the om
it attribute to "yes". If the WSDL specifies that the argument is nillable, ColdFusion MX sets the associated
argument to null. If the WSDL specifies minoccurs=0, ColdFusion omits the argument from the WSDL.
Example1





#res#

Example2





The temperature at zip code 55987 is #aTemp#

#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

737

Adobe ColdFusion Documentation

Tags j-l
This section lists tags starting with alphabets J-L with their description.
cflayout
cflayoutarea
cfldap
cflocation
cflock
cflog
cflogin
cfloginuser
cflogout
cfloop
cfloop: index loop
cfloop: conditional loop
cfloop: looping over a date or time range
cfloop: looping over a query
cfloop: looping over a list, a file, or an array
cfloop: looping over a COM collection or structure

© 2014 Adobe Systems Incorporated. All rights reserved.

738

Adobe ColdFusion Documentation

cflayout
Description

Creates a region of its container (such as the browser window or a cflayoutarea tag) with a specific layout
behavior: a bordered area, a horizontal or vertically arranged box, or a tabbed navigator.
Category

Display management tags
Syntax


cflayoutarea tags


Note
You can specify this tag's attribute in an attributeCollection attribute whose value is a
structure. Specify the structure name in the attributeCollection attribute and use the tag's
attribute name as structure key.

See also

cfajaximport, cfdiv, cflayoutarea, cfpod, cfwindow, Using Ajax User Interface Components
and Features in the Developing ColdFusion Applications
History

ColdFusion 9:
Added accordion value of the type attribute and the activeOnTop, fillHeight, and titleCollapse
attributes.
The attributes, height and width are supported for the types hbox and vbox.
ColdFusion 8: Added this tag.
Attributes

© 2014 Adobe Systems Incorporated. All rights reserved.

739

Adobe ColdFusion Documentation

Attribute

Req/Opt

type

Required

© 2014 Adobe Systems Incorporated. All rights reserved.

Default

Applies to

Description

all

The type of layout.
The following values
are valid:

740

Adobe ColdFusion Documentation

accordion: a
container with
multiple layout
areas that display
no more than one
area at a time.
Each layout area
has a title bar that
is always
displayed. The
user can expand
or collapse each
layout area by
clicking + or button on the
layout area title
bar
border: a box
with a border and
up to five layout
areas, each with a
border. For more
information, see
Usage.
hbox: a horizontal
box where all
immediate child c
flayoutarea co
ntrols are
arranged
horizontally.
tab: a tabbed
display where the
current child cfla
youtarea tag
occupies the
display area of the
layout, and each
layout area has a
tab that the user
can select to
display its
contents.
vbox: a vertical
box where all
immediate child c
flayoutarea co
ntrols are
arranged
vertically.

© 2014 Adobe Systems Incorporated. All rights reserved.

741

Adobe ColdFusion Documentation

activeOnTop

Optional

false

accordion

Specifies whether
the active panel
moves to the top of
the layout,
becoming the first
panel.

align

Optional

Determined by
browser layout
direction

all

Specifies the default
alignment of the
content of child
layout areas. Each c
flayoutarea tag
can specify an alig
nment attribute to
override this value.
The following values
are valid:
center
justify
left
right

fillHeight

Optional

true

accordion

A Boolean value
that specifies
whether to adjust
the active layout
area's height to fill
the available space
in the layout control
container:
true
false
If you specify fil
lHeight as fal
se, then
ColdFusion sets o
verflow to hidd
en.

© 2014 Adobe Systems Incorporated. All rights reserved.

742

Adobe ColdFusion Documentation

fitToWindow

Optional

false

border

A Boolean value
that specifies
whether the border
layout must occupy
100% of the width
and height of the
window:
true
false
The underlying
implementation
uses a viewport,
hence, any
content outside
the layout is not
accommodated in
the layout.
When using
nested border
layouts, if you
specify
fitToWindow as
true, the layouts
nested within the
border layout may
not automatically
fit into the
available space.
Hence, for nested
layouts, it is
recommended to
use width or siz
e instead of fitT
oWindow.

© 2014 Adobe Systems Incorporated. All rights reserved.

743

Adobe ColdFusion Documentation

height

Optional

name

Optional

padding

Optional

© 2014 Adobe Systems Incorporated. All rights reserved.

600 for border
layout; autoheight
for others

0

all

Height of the layout
in pixels.
For the tab layout,
the height attribute
has the same
functionality as the t
abheight attribute.
If you specify both h
eight and tabhei
ght attributes, heig
ht takes priority
over tabheight.
The height value
specified here takes
priority over the
height value
specified using the s
tyle attribute.

all

The name of the
layout region.
Should be unique on
a page.

hbox, vbox

For hbox layouts,
specifies the
padding on the
right side of each
child layout area.
For vbox layouts,
specifies the
padding at the
bottom of each
child layout area.
You can use any
valid CSS length
or percent format,
such as 10, 10%
10px, or 10em, for
this attribute.
The padding is
included in the
child layout area
and takes the
style of the layout
area.

744

Adobe ColdFusion Documentation

style

Optional

all

A CSS style
specification that
defines layout
styles.

tabHeight

Optional

tab

Specifies the height
of the content area
of all child layout
areas. You can
override this setting
by specifying a
height setting in a
individual cflayou
tarea tag style
attributes.

tabPosition

Optional

tab

Specifies the
location of the tabs
relative to the tab
region contents.

top

bottom: the tabs
appear at the
bottom of the
layout.
top: the tabs
appear at the top
of the layout.
tabStrip

Optional

true

tab

If true, a
background tab strip
is displayed.

titleCollapse

Optional

true

accordion

Specifies whether
clicking anywhere
on each layout
area's title bar
expands and
collapses the layout
area. If false, the
user must click the
title bar +/- button to
expand or collapse
a layout area.

© 2014 Adobe Systems Incorporated. All rights reserved.

745

Adobe ColdFusion Documentation

Optional

width

all

Width of the layout
in pixels. This value
takes priority over
the width defined
using the style
attribute. If no value
is specified,
autoWidth is applied
and therefore,
content fills the
entire screen.

Usage

The immediate children of a cflayout tag must be cflayoutarea tags or nondisplay tags whose bodies contain
one or more cflayoutarea tags at the top level. For example, a cflayout tag could have a tag such as cfloop
or cfquery as a child, and these tags would have cflayoutarea tags in their bodies.
The border type layout has the following characteristics:
The layout control and each of its immediate layout area children is surrounded by a border.
The control can have up to five children positioned at the left, right, center, top, and bottom of the layout.
You can configure the child layout areas, except for the center area, to have splitters so that users can
expand and collapse them or close them completely.
The center child layout area occupies all available space in the layout that is not used by any of the other
layout areas.
To specify layout height, use the height setting of the styleattribute.
Note
If you specify a border layout on a page that has a DOCTYPE declaration, the layout
cannot properly determine its height and you must specify the height in a cflayout tag s
tyle attribute.

You can use the following JavaScript functions to access the underlying Ext JS - JavaScript Library objects
for border and tab type cflayout controls.
Function

Description

ColdFusion.Layout.getBorderLayout

Gets the underlying Ext JS - JavaScript Library object
for the specified border type cflayout control.

ColdFusion.Layout.getTabLayout

Gets the underlying Ext JS - JavaScript Library object
for the specified tab type cflayout control.

ColdFusion.Layout.getAccordionLayout

Gets the underlying Ext JS - JavaScript Library object
for the specified accordion type cflayout control.

For more information on configuring layout areas, see cflayoutarea.
Example

© 2014 Adobe Systems Incorporated. All rights reserved.

746

Adobe ColdFusion Documentation

The following example shows a set of nested layouts. The outer layout is a vbox, with two layout areas. The top
layout area has a border layout, the bottom layout area contains a form with buttons to control the display of the
border layout areas.

© 2014 Adobe Systems Incorporated. All rights reserved.

747

Adobe ColdFusion Documentation










This is text in layout area 1: top


This is text in layout area 2: left

You can close and collapse this area.


This is text in layout area 3: center



This is text in layout area 4: right

You can collapse this, but not close it.

It is initially collapsed.


This is text in layout area 5: bottom




Change the state of Area 2











© 2014 Adobe Systems Incorporated. All rights reserved.

748

Adobe ColdFusion Documentation

cflayoutarea
Description

Defines a region within a cflayout tag body, such as an individual tab of a tabbed layout.
Category

Display management tags
Syntax

In a border layout

area elements

In a hbox or vbox layout

area elements

In a tab layout

area elements

In an accordion layout


© 2014 Adobe Systems Incorporated. All rights reserved.

750

Adobe ColdFusion Documentation

area elements

If you specify a source attribute, all child tags are ignored. If you do not have child tags, close the tag with />.
Note
You can specify this tag's attribute in an attributeCollection attribute whose value is a
structure. Specify the structure name in the attributeCollection attribute and use the tag's
attribute name as structure key.

See also

cfdiv, cflayout, cfpod, cfwindow, Ajax JavaScript Functions, Using layouts in Controlling Ajax user interface
layout in the Developing ColdFusion Applications
History

ColdFusion 8: Added this tag
Attributes

Attribute

Req/Opt

Default

Applies to

Description

align

Optional

The cflayout tag
align attribute
value

all

Specifies how to
align child controls
within the layout
area. The following
values are valid:
center
justify
left
right

bindLoad

Optional

© 2014 Adobe Systems Incorporated. All rights reserved.

true

tab, accordion

A Boolean value
that specifies
whether to execute
the source attribute
expression when the
layoutarea is first
loaded.

751

Adobe ColdFusion Documentation

closable

Optional

false

tab

A Boolean value
that specifies
whether the area
can close.
Specifying this
attribute adds an x
icon on the tab or
title bar that a user
can click to close
the area.

collapsible

Optional

false

border, accordion

A Boolean value
that specifies
whether the area
can collapse.
Specifying this
attribute adds a >>
or << icon on the
title bar that a user
can click to collapse
the area.
You cannot use this
attribute for border
layout areas with a
position attribute
value of center.

disabled

Optional

false

tab

A Boolean value
that specifies
whether the tab is
disabled, that is,
whether a user can
select the tab to
display its contents.
Disabled tabs are
greyed out. Ignored
if the selected attr
ibute value is true.

initCollapsed

Optional

false

border

A Boolean value
that specifies
whether the area is
initially collapsed.
You cannot use this
attribute for border
layout areas with a
position attribute
value of center.
Ignored if the colla
psible attribute
value is false.

© 2014 Adobe Systems Incorporated. All rights reserved.

752

Adobe ColdFusion Documentation

initHide

Optional

false

border, tab,
accordion

A Boolean value
that specifies
whether the area is
initially hidden. To
show an initially
hidden area, use the
ColdFusion.Layo
ut.showArea or C
oldFusion.Layou
t.showTab functio
n.
You cannot use this
attribute for border
layout areas with a
position attribute
value of center.

maxSize

Optional

-1(no maximum
size)

border

If the position attr
ibute value is top or
bottom, the
maximum height of
the area, in pixels,
that you can set by
dragging a splitter. If
the position attrib
ute value is left or
right, the
maximum width of
the area.
You cannot use this
attribute for border
layout areas with a
position attribute
value of center.

© 2014 Adobe Systems Incorporated. All rights reserved.

753

Adobe ColdFusion Documentation

minSize

Optional

name

Optional

onBindError

Optional

© 2014 Adobe Systems Incorporated. All rights reserved.

-1(no minimum size)

See Description

border

If the position attr
ibute value is top or
bottom, the
minimum height of
the area, in pixels,
that you can set by
dragging a splitter. If
the position attrib
ute value is left or
right, the
minimum width of
the area. You
cannot use this
attribute for border
layout areas with a
position attribute
value of center.

all

The name of the
layout area.

all

The name of a
JavaScript function
to execute if
evaluating a bind
expression results in
an error. The
function must take
two attributes: an
HTTP status code
and a message.
If you omit this
attribute, and have
specified a global
error handler (by
using the ColdFusi
on.setGlobalErr
orHandler functio
n), it displays the
error message;
otherwise a default
error pop-up
displays.

754

Adobe ColdFusion Documentation

overflow

Optional

auto For accordion,
if fillheight attri
bute of the cflayo
ut tag is false,
default value is hid
den.

all

Specifies how to
display child content
whose size would
cause the control to
overflow the window
boundaries. The
following values are
valid:
auto: show scroll
bars when
necessary.
hidden: do not
allow access to
overflowing
content.
scroll: always
show horizontal
and vertical scroll
bars, even if they
are not needed.
visible: content
can display
outside the
bounds of the
layout area.
Notes:
You cannot use v
isible or scrol
l for layout areas
in border layouts.
In Internet
Explorer, layout
areas with the vi
sible setting
expand to fit the
size of the
contents, rather
than having the
contents extend
beyond the layout
area.

© 2014 Adobe Systems Incorporated. All rights reserved.

755

Adobe ColdFusion Documentation

position

Required if the cfl
ayout type is bord
er

border

The position of the
area in the layout.
Must be one of the
following values:
top: Position the
area across the
top of the full
layout.
bottom: Position
the area across
the bottom of the
full layout.
left: Position
the area on the
left side of the
layout, between
any visible top
and bottom areas.
right: Position
the area on the
right side of the
layout, between
any visible top
and bottom areas.
center: Position
the area in the
space not taken
by the top,
bottom, left, and
right areas.
Border style
layouts can have
at most one layout
area of each type.

© 2014 Adobe Systems Incorporated. All rights reserved.

756

Adobe ColdFusion Documentation

refreshOnActiva
te

Optional

false

tab, accordion

selected

Optional

first tab is selected

tab, accordion

© 2014 Adobe Systems Incorporated. All rights reserved.

true: Refresh the
contents of the
tab/ accordion
panel by running
the source bind
expression
whenever the
tab/panel display
region shows (for
example, when
the user selects
the tab), in
addition to when
bind events occur.
false: Refresh
the tab/accordion
panel display
region only when
the bind
expression is
triggered by its
bind event.
To use this
attribute, also
specify a source
attribute.
A Boolean value
that specifies
whether this tab is
initially selected so
that its contents
appears in the
layout.

757

Adobe ColdFusion Documentation

size

Optional

© 2014 Adobe Systems Incorporated. All rights reserved.

-1calculate initial
size dynamically

border, hbox, vbox

For hbox layouts
and border layouts
with position attri
bute values of top o
r bottom, the initial
height of the area.
For vbox layouts
and border layouts
with position attri
bute values of left
or right, the initial
width of the area.
For hbox and vbox
layouts, you can use
any valid CSS
length or percent
format (such as 10,
10% 10px, or 10em)
for this attribute.
For border layouts,
this attribute value
must be an integer
number of pixels.
You cannot use this
attribute for border
layout areas with a
position attribute
value of center.
ColdFusion
automatically
determines the
center size based
on the size of all
other layout areas.
Note: If a layout
area in a border
layout contains only
AJAX controls such
as HTML format cf
tree tags, specify a
size attribute.
Otherwise, the
AJAX components
may not be visible
until the layout area
is resized.

758

Adobe ColdFusion Documentation

source

Optional

© 2014 Adobe Systems Incorporated. All rights reserved.

all

A URL that returns
the layout area
contents.
ColdFusion uses
standard page path
resolution rules. You
can use a bind
expression with
dependencies in this
attribute. If a file
specified in this
attribute includes
tags that use AJAX
features, such as cf
form, cfgrid, and
cfpod, use the cfa
jaximport tag on
the page that
includes the cflay
outarea tag. For
more information,
see cfajaximport
.
For more
information on the s
ource attribute, see
Usage.

759

Adobe ColdFusion Documentation

splitter

Optional

style

tabTip

border

A Boolean value
that specifies
whether the layout
area has a divider
between it and the
adjacent layoutar
ea control. Users
can drag the splitter
to change the
relative sizes of the
areas.
If this attribute is set
to true on a left
or right position
layout area, the
splitter resizes the
area and its
adjacent area
horizontally. If this
attribute is set to tr
ue on a top or bot
tom position layout
area, the splitter
resizes the layout
vertically.
You cannot use this
attribute for border
layout areas with a
position attribute
value of center.

Optional

all

A CSS style
specification that
controls the
appearance of the
area.

Optional

tab

If defined, a tab tip
is displayed.

© 2014 Adobe Systems Incorporated. All rights reserved.

false

760

Adobe ColdFusion Documentation

title

Optional; required
for tab layouts

border, tab,
accordion

For tab layouts, the
text to display on the
tab. For border
layouts, if you
specify this attribute,
ColdFusion creates
a title bar for the
layout area with the
specified text as the
title. By default,
border layouts that
are not closable or
collapsible do not
have a title bar.
You cannot use this
attribute for border
layout areas with a
position attribute
value of center.

{{title}}icon

Optional

accordion

Specifies the
location of the icon
to display with the
title.

Usage

All cflayoutarea tags must be children of cflayout tags and cannot have cflayoutarea tags as immediate
children, but they can contain cflayout tags. However, the cflayoutarea tags do not have to be direct children
of the cflayout tag; instead, the cflayout tag could have a tag such as cfloop or cfquery as a child, and the
cflayoutarea tags could be in the body of the cfloop or cfquery tag. These rules let you create arbitrarily
complex combinations of different layouts.
Note
You cannot put a layout of type border inside a layout of type tab.

If you do not specify a size attribute value, ColdFusion attempts to determine the required size for the layout area
contents. However, in some cases, such as when the layout area contains AJAX controls, ColdFusion might not be
able to determine the required size, and you must specify the size attribute to make the AJAX control appear. In
these cases, a scroll bar appears for the layout area.
You can use a source attribute or a tag body to specify the layout area contents; if you specify both, ColdFusion
uses the contents specified by the source attribute and ignores the tag body. If you use a source attribute, an
animated icon and the text "Loading..." appears while the contents is being fetched.
If the source attribute specifies a page that defines JavaScript functions, the function definitions on that page must
have the following format:

functionName = function(arguments) {function body}

© 2014 Adobe Systems Incorporated. All rights reserved.

761

Adobe ColdFusion Documentation

Function definitions that use the following format may not work:

function functionName (arguments) {function body}

However, Adobe recommends that you include all custom JavaScript in external JavaScript files and import them on
the application's main page, and not write them inline in code that you get using the source attribute. Imported pages
do not have this function definition format restriction.
If you use the source attribute, you can use a bind expression to include form field values or other form control
attributes as part of the source specification. You can bind to HTML format form controls only. For detailed
information on using bind expressions see Using Ajax Data and Development Features in the Developing
ColdFusion Applications. In border type layouts, a center layout area always takes up any space that is not used
by the other areas, even if you do not specify a cflayoutarea tag with a center position attribute. Therefore,
if you want only two layout areas in either direction, one of the two must be the center area, or you must explicitly
size the two areas to take up the full layout area.
When you nest layouts, set the inner layout area initial sizes appropriately to ensure that they appear.Use the
following JavaScript functions to enable, disable, show, hide, expand, collapse, and select layout areas:
Function

Description

ColdFusion.Layout.createTab

Creates a tab in an existing tabbed layout.

ColdFusion.Layout.disableTab

Disables the specified tab so it cannot be selected.

ColdFusion.Layout.enableTab

Enables the specified tab so users can select it and
display the area contents.

ColdFusion.Layout.hideTab

Hides a tab.

ColdFusion.Layout.selectTab

Selects a tab and displays the layout area contents.

ColdFusion.Layout.showTab

Shows a tab that was hidden using the inithide attri
bute or the hideTab() function.

ColdFusion.Layout.collapseArea

Collapses an area of a border layout.

ColdFusion.Layout.expandArea

Expands a collapsed area of a border layout.

ColdFusion.Layout.getTabLayout

Hides an area of a border layout.

ColdFusion.Layout.hideArea

Hides an area of a border layout.

ColdFusion.Layout.showArea

Shows an area of a border layout that was hidden
using the inithide attribute or the hideArea() funct
ion.

ColdFusion.Layout.hideAccordion

Hides an accordion.

© 2014 Adobe Systems Incorporated. All rights reserved.

762

Adobe ColdFusion Documentation

ColdFusion.Layout.showAccordion

Shows an accordion that was hidden using the inithi
de attribute or the hideArea() function.

ColdFusion.Layout.selectAccordion

Selects an accordion and displays the layout area
contents.

ColdFusion.Layout.collapseAccordion

Collapses an area of an accordion layout.

ColdFusion.Layout.expandAccordion

Expands a collapsed area of an accordion layout.

Note
When you use the style attribute to specify the background color of a border layout area,
specify a height style of 100% to make the background color cover the entire layout area. This
is because the style specification applies to an inner content area of the layout area, not the
layout area itself, and the 100% specification ensures that the content area takes up all available
space in the layout area.

Example

The following example creates a three-tabbed layout and lets you use buttons to dynamically control the second tab.

© 2014 Adobe Systems Incorporated. All rights reserved.

763

Adobe ColdFusion Documentation






Atab


This is text in layout area 1


This is text in layout area 2


This is text in layout area 3














© 2014 Adobe Systems Incorporated. All rights reserved.

764

Adobe ColdFusion Documentation

cfldap
Description

Provides an interface to a Lightweight Directory Access Protocol (LDAP) directory server, such as the Netscape
Directory Server.
Category

Internet protocol tags
Syntax



Note
You can specify this tag's attributes in an attributeCollection attribute whose value is a
structure. Specify the structure name in the attributeCollection attribute and use the tag's
attribute names as structure keys.

See also

cfftp, cfhttp, cfmail, cfmailparam, cfpop, Managing LDAP Directories in the Developing ColdFusion
Applications
History

© 2014 Adobe Systems Incorporated. All rights reserved.

765

Adobe ColdFusion Documentation

ColdFusion 11: Added 3 new attributes: clientcert, clientcertpassword, and usetls. Removed the filterFile attribute.
ColdFusion 8: Added the ability to use a comma as a delimiter when specifying a list of variables in the returnAsB
inary attribute, for example, returnAsBinary="objectGUID,objectSID". Previously, the allowed delimiter
was a space.ColdFusion MX 7: Added the returnAsBinary attribute. Added SSL V2 client based authentication;
this means that ColdFusion supports the CFSSL_CLIENT_AUTH option. If CFSSL_CLIENT_AUTH is selected,
ColdFusion assumes that the first certificate in the cacerts (or the certificate database) contains the Client
Certificate.ColdFusion MX:
Changed the name attribute behavior: this tag validates the query name in the name attribute.
Changed sorting behavior: this tag does not support client-side sorting of query results. (It supports
server-side sorting; use the sort and sortcontrol attributes.)
Changed how results are sorted: server-side sorting results might be sorted slightly differently than in
ColdFusion 5. If you attempt a sort against a server that does not support it, ColdFusion MX throws an error.
Deprecated the filterConfig and filterFile attributes. They might not work, and might cause an error,
in later releases.
Attributes

Attribute

Req/Opt

Default

action

Required

query

server

Required

© 2014 Adobe Systems Incorporated. All rights reserved.

Description
query: returns LDAP
entry information only.
Requires name, start,
and attributes attrib
utes.
add: adds LDAP entries
to LDAP server.
Requires attributes
attribute.
modify: modifies
LDAP entries, except
distinguished name dn
attribute, on LDAP
server. Requires dn.
See modifyType attrib
ute.
modifyDN: modifies
distinguished name
attribute for LDAP
entries on LDAP server.
Requires dn.
delete: deletes LDAP
entries on an LDAP
server. Requires dn.
Host name or IP address
of LDAP server.

766

Adobe ColdFusion Documentation

attributes

Required if action = "Qu
ery", "Add", "ModifyD
N", or "Modify"

delimiter

Optional

For queries:
comma-delimited list of
attributes to return. For
queries, to get all
attributes, specify "*". If
action = "add" or "mo
dify", you can specify a
list of update columns.
Separate attributes with a
semicolon. If action = "
ModifyDN", ColdFusion
passes attributes to the
LDAP server without
syntax checking.
; (semicolon)

Separator between
attribute name-value
pairs. Use this attribute if
either of these situations
exist:
The attributes attrib
ute specifies more than
one item.
An attribute contains
the default delimiter
(semicolon), for
example: mgrpmsgrej
ecttext;lang-en
Used by query, add,
and modify actions,
and by cfldap to
output multi-value
attributes. For example,
if $ (dollar sign), you
could specify "cn = Do
uble Tree Inn$stre
et = 1111 Elm; Suite
100, where the
semicolon is part of the
street value.

dn

Required if action = "Ad
d","Modify", "ModifyD
N", or "delete"

© 2014 Adobe Systems Incorporated. All rights reserved.

Distinguished name, for u
pdate action, for
example, "cn = Bob Jen
sen, o = Ace Industry
, c = US"

767

Adobe ColdFusion Documentation

filter

Optional

maxRows

Optional

modifyType

Optional

"objectclass = *"

Search criteria for actio
n = "query". List
attributes in the form: "(a
ttribute operator va
lue)" For example: "(s
n = Smith)"
Maximum number of
entries for LDAP queries.

replace

How to process an
attribute in a multi-value
list:
add: appends it to any
attributes.
delete: deletes it from
the set of attributes.
replace: replaces it
with specified attributes.
You cannot add an
attribute that is already
present or that is empty.

name

Required if action = "Qu
ery"

Name of LDAP query. The
tag validates the value.

password

Required if secure = "CF
SSL_BASIC"

Password that
corresponds to user
name. If secure = "CFS
SL_BASIC", V2 encrypts
the password before
transmission.

port

Optional

389

rebind

Optional

no

© 2014 Adobe Systems Incorporated. All rights reserved.

Port.
yes: attempts to rebind
referral callback and
reissue query by
referred address using
original credentials.
no: referred
connections are
anonymous.

768

Adobe ColdFusion Documentation

referral

Optional

Integer. Number of hops
allowed in a referral. A
value of 0 disables
referred addresses for
LDAP; no data is
returned.

returnAsBinary

Optional

A space-delimited list of
columns that are to be
returned as binary values.

scope

Optional

oneLevel

Scope of search, from
entry specified in start a
ttribute for action = "Qu
ery".
oneLevel: entries one
level below entry.
base: only the entry.
subtree: entry and all
levels below it.

secure

Optional

Security to employ, and
required information. If
you specify this attribute,
its value must be one of
the following:
CFSSL_BASIC - Provi
des V2 SSL encryption
and server
authentication.
CFSSL_CLIENT_AUTH
- This is
mandatory if
client
certificate based
authentication is
to be used with
CFLDAP tag . This
is to be used
with
clientcert and
clientcertpasswor
d.

© 2014 Adobe Systems Incorporated. All rights reserved.

769

Adobe ColdFusion Documentation

separator

Optional

sort

Optional

sortControl

Optional

start

Required if action = "Qu
ery"

startRow

Optional

1

Used with action = "qu
ery". First row of LDAP
query to insert into a
ColdFusion query.

timeout

Optional

60000

Maximum length of time,
in milliseconds, to wait for
LDAP processing.

username

Required if secure = "CF
SSL_BASIC"

(anonymous)

User ID.

© 2014 Adobe Systems Incorporated. All rights reserved.

, (comma)

Delimiter to separate
attribute values of
multi-value attributes.
Used by query, add, and
modify actions, and by c
fldap to output
multi-value attributes. For
example, if $ (dollar sign),
the attributes attribute
could be "objectclass
= top$person", where
the first value of objectc
lass is top, and the
second value is person.
This avoids confusion if
values include commas.
Attributes by which to sort
query results. Use a
comma delimiter.

asc

nocase:
case-insensitive sort.
asc: ascending (a to z)
case-sensitive sort.
desc: descending (z to
a) case-sensitive sort.
You can enter a
combination of sort
types; for example, sor
tControl = "nocase
, asc".
Distinguished name of
entry to be used to start a
search.

770

Adobe ColdFusion Documentation

clientcert

Optional

The full path to the key
store file that contains the
client certificate.

clientcertpassword

Optional

Password for the client
certificate.

usetls

Optional

true/false

Whether to use the
startTls extension for
initiating SSL over normal
LDAP port.

Usage

If you use the query action, cfldap creates a query object, allowing access to information in the query variables, as
follows:
Variable name

Description

queryname.recordCount

Number of records returned by query

queryname.currentRow

Current row of query that cfoutput is processing

queryname.columnList

Column names in query

If you use the security="CFSSL_BASIC" option, ColdFusion determines whether to trust the server by comparing
the server's certificate with the information in the jre/lib/security/cacerts keystore of the JRE used by ColdFusion.
The ColdFusion default cacerts file contains information about many certificate granting authorities. If you must
update the file with additional information, you can use the keytool utility in the ColdFusion jre/bin directory to import
certificates that are in X.509 format. For example, enter the following:

keytool -import -keystore cacerts -alias ldap -file ldap.crt -keypass bl19mq

Then restart ColdFusion. The keytool utility initial keypass password is "change it". For more information on using
the keytool utility, see the Sun JDK documentation.Characters that are illegal in ColdFusion can be used in LDAP
attribute names. As a result, the cfldap tag could create columns in the query result set whose names contain
illegal characters and are, therefore, inaccessible in CFML. In ColdFusion, illegal characters are automatically
mapped to the underscore character; therefore, column names in the query result set might not exactly match the
names of the LDAP attributes.
For usage examples, see the Developing ColdFusion Applications.
Example

© 2014 Adobe Systems Incorporated. All rights reserved.

771

Adobe ColdFusion Documentation

cfldap Example
Provides an interface to LDAP directory servers. The example uses the
University of Connecticut public LDAP server. For more public LDAP servers,
see http://www.emailman.com.
Enter a name and search the public LDAP resource.
An asterisk before or after the name acts as a wildcard.












#results.recordCount# matches found 


Name
Organization
Title
E-Mail
Phone


#cn#
#o#
#title#

#mail#
#telephonenumber#







Enter a name to search in the database.




© 2014 Adobe Systems Incorporated. All rights reserved.

772

Adobe ColdFusion Documentation

cflocation
Description

Stops execution of the current page and opens a ColdFusion page or HTML file.
Category

Flow-control tags, Page processing tags
Syntax



Note
You can specify this tag's attributes in an attributeCollection attribute whose value is a
structure. Specify the structure name in the attributeCollection attribute and use the tag's
attribute names as structure keys.

See also

cfabort, cfbreak, cfexecute, cfexit, cfif, cfloop, cfswitch, cfthrow, cftry
History

ColdFusion 11: The addToken attribute is modified. If Secure Profile is enabled, addToken's default value will be
"false".
ColdFusion 8: Added the statusCode attribute.
Attributes

Attribute

Req/Opt

url

Required

© 2014 Adobe Systems Incorporated. All rights reserved.

Default

Description
URL of HTML file or
CFML page to open.

773

Adobe ColdFusion Documentation

addToken

Optional

Default value is false
(when the secure profile
enabled).

The clientManagement
attribute must be enabled
(see cfapplication).
yes: appends client
variable information to
URL.
no
New in ColdFusion 11: If
Secure Profile is enabled,
addToken's default value
will be false.

© 2014 Adobe Systems Incorporated. All rights reserved.

774

Adobe ColdFusion Documentation

statusCode

Optional

302

The HTTP status code, as
follows:
300
HTTP_MULTIPLE_CH
OICES: The requested
address refers to more
than one entity.
301
HTTP_MOVED_PERM
ANENTLY: The page is
assigned a new URI.
The change is
permanent.
302
HTTP_MOVED_TEMP
ORARILY: The page is
assigned a new URI.
The change is
temporary.
303
HTTP_SEE_OTHER:
The client should try
another network
address.
304
HTTP_NOT_MODIFIED
: The requested
resource has not been
modified.
305
HTTP_USE_PROXY:
The requested resource
must be accessed
through the proxy given
by the Location field.
307
HTTP_TEMPORARY_
REDIRECT: The
requested data
temporarily resides at a
new location.
The status codes from
304 to 307 do not
redirect you to the page
specified in a URL,
unless you also follow
the guidelines specified
in the most recent
HTTP RFC.

Usage

© 2014 Adobe Systems Incorporated. All rights reserved.

775

Adobe ColdFusion Documentation

You might write a standard message or response in a file, and call it from several applications. Use this tag to
redirect the user's browser to the standard file. This tag has no effect if you use it after the cfflush tag on a page.
Note
When using cfabort, cflocation, or cfcontent tags, the OnAbort method is invoked
instead on OnRequestEnd.

Example

cflocation Example
This tag redirects the browser to a web resource; normally, you would use this
tag to go to a CF page or an HTML file on the same server. The addToken attribute
lets you send client information to the target page.
If you remove the comments, this code redirects you to CFDOCS home page:


© 2014 Adobe Systems Incorporated. All rights reserved.

776

Adobe ColdFusion Documentation

cflock
Description

Ensures the integrity of shared data. Instantiates the following kinds of locks:
Exclusive - Allows single-thread access to the CFML constructs in its body. The tag body can be executed by
one request at a time. No other requests can start executing code within the tag while a request has an
exclusive lock. ColdFusion issues exclusive locks on a first-come, first-served basis.
Read-only - Allows multiple requests to access CFML constructs within the tag body concurrently. Use a
read-only lock only when shared data is read and not modified. If another request has an exclusive lock on
shared data, the new request waits for the exclusive lock to be released.
Category

Application framework tags
Syntax





Note
You can specify this tag's attributes in an attributeCollection attribute whose value is a
structure. Specify the structure name in the attributeCollection attribute and use the tag's
attribute names as structure keys.

See also

cfapplication, cfassociate, cfmessagebox, Using Persistent Data and Locking in the Developing
ColdFusion Applications
History

ColdFusion 8: Added Request value to scope attribute.
Attributes

Attribute

Req/Opt

© 2014 Adobe Systems Incorporated. All rights reserved.

Default

Description

777

Adobe ColdFusion Documentation

timeout

Required

Maximum length of time,
in seconds, to wait to
obtain a lock. If lock is
obtained, tag execution
continues. Otherwise,
behavior depends on thr
owOnTimeout attribute
value. If you set timout=
"0", the timeout is
determined by the
"Timeout Requests after x
" setting in the ColdFusion
Administrator Settings
page, if that setting is
enabled. However, if the
setting is not enabled, and
you set timeout="0",
ColdFusion can wait
indefinitely to obtain the
lock.

name

Optional

Locks name. Mutually
exclusive with the scope
attribute. Only one
request can execute the
code within a {{cflock}}tag
with a given name at a
time. Cannot be an empty
string.Permits
synchronizing access to
resources from different
parts of an application.
Lock names are global to
a ColdFusion server. They
are shared among
applications and user
sessions, but not
clustered servers.

© 2014 Adobe Systems Incorporated. All rights reserved.

778

Adobe ColdFusion Documentation

Optional

scope

Locks scope. Mutually
exclusive with the name at
tribute. Only one request
in the specified scope can
execute the code within
this tag (or within any
other cflock tag with the
same lock scope) at a
time.
Application
Request
Server
Session

throwOnTimeout

Optional

yes

How time-out conditions
are handled:
yes: exception is
generated for the
time-out.
no: execution continues
past this tag.

Optional

type

exclusive

readOnly: lets more
than one request read
shared data.
exclusive: lets one
request read or write
shared data.

Note
Limit the scope of code that updates shared data structures, files, and CFXs. Exclusive locks are
required to ensure the integrity of updates, but read-only locks are faster. In a
performance-sensitive application, substitute read-only locks for exclusive locks where possible,
for example, when reading shared data.

Usage

ColdFusion is a multi-threaded server; it can process multiple page requests at a time. Use the cflock tag for
these purposes:
To ensure that modifications to shared data and objects made in concurrently executing requests occur
sequentially.
Around file manipulation constructs, to ensure that file updates do not fail because files are open for writing
by other applications or tags.
Around CFX invocations, to ensure that ColdFusion can safely invoke CFXs that are not implemented in a
thread-safe manner. (This applies only to CFXs developed in C+.) To work safely with ColdFusion, a C+ CFX
that maintains and manipulates shared (global) data structures must be made thread-safe; however, this

© 2014 Adobe Systems Incorporated. All rights reserved.

779

Adobe ColdFusion Documentation

requires advanced knowledge. You can use a CFML custom tag wrapper around a CFX to make its
invocation thread-safe. When you display, set, or update variables in a shared scope, use the scope attribute
to identify the scope as Server, Application or Session.
Deadlocks

A deadlock is a state in which no request can execute the locked section of a page. After a deadlock occurs, neither
user can break it, because all requests to the protected section of the page are blocked until the deadlock can be
resolved by a lock time-out.
The cflock tag uses kernel level synchronization objects that are released automatically upon time out and/or the
abnormal termination of the thread that owns them. Therefore, while processing a cflock tag, ColdFusion never
deadlocks for an infinite period. However, large time-outs can block request threads for long periods, and radically
decrease throughput. To prevent this, always use the minimum time-out value.Another cause of blocked request
threads is inconsistent nesting of cflock tags and inconsistent naming of locks. If you nest locks, everyone
accessing the locked variables must consistently nest cflock tags in the same order. Otherwise, a deadlock can
occur. These examples show situations that cause deadlocks:
Example deadlock with two users
User 1

User 2

Locks the session scope.

Locks the Application scope.

Deadlock: Tries to lock the Application scope, but it is
already locked by User 2.

Deadlock: Tries to lock the Session scope, but it is
already locked by User 1.

The following deadlock could occur if you tried to nest an exclusive lock inside a read lock:
Example deadlock with one user
User 1
Locks the Session scope with a read lock.
Attempts to lock the Session scope with an exclusive lock.
Deadlock: Cannot lock the Session scope with an exclusive lock because the scope is already locked for reading.

The following code shows this scenario:


...............

.........



To avoid a deadlock, everyone who nests locks must do so in a well-specified order and name the locks
consistently. If you must lock access to the Server, Application, and Session scopes, do so in this order:

© 2014 Adobe Systems Incorporated. All rights reserved.

780

Adobe ColdFusion Documentation

1.
2.
3.
4.
5.
6.

Lock the Session scope. In the cflock tag, specify scope = "session".
Lock the Application scope. In the cflock tag, specify scope = "Application".
Lock the Server scope. In the cflock tag, specify scope = "server".
Unlock the Server scope.
Unlock the Application scope.
Unlock the Session scope.
Note
If you do not have to lock a scope, you can skip any pair of these lock/unlock steps. For
example, if you do not have to lock the Server scope, you can skip Steps 3 and 4. Similar
rules apply for named locks.

For more information, see the following:
Using Persistent Data and Locking in the Developing ColdFusion Applications.
Locking thread data and resource access in the Developing ColdFusion Applications (for information
on locking the Request scope when you use the cfthread tag to create multithreaded ColdFusion
applications).
ColdFusion Locking Best Practices, on the Adobe website.
Example

















© 2014 Adobe Systems Incorporated. All rights reserved.

781

Adobe ColdFusion Documentation








cflock Example



Thanks for shopping E-Turtleneck. You chose size #form.size#,
color #form.color#.












E-Turtleneck has now sold #application.number# turtlenecks!






E-Turtleneck has sold #application.number# turtlenecks to date.



Congratulations! You selected the most comfortable turtleneck in the world.
Please select color and size.


Select a color.

red
white
blue
turquoise
black
forest green


© 2014 Adobe Systems Incorporated. All rights reserved.

782

Adobe ColdFusion Documentation




Select a size.

XXsmall
Xsmall
small
medium
large
Xlarge




Press Submit when you are finished making your selection.
 



© 2014 Adobe Systems Incorporated. All rights reserved.

783

Adobe ColdFusion Documentation




© 2014 Adobe Systems Incorporated. All rights reserved.

784

Adobe ColdFusion Documentation

cflog
Description

Writes a message to a log file.
Category

Data output tags
Syntax



Note
You can specify this tag's attributes in an attributeCollection attribute whose value is a
structure. Specify the structure name in the attributeCollection attribute and use the tag's
attribute names as structure keys.

See also

cfcol, cfcontent, cfoutput, cftable, writeLog()
History

ColdFusion MX: Deprecated the thread, date, and time attributes. They might not work, and might cause an
error, in later releases. (In earlier releases, these attributes determined whether the respective data items were
output to the log. In ColdFusion MX, this data is always output.)
Attributes

Attribute

Req/Opt

text

Required

application

Optional

© 2014 Adobe Systems Incorporated. All rights reserved.

Default

Description
Message text to log.

yes

yes: logs the
application name, if it is
specified in a cfappli
cation tag or
Application.cfc file.
no

785

Adobe ColdFusion Documentation

file

Optional

Message file. Specify only
the main part of the
filename. For example, to
log to the Testing.log file,
specify "Testing". The file
must be located in the
default log directory. You
cannot specify a directory
path. If the file does not
exist, it is created
automatically, with the
extension .log.

log

Optional

If you omit the file attrib
ute, writes messages to
standard log file. Ignored,
if you specify file attribu
te.
Application: writes
to Application.log,
normally used for
application-specific
messages.
Scheduler: writes to
Scheduler.log, normally
used to log the
execution of scheduled
tasks.

type

Optional

Information

Type (severity) of the
message:
Information
Warning
Error
Fatal

Usage

This tag logs custom messages to standard or custom log files. You can specify a file for the log message or send
messages to the default application or scheduler log. The log message can include ColdFusion expressions. Log
files must have the extension .log and must be located in the ColdFusion log directory. Log entries are written as
comma-delimited lists with these fields:
type
thread
date
time
application
textValues are enclosed in double quotation marks. If you specify no for the application attribute, the
corresponding entry in the list is empty.
You can disable cflogtag execution. For more information, see the ColdFusion Administrator Basic Security

© 2014 Adobe Systems Incorporated. All rights reserved.

786

Adobe ColdFusion Documentation

page. The following example logs the name of a user that logs on an application. The message is logged to
the file myAppLog.log in the ColdFusion log directory. It includes the date, time, and thread ID, but not the
application name.



For example, if a user enters "Sang Thornfield" in a form's username field, this entry is added to the
myApplog.log file entry:"Information","153","02/28/01","14:53:40",,"User Sang Thornfield logged on."

© 2014 Adobe Systems Incorporated. All rights reserved.

787

Adobe ColdFusion Documentation

cflogin
Description

A container for user login and authentication code. ColdFusion runs the code in this tag if a user is not already
logged in. You put code in the tag that authenticates the user and identifies the user with a set of roles. Used with c
floginuser tag.
Category

Security tags
Syntax


...



See also

cfloginuser, cflogout, GetAuthUser, GetUserRoles, IsUserInAnyRole, IsUserInRole, IsUserLogge
dIn, Securing Applications in the Developing ColdFusion Applications
History

ColdFusion 11: Added 2 new attributes allowconcurrent and usebasicauth.
ColdFusion 8: The applicationtoken attribute lets you specify a unique application identifier for each
application, or the same value for multiple applications.ColdFusion MX 6.1: Changed behavior: the cflogin variabl
e exists when ColdFusion receives a request with NTLM or Digest (HTTP Negotiated header) authentication
information.ColdFusion MX: Added this tag.
Attributes

Attribute

Req/Opt

© 2014 Adobe Systems Incorporated. All rights reserved.

Default

Description

788

Adobe ColdFusion Documentation

applicationtoken

Optional

The current application
name

The login that applies to
the application. To let
users log in to only one
application, specify a
unique value for that
application. To let users
log in to multiple
applications, specify the
same value for those
applications. If you do not
set a value for the appli
cationtoken attribute,
the default value is CFAUT
HORIZATION_applicat
ionname.

cookiedomain

Optional

idletimeout

Optional

1800

Time interval, in seconds,
after which ColdFusion
logs off the user.

allowconcurrent

Optional

true

If concurrent login
sessions should be
allowed.

usebasicauth

Optional

true

If basic authentication
should be used to validate
the login.

Domain of the cookie that
is used to mark a user as
logged in. Use this
attribute to enable a user
login cookie to work with
multiple clustered servers
in the same domain.

Usage

The body of this tag executes only if there is no logged-in user. When using application-based security, you put code
in the body of the cflogin tag to check the user-provided ID and password against a data source, LDAP directory,
or other repository of login identification. The body must include a cfloginuser tag to establish the authenticated
user's identity in ColdFusion.
You control the data source and are responsible for coding the SQL within the cflogin tag; make sure that the
associated database has user, password, and role information.
The cflogin tag has a built-in cflogin structure that contains two variables, cflogin.name and cflogin.pas
sword, if the page is executing in response to any of the following:
Submission of a form that contains input fields with the names j_username and j_password.
A request that uses HTTP Basic authentication and, therefore, includes an Authorization header with the user
name and password.
A request that uses NTLM or Digest authentication. In this case, the username and password are hashed

© 2014 Adobe Systems Incorporated. All rights reserved.

789

Adobe ColdFusion Documentation

using a one-way algorithm in the Authorization header; ColdFusion gets the username from the web server
and sets the cflogin.password value to the empty string.
You can use these values in the cflogin tag body to authenticate the user, and, in the cfloginuser tag,
to log the user in. The structure is only available in the cflogin tag body.
Example

The following example shows a simple authentication. This code is typically in the Application.cfc onRequestStart
method or in the application.cfm page.















The following view-only example checks the user ID and password against a data source:


SELECT Roles FROM SecurityRoles
WHERE username=




© 2014 Adobe Systems Incorporated. All rights reserved.

790

Adobe ColdFusion Documentation

cfloginuser
Description

Identifies an authenticated user to ColdFusion. Specifies the user ID and roles. Used within a cflogin tag.
Category

Security tags
Syntax



See also

cflogin, cflogout, GetAuthUser, GetUserRoles, IsUserInAnyRole, IsUserInRole, IsUserLoggedIn,
Securing Applications in the Developing ColdFusion Applications
History

ColdFusion MX 6.1: Changed behavior: if the Session scope is enabled, and the cfapplication tag loginStor
age attribute is set to Session, the login remains in effect until the session expires or the user is logged out by the c
flogout tag.
ColdFusion MX: Added this tag.
Attributes

Attribute

Req/Opt

Default

Description

name

Required

A user name.

password

Required

A user password.

roles

Required

A comma-delimited list of
role identifiers.ColdFusion
processes spaces in a list
element as part of the
element.

Usage

Used inside the cflogin tag to identify the authenticated user to ColdFusion. After you call this function, the GetAu
thUser and IsUserInRole return the user name and role information.

© 2014 Adobe Systems Incorporated. All rights reserved.

791

Adobe ColdFusion Documentation

Note
By default, the user information is stored as memory-only cookies. The cfapplication tag or
the Application.cfc This.loginStorage variable can specify that login information is stored in the
Session scope.

Example

See cflogin.

© 2014 Adobe Systems Incorporated. All rights reserved.

792

Adobe ColdFusion Documentation

cflogout
Description

Logs the current user out. Removes knowledge of the user ID, password, and roles from the server. If you do not
use this tag, the user is automatically logged out when the session ends.
Category

Security tags
Usage



See also

cflogin, cfloginuser, GetAuthUser, GetUserRoles, IsUserInAnyRole, IsUserInRole, IsUserLogged
In, Securing Applications in Developing ColdFusion Applications
History

ColdFusion 11: Added the session attribute.
ColdFusion MX 6.1: Changed behavior: if the Session scope is enabled, a login remains in effect until the session
expires or the user is logged out by the cflogout tag.
ColdFusion MX: Added this tag.
Attribute

Attribute

Description

Default

session

When invoked which session
should be logged out.

current

This is a string. The possible values
are:
all
current
others

Example

© 2014 Adobe Systems Incorporated. All rights reserved.

793

Adobe ColdFusion Documentation




Authorized user: #getAuthUser()#

Authorized user: #getAuthUser()#

© 2014 Adobe Systems Incorporated. All rights reserved.

794

Adobe ColdFusion Documentation

cfloop
Description

Looping is a programming technique that repeats a set of instructions or displays output repeatedly until one or more
conditions are met. This tag supports the following types of loops:
cfloop: index loop
cfloop: conditional loop
cfloop: looping over a date or time range
cfloop: looping over a query
cfloop: looping over a list, a file, or an array
cfloop: looping over a COM collection or structure
For more information, see cfloop and cfbreak and Populating arrays with data in the Developing ColdFusion
Applications.
Category

Flow-control tags

© 2014 Adobe Systems Incorporated. All rights reserved.

795

Adobe ColdFusion Documentation

cfloop: index loop
Description

An index loop repeats for a number of times that is determined by a numeric value. An index loop is also known as a
FOR loop.
Syntax


HTML or CFML code ...


See also

cfabort, cfbreak, cfcontinue, cfdirectory, cfexecute, cfexit, cfif, cflocation, cfrethrow, cfsw
itch, cfthrow, cftry; cfloop and cfbreak in the Developing ColdFusion Applications
Attributes

Attribute

Req/Opt

Default

index

Required

Index value. ColdFusion
sets it to the from value
and increments or
decrements by step valu
e, until it equals the to val
ue.

from

Required

Beginning value of index.

to

Required

Ending value of index.

step

Optional

charset

optional

1

Description

Step by which to
increment or decrement
the index value.
Charset to use when
reading in a file
line-by-line.

Usage

Using anything other than integer values in the from and to attributes of an index loop can product unexpected
results. For example, if you increment through an index loop from 1 to 2, with a step of 0.1, ColdFusion outputs
"1,1.1,1.2,...,1.9", but not "2". This is a programming language problem regarding the internal representation of

© 2014 Adobe Systems Incorporated. All rights reserved.

796

Adobe ColdFusion Documentation

floating point numbers.
Note
The to value is evaluated once, when the cfloop tag is encountered. Any change to this value
within the loop block, or within the expression that evaluates to this value, does not affect the
number of times the loop is executed.

Example

In this example, the code loops five times, displaying the index value each time:


The loop index is #LoopCount#.



The output of this loop is as follows:

The
The
The
The
The

loop
loop
loop
loop
loop

index
index
index
index
index

is
is
is
is
is

1.
2.
3.
4.
5.

In this example, the code loops four times, displaying the index value each time. The value of j is decreased by
one for each iteration. This does not affect the value of to, because it is a copy of j that is made before entering the
loop.



The loop index is #LoopCount#.




The output of this loop is as follows:

The
The
The
The

loop
loop
loop
loop

index
index
index
index

is
is
is
is

1.
2.
3.
4.

As before, the value of j is decremented by one for each iteration, but this does not affect the value of to, because
its value is a copy of j that is made before the loop is entered.
In this example, step has the default value, 1. The code decrements the index:

© 2014 Adobe Systems Incorporated. All rights reserved.

797

Adobe ColdFusion Documentation


The loop index is #LoopCount#.



The output of this loop is as follows:

The
The
The
The
The

loop
loop
loop
loop
loop

index
index
index
index
index

is
is
is
is
is

5.
4.
3.
2.
1.

© 2014 Adobe Systems Incorporated. All rights reserved.

798

Adobe ColdFusion Documentation

cfloop: conditional loop
Description

A conditional loop iterates over a set of instructions as long as a condition is True. To use this type of loop correctly,
the instructions must change the condition every time the loop iterates, until the condition is False. Conditional loops
are known as WHILE loops, as in, "loop WHILE this condition is true."
Syntax


...


See also

cfabort, cfbreak, cfcontinue, cfexecute, cfexit, cfif, cflocation, cfswitch, cfthrow, cftry; cflo
op and cfbreak in the Developing ColdFusion Applications
Attributes

Attribute

Req/Opt

condition

Required

Default

Description
Condition that controls the
loop.

Example

The following example increments CountVar from 1 to 5.






The loop index is #CountVar#.



The output of this loop is as follows:

The
The
The
The
The

loop
loop
loop
loop
loop

index
index
index
index
index

is
is
is
is
is

1.
2.
3.
4.
5.

© 2014 Adobe Systems Incorporated. All rights reserved.

799

Adobe ColdFusion Documentation

cfloop: looping over a date or time range
Description

Loops over the date or time range specified by the from and to attributes. By default, the step is 1 day, but you can
change the step by creating a timespan.
Syntax




See also

cfabort, cfbreak, cfcontinue, cfdirectory, cfexecute, cfexit, cfif, cflocation, cfrethrow, cfsw
itch, cfthrow, cftry; cfloop and cfbreak in the Developing ColdFusion Applications
Attributes

Attribute

Req/Opt

Default

from

Required

The beginning of the date
or time range.

to

Required

The end of the date or
time range.

index

Required

Index value. ColdFusion
sets it to the from value
and increments by the st
ep value, until it equals
the to value.

step

Optional

1 day

Description

Step, expressed as a
timespan, by which the
index increments.

Example

The following example loops from today's date to today's date plus 30 days, stepping by 7 days at a time and
displaying the date:

© 2014 Adobe Systems Incorporated. All rights reserved.

800

Adobe ColdFusion Documentation




#dateformat(i, "mm/dd/yyyy")#



The following example displays the time in 30-minute increments, starting from midnight and ending 23 hours, 59
minutes, and 59 seconds later:




#TimeFormat(i, "hh:mm tt")#



© 2014 Adobe Systems Incorporated. All rights reserved.

801

Adobe ColdFusion Documentation

cfloop: looping over a query
Description

A loop over a query executes for each record in a query record set. The results are similar to those of the cfoutput
tag. During each iteration, the columns of the current row are available for output. The cfloop tag loops over tags
that cannot be used within a cfoutput tag.
Syntax




See also

cfabort, cfbreak, cfcontinue, cfexecute, cfexit, cfif, cflocation, cfoutput, cfswitch, cfthrow,
cftry; For more information, see cfloop and cfbreak in the Developing ColdFusion Applications
Attributes

Attribute

Req/Opt

query

Required

Default

Description
Query that controls the
loop. When using query
attribute, you can now use
dynamic references in
addition to string, as
shown in the following
code:



startRow

Optional

First row of query that is
included in the loop.

endRow

Optional

Last row of query that is
included in the loop.

© 2014 Adobe Systems Incorporated. All rights reserved.

802

Adobe ColdFusion Documentation

group

Optional

Query column to use to
group sets of records.
Eliminates adjacent
duplicate rows when data
is sorted. Use if you
retrieved a recordset
ordered on one or more
query columns. For
example, if a recordset is
ordered on "Customer_I
D", you can group the
output on "Customer_ID.
".

Example


SELECT * FROM Messages


#Message_ID#



The cfloop tag also iterates over a record set with dynamic start and stop points. This gets the next n sets of
records from a query. This example loops from the fifth through the tenth record returned by the MessageRecords
query:




#MessageRecords.Message_ID#



The loop stops when there are no more records, or when the current record index is greater than the value of the en
dRow attribute. The following example combines the pages that are returned by a query of a list of page names into
one document, using the cfinclude tag:


SELECT TemplateName
FROM Templates





© 2014 Adobe Systems Incorporated. All rights reserved.

803

Adobe ColdFusion Documentation

cfloop: looping over a list, a file, or an array
Description

Looping over a list steps through elements contained in any of these entities:
A variable
A value that is returned from an expression
An array
A file Looping over a file does not open the entire file in memory.
Syntax



See also

cfabort, cfbreak, cfcontinue, cfexecute, cfexit, cfif, cflocation, cfswitch, cfthrow, cftry; cflo
op and cfbreak in the Developing ColdFusion Applications
History

ColdFusion 8: Added the characters, file, and array attributes.
Attributes

Attribute

Req/Opt

index

Required

In a list, file, or array loop,
the variable to receive the
next element.

list

Required unless you
specify a filename in the f
ile attribute

A list, variable, or
filename; contains a list.

array

Optional

An array.

© 2014 Adobe Systems Incorporated. All rights reserved.

Default

Description

804

Adobe ColdFusion Documentation

characters

Optional

The number of characters
to read during each
iteration of the loop from
the file specified in the fi
le attribute. If the value of
the characters attribute
is more than the number
of characters in the file,
ColdFusion uses the
number of characters in
the file.

delimiters

Optional

Characters that separate
items in list.

file

Optional

The absolute pathname of
the on-disk or in-memory
text file to read, one line at
a time. This is helpful
when reading large text
files, because you can
reuse the value of the
index variable, which
contains the current line of
the file. When the loop
completes, ColdFusion
closes the file.

charset

Optional

A charset to use when
reading the file. See  for a list of common
charsets.

Example

This loop displays four names:


#ListElement#



You can put more than one character in the delimiters attribute, in any order. For example, this loop processes
commas, colons, and slashes as list delimiters:


#ListElement#



© 2014 Adobe Systems Incorporated. All rights reserved.

805

Adobe ColdFusion Documentation

ColdFusion skips the second and subsequent consecutive delimiters between list elements. Thus, in the example,
the two colons between "George" and "Ringo" are processed as one delimiter.
To loop over each line of a file, use the tag as follows:


#line#



To read a specified number of characters from a text file during each iteration of the loop, use the tag as follows:


#chars#



When you read the following text file, ColdFusion reads 12 characters during each iteration of the loop; the result
appears as follows:
Text file

Result

This is line 1.
This is line 2.
This is line 3.
This is line 4.
This is line 5.
This is line 6.
This is line 7.
This is line 8.
This is line 9.
This is line 10.
This is line 11.

This is line1. This isline 2. This is line 3. This is line 4.
Thisis line 5. This is line 6. This is line 7. This is line 8.
This is line 9. This is line 10. This is line 11.

To loop over an array, you can do the following:



#name#



© 2014 Adobe Systems Incorporated. All rights reserved.

806

Adobe ColdFusion Documentation

cfloop: looping over a COM collection or structure
Description

The cfloop collection attribute loops over every object within a COM/DCOM collection object, or every element
in a structure:
A COM/DCOM collection object is a set of similar items referenced as a group. For example, the group of
open documents in an application is a collection.
A structure contains a related set of items, or it can be used as an associative array. Looping is particularly
useful when using a structure as an associative array.
In the loop, each item is referenced by the variable name in the item attribute. The loop executes until all
items have been accessed.
The collection attribute is used with the item attribute. In the example that follows, item is assigned a
variable called file2, so that with each cycle in the cfloop, each item in the collection is referenced. In the
cfoutput section, the name property of the file2 item is referenced for display.
For more information, see Integrating COM and CORBA Objects in CFML Applications in the Developing
ColdFusion Applications.
Example

This example uses a COM object to output a list of files. In this example, FFunc is a collection of file2 objects.

© 2014 Adobe Systems Incorporated. All rights reserved.

807

Adobe ColdFusion Documentation







 #file2.name# 
 


...










Employee
Dept.



#person#
#StructFind(Departments, person)#




#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

808

Adobe ColdFusion Documentation

Tags m-o
This section lists tags starting with alphabets M-O with their description.
cfmail
cfmailparam
cfmailpart
cfmap
cfmapitem
cfmediaplayer
cfmenu
cfmenuitem
cfmessagebox
cfmodule
cfNTauthenticate
cfoauth
cfobject
cfobject: .NET object
cfobject: COM object
cfobject: component object
cfobject: CORBA object
cfobject: Java or EJB object
cfobject: web service object
cfobjectcache
cfoutput

© 2014 Adobe Systems Incorporated. All rights reserved.

809

Adobe ColdFusion Documentation

cfmail
Description

Sends an e-mail message that optionally contains query output, using an SMTP server.
Category

Communications tags, Internet protocol tags
Syntax


encryptionalgorithm = "DES_EDE3_CBC, RC2_CBC, AES128_CBC, AES192_CBC, AES256_CBC">
(Optional) Mail message body and/or cfmailparam tags


© 2014 Adobe Systems Incorporated. All rights reserved.

810

Adobe ColdFusion Documentation

Note
You can specify this tag's attributes in an attributeCollection attribute whose value is a
structure. Specify the structure name in the attributeCollection attribute and use the tag's
attribute names as structure keys.

See also

cfmailparam, cfmailpart, cfpop, cfftp, cfhttp, cfldap, Wrap; Using ColdFusion with mail servers in Send
ing and Receiving E-Mail in the Developing ColdFusion Applications
History

ColdFusion 11: Added the attributes, encrypt, recipientcert, and encryptionalgorithm.
ColdFusion 8.0.1: Added the attribute Remove.
ColdFusion 8: Added priority, useSSL, and useTLS attributes.
ColdFusion MX 7:
The cfmail tag no longer lets you send multipart mail by embedding the entire MIME-encoded message in
the tag body. Use the cfmailpart tag, instead.
The cfmail tag renders non-proportional fonts proportionately. This is a behavior change from ColdFusion
5. ColdFusion MX 7 uses UTF-8 and sends this in the mail header (Content-Type: text/plain; charset=UTF-8).
ColdFusion 5 uses ISO-8859-1 (Latin 1). To avoid this behavior, add the charset="ISO-8859-1" attribute
to restore the default ColdFusion 5 encoding. Alternatively, you can change the encoding on the Mail page in
the ColdFusion Administrator.
ColdFusion MX 6.1:
Added the following attributes: charset, failto, replyto, username, password and wraptext.
Added support for multiple mail servers in the server attribute.
Added several configuration options to the ColdFusion Administrator Mail Settings page.
ColdFusion MX: Added the SpoolEnable attribute.ColdFusion 9: Added support for digitally signing the
mail. The following are the relevant attributes that are newly added: sign, keystore, keystorepassword,
keyalias, keypassword and remove.
Attributes

Attribute

Req/Opt

bcc

Optional

© 2014 Adobe Systems Incorporated. All rights reserved.

Default

Description
Addresses to which to
copy the message,
without listing them in the
message header. To
specify multiple
addresses, separate the
addresses with commas.

811

Adobe ColdFusion Documentation

cc

Optional

charset

Optional

Addresses to which to
copy the message. To
specify multiple
addresses, separate the
address with commas.
Character encoding
selected in ColdFusion
Administrator Mail page; u
tf-8

Character encoding of the
mail message, including
the headers. The following
list includes commonly
used values:
utf-8
iso-8859-1
windows-1252
us-ascii
shift_jis
iso-2022-jp
euc-jp
euc-kr
big5
hz-gb-2312
euc-cn
utf-16
For more information on
character encodings,
see www.w3.org/Intern
ational/O-charset.html.

debug

Optional

failto

Optional

© 2014 Adobe Systems Incorporated. All rights reserved.

no

yes: sends debugging
output to standard
output. By default, if the
console window is
unavailable, ColdFusion
sends output to
cf_root\runtime\logs\col
dfusion-out.log on
server configurations.
no: does not generate
debugging output.
Address to which mailing
systems must send
delivery failure
notifications. Sets the mail
envelope reverse-path
value.

812

Adobe ColdFusion Documentation

from

Required

E-mail message sender:
A static string; for
example, "support@m
ex.com"
A variable; for example,
"#GetUser.EMailAdd
ress#".
This attribute does not
have to be a valid
Internet address; it can
be any text string
without white spaces.

to

Required

Message recipient e-mail
addresses:
Static address, for
example, "support@.
com".
Variable that contains
an address, for
example, "#Form.Ema
il#".
Name of a query
column that contains an
address, for example, "
#EMail#". An e-mail
message is sent for
each returned row.
To specify multiple
addresses, separate the
addresses with
commas.

subject

Required

© 2014 Adobe Systems Incorporated. All rights reserved.

Message subject. Can be
dynamically generated.
For example, to send
messages that give
customers status updates:
"Status of Order Numb
er #Order_ID#".

813

Adobe ColdFusion Documentation

group

Optional

CurrentRow

Query column to use
when you group sets of
records to send as a
message. For example, to
send a set of billing
statements to a customer,
group on "Customer_ID.
" Case-sensitive.
Eliminates adjacent
duplicates when data is
sorted by the specified
field.

groupcasesensitive

Optional

No

Boolean. Whether to
consider case when using
the group attribute. To
group on case-sensitive
records, set this attribute
to Yes.

keyalias

Optional

Alias of the key with which
the certificate and private
key are stored in the
keystore. If it is not
specified, the first entry in
the keystore is chosen as
the alias.

keypassword

Optional

Password for your private
key. If not specified, the
keystorepassword is
used.

keystore

Optional

The location of the
keystore file, for example,
C:\OpenSSL\bin\keystore.
jks.

keystorepassword

Optional

The password of the
keystore. This is stored in
ColdFusion configuration
files.

mailerid

Optional

© 2014 Adobe Systems Incorporated. All rights reserved.

ColdFusion Application
Server

Mailer ID to be passed in
X-Mailer SMTP header,
which identifies the mailer
application.

814

Adobe ColdFusion Documentation

maxrows

Optional

Maximum number of
messages to send when
looping over a query.

mimeattach

Optional

Path of the on-disk or
in-memory file to attach to
message. Attached file is
MIME-encoded.
ColdFusion attempts to
determine the MIME type
of the file; use the cfmai
lparam tag to send an
attachment and specify
the MIME type.

password

Optional

A password to send to
SMTP servers that require
authentication. Requires a
username attribute.

port

Optional

TCP/IP port on which
SMTP server listens for
requests (normally 25). A
value here overrides the
Administrator.

priority

Optional

3

The message priority
level. Can be one of the
following values:
An integer in the range
1-5; 1 represents the
highest priority.
One of the following
string values, which
correspond to the
numeric values: highe
st or urgent, high, n
ormal, low, and lowe
st or non-urgent.

query

Optional

© 2014 Adobe Systems Incorporated. All rights reserved.

Name of cfquery from
which to draw data for
messages. Use this
attribute to send more
than one message, or to
send query results within
a message.

815

Adobe ColdFusion Documentation

remove

Optional

replyto

Optional

Addresses to which the
recipient is directed to
send replies.

server

Optional

SMTP server address, or
(Enterprise edition only) a
comma-delimited list of
server addresses, to use
for sending messages. At
least one server must be
specified here or in the
ColdFusion Administrator.
A value here overrides the
Administrator. A value that
includes a port
specification overrides the
port attribute. For
details, see Usage.

sign

© 2014 Adobe Systems Incorporated. All rights reserved.

no

If yes, ColdFusion
removes attachment files
(if any) after the mail is
successfully delivered.

Digitally signs the mail. If
set to true, all messages
that you send will have
digital signature.

816

Adobe ColdFusion Documentation

spoolenable

Optional

Whether to spool mail or
always send it
Immediately. Overrides
the ColdFusion
Administrator Spool mail
messages to disk for
delivery setting.
yes: saves a copy of
the message until the
sending operation is
complete. Pages that
use this option might
run slower than the
ones that use the No op
tion.
no: queues the
message for sending,
without storing a copy
until the operation is
complete. If a delivery
error occurs when this
option is No,
ColdFusion generates
an Application
exception and logs the
error to the mail.log file.

startrow

Optional

timeout

Optional

© 2014 Adobe Systems Incorporated. All rights reserved.

1

Row in a query to start
from.
Number of seconds to
wait before timing out
connection to SMTP
server. A value here
overrides the
Administrator.

817

Adobe ColdFusion Documentation

type

Optional

text/plain

MIME type of the
message. Can be a valid
MIME media type or one
of the following:
text: specifies
text/plain type.
plain: specifies
text/plain type.
html: specifies
text/html type.
For a list of all
registered MIME media
types, see www.iana.or
g/assignments/media-ty
pes/.

username

Optional

A user name to send to
SMTP servers that require
authentication. Requires a
password attribute.

useSSL

Optional

Whether to use Secure
Sockets Layer.

useTLS

Optional

Whether to use Transport
Level Security.

wraptext

Optional

Do not wrap text

The maximum line length,
in characters of the mail
text. If a line has more
than the specified number
of characters, replaces
the last white space
character, such as a tab
or space, preceding the
specified position with a
line break. If there are no
white space characters,
inserts a line break at the
specified position. A
common value for this
attribute is 72.

encrypt

Optional

false

If the Email should be
encrypted.

recipientcert

Optional

false

The path to the public key
certificate of the recipient.

© 2014 Adobe Systems Incorporated. All rights reserved.

818

Adobe ColdFusion Documentation

encryptionalgorithm

Optional

The encryption algorithm
to use.
The valid algorithms are:
DES_EDE3_CBC
RC2_CBC
AES128_CBC
AES192_CBC
AES256_CBC
The encryption support is
provided through S/MIME.

Usage

Sends a mail message to the specified address. Mail messages can include attachments. The tag body can include
CFML code to generate mail output. The cfmailparam and cfmailpart tags can only be used in the cfmail ta
g body. Mail messages can be single or multipart. If you send a multi-part mail message, all message content must
be in cfmailpart tags; ColdFusion ignores multipart message text that is not in cfmailpart tags.
Note
The cfmail tag does not make copies of attachments when spooling mail to disk. If you use the
cfmail tag to send a message with an attachment with spooling enabled and you use the cffi
le tag to delete the attachment file, ColdFusion might not send the mail because the mailing
process might execute after the file was deleted. (When this happens, the mail log includes a
FileNotFound exception and the e-mail is not sent.) You can prevent this problem by setting Spo
olEnable="No" in the attribute or disabling spooling in the ColdFusion Administrator. Disabling
spooling causes the e-mail to be delivered immediately.

If you set type="text", sometimes whitespace might be compressed in the messages that you send. To resolve
this, in the ColdFusion Administrator, go to Server Settings > Settings and then deselect the option Enable
Whitespace Management.
Mail addressing

Mail addresses can have any of the following forms:
Format

Example

user (server)company.com




DisplayName 

Rob Smith 

"DisplayName" 

"Rob Smith" 

user@server (DisplayName)

rsmith@company.com (Rob Smith)

© 2014 Adobe Systems Incorporated. All rights reserved.

819

Adobe ColdFusion Documentation
Specifying mail servers

The server attribute can specify one or more mail servers.
Note
If you specify multiple mail servers in ColdFusion Standard, the cfmail tag uses only the first
server in the specification. ColdFusion logs a warning message to the mail log file and ignores
the additional servers.

For each server, you can optionally specify a user name, password, and port. These values override the
corresponding attributes, if any. The server attribute has the following format:

[user:password@]server[:port],[user:password@]server[:port],....

For example, the following line specifies one server, mail.myco.com that uses the default port and no user or
password, and a second server with a user, password, and specific port:

server=mail.myco.com,mail_admin:adm2qzf@mail2.myco.com:24

When you specify multiple mail servers in ColdFusion Enterprise, ColdFusion tries the available servers in the order
they are listed until it connects to a server. ColdFusion does not try to connect to a server that was unavailable in the
last 60 seconds.
Digital Signature

To add digital signature to your mail, specify the attributes sign, keystore, keystorepassword, keyalias,
and keypassword as provided in the following example:



To add digital signature to all the mails you send, instead of adding the attributes to the tag, specify the settings in
the Server Settings > Settings page of the ColdFusion Administrator.
If you do not specify the attributes in the tag, the Administrator settings are applied. Also, in the tag, if you set sign
= "true" and do not specify the attributes keystore, keystorepassword, keyalias, and keypassw
ord, then the values for these attributes specified using ColdFusion Administrator are applied.
Example

© 2014 Adobe Systems Incorporated. All rights reserved.

820

Adobe ColdFusion Documentation

cfmail Example









In ColdFusion 11, you can encrypt your mails using the following procedure:
1. Get the certificate of the user for whom you wanted to send the mail (.p7c format).
2. Specify the path to the generated certificate for the recipientcert attribute. For instance:

3. Configure the mail server from your ColdFusion Administrator.
4. Download the Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy Files from the
Oracle website for the JRE version that ColdFusion is configured with (if you are using an encryption
algorithm whose key size is greater than 128).
5. Send the mail. See the following example.

© 2014 Adobe Systems Incorporated. All rights reserved.

821

Adobe ColdFusion Documentation





This message is encrypted using the algorithm : #algo#.



© 2014 Adobe Systems Incorporated. All rights reserved.

822

Adobe ColdFusion Documentation

cfmailparam
Description

Attaches a file or adds a header to an e-mail message.
Category

Communications tags, Internet protocol tags
Syntax



file = "filename"
type ="media type"
OR

...


Note
You can specify this tag's attributes in an attributeCollection attribute whose value is a
structure. Specify the structure name in the attributeCollection attribute and use the tag's
attribute names as structure keys.

See also

cfmail, cfmailpart, cfftp, cfhttp, cfldap, cfpop; Using the cfmailparam tag in Sending and Receiving
E-Mail in the Developing ColdFusion Applications
History

ColdFusion 8.0.1: Added the attributes Content and Remove.
ColdFusion MX 6.x: Added the Disposition and ContentID attributes.
ColdFusion MX 6.1: Added the type attribute.
Attributes

Attribute

Req/Opt

© 2014 Adobe Systems Incorporated. All rights reserved.

Default

Description

823

Adobe ColdFusion Documentation

Lets you send the
contents of a ColdFusion
variable as an attachment.
To do so, specify the
variable in # signs as the
content attribute value, as
in the following example:

content



contentID

Optional

disposition

Optional

The Identifier for the
attached file. This ID must
be globally unique and is
used to identify the file in
an IMG or other tag in the
mail body that references
the file content.
attachment

How the attached file is to
be handled. Can be one
of the following:
attachment: presents
the file as an
attachment.
inline: displays the
file contents in the
message.

file

Required if you do not
specify name attribute

Attaches a file in a
message. Mutually
exclusive with name attrib
ute. The file is MIME
encoded before sending.

name

Required if you do not
specify file attribute

Name of header.
Case-insensitive. Mutually
exclusive with file attrib
ute.

© 2014 Adobe Systems Incorporated. All rights reserved.

824

Adobe ColdFusion Documentation

remove

Optional

type

Optional

no

If yes, ColdFusion
removes attachment files
(if any) after the mail is
successfully delivered.
The MIME media type of
the file. Not used with the
name attribute. Can be a
valid MIME media type or
one of the following:
text: specifies
text/plain type.
plain: specifies
text/plain type.
html: specifies
text/html type.
If you specify the type,
the value you specify
becomes the content
type header; otherwise,
ColdFusion generates
the content type
header.
Note: For a list of all
registered MIME media
types, see www.iana.or
g/assignments/media-ty
pes/.

value

Optional

Value of the header. Not
used with the file attribu
te.

Usage

This tag attaches a file or adds a header to an e-mail message. It can only be used in the cfmail tag. You can use
multiple cfmailparam tags within a cfmail tag. You can use this tag to include a file, such as an image, in an
HTML mail message. The file can be displayed inline in an HTML message, or as an attachment, as Example 2
shows. To include multiple files, use multiple cfmailparam tags.
Display a file inline in a mail message

1. Specify type="html" in the cfmail tag.
2. Specify disposition="inline" and a ContentID attribute in the cfmailparam tag.
3. Use a src="cid:ContentIDValue" attribute to identify the content to include in the HTML tag such as the im
g tag.
Example

Example 1: This view-only example uses the cfmailparamtag to add a header to a message, attach files, and to
return a receipt to the sender.

© 2014 Adobe Systems Incorporated. All rights reserved.

825

Adobe ColdFusion Documentation



Please review the new logo. Tell us what you think.





Example 2: This view-only example displays an image in the body of an HTML message.



There should be an image here

After the picture


© 2014 Adobe Systems Incorporated. All rights reserved.

826

Adobe ColdFusion Documentation

cfmailpart
Description

Specifies one part of a multipart e-mail message. Can only be used in the cfmail tag. You can use more than one
cfmailpart tag within a cfmail tag.
Category

Communications tags, Internet protocol tags
Syntax


(Optional cfmailparam entries)

Mail part contents

...


Note
You can specify this tag's attributes in an attributeCollection attribute whose value is a
structure. Specify the structure name in the attributeCollection attribute and use the tag's
attribute names as structure keys.

See also

cfmail, cfmailparam, cfpop, cfftp, cfhttp, cfldap, cfcontent, Wrap; E-mail in the Developing
ColdFusion Applications
History

ColdFusion MX 6.1: Added this tag.
Attributes

Attribute

Req/Opt

© 2014 Adobe Systems Incorporated. All rights reserved.

Default

Description

827

Adobe ColdFusion Documentation

charset

Optional

Character encoding
specified by charset attri
bute of cfmail tag

The character encoding in
which the part text is
encoded. The following
list includes commonly
used values:
utf-8
iso-8859-1
windows-1252
us-ascii
shift_jis
iso-2022-jp
euc-jp
euc-kr
big5
hz-gb-2312
euc-cn
utf-16
For more information on
character encodings,
see www.w3.org/Intern
ational/O-charset.html.

type

Required

The MIME media type of
the part. Can be a can be
valid MIME media type or
one of the following:
text: specifies text/plain
type.
plain: specifies
text/plain type.
html: specifies text/html
type.
Note: For a list of all
registered MIME media
types, see www.iana.or
g/assignments/media-ty
pes/.

© 2014 Adobe Systems Incorporated. All rights reserved.

828

Adobe ColdFusion Documentation

wraptext

Optional

Do not wrap text

Specifies the maximum
line length, in characters
of the mail text. If a line
has more than the
specified number of
characters, replaces the
last white space
character, such as a tab
or space, preceding the
specified position with a
line break. If there are no
white space characters,
inserts a line break at the
specified position. A
common value for this
attribute is 72.

Usage

Use this tag to create mail messages with alternative versions of the message that duplicate the content in multiple
formats. The most common use is to send a plain text version of the message that can be read by all mail readers
followed by a version formatted in HTML for display by HTML-compatible mail readers. Specify the simplest version
first, with more complex versions afterwards. For more information, see www.ietf.org/rfc/rfc2046.txt.
Example

cfmailpart Example


You are reading this message as plain text, because your mail reader does not
handle
HTML text.


HTML Mail Message
You are reading this message as HTML.
Your mail reader handles HTML text.



© 2014 Adobe Systems Incorporated. All rights reserved.

829

Adobe ColdFusion Documentation

cfmap
Description

Embeds a geographical map within a ColdFusion web page.Currently, ColdFusion supports only embedding of
Google map. To generate a map, provide a valid Google map API key, and specify the latitude and longitude of the
location, or the address of the location. The Google map API key can be specified in the following ways:
1. Using the cfajaximporttag. You specify the map API key in the params attribute as follows:



2. Using Application.cfc as follows:



3. Using the Settings page in the ColdFusion Administrator. Specify the map API key in the Google Map Key
field. You can also specify the map API key in runtime.cfc
Category

Display management tags
Syntax

© 2014 Adobe Systems Incorporated. All rights reserved.

830

Adobe ColdFusion Documentation




See also

cfdiv, cfwindow, cfmapitem
History

ColdFusion 10: Added the attribute showUser}}
ColdFusion 9.0.1: Added the attribute {{initShow.
ColdFusion 9: Added this tag.
Attributes

Attribute

Req/Opt

centeraddress

Required if centerlatitude
and centerlongitude are
not specified

© 2014 Adobe Systems Incorporated. All rights reserved.

Default

Description
The address of the
location, which is set as
the center of the map.

831

Adobe ColdFusion Documentation

centerlatitude

Required if centeraddress
is not specified

The latitude value for the
location, in degrees. This
value is set as the center
of the map.
This attribute must be
used with the centerlat
itude attribute.
The valid values for cent
erlatitude are -90 to +
90

centerlongitude

Required if centeraddress
is not specified

The longitude value for
the location, in degrees.
This value is set as the
center of the map.
This attribute must be
used with the centerlon
gitude attribute.
The valid values for
centerlongitude are -180
to +180.

collapsible

Optional

false

Whether to provide a
collapsible property for the
surrounding panel:
true
false
If you set collapsible to
true, you cannot set
hideborders to true.

continuouszoom

Optional

true

Whether to provide zoom
control that enables
smooth zooming for the
map:
true
false

doubleclickzoom

Optional

true

Whether to enable
double-click zoom:
true
false

height

Optional

© 2014 Adobe Systems Incorporated. All rights reserved.

400 pixels

Height of the map, in
pixels.

832

Adobe ColdFusion Documentation

hideborder

Optional

true

Whether to hide border for
surrounding panel:
true
false
If you set hideborder
to true, you cannot set
collapsible to true.

initshow

Optional

markerbind

Optional

A bind expression to
dynamically populate data
in the window that is
opened when you click
the marker icon. The bind
expression can specify a
CFC function, a
JavaScript function, or a
URL.

markercolor

Optional

The color of the marker
specified as a
hexadecimal value. By
default, the centermarker
is green in color.
The attributes markeric
on and markercolor are
mutually exclusive.

markericon

Optional

Location of an image file
to use as the marker icon.
The attributes markericon
and markercolor are
mutually exclusive.

markerwindowcontent

Optional

Static content displayed in
the marker window. This
attribute is mutually
exclusive with the marker
bind attribute.

© 2014 Adobe Systems Incorporated. All rights reserved.

true

Use to show/hide a map
when the page loads.
This is useful if you have
collapsible divs or
collapsible spry regions,
where the user has to
show the map on click of
a link or button

833

Adobe ColdFusion Documentation

name

Required

Name of the map.
The name attribute is
required to invoke
JavaScript functions.

onerror

Optional

The JavaScript function to
run when there is a
Google map API error.
The JavaScript function is
passed with two
parameters, Google map
status code and error
message.

onload

Optional

Custom JavaScript
function that runs after the
map loads, for instance,
registering an event.

overview

Optional

false

Whether to add an
Overview panel to the
map:
true
false

showmarkerwindow

Optional

© 2014 Adobe Systems Incorporated. All rights reserved.

false

If set to true, displays
the marker window. If the
attribute markerbind is
used, unless you set this
attribute to true, the
marker window is not
displayed.
This attribute is ignored if
markerwindowcontent
is set to true.

834

Adobe ColdFusion Documentation

showUser

Optional

false

If set to true, on
HTML-compliant
browsers, user location is
shown on the map.
For browsers that are not
HTML 5 compliant, the
address falls back to the
value you specify for cen
terAddress. If no value
is specified, it falls back to
the value specified for ce
nterLatitude and cen
terLongitude. User
has to authenticate the
site so that it tracks user
location. For example, in
Google Chrome, you are
prompted to Allow to track
your Physical location.

scrollwheelzoom

Optional

true

Whether to enable mouse
wheel zooming control:
true
false

showallmarkers

Optional

true

Whether to display all
markers added to the
map:
true
false
When you specify show
allmarkers as true, to
display all the markers
within the map area, the
zoom level specified for
the map may be
overridden.

showcentermarker

Optional

true

Whether to display the
marker icon that identifies
the map center:
true
false

showscale

Optional

false

Whether to show scale
control:
true
false

© 2014 Adobe Systems Incorporated. All rights reserved.

835

Adobe ColdFusion Documentation

tip

Optional

A short description of the
center location that
appears as a tool tip.

title

Optional

Title of the panel.
You cannot define a title,
if you set hideborder to
true.

type

Optional

map

Type of the Google map:
map
satellite
hybrid
terrain
earth: If you use typ
e="earth", you are
prompted to download
Google Earth 3D
plug-in.

typecontrol

Optional

basic

Whether to provide a type
control that lets you switch
the map:
basic: Displays the
marker types that
provides the options ma
p, satellite, and hy
brid.
none
advanced: Displays a
drop-down list with five
options defined for the
attribute type.

width

Optional

400 pixels

Map width, in pixels.

zoomcontrol

Optional

small

Whether to enable zoom
control:
none
small
large
large3d
small3d

zoomlevel

Optional

3

Specifies the starting
zoom value.

Usage

© 2014 Adobe Systems Incorporated. All rights reserved.

836

Adobe ColdFusion Documentation

This tag can be used to create a map within an HTML page, a div tag, or in a new window. If you use this tag in a
new window, you must use the cfmap tag within the cfwindow tag.
The {{zoomcontrol}}attribute lets you change the size of the embedded map. You can increase the zoom value to
get a close-up view of the map. Or, decrease the zoom value to view a larger area of the map at a reduced size.
Each time you change the zoom value, the entire map does not refresh, but only those portions of the map that
change, making the display of data fast.
The cfmap tag supports the map display in five formats - map, satellite, terrain, earth, and hybrid. The
map format displays a standard road map image. The satellite format displays a satellite image of the map. The
hybrid format displays a combination of the roadmap and the satellite image of the map, with important street names
and places marked on the satellite image.
The following attributes do not work if type="earth": Zoomlevel, showScale, overview, tip, zoomControl,
showCenterMarker, and showAllMarkers.
For cfmap tag to work on Safari 3.x and Google Chrome, specify the HTML head tag ( ).
Examples

cfmap Example using latitude and longitude attributes


cfmap Example using center address


© 2014 Adobe Systems Incorporated. All rights reserved.

837

Adobe ColdFusion Documentation

cfmapitem
Description

The cfmapitem tag is a child tag of the cfmap tag. This tag creates markers on the map. You can specify the
marker in a map using either the cfmapitem tag or using the ColdFusion.Map.AddMapMarker JavaScript API.
See ColdFusion.Map.addMarker for details.
Category

Display management tags
Syntax



See also

cfdiv cfwindow, cfmap
History

ColdFusion 10: Added the attribute {{showUser}}
ColdFusion 9: Added this tag.
Attributes

Attribute

Req/Opt

address

Required, if latitude and
longitude are not specified

The address of the
location to set the map
marker.

latitude

Required, if address is not
specified

The latitude value for the
marker, in degrees. The
valid values for latitude
are -90 to + 90.

© 2014 Adobe Systems Incorporated. All rights reserved.

Default

Description

838

Adobe ColdFusion Documentation

longitude

Required, if address is not
specified

markercolor

Optional

markericon

Optional

Location of an image file
to use as the marker icon.
The attributes markeric
on and markercolor are
mutually exclusive.

markerwindowcontent

Optional

Static content displayed in
the marker window. This
attribute ignores the mark
erbind attribute defined
in the tag cfmap.

name

Optional

The name of the map.

green

The color of the marker
specified as a
hexadecimal value. By
default, the centermarker
is green in color.
The attributes markeric
on and markercolor are
mutually exclusive.

Optional

Inherits parent cfmap
setting

If set to true, displays
the marker window. If the
attribute markerbind is
used, unless you set this
attribute to true, the
marker window is not
displayed.

Optional

false

If set to true, on
HTML-compliant
browsers, user location is
shown on the map.

showmarker
window

showUser

tip

The longitude value for
the marker, in degrees.
The valid values for
longitude are -180 to +
180.

Optional

A short description of the
marker location that
appears as a tool tip.

Usage

This tag must be used within the cfmap tag.
The following inheritance rules apply:

© 2014 Adobe Systems Incorporated. All rights reserved.

839

Adobe ColdFusion Documentation

The value specified for the attribute showmarkerwindow in the cfmap tag is inherited by all cfmapitem tag
s.
A child cfmapitem tag can override the attribute showmarkerwindow in the cfmap tag by changing the
value.
Any bind expression defined using the markerbind is ignored if the cfmapitem tag defines the attribute ma
rkerwindowcontent.
Examples

cfmapitem example using latitude and longitude attributes



cfmap Example using address address



© 2014 Adobe Systems Incorporated. All rights reserved.

840

Adobe ColdFusion Documentation

cfmediaplayer
Description

Creates an in-built media player that lets you play videos in any format supported by HTML 5 compliant browsers in
addition to FLV, MPEG-3, and MPEG-4 files. FLV files can be played from any web server. You can play
MPEG-3/MPEG-4 only from Flash Media Server using RTMP. You can also play audio files of MP3 format.
Category

Display management tags
Syntax


height="integer"
width="integer"
wmode="window|opaque|transparent">


History

ColdFusion 10: type, repeat, posterImage, title, skin, onPause, {{onError}}
ColdFusion 9: Added this tag.
Attributes

Attribute

Req/Opt

© 2014 Adobe Systems Incorporated. All rights reserved.

Default

Description

841

Adobe ColdFusion Documentation

align

Optional

left

Specifies the horizontal
alignment of the media
player. You can select
from left, right, and c
enter.

autoplay

Optional

false

A Boolean value that
specifies if the media
player must automatically
play the FLV file on
loading the CFM page:
true
false

bgcolor

Optional

6b7c85

The background color of
the media player specified
as a Hexadecimal value
or or a recognized color
name, for example red. In
the case of HTML player,
this attribute applies only
if you are using the
attribute wmode set to tra
nsparent.
The dependency does not
exist if you are using
Flash player.

controlbar

Optional

true

A Boolean value that
specifies if you want to
display the control panel
for the media player:
true
false

hideborder

Optional

true

A Boolean value that
specifies if you want a
border for the media
player panel:
true
false

hidetitle

Optional

© 2014 Adobe Systems Incorporated. All rights reserved.

true

If true, hides the video
file name.

842

Adobe ColdFusion Documentation

fullScreenControl

Optional

yes

Whether full screen is
enabled:
yes
no
The following
characteristics apply:
Single click
plays/pauses the media
player.
Borders, if defined, are
not displayed in
full-screen mode.
Double-click for
full-screen mode.
(If you are in full-screen
mode) Press "Esc" or
double-click to restore
the player to normal
mode.
This attribute is
unsupported for HTML
playback. Also, you
cannot disable full
screen for Flash player.

height

Optional

name

Required if source is not
defined

Name of the media player.
The name attribute is
required when you invoke
JavaScript functions.

onComplete

Optional

Custom JavaScript
function to run when the
FLV file has finished
playing.

Height of the media
player, in pixels.

Custom JavaScript
function to run when
playback results in an
error.

onError

onLoad

275 pixels

Optional

onPause

© 2014 Adobe Systems Incorporated. All rights reserved.

Custom JavaScript
function to run on loading
of the player component.
Custom JavaScript
function to run when the
video is paused.

843

Adobe ColdFusion Documentation

onStart

Optional

Custom JavaScript
function to run when the
FLV file starts playing.
Sets a poster image for
the video playback. Takes
URL or relative address
as value.

posterImage

quality

Optional

high

The quality of the media
playback:
low
medium
high

repeat

false

Path to the XML in which
skinning options are
specified. Applies only to
FlashFor example, 

skin

source

If true, continues
playback from first to last
frame after the media
player reaches the end of
the video.

Required if name is not
defined

© 2014 Adobe Systems Incorporated. All rights reserved.

The URL to the FLV file.
This can be a URL
relative to the current
page.
You can store the FLV file
on the ColdFusion server
or any other streaming
server.

844

Adobe ColdFusion Documentation

style

Optional

The following are the
supported styles:
bgcolor: The
background color of the
media player.
borderbottom: A
numeric value. The
default is 10.
bordertop: A numeric
value. The default is 10.
borderleft: A numeric
value. The default is 10.
borderright: A numeric
value. The default is 10.
titletextcolor:
Hexadecimal value of
RGB color. For
example, specify the
color white as
##FFFFFF or FFFFFF.
The default is black.
titlebgcolor:
Hexadecimal value of
RGB color. The default
is black.
progresscolor: The
foreground color for the
progress bar.
Hexadecimal value of
RGB color. The default
is black.
progressbgcolor: The
background color for
the progress bar.
Hexadecimal value of
RGB color. The default
is black.
controlscolor: The
foreground color of the
controls in the Control
panel. Hexadecimal
value of RGB color. The
default is black.
controlbarbgcolor: The
background color of the
controls. Hexadecimal
value of RGB color. The
default is black.

© 2014 Adobe Systems Incorporated. All rights reserved.

845

Adobe ColdFusion Documentation

Sets title on the media
player. The title appears
over the media player on
upper-left corner. If title is
specified and hideTitle
is not specified, then hid
eTitle is set to false.
Also when playback is
Flash, the attribute wmode
for Flash player is set to o
paque, and ignores the
default/user-specified
value.

title

type

flash

The media player type, if
html or flash.

width

Optional

480 pixels

Width of the media player,
in pixels.

wmode

Optional

window

Specifies the absolute
positioning and layering
capabilities in your
browser:
window: Plays the
media player in its own
rectangular window on
a web page
opaque: Hides
everything behind the
media player on the
web page
transparent: Lets the
background of the web
page show through the
transparent portions of
the media player
When you set playback
type as Flash, value of
this attribute is set to
opaque, and ignores
the
default/user-specified
value.

Example

In this example, the FLV file is stored in the web root used by the ColdFusion server. You need to store an FLV file mediafile.flv in the location _web_root__xyz_. You can now create the media player with the following content:

© 2014 Adobe Systems Incorporated. All rights reserved.

846

Adobe ColdFusion Documentation

cfmediaplayer Example


The following code illustrates styling of the media player:








© 2014 Adobe Systems Incorporated. All rights reserved.

847

Adobe ColdFusion Documentation

cfmenu
Description

Creates a horizontal or vertical menu. Any menu item can be the top level of a submenu.
Category

Display management tags
Syntax


cfmenuitem tags


The cfmenu tag must have a body that contains at least one cfmenuitem tag to define the menu items and an end
 tag.
Note
You can specify this tag's attribute in an attributeCollection attribute whose value is a
structure. Specify the structure name in the attributeCollection attribute and use the tag's
attribute name as structure key.

See also

cfajaximport, cfmenuitem, Using menus and toolbars in Using Ajax User Interface
Components and Features in the Developing ColdFusion Applications
History

ColdFusion 8: Added this tag.
Attributes

Attribute

Req/Opt

© 2014 Adobe Systems Incorporated. All rights reserved.

Default

Description

848

Adobe ColdFusion Documentation

bgColor

Optional

Background color style of
the menu

The color of the menu
background. You can use
any valid HTML color
specification. This
specification has the
following behaviors:
You can override it
locally by specifying the
menuStyle attribute of
this tag and any cfmen
uitem tag.
It controls the
background of color
surrounding a submenu
whose background is
specified by a childSt
yle attribute.

childStyle

Optional

A CSS style specification
that applies to the
following menu items:
The items of the
top-level menu
All child menu items,
including the children of
submenus
This attribute lets you
use a single style
specification for all
menu items.

font

Optional

Browser default font

The font to use for all child
menu items. Use any valid
HTML font-family style
attribute. Some common
values are serif, sansserif, Times, Courier,
and Arial.

fontColor

Optional

black

The color of the menu
text. Use any valid HTML
color specification.

© 2014 Adobe Systems Incorporated. All rights reserved.

849

Adobe ColdFusion Documentation

fontSize

Optional

Font size of the menu
item

The size of the font. Use a
numeric value, such as 8,
to specify a pixel
character size. Use a
percentage value, such as
80%, to specify a size
relative to the default font
size. Font sizes larger
than 20 pixels can result
in submenu text
exceeding the menu
boundary.

menuStyle

Optional

A CSS style specification
that applies to the menu,
including any parts of the
menu that do not have
items. If you do not
specify style information in
the cfmenuitem tags,
this attribute controls the
style of the top-level
items.

name

Optional

The name of the menu.

selectedFontColor

Optional

black

The color of the text for
the menu item that has
the focus. Use any valid
HTML color specification.

selectedItemColor

Optional

light blue

The color that highlights
the menu item that has
the focus. You can use
any valid HTML color
specification.

type

Optional

horizontal

The orientation of the
menu. The following
values are valid:
horizontal: Menu
items are arranged
horizontally.
vertical: Menu items
are arranged vertically.
Submenus of both
menu types are always
arranged vertically.

© 2014 Adobe Systems Incorporated. All rights reserved.

850

Adobe ColdFusion Documentation

width

Optional

Width of the container

The width of a vertical
menu; not valid for
horizontal menus. Use a
numeric value, such as
50, to specify a pixel size.
Use a percentage value,
such as 30%, to specify a
size relative to the parent
element's size.

Usage

The cfmenu tag defines a horizontal or vertical ColdFusion menu. You use a single cfmenu tag to define the
general menu characteristics, and you use cfmenuitem child tags to define the individual menu entries and any
submenus. You create submenus by putting cfmenuitem tags in the body of a cfmenuitem tag.
You cannot nest a cfmenu tag inside a form or inside a cfmenu tag or cfmenuitem tag.
Example

The following example creates a simple menu bar. When you click an entry in the bar, the browser displays the
Adobe website page for the selected product. You can expand the ColdFusion item by clicking the icon, and then
select an item to display a specific ColdFusion web page.




















© 2014 Adobe Systems Incorporated. All rights reserved.

851

Adobe ColdFusion Documentation

cfmenuitem
Description

Defines an entry in a menu, including an item that is the head of a submenu.
Category

Display management tags
Syntax


Optional child menuitem tags

OR


If the cfmenuitem tag does not have a body with an end  tag, close the tag with a forward slash
character before the closing greater than character (/>), for example, .
Note
You can specify this tag's attribute in an attributeCollection attribute whose value is a
structure. Specify the structure name in the attributeCollection attribute and use the tag's
attribute name as structure key.

See also

cfmenu, Using menus and toolbars in Using Ajax User Interface Components and Features in the Developing
ColdFusion Applications
History

ColdFusion 8: Added this tag.
Attributes

Attribute

Req/Opt

Default

Description

display

Required if divider attri
bute is not specified

'

The text to show as the
menu item label.

© 2014 Adobe Systems Incorporated. All rights reserved.

852

Adobe ColdFusion Documentation

childStyle

Optional

divider

Optional

This attribute specifies
that the item is a divider. If
you specify this attribute,
you cannot specify any
other attributes. You can
use this attribute without a
value, as in the following
example:{{.}}You cannot
use this attribute in a
top-level horizontal menu.

href

Optional

A URL link to activate or
JavaScript function to call
when the user clicks the
menu item.

image

Optional

URL of an image to
display at the left side of
the menu item. The file
type can be any format
that the browser can
display.
For most displays, you
must use 15x15 pixel
images, because larger
images conflict with the
menu item text.

menuStyle

Optional

Style determined by
parent

A CSS style specification
that controls the overall
style of any submenu of
this menu item. This
attribute controls the
submenu of the current
menu item, but not any
child submenus of the
submenu.

style

Optional

Style determined by
parent

A CSS style specification
that applies to the current
menu item only. It is not
overridden by the childS
tyle attribute.

© 2014 Adobe Systems Incorporated. All rights reserved.

Style determined by
parent

A CSS style specification
that applies to all child
menu items, including the
children of submenus.

853

Adobe ColdFusion Documentation

name

Optional

target

Optional

The name of the menu
item.
The current window and
frame (if any)

The target in which to
display the contents
returned by the href attri
bute. The attribute can be
a browser window or
frame name, or an HTML
target value, such as _se
lf.

Usage

Every cfmenuitem tag must be a child of a cfmenu tag or a cfmenuitem tag. To create a submenu, put the cfme
nuitem tags for submenu items in the body of the cfmenuitem tag for the submenu root in the parent menu. For
an example of a simple submenu, see cfmenu.
Example

The following menu shows the effects of the various style attributes on the menu and menu item appearance.

© 2014 Adobe Systems Incorporated. All rights reserved.

854

Adobe ColdFusion Documentation




























© 2014 Adobe Systems Incorporated. All rights reserved.

855

Adobe ColdFusion Documentation

cfmessagebox
Description

Defines a control for displaying pop-up messages. The control has more features than the standard alert box,
including the ability to include a prompt and entry field in the box.
Category

Display management tags
Syntax



History

ColdFusion 9: Added this tag
Attributes

Attribute

Req/Opt

bodyStyle

Optional

© 2014 Adobe Systems Incorporated. All rights reserved.

Default

Description
A CSS style specification
for the body of the
message box. As a
general rule, use this
attribute to set color and
font styles.

856

Adobe ColdFusion Documentation

buttonType

Optional

yesno

Applies to the control type
- confirm.
The buttons to display on
the message box:
yesno: displays the
buttons Yes and No
yesnocancel:
displays the buttons
Yes, No, and Cancel

callbackhandler

Optional

The function that the
control calls when a user
clicks one of the buttons.
For more information see
Usage.

icon

Optional

Specifies the following
CSS classes:
error: Provides the error
icon. You can use this
icon when displaying
error messages.
info: Provides the info
icon. You can use this
icon when displaying
any information.
question: Provides the
question icon. You can
use this icon in a
confirmation message
box that prompts a user
response.
warning: Provides the
warning icon. You can
use this icon when
displaying a warning
message.

labelCancel

Optional

Cancel

The text to put on the
cancel button of a prompt
message box.

labelOk

Optional

OK

The text to put on an alert
button and prompt
message box OK button.

© 2014 Adobe Systems Incorporated. All rights reserved.

857

Adobe ColdFusion Documentation

labelNo

Optional

No

The text to put on the
button used for a negative
response in a confirm
message box.

labelYes

Optional

Yes

The text to put on the
button used for a positive
response in a confirm
message box.

message

Optional

modal

Optional

The text to display inside
the message box.
yes

A Boolean value that
specifies if the message
box must be a modal
window:
yes
no

multiline

Optional

name

Required

The control name. Used
to refer to the control in
JavaScript.

title

Optional

The title for the message
box.
If you do not specify a
title, ColdFusion assigns
the control type value as
the default title.

© 2014 Adobe Systems Incorporated. All rights reserved.

false

Valid only for prompt type
message boxes. A
boolean value specifying
whether the prompt input
text box has a single or
multiple lines for text
input.

858

Adobe ColdFusion Documentation

Required

type

The control type. Must be
one of the following:
alert - A message
with a single OK button.
confirm - A message
box with two buttons
YES and NO or three
buttons YES, NO, and
CANCEL.
prompt - a message
box with a single-line or
multiline text input area
and OK and CANCEL
buttons.

width

Optional

Width of the message box
in pixels.

x

Optional

The X (horizontal)
coordinate of the
upper-left corner of the
message box.ColdFusion
ignores this attribute if you
do not set the y attribute.

y

Optional

The Y (vertical) coordinate
of the upper-left corner of
the message
box.ColdFusion ignores
this attribute if you do not
set the x attribute.

Usage

The cfmessagebox creates a message box, but does not show it. You show a message box, say named mymessa
gebox, in JavaScript code as follows:

ColdFusion.MessageBox.show("mymessagebox");

If you specify a callbackhandler, clicking a button in the message box invokes the callbackhandler by passing the
button label as a parameter. For prompt boxes, an additional parameter containing the prompt text is also passed.
For alert and confirm boxes:

var function_name = function(button);

For prompt boxes:

© 2014 Adobe Systems Incorporated. All rights reserved.

859

Adobe ColdFusion Documentation

var function_name = function(button, promptmessage);

The EventObject parameter is the JavaScript ID (not the name) of the button that was pressed. The textmessage
parameter is a string with the contents of the prompt text box.
Example

The following example has three buttons, one to display each type of message box. The message box labels are
customized, and the messagebox callback function displays the type of the clicked button.

© 2014 Adobe Systems Incorporated. All rights reserved.

860

Adobe ColdFusion Documentation










Click a button display the corresponding message box.











© 2014 Adobe Systems Incorporated. All rights reserved.

861

Adobe ColdFusion Documentation

cfmodule
Description

Invokes a custom tag for use in ColdFusion application pages. This tag processes custom tag name conflicts.
Category

Application framework tags
Syntax



See also

cfapplication, cfassociate, cflock; Creating and Using Custom CFML Tags in the Developing
ColdFusion Applications
History

ColdFusion MX: Changed behavior when using this tag within a custom tag: if the attribute_name parameter is
the same as a key element within the attributeCollection parameter, ColdFusion now uses the name value
that is within the attributeCollection parameter. (Earlier releases did not process this consistently.)
Attributes

Attribute

Req/Opt

© 2014 Adobe Systems Incorporated. All rights reserved.

Default

Description

862

Adobe ColdFusion Documentation

attributeCollection

Optional

Structure. A collection of
key-value pairs that
represent attribute names
and values. You can
specify multiple key-value
pairs. You can specify this
attribute only once.
Note: This attribute
functions differently from
the attributeCollect
ion attribute that is
supported by most other
tags. You must specify the
name and template attri
butes as direct cfmodule
tag attributes, not in the a
ttributeCollection s
tructure.

attribute_name

Optional

Attribute for a custom tag.
You can include multiple
instances of this attribute
to specify the parameters
of a custom tag.

name

Required unless
{{template}}attribute is
used

Mutually exclusive with the template attribute. A custom tag name, in the form "Name.Name.Name..." Identifies
subdirectory, under the ColdFusion tag root directory, that contains custom tag page, for example (Windows format):
 This identifies the page GetUserOptions.cfm in the
directory CustomTags
Forums40 under the ColdFusion root directory.|
template |
Required unless name attribute is used|
Mutually exclusive with the name attribute. A path to the page that implements the tag.
Relative path: expanded from the current page.
Absolute path: expanded by using ColdFusion mapping.
A physical path is not valid. |
Usage

To name a ColdFusion page that contains the custom tag definition, including its path, use the template attribute.
To refer to the custom tag in the ColdFusion installation directory, using dot notation to indicate its location, use the
name attribute. On UNIX systems, ColdFusion searches first for a file with a name that matches the name attribute,
but is all lower case. If it does not find the file, it looks for a file name that matches the attribute with identical
character casing.
You can use the attributeCollection attribute and explicit custom tag attributes in the same call. Within the

© 2014 Adobe Systems Incorporated. All rights reserved.

863

Adobe ColdFusion Documentation

custom tag code, the attributes passed with attributeCollection are saved as independent attribute values,
with no indication that they are grouped into a structure by the custom tag's caller.Similarly, if the custom tag uses a
cfassociate tag to save its attributes, the attributes passed with attributeCollection are saved as
independent attribute values, with no indication that they are grouped into a structure by the custom tag's caller.
If you specify an end tag to cfmodule, ColdFusion calls your custom tag as if it had both a start and an end tag. For
more information, see Handling end tags in Executing custom tags in the Developing ColdFusion Applications.
Example

cfmodule Example
This view-only example shows use of cfmodule to call a custom tag inline.
This example uses a sample custom tag that is saved in myTag.cfm in the snippets
directory.
You can also save ColdFusion custom tags in the CFusionMX7\CustomTags directory.








Here is one way in which to invoke the custom tag, using the TEMPLATE
attribute.
#HTMLCodeFormat(" ")#

The result: #result#




Here is another way to invoke the custom tag, using the NAME attribute.
#HTMLCodeFormat(" ")#

The result: #result#



Here is the short cut to invoking the same tag.
#HTMLCodeFormat( "")#

© 2014 Adobe Systems Incorporated. All rights reserved.

865

Adobe ColdFusion Documentation


The result: #result#

© 2014 Adobe Systems Incorporated. All rights reserved.

866

Adobe ColdFusion Documentation

cfNTauthenticate
Description

Authenticates a user name and password against the Windows NT domain on which the ColdFusion server is
running, and optionally retrieves the user's groups.
Category

Security tags
Syntax



Note
You can specify this tag's attributes in an attributeCollection attribute whose value is a
structure. Specify the structure name in the attributeCollection attribute and use the tag's
attribute names as structure keys.

See also

cflogin, cfloginuser, IsUserInAnyRole, GetAuthUser
History

ColdFusion MX 7: Added this tag.
Attributes

Attribute

Req/Opt

domain

Required

Domain against which to
authenticate the user. The
ColdFusion J2EE server
must be running on this
domain.

password

Required

User's password.

username

Required

User's login name.

© 2014 Adobe Systems Incorporated. All rights reserved.

Default

Description

867

Adobe ColdFusion Documentation

listGroups

Optional

No

Boolean value that
specifies whether to
include a
comma-delimited list of
the user's groups in the
result structure.

result

Optional

cfntauthenticate

Name of the variable in
which to return the results.

throwOnError

Optional

no

Boolean value that
specifies whether to throw
an exception if the
validation fails. If this
attribute is yes,
ColdFusion throws an
error if the username or
password is invalid; the
application must handle
such errors in a try/catch
block or ColdFusion error
handler page.

Usage

Use this function to authenticate a user against a Windows NT domain and optionally get the user's groups. This
function does not work with the Microsoft Active Directory directory service, and does nothing on UNIX and Linux
systems. You typically use this tag inside a cflogin tag to authenticate the user for a cfloginuser tag, as the
example shows.
Note
ColdFusion must run as a user that has the privilege to authenticate other users in the specified
domain.

The structure specified in the result attribute contains the following information:
Field

Value

auth

Whether the user is authenticated:
yes
no

groups

A comma-delimited list of the user's groups in the
specified domain. The structure includes this field only
if the listGroups attribute is yes.

name

The user name; equals the tag's username attribute.

© 2014 Adobe Systems Incorporated. All rights reserved.

868

Adobe ColdFusion Documentation

The authentication status. One of the following:

status

success
UserNotInDirFailure: the user is not listed in the
directory.
AuthenticationFailure: the user is in the
directory, but the password is not valid.

This tag provides two models for handling authentication: status checking and exception handling. If the throwOnEr
ror attribute is no, use the result variable's auth and status fields to determine whether the user was authenticated
and, if not, the reason for the failure. If the throwOnError attribute is yes, ColdFusion throws an exception error if
the user is not valid. In this case, use try/catch error handling. The catch block must handle any authentication
failure.
Example

The following example uses the auth and status fields to determine whether the user is authenticated and the failure
cause. It consists of three files that you put in the same directory:
A main cfntauthexample.cfm page that displays the name if the user is authenticated and contains a logout
link.
A login form page that is displayed if the user is not logged in.
The Application.cfm page, which contains all the login, authentication, and logout processing code.
For a full description of login processing, see the Developing ColdFusion Applications. For information on
how this example works, see the comments in the code.Save the following page as
cfntauthenticateexample.cfm. To run the example, request this page in your browser or IDE.



Welcome #GetAuthUser()#

Log Out


Save the following page as loginform.cfm:


Please Log In


User Name: 

Password: 

Domain: 




© 2014 Adobe Systems Incorporated. All rights reserved.

869

Adobe ColdFusion Documentation

Save the following page as Application.cfm:



























The password for #theusername# is not correct

Please Try again


The user name #theusername# is not valid

Please Try again








© 2014 Adobe Systems Incorporated. All rights reserved.

870

Adobe ColdFusion Documentation

cfoauth
The  tag allows you to easily integrate third-party Oauth 2 authentication provider in your application. This
tag currently supports Facebook and Google authentication. Also, this tag supports Oauth providers that support the
Oauth 2 protocols. For instance, Microsoft and Github.
Syntax



Attributes

Attribute

Req/Opt

Type="facebook"
Type="google"

One of the following is
required:
type
accesstokenendpoint,
authendpoint

clientid

required

© 2014 Adobe Systems Incorporated. All rights reserved.

Default

Description
Currently supported
values are Facebook and
Google. Implicitly supports
the authentication
workflow of Facebook and
Google.
Unique ID generated
while registering your
application with the Oauth
provider.

871

Adobe ColdFusion Documentation

scope

optional

Scopes are the
permissions that a
developer seeks from the
users. These are usually
comma separated values
of permissions.

Refer to the Oauth
provider's documentations
for more information.

For example, after
Facebook authentication,
if a developer wants to
access an email address
and then the friend lists of
a user, the developer will
use:
scope=email,read_friendli
sts.

Note: The scope name
varies for different Oauth
providers.
state

optional

© 2014 Adobe Systems Incorporated. All rights reserved.

The state variable is used
to pass back any
information to your web
application after the
authentication and
redirection are completed.
Any value passed to this
attribute is returned to the
web application after
authentication. This is
useful for CSRF
(Cross-site request
forgery) protection. You
can use ColdFusion’s
security-related CSRF
functions for this attribute.

872

Adobe ColdFusion Documentation

authendpoint

optional

secretkey

optional

accesstokenendpoint

optional

result

optional

redirecturi

optional

Either type can be
specified or endpoints
combination but not both

If type is not specified, this
will be used as end point
URL to be invoked for
user authentication.
Parameter is the App
Secret as displayed in
your social media app's
settings.

Either type can be
specified or endpoints
combination but not both

If type is not specified this
will be used as end point
URL to be invoked for app
authentication.
A struct which will have
login info of the user
including login
success/failure, failure
reason, user name, user
id.

This will default to the
URL which is executing
the code.
So if in oauth settings
user has given app URL
as :

To redirect once user
authentication is done.

http://domainname/appna
me
And the file executing the
code is :
http://domainname/appna
me/login.cfm
The redirect URI will be :
http://domainname/appna
me/login.cfm
urlparams

optional

Extra options which will be
passed as URL query
string to authendpoint.

Step 1: Register with the Oauth 2 provider

Register your application in the Oauth 2 provider site with the relevant site-specific application details. (For instance,
in Facebook you must create the Facebook App ID and App Secret).

© 2014 Adobe Systems Incorporated. All rights reserved.

873

Adobe ColdFusion Documentation

In ColdFusion, specify your ID and App Secret in the cfoauth tag.
ColdFusion implicitly supports FB and Google. For
other sites, use access token endpoint and other
attributes.

The syntax is



redirecturi will default to the URL which is executing the code. For example, if in oauth settings user has entered the
app URL as: http://domainname/appname and the file executing the code as http://domainname/appname/login.cfm,
the redirect URI will be: http://domainname/appname/login.cfm.
Also, register your domain details in your social media site.

Step 2: Understand the authentication process.

Once the user clicks the client site login button, the user will be prompted with a popup to grant the
permissions.
If the user is not logged into the client site, they will be prompted to login.
If the user has already authorized your app and has already granted the permissions requested in scope, the
user will be immediately redirected to your redirect_uri.
If the user has already authorized your application, but
you are requesting additional permissions in the scope
parameter, the user will be presented with a dialog
which shows only the requested permissions that the
user has not already granted your application.

Step 3: Implementing

The following example shows a simple authentication:

© 2014 Adobe Systems Incorporated. All rights reserved.

874

Adobe ColdFusion Documentation







© 2014 Adobe Systems Incorporated. All rights reserved.

875

Adobe ColdFusion Documentation

cfobject
Description

Creates a ColdFusion object of a specified type.
Note
You can enable and disable this tag in the ColdFusion Administrator page, under ColdFusion
Security > Sandbox Security.

Category

Extensibility tags
Syntax

The tag syntax depends on the object type. Some types use the type attribute; others do not. See the following
sections:
cfobject: .NET object
cfobject: COM object
cfobject: component object
cfobject: CORBA object
cfobject: Java or EJB object
cfobject: web service object
Note
On UNIX, this tag does not support COM objects.

See also

cfargument, cfcomponent, cffunction, cfinvoke, cfinvokeargument, cfproperty, cfreturn; Using
Java objects in the Developing ColdFusion Applications
History

ColdFusion 8:
Added password, proxyPassword, proxyPort, proxyServer, proxyUser, refreshWSDL, userName,
wsdl2JavaArgs, and wsportname attributes to for use with web service objects.
Added .NET/dotnet type and the associated assembly, port, protocol, and secure attributes.
ColdFusion MX:
Changed instantiation behavior: this tag, and the CreateObject function, can now instantiate ColdFusion
components (CFCs); you can use them within the cfscript tag.
For CORBA object: changed the Naming Service separator format for addresses from a dot to a forward
slash. For example, if "context=NameService", for a class, use either of the following formats for the clas
sparameter:
"/Eng/CF"
".current/Eng.current/CF"
(In earlier releases, the format was ".Eng.CF".)
For CORBA object: changed the locale attribute; it specifies the Java configuration that contains the
properties file.

© 2014 Adobe Systems Incorporated. All rights reserved.

876

Adobe ColdFusion Documentation

cfobject: .NET object
Description

Creates a .NET object, that is, a ColdFusion proxy for accessing a class in a local or remote .NET assembly.
Syntax



Note
You can specify this tag's attributes in an attributeCollection attribute whose value is a
structure. Specify the structure name in the attributeCollection attribute and use the tag's
attribute names as structure keys.

See also

.NET object, DotNetToCFType, Using Microsoft .NET Assemblies in the Developing ColdFusion Applications
History

ColdFusion 8: Added .NET and dotnet type values, and the assembly, port, protocol, and secure attributes.
Attributes

Attribute

Req/Opt

class

Required

Name of the .NET class to
instantiate as an object.

name

Required

String; reference name of
the component to use in
your application.

type

Required for .NET

Object type. Must be .NE
T or dotnet for .NET
objects.

action

Optional

© 2014 Adobe Systems Incorporated. All rights reserved.

Default

create

Description

Action to take. Must be cr
eate.

877

Adobe ColdFusion Documentation

assembly

Optional.

mscorlib.dll which
contains the .NET core
classes.

For local .NET
assemblies, the absolute
path or paths to the
assembly or assemblies
(EXE or DLL files) from
which to access the .NET
class and its supporting
classes. If a class in an
assembly requires
supporting classes that
are in other assemblies,
you must also specify
those assemblies. You
can, however, omit the
supporting assemblies for
the following types of
supporting classes:
.NET core classes
(classes in mscorlib.dll)
Classes in assemblies
that are in the global
assembly cache (GAC)
To specify multiple
assemblies, use a
comma-delimited list.Fo
r remote .NET
assemblies, you must
specify the absolute
path or paths of the
local proxy JAR file or
files that represent the
assemblies.
If you omit this attribute,
and there is no local
.NET installation, the
tag fails without
generating an error. If
you omit this attribute,
there is a local .NET
installation, and the
specified class is not in
the .NET core classes,
ColdFusion generates
an error.

port

Optional

© 2014 Adobe Systems Incorporated. All rights reserved.

6086

Port number at which the
.NET-side agent is
listening.

878

Adobe ColdFusion Documentation

protocol

Optional

tcp

Protocol to use for
communication between
ColdFusion and .NET.
Must be one of the
following values:
http: Use HTTP/SOAP
communication
protocol. This option is
slower than tcp, but
might be required for
access through a
firewall.
tcp: Use binary TCP/IP
protocol. This method is
more efficient than
HTTP.

secure

Optional

false

Whether to secure
communications with the
.NET-side agent. If true,
ColdFusion uses SSL to
communicate with .NET.

server

Optional

localhost

Host name or IP address
of the server where the
.NET-side agent is
running. Can be in any of
these forms:
server name (for
example, myserver)
IP address (for
example, 127.0.0.1)
You must specify this
attribute to access .NET
components on a
remote server.

Usage

The cfobject tag with a .NET or dotnet value for the type attribute creates a reference to a .NET object of a
given class. Using the reference, you can access the .NET object's fields and methods. The .NET classes do not
have to be local, and you can use the cfobject tag on a system that does not have .NET installed, including
UNIX-based or OS-X systems.
To access .NET assemblies, do the following:
Install the ColdFusion .NET Extension and run the .NET extension service on the system on which the
assemblies are installed. You do not have to install the extension or run the extension service on a
ColdFusion system that accesses only remote assemblies. For installation instructions, see Installing and
Using ColdFusion.
If the assemblies are located on a remote system, create Java proxies for the .NET classes that you use,
copy the proxies to the ColdFusion system, and configure the remote system for access by the proxies. For

© 2014 Adobe Systems Incorporated. All rights reserved.

879

Adobe ColdFusion Documentation

information on these steps, see Using Microsoft .NET Assemblies in the Developing ColdFusion Applications.
If the .NET assemblies are on your ColdFusion system, you do not have to perform these steps.
Accessing methods and fieldsYou call .NET methods as you use any other ColdFusion object methods. In the
simplest case, your application code uses the following format to call a .NET class method:


assembly="C:/Net/Assemblies/math.dll">


If a .NET class has multiple constructors, and you do not want ColdFusion to use the default constructor to
create the object, invoke a specific constructor by calling the special init method of the ColdFusion object
with the constructor's arguments. For example, you can use the following tags to instantiate com.foo.MyCla
ss(int, int):




You access and change .NET class public fields by calling the following methods:

Get_fieldName()
Set_fieldName()

For example, if the .NET class has a public field named account, you can access and modify its value by
using Get_acount() and Set_account() methods, respectively.
You can access, but not modify final fields, so you can only call Get_fieldName() for these fields.
Example

The following example uses the GetProcess method of the .NET System.Diagnostics.Process class to get and
display information about the processes running on the local system. Because it uses a core .NET class, for which
ColdFusion automatically generates proxies, you do not have to specify an assembly name in the cfobject tag.
For more complex examples, including examples that use custom .NET classes, see Using Microsoft .NET
Assemblies in the Developing ColdFusion Applications.

© 2014 Adobe Systems Incorporated. All rights reserved.

880

Adobe ColdFusion Documentation











Process ID
Name
Memory (KB)
Peak Memory (KB)
Virtual Memory Size (KB)
Start Time
Total Processor Time


#process.Get_Id()#
#process.Get_ProcessName()#
#process.Get_PagedMemorySize()/1000#
#process.Get_PeakPagedMemorySize()/1000#
#process.Get_VirtualMemorySize()/1000#
#process.Get_StartTime()#
#process.Get_TotalProcessorTime()#






© 2014 Adobe Systems Incorporated. All rights reserved.

881

Adobe ColdFusion Documentation

cfobject: COM object
Creates and manipulates a Component Object Model (COM) object. Invokes a registered automation server object
type. For information on OLEView, and about COM and DCOM, see the Microsoft OLE Development website: www.
microsoft.com.
To use this tag, provide the object's program ID or filename, the methods and properties available through the
IDispatch interface, and the arguments and return types of the object's methods. For most COM objects, you can get
this information with the OLEView utility.
Note
On UNIX, the cfobject tag does not support COM objects.

Syntax


type = "com"

Note
You can specify this tag's attributes in an attributeCollection attribute whose value is a
structure. Specify the structure name in the attributeCollection attribute and use the tag's
attribute names as structure keys.

See also

ReleaseComObject, cfcollection, cfexecute; COM in the Developing ColdFusion Applications
Attributes

Attribute

Req/Opt

class

Required

Component ProgID for the
object to invoke. When
using Java stubs to
connect to the COM
object, the class must be
the ProgID of the COM
object.

name

Required

String; name for the
instantiated component.

© 2014 Adobe Systems Incorporated. All rights reserved.

Default

Description

882

Adobe ColdFusion Documentation

action

Optional

context

Optional

server

Required if context =
"Remote"

create

create: instantiates a
COM object (typically, a
DLL) before invoking
methods or properties.
connect: connects to a
COM object (typically,
an EXE) running on
server.
inproc
local
remote
In Windows, if not
specified, uses Registry
setting.
Server name, using
Universal Naming
Convention (UNC) or
Domain Name Serve
(DNS) convention, in one
of these forms:
lanserver
lanserver
http://www.servername.
com
www.servername.com
127.0.0.1

type

Optional

Object type. The value co
m specifies COM objects:

Example

© 2014 Adobe Systems Incorporated. All rights reserved.

883

Adobe ColdFusion Documentation

cfobject (COM) Example






This object has #obj.Count# items.

 





The last name in the third item is #emp.lastname#.

 



Looping through all items in the collection:



Last name: #file2.lastname# 



© 2014 Adobe Systems Incorporated. All rights reserved.

884

Adobe ColdFusion Documentation

cfobject: component object
Description

Creates an instance of a ColdFusion component (CFC) object.
Syntax



Note
You can specify this tag's attributes in an attributeCollection attribute whose value is a
structure. Specify the structure name in the attributeCollection attribute and use the tag's
attribute names as structure keys.

See also

cfcollection, cfcomponent, cfexecute, cfindex, IsInstanceOf, cfreport, cfsearch, cfwddx; Using
ColdFusion components in the Developing ColdFusion Applications
Attributes

Attribute

Req/Opt

Default

component

Required

Name of component to
instantiate.

name

Required

String; name for the
instantiated component.
The name must not have
a period as the first or last
character.

type

Optional

component

Description

The object type. You can
omit this attribute or
specify component.
ColdFusion automatically
sets the type to
component.

Usage

When the cfobject tag creates an instance of the CFC, ColdFusion executes any constructor code in the CFC;
that is, it runs code that is not in the method definitions.On UNIX systems, ColdFusion searches first for a file with a
name that matches the specified component name, but is all lowercase. If it does not find the file, it looks for a
filename that matches the component name exactly, with the identical character casing.

© 2014 Adobe Systems Incorporated. All rights reserved.

885

Adobe ColdFusion Documentation
Example





#res#


#res#

© 2014 Adobe Systems Incorporated. All rights reserved.

886

Adobe ColdFusion Documentation

cfobject: CORBA object
Description

Calls methods on a registered CORBA object.
Syntax



Note
You can specify this tag's attributes in an attributeCollection attribute whose value is a
structure. Specify the structure name in the attributeCollection attribute and use the tag's
attribute names as structure keys.

See also

cfcollection, cfexecute, cfindex, cfreport, cfsearch, cfwddx; CORBA in the Developing ColdFusion
Applications
History

See the History section of the main cfobject tag page.
Attributes

Attribute

Req/Opt

class

Required

© 2014 Adobe Systems Incorporated. All rights reserved.

Default

Description
If context = "ior",
absolute path of file that
contains string version
of the Interoperable
Object Reference
(IOR). ColdFusion must
be able to read file; it
must be local to
ColdFusion server or
accessible on network.
If context = "namese
rvice", forward
slash-delimited naming
context for naming
service, for example: Al
laire//Doc/empobj
ect.

887

Adobe ColdFusion Documentation

context

Required

ior: ColdFusion uses
Interoperable Object
Reference (IOR) to
access CORBA server.
nameservice:
ColdFusion uses
naming service to
access server. This
option is valid only with
the InitialContext of a
VisiBroker Orb.

locale

Optional

Sets arguments for a call
to init_orb. Use this
attribute only for
VisiBroker ORBs. It is
available on C++, Version
3.2. The value must be in
the form: {{locale = "
-ORBagentAddr
199.99.129.33
-ORBagentPort
19000"}}Each type-value
pair must start with a
hyphen.

name

Required

String; name for the
instantiated component.
An application uses it to
reference the CORBA
object's methods and
attributes.

type

Required for CORBA

Object type. Must be cor
ba for CORBA objects.

Usage

ColdFusion Enterprise version 4.0 and later supports CORBA through the Dynamic Invocation Interface (DII). To
use cfobject with CORBA objects, provide the name of the file that contains a string-formatted version of the IOR,
or the object's naming context in the naming service; and the object's attributes, method names, and method
signatures.User-defined types (for example, structures) are not supported.
Example



© 2014 Adobe Systems Incorporated. All rights reserved.

888

Adobe ColdFusion Documentation

cfobject: Java or EJB object
Description

Creates and manipulates a Java and Enterprise Java Bean (EJB) object.
Syntax



Note
You can specify this tag's attributes in an attributeCollection attribute whose value is a
structure. Specify the structure name in the attributeCollection attribute and use the tag's
attribute names as structure keys.

See also

cfcollection, cfexecute, cfindex, IsInstanceOf, cfreport, cfsearch, cfwddx; Using Java objects in
the Developing ColdFusion Applications
Attributes

Attribute

Req/Opt

Default

Description

action

Optional

create

Only the default create a
ction, which creates the
object, is supported.

class

Required

The Java class.

name

Required

String; name for the
instantiated component.

type

Required for Java

Object type. Must be jav
a for Java and EJB
objects.

Usage

To call Java CFXs or Java objects, ColdFusion uses a Java Virtual Machine (JVM) that is embedded in the process.
You can configure JVM loading, location, and settings in the ColdFusion Administrator.Any Java class available in
the class path that is specified in the ColdFusion Administrator can be loaded and used from ColdFusion, by using
the cfobject tag.
Access Java methods and fields

1.
© 2014 Adobe Systems Incorporated. All rights reserved.

889

Adobe ColdFusion Documentation

1. Call the cfobject tag, to load the class. See the example code.
2. Use the initmethod with appropriate arguments, to call a constructor. For example:



Calling a public method on the object without first calling the init method results in an implicit call to the
default constructor. Arguments and return values can be any Java type (simple, array, object). ColdFusion
makes the conversions if strings are passed as arguments, but not if they are received as return
values.Overloaded methods are supported if the number of arguments is different.
Calling EJBs

To create and call EJB objects, use the cfobject tag. In the second example in the following section, the
WebLogic JNDI is used to register and find EJBHome instances.
Example











Share value = #value#



© 2014 Adobe Systems Incorporated. All rights reserved.

890

Adobe ColdFusion Documentation

cfobject: web service object
Description

Creates a web service proxy object.
Syntax


webservice= "service identifier"
password = "string"
proxyPassword = "string"
proxyPort = "port number"
proxyServer = "URL or IP address"
proxyUser = "string"
refreshWSDL = "no|yes"
type = "webservice"
username = "string"
wsdl2javaArgs = "argument string"
wsportname = "port name">

Note
You can specify this tag's attributes in an attributeCollection attribute whose value is a
structure. Specify the structure name in the attributeCollection attribute and use the tag's
attribute names as structure keys.

See also

cfcollection, cfexecute, cfindex, cfreport, cfsearch, cfwddx; Consuming web services in Using Web
Services in the Developing ColdFusion Applications
History

See the History section of the main cfobject tag page.
Attributes

Attribute

Req/Opt

name

Required

© 2014 Adobe Systems Incorporated. All rights reserved.

Default

Description
Local name for the web
service. String.

891

Adobe ColdFusion Documentation

webservice

Required

One of the following:
The absolute URL of
the web service.
The name (string)
assigned in the
ColdFusion
Administrator to the
web service.

password

Optional

Password set in the
Administrator, if any

The password to use to
access the web service. If
the webservice attribute
specifies a web service
name configured in the
ColdFusion Administrator,
overrides any password
specified in the
Administrator entry.

proxyPassword

Optional

http.proxyPassword
system property, if any

The user's password on
the proxy server.

proxyPort

Optional

http.proxyPort system
property, if any.

The port to use on the
proxy server.

proxyServer

Optional

http.proxyHost system
property, if any.

The proxy server required
to access the web service
URL.

proxyUser

Optional

http.proxyUser system
property, if any

The user ID to send to the
proxy server.

refreshWSDL

Optional

no

type

Optional

© 2014 Adobe Systems Incorporated. All rights reserved.

yes: reloads the WSDL
file and regenerates the
artifacts used to
consume the web
service
no
The object type. You can
omit this attribute or
specify webservice.

892

Adobe ColdFusion Documentation

username

Optional

wsdl2javaArgs

Optional

User name set in the
Administrator, if any

The user name to use to
access the web service. If
the webservice attribute
specifies a web service
configured name in the
ColdFusion Administrator,
overrides any user name
specified in the
Administrator entry.
A string that contains a
space-delimited list of
arguments to pass to the
WSDL2Java tool that
generates Java stubs for
the web services. Useful
arguments include the
following:
W or -noWrapped:
turns off the special
treatment of wrapped
document/literal style
operations.
a or -all: generates
code for all elements in
the WSDL, even
unreferenced ones.
w or -wrapArrays:
prefers building beans
to straight arrays for
wrapped XML array
types. This switch is not
in included in the Axis
documentation.
For detailed information
on valid arguments, see
the Apache Axis
WSDL2Java Reference.

wsportname

Optional

First port in the WSDL

The port name for the web
service. This value is case
sensitive and corresponds
to the port element's na
me attribute under the ser
vice element.Specify this
parameter if the web
service contains multiple
ports.

Usage

© 2014 Adobe Systems Incorporated. All rights reserved.

893

Adobe ColdFusion Documentation

Instantiates a proxy object for a web service. You can enter the absolute URL in this tag, or refer to a web service
that is entered in the ColdFusion Administrator. To minimize potential code maintenance, enter the web service in
the Administrator, and then refer to that name in this tag.

© 2014 Adobe Systems Incorporated. All rights reserved.

894

Adobe ColdFusion Documentation

cfobjectcache
Description

Flushes the query cache.
Category

Database manipulation tags
Syntax



Note
You can specify this tag's attributes in an attributeCollection attribute whose value is a
structure. Specify the structure name in the attributeCollection attribute and use the tag's
attribute names as structure keys.

See also

cfobject
History

ColdFusion 5: Added this tag.
Attributes

Attribute

Req/Opt

action

Required

© 2014 Adobe Systems Incorporated. All rights reserved.

Default

Description
clear: clears queries from
the cache in the
Application scope.

895

Adobe ColdFusion Documentation

cfoutput
Description

Displays output that can contain the results of processing ColdFusion variables and functions. Can loop over the
results of a database query.
Category

Data output tags
Syntax




Note
You can specify this tag's attributes in an attributeCollection attribute whose value is a
structure. Specify the structure name in the attributeCollection attribute and use the tag's
attribute names as structure keys.

See also

cfcol, cfcontent, cfdirectory, cftable
History

ColdFusion 4.5.0: Added the groupCaseSensitive attribute.
Attributes

Attribute

Req/Opt

© 2014 Adobe Systems Incorporated. All rights reserved.

Default

Description

896

Adobe ColdFusion Documentation

group

Optional

Query column to use to
group sets of records.
Eliminates adjacent
duplicate rows when data
is sorted. Use if you
retrieved a record set
ordered on one or more a
query columns. For
example, if a record set is
ordered on "Customer_I
D" in the cfquery tag,
you can group the output
on "Customer_ID."

groupCaseSensitive

Optional

yes

Boolean. Whether to
consider the case in
grouping rows.

maxRows

Optional

Displays all rows

Maximum number of rows
to display.

query

Optional

startRow

Optional

Name of cfquery from
which to draw data for
output section.
1

Row from which to start
output.

Usage

In the cfoutput tag body, ColdFusion treats text that is surrounded by number signs (#) as a ColdFusion variable
or function call. For example, the following code displays the text "Hello World!":


#myVar#

When you specify a query attribute, this tag loops over the query rows and produces output for each row within the
range specified by the startRow and maxRows values, and groups or eliminates duplicate entries as specified by
the grouping attribute values, if any. It also sets the query.currentRow variable to the current row being processed.
If you nest cfoutput blocks that process a query, you specify the query and group attributes at the top-most
level; you can specify a group attribute for each inner block except the innermost cfoutput block.
This tag requires an end tag.
Example





© 2014 Adobe Systems Incorporated. All rights reserved.

897

Adobe ColdFusion Documentation

SELECT Dept_ID, CorName, CorLevel
FROM courseList
ORDER by Dept_ID, CorLevel, CorName

cfoutput Example
cfoutput tells ColdFusion Server to begin processing, and then to hand back
control of page rendering to the web server.
For example, to show today's date, you could write #DateFormat("#Now()#"). If you
enclosed that expression in cfoutput, the result would
be#DateFormat(Now())#.
In addition, cfoutput may be used to show the results of a query operation, or
only a partial result, as shown:
There are #getCourses.recordCount# total records in our
query. Using the maxRows parameter, we are limiting our display to 4 rows.

#Dept_ID# #CorName# #CorLevel#


EXAMPLE: The next example uses the group attribute to eliminate duplicate lines
from a
list of course levels taught in each department.

SELECT Dept_ID, CorLevel
FROM courseList
ORDER by Dept_ID, CorLevel


#Dept_ID# #CorLevel#


cfoutput can also show the results of
such as getting the day of the week from
extract the integer representing the Day
the server function Now() and then apply
the DayofWeekAsString function:

a more complex expression,
today's date. We first
of the Week from
the result to


Today is #DayofWeekAsString(DayofWeek(Now()))#

Today is #DayofWeekAsString(DayofWeek(Now()))#
 EXAMPLE: This last example shows nested cfoutput tags:

SELECT Emp_ID, firstname, lastname, e.dept_id, salary, d.dept_name
FROM employee e, departmt d
WHERE e.dept_id = d.dept_id
ORDER BY d.dept_name



#dept_name#



© 2014 Adobe Systems Incorporated. All rights reserved.

898

Adobe ColdFusion Documentation






© 2014 Adobe Systems Incorporated. All rights reserved.

899

Adobe ColdFusion Documentation



Employee
Salary


#empSalary.lastname#, #empSalary.firstname#
#DollarFormat(empSalary.salary)#


Total
#DollarFormat(deptTotal)#




#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

900

Adobe ColdFusion Documentation

Tags p-q
This section lists tags starting with alphabets P-Q with their description.
cfparam
cfpdf
cfpdfform
cfpdfformparam
cfpdfparam
cfpdfsubform
cfpod
cfpop
cfpresentation
cfpresentationslide
cfpresenter
cfprint
cfprocessingdirective
cfprocparam
cfprocresult
cfprogressbar
cfproperty
cfquery
cfqueryparam

© 2014 Adobe Systems Incorporated. All rights reserved.

901

Adobe ColdFusion Documentation

cfparam
Description

Tests for the existence of a parameter (that is, a variable), validates its data, and, if a default value is not assigned,
optionally provides one.
History

ColdFusion 10: Added the attribute {{maxLength}}
ColdFusion MX 7:
Added min, max, and pattern attributes.
Added creditcard, email, eurodate, float, integer, range, regex, regular_expression, ssn, s
ocial_security_number, time, URL, USdate, XML, and zipcode values of the type attribute.
Category

Variable manipulation tags
Syntax



See also

cfcookie, cfregistry, cfsavecontent, cfschedule, cfset; Validating data with the IsValid function and the
cfparam tag in the Developing ColdFusion Applications
Attributes

Attribute

Req/Opt

name

Required

© 2014 Adobe Systems Incorporated. All rights reserved.

Default

Description
Name of the parameter
(variable) to test (such as
"Client.Email " or
"Cookie.BackgroundColor
"). If omitted, and if the
parameter does not exist,
an error is thrown.

902

Adobe ColdFusion Documentation

default

Optional

Value to set parameter to
if it does not exist. Any
expression used for the
default attribute is
evaluated, even if the
parameter exists. The
result is not assigned if
the parameter exists, but
if the expression has side
effects, they still occur.

max

Optional

The maximum valid value;
used only for range valid
ation.

maxLength

Optional

Used to specify the
maximum character
length of email, url, and
string.

min

Optional

The minimum valid value;
used only for range valid
ation.

pattern

Optional

A JavaScript regular
expression that the
parameter must match;
used only for regex or re
gular_expression vali
dation.

type

Optional

any

The valid format for the
data; one of the following.
For detailed information
on validation algorithms,
see Validating form data
using hidden fields in Vali
dating data in the Develop
ing ColdFusion
Applications.
any: any type of value.
array: an array of
values.
binary: a binary value.
boolean: a Boolean
value: yes, no, true,
false, or a number.
creditcard: a 13-16
digit number conforming
to the mod10 algorithm.

© 2014 Adobe Systems Incorporated. All rights reserved.

903

Adobe ColdFusion Documentation

date or time: a
date-time value.
email: a valid e-mail
address.
eurodate: a date-time
value. Any date part
must be in the format
dd/mm/yy. The format
can use /, -, or .
characters as
delimiters.
float or numeric: a
numeric value.
guid: a Universally
Unique Identifier of the
form "XXXXXXXX-XXXX
-XXXX-XXXX-XXXXXX
XXXXXX" where X is a
hexadecimal number.
integer: an integer.
query: a query object.
range: a numeric
range, specified by the
min and max attributes.
regex or regular_ex
pression: matches
input against pattern
attribute.
ssn or social_secur
ity_number: a U.S.
social security number.
string: a string value
or single character.
struct: a structure.
telephone: a standard
U.S. telephone number.
URL: an http, https, ftp,
file, mailto, or news
URL.
UUID: a ColdFusion
Universally Unique
Identifier, formatted XXX
XXXXX-XXXX-XXXX-X
XXXXXXXXXXXXXX,
where X is a
hexadecimal number.
See CreateUUID.
USdate: a U.S. date of
the format mm/dd/yy,
with 1-2 digit days and
months, 1-4 digit years.

© 2014 Adobe Systems Incorporated. All rights reserved.

904

Adobe ColdFusion Documentation

variableName: a
string formatted
according to
ColdFusion variable
naming conventions.
xml: XML objects and
XML strings.
zipcode: U.S., 5- or
9-digit format ZIP
codes.

Usage

You can use this tag to make the following tests:
To test whether a required variable exists, use this tag with only the name attribute. If it does not exist,
ColdFusion stops processing the page and returns an error.
To test whether a required variable exists, and that it is of the specified type, use this tag with the name and t
ype attributes. If the variable does not exist or its value is not of the specified type, ColdFusion returns an
error.
To set a default value for the variable, use this tag with the name and default attributes. If the variable does
not exist, it is created and set to the default attribute value. If the variable exists, processing continues; the
value is not changed.
If you specify variableName for the typeattribute, the parameter's value must be a string that is in
ColdFusion variable name format; that is, starts with a letter, underscore (_), or Unicode currency symbol,
and contains letters, numbers, underscores, periods, and Unicode currency symbols, only. ColdFusion does
not check whether the parameter value corresponds to an existing ColdFusion variable.
To improve performance, avoid using the cfparam tag in ColdFusion functions, including
in CFC methods. Instead, place the cfparam tags in the body of the CFML pages.

Example

© 2014 Adobe Systems Incorporated. All rights reserved.

905

Adobe ColdFusion Documentation













cfparam Example
cfparam is used to set default values so that a developer does not have to
check for the existence of a variable using a function like IsDefined.
The default value of our tempVar is "#StoreTempVar# "


The value of tempVar has changed: the new value is
#tempVar#




"cfparam.cfm" method = "post">
value for tempVar, and hit submit:

"Text" name = "tempVar">
"Submit" name = "" value = "submit">

© 2014 Adobe Systems Incorporated. All rights reserved.

906

Adobe ColdFusion Documentation

cfpdf
Description
Manipulates existing PDF documents. The following list describes some of the tasks you can perform with the cfpd
f tag:
Merge several PDF documents into one PDF document.
Delete pages from a PDF document.
Merge pages from one or more PDF documents and generate a new PDF document.
Linearize PDF documents for faster web display.
Remove interactivity from forms created in Acrobat to generate flat PDF documents.
Encrypt and add password protection to PDF documents.
Generate thumbnail images from PDF documents or pages.
Add or remove watermarks from PDF documents or pages.
Retrieve information associated with a PDF document, such as the software used to generate the file or the
author, and set information for a PDF document, such as the title, author and keywords.
Create PDF portfolios
Add and remove header/footer from PDF documents
Optimize PDF documents
History

ColdFusion 11 has added the following new attributes to the  tag:
keystore
keystorepassword
keyalias
keypassword
author
signaturefieldname
unsignall
height
width
ColdFusion 8: Added this tag.ColdFusion 9: Added new attributes: jpgdpi, maxBreadth, noAttachments, left
Margin, algo, noMetadata, noBookMarks, noJavaScripts, useStructure, noFonts, text, noComments,
encodeAll, numberFormat, compressTIFFs, addQuads, rightMargin, topMargin, bottomMargin, noTh
umbnails, align, noLinks, maxLength, hires, hScale, overridepage, honourspaces, maxScale, packa
ge, vScale

Category

Data output tags
Syntax

Add a watermark to a PDF document

\\one of the following:
destination = "PDF output file pathname"
name = "PDF document variable name"
image = "image file name to be used as the footer"
text = "text to be used in the footer"
Add headers

align = "left|right|center"
leftmargin = "value of the header left marign"
rightmargin = "value of the header right margin"
numberformat = "LOWERCASEROMAN|NUMERIC|UPPERCASEROMAN" 
opacity = "header opacity"
topmargin = "value of the top margin of the header"
\\one of the following:
destination = "PDF output file pathname"
name = "PDF document variable name"
text = _PAGELABEL: add current page label|_LASTPAGELABEL: add last page label|
_PAGENUMBER: add current page number|_LASTPAGENUMBER: add last page
number \\text for the header. You can also add a normal text string.
image = "image file name to be used as the header"
Add footer

destination = "PDF output file pathname"
name = "PDF document variable name"
align = "left|right|center"
one of the following:
image = "image file name to be used as the footer"
text =
_PAGELABEL: add current page label|_LASTPAGELABEL: add last page label|
_PAGENUMBER: add current page number|_LASTPAGENUMBER: add last page
number \\text for the header
leftmargin = "value of the footer left marign"
rightmargin = "value of the footer right margin"
numberformat
opacity = "footer opacity"
bottommargin = "value of the bottom margin"
Delete pages from a PDF document

Delete headers and footers

Merge PDF documents into an output PDF file

\\required only when package is specified as true
order = "name|time"
one of the following if  is specified:
name = "PDF document variable name"
destination = "PDF output file pathname"
optional
package = "true|false" 
ascending = "yes|no"
keepBookmark = "yes|no"
overwrite = "yes|no"
pages = "pages to merge in PDF source file"
password = "PDF source file password"
stopOnError = "yes|no"
\\one of the following:
destination = "PDF output file pathname"
name = "PDF document variable name">
Use DDX instructions to manipulate PDF documents

optional
action="processddx"
Set passwords and encrypt PDF documnets

Name a PDF document variable

Remove a watermark from a PDF document

one of the following:
destination = "PDF output file pathname"
name = "PDF document variable name"
Set information about a PDF document

Generate thumbnails from pages in a PDF document

pages = "page or pages to make into thumbnails"
resolution= "low|high"
scale = "percentage between 1 and 100"
transparent = "yes|no">
hires = "yes|no"
overridepage = "yes|no"
compresstiffs = "yes|no"
maxscale = "maximum scale of the thumbnail"
maxlength = "maximum length of the thumbnail"
maxbreadth = "maximum width of the thumbnail"
Write a PDF document to an output file

optional
flatten = "yes|no"
overwrite = "yes|no"
password = "PDF source file password"
saveOption = "linear|incremental|full"
version = "1.1|1.2|1.3|1.4|1.5|1.6">
encodeall = "yes|no"
Reduce the quality of a PDF document

pages = "*" 
optional
vscale= "Vertical scale of the image to be modified. Valid values are vscale>0"
hscacle="Horizontal scale of the image to be modified. Valid values are hscale<1"
destination = "PDF output file pathname"
name = "PDF document variable"
noattachments = "Discard all attachments"
nobookmarks = "Discard all bookmarks"
nocomments = "Discard all comments"
nofonts = "Discard all fonts"
nojavascripts = "Discard all JavaScript actions"
nolinks = "Discard external cross-references"
nometadata = "Discard document information and metadata"
nothumbnails = "Discard embedded page thumbnails"
overwrite = "true" 
password = "" 
Extract text

source= "absolute or relative path of the PDF file|PDF document variable|
cfdocument variable"
pages = "*" 
optional
addquads = "add the position or quadrants for the text in the PDF"
honourspaces = "true|false"
overwrite = "true" 
password = "" 
type = "string|xml" 
one of the following:
destination = "PDF output file pathname"
name = "PDF document variable"
usestructure = "true|false"
Extract image


© 2014 Adobe Systems Incorporated. All rights reserved.

912

Adobe ColdFusion Documentation

source = "absolute or relative path of the PDF file|PDF document variable|
cfdocument variable"
pages = "*" 
optional
overwrite = "true|false" 
format = "png|tiff|jpg" 
imageprefix = "*" 
password = "" 
destination = "PDF output file pathname"
Page level transformations

rotation = "0|90|180|270"
vscale = "length of the page to be transformed"
one of the following:

© 2014 Adobe Systems Incorporated. All rights reserved.

913

Adobe ColdFusion Documentation

destination = ""Path of the directory where the PDF document will be saved"
name = "PDF document variable"

Note
You can specify this tag's attributes in an attributeCollection attribute whose value is a
structure. Specify the structure name in the attributeCollection attribute and use the tag's
attribute names as structure keys.

See also

cfdocument, cfdocumentsection, cfpdfform, cfpdfformparam, cfpdfparam, cfpdfsubform, cfprint,
IsDDX, IsPDFFile, IsPDFObject, Assembling PDF Documents in the Developing ColdFusion Applications
Attributes

Attribute

Action

Req/Opt

Description

action

N/A

Optional

Action to take:
addWatermark
deletePages
getInfo
merge
processddx
protect
read
removeWatermark
setInfo
sign
thumbnail
write
optimize
extracttext
extractimage
addheader

© 2014 Adobe Systems Incorporated. All rights reserved.

914

Adobe ColdFusion Documentation

addfooter
removeheaderfooter
transform
unsign
validatesignature
New in ColdFusion
11–Validates all the
signatures in the
document. The name
attribute will then
store the resultant
struct of this
operation. The name
attribute will contain
2 elements:
A Boolean
field that
indicates
whether
all the
signatures
have been
deemed
valid or
not.
An array
list
consisting
of the
names of
all the
signatures
that were
invalid. If
all the
signatures
are valid,
the array
list will be
empty.
readsignaturefields

© 2014 Adobe Systems Incorporated. All rights reserved.

915

Adobe ColdFusion Documentation

New in ColdFusion
11–Reads all the
signature fields and
returns a query
object in the variable
indicated by the
attribute name. This
query object will
have 4 columns:
Name–A
fully
qualified
name of
the
signature
field
Certifiable
--Indicates
if this field
can
contain an
author
signature
or not
Signable–I
ndicates
whether
this field
can be
signed or
not
Is
signed–In
dicates
whether
this field is
already
signed or
not
addquads

extracttext

Optional

Add the position or
quadrants of the
thumbnail

align

addheader
addfooter

Optional

Aligns the header and
footer in PDF.

© 2014 Adobe Systems Incorporated. All rights reserved.

916

Adobe ColdFusion Documentation

algo

optimize

Required

Specifies the algorithm for
image downsampling. The
values are bilinear, bi
cubic, and nearest_ne
ighbour

ascending

merge

Optional

Order in which the PDF
files are sorted:
yes: Files are sorted in
ascending order
no: Files are sorted in
descending order
Applicable only when you
specify the directory at
tribute.

author

sign

Optional

Business transactions,
including financial, legal,
and other regulated
transactions, require high
assurance when signing
documents. When
documents are distributed
electronically, it is
important that recipients
can:
Verify document
authenticity – confirm the
identity of person who
signed the document
Verify document integrity
– confirm that the
document has not been
altered in transit
Author-based signatures
provide both of these
security services.
If attribute is not
mentioned then it is
treated as author=false

bottomMargin

addfooter

© 2014 Adobe Systems Incorporated. All rights reserved.

Optional

Specifies the value of the
bottomMargin

917

Adobe ColdFusion Documentation

copyFrom

addWatermark

Optional

Pathname of the PDF
document from which to
use the first page as a
watermark

compresstiffs

thumbnail

Optional

Compress thumbnail
which are in TIFF format.

ddxfile

processddx

Required

Pathname of the DDX file,
or a string with DDX
instructions

destination

addWatermark
archive
deletePages
merge
protect
removeWatermark
sign
setInfo
thumbnail
write
optimize
extracttext
extractimage
addheader
addfooter
removeheaderfooter
transform

Required for the write a
ctionOptional for all other
actions

© 2014 Adobe Systems Incorporated. All rights reserved.

918

Adobe ColdFusion Documentation

Pathname of the modified
PDF document. If the
destination file exists, set
the overwrite attribute to y
es. If the destination file
does not exist,
ColdFusion creates the
file, if the parent directory
exists.
You can specify the dest
ination attribute or the
name attribute, but not
both.
For the thumbnail actio
n, the destination is the
directory path where the
images are written. If you
specify a relative
pathname to the
destination directory, the
destination directory is
relative to the template
directory. If you do not
specify a destination
directory, ColdFusion
creates a directory called
thumbnails in the directory
in the template directory.
For the optimize action,
destination is the path
where the PDF document
which needs to be
optimized is located. For
extracttext and
extractimage, destination
is the path of the PDF
document from which the
text or image needs to be
extracted.
For addheader, addfooter,
removeheader footer,
destination is the path of
the PDF document where
you need to add a header
or footer, or remove the
header and footer.
For transform, destination
specifies the directory
path of the PDF document
where you need to
perform page level
transformations.

© 2014 Adobe Systems Incorporated. All rights reserved.

919

Adobe ColdFusion Documentation

directory

merge

Optional

Directory of the PDF
documents to merge.
Specify either the direct
ory attribute or the sour
ce attribute. If you specify
the directory attribute,
ColdFusion orders the
documents by filename in
descending order, by
default. To change the
order of the files, use the
order attribute.

encodeall

write

Optional

Encode streams that are
not encoded to optimize
page content

encrypt

protect

Optional

Encryption type for the
PDF output file:
RC4_40
RC4_128
RC4_128M
AES_128
None
For more information, see
the section Encryption for
PDF documents.

flatten

write

Optional

Applies to forms created
in Acrobat only (not forms
created in LiveCycle);
specifies whether
interactivity is turned off:
yes: the form fields are
no longer interactive.
no: the form fields remain
interactive.

© 2014 Adobe Systems Incorporated. All rights reserved.

920

Adobe ColdFusion Documentation

foreground

addWatermark

Optional

Placement of the
watermark on the page:
yes: the watermark
appears in the foreground
(over the page content).
no: the watermark
appears in the
background (behind the
page content).

format

thumbnail

Optional

File type of thumbnail
image output:
jpg
tiff
png

hires

thumbnail

optional

Sets a high resolution for
the thumbnail if set to yes.

height

sign

Optional

Height of the signature
field.

honourspaces

extracttext

optional

Set this option to "true"
, for improved readability
and spacing.

hscale

optimize

optional

Horizontal scale of the
image to be modified.
Valid values are hscale<1.

image

addWatermark

Optional

Image used as a
watermark. You can
specify a pathname, a
variable that contains an
image file, or a
ColdFusion image
variable.

© 2014 Adobe Systems Incorporated. All rights reserved.

921

Adobe ColdFusion Documentation

imagePrefix

thumbnail

Optional

Prefix used for each
image thumbnail file
generated. The image
filenames use the format: i
magePrefixpagen.format.
For example, the
thumbnail for page 1 of a
document with the image
Prefix attribute set to my
Thumbnail is
myThumbnail_page_1.jpg
.

info

setInfo

Required

Structure variable for
relevant information, for
example, " #infoStruct
#" . You can specify the
Author, Subject, Title, and
Keywords for the PDF
output file.

inputFiles

processddx

Required

Structure that maps the
PDF source files to the
input variables in the DDX
file, or a string of elements
and their pathname.

isBase64

addWatermark

Optional

Valid only when the imag
e attribute is specified.
Specifies whether the
image used as a
watermark is in Base64
format:
yes: the image is in
Base64 format.
no: the image is not in
Base64 format.

keepBookmark

merge

Optional

Specifies whether
bookmarks from the
source PDF documents
are retained in the merged
document:
yes: the bookmarks are
retained.
no: the bookmarks are
removed.

© 2014 Adobe Systems Incorporated. All rights reserved.

922

Adobe ColdFusion Documentation

keyalias

sign

Optional

Alias of the key with which
the certificate and private
key are stored in the
keystore. If it is not
specified, the first entry in
the keystore is chosen as
the alias.

keystore

sign

Required

The
location of the keystore
file. For example,
C:\OpenSSL\bin\keystore.
jks.

keypassword

sign

Optional

Password for your private
key. If not specified the
keystorepassword is
used.

keystorepassword

sign

Required

The password of the
keystore.

leftmargin

addheader

Optional

Specifies the value of the
header left margin

maxbreadth

thumbnail

Optional

Specifies maximum width
of the thumbnail

maxlength

thumbnail

Optional

Specifies the maximum
length of the thumbnail

maxscale

thumbnail

Optional

Specifies the maximum
scale of the thumbnail

© 2014 Adobe Systems Incorporated. All rights reserved.

923

Adobe ColdFusion Documentation

name

addWatermark
deletePages
getInfo
merge
processddx
protect
read
readsignaturefields
removeWatemark
write
tranform
addheader
addfooter
removeheaderfooter

Required:
getInfo
processddx
read
readsignaturefields
Optional:
addWatermark
deletePages
merge
protect
removeWatermark
tranform
addheader
addfooter
removeheaderfooter

PDF document variable
name, for example, myBo
ok.
If the source is a PDF
document variable, you
cannot specify the name a
ttribute again; you can
write the modified PDF
document to the
destination.
You can specify the dest
ination attribute or the
name attribute, but not
both.
For the processddxactio
n, the name represents
the structure that is
populated with the
success or failure of the
output variables.
For the readsignaturefield
s action, the name
represents the structure
thats is populated with the
info of all the signature
fields in the source PDF
document.

newOwnerPassword

protect

Optional (see Description)

Password used to set
permissions on a PDF
document.
To change the default
permissions, specify the n
ewOwnerPassword attrib
ute. For more information,
see the section PDF
document passwords.

newUserPassword

protect

Optional (see Description)

Password used to open
PDF document.Specify
either the newUserPassw
ord attribute or a newOwn
erPassword attribute; if
you specify both, the
passwords must differ.
For more information, see
the section PDF
document passwords.

© 2014 Adobe Systems Incorporated. All rights reserved.

924

Adobe ColdFusion Documentation

noattachments

thumbnail

Optional

Removes all attachments
from PDF documents.

noattachments

optimize

Optional

Remove all file
attachments

nobookmarks

optimize

Optional

Remove bookmarks from
PDF document

nocomments

optimize

Optional

Remove comments from
PDF document

nofonts

optimize

Optional

Remove font styling

nojavascripts

optimize

Optional

Remove all document
level JavaScript actions

nolinks

optimize

Optional

Remove external
cross-references

nometadata

optimize

Optional

Remove document
information and metadata

nothumbnails

optimize

Optional

Remove embedded page
thumbnails

numberformat

addfooter

Optional

Specify the numbering
format for PDF pages in
the footer.

opacity

addWatermark
addheader
addfooter

Optional

Opacity of the watermark.
Valid values are integers
in the range 0
(transparent) through 10
(opaque).

© 2014 Adobe Systems Incorporated. All rights reserved.

925

Adobe ColdFusion Documentation

order

merge

Optional

Order in which the PDF
documents in the directory
are merged:
name: orders the
documents alphabetically
by filename.
time: orders the
documents by timestamp.
By default, ColdFusion
merges the files in
descending order (for
example, from Z to A). To
change this, set the
ascending attribute to yes
.

outputFiles

processddx

Required

Structure that contains the
output files in the DDX file
or string as keys and the
pathname to the result file
as the value.

overwrite

addSign
addWatermark
archive
deletePages
merge
protect
removeWatermark
Sign
setInfo
thumbnail
write
tranform
addheader
addfooter
removeheaderfooter

Optional

Specifies whether PDF
output overwrites the
destination file:

merge

Optional

package

© 2014 Adobe Systems Incorporated. All rights reserved.

yes: overwrites the
destination file.
no: does not overwrite the
destination file.
For the thumbnail actio
n, specifies whether to
overwrite the destination
directory. If the directory
exists, the thumbnails are
not generated unless ove
rwrite is set to yes.
Create PDF packages

926

Adobe ColdFusion Documentation

pages

addWatermark
deletePages
merge
removeWatermark
optimize
extracttext
extractimage
sign
addheader
addfooter
removeheaderfooter
transform

Required:
deletePages
Optional:
addWatermark
merge
removeWatermark
thumbnail
optimize
extractext
extractimage
tranform
addheader
addfooter
removeheaderfooter

Page or pages in the
source PDF document on
which to perform the
action. You can specify
multiple pages and page
ranges as follows:
"1,6-9,56-89,100,
110-120".
For the removeWatermark
action, the pages attribute
applies only to the
watermark type.
ColdFusion ignores
duplicate pages and
numbers greater than the
total page count. For
action=sign, value of
attribute pages should
consist of just one page
number.

password

addWatermark
addSign
archive
deletePages
getInfo
merge
protect
read
readsignaturefields
removeWatermark
setInfo
sign
thumbnail
unsign
write
optimize
extracttext
extractimage
addheader
addfooter
removeheaderfooter
validatesignaturefi
elds
transform

Optional

Owner or user password
of the source PDF
document, if the
document is
password-protected.

© 2014 Adobe Systems Incorporated. All rights reserved.

927

Adobe ColdFusion Documentation

permissions

protect

Optional

Type of permissions on
the PDF document:
All
AllowAssembly
AllowCopy
AllowDegradedPrinti
ng
AllowFillIn
AllowModifyAnnotati
ons
AllowModifyContents
AllowPrinting
AllowScreenReaders
AllowSecure
None
Except for All or None,
you can specify a
comma-separated list of
permissions. To set
permissions, you must
also set the newOwnerPa
ssword attribute.

position

addWatermark
sign

Optional

The position attribute is
the coordinate of the
lower left corner of the
signature field.

resolution

thumbnail

Optional

Image quality used to
generate thumbnail
images:
high: use high resolution
(uses more memory).
low: use low resolution.

rotation

addWatermark
transform

© 2014 Adobe Systems Incorporated. All rights reserved.

Optional

Degree of rotation of the
watermark image on the
page, for example, "30".

928

Adobe ColdFusion Documentation

saveOption

write

Optional

Save options for the PDF
output:
full: normal save
(default)
incremental: required
to save modifications to a
signed PDF document.
linear: for faster
display.

scale

thumbnail

Optional

Size of the thumbnail
relative to the source
page. The value
represents a percentage
from 1 through 100.

showOnPrint

addWatermark

Optional

Specify whether to print
the watermark with the
PDF document:
yes: the watermark is
printed with the PDF
document.
no: the watermark is
display-only.

signaturefieldname

sign
unsign

© 2014 Adobe Systems Incorporated. All rights reserved.

Optional

Name of signature field in
which the user wants to
sign or the name of the
signature field that the
user wants to unsign.

929

Adobe ColdFusion Documentation

source

stopOnError

archive
addWatermark
deletePages
getInfo
merge
protect
read
removeWatermark
setInfo
sign
thumbnail
write
optimize
extracttext
extractimage
addheader
addfooter
removeheaderfooter
unsign
transform

Required (see Usage
section for merge)

merge

Optional

PDF document used as
the source. The source
can be one of the
following:
An absolute or relative
pathname to a PDF
document, for example,
c:\work\myPDF.pdf or
myPDF.pdf.
A PDF document variable
in memory that is
generated by the cfdocu
ment tag or the cfpdf ta
g, for example, " myPDFdo
c".

Valid only if the directory
attribute is specified. If the
specified directory
contains files other than
ColdFusion-readable PDF
files, ColdFusion either
stops merge process or
continues.
yes: stops the merge
process if invalid PDF files
exist in the specified
directory.
no: continues the merge
process even if invalid
files exist in the specified
directory.

transparent

thumbnail

Optional

(format="png" only)
Specifies whether the
image background is
transparent or opaque:
yes: the background is
transparent.
no: the background is
opaque.

© 2014 Adobe Systems Incorporated. All rights reserved.

930

Adobe ColdFusion Documentation

unsignall

unsign

Optional

Unsigns all the signatures
in the document.

useStructure

extracttext

Optional

Let's you extract content
based on the PDF
structure. For better
readability of the extracted
text, use this attribute
together with the attribute
honourspaces.

version

write

Optional

Version of the PDF used
to write the document:
1.1
1.2
1.3
1.4
1.5
1.6
For more information, see
the section PDF versions.

Width

sign

optional

Width of the signature
field.

Note
To modify the PDF source document, specify the same file pathname for the source and desti
nation attributes, and set the overwrite attribute to yes.

Archiving a signed PDF created using ColdFusion behaves abnormally when opened using Adobe Acrobat. To fix
the document for archiving enable the "Changing the Document" permission under the Security options of Acrobat.
Usage

You use the cfpdf tag to manipulate and assemble existing PDF documents. Although the cfpdf tag provides
much of the functionality available in Acrobat, you cannot use this tag to generate a PDF document from another file
format. To create PDF output from HTML and CFML content, use the cfdocument tag.
You cannot embed a cfpdf tag within a cfdocument tag or embed a cfdocument tag within a cfdpdf tag;
however, you can write the output of a cfdocument tag to a variable and pass the variable to the cfpdf tag. The
following example shows how to use the cfdocument tag to create a cover page and add it to a merged PDF
document:

© 2014 Adobe Systems Incorporated. All rights reserved.

931

Adobe ColdFusion Documentation





Here is a cover page










You can use the cfpdf tag to assemble interactive PDF form files into a single PDF document and flatten forms
created in Acrobat (by using the flatten attribute with the write action); however, to process PDF form data, use
the cfpdfform and related tags. You cannot use the cfpdf tag to flatten forms created in Adobe LiveCycle
Designer ES.
Reading and writing PDF files

The cfpdf tag provides several options for reading and writing PDF files. You can specify a PDF variable or a PDF
file as the source, and you can write the output to a variable or to a file (but not both). The following table explains
the read and write operations:
Task

Attributes

Example

Overwrite a source PDF file

Specify the PDF file pathname as
the source and do not specify a de
stination.



Write a PDF document in memory
to a file

Specify the PDF variable as the so
urce and a PDF file pathname for
the destination.



© 2014 Adobe Systems Incorporated. All rights reserved.

932

Adobe ColdFusion Documentation

Write a PDF document to a new file

Specify a PDF file pathname as the
source and a different PDF file
pathname as the destination.



Write a PDF file to a PDF variable

Specify the PDF file pathname as
the source and a PDF variable na
me.



Overwrite a PDF document in
memory

Specify the PDF variable name as
the source and do not specify a
destination.



Working with PDF files in memory

ColdFusion gives you the option to write a PDF file to a variable by using the name attribute, which is useful if you
want to perform multiple operations on a document before writing it to a file. However, this is practical for small files
only because of memory requirements. If you are working with large PDF documents, write the PDF documents to
files.ColdFusion recommends that you do not specify the name attribute when you specify a variable as the source
because it creates a copy, which increases processing. In most cases, this is unnecessary because you can reuse
variables even after you write them to files.
Note
When you use PDF variables within a try/catch block and ColdFusion generates an error, the
variables are unusable after the error is generated.

Printing PDF documents

Use the cfprint tag to print PDF documents. Markups, such as sticky notes, comments, and editorial revisions,
are not printed with the document.
addWatermark action Use the addwatermarkaction to add a watermark to specified pages in a PDF
document. You can add a watermark in one of the following ways:
Use the first page of another PDF document as a watermark. ColdFusion overlays the copyfrom pag
e on the source document, without enlarging the image.
Specify an image file to use as a watermark.
Specify an image in memory by using an image variable.
The following code shows how to use the first page of a PDF document as a watermark:



By default, ColdFusion applies the watermark to all of the pages in the output file, with the watermark

© 2014 Adobe Systems Incorporated. All rights reserved.

933

Adobe ColdFusion Documentation

image centered on the page. The following code applies a JPEG image as a watermark to the first
page of the output file:



To specify a ColdFusion image as a watermark, use the cfimage tag or Image functions. The addwa
termark action also supports RGB and ARGB images, especially the images added using the cfima
getag and related functions. The following example converts an image to grayscale and applies it as a
watermark to a PDF file:








For more information on ColdFusion images, see Creating and Manipulating ColdFusion Images in the
Developing ColdFusion Applications.
addfooterUse this action to add a footer in a PDF document. Specify the source where the PDF document is
located and the destination where the new PDF document with the footer is saved, as shown in the following
code snippet:

 // By default, the alignemnt is center

You can also specify an image or text that you have to insert in the footer along with various other attributes
such as align, bottommargin, leftmargin, numberformat, and opacity.
addheaderUse this action to add header in a PDF document. Specify the source and destination for the PDF
document and specify the text or image that you want to insert in the header, as shown in the following code:

© 2014 Adobe Systems Incorporated. All rights reserved.

934

Adobe ColdFusion Documentation



deletePages action Use the deletePagesaction to remove pages from a specified PDF document. You
can specify a single page, a page range, or a comma-separated list of pages, as the following code shows:



extracttext Use the extracttextaction to extract all words from the specified page numbers in the PDF
document, as shown in the following code snippet:



The images are extracted and saved in the directory that you specify in the destination attribute. You can
specify a prefix for the images (imageprefix) being extracted, otherwise the system prefixes the image
name similar to "cf+page number". To save the images in a specific format, use the format attribute.
getInfo action Use the getInfoaction to extract information associated with the PDF document, such as the
author, title, and creation date. You specify the name of the structure variable that contains the relevant data
associated with the file, as the following code shows:


#PDFInfo.title#
#PDFInfo.author#
#PDFInfo.keywords#
#PDFInfo.created#

For a complete list of information elements, use the cfdumptag, as the following code shows:

© 2014 Adobe Systems Incorporated. All rights reserved.

935

Adobe ColdFusion Documentation



Note
To view the permissions for a PDF document that is password-protected, specify the user
password, not the owner password. If you specify the owner password, all permissions are
set to Allowed.

Reducing quality of PDF document

The optimize action is used to downsample images and discard unused objects in a PDF document.
optimize To downsample images in a PDF document, the algos attribute is used with values bilinear, bi
cubic, and nearest_neighbour. The following code snippet generates a PDF after image downsampling:



You can also discard unused objects such as comments, JavaScripts, attachments, bookmarks, and
metadata from your PDF document using the following attributes with optimize action:



Transforming pages in a PDF document

You can scale a page, specify the position, and rotation values for pages in a PDF document.
transform The transform action has four attributes that define the size (hscale, vscale), position(posit
ion), and rotation (rotation) of a page. The following code snippet shows the usage:

© 2014 Adobe Systems Incorporated. All rights reserved.

936

Adobe ColdFusion Documentation


hscale = ".5"
vscale = ".15"
position = "8, 10"
rotation = "180">

The value for rotation must be in steps (0, 90, 180, 270). If you specify any other value, the system generates
an error.
PDF file information elements

The following table describes the information elements you can retrieve with the getinfo action:
Element

Example

Description

Application

Acrobat PDFMaker 7.0.7 for Word

Application used to create the PDF
document. This value is read-only.

Author

Harper Lee

Author of the PDF document. You
can specify a text string with the se
tInfo action.

CenterWindowOnScreen

empty string

Display setting for initial view of the
PDF document. To change this
setting, use the processddx action
with the InitialViewProfile D
DX element.

ChangingDocument

Not Allowed

Permissions assigned for editing
the PDF content. To change this
setting, use the permissions attri
bute with the protect action.

Commenting

Allowed

Permissions assigned for adding
comments to the PDF document.
To change this setting, use the per
missions attribute with the prote
ct action.

ContentExtraction

Allowed

Permissions assigned for extracting
content from the PDF document. To
change this setting, use the permi
ssions attribute with the protect
action.

© 2014 Adobe Systems Incorporated. All rights reserved.

937

Adobe ColdFusion Documentation

CopyContent

Allowed

Permissions assigned for copying
content from the PDF document. To
change this setting, use the permi
ssions attribute with the protect
action.

Created

D:20061121155226-05'00'

System-generated creation date of
the PDF document. You can specify
a text string with the setInfo actio
n.

DocumentAssembly

Not Allowed

Permissions assigned for merging
the PDF document with other PDF
documents. To change this setting,
use the permissions attribute
with the protect action.

Encryption

Password Security

Specifies whether the PDF file is
password-protected. To change the
encryption algorithm, or add a
password, use the protect action.

FilePath

C:\ColdFusion\wwwroot\lion\myDoc
.pdf

Absolute pathname for the PDF file.
This value is read-only.

FillingForm

Allowed

Permissions assigned for entering
data in form fields. To change this
setting, use the permissions attri
bute with the protect action.

FitToWindow

empty string

Display setting for initial view of the
PDF document. To change this
setting use the processddx action
with the InitialViewProfile D
DX element.

HideMenubar

empty string

Display setting for initial view of the
PDF document. To change this
setting, use the processddx action
with the InitialViewProfile D
DX element.

HideToolbar

empty string

Display setting for initial view of the
PDF document. To change this
setting, use the processddx action
with the InitialViewProfile D
DX element.

© 2014 Adobe Systems Incorporated. All rights reserved.

938

Adobe ColdFusion Documentation

HideWindowUI

empty string

Display setting for initial view of the
PDF document. To change this
setting, use the processddx action
with the InitialViewProfile D
DX element.

Keywords

marketing, sales, production

Keywords specified for searches in
the PDF document. You can specify
a comma-separated list of keywords
with the setInfo action.

Language

EN-US

Language version used to create
the source file for the PDF
document. This value is read-only.

Modified

D:20061121155226-06'00'

System-generated timestamp for
when the PDF file was last
modified. You can specify a text
string with the setInfo action

PageLayout

OneColumn

Display setting for the initial view of
the PDF document. To change this
setting, use the processddx action
with the InitialViewProfile D
DX element.

Printing

Allowed

Permissions assigned for printing
the document. To change this
setting, use the permissions attri
bute with the protect action.

Producer

Acrobat Distiller 7.0.5 (Windows)

Version of Acrobat Distiller used to
generate the PDF document. This
value is read-only.

Properties

empty string

This value is read-only.

Secure

Not Allowed

Display setting that shows whether
the PDF document is password
protected.

ShowDocumentsOption

empty string

Display setting for initial view of the
PDF document. To change this
setting, use the processddx action
with the InitialViewProfile D
DX element.

© 2014 Adobe Systems Incorporated. All rights reserved.

939

Adobe ColdFusion Documentation

ShowWindowsOption

empty string

Display setting for initial view of the
PDF document. To change this
setting, use the processddx action
with the InitialViewProfile D
DX element.

Signing

Allowed

Permissions for allowing electronic
signatures to the PDF document.
To change this setting, use the per
missions attribute with the prote
ct action.

Subject

Product Marketing

The subject assigned to the PDF
document. You can specify a text
string with the setInfo action.

Title

Chapter 1: Getting Started

The title assigned to the PDF
document. You can specify a text
string with the setInfo action.

TotalPages

25

Total pages in the PDF document.
This value is read-only.

Trapped

empty string

Indicates whether trapping is
applied to the PDF document.
Trapping is used in printing to
eliminate gaps between two
adjoining ink colors. You can
specify a text string with the setIn
fo action.

Version

1.6

Version of the Adobe PDF
generator used to create the PDF
document. To change this setting
use the version attribute with the
write action. For more
information, see the section PDF
versions.

merge action Use the mergeaction to assemble PDF documents or pages from PDF source files into one
output file. The following code shows how to merge all the PDF files in a directory:



By default, ColdFusion adds the files in descending order by timestamp. The following code merges the
source files in ascending order by filename:

© 2014 Adobe Systems Incorporated. All rights reserved.

940

Adobe ColdFusion Documentation



This is useful if the source files have logical names, such as Chap0.pdf, Chap1.pdf, Chap2.pdf, and so on.By
default, ColdFusion continues the merge process even if it encounters a file in the specified directory that is
not a valid PDF document. To stop the merge process if the directory contains files other than valid PDF
documents, set the stopOnError attribute to yes:



To create a PDF file from specific pages in a document, use the source attribute with the pagesattribute.
The following code creates a file from pages 1-5 of the source document:



To merge several files into one document, specify the absolute pathnames of the files in a comma-separated
list, as the following code shows:



You can now create PDF packages using the package = "true" attribute with the merge action. For more
control over the order of files, to assemble files in different locations, and to extract pages from multiple PDF
files, use the cfpdfparam tag with the merge action. For more information on merging PDF files, see Assem
bling PDF Documents in the Developing ColdFusion Applications.
If cfpdf action="merge" and package="yes", all file formats can be used as source. The following
sample code has ZIP and JPEG file formats as source:






processddx action Use the proccessddx action to assemble PDF files by processing Document
Description XML (DDX) instructions. DDX is a declarative markup language used by Adobe LiveCycle

© 2014 Adobe Systems Incorporated. All rights reserved.

941

Adobe ColdFusion Documentation

Assembler. You can use DDX instructions to perform advanced tasks, such as adding table of contents
pages, headers and footers, automatic page numbers, and text-string watermarks to PDF
documents.ColdFusion provides a subset of LiveCycle Assembler functionality. To determine whether you
can perform your tasks in ColdFusion or whether you have to purchase LiveCycle Assembler, see the tables
in the following sections.
For complete DDX syntax, see the Adobe LiveCycle Assembler Document Description XML Reference.
Supported DDX elements

The following table lists the DDX elements that ColdFusion supports:
About

Author

Background

Center

DatePattern

DDX

DocumentInformation

DocumentText

Footer

Header

InitialViewProfile

Keyword

Keywords

Left

MasterPassword

Metadata

NoBookmarks

OpenPassword

PageLabel

Password

PasswordAccessProfile

PasswordEncryptionProfile

PDF (see Note)

PDFGroup

Permissions

Right

StyledText

StyleProfile

Subject

TableOfContents

TableOfContentsEntryPattern

TableOfContentsPagePattern

Title

Watermark

Note
ColdFusion does not support the certification and mergeLayers attributes of the PDF ele
ment.

Restricted DDX elements

New in ColdFusion 11 - The following restricted DDX elements are supported in ColdFusion 11
(Enterprise Edition).
If you are using ColdFusion 10 or earlier, the following DDX elements are excluded by ColdFusion:
ArtBox

AttachmentAppearance

© 2014 Adobe Systems Incorporated. All rights reserved.

Bookmarks

942

Adobe ColdFusion Documentation

BlankPage

BleedBox

Comments

Description

FileAttachments

FilenameEncoding

LinkAlias

Links

NoBackgrounds

NoComments

NoFileAttchments

NoFooters

NoForms

NoHeaders

NoLinks

NoPageLabels

NoThumbnails

NoWatermarks

NoXFA

PageMargins

PageSize

PageRotation

PageOverlay

PageUnderlay

PDFsFromBookmarks

Transform

TrimBox

Simple DDX instructions

You can create DDX instructions in any text editor and save the file with a DDX extension. The following example
shows the DDX instructions for merging several documents and generating a table of contents with bookmarks from
the source PDF documents:












Processing DDX instructions in ColdFusion

The following code processes the DDX instructions in ColdFusion:

© 2014 Adobe Systems Incorporated. All rights reserved.

943

Adobe ColdFusion Documentation















The DDX instructions are not valid.


#ddxVar.Out1#

The name attribute defines a variable that you use to determine the success or failure of the process. Use the cfou
tput tag to display the success or failure message, as the previous example shows, or use the cfdump tag to
display a structure:



This code returns the following information for each output file in the structure:
"Successful", if the file is assembled successfully.
"Reason for failure", if the file is not assembled successfully and the reason for failure is known.
"Failure", if the file is not assembled successfully and the reason for failure is not known.
Use the IsDDX function to determine whether a DDX file or set of instructions is valid.
For detailed examples, see Assembling PDF Documents in the Developing ColdFusion Applications.
protect action Use the protect action to password-protect PDF output files, set permissions, and encrypt
PDF output files. When you use the protect action, set a newUserPassword or a newOwnerPassword.
(You can set both, as long as the passwords differ.) When you assign a user password to a document, all
users must use this password to open the PDF document. The following code adds a user password to a
PDF document:

© 2014 Adobe Systems Incorporated. All rights reserved.

944

Adobe ColdFusion Documentation



To set the permissions on the output file, set the newOwnerPassword. A user who enters the owner
password when accessing the PDF file is considered the owner of file. The following example shows how to
set a new owner password:



Because the permissions are set to AllowDegradedPrinting in this example, ColdFusion lets users print
the document at 150 DPI, but prohibits all other actions. If a user tries to delete the file, for example,
ColdFusion generates an error message indicates that the password was entered incorrectly or the
permissions do not allow the action to be performed.ColdFusion does not retain permissions: if you add a ne
wUserPassword attribute, you also must set the permission explicitly.
To work with myVar, you specify newownerpw as the password.
PDF document passwords

A PDF document can have two kinds of passwords: a user password and an owner password. The following table
describes the two types of ColdFusion passwords and their equivalents in Acrobat:
ColdFusion password

Acrobat equivalent

Description

User password

Document Open password, user
password

Anyone who tries to open the PDF
document must enter the password
that you specify. A user password
does not allow a user to change
restricted features in the PDF
document.

Owner password

Permissions password, master
password

Lets the person who enters the
password restrict access to features
in a PDF document.

When you protect a PDF, your password changes to the one you provide. ColdFusion updates the variable's saved
password to the one you provide. However, if you provide both passwords, ColdFusion uses the owner password.
The following protects a PDF:



To get all the properties of the PDF, you do the following:

© 2014 Adobe Systems Incorporated. All rights reserved.

945

Adobe ColdFusion Documentation



To get only the properties allowed for the user, you do the following:



Permissions for PDF documents

The following table lists the permissions an owner can set for PDF documents:
Permissions

Description

All

There are no restrictions on the PDF document.

AllowAssembly

Users can add the PDF document to a merged
document.

AllowCopy

Users can copy text, images, and other file content.
This setting is required to generate thumbnail images
with the thumbnail action.

AllowDegradedPrinting

Users can print the document at low-resolution (150
DPI).

AllowFillIn

Users can enter data into PDF form fields. Users can
sign PDF forms electronically.

AllowModifyAnnotations

Users can add or change comments in the PDF
document.

AllowModifyContents

Users can change the file content. Users can add the
PDF document to a merged document.

AllowPrinting

Users can print the document at high-resolution
(print-production quality). This setting is required for
use with the cfprint tag.

AllowScreenReaders

Users can extract content from the PDF document.

AllowSecure

Users can sign the PDF document (with an electronic
signature).

None

Users can view the document only.

Encryption for PDF documents

© 2014 Adobe Systems Incorporated. All rights reserved.

946

Adobe ColdFusion Documentation

The encrypt attribute sets the type of encryption used for opening a password-protected document. By default,
ColdFusion uses the RC4 128-bit encryption algorithm to encrypt PDF files. To change the encryption algorithm, use
the encrypt attribute with the protect action. The following code encrypts the PDF output file with the AES
algorithm:



ColdFusion supports the following encryption algorithms:
Encryption algorithm

Compatibility

Description

AES_128

Adobe Acrobat 7.0 and later

Advanced Encryption Standard
(AES) specifies the Rijndael
algorithm, a symmetric block cipher
that can process data blocks of 128
bits. This is the highest encryption
level.
This encryption algorithm lets users
do the following:
Encrypt all document contents.
Encrypt all document contents
except for the metadata.
Encrypt only the file attachments.

RC4_128M

Adobe Acrobat 6.0 and later

RC4 specifies the RSA Security
software stream cipher for
algorithms such as Secure Sockets
Layer (SSL), to protect Internet
traffic, and WEP, to secure wireless
networks.
This encryption algorithm lets users
do the following:
Encrypt all document contents.
Encrypt all document contents
except for the metadata.

RC4_128

Adobe Acrobat 5.0 and later

RC4 128-bit encryption. This
encryption algorithm lets users
encrypt the document contents, but
not the document metadata.

RC4_40

Adobe Acrobat 3.0 and later

RC4 40-bit encryption. This is the
lowest encryption level.

None

-

The document is not encrypted.

© 2014 Adobe Systems Incorporated. All rights reserved.

947

Adobe ColdFusion Documentation

Note
Document metadata is used in Internet searches. If the metadata is encrypted, search engines
cannot search the PDF document. Users running an earlier version of Acrobat cannot open a
PDF document with a higher encryption setting. For example, if you specify AES 128 encryption,
a user cannot open the document in Acrobat 6.0 or earlier.
read action Use the read action to read the source PDF document into the namevariable, as the following
code shows:



...


removeWatermark action Use the removewatermarkaction to remove a watermark from a PDF document
or specified pages in a document. The following example removes a watermark from the first page of a PDF
document and writes the output to a new file:



removeheaderfooter actionUse this action to remove the header and footer from a PDF document or from
specified pages in a document. The following example removes the header and footer from the entire
document:



setInfo action Use the setinfo action to specify information associated with a PDF document to be saved
with it. Create a structure that contains the relevant information. Use the info attribute of the cfpdf tag to
refer to the structure. The following code shows the elements that you can modify by using the setInfoactio
n:








thumbnail action Use the thumbnail action to generate thumbnail images from the source PDF document.
If you do not specify a destination directory for the thumbnail files, ColdFusion creates a directory for the
thumbnails in the directory where the CFM page is located. If you specify a filename as the source, the

© 2014 Adobe Systems Incorporated. All rights reserved.

948

Adobe ColdFusion Documentation

thumbnail directory name is a concatenation of the name of the source file and _thumbnails. For example, the
following code generates a thumbnail image for each page in myBook.pdf and stores them in a directory
called myBook_thumbnails:



If the CFM page is located in the directory c:\myProject\genThumbnails.cfm, the pathname for the thumbnails
directory is c:\myProject\myBook_thumbnails.By default, ColdFusion generates thumbnail files in JPEG
format and the images are scaled to 25% of the original.
You can specify individual pages within the source document to generate thumbnails. Also, you can change
the size of the thumbnail; the resolution, the output format (JPEG, PNG, or TIFF); and the prefix used for the
thumbnail filenames. The following code generates a low-resolution thumbnail from the first page of the
source document that is scaled at 50% of the original size:



The full output file pathname is as follows:

c:\myBook\images\Cover_page_1.png

Note
To generate thumbnail images, the permissions of the source document must include All
owCopy. For more information, see Permissions for PDF documents in cfpdf.

With ColdFusion 9, the following new attributes were introduced for the thumbnail action:
hires: You can set this attribute to true to extract high-resolution images from the page. If a
document contains high-resolution images and you want to retain the resolution of the images, then
this attribute is useful.
For example:



overridepage: If you set this attribute to true, the thumbnail generated does not adhere to the PDF
page size, but to the image size that is present in that page. If the image is not present, the size is set
to the maximum size of the page.
compresstiffs: Use this attribute to compress the size of the thumbnail images. As the name of the
attribute suggests, it is only valid for the TIFF format. Following is an example:

© 2014 Adobe Systems Incorporated. All rights reserved.

949

Adobe ColdFusion Documentation



maxscale : Use this attribute to specify an integer value for the maximum scale of the thumbnail
images.
maxlength: Use this attribute to specify an integer value of the maximum length of the thumbnail
images.
maxbreadth: Use this attribute to specify an integer value of the maximum width of the thumbnail.
The following example illustrates the use of maxscale, maxlength, and maxbreadth:



Note
Typically, the value of the scale attribute is set to 100 when using the maxscale
attribute.
write action Use the writeaction to write the source PDF document, or the PDF document stored in
memory as a variable, to a file. The following code converts a PDF file stored in memory to a different PDF
version and writes the output to a new file:




You can now use either name or destination attributes with the write action. The name attribute takes the
value as the PDF document variable. For example, you can write the preceding code snippet as:




The new encodeall attribute encodes all the unencoded streams in the source. However, it does not
discriminate between dumb encodings like LZW and encodings like flate, so only unencoded streams get f
lateencoded.
Note
You can now register thumbnail fonts using the font management screen.

© 2014 Adobe Systems Incorporated. All rights reserved.

950

Adobe ColdFusion Documentation
PDF versions

Change the PDF version so that users running an older version of Acrobat or Adobe Reader can open the file. The
following table shows the compatibility between the PDF version and the corresponding Acrobat and Adobe Reader
versions:
PDF version

Compatibility

1.1

Acrobat and Adobe Reader 2

1.2

Acrobat and Adobe Reader 3

1.3

Acrobat and Adobe Reader 4

1.4

Acrobat and Adobe Reader 5

1.5

Acrobat and Adobe Reader 6

1.6

Acrobat and Adobe Reader 7

To linearize PDF documents for faster web display, set the saveOption attribute to linear, as the following code
shows:



Do not use the linear save option if you have to maintain interactivity in PDF forms or if the PDF document is
enabled for electronic signatures. To allow for electronic signatures, set the saveOption attribute to incremental
, as the following code shows:



Use the flatten attribute to flatten forms created in Acrobat:



Note
ColdFusion does not support flattening forms created in Adobe LiveCycle. For more information
about forms created in LiveCycle and Acrobat, see Manipulating PDF Forms in ColdFusion in the
Developing ColdFusion Applications.

Example

© 2014 Adobe Systems Incorporated. All rights reserved.

951

Adobe ColdFusion Documentation

The following example generates thumbnail images from pages in a PDF document and links the thumbnail images
to the pages in the PDF document:

PDF Thumbnail Demo

















Archiving PDF documents
Introduced in ColdFusion 11: Use the action type=”archive” to archive the PDF files based on
the ISO's PDF/A standards.PDF/A is one set of standards among a suite of PDF-based standards
managed by the International Organization for Standardization (ISO). It was developed to enable the long-term
preservation of electronic documents and provides specifications for the creation, viewing, and printing of PDF
documents, with the intent of preserving final documents of record as self-contained documents. The standard does
not define an archiving strategy or the goals of an archiving system. Rather, it identifies a "profile" for a PDF file that
makes it possible to reproduce the visual appearance of the document the exact same way in the future. This profile
specifies what must be included in the file, while prohibiting features that are not suitable for long-term archiving.

© 2014 Adobe Systems Incorporated. All rights reserved.

952

Adobe ColdFusion Documentation




For action =”sign” and "unsign", the following attribute is available:
signaturefieldname attribute(Optional):Fully qualified name of the existing field
on which the user wants to sign (or) the signature field which has to be
unsigned.

© 2014 Adobe Systems Incorporated. All rights reserved.

953

Adobe ColdFusion Documentation




For action =”unsign”, the following attribute is available:
Unsignall attribute (Optional): If true, then will unsign all signature fields in the source document.



For action =”validatesignature”, the following attribute is available:
Name attribute which will store the resultant structure of this operation. It consists of two elements. One is the
boolean field which indicates whether all signatures have been deemed valid or not. The second is an array
list consisting of the names of all the signatures which were invalid.


#pdfInfo.SUCCESS#

For action =”readsignaturefields”:
Reads all the signature fields and returns a query object in the variable
indicated by attribute name. This query object will have five columns. The five
columns are:
a) Signed - fully qualified name of the signature field.
b) Authored - indicates if this field can contain an author signature or not.
c) Can_Be_Signed - whether this field can be signed.
d) Can_Be_Authored - tells if this field is already signed or not
e) Visible - tells if the field is visible.

© 2014 Adobe Systems Incorporated. All rights reserved.

954

Adobe ColdFusion Documentation





© 2014 Adobe Systems Incorporated. All rights reserved.

955

Adobe ColdFusion Documentation

cfpdfform
Description

Manipulates existing forms created in Adobe Acrobat and Adobe LiveCycle Designer. The following list describes
some of the tasks you can perform with the cfpdfform tag:
Embed an interactive form created in Acrobat LiveCycle in a PDF document. You use the cfpdfform tag to
embed the PDF form in a cfdocument tag.
Render an existing form created in Acrobat or LiveCycle. This includes prefilling fields from a database or an
XML data file and processing form data from an HTTP post or PDF submission.
Extract or prefill values in stored PDF forms and save the output to a file or use it to update a data source.
History

ColdFusion 8: Added this tag.
Category

Forms tags
Syntax

populate

read

fdfdata = "filename to be exported to"

© 2014 Adobe Systems Incorporated. All rights reserved.

956

Adobe ColdFusion Documentation

Note
You can specify this tag's attributes in an attributeCollection attribute whose value is a
structure. Specify the structure name in the attributeCollection attribute and use the tag's
attribute names as structure keys.

See also

cfdocument, cfdocumentsection, cfform, cfinput, cfpdf, cfpdfformparam, cfpdfparam, cfpdfsubfo
rmcfprint, IsPDFFile, IsPDFObject, Manipulating PDF Forms in ColdFusion in the Developing ColdFusion
Applications
Attributes

Attribute

Action

Req/Opt

action

NA

Required

Default

Description
Action to perform on
the source:
populate
read

destination

populate

© 2014 Adobe Systems Incorporated. All rights reserved.

Optional

Write to browser

Pathname for the
output file. You can
specify an absolute
pathname or a
pathname relative to
the context root.
The file extension
must be PDF or
XDP. The file
extension
determines the
format of the file.
(The XDP format
applies only to
LiveCycle forms.)If
you do not specify
the destination,
ColdFusion displays
the form in the
browser.Do not
specify the
destination when
you embed a form in
a PDF document.

957

Adobe ColdFusion Documentation

overwrite

populate read

Optional

no

Specifies whether to
overwrite the
destination file (if ac
tion="populate"
) or the data file (if a
ction="read"):
yes
no

overwriteData

populate

Optional

no

Specifies whether to
overwrite existing
data in PDF form
fields with data from
the data source:
yes: Overwrite
existing data in
the form fields
with that from the
data source.
no: Retain
existing data in
form fields and
populate only
those fields
without data.
This attribute
applies to data
supplied from an
XML data source
and from the cfp
dfparam and cf
pdfsubform tags
.

result

read

© 2014 Adobe Systems Incorporated. All rights reserved.

Optional(see
Description)

ColdFusion
structure that
contains the form
field values.Specify
the XMLdata attribu
te or the result att
ribute; you can
specify both.

958

Adobe ColdFusion Documentation

source

populate read

Required

Pathname of the
source PDF
(absolute on-disk or
in-memory path, or
path relative to the
context root) or byte
array representing a
PDF.

XMLdata

populate read

Optional(see
Description)

Pathname for the
XML data file.
If action="popu
late", the data
from this file, XML
object, or XML
string populates
the form fields.
You can specify a
pathname relative
to the context root
or a relative
pathname.
If action="read
", ColdFusion
writes the data to
the variable.
Specify either the
XMLdata attribute
or the result attr
ibute for the read
action; you can
specify both.

fdf

populate

Optional

fdfdata

populateread

Optional

false

If set to true, the
system creates FDF
with subforms and
params instead of
an XML
For populate, you
specify the file name
from where the FDF
data is imported.
For read, you
specify the file name
where the FDF data
is exported.

Usage

ColdFusion supports two types of interactive forms: forms created in Adobe Acrobat 6.0 or earlier, and forms

© 2014 Adobe Systems Incorporated. All rights reserved.

959

Adobe ColdFusion Documentation

created in Adobe LiveCycle. In Adobe Acrobat Professional and Standard 7.0, Adobe introduced Adobe LiveCycle
Designer for creating PDF forms. ColdFusion supports forms created in LiveCycle Designer 7.0 and later.
Forms created in Acrobat have a flat structure: a list of fields at the same level. Forms created in LiveCycle Designer
are hierarchical, often composed of nested subforms. To map the data to the form field, you use cfpdfsubform ta
gs to recreate the structure of the form in ColdFusion. For examples, see the Usage section of the cfpdfsubform t
ag, and " Manipulating PDF Forms in ColdFusion in the Developing ColdFusion Applications.
populate action Use the populate action to populate PDF form fields from the specified data file. You can
specify a destination to write the output to a file or write the populated form directly to the browser. To display
the interactive PDF form in the browser, do not specify a destination.
The following example shows how to populate a PDF form with an XML data file and display the completed
form in a browser:



This example shows how to populate a PDF form with an XML data file and write the completed form to a
new PDF file:




Also, you can specify a URL that returns XML data. In the following example, "http://test1.com/xyz"re
turns XML content:



For forms created in Acrobat, you can write the output to a PDF file only. For forms created in LiveCycle, you
have the option to write the output to an XML Data Package (XDP) file. An XDP file is an XML representation
of a PDF file.
Note
Supplied values in form fields created in Acrobat or LiveCycle Designer are case
sensitive. For example, if a check box in a form requires a "Yes" value, the value "yes"
does not populate that field.

The file extension determines the file format: to save the output in XDP format, use an XDP extension in the
destination filename:

© 2014 Adobe Systems Incorporated. All rights reserved.

960

Adobe ColdFusion Documentation




You can use one or more cfpdfformparam tags within a cfpdfform tag to populate individual fields in a
PDF form.
The following example shows how to populate an existing form created in Acrobat (payslipTemplate.pdf) and
create a PDF form (employeeid123.pdf) with the employeeID and salary fields filled in:







ColdFusion requires that you reproduce the exact structure of the source PDF form to populate fields. To
verify the structure of a PDF form in ColdFusion, use the read action of cfpdfform tag, and then use the c
fdump tag to display the result structure. Use a cfpdfsubform tag for each level within the structure. For
more information, see Manipulating PDF Forms in ColdFusion in the Developing ColdFusion Applications.
The following example shows how to populate a form created in LiveCycle. Many forms created from
templates in LiveCycle contain a subform called form1. Use the cfpdfsubformtag to create a subform in
ColdFusion.









You can now import files in FDF format using the populateaction. The following example shows how:




If the fdf attribute for the populate action is set to true, it allows you to populate data in FDF format with
subforms and params instead of XML, as shown in the following example:

© 2014 Adobe Systems Incorporated. All rights reserved.

961

Adobe ColdFusion Documentation



























read action Use the read action to read the data from the source PDF form and generate a result structure
that contains the form fields and their values. Also, you can use the read action to generate an XML data file
from a PDF source file.
The following example shows how to read a PDF file and generate a result structure from the data:




You can use the cfdumptag to display the result structure:



You can use the result fields in ColdFusion, for example, #resultStruct.employeeId# and #resultSt
ruct.salary#.
The following example shows how to read a PDF file and write the data to an XML file:

© 2014 Adobe Systems Incorporated. All rights reserved.

962

Adobe ColdFusion Documentation



The following example shows how to read a PDF file into a variable that contains XML data:



The following example shows how to read a PDF file into an XML data variable and generate a result
structure. The cffiletag writes the data to an XML file:










Extracting data from a PDF submission

Use the following code to extract data from a PDF submission and write it to a structure called fields:




Use the cfdump tag to display the data structure, as follows:



Note
When you extract data from a PDF submission, always specify " #PDF.content#" as the
source.

You can set the form fields to a variable, as the following code shows:

© 2014 Adobe Systems Incorporated. All rights reserved.

963

Adobe ColdFusion Documentation



Use the populate action of the cfpdfform tag to write the output to a file. Specify "#PDF.content#" as the
source. In the following example, the unique filename is generated from a field on the PDF form:



Extracting data from an HTTP post submission

An HTTP post submission transmits the data from the PDF form, but not the form itself. You can extract data from
the PDF form fields, but you cannot write the output directly to a file. To extract the data and update a database, for
example, you must map the fields in the database to the structure and HTTP post data exactly.
Note
The structure of the HTTP post data (after submission) is not the same as the structure of the
PDF form (before data submission). For examples of both, see Manipulating PDF Forms in
ColdFusion in the Developing ColdFusion Applications.

To determine the structure of the HTTP post data, use the cfdump tag with the form name as the variable to display
the data structure, as follows:



Note
When you extract data from an HTTP post submission, always specify the form name as the
source. For example, specify "#FORM.form1#" for a form generated from a template in
LiveCycle Designer. When data extraction that uses the cfpdfform tag results in more than
one page, instead of returning one structure, ColdFusion returns one structure per page.

Embedding PDF forms within a PDF document

You can use the cfpdfform tag inside the cfdocument tag to embed an existing interactive PDF form within a
PDF document. Use at least one cfdocumentsection tag with the cfpdfform tag, but do not place the cfpdff
orm tag within the cfdocumentsection tag. For more information about embedding PDF forms, see Manipulating
PDF Forms in ColdFusion in the Developing ColdFusion Applications.
Flattening forms created in Acrobat

You use the cfpdf tag to flatten forms created in Acrobat. ColdFusion does not support flattening forms created in
LiveCycle. For more information, see Assembling PDF Documents in the Developing ColdFusion Applications.
Printing forms

© 2014 Adobe Systems Incorporated. All rights reserved.

964

Adobe ColdFusion Documentation

Use the cfprint tag to print forms created in Acrobat. Markups, such as sticky notes, comments, and editorial
revisions, are not printed with the form. You cannot use the cfprint tag to print forms created in LiveCycle
Designer.
Exporting PDF Forms in FDF

You can export PDF forms in FDF format using the read action. The following example shows how you can export
a PDF form in FDF format:




Example

The following example shows how to embed an interactive PDF form in a PDF document created with the cfdocum
ent tag:

© 2014 Adobe Systems Incorporated. All rights reserved.

965

Adobe ColdFusion Documentation



SELECT * FROM EMPLOYEES
WHERE EMAIL = 




Nondisclosure Agreement


Page #cfdocument.currentpagenumber# of
#cfdocument.totalpagecount#



Employee Nondisclosure Agreement
Please verify the information in the enclosed form. Make any of the
necessary changes in the online form and click the Print button.
Sign and date the last page. Staple the pages together and return the
completed form to your manager.













I, #getEmpInfo.FIRSTNAME# #getEmpInfo.LASTNAME#,
hereby attest that the information in this document is accurate and complete.





© 2014 Adobe Systems Incorporated. All rights reserved.

966

Adobe ColdFusion Documentation

© 2014 Adobe Systems Incorporated. All rights reserved.

967

Adobe ColdFusion Documentation

cfpdfformparam
Description

Provides additional information to the cfpdfform tag.
The cfpdfformparam tag is always a child tag of the cfpdfform or cfpdfsubform tag. Use the cfpdfformpa
ram tag to populate fields in a PDF form.
History

ColdFusion 8: Added this tag.
Category

Forms tags
Syntax





Note
You can specify this tag's attributes in an attributeCollection attribute whose value is a
structure. Specify the structure name in the attributeCollection attribute and use the tag's
attribute names as structure keys.

See also

cfdocument, cfdocumentsection, cfform, cfinput, cfpdf, cfpdfform, cfpdfparam, cfpdfsubformcfp
rint, IsPDFFile, IsPDFObject
Attributes

Attribute

Req/Opt

Default

Description

index

Optional

1

Index associated with the
field name. If multiple
fields have the same
name, use the index value
to locate one of them.
Applies to forms created
in LiveCycle only.

name

Required

© 2014 Adobe Systems Incorporated. All rights reserved.

Field name on the PDF
form.

968

Adobe ColdFusion Documentation

Required

value

Value associated with the
field name. For interactive
fields, specify a
ColdFusion variable.

Usage

Use the cfpdfformparam tag inside the cfpdfform tag or the cfpdfsubform tag to populate fields in a PDF
form.Use the index attribute of the cfpdfformparam tag to specify fields with the same name and different
values, as the following code shows:






Note
Use the index attribute with forms created in LiveCycle only. Forms created in Acrobat cannot
contain more than one field with the same name; therefore the index attribute is not valid.

Example

See the cfpdfform tag examples.

© 2014 Adobe Systems Incorporated. All rights reserved.

969

Adobe ColdFusion Documentation

cfpdfparam
Description

Provides additional information for the cfpdf tag. The cfpdfparam tag applies only to the merge action of the cfp
df tag and is always a child tag of the cfpdf tag.
History

ColdFusion 8: Added this tag.
Category

Forms tags
Syntax





Note
You can specify this tag's attributes in an attributeCollection attribute whose value is a
structure. Specify the structure name in the attributeCollection attribute and use the tag's
attribute names as structure keys.

See also

cfdocument, cfdocumentsection, cfpdf, cfpdfform, cfpdfformparam, cfpdfsubform, cfprint, IsPDF
File, IsPDFObject
Attributes

Attribute

Req/Opt

pages

Optional

Page or pages of the PDF
source file to merge. You
can specify a range of
pages, for example, "1-5
", or a comma-separated
list of pages, for example,
"1-5,9-10,18".

password

Optional

User or owner password,
if the source PDF file is
password-protected.

© 2014 Adobe Systems Incorporated. All rights reserved.

Default

Description

970

Adobe ColdFusion Documentation

Required

source

Source PDF file to merge.
You can specify a PDF
variable, a cfdocument v
ariable, or the pathname
to a file.

Usage

Use the cfpdfparam tag to merge several PDF documents into one file. The cfpdfparam tag lets you specify the
order of source files explicitly. You can use this tag to merge pages from multiple PDF document source files in
different locations.
The following code creates a single PDF document called combined.pdf that contains pages 1-3 and page 5 of the
file abc.pdf, followed by all of the pages in xyz.pdf, a file in memory with the variable name myPDFvariable, and
lastly pages 10-90 from the file abc.pdf. The password attribute applies only if the source file is
password-protected:



\\x




Note
When you use the cfpdfparam tag with the cfpdf merge action, you must specify either the d
estination attribute or the name attribute for the cfpdf tag.

Example

The following ColdFusion page creates a form for downloading tax forms and tax information booklets:

Downloading Federal Tax Documents
Please choose the your type of business.



Signature

Today's Date









Sole Proprieter
Partnership
S
Corporation





© 2014 Adobe Systems Incorporated. All rights reserved.

971

Adobe ColdFusion Documentation

The ColdFusion action page merges PDF files in different locations based on the selection in the form:



































Note
ColdFusion automatically flattens form fields when you use the merge action of the cfpdf tag.

© 2014 Adobe Systems Incorporated. All rights reserved.

972

Adobe ColdFusion Documentation

cfpdfsubform
Description

Populates a subform within the cfpdfform tag.
The cfpdfsubform tag can be a child tag of the cfpdfform tag or nested in another cfpdfsubform tag.
History

ColdFusion 8: Added this tag.
Category

Forms tags
Syntax






Note
You can specify this tag's attributes in an attributeCollection attribute whose value is a
structure. Specify the structure name in the attributeCollection attribute and use the tag's
attribute names as structure keys.

See also

cfdocument, cfdocumentsection, cfform, cfinput, cfpdf, cfpdfform, cfpdfformparam, cfpdfparam,
cfprint, IsPDFFile, IsPDFObject
Attributes

Attribute

Req/Opt

Default

Description

index

Optional

1

Index associated with the
field name. If multiple
fields have the same
name, ColdFusion uses
the index value to locate
one of them.

name

Required

Name of the subform
corresponding to subform
name in the PDF form.

Usage

© 2014 Adobe Systems Incorporated. All rights reserved.

973

Adobe ColdFusion Documentation

Use the cfpdfsubform tag with the cfpdfform tag to populate one or more subforms within a PDF form. The cf
pdfsubform tag can contain multiple cfpdfformparam tags. Also, you can nest subforms, as the following
example shows:
















Use subforms to match the exact structure of the source PDF form. If you do not, ColdFusion cannot prefill the form
with data and generates an error. Many of the forms generated from templates in LiveCycle contain a subform called
form1. You must specify this as a subform in your code, as the following example shows:








To verify the structure of a PDF form in ColdFusion, use the read action of the cfpdfform tag, as the following
example shows:



Then use the cfdump tag to display the structure:



Example

See the cfpdfform tag examples.

© 2014 Adobe Systems Incorporated. All rights reserved.

974

Adobe ColdFusion Documentation

cfpod
Description

Creates a pod, an area of the browser window or layout area with an optional title bar and a body that contains
display elements.
Category

Display management tags
Syntax


OR

pod contents


If the tag does not have a body and end tag, close it with /> character combination.
Note
You can specify this tag's attribute in an attributeCollection attribute whose value is a
structure. Specify the structure name in the attributeCollection attribute and use the tag's
attribute name as structure key.

See also

cfajaximport, cfdiv, cflayout, cfwindow
History

ColdFusion 8: Added this tag.
Attributes

© 2014 Adobe Systems Incorporated. All rights reserved.

975

Adobe ColdFusion Documentation

Attribute

Req/Opt

bodyStyle

Optional

A CSS style specification
for the pod body.As a
general rule, use this
attribute to set color and
font styles. Using this
attribute to set the height
and width, for example,
can result in distorted
output.

headerStyle

Optional

A CSS style specification
for the pod header.As a
general rule, use this
attribute to set color and
font styles. Using this
attribute to set the height
and width, for example,
can result in distorted
output.

height

Optional

name

Optional

onBindError

Optional

© 2014 Adobe Systems Incorporated. All rights reserved.

Default

100

Description

Height if the control,
including the title bar and
borders, in pixels
Name of the pod control.

See Description

The name of a JavaScript
function to execute if
evaluating a bind
expression results in an
error. The function must
take two attributes: an
HTTP status code and a
message.
If you omit this attribute,
and have specified a
global error handler (by
using the ColdFusion.s
etGlobalErrorHandle
r function), it displays the
error message; otherwise
a default error pop-up
displays.

976

Adobe ColdFusion Documentation

overflow

Optional

auto

Specifies how to display
child content whose size
would cause the control to
overflow the pod
boundaries. The following
values are valid:
auto: shows scrollbars
when necessary.
hidden: does not allow
access to overflowing
content.
scroll: always shows
horizontal and vertical
scroll bars, even if they
are not needed.
visible: content can
display outside the
bounds of the pod.
Note: In Internet
Explorer, pods with the
visible setting
expand to fit the size of
the contents, rather
than having the
contents extend beyond
the layout area.

source

Required if the tag does
not have a body

© 2014 Adobe Systems Incorporated. All rights reserved.

A URL that returns the
pod contents. ColdFusion
uses standard page path
resolution rules. If you
specify this attribute and
the cfpod tag has a
body, ColdFusion ignores
the body contents.
You can use a bind
expression with
dependencies in this
attribute; for more
information see Usage.
Note: If a CFML page
specified in this attribute
contains tags that use
AJAX features, such as c
fform, cfgrid, and cfw
indow, you must use a c
fajaximport tag on the
page with the cfpod tag.
For more information, see
cfajaximport.

977

Adobe ColdFusion Documentation

title

Optional

width

Optional

Text to display in the
pod's title bar. You can
use HTML mark-up to
control the title
appearance, of example
to show the text in red
italic font. If you omit this
attribute, the pod does not
have a title bar.
500

Width if the control,
including borders, in
pixels.

Usage

You use a source attribute or a tag body to specify the pod contents; if you specify both, ColdFusion uses the
contents specified by the source attribute and ignores the tag body. If you use a source attribute, an animated
icon and the text "Loading..." appears while the contents is being fetched.
If the source attribute specifies a page that defines JavaScript functions, the function definitions on that page must
have the following format:

functionName = function(arguments) {function body}

Function definitions that use the following format may not work:

function functionName (arguments) {function body}

However, Adobe recommends that you include all custom JavaScript in external JavaScript files and import them on
the application's main page, and not write them inline in code that you get using the source attribute. Imported
pages do not have this function definition format restriction.
If you use the source attribute, you can use a bind expression to include form field values or other form control
attributes as part of the source specification. You can bind to HTML format form controls only.
To use a bind expression, specify a URL and pass one or more URL parameters the page, including bind
parameters.
In its most basic form, a bind parameter consists of the name or id attribute
of the control to which you are binding in braces ({ }). To include
the value of the city control as a bind parameter,
for example, use the following format:

source="/myapplication/cityPod.cfm?cityname={city}"

For detailed information about using bind expressions, see Binding data to form fields in the Developing ColdFusion
Applications.

© 2014 Adobe Systems Incorporated. All rights reserved.

978

Adobe ColdFusion Documentation
Example

The following CFML page displays two pods in a vertical layout. Each pod gets its contents from a displayforpod.cfm
page that uses the cffeed tag to get an Atom feed.


















The following code shows the contents of the displayforpod.cfm page:



#feedQuery.content#

=========================================




© 2014 Adobe Systems Incorporated. All rights reserved.

979

Adobe ColdFusion Documentation

cfpop
Description

Retrieves or deletes e-mail messages from a POP mail server.
Category

Communications tags, Internet protocol tags
Syntax


generateUniqueFilenames = "yes|no"
maxRows = "number"
messageNumber = "number"
name = "query name"
password = "password"
port = "port number"
secure = "yes|no">
startRow = "number"
timeout = "seconds"
uid = "number"
delimeter = "delimeter char"
username = "user name">

Note
You can specify this tag's attributes in an attributeCollection attribute whose value is a
structure. Specify the structure name in the attributeCollection attribute and use the tag's
attribute names as structure keys.

See also

cfftp, cfhttp, cfldap, cfmail, cfmailparam, SetLocale; Sending and Receiving E-Mail in the Developing
ColdFusion Applications
History

ColdFusion 11: New action, markRead is supported. New attribute delimeter.
ColdFusion 10: Added attribute {{secure}}
ColdFusion MX 7.01: Added cids query variable.
ColdFusion MX 6.1:
Added support for multipart mail messages with Text and HTML parts.
Changed the attachment name separator: the TAB character is now the separator between attachment
names in the attachments and attachmentfiles query fields if a message has multiple attachments.

© 2014 Adobe Systems Incorporated. All rights reserved.

980

Adobe ColdFusion Documentation

This behavior is identical to ColdFusion 5 and earlier versions.
ColdFusion MX: Changed the attachment name separator: the comma separates names in the attachment
s and attachmentfiles query fields if a message has multiple attachments.
Attributes

Attribute

Req/Opt

server

Required

Default

Description
POP server identifier:
A host name, for
example, "biff.upper
lip.com".
An IP address, for
example, "192.1.2.22
5".

action

Optional

attachmentPath

Optional

© 2014 Adobe Systems Incorporated. All rights reserved.

getHeaderOnly

getHeaderOnly: returns
message header
information only
getAll: returns message
header information,
message text, and
attachments if attachm
entPath is specified
delete: deletes
messages on POP
server
markRead: marks the
message as read
If action="getAll",
specifies a directory in
which to save any
attachments. If the
directory does not exist,
ColdFusion creates it.
If you omit this attribute,
ColdFusion does not save
any attachments. If you
specify a relative path, the
path root is the
ColdFusion temporary
directory, which is
returned by the GetTemp
Directory function.

981

Adobe ColdFusion Documentation

debug

Optional

no

yes: sends debugging
output to standard
output. By default, if the
console window is
unavailable on server
configurations,
ColdFusion sends
output to
cf_root/runtime/logs/col
dfusion-out.log.
no: does not generate
debugging output.

generateUniqueFilen
ames

Optional

no

yes: generate unique
filenames for files
attached to an e-mail
message, to avoid
naming conflicts when
files are saved.
no

maxRows

Optional

Retrieves all available
rows

Number of messages to
return or delete, starting
with the number in start
Row. Ignored if messageN
umber or uid is specified.
Message number or
comma-separated list of
message numbers to get
or delete. Invalid message
numbers are
ignored.Ignored if uid is
specified.

messageNumber

name

Required if action = "ge
tAll" or "getHeaderOn
ly"

Name for query object
that contains the retrieved
message information.

password

Optional

Password that
corresponds to username
.

port

Optional

110

POP port.

secure

Optional

no

if set to yes, enables SSL
for pop requests.

© 2014 Adobe Systems Incorporated. All rights reserved.

982

Adobe ColdFusion Documentation

startRow

Optional

1

First row number to get or
delete. Ignored if messag
eNumber or uid is
specified.

timeout

Optional

60

Maximum time, in
seconds, to wait for mail
processing.
UID or a
comma-separated list of
UIDs to get or delete.
Invalid UIDs are ignored.

uid

username

Optional

A user name.

delimiter

Optional

The value of the uid
attribute can be a
comma-separated list of
UIDs. If the delimiter
attribute is specified, the
value of delimiter will be
used as a delimiter
instead of comma.

Usage

The cfpop tag retrieves one or more mail messages from a POP server and populates a ColdFusion query object
with the resulting messages, one message per row. Alternatively, it deletes one or more messages from the POP
server.
Note
When the cfpop tag encounters malformed mail messages, it does not generate errors; instead,
it returns empty fields.

To optimize performance, two retrieve options are available. Message header information is typically short, and
therefore quick to transfer. Message text and attachments can be long, and therefore take longer to process.
The attachmentpath attribute

Use the following syntax to specify an in-memory directory in the attachmentpath attribute. In-memory files speed
processing of transient data.

ram:///path

The path can include multiple directories, for example ram:///petStore/mail/attachments You must create
the directories in the path before you specify the file. For more information on using in-memory files, see Working
with in-memory files in Optimizing ColdFusion applications in the Developing ColdFusion Applications.

© 2014 Adobe Systems Incorporated. All rights reserved.

983

Adobe ColdFusion Documentation
The cfpop query variables

The following table describes the variables that provide information about the query that is returned by cfpop:
Variable names

Description

queryname.recordCount

Number of records returned by query.

queryname.currentRow

Current row that cfoutput is processing.

queryname.columnList

List of column names in query.

Query message header and body columns

The following table lists the message header and body columns that are returned if action = "getHeaderOnly" o
r "getAll":
Column name

getHeaderOnly returns

getAll returns

queryname.date

yes

yes

queryname.from

yes

yes

queryname.messagenumber

yes

yes

queryname.messageid

yes

yes

queryname.replyto

yes

yes

queryname.subject

yes

yes

queryname.cc

yes

yes

queryname.to

yes

yes

queryname.body

no

yes

queryname.textBody

no

yes

queryname.HTMLBody

no

yes

queryname.header

yes

yes

queryname.attachments

no

yes

queryname.attachmentfiles

no

yes

queryname.UID

yes

yes

© 2014 Adobe Systems Incorporated. All rights reserved.

984

Adobe ColdFusion Documentation

queryname.cids

no

yes

If the mail message includes a part with a Content-Type of text/plain, the queryname.textBody column contains the
part's message content. If the mail message includes a part with a Content-Type of text/HTML, the
queryname.HTMLBody column contains the part's message content. If no Content-Type matches these types, the
columns are empty. The queryname.Body column always contains the first message body found.
The queryname.attachments column contains a tab-separated list of all the attachment names. The
queryname.attachmentfiles column contains a tab-separated list of the locations of the attachment files. Use the cff
ile tag to delete these temporary files when you have processed them.
To create a ColdFusion date/time object from the date-time string that is extracted from a mail message in the
queryname.date column, use the following table:
Locale

How to create a ColdFusion date/time object from
queryname.date

English (US)

Use the ParseDateTime function. If you specify the p
op-conversion attribute, the function adjusts the
date/time object to UTC.

Other

Extract the date part of string; pass it to the LSParseD
ateTime function.

Note
To set the default display format of date, time, number, and currency values, use the SetLocal
e function.

For more information on cfpop, see Sending and Receiving E-Mail in the Developing ColdFusion Applications.
Example

© 2014 Adobe Systems Incorporated. All rights reserved.

985

Adobe ColdFusion Documentation


cfpop Example
cfpop lets you retrieve and manipulate mail in a POP3 mailbox.
This view-only example shows how to create one feature of
a mail client, to display the mail headers in a POP3 mailbox.
To execute this, un-comment this code and run with a mail-enabled CF Server.



Message Headers in Your Inbox
Number of Records:
#GetHeaders.recordCount#


Row: #currentRow#: From: #From# -- Subject: #Subject#





Enter your mail server:

Enter your username:

Enter your password:



--->

© 2014 Adobe Systems Incorporated. All rights reserved.

986

Adobe ColdFusion Documentation

cfpresentation
Description

Defines the look of a dynamic slide presentation and determines whether to write the presentation files to disk. The
cfpresentation tag is the parent tag for one or more cfpresentationslide tags, where you define the
content for the presentation, and the cfpresenter tags, which provide information about the people presenting the
slides.
History

ColdFusion 9: Added format and destination attributes.
ColdFusion 8: Added this tag.
Category

Data output tags
Syntax


presentation content...


© 2014 Adobe Systems Incorporated. All rights reserved.

987

Adobe ColdFusion Documentation

Note
You can specify this tag's attributes in an attributeCollection attribute whose value is a
structure. Specify the structure name in the attributeCollection attribute and use the tag's
attribute names as structure keys.

See also

cfchart, cfpresentationslide, cfpresenter, cfreport, Creating Slide Presentations in the Developing
ColdFusion Applications
Attributes

Attribute

Req/Opt

authPassword

Optional

Sends a password to the
target URL for Basic
Authentication. Combined
with username to form a
base64 encoded string
that is passed in the
Authenticate header.
Does not provide support
for Integrated Windows,
NTLM, or Kerberos
authentication.

authUser

Optional

Sends a user name to the
target URL for Basic
Authentication. Combined
with password to form a
base64 encoded string
that is passed in the
Authenticate header.
Does not provide support
for Integrated Windows,
NTLM, or Kerebos
authentication.

© 2014 Adobe Systems Incorporated. All rights reserved.

Default

Description

988

Adobe ColdFusion Documentation

autoPlay

Optional

yes

Specifies whether to play
the presentation
automatically:
yes: the presentation
automatically runs
through the entire
presentation at startup.
no: the user must click
the Play button to start
the presentation and
click the Next button to
advance to the next
slide in the
presentation.

backgroundColor

Optional

727971

Background color of the
presentation. The value is
hexadecimal: use the form
"##xxxxxx" or "##xxxx
xxxx", where x = 0-9 or
A-F; use two number
signs or none. Also, you
can use a subset of HTML
named colors listed in the
section Named colors.

control

Optional

normal

Presentation control:
normal
brief

controlLocation

Optional

right

Specifies the location of
the presentation control:
right
left

destination

Optional

© 2014 Adobe Systems Incorporated. All rights reserved.

Absolute file name or a
file path relative to the
CFM page. You can use
this for both connect
presentation and ppt
presentations. Required if
format="html".

989

Adobe ColdFusion Documentation

directory

Optional

Directory where the
presentation is saved.
This can be an absolute
path or a path relative to
the CFM page. Also,
ColdFusion creates a
subdirectory called data
that contains:
A SWF file for each
slide
srchdata.xml (which
creates the search
interface)
vconfig.xml
viewer.xml
images, video clips, and
SWF files referenced by
the cfpresentations
lide tags
If you do not specify a
directory, ColdFusion
writes the files to a
temp directory and runs
the presentation in the
client browser.

format

Optional

Specifies the file format
for conversion:
ppt converts html input
provided in
cfpresentationslide to a
PowerPoint file.
html converts ppt to an
HTML presentation.

glowColor

Optional

© 2014 Adobe Systems Incorporated. All rights reserved.

35D334

Color used for glow
effects on the buttons.
The value is hexadecimal:
use the form "##xxxxxx
" or "##xxxxxxxx",
where x = 0-9 or A-F; use
two number signs or
none. Also, you can use a
subset of HTML named
colors listed in the section
Named colors.

990

Adobe ColdFusion Documentation

initialTab

Optional

outline

Specifies which tab
displays on top when the
presentation is run. This
applies only when the con
trol value is normal:
outline
search
notes

lightColor

Optional

4E5D60

Light color used for
light-and-shadow effects.
The value is hexadecimal:
use the form "##xxxxxx
" or "##xxxxxxxx",
where x = 0-9 or A-F; use
two number signs or
none. Also, you can use a
subset of HTML named
colors listed in the section
Named colors.

loop

Optional

no

Specifies whether the
presentation runs in a
loop:
yes: the presentation
restarts automatically
after it ends.
no: the user must click
the Play button to
restart the presentation.

overwrite

Optional

yes

Specifies whether files in
the directory are
overwritten. Valid only
when the directory
attribute is specified.
yes: overwrites files if
they are already
present
no: creates new files

© 2014 Adobe Systems Incorporated. All rights reserved.

991

Adobe ColdFusion Documentation

primaryColor

Optional

6F8488

proxyHost

Optional

Host name or IP address
of a proxy server to which
to send the request.

proxyPassword

Optional

Password required by the
proxy server.

proxyPort

Optional

proxyUser

Optional

shadowColor

Optional

000000

Shadow color used for
light-and-shadow effects.
The value is hexadecimal:
use the form "##xxxxxx
" or "##xxxxxxxx",
where x = 0-9 or A-F; use
two number signs or
none. Also, you can use a
subset of HTML named
colors listed in the section
Named colors.

showNotes

Optional

no

Specifies whether the
Notes tab is present in the
presentation control
panel:

80

Primary color of the
presentation. The value is
hexadecimal: use the form
"##xxxxxx" or "##xxxx
xxxx", where x = 0-9 or
A-F; use two number
signs or none. Also, you
can use a subset of HTML
named colors listed in the
section Named colors.

The port to connect to on
the proxy server.
User name to provide to
the proxy server.

yes
no
showOutline

Optional

yes

Specifies whether the
Outline is present in the
presentation control
panel:
yes
no

© 2014 Adobe Systems Incorporated. All rights reserved.

992

Adobe ColdFusion Documentation

showSearch

Optional

yes

Specifies whether the
Search tab is present in
the presentation control
panel:
yes
no

textColor

Optional

title

Required

userAgent

Optional

FFFFFF

Color for all the text in the
presentation user
interface. The value is
hexadecimal: use the form
"##xxxxxx" or "##xxxx
xxxx", where x = 0-9 or
A-F; use two number
signs or none. Also, you
can use a subset of HTML
named colors listed in the
section Named colors.
Title of the presentation

ColdFusion

Text to put in the HTTP
User-Agent request
header field. Used to
identify the request client
software.

Usage

Use the cfpresentation tag to create the container for a slide presentation. You can define the position and
appearance of the presentation controls, the background color, and the text for the presentation. Also, use this tag to
determine whether to write the presentation to files or to run it directly in the client browser.
The settings in the cfpresentation tag do not affect the appearance of the content defined in the cfpresentat
ionslide tags.
destination attribute

Use the following syntax to specify an in-memory file, which is not written to disk in the destination attribute.
In-memory files speed processing of transient data.

ram:///filepath

The filepath can include directories, for example ram:///petStore/presentations/quarterlyresults.ht
ml. Create the directories in the path before you specify the file. For more information on using in-memory files, see
Working with in-memory files in Optimizing ColdFusion applications in the Developing ColdFusion Applications.
Named colors

The cfpresentation tag supports the following named colors for use with the backgroundColor, glowColor,

© 2014 Adobe Systems Incorporated. All rights reserved.

993

Adobe ColdFusion Documentation

lightColor, primaryColor, shadowColor, and textColor attributes:
Named color

Hexadecimal value

red

FF0000

green

008000

blue

0000FF

black

000000

white

FFFFFF

yellow

FFFF00

gray

808080

darkgray

A9A9A9

lightgray

D3D3D3

cyan

00FFFF

magenta

FF00FF

orange

FFA500

pink

FFC0CB

Example

© 2014 Adobe Systems Incorporated. All rights reserved.

994

Adobe ColdFusion Documentation













Sales

Overview
Q1 Sales Figures
Projected Sales
Competition
Advantages
Long Term Growth




Q1 Sales Figures











© 2014 Adobe Systems Incorporated. All rights reserved.

995

Adobe ColdFusion Documentation

cfpresentationslide
Description

Creates a slide dynamically from a source file or HTML and CFML code on the ColdFusion page. The cfpresenta
tionslide is a child tag of the cfpresentation tag.
History

ColdFusion 9: Added the slides attribute. Added PowerPoint file support to the src attribute.
ColdFusion 8: Added this tag.
Category

Data output tags
Syntax





Note
You can specify this tag's attributes in an attributeCollection attribute whose value is a
structure. Specify the structure name in the attributeCollection attribute and use the tag's
attribute names as structure keys.

See also

cfchart, cfpresentation, cfpresenter, cfreport, Creating Slide Presentations in the Developing
ColdFusion Applications
Attributes

© 2014 Adobe Systems Incorporated. All rights reserved.

996

Adobe ColdFusion Documentation

Attribute

Req/Opt

Default

Description

advance

Optional

See Description

Overrides the cfpresent
ation tag autoPlay attri
bute for the slide:
auto: after the slide
plays, the presentation
advances to the next
slide automatically. This
is the default value if cf
presentation
autoPlay="yes".
never: after the slide
plays, the presentation
does not advance to the
next slide until the user
clicks the Next button.
This is the default value
if cfpresentation
autoPlay="no".
click: after the slide
plays, the presentation
advances to the next
slide if the user clicks
anywhere in the main
presentation area.

audio

Optional

Pathname of the audio file
relative to the CFM page
or the web root. The audio
file must be an MP3 file.
You cannot specify both
audio and video for a
slide.

authPassword

Optional

Use to pass a password
to the target URL for
Basic Authentication.
Combined with username
to form a base64 encoded
string that is passed in the
Authenticate header.
Does not provide support
for Integrated Windows,
NTLM, or Kerberos
authentication.

© 2014 Adobe Systems Incorporated. All rights reserved.

997

Adobe ColdFusion Documentation

authUser

Optional

Use to pass a user name
to the target URL for
Basic Authentication.
Combined with password
to form a base64 encoded
string that is passed in the
Authenticate header.
Does not provide support
for Integrated Windows,
NTLM, or Kerberos
authentication.

duration

Optional

Duration in seconds that
the slide is played. If you
do not specify a duration,
the slide plays for the
duration of the audio clip
associated with the slide.

marginBottom

Optional

0

Bottom margin of the
slide.

marginLeft

Optional

0

Left margin of the slide.

marginRight

Optional

0

Right margin of the slide

marginTop

Optional

0

Top margin of the slide

notes

Optional

Notes used for the slide.
Notes are displayed only if
the showNotes attribute of
the cfpresentationsl
ide tag is set to yes.

presenter

Optional

Presenter of the slide. A
slide can have only one
presenter. This name
must match one of the
presenter names in the cf
presenter tag.

scale

Optional

© 2014 Adobe Systems Incorporated. All rights reserved.

1.0

Scale used for the HTML
content in the slide
presentation. If you do not
specify the scale,
ColdFusion automatically
scales the content to fit in
the slide.

998

Adobe ColdFusion Documentation

slides

Optional

src

Optional

All slides

Specifies the slide
numbers required to
export when the src attrib
ute points to a PowerPoint
file. Use a hyphen to
specify a range; use a
comma to specify
non-contiguous slides. For
example:slides="1-10
" or slides="1,10"
HTML, SWF, or PPT
source files used as a
slide. You can specify the
following as the slide
source:
An absolute path
A path relative to the
CFM page
A URL: Specify if the
source returns HTML
content
SWF files must be
present on the system
running ColdFusion and
the path must be either
an absolute path or a
path relative to the CFM
page.
If you do not specify a
source file, include
HTML/CFML code as
the body. If you specify
a source file and HTML
/CFML, ColdFusion
ignores the source file
and displays the
HTML/CFML content in
the slide.

title

Optional

userAgent

Optional

© 2014 Adobe Systems Incorporated. All rights reserved.

Title of the slide
ColdFusion

Text to put in the HTTP
User-Agent request
header field. Identifies the
request client software.

999

Adobe ColdFusion Documentation

useExternalProgram

Optional

true

Boolean value to switch
between OpenOffice and
POI libraries:
true: OpenOffice
libraries.
false: POI libraries

Optional

video

Video file used for the
presenter of the slide. If
you specify video for the
slide and an image for the
presenter, the video is
used instead of the image
for the slide. You cannot
specify both audio and
video for a slide. The
video must be an FLV or
SWF file.
The video file pathname
must be relative to the
CFM page or the web
root.

Usage

Use the cfpresentationslide tag within the cfpresentation tag to create a slide presentation from individual
SWF or HTML source files. If you do not specify a source file, include the HMTL or CFML code for the body of the
slide within the cfpresentationslide tag. You can assign one presenter to each slide. Use the cfpresenter t
ag to define presenters referenced by the cfpresentationslide tags.
The following code shows how to create a slide presentation from existing SWF files:











Note
The cfpresentationslide tag requires an end tag. If you specify a source file as the content
for the slide instead of CFML and HTML code within start and end tags, use the end slash as a
shortcut for the end tag.

© 2014 Adobe Systems Incorporated. All rights reserved.

1000

Adobe ColdFusion Documentation

You can reference source files from a URL as long as they return HTML content. The following code shows how to
create a slide presentation from HTML files located on an external website:












Note
The links within slides created from HTML files are not active.

Also, you can enter HTML and CFML code as the body for a slide. Within the code, you can include charts, graphs,
and images, as the following code shows:

© 2014 Adobe Systems Incorporated. All rights reserved.

1001

Adobe ColdFusion Documentation








Introduction




Overview
Q1 Sales Figures
Projected Sales
Competition
Advantages
Long Term Growth







Q1 Sales Figures











Example

© 2014 Adobe Systems Incorporated. All rights reserved.

1002

Adobe ColdFusion Documentation









USGS Naming Conventions

Overview
General Naming Conventions
Domestic Naming Conventions
Foreign Naming Conventions



duration="10" presenter="Robert L. Payne"/>




© 2014 Adobe Systems Incorporated. All rights reserved.

1003

Adobe ColdFusion Documentation

cfpresenter
Description

Describes a presenter in a slide presentation. A slide presentation can have multiple presenters. The presenters
must be referenced from the slides defined by the cfpresentationslide tag.
History

ColdFusion 8: Added this tag.
Category

Data output tags
Syntax



Note
You can specify this tag's attributes in an attributeCollection attribute whose value is a
structure. Specify the structure name in the attributeCollection attribute and use the tag's
attribute names as structure keys.

See also

cfchart, cfpresentation, cfpresentationslide
Attributes

Attribute

Req/Opt

biography

Optional

© 2014 Adobe Systems Incorporated. All rights reserved.

Default

Description
A text string that provides
information about the
presenter; for example,
"Sally Maverick has been
a top seller of Adobe
products for the last five
years."

1004

Adobe ColdFusion Documentation

email

Optional

E-mail address of the
presenter. This attribute
activates the Contact link
in the presentation control
panel, which opens an
e-mail message when you
click it.

image

Optional

Pathname for the
presenter's image in
JPEG format. The JPEG
file must be relative to the
CFM page. If you specify
a video for the cfpresen
tationslide tag, the
video clip overrides this
value for that slide.

name

Required

Name of the presenter.
Use this value in the pres
enter attribute of the cf
presentationslide ta
g to associate the
presenter with the slide.

logo

Optional

Pathname of the image
file that represents the
presenter's logo or the
logo of the presenter's
organization. The logo
must be in JPEG format.
The file must be relative to
the CFM file website.

title

Optional

Title of the presenter, for
example, "VP of Sales".

Usage

Use the cfpresenter tag to define the presenters that you specify for each slide. The presenter information
appears in the control panel for the slide to which it is assigned. To specify a presenter for a slide, use the present
er attribute of the cfpresentationslide tag.
You can specify an image of the presenter and the presenter's company logo by using the image and logo attribut
es of the presenter tag, respectively. To display a video clip in place of the presenter's image, you can specify an
FLV or SWF file for video attribute of the cfpresentationslide tag.
Example

© 2014 Adobe Systems Incorporated. All rights reserved.

1005

Adobe ColdFusion Documentation

















© 2014 Adobe Systems Incorporated. All rights reserved.

1006

Adobe ColdFusion Documentation

cfprint
Description

Prints specified pages from a PDF file. Use this tag to perform automated batch print jobs. Use the cfprint tag to
print any PDF document, including the ones generated by the cfdocument, cfpdf, and cfpdfform tag. Also, you
use this tag to print Report Builder reports exported in PDF format.
History

ColdFusion 8: Added this tag.
Category

Data output tags
Syntax



Note
You can specify this tag's attributes in an attributeCollection attribute whose value is a
structure. Specify the structure name in the attributeCollection attribute and use the tag's
attribute names as structure keys.

See also

cfdocument, cfpdf, cfpdfform, cfpdfformparam, cfpdfparam, cfpdfsubform, GetPrinterInfo, IsPD
FFile, IsPDFObject
Attributes

Attribute

Req/Opt

© 2014 Adobe Systems Incorporated. All rights reserved.

Default

Description

1007

Adobe ColdFusion Documentation

attributeStruct

Optional

ColdFusion structure used
to specify additional print
instructions. Individually
named attributes take
precedence over the
key-value pairs in the
attribute structure. For
information about
key-value pairs, see the
table in the section
attributeStruct.

color

Optional

Color or monochrome
printing:
yes: print in color
no: print in black and
white, with colors in
shades of gray

copies

Optional

fidelity

Optional

Number of copies to print.
The value must be greater
than or equal to 1.
no

Whether to print a job
based on the print
requirements specified.
Valid values are:
yes: if the job cannot
be printed exactly as
specified in the print
requirements, the job is
rejected.
no: a reasonable
attempt to print the job
is acceptable

© 2014 Adobe Systems Incorporated. All rights reserved.

1008

Adobe ColdFusion Documentation

pages

Optional

paper

Optional

all

Pages in the source file to
print. Duplicate pages and
pages beyond the total
count of pages in the
document are ignored as
long as there is at least
one page between 1 and
the total number of pages
in the document. You can
combine individual page
numbers and page
ranges, for example,
1-3,6,10-20. If you do not
specify a value for the pa
ges attribute, ColdFusion
prints the entire
document.
Paper used for the print
job. The value can be any
returned by the GetPrin
terInfo function. The
following values are valid:
na-letter
na-legal
iso-a4
iso-a5
iso-b4
iso-b5
jis-b4
jis-b5
For more information,
see the section
Supported paper types.

password

Optional

© 2014 Adobe Systems Incorporated. All rights reserved.

The owner or user
password for the PDF
source file. If the PDF file
is password-protected,
specify this attribute for
the file to print.

1009

Adobe ColdFusion Documentation

printer

Optional

The name of a printer. An
example in Windows is
\\s1001prn02\NTN-2W-H
P_BW02. The default
name is the default printer
for the account where the
ColdFusion server is
running. Printer names
are case sensitive and
must be entered exactly
as they appear in the
System Information page
of the ColdFusion
Administrator. For more
information, see Usage.

source

Required

Source document to print.
Specify one of the
following:
An absolute or relative
pathname to an on-disk
or in-memory PDF
document file, for
example,
c:\work\myPDF.pdf or
myPDF.pdf. The default
directory is the template
directory.
A PDF document
variable in memory that
is generated by the cfd
ocument tag or the cf
pdf tag, for example, "
myPDFdoc".

type

Optional

PDF

The file type of the
document being printed.
The only valid value is
PDF.

Usage

Use the cfprint tag for automated batch printing of PDF documents. For example, you can run a batch job each
evening that generates a report in PDF format and then prints either the entire report or selected pages for review
the next morning without user intervention.Most of the cfprint tag attributes are printer-dependent. If a printer
does not support a specified attribute, it ignores the instruction. The default settings for the attributes also are
printer-dependent. If you set a default printer, only specify the PDF file source and the password, if the file is
password-protected.

© 2014 Adobe Systems Incorporated. All rights reserved.

1010

Adobe ColdFusion Documentation

Note
The particular printer attributes supported are dependent on the operating system, the network
printer server, if there is one, and the printer. The cfprint tag is dependent on the Java Print
Service (JPS). Many printers support attributes that are not accessible from JPS. For example,
the JPS for a Macintosh OSX running JDK 1.5 supports the fewest printer attributes. Upgrading
to JDK 1.6 adds some functionality, but finishing attributes are still not supported.

If the fidelity attribute is set to yes, the job does not print if any of the specified attributes are not supported by
the printer. If the fidelity attribute is set to no, the printer accepts the print job and either ignores any attribute it
does not support or substitutes a reasonable alternative for the attribute.
To determine which attributes are supported on a specified printer, use the GetPrinterInfo function.
Supported paper types

You can use the equivalent page types supported by the cfdocument tag, but they are not returned by the GetPri
nterInfo function:
cfdocument
letter
legal
A4
A5
B4
B5
B4-JIS
B5-JIS

cfprint
na-letter
na-legal
iso-a4
iso-a5
iso-b4
iso-b5
jis-b4
jis-b5

View a list of configured printers

1. Log on to the ColdFusion Administrator.
2. Click the System Information icon located at the top right of the Administrator Console window. (The icon has
an "i" on it.)
3. Scroll to the bottom of the System Information page. Under Printer Details is the Default Printer. Below the
default printer is Printers, which lists the configured printers available to ColdFusion, including the default
printer.
Printer configuration is operating system-dependent. Configure printers outside of ColdFusion.
View the print log

1. Log on to the ColdFusion Administrator.
2. Expand the Debugging and Logging topic.
3. Click the Log Files link. The print.log file appears in the list of log files.
Permissions for printing

If the PDF file is encrypted, the permissions for the file must be set to AllowPrinting, or specify the owner
password to print the file. Use the protect action of the cfpdf tag to set permissions and passwords on PDF files.
For more information, see Permissions for PDF documents in cfpdf.
If a Security Manager is installed, the following permission is required in the coldfusion.policy file to initiate a print job
request:

© 2014 Adobe Systems Incorporated. All rights reserved.

1011

Adobe ColdFusion Documentation

grant { permission java.lang.RuntimePermission "queuePrintJob"; };

In Windows systems, the account running the ColdFusion server must have PRINTER_ACCESS_USE access rights
for each printer it uses. Even if the printer is configured locally on the system, the printer is not available if the
account in which ColdFusion is running does not have the proper permissions.
Note
By default, ColdFusion installs and runs as the Local System account, which may not have
printer queue access rights. For information on running ColdFusion as a specific user, see the
following Tech Note: http://www.adobe.com/cfusion/knowledgebase/index.cfm?id=tn_17279

attributeStruct

The following table lists the optional attributeStruct key-value pairs that you use to specify print requests:
Element

Description

autoRotateAndCenter

Adjusts the document's orientation to match the
orientation specified in the printer attributes and centers
the page in the imaging area:
yes: the orientation, if specified, is ignored (default)
no: the orientation, if specified, is applied to the
document

collate or sheetCollate

Specifies whether the sheets of each copy of each
printed document in a job are in sequence when
multiple copies of the document are specified by the co
pies attribute:
yes
no

color or chromaticity

Specifies color or monochrome printing. Monochrome
printing displays colors in shades of gray:
yes: print in color.
no: print in monochrome.

copies

Number of copies of the source document to print.
Valid values are integers greater than or equal to 1.

coverPage or jobSheets

Specifies which job start and end sheets, if any, are
printed with a job:
none
standard

© 2014 Adobe Systems Incorporated. All rights reserved.

1012

Adobe ColdFusion Documentation

fidelity

Specifies whether to print a job based on the print
requirements specified. The following values are valid
values:
yes: If the job cannot be printed exactly as specified
in the print requirements, the job is rejected.
no: A reasonable attempt to print the job is
acceptable (default).

finishings

Finishing operation to perform after each copy of a
document is printed:
staple-top-left
staple-bottom-left
staple-top-right
staple-bottom-right
edge-stitch-left
edge-stitch-right
edge-stitch-top
edge-stitch-bottom
dual-right
dual-top
dual-bottom
dual-left

jobHoldUntil

Date-time attribute for the exact date and time at which
the job is available for printing. Valid values are
ColdFusion date and time variables.

jobName

The name of a print job.

jobPriority

Integer value that represents a print job's priority.
Among those jobs that are ready to print, a printer must
print all jobs with a priority value of n before printing
those with a priority value of n-1 for all n. Valid values
are integers from 1 (lowest priority) through 100
(highest priority).

numberUp

Number of pages to print on a single side of paper. The
value must be a number greater than or equal to 1.

orientation or orientationRequested

Orientation of the page to be printed. The only valid
value for PDF documents is portrait. To change the
orientation to landscape, set the autoRotateAndCen
ter to yes (which is the default value). The autoRota
teAndCenter instruction overrides the orientation
instruction.

© 2014 Adobe Systems Incorporated. All rights reserved.

1013

Adobe ColdFusion Documentation

pages

Pages in the source file to print. Duplicate pages and
pages beyond the total count of pages in the document
are ignored as long as there is at least one page
between 1 and the total number of pages in the
document. You can combine individual page numbers
and page ranges, for example, 1-3,6,10-20. If you do
not specify a value for the pages attribute, ColdFusion
prints the entire document.

pageScaling

Specifies how pages are scaled on the paper:
fit-to-printer-margins: Reduces or enlarges
each page to fit the printable area of the currently
selected paper size.
reduce-to-printer-margins: Shrinks large
pages to fit the currently selected paper size but
does not enlarge small pages. If an area is selected
and is larger than the printable area of the currently
selected paper, the page is scaled to fit the printable
area (Default).
none: Prints the upper left or center of a page (if
autorotated and centered) without scaling. Pages
that don't fit on the paper are cropped.

pageSubset

Prints a subset of pages in specified by the pages
attribute:
all: Prints all the pages in the specified page range
(Default).
odd: Prints only the odd pages in the specified page
range.
even: Prints only the even pages in the specified
page range.

paper

Paper used for the print job. The value can be any
returned by the GetPrinterInfo function. The
following values are the most common:
na-letter
iso-a4

presentationDirection

© 2014 Adobe Systems Incorporated. All rights reserved.

Used in conjunction with the numberUp attribute to
indicate the layout of multiple document pages on one
side of the paper.

1014

Adobe ColdFusion Documentation

printer

The name of a printer. An example in Windows is
\\s1001prn02\NTN-2W-HP_BW02. The default name is
the default printer for the account where the
ColdFusion server is running. Printer names are case
sensitive and you must enter the names exactly as they
appear in the System Information page of the
ColdFusion Administrator. For more information on
viewing print logs, see Usage.

quality

Print quality for the print job:
draft
high
normal

requestingUserName

A string that specifies the name of the end user that
submitted the print job.

reversePages

Prints pages in reverse order. If page ranges are
entered, the pages print opposite of the order in which
they were entered. For example, if the Pages box
shows 3-5, 7-10, selecting Reverse Pages prints pages
10-7, and then 5-3.
yes
no (default)

sides

Sides of the paper on which the pages are printed:
one-sided (default)
duplex or two-sided-long-edge
tumble or two-sided-short-edge

usePdfPageSize

Uses the PDF page size to determine the area of the
paper printed rather than the paper size. This is useful
for printing PDF documents that contain multiple page
sizes:
yes
no (default)

Example

The following example shows how to use the attributeStruct attribute and the cfprint tag to print five,
double-sided copies of a letter-sized PDF document, which are stapled on the top-left corner and collated:





© 2014 Adobe Systems Incorporated. All rights reserved.

1015

Adobe ColdFusion Documentation

The following example shows how to specify all of the print attributes with the attributeStruct attribute:


aset["paper"] = "letter">
aset["sides"] = "duplex">
aset["copies"] = "5">
aset["printer"] = "\\s1001prn02\NTN-2W-HP_BW02">



Printers have a setting called autoRotateAndCenter, which is set to yes by default. The following example
shows how to override the default autoRotatateAndCenter setting and use the orientation setting instead:






To run a print job asynchronously, start a print job in a thread. Do not wait for the print job to be sent to the printer
before proceeding. To start a print job in a thread, enclose the cfprint tag within cfthread start and end tags, as
the following example shows:




....

For more information, see cfthread.

© 2014 Adobe Systems Incorporated. All rights reserved.

1016

Adobe ColdFusion Documentation

cfprocessingdirective
Description

Provides the following information to ColdFusion about how to process the current page:
Specifies whether to remove excess whitespace character from ColdFusion generated content in the tag
body.
Identifies the character encoding (character set) of the page contents.
Category

Data output tags, Page processing tags
Syntax


OR

CFML tags


See also

cfcol, cfcontent, cfoutput, cfsetting, cfsilent, cftable; Developing Globalized Applications in the Dev
eloping ColdFusion Applications
History

ColdFusion MX:
Changed suppresswhitespace attribute value behavior: you can specify the suppresswhitespace attri
bute value as a string variable. (ColdFusion 5 supported setting it only as a constant.)
Added the pageEncoding attribute.
ColdFusion 11:
In general, one should no longer need to use this tag to specify the page encoding as the ColdFusion server
should be able to identify it automatically.
Attributes

Attribute

Req/Opt

© 2014 Adobe Systems Incorporated. All rights reserved.

Default

Description

1017

Adobe ColdFusion Documentation

pageEncoding

Optional

Character encoding
identified by the page byte
order mark, if any;
otherwise, system default
encoding

A string literal; cannot be
a variable. Identifies the
character encoding of the
current CFML page. This
attribute affects the entire
page, not just the cfproc
essingdirective tag
body. The value may be
enclosed in single- or
double-quotation marks,
or none.
The following list includes
commonly used values:
utf-8
iso-8859-1
windows-1252
us-ascii
shift_jis
iso-2022-jp
euc-jp
euc-kr
big5
euc-cn
utf-16
For more information on
character encodings,
see www.w3.org/Intern
ational/O-charset.html.

suppressWhiteSpace

Optional

Boolean; whether to
suppress white space
characters within the cfp
rocessingdirective b
lock that are generated by
CFML tags and often do
not affect HTML
appearance. Does not
affect any white space in
HTML code.

Usage

The cfprocssingdirective tag has limitations that depend on the attribute you use. For this reason, Adobe
recommends that you include either the pageencoding or suppresswhitespace attribute in a cfprocessingd
irective tag, not both. To specify both values, use separate tags.
In a ColdFusion component (.cfc file), the cfprocessingdirective tag must follow the cfcomponent tag.
If you use the pageEncoding attribute, the following rules apply:
You must put the tag within the first 4096 bytes of a page. It can be positioned after a cfsetting or cfsile
nt tag.
If you use the tag on a page that includes other pages by using the cfinclude or cfmodule tags, custom

© 2014 Adobe Systems Incorporated. All rights reserved.

1018

Adobe ColdFusion Documentation

tag invocation, and so on, the tag has no effect on the included pages.
You cannot embed the tag within conditional logic, because the pageEncoding attribute is evaluated when
ColdFusion compiles a page (not when it executes the page). For example, the following code has no effect
at execution time, because the cfprocessingdirectivetag has already been evaluated:





If you have multiple cfprocessingdirective tags in one page that specify the pageEncoding attribute,
they must all specify the same value; if not, ColdFusion throws an error.
If you specify only the pageencoding attribute, do not use a separate end tag.
ColdFusion accepts character encoding names that are supported by the Java platform. If an invalid name is
specified, ColdFusion throws an InvalidEncodingSpecification exception.
If a page has a byte order mark (BOM), and a pageencoding attribute specifies an encoding that differs
from the BOM, ColdFusion generates an error.
The following rules apply to the suppressWhiteSpace attribute:
You can specify the suppresswhitespace attribute value as a constant or a variable. To use a variable:
define the variable (for example, whitespaceSetting), assign it the value yes or no, and code a statement
such as the following:



code to whose output the setting is applied


The suppresswhitespace attribute only affects code that you put between the  begin tag and the  end tag.
The following example shows the use of a nested cfprocessingdirective tag. The outer tag suppresses
unnecessary whitespace during computation of a large table; the inner tag retains whitespace, to output a
preformatted table.
Example




#table_data#




The following example shows the use of the pageencoding attribute:



© 2014 Adobe Systems Incorporated. All rights reserved.

1019

Adobe ColdFusion Documentation

cfprocparam
Description

Defines stored procedure parameters. This tag is nested within a cfstoredproc tag.
Category

Database manipulation tags
Syntax



Note
You can specify this tag's attributes in an attributeCollection attribute whose value is a
structure. Specify the structure name in the attributeCollection attribute and use the tag's
attribute names as structure keys.

See also

cfinsert, cfprocresult, cfquery, cfqueryparam, cfstoredproc, cftransaction, cfupdate; Optimizin
g ColdFusion applications in Designing and Optimizing a ColdFusion Application in the Developing ColdFusion
Applications
History

ColdFusion MX:
The maxrows attribute is obsolete.
Changed the dbvarname attribute behavior: it is now ignored for all drivers. ColdFusion uses JDBC 2.2 and
does not support named parameters. This is deprecated.
Changed the maxLength attribute behavior: it now applies to IN and INOUT parameter values.
Attributes

Attribute

Req/Opt

© 2014 Adobe Systems Incorporated. All rights reserved.

Default

Description

1020

Adobe ColdFusion Documentation

CFSQLType

Required

SQL type to which the
parameter (any type) is
bound. ColdFusion
supports the following
values, where the last
element of the name
corresponds to the SQL
data type. Different
database systems might
support different subsets
of this list. For information
on supported parameter
types, see your DBMS
documentation.
CF_SQL_BIGINT
CF_SQL_BIT
CF_SQL_BLOB
CF_SQL_CHAR
CF_SQL_CLOB
CF_SQL_DATE
CF_SQL_DECIMAL
CF_SQL_DOUBLE
CF_SQL_FLOAT
CF_SQL_IDSTAMP
CF_SQL_INTEGER
CF_SQL_LONGVARCHA
R
CF_SQL_MONEY
CF_SQL_MONEY4
CF_SQL_NUMERIC
CF_SQL_REAL
CF_SQL_REFCURSOR
CF_SQL_SMALLINT
CF_SQL_TIME
CF_SQL_TIMESTAMP
CF_SQL_TINYINT
CF_SQL_VARCHAR
For a mapping of
ColdFusion SQL data
types to JDBC data
types, see cfquerypa
ram.

© 2014 Adobe Systems Incorporated. All rights reserved.

1021

Adobe ColdFusion Documentation

maxLength

Optional

0

Maximum length of a
string or character IN or
INOUT value attribute. A
maxLength of 0 allows
any length. The maxLeng
th attribute is not required
when specifying type=ou
t.

null

Optional

no

Whether the parameter is
passed in as a null value.
Not used with OUT type
parameters.
yes: tag ignores the va
lue attribute.
no

scale

Optional

0

type

Optional

in

value

Required if type = "IN"

© 2014 Adobe Systems Incorporated. All rights reserved.

Number of decimal places
in numeric parameter. A s
cale of 0 limits the value
to an integer.
in: the parameter is
used to send data to the
database system only.
Passes the parameter
by value.
out: the parameter is
used to receive data
from the database
system only. Passes
the parameter as a
bound variable.
inout: the parameter
is used to send and
receive data. Passes
the parameter as a
bound variable.
Value that ColdFusion
passes to the stored
procedure. This is optional
for inout parameters.

1022

Adobe ColdFusion Documentation

variable

Required if type = "OUT"
or "INOUT"

ColdFusion variable
name; references the
value that the output
parameter has after the
stored procedure is called.
This is ignored for in para
meters.

Usage

Use this tag to identify stored procedure parameters and their data types. Code one cfprocparam tag for each
parameter. The parameters that you code vary based on parameter type and DBMS. ColdFusion supports positional
parameters. If you use positional parameters, you must code cfprocparam tags in the same order as the
associated parameters in the stored procedure definition.Output variables are stored in the ColdFusion variable
specified by the variable attribute.
You cannot use the cfprocparam tag for Oracle 8 and 9 reference cursors. Instead, use the cfprocresult tag.
Example

The following examples list the equivalent Oracle and Microsoft SQL Server stored procedures that insert data into
the database. The CFML to invoke either stored procedure is the same.
The following example shows the Oracle stored procedure:

CREATE OR REPLACE PROCEDURE Insert_Book (
arg_Title Books.Title%type,
arg_Price Books.Price%type,
arg_PublishDate Books.PublishDate%type,
arg_BookID OUT Books.BookID%type)
AS
num_BookID NUMBER;
BEGIN
SELECT seq_Books.NEXTVAL
INTO num_BookID
FROM DUAL;
INSERT INTO
Books (
BookID,
Title,
Price,
PublishDate )
VALUES (
num_BookID,
arg_Title,
arg_Price,
arg_PublishDate );
arg_BookID := num_BookID;
END;
/

The following example shows the SQL Server stored procedure:

© 2014 Adobe Systems Incorporated. All rights reserved.

1023

Adobe ColdFusion Documentation

CREATE PROCEDURE Insert_Book (
@arg_Title VARCHAR(255),
@arg_Price SMALLMONEY,
@arg_PublishDate DATETIME,
@arg_BookID INT OUT)
AS
BEGIN
INSERT INTO
Books (
Title,
Price,
PublishDate )
VALUES (
@arg_Title,
@arg_Price,
@arg_PublishDate );
SELECT @arg_BookID = @@IDENTITY;
END;

You use the following CFML code to call either stored procedure:

© 2014 Adobe Systems Incorporated. All rights reserved.

1024

Adobe ColdFusion Documentation












'#form.title#' inserted into database. The ID is #bookId#.



Insert a new book
Title:



Price:



Publish Date:






© 2014 Adobe Systems Incorporated. All rights reserved.

1025

Adobe ColdFusion Documentation

cfprocresult
Description

Associates a query object with a result set returned by a stored procedure. Other ColdFusion tags, such as cfoutp
ut and cftable, use this query object to access the result set. This tag is nested within a cfstoredproc tag.
Category

Database manipulation tags
Syntax



Note
You can specify this tag's attributes in an attributeCollection attribute whose value is a
structure. Specify the structure name in the attributeCollection attribute and use the tag's
attribute names as structure keys.

See also

cfinsert, cfprocparam, cfquery, cfqueryparam, cfstoredproc, cftransaction, cfupdate; Optimizing
database use in Designing and Optimizing a ColdFusion Application in the Developing ColdFusion Applications
Attributes

Attribute

Req/Opt

Default

Description

name

Required

maxRows

Optional

-1 (All)

Maximum number of rows
returned in result set.

resultSet

Optional

1

Names one result set, if
stored procedure returns
more than one.

Name for the query result
set.

Usage

To enable access to data returned by the stored procedure, specify one or more cfprocresult tags. If the stored
procedure returns more than one result set, use the resultSet attribute to specify which of the stored procedure's
result sets to return.
The resultSet attribute must be unique within the scope of the cfstoredproc tag. If you specify a result set
twice, the second occurrence overwrites the first.CFML supports Oracle 8 and 9 Reference Cursor type, which
passes a parameter by reference. Parameters that are passed this way can be allocated and deallocated from

© 2014 Adobe Systems Incorporated. All rights reserved.

1026

Adobe ColdFusion Documentation

memory within the execution of one application. To use reference cursors in packages or stored procedures, use the
cfprocresult tag. This causes the ColdFusion JDBC database driver to put Oracle reference cursors into a result
set. (You cannot use this method with Oracle's ThinClient JDBC drivers.)
Example













The output param value: '#foo#'


The Results Information
#name#,#DATE_COL#





Record Count: #RS1.recordCount# 
Columns: #RS1.columnList#


#col1#,#col2#,#col3#





Record Count: #RS3.recordCount# 
Columns: #RS3.columnList#

The return code for the stored procedure is:
'#cfstoredproc.statusCode#'


...

© 2014 Adobe Systems Incorporated. All rights reserved.

1027

Adobe ColdFusion Documentation

cfprogressbar
Description

Defines a progress bar to indicate the progress of an activity such as a file download.
Category

Display management tags
Syntax



History

ColdFusion 9: Added this tag.
Attributes

Attribute

Req/Opt

Default

Description

autoDisplay

Optional

true

Set to true to display the
progress bar.

name

Required

© 2014 Adobe Systems Incorporated. All rights reserved.

The control name. Used
to refer to the control in
JavaScript, for example in
the script that starts the
progress.

1028

Adobe ColdFusion Documentation

bind

Required if duration is
not specified

A bind expression
specifying a client
JavaScript function or
server CFC that the
control calls to get
progress information each
time the period defined by
the interval attribute
elapses. You cannot use
this attribute with a durat
ion attribute.
If an error occurs, no
further bind expression
calls are triggered and on
Error is called (if
defined).

duration

Required if bind is not
specified

The time, in milliseconds,
between when the bar
starts showing progress
and when it shows
completed progress. Use
only on automatic
progress bars that do not
use a bind expression to
get actual progress
information. You cannot
use this attribute with a bi
nd attribute.

height

Optional

Height of the bar in pixels.

interval

Optional

onComplete

Optional

© 2014 Adobe Systems Incorporated. All rights reserved.

1000

Used if duration is
specified. The time
interval, in milliseconds, at
which the progress bar
updates. Although this
attribute is optional,
specify it to prevent the
bar from updating
frequently.
The name of a function to
call when progress
completes.

1029

Adobe ColdFusion Documentation

Applies only if you use bi
nd. The JavaScript
function to run on an error
condition. The error can
be a network error or
server-side error.

onError

style

Optional

The following are the
supported colors:
bgcolor: The
background color for
the progress bar. A
hexadecimal value
without "#" prefixed.
textcolor: Text color on
progress bar.
progresscolor: Color
used to indicate the
progress.

width

Optional

400

The width (length) of the
bar in pixels.

Usage

A progress bar has one of two behaviors:
Manual, where the progress indicator length increases steadily over a time specified by the duration attribu
te.
Dynamic, where the bind attribute specifies a function that determines the indicator length.
If you use a bind expression, the called function takes no parameters, and must return a structure with two
values:
status - A decimal completion value, in the range 0 -1.0
message - A message to display in the progress bar, such as "Loading..." or "Completed".
You use two Ajax functions to start and stop the progress bar:

ColdFusion.ProgressBar.start(barName)
ColdFusion.ProgressBar.stop(barName)

You must call the start method to start the progress bar. You call the stop method to explicitly stop the
progress bar. The bar stops automatically when the bind method returns a status value of 1 or the period
specified by the duration attribute elapses. Therefore, you need to use this method only if a process does
not complete, if the process completes before the duration period, or in other nonstandard situations, such
as error conditions.
Example

The following uses a simple comment form, and uses a timer to simulate the time it would take to process the form.
The Application.cfc page must enable session management.

© 2014 Adobe Systems Incorporated. All rights reserved.

1030

Adobe ColdFusion Documentation

The main application page contains the following code:

© 2014 Adobe Systems Incorporated. All rights reserved.

1031

Adobe ColdFusion Documentation












StructDelete(Session,"STATUS");




To make our service better and to benefit from our special offers,
take a moment to give us your email address and send us a comment.
Name:

  
E-mail:

  
Comment:

 
       









© 2014 Adobe Systems Incorporated. All rights reserved.

1032

Adobe ColdFusion Documentation

The mycfc.cfc file has a single getstatus function:









Sleep(200);




Sleep(200);










© 2014 Adobe Systems Incorporated. All rights reserved.

1033

Adobe ColdFusion Documentation

cfproperty
Description

Defines properties and their annotations for a ColdFusion component (CFC). The properties are used to create
complex data types for web services, while the annotations are used to define Object Relational Model (ORM) for a
CFC. The attributes of this tag are exposed as component metadata and are subject to inheritance rules.
Category

Extensibility tags
Syntax



Note
For ORM-related attributes and their usage, see Map the properties in the Developing
ColdFusion Applications.

See also

cfargument, cfcomponent, cffunction, cfinvoke, cfinvokeargument, cfobject, cfreturn; Documenti
ng CFCs in Building and Using ColdFusion Components, Implicit Get and Set Functions in the Developing
ColdFusion Applications
History

ColdFusion 9: Added attributes for defining Object Relational Model for the CFC.Added implicit getters and setters.
Added validate and validateparams attributes.
ColdFusion MX: Added this tag.
Attributes

Attribute

Req/Opt

batchsize

Default

Description
For information about
these attributes, see Cold
Fusion ORM.

cascade
catalog

© 2014 Adobe Systems Incorporated. All rights reserved.

1034

Adobe ColdFusion Documentation

cfc
collectiontype
column
constrained
datatype
default

Optional

If no property value is set
when the component is
used for a web service,
specifies a default value.
If this attribute is present,
the required attribute
must be set to no or not
specified.
For ORM-specific usage
of the default attribute,
see ColdFusion ORM.

displayname

Optional

A value to be displayed
when using introspection
to show information about
the CFC. The value
appears in parentheses
following the property
name.

dynamicInsert

For information about
these attributes, see Cold
Fusion ORM.

dynamicupdate
elementColumn
elementtype
entityname
fetchbatchsize
fieldType
fkcolumn
formula

© 2014 Adobe Systems Incorporated. All rights reserved.

1035

Adobe ColdFusion Documentation

generator
getter

Optional

Specifies whether to
generate getter methods
or not. Value are:
true
false

Optional

hint

Text to be displayed when
using introspection to
show information about
the CFC. This attribute
can be useful for
describing the purpose of
the parameter.
For information about
these attributes, see Cold
Fusion ORM.

index

insert
inverse

inversejoi
ncolumn

joincolumn
lazy
length
linkcatalog
linkschema
linktable
mappedby
missingrowIgnored
name

Required

© 2014 Adobe Systems Incorporated. All rights reserved.

A string; a property name.
Must be a static value.

1036

Adobe ColdFusion Documentation

For information about
these attributes, see Cold
Fusion ORM.

notnull

optimisticLock
optimisticLockgener
ated
orderby
orderByreadonly
For information about
these attributes, see Cold
Fusion ORM.

params

persistent
preceision
readonly
readonly
required

Optional

no

Whether the parameter is
required:
yes
no
For information about
these attributes, see Cold
Fusion ORM.

rowid

scale

setter

Specifies whether to
generate setter methods
or not. Possible values
are:
true
false

schema

© 2014 Adobe Systems Incorporated. All rights reserved.

For information about
these attributes, see Cold
Fusion ORM.

1037

Adobe ColdFusion Documentation

selectbeforeupdate
selectkey
sequence
serializable

Optional

source

true

Specifies whether this
property can be serialized.
If you set this value to fa
lse, the property cannot
be serialized, so any
changes made are not
retained on session
replication, and the
property has its default
value (if any) on the
second server. Use this
attribute to prevent
serializaton of properties
in CFCs that are
serializable.
For information about
these attributes, see Cold
Fusion ORM.

structkeycolumn
structkeycolumn
structkeydatatype
structkeyType
table
table

© 2014 Adobe Systems Incorporated. All rights reserved.

1038

Adobe ColdFusion Documentation

type

Optional

any

A string; identifies the
property data type:
any
array
binary
boolean
date
guid: the argument
must be a UUID or
GUID of the form
xxxxxxxx-xxxx-xxxx-xxx
x-xxxxxxxxxxxx where
each x is a character
representing a
hexadecimal number
(0-9A-F).
numeric
query
string
struct
uuid: The argument
must be a ColdFusion
UUID of the form
xxxxxxxx-xxxx-xxxx-xxx
xxxxxxxxxxxxx where
each x is a character
representing a
hexadecimal number
(0-9A-F).
variableName: a
string formatted
according to
ColdFusion variable
naming conventions.
a component name: if
the type attribute value
is not one of the
preceding items,
ColdFusion treats it as
the name of a
ColdFusion component.
When the function
executes, it generates
an error if the argument
that is passed in is not a
CFC with the specified
name.

unique

© 2014 Adobe Systems Incorporated. All rights reserved.

For information about
these attributes, see Cold
Fusion ORM.

1039

Adobe ColdFusion Documentation

uniquekey
update

where

validate

Optional

validateparam

Optional

For more information, see
Validate and
validateparams attributes i
n Functions.

Usage

You must position cfproperty tags at the beginning of a component, above executable code and function
definitions. If a component is not used as a web service,  only provides metadata information of the
property. It does not define variables or set values that you can use in your component. However, it creates implicit
setters and getters for the property in the CFC depending on whether getter/setter attributes are enabled. For
details, see Implicit Get and Set Functions in Developing ColdFusion Applications.
For Object Relational Model (ORM), cfproperty is used to define relational mapping for the property of the CFC.
For details, see ColdFusion ORM in Developing ColdFusion Applications.
For web services that you create in ColdFusion, the cfproperty tag defines complex variables used by the web
service.
Example

The following code defines a component in the file address.cfc that contains properties that represent a street
address:









This component represents a complex data type that can be used in a component that is exported as a web service,
such as the following:

© 2014 Adobe Systems Incorporated. All rights reserved.

1040

Adobe ColdFusion Documentation








© 2014 Adobe Systems Incorporated. All rights reserved.

1041

Adobe ColdFusion Documentation

cfquery
Description

Passes queries or SQL statements to a data source.Adobe recommends that you use the cfqueryparam tag within
every cfquery tag, to help secure your databases from unauthorized users. For more information, see Security
Bulletin ASB99-04, "Multiple SQL Statements in Dynamic Queries," in the Security Zone, www.adobe.com/go/sn_as
b99-04, and Accessing and Retrieving Data in the Developing ColdFusion Applications.
Category

Database manipulation tags
Syntax




Note
You can specify this tag's attributes in an attributeCollection attribute whose value is a
structure. Specify the structure name in the attributeCollection attribute and use the tag's
attribute names as structure keys.

See also

cfdbinfo, cfinsert, cfprocparam, cfprocresult, cfqueryparam, cfstoredproc, cftransaction, cfu
pdate; Optimizing database use in Optimizing ColdFusion applications in the Developing ColdFusion Applications
History

ColdFusion 10: Added the following attributes: fetchClientInfo, cacheID, cacheRegion, clientInfo}}
ColdFusion 9.0.1: Introduced support for HQL queries; added the attribute
{{ormoptions.
ColdFusion 9: Datasource attribute is optional now.

© 2014 Adobe Systems Incorporated. All rights reserved.

1042

Adobe ColdFusion Documentation

ColdFusion 8: Added the result variable that specifies the ID of a row.
ColdFusion MX 7:
Added the result attribute for specifying an alternate name for the structure that holds the result variables.
Added result variables for the SQL statement executed (sql), the number of records returned (recordcoun
t), whether the query was cached (cached), an array of cfqueryparam values (sqlparameters), and the
list of columns in the returned query (columnlist).
ColdFusion MX:
Changed Query of Queries behavior: it now supports a larger subset of standard SQL.
Changed dot notation support: ColdFusion now supports dot notation within a record set name. ColdFusion
interprets such a name as a structure.
Deprecated the connectString, dbName, dbServer, provider, providerDSN, and sql attributes, and
all values of the dbtype attribute except query. They do not work, and might cause an error, in releases
later than ColdFusion 5.
New query object variable: cfquery.ExecutionTime.
No longer supports native drivers. It now uses JDBC (and ODBC-JDBC bridge) for database connectivity.
Attributes

Attribute

Req/Opt

name

Required

blockFactor

Optional

cachedAfter

Optional

© 2014 Adobe Systems Incorporated. All rights reserved.

Default

Description
Name of query. Used in
page to reference query
record set. Must begin
with a letter. Can include
letters, numbers, and
underscores.

1

Maximum rows to get at a
time from server. Range:
1 - 100. Might not be
supported by some
database systems.
Date value (for example,
April 16, 1999, 4-16-99). If
date of original query is
after this date, ColdFusion
uses cached query data.
To use cached data,
current query must use
same SQL statement,
data source, query name,
user name, password. A
date/time object is in the
range 100 AD-9999 AD.
When specifying a date
value as a string, enclose
it in quotation marks.

1043

Adobe ColdFusion Documentation

cacheID

Optional

ID to be used to store
query result in cache. This
ID can be used to either
retrieve or remove query
from cache

cacheR{{egion}}

Optional

Cache region to be used
to cache query result. If
not specified, by default
query is cached in the
QUERY region.

cachedWithin

Optional

Timespan, using the Crea
teTimeSpan function. If
original query date falls
within the time span,
cached query data is
used. CreateTimeSpan
defines a period from the
present, back. Takes
effect only if query
caching is enabled in the
Administrator. To use
cached data, the current
query must use the same
SQL statement, data
source, query name, user
name, and password.

clientInfo

Optional

Structure containing
properties of the client to
be set on the database
connection.

dataSource

Optional

The Datasource attribute
is now optional. If omitted,
the query uses the
datasource specified in
the application. If it is not
specified in either places,
then the error will be
thrown.

© 2014 Adobe Systems Incorporated. All rights reserved.

1044

Adobe ColdFusion Documentation

dbtype

Optional

debug

Optional; value and
equals sign may be
omitted

fetchClientInfo

Optional

no

If set yes, returns a struct
with the key-value pair
passed by the last query.

maxRows

Optional

-1 (All)

Maximum number of rows
to return in record set.

ormoptions

Optional

A struct that takes orm
options for executing
HQL. Applies only if dbty
pe is set to hql.

password

Optional

Overrides the password in
the data source setup.

© 2014 Adobe Systems Incorporated. All rights reserved.

Results of a query as
input. Specify either dbty
pe or dataSource.ColdF
usion supports HQL in cf
query. Therefore, you
can specify dbtype="hq
l" as shown in the
following example:from
Artists where
firstname=
yes, or if omitted: if
debugging is enabled,
but the Administrator
Database Activity option
is not enabled, displays
SQL submitted to the
data source and
number of records
returned by query.
no: if the Administrator
Database Activity option
is enabled, suppresses
display.

1045

Adobe ColdFusion Documentation

Optional

result

Name for the structure in
which cfquery returns
the result variables. For
more information, see
Usage.
Maximum number of
seconds that each action
of a query is permitted to
execute before returning
an error. The cumulative
time may exceed this
value.
For JDBC statements,
ColdFusion sets this
attribute. For other
drivers, see the driver
documentation.

timeout

username

Optional

Overrides user name in
the data source setup.

Usage

Use this tag to execute a SQL statement against a ColdFusion data source. Although you can use the cfquery tag
to execute any SQL Data Definition Language (DDL) or Data Manipulation Language (DML) statement, you typically
use it to execute a SQL SELECT statement.
Note
To call a stored procedure, use the cfstoredproc tag.

This tag creates a query object, providing this information in query variables:
Variable name

Description

query_name.currentRow

Current row of query that cfoutput is processing.

query_name.columnList

Comma-separated list of the query columns.

query_name.RecordCount

Number of records (rows) returned from the query.

The cfquery tag also returns the following result variables in a structure. You can access these variables with a
prefix of the name you specified in the result attribute. For example, if you assign the name myResult to the res
ult attribute, you would retrieve the name of the SQL statement that was executed by accessing #myResult.sql
#. The result attribute provides a way for functions or CFCs that are called from multiple pages, possibly at the
same time, to avoid overwriting results of one call with another. The result variable of INSERT queries contains a
key-value pair that is the automatically generated ID of the inserted row; this is available only for databases that
support this feature. If more than one record was inserted, the value can be a list of IDs. The key name is
database-specific.

© 2014 Adobe Systems Incorporated. All rights reserved.

1046

Adobe ColdFusion Documentation

Variable name

Description

result_name.sql

The SQL statement that was executed.

result_name.recordcount

Number of records (rows) returned from the query.

result_name.cached

True if the query was cached; False otherwise.

result_name.sqlparameters

An ordered Array of cfqueryparam values.

result_name.columnList

Comma-separated list of the query columns.

result_name.ExecutionTime

Cumulative time required to process the query.

result_name.IDENTITYCOL

SQL Server only. The ID of an inserted row.

result_name.ROWID

Oracle only. The ID of an inserted row. This is not the
primary key of the row, although you can retrieve rows
based on this ID.

result_name.SYB_IDENTITY

Sybase only. The ID of an inserted row.

result_name.SERIAL_COL

Informix only. The ID of an inserted row.

result_name.GENERATED_KEY

MySQL only. The ID of an inserted row. MySQL 3 does
not support this feature.

result_name.GENERATEDKEY

Supports all databases. The ID of an inserted row.

You can cache query results and execute stored procedures. For information about this and about displaying cfque
ry output, see the Developing ColdFusion Applications. Because the timeout attribute only affects the maximum
time for each suboperation of a query, the cumulative time may exceed its value. To set a timeout for a page that
might get a very large result set, set the Administrator > Server Settings > Timeout Requests option to an
appropriate value or use the RequestTimeout attribute of the cfsetting tag (for example, ).
The Caching page of the ColdFusion Administrator specifies the maximum number of cached queries. Setting this
value to 0 disables query caching.
You cannot use ColdFusion reserved words as query names. You cannot use SQL reserved words as variable or
column names in a Query of Queries, unless they are escaped. The escape character is the bracket []; for example:

SELECT [count] FROM MYTABLE.

For a list of reserved keywords in ColdFusion, see Escaping reserved keywords in Query of Queries user guide in th
e Developing ColdFusion Applications.
Example

© 2014 Adobe Systems Incorporated. All rights reserved.

1047

Adobe ColdFusion Documentation








SELECT PARKNAME, REGION, STATE
FROM Parks
ORDER BY ParkName, State





© 2014 Adobe Systems Incorporated. All rights reserved.

1049

Adobe ColdFusion Documentation




 


Park Name


Region


State





#GetParks.CurrentRow#


#ParkName#


#Region#


#State#









© 2014 Adobe Systems Incorporated. All rights reserved.

1048

Adobe ColdFusion Documentation

See next #MaxRows# rows




© 2014 Adobe Systems Incorporated. All rights reserved.

1050

Adobe ColdFusion Documentation

cfqueryparam
Description

Verifies the data type of a query parameter and, for DBMSs that support bind variables, enables ColdFusion to use
bind variables in the SQL statement. Bind variable usage enhances performance when executing a cfquery state
ment multiple times.
This tag is nested within a cfquery tag, embedded in a query SQL statement. If you specify optional parameters,
this tag performs data validation.Adobe recommends that you use the cfqueryparam tag within every cfquery ta
g, to help secure your databases from unauthorized users. For more information, see Security Bulletin ASB99-04, "
Multiple SQL Statements in Dynamic Queries," at www.adobe.com/go/sn_asb99-04, and Accessing and Retrieving
Data in the Developing ColdFusion Applications.
Category

Database manipulation tags
Syntax


AND/OR ...additional criteria of the WHERE clause...>


Note
You can specify this tag's attributes in an attributeCollection attribute whose value is a
structure. Specify the structure name in the attributeCollection attribute and use the tag's
attribute names as structure keys.

See also

cfinsert, cfprocparam, cfprocresult, cfquery, cfstoredproc, cftransaction, cfupdate; Enhancing
security with cfqueryparam in the Developing ColdFusion Applications
Attributes

Attribute

Req/Opt

© 2014 Adobe Systems Incorporated. All rights reserved.

Default

Description

1051

Adobe ColdFusion Documentation

value

Required

CFSQLType

Optional

Value that ColdFusion
passes to the right of the
comparison operator in a
where clause. If CFSQLT
ype is a date or time
option, ensure that the
date value uses your
DBMS-specific date
format. Use the CreateO
DBCDateTime or DateFo
rmat and TimeFormat fu
nctions to format the date
value.
CF_SQL_CHAR

SQL type that parameter
(any type) is bound to:
CF_SQL_BIGINT
CF_SQL_BIT
CF_SQL_CHAR
CF_SQL_BLOB
CF_SQL_CLOB
CF_SQL_DATE
CF_SQL_DECIMAL
CF_SQL_DOUBLE
CF_SQL_FLOAT
CF_SQL_IDSTAMP
CF_SQL_INTEGER
CF_SQL_LONGVARCHA
R
CF_SQL_MONEY
CF_SQL_MONEY4
CF_SQL_NUMERIC
CF_SQL_REAL
CF_SQL_REFCURSOR
CF_SQL_SMALLINT
CF_SQL_TIME
CF_SQL_TIMESTAMP
CF_SQL_TINYINT
CF_SQL_VARCHAR

list

Optional

© 2014 Adobe Systems Incorporated. All rights reserved.

no

yes: the value attribut
e value is a delimited
list.
no

1052

Adobe ColdFusion Documentation

maxLength

Optional

Length of string in value
attribute

Maximum length of
parameter. Ensures that
the length check is done
by ColdFusion before the
string is sent to the
DBMS, thereby helping to
prevent the submission of
malicious strings.

null

Optional

no

Whether parameter is
passed as a null value:
yes: tag ignores the va
lue attribute.
no

scale

Optional

0

Number of decimal places
in parameter. Applies to C
F_SQL_NUMERIC and CF
_SQL_DECIMAL.

separator

Required, if you specify a
list in value attribute

, (comma)

Character that separates
values in list, in value att
ribute.

Usage

Use the cfqueryparam tag in any SQL statement (for example, SELECT, INSERT, UPDATE, and DELETE) that
uses ColdFusion variables. For maximum validation of string data, specify the maxlength attribute.
This tag does the following:
Allows the use of SQL bind parameters, which improves performance.
Ensures that variable data matches the specified SQL type.
Allows long text fields to be updated from a SQL statement.
Escapes string variables in single-quotation marks.
To benefit from the enhanced performance of bind variables, use cfqueryparam for all ColdFusion
variables, and your DBMS must support bind variables. If a DBMS does not support bind parameters,
ColdFusion validates and substitutes the validated parameter value back into the string. If validation fails, it
returns an error message.
The validation rules are as follows:
For these types, a data value can be converted to a numeric value: CF_SQL_SMALLINT,
CF_SQL_INTEGER, CF_SQL_REAL, CF_SQL_FLOAT, CF_SQL_DOUBLE, CF_SQL_TINYINT,
CF_SQL_MONEY, CF_SQL_MONEY4, CF_SQL_DECIMAL, CF_SQL_NUMERIC, and CF_SQL_BIGINT
For these types, a data value can be converted to a date supported by the target data source:
CF_SQL_DATE, CF_SQL_TIME, CF_SQL_TIMESTAMP
For all other types, if the maxLength attribute is used, a data value cannot exceed the maximum length
specified.
ColdFusion debug output shows the bind variables as question marks and lists the values beneath the query,
in order of usage.

© 2014 Adobe Systems Incorporated. All rights reserved.

1053

Adobe ColdFusion Documentation

Note
To insert an empty string into a Microsoft Access table using the SequelLink ODBC
Socket or SequelLink Access driver, the CFSQLType attribute must specify
CF_SQL_LONGVARCHAR.

The following table shows the mapping of ColdFusion SQL data types with JDBC SQL types and those of the
listed database management systems:
ColdFusion

JDBC

DB2

Informix

CF_SQL_ARRA
Y

ARRAY

CF_SQL_BIGIN
T

Oracle

BIGINT

Bigint

int8, serial8

CF_SQL_BINA
RY

BINARY

Char for Bit Data

CF_SQL_BIT

BIT

CF_SQL_BLOB

BLOB

Blob

blob

blob, bfile

longvarbinary

CF_SQL_CHAR

CHAR

Char

char, nchar

char, nchar

char

CF_SQL_CLOB

CLOB

Clob

clob

clob,nclob

CF_SQL_DATE

DATE

Date

date, datetime,
year to day

CF_SQL_DECI
MAL

DECIMAL

Decimal

decimal, money

CF_SQL_DISTI
NCT

DISTINCT

CF_SQL_DOUB
LE

DOUBLE

Double

CF_SQL_FLOA
T

FLOAT

Float

float

number

real

CF_SQL_IDSTA
MP

CHAR

Char

char, nchar

char, nchar

char

CF_SQL_INTE
GER

INTEGER

Integer

integer, serial

bigint

binarytimestamp

boolean

© 2014 Adobe Systems Incorporated. All rights reserved.

MSSQL

bit

date

number

decimal

double

integer

1054

Adobe ColdFusion Documentation

CF_SQL_LONG
VARBINARY

LONGVARBINA
RY

Long Varchar for
Bit Data

byte

long raw

longvarbinary

CF_SQL_LONG
VARCHAR

LONGVARCHA
R

Long Varchar

text

long

longvarchar

CF_SQL_MON
EY

DOUBLE

Double

double

CF_SQL_MON
EY4

DOUBLE

Double

double

CF_SQL_NULL

NULL

CF_SQL_NUME
RIC

NUMERIC

Numeric

numeric

CF_SQL_OTHE
R

OTHER

CF_SQL_REAL

REAL

CF_SQL_REFC
URSOR

REF

CF_SQL_SMAL
LINT

SMALLINT

CF_SQL_STRU
CT

STRUCT

CF_SQL_TIME

Real

smallfloat

real

Smallint

smallint

smallint

TIME

Time

datetime hour to
second

time

CF_SQL_TIME
STAMP

TIMESTAMP

Timestamp

datetime year to
fraction(5),
datetime year to
second

CF_SQL_TINYI
NT

TINYINT

CF_SQL_VARB
INARY

VARBINARY

Rowid

CF_SQL_VARC
HAR

VARCHAR

Varchar

date

timestamp

tinyint

© 2014 Adobe Systems Incorporated. All rights reserved.

varchar,
nvarchar,
lvarchar

raw

varbinary

varchar2,
nvarchar2

varchar

1055

Adobe ColdFusion Documentation
Example


cfqueryparam Example


SELECT *
FROM courses
WHERE Course_ID = 


Course Number: #Course_ID#
 Description: #descript#


This example throws an error because the value passed in the CFQUERYPARAM tag
exceeds the
MAXLENGTH attribute



SELECT *
FROM employees
WHERE LastName=



Course Number: #FirstName# #LastName#
Description: #Department# 


#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

1056

Adobe ColdFusion Documentation

Tags r-s
This section lists tags starting with alphabets R-S with their description.
cfregistry
cfreport
cfreportparam
cfrethrow
cfreturn
cfsavecontent
cfschedule
cfscript
cfsearch
cfselect
cfservlet
cfservletparam
cfset
cfsetting
cfsharepoint
cfsilent
cfslider
cfspreadsheet
cfsprydataset
cfstoredproc
cfswitch

© 2014 Adobe Systems Incorporated. All rights reserved.

1057

Adobe ColdFusion Documentation

cfregistry
Description

This tag is deprecated for the UNIX platform. Reads, writes, and deletes keys and values in the system registry.
Provides persistent storage of client variables.
Note
For this tag to execute, it must be enabled in the ColdFusion Administrator. For more information,
see Configuring and Administering ColdFusion.

Category

Other tags, Variable manipulation tags
Syntax

The tag syntax depends on the action attribute value. See the following:
cfregistry action = "get"
cfregistry action = "set"
cfregistry action = "getAll"
cfregistry action = "delete"
See also

cfcookie, cfparam, cfsavecontent, cfschedule, cfset; About resource and sandbox security and Using
Persistent Data and Locking in the Developing ColdFusion Applications
History

ColdFusion MX:
Deprecated this tag on the UNIX platform. It might not work, and might cause an error, in later releases.
Changed how persistent data is stored: ColdFusion now stores most persistent data outside the system
registry, in XML files.
cfregistry action = "getAll"
Description

Returns all registry keys and values defined in a branch. You can access the values as you would any record set.
Syntax



© 2014 Adobe Systems Incorporated. All rights reserved.

1058

Adobe ColdFusion Documentation

Note
You can specify this tag's attributes in an attributeCollection attribute whose value is a
structure. Specify the structure name in the attributeCollection attribute and use the tag's
attribute names as structure keys.

See also

Using Persistent Data and Locking in the Developing ColdFusion Applications
Attributes

Attribute

Req/Opt

Default

action

Required

Always getall.

branch

Required

Name of a registry
branch.

name

Required

Name of record set to
contain returned keys and
values.

sort

Optional

asc

Description

Sorts query column data
(case-insensitive). Sorts
on Entry, Type, and Value
columns as text. Specify a
combination of columns
from query output, in a
comma-delimited list. For
example:

sort =
"value
desc,
entry asc"

asc: ascending (a to z)
sort order.
desc: descending (z to
a) sort order.

© 2014 Adobe Systems Incorporated. All rights reserved.

1059

Adobe ColdFusion Documentation

Optional

type

string

string: returns string
values.
dWord: returns DWord
values.
key: returns keys.
any: returns keys and
values.

Usage

This tag returns #entry#, #type#, and #value# in a record set that you can access through tags such as cfoutp
ut. To fully qualify these variables, use the record set name, as specified in the name attribute.
If #type# is a key, #value# is an empty string.
If you specify type= "any", getAll also returns binary registry values. For binary values, the #type# variable
contains UNSUPPORTED and #value# is blank.
Example



cfregistry action = "getAll"






cfregistry action = "get"
Description

Accesses a registry value and stores it in a ColdFusion variable.
Syntax



Note
You can specify this tag's attributes in an attributeCollection attribute whose value is a
structure. Specify the structure name in the attributeCollection attribute and use the tag's
attribute names as structure keys.

© 2014 Adobe Systems Incorporated. All rights reserved.

1060

Adobe ColdFusion Documentation
See also

Using Persistent Data and Locking in the Developing ColdFusion Applications
Attributes

Attribute

Req/Opt

Default

action

Required

Always get.

branch

Required

Name of a registry
branch.

entry

Required

Registry value to access.

variable

Required

Variable into which to put
value.

type

Optional

string

Description

string: returns string
value.
dWord: returns DWord
value.
key: returns key's
default value.

Usage

If the value does not exist, the cfregistry tag does not create an entry.
Example



cfregistry action = "get"

Java ClassPath value is #RegValue#


cfregistry action = "set"
Description

Adds a registry key, adds a value, or updates a value.
Syntax

© 2014 Adobe Systems Incorporated. All rights reserved.

1061

Adobe ColdFusion Documentation



Note
You can specify this tag's attributes in an attributeCollection attribute whose value is a
structure. Specify the structure name in the attributeCollection attribute and use the tag's
attribute names as structure keys.

See also

Using Persistent Data and Locking in the Developing ColdFusion Applications
Attributes

Attribute

Req/Opt

Default

Description

action

Required

Always set.

branch

Required

Name of a registry
branch.

entry

Required

Key or value to set.

type

Optional

string: sets a string
value (default).
dWord: sets a DWord
value.
key: creates a key.

value

Optional

Value data to set. If you
omit this attribute, the cfr
egistry tag creates
default value, as follows:
string: creates an
empty string: "".
dWord: creates a value
of 0 (zero).

Usage

If it does not exist, the cfregistry tag creates the key or value.
Example

© 2014 Adobe Systems Incorporated. All rights reserved.

1062

Adobe ColdFusion Documentation





cfregistry action = "set"

cfregistry action = "delete"
Description

Deletes a registry key or value.
Syntax



Note
You can specify this tag's attributes in an attributeCollection attribute whose value is a
structure. Specify the structure name in the attributeCollection attribute and use the tag's
attribute names as structure keys.

See also

Using Persistent Data and Locking in the Developing ColdFusion Applications
Attributes

Attribute

Req/Opt

action

Required

branch

Required

© 2014 Adobe Systems Incorporated. All rights reserved.

Default

Description
Always delete.
For key deletion: name
of registry key to delete.
Do not specify the entr
y attribute.
For value deletion:
name of registry branch
that contains value to
delete. Specify the ent
ry attribute.

1063

Adobe ColdFusion Documentation

entry

Required for value
deletion

Value to delete.

Usage

If you delete a key, the cfregistry tag also deletes values and subkeys defined beneath it.
Example


cfregistry action = "delete"

© 2014 Adobe Systems Incorporated. All rights reserved.

1064

Adobe ColdFusion Documentation

cfreport
Description

Used to do either of the following:
Execute a report created with the ColdFusion Report Builder, displaying it in PDF, Adobe FlashPaper, RTF,
HTML, XML or Excel format. Optionally, you can save this report to a file.
Run a predefined Crystal Reports report. Applies only to Windows systems.
Category

Data output tags
Syntax

ColdFusion Report Builder syntax:



Crystal Reports syntax:



Note
You can specify this tag's attributes in an attributeCollection attribute whose value is a
structure. Specify the structure name in the attributeCollection attribute and use the tag's
attribute names as structure keys.

See also

cfcollection, cfdocument, cfdocumentitem, cfdocumentsection, cfexecute, cfindex, cfobject, cf

© 2014 Adobe Systems Incorporated. All rights reserved.

1065

Adobe ColdFusion Documentation

reportparam, cfsearch, cfwddx; Creating Reports with Report Builder in the Developing ColdFusion
Applications; Report Builder online Help
History

ColdFusion 8: Added the style and resourceTimespan attributes. Added the HTML and XML values to the form
at attribute.ColdFusion MX 7.0.1: Added the RTF value to the format attribute, to let you generate reports in RTF
format.ColdFusion MX 7: Added support for the ColdFusion Report Builder.ColdFusion MX: Changed data source
connection behavior: Crystal Reports now establishes an independent connection to the data source. The
connection is not subject to any ColdFusion data source-specific restrictions. For example, the Crystal Reports
server can access a data source, regardless of whether it is disabled in the ColdFusion Administrator.
Attributes

Attribute

Applies to

Req/Opt

datasource

Crystal Reports

Optional

encryption

Report Builder

Optional

Default

Description
Name of registered
or native data
source.

none

(format="PDF" onl
y) Type of
encryption for the
report output. Valid
values are:
128-bit
40-bit
none

© 2014 Adobe Systems Incorporated. All rights reserved.

1066

Adobe ColdFusion Documentation

filename

Report Builder

© 2014 Adobe Systems Incorporated. All rights reserved.

Optional

Filename to contain
the report. You
cannot specify both
the name and file
name attributes. The
filename extension
must match the
value of the format
attribute.
If you write report
output to an HTML
file, ColdFusion
automatically
creates a directory
relative to the output
file in the format fi
lename_files. Also,
it generates PNG
files for any charts in
the report and
copies of any image
files imported into
the report and
stores them in this
directory.

1067

Adobe ColdFusion Documentation

format

Report Builder

Required

Format of the report
output:
PDF
FlashPaper
Excel
RTF
XML
HTML
When you write
report output
directly to the
browser in HTML
format,
ColdFusion
generates a
temporary
directory and files
for the images in
the report. The
location of the
temporary
directory that
contains the
image files
is:C:\ColdFusion9
\tmpCache\CFFile
Servlet_cfreport_r
eport_unique_ide
ntifier_To
determine when
the images are
removed from the
browser, use the
resourceTimes
pan attribute.

© 2014 Adobe Systems Incorporated. All rights reserved.

1068

Adobe ColdFusion Documentation

formula

Crystal Reports

Optional

One or more named
formulas. Terminate
each formula with a
semicolon. Use the
format:

formu
la =
"form
ulana
me1 =
'form
ula1'
;form
ulana
me2 =
'form
ula2'
;"

If you use a
semicolon in a
formula, escape it
by typing it twice
(\;;). For example:

formu
la =
"Name
1 =
'Val_
1a;;V
al_1b
';Nam
e2 =
'Val2
';"

name

Report Builder

© 2014 Adobe Systems Incorporated. All rights reserved.

Optional

Name of the
ColdFusion variable
that contains the
report output. You
cannot specify both
name and filenam
e. This attribute is
not valid when form
at="HTML".

1069

Adobe ColdFusion Documentation

orderBy

Crystal Reports

Optional

overwrite

Report Builder

Optional

Orders results
according to your
specifications.
no

Specifies whether to
overwrite files that
have the same
name as that
specified in the fil
ename attribute:
yes
no

ownerPassword

Report Builder

Optional

(format="PDF" onl
y) Owner password
for the report,

password

Crystal Reports

Optional

Password that
corresponds to
username required
for database
access. Overrides
default settings for
data source in the
ColdFusion
Administrator.

permissions

Report Builder

Optional

(format="PDF" onl
y) Specifies one or
more of the
following
permissions:
AllowPrinting
AllowModifyCo
ntents
AllowCopy
AllowModifyAn
notations
AllowFillIn
AllowScreenRe
aders
AllowAssembly
AllowDegraded
Printing
Separate multiple
permissions with
commas.

© 2014 Adobe Systems Incorporated. All rights reserved.

1070

Adobe ColdFusion Documentation

query

ReportBuilder

Optional

Name of the query
that contains input
data for the report.
This query overrides
the query in the
Report Builder
report. The
ColdFusion query
must contain at least
all of the columns
included in the
Report Builder
query; however, the
WHERE clause can
differ. If you omit
this parameter,
Report Builder uses
the data from the
internal SQL
statement or from c
freportparam ite
ms.

report

Crystal Reports

Required

Report pathname.
Store Crystal
Reports files in the
same directories as
ColdFusion page
files.

© 2014 Adobe Systems Incorporated. All rights reserved.

1071

Adobe ColdFusion Documentation

resourceTimespa
n

Report Builder

© 2014 Adobe Systems Incorporated. All rights reserved.

Optional

5 minutes

(format="HTML" o
nly) Life span of the
resource directory.
When you export a
Report Builder
report in HTML
format, ColdFusion
writes any images or
other resource files
in the report to a
temporary resource
directory. Use this
attribute to
determine when the
resource directory is
deleted. For the
value, use the Crea
teTimeSpan functi
on and specify the
time span in days,
hours, minutes, and
seconds, separated
by commas; for
example, to delete
the resource
directory after one
hour, specify: #Cre
ateTimeSpan(0,1
,0,0)#}}If the
value is set to
0, the resource
directory
persists until
the next server
restart.ColdFus
ion deletes the
resource
directory only
when
{{format="HTML"
and neither the
name nor filename
attribute is specified.
The default setting
is 5 minutes: #Crea
teTimeSpan(0,0,
5,0)#

1072

Adobe ColdFusion Documentation

style

ReportBuilder

Optional

Style in CSS format
that overrides a
style defined in the
Report Builder
report at run time.
You can specify an
absolute file path, a
file path relative to
the report, or a
string in valid CSS
format.
For the styles to
take effect, the style
names must match
Style Name
attributes assigned
to elements in the
Report Builder
report. You can
generate a CSS file
in Report Builder
and export it or you
can create a CSS
file with a text editor.
For a list of
supported CSS
styles, see the
section Style
properties.

template

Report Builder

Required

Specifies the
pathname to the
Report Builder
(CFR) file, relative to
the web root.

timeout

Crystal Reports

Optional

Specifies the
maximum time, in
seconds, in which a
connection must be
made to a Crystal
Reports file.

type

Crystal Reports

Optional

standard

Type of report:
standard (not
valid for Crystal
Reports 8.0)
netscape
microsoft

© 2014 Adobe Systems Incorporated. All rights reserved.

1073

Adobe ColdFusion Documentation

userName

Crystal Reports

Optional

Username required
for entry into a
database from
which the report is
created. Overrides
default settings for
data source in
ColdFusion
Administrator.

userPassword

Report Builder

Optional

(format="PDF" onl
y) User password.

Usage

Use this tag to generate a report using a report definition created in either ColdFusion Report Builder or in Crystal
Reports. (For more information on using the ColdFusion Report Builder, display the online help by opening the
Report Builder and pressing F1.)
Note
The Excel report output format type provides limited support for the formatting options available
in ColdFusion Reporting. Images and charts are not supported and numeric data containing
formatting (commas, percents, currency, and so on) appear as plain text in Excel. The Excel
output format supports simple reports only and Adobe recommends that you give careful design
and layout consideration to reports designed for Excel output.

This tag requires an end tag.
Using Cascading Style Sheets

You can override Cascading Style Sheets (CSS) in Report Builder reports at run time by using the style attribute
of the cfreport tag in ColdFusion.
You can create CSS files in one of two ways: by exporting styles with the Export Report Styles icon in Report Builder
or by creating a CSS file in any text editor. For the CSS styles to take effect, however, you must use Report Builder
to assign the style names to the elements in the report. (The exception is the default style: you can use the style at
tribute to define the default style in ColdFusion and apply it to the report even if the default style is not defined in
Report Builder.)After you assign the style names in Report Builder, you can update the style definitions in the CSS
file at any time and apply them at run time by using the cfreport and cfreportparam tags. If your report
contains subreports, the default style applies to the master report and to all of the subreports. If the master report
uses CSS styles other than the default style, the CSS styles do not apply to the subreports unless you specify them
explicitly.
The following code shows how to apply three different style sheets to the main report and two subreports at run
time:






© 2014 Adobe Systems Incorporated. All rights reserved.

1074

Adobe ColdFusion Documentation

The following code shows how to apply a CSS style as a value of the style attribute:




The following code shows how to create a variable called myStyle and use it as a value of the style attribute:





Style attribute syntax

The style file or string must be valid CSS syntax. For more information, see http://www.w3.org/Style/CSS/. The style
must contain one or more rule sets. Each rule set consists of a simple selector, which is the Report Builder style
name, followed by a declaration block, which consists of a series of declarations separated by semicolons. A
declaration is a property:value pair.
If a selector contains invalid syntax, ColdFusion ignores the selector and its declaration block. Selectors and
properties not supported by this feature are ignored. Styles are case-insensitive, except parts not under the control
of CSS (such as font names).
The following example shows the CSS definition for the default style:

DefaultStyle
{
default-style: true;
color: black;
font-family: Arial, "Comic Sans MS";
font-size: 16;
text-decoration: underline;
}

The following example shows the CSS definition for a custom style called PurpleBoldItalicText:

PurpleBoldItalicText
{
color: purple;
font: italic bold 20px 30px Arial;
}

Identifiers for styles must be CSS2-compliant. For example, CSS1 allows '_' in identifiers, but CSS2 does not.
In CSS2, identifiers, including element names, classes, and IDs in selectors, can contain only the characters A-Z,
a-z, and 0-9. Also, they can include ISO 10646 characters 161 and higher and the hyphen character (-); however,
identifiers cannot start with a hyphen or a digit. They can contain escaped characters and any ISO 10646 character
as a numeric code. For example, you can write the identifier "B&W?" as "B\&W?" or "B\26 W\3F".

© 2014 Adobe Systems Incorporated. All rights reserved.

1075

Adobe ColdFusion Documentation
Style properties

The following table shows the style properties exported by Report Builder:
Property name

Report Builder only

Valid values

Description

background-color

No

See the section Valid
color values

Background color of the
specified report element, if
the element is not
transparent. The default
background color is white.

border

No

border-width
border-style
border-color

A shorthand property that
specifies the border-wi
dth, border-style,
and border-color prop
erties for all of the borders
in an element.

border-color

No

See the section Valid
color values

Border color for text,
images, and charts. You
can customize each side
of the border. The default
color is white.

border-style

No

solid
dashed
none

A shorthand property that
specifies the border-to
p-style, border-righ
t-style, border-bott
om-style, and borderleft-style (the
comma-separated values
must be in this order). If
one or more values are
not specified, the value for
the opposite side is used.
If only one value is listed,
that value applies to all
sides.
The none value overrides
the border-width value
. Any other values,
including hidden, dotte
d, groove, ridge, inse
t, outset, and double,
are displayed as solid.

© 2014 Adobe Systems Incorporated. All rights reserved.

1076

Adobe ColdFusion Documentation

border-top-colorborder-left
-colorborder-bottom-color
border-right-color

No

See the section Valid
color values

Color of the element's top,
left, bottom, and right
border. For more details
see that section Border
and margin styles.
If no border-color prop
erty is specified, the value
of the color property is
used instead.

border-top-styleborder-left
-styleborder-bottom-styleb
order-right-style

No

solid
dashed

Line style of the element's
top, left, bottom, and right
border. For more details
see the section Border
and margin styles.Any
value other than dashed
displays as solid.

border-top-widthborder-lef
t-widthborder-bottom-widt
hborder-right-width

No

thin
medium
thick
1px
2px
4px

Thickness of the top, left,
bottom, and right border
of an element. Negative
values are not valid. For
more details see the
section Border and margin
styles:
thin = 1/2 pt
medium = 2px
thick = 4px

border-width

No

thin
medium
thick
1px
2px
4px

A shorthand property that
specifies the border-to
p-width, border-righ
t-width, and border-b
ottom-width properties
with a single property and
value notation (the
comma-separated values
must be in this order). If
one or more values are
not specified, the value for
the opposite side is used.
If only one value is listed,
it applies to all sides:
thin = 1/2 pt**
medium = 2px
thick = 4px

© 2014 Adobe Systems Incorporated. All rights reserved.

1077

Adobe ColdFusion Documentation

clip

No

auto
stretch
ratio

Specifies how images are
resized:
auto: If the dimensions
of the source image
differ from the element
in the report, this
attribute crops the
image to fit within the
element boundaries.
The image is not
resized. Only the part of
the image that fits in the
boundaries is displayed.
stretch: If the
dimensions of the
source image differ
from the element in the
report, this attribute
resizes the image so
that it fits within the
element boundaries. If
the dimensions differ,
the image is distorted.
ratio: If the
dimensions of the
source image differ
from the element in the
report, this attribute
resizes the image to fit
within the element
boundaries but
maintains the aspect
ratio of the source so
that the image is not
distorted.

color

No

See the section Valid
color values

Color of the text (in text
elements) and the border
(in graphic elements). The
default color is black.

corner-radius

Yes

integer

Radius for arcs used to
draw the corner of
rectangles. The default is
0 (square corners).
Values less than 0 are
interpreted as 0.

© 2014 Adobe Systems Incorporated. All rights reserved.

1078

Adobe ColdFusion Documentation

default-style

Yes

true
false

Default style for elements
that do not or cannot have
a style applied. A
subreport inherits its
parent's default-style if it
does not have one of its
own.

embed-pdf-font

Yes

true
false

Specifies whether fonts
are embedded in the PDF
document. Embedded
fonts insure that the fonts
display properly even if
the font is not installed on
the system where the
report is viewed.

empty-cells

No

show
hide

Shows or hides a null
value for text expressions:
show: If the text
expression returns a
null value, the string
"null" is displayed.
hide: If the text
expression returns a
null value, the null value
is replaced with an
empty string. This is the
default.

font

No

© 2014 Adobe Systems Incorporated. All rights reserved.

font-style
font-weight
font-size
line-height
font-family

Font characteristic
specifications. Use this as
a shorthand to specifying
multiple property values;
for example:font:
italic 20px Arial;D
efault values for this
property match those
used for the individual
properties. Default values
for the individual
properties are applied to
the values omitted from
the font property.

1079

Adobe ColdFusion Documentation

font-family

No

Comma-separated list of
font names.

Group of fonts to apply to
the element. The first font
found in the list is applied
to the element. The
default is:font-family:
Arial, Helvetica,
sansserif;If a font
name contains spaces,
enclose the name in
quotation marks, for
example:font-family:
Courier, "Courier
New", Arial;

font-size

No

[length]

Font size measured in
points or pixels. Negative
values are not valid. The
default value is 10 points.
You can specify points or
pixels. 1 pixel = 0.75.
points. This property also
is a component of the font
property.Standard CSS
supports other types of
values not supported by
Report Builder.

font-style

No

normal
italic
oblique

Font style. The italic a
nd oblique values are
similar. The default value
is normal. Also, this
property is a component
of the font property.

font-weight

No

normal
bold
bolder
lighter
100
200
300
400
500
600
700
800
900

Font weight. Report
Builder does not support
varying degrees of
boldness or lightness;
therefore, normal and li
ghter appear as normal
; all other values appear
as bold. The default is n
ormal. Also, this property
is a component of the fon
t property.

© 2014 Adobe Systems Incorporated. All rights reserved.

1080

Adobe ColdFusion Documentation

line-height

line-size

No

Yes

© 2014 Adobe Systems Incorporated. All rights reserved.

normal
number
length
percentage

Amount of space between
consecutive lines of text:

none
thin
1px
2px
4px
dashed

Type of the border around
a graphic element or the
type and the thickness of
line elements. By default,
lines and rectangles have
a 1-pixel border; thin is
0.05 pixels.

normal: Sets the
line-height to
single-spacing (default).
number: A multiplier
that determines the line
height as a factor of the
element's font size. To
determine the line
height from this
number, multiply the
current element
font-size by the number.
Negative values are not
valid.
length: Sets the line
height to an explicit
length. You can specify
points (for example,
"20") or pixels (for
example, "20px"). 1
pixel = 0.75 points.
Negative values are not
valid. Standard CSS
allows other units of
length not supported by
Report Builder.
percentage: Defines
the line-height as a
percentage. The
percent symbol is
required (for example,
150%). Negative values
are invalid.

1081

Adobe ColdFusion Documentation

margin

No

top-integer
[right-integer]
[bottom-integer]
[left-integer]

Amount of blank space
within the bounding box of
an element. This is a
shorthand property that
specifies the margin-to
p, margin-right, marg
in-bottom, and margin
-left properties with a
single property and value
notation (the values must
be in this order separated
by commas.) If one or
more values are not
specified, the value for the
opposite side is used. If
only one value is listed, it
applies to all sides. For
more details see the
section Border and margin
styles.CSS margins are
transparent, which reveals
the background of the
parent element. Negative
values are valid; this
allows for text
overlays.Examples:margi
n: 10,20,30,40; marg
in: 10; margin:
10,20,30;

margin-topmargin-leftmar
gin-bottommargin-right

No

integer

See margin.

parent-style

Yes

styleName

Name of the parent report
style from which this style
inherits some or all of its
properties. The style
name must be defined in
either the report or before
this style definition in the
CSS file or text.

text-align

No

left
center
right
justify

Alignment of text and
images on the horizontal
axis. The default value is
left.

© 2014 Adobe Systems Incorporated. All rights reserved.

1082

Adobe ColdFusion Documentation

text-decoration

No

underline
line-through
underline
line-through

Text characteristics not
defined with the font-st
yle and font-weight p
roperties. The color of the
text-decoration is
determined by the color
property for the element.
Unknown values are
ignored.

text-rotation

Yes

none
left
right

Rotation of text elements.
Use it to change the text
direction by rotating it 90
degrees to the right or left.

transparency-mode

Yes

opaque
transparent

Transparency of
elements. Graphic
elements, such as
rectangles and lines, are
opaque by default, but
images are transparent.
Subreport elements, static
text, and text fields are
transparent by default.

vertical-align

No

top
middle
bottom

Alignment of text and
images on the vertical
axis. The default value is
top.

© 2014 Adobe Systems Incorporated. All rights reserved.

1083

Adobe ColdFusion Documentation

xhtml-formatted-text

Yes

true
false

Specifies whether the text
element contains
XHTML-compatible
instructions:
true: The text element
contains
xhtml-compatible
instructions, for
example, My Text
Label. In this
example, the text within
the tags displays in bold
(My Text Label), and
the tags ( ) are
not displayed.
false: The text
element does not
contain
xhtml-compatible
instructions; therefore,
all the text within the
text element is
displayed. This is the
default.

Styles or values that are not supported by Report Builder are ignored in the report, in which case, if a default-style is
defined, Report Builder applies the default style to the element.
Valid color values

You can specify a color as #RRGGBB. This represents a color that uses a triplet of hexadecimal values
concatenated together. The values represent the red, green, and blue components for a given color. The range of
each component value is 00-FF in hexadecimal. Also, you can use one of the 140 X11 color names (see http://www.
blooberry.com/indexdot/color/x11makerFrameNS.htm). The color name is case-insensitive. This set of names
assigns names to specific RGB values. Also, a color name can also be specified as ##RGB, rgb(r,g,b), or
rgb(r%,g%,b%). See CSS Color Units for syntax details (see http://www.blooberry.com/indexdot/css/syntax/units/col
or.htm). UI Name is not supported.
The following example shows the different ways you can represent the color lime:

color:lime
color:#00FF00
color:#0F0
color:rgb(0,255,0)
color:rgb(0%,50%,0%)

If you specify a color in hexadecimal format as part of the style attribute for the cfreport tag, use the format ##0
0FF00. For example:

© 2014 Adobe Systems Incorporated. All rights reserved.

1084

Adobe ColdFusion Documentation



Border and margin styles

Use the border-width, border-style, border-color, and margin properties when all four sides of the
element have the same value. You can specify from one to four parameters for these properties:
Number of parameters

Example

Result

1

border-width: thick

Parameter applied to all four sides
of the element's border.

2

border-width: thick, thin

First parameter (thick) applied to
the top and bottom sides; second
parameter (thin) applied to the left
and right sides.

3

border-width: thick, thin, medium

First parameter (thick) applied to
the top; second parameter (thin)
applied to the left and right sides;
third parameter (medium) applied to
the bottom.

4

border-width: thick, thin, medium,
thick

First parameter (thick) applied to
the top; second parameter (thin)
applied to the right side; third
parameter (medium) applied to the
bottom; fourth parameter (thick)
applied to the left side.

You can use the properties for each side of a border to override the style specified by the border-width, border
-style, border-color, and margin properties.
Example

Example 1: This example shows the use of cfreport for the ColdFusion Report Builder.


SELECT EmployeeID, LastName, FirstName, Title, City, Region, Country
FROM Employees
ORDER BY Country, City



© 2014 Adobe Systems Incorporated. All rights reserved.

1085

Adobe ColdFusion Documentation

Example 2: This view-only example shows the use of cfreport for Crystal Reports.

cfreport Tag

cfreport lets reports from the Crystal Reports Professional report writer display
through a ColdFusion interface. To run, the tag requires the name of the report.
cfreport can also pass information to the report file displayed, to change the
output conditions.
This example would run a report called "monthlysales.rpt " and pass it an
optional filter condition to show only the information for a subset
of the report.

{Departments.Department} = 'International'

Substitute your report files and filters for this code. cfreport can put Crystal
Reports into web pages.

© 2014 Adobe Systems Incorporated. All rights reserved.

1086

Adobe ColdFusion Documentation

cfreportparam
Description

The cfreportparam tag lets you perform the following tasks:
Pass input parameters to a ColdFusion Report Builder report definition.
Override query data in subreports and charts defined in Report Builder reports.
Override styles defined in Report Builder subreports.
The cfreportparam tag is always a child tag of the cfreport tag.
Category

Data output tags
Syntax





Note
You can specify this tag's attributes in an attributeCollection attribute whose value is a
structure. Specify the structure name in the attributeCollection attribute and use the tag's
attribute names as structure keys.

See also

cfreport; Creating Reports with Report Builder in the Developing ColdFusion Applications; Report Builder online
Help
History

ColdFusion 8: Added the chart, query, series, subreport, and style attributes.
ColdFusion MX 7: Added this tag.
Attributes

Attribute

Req/Opt

© 2014 Adobe Systems Incorporated. All rights reserved.

Default

Description

1087

Adobe ColdFusion Documentation

chart

Optional

Name of the chart
contained in a report or
subreport. The value of
this attribute must match
Name property of a chart
defined in the Report
Builder report. If you
specify the chart attribut
e, you cannot specify the
subreport or name attri
bute.

name

Optional

Variable name for data
that is passed. The value
of this attribute must
match the name of an
input parameter defined in
the Report Builder report.
If you specify the name att
ribute, you cannot specify
the chart or subreport
attribute.

query

Optional

Query value to pass to a
subreport or chart. The
ColdFusion query must
contain at least all of the
columns included in the
Report Builder query.
Charts and subreports
require this attribute.

series

Optional

subreport

Optional

© 2014 Adobe Systems Incorporated. All rights reserved.

1

Ordinal number of a chart
series to use for the
query. This attribute is
valid only when the char
t attribute is specified.
Name of the subreport.
The value of this attribute
must match the Name
property of the subreport
in Report Builder.
Subreport names within a
report must be unique. If
you specify the subrepo
rt attribute, you cannot
specify the chart or nam
e attribute.

1088

Adobe ColdFusion Documentation

style

Optional

Style in CSS format for a
subreport. The value can
be an absolute file path, a
file path relative to the
report, or a string in valid
CSS format. For the styles
to take effect, the style
names must match Style
Name attributes assigned
to elements in the Report
Builder report. You can
generate the CSS file in
Report Builder and
exported or created with a
text editor. For a list of
supported CSS styles,
see the section Style
properties.

value

Optional (see Description)

Value of the data that is
sent. Specify the value a
ttribute with the name attri
bute. You cannot specify
this attribute when a char
t or subreport attribute
is specified. The value
can be a string or a
variable.

Usage

You can specify only one of the following attributes in a cfreportparam tag:
name
subreport
chart
You can use the query, subreport, and chart attributes to override Report Builder queries and chart
information at run time. This way you can customize subreport and chart data from the CFM page without
having to change the queries built into your report.
For example, in Report Builder, you can create a master report that contains several subreports and populate
each subreport with a different query. Instead of modifying the queries in Report Builder, you can customize
your reports by creating modified queries on the ColdFusion calling page. The ColdFusion query must contain
at least all of the columns included in the Report Builder query.
Note
You cannot specify a subreport query that depends on arguments from the master report.
Instead, you can define a CFML function or CFC method that returns the subreport query
given the arguments from the master report. ColdFusion calls this code when it executes
the subreport.

On the calling CFM page, you can specify a cfreportparam tag for any subreport and chart in the Report

© 2014 Adobe Systems Incorporated. All rights reserved.

1089

Adobe ColdFusion Documentation

Builder report. The value of the subreport or chartattribute must match the Name property of the
subreport or chart defined in the Report Builder report. (Charts are treated like subreports.)The following code
shows a master report that contains two subreports and a chart with two chart series:









The cfreportparam tag also lets you override CSS styles assigned to subreports in Report Builder. Use the
style attribute with the subreport attribute; the value of the subreportattribute must match the name of
the subreport in Report Builder. The following code applies a style sheet to the master report and two
different style sheets to the subreports:






For more information, see the section Using Cascading Style Sheets.
Example



SELECT Departments.Dept_ID as dDept_ID, Departments.Dept_Name,
CourseList.Course_ID, CourseList.Dept_ID as cDept_ID,
CourseList.CorNumber, CourseList.CorName,
CourseList.CorLevel
FROM Departments, CourseList
WHERE Departments.Dept_ID = CourseList.Dept_ID
ORDER BY CourseList.Dept_ID





© 2014 Adobe Systems Incorporated. All rights reserved.

1090

Adobe ColdFusion Documentation

cfrethrow
Description

Rethrows the currently active exception. Preserves the exception's cfcatch.type and cfcatch.tagContext vari
able values.
Category

Exception handling tags, Extensibility tags
Syntax



See also

cferror, cfthrow, cftry; Handling runtime exceptions with ColdFusion tags in the Developing ColdFusion
Applications
Usage

Use this tag within a cfcatch block. This tag is useful in error handling code, if the error handler cannot handle an
error that it catches. For example, if cfcatch type = "any" gets a DATABASE exception, and the code is
designed to handle only CFX exceptions, the handler raises the exceptions again, with details intact, so that a
higher-level handler can process the error information. If you used the cfthrow tag, the type and details of the
original exception would be lost.
Example

© 2014 Adobe Systems Incorporated. All rights reserved.

1091

Adobe ColdFusion Documentation

cfrethrow Example




SELECT*
FROM Messages









Sorry, this request can't be completed
Catch variables




#c# = #cfcatch[c]#






© 2014 Adobe Systems Incorporated. All rights reserved.

1092

Adobe ColdFusion Documentation

cfreturn
Description

Returns result values from a component method. Contains an expression returned as result of the function.
Return value

An expression; the result of the function from which this tag is called.
Category

Extensibility tags
Syntax



See also

cfargument, cfcomponent, cffunction, cfinvoke, cfinvokeargument, cfobject, cfproperty; Building
and Using ColdFusion Components in the Developing ColdFusion Applications
History

ColdFusion MX: Added this tag.
Attributes

Attribute

Req/Opt

expr

Required

Default

Description
Function result; value of
any type.

Usage

This tag is equivalent to a return statement within a cfscript tag. It accepts one return variable argument. To
return more than one value, populate a structure with name-value-pairs, and return the structure with this tag.
To access the result value from this tag, you use the variable scope that is the value of the cfinvoke tag returnV
ariable attribute.
You can code a maximum of one cfreturn tag within a function.
For example code, see Building and Using ColdFusion Components in the Developing ColdFusion Applications.
Example

© 2014 Adobe Systems Incorporated. All rights reserved.

1093

Adobe ColdFusion Documentation




SELECT FIRSTNAME, LASTNAME, EMAIL
FROM tblEmployees





SELECT *
FROM tblDepartments





© 2014 Adobe Systems Incorporated. All rights reserved.

1094

Adobe ColdFusion Documentation

cfsavecontent
Description

Saves the generated content of the cfsavecontent tag, including the results of evaluating expressions and
executing custom tags, in the specified variable.
Category

Variable manipulation tags
Syntax


the content


Note
You can specify this tag's attributes in an attributeCollection attribute whose value is a
structure. Specify the structure name in the attributeCollection attribute and use the tag's
attribute names as structure keys.

See also

Caching parts of ColdFusion pages in Optimizing ColdFusion applications in the Developing ColdFusion
Applications
Attributes

Attribute

Req/Opt

variable

Required

Default

Description
Name of the variable in
which to save the
generated content of the
tag.

Usage

This tag requires an end tag.
You cannot use this tag to suppress output from a tag library.
Example

The following example uses a custom tag to generate a report and saves the report in the variable CONTENT. It
replaces all instances of the word "report" with the phrase "MyCompany Quarterly Report" and outputs the result.

© 2014 Adobe Systems Incorporated. All rights reserved.

1095

Adobe ColdFusion Documentation





#replace(content, "report", "MyCompany Quarterly Report", "all")#


© 2014 Adobe Systems Incorporated. All rights reserved.

1096

Adobe ColdFusion Documentation

cfschedule
Description

Provides a programmatic interface to the ColdFusion scheduling engine. Can run a CFML page at scheduled
intervals, with the option to write the page output to a static HTML page. This feature enables you to schedule pages
that publish data, such as reports, without waiting while a database transaction is performed to populate the page.
ColdFusion does not invoke Application.cfc methods, when invoking a task's event handler methods.
Category

Variable manipulation tags; Using Scheduler
Syntax


group="group1"
oncomplete="how to handle exception"
eventhandler="path_to_event_handler"
onException="refire|pause|invokeHandler"
cronTime="time"
repeat="number"
priority="integer"
exclude="date|date_range|comma-separated_dates"
onMisfire = ""
cluster="yes|no
mode="server|application"
retryCount="number"
OR


© 2014 Adobe Systems Incorporated. All rights reserved.

1097

Adobe ColdFusion Documentation

OR

OR

OR

OR


Note
You can specify this tag's attributes in an attributeCollection attribute whose value is a
structure. Specify the structure name in the attributeCollection attribute and use the tag's
attribute names as structure keys.

See also

cfcookie, cfparam, cfregistry, cfsavecontent, cfset
History

ColdFusion 10: Added the actions list, pauseall, and resumeall. Also, added the attributes group, onCompl
ete, eventHandler, onException, cronTime, repeat, result, priority, exclude, onMisfire, clust
er, mode, isDaily, overwrite, and retryCount.
ColdFusion MX 6.1: Changed the way intervals are calculated. The day length now reflects changes between
standard and daylight saving times. The month length is now the calendar month length, not four weeks. The
scheduler handles leap years correctly.
Attributes

Attribute

Req/Opt

action

Required

© 2014 Adobe Systems Incorporated. All rights reserved.

Default

Description
delete: Deletes the
specified task.
update: Updates an
existing task or creates
a task, if one with the
name specified by the t
ask attribute does not
exist.
run: Executes the
specified task.
pause: Pauses the
specified task.
resume: Continues
executing the specified
task.
list: Lists all the
scheduled tasks.
pauseAll: Pauses all
scheduled tasks for a
particular application.
resumeAll: Resumes
all scheduled tasks for a
particular application.

1099

Adobe ColdFusion Documentation

task

Required

Name of the task.

endDate

Optional

Date when scheduled task
ends. The default date
format is mm/dd/yy.

endTime

Optional

Time when scheduled
task ends (seconds).

file

Required if publish = "Y
es"

Name of the file in which
to store the published
output of the scheduled
task. The file can only
have a .txt or .log
extension by default. You
can add more extensions
in cfusion\lib\neo-cron
xml.
Interval at which task is
scheduled:

interval

number of seconds
once
daily
weekly
monthly
operation

Optional

HTTPRequest

overwrite

true

If false, results in the
creation of new output
files every time the task
executes. If true, instead
of creating new
outputfiles, the existing
one is overwritten.

password

Optional

Password, if URL is
protected.

path

Required if publish =
"Yes"

Path to the directory in
which to put the published
file.

© 2014 Adobe Systems Incorporated. All rights reserved.

Operation that the
scheduler performs.

1100

Adobe ColdFusion Documentation

port

Optional

proxyPassword

Opt

proxyPort

Optional

proxyServer

Optional

Host name or IP address
of a proxy server.

proxyUser

Opt

User name to provide to
the proxy server.

publish

Optional

requestTimeOut

Optional

resolveURL

Optional

result

Required for the list
action.

80

Port to use on the server
that is specified by the ur
l parameter. If resolveU
RL = "yes", retrieved
document URLs that
specify a port number are
automatically resolved, to
preserve links in the
retrieved document. A
port value in the url attrib
ute overrides this value.
Password to provide to
the proxy server.

80

no

Port number to use on the
proxy server.

yes: saves the result to
a file.
no
Can be used to extend the
default time-out period.

no

yes: resolves links in
the output page to
absolute references.
no
Name for the query in
which cfschedule returns
the result variables.

startDate

Date on which to first run
the scheduled task. The
default date format is
mm/dd/yy.

startTime

Time at which to run the
scheduled task.

url

Required if action = "up
date"

© 2014 Adobe Systems Incorporated. All rights reserved.

URL of the page to
execute.

1101

Adobe ColdFusion Documentation

username

Optional

User name, if URL is
protected.

group

Optional

default

The group to which the
scheduled task belongs.

onComplete

Optional

invokeHandler

The action to be
performed after the
completion of current task.
Used when chaining
scheduled tasks. For
details, see Using
Scheduler.

eventHandler

Optional

onException

Optional

A CFC file whose
pre-defined methods are
invoked for various events
while running the task.
The CFC must be
implementing
ITaskEventhandlerThe
path you specify must be
relative to webroot. For
example, schedulerdem
o.eventhandler.
invokeHandler, if
eventHandler is specified

Specify what to do if a
task results in error. If
unspecified, then no
action is taken. The
options are:
refire: Tries to run
the task immediately.
pause: Stops the task
from executing further.
invokeHandler: Invo
kes onError method
of the eventhandler as
defined by the user.

cronTime

Optional

repeat

Optional

-1

The number of times a
task has to be repeated.

priority

Optional

5

An integer that indicates
the priority.

© 2014 Adobe Systems Incorporated. All rights reserved.

Specifying task
scheduling time in cron
job syntax.

1102

Adobe ColdFusion Documentation

exclude

Optional

onMisfire

Optional

Comma-separated list of
dates or date range for
exclusion in the schedule
period.
invokeHandler if
eventHandler is specified

Specify what to do if a
task misfires. If
unspecified, then no
action is taken. The
options are:
fire_now: Tries to run
the task immediately.
invokeHandler: Invokes
onMisfire method of the
event handler as
defined by the user.

cluster

Optional

no

If yes, the task can be
executed in cluster setup.

mode

Optional

server

If the task is
server-specific or
application specific.

retryCount

Optional

3

The number of reattempts
if the task fails. The value
must be greater than or
equal to 0 and less than
or equal to 3.

Note: ColdFusion does not invoke Application.cfc methods, when invoking a task's event handler
methods.
Usage

This tag and the ColdFusion Administrator Scheduled task page schedule ColdFusion tasks. Tasks that you add or
change using this tag are visible in the Administrator. You can disable this tag in the Administrator
Sandbox/Resource security page. This tag's success or failure status is written to the schedule.log file in the cf_root/
cfusion/logs directory (or the logs directory of another instance you may have created with the ColdFusion
Enterprise Instance Manager).
When you create a task, you specify the URL of the ColdFusion page to execute, the date, time and frequency of
execution, and whether to publish the task output to an HTML file. If the output is published, you specify the output
file path and file.
If you schedule a job to run monthly on any date in the range 28-31, the scheduler does the following:
If you schedule a monthly job to run on the last day of a month, the scheduled job will run on the last day of
each month. For example, if you schedule a monthly job to start on January 31, it will run on January 31,
February 28 or 29, March 31, April 30, and so on.
If you schedule a monthly job to run on the 29th or 30th of the month, the job will run on the specified day of

© 2014 Adobe Systems Incorporated. All rights reserved.

1103

Adobe ColdFusion Documentation

each month for 30 or 31-day months, and the last day of February. For example, if you schedule a monthly
job to start on January 30, the job will run on January 30, February 28 or 29, March 30, April 30, and so on.
If you schedule a job to run once, the starting time is in the past, and the task has not yet run, it runs
immediately. If you schedule a recurring job with a start time in the past, ColdFusion schedules the job to run
on the next closest interval in the future.
The Scheduler configuration file, cf_root\lib\neo-cron.xml contains all scheduled events, as individual entries
(except the clustered tasks).
Example

cfschedule Example



© 2014 Adobe Systems Incorporated. All rights reserved.

1104

Adobe ColdFusion Documentation

cfscript
Description
Category
Syntax
See also
History
Usage
Keywords
Exception handling with the cfscript tag
Invoking ColdFusion components with the cfscript tag
Consuming web services with the cfscript tag
Script support for tags
Using custom tags in scripts
Example
Description

Encloses a code block that contains cfscript statements.
Category

Application framework tags, Other tags
Syntax


cfscript code here


See also

cfinvoke, cfmessagebox, CreateObject; Extending ColdFusion Pages with CFML Scripting in the
Developing ColdFusion Applications
History

ColdFusion 11: Enhanced support like usage of custom tags.
ColdFusion MX:
Changed how to invoke component methods: this tag can now invoke component methods, using the Creat
eObject function
Changed use of reserved words: you cannot use ColdFusion reserved words within this tag
Added the try and catch statements.
Usage

Performs processing in CFScript. This tag uses ColdFusion functions, expressions, and operators. You can read
and write ColdFusion variables within this tag. For a detailed description of the CFScript scripting language,

© 2014 Adobe Systems Incorporated. All rights reserved.

1105

Adobe ColdFusion Documentation

including documentation of CFScript statements and the CFScript equivalents of CFML tags, see Extending
ColdFusion Pages with CFML Scripting in the Developing ColdFusion Applications.
You can use this tag to enclose a series of assignment statements that would otherwise require cfset statements.
If you code a cftry/cfcatch_ block within this tag using an exception's Java class name,
provide the fullyqualified class name._

You cannot use some ColdFusion reserved words in this tag. You cannot put a user-defined function whose name
begins with any of these strings within this tag:
cf
cf_
_cf
coldfusion
coldfusion_
_coldfusion
You cannot use the elseif construct within a cfscripttag. You can use code such as the following:

else if ( condition )
{
...
}

Keywords

The following words are now treated as keywords:
import
finally
component
interface
pageencoding
Exception handling with the cfscript tag

To handle exceptions with this tag, use try and catch statements, which are equivalent to the cftry and cfcatc
h tags. For each try statement, you must have a catch statement. In the catch block, the variable exceptionVa
riable contains the exception type. This variable is the equivalent of the cfcatch tag built-in variable cfcatch.T
ype. For more information, see Extending ColdFusion Pages with CFML Scripting in the Developing ColdFusion
Applications.
Invoking ColdFusion components with the cfscript tag

CFScript invokes component methods using the CreateObject function. The following example shows how to
invoke a component object with the cfscript tag, using ordered arguments:

© 2014 Adobe Systems Incorporated. All rights reserved.

1106

Adobe ColdFusion Documentation


quote = CreateObject( "component", "nasdaq.quote" ) ;

res = quote.getLastTradePrice( "macr" ) ;


The following example shows how to use an attribute collection within the cfscript tag to pass parameters when
invoking a component object. An attribute collection is a structure in which each key corresponds to a parameter
name and each value is the parameter value passed for the corresponding key.


stArgs = structNew();
stArgs.zipcode = "55987";

...

The temperature at zip code 55987 is #aTemp#

In this example, the structure is created in a cfscript block, but you can use any ColdFusion method to create the
structure.
Consuming web services with the cfscript tag

The following example shows how to consume a web service with the cfscript tag. You use the CreateObject f
unction to connect to the web service.


ws = CreateObject("webservice",
"http://www.xmethods.net/sd/2001/TemperatureService.wsdl");
xlatstring = ws.getTemp("55987");
writeoutput(xlatstring);


For more information, see Using Web Services in the Developing ColdFusion Applications.
Script support for tags
ColdFusion traditionally allowed you to build your applications using simple tags. ColdFusion 11 allows you to write
all the tags in the script format in a very generic manner. The format for the generic syntax is as follows:

© 2014 Adobe Systems Incorporated. All rights reserved.

1107

Adobe ColdFusion Documentation


cftag1 (att1=val1, att2=val2) // The parent tag
{
// First child tag having attributes in the parenthesis (Optional)
child_Tag1 (child_attr1='cv1', child_attr2='cv2')
{
// Nested child tag
child_childTag (child_child_attr1=ccv1, child_child_attr2=ccv2);
}
// Second child of parent tag
child_Tag2 (child2_attr1='cv1', child2_attr2='cv2');
}


Note that the attributes of a tag must be enclosed within a parenthesis and also the attributes must be
comma-separated.
Consider the following example:








You have been used to writing ColdFusion code as mentioned in the above example. To give you more control,
invoking tags inside the ColdFusion script block is now supported.
So, now you can write your code in the following manner:


cfform (name='myForm', acton='')
{
cfgrid (name="myGrid", query='userNameQuery')
{
cfgridcolumn (name='firstName', id='firstName', type='string');
cfgridcolumn (name='lastName', id='LastName', type='string');
}
}


© 2014 Adobe Systems Incorporated. All rights reserved.

1108

Adobe ColdFusion Documentation

The script support is not available for the following tags:

 (use writeOutput() instead)
 (use writeDump() instead)
 (use invoke() instead)

 (use createObject instead)
Using custom tags in scripts
Custom tags can also be used in  blocks just like normal ColdFusion tags. For instance,
If there is a custom tag named cf_happybirthday to generate a birthday message which is used in the tag syntax
like:



The same can be written in the script syntax as :

cf_happybirthday (name="Ted Cantor", birthDate="December 5, 1987");

Also, script support for cfimport-based prefix custom tag is supported. You can use prefix-based custom tag in script
blocks as follows:


cfimport(taglib=" ../importFolder/", prefix="myTags");
myTags:customTag();


In the above example, customTag is a CFM file under the importFolder directory.
Example

This simple example shows variable declaration and manipulation.




y = x;
z = 2 * y;
StringVar = form.myString;

 
twice #x# is #z#.
Your string value was: #StringVar# 


© 2014 Adobe Systems Incorporated. All rights reserved.

1109

Adobe ColdFusion Documentation

cfsearch
Description

Searches one or more Solr collections.A collection must be created and indexed before this tag can return search
results.A collection can be created in these ways:
With the cfcollection tag
In the ColdFusion Administrator
A collection can be indexed in the following ways:
In ColdFusion, with the cfindex tag
In the ColdFusion Administrator, which calls the cfindex tag
For more information, see Building a Search Interface in the Developing ColdFusion Applications.
Category

Extensibility tags
Syntax

cfsearch supports script style syntax:
new search().search(name="", collection="");

cfsearch supports script style syntax:


Note
You can specify this tag's attributes in an attributeCollection attribute whose value is a
structure. Specify the structure name in the attributeCollection attribute and use the tag's
attribute names as structure keys.

See also

© 2014 Adobe Systems Incorporated. All rights reserved.

1110

Adobe ColdFusion Documentation

cfcollection, cfexecute, cfindex, cfobject, cfreport, cfwddx
History

ColdFusion 10: New attribute {{orderBy}}
ColdFusion 9: Added support for Solr search engine.
ColdFusion MX 7:
Added category, categoryTree, status, suggestions, contextPassages, contextBytes, conte
xtHighlightBegin, contextHighlightEnd, and previousCriteria attributes.
Added author, category, categoryTree, context, rank, size, recordsSearched, and type result
columns.
Added information on the status structure and its associated keys.
Removed references to a separate K2 server and k2server.ini file.
Removed references to unregistered collections.
Removed references to external collections. ColdFusion MX now manages all collections through the Verity
Search service.
Changed cflock recommendation. It is no longer a best practice to surround the cfsearch tag with a cflo
ck tag.
ColdFusion MX:
Deprecated the external attribute. It might not work, and might cause an error, in later releases.
(ColdFusion stores this information about each collection; it automatically detects whether a collection is
internal or external.) This tag supports absolute (also known as fully qualified) collection pathnames and
mapped collection names.
Changed query result behavior: the cfindex tag can index the query results from a cfsearch operation.
Changed Verity operations behavior: ColdFusion supports Verity operations on Acrobat PDF files.
Changed multiple collection behavior: this tag can search multiple collections. In a multiple collection search,
you cannot combine collections that are registered with K2Server and registered in another way.
Changed acceptable collection naming: this tag accepts collection names that include spaces.
Changed the following support: this tag supports Verity 2.6.1 and the LinguistX and ICU locales.
Changed thrown exceptions: this tag can throw the SEARCHENGINE exception.
Attributes

Attribute

Req/Opt

name

Required

Name of the search
query.

collection

Required

One or more collection
names. You can specify
more than one collection
unless you are performing
a category search (that is,
specifying category or c
ategoryTree).

© 2014 Adobe Systems Incorporated. All rights reserved.

Default

Description

1111

Adobe ColdFusion Documentation

category

Optional

A list of categories,
separated by commas, to
which the search is
limited. If specified, and
the collection does not
have categories enabled,
ColdFusion throws an
exception.

categoryTree

Optional

The location in a
hierarchical category tree
at which to start the
search. ColdFusion
searches at and below
this level. If specified, and
the collection does not
have categories enabled,
ColdFusion throws an
exception. Can be used in
addition to the category
attribute.

criteria

Optional

Search criteria. Follows
the syntax rules of the ty
pe attribute. If you pass a
mixed-case entry in this
attribute, the search is
case sensitive. If you pass
all uppercase or all
lowercase, the search is
case-insensitive. Follow
Solr syntax and delimiter
character rules; see Solr
search support in the Dev
eloping ColdFusion
Applications.

contextBytes

OptionalSolr

300

The maximum number of
bytes returned in the
context summary.

contextHighlightBeg
in

OptionalSolr



The HTML to prepend to
search terms in the
context summary. Use
this attribute in
conjunction with context
HighlightEnd to
highlight search terms in
the context summary.

© 2014 Adobe Systems Incorporated. All rights reserved.

1112

Adobe ColdFusion Documentation

contextHighlightEnd

OptionalSolr



The HTML to append to
search terms in the
context summary. Use
this attribute in
conjunction with context
HighlightBegin to
highlight search terms in
the context summary.

contextPassages

OptionalSolr

0

The number of
passages/sentences Solr
returns in the context
summary (that is, the con
text column of the
results). The default is 0,
which disables context
summary.

language

Optional

english

Deprecated. This attribute
is now ignored and the
language of the collection
is used to perform the
search.

maxRows

Optional

all

Maximum number of rows
to return in query results.

orderBy

Optional

Sorts the custom field
column rank order. By
default, it sorts in
ascending order.

previousCriteria

Optional

The name of a result set
from an existing set of
search results. The
search engine searches
the result set for criteri
a without regard to the
previous search score or
rank. Use this attribute to
implement searching
within result sets.

startRow

Optional

© 2014 Adobe Systems Incorporated. All rights reserved.

1

Row number of the first
row to get.

1113

Adobe ColdFusion Documentation

status

Optional

suggestions

Optional

Specifies the name of the
structure variable into
which ColdFusion places
search information,
including alternative
criteria suggestions
(spelling corrections). For
a list of keys in this
structure, see the section
Status structure keys.
never

Specifies whether the
search engine returns
spelling suggestions for
possibly misspelled
words. Use one of the
following options:
Always: Always return
spelling suggestions.
Never: Never return
spelling suggestions.
positive integer: Return
spelling suggestions if
the number of
documents retrieved by
the search is less than
or equal to the number
specified.
There is a small
performance penalty for
retrieving suggestion
data.

© 2014 Adobe Systems Incorporated. All rights reserved.

1114

Adobe ColdFusion Documentation

Optional

type

simple

Used to specify the parser
that the engine uses to
process the criteria.
simple: STEM and
MANY operators are
implicitly used.
explicit: operators must
be invoked explicitly.
Also known as
Bool_Plus.
internet: for documents
that are mostly
WYSIWIG
(what-you-see-is-what-y
ou-get) documents.
Also known as
Internet_advanced.
internet_basic:
minimizes search time.
natural: specifies the
Query By Example
(QBE) parser. Also
known as FreeText.

Usage

The cfsearch tag returns a query object whose columns you can reference in a cfoutput tag. For example, the
following code specifies a search for the exact terms "filming" or "filmed":




Search Result total =#name.RecordCount# 


url=#name.url#

key=#name.key#

title=#name.title#

score=#name.score#

custom1=#name.custom1#

custom2=#name.custom2#

summary=#name.summary#

recordcount=#name.recordcount#

currentrow=#name.currentrow#

columnlist=#name.columnlist#

recordssearched=#name.recordssearched#



© 2014 Adobe Systems Incorporated. All rights reserved.

1117

Adobe ColdFusion Documentation







url=#url#

key=#key#

title=#title#

score=#score#

custom1=#custom1#

custom2=#custom2#

summary=#summary#

recordcount=#recordcount#

currentrow=#currentrow#

columnlist=#columnlist#

recordssearched=#recordssearched#








url=#book.url#

key=#book.key#

title=#book.titleE#

score=#book.score#

custom1=#book.custom1#

custom2=#book.custom2#

summary=#book.summary#

recordcount=#book.recordcount#

currentrow=#book.currentrow#

columnlist=#book.columnlist#

recordssearched=#book.recordssearched#


© 2014 Adobe Systems Incorporated. All rights reserved.

1118

Adobe ColdFusion Documentation




© 2014 Adobe Systems Incorporated. All rights reserved.

1119

Adobe ColdFusion Documentation

cfselect
Description

Constructs a drop-down list box form control. Used in a cfform tag. You can populate the list from a query, or by
using the HTML option tag.
Category

Forms tags
Syntax


zero or more HTML option tags


Some attributes apply to only specific display formats. For details see the Attributes table.
Note
You can specify this tag's attributes in an attributeCollection attribute whose value is a
structure. Specify the structure name in the attributeCollection attribute and use the tag's
attribute names as structure keys.

See also

cfapplet, cfcalendar, cfform, cfformgroup, cfformitem, cfgrid, cfinput, cfslider, cftextarea, c
ftree; Introduction to Retrieving and Formatting Data and Using Ajax User Interface Components and Features in
the Developing ColdFusion Applications
History

© 2014 Adobe Systems Incorporated. All rights reserved.

1120

Adobe ColdFusion Documentation

ColdFusion 8:
Added support for binding in HTML format forms, including the bind, bindAttribute, and bindOnLoad,
and onBindError attributes.
Added support for tool tips in HTML format forms, including the sourceForTooltip attribute.

ColdFusion MX 7:
When populating a cfselect tag with a query when the database field has spaces instead of a value, the
error processing of the cfform tag required field is not triggered as it was in ColdFusion MX 6.1.
Added support for specifying multiple values to the selected attribute.
Deprecated the passthrough attribute. The tag now supports all HTML select tag attributes directly.
Added on-prefixed attributes.
Added enabled, group, height, label, queryPosition, tooltip, visible, and width attributes.
Attributes

The following table lists attributes that ColdFusion uses directly. The tag also supports all HTML select tag
attributes that are not on this list, and passes them directly to the browser.
Note
Attributes that are marked as Flash only are not handled by the skins provided with ColdFusion.
They are, however, included in the generated XML.

Attribute

Req/Opt;Format

name

Required;All

Name of the select form
element.

bind

Optional; HTML

A bind expression that
dynamically sets an
attribute of the control. For
details, see Usage.

bindAttribute

Optional;HTML

© 2014 Adobe Systems Incorporated. All rights reserved.

Default

Populate the options

Description

Specifies the HTML tag
attribute whose value is
set by the bind attribute.
You can only specify
attributes in the browser's
HTML DOM tree, not
ColdFusion-specific
attributes.
Ignored if there is no bin
d attribute.

1121

Adobe ColdFusion Documentation

bindOnLoad

Optional;HTML

no

A Boolean value that
specifies whether to
execute the bind attribute
expression when first
loading the form. Ignored
if there is no bind attribut
e.

display

Optional;All

Value of value attribute

Query column to use for
the display label of each
list element. Used with the
query attribute.

editable

Optional; Flash

no

Boolean value specifying
whether you can edit the
contents of the control.

enabled

Optional; Flash

yes

Boolean value specifying
whether the control is
enabled. A disabled
control appears in light
gray. The inverse of the d
isabled attribute.

group

Optional; HTML and XML

Query column to use to
group the items in the
drop-down list into a
two-level hierarchical list.

height

Optional; Flash

The height of the control,
in pixels.

id

Optional;HTML

label

Optional;Flash and XML

Label to put next to the
control on a Flash or
XML-format form.

message

Optional;All

Message to display if req
uired = "yes" and no
selection is made.

multiple

Optional;All

© 2014 Adobe Systems Incorporated. All rights reserved.

Value of name attribute

no

The HTML ID of the
control.

yes: allows selecting
multiple elements in
drop-down list.
no

1122

Adobe ColdFusion Documentation

onBindError

Optional;HTML

onChange

Optional;All

JavaScript (HTML/XML)
or ActionScript (Flash) to
run when the control
changes due to user
action.

onClick

Optional; HTML and XML

JavaScript to run when
the user clicks the control.

onError

Optional;HTML and XML

Custom JavaScript
function to execute if
validation fails.

onKeyDown

Optional;All

JavaScript (HTML/XML)
or ActionScript (Flash) to
run when the user
presses a keyboard key in
the control.

onKeyUp

Optional;All

JavaScript (HTML/XML)
or ActionScript (Flash) to
run when the user
releases a keyboard key
in the control.

onMouseDown

Optional;All

JavaScript (HTML/XML)
or ActionScript (Flash) to
run when the user
releases a mouse button
in the control.

© 2014 Adobe Systems Incorporated. All rights reserved.

See Description

The name of a JavaScript
function to execute if
evaluating a bind
expression results in an
error. The function must
take two attributes: an
HTTP status code and a
message. (The status
code is1 if the error is not
an HTTP error.)If you omit
this attribute, and
specified a global error
handler (by using the Col
dFusion.setGlobalEr
rorHandler function), it
displays the error
message; otherwise a
default error pop-up
appears.

1123

Adobe ColdFusion Documentation

onMouseUp

Optional;All

JavaScript (HTML/XML)
or ActionScript (Flash) to
run when the user
presses a mouse button in
the control.

query

Optional;All

Name of query to
populate drop-down list.

queryPosition

Optional;All

above

If you populate the options
list with a query and use
HTML option child tags
to specify additional
entries, this attribute
determines the location of
the items from the query
relative to the items from
the option tags:
above: puts the query
items above the optio
ns items.
below: puts the query
items below the optio
ns items.

required

Optional;All

no

Note: This attribute has no
effect if you omit the size
attribute or set it to 1,
because the browser
always submits the
displayed item. You can
work around this issue:
format forms by having an
initial option tag with va
lue=" " (notice the
space character between
the quotation marks). This
workaround applies only
for Flash forms and not for
HTML forms or XML
forms.
yes: a list element must
be selected when the
form is submitted.
no

© 2014 Adobe Systems Incorporated. All rights reserved.

1124

Adobe ColdFusion Documentation

selected

Optional;All

size

Optional;All

sourceForTooltip

Optional; HTML

The URL of a page to
display as a tool tip. The
page can include CFML
and HTML markup to
control the tip contents
and format, and the tip
can include images.
If you specify this
attribute, an animated
icon appears with the text
"Loading..." while the tip is
being loaded.

style

Optional;All

In HTML or XML format
forms, ColdFusion passes
the style attribute to the
browser or XML.
In Flash format, must be a
style specification in CSS
format, with the same
syntax and contents as
used in Flex for the
corresponding Flash
element.

© 2014 Adobe Systems Incorporated. All rights reserved.

One or more option
values to preselect in the
selection list. To specify
multiple values, use a
comma-delimited list. This
attribute applies only if
selection list items are
generated from a query.
The cfform tag preser
veData attribute can
override this value.
1

Number of entries to
display at one time. The
default value displays a
drop-down list. Any other
value displays a list box
with size number of
entries visible at one time.

1125

Adobe ColdFusion Documentation

tooltip

Optional; Flash, HTML

Text to display when the
mouse pointer hovers
over the control. The text
can include HTML
markup.
Ignored if you specify a s
ourceForTooltip attrib
ute.

value

Optional;All

Query column to use for
the value of each list
element. Used with the qu
ery attribute.

visible

Optional; Flash

width

Optional; Flash

yes

Boolean value that
specifies whether to show
the control. The display
reserves empty space for
an invisible control.
The width of the control, in
pixels.

Usage

For this tag to work properly. the browser must have JavaScript enabled. This tag requires an end tag and can
include HTML option and optgroup child tags. To ensure that a selected list box item persists across postbacks,
use the cfform tag preserveData attribute with a list generated from a query. (This strategy works only with data
that is populated from a query.)If the cfform preserveData attribute is yes and the form posts back to the same
page, and if the control is populated by a query, the posted selections for the cfselect control are used instead of
the Selected attribute. For controls that are populated with regular HTML option tags, the developer must
dynamically add the Selected attribute to the appropriate option tags.
The group option generates a query by using SQL GROUP BY syntax and places the value column entries from
each group in an indented list under the group column's field value. This option generates an HTML optgroup tag
for each entry in the group column.Close each HTML option tag in the cfselect tag body with a  en
d tag. If you do not do so, and you specify queryPosition="below", the first item from the query might not
appear in the list.
The bind attribute lets you set cfselect attributes dynamically. Often, it is used to dynamically create the options
list based on values that the user enters in the form. For example, you can use the bind attribute to create a Cities
option list based on the user's selection from a States cfselect control. When you use a bind attribute to
populate the selection list, the function or URL that returns the selection values must return one of the following:
A two-dimensional array, where the first element in each array row is the option value and the second
element in the row is the text to display in the option list.
If the bind specifies a CFC function, a query, or, if the bind specifies a URL, a JSON representation of a
query. The query must include columns whose names are the values of the cfselect tag value and displ
ay attributes. Although you can return additional columns, you cannot use them in your client-side code.
When you call a CFC function, you do not have to convert the query to JSON format yourself; ColdFusion
automatically does the conversion.
To use this format, specify a value attribute. If you omit the display attribute, you must have only a single
column in the query that contains the values; the values are also used as the displayed text.

© 2014 Adobe Systems Incorporated. All rights reserved.

1126

Adobe ColdFusion Documentation

For detailed information on binding, see Binding data to form fields in the Developing ColdFusion Applications
. For more information, see the cfform tag entry.
Example

Example 1: Without data bindingThe following example lets you select one or more employee names from a list of
all employees, grouped by departments, and displays the selected names and the employee's e-mail addresses. It
includes an option to get data for all employees.




SELECT Emp_ID, EMail, Phone, Department, FirstName, LastName,
FirstName ||' '
||lastName as Name
FROM Employees
GROUP BY Department, Emp_ID, EMail, Phone, FirstName, LastName, FirstName

cfselect Example



You Selected the following employees



#name#

Email: #email#






SELECT Emp_ID, EMail, Phone, Department, FirstName, LastName,
FirstName
||' ' ||lastName as Name
FROM GetAllEmployees
WHERE Emp_ID in (#form.employeeid#)



#firstName# #lastName#

Email: #email#







Select one or more employees

© 2014 Adobe Systems Incorporated. All rights reserved.

1127

Adobe ColdFusion Documentation





Select All




© 2014 Adobe Systems Incorporated. All rights reserved.

1128

Adobe ColdFusion Documentation




Example 2: With data bindingThe following example uses binding to fill in the options list of the Cities control only
after the user selects a state. (In this example, only two states, California and New Jersey, have city entries.)The
CFML page is the simplest part of the example. It consists of the following lines:








--state--


--city--





The BinFcns CFC has three functions: getstates, to get the states; getcities, to get the cities; and an internal
getXmlData function that parses an XML file to get the state and city information. The following examples shows
the CFC:

© 2014 Adobe Systems Incorporated. All rights reserved.

1129

Adobe ColdFusion Documentation


















































© 2014 Adobe Systems Incorporated. All rights reserved.

1130

Adobe ColdFusion Documentation

The states.xml file has the following code. To keep the code short, only two states have cities, and only four states
are listed.



New Jersey












California











Maine


Massachusetts



© 2014 Adobe Systems Incorporated. All rights reserved.

1131

Adobe ColdFusion Documentation

cfservlet
Description

This tag is deprecated. Executes a Java servlet on a JRun engine. To access servlets that run on the same server
as ColdFusion, use code such as the following, in which path specifies a servlet, JSP, or anything else:

GetPageContext().include(path)
GetPageContext().forward(path)

For more information, see the JSP PageContext API or the Servlet RequestDispatcher API.
History

ColdFusion MX: Deprecated this tag. It might not work, and it might cause an error, in later releases.

© 2014 Adobe Systems Incorporated. All rights reserved.

1132

Adobe ColdFusion Documentation

cfservletparam
Description

This tag is deprecated. A child tag of the cfservlet tag. Passes data to a servlet. Each cfservletparam tag
within the cfservlet block passes a separate item of data to the servlet. To access servlets that run on the same
server as ColdFusion, use code such as the following, in which path specifies a servlet, JSP, or anything else:

GetPageContext().include(path)
GetPageContext().forward(path)

For more information, see the JSP PageContext API or the Servlet RequestDispatcher API.
History

ColdFusion MX: Deprecated this tag. It might not work, and it might cause an error, in later releases.

© 2014 Adobe Systems Incorporated. All rights reserved.

1133

Adobe ColdFusion Documentation

cfset
Description

Sets a value in ColdFusion. Used to create a variable, if it does not exist, and assign it a value. Also used to call
functions.
Category

Variable manipulation tags
Syntax



See also

cfcookie, cfparam, cfregistry, cfsavecontent, cfschedule; Elements of CFML in the Developing
ColdFusion Applications
Attributes

Attribute

Req/Opt

Default

Description

variable_name

Required

A variable.

var

Optional

A keyword. Does not take
a value. Identifies the
variable as being local to
a function. The variable
only exists for the time of
the current invocation of
the function.

Usage

You use the cfset tag in several ways in your applications.
Calling functions

When you use the cfset tag to call a function, you do not have to assign the function return value to a variable if
the function does not return a value or you do not have to use the value returned by the function. For example, the
following line is a valid ColdFusion cfset tag for deleting the MyVariable variable from the Application scope:



Arrays

The following example assigns a new array to the variable months:

© 2014 Adobe Systems Incorporated. All rights reserved.

1134

Adobe ColdFusion Documentation



This example creates a variable Array_Length that resolves to the length of the Scores array:



This example assigns, to index position two in the array months, the value February:



Dynamic variable names

In this example, the variable name is itself a variable:




Function local variables

The var keyword specifies that the variable being defined is only available inside the body of a function that you
define by using the cffunction tag. The variable value that is set in one invocation of the function is not available
in any other invocation of the function. The var keyword is the equivalent of the var statement in CFScript. The
following rules apply to the var keyword:
Any cfset tag that uses the var keyword must be inside the body of a cffunction tag. If you use the var
keyword in a cfset tag outside a cffunction tag body, ColdFusion displays an error message.
Place all cfset tags that use the var keyword at the beginning of the cffunction tag body, before any
other ColdFusion tags.
The following example shows how to use the new keyword:





#myFunct()#

In this example, the variable myVar exists only when the function myFunct executes, and it is not available
elsewhere on the ColdFusion page.
COM objects

In this example, a COM object is created. A cfset tag defines a value for each method or property in the COM

© 2014 Adobe Systems Incorporated. All rights reserved.

1135

Adobe ColdFusion Documentation

object interface. The last cfset creates a variable to store the return value from the COM object's SendMail meth
od.










 #success# 

Example

© 2014 Adobe Systems Incorporated. All rights reserved.

1136

Adobe ColdFusion Documentation



SELECT *
FROM Messages

cfset Example
cfset sets and reassigns values to local or global variables within a page.

For example, the variable NumRecords has been declared on this
page to hold the number of records returned from query
(#NumRecords#).
In addition, cfset can be used to pass variables from other pages,
such as this example, which takes the url parameter Test from this
link: 
">click here) to display a message:


#url.test#

The variable url.test has not been passed from another page.

cfset can also be used to collect environmental variables, such as the
time, the IP address of the user, or another function or expression.

user_ip = CGI.REMOTE_ADDR>
complex_expr = (23 MOD 12) * 3>
str_example = Reverse(Left(GetMessages.body, 35))>



The date: #the_date#
User IP Address: #user_ip#
Complex Expression ((23 MOD 12) * 3): #complex_expr#
String Manipulation (the first 35 characters of
the body of the first message in our query)

Reversed: #str_example#

Normal: #Reverse(str_example)#



© 2014 Adobe Systems Incorporated. All rights reserved.

1137

Adobe ColdFusion Documentation

cfsetting
Description

Controls aspects of page processing, such as the output of HTML code in pages. The cfsetting tag can also be used
in script style.
Category

Page processing tags, Variable manipulation tags
Syntax



Script style syntax for cfsetting:

setting enablecfoutputonly="true" requesttimeout="0" showdebugoutput="yes";

Note
You can specify this tag's attributes in an attributeCollection attribute whose value is a
structure. Specify the structure name in the attributeCollection attribute and use the tag's
attribute names as structure keys.

See also

cfcache, cfflush, cfheader, cfhtmlhead, cfinclude, cfprocessingdirective, cfsilent; Controlling
debugging output with the cfsetting tag in the Developing ColdFusion Applications
History

ColdFusion MX 6.1: Changed behavior: if the tag has a body, ColdFusion executes its contents.
ColdFusion MX:
Added the requestTimeOut attribute.
The catchExceptionsByPattern attribute is obsolete. It does not work, and causes an error, in releases
later than ColdFusion 5.
Changed exception handling: the structured exception manager searches for the best-fit cfcatch handler.
(In earlier releases, an exception was handled by the first cfcatch block that could handle an exception of
its type.)
Attributes

Attribute

Req/Opt

© 2014 Adobe Systems Incorporated. All rights reserved.

Default

Description

1138

Adobe ColdFusion Documentation

enableCFoutputOnly

Optional

yes: blocks output of
HTML that is outside cf
output tags.
no: displays HTML that
is outside cfoutput ta
gs.

requestTimeout

Optional

integer; number of
seconds. Time limit,
after which ColdFusion
processes the page as
an unresponsive thread.
Overrides the time-out
set in the ColdFusion
Administrator.
If you specify 0 as the
value, timeout is
disabled for the request.

showDebugOutput

Optional

yes

yes: if debugging is
enabled in the
Administrator, displays
debugging information.
no: suppresses
debugging information
that would otherwise
display at the end of the
generated page.

Usage

The cfsetting requestTimeout attribute replaces the use of requestTimeOut within a URL. To enforce a
page time-out, detect the URL variable and use code such as the following to change the page time-out:



You can use this tag to manage whitespace in ColdFusion output pages. If you nest cfsetting tags: to make
HTML output visible, match each enableCFoutputOnly = "Yes" statement with an enableCFoutputOnly =
"No" statement. For example, after five enableCFoutputOnly = "Yes" statements, to enable HTML output,
you must have five corresponding enableCFoutputOnly = "No" statements. If HTML output is enabled (no
matter how many enableCFoutputOnly = "No" statements have been processed) the first enableCFoutputO
nly = "Yes" statement blocks output.
If the debugging service is enabled and showDebugOutput =" Yes", the IsDebugMode function returns Yes;
otherwise, No.

© 2014 Adobe Systems Incorporated. All rights reserved.

1139

Adobe ColdFusion Documentation

Note
Releases after ColdFusion MX allow a  end tag; however, this end tag does not
affect processing. The cfsetting attributes affect code inside and outside the cfsetting tag
body. ColdFusion MX ignored code between cfsetting start and end tags.

Example

CFSETTING is used to control the output of HTML code in ColdFusion pages.
This tag can be used to minimize the amount of generated whitespace.

This text is not shown

This text is shown


Text within cfoutput is always shown



Text within cfoutput is always shown


© 2014 Adobe Systems Incorporated. All rights reserved.

1140

Adobe ColdFusion Documentation

cfsharepoint
Description

Invokes a feature that SharePoint exposes as a web service action, such as the Document Workspace getdwsdat
a action.
Category

Extensibility tags, MS Office Integration tags.
Syntax


or


Note
You can specify this tag's attributes in an attributeCollection attribute whose value is a
structure. Specify the structure name in the attributeCollection attribute and use the tag's
attribute names as structure keys.

History

ColdFusion 9: Added tag.
Attributes

Attribute

Req/Opt

action

Required

© 2014 Adobe Systems Incorporated. All rights reserved.

Default

Description
The name of a web
service action. See Usage
for the list of service
actions you can specify.

1141

Adobe ColdFusion Documentation

domain

Optional

The domain name
required to connect to the
SharePoint server.
Required if you do not
specify a login attribute.

login

Optional

A structure containing
user, password, and
domain login credentials
to pass to the service. If
you do not specify domai
n, password, and userN
ame attributes, specify a l
ogin structure with doma
in, password, and user
Name entries.

name

Optional

Name of the result
variable in which to put
the data returned by the
SharePoint service.

params

Optional

A structure containing
names and values of the
parameters to pass to the
service.
This attribute is required
for any service that
requires parameters.

password

Optional

The password required to
connect to the SharePoint
server. Required if you do
not specify a login attrib
ute.

userName

Optional

The user name required
to connect to the
SharePoint server.
Required if you do not
specify a login attribute.

wsdl

Optional

Path to the service wsdl
file. Required to invoke an
action that is not in the list
of supported actions. See
Usage for details.

Usage

© 2014 Adobe Systems Incorporated. All rights reserved.

1142

Adobe ColdFusion Documentation

The cfsharepoint tag invokes a Microsoft SharePoint web service. You call many SharePoint web service
actions by specifying the action name in the action attribute and passing the web service parameters in the param
s attribute. You access the services and methods that the cfsharepoint tag does not support directly by
specifying the service WSDL URLs in the wsdl attribute.
Note
You can use the cfsharepoint tag with servers that use basic authentication only.

You request a service and action by specifying the action attribute values listed in the following tables. In nearly all
cases, these are identical to the SharePoint action names. Notes indicate where the attribute values differ from the
action names because multiple services have the same action name.
Note
The web service action parameters are documented at http://msdn.microsoft.com/en-us/library/d
d878586(v=office.12).aspx. You can also determine the parameters from the web service WSDL,
at http://server_name/_vti_bin/WebServiceName?wsdl.

When the cfsharepoint tag receives the results from the SharePoint server and completes, the structure
specified by the name attribute contains the response. This structure also has a ResultFlag entry containing the
value Success or Failure. The entry value is Success if there is no Axis Fault or an error is returned in the
response, otherwise, the value is Failure.Document Workspace
cancreatedwsurl

deletedwsfolder

renamedws

createdws

finddwsdoc

updatedwsdata

createdwsfolder

getdwsdata

deletedws

removedwsuser

Note
The createdwsfolder and deletedwsfolder action attribute values correspond to the cre
atefolder and deletefolder actions of the Document Workspace service.

Imaging
delete

getitemsbyids

download

listpicturelibrary

getimaginglistitems

rename

© 2014 Adobe Systems Incorporated. All rights reserved.

upload

1143

Adobe ColdFusion Documentation

Note
The getimaginglistitems action attribute value correspond to the getlistitems action of
the Imaging service.

Lists
addattachment

getattachmentcollection

updatelist

addlist

getlist

updatelistitems

deleteattachment

getlistcollection

deletelist

getlistitems

Search or spsearch
Note
spsearch/search is not present in Windows Sharepoint Services 2.0.

In Windows SharePoint Services 3.0, if the action attribute specifies any of the following actions, the spsearch.asmx
web service is used to perform the search. In Microsoft Office SharePoint Portal Server 2003 or Microsoft Office
SharePoint Server 2007, search.asmx is used to perform the search. In Windows Sharepoint Services 2.0, an
exception is thrown.
query

registration

queryex

status

UserGroup
addgrouptorole

getgroupcollection

removerole

addrole

getrolecollection

removeusercollectionfromgroup

addusercollectiontogroup

getusercollectionfromrole

removeuserfromgroup

addusercollectiontorole

getusercollectionfromrole

addusertogroup

getuserinfo

Views
addview

getview

deleteview

getviewcollection

© 2014 Adobe Systems Incorporated. All rights reserved.

updateview

1144

Adobe ColdFusion Documentation

Data type conversion

Some web service actions require parameters in a Microsoft data type that does not correspond directly to a
ColdFusion data type. The cfsharepoint tag automatically converts between the Microsoft data types and the
most appropriate Java data types, which ColdFusion uses internally. The following table lists the conversions, and
indicates the corresponding ColdFusion data type.
SharePoint data type

ColdFusion Java data type

XmlNode

XMLNodeList - corresponds to a ColdFusion XML
object, for example created by passing an XML string
to the XmlParse function.)

ArrayOfString

string array - corresponds to a ColdFusion array
containing string data.

UnsignedInt

int - corresponds to a ColdFusion number that is an
integer value

ArrayOfUnsignedInt

int array - corresponds to a ColdFusion array
containing string data.

Example

The following example shows how you can manipulate lists and views. It requires resources on the SharePoint
server that are not specified here.








Getting the list collection



result.ResultFlag: #result.ResultFlag#


Deleting mycustomlist from the collection, if it exists.






Was anything deleted?


© 2014 Adobe Systems Incorporated. All rights reserved.

1145

Adobe ColdFusion Documentation

YES. The result is:




NO

Adding a mycustomlist list


addlist result.ResultFlag: #result1.ResultFlag#






")>




10





")>
50")>
Adding a myview1 view for the mycustomlist list


addview result.ResultFlag: #result.ResultFlag#



Adding a myview3 view for the mycustomlist list


addview result.ResultFlag: #result.ResultFlag#


Getting the updated mycustomlist view collection


getviewcollection result



The names of the collection's views:



© 2014 Adobe Systems Incorporated. All rights reserved.

1146

Adobe ColdFusion Documentation

#v.displayname#




Deleting the list


deletelist result.ResultFlag: #result1.ResultFlag#


© 2014 Adobe Systems Incorporated. All rights reserved.

1147

Adobe ColdFusion Documentation




© 2014 Adobe Systems Incorporated. All rights reserved.

1148

Adobe ColdFusion Documentation

cfsilent
Description

Suppresses output produced by CFML within a tag's scope.
Category

Data output tags, Page processing tags
Syntax


...


See also

cfcache, cfflush, cfheader, cfhtmlhead, cfinclude, cfsetting; Writing and Calling User-Defined
Functions in the Developing ColdFusion Applications
Usage

This tag requires an end tag.
Example

cfsilent




Inside cfsilent block

b-a = #c#


Even information within cfoutput tags does not display within a
cfsilent block.


b-a = #c#



© 2014 Adobe Systems Incorporated. All rights reserved.

1149

Adobe ColdFusion Documentation

cfslider
Description

Places a slider control, for selecting a numeric value from a range, in a ColdFusion form. The slider moves over the
slider groove. As the user moves the slider, the current value displays. Used within a cfform tag for forms in HTML
and applet format. Not supported with Flash forms. In HTML forms, you can create visually rich sliders that let you
modify adjustable values in fixed increments. You can specify maximum, minimum, and increment values, to help
you quickly filter complex results. The sliders are categorized based on the slider control. The available slider
controls are:
Vertical The slider has vertical controls that can be adjusted to the top or bottom.
Horizontal The slider has horizontal controls that can be adjusted to the left or right.
Tip The slider displays the values as data tips.
Snapping The slider moves in incremental values.
Category

Forms tags
Syntax

For HTML



Syntax

For Applet

© 2014 Adobe Systems Incorporated. All rights reserved.

1150

Adobe ColdFusion Documentation



Note
You can specify this tag's attributes in an attributeCollection attribute whose value is a
structure. Specify the structure name in the attributeCollection attribute and use the tag's
attribute names as structure keys.

See also

cfapplet, cfcalendar, cfform, cfformgroup, cfformitem, cfgrid, cfinput, cfselect, cftextarea, c
ftree; Introduction to Retrieving and Formatting Data and Building Dynamic Forms with cfform Tags in the Develop
ing ColdFusion Applications
History

ColdFusion MX: Deprecated the img, imgStyle, grooveColor, refreshLabel, tickmarklabels, tickmark
major, tickmarkminor, and tickmarkimages attributes. They sometimes do not work, and can cause an error,
in later releases.
Attributes

Attribute

Req/Opt

name

Required

© 2014 Adobe Systems Incorporated. All rights reserved.

Default

Description
Name of cfslider contr
ol.

1151

Adobe ColdFusion Documentation

align

Optional

Alignment of slider:
top
left
bottom
baseline
texttop
absbottom
middle
absmiddle
right

bgColor

Optional

Background color of slider
label. For a hexadecimal
value, use the form: bgCo
lor = "##xxxxxx",
where x = 0-9 or A-F; use
two number signs or
none.
any color, in
hexadecimal format
black
red
blue
magenta
cyan
orange
darkgray
pink
gray
white
lightgray
yellow

bold

Optional

clickToChange

OptionalHTML

no

yes: label text in bold.
no: medium text.
Whether clicking the slider
changes the value of the
pointer:
true
false

font

Optional

Font name for label text.

fontSize

Optional

Font size for label text, in
points.

© 2014 Adobe Systems Incorporated. All rights reserved.

1152

Adobe ColdFusion Documentation

format

Optional

applet

Specifies if the format is:
html
applet

height

Optional

hSpace

Optional

italic

Optional

increment

OptionalHTML

The unit increment value
for a snapping slider.

label

Optional

Label to display with
control; for example, "Vol
ume" This displays:"Volu
me %value%"}}To
reference the
value, use
{{"%value%". If %% is
omitted, slider value
displays directly after
label.

lookAndFeel

Optional

max

OptionalHTML

Maximum value for the
slider.

min

OptionalHTML

Minimum value for the
slider.

message

OptionalApplet

Message text to appear if
validation fails.

© 2014 Adobe Systems Incorporated. All rights reserved.

40, for applet 100,
for HTML

Slider control height, in
pixels.
Horizontal spacing to left
and right of slider, in
pixels.

no

Windows

yes: label text in italics.
no: normal text.

motif: renders slider
using Motif style.
windows: renders
slider using Windows
style.
metal: renders slider
using Java Swing style.
If platform does not
support choice, the tag
defaults to the
platform's default style.

1153

Adobe ColdFusion Documentation

notSupported

Optional

Text to display if a page
that contains a Java
applet-based cfform con
trol is opened by a
browser that does not
support Java or has Java
support disabled. For
example:{{" Browser
must support Java to view
ColdFusion Java
Applets"}}Default
message:Browser
must support Java to

view ColdFusion
Java Applets!

onChange

OptionalHTML

Custom JavaScript
function to run when slider
value changes. Specify
only the function name.

onDrag

OptionalHTML

Custom JavaScript
function to run when you
drag the slider. Specify
only the function name.

onError

Optional

Custom JavaScript
function to run if validation
fails. Specify only the
function name.

onValidate

Optional

Custom JavaScript
function to validate user
input; in this case, a
change to the default
slider value. Specify only
the function name.

range

Optional

© 2014 Adobe Systems Incorporated. All rights reserved.

"0,100"

Numeric slider range
values. Separate values
with a comma.

1154

Adobe ColdFusion Documentation

scale

Optional

Unsigned integer. Defines
slider scale, within range.
For example, if range = "
0,1000" and scale = "
100", the display values
are:0, 100, 200, 300,
...Signed and unsigned
integers in ColdFusion are
in the range
-2,147,483,648 to
2,147,483,647.

textColor

Optional

Options: same as for bgc
olor attribute.

tip

OptionalHTML

true

Whether the data valu has
to display as data tips:
true
false

value

Optional

Minimum in range

Starting slider setting.
Must be within the range
values.

vertical

Optional

no(for applet
forms) false(for
HTML forms)

For Applet forms:

vSpace

Optional

width

Optional

© 2014 Adobe Systems Incorporated. All rights reserved.

yes: renders slider in
browser vertically. Set w
idth and height attrib
utes; ColdFusion does
not automatically swap
width and height values.
no: renders slider
horizontally.
For HTML forms:
true: renders slider in
browser vertically. Set w
idth and height attrib
utes; ColdFusion does
not automatically swap
width and height values.
false: renders slider
horizontally.
Vertical spacing above
and below slider, in pixels.

200, for HTML

Slider control width, in
pixels.

1155

Adobe ColdFusion Documentation
Usage

This tag requires the client to download a Java applet. Using this tag is sometimes slightly slower than using an
HTML form element to display the same information. Also, if the client does not have an up-to-date Java plug-in
installed, the system sometimes has to download an updated Java plug-in to display the tag.
For this tag to work properly, the browser must be JavaScript-enabled.
If the following conditions are true, a user's selection from query data that populates this tag's options continues to
display after the user submits the form:
The cfform preserveData attribute is set to "Yes".
The cfform action attribute posts to the same page as the form itself (this is the default), or the action
page has a form that contains controls with the same names as corresponding controls on the user entry
form.
For more information, see the cfform tag entry.
Example



SELECT CORNUMBER,DEPT_ID,COURSE_ID,CORNAME
FROM COURSELIST


SELECT *
FROM CENTERS


//Use an absolute path for the files. --->
theDir=GetDirectoryFromPath(GetCurrentTemplatePath());
theFile=theDir & "courses.xls";
//Create two empty ColdFusion spreadsheet objects. --->
theSheet = SpreadsheetNew("CourseData");
theSecondSheet = SpreadsheetNew("CentersData");
//Populate each object with a query. --->
SpreadsheetAddRows(theSheet,courses);
SpreadsheetAddRows(theSecondSheet,centers);









First sheet row 3 read as a CSV variable

Second sheet rows 5-10 read as an HTML variable

Second sheet read as a query variable



SpreadsheetAddRow(spreadsheetData,"03,ENGL,230,Poetry 1",8,1);

© 2014 Adobe Systems Incorporated. All rights reserved.

1163

Adobe ColdFusion Documentation

SpreadsheetAddColumn(spreadsheetData,
"Basic,Intermediate,Advanced,Basic,Intermediate,Advanced,Basic,Intermediate,Advance
d",
3,2,true);





© 2014 Adobe Systems Incorporated. All rights reserved.

1164

Adobe ColdFusion Documentation


















© 2014 Adobe Systems Incorporated. All rights reserved.

1165

Adobe ColdFusion Documentation

cfsprydataset
Description

Creates a Spry XML or JSON data set from the results of a bind expression.
Category

Internet protocol tags
Syntax



Note
You can specify this tag's attributes in an attributeCollection attribute whose value is a
structure. Specify the structure name in the attributeCollection attribute and use the tag's
attribute names as structure keys.

See also

cfajaximport, Using Spry with ColdFusion in the Developing ColdFusion Applications
History

ColdFusion 8: Added this tag.
Attributes

Attribute

Req/Opt

© 2014 Adobe Systems Incorporated. All rights reserved.

Default

Description

1166

Adobe ColdFusion Documentation

bind

Required

A bind expression that
returns an XML- or JSONformatted string to
populate the Spry data
set. The bind expression
specifies a CFC function
or URL and includes bind
parameters that represent
the values of ColdFusion
controls. For detailed
information on bind
expressions, see Binding
data to form fields in the D
eveloping ColdFusion
Applications.

name

Required

The name of the Spry
data set.

onBindError

Optional;HTML

options

Optional

© 2014 Adobe Systems Incorporated. All rights reserved.

See Description

The name of a JavaScript
function to execute if the
bind expression results in
an error. The function
must take two attributes:
an HTTP status code and
a message.
If you omit this attribute,
and specified a global
error handler (by using the
ColdFusion.setGloba
lErrorHandler function
), the handler displays the
error message; otherwise
a default error pop-up
appears.
A JavaScript object
containing constructor
options for the data set.
For example, to request
the data using the HTTP
POST method, specify the
following attribute:option
s="{method:
'POST'}". For detailed
information on Spry
options, see the Spry
documentation at www.ad
obe.com/go/learn_spry_fr
amework_en.

1167

Adobe ColdFusion Documentation

Optional

type

xml

Specifies data set type,
corresponding to the
format of the data that is
returned by the bind
expression. The following
values are valid:
json
xml

xpath

Required for xml typeNot
used for JSON

An XPath expression that
extracts data from the
XML returned by the bind
expression. The data set
contains only the data that
matches the XPath
expression.

Usage

Use this tag to use a bind expression to dynamically create the contents of a Spry XML or JSON data set based on
the value of a ColdFusion control or another Spry data set. To create a Spry data set without using a bind
expression, use the Spry.Data.JSONDataSet() and Spry.Data.XMLDataSet() JavaScript functions.
This tag cannot create a Spry HTML data set.
To use a filter to select the contents of a JSON data set from a JSON expression, specify a path or subpath optio
n in the options attribute. For example, to create a Spry JSON data set by using only the items.item element from
the JSON data, use a tag such as the following:



Example

The following cfsprydataset tag updates the dsProduct Spry XML data set by calling the GridDataManager.g
etProductDetails CFC function each time the selected row in the bookgrid control changes. It passes the TITLE
field of the selected row to the CFC function as a prodname parameter. For a complete example that uses this tag,
see Using Spry with ColdFusion in the Developing ColdFusion Applications.



© 2014 Adobe Systems Incorporated. All rights reserved.

1168

Adobe ColdFusion Documentation

cfstoredproc
Description

Executes a stored procedure in a server database. It specifies database connection information and identifies the
stored procedure.
Category

Database manipulation tags
Syntax



Note
You can specify this tag's attributes in an attributeCollection attribute whose value is a
structure. Specify the structure name in the attributeCollection attribute and use the tag's
attribute names as structure keys.

See also

cfinsert, cfqueryparam, cfprocparam, cfprocresult, cftransaction, cfquery, cfupdate; Optimizing
database use in the Developing ColdFusion Applications
History

ColdFusion 11: Added the attribute, dbVarName.
ColdFusion 10: Added the following attributes: timeOut, fetchClientInfo,and clientInfo.
ColdFusion MX 7: Added the result attribute.ColdFusion MX: Deprecated the connectString, dbName, dbServ
er, dbtype, provider, and providerDSN attributes. They do not work, and might cause an error, in releases
later than ColdFusion 5. (Releases starting with ColdFusion MX use Type 4 JDBC drivers.)
Attributes

Attribute

Req/Opt

© 2014 Adobe Systems Incorporated. All rights reserved.

Default

Description

1169

Adobe ColdFusion Documentation

dataSource

Required

Name of data source that
points to database that
contains stored
procedure.

procedure

Required

Name of stored procedure
on database server.

blockFactor

Optional

cachedAfter

Optional

A date value (for example,
April 16, 2008,
4-16-2008). If the date of
original query is after this
date, ColdFusion uses
cached query data. To
use cached data, the
current query must use
same SQL statement,
data source, query name,
user name, and
password. A date/time
object is in the range 100
AD-9999 AD.When
specifying a date value as
a string, enclose it in
quotation marks.

cachedWithin

Optional

A time span, created
using the CreateTimeSp
an function. If the original
query date falls within the
time span, cached query
data is used.
CreateTimeSpan defines
a period from the present,
back. Takes effect only if
query caching is enabled
in the Administrator. To
use cached data, the
current query must use
the same SQL statement,
data source, query name,
user name, and
password.

© 2014 Adobe Systems Incorporated. All rights reserved.

1

Maximum number of rows
to get at a time from
server. Range is 1 to 100.

1170

Adobe ColdFusion Documentation

clientInfo

Optional

debug

Optional

no

yes: lists debug
information on each
statement.
no

fetchClientInfo

Optional

no

If set to yes, returns a
struct with the key-value
pair passed by the last
query.

password

Optional

Overrides password in
data source setup.

result

Optional

Specifies a name for the
structure in which cfstor
edproc returns the
statusCode and
ExecutionTime variables.
If set, this value replaces
cfstoredproc as the
prefix to use when
accessing those variables.
For more information, see
Usage.

returnCode

Optional

no

timeOut

Optional

Number of seconds each
action is permitted to
execute, before returning
an error.
The cumulative time may
exceed this value. For
JDBC statements,
ColdFusion sets this
attribute. For other
drivers, see the driver
documentation.

© 2014 Adobe Systems Incorporated. All rights reserved.

Structure containing
properties of the client to
be set on the database
connection.

yes: populates cfstor
edproc.statusCode
with status code
returned by the stored
procedure.
no

1171

Adobe ColdFusion Documentation

username

Optional

Overrides username in
data source setup.

dbVarName

Optional

When sending the named
parameters to a stored
procedure, this attribute
can be used to specify the
name of the parameter.

To enable dbVarName for
a datasource, add the
system property
coldfusion.dbvarDependa
nts.

For example, if the list of
DSNs that require the
dbVarName support are
dsn1 and dsn2, then add
the JVM flag:

-Dcoldfus
ion.dbvarD
ependants=
{dsn1,
dsn2}

Usage

Use this tag to call a database stored procedure. Within this tag, you code cfprocresult and cfprocparam tags
as follows:
cfprocresult: If the stored procedure returns one or more result sets, code one cfprocresult tag per
result set.
cfprocparam: If the stored procedure uses input or output parameters, code one cfprocparam tag per
parameter, ensuring that you include every parameter in the stored procedure definition.
If you set returnCode = "Yes", this tag sets the variable prefix.statusCode, which holds the status code
for a stored procedure. Status code values vary by DBMS. For the meaning of code values, see your DBMS
documentation. This tag sets the variable prefix.ExecutionTime, which contains the execution time of the
stored procedure, in milliseconds.
The value of prefix is either cfstoredproc or the value specified by the result attribute, if it is set. The re
sult attribute provides a way for stored procedures that are called from multiple pages, possibly at the same
time, to avoid overwriting the results of one call with another. If you set the result attribute to myResult, for

© 2014 Adobe Systems Incorporated. All rights reserved.

1172

Adobe ColdFusion Documentation

example, you would access ExecutionTime as myResult.ExecutionTime. Otherwise, you would
access it as cfstoredproc.ExecutionTime.}}Before implementing this tag, ensure that
you understand stored procedures and their usage. The following examples use a
Sybase stored procedure; for an example of an Oracle 8 or 9 stored procedure,
see cfprocparam.
Example











'#form.title#' inserted into database.The ID is #bookId#.



Insert a new book
Title:



Price:



Publish Date:




© 2014 Adobe Systems Incorporated. All rights reserved.

1173

Adobe ColdFusion Documentation







© 2014 Adobe Systems Incorporated. All rights reserved.

1175

Adobe ColdFusion Documentation

cfswitch
Description

Evaluates a passed expression and passes control to the cfcase tag that matches the expression result. You can,
optionally, code a cfdefaultcase tag, which receives control if there is no matching cfcase tag value.
Category

Flow-control tags
Syntax


one or more cfcase tags
zero or one cfdefaultcase tags


See also

cfcase, cfdefaultcase, cfabort, cfloop, cfbreak, cfexecute, cfexit, cfif, cflocation, cfrethrow
, cfthrow, cftry; cfswitch, cfcase, and cfdefaultcase in the Developing ColdFusion Applications
History

ColdFusion 8: Changed the way the ColdFusion parses  values. Previously,  tags with numeric
value dates did not return expected results{{. For example, }} and  tag now returns the
expected result.
ColdFusion MX: Changed cfdefaultcase tag placement requirements: you can put the cfdefaultcase tag at
any position within a cfswitch statement; it is not required to be the last item.
Attributes

Attribute

Req/Opt

expression

Required

Default

Description
ColdFusion expression
that yields a scalar value.
ColdFusion converts
integers, real numbers,
Booleans, and dates to
numeric values. For
example, true, 1, and 1.0
are all equal.

Usage

This tag requires an end tag. All code within this tag must be within a cfcase or cfdefaultcase tag. Otherwise,

© 2014 Adobe Systems Incorporated. All rights reserved.

1176

Adobe ColdFusion Documentation

ColdFusion throws an error.Use this tag followed by one or more cfcase tags. Optionally, include a cfdefaultca
se tag. This tag selects the matching alternative from the cfcase and cfdefaultcase tags, jumps to the
matching tag, and executes the code between the cfcase start and end tags.
The cfswitch tag provides better performance than a series of cfif/cfelseif tags, and the code is easier to
read.
Example



SELECT Emp_ID, FirstName, LastName, EMail, Phone, Department
FROM Employees

cfswitch Example

Each time the case is fulfilled, the specific information is printed;
if the case is not fulfilled, the default case is output 



#FirstName# #LastName# is in sales




#FirstName# #LastName# is in accounting


 
#FirstName# #LastName# is in administration




#FirstName# #LastName# is not in Sales, Accounting, or
Administration.






#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

1177

Adobe ColdFusion Documentation

Tags t
This section lists tags starting with alphabet T with their description.
cftable
cftextarea
cftextinput
cfthread
cfthrow
cftimer
cftooltip
cftrace
cftransaction
cftree
cftreeitem
cftry

© 2014 Adobe Systems Incorporated. All rights reserved.

1178

Adobe ColdFusion Documentation

cftable
Description

Builds a table in a ColdFusion page. This tag renders data as preformatted text, or, with the HTMLTable attribute, in
an HTML table. If you don't want to write HTML table tag code, or if your data can be presented as preformatted
text, use this tag. Preformatted text (defined in HTML with the 
 and 
 tags) displays text in a
fixed-width font. It displays white space and line breaks exactly as they are written within the pre tags. For more
information, see an HTML reference guide.
To define table column and row characteristics, use the cfcol tag within this tag.
Category

Data output tags
Syntax


...


Note
You can specify this tag's attributes in an attributeCollection attribute whose value is a
structure. Specify the structure name in the attributeCollection attribute and use the tag's
attribute names as structure keys.

See also

cfcol, cfcontent, cflog, cfoutput, cfprocessingdirective; Retrieving data in the Developing
ColdFusion Applications
Attributes

Attribute

Req/Opt

query

Required

© 2014 Adobe Systems Incorporated. All rights reserved.

Default

Description
Name of cfquery from
which to draw data.

1179

Adobe ColdFusion Documentation

border

Optional

Displays a border around
the table. If you use this
attribute (regardless of its
value), ColdFusion
displays a border around
the table.Use this only if
you use the HTMLTable a
ttribute.

colHeaders

Optional

Displays column heads. If
you use this attribute, also
use the cfcol tag heade
r attribute to define them.
If you use this attribute
(regardless of its value),
ColdFusion displays
column heads.

colSpacing

Optional

2

Number of spaces
between columns.

headerLines

Optional

2

Number of lines to use for
table header (the default
leaves one line between
header and first row of
table).

HTMLTable

Optional

Renders data in an HTML
3.0 table.
If you use this attribute
(regardless of its value),
ColdFusion renders data
in an HTML table.

maxRows

Optional

Maximum number of rows
to display in the table.

startRow

Optional

1

The query result row to
put in the first table row.

Usage

This tag aligns table data, sets column widths, and defines column heads. At least one cfcol tag is required within
this tag. Put cfcol and cftable tags adjacent in a page. The only tag that you can nest within this tag is the cfco
l tag. You cannot nest cftable tags.
To display the cfcol header text, specify the cfcol header and the cftable colHeader attribute. If you
specify either attribute without the other, the header does not display and no error is thrown.
Example

© 2014 Adobe Systems Incorporated. All rights reserved.

1180

Adobe ColdFusion Documentation




SELECT Emp_ID, FirstName, LastName, EMail, Phone, Department
FROM Employees



cftable Example




Name/Email"
= "Left"
= 15
"#FirstName# #LastName#">






© 2014 Adobe Systems Incorporated. All rights reserved.

1181

Adobe ColdFusion Documentation

cftextarea
Description

Puts a multiline text entry box in a cfform tag and controls its display characteristics. Optionally, displays a rich text
editor with configurable controls for formatting HTML text.
Category

Forms tags
Syntax

© 2014 Adobe Systems Incorporated. All rights reserved.

1182

Adobe ColdFusion Documentation


text


Some attributes apply to only specific display formats. For details see the Attributes table.

© 2014 Adobe Systems Incorporated. All rights reserved.

1183

Adobe ColdFusion Documentation

Note
You can specify this tag's attributes in an attributeCollection attribute whose value is a
structure. Specify the structure name in the attributeCollection attribute and use the tag's
attribute names as structure keys.

See also

cfajaximport, cfapplet, cfcalendar, cfform, cfformgroup, cfformitem, cfgrid, cfinput, cfselect
, cfslider, cftree; Introduction to Retrieving and Formatting Data and Using Ajax form
controls and features in the Developing ColdFusion Applications
History

ColdFusion 8:
Added support for the bind attribute in HTML format forms, including the bindAttribute, bindOnLoad,
and onBindError attributes.
Added support for tool tips in HTML format, including the sourceForTooltip attribute.
Added support for a rich text editor in HTML format, including the richtext, basepath, fontFormats, fo
ntNames, fontSizes, skin, stylesXML, templatesXML, toolbar, and toolbarOnFocus attributes
and support for the height and width attributes.ColdFusion MX 7: Added this tag.
Attributes

The following table lists attributes that ColdFusion uses directly. In HTML format, the tag also supports all HTML te
xtarea tag attributes that are not on this list, and passes them directly to the browser.
Note
Attributes that are not marked as All or XML are not handled by the skins provided with
ColdFusion. They are, however, included in the generated XML.

Attribute

Req/Opt;Format

name

Required;All

basepath

Optional; HTML

© 2014 Adobe Systems Incorporated. All rights reserved.

Default

Description
Name of the cftextinp
ut control.

/CFIDE/scripts/ajax
/FCKEditor

Path to the directory that
contains the rich text
editor. The editor
configuration files are at
the top level of this
directory.Meaningful only
if the richText attribute
is true.

1184

Adobe ColdFusion Documentation

bind

Optional;Flash,HTML

bindAttribute

Optional;HTML

value

Specifies the HTML tag
attribute whose value is
set by the bind attribute.
You can only specify
attributes in the browser's
HTML DOM tree, not
ColdFusion-specific
attributes. Ignored if there
is no bind attribute.

bindOnLoad

Optional;HTML

no

A Boolean value that
specifies whether to
execute the bind attribute
expression when first
loading the form. Ignored
if there is no bind attribut
e.

disabled

Optional;All

not disabled

Disables user input,
making the control
read-only. To disable
input, specify disabled
without an attribute, or di
sabled="Yes" (or any
ColdFusion positive
Boolean value, such as
True). To enable input,
omit the attribute or
specify disabled="No"
(or any ColdFusion
negative Boolean value,
such as False).

enabled

Optional;Flash

yes

Boolean value that
specifies whether the
control is enabled. A
disabled control appears
in light gray. The inverse
of the disabled attribute.

© 2014 Adobe Systems Incorporated. All rights reserved.

A bind expression that
dynamically sets an
attribute of the control. For
details, see Usage.

1185

Adobe ColdFusion Documentation

fontFormats

Optional; HTML

All valid formats

A comma-separated list of
the font names to display
in the rich text editor
Formats selector. The
formats specify the HTML
tags to apply to typed or
selected text. You can
specify any subset of the
following list:
"p,div,pre,address,h1,h2,h
3,h4,h5,h6".

fontNames

Optional; HTML

All valid font names

A comma-separated list of
the font names to display
in the rich text editor Font
selector. You can specify
any subset of the
following list: "Arial,Comic
Sans MS,Courier
New,Tahoma,Times New
Roman,Verdana".

FontSizes

Optional; HTML

See Description

A comma-separated list of
the font sizes to display in
the rich text editor Size
selector. List entries must
have the format of numeri
c font size/descriptive text.
For example, to display
the text "small font" to
indicate a font size of 1,
specify "1/small font". By
default, the following
values appear in the
selector:
1/xx-small,2/x-small,3/sm
all,4/medium,5/large,6/x-l
arge,7/xx-large.

height

Optional;Flash,HTML

© 2014 Adobe Systems Incorporated. All rights reserved.

In Flash forms, height of
the control, in pixels.
In HTML forms, this
attribute has an effect only
if you specify richtext=
"true"; in this case, it is
the height, in pixels, of the
control, including the
control bar and text box.

1186

Adobe ColdFusion Documentation

html

Optional;Flash

label

Optional;Flash and XML

Label to put beside the
control on a form.

maxLength

Optional;All

The maximum length of
text that can be entered.
ColdFusion uses this
attribute only if you
specify maxlength in the
validate attribute.

message

Optional;All

Message text to display if
validation fails.

onBindError

Optional;HTML

onChange

Optional;All

JavaScript (HTML/XML)
or ActionScript (Flash) to
run when the control
changes due to user
action.

onClick

Optional;HTML and XML

JavaScript to run when
the user clicks the control.

onError

Optional;HTML and XML

Custom JavaScript
function to execute if
validation fails.

© 2014 Adobe Systems Incorporated. All rights reserved.

no

See Description

Boolean value that
specifies whether the text
area contains HTML.

The name of a JavaScript
function to execute if
evaluating a bind
expression results in an
error. The function must
take two attributes: an
HTTP status code and a
message. (The status
code is -1 if the error is
not an HTTP error.)If you
omit this attribute, and
have specified a global
error handler (by using the
ColdFusion.setGloba
lErrorHandler function
), it displays the error
message; otherwise a
default error pop-up
displays.

1187

Adobe ColdFusion Documentation

onKeyDown

Optional;All

JavaScript (HTML/XML)
or ActionScript (Flash)
ActionScript to run when
the user presses a
keyboard key in the
control.

onKeyUp

Optional;All

JavaScript (HTML/XML)
or ActionScript (Flash) to
run when the user
releases a keyboard key
in the control.

onMouseDown

Optional;All

JavaScript (HTML/XML)
or ActionScript (Flash) to
run when the user
releases a mouse button
in the control.

onMouseUp

Optional;All

JavaScript (HTML/XML)
or ActionScript (Flash) to
run when the user
presses a mouse button in
the control.

onValidate

Optional;HTML and XML

Custom JavaScript
function to validate user
input. The JavaScript
DOM form object, input
object, and input object
value are passed to the
function, which must
return True if validation
succeeds, False otherwi
se. If you specify this
attribute, ColdFusion
ignores the validate att
ribute.

© 2014 Adobe Systems Incorporated. All rights reserved.

1188

Adobe ColdFusion Documentation

pattern

Required if {{validate =
"regular_expression"}}HT
ML and XML.

JavaScript regular
expression pattern to
validate input. Omit
leading and trailing
slashes. ColdFusion uses
this attribute only if you
specify regex in the vali
date attribute. For
examples and syntax, see
Building Dynamic Forms
with cfform Tags in the De
veloping ColdFusion
Applications.

range

Optional;All

Minimum and maximum
allowed numeric values.
ColdFusion uses this
attribute only if you
specify range in the vali
date attribute. If you
specify a single number or
a single number followed
by a comma, it is treated
as a minimum, with no
maximum. If you specify a
comma followed by a
number, the maximum is
set to the specified
number, with no minimum.

required

Optional;All

no

richText

Optional; HTML

no

© 2014 Adobe Systems Incorporated. All rights reserved.

yes: the field must
contain text.
no: the field can be
empty.
A Boolean value
specifying whether this
control is a rich text editor
with tool bars to control
the text formatting. For
detailed information on
using the rich text editor,
see Using the rich text
editor in Using Ajax form
controls and features in
the Developing
ColdFusion Applications.

1189

Adobe ColdFusion Documentation

skin

Optional; HTML

sourceForTooltip

Optional; HTML

The URL of a page to
display as a tool tip. The
page can include CFML
and HTML to control the
contents and format, and
the tip can include
images.
If you specify this
attribute, an animated
icon appears with the text
"Loading..." while the tip is
being loaded.

style

Optional;All

In HTML or XML format
forms, ColdFusion passes
the style attribute to the
browser or XML.
In Flash format forms,
must be a style
specification in CSS
format, with the same
syntax and contents as
used in Flex for the
corresponding Flash
element.

© 2014 Adobe Systems Incorporated. All rights reserved.

default

Specifies the skin to be
used for the rich text
editor. By default, the
valid values are default,
silver, and office200
3. You can also create
custom skins that you can
then specify in this
attribute. For more
information, see Using the
rich text editor in Using
Ajax form controls and
features in the Developing
ColdFusion Applications.

1190

Adobe ColdFusion Documentation

stylesXML

Optional; HTML

/CFIDE/scripts/ajax
/FCKEditor/fckstyle
s.xml

The path of the file that
defines the styles in the
rich text editor Styles
selector. Relative paths
start at the directory that
contains the fckeditor.html
file, normally cf_webRoot/
CFIDE/scripts/ajax/FCKed
itor/editor. You can
specify an absolute path
starting at the web root,
such as
/myApps/RTEeditor.mysty
les.xml. For information
on configuring styles, see
Using the rich text editor i
n Using Ajax form controls
and features in the Develo
ping ColdFusion
Applications.

templatesXML

Optional; HTML

/CFIDE/scripts/ajax
/FCKEditor/fcktempl
ates.xml

The path of the file that
defines the templates that
are displayed when you
click the rich text editor
Templates icon. For
pathing details, see styl
esXML. For information on
configuring templates, see
Using the rich text editor i
n the Developing
ColdFusion Applications.

toolbar

Optional; HTML

Default

Specifies the rich text
editor toolbar. By default,
the valid values for this
attribute are: Default, a
complete set of controls,
and Basic, a minimal
configuration. You can
add configurations; for
details see Using the rich
text editor in Using Ajax
form controls and features
in the Developing
ColdFusion Applications.
Note: This attribute's
value is case sensitive.

© 2014 Adobe Systems Incorporated. All rights reserved.

1191

Adobe ColdFusion Documentation

toolbarOnFocus

Optional; HTML

tooltip

Optional; Flash, HTML

Text to display when the
mouse pointer hovers
over the control. Can
include HTML formatting.
Ignored if you specify a s
ourceForTooltip attrib
ute.

validate

Optional;All

The type or types of
validation to perform.
Available validation types
and algorithms depend on
the format. For details,
see the Usage section of
the cfinput tag
reference.

validateAt

Optional;HTML and XML

no

onSubmit

A Boolean value that
specifies whether the rich
text editor toolbar
expands and displays its
controls only when the
rich text editor has the
focus.

How to do the validation;
one or more of the
following:
onSubmit
onServer
onBlur
For Flash format forms,
onSubmit and onBlur
are identical; for both,
validation is done when
the user submits the
form. For multiple
values, use a
comma-delimited list.
For details, see the
Usage section of the cf
input tag reference.

© 2014 Adobe Systems Incorporated. All rights reserved.

1192

Adobe ColdFusion Documentation

value

Optional;All

visible

Optional;Flash

width

Optional;Flash,HTML

wrap

OptionalAll

Initial value to display in
text control. You can
specify an initial value as
an attribute or in the tag
body, but not in both
places. If you specify the
value as an attribute, put
the closing cftextarea t
ag immediately after the
opening cftextarea tag
, with no spaces or line
feeds between, or place a
closing slash at the end of
the opening cftextarea
tag; for example .
yes

Boolean value that
specifies whether to show
the control. Space that
would be occupied by an
invisible control is blank.
The width of the control, in
pixels.
In HTML forms, this
attribute has an effect only
if you specify richtext=
"true".
hard: wraps long lines,
and sends the carriage
return to the server.
off: does not wrap long
lines.
physical: wraps long
lines, and transmits the
text at all wrap points.
soft: wraps long lines,
but does not send the
carriage return to the
server.
virtual: wraps long lines,
but does not send the
carriage return to the
server.

Usage

© 2014 Adobe Systems Incorporated. All rights reserved.

1193

Adobe ColdFusion Documentation

For this tag to work properly in HTML format. the browser must be JavaScript-enabled.
If you put text in the tag body, the control displays all text characters between the cftextarea opening and closing
tags; therefore, if you use line feeds or white space to format your source text, they appear in the control. If the cffo
rm preserveData attribute is "yes", and the form posts back to the same page, the posted value (not the value
of the value attribute) of the cftextinput control is used.
Validation

For a detailed description of the validation attribute and the types of validation supported by ColdFusion, see the
Usage section of the cfinput tag reference. For more details on ColdFusion validation techniques, see Validating
data in the Developing ColdFusion Applications.
Flash form data binding

The bind attribute lets you populate form fields using the contents of other form fields. To specify text from another
Flash form field in a cftextarea bind attribute, use the following format:{sourceTagName.text}For example, the
following line uses the value of the text that the user enters in the from the userName field in the greeting in the
comment text box. The user can change or replace this message with a typed entry.



Enter your name here




HTML form data binding

The bind attribute lets you set any cftextarea attribute dynamically from the value of another form control or by
calling a CFC or JavaScript function. By default it sets the control's value attribute, but you can specify a different
attribute to set by using the bindAttribute attribute. For more information on binding, see Binding data to form
fields in the Developing ColdFusion Applications.
Example

This example has two cftextarea controls. When you submit the form, ColdFusion copies the text from the first
control into the second. The onBlur maxlength validation prevents you from entering more than 100 characters. The
> character that closes the cftextarea opening tag, the text in the tag body, and the cftextarea closing tag are
on a single line to ensure that only the desired text displays, but the line is split in this example for formatting
purposes.

© 2014 Adobe Systems Incorporated. All rights reserved.

1194

Adobe ColdFusion Documentation

cftextarea Example





Replace this text. Maximum length is 100 Characters, and this text is
currently 99 characters long.







© 2014 Adobe Systems Incorporated. All rights reserved.

1195

Adobe ColdFusion Documentation

cftextinput
Description

Puts a single-line text entry box in a cfform tag and controls its display characteristics. This tag is deprecated, and
is not supported in XML format forms. In its place, you must use a cfinput or cftextarea tag and use a
cascading style sheet (CSS) to specify the text style characteristics.
History

ColdFusion MX 7: This tag is deprecated. In later releases it might not work, and might cause an error.
ColdFusion MX 6.1: Changed the validate = "creditcard" option requirements: the text entry must have 13-16
digits.

© 2014 Adobe Systems Incorporated. All rights reserved.

1196

Adobe ColdFusion Documentation

cfthread
Description

The cfthread tag enables you to create threads, independent streams of code execution, in your ColdFusion
application. You use this tag to run or end a thread, temporarily stop thread execution, or join together multiple
threads.
Category

Application framework tags
Syntax

join

run

Thread code

sleep

terminate


For all actions except run, the cfthread tag must have an empty body and be followed immediately by a  end tag, or must have no end tag and have a slash before the tag closure, as in .

© 2014 Adobe Systems Incorporated. All rights reserved.

1197

Adobe ColdFusion Documentation

Note
You can specify this tag's attributes in an attributeCollection attribute whose value is a
structure. Specify the structure name in the attributeCollection attribute and use the tag's
attribute names as structure keys.

See also

Sleep, Using ColdFusion Threads in the Developing ColdFusion Applications
History

ColdFusion 8: Added this tag
Attributes

Attribute

Req/Opt

Default

Applies to

Description

action

Optional

run

All

The action to take,
one of the following
values:
join: Makes the
current thread
wait until the
thread or threads
specified in the na
me attribute
complete
processing, or
until the period
specified in the ti
meout attribute
passes, before
continuing
processing. If you
don't specify a
timeout and the
thread you are
joining to doesn't
finish, the current
thread also
cannot finish
processing.

© 2014 Adobe Systems Incorporated. All rights reserved.

1198

Adobe ColdFusion Documentation

run: Creates a
thread and starts
it processing.
Code in the cfth
read tag body
runs
simultaneously
and independently
of page-level code
and code in other
cfthread tags.
sleep: Suspends
the current
thread's
processing for the
time specified by
the duration att
ribute. Equivalent
to the Sleep func
tion.
terminate:
Stops processing
of the thread
specified in the na
me attribute. If you
terminate a
thread, the thread
scope includes an
ERROR metadata
structure with
information about
the termination.
duration

Required

© 2014 Adobe Systems Incorporated. All rights reserved.

sleep

The number of
milliseconds for
which to suspend
thread processing.

1199

Adobe ColdFusion Documentation

name

priority

Optional, Required,
if action =
"join" or
"terminate"

Optional

join run termina
te

The name of the
thread to which the
action applies:
terminate: The
name of the
thread to stop.
join: The name
of the thread or
threads to join to
the current thread.
To specify
multiple threads,
use a
comma-delimited
list.
run: The name to
use to identify the
thread being
created.

NORMAL

run

The priority level at
which to run the
thread. The
following values are
valid:
HIGH
LOW
NORMAL
Higher priority
threads get more
processing time
than lower priority
threads.
Page-level code,
the code that is
outside of cfthr
ead tags, always
has NORMAL priori
ty.

© 2014 Adobe Systems Incorporated. All rights reserved.

1200

Adobe ColdFusion Documentation

Optional

timeout

0

join

The number of
milliseconds that the
current thread waits
for the thread or
threads being joined
to finish. If any
thread does not
finish by the
specified time, the
current thread
proceeds.
If the attribute value
is 0, the following
action occurs:
The current
thread continues
waiting until all
joining threads
finish.
If the current
thread is the page
thread, the page
continues waiting
until the threads
are joined, even if
you specify a
page time-out.

Usage

Page-level code (code outside any cfthread tags) executes in its own thread, referred to as the page thread. Only
the page thread can create other threads. A thread that you create cannot create a child thread.
Note
If a thread never completes processing (is hung), it continues to occupy system resources. You
can use the ColdFusion Sever Monitor to check for and terminate hung threads.

ColdFusion makes a complete (deep) copy of all the attribute variables before passing them to the thread, so the
values of the variables inside the thread are independent of the values of any corresponding variables in other
threads, including the page thread. Thus, the values passed to threads are thread safe because the attribute values
cannot be changed by any other thread.
Thread scopes

Each thread has three special scopes:
The thread-local scope is an implicit scope that contains variables that are available only to the thread, and
exist only for the life of the thread.
The Thread scope is available to the page and to all other threads started from the page. Its data remains
available until the page and all threads started from the page finish, even if the page finishes before the
threads complete processing.

© 2014 Adobe Systems Incorporated. All rights reserved.

1201

Adobe ColdFusion Documentation

The Attributes scope contains attributes that are passed to the scope, and is available only within the thread
and only for the life of the thread.
For detailed information about using ColdFusion scopes in threads, see Using ColdFusion Threads in the Dev
eloping ColdFusion Applications.All threads in a page share a single Variables scope, so you can use it for
data that is common across all threads. You must be careful to lock access to the variables, if necessary, to
prevent deadlocks or race conditions between threads.
Note
When ColdFusion uses a connector to access the web server, after the page gets
completed, the CGI and Request scopes are not accessible to threads that you create by
using the cfthread tag. This limitation does not apply if you use the integrated web
server or if you run ColdFusion as a J2EE application.

Metadata variables

The thread scope contains the following variables that provide information about the thread (metadata):
Variable

Description

ElapsedTime

The amount of processor time that was spent handling
the thread.

Error

The structure that is generated if an error occurs during
thread execution. The structure contains the keys that
you can access in a cfcatch tag.
If an error occurs in a thread, page-level processing is
not affected, and ColdFusion does not generate an
error message. The thread with the error terminates
and the page-level code or other threads can get the
error information from the Error field and handle the
error appropriately. For detailed information, see Handli
ng ColdFusion thread errors in Working with threads in
the Developing ColdFusion Applications.

Name

The thread name.

Output

Output that is generated by the thread. A thread cannot
display output; page-level code must use this variable
to display thread results. For detailed information, see
Handling thread output in Working with threads in the D
eveloping ColdFusion Applications.

Priority

The thread processing priority, as specified in the cfth
read priority attribute. The following values are
valid:
HIGH
LOW
NORMAL

© 2014 Adobe Systems Incorporated. All rights reserved.

1202

Adobe ColdFusion Documentation

Starttime

The time at which the thread began processing, in
ColdFusion date-time format.

Status

The current status of the thread; one of the following
values:
NOT_STARTED: The thread has been queued but is
not processing yet.
RUNNNG: The thread is running normally.
TERMINATED: The thread stopped running due to a c
fthread tag with a terminate action, an error, or
an administrator action.
COMPLETED: The thread ended normally.
WAITING: The thread has executed a cfthread ta
g with action="join", but one or more threads
being joined has not completed.

Example

The following example uses three threads to get the results of three RSS feeds. The user must submit the form with
all three feeds specified. The application joins the threads with a time-out of 6 seconds, and displays the feed titles
and the individual item titles as links.

© 2014 Adobe Systems Incorporated. All rights reserved.

1203

Adobe ColdFusion Documentation













This example requires three feeds.

Click the Back button and try again.











#feedResult.myProps.title#

#TITLE#






Enter three RSS Feeds









© 2014 Adobe Systems Incorporated. All rights reserved.

1204

Adobe ColdFusion Documentation

cfthrow
Description

Throws a developer-specified exception, which can be caught with a cfcatch tag that has any of the following typ
e attribute options:
type = "custom_type"
type = "Application"
type = "Any"
Category

Exception handling tags, Flow-control tags
Syntax


OR


Note
You can specify this tag's attributes in an attributeCollection attribute whose value is a
structure. Specify the structure name in the attributeCollection attribute and use the tag's
attribute names as structure keys.

See also

cferror, cfrethrow, cftry, onError; Handling Errors in the Developing ColdFusion Applications
History

ColdFusion MX: Changed thrown exceptions: this tag can throw ColdFusion component method exceptions.
Attributes

Attribute

Req/Opt

© 2014 Adobe Systems Incorporated. All rights reserved.

Default

Description

1205

Adobe ColdFusion Documentation

detail

Optional

Description of the event.
ColdFusion appends error
position to description;
server uses this
parameter if an error is
not caught by your code.

errorCode

Optional

A custom error code that
you supply.

extendedInfo

Optional

A custom error code that
you supply.

message

Optional

Message that describes
exception event.

object

Optional

Requires the value of the
cfobject tag name attrib
ute.
Throws a Java exception
from a CFML tag.
This attribute is mutually
exclusive with all other
attributes of this tag.

type

Optional

Application

A custom type
Application
Do not enter another
predefined type; types
are not generated by
ColdFusion
applications. If you
specify Application, you
need not specify a type
for cfcatch.

Usage

Use this tag within a cftry block, to throw an error. The cfcatch block can access accompanying information, as
follows:
Message, with cfcatch.message
Detail, with cfcatch.detail
Error code, with cfcatch.errorcode To get more information, use cfcatch.tagContext. This array
shows where control switches from one page to another in the tag stack (for example, cfinclude, cfmodul
e).
To display the information displayed by tagContext variable, select the "Enable Robust Exception
Information" option on the Debugging & Logging > Debug Output Settings page of the ColdFusion
Administrator.

© 2014 Adobe Systems Incorporated. All rights reserved.

1206

Adobe ColdFusion Documentation

To use this tag with the object parameter, first use a cfobject tag that specifies a valid Java exception
class. For example, the following cfobjecttag defines an object, obj, of the exception class myException
(which you must create in Java):



If your exception class has constructors that take parameters, such as a message, you can use the special i
nitmethod to invoke the constructor, as in the following line. If you do not need to specify any constructor
attributes, you can omit this step.



You can then use the, the cfthrowstatement to throw the exception as follows:



For more information on using Java objects in ColdFusion, see Integrating JEE and Java Elements in CFML
Applications in the Developing ColdFusion Applications.
Example

© 2014 Adobe Systems Incorporated. All rights reserved.

1207

Adobe ColdFusion Documentation

cfthrow Example










You've Thrown an Error


#cfcatch.message#
The contents of the tag stack are:



#i# #sCurrent["ID"]#
(#sCurrent["LINE"]#,#sCurrent["COLUMN"]#)
#sCurrent["TEMPLATE"]#





The following example shows how to throw an exception from a component method:





SELECT LASTNAME, FIRSTNAME, EMAIL
FROM tblEmployees
WHERE LASTNAME LIKE '#arguments.lastName#'









For an explanation of the example and more information, see Building and Using ColdFusion Components in the De
veloping ColdFusion Applications.

© 2014 Adobe Systems Incorporated. All rights reserved.

1208

Adobe ColdFusion Documentation

cftimer
Description

Displays execution time for a specified section of CFML code. ColdFusion displays the timing information along with
any output produced by the timed code.
Note
To permit this tag to execute, enable the Enable Debugging and the Timer Information options on
the Debugging Settings page in the ColdFusion Administrator. Also, the IP address of the
machine that runs ColdFusion must be added to the list of debugging IP addresses in the
Debugging IP Addresses page if the request is sent by a remote machine. If the request is from a
localhost, the IP address 127.0.0.1 must be present in the list of debugging IP addresses.

Category

Debugging tags
Syntax


CFML statement(s)


Note
You can specify this tag's attributes in an attributeCollection attribute whose value is a
structure. Specify the structure name in the attributeCollection attribute and use the tag's
attribute names as structure keys.

See also

cfdump, cftrace; Debugging and Troubleshooting Applications in the Developing ColdFusion
Applications
History

ColdFusion MX 7: Added this tag.
Attributes

Attribute

Req/Opt

Default

Description

label

Optional

" "

Label to display with
timing information.

© 2014 Adobe Systems Incorporated. All rights reserved.

1209

Adobe ColdFusion Documentation

Optional

type

debug

inline: displays timing
information inline,
following the resulting
HTML.
outline: displays
timing information and
also displays a line
around the output
produced by the timed
code. The browser must
support the FIELDSET
tag to display the
outline.
comment: displays
timing information in an
HTML comment in the
format . The
default label is cftime
r.
debug: displays timing
information in the debug
output under the
heading CFTimer
Times.

Usage

Use this tag to determine how long it takes for a block of code to execute. You can nest cftimer tags.
This tag is useful for debugging CFML code during application development. In production, you can leave cftimer
tags in your code as long as you have disabled the debugging option in the ColdFusion Administrator.
Example

...



SELECT *
FROM Employees


#lastname#, #firstname#








SELECT *
FROM CourseList

© 2014 Adobe Systems Incorporated. All rights reserved.

1210

Adobe ColdFusion Documentation





#Course_ID#
#CorName#
#CorLevel#









SELECT *
FROM Parks

Select View > Source to see timing information



#Parkname#









SELECT *
FROM Departments

Scroll down to CFTimer Times heading to see timing information



#Dept_ID#
#Dept_Name#




© 2014 Adobe Systems Incorporated. All rights reserved.

1211

Adobe ColdFusion Documentation


...

© 2014 Adobe Systems Incorporated. All rights reserved.

1212

Adobe ColdFusion Documentation

cftooltip
Description

Specifies tool tip text that displays when the user hovers the mouse pointer over the elements in the tag body. This
tag does not require a form and is not used inside Flash forms.
Category

Display management tags
Syntax


Display tags


This tag must have an end tag.
Note
You can specify this tag's attribute in an attributeCollection attribute whose value is a
structure. Specify the structure name in the attributeCollection attribute and use the tag's
attribute name as structure key.

See also

cfajaximport, Using Ajax User Interface Components and Features in the Developing ColdFusion
Applications
History

ColdFusion 8: Added this tag
Attributes

Attribute

Req/Opt

© 2014 Adobe Systems Incorporated. All rights reserved.

Default

Description

1213

Adobe ColdFusion Documentation

autoDismissDelay

Optional

5000

The number of
milliseconds between the
time when the user moves
the mouse pointer over
the component (and
leaves it there) and when
the tool tip disappears.

hideDelay

Optional

250

The number of
milliseconds to delay
between the time when
the user moves the
mouse pointer away from
the component and when
the tool tip disappears.

preventOverlap

Optional

true

A Boolean value
specifying whether to
prevent the tool tip from
overlapping the
component that it
describes.

showDelay

Optional

200

The number of
milliseconds to delay
between the time when
the user moves the
mouse over the
component and when the
tool tip appears.

sourceForTooltip

Optional

The URL of a page with
the tool tip contents. The
page can include HTML
markup to control the
format, and the tip can
include images.
If you specify this
attribute, an animated
icon appears with the text
"Loading..." while the tip is
being loaded.

style

Optional

A CSS style specification
for the tooltip. Use this
attribute to set the width,
text color, background
color, padding, and other
style properties.

© 2014 Adobe Systems Incorporated. All rights reserved.

1214

Adobe ColdFusion Documentation

tooltip

Optional

Tip text to display. The
text can include HTML
formatting.
Ignored if you specify a s
ourceForTooltip attrib
ute.

Usage

Specify a tooltip or a sourceForTooltip attribute; otherwise, this tag has no effect.
If you specify the path to a CFML page in the sourceForTooltip attribute, ColdFusion processes the page and
uses its output in the tip text. You can therefore use CFML programming, in addition to HTML formatting, to control
the contents and appearance of the tip text. You must use the cftooltip tag for text and simple components, such
as images, not for complex Ajax components such as windows, pods, or layout areas. If you use the cftooltip ta
g with complex components, you might get unexpected behavior; for example, the tool tip might overlap window
contents, even if you specify the preventoverlap attribute.
You can nest tool tips within the cfinput, cfgrid, and cfform tags, although this may result in multiple tool tips
obscuring one another.
Example

The following simple example can dynamically display different tool-tip text based on the value of the theItem varia
ble on the main CFML page.
The main CFML page:







Try this one!




The tiptext.cfm page could have a single CFML tag:

 Click to find more about #URL.itemid# 

© 2014 Adobe Systems Incorporated. All rights reserved.

1215

Adobe ColdFusion Documentation

cftrace
Description

Displays and logs debugging data about the state of an application at the time the cftrace tag executes. Tracks
run-time logic flow, variable values, and execution time. Displays output at the end of the request or in the
debugging section at the end of the request; or, in Dreamweaver MX and later, in the Server Debug tab of the
Results window. ColdFusion logs cftrace output to the file logs\cftrace.log, in the ColdFusion installation directory.
Note
To permit this tag to execute, enable debugging in the ColdFusion Administrator. Optionally, to
report trace summaries, enable the Trace section

Category

Debugging tags, Variable manipulation tags
Syntax




Note
You can specify this tag's attributes in an attributeCollection attribute whose value is a
structure. Specify the structure name in the attributeCollection attribute and use the tag's
attribute names as structure keys.

See also

cfdump, cferror, cfrethrow, cftimer, cftry; Debugging and Troubleshooting Applications in the
Developing ColdFusion Applications
History

ColdFusion MX: Added this tag.
Attributes

Attribute

Req/Opt

© 2014 Adobe Systems Incorporated. All rights reserved.

Default

Description

1216

Adobe ColdFusion Documentation

abort

Optional

category

Optional

inline

Optional

text

Optional

type

Optional

no

yes: calls a cfabort t
ag when the tag is
executed.
no
User-defined string that
identifies trace groups.

no

yes: displays trace
code inline on the page
in the location of the cf
trace tag, in addition
to the debugging
information output.
no
User-defined string, which
can include simple
variables, but not complex
variables such as arrays.
Outputs to the cflog tex
t attribute.

Information

Corresponds to the cflo
g type attribute; displays
an appropriate icon:
Information
Warning
Error
Fatal Information

var

Optional

The name of a simple or
complex variable to
display. Useful for
displaying a temporary
value, or a value that does
not display on any CFM
page.

Usage

You cannot put application code within this tag. (This avoids problems that can occur if you disable debugging.) This
tag is useful for debugging CFML code during application development. You can display cftrace tag output in the
following ways:
As a section in the debugging output
Inline in an application page, and as a section in debugging output. If you specify inline tracing, ColdFusion
flushes all output up to the cftrace tag, and displays the trace output when it encounters the tag.
The following is an example of a log file entry:

© 2014 Adobe Systems Incorporated. All rights reserved.

1217

Adobe ColdFusion Documentation

"Information","web-4","04/08/02","23:21:30", ,"[30 ms (1st trace)]
[C:\CFusion\wwwroot\generic.cfm @ line: 9] [thisPage = /generic.cfm]"
"Information","web-0","04/08/02","23:58:58", ,"[5187 ms (10)]
[C:\CFusion\wwwroot\generic.cfm @ line: 14] - [category]
[thisPage = /generic.cfm] [ABORTED] thisPage "

For a complex variable, ColdFusion lists the variable name and the number of elements in the object; it does
not log the contents of the variable.
Example

The following example traces a FORM variable that is evaluated by a cfif block:



Congratulations, you're a winner!

Sorry, you lost!


© 2014 Adobe Systems Incorporated. All rights reserved.

1218

Adobe ColdFusion Documentation

cftransaction
Description

For enterprise database management systems that support transaction processing, instructs the database
management system to treat multiple database operations as a single transaction. Provides database commit and
rollback processing. See the documentation for your database management system to determine whether it
supports SQL transaction processing.
Category

Database manipulation tags
Syntax




Note
You can specify this tag's attributes in an attributeCollection attribute whose value is a
structure. Specify the structure name in the attributeCollection attribute and use the tag's
attribute names as structure keys.

See also

cfinsert, cfprocparam, cfprocresult, cfquery, cfqueryparam, cfstoredproc, cfupdate; Commits,
rollbacks, and transactions and Tags as functions and operators in Developing ColdFusion Applications
History

ColdFusion 8: Added the setsavepoint value to the action attribute. Added the savepoint attribute.
Attributes

Attribute

Req/Opt

Default

action

Optional

begin

© 2014 Adobe Systems Incorporated. All rights reserved.

Description
begin: The start of the
block of code to
execute.
commit: Commits a
pending transaction.
rollback: Rolls back
a pending transaction.
setsavepoint: Saves
a specific state within a
transaction

1219

Adobe ColdFusion Documentation

isolation

Optional

Isolation level, which
indicates which type of
read can occur during the
execution of concurrent
SQL transactions. The
possible read actions
include dirty read, in
which a second SQL
transaction reads a row
before the first SQL
transaction executes a
COMMIT; non-repeatable
read, in which a SQL
transaction reads a row
and then a second SQL
transaction modifies or
deletes the row and
executes a COMMIT; and
phantom, in which a SQL
transaction reads rows
that meet search criteria,
a second SQL transaction
then generates at least
one row that meets the
first transaction's search
criteria, and then the first
transaction repeats the
search, resulting in a
different result set.
read_uncommitted:
Allows dirty read,
non-repeatable read,
and phantom
read_committed:
Allows non-repeatable
read and phantom.
Does not allow dirty
read.
repeatable_read:
Allows phantom. Does
not allow dirty read or
non-repeatable read.
serializable: Does
not allow dirty read,
non-repeatable read, or
phantom.

© 2014 Adobe Systems Incorporated. All rights reserved.

1220

Adobe ColdFusion Documentation

savepoint

Optional

nested

Optional

The name of the
savepoint in the
transaction. Setting
savepoints lets you roll
back portions of a
transaction. For example,
if your transaction
includes an insert, an
update, and a delete, and
you set a savepoint after
the update, you can roll
back the transaction to
exclude the delete.
true

This attribute specifies
whether the cftransaction
tag can be nested inside
another cftransaction tag.
If the attribute value is
false and there is a parent
cftransaction tag,
ColdFusion generates an
error.

Usage

If you do not specify a value for the action attribute, automatic transaction processing proceeds as follows:
If the cfquery operations within the transaction block complete without an error, the transaction is
committed.
If a cfquery tag generates an error within a cftransaction block, all cfquery operations in the
transaction roll back.
If you do not specify a value for the isolation attribute, ColdFusion uses the default isolation level for the
associated database.By using CFML error handling and the action attribute, however, you can explicitly
control whether a transaction is committed or rolled back, based on the success or failure of the database
query. In a transaction block, you can do the following:
Commit a database transaction by nesting the  tag in the block.
Roll back a transaction by nesting the  tag in the block.(In
these examples, the slash is an alternate syntax that is the equivalent of an end tag.)In a transaction block,
you can write queries to more than one database, but you must commit or roll back a transaction to one
database before writing a query to another. To control how the database engine performs locking during the
transaction, use the isolation attribute. The cftransaction tag does not work as expected if you use
the cfthread tag in it to make query calls.
You can now nest cftransaction tags. Typically, ColdFusion 9 does not support nested transactions, but you
can embed one cftransaction tag inside another. If you nest these tags, only the outermost cftransaction tag
takes effect.
This feature lets you write functions that must run in a transaction without considering whether the function is
called by code that is inside a cftransaction tag. Use a cftransaction tag in the function. If the calling code is in
a transaction, the tag has no effect. If the calling code is not in a transaction, the tag starts the transaction.
The following code shows nested transaction tags.

© 2014 Adobe Systems Incorporated. All rights reserved.

1221

Adobe ColdFusion Documentation



insert into region(regionid, regiondescription) values('111', 'YPR')



update region set regiondescription = 'new' where regionid='111'




Note
In a realistic situation, the second cftransaction and cfquery can be written in a CFC that
are, in turn, called by the first cftransaction and cfquery by passing the regionid value.

Example

The cftransaction tag can be used to group multiple queries that use
the cfquery tag into one business event. Changes to data that is requested
by the queries are not committed to the datasource until all actions within
the transaction block have executed successfully.
This a view-only example.


You can set savepoints at the completion of insert, update, and delete actions of a transaction. You then use error
handling logic to determine whether it is necessary to roll back to a previous savepoint.
Example

© 2014 Adobe Systems Incorporated. All rights reserved.

1222

Adobe ColdFusion Documentation


from a bank account. The withdrawal amounts are stored --->
in an array. --->
There is a CFC named bank.cfc whose contains appear --->
after the example. --->




















© 2014 Adobe Systems Incorporated. All rights reserved.

1223

Adobe ColdFusion Documentation

© 2014 Adobe Systems Incorporated. All rights reserved.

1224

Adobe ColdFusion Documentation

cftree
Description

Inserts a tree control in a form. Validates user selections. Used within a cfform tag block. Use a ColdFusion query
to supply data to the tree.
Category

Forms tags
Syntax


onBlur="ActionScript to invoke"
onChange="ActionScript to invoke"
onError="text"
onFocus="Actionscript to invoke"
onValidate="script name"
required="yes|no"
style= "style specification"
tooltip="text"
visible="yes|no"
vScroll="yes|no"
vSpace="integer"
width="integer">


Note
You can specify this tag's attributes in an attributeCollection attribute whose value is a
structure. Specify the structure name in the attributeCollection attribute and use the tag's
attribute names as structure keys.

© 2014 Adobe Systems Incorporated. All rights reserved.

1225

Adobe ColdFusion Documentation
See also

cfajaximport, cfapplet, cfcalendar, cfform, cfformgroup, cfformitem, cfgrid, cfinput, cfselect
, cfslider, cftextarea, cftreeitem; Working with action pages ,Building tree controls with
the cftree tag ,and Using HTML trees in the Developing ColdFusion Applications
History

ColdFusion 8: Added support for Ajax based HTML trees, including the cache attribute and the html value for for
mat attribute.
ColdFusion MX7.01: Added support for onBlur and onFocus events.
ColdFusion MX 7:
Added the format attribute and support for generating Flash and XML and object output.
Added enabled, onChange, style, tooltip, and visible attributes (Flash format only).ColdFusion MX:
Changed behavior: ColdFusion renders a tree control regardless of whether there are any treeitems within
it.
Attributes

Note
In XML format, ColdFusion passes all attributes to the XML. The supplied XSLT skins do not
handle or display XML format trees, but do display applet and Flash format trees.

Attribute

Req/OptFormat

name

Required;All

align

Optional;Applet, object

appendKey

Optional;All

© 2014 Adobe Systems Incorporated. All rights reserved.

Default

Description
Name for a tree control.
top
left
bottom
baseline
texttop
absbottom
middle
absmiddle
right

yes

yes: if you use cftree
item href attributes,
ColdFusion appends a
CFTREEITEMKEY
query string variable
with the value of the
selected tree item to the
cfform action URL.
no: does not append
the tree item value to
the URL.

1226

Adobe ColdFusion Documentation

bold

Optional;Applet, Flash,
HTML

no

yes: displays tree
control text in bold.
no

border

Optional;Applet, object

yes

yes: displays a border
around the tree control.
no

cache

Optional;HTML

yes

Applies only if the tree's
child treeitem tag uses
a bind expression. A
Boolean value that
specifies whether to get
new data each time the
user expands tree nodes,
as follows:
yes: fetches a node's
child items only once,
when the node is first
expanded
no: fetches child items
each time the node is
expanded.

completePath

Optional;Applet, HTML,
object

© 2014 Adobe Systems Incorporated. All rights reserved.

no

yes: starts the Form.tre
ename.path variable
with the root of the tree
path when cftree is
submitted.
no: omits the root level
from the Form.treenam
e.path variable; the
value starts with the first
child node in the tree.
For the preserveData
attribute of cfform to
work with the tree, set
this attribute to yes. For
tree items populated by
a query, if you use the c
ftreeitem queryasr
oot attribute to specify
a root name, that value
is returned. If you do
not specify a root name,
ColdFusion returns the
query name.

1227

Adobe ColdFusion Documentation

delimiter

Optional;All

{{\\\\}}

Character to separate
elements in the Forms.tre
ename.path variable of
the action page.

enabled

Optional;Flash

yes

Flash format only:
Boolean value that
specifies whether the
control is enabled. A
disabled control appears
in light gray.

font

Optional;Applet, HTML

Font name for text in the
tree control.

fontSize

Optional;Applet, Flash,
HTML

Font size for text in the
tree control, in pixels.

format

Optional;All

applet

height

Optional;Applet, Flash

320(applet only)

© 2014 Adobe Systems Incorporated. All rights reserved.

applet: displays the
tree using a Java applet
in the browser.
flash: displays the
tree using a Flash
control
html: displays the tree
uses Ajax-based HTML
object: returns the
tree as a ColdFusion
structure with the name
specified by the name at
tribute, For details of
the structure contents,
see the section object
format.
xml: generates an XML
representation of the
tree. In XML format
forms, includes the
generated XML in the
form. In HTML format
forms, puts the XML in
a string variable with
the name specified by
the name attribute.
Tree control height, in
pixels. If you omit this
attribute in Flash format,
Flash automatically sizes
the tree.

1228

Adobe ColdFusion Documentation

highlightHref

Optional;Applet, Object

yes

yes: highlights as a link
the displayed value for
any cftreeitem tag
that specifies an href a
ttribute.
no: disables
highlighting.

hScroll

Optional;Applet, object

yes

yes: permits horizontal
scrolling.
no

hSpace

Optional;Applet

italic

Optional;Applet, Flash,
HTML

label

Optional;HTML,

lookAndFeel

Optional;Applet, object

message

Optional;Applet, HTML

© 2014 Adobe Systems Incorporated. All rights reserved.

Horizontal spacing to left
and right of tree control, in
pixels.
no

yes: displays tree
control text in italics.
no

windows

motif: renders the tree
in Motif style.
windows: renders the
tree in Windows style.
metal: renders the tree
in Java Swing style.
If the platform does not
support a style option,
the tag uses the default
style for the platform.
Message to display if
validation fails.

1229

Adobe ColdFusion Documentation

notSupported

Optional;Applet

onBlur

Optional;Flash

ActionScript to run when
the tree loses focus.

onChange

Optional;Flash

ActionScript to run when
the control changes due
to user action.
If you specify an
onChange event handler,
the Form scope of the
ColdFusion action page
does not automatically get
information about selected
items. The ActionScript
onChange event handler
must handle all changes
and selections.

onError

Optional;Applet, HTML

A JavaScript function to
run if validation fails.

onFocus

Optional;Flash

ActionScript to run when
the tree gets focus. The
JavaScript DOM form
object, value of the name
attribute, value that failed
validation, and any error
text specified by the mess
age attribute are passed
to the method.

© 2014 Adobe Systems Incorporated. All rights reserved.

See Description

Text to display if a page
that contains a Java
applet-based cfform con
trol is opened by a
browser that does not
support Java or has Java
support disabled, for
example;" Browser
must support Java
to view ColdFusion Jav
a
Applets"}}Defau
lt
message:{{Browse
r must support Java
to 
view ColdFusio
n Java Applets!

1230

Adobe ColdFusion Documentation

onValidate

Optional;Applet, HTML

required

Optional;Applet, Flash,
HTML

style

Optional;Flash, HTML

Must be a style
specification in CSS
format. In HTML format,
this attribute corresponds
to the value of an HTML s
tyle attribute. In Flash
format, use the same
syntax and contents as
used in Flex for the
corresponding Flash
element.

tooltip

Optional;Flash

Flash format only: Text to
display when the mouse
pointer hovers over the
control.

value

Optional;HTML,

visible

Optional;Flash

yes

Flash format only:
Boolean value that
specifies whether to show
the control. Space that
would be occupied by an
invisible control is blank.

vScroll

Optional;Applet, object

yes

yes: permits vertical
scrolling.
no

vSpace

Optional;Applet

© 2014 Adobe Systems Incorporated. All rights reserved.

JavaScript function to
validate user input. The
JavaScript DOM form
object, input object, and
input object value are
passed to the specified
routine, which must return
true if validation
succeeds; false,
otherwise.
no

yes: users must select
an item in the tree
control.
no

Vertical margin above and
below tree control, in
pixels.

1231

Adobe ColdFusion Documentation

Optional;Applet, Flash

width

200 (applet only)

Tree control width, in
pixels. If you omit this
attribute in Flash format,
Flash automatically sizes
the tree.

Note
All attributes are passed to the XML generated in XML format, but no ColdFusion skin interprets
cftree XML.

Usage

This tag must be in a cfform tag block. The applet format tree requires the client to download a Java applet. Also, if
the client does not have an up-to-date Java plug-in installed, the system might also have to download an updated
Java plug-in to display an applet format tree. The Flash format tree uses a Flash control, and can be embedded in
an HTML format cfform tag. For this tag to work properly in Flash, HTML, or applet format, the browser must also
be JavaScript-enabled.
Note
If you specify Flash format for this tag in an HTML format form, and you do not specify height a
nd width attributes, Flash takes up more than the remaining visible area on the screen. If any
other output follows the tree, including any form controls, users must scroll to see it. Therefore, if
you follow a Flash tree in an HTML form with additional output, specify height and width value
s.

If the following conditions are true, a user's selection from query data that populates this tag's options continues to
display after the user submits the form:
The cfform preserveData attribute is set to "yes"
The cfform action attribute posts to the same page as the form itself (this is the default), or the action
page has a form that contains controls with the same names as corresponding controls on the user entry
formFor more information, see the cfform tag entry.
Form variables

When you select a tree item and submit the form that contains the tree, ColdFusion creates a structure with two
variables in the action page Form scope. The structure name is the tree name. The following table lists the fields:
Field

Value

path

The path through the tree to the selected node, in the
form [root]node_1_node_2_\.... In applet format, the
path includes the root node only if the completePath
attribute is true. In Flash format, the path always
includes the root node.

node

The value of the selected tree node.

object format

© 2014 Adobe Systems Incorporated. All rights reserved.

1232

Adobe ColdFusion Documentation

If you specify object in the format attribute, ColdFusion returns the tree as a ColdFusion structure, and does not
send the tree to the browser. You can, for example, loop over the structure to populate a menu, generate
"breadcrumb" links for page navigation, or create a DHTML tree.
Note
If you specify an object format tree in an XML format form, ColdFusion does not generate the
tree.

The structure variable name is specified by the cftree name attribute. The top level of the structure has two types
of entries:
Attribute settings
A children array
Attribute settings

The structure has top-level entries with the values of the following cftree attributes:
align

completePath

highlightHref

lookAndFeel

appendKey

delimiter

hScroll

name

bold

fontWeight

italic

vscroll

border

Children array

The top-level children entry is an array of items entries. Each item has the following entries:
Field

Value

children

This item's child items; an array of item structures.

display

Tree item label, as determined by the cftreeitem di
splay attribute.

expand

Whether to expand the item to display any children;
value of cftreeitem expand attribute.

href

The URL to link to when the user selects the item;
value of the cftreeitem href attribute.

img

The tree image icon Image to display as an icon for the
tree item; value of cftreeitem img attribute. You can
use the img attribute to display custom icons only in
the Applet version; not in the Flash version.

© 2014 Adobe Systems Incorporated. All rights reserved.

1233

Adobe ColdFusion Documentation

imgOpen

Image to display when the tree item is open
(expanded); value of cftreeitem imgopen attribute.

parent

Value of this item's parent item in the tree.

path

The node path from the tree root to the current
element.

queryAsRoot

Whether the query is the root of the item; value of cftr
eeitem queryAsRoot attribute.

target

The link target, such as _blank; value of the item's cft
reeitem target attribute.

value

The item's value, as determined by the cftreeitem v
alue attribute.

Example

The following example creates a tree that shows available courses from the CourseList table of the cfdocexamples
database, and puts each department's courses in a folder. This example is displayed in Flash and uses the
Departments list to get department names.


SELECT d.dept_name, c.course_id, c.CorName, c.CorLevel, c.corName ||' ( '
||c.corLevel ||' )' AS corLabel
FROM CourseList c, Departments d
WHERE d.Dept_ID = c.Dept_ID
ORDER BY d.dept_Name, c.corName, c.corLevel







The following example creates a tree that shows the basic information about all employees in an organization,
organized by department. The departments are expanded to show all employees. You click the + signs to display
additional information. If you click the employee name, ColdFusion links back to the same page and displays the
Path and node values for the selection.

© 2014 Adobe Systems Incorporated. All rights reserved.

1234

Adobe ColdFusion Documentation




SELECT Emp_ID, FirstName, LastName, EMail, Phone, Department
FROM Employees
GROUP BY Department, Emp_ID, FirstName, LastName, EMail, Phone



cftree Example


Selected item information


Path: #form.Employees.Path#

node: #form.Employees.node#




























© 2014 Adobe Systems Incorporated. All rights reserved.

1235

Adobe ColdFusion Documentation

© 2014 Adobe Systems Incorporated. All rights reserved.

1236

Adobe ColdFusion Documentation

cftreeitem
Description

Populates a form tree control, created with the cftree tag, with one or more elements.
Category

Forms tags
Syntax


OR

onBindError = "JavaScript function name"

Note
You can specify this tag's attributes in an attributeCollection attribute whose value is a
structure. Specify the structure name in the attributeCollection attribute and use the tag's
attribute names as structure keys.

History

ColdFusion 8: Added the bind and onBindError attributes.
See also

cfapplet, cfform, cfformgroup, cfformitem, cfgrid, cfinput, cfselect, cfslider, cftextarea, cft
ree; Building tree controls with the cftree tag and Using HTML trees in the Developing ColdFusion Applications
Attributes

Note
In XML format, ColdFusion passes all attributes to the XML. The supplied XSLT skins do not
handle or display XML format trees, but do display applet and Flash format trees.

© 2014 Adobe Systems Incorporated. All rights reserved.

1237

Adobe ColdFusion Documentation

Attribute

Req/Opt;Format

value

Required for applet,
Flash, XML.value or bin
d is required for HTML.

Value passed when the
form containing the tree is
submitted. When
populating a tree with data
from a cfquery, you can
specify multiple columns
to use in a delimited list;
for example, value = "de
pt_id,emp_id". In this
case, each column
generates an item that is
a child of the column that
precedes it in the list.

bind

value or bind is
required for HTML

A bind expression
specifying a CFC function,
JavaScript function, or
URL that dynamically gets
all tree nodes. You can
use this attribute only at
the top level of the tree,
and in this case, the tree
can have only cftreeit
em tag.
If you use the bind attrib
ute, the only other allowed
attribute is onBindError
. For details creating trees
that using binding, see
Using HTML trees in the
Developing ColdFusion
Applications

display

Optional;All

value

expand

Optional;All

yes

© 2014 Adobe Systems Incorporated. All rights reserved.

Default

Description

Tree item label. When
populating a tree with data
from a query, specify
names in a delimited list,
for example:display =
"dept_name,emp_name
"
yes: expands tree to
show tree item children.
no: keeps tree item
collapsed.

1238

Adobe ColdFusion Documentation

href

Optional;All

URL to link to if the user
clicks the tree item. If you
use a query attribute, the
href attribute can specify
a query column that
contains URLs. If href is
not a query column, the
attribute text must be a
URL or list of URLs. When
populating a tree with data
from a query, specify the
URLs in a
comma-delimited list, for
example:{{href =
"http://dept_svr,
http://emp_svr
"}}

© 2014 Adobe Systems Incorporated. All rights reserved.

1239

Adobe ColdFusion Documentation

img

Optional;Applet, HTML,
object

folder

Image name, filename, or
file URL for tree item icon.
The following values are
provided:
cd
computer
document
element
folder
floppy
fixed
remote
You can also specify a
custom image. To do
so, include path and file
extension; for example:
img =
"../images/page1.
gif" You can also
specify a path relative
to the web root.Custom
images are not
supported for Flash
format.
To specify more than
one image in a tree, or
an image at the second
or subsequent level,
use commas to
separate names,
corresponding to level;
for example:img =
"folder,document"
img = ",document"
(example of
second level)

imgopen

Optional;Applet, HTML,
object

© 2014 Adobe Systems Incorporated. All rights reserved.

Icon displayed with open
tree item, as described for
the img attribute.

1240

Adobe ColdFusion Documentation

onBindError

Optional;HTML

parent

Optional;All

Value of the tree item
parent. Determines the
item's placement in the
tree hierarchy. If omitted,
the item is placed at the
tree root level, or if the qu
eryAsRoot attribute is
True, directly under the
query.

query

Optional;All

Query name to use to
populate the treeitem.
ColdFusion generates an
item for each field value in
the query column list
specified by the value att
ribute. The fields in each
row are hierarchically
linked to the first column.

© 2014 Adobe Systems Incorporated. All rights reserved.

see Description

The name of a JavaScript
function to execute if
evaluating a bind
expression results in an
error. The function must
take two attributes: an
HTTP status code and a
message.
If you omit this attribute,
and you specified a global
error handler (by using the
ColdFusion.setGloba
lErrorHandler function
), it displays the error
message; otherwise a
default error pop-up
appears.

1241

Adobe ColdFusion Documentation

queryAsRoot

Optional;All

yes

Applies only if you specify
a query attribute. Defines
the query as the root level
for all items generated by
this tag. This attribute lets
you avoid creating a
parent cftreeitem.
yes: generates a parent
(root) item for all other
items generated by the
tag, with the query
name as its value; if you
specify a parent attrib
ute, the root item is a
child of the specified
parent.
no: uses the item
specified by the paren
t attribute as the
immediate parent of all
items generated by this
tag. If there is no paren
t attribute, use the
query as the parent.
A string: creates a root
item and uses the
specified string as the
item name; if you
specify a parent attrib
ute, the root item is a
child of the specified
parent.

target

Optional;All

Target attribute of href U
RL. When populating a
tree with data from a
query, specify targets in a
comma-delimited list, for
example:target =
"FRAME_BODY,_blank"

Usage

For this tag to work properly. the browser must be JavaScript-enabled. This tag must be a child of a cftree tag.
The cftreeitem tag has three basic formats:
If you do not use a query or bind attribute to populate this tag, it creates a single tree item.
If you use a query, it creates multiple items; each row of the query creates a hierarchically nested set of
items with one item per column.
If you use the bind attribute, the client side tree dynamically gets the data for the tree item's immediate
children, and creates the child items, when a tree item expands. For detailed information on using the bind a

© 2014 Adobe Systems Incorporated. All rights reserved.

1242

Adobe ColdFusion Documentation

ttribute to populate an HTML format tree, see Using HTML trees in the Developing ColdFusion Applications.
Example

The following example creates a simple tree by using a single cftreeitem tag and a query:







The following example creates a tree that shows the basic information about all employees in an organization,
organized by department. The departments are expanded to show all employees. You click the + signs to display
additional information. If you click the employee name, ColdFusion links back to the same page and displays the
selected employee's ID.

© 2014 Adobe Systems Incorporated. All rights reserved.

1243

Adobe ColdFusion Documentation




SELECT Emp_ID, FirstName, LastName, EMail, Phone, Department
FROM Employees
GROUP BY Department, Emp_ID, FirstName, LastName, EMail, Phone



cftreeitem Example




You Requested information on #URL.cftreeitemKey#; User ID #URL.user_ID#



























© 2014 Adobe Systems Incorporated. All rights reserved.

1244

Adobe ColdFusion Documentation

cftry
Description

Used with one or more cfcatch tags. Together, they catch and process exceptions in ColdFusion pages. Exceptio
ns are events that disrupt the normal flow of instructions in a ColdFusion page, such as failed database operations,
missing include files, and developer-specified events.
Category

Exception handling tags
Syntax


Code that might throw an exception
One or more cfcatch blocks


See also

cfcatch, cffinally, cferror, cfrethrow, cfthrow, onError; Handling Errors in the Developing
ColdFusion Applications
History

ColdFusion MX: Changed cfscript to include try and catch statements that are equivalent to the cftry and c
fcatch tags.
Usage

Within a cftry block, put the code that might throw an exception, followed by one ore more cfcatch tags that
catch and process exceptions. This tag requires an end tag.
Example

© 2014 Adobe Systems Incorporated. All rights reserved.

1245

Adobe ColdFusion Documentation


cftry Example




SELECT *
FROM EMPLOYEES





You've Thrown a Database Error


#cfcatch.message#
Caught an exception, type = #CFCATCH.TYPE# 
The contents of the tag stack are:



#i# #sCurrent["ID"]#
(#sCurrent["LINE"]#,#sCurrent["COLUMN"]#)
#sCurrent["TEMPLATE"]#





#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

1246

Adobe ColdFusion Documentation

Tags u-z
This section lists tags starting with alphabets U-Z with their description.
cfupdate
cfwddx
cfwebsocket
cfwindow
cfxml
cfzip
cfzipparam

© 2014 Adobe Systems Incorporated. All rights reserved.

1247

Adobe ColdFusion Documentation

cfupdate
Description

Updates records in a data source from data in a ColdFusion form or form Scope.
Category

Database manipulation tags
Syntax



Note
You can specify this tag's attributes in an attributeCollection attribute whose value is a
structure. Specify the structure name in the attributeCollection attribute and use the tag's
attribute names as structure keys.

See also

cfinsert, cfprocparam, cfprocresult, cfquery, cfqueryparam, cfstoredproc, cftransaction; Creat
ing an update action page with cfupdate in the Developing ColdFusion Applications.
History

ColdFusion 10: Added the clientInfo attribute.ColdFusion MX: Deprecated the connectString, dbName, dbSe
rver, dbtype, provider, and providerDSN attributes. They do not work, and might cause an error, in releases
later than ColdFusion 5.
Attributes

Attribute

Req/Opt

clientInfo

Optional

Structure containing
properties of the client to
be set on the database
connection.

dataSource

Required

Name of the data source
that contains the table.

© 2014 Adobe Systems Incorporated. All rights reserved.

Default

Description

1248

Adobe ColdFusion Documentation

tableName

Required

Name of table to update.
For Oracle drivers, must
be uppercase.
For Sybase driver, case
sensitive; must be in
same case as used
when the table was
created.

formFields

Optional

(all on form, except keys)

Comma-delimited list of
form fields to update.
If a form field is not
matched by a column
name in the database,
ColdFusion throws an
error. The formFields list
must include the database
table primary key field,
which must be present in
the form. It can be hidden.

password

Optional

Overrides the password
value specified in ODBC
setup.

tableOwner

Optional

For data sources that
support table ownership
(for example, SQL Server,
Oracle, Sybase SQL
Anywhere), the table
owner.

tableQualifier

Optional

For data sources that
support table qualifiers.
The purpose of table
qualifiers is as follows:
SQL Server and Oracle:
name of the database
that contains the table
Intersolv dBASE driver:
directory of DBF files

username

Optional

Overrides username valu
e specified in ODBC
setup.

Example

© 2014 Adobe Systems Incorporated. All rights reserved.

1249

Adobe ColdFusion Documentation






SELECT * FROM EMPLOYEES





#firstName#
#lastName#
#phone#
Edit





SELECT * FROM employees WHERE emp_id=#url.id#




#phoneQuery.firstName# #phoneQuery.lastName#








Note
The cfupdate tag internally uses parameterized queries.

© 2014 Adobe Systems Incorporated. All rights reserved.

1250

Adobe ColdFusion Documentation

cfwddx
Description

Serializes and deserializes CFML data structures to the XML-based WDDX format. The WDDX is an XML
vocabulary for describing complex data structures in a standard, generic way. Implementing it lets you use the HTTP
protocol to such information among application server platforms, application servers, and browsers. This tag
generates JavaScript statements to instantiate JavaScript objects equivalent to the contents of a WDDX packet or
CFML data structure. Interoperates with Unicode.
Category

Extensibility tags
Syntax



Note
You can specify this tag's attributes in an attributeCollection attribute whose value is a
structure. Specify the structure name in the attributeCollection attribute and use the tag's
attribute names as structure keys.

See also

cfcollection, cfdump, cfexecute, cfindex, cfobject, cfreport, cfsearch, ToScript; Using XML and
WDDX in the Developing ColdFusion Applications
History

ColdFusion MX
Changed column name case behavior: ColdFusion preserves the case of column names in JavaScript.
(Earlier releases converted query column names to lowercase.)
Changed encoding format support: this tag supports several encoding formats. The default encoding format is
UTF-8. The tag interoperates with Unicode.
Attributes

Attribute

Req/Opt

© 2014 Adobe Systems Incorporated. All rights reserved.

Default

Description

1251

Adobe ColdFusion Documentation

action

Required

cfml2wddx: serializes
CFML to WDDX.
wddx2cfml:
deserializes WDDX to
CFML.
cfml2js: serializes
CFML to JavaScript.
wddx2js: deserializes
WDDX to JavaScript.

input

Required

A value to process.

output

Required if action = "wd
dx2cfml"

Name of variable for
output. If action = "WDD
X2JS" or "CFML2JS",
and this attribute is
omitted, result is output in
HTML stream.

topLevelVariable

Required if action = "wd
dx2js" or "cfml2js"

Name of top-level
JavaScript object created
by deserialization. The
object is an instance of
the WddxRecordset
object.

useTimeZoneInfo

Optional

yes

Whether to output
time-zone information
when serializing CFML to
WDDX.
yes: the hour-minute
offset, represented in
ISO8601 format, is
output.
No: the local time is
output.

validate

Optional

no

Applies if action = "wdd
x2cfml" or "wddx2js".
yes: validates WDDX
input with an XML
parser using WDDX
DTD. If parser
processes input without
error, packet is
deserialized. Otherwise,
an error is thrown.
no: does not perform
input validation.

© 2014 Adobe Systems Incorporated. All rights reserved.

1252

Adobe ColdFusion Documentation
Usage

ColdFusion preserves the case of column names cases in JavaScript.
The wddx2js and cfml2js actions create a WddxRecordset javascript object when they encounter a RecordSet
java object. The serialized JavaScript code requires a wddx.js file.
This tag performs the following conversions:
From

To

CFML

WDDX

CFML

JavaScript

WDDX

CFML

WDDX

JavaScript

For more information, and a list of the ColdFusion array and structure functions that you can use to manage XML
document objects and functions, see Using XML and WDDX in the Developing ColdFusion Applications.
Note
The cfwddx tag throws an exception if you attempt to serialize a CFC or user-defined function
(UDF).

Example

© 2014 Adobe Systems Incorporated. All rights reserved.

1253

Adobe ColdFusion Documentation






SELECT Message_Id, Thread_id, Username FROM messages

The recordset data is:...


#Message_ID# #Thread_ID# #Username#



Serializing CFML data...



Resulting WDDX packet is:
<cfoutput>#wddxText#</cfoutput>

Deserializing WDDX packet...


The recordset data is:...


#Message_ID# #Thread_ID# #Username#



© 2014 Adobe Systems Incorporated. All rights reserved.

1254

Adobe ColdFusion Documentation

cfwebsocket
Description

Lets you create the WebSocket object in your CFM template. The tag creates a reference to the WebSocket
JavaScript object at the client-side
Category

Internet protocol tags
History

ColdFusion 11: Added a new attribute, secure.
ColdFusion 10: Added this tag.
Syntax



Attribute

Attribute

Req/Opt

Descriptions

name

Required

The name of the WebSocket object.
This is the reference to the
JavaScript objects that are used to
call WebSocket JavaScript
functions.

onMessage

Required

The JavaScript function that is
called when the WebSocket
receives a message from the
server. The following are the two
supported arguments:
aEvent: The WebSocket event
that is dispatched from the
server.
aToken: Used to get data
received from the server.

© 2014 Adobe Systems Incorporated. All rights reserved.

1255

Adobe ColdFusion Documentation

onOpen

Optional

The JavaScript function that is
called when the WebSocket
establishes a connection.

onClose

Optional

The JavaScript function that is
called when the WebSocket closes
a connection.

onError

Optional

The JavaScript function that is
called if there is an error while
performing an action over the
WebSocket connection.

usecfAuth

Optional

If set to true (default), users need
not authenticate for WebSocket
connection (provided they have
already logged in to the
application). This is the default
value.
If false, users have to specify the
credentials for the WebSocket
connection.

subscribeTo

Optional

Comma-separated list of channels
to subscribe to. You can specify any
or all channels set in the
Application.cfc.

secure

Optional

If true, the web socket
communication will happen over
SSL.

Example
In the following example,
The user is automatically subscribed to the stocks channel.
You have specified the channel name in the Application.cfc.
The example uses the default channel listener.
In the Index.cfm, you specify the channels to which the user can automatically subscribe to (using the
attribute subscribeTo) and also define the message handler.
Application.cfc

component
{
this.name="websocketsampleapp1";
this.wschannels=[{name="stocks"}];
}

© 2014 Adobe Systems Incorporated. All rights reserved.

1256

Adobe ColdFusion Documentation

Index.cfm





The code creates a JavaScript WebSocket object named mycfwebsocketobject. If the server sends a
message, it calls mymessagehandler function.Since you have specified subscribeTo in the cfwebsocke
t tag, the WebSocket object automatically subscribes you to the channel stocks.

© 2014 Adobe Systems Incorporated. All rights reserved.

1257

Adobe ColdFusion Documentation

cfwindow
Description

Creates a pop-up window in the browser. Does not create a separate browser pop-up instance.
Category

Display management tags
Syntax


window contents


If you use the source attribute, ColdFusion ignores any tag body contents. If you do not have a tag body and omit
the  end tag, close the cfwindow tag with the /> character combination.
Note
You can specify this tag's attribute in an attributeCollection attribute whose value is a
structure. Specify the structure name in the attributeCollection attribute and use the tag's
attribute name as structure key.

See also

cfajaximport, cfdiv, cflayout, cfpod, ColdFusion.Window.create, Using pop-up windows in the De
veloping ColdFusion Applications
History

© 2014 Adobe Systems Incorporated. All rights reserved.

1258

Adobe ColdFusion Documentation

ColdFusion 8: Added this tag.
Attributes

Attribute

Req/Opt

bodyStyle

Optional

center

Optional

Default

Description
A CSS style specification
for the window body. As a
general rule, use this
attribute to set color and
font styles. Using this
attribute to set the height
and width, for example,
can result in distorted
output.

false

A Boolean value that
specifies whether to
center the window over
the browser window.
If true, ColdFusion
ignores the x and y attri
bute values.
If false, and you do
not specify x and y attri
butes, ColdFusion
centers the window.

closable

Optional

true

A Boolean value that
specifies whether the user
can close the window. If t
rue, the window has an X
close icon.

destroyOnClose

Optional

false

If true, destroys the
window when it is closed.

draggable

Optional

true

A Boolean value that
specifies whether the user
can drag the window. To
drag the window, click the
mouse on the title bar and
hold the button down
while dragging. If the
window does not have a
title, users cannot drag it.

© 2014 Adobe Systems Incorporated. All rights reserved.

1259

Adobe ColdFusion Documentation

headerStyle

Optional

height

Optional

300

Height of the window in
pixels. If you specify a
value greater than the
available space, the
window occupies the
available space and the
resize handles do not
appear.

initShow

Optional

false

A Boolean value that
specifies whether to
display the window when
the containing page first
appears. If this value is fa
lse, use the ColdFusio
n.Window.show JavaScr
ipt function to display the
window.

minHeight

Optional

0

The minimum height, in
pixels, to which users can
resize the window.

minWidth

Optional

0

The minimum width, in
pixels, to which users can
resize the window.

modal

Optional

false

A Boolean value that
specifies whether the
window is modal, that is,
whether the user can
interact with the main
window while this window
is displayed. If true, the
user cannot interact with
the main window.

© 2014 Adobe Systems Incorporated. All rights reserved.

A CSS style specification
for the window header. As
a general rule, use this
attribute to set color and
font styles. Using this
attribute to set the height
and width, for example,
can result in distorted
output.

1260

Adobe ColdFusion Documentation

name

Optional

onBindError

Optional

© 2014 Adobe Systems Incorporated. All rights reserved.

The name of the window.
Must be unique on the
pages. This attribute is
required to interact with
the window, including to
dynamically show or hide
it.
see Description

The name of a JavaScript
function to execute if
evaluating a bind
expression results in an
error. The function must
take two attributes: an
HTTP status code and a
message.
If you omit this attribute,
and specified a global
error handler (by using the
ColdFusion.setGloba
lErrorHandler function
), it displays the error
message; otherwise a
default error pop-up
appears.

1261

Adobe ColdFusion Documentation

overflow

Optional

auto

Specifies how to display
child content whose size
would cause the control to
overflow the window
boundaries. The following
values are valid:
auto-Show scroll bars
when necessary.
hidden-Do not allow
access to overflowing
content.
scroll-Always show
horizontal and vertical
scroll bars, even if they
are not needed.
visible-Content can
display outside the
bounds of the window.
Note: In Internet
Explorer, windows with
the visible setting
expand to fit the size of
the contents, rather
than having the
contents extend beyond
the layout area.

refreshOnShow

Optional

© 2014 Adobe Systems Incorporated. All rights reserved.

false

true-Refresh the
contents of the window
by running the source
bind expression
whenever the window
shows (for example, by
calling the ColdFusio
n.Window.show Java
Script function), in
addition to when bind
events occur
false- Refresh the
window only when the
bind expression is
triggered by its bind
event.
To use this attribute,
you must also specify a
source attribute.

1262

Adobe ColdFusion Documentation

resizable

Optional

source

Optional

A URL that returns the
window contents. This
attribute can use URL
parameters to pass data
to the page. ColdFusion
uses standard page path
resolution rules to locate
the page. You can use a
bind expression in this
attribute; for more
information see Usage.
Note: If a CFML page
specified in this attribute
contains tags that use
Ajax features, such as cf
form, cfgrid, and cfpo
d, you must use a cfaja
ximport tag on the page
with the cfwindow tag.
For more information, see
cfajaximport.

title

Optional

The text to display in the
window's title bar. You
can use HTML mark-up to
control the title
appearance; for example,
to show the text in red
italic font.

width

Optional

© 2014 Adobe Systems Incorporated. All rights reserved.

true

500

A Boolean value
specifying whether the
user can resize the
window.

Width of the window in
pixels. If you specify a
value greater than the
available space, the
window occupies the
available space and the
resize handles do not
appear.

1263

Adobe ColdFusion Documentation

x

Optional

The X (horizontal)
coordinate of the
upper-left corner of the
window, relative to the
browser window.
ColdFusion ignores this
attribute if the center attr
ibute value is true and if
you do not set the y attrib
ute value.

y

Optional

The Y (vertical) coordinate
of the upper-left corner of
the window, relative to the
browser
window.ColdFusion
ignores this attribute if the
center attribute value is
true and if you do not set
the x attribute value.

Usage

You cannot use this tag in a form or as a child of a cflayout, or cflayoutarea tag.Define the cfwindow tag on
the page that displays it (or a page that is included by using the cfinclude tag). So, you cannot use the cfwindo
w tag on a page that is specified by a cfmenuitem tag http attribute, cfdiv tag bind attribute, or cflayoutare
a or cfpod tag source attribute. Instead, for example, you can display a window when a user clicks a menu item
by defining the window on the same page as your menu and using a JavaScript function in the cfmenuitem tag ht
tp attribute to call the window's show function. The cfwindow tag uses its source attribute to get its contents from
another page.
You can use a source attribute or a tag body to specify the window contents; if you specify both, ColdFusion uses
the contents specified by the source attribute and ignores the tag body. If you use a source attribute, an animated
icon and the text "Loading..." appears while the contents is being fetched.
If the source attribute specifies a page that defines JavaScript functions, the function definitions on that page must
have the following format:

functionName = function(arguments) {function body}

Function definitions that use the following format may not work:

function functionName (arguments) {function body}

However, Adobe recommends that you include all custom JavaScript in external JavaScript files and import them on
the application's main page, and not write them inline in code that you get by using the source attribute. Imported
pages do not have this function definition format restriction.

© 2014 Adobe Systems Incorporated. All rights reserved.

1264

Adobe ColdFusion Documentation

If you use the source attribute, you can use a bind expression to include form field values or other form control
attributes as part of the source specification. You can bind to HTML format form controls only. For detailed
information on using bind expressions, see Binding data to form fields in the Developing ColdFusion Applications.
JavaScript functions

You can use the following JavaScript functions to manage an HTML format window:
Function

Description

ColdFusion.Window.create

Creates a window without using a cfwindow tag.

ColdFusion.Window.getWindowObject

Gets the underlying Ext JS - JavaScript Library object
for the specified HTML format cfwindow control.

ColdFusion.Window.hide

Closes a window.

ColdFusion.Window.onHide

Specifies a function to run each time a specific window
closes.

ColdFusion.Window.onShow

Specifies a function to run each time a specific window
opens.

ColdFusion.Window.show

Opens a window.

Example

The following example shows several features of the cfwindow tag and dynamic binding of the cfwindow tag sou
rce attribute to form controls. It shows how you can use x and y attributes to position the windows and how several
attributes, such as closable and resizable affect the window appearance. It also shows how you can use bind
expressions to dynamically update window contents when form control values change, including different ways to
trigger updating the window contents.







Click the mouse on the control to show its text in window 1.


Click the button to show the input control text in window 2.



Click the Checkbox to change and show its status in window 3



© 2014 Adobe Systems Incorporated. All rights reserved.

1265

Adobe ColdFusion Documentation

Click the button to open a window containing the page
specified by the input control.












© 2014 Adobe Systems Incorporated. All rights reserved.

1266

Adobe ColdFusion Documentation




The windowsource.cfm page that the cfwindow tag source attributes specify to display in the windows contains
the following code:

Main page input:

#url.text#


© 2014 Adobe Systems Incorporated. All rights reserved.

1267

Adobe ColdFusion Documentation

cfxml
Description

Creates a ColdFusion XML document object that contains the markup in the tag body. This tag can include XML and
CFML tags. ColdFusion processes the CFML code in the tag body, and then assigns the resulting text to an XML
document object variable, which is always stored in Unicode.
Category

Extensibility tags
Syntax



Note
You can specify this tag's attributes in an attributeCollection attribute whose value is a
structure. Specify the structure name in the attributeCollection attribute and use the tag's
attribute names as structure keys.

See also

IsXmlDoc, IsXmlElem, IsXmlRoot, ToString, XmlChildPos, XmlNew, XmlParse, XmlSearch, XmlTransfo
rm; Using XML and WDDX in the Developing ColdFusion Applications
History

ColdFusion MX 7: Added support for using an XML declaration at the start of the text.
ColdFusion MX: Added this tag.
Attributes

Attribute

Req/Opt

Default

Name of the document
object.

variable

caseSensitive

Description

Optional

no

yes: maintains the case
of document elements
and attributes.
no

Usage

If your XML object is case sensitive, you cannot use dot notation to reference an element or attribute name. Use the
name in associative array (bracket) notation, or a reference that does not use the case-sensitive name (such as
xmlChildren1) instead. In the following code, the first line works with a case-sensitive XML object. The second and

© 2014 Adobe Systems Incorporated. All rights reserved.

1268

Adobe ColdFusion Documentation

third lines cause errors:

MyDoc.xmlRoot.XmlAttributes["Version"] = "12b";
MyDoc.xmlRoot.XmlAttributes.Version = "12b";
MyDoc.MyRoot.XmlAttributes["Version"] = "12b";

Use the XmlFormat function to escape special characters such as &, > and <.
To convert an XML document object back into a string, use the ToString function, at which time ColdFusion
automatically prepends the  XML declaration.
To change the declaration to specify another encoding, use the Replace function. To specify the encoding of the
text that is returned to a browser or other application, use the cfcontent tag. The following example illustrates this
process:






Belgian Waffles
Our famous Belgian Waffles







#mynewvar#


The cfprocessingdirective tag prevents ColdFusion from putting white space characters in front of the XML
declaration.
Example

This following example creates a document object whose root element is MyDoc. The object includes text that
displays the value of the ColdFusion variable testVar. The code creates four nested child elements, which are
generated by an indexed cfloop tag. The cfdump tag displays the XML document object.

© 2014 Adobe Systems Incorporated. All rights reserved.

1269

Adobe ColdFusion Documentation






The value of testVar is True.

The value of testVar is False.



This is Child node #LoopCount#.






© 2014 Adobe Systems Incorporated. All rights reserved.

1270

Adobe ColdFusion Documentation

cfzip
Description

Manipulates ZIP and Java Archive (JAR) files. In addition to the basic zip and unzip functions, use the cfzip tag to
delete entries from an archive, filter files, read files in binary format, list the contents of an archive, and specify an
entry path used in an executable JAR file.
History

ColdFusion 11: Added 2 new attributes, password and encryptionalgorithm.
ColdFusion 8: Added this tag.
Category

File management tags
Syntax

delete

list

read

readBinary

unzip

zip

optional
encryptionAlgorithm = "standard|AES-128|AES-256"
password = "password string"
action = "zip"
filter = "file filter"
overwrite = "yes|no"
prefix = "string"

© 2014 Adobe Systems Incorporated. All rights reserved.

1272

Adobe ColdFusion Documentation

recurse = "yes|no"
storePath = "yes|no">

Note
You can specify this tag's attributes in an attributeCollection attribute whose value is a
structure. Specify the structure name in the attributeCollection attribute and use the tag's
attribute names as structure keys.

See also

cfzipparam
Attributes

Attribute

Action

Req/Opt

Default

Description

action

N/A

Optional

zip

Action to take. Must
be one of the
following:
delete
list
read
readBinary
unzip
zip
If you do not
specify an action,
ColdFusion
applies the default
action, zip.

charset

read

Optional

default encoding of
the host machine

Character set used
to translate the ZIP
or JAR entry into a
text string.
Examples of
character sets:
JIS
RFC1345
UTF-16

destination

unzip

Required

Destination directory
where the ZIP or
JAR file is extracted.

entryPath

deletereadreadBinar
yunzip

Optional

Pathname on which
the action is
performed.

© 2014 Adobe Systems Incorporated. All rights reserved.

1273

Adobe ColdFusion Documentation

file

deletelistreadreadBi
naryunzipzip

Required

Absolute pathname
of the file on which
the action is
performed; for
example, the full
pathname of the ZIP
file: c:\temp\log.zip.
If you do not specify
the full pathname
(for example, file=
"log.zip"),
ColdFusion creates
the file in a
temporary directory.
You can use the Ge
tTempDirectory f
unction to access
the ZIP or JAR file.

filter

deletelistunzipzip

Optional

File filter applied to
the action. The
action applies to all
files in the specified
pathname that
match the filter.

name

list

Required

Record set name in
which the result of
the list action is
stored. The record
set columns are the
following:

© 2014 Adobe Systems Incorporated. All rights reserved.

1274

Adobe ColdFusion Documentation

name: Filename
of the entry in the
JAR file. For
example, if the
entry is
help/docs/index.ht
m, the name is
index.htm.
directory:
Directory
containing the
entry. For the
preceding
example, the
directory is
help/docs. You
can obtain the full
entry name by
concatenating
directory and
name. If an entry
is at the root level,
the directory is
empty (" ").
size:
Uncompressed
size of the entry,
in bytes.
compressedSiz
e: Compressed
size of the entry,
in bytes.
type: Type of
entry (directory or
file).
dateLastModif
ied: Last
modified date of
the entry, cfdate
object.
comment: Any
comment, if
present, for the
entry.
crc: Crc-32
checksum of the
uncompressed
entry data.

© 2014 Adobe Systems Incorporated. All rights reserved.

1275

Adobe ColdFusion Documentation

overwrite

unzipzip

Optional

no

unzip: Specifies
whether to overwrite
the extracted files:
yes: If the
extracted file
exists at the
destination
specified, the file
is overwritten.
no: If the
extracted file
exists at the
destination
specified, the file
is not overwritten
and that entry is
not extracted. The
remaining entries
are extracted.
zip: Specifies
whether to
overwrite the
contents of a ZIP
or JAR file:
yes: Overwrites
all of the content
in the ZIP or JAR
file if it exists.
no: Updates
existing entries
and adds new
entries to the ZIP
or JAR file if it
exists.

prefix

zip

© 2014 Adobe Systems Incorporated. All rights reserved.

Optional

String added as a
prefix to the ZIP or
JAR entry. The
string is the name of
a subdirectory in
which the entries
are added.

1276

Adobe ColdFusion Documentation

recurse

deletelistunzipzip

Optional

yes

Specifies whether
the action applies to
subdirectories:
yes: Includes
subdirectories.
no: Does not
include
subdirectories.

showDirectory

list

Optional

no

Specifies whether to
show the directory
structure:
yes: Lists the
directories.
no: Does not list
directories.

source

zip

© 2014 Adobe Systems Incorporated. All rights reserved.

Required (see
description)

Source directory to
be zipped. Not
required if the cfzi
pparam tag is
specified.

1277

Adobe ColdFusion Documentation

storePath

unzipzip

Optional

yes

unzip: Specifies
whether files are
stored at the entry
path:
yes: The files are
extracted to the
entry path.
no: The entry
path is ignored
and all the files
are extracted at
the root level.
zip: Specifies
whether
pathnames are
stored in the ZIP
or JAR file:
yes: Pathnames
of entries are
stored in the ZIP
or JAR file.
no: Pathnames of
the entries are not
stored in the ZIP
or JAR file. All the
files are placed at
the root level. In
case of a name
conflict, the last
file in the iteration
is added.

variable

readreadBinary

Required

Variable in which
the content is
stored.

password

zip

Optional

The password to be
used for the archive.

© 2014 Adobe Systems Incorporated. All rights reserved.

1278

Adobe ColdFusion Documentation

encryptionAlgor
ithm

zip

Optional

The encryption
algorithm to use for
compression. The
following options are
valid:
AES-256
AES-128
Standard

If the attibutes are
specified in the
CFZip tag, they can
be inherited or
overridden by the
corresponding
attributes in the
CFZipparam tag.
If only password is
provided, the default
encryptionAlgorithm
will be AES 256-bit.
If used with a
directory, all files in
that directory will be
protected with the
same
password/encryptio
n.
Usage

Use the cfzip tag to zip and unzip files and manipulate existing ZIP or JAR files in ColdFusion. You can use the cf
zip tag independently or with one or more cfzipparam tags to manipulate multiple files or directories. The cfzip
tag is the parent tag of the cfzipparam tag.
The ZIP format is the standard format for file archiving and compression. The JAR format is based on the ZIP
format. JAR files are platform-independent.
Note
The cfzip tag does not create directories. If you specify a directory that does not exist,
ColdFusion generates an error.

Use the following syntax to specify an in-memory file or directory in any attribute that takes a path. In-memory files
are not written to disk and speed processing of transient data.

ram:///filepath

© 2014 Adobe Systems Incorporated. All rights reserved.

1279

Adobe ColdFusion Documentation

The filepath can include multiple directories, for example ram:///petStore/images/dogImages.zip. You
must create the directories in the path before you specify the file. For more information on using in-memory files, see
Working with in-memory files in Optimizing ColdFusion applications in the Developing ColdFusion Applications.
delete action

Use the delete action to delete entries from a ZIP or JAR file.













list action

Use the list action to list the entries of a ZIP or JAR file. The following table shows the types of information you
can retrieve for entries in the archive:
Field

Description

comment

Text string description saved with the entry source.

compressedSize

Compressed size of the entry in bytes.

crc

Checksum for the entry source.

dateLastModified

Date and time when the source was last modified.

directory

Name of the directory where the entry is stored.

name

Entry pathname.

size

Uncompressed size of the entry source in bytes.

type

Source type for the entry, for example, file.

You can use the cfdump tag to list all of the information in a ZIP or JAR file, as the following example shows:

© 2014 Adobe Systems Incorporated. All rights reserved.

1280

Adobe ColdFusion Documentation




You can use the cfoutput tag to list individual fields for the entries in an archive, as the following example shows:





Entry Name: #entry.name#
Last Modified Date:
#dateFormat(entry.dateLastModified)#,#timeFormat(entry.dateLastModified)#
Size (uncompressed): #numberFormat(entry.size/1000)# KB






read action

Use the read action to read the content of the ZIP or JAR file entry in human-readable format. The read action
uses the charset value to create the string.




readBinary action

Use the readBinary action to read the content of a ZIP or JAR file in binary format.







unzip action

Use the unzip action to extract the entries from a ZIP or JAR file.

© 2014 Adobe Systems Incorporated. All rights reserved.

1281

Adobe ColdFusion Documentation









zip action

Use the zip action to create or update a ZIP or JAR file. This is the default action; you do not have to specify it
explicitly. If you specify a ZIP or JAR file that does not exist, ColdFusion creates it. If the ZIP or JAR file exists,
ColdFusion adds new entries from the source and updates existing entries if they have changed. If you set the over
write attribute to yes, all of the entries in the ZIP or JAR file are replaced by the new content.








Example

The following example shows how to zip image files chosen from a form and e-mail the ZIP file to the person
requesting the images.
The first ColdFusion page populates a pop-up menu with the names of artists generated from a database query:

© 2014 Adobe Systems Incorporated. All rights reserved.

1282

Adobe ColdFusion Documentation



SELECT FIRSTNAME || ' ' || LASTNAME AS FULLNAME,ARTISTS.ARTISTID
FROM ARTISTS



Choose an Artist
Please choose an artist:






The first action page displays the images by the selected artist, zips the files, and writes the ZIP file to a temporary
directory. Also, it includes a form to e-mail the ZIP file:

© 2014 Adobe Systems Incorporated. All rights reserved.

1283

Adobe ColdFusion Documentation



SELECT FIRSTNAME, LASTNAME, LARGEIMAGE
FROM ARTISTS, ART
WHERE ARTISTS.ARTISTID = ART.ARTISTID
AND ARTISTS.ARTISTID=
ORDER BY ARTNAME


You have chosen the work of #artwork.FirstName# #artwork.LastName#.












Mail the ZIP File
Please enter your e-mail address so we can send you the ZIP file as an
attachment.

Your e-mail address: 






The second action page mails the ZIP file as an attachment:

© 2014 Adobe Systems Incorporated. All rights reserved.

1284

Adobe ColdFusion Documentation

Mail the ZIP file
Your file has been mailed to you.



The images you requested are enclosed in a ZIP file.



© 2014 Adobe Systems Incorporated. All rights reserved.

1285

Adobe ColdFusion Documentation

cfzipparam
Description

Provides additional information to the cfzip tag.
The cfzipparamtag is always a child tag of the cfzip tag.
History

ColdFusion 11: Added 2 new attributes, password and encryptionalgorithm.
ColdFusion 8: Added this tag.
Category

File management tags
Syntax





You can specify this tag’s attributes in anattributeCollectionattribute whose value is a
structure. Specify the structure name in theattributeCollectionattribute and use the tag’s
attribute names as structure keys.

See also

cfzip
Attributes

Attribute

Req/Opt

© 2014 Adobe Systems Incorporated. All rights reserved.

Default

Description

1286

Adobe ColdFusion Documentation

charset

Optional

default encoding of the
host machine

Converts string content
into binary data before
putting it into a ZIP or JAR
file. Used only whencfzi
p action="zip"and the
cfzipparamcontent is a
string.
Examples of character
sets:
JIS
RFC1345
UTF-16

content

Optional

Content written to the ZIP
or JAR entry. Used only
whencfzip
action="zip".
Valid content data types
arebinaryandstring. If
you specify thecontentat
tribute, specify theentryp
athattribute.

entryPath

Optional

Pathname used:
Forcfzip
action="zip", it
is the entry path
used. This is valid
only when thesour
ceis a file. The
entry path creates
a subdirectory in
the ZIP or JAR file.
Forcfzip
action="unzip",
it is the pathname
to unzip.
Forcfzip
action="delete
", it is the
pathname to delete
from the ZIP or
JAR file.

© 2014 Adobe Systems Incorporated. All rights reserved.

1287

Adobe ColdFusion Documentation

filter

Optional

File filter applied to the
action. For example, for
thezipaction, all the files
in thesourcedirectory
that match the filter are
zipped.

prefix

Optional

String added as a prefix to
the ZIP or JAR entry.
Used only whencfzip
action="zip".

recurse

Optional

source

Optional

yes

Include the directory to be
zipped, unzipped, or
deleted, as specified by
thecfzipparent tag.
Source directory or file.
Used only whencfzip
action="zip".
Specified files are added
to the ZIP or JAR file:
If you specifysour
ceattribute for thec
fziptag, thecfzip
param sourceis
relative to it.
If you do not
specify asourceatt
ribute for thecfzip
tag, thecfzippar
am sourcemust
be an absolute
pathname.

© 2014 Adobe Systems Incorporated. All rights reserved.

1288

Adobe ColdFusion Documentation

encryptionAlgorithm

Optional

The encryption algorithm
to use for compression.
The following options are
valid:
AES-256
AES-128
Standard
If the attibutes are
specified in the CFZip tag,
they can be inherited or
overridden by the
corresponding attributes
in the CFZipparam tag.
If only password is
provided, the default
encryptionAlgorithm will
be AES 256-bit.
If used with a directory, all
files in that directory will
be protected with the
same
password/encryption.

password

read readBinary zip unzip

Required, if
encryptionAlgorithm is
specified

The password to protect
the archive.

Usage

Use thecfzipparamtag with thecfziptag to zip, extract, or delete multiple files or directories. For example, to zip
multiple directories, specify acfzipparamtag for each source directory.
Example

Example 1







Example 2

© 2014 Adobe Systems Incorporated. All rights reserved.

1289

Adobe ColdFusion Documentation








Example 3










Example 4







Example 5
The following example shows how to zip multiple image files chosen from a form and e-mail the ZIP file to the
person requesting the images.
The first ColdFusion page populates a pop-up menu with the names of artists generated from a database query:

© 2014 Adobe Systems Incorporated. All rights reserved.

1290

Adobe ColdFusion Documentation


Select the images
Please choose the images you would like sent to you.






Cube


Pentagon


Surfer Dude


Surfer Girl




The first action page zips the files selected from the form, and writes the ZIP file to the hard drive. Also, it includes a
form to e-mail the ZIP file:

© 2014 Adobe Systems Incorporated. All rights reserved.

1291

Adobe ColdFusion Documentation


















Mail the ZIP File
Please enter your e-mail address so we can send you the ZIP file as an
attachment.




The images you requested are enclosed in a ZIP file.






Your e-mail address: 






The second action page mails the ZIP file as an attachment:

© 2014 Adobe Systems Incorporated. All rights reserved.

1292

Adobe ColdFusion Documentation

Mail the ZIP file
Your file has been mailed to you.



The images you requested are enclosed in a ZIP file.



To protect a zip archive with a password:






© 2014 Adobe Systems Incorporated. All rights reserved.

1293

Adobe ColdFusion Documentation

ColdFusion Functions
The following list shows the ColdFusion Markup Language (CFML) functions.
New Functions in ColdFusion 10
Functions by category
Function changes since ColdFusion 5
Functions a-b
Functions c-d
Functions e-g
Functions h-im
Functions in-k
Functions l
Functions m-r
Functions s
Functions t-z

#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

1294

Adobe ColdFusion Documentation

New Functions in ColdFusion 10
ArraySlice
ArrayEach
ArrayFilter
ArrayFindAll
ArrayFindAllNoCase

ImageMakeTranslucent
Invoke
IsClosure
ListFilter
LSDateTimeFormat

CacheIdExists
CacheRegionNew
CacheRegionRemove
CacheRemoveAll
Canonicalize
CacheRegionExists

ListRemoveDuplicates
OnWSAuthenticate
ORMIndex
ORMIndexPurge
ORMSearch
ORMSearchOffline

CallStackDump
CallStackGet
CSRFGenerateToken
CSRFVerifyToken
DateTimeFormat
DecodeForHTML

ReEscape
RestInitApplication
RemoveCachedQuery
RestDeleteApplication
RestSetResponse
SessionRotate

DecodeFromURL
DirectoryCopy
EncodeForHTML
EncodeForCSS
EncodeForHTMLAttribute
EncodeForJavaScript

SessionGetMetaData
SessionInvalidate
StructEach
StructFilter
WSGetAllChannels
WSGetSubscribers

EncodeForURL
EncodeForXML
FileGetMimeType
GetApplicationMetadata
GetCPUUsage

WSPublish
WSSendMessage

GetTotalSpaceGetFreeSpace
GetTotalSpace
GetSystemFreeMemory
GetSystemTotalMemory
HMac
ImageCreateCaptcha
ImageMakeColorTransparent

#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

1295

Adobe ColdFusion Documentation

Functions by category
The following section list functions by their category or purpose.
Array functions
Cache functions
Conversion functions
Date and time functions
Data output functions
Debugging functions
Decision functions
Display and formatting functions
Dynamic evaluation functions
Exception handling functions
Extensibility functions
Flow control functions
Full-text search functions
Image functions
International functions
List functions
Mathematical functions
Microsoft office integration functions
ORM functions
Other functions
Query functions
Security functions
Spreadsheet functions
String functions
Structure functions
System functions
Transaction functions
XML functions
Mobile Functions

© 2014 Adobe Systems Incorporated. All rights reserved.

1296

Adobe ColdFusion Documentation

Array functions
ArrayAppend
ArrayAvg
ArrayClear
ArrayDeleteAt
ArrayInsertAt
ArrayContains
ArrayEach
ArraySlice

ArrayIsDefined
ArrayIsEmpty
arrayLen
ArrayMax
ArrayMin
ArrayDelete
ArrayFilter

© 2014 Adobe Systems Incorporated. All rights reserved.

ArrayNew
ArrayPrepend
ArrayResize
ArraySet
ArraySort
ArrayFind
ArrayFindAll

ArraySum
ArraySwap
ArrayToList
IsArray
ListToArray
ArrayFindNoCase
ArrayFindAllNoCase

1297

Adobe ColdFusion Documentation

Cache functions
CacheGet
CacheGetAllIds
CacheRegionNew
CacheRegionExists

CacheGetMetadata
CacheGetProperties
CacheRegionRemove

© 2014 Adobe Systems Incorporated. All rights reserved.

CachePut
CacheRemove
CacheRemoveAll

CacheSetProperties
CacheIdExists
Canonicalize

1298

Adobe ColdFusion Documentation

Conversion functions
ArrayToList
BinaryDecode
BinaryEncode
CharsetDecode
CharsetEncode
DeserializeJSON

DotNetToCFType
Hash
LCase
ListToArray
SerializeJSON
ToBase64

© 2014 Adobe Systems Incorporated. All rights reserved.

ToBinary
ToScript
ToString
URLDecode
URLEncodedFormat
Val

XmlFormat
XmlParse
XmlTransform

1299

Adobe ColdFusion Documentation

Date and time functions
CreateDate
CreateDateTime
CreateODBCDate
CreateODBCDateTime
CreateODBCTime
CreateTime
CreateTimeSpan
DateAdd
DateCompare
DateConvert
DateDiff

DateFormat
DatePart
Day
DayOfWeek
DayOfWeekAsString
DayOfYear
DaysInMonth
DaysInYear
FirstDayOfMonth
GetHttpTimeString
GetTickCount

© 2014 Adobe Systems Incorporated. All rights reserved.

GetTimeZoneInfo
Hour
IsDate
IsLeapYear
IsNumericDate
LSDateFormat
LSIsDate
LSParseDateTime
LSTimeFormat
Minute
Month

MonthAsString
Now
ParseDateTime
Quarter
Second
TimeFormat
Week
Year
DateTimeFormat

1300

Adobe ColdFusion Documentation

Data output functions
WriteDump|
WriteLog|
WriteOutput|

© 2014 Adobe Systems Incorporated. All rights reserved.

1301

Adobe ColdFusion Documentation

Debugging functions
Trace

© 2014 Adobe Systems Incorporated. All rights reserved.

1302

Adobe ColdFusion Documentation

Decision functions
DirectoryExists
FileExists
FileIsEOF
IIf
IsArray
IsBinary
IsBoolean
IsCustomFunction
IsDate
IsDebugMode
IsDDX

IsDefined
IsInstanceOf
IsJSON
IsK2ServerABroker
IsK2ServerDocCountE
xceeded
IsK2ServerOnline
IsLeapYear
IsNumeric
IsNumericDate
IsObject
IsNull

© 2014 Adobe Systems Incorporated. All rights reserved.

IsPDFFile
IsPDFObject
IsQuery
IsSimpleValue
IsStruct
IsUserInAnyRole
IsValid
IsWDDX
IsXML
IsXmlAttribute
IsXmlDoc

IsXmlElem
IsXmlNode
IsXmlRoot
LSIsCurrency
LSIsDate
LSIsNumeric
StructIsEmpty
StructKeyExists
YesNoFormat

1303

Adobe ColdFusion Documentation

Display and formatting functions
AjaxLink
AjaxOnLoad
CJustify
DateFormat
DecimalFormat
DollarFormat
FormatBaseN
GetLocale

GetLocaleDisplayNam
e
HTMLCodeFormat
HTMLEditFormat
LJustify
LSCurrencyFormat
LSDateFormat
LSEuroCurrencyForma
t
LSIsCurrency

© 2014 Adobe Systems Incorporated. All rights reserved.

LSIsDate
LSNumberFormat
LSParseCurrency
LSParseDateTime
LSParseEuroCurrency
LSParseNumber
LSTimeFormat
NumberFormat

ParagraphFormat
RJustify
StripCR
TimeFormat
YesNoFormat

1304

Adobe ColdFusion Documentation

Dynamic evaluation functions
DE
SetVariable

Evaluate

© 2014 Adobe Systems Incorporated. All rights reserved.

IIf

PrecisionEvaluate

1305

Adobe ColdFusion Documentation

Exception handling functions
Throw

© 2014 Adobe Systems Incorporated. All rights reserved.

1306

Adobe ColdFusion Documentation

Extensibility functions
CreateObject
DotNetToCFType

GetComponentMetaDat
a
GetGatewayHelper

© 2014 Adobe Systems Incorporated. All rights reserved.

IsInstanceOf
ReleaseComObject

SendGatewayMessage
ToScript

1307

Adobe ColdFusion Documentation

Flow control functions
Throw

© 2014 Adobe Systems Incorporated. All rights reserved.

Location

1308

Adobe ColdFusion Documentation

Full-text search functions
History

ColdFusion MX 6.1: These functions are deprecated. They might not work, and might cause errors, in a future
release.
GetK2ServerDocCountLimit

IsK2ServerABroker
IsK2ServerDocCountExceeded

© 2014 Adobe Systems Incorporated. All rights reserved.

IsK2ServerOnline

1309

Adobe ColdFusion Documentation

Image functions

ImageAddBorder
ImageBlur
ImageClearRect
ImageCopy
ImageCrop
ImageDrawArc
ImageDrawBeveledRec
t
ImageDrawCubicCurve
ImageDrawLine
ImageDrawLines
ImageDrawOval
ImageDrawPoint
ImageDrawQuadraticC
urve

ImageDrawRect
ImageDrawRoundRect
ImageDrawText
ImageFlip
ImageGetBlob
ImageGetBufferedIma
ge
ImageGetEXIFMetaDat
a
ImageGetEXIFTag
ImageGetHeight
ImageGetIPTCTag
ImageGetIPTCMetaDat
a
ImageGetWidth
ImageGrayscale

© 2014 Adobe Systems Incorporated. All rights reserved.

ImageNewImageInfo
ImageNegative
ImageNew
ImageOverlay
ImagePaste
ImageRead
ImageReadBase64
ImageResize
ImageRotate
ImageRotateDrawingA
xis
ImageScaleToFit
ImageSetAntialiasin
g
ImageSetBackgroundC
olor

ImageSetDrawingColo
r
ImageSetDrawingStro
ke
ImageSetDrawingTran
sparency
ImageSharpen
ImageShear
ImageShearDrawingAx
is
ImageTranslate
ImageTranslateDrawi
ngAxis
ImageWrite
ImageWriteBase64
ImageXORDrawingMode
IsImage
IsImageFile

1310

Adobe ColdFusion Documentation

International functions
DateConvert
GetEncoding
GetHttpTimeString
GetLocale
GetLocaleDisplayNam
e

GetTimeZoneInfo
LSIsCurrency
LSCurrencyFormat
LSDateFormat
LSEuroCurrencyForma
t

© 2014 Adobe Systems Incorporated. All rights reserved.

LSIsDate
LSParseDateTime
LSIsNumeric
LSNumberFormat
LSParseCurrency

LSParseEuroCurrency
LSParseNumber
LSTimeFormat
SetLocale

1311

Adobe ColdFusion Documentation

List functions
ArraySort
ArrayToList
Asc
Chr
CJustify
Compare
CompareNoCase
Decrypt
Encrypt
Find

FindNoCase
FindOneOf
FormatBaseN
GetClientVariablesL
ist
LCase
Left
Len
ListAppend
ListChangeDelims
ListContains

ListContainsNoCase
ListDeleteAt
ListFind
ListFindNoCase
ListFirst
ListGetAt
ListInsertAt
ListLast
ListLen
ListMap
ListPrepend

ListQualify
ListReduce
ListRest
ListRemoveDuplicate
s
ListSetAt
ListSort
ListToArray
ListValueCount
ListValueCountNoCa
se
ReplaceList
ValueList

© 2014 Adobe Systems Incorporated. All rights reserved.

1312

Adobe ColdFusion Documentation

Mathematical functions
Abs
ACos
ArrayAvg
ArraySum
ASin
Atn
BitAnd
BitMaskClear
BitMaskRead
BitMaskSet

BitNot
BitOr
BitSHLN
BitSHRN
BitXor
Ceiling
Cos
DecrementValue
Exp
Fix

© 2014 Adobe Systems Incorporated. All rights reserved.

FormatBaseN
IncrementValue
InputBaseN
Int
Log
Log10
Max
Min
Pi
PrecisionEvaluate

Rand
Randomize
RandRange
Round
Sgn
Sin
Sqr
Tan

1313

Adobe ColdFusion Documentation

Microsoft office integration functions
IsSpreadsheetFile
IsSpreadsheetObject
SpreadsheetAddColum
n
SpreadsheetAddFreez
ePane
SpreadsheetAddImage
SpreadsheetAddInfo
SpreadsheetAddRow
SpreadsheetAddRows
SpreadsheetAddSplit
Pane
SpreadsheetCreateSh
eet
SpreadsheetDeleteCo
lumn

SpreadsheetDeleteCo
lumns
SpreadsheetDeleteRo
w
SpreadsheetDeleteRo
ws
SpreadsheetFormatCe
ll
SpreadsheetFormatCe
llRange
SpreadsheetFormatCo
lumn
SpreadsheetFormatCo
lumns
SpreadsheetFormatRo
w
SpreadsheetFormatRo
ws
SpreadsheetGetCellC
omment
SpreadsheetGetCellF
ormula
SpreadsheetGetCellV
alue

© 2014 Adobe Systems Incorporated. All rights reserved.

SpreadsheetRead
SpreadsheetRemoveSh
eet
SpreadsheetInfo
SpreadsheetMergeCel
ls
SpreadsheetNew
SpreadsheetReadBina
ry
SpreadsheetSetActiv
eSheetNumber
SpreadsheetSetCellC
omment
SpreadsheetSetCellF
ormula
SpreadsheetSetCellV
alue

SpreadsheetSetActiv
eSheet
SpreadsheetSetFoote
r
SpreadsheetSetHeade
r
SpreadsheetSetColum
nWidth
SpreadsheetShiftCol
umns
SpreadsheetShiftRow
s
SpreadsheetSetRowHe
ight
SpreadsheetWrite
Trace

1314

Adobe ColdFusion Documentation

ORM functions
EntityDelete
EntityLoad
EntityLoadByExample
EntityLoadByPK
EntityMerge

EntityNew
EntityReload
EntitySave
EntitytoQuery

© 2014 Adobe Systems Incorporated. All rights reserved.

ORMClearSession
ORMCloseSession
ORMEvictCollection
ORMEvictEntity
ORMEvictQueries

ORMExecuteQuery
ORMFlush
ORMGetSession
ORMGetSessionFactor
y
ORMReload

1315

Adobe ColdFusion Documentation

Other functions
ApplicationStop
CreateUUID
DeleteClientVariabl
e
GetBaseTagData
GetBaseTagList

GetBaseTemplatePath
GetClientVariablesL
ist
GetLocalHostIP

© 2014 Adobe Systems Incorporated. All rights reserved.

IsLocalHost
ObjectEquals
ObjectLoad
ObjectSave
PreserveSingleQuote
s

URLSessionFormat
WriteDump
WriteLog
WriteOutput

1316

Adobe ColdFusion Documentation

Query functions
IsQuery
QueryAddColumn

QueryAddRow
QueryConvertForGrid

© 2014 Adobe Systems Incorporated. All rights reserved.

QueryNew
QuerySetCell

QuotedValueList
ValueList

1317

Adobe ColdFusion Documentation

Security functions
Decrypt
Decrypt DecryptBinary
Encrypt
EncryptBinary
GetAuthUser
GenerateSecretKey
GetTempDirectory
GetTempFile
GetUserRoles
Hash
IsUserInAnyRole
IsUserInRole
IsUserLoggedIn
VerifyClient
VerifyClient
VerifyClient
GeneratePBKDFKey

© 2014 Adobe Systems Incorporated. All rights reserved.

1318

Adobe ColdFusion Documentation

Spreadsheet functions
SpreadsheetAddCol
umn
SpreadsheetAddIma
ge
SpreadsheetAddFre
ezePane
SpreadsheetAddInf
o
SpreadsheetAddRow
SpreadsheetAddRow
s
SpreadsheetAddSpl
itPane
SpreadsheetCreateShe
et
SpreadsheetDelete
Column
SpreadsheetDelete
Columns

SpreadsheetDelete
Row
SpreadsheetDelete
Rows
SpreadsheetFormat
Cell
SpreadsheetFormat
Column
SpreadsheetFormat
CellRange
SpreadsheetFormatCol
umns
SpreadsheetFormat
Row
SpreadsheetFormat
Rows
SpreadsheetGetCel
lComment
SpreadsheetGetCel
lFormula

© 2014 Adobe Systems Incorporated. All rights reserved.

SpreadsheetGetCel
lValue
SpreadsheetInfo
SpreadsheetMergeC
ells
SpreadsheetNew
SpreadsheetRead
SpreadsheetReadBi
nary
SpreadsheetRemove
Sheet
SpreadsheetSetAct
iveSheet
SpreadsheetSetAct
iveSheetNumber
SpreadsheetSetCel
lComment

SpreadsheetSetCel
lFormula
SpreadsheetSetCel
lValue
SpreadsheetSetCol
umnWidth
SpreadsheetSetFoo
ter
SpreadsheetSetHea
der
SpreadsheetSetRow
Height
SpreadsheetShiftC
olumns
SpreadsheetShiftR
ows
SpreadsheetWrite
SpreadSheetAddAutofilt
er
SpreadSheetAddPageb
reaks

1319

Adobe ColdFusion Documentation

String functions
History

ColdFusion MX: ColdFusion now supports the Java UCS-2 representation of Unicode character values 0-65535.
(Earlier releases supported ASCII values.) String-processing functions process any of these characters (including
ASCII 0 (NUL) characters), and continue counting subsequent characters of the string, if any. (In earlier releases,
some string-processing functions processed the ASCII 0 (NUL) character, but did not process subsequent
characters of the string.)
Asc
BinaryDecode
BinaryEncode
CharsetDecode
CharsetEncode
Chr
CJustify
Compare
CompareNoCase
DayOfWeekAsString
Decrypt
Encrypt
Find
FindNoCase
FindOneOf
FormatBaseN
GenerateSecretKey
GetToken

Hash
HTMLCodeFormat
HTMLEditFormat
Insert
JSStringFormat
LCase
Left
Len
LJustify
ListValueCount
LSParseNumber
LTrim
ListValueCountNoCas
e
LSIsDate
LSIsNumeric
LSParseCurrency
LSIsCurrency

LSParseDateTime
LSParseEuroCurrency
Mid
MonthAsString
ParagraphFormat
ParseDateTime
REFind
REFindNoCase
REMatch
REMatchNoCase
RemoveChars
RepeatString
Replace
RTrim
SpanExcluding
ReplaceNoCase
REReplace
REReplaceNoCase

ReplaceList
Reverse
Right
RJustify
SpanIncluding
StripCR
ToBase64
ToBinary
ToString
Trim
UCase
URLDecode
URLEncodedFormat
Val
Wrap
XmlFormat

See also Conversion functions.

© 2014 Adobe Systems Incorporated. All rights reserved.

1320

Adobe ColdFusion Documentation

Structure functions
Duplicate
IsStruct
StructAppend
StructClear
StructCopy

StructCount
StructDelete
StructFind
StructFindKey
StructFindValue

© 2014 Adobe Systems Incorporated. All rights reserved.

StructGet
StructInsert
StructIsEmpty
StructKeyArray
StructKeyExists

StructKeyList
StructNew
StructSort
StructUpdate

1321

Adobe ColdFusion Documentation

System functions
DirectoryExists
Duplicate
ExpandPath
FileClose
FileCopy
FileDelete
FileExists
FileIsEOF
FileMove
FileOpen
FileRead
FileReadBinary
FileReadLine
FileSetAccessMode

FileSetAttribute
FileSetLastModified
DirectoryDelete
FileSeek
FileWrite
GetBaseTemplatePath
GetContextRoot
GetCurrentTemplateP
ath
GetDirectoryFromPat
h
GetDirectoryFromPat
h
GetEncoding
GetException
GetFileFromPath
GetFileInfo

© 2014 Adobe Systems Incorporated. All rights reserved.

GetFunctionList
GetHttpRequestData
GetLocale
GetLocaleDisplayNam
e
GetMetaData
GetMetricData
DirectoryList
FileSkipBytes
GetPageContext
GetPrinterInfo
GetProfileSections
GetProfileString
GetReadableImageFor
mats
GetTempDirectory

GetTempFile
GetTemplatePath
GetTickCount
GetWriteableImageFo
rmats
SetLocale
SetProfileString
Sleep
WriteOutput
DirectoryExists
DirectoryCreate
DirectoryRename
GetFunctionCalledNa
me

1322

Adobe ColdFusion Documentation

Transaction functions
TransactionCommit

TransactionRollback

© 2014 Adobe Systems Incorporated. All rights reserved.

TransactionSetSavePoint

1323

Adobe ColdFusion Documentation

XML functions
AddSOAPRequestHeade
r
AddSOAPResponseHead
er
GetSOAPRequest
GetSOAPRequestHeade
r
GetSOAPResponse
GetSOAPResponseHead
er

IsSOAPRequest
IsXML
IsXmlAttribute
IsXmlDoc
IsXmlElem
IsXmlNode

IsXmlRoot
IsWDDX
ToString
XmlChildPos
XmlElemNew
XmlFormat

XmlGetNodeType
XmlNew
XmlParse
XmlSearch
XmlTransform
XmlValidate

#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

1324

Adobe ColdFusion Documentation

Mobile Functions
See ColdFusion Mobile Functions.

© 2014 Adobe Systems Incorporated. All rights reserved.

1325

Adobe ColdFusion Documentation

Function changes since ColdFusion 5
The tables in the sub-section lists functions, parameters and values that have changed since ColdFusion 5 and
indicate the specific release in which the change was made.
New functions, parameters, and values
Deprecated functions, parameters, and values
Obsolete functions, parameters, and values

© 2014 Adobe Systems Incorporated. All rights reserved.

1326

Adobe ColdFusion Documentation

New functions, parameters, and values
New and changed functions are also documented elsewhere in the manual, for the following releases:
New Functions in ColdFusion 9 and 9.0.1 (in the ColdFusion 9 version of this manual)
New Functions in ColdFusion 10
New in ColdFusion 11

Function

Parameter or value

Added in this ColdFusion release

AjaxLink

All

ColdFusion 8

AjaxOnLoad

All

ColdFusion 8

ArrayIsDefined

All

ColdFusion 8

ArrayAppend

merge attribute

ColdFusion 10

BinaryDecode

All

ColdFusion MX 7

BinaryEncode

All

ColdFusion MX 7

cacheGetSession

All

ColdFusion 9.0.1

CharsetDecode

All

ColdFusion MX 7

CharsetEncode

All

ColdFusion MX 7

CreateObject

.net value of the type parameter
and associated assembly, server
, port, protocol, and secure pa
rameters.WSDL2Java and argStr
uct parameters for web service
objects

ColdFusion 8

portName parameter

ColdFusion MX 7

All

ColdFusion MX

DateAdd

l key of datepart parameter

ColdFusion MX 6.1

DatePart

l key of datepart parameter

ColdFusion MX 6.1

Decrypt

IVorSalt and iterations para
meters

ColdFusion MX 7.0.1

© 2014 Adobe Systems Incorporated. All rights reserved.

1327

Adobe ColdFusion Documentation

algorithm and encoding param
eters

ColdFusion MX 7

DecryptBinary

All

ColdFusion MX 7.0.1

DeserializeJSON

All

ColdFusion 8

DotNetToCFType

All

ColdFusion 8

Encrypt

IVorSalt and iterations para
meters

ColdFusion MX 7.0.1

algorithm and encoding param
eters

ColdFusion MX 7

EncryptBinary

All

ColdFusion MX 7.0.1

FileClose

All

ColdFusion 8

FileCopy

All

ColdFusion 8

FileDelete

All

ColdFusion 8

FileIsEOF

All

ColdFusion 8

FileMove

All

ColdFusion 8

FileOpen

All

ColdFusion 8

FileRead

All

ColdFusion 8

FileReadBinary

All

ColdFusion 8

FileReadLine

All

ColdFusion 8

FileSetAccessMode

All

ColdFusion 8

FileSetAttribute

All

ColdFusion 8

FileSetLastModified

All

ColdFusion 8

FileUpload

All

ColdFusion 9.0.1

FileUploadAll

All

ColdFusion 9.0.1

FileWrite

All

ColdFusion 8

© 2014 Adobe Systems Incorporated. All rights reserved.

1328

Adobe ColdFusion Documentation

GenerateSecretKey

All

ColdFusion MX 7

GetGatewayHelper

All

ColdFusion MX 7

GetAuthUser

All

ColdFusion MX

GetComponentMetaData

All

ColdFusion 8

GetContextRoot

All

ColdFusion MX 7

GetEncoding

All

ColdFusion MX

GetFileInfo

All

ColdFusion 8

GetLocaleDisplayName

All

ColdFusion MX 7

GetLocalHostIP

All

ColdFusion MX 7.0.1

GetMetaData

All

ColdFusion MX

GetPageContext

All

ColdFusion MX

GetPrinterInfo

All

ColdFusion 8

GetProfileSections

All

ColdFusion MX

GetReadableImageFormats

All

ColdFusion 8

GetSOAPRequest

All

ColdFusion MX 7

GetSOAPRequestHeader

All

ColdFusion MX 7

GetSOAPResponse

All

ColdFusion MX 7

GetSOAPResponseHeader

All

ColdFusion MX 7

GetUserRoles

All

ColdFusion 8

GetWriteableImageFormats

All

ColdFusion 8

Hash

algorithm and encoding param
eters

ColdFusion MX 7

ImageAddBorder

All

ColdFusion 8

ImageBlur

All

ColdFusion 8

© 2014 Adobe Systems Incorporated. All rights reserved.

1329

Adobe ColdFusion Documentation

ImageClearRect

All

ColdFusion 8

ImageCopy

All

ColdFusion 8

ImageCrop

All

ColdFusion 8

ImageDrawArc

All

ColdFusion 8

ImageDrawBeveledRect

All

ColdFusion 8

ImageDrawCubicCurve

All

ColdFusion 8

ImageDrawPoint

All

ColdFusion 8

ImageDrawLine

All

ColdFusion 8

ImageDrawLines

All

ColdFusion 8

ImageDrawOval

All

ColdFusion 8

ImageDrawQuadraticCurve

All

ColdFusion 8

ImageDrawRect

All

ColdFusion 8

ImageDrawRoundRect

All

ColdFusion 8

ImageDrawText

All

ColdFusion 8

ImageFlip

All

ColdFusion 8

ImageGetBlob

All

ColdFusion 8

ImageGetBufferedImage

All

ColdFusion 8

ImageGetEXIFMetadata

All

ColdFusion 8

ImageGetEXIFTag

All

ColdFusion 8

ImageGetHeight

All

ColdFusion 8

ImageGetIPTCMetadata

All

ColdFusion 8

ImageGetIPTCTag

All

ColdFusion 8

ImageGetWidth

All

ColdFusion 8

ImageGrayscale

All

ColdFusion 8

© 2014 Adobe Systems Incorporated. All rights reserved.

1330

Adobe ColdFusion Documentation

ImageInfo

All

ColdFusion 8

ImageNegative

All

ColdFusion 8

ImageNew

All

ColdFusion 8

ImageOverlay

All

ColdFusion 8

ImagePaste

All

ColdFusion 8

ImageRead

All

ColdFusion 8

ImageReadBase64

All

ColdFusion 8

ImageResize

All

ColdFusion 8

ImageRotate

All

ColdFusion 8

ImageRotateDrawingAxis

All

ColdFusion 8

ImageScaleToFit

All

ColdFusion 8

ImageSetAntialiasing

All

ColdFusion 8

ImageSetBackgroundColor

All

ColdFusion 8

ImageSetDrawingColor

All

ColdFusion 8

ImageSetDrawingStroke

All

ColdFusion 8

ImageSetDrawingTransparenc
y

All

ColdFusion 8

ImageSharpen

All

ColdFusion 8

ImageShear

All

ColdFusion 8

ImageShearDrawingAxis

All

ColdFusion 8

ImageTranslate

All

ColdFusion 8

ImageTranslateDrawingAxis

All

ColdFusion 8

ImageWrite

All

ColdFusion 8

ImageWriteBase64

All

ColdFusion 8

© 2014 Adobe Systems Incorporated. All rights reserved.

1331

Adobe ColdFusion Documentation

ImageXORDrawingMode

All

ColdFusion 8

IsDDX

All

ColdFusion 8

IsImage

All

ColdFusion 8

IsImageFile

All

ColdFusion 8

IsInstanceOf

All

ColdFusion 8

IsJSON

All

ColdFusion 8

IsLocalHost

All

ColdFusion MX 7.0.1

IsObject

All

ColdFusion MX

IsPDFFile

All

ColdFusion 8

IsPDFObject

All

ColdFusion 8

IsSOAPRequest

All

ColdFusion MX 7

IsUserInAnyRole

All

ColdFusion 8

IsUserInRole

All

ColdFusion MX

IsUserLoggedIn

All

ColdFusion 8

IsValid

All

ColdFusion MX 7

IsXML

All

ColdFusion MX 7

IsXmlAttribute

All

ColdFusion MX 7

IsXmlDoc

All

ColdFusion MX

IsXmlElem

All

ColdFusion MX

IsXmlNode

All

ColdFusion MX 7

IsXmlRoot

All

ColdFusion MX

LSTimeFormat

l key of mask parameter

ColdFusion MX 6.1

QueryAddColumn

datatype parameter

ColdFusion MX 7

QueryConvertForGrid

All

ColdFusion 8

© 2014 Adobe Systems Incorporated. All rights reserved.

1332

Adobe ColdFusion Documentation

QueryNew

columntypelist parameter

ColdFusion MX 7

PrecisionEvaluate

All

ColdFusion 8

Rand

algorithm parameter

ColdFusion MX 7

Randomize

algorithm parameter

ColdFusion MX 7

RandRange

algorithm parameter

ColdFusion MX 7

ReleaseComObject

All

ColdFusion MX 6.1

REMatch

All

ColdFusion 8

REMatchNoCase

All

ColdFusion 8

SerializeJSON

All

ColdFusion 8

SendGatewayMessage

All

ColdFusion MX 7

Sleep

All

ColdFusion 8

SpreadsheetFormatCellRange

All

ColdFusion 9.0.1

SpreadsheetRemoveSheet

All

ColdFusion 9.0.1

TimeFormat

l key of mask parameter

ColdFusion MX 6.1

ToScript

All

ColdFusion MX 7

URLDecode

charset parameter

ColdFusion MX

URLEncodedFormat

charset parameter

ColdFusion MX

URLSessionFormat

All

ColdFusion MX

VerifyClient

All

ColdFusion 8

Wrap

All

ColdFusion MX 6.1

XmlChildPos

All

ColdFusion MX

XmlElemNew

All

ColdFusion MX

XmlElemNew

namespace parameter

ColdFusion MX 7

© 2014 Adobe Systems Incorporated. All rights reserved.

1333

Adobe ColdFusion Documentation

XmlGetNodeType

All

ColdFusion MX 7

XmlNew

All

ColdFusion MX

XmlParse

All

ColdFusion MX

XmlParse

validator parameter

ColdFusion MX 7

XmlSearch

All

ColdFusion MX

XmlTransform

All

ColdFusion MX

XmlTransform

parameters parameter

ColdFusion MX 7

XmlValidate

All

ColdFusion MX 7

© 2014 Adobe Systems Incorporated. All rights reserved.

1334

Adobe ColdFusion Documentation

Deprecated functions, parameters, and values
The following functions, parameters, and values are deprecated. Do not use them in ColdFusion applications. They
might not work, and might cause an error, in releases later than ColdFusion MX.
Updated information for ColdFusion 11
Please note that there is a new document for ColdFusion 11, located outside of this manual, with
additional and more details about deprecated and removed/obsoleted features. See Deprecated
Features.

Function

Parameter or value

Deprecated as of this ColdFusion
release

GetMetricData

cachepops parameter

ColdFusion MX

GetK2ServerDocCount

All

ColdFusion MX 6.1

GetK2ServerDocCountLimit

All

ColdFusion MX 6.1

GetTemplatePath

All

ColdFusion MX

IsK2ServerABroker

All

ColdFusion MX 6.1

IsK2ServerDocCountExceeded

All

ColdFusion MX 6.1

IsK2ServerOnLine

All

ColdFusion MX 6.1

ParameterExists

All

ColdFusion MX. Use the IsDefine
d function.

SetLocale

locale = "Spanish
(Mexican)" value

ColdFusion MX. Use Spanish
(Standard).

© 2014 Adobe Systems Incorporated. All rights reserved.

1335

Adobe ColdFusion Documentation

Obsolete functions, parameters, and values
The following functions, parameters, and values are obsolete. Do not use them in ColdFusion applications. They do
not work in releases later than ColdFusion 5.
Updated information for ColdFusion 11
Please note that there is a new document for ColdFusion 11, located outside of this manual, with
additional and more details about deprecated and removed/obsoleted features. See Deprecated
Features

Function

Parameter or value

Obsolete as of this ColdFusion
release

AuthenticatedContext

All

ColdFusion MX

AuthenticatedUser

All

ColdFusion MX

isAuthenticated

All

ColdFusion MX

isAuthorized

All

ColdFusion MX

isProtected

All

ColdFusion MX

#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

1336

Adobe ColdFusion Documentation

Functions a-b
Abs
ACos
AddSOAPRequestHeader
AddSOAPResponseHeader
AjaxLink
AjaxOnLoad
ApplicationStop
ArrayAppend
ArrayAvg
ArrayClear
ArrayContains
ArrayDelete
ArrayDeleteAt
ArrayEach
ArrayFilter
ArrayFind
ArrayFindAll
ArrayFindAllNoCase
ArrayFindNoCase
ArrayInsertAt
ArrayIsDefined
ArrayIsEmpty
arrayLen
ArrayMap
ArrayMax
ArrayMin
ArrayNew
ArrayPrepend
ArrayReduce
ArrayResize
ArraySet
ArraySlice
ArraySort
ArraySum
ArraySwap
ArrayToList
Asc
ASin
Atn
AuthenticatedContext
AuthenticatedUser
BinaryDecode
BinaryEncode
BitAnd
BitMaskClear
BitMaskRead
BitMaskSet
BitNot
BitOr
BitSHLN
BitSHRN

© 2014 Adobe Systems Incorporated. All rights reserved.

1337

Adobe ColdFusion Documentation

BitXor
ArrayDeleteNoCase

© 2014 Adobe Systems Incorporated. All rights reserved.

1338

Adobe ColdFusion Documentation

Abs
Description

Absolute-value function. The absolute value of a number is the number without its sign.
Returns

The absolute value of a number.
Category

Mathematical functions
Function syntax

Abs(number)

See also

Sgn
Parameters

Parameter

Description

number

A number

Example

Abs Example
The absolute value of the following numbers:
1,3,-4,-3.2,6 is

#Abs(1)#,#Abs(3)#,#Abs(-4)#,#Abs(-3.2)#,#Abs(6)#

The absolute value of a number is the number without its sign.

© 2014 Adobe Systems Incorporated. All rights reserved.

1339

Adobe ColdFusion Documentation

ACos
Description

Arccosine function. The arccosine is the angle whose cosine is number.
Returns

The arccosine, in radians, of a number.
Category

Mathematical functions
Function syntax

ACos(number)

See also

Cos, Sin, ASin, Tan, Atn, Pi
Parameters

Parameter

Description

number

Cosine of an angle. The value must be between -1.0
and 1.0, inclusive.

Usage

The range of the result is 0 to p.To convert degrees to radians, multiply degrees by p/180. To convert radians to
degrees, multiply radians by 180/p.
Example

© 2014 Adobe Systems Incorporated. All rights reserved.

1340

Adobe ColdFusion Documentation

ACos Example




ACos(#FORM.CosNum#) = #ACos(FORM.cosNum)# Radians 

or

ACos(#FORM.CosNum#) = #ACos(FORM.cosNum) * 180/PI()#


Enter a number between -1 and 1




Enter a number to get its arccosine in Radians and Degrees.


 


© 2014 Adobe Systems Incorporated. All rights reserved.

1341

Adobe ColdFusion Documentation

AddSOAPRequestHeader
Description

Adds a SOAP header to a web service request before making the request.
Returns

Nothing.
Category

XML functions
Function syntax

AddSOAPRequestHeader(webservice, namespace, name, value [, mustunderstand])

See also

AddSOAPResponseHeader, GetSOAPRequest, GetSOAPRequestHeader, GetSOAPResponse, GetSOAPRespo
nseHeader, IsSOAPRequest; Basic web service concepts in the Developing ColdFusion Applications
History

ColdFusion MX 7: Added this function.
Parameters

Parameter

Description

webservice

A web service object as returned from the cfobject t
ag or the CreateObject function.

namespace

A string that is the namespace for the header.

name

A string that contains the name of the SOAP header in
the request.

value

The value for the SOAP header; this can be a CFML
XML value.

mustunderstand

Optional. True or False (default). Sets the SOAP
mustunderstand value for this header.

Usage

Used within CFML code by a consumer of a web service before it calls the web service.If you pass XML in the valu
e parameter, ColdFusion ignores the namespace and name parameters. If you require a namespace, define it within
the XML itself.
Example

© 2014 Adobe Systems Incorporated. All rights reserved.

1342

Adobe ColdFusion Documentation

There are two parts to this example. The first part is the web service CFC that this function (as well as the other
ColdFusion SOAP functions) uses to demonstrate its interaction with a web service. To implement the web service
for this function, see the example for AddSOAPResponseHeader.Execute the following example as a client to see
how the AddSOAPRequestHeader function operates.


AddSOAPRequestHeader Example

// Create the web service object.
ws = CreateObject("webservice",
"http://localhost/soapheaders/headerservice.cfc?WSDL");
// Set the username header as a string.
addSOAPRequestHeader(ws, "http://mynamespace/", "username", "tom", false);
// Set the password header as a CFML XML object.
doc = XmlNew();
doc.password = XmlElemNew(doc, "http://mynamespace/", "password");
doc.password.XmlText = "My Voice is my Password";
doc.password.XmlAttributes["xsi:type"] = "xsd:string";
addSOAPRequestHeader(ws, "ignoredNameSpace", "ignoredName", doc);
// Invoke the web service operation.
ret = ws.echo_me("argument");
// Get the first header as an object (string) and as XML.
header = getSOAPResponseHeader(ws, "http://www.tomj.org/myns", "returnheader");
XMLheader = getSOAPResponseHeader(ws, "http://www.tomj.org/myns", "returnheader",
true);
// Get the second header as an object (string) and as XML.
header2 =getSOAPResponseHeader(ws, "http://www.tomj.org/myns", "returnheader2");
XMLheader2 = getSOAPResponseHeader(ws, "http://www.tomj.org/myns", "returnheader2",
true);



Soap Header value: #HTMLCodeFormat(header)#

Soap Header XML value: #HTMLCodeFormat(XMLheader)#

Soap Header 2 value: #HTMLCodeFormat(header2)#

Soap Header 2 XML value: #HTMLCodeFormat(XMLheader2)#

Return value: #HTMLCodeFormat(ret)#





The cfinvoke tag returned: #ret#

© 2014 Adobe Systems Incorporated. All rights reserved.

1343

Adobe ColdFusion Documentation

AddSOAPResponseHeader
Description

Adds a SOAP response header to a web service response. Call only from within a CFC web service function that is
processing a request as a SOAP web service.
Returns

Nothing
Category

XML functions
Function syntax

AddSOAPResponseHeader(namespace, name, value [, mustunderstand])

See also

AddSOAPRequestHeader, GetSOAPRequest, GetSOAPRequestHeader, GetSOAPResponse, GetSOAPRespon
seHeader, IsSOAPRequest; Basic web service concepts in the Developing ColdFusion Applications
History

ColdFusion MX 7: Added this function.
Parameters

Parameter

Description

namespace

A string that is the namespace for the header.

name

A string that contains the name of the SOAP header in
the request.

value

The value for the SOAP header; this can be a CFML
XML value.

mustunderstand

Optional. True or False (default). Sets the SOAP
mustunderstand value for this header.

Usage

Call this function only from within a CFC web service function. It throws an error if it is invoked in a context that is not
a web service request.If you pass XML in the value parameter, ColdFusion ignores the namespace and name
parameters. If you require a namespace, define it within the XML itself.Use the IsSOAPRequest function to
determine if the CFC is running as a web service.
Example

© 2014 Adobe Systems Incorporated. All rights reserved.

1344

Adobe ColdFusion Documentation

This example creates a CFC web service that illustrates the operation of the AddSOAPResponseHeader function
and also provides a web service that illustrates the operation of other ColdFusion SOAP functions. Save the
following code as headerservice.cfc in a folder called soapheaders under your web root. Test its operation, and
specifically the operation of the AddSOAPResponseHeader function, by executing the examples that invoke this
web service. For example, see the example for AddSOAPRequestHeader.

AddSOAPResponseHeader Example










 as XML: " & xmlusername>




 as XML: " & xmlpassword>
















© 2014 Adobe Systems Incorporated. All rights reserved.

1345

Adobe ColdFusion Documentation

AjaxLink
Description

Causes an HTML href attribute to display link results in the current Ajax container. When the browser follows a link
that is specified by this function, the HTTP response does not replace the current page; instead, it populates the
containing cfdiv, cflayoutarea, cfpod, or cfwindow control.
Returns

Code that causes the linked page to be displayed in the containing control.
Category

Display and formatting functions
Function syntax

AjaxLink(URL)

See also

cfdiv, cflayoutarea, cfpod, cfwindow, Using Ajax User Interface Components and Features in the Developin
g ColdFusion Applications
History

ColdFusion 8: Added this function.
Parameters

Parameter

Description

URL

The URL of the link.

Usage

This function has an effect only when it is used to specify the URL of an href attribute when the HTML a tag is
inside a cfdiv, cflayoutarea, cfpod, or cfwindow control. Otherwise, the link has its normal effect.To prevent
cross-site scripting, ColdFusion does not load a remote web page.
Example


Click me


© 2014 Adobe Systems Incorporated. All rights reserved.

1346

Adobe ColdFusion Documentation

AjaxOnLoad
Description

Causes the specified JavaScript function to run when the page loads.
Returns

This function does not return a value.
Category

Display and formatting functions
Function syntax

AjaxOnLoad(functionName)

See also

cfdiv, cflayoutarea, cfpod, cfwindow, Using Ajax User Interface Components and Features in the Developin
g ColdFusion Applications
History

ColdFusion 8: Added this function.
Parameters

Parameter

Description

functionName

The name of the function to run when the page loads.
The specified function does not take a parameter.

Usage

This function causes a JavaScript function to run when a page loads in the browser. The JavaScript function can
perform any initialization actions that are required for the page to function properly. For example, a login window
might open on a page if the user is not already logged in. You can use the AjaxOnLoad function to specify a
JavaScript function that determines the login status and opens the window only if needed.You can use this function
on top-level pages, or on pages that you dynamically include in your application by using the source attribute of the
cfpod and cfwindow tags.
Example

The following example uses the AjaxOnLoad function to call an init function each time the page loads. The init fu
nction displays a login window.

© 2014 Adobe Systems Incorporated. All rights reserved.

1347

Adobe ColdFusion Documentation












mail server:



username:



password:



 










© 2014 Adobe Systems Incorporated. All rights reserved.

1348

Adobe ColdFusion Documentation

ApplicationStop
Description

Stops or resets the current application. The application is restarted on the next request to the application.
Returns

void
Category

Other functions
Function Syntax

applicationstop()

History

Added in ColdFusion 9.
Example

© 2014 Adobe Systems Incorporated. All rights reserved.

1349

Adobe ColdFusion Documentation



...
....




#artist.getFullName()#



Item
Price
Sold


#index.getArtName()#
#index.getPrice()#
#index.getIsSold()#



View list


Artworks for the selected artists are not available



© 2014 Adobe Systems Incorporated. All rights reserved.

1350

Adobe ColdFusion Documentation

ArrayAppend
Description

Appends an array element to an array.
Returns

True, on successful completion.
Category

Array functions
Function syntax

ArrayAppend(array, value [,merge])

See also

ArrayPrepend; Adding elements to an array in Basic array techniques in the Developing ColdFusion
Applications
History

ColdFusion MX: Changed behavior: this function can be used on XML objects.
Parameters

Parameter

Description

array

Name of an array

arrayAppend

A boolean value that decides if array elements are
added as one element at the end of the source array.
By default, it would be false thereby retaining the old
behavior.

value

Value to add at end of array

merge

If set to true appends array elements individually to
the source array. If false (default) the complete array
is added as one element at the end, in the source
array.

Example

© 2014 Adobe Systems Incorporated. All rights reserved.

1351

Adobe ColdFusion Documentation

ArrayAppend Example

SELECT FirstName, LastName FROM Employees







#ArrayAppend(myArray, "#FirstName# #LastName#")#
, Array was appended






The contents of the array are as follows:
#myList#


© 2014 Adobe Systems Incorporated. All rights reserved.

1352

Adobe ColdFusion Documentation

ArrayAvg
Description

Calculates the average of the values in an array.
Returns

Number. If the array parameter value is an empty array, returns zero.
Category

Array functions, Mathematical functions
Function syntax

ArrayAvg(array)

See also

ArraySum; Basic array techniques in the Developing ColdFusion Applications
Parameters

Parameter

Description

array

Name of an array

Usage

The following example uses the ColdFusion built-in variable Form.fieldNames, which is available on the action
page of a form. It contains a comma-delimited list of the names of the fields on the form.
Example














ArrayAvg Example
 This example uses ArrayAvg to find the average of the numbers that you enter

© 2014 Adobe Systems Incorporated. All rights reserved.

1353

Adobe ColdFusion Documentation

into an array.

To enter more than two numbers click the more button.








Number #LoopItem#



















The average of the numbers that you entered is
#ArrayAvg(myNumberArray)#.

Try again. You must enter at least two numeric values.




© 2014 Adobe Systems Incorporated. All rights reserved.

1354

Adobe ColdFusion Documentation




© 2014 Adobe Systems Incorporated. All rights reserved.

1355

Adobe ColdFusion Documentation

ArrayClear
Description

Deletes the data in an array.
Returns

True, on successful completion.
Category

Array functions
Function syntax

ArrayDeleteAt; Functions for XML object management in Modifying a ColdFusion XML object in the Dev
eloping ColdFusion ApplicationsSee also
History

ColdFusion MX: Changed behavior: This function can be used on XML objects.
Parameters

Parameter

Description

array

Name of an array

Example

foo = ["a", "b"];
arrayClear( foo );
// array foo is now empty

© 2014 Adobe Systems Incorporated. All rights reserved.

1356

Adobe ColdFusion Documentation

ArrayContains
Description

Description: Searches an array for the presence of a specified object. The function searches for simple objects such
as strings and numbers or for complex objects such as structures. Simple object string searches are case-sensitive.
This function does not support searches for COM and CORBA objects.
Returns

Yes, if the specified object exists in the array.
Category

Array functions
Function Syntax

ArrayContains(array,object)

See Also

ArrayFind, ArrayFindNoCase
Parameters

Parameter

Description

array

Array to search in

object

Object to search for.

Example

© 2014 Adobe Systems Incorporated. All rights reserved.

1357

Adobe ColdFusion Documentation

ArrayContains Example
2-dimensional array example

1-dimensional array example





Checking if value exists

#ArrayContains(montharray, "December")#


© 2014 Adobe Systems Incorporated. All rights reserved.

1358

Adobe ColdFusion Documentation

ArrayDelete
Description

Searches an array for the first position of a specified object and deletes it. The function searches for simple objects
such as strings and numbers or for complex objects such as structures. Simple object string searches are
case-sensitive. This function does not support searches for COM and CORBA objects.
Returns

Yes, on successful deletion of the array element.
Category

Array functions
Function syntax

ArrayDelete(array,object)

See Also
ArrayDeleteAt, ArrayClear
Parameters

Parameter

Description

array

Array to search in.

object

Object to search for.

Example


array = ["string","string"];
writeOutput(arrayDelete(array, "string"));
writeDump(array);


© 2014 Adobe Systems Incorporated. All rights reserved.

1359

Adobe ColdFusion Documentation

ArrayDeleteAt
Description

Deletes an element from a specified position in an array. When an element is deleted, ColdFusion recalculates
index positions. For example, in an array that contains the months of the year, deleting the element at position 5
removes the entry for May. After this, to delete the entry for June, you would delete the element at position 5 (not 6).
Returns

True, on successful completion.
Category

Array functions
Function syntax

ArrayDeleteAt(array, position)

See also

ArrayInsertAt; Functions for XML object management in Modifying a ColdFusion XML object in the Dev
eloping ColdFusion Applications
History

ColdFusion MX:
Changed behavior: This function can be used on XML objects.
Changed thrown exceptions: This function can throw the InvalidArrayIndexException error.
Parameters

Parameter

Description

array

Name of an array

position

Array position

Throws

If this function attempts to delete an element at position 0, or specifies a value for position that is greater than the
size of array, this function throws an InvalidArrayIndexException error.
Example

© 2014 Adobe Systems Incorporated. All rights reserved.

1360

Adobe ColdFusion Documentation

ArrayDeleteAt Example










This is what the array looks like before delete:


#DaysArray[1][1]#  #DaysArray[1][2]#

#DaysArray[2][1]#  #DaysArray[2][2]#

#DaysArray[3][1]#  #DaysArray[3][2]#



We delete this element of the array:

#ArrayDeleteAt(DaysArray,2)#



This is what the array looks like after delete:


#DaysArray[1][1]#  #DaysArray[1][2]#

#DaysArray[2][1]#  #DaysArray[2][2]#



© 2014 Adobe Systems Incorporated. All rights reserved.

1361

Adobe ColdFusion Documentation

ArrayEach
Description

Used to loop over an array.
Returns

Nothing
Category

Closure functions
Syntax

arrayEach(array,function(any currentObj) {});
See also

Other closure functions.
History

ColdFusion 11: Passing array index to callback functions.
ColdFusion 10: Added this function.
Parameters

Parameter

Description

array

Name of the array object.

function

Callback executed for each element in the array.

Passing array index to callback functions in ArrayEach

ColdFusion 10 supports passing objects in a callback function. From ColdFusion 11, you can pass the index of an
array to the callback function as shown below:


cityArray = ["San Jose","New york","Boston", "Las Vegas"];
function printArrayCity(city, index)
{
writeOutput("
" & city & "
}

is at index " &

index);

ArrayEach(cityArray ,printArrayCity);


© 2014 Adobe Systems Incorporated. All rights reserved.

1362

Adobe ColdFusion Documentation

Also, the original array can also be passed to the closure function. So the following code is also valid:
...
function printArrayCity(city, index, cityArray)
{
}
...

Example


// example 1 using an inline callback
numbers = [1,2,3,4,5];
doubledNumbers = [];
arrayEach(numbers, function(number){
arrayAppend(doubledNumbers, number * 2);
});
writeOutput(arrayToList(doubledNumbers)); // outputs 2,4,6,8,10
// example 2, using a separately-defined function
numbers = [1,2,3,4,5];
doubledNumbers = [];
function double(number){
arrayAppend(doubledNumbers, number * 2);
}
arrayEach(numbers, double); // here we use the NAME of an existing UDF
writeOutput(arrayToList(doubledNumbers)); // outputs 2,4,6,8,10


© 2014 Adobe Systems Incorporated. All rights reserved.

1363

Adobe ColdFusion Documentation

ArrayFilter
Description

Used to filter the elements of an array.
Returns

A new array
Category

Closure functions
Syntax

arrayFilter(array,function(arrayElement){return true|false;});
Example


names = ["Ray","Adam","Scott","Todd","Dave"];
shortNames = arrayFilter(names, function(n) {
return len(n) < 4;
});
writeDump(shortNames);


See also

Other closure functions.
History

ColdFusion 10: Added this function.
Parameters

Parameter

Description

array

Name of the array object.

function

Inline function executed for each element in the array.
Returns true if the array element has to be included in
the resultant array.

arrayElement

Array element being accessed.

© 2014 Adobe Systems Incorporated. All rights reserved.

1364

Adobe ColdFusion Documentation

ArrayFind
Description

Searches an array for the first position of a specified object. The function searches for simple objects such as strings
and numbers or for complex objects such as structures. When the second parameter is a simple object, string
searches are case-sensitive. This function does not support searches for COM and CORBA objects.
Returns

Index in the array of the first match, or 0 if there is no match.
Category

Array functions
Function syntax

ArrayFind(array, object)
ArrayFind(array, function(arrayElement) {return true|false;})

See Also

ArrayFindNoCase
Parameters

Parameter

Description

array

Array to search in.

function

Inline function executed for each element in the array.
Returns true if the array element matches the search
criterion.

object

Object to search for.

arrayElement

Array element being accessed.

Example


writeDump(ArrayFind(["STRING","string"], "string"));
writeDump(ArrayFind(["STRING","string"], function(s) {if(compare(s, "string")==0)
return true; return false;}));


© 2014 Adobe Systems Incorporated. All rights reserved.

1365

Adobe ColdFusion Documentation

ArrayFindAll
Description

Searches an array for all positions of a specified object. The function searches for simple objects such as strings
and numbers or for complex objects such as structures. When the second parameter is a simple object, string
searches are case-sensitive. This function does not support searches for COM and CORBA objects.
Returns

Array of indices in which the object was found.
Category

Closure functions
Syntax

ArrayFindAll(array, object)
ArrayFindAll(array, function(arrayElement) {return true|false;})

See also
Other closure functions.
History

ColdFusion 10: Added this function.
Parameters

Parameter

Description

array

Array to search in.

object

Object to search for.

function

Inline function executed for each element in the array.
Returns true if the array elements match the search
criterion.

arrayElement

Array element being accessed.

Example


writeDump(ArrayFindAll(["STRING","string"], "string"));
writeDump(ArrayFindAll(["STRING","string"], function(s) {if(compare(s,
"string")==0) return true; return false;}));


© 2014 Adobe Systems Incorporated. All rights reserved.

1366

Adobe ColdFusion Documentation

ArrayFindAllNoCase
Description

Description: Searches an array for all positions of a specified object. The function searches for simple objects such
as strings and numbers or for complex objects such as structures. When the second parameter is a simple object,
string searches are not case-sensitive. This function does not support searches for COM and CORBA objects.
Note that ArrayFindAllNoCase() behaves identically to ArrayFindAll(), except in the special cases where the second
parameter is a function or you are searching for a string in an array of strings. When the second parameter is a
function, ArrayFindAll() executes the function for each element in the array and ArrayFindAllNoCase() searches the
array for the function.
Returns

Array of indices in which the object was found.
Category

Closure functions
Syntax

ArrayFindAllNoCase(array, object)

See also

Other closure functions.
History

ColdFusion 10: Added this function.
Parameters

Parameter

Description

array

Array to search in.

object

Object to search for.

function

Inline function executed for each element in the array.
Returns true if the array elements match the search
criterion.

arrayElement

Array element being accessed.

Example

© 2014 Adobe Systems Incorporated. All rights reserved.

1367

Adobe ColdFusion Documentation


writeDump(ArrayFindAllNoCase(["STRING","string"], "string"));


© 2014 Adobe Systems Incorporated. All rights reserved.

1368

Adobe ColdFusion Documentation

ArrayFindNoCase
Description

Searches an array for the first position of a specified object. The function searches for simple objects such as strings
and numbers or for complex objects such as structures. When the second parameter is a simple object, string
searches are not case-sensitive. This function does not support searches for COM and CORBA objects.
Note that ArrayFindNoCase() behaves identically to ArrayFind(), except in the special cases where the second
parameter is a function or you are searching for a string in an array of strings. When the second parameter is a
function, ArrayFind() executes the function for each element in the array and ArrayFindNoCase() searches the array
for the function.
Returns

Index in the array of the first match, or 0 if there is no match.
Category

Array functions
History

ColdFusion 9: Added this function.
Function syntax

ArrayFindNoCase(array, object)

See Also

ArrayFind
Parameters

Parameter

Description

array

Array to search in.

object

Object to search for

function

Inline function executed for each element in the array.
Returns true if the array element matches the search
criterion.

arrayElement

Array element being accessed.

Example

© 2014 Adobe Systems Incorporated. All rights reserved.

1369

Adobe ColdFusion Documentation


writeOutput(ArrayFindNoCase(["STRING","string"], "string"));


© 2014 Adobe Systems Incorporated. All rights reserved.

1370

Adobe ColdFusion Documentation

ArrayInsertAt
Description

Inserts a value into an array. Array elements whose indexes are equal to or greater than the new position are
incremented by one. The array length increases by one.
Returns

True, on successful completion.
Category

Array functions
Function syntax

ArrayInsertAt(array, position, value)

See also

ArrayDeleteAt; Functions for XML object management in Modifying a ColdFusion XML object in the De
veloping ColdFusion Applications
History

ColdFusion MX:
Changed behavior: This function can be used on XML objects.
Changed thrown exceptions: This function can throw the InvalidArrayIndexException error.
Parameters

Parameter

Description

array

Name of an array

position

Index position at which to insert value

value

Value to insert

Usage

To apply the ArrayInsertAt() function to a multidimensional array, you must specify all but the last index in the
array parameter. The following example inserts an element at myarray24:



Throws

© 2014 Adobe Systems Incorporated. All rights reserved.

1371

Adobe ColdFusion Documentation

If this function attempts to insert an element at position 0, or specifies a value for position that is greater than the
size of array, this function throws an InvalidArrayIndexException error.
Example

ArrayInsertAt Example








Add an element before position 3:
#ArrayInsertAt(DaysArray,3,"Wednesday")#
Now output the array as a list:
#ArrayToList(DaysArray)#


© 2014 Adobe Systems Incorporated. All rights reserved.

1372

Adobe ColdFusion Documentation

ArrayIsDefined
Description

Determines whether an array element is defined.
Returns

True, if the array element is defined (exists); false, otherwise.
Category

Array functions
Function syntax

ArrayIsDefined(array, elementIndex)

See also

ArrayIsEmpty
History

ColdFusion 8: Added this function.
Parameters

Parameter

Description

array

Name of a one-dimensional array, or the array name
and indexes into higher-order dimensions of a
multidimensional array.

elementIndex

Index of the element in a one-dimensional array, or the
index of the element in the final dimension of a
multidimensional array.

Usage

The index value of an element must be less than the length of the array.To test the existence of an element in a
multidimensional array, specify all but the last dimension of the array in the first parameter. For example, the
following line tests the existence of element MyArray241:

ArrayIsDefined(MyArray[2][4], 1)

Example

© 2014 Adobe Systems Incorporated. All rights reserved.

1373

Adobe ColdFusion Documentation

ArrayIsDefined Example







Your array contents are:


Does element 3 exist?: 
#ArrayIsDefined(MyArray, 3)#

Does element 2 exist? 
#ArrayIsDefined(MyArray, 2)#


© 2014 Adobe Systems Incorporated. All rights reserved.

1374

Adobe ColdFusion Documentation

ArrayIsEmpty
Description

Determines whether an array is empty of data elements.
Returns

True, if the array is empty; False, otherwise.
Category

Array functions
Function syntax

ArrayIsEmpty(array)

See also

ArrayIsDefined, arrayLen, Functions for XML object management in Modifying a ColdFusion XML object in the
Developing ColdFusion Applications
History

ColdFusion MX: Changed behavior: this function can be used on XML objects.
Parameters

Parameter

Description

array

Name of an array

Usage

You can test whether an element of a higher level dimension of a multidimensional array is empty by specifying the
element in the ArrayIsEmpty function. To test whether the first row of the two-dimensional array MyArray is
empty, use the following function:

ArrayIsEmpty(MyArray2[1])

Example

© 2014 Adobe Systems Incorporated. All rights reserved.

1375

Adobe ColdFusion Documentation

ArrayIsEmpty Example






Your array contents are:
#ArrayToList(MyArray)#

Is the array empty?:
#ArrayIsEmpty(MyArray)#
Now, clear the array:



Is the array empty?:
#ArrayIsEmpty(MyArray)#

© 2014 Adobe Systems Incorporated. All rights reserved.

1376

Adobe ColdFusion Documentation

arrayLen
Description

Determines the number of elements in an array.
Returns

The number of elements in an array.
Category

Array functions
Function syntax

arrayLen(array)

See also

ArrayIsEmpty; Functions for XML object management in Modifying a ColdFusion XML object in the Devel
oping ColdFusion Applications
History

ColdFusion MX: Changed behavior: This function can be used on child XML objects.
Parameters

Parameter

Description

array

Name of an array

Example

© 2014 Adobe Systems Incorporated. All rights reserved.

1377

Adobe ColdFusion Documentation

arrayLen Example

SELECT FirstName, LastName FROM Employees













The contents of the array are as follows:
#myList#
This array has #arrayLen(MyArray)# elements.


© 2014 Adobe Systems Incorporated. All rights reserved.

1378

Adobe ColdFusion Documentation

ArrayMap
Description
Iterates over every entry of the array and calls the closure function to work on the element of the array. The returned
value will be set at the same index in a new array and the new array will be returned
Returns

Array
Syntax

ArrayMap(array, function(item [,index, array]))

History

ColdFusion 11: Added this function.
Attributes

Attribute

Req/Opt

Default

Description

array

Required

The input array.

function

Required

Closure or a function
reference that will be
called for each of the
iteration. The arguments
passed to the callback are
item: item in the array
index: index of the array
array: a reference of the
original arrray

© 2014 Adobe Systems Incorporated. All rights reserved.

1379

Adobe ColdFusion Documentation

ArrayMax
Description

Array maximum function.
Returns

The largest numeric value in an array. If the array parameter value is an empty array, returns zero.
Category

Array functions
Function syntax

ArrayMax(array)

Parameters

Parameter

Description

array

Name of an array

Example

ArrayMax Example
This example uses ArrayMax to find the largest number in an array.
 







The largest number that you entered is
#ArrayMax(myNumberArray)#.













© 2014 Adobe Systems Incorporated. All rights reserved.

1380

Adobe ColdFusion Documentation

ArrayMin
Description

Array minimum function.
Returns

The smallest numeric value in an array. If the array parameter value is an empty array, returns zero.
Category

Array functions
Function syntax

ArrayMin(array)

Parameters

Parameter

Description

array

Name of an array

Example

ArrayMin Example
This example uses ArrayMin to find the smallest number in an array.








The smallest number that you entered is
#ArrayMin(myNumberArray)#.













© 2014 Adobe Systems Incorporated. All rights reserved.

1381

Adobe ColdFusion Documentation

ArrayNew
Description

Creates an array of 1-3 dimensions. Index array elements with square brackets: [ ].ColdFusion arrays expand
dynamically as data is added.
Returns

An array
Category

Array functions
Function syntax

ArrayNew(dimension)

Parameters

Parameter

Description

dimension

Number of dimensions in new array: 1, 2, or 3

Example

ArrayNew Example










Is this an array? #IsArray(MyNewArray)#
It has #ArrayLen(MyNewArray)# elements.
Contents: #ArrayToList(MyNewArray)#



© 2014 Adobe Systems Incorporated. All rights reserved.

1382

Adobe ColdFusion Documentation

ArrayPrepend
Description

Inserts an array element at the beginning of an array.
Returns

True, on successful completion.
Category

Array functions
Function syntax

ArrayPrepend(array, value)

See also

ArrayAppend; Adding elements to an array in Basic array techniques in the Developing ColdFusion
Applications
Parameters

Parameter

Description

array

Name of an array

value

Value to insert at beginning of array

Example

© 2014 Adobe Systems Incorporated. All rights reserved.

1383

Adobe ColdFusion Documentation

ArrayPrepend Example

SELECT FirstName, LastName FROM Employees







#ArrayPrepend(myArray, "#FirstName# #LastName#")#
, Array was prepended






The contents of the array are as follows:
#myList#


© 2014 Adobe Systems Incorporated. All rights reserved.

1384

Adobe ColdFusion Documentation

ArrayReduce
Description
Iterates over every entry of the array and calls the closure to work on the elements of the array. This function will
reduce the array to a single value and will return the value.
Returns

any
Syntax

ArrayReduce(array, function(result, item, [,index, array])[, initialValue])

History

ColdFusion 11: Added this function.
Attributes

Attribute

Req/Opt

Default

Description

array

Required

The input array.

function

Required

Closure or a function
reference that will be
called for each of the
iteration. The arguments
passed to the callback are
result: result of the
reduce operation after
the previous iteration
item: item in the array
index : current index for
the iteration
array : reference of the
original array

initialValue

Optional

Initial value which will be
used for the reduce
operation. The type is
any.

Example

© 2014 Adobe Systems Incorporated. All rights reserved.

1385

Adobe ColdFusion Documentation


arr = [1,2,3,4,5];
function square(element, index)
{
writeOutput("index is " & index);
return element * element;
}

sq = arrayMap(arr, square);
writeDump(sq);
result = arrayReduce(sq, function(value, element)
{
value = value?:0;
value += element;
return value;
});
writeDump(result);


© 2014 Adobe Systems Incorporated. All rights reserved.

1386

Adobe ColdFusion Documentation

ArrayResize
Description

Resets an array to a specified minimum number of elements. Resetting can improve performance, if used to size an
array to its expected maximum. For more than 500 elements, use ArrayResize immediately after using the Array
New tag.ColdFusion arrays expand dynamically as data is added.
Returns

True, on successful completion.
Category

Array functions
Function syntax

ArrayResize(array, minimum_size)

Parameters

Parameter

Description

array

Name of an array

minimum_size

Minimum array size

Example

ArrayResize Example


SELECT * FROM Courses






The array is now #ArrayLen(MyArray)# elements, to match
the query of #GetCourses.RecordCount# records.


© 2014 Adobe Systems Incorporated. All rights reserved.

1387

Adobe ColdFusion Documentation

ArraySet
Description

In a one-dimensional array, sets the elements in a specified index range to a value. Useful for initializing an array
after a call to ArrayNew.
Returns

True, on successful completion.
Category

Array functions
Function syntax

ArraySet(array, start_pos, end_pos, value)

See also

ArrayNew; Populating arrays with data in the Developing ColdFusion Applications
History

ColdFusion MX: Changed behavior: This function can be used on XML objects.
Parameters

Parameter

Description

array

Name of an array.

start_pos

Starting index position of range to set.

end_pos

Ending index position of range to set. If this value is
greater than array length, ColdFusion adds elements to
array.

value

Value to which to set each element in the range.

Example

© 2014 Adobe Systems Incorporated. All rights reserved.

1388

Adobe ColdFusion Documentation

ArraySet Example








...

© 2014 Adobe Systems Incorporated. All rights reserved.

1389

Adobe ColdFusion Documentation

ArraySlice
Description

Returns part of an array with only the elements you need.
Returns

Portion of an array based on the offset and length settings.
History

ColdFusion 10: Added this function.
Syntax

arraySlice(array,offset,length)
Properties

Parameter

Description

array

Name of the array that you want to slice.

offset

Specifies the position from which to slice the array.
Negative value indicates that the array is sliced, with
sequence starting from array's end.

length

Element count from offset.

Example


array = [1, 2, 3, 4, 5, 6, 7, 8];
newArray = arraySlice(array, 2, 3);//returns 2,3,4
newArray = arraySlice(array, 4);//returns 4,5,6, 7, 8
newArray = arraySlice(array, -5, 3);//returns 4,5,6


© 2014 Adobe Systems Incorporated. All rights reserved.

1390

Adobe ColdFusion Documentation

ArraySort
Description

Sorts array elements numerically or alphanumerically.
Returns

True, if sort is successful; False, otherwise.
Category

Array functions, List functions
Function syntax

ArraySort(array, sort_type [, sort_order ])

Or:

ArraySort(array, callback)

History

ColdFusion 10:
Added the localeSensitive attribute.
Added alternative callback-based syntax
ColdFusion MX:
Changed thrown exceptions: This function can throw the ArraySortSimpleValueException error and
ValueNotNumeric error.
Changed the order in which sorted elements are returned: In a textnocase, descending sort, this function
might return elements in a different sort order than in earlier releases. If sort_type = "textnocase" and
sort_order = "desc", ColdFusion processes elements that differ only in casedifferently from earlier
releases, as follows:
ColdFusion reverses the elements' original order.
Releases earlier than ColdFusion MX do not change the elements' original order.
For example, in a textnocase, desc sort of d,a,a,b,A, the following occurs:
ColdFusion MX and later returns d,b,A,a,a
Releases earlier than ColdFusion MX return d,b,a,a,A
Parameters

Parameter

Description

array

Name of an array

© 2014 Adobe Systems Incorporated. All rights reserved.

1391

Adobe ColdFusion Documentation

localeSensitive

sort_type

Specify if you wish to do a locale sensitive sorting. The
default value is false.
numeric: sorts numbers
text: sorts text alphabetically, taking case into
account (also known as case sensitive). All letters of
one case precede the first letter of the other case:
aabzABZ, if sort_order = "asc" (ascending
sort)- ZBAzbaa, if sort_order = "desc" (descen
ding sort)
textnocase: sorts text alphabetically, without regard
to case (also known as case-insensitive). A letter in
varying cases precedes the next letter:
aAaBbBzzZ, in an ascending sort; preserves original
intra-letter order - ZzzBbBaAa, in a descending sort;
reverses original intra-letter order

sort_order

asc - ascending sort order. Default.
aabzABZ or aAaBbBzzZ, depending on value of sor
t_type, for letters- from smaller to larger, for
numbers
desc - descending sort order.
ZBAzbaa or ZzzBbBaAa, depending on value of sor
t_type, for letters- from larger to smaller, for
numbers

callback

A function which take two elements of the array, and
returns whether the first is less than (-1), equal to (0) or
greater than (1) the second one (similar to how compar
e() works for strings).

Throws

If an array element is something other than a simple element, this function throws an
ArraySortSimpleValueException error. If sort_type is numeric and an array element is not numeric, this function
throws a ValueNotNumeric error.
Usage

In ColdFusion 10, added support for all Java supported locale-specific characters (including support for umlaut
characters). A flag for this support has been added for sorttype = "text" or sorttype = "textnocase".
Example

© 2014 Adobe Systems Incorporated. All rights reserved.

1392

Adobe ColdFusion Documentation



SELECT FirstName, LastName FROM Employees











...

Example using a callback:


authors = [
{firstName="Witi", lastName="Ihimaera"},
{firstName="Patricia", lastName="Grace"},
{firstName="Alan", lastName="Duff"},
{firstName="Lee", lastName="Tamahori"}, // OK: not an author
{firstName="Keri", lastName="Hulme"}
];
arraySort(
authors,
function (e1, e2){
return compare(e1.lastName, e2.lastName);
}
);
writeDump(authors);


Note that the callback function does not need to be inline, as in the example; it can be any predefined user-defined
function.

© 2014 Adobe Systems Incorporated. All rights reserved.

1393

Adobe ColdFusion Documentation

ArraySum
Description

Array sum function.
Returns

The sum of values in an array. If the array parameter value is an empty array, returns zero.
Category

Array functions, Mathematical functions
Function syntax

ArraySum(array)

Parameters

Parameter

Description

array

Name of an array

Example

ArraySum Example
This example uses ArraySum to add two numbers.
 







The sum of the numbers is
#ArraySum(myNumberArray)#.















© 2014 Adobe Systems Incorporated. All rights reserved.

1394

Adobe ColdFusion Documentation

© 2014 Adobe Systems Incorporated. All rights reserved.

1395

Adobe ColdFusion Documentation

ArraySwap
Description

Swaps array values of an array at specified positions. This function is more efficient than multiple cfset tags.
Returns

True, on successful completion.
Category

Array functions
Function syntax

ArraySwap(array, position1, position2)

See also

Functions for XML object management in Modifying a ColdFusion XML object in the Developing ColdFusion
Applications
Parameters

Parameter

Description

array

Name of an array

position1

Position of first element to swap

position2

Position of second element to swap

Example

ArraySwap Example

month[1] = "February">
month[2] = "January">
temp = ArraySwap(month, 1, 2)>
temp = ArrayToList(month)>

Show the results: #temp#

© 2014 Adobe Systems Incorporated. All rights reserved.

1396

Adobe ColdFusion Documentation

ArrayToList
Description

Converts a one-dimensional array to a list.
Returns

Delimited list, as a string.
Category

Array functions, Conversion functions, List functions
Function syntax

ArrayToList(array [, delimiter ])

Parameters

Parameter

Description

array

Name of array

delimiter

Character or multicharacter string to separate list
elements. The default value is comma.

Example

© 2014 Adobe Systems Incorporated. All rights reserved.

1397

Adobe ColdFusion Documentation

ArrayToList Example

SELECT FirstName, LastName FROM Employees















The contents of the array are as follows:
#myList#
This array, alphabetized by first name (descending):
#myAlphaList#
This array has #ArrayLen(MyArray)# elements.


© 2014 Adobe Systems Incorporated. All rights reserved.

1398

Adobe ColdFusion Documentation

Asc
Description

Determines the value of a character.
Returns

The value of the first character of a string; if the string is empty, returns zero.
Category

String functions
Function syntax

Asc(string)

See also

Chr
History

ColdFusion MX: Changed Unicode support: ColdFusion supports the Java UCS-2 representation of Unicode
characters, up to a value of 65536. (Earlier releases supported 1-255.)
Parameters

Parameter

Description

string

A string

Example

© 2014 Adobe Systems Incorporated. All rights reserved.

1399

Adobe ColdFusion Documentation

Asc Example



#Left(FORM.charVals,1)# =
#Asc(FORM.charVals)#


Enter a character



Enter a character to see its ASCII value


 


© 2014 Adobe Systems Incorporated. All rights reserved.

1400

Adobe ColdFusion Documentation

ASin
Description

Determines the arcsine of a number. The arcsine is the angle whose sine is number.
Returns

The arcsine, in radians, of a number.
Category

Mathematical functions
Function syntax

ASin(number)

See also

Sin, Cos, ACos, Tan, Atn, Pi
Parameters

Parameter

Description

number

Sine of an angle. The value must be between -1 and 1,
inclusive.

Usage

The range of the result is -p/2 to p/2 radians. To convert degrees to radians, multiply degrees by p/180. To convert
radians to degrees, multiply radians by 180/p.
Example

© 2014 Adobe Systems Incorporated. All rights reserved.

1401

Adobe ColdFusion Documentation

ASin Example





ASin(#FORM.SinNum#) =
#ASin(FORM.sinNum)# Radians

 or 
ASin(#FORM.SinNum#) =

#ASin(FORM.sinNum) * 180/Pi()# Degrees



Enter the sine of the angle to calculate, in degrees and radians.
The value must be between 1 and -1, inclusive.



Enter the sine of the angle to calculate, in degrees and radians. The
value must be between 1 and -1, inclusive.



Enter the sine of the angle to calculate, in degrees and radians. The
value must be between 1 and -1,inclusive.



Enter a number to get its arcsine in Radians and Degrees.


 


© 2014 Adobe Systems Incorporated. All rights reserved.

1402

Adobe ColdFusion Documentation

Atn
Description

Arctangent function. The arctangent is the angle whose tangent is number.
Returns

The arctangent, in radians, of a number.
Category

Mathematical functions
Function syntax

Atn(number)

See also

Sin, ASin, Cos, ACos, Pi
Parameters

Parameter

Description

number

Tangent of an angle

Usage

The range of the result is -p/2 to p/2 radians. To convert degrees to radians, multiply degrees by p/180. To convert
radians to degrees, multiply radians by 180/p.
Example

Atn Example



Atn(#FORM.AtnNum#) is
#Atn(FORM.AtnNum)# radians is #Atn(FORM.AtnNum * 180/PI())#
Degrees


Enter a number



Enter a number to get its arctangent in Radians and Degrees


 


© 2014 Adobe Systems Incorporated. All rights reserved.

1403

Adobe ColdFusion Documentation

© 2014 Adobe Systems Incorporated. All rights reserved.

1404

Adobe ColdFusion Documentation

AuthenticatedContext
Description

This function is obsolete. Use the newer security tools; see Conversion functions and Securing Applications in the D
eveloping ColdFusion Applications.
History

ColdFusion MX: This function is obsolete. It does not work in ColdFusion MX and later ColdFusion releases.

© 2014 Adobe Systems Incorporated. All rights reserved.

1405

Adobe ColdFusion Documentation

AuthenticatedUser
Description

This function is obsolete. Use the newer security tools; see Conversion functions and Securing Applications in the D
eveloping ColdFusion Applications.
History

ColdFusion MX: This function is obsolete. It does not work in ColdFusion MX and later ColdFusion releases.

© 2014 Adobe Systems Incorporated. All rights reserved.

1406

Adobe ColdFusion Documentation

BinaryDecode
Description

Converts a string to a binary object. Used to convert binary data that has been encoded into string format back into
binary data.
Returns

A binary object.
Category

Conversion functions, String functions
Function syntax

BinaryDecode(string, binaryencoding)

See also

BinaryEncode, CharsetEncode, CharsetDecode
History

ColdFusion MX 7: Added this function.
Parameters

Parameter

Description

string

A string containing encoded binary data.

binaryencoding

A string that specifies the algorithm used to encode the
original binary data into a string; must be one of the
following:
Hex: the characters 0-9 and A-F represent the
hexadecimal value of each byte; for example, 3A.
UU: data is encoded using the UNIX UUencode
algorithm.
Base64: data is encoded using the Base64
algorithm, as specified by IETF RFC 2045, at www.ie
tf.org/rfc/rfc2045.txt.

Usage

Use this function to convert a binary-encoded string representation of binary data back to a binary object for use in
your application. Binary data is often encoded as a string for transmission over many Internet protocols, such as
HTTP and SMTP, or for storage in a database.Adobe recommends that you use the BinaryDecode function, not
the ToBinary(base64data) function, to convert Base64-encoded data to binary data in all new applications.See the
following pages for additional information on handling binary data:

© 2014 Adobe Systems Incorporated. All rights reserved.

1407

Adobe ColdFusion Documentation

cffile for loading and reading binary data in files
cfwddx for serializing and deserializing binary data
IsBinary for checking variables for binary format
Len for determining the length of a binary object
Example

The following example reads a GIF file as binary data, converts it to a binary-encoded string, converts the
binary-encoded data back to binary data and writes the result to a file. It displays the encoded string and the image
in the output file.

Binary Encoding Conversion Example






binencode=BinaryEncode(binimage, Form.binEncoding);
bindecode=BinaryDecode(binencode, Form.binEncoding);





The binary encoding: #Form.binEncoding#
The image converted into a binary-encoded string by BinaryEncode


#binencode#
The image as written back to a file after converting back to binary
using BinaryDecode







Select binary encoding


UU
Base64
Hex







© 2014 Adobe Systems Incorporated. All rights reserved.

1408

Adobe ColdFusion Documentation

BinaryEncode
Description

Converts binary data to a string.
Returns

An encoded string representing the binary data.
Category

Conversion functions, String functions
Function syntax

BinaryEncode(binarydata, encoding)

See also

BinaryDecode, CharsetEncode, CharsetDecode
History

ColdFusion MX 7: Added this function.
Parameters

Parameter

Description

binarydata

A variable containing the binary data to encode.

encoding

A string that specifies the encoding method to use to
represent the data; one of the following:
Hex: use the characters 0-9 and A-F to represent the
hexadecimal value of each byte; for example, 3A.
UU: use the UNIX UUencode algorithm to convert
the data.
Base64: use the Base64 algorithm to convert the
data, as specified by IETF RFC 2045, at www.ietf.org
/rfc/rfc2045.txt.

Usage

Binary objects and, in some cases, 8-bit characters, cannot be transported over many Internet protocols, such as
HTTP and SMTP, and might not be supported by some database systems. By Binary encoding the data, you
convert the data into a format that you can transfer over any Internet protocol or store in a database as character
data. To convert the data back to a binary format, use the BinaryDecode function. Adobe recommends that you
use the BinaryEncode function, and not the ToBase64(binarydata) function, to convert binary data to Base64 data
in all new applications.This function provides a superset of the functionality of the ToBase64(binarydata)
function.See the following pages for additional information on handling binary data:

© 2014 Adobe Systems Incorporated. All rights reserved.

1409

Adobe ColdFusion Documentation

cffile for loading and reading binary data
cfwddx for serializing and deserializing binary data
IsBinary for checking variables for binary format
Len for determining the length of a binary object
Example

The following example reads a GIF file as binary data, converts it to a binary-encoded string, converts the
binary-encoded data back to binary data, and writes the result to a file. It displays the encoded string and the image
in the output file.

Binary Encoding Conversion Example






binencode=BinaryEncode(binimage, Form.binEncoding);
bindecode=BinaryDecode(binencode, Form.binEncoding);





The binary encoding: #Form.binEncoding#
The image converted into a binary-encoded string by BinaryEncode


#binencode#
The image as written back to a file after converting back to binary
using BinaryDecode







Select binary encoding


UU
Base64
Hex







© 2014 Adobe Systems Incorporated. All rights reserved.

1410

Adobe ColdFusion Documentation

BitAnd
Description

Performs a bitwise logical AND operation.
Returns

The bitwise AND of two long integers.
Category

Mathematical functions
Function syntax

BitAnd(number1, number2)

See also

BitNot, BitOr, BitXor
Parameters

Parameter

Description

number1

32-bit signed integer

number2

32-bit signed integer

Usage

Bit functions operate on 32-bit signed integers, in the range -2147483648 - 2147483647.
Example

BitAnd Example
Returns the bitwise AND of two long integers.
BitAnd(5,255): #BitAnd(5,255)#
BitAnd(5,0): #BitAnd(5,0)#
BitAnd(128,128): #BitAnd(128,128)#

© 2014 Adobe Systems Incorporated. All rights reserved.

1411

Adobe ColdFusion Documentation

BitMaskClear
Description

Performs a bitwise mask clear operation.
Returns

A number, bitwise cleared, with length bits beginning at start.
Category

Mathematical functions
Function syntax

BitMaskClear(number, start, length)

See also

BitMaskRead, BitMaskSet
Parameters

Parameter

Description

number

32-bit signed integer

start

Integer, in the range 0-31, inclusive; start bit for mask

length

Integer, in the range 0-31, inclusive; length of mask

Usage

Bit functions operate on 32-bit signed integers, in the range -2147483648 - 2147483647.
Example

BitMaskClear Example
Returns number bitwise cleared with length bits beginning from start.
BitMaskClear(255, 4, 4): #BitMaskClear(255, 4, 4)#
BitMaskClear(255, 0, 4): #BitMaskClear(255, 0, 4)#
BitMaskClear(128, 0, 7): #BitMaskClear(128, 0, 7)#

© 2014 Adobe Systems Incorporated. All rights reserved.

1412

Adobe ColdFusion Documentation

BitMaskRead
Description

Performs a bitwise mask read operation.
Returns

An integer, created from length bits of_ number,_ beginning at start.
Category

Mathematical functions
Function syntax

BitMaskRead(number, start, length)

See also

BitMaskClear, BitMaskSet
Parameters

Parameter

Description

number

32-bit signed integer to mask

start

Integer, in the range 0-31, inclusive; start bit for read

length

Integer, in the range 0-31, inclusive; length of mask

Usage

Bit functions operate on 32-bit signed integers, in the range -2147483648 - 2147483647.
Example

BitMaskRead Example
Returns integer created from length bits of number, beginning
with start.
BitMaskRead(255, 4, 4): #BitMaskRead(255, 4, 4)#
BitMaskRead(255, 0, 4): #BitMaskRead(255, 0, 4)#
BitMaskRead(128, 0, 7): #BitMaskRead(128, 0, 7)#

© 2014 Adobe Systems Incorporated. All rights reserved.

1413

Adobe ColdFusion Documentation

BitMaskSet
Description

Performs a bitwise mask set operation.
Returns

A number, bitwise masked with length bits of mask beginning at start.
Category

Mathematical functions
Function syntax

BitMaskSet(number, mask, start, length)

See also

BitMaskClear, BitMaskRead
Parameters

Parameter

Description

number

32-bit signed integer

mask

32-bit signed integer; mask

start

Integer, in the range 0-31, inclusive; start bit for mask

length

Integer, in the range 0-31, inclusive; length of mask

Usage

Bit functions operate on 32-bit signed integers, in the range -2147483648 - 2147483647.
Example

BitMaskSet Example
Returns number bitwise masked with length bits of mask beginning at start.
BitMaskSet(255, 255, 4, 4): #BitMaskSet(255, 255, 4, 4)#
BitMaskSet(255, 0, 4, 4): #BitMaskSet(255, 0, 4, 4)#
BitMaskSet(0, 15, 4, 4): #BitMaskSet(0, 15, 4, 4)#

© 2014 Adobe Systems Incorporated. All rights reserved.

1414

Adobe ColdFusion Documentation

BitNot
Description

Performs a bitwise logical NOT operation.
Returns

A number; the bitwise NOT of a long integer.
Category

Mathematical functions
Function syntax

BitNot(number)

See also

BitAnd, BitOr, BitXor
Parameters

Parameter

Description

number

32-bit signed integer

Usage

Bit functions operate on 32-bit signed integers, in the range -2147483648 - 2147483647.
Example

BitNot Example
Returns the bitwise NOT of a long integer.
BitNot(0): #BitNot(0)#
BitNot(255): #BitNot(255)#

© 2014 Adobe Systems Incorporated. All rights reserved.

1415

Adobe ColdFusion Documentation

BitOr
Description

Performs a bitwise logical OR operation.
Returns

A number; the bitwise OR of two long integers.
Category

Mathematical functions
Function syntax

BitOr(number1, number2)

See also

BitAnd, BitNot, BitXor
Parameters

Parameter

Description

number1

32-bit signed integer

number2

32-bit signed integer

Usage

Bit functions operate on 32-bit signed integers, in the range -2147483648 - 2147483647.
Example

BitOr Example
Returns the bitwise OR of two long integers.
BitOr(5,255): #BitOr(5,255)#
BitOr(5,0): #BitOr(5,0)#
BitOr(7,8): #BitOr(7,8)#

© 2014 Adobe Systems Incorporated. All rights reserved.

1416

Adobe ColdFusion Documentation

BitSHLN
Description

Performs a bitwise shift-left, no-rotation operation.
Returns

A number, bitwise shifted without rotation to the left by count bits.
Category

Mathematical functions
Function syntax

BitSHLN(number, count)

See also

BitSHRN
Parameters

Parameter

Description

number

32-bit signed integer

count

Integer, in the range 0-31, inclusive; number of bits to
shift the number

Usage

Bit functions operate on 32-bit signed integers, in the range -2147483648 - 2147483647.
Example

BitSHLN Example
Returns the number, bitwise shifted, without rotation, to the left by count
bits.
BitSHLN(1,1): #BitSHLN(1,1)#
BitSHLN(1,30): #BitSHLN(1,30)#
BitSHLN(1,31): #BitSHLN(1,31)#
BitSHLN(2,31): #BitSHLN(2,31)#

© 2014 Adobe Systems Incorporated. All rights reserved.

1417

Adobe ColdFusion Documentation

BitSHRN
Description

Performs a bitwise shift-right, no-rotation operation.
Returns

A number, bitwise shifted, without rotation, to the right by count bits.
Category

Mathematical functions
Function syntax

BitSHRN(number, count)

See also

BitSHLN
Parameters

Parameter

Description

number

32-bit signed integer

count

Integer, in the range 0-31, inclusive. Number of bits to
shift the number

Usage

Bit functions operate on 32-bit signed integers, in the range -2147483648 - 2147483647.
Example

BitSHRN Example
Returns a number, bitwise shifted, without rotation, to the right, by count
bits.
BitSHRN(1,1): #BitSHRN(1,1)#
BitSHRN(255,7): #BitSHRN(255,7)#
BitSHRN(-2147483548,1): #BitSHRN(-2147483548,1)#

© 2014 Adobe Systems Incorporated. All rights reserved.

1418

Adobe ColdFusion Documentation

BitXor
Description

Performs a bitwise logical XOR operation.
Returns

Bitwise XOR of two long integers.
Category

Mathematical functions
Function syntax

BitXor(number1, number2)

See also

BitAnd, BitNot, BitOr
Parameters

Parameter

Description

number1

32-bit signed integer

number2

32-bit signed integer

Usage

Bit functions operate on 32-bit signed integers, in the range -2147483648 - 2147483647.
Example

BitXOr Example
Returns the bitwise XOR of two long integers.
BitXOr(5,255): #BitXOr(5,255)#
BitXOr(5,0): #BitXOr(5,0)#
BitXOr(128,128): #BitXOr(128,128)#

#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

1419

Adobe ColdFusion Documentation

ArrayDeleteNoCase
Description

Searches an array for the first position of a specified object and deletes it. The function searches for simple objects
such as strings and numbers or for complex objects such as structures. Simple object string searches are
case-insensitive. This function does not support searches for COM and CORBA objects.
Returns

Yes, on successful deletion of the array element.
Category

Array functions
Function syntax

ArrayDelete(array,object)

See Also
ArrayDeleteAt, ArrayClear
Parameters

Parameter

Description

array

Array to search in.

object

Object to search for.

Example


array = ["STRING","STRING"];
writeOutput(arrayDelete(array, "string"));
writeDump(array);


© 2014 Adobe Systems Incorporated. All rights reserved.

1420

Adobe ColdFusion Documentation

Functions c-d
CacheGet
CacheGetAllIds
CacheGetMetadata
CacheGetProperties
cacheGetSession
CacheIdExists
CachePut
CacheRegionExists
CacheRegionNew
CacheRegionRemove
CacheRemove
CacheRemoveAll
CacheSetProperties
CallStackDump
CallStackGet
CanDeSerialize
Canonicalize
CanSerialize
Ceiling
CharsetDecode
CharsetEncode
Chr
CJustify
Compare
CompareNoCase
Cos
CreateDate
CreateDateTime
CreateObject
CreateObject: .NET object
CreateObject: COM object
CreateObject: component object
CreateObject: CORBA object
CreateObject: Java or EJB object
CreateObject: web service object
CreateODBCDate
CreateODBCDateTime
CreateODBCTime
CreateTime
CreateTimeSpan
CreateUUID
CSRFGenerateToken
CSRFVerifyToken
DateAdd
DateCompare
DateConvert
DateDiff
DateFormat
DatePart
DateTimeFormat

© 2014 Adobe Systems Incorporated. All rights reserved.

1421

Adobe ColdFusion Documentation

Day
DayOfWeek
DayOfWeekAsString
DayOfYear
DaysInMonth
DaysInYear
DE
DecimalFormat
DecodeForHTML
DecodeFromURL
DecrementValue
Decrypt
DecryptBinary
DeleteClientVariable
Deserialize
DeserializeJSON
DeserializeXML
DirectoryCopy
DirectoryCreate
DirectoryDelete
DirectoryExists
DirectoryList
DirectoryRename
DollarFormat
DotNetToCFType
Duplicate

© 2014 Adobe Systems Incorporated. All rights reserved.

1422

Adobe ColdFusion Documentation

CacheIdExists
Description

Used to find if a cached object exists in the cache region. The region can be the default cache region (either at
server or application level) or the custom region you specify.
Returns

True, if the cached object exists in the specified cache region.
History

ColdFusion 10: Added this function.
Syntax

cacheIdExists(id [,_ region___])
Properties

Parameter

Description

id

(Required) The ID of the cached object.

region

(Optional) The cache region where you check for the
cached object.

Example: Checks if the cache object is present in the user-defined cache region














© 2014 Adobe Systems Incorporated. All rights reserved.

1428

Adobe ColdFusion Documentation

cacheGetSession
Description

Lets you retrieve the underlying cache object to access additional cache functionality that is not implemented in the
tag cfcache.
Note
CautionUsing the cacheGetSession function might pose security vulnerabilities. If you wish to
disable the usage of this function, add it to Sandbox Security. For more information, see Using
sandbox security.

Returns

The underlying cache object.
Syntax

cacheGetSession()
Parameters

Parameter

Description

objectType

Any of the following values:
object
template
name of the user-defined cache

isKey

Set to true if objectType is user-defined cache. The
default value is false.

Category

Cache functions
See also

cfcache, CachePut, CacheGet, CacheGetAllIds, CacheGetMetadata, CacheRemove, CacheSetProperti
es
History

ColdFusion 9.0.1: Added this function
Example 1

The following example shows how to create a user-defined cache by adding an entry in ehCache.xml:

© 2014 Adobe Systems Incorporated. All rights reserved.

1429

Adobe ColdFusion Documentation



After you specify the details in the ehCache.xml, you can use the user-defined cache as shown here:








getMaxElementsInMemory() :: #config.getMaxElementsInMemory()#

isEternal() ::
#config.isEternal()#

getTimeToIdleSeconds() :: #config.getTimeToIdleSeconds()#

getTimeToLiveSeconds() :: #config.getTimeToLiveSeconds()#

isOverflowToDisk() :: #config.isOverflowToDisk()#

getDiskSpoolBufferSizeMB() :: #config.getDiskSpoolBufferSizeMB()#

getMaxElementsOnDisk() :: #config.getMaxElementsOnDisk()#

isDiskPersistent() :: #config.isDiskPersistent()#

getDiskExpiryThreadIntervalSeconds() ::
#config.getDiskExpiryThreadIntervalSeconds()#

getMemoryStoreEvictionPolicy() ::
#config.getMemoryStoreEvictionPolicy()#

isClearOnFlush() :: #config.isClearOnFlush()#



Example 2

The following example shows how to use the function cacheGetSession to operate on default caches:

© 2014 Adobe Systems Incorporated. All rights reserved.

1430

Adobe ColdFusion Documentation








© 2014 Adobe Systems Incorporated. All rights reserved.

1431

Adobe ColdFusion Documentation

CachePut
Description

Stores an object in the cache.
Returns

Nothing
Category

Cache functions
Function syntax

CachePut(id, value, [timeSpan], [idleTime], [region], [throwOnError])

See also

cfcache, CacheGet, CacheGetAllIds, CacheGetProperties, CacheRemove, CacheSetProperties
History

ColdFusion 10: Added the region and throwOnError parameters.ColdFusion 9: Added the function.
Parameters

Parameter

Description

id

The ID for the cache object.

value

The value of the object. Can be any data type
supported by ColdFusion

timeSpan

(Optional) The interval until the object is flushed from
the cache, as a decimal number of days. One way to
set the value is to use the return value from the Creat
eTimeSpan function. The default is to not time out the
object.

idleTime

(Optional) A decimal number of days after which the
object is flushed from the cache if it is not accessed
during that time. One way to set the value is to use the
return value from the CreateTimeSpan function.

region

Optional. Specifies the cache region where you can
place the cache object.

throwOnError

Optional. If True and if regen does not exist, throws an
error.

© 2014 Adobe Systems Incorporated. All rights reserved.

1432

Adobe ColdFusion Documentation

© 2014 Adobe Systems Incorporated. All rights reserved.

1433

Adobe ColdFusion Documentation

CacheRegionExists
Description

Checks if the cache region exists.
Returns

True if the cache region exists.
History

ColdFusion 10: Added this function.
Syntax

cacheRegionExists(region__)
Properties

Parameter

Description

region

Name of the cache region.

Example





Region is deleted






Region is deleted




© 2014 Adobe Systems Incorporated. All rights reserved.

1434

Adobe ColdFusion Documentation

CacheRegionNew
Description

Creates a new custom cache region (if no cache region exists).
Returns

An error if throwOnError parameter is set to true, provided cache region already exists.
History

ColdFusion 10: Added this function.
Syntax

cacheRegionNew(region,[properties],[throwOnError]__)
Properties

Parameter

Description

region

Name of the new cache region to be created.

properties

Optional. Struct that contains the cache region
properties.

throwOnError

Optional. A Boolean value specifying if to throw an
exception if the cache region name you specify already
exists. The default value is true.

Example

© 2014 Adobe Systems Incorporated. All rights reserved.

1435

Adobe ColdFusion Documentation






















Starting to write to cache..

Trying to fetch cached item...



Done!!

#obj.name#

© 2014 Adobe Systems Incorporated. All rights reserved.

1436

Adobe ColdFusion Documentation

CacheRegionRemove
Description

Removes a specified cache region.
Returns

Nothing
History

ColdFusion 10: Added this function.
Syntax

cacheRegionRemove(region__)
Properties

Parameter

Description

region

Name of the cache region that has to be removed.

Example

See the example for CacheRegionExists.

© 2014 Adobe Systems Incorporated. All rights reserved.

1437

Adobe ColdFusion Documentation

CacheRemove
Description

Removes an object from the cache.
Returns

Nothing.
Category

Cache functions
Function syntax

CacheRemove(ids, [throwOnError]])

See also

cfcache, CacheGet, CachePut, CacheGetAllIds, CacheGetProperties, CacheGetMetadata, CacheSetP
roperties
History

ColdFusion 11: The ids parameter will also accept an array.
ColdFusion 10: Added the attributes region and {{exact}}.
ColdFusion 9: Added the function.
Parameters

Parameter

Description

exact

(Optional) If true, the search narrows down to values
that exactly match the IDs (for removal). The default
value is true.

ids

A comma delimited string of IDs of the cached objects
to remove. Starting from ColdFusion 11, you can also
specify an array of IDs.

region

(Optional) Name of the cache region from which to
remove the cached objects.

throwOnError

A Boolean value specifying whether to throw an
exception if any ID does not specify a cached element.
The default value is false.

Example with parameter exact set to true

© 2014 Adobe Systems Incorporated. All rights reserved.

1438

Adobe ColdFusion Documentation












Before cacheRemove() :: Number of objects in the cache:
#ArrayLen(cacheGetAllIds())#



(List of cache Ids #ListSort(ArrayToList(cacheGetAllIds()),"textnocase","ASC")#)

After cacheRemove() :: Number of objects in the cache:
#ArrayLen(cacheGetAllIds())#



Example with parameter exact set to false








Before cacheRemove() :: Number of objects in the cache:
#ArrayLen(cacheGetAllIds())#



(List of cache Ids #ListSort(ArrayToList(cacheGetAllIds()),"textnocase","ASC")#)

After cacheRemove() :: Number of objects in the cache:
#ArrayLen(cacheGetAllIds())#



© 2014 Adobe Systems Incorporated. All rights reserved.

1439

Adobe ColdFusion Documentation

CacheRemoveAll
Description

Removes all stored objects in a cache region. If no cache region is specified, objects in the default region are
removed.
Returns

Nothing
History

ColdFusion 10: Added this function.
Syntax

cacheRemoveAll(region__)
Properties

Parameter

Description

region

(Optional) Indicates the cache region from which to
remove the stored objects. If no value is specified,
default cache region is considered by default.

Example












Before cacheRemove() :: Number of objects in the cache:
#ArrayLen(cacheGetAllIds())#



After cacheRemove() :: Number of objects in the cache:
#ArrayLen(cacheGetAllIds())#



© 2014 Adobe Systems Incorporated. All rights reserved.

1440

Adobe ColdFusion Documentation

CacheSetProperties
Description

Sets the cache properties for the object cache, the page cache, or both. If a cache does not yet exist, creates it. The
cache and properties are application-specific.
Returns

Nothing
Category

Cache functions
Function syntax

CacheSetProperties(propStruct)

See also

cfcache, CacheGet, CachePut, CacheGetAllIds, CacheGetProperties, CacheGetMetadata, CacheRemo
ve
History

ColdFusion 10: Added the attribute {{region}}ColdFusion 9: Added the function.
Parameters

Parameter

Description

propsSruct

A structure specifying the cache properties plus
identifying information

region

(Optional) The name of the cache region

The propsStruct structure can have any or all of the following fields:
Structure element

Description

diskstore

The disk store.

diskpersistent

A Boolean value specifying whether to persist caches
stored on disk through JVM restarts.

eternal

A Boolean value specifying whether no timeout or
idletime applies. A true value indicates that the object
or page is cached without any timespan being
specified.

© 2014 Adobe Systems Incorporated. All rights reserved.

1441

Adobe ColdFusion Documentation

maxelementsinmemory

The maximum number of objects that can be cached in
memory. If the number is exceeded and overflowtod
isk is false, the new objects entered replace old
elements using algorithm specified in the
memoryevictionpolicy entry.

maxelementsondisk

The maximum number of objects that can be stored on
disk if overfllowtodisk is true.

memoryevictionpolicy

The algorithm to used to evict old entries when
maximum limit is reached, such as LRU (least recently
used) or LFU (least frequently used).

objecttype

The cache type: object or template.

overflowtodisk

A Boolean value specifying whether when the
maximum number of elements allowed in memory is
reached, objects can be moved to disk, as determined
by the memoryevictionpolicy value.

statistics

true indicates that statistics collection for Ehcache is
enabled.

timetoidoleconds

The idle time in seconds. Used if a cfcache tag does
not specify an idleTime attribute.

timetolivesecond

The timeout time in seconds. Used if a cfcache tag
does not specify a timespan attribute.

objecttype

The type of cache: one of the following:
template - Set properties for the page cache, which
contains cached pages and page segments.
object - Set properties for the object cache.
all - Set properties for both cache types.

© 2014 Adobe Systems Incorporated. All rights reserved.

1442

Adobe ColdFusion Documentation

CallStackGet
Description

Returns an array of structs. Each struct contains template name, line number, and if applicable the function name.
History

ColdFusion 10: Added this function.
Syntax

callStackGet(__)
Usage

Callstack is a snapshot of all function calls or invocations. For your ColdFusion application, callstack provides the
template name, line number, and if applicable, the function name.The feature is helpful in scenarios where you want
to track the recursive calls that you made. For example,
a.cfm does an include of b.cfm.
b.cfm invokes the function callStackGet at line 15.
This results in a callstack that returns a struct that contains the template name, line number, and the function
name.
Example

In this example, the factorial of a number is computed.Here,
1.
2.
3.
4.

The function callStackGet is called on line 9 in function factorial in the template fact.cfm
In turn, it is called from line 14 from the template fact.cfm
In turn, it is called from template callfact.cfm (line 2)
And so on, for other values of n
callfact.cfm





#cfcatch.message#

#cfcatch.detail#






fact.cfm

© 2014 Adobe Systems Incorporated. All rights reserved.

1443

Adobe ColdFusion Documentation


numeric function factorial(n)
{
if(n == 1)
{
writedump(callStackGet());
writeoutput("
");
return 1;
}
else
{
writedump(callStackGet());
writeoutput("
");
return n * factorial(n - 1);
}
}
factorial(5);


© 2014 Adobe Systems Incorporated. All rights reserved.

1444

Adobe ColdFusion Documentation

CallStackDump
Description

Similar to the function callStackGet except that it returns a string representation of the call stack.
History

ColdFusion 10: Added this function.
Syntax

callStackDump(destination__)
Parameters

Parameter

Description

destination

Optional parameter that takes one of the following
values:
console
browser: This is the default destination.
file: If you do not provide the complete path to the
file, the file is written to the temp directory as
determined by the function getTempDirectory.

Usage

Callstack is a snapshot of all function calls or invocations. For your ColdFusion application, callstack provides the
template name, line number, and if applicable, the function name.The feature is helpful in scenarios where you want
to track the recursive calls that you made.
Example

In this example, the factorial of a number is computed. The example is similar to the example for CallStackGet ex
cept that the function used here is callStackDump.callfact.cfm





#cfcatch.message#

#cfcatch.detail#






fact.cfm

© 2014 Adobe Systems Incorporated. All rights reserved.

1445

Adobe ColdFusion Documentation











 Factorial of 5 - #factorial(5)#

© 2014 Adobe Systems Incorporated. All rights reserved.

1446

Adobe ColdFusion Documentation

CacheGetProperties
Description

Gets the cache properties for the object cache, the page cache, or both. The information is application-specific.
Returns

An Array of structures containing the cache properties. Each structure has the properties for the cache type: object
or page. If you specify either type in the parameter, the array has a single structure entry. Each structure has the
following fields:
Structure element

Description

diskpersistent

A Boolean value specifying whether to persist caches
stored on disk through JVM restarts.

eternal

A Boolean value specifying whether no timeout or
idletime applies. A true value indicates that the object
or page is cached without any timespan being
specified.

maxelementsinmemory

The maximum number of objects that can be cached in
memory. If the number is exceeded and overflowtod
isk is false, the new objects entered replace old
elements using algorithm specified in the
memoryevictionpolicy entry.

maxelementsondisk

The maximum number of objects that can be stored on
disk if overflowtodisk is true.

memoryevictionpolicy

The algorithm to used to evict old entries when
maximum limit is reached, such as LRU (least recently
used) or LFU (least frequently used).

objecttype

The cache type: object or template.

overflowtodisk

A Boolean value specifying whether when the
maximum number of elements allowed in memory is
reached, objects can be moved to disk, as determined
by the memoryevictionpolicy value.

statistics

true indicates that statistics collection for Ehcache is
enabled.

timetoidolseconds

The idle time in seconds. Used if a cfcache tag does
not specify an idleTime attribute.

© 2014 Adobe Systems Incorporated. All rights reserved.

1447

Adobe ColdFusion Documentation

timetoliveseconds

The timeout time in seconds. Used if a cfcache tag
does not specify a timespan attribute. Used if a cfqu
ery tag does not specify a cachedwithin attribute.

The cacheGetProperties function also supports the following ehCache Structure Elements:
cacheloadertimeoutmillis
clearonflush
copyonread
copyonwrite
diskaccessstripes
diskexpirythreadintervalseconds
diskpersistent
diskspoolbuffersizemb
eternal
logging
maxbyteslocaldisk
maxbyteslocaldiskasstring
maxbyteslocaldiskpercentageset
maxbyteslocalheap
maxbyteslocalheapasstring
maxbyteslocalheappercentageset
maxbyteslocaloffheap
maxbyteslocaloffheapasstring
maxbyteslocaloffheappercentageset
maxelementsinmemory
maxelementsondisk
maxentrieslocaldisk
maxentrieslocalheap
maxmemoryoffheap
maxmemoryoffheapinbytes
memoryevictionpolicy
name
objecttype
overflowtodisk
overflowtooffheap
overflowtooffheapset
statistics
timetoidleseconds
timetoliveseconds
For more information on the above mentioned structure elements, refer to EhCache Documentation.
Category

Cache functions
Function syntax

CacheGetProperties([type])

See also

© 2014 Adobe Systems Incorporated. All rights reserved.

1448

Adobe ColdFusion Documentation

cfcache, CachePut, CacheGet, CacheGetAllIds, CacheGetMetadata, CacheRemove, CacheSetProperti
es
History

ColdFusion 10: Added the attribute {{region}}ColdFusion 9: Added the function.
Parameters

Parameter

Description

type

(Optional) The cache type:
template - Get properties for the page cache,
which contains cached pages and page segments.
object - Get properties for the object cache.
no parameter - Get properties for both cache types.

region

© 2014 Adobe Systems Incorporated. All rights reserved.

(Optional) The name of the cache region

1449

Adobe ColdFusion Documentation

CanDeSerialize
Description

ColdFusion will invoke this function before invoking the Deserialize function.
Returns

Boolean. If true, the deserialize() function of the custom serializer will be called. If false, ColdFusion's default
deserializer will be used for serialization.
Function syntax

boolean function canDeSerialize(type)

History

ColdFusion 11: Added this function. For more information see REST Enhancements in ColdFusion 11.
Parameters

Parameter

Description

type

Required. String. The type to which the data has to be
deserialized.

Example











© 2014 Adobe Systems Incorporated. All rights reserved.

1450

Adobe ColdFusion Documentation

Canonicalize
Description

Canonicalize or decode the input string.
Cross-site Scripting (XSS) is the most prevalent web application security flaw. This occurs when the
user-supplied-data is sent to the browser without being properly validated. Canonicalization is the process of
reducing a possibly encoded string down to its simplest form. Before validating any data, you must canonicalize the
data. The canonicalize method can decode HTML entities, URL (Percent) encodings, and JavaScript encodings. In
addition to simple decoding, canonicalize can also handle input, which is encoded using different techniques:
Multiple Encoding

By encoding the input multiple times or nesting the encoding using an encoding scheme.
Examples:
Encoding

Description

< -> < -> &lt;

Encoded multiple times using the HTML Entity
Encoding

< -> %3C -> %253C -> %25253C

Encoded multiple times using percent Encoding

\ -> %5C -> %%33%63

Nested Encoding using URL (Percent) encoding
multiple times

Mixed Encoding
When the input is encoded using different encoding schemes (For instance, encoded using both HTML and URL
encoding).
Examples:
Encoding

Description

< -> < -> &%6ct;

First encoded using HTML entity encoding and then
encoded using the percent Encoding

< -> %3C -> %&x33;c

First encoded using URL (percent) encoding next
nested encoded 3 using the HTML Entity encoding.

The data that is encoded more than once (nested or mixed) is something that normal users will not generate.
Hence, having this kind of input data should be considered as malicious.
Returns

Decoded form of input string.
Category

Display and formatting functions
Syntax

© 2014 Adobe Systems Incorporated. All rights reserved.

1451

Adobe ColdFusion Documentation

canonicalize(inputString, restrictMultiple, restrictMixed [, throwOnError])
History

ColdFusion 11: Added the new attribute, throwOnError.
ColdFusion 10: Added this function.
See also

EncodeForHTML,EncodeForHTMLAttribute, EncodeForJavaScript, EncodeForCSS, EncodeForURL
Parameters

Parameter

Description

inputString

Required. The string to be encode.

restrictMultiple

Required. . If set to true, multiple encoding is
restricted.
This argument can be set to true to restrict the input if
multiple or nested encoding is detected. If this
argument is set to true, and the given input is multiple
or nested encoded using one encoding scheme an
error will be thrown.

restrictMixed

Required. If set to true, mixed encoding is restricted.
This argument can be set to true to restrict the input if
mixed encoding is detected. If this argument is set to
true, and the given input is encoded using mixed
encoding, an error will be thrown.

throwOnError

Optional. Default value is false. If restrictMultiple or
restrictMixed is true and the given input contains mixed
or multiple encoded strings, an exception will be
thrown. If the value of this argument is true, instead of
an exception, an empty string will be returned
otherwise the exception will be thrown.

Example

© 2014 Adobe Systems Incorporated. All rights reserved.

1452

Adobe ColdFusion Documentation


#canonicalize("<",false,false)#



#canonicalize("%26lt; %26lt; %2526lt%253B %2526lt%253B
%2526lt%253B",true,true, true)#








#canonicalize("%26lt; %26lt; %2526lt%253B %2526lt%253B
%2526lt%253B",true,true, false)#


#canonicalize("%25 %2526 %26##X3c;script&##x3e;
&##37;3Cscript%25252525253e",false,true)#


#canonicalize("%26lt; %26lt; %2526lt%253B %2526lt%253B
%2526lt%253B",false,true, true)#








#canonicalize("%26lt; %26lt; %2526lt%253B %2526lt%253B
%2526lt%253B",false,false)#

#canonicalize("&##X25;3c",false,false)#

#canonicalize("&##x25;3c",false,false)#



#canonicalize("\\U003C",false,false)#

#canonicalize("\\X3C",false,false)#


© 2014 Adobe Systems Incorporated. All rights reserved.

1453

Adobe ColdFusion Documentation

© 2014 Adobe Systems Incorporated. All rights reserved.

1454

Adobe ColdFusion Documentation

CanSerialize
Description

ColdFusion will invoke this function before invoking the serialize() function.
Returns

Boolean. If true, the serialize() function of the custom serializer will be called. If false, ColdFusion's default serializer
will be used for serialization.
Function syntax

boolean function canSerialize(type)

History

ColdFusion 11: Added this function. For more information see REST Enhancements in ColdFusion 11.
Parameters

Parameter

Description

type

Required. String. The type to which the data has to be
serialized.

Example











© 2014 Adobe Systems Incorporated. All rights reserved.

1455

Adobe ColdFusion Documentation

Ceiling
Description

Determines the closest integer that is greater than a specified number.
Returns

The closest integer that is greater than a given number.
Category

Mathematical functions
Function syntax

Ceiling(number)

See also

Int, Fix, Round
Parameters

Parameter

Description

number

A real number

Example

Ceiling Example

The ceiling
The ceiling
The ceiling
The ceiling


of
of
of
of

3.4 is #ceiling(3.4)#
3 is #ceiling(3)#

3.8 is #ceiling(3.8)#

-4.2 is #ceiling(-4.2)#


© 2014 Adobe Systems Incorporated. All rights reserved.

1456

Adobe ColdFusion Documentation

CharsetDecode
Description

Converts a string to a binary representation.
Returns

A binary object that represents the string.
Category

Conversion functions, String functions
Function syntax

CharsetDecode(string, encoding)

See also

BinaryDecode, BinaryEncode, CharsetEncode; Determining the page encoding of server output in Processing
a request in ColdFusion in the Developing ColdFusion Applications
History

ColdFusion MX 7: Added this function.
Parameters

Parameter

Description

string

A string containing data to encode in binary format.

© 2014 Adobe Systems Incorporated. All rights reserved.

1457

Adobe ColdFusion Documentation

encoding

A string that specifies encoding of the input data. Must
be a character encoding name recognized by the Java
runtime. The following list includes commonly used
values:
utf-8
iso-8859-1
windows-1252
us-ascii
shift_jis
iso-2022-jp
euc-jp
euc-kr
big5
euc-cn
utf-16
For a complete list of character encoding names
supported by Sun Java runtimes, see http://java.sun.
com/j2se/1.3/docs/guide/intl/encoding.doc.html and h
ttp://java.sun.com/j2se/1.4/docs/guide/intl/encoding.d
oc.html.

Usage

This function converts a string directly to a binary object. In releases of ColdFusion through ColdFusion MX 6.1, you
had to use the ToBase64 function to convert the string to Base64 and then use the ToBinary function to convert
strings to binary data.
Example

The following example uses the CharsetDecode function to convert a string from a form to a binary object, and
uses the CharsetEncode function to convert it back to the original value. You can change the character encoding
that ColdFusion uses for the conversion. If you select the Asian language encodings, characters that are not in the
specified character set are successfully converted.

© 2014 Adobe Systems Incorporated. All rights reserved.

1458

Adobe ColdFusion Documentation

Character Encoding Conversion Example




chardecode=CharsetDecode(Form.myString, Form.charEncoding);
charencode=CharsetEncode(chardecode, Form.charEncoding);



Parameter Settings
The string:

#Form.myString#
The character encoding: #Form.charEncoding#
Results of the operations:
Dump of the string converted to a binary object by CharsetDecode:



The binary object converted back to a string by CharsetEncode:


#charencode#




Select the character encoding



UTF-8
ASCII
ISO8859_1
CP1252
SJIS
MS932
EUC_CN
Big5




Enter a string

The following four characters are not in all character encodings:







© 2014 Adobe Systems Incorporated. All rights reserved.

1459

Adobe ColdFusion Documentation

CharsetEncode
Description

Uses the specified encoding to convert binary data to a string.
Returns

A string representation of the binary object.
Category

Conversion functions, String functions
Function syntax

CharsetEncode(binaryobject, encoding)

See also

BinaryDecode, BinaryEncode, CharsetDecode; Determining the page encoding of server output in Processing
a request in ColdFusion in the Developing ColdFusion Applications
History

ColdFusion MX 7: Added this function.
Parameters

Parameter

Description

binaryobject

A variable containing binary data to decode into text.

© 2014 Adobe Systems Incorporated. All rights reserved.

1460

Adobe ColdFusion Documentation

encoding

The character encoding that was used to encode the
string into binary format. It must be a character
encoding name recognized by the Java runtime. The
following list includes commonly used values:
utf-8
iso-8859-1
windows-1252
us-ascii
shift_jis
iso-2022-jp
euc-jp
euc-kr
big5
euc-cn
utf-16
For a complete list of character encoding names
supported by Sun Java runtimes, see http://java.sun.
com/javase/6/docs/technotes/guides/intl/encoding.do
c.html.

Usage

Adobe recommends that you use this function, and not the ToString function, to convert binary data to strings in
all new applications.
Example

The following example uses the CharsetDecode function to convert a string from a form to a binary object, and
uses the CharsetEncode function to convert it back to the original value. You can change the character encoding
that ColdFusion uses for the conversion. If you select the Asian language encodings, characters that are not in the
specified character set are successfully converted.

© 2014 Adobe Systems Incorporated. All rights reserved.

1461

Adobe ColdFusion Documentation

Character Encoding Conversion Example




chardecode=CharsetDecode(Form.myString, Form.charEncoding);
charencode=CharsetEncode(chardecode, Form.charEncoding);



Parameter Settings
The string:

#Form.myString#
The character encoding: #Form.charEncoding#
Results of the operations:
Dump of the string converted to a binary object by CharsetDecode:



The binary object converted back to a string by CharsetEncode:


#charencode#




Select the character encoding



UTF-8
ASCII
ISO8859_1
CP1252
SJIS
MS932
EUC_CN
Big5




Enter a string

The following four characters are not in all character encodings:







© 2014 Adobe Systems Incorporated. All rights reserved.

1462

Adobe ColdFusion Documentation

Chr
Description

Converts a numeric value to a UCS-2 character.
Returns

A character with the specified UCS-2 character code.
Category

String functions
Function syntax

Chr(number)

See also

Asc
History

ColdFusion MX: Changed Unicode support: ColdFusion supports the Java UCS-2 representation of Unicode
characters, up to a value of 65535. (Earlier releases supported 1-255.)
Parameters

Parameter

Description

number

A value (a number in the range 0 - 65535, inclusive)

Usage

The values 0 - 31 are standard, nonprintable codes. For example:
Chr(10) returns a linefeed character
Chr(13) returns a carriage return character
The two-character string Chr(13) & Chr(10)returns a Windows newline
Note
For a complete list of the Unicode characters and their codes, see
www.unicode.org/charts/

Example

© 2014 Adobe Systems Incorporated. All rights reserved.

1463

Adobe ColdFusion Documentation



#form.charVals# = #Chr(form.charVals)#


Type an integer character code from 1 to 65535

to see its corresponding character.


 


© 2014 Adobe Systems Incorporated. All rights reserved.

1464

Adobe ColdFusion Documentation

CJustify
Description

Centers a string in a field length.
Returns

String, center-justified by adding spaces before or after the input parameter. If length is less than the length of the
input parameter string, the string is returned unchanged.
Category

Display and formatting functions, String functions
Function syntax

Cjustify(string, length)

See also

LJustify, RJustify
Parameters

Parameter

Description

string

A string or a variable that contains one. May be empty.
If it is a variable that is defined as a number, the
function processes it as a string.

length

A positive integer or a variable that contains one.
Length of field.Can be coded as:
A number; for example, 6
A string representation of a number; for example, "6
"
Any other value causes ColdFusion to throw an error.

Example

© 2014 Adobe Systems Incorporated. All rights reserved.

1465

Adobe ColdFusion Documentation












CJustify
Enter a string; it will be center-justified within the sample field.








© 2014 Adobe Systems Incorporated. All rights reserved.

1466

Adobe ColdFusion Documentation

Compare
Description

Performs a case sensitive comparison of two strings.
Returns

-1, if string1 is less than string2
0, if string1 is equal to string2
1, if string1 is greater than string2
Category

String functions
Function syntax

Compare(string1, string2)

See also

CompareNoCase, Find
Parameters

Parameter

Description

string1

A string or a variable that contains one

string2

A string or a variable that contains one

Usage

Compares the values of corresponding characters in string1 and string2.
Example

© 2014 Adobe Systems Incorporated. All rights reserved.

1467

Adobe ColdFusion Documentation

Compare Example
The compare function performs a case-sensitive comparison of two
strings.





String 1 is less than String 2
The strings are not equal


String 1 is equal to String 2
The strings are equal!


String 1 is greater than String 2
The strings are not equal


This is the default case




String 1


String 2






© 2014 Adobe Systems Incorporated. All rights reserved.

1468

Adobe ColdFusion Documentation

CompareNoCase
Description

Performs a case-insensitive comparison of two strings.
Returns

An indicator of the difference:
A negative number, if string1 is less than string2
0, if string1 is equal to string2
A positive number, if string1 is greater than string2
Category

String functions
Function syntax

CompareNoCase(string1, string2)

See also

Compare, FindNoCase; Evaluation and type conversion issues in Data type conversion in the Developing
ColdFusion Applications
Parameters

Parameter

Description

string1

A string or a variable that contains one

string2

A string or a variable that contains one

Example

© 2014 Adobe Systems Incorporated. All rights reserved.

1469

Adobe ColdFusion Documentation

CompareNoCase Example
This function performs a case-insensitive comparison of two strings.





String 1 is less than String 2
The strings are not equal


String 1 is equal to String 2
The strings are equal!


String 1 is greater than String 2
The strings are not equal


This is the default case




String 1


String 2






© 2014 Adobe Systems Incorporated. All rights reserved.

1470

Adobe ColdFusion Documentation

Cos
Description

Calculates the cosine of an angle that is entered in radians.
Returns

A number; the cosine of the angle.
Category

Mathematical functions
Function syntax

Cos(number)

See also

ACos, Sin, ASin, Tan, Atn, Pi
Parameters

Parameter

Description

number

Angle, in radians, for which to calculate the cosine

Usage

The range of the result is -1 to 1. To convert degrees to radians, multiply degrees by p/180. To convert radians to
degrees, multiply radians by 180/p.
Note
Because the function uses floating point arithmetic, it returns a small number (such as
6.12323399574E-017) for angles that must produce 0. To test for a 0 value, check whether the
value is less than 0.0000000000001.

Example

© 2014 Adobe Systems Incorporated. All rights reserved.

1471

Adobe ColdFusion Documentation

Cos Example










Cos(#FORM.cosNum#) = #cosValue#




You must enter a numeric angle in degrees.



Enter an angle in degrees to get its cosine:




  


© 2014 Adobe Systems Incorporated. All rights reserved.

1472

Adobe ColdFusion Documentation

CreateDate
Description

Creates a date/time object.
Returns

A date/time value.
Category

Date and time functions
Function syntax

CreateDate(year, month, day)

See also

CreateDateTime, CreateODBCDateTime; Evaluation and type conversion issues in Data type conversion in the
Developing ColdFusion Applications
Parameters

Parameter

Description

year

Integer in the range 0-9999. Integers in the range 0-29
are converted to 2000-2029. Integers in the range
30-99 are converted to 1930-1999. You cannot specify
dates before AD 100.

month

Integer in the range 1 (January)-12 (December)

day

Integer in the range 1-31

Usage

CreateDate is a subset of CreateDateTime.The time in the returned object is set to 00:00:00.
Example

© 2014 Adobe Systems Incorporated. All rights reserved.

1473

Adobe ColdFusion Documentation

CreateDate Example

Your date value, generated with CreateDate:



Formatted with CreateDate: #CreateDate(form.year, form.month, form.day)#
Formatted with CreateDateTime: #CreateDateTime(form.year, form.month,
form.day, 12,13,0)#
Formatted with CreateODBCDate: #CreateODBCDate(yourDate)#
Formatted with CreateODBCDateTime: #CreateODBCDateTime(yourDate)#

The same value can be formatted with DateFormat:

Formatted with CreateDate and DateFormat:
#DateFormat(CreateDate(form.year, form.month, form.day), "mmm-dd-yyyy")#
Formatted with CreateDateTime and DateFormat:
#DateFormat(CreateDateTime(form.year, form.month, form.day, 12,13,0))#
Formatted with CreateODBCDate and DateFormat:
#DateFormat(CreateODBCDate(yourDate), "mmmm d, yyyy")#
Formatted with CreateODBCDateTime and DateFormat:
#DateFormat(CreateODBCDateTime(yourDate), "d/m/yy")#




Enter the year, month, and day, as integers:
Year
Month
Day

 


© 2014 Adobe Systems Incorporated. All rights reserved.

1474

Adobe ColdFusion Documentation

CreateDateTime
Description

Creates a date-time object.
Returns

A date/time value.
Category

Date and time functions
Function syntax

CreateDateTime(year, month, day, hour, minute, second)

See also

CreateDate, CreateTime, CreateODBCDateTime, Now; Evaluation and type conversion issues in Data type
conversion in the Developing ColdFusion Applications
Parameters

Parameter

Description

year

Integer in the range 0-9999. Integers in the range 0-29
are converted to 2000-2029. Integers in the range
30-99 are converted to 1930-1999. You cannot specify
dates before AD 100.

month

Integer in the range 1 (January) - 12 (December)

day

Integer in the range 1 - 31

hour

Integer in the range 0 - 23

minute

Integer in the range 0 - 59

second

Integer in the range 0 - 59

Example

© 2014 Adobe Systems Incorporated. All rights reserved.

1475

Adobe ColdFusion Documentation

CreateDateTime Example

Your date value, generated with CreateDateTime:



Formatted with CreateDate: #CreateDate(form.year, form.month, form.day)#
Formatted with CreateDateTime: #CreateDateTime(form.year, form.month,
form.day, form.hour, form.minute, form.second)#
Formatted with CreateODBCDate: #CreateODBCDate(yourDate)#
Formatted with CreateODBCDateTime: #CreateODBCDateTime(yourDate)#

The same value can be formatted with DateFormat:

Formatted with CreateDate and DateFormat:
#DateFormat(CreateDate(form.year, form.month, form.day), "mmm-dd-yyyy")#
Formatted with CreateDateTime and DateFormat:
#DateFormat(CreateDateTime(form.year, form.month, form.day,
form.hour, form.minute, form.second))#
Formatted with CreateODBCDate and DateFormat:
#DateFormat(CreateODBCDate(yourDate), "mmmm d, yyyy")#
Formatted with CreateODBCDateTime and DateFormat:
#DateFormat(CreateODBCDateTime(yourDate), "d/m/yy")#




Please enter the year, month, and day, in integer format, for a date to view:
Year 
Month 
Day 
Hour 
Minute 
Second 

 


© 2014 Adobe Systems Incorporated. All rights reserved.

1476

Adobe ColdFusion Documentation

CreateObject
Description

Creates a ColdFusion object, of a specified type.
Returns

An object, of the specified type.
Category

Extensibility functions
History

ColdFusion 10: Added the parameter wsVersion ColdFusion 9:
ColdFusion 9 does not require the type argument.
ColdFusion 8:
Added the .NET/dotnet type
For web service object, added the WSDL2Java and argstruct parameters
ColdFusion MX 7: For web service object: added the portName parameter, which specifies a port named in the ser
vice element of the WSDL.ColdFusion MX:
1. Changed instantiation behavior: this function, and the cfobject tag, can instantiate ColdFusion components
and web services. Executing operations on a CFC object executes CFML code that implements the CFC's
method in the CFC file. For more information, see the Developing ColdFusion Applications.
2. For CORBA object: changed the Naming Service separator format for addresses from a dot to a forward
slash. For example, if "context=NameService", for a class, use either of the following formats for the clas
s parameter:
"/Eng/CF"
".current/Eng.current/CF"
(In earlier releases, the format was ".Eng.CF".)
1. For CORBA object: changed the locale parameter; it specifies the Java config that contains the properties
file.
CreateObject object types

For information about using this function, see these sections:
CreateObject: .NET object
CreateObject: COM object
CreateObject: component object
CreateObject: CORBA object
CreateObject: Java or EJB object
CreateObject: web service object
Note
On UNIX, this function does not support COM objects.

© 2014 Adobe Systems Incorporated. All rights reserved.

1477

Adobe ColdFusion Documentation

CreateObject: .NET object
Description

Creates a .NET object, that is, a ColdFusion proxy for accessing a class in a local or remote .NET assembly.
Returns

A .NET object, that is, a ColdFusion reference to a local or remote .NET assembly class.
Function syntax

CreateObject(type, class, assembly[, server, port, protocol, secure])

See also

DotNetToCFType, Using Microsoft .NET Assemblies in the Developing ColdFusion Applications
Parameters

Attribute

Default

Description

type

component

Object type. Must be .NET or dotn
et for .NET objects.

class

© 2014 Adobe Systems Incorporated. All rights reserved.

Name of the .NET class to
represent as an object.

1478

Adobe ColdFusion Documentation

assembly

mscorlib.dll which
contains the .NET core
classes

For local .NET assemblies, the
absolute path or paths to the
assembly or assemblies (.exe or .dll
files) from which to access the .NET
class and its supporting classes. If a
class in an assembly requires
supporting classes that are in other
assemblies, specify those
assemblies also. You can, however,
omit the supporting assemblies for
the following types of supporting
classes:
.NET core classes (classes in
mscorlib.dll)
classes in assemblies that are in
the global assembly cache (GAC)
To specify multiple assemblies,
use a comma-delimited list.
For remote .NET assemblies,
specify the absolute path or paths
of the local proxy JAR file or files
that represent the assemblies.If you
omit this parameter, and there is no
local .NET installation, the function
fails without generating an error. If
you omit this parameter, there is a
local .NET installation, and the
specified class is not in the .NET
core classes, ColdFusion generates
an error.

server

localhost

Host name or IP address of the
server where the .NET-side agent is
running. Can be in any of these
forms:
server name (for example,
myserver)
IP address (for example,
127.0.0.1)
Specify this attribute to access
.NET components on a remote
server.

port

6086

© 2014 Adobe Systems Incorporated. All rights reserved.

Port number at which the .NET-side
agent is listening.

1479

Adobe ColdFusion Documentation

protocol

tcp

Protocol to use for communication
between ColdFusion and .NET.
Must be one of the following values:
http: Use HTTP/SOAP
communication protocol. This
option is slower than tcp, but
might be required for access
through a firewall.
tcp: Use binary TCP/IP protocol.
This method is more efficient than
HTTP.

secure

false

Whether to secure communications
with the .NET-side agent. If true,
ColdFusion uses SSL to
communicate with .NET.

Usage

The CreateObject function and cfobject tag differ only in syntax. For more information on creating ColdFusion
.NET objects. For detailed information on using the .NET assemblies in ColdFusion, see Using Microsoft .NET
Assemblies in the Developing ColdFusion Applications.

© 2014 Adobe Systems Incorporated. All rights reserved.

1480

Adobe ColdFusion Documentation

CreateObject: COM object
Description

The CreateObject function can create a Component Object Model (COM) object. To create a COM object,
provide the following information:
The object's program ID or filename
The methods and properties available to the object through the IDispatch interface
The arguments and return types of the object's methods
For most objects, you can get this information from the OLEView utility.
Note
On UNIX, this function does not support COM objects.

Returns

A COM object.
Function syntax

CreateObject(type, class, context, serverName)

See also

ReleaseComObject, cfobject; Integrating COM and CORBA Objects in CFML Applications in the Developing
ColdFusion Applications
Parameters

Parameter

Description

type

Type of object to create.
com
corba
java
component
webservice
The default value of type is component.

class
context

© 2014 Adobe Systems Incorporated. All rights reserved.

Component ProgID for the object to invoke.
InProc
Local
Remote

1481

Adobe ColdFusion Documentation

serverName

Server name, using UNC or DNS convention, in one of
these forms:
lanserver
lanserver
http://www.servername.com
www.servername.com
127.0.0.1
If context = "remote", this parameter is
required.

Usage

The following example creates the Windows Collaborative Data Objects (CDO) for NTS NewMail object to send
mail. You use this code in a cfscript tag.

Mailer = CreateObject("COM", "CDONTS.NewMail");

© 2014 Adobe Systems Incorporated. All rights reserved.

1482

Adobe ColdFusion Documentation

CreateObject: component object
Description

The CreateObject function can create an instance of a ColdFusion component (CFC) object.
Returns

A component object.
Function syntax

CreateObject(type, component-name)

See also

Building and Using ColdFusion Components in the Developing ColdFusion Applications
Parameters

Parameter

Description

type

Type of object to create.
com
corba
java
component
webservice
The default value of type is component.

component-name

The CFC name; corresponds to the name of the file
that defines the component; for example, use
engineComp to specify the component defined in the
engineComp.cfc file

Usage

On UNIX systems, ColdFusion searches first for a file with a name that matches the specified component name, but
is all lowercase. If it does not find the file, it looks for a filename that matches the component name exactly, with the
identical character casing.In the following example, the CFScript statements assign the tellTimeCFC variable to
the tellTime component using the CreateObject function. The CreateObject function references the
component in another directory. To invoke component methods, you use function syntax.

© 2014 Adobe Systems Incorporated. All rights reserved.

1483

Adobe ColdFusion Documentation

Server's Local Time:

tellTimeCFC=CreateObject("component","appResources.components.
tellTime");
tellTimeCFC.getLocalTime();



Calculated UTC Time:

tellTimeCFC.getUTCTime();


© 2014 Adobe Systems Incorporated. All rights reserved.

1484

Adobe ColdFusion Documentation

CreateObject: CORBA object
Description

The CreateObject function can call a method on a CORBA object. The object must be defined and registered for
use.
Returns

A handle to a CORBA interface.
Function syntax

CreateObject(type, context, class, locale)

See also

Integrating COM and CORBA Objects in CFML Applications in the Developing ColdFusion Applications
History

See the History section of the main CreateObject function page.
Parameters

Parameter

Description

type

Type of object to create.
com
corba
java
component
webservice
The default value of type is component.

context

IOR: ColdFusion uses IOR to access CORBA server
NameService: ColdFusion uses naming service to
access server. Valid only with the InitialContext of a
VisiBroker ORB.

class

If context = "ior": absolute path of file that
contains string version of the Interoperable Object
Reference (IOR). ColdFusion must be able to read
file; it must be local to ColdFusion server or
accessible on network
If context = "nameservice": forward
slash-delimited naming context for naming service.
For example: Allaire//Doc/empobject.

© 2014 Adobe Systems Incorporated. All rights reserved.

1485

Adobe ColdFusion Documentation

locale

The name of the Java config that holds the properties
file. For more information, see Configuring and
Administering ColdFusion.

Usage

In the class parameter, if "context=NameService", use a dot separator for the first part of the string. Use either of
the following formats:
"/Eng/CF"
".current/Eng.current/CF"
ColdFusion supports CORBA through the Dynamic Invocation Interface (DII). To use this function with
CORBA objects, provide the name of the file that contains a string version of the IOR, or the object's naming
context in the naming service. Provide the object's attributes, method names, and method signatures.This
function supports user-defined types (structures, arrays, and sequences).
Example

myobj = CreateObject("corba", "d:\temp\tester.ior", "ior",
"visibroker") //
uses IOR
myobj = CreateObject("corba", "/Eng/CF", "nameservice",
"visibroker")
// uses nameservice
myobj = CreateObject("corba", "d:\temp\tester.ior", "nameservice")
// uses nameservice and default configuration

© 2014 Adobe Systems Incorporated. All rights reserved.

1486

Adobe ColdFusion Documentation

CreateObject: Java or EJB object
Description

The CreateObject function can create a Java object, and, by extension, an EJB object.
Returns

A Java object.
Function syntax

CreateObject(type, class)

Parameters

Parameter

Description

type

Type of object to create.
com
corba
java
component
webservice
The default value of type is component.
A Java class name

class

Usage

Any Java class available in the class path that is specified in the ColdFusion Administrator can be loaded and used
from ColdFusion with the CreateObject function.To access Java methods and fields:
1. Call the CreateObject function or the cfobject tag to load the class.
2. Use the initmethod, with appropriate arguments, to call an instance of the class. For example:



Calling a public method on the object without first calling the "init" method invokes a static method.
Arguments and return values can be any Java type (simple, array, object). If strings are passed as
arguments, ColdFusion does the conversions; if strings are received as return values, ColdFusion does no
conversion.Overloaded methods are supported if the number of arguments is different. Future enhancements
will let you use cast functions that allow method signatures to be built more accurately.

© 2014 Adobe Systems Incorporated. All rights reserved.

1487

Adobe ColdFusion Documentation

CreateObject: web service object
Description

This function can create a web service object.
Returns

A web service object.
Function syntax

CreateObject(type, urltowsdl[, portname, wsdl2JavaArgs])
OR
CreateObject(type, urltowsdl, argStruct)

Parameters

Parameter

Description

type

Type of object to create.
com
corba
java
component
webservice
The default value of type is component.

urltowsdl

Specifies the URL to web service WSDL file. One of the
following:
The absolute URL of the web service
The Name (string) assigned in the ColdFusion
Administrator to the web service

portname

© 2014 Adobe Systems Incorporated. All rights reserved.

The port name for the web service. This value is
case-sensitive and corresponds to the port element's
name attribute under the service element. Specify
this parameter if the web service contains multiple
ports. If no port name is specified, ColdFusion uses the
first port found in the WSDL.

1488

Adobe ColdFusion Documentation

A string containing a space-delimited list of arguments
to pass to the WSDL2Java tool that generates Java
stubs for the web services. Useful arguments include
the following:

wsdl2JavaArgs

W or -noWrapped: Turns off the special treatment of
wrapped document/literal style operations.
a or -all: Generates code for all elements in the
WSDL, even unreferenced ones.
w or -wrapArrays: Prefers building beans to
straight arrays for wrapped XML array types. This
switch is not in included in the Axis documentation.
For detailed information on valid arguments, see the
Apache Axis WSDL2Java Reference.
A structure containing web service configuration
arguments. For more information see Usage

argStruct

Usage

You can use the CreateObject function to create a web service. The argStruct structure can contain any
combination of the following values:
Name

Default

Description

password

Password set in the
Administrator, if any

The password to use to access the
web service. If the webservice att
ribute specifies a web service name
configured in the Administrator,
overrides any user name specified
in the Administrator entry.
See portname in the Syntax
Parameter table.

port

proxyPassword

http.proxyPassword system
property, if any

The user's password on the proxy
server.

proxyPort

http.proxyPort system
property, if any

The port to use on the proxy server.

proxyServer

http.proxyHost system
property, if any

The proxy server required to access
the webservice URL.

proxyUser

http.proxyUser system
property, if any

The user ID to send to the proxy
server.

© 2014 Adobe Systems Incorporated. All rights reserved.

1489

Adobe ColdFusion Documentation

refreshWSDL

no

yes: Reload the WSDL file and
regenerate the artifacts used to
consume the web service
no

saveJava

no

yes: Save the Java generated by
the WSDL2Java converter that
generates Java web service
stubs. This code can be useful in
debugging errors.
no

timeout

0 (no time-out)

The time-out for retrieving the web
service WSDL, in seconds.

username

User name set in the
Administrator, if any

The user name to use to access the
web service. If the webservice att
ribute specifies a web service name
configured in the Administrator,
overrides any user name specified
in the Administrator entry.

wsdl2javaArgs

See the Syntax parameter table.

Example


ws = CreateObject("webservice",
"http://www.xmethods.net/sd/2001/TemperatureService.wsdl");
xlatstring = ws.getTemp(zipcode = "55987");
writeoutput("The temperature at 55987 is " & xlatstring);


© 2014 Adobe Systems Incorporated. All rights reserved.

1490

Adobe ColdFusion Documentation

CreateODBCDate
Description

Creates an ODBC date object.
Returns

A date object, in normalized ODBC date format.
Category

Date and time functions
Function syntax

CreateODBCDate(date)

See also

CreateDate, CreateODBCDateTime
Parameters

Parameter

Description

date

Date or date/time object in the range 100 AD-9999 AD.

Usage

This function does not parse or validate values. To ensure that dates are entered and processed correctly (for
example, to ensure that a day/month/year entry is not confused with a month/day/year entry, and so on), Adobe
recommends that you parse entered dates with the DateFormat function, using the mm-dd-yyyy mask, into three
elements. Ensure that values are within appropriate ranges; for example, to validate a month value, use the
attributes validate = "integer" and range = "1,12".
Example

© 2014 Adobe Systems Incorporated. All rights reserved.

1491

Adobe ColdFusion Documentation

CreateODBCDate Example

Your date value, generated with CreateDateTime:



Formatted with CreateDate: #CreateDate(form.year, form.month, form.day)#
Formatted with CreateDateTime:
#CreateDateTime(form.year, form.month, form.day, form.hour, form.minute,
form.second)#
Formatted with CreateODBCDate: #CreateODBCDate(yourDate)#
Formatted with CreateODBCDateTime: #CreateODBCDateTime(yourDate)#

The same value can be formatted with DateFormat:

Formatted with CreateDate and DateFormat:
#DateFormat(CreateDate(form.year,form.month, form.day), "mmm-dd-yyyy")#
Formatted with CreateDateTime and DateFormat:
#DateFormat(CreateDateTime(form.year, form.month, form.day, form.hour,
form.minute, form.second))#
Formatted with CreateODBCDate and DateFormat:
#DateFormat(CreateODBCDate(yourDate), "mmmm d, yyyy")#
Formatted with CreateODBCDateTime and DateFormat:
#DateFormat(CreateODBCDateTime(yourDate), "d/m/yy")#




Enter the year, month and day, as integers:
Year 
Month 
Day 
Hour 
Minute 
Second 

 


© 2014 Adobe Systems Incorporated. All rights reserved.

1492

Adobe ColdFusion Documentation

CreateODBCDateTime
Description

Creates an ODBC date-time object.
Returns

A date-time object, in ODBC timestamp format.
Category

Date and time functions
Function syntax

CreateODBCDateTime(date)

See also

CreateDateTime, CreateODBCDate, CreateODBCTime, Now; Evaluation and type conversion issues in Data
type conversion in the Developing ColdFusion Applications
Parameters

Parameter

Description

date

Date-time object in the range 100 AD-9999 AD.

Usage

When passing a date-time value as a string, enclose it in quotation marks. Otherwise, it is interpreted as a number
representation of a date-time object.
Example

© 2014 Adobe Systems Incorporated. All rights reserved.

1493

Adobe ColdFusion Documentation


CreateODBCDateTime Example

Your date value, generated using CreateDateTime:



Formatted with CreateDate: #CreateDate(form.year, form.month,form.day)#
Formatted with CreateDateTime: #CreateDateTime(form.year,form.month,
form.day,form.hour,form.minute,form.second)#
Formatted with CreateODBCDate: #CreateODBCDate(yourDate)#
Formatted with CreateODBCDateTime: #CreateODBCDateTime(yourDate)#

The same value can be formatted with DateFormat:

Formatted with CreateDate and DateFormat:
#DateFormat(CreateDate(form.year,form.month,form.day), "mmm-dd-yyyy")#
Formatted with CreateDateTime and DateFormat:
#DateFormat(CreateDateTime(form.year,form.month,form.day,
form.hour,form.minute,form.second))#
Formatted with CreateODBCDate and DateFormat:
#DateFormat(CreateODBCDate(yourDate), "mmmm d, yyyy")#
Formatted with CreateODBCDateTime and DateFormat:
#DateFormat(CreateODBCDateTime(yourDate), "d/m/yy")#




Enter a year, month and day, as integers:
Year 
Month 
Day



Hour 
Minute 

Second 

 


© 2014 Adobe Systems Incorporated. All rights reserved.

1494

Adobe ColdFusion Documentation

© 2014 Adobe Systems Incorporated. All rights reserved.

1495

Adobe ColdFusion Documentation

CreateODBCTime
Description

Creates an ODBC time object.
Returns

A time object, in ODBC timestamp format.
Category

Date and time functions
Function syntax

CreateODBCTime(date)

See also

CreateODBCDateTime, CreateTime, Evaluation and type conversion issues in Data type conversion in the Devel
oping ColdFusion Applications
Parameters

Parameter

Description

date

Date/time object in the range 100 AD-9999 AD.

Usage

When passing a date-time value as a string, enclose it in quotation marks. Otherwise, it is interpreted as a number
representation of a date-time object.
Example

© 2014 Adobe Systems Incorporated. All rights reserved.

1496

Adobe ColdFusion Documentation

CreateODBCTime Example

Your time value, created with CreateTime...



Formatted with CreateODBCTime: #CreateODBCTime(yourTime)#
Formatted with TimeFormat: #TimeFormat(yourTime)#



Hour 
Minute 
Second 

 


© 2014 Adobe Systems Incorporated. All rights reserved.

1497

Adobe ColdFusion Documentation

CreateTime
Description

Creates a time variable.
Returns

A time variable.
Category

Date and time functions
Function syntax

CreateTime(hour, minute, second)

See also

CreateODBCTime, CreateDateTime; Evaluation and type conversion issues in Data type conversion in the Devel
oping ColdFusion Applications
Parameters

Parameter

Description

hour

Number in the range 0-23

minute

Number in the range 0-59

second

Number in the range 0-59

Usage

CreateTime is a subset of CreateDateTime.A time variable is a special case of a date-time variable. The date
part of a time variable is set to December 30, 1899.
Example

© 2014 Adobe Systems Incorporated. All rights reserved.

1498

Adobe ColdFusion Documentation

CreateTime Example

Your time value, presented using CreateTime time function:


Formatted with timeFormat: #TimeFormat(yourTime)#
Formatted with timeFormat and hh:mm:ss: #TimeFormat(yourTime, 'hh:mm:ss')#



Hour   
Minute 
Second 

 


© 2014 Adobe Systems Incorporated. All rights reserved.

1499

Adobe ColdFusion Documentation

CreateTimeSpan
Description

Creates a date/time object that defines a time period. You can add or subtract it from other date-time objects and
use it with the cachedWithin attribute of cfquery.
Returns

A date-time object. (A Java Double)
Category

Date and time functions
Function syntax

CreateTimeSpan(days, hours, minutes, seconds)

See also

CreateDateTime, DateAdd, DateConvert; Defining application-level settings and variables in Defining the
application and its event handlers in Application.cfc in the Developing ColdFusion Applications
Parameters

Parameter

Description

days

Integer in the range 0-32768; number of days in time
period

hours

Number of hours in time period

minutes

Number of minutes in time period

seconds

Number of seconds in time period

Usage

Creates a special date-time object that should be used only to add and subtract from other date-time objects or with
the cfquery cachedWithin attribute.If you use the cachedWithin attribute of cfquery, and the original query
date falls within the time span you define, cached query data is used. In this case, the CreateTimeSpan function is
used to define a period of time from the present backwards. The cachedWithin attribute takes effect only if you
enable query caching in the ColdFusion Administrator. For more information, see cfquery.
Example

© 2014 Adobe Systems Incorporated. All rights reserved.

1500

Adobe ColdFusion Documentation


CreateTimeSpan Example






SELECT PARKNAME, REGION, STATE
FROM Parks
ORDER by ParkName, State







Park Name


Region


State





#GetParks.CurrentRow#


#ParkName#


#Region#


#State#







See next #MaxRows# rows





© 2014 Adobe Systems Incorporated. All rights reserved.

1501

Adobe ColdFusion Documentation

© 2014 Adobe Systems Incorporated. All rights reserved.

1502

Adobe ColdFusion Documentation

CreateUUID
Description

Creates a Universally Unique Identifier (UUID). A UUID is a 35-character string representation of a unique 128-bit
integer.
Returns

A ColdFusion format UUID, in the format xxxxxxxx-xxxx-xxxx-xxxxxxxxxxxxxxxx, where x is a hexadecimal
digit (0-9 or A-F). (The character groups are 8-4-4-16.)
Category

Other functions
Function syntax

CreateUUID()

Usage

The ColdFusion UUID generation algorithm uses the unique time-of-day value, the IEEE 802 Host ID, and a
cryptographically strong random number generator to generate UUIDs that conform to the principles laid out in the
draft IEEE RFC "UUIDs and GUIDs."The ColdFusion UUID format is as follows: xxxxxxxx-xxxx-xxxx-xxxxxxx
xxxxxxxxx (8-4-4-16).This does not conform to the Microsoft/DCE standard, which is as follows: xxxxxxxx-xxxxxxxx-xxxx-xxxxxxxxxxxx (8-4-4-4-12) There are UUID test tools and a user-defined function called
CreateGUID, which converts CFML UUIDs to UUID/Microsoft GUID format, available on the web at www.cflib.org.
Use this function to generate a persistent identifier in a distributed environment. To a very high degree of certainty,
this function returns a unique value; no other invocation on the same or any other system returns the same
value.UUIDs are used by distributed computing frameworks, such as DCE/RPC, COM+, and CORBA. In
ColdFusion, you can use UUIDs as primary table keys for applications in which data is stored in shared databases.
In such cases, using numeric keys can cause primary-key constraint violations during table merges. Using UUIDs,
you can eliminate these violations.
Example

CreateUUID Example
 This example uses CreateUUID to generate a UUID when you submit the form.
You can submit the form more than once. 



Your new UUID is: #CreateUUID()#


 


© 2014 Adobe Systems Incorporated. All rights reserved.

1503

Adobe ColdFusion Documentation

CSRFGenerateToken
Description

Provides a random token and stores it in the session. You can also provide a specific key to store in the session.
Returns

Token
Category

Display and formatting functions
Syntax

CSRFGenerateToken([key] [,forceNew])
See also

CSRFVerifyToken
History

ColdFusion 10: Added this function.
Parameters

Parameter

Required\Optional

Description

key

optional

A random token is generated based
on the key provided. This key is
stored in the session.

forceNew

optional

If set to true, a new token is
generated every time the method is
called. If false, in case a token
exists for the key, the same key is
returned.

Usage

Use this function to create a random token and store it in the session.
Example








© 2014 Adobe Systems Incorporated. All rights reserved.

1504

Adobe ColdFusion Documentation

CSRFVerifyToken
Description

Validates the given token against the same stored in the session for a specific key.
Returns

a Boolean value. true is successful.
Category

Display and formatting functions
Syntax

CSRFVerifyToken(token [,key])
See also

CSRFGenerateToken
History

ColdFusion 10: Added this function.
Parameters

Parameter

Required\Optional

Description

token

required

Token that to be validated against
the token stored in the session.

key

Optional

The key against which the token be
searched.

Usage

Use this function to validate the given token against the same stored in the session for a specific key.
Example



#validate#

© 2014 Adobe Systems Incorporated. All rights reserved.

1505

Adobe ColdFusion Documentation

DateAdd
Description

Adds units of time to a date.
Returns

A date/time object.
Category

Date and time functions
Function syntax

DateAdd("datepart", number, "date")

See also

DateConvert, DatePart, CreateTimeSpan
History

ColdFusion MX 6.1: Added the datepart character L or l to represent milliseconds.
Parameters

Parameter

Description

datepart

String:
yyyy: Year
q: Quarter
m: Month
y: Day of year
d: Day
w: Weekday
ww: Week
h: Hour
n: Minute
s: Second
l: Millisecond

number

Number of units of datepart to add to date (positive, to
get dates in the future; negative, to get dates in the
past). Number must be an integer.

date

Date/time object, in the range 100 AD-9999 AD.

Usage

© 2014 Adobe Systems Incorporated. All rights reserved.

1506

Adobe ColdFusion Documentation

The datepart specifiers y, d, and w add a number of days to a date.When passing a date/time object as a string,
enclose it in quotation marks. Otherwise, it is interpreted as a numeric representation of a date/time object.
Example


#date#


#posdateresult#

Example













SELECT UserName, Subject, Posted
FROM Messages

This example uses DateAdd to determine when a message in
the database will expire. Currently, messages older
than #value#

years
quarters
months
days of year
weekdays
weeks
hours
minutes
seconds
years

are expired.


© 2014 Adobe Systems Incorporated. All rights reserved.

1507

Adobe ColdFusion Documentation




UserName
Subject
Posted

#UserName#
#Subject#
#Posted# EXPIRED




Select an expiration value:


years
months
days
weeks
hours
minutes
seconds


© 2014 Adobe Systems Incorporated. All rights reserved.

1508

Adobe ColdFusion Documentation




© 2014 Adobe Systems Incorporated. All rights reserved.

1509

Adobe ColdFusion Documentation

DateCompare
Description

Performs a full date/time comparison of two dates.
Returns

-1, if date1 is earlier than date2
0, if date1 is equal to date2
1, if date1 is later than date2
Category

Date and time functions
Function syntax

DateCompare("date1", "date2" [, "datePart"])

See also

CreateDateTime, DatePart
Parameters

Parameter

Description

date1

Date/time object, in the range 100 AD-9999 AD.

date2

Date/time object, in the range 100 AD-9999 AD.

datePart

Optional. String. Precision of the comparison.
s-Precise to the second (default)
n-Precise to the minute
h-Precise to the hour
d-Precise to the day
m-Precise to the month
yyyy-Precise to the year

Usage

When passing a date/time object as a string, enclose it in quotation marks. Otherwise, it is interpreted as a numeric
representation of a date/time object.
Example

DateCompare Example
The DateCompare function compares two date/time values.




© 2014 Adobe Systems Incorporated. All rights reserved.

1510

Adobe ColdFusion Documentation




#DateFormat(FORM.date1)#
#TimeFormat(FORM.date1)# (Date 1) is
earlier than #DateFormat(FORM.date2)#
#TimeFormat(FORM.date2)# (Date 2)
The dates are not equal


#DateFormat(FORM.date1)#
#TimeFormat(FORM.date1)# (Date 1) is equal
to #DateFormat(FORM.date2)#
#TimeFormat(FORM.date2)# (Date 2)
The dates are equal!


#DateFormat(FORM.date1)#
#TimeFormat(FORM.date1)# (Date 1) is later
than #DateFormat(FORM.date2)#
#TimeFormat(FORM.date2)# (Date 2)
The dates are not equal


This is the default case



Enter two valid date values




Date 1


Date 2


Specify precision to the:



Second


Minute


Hour


Day


Month

© 2014 Adobe Systems Incorporated. All rights reserved.

1511

Adobe ColdFusion Documentation



Year




© 2014 Adobe Systems Incorporated. All rights reserved.

1512

Adobe ColdFusion Documentation




© 2014 Adobe Systems Incorporated. All rights reserved.

1513

Adobe ColdFusion Documentation

DateConvert
Description

Converts local time to Coordinated Universal Time (UTC), or UTC to local time. The function uses the daylight
savings settings in the executing computer to compute daylight savings time, if necessary.
Returns

UTC- or local-formatted time object.
Category

Date and time functions
Function syntax

DateConvert("conversion-type", "date")

See also

GetTimeZoneInfo, CreateDateTime, DatePart
Parameters

Parameter
conversion-type

Description
local2Utc: Converts local time to UTC time.
utc2Local: Converts UTC time to local time.
Date and time string or a variable that contains one. To
create, use CreateDateTime.

date

Usage

When passing a date/time object as a string, enclose it in quotation marks. Otherwise, it is interpreted as a numeric
representation of a date/time object.
Note
You can pass the CreateDate or Now function as the date parameter of this function; for
example: #DateConvert(CreateDate(2007, 4, 10))#

Example

DateConvert Example


The current date and time: #curDate#. 



© 2014 Adobe Systems Incorporated. All rights reserved.

1514

Adobe ColdFusion Documentation

The current date and time converted to UTC time: #utcDate#.




Your date value, presented as a ColdFusion date/time
string:#yourdate#.

Your date and time value, converted to Coordinated Universal Time
(UTC): #yourUTC#.
Your UTC date and time, converted back to local date and time:
#DateConvert("utc2local", yourUTC)#.


Type the date and time, and press Enter to see the conversion.



Enter year, month and day in integer format for date value to view:


© 2014 Adobe Systems Incorporated. All rights reserved.

1515

Adobe ColdFusion Documentation



Year


Month


Day


Hour


Minute


Second





© 2014 Adobe Systems Incorporated. All rights reserved.

1516

Adobe ColdFusion Documentation

DateDiff
Description

Determines the integer number of units by which date1 is less than date2.
Returns

A number of units, of type datepart.
Category

Date and time functions
Function syntax

DateDiff("datepart", "date1", "date2")

See also

DateAdd, DatePart, CreateTimeSpan
History

ColdFusion MX:
Changed how negative date differences are calculated: this function calculates negative date differences
correctly; its output may be different from that in earlier releases.
Changed the w and ww masks; they determine the number of full weeks between the two dates.
Parameters

Parameter

Description

datepart

String that specifies the units in which to count; for
example yyyy requests a date difference in whole
years.
yyyy: Years
q: Quarters
m: Months
y: Days of year (same as d)
d: Days
w: Weekdays (same as ww)
ww: Weeks
h: Hours
n: Minutes
s: Seconds

date1

Date/time object, in the range 100 AD-9999 AD.

date2

Date/time object, in the range 100 AD-9999 AD.

© 2014 Adobe Systems Incorporated. All rights reserved.

1517

Adobe ColdFusion Documentation
Usage

The DateDiff function determines the number of complete datepart units between the two dates; for example, if
the datepart parameter is "m" and the dates differ by 55 days, the function returns 1.Enclose string constant dates in
quotation marks. If the text contains only numbers (such 1932), and is not surrounded by quotation marks,
ColdFusion interprets it as a date/time object, resulting in an incorrect value.
Example









This example uses DateDiff to determine the difference
in

years
quarters
months
days
days
weekdays
weeks
hours
minutes
seconds
years

dateparts between date1 and date2.

The difference is #Abs(DateDiff(type, form.date2,
form.date1))#

years
quarters
months
days
days
weekdays
weeks
hours
minutes
seconds
years
.

The two dates are equal!Try changing one of the values ...


© 2014 Adobe Systems Incorporated. All rights reserved.

1518

Adobe ColdFusion Documentation


Please enter two valid date/time values, formatted like this:
#DateFormat(Now())#



Date 1

Date 2

What kind of unit to show difference?

years
quarters
months
days of year
days
weekdays
weeks
hours
minutes
seconds



© 2014 Adobe Systems Incorporated. All rights reserved.

1519

Adobe ColdFusion Documentation




© 2014 Adobe Systems Incorporated. All rights reserved.

1520

Adobe ColdFusion Documentation

DateFormat
Description

Formats a date value using U.S. date formats. For international date support, use LSDateFormat.
Returns

A text string representing the date formatted according to the mask. If no mask is specified, returns the value in ddmmm-yy format.
Category

Date and time functions
Function syntax

DateFormat("date" \[, "mask" ])

See also

Now, CreateDate, LSDateFormat, LSParseDateTime, LSTimeFormat, TimeFormat, ParseDateTime
History

ColdFusion MX: Added support for the following mask parameter options: short, medium, long, and full.
Parameters

Parameter

Description

date

Date/time object, in the range 100 AD-9999 AD.

© 2014 Adobe Systems Incorporated. All rights reserved.

1521

Adobe ColdFusion Documentation

Characters that show how ColdFusion displays a date:

mask

d: Day of the month as digits; no leading zero for
single-digit days.
dd: Day of the month as digits; leading zero for
single-digit days.
ddd: Day of the week as a three-letter abbreviation.
dddd: Day of the week as its full name.
m: Month as digits; no leading zero for single-digit
months.
mm: Month as digits; leading zero for single-digit
months.
mmm: Month as a three-letter abbreviation.
mmmm: Month as its full name.
yy: Year as last two digits; leading zero for years less
than 10.
yyyy: Year represented by four digits.
gg: Period/era string. Ignored. Reserved. The
following masks tell how to format the full date and
cannot be combined with other masks:
short: equivalent to m/d/y
medium: equivalent to mmm d, yyyy
long: equivalent to mmmm d, yyyy
full: equivalent to dddd, mmmm d, yyyy

Usage

When passing a date/time object as a string, enclose it in quotation marks. Otherwise, it is interpreted as a numeric
representation of a date/time object.
Note
You can pass the CreateDate function or Now function as the date parameter of this function;
for example: #DateFormat(CreateDate(2001, 3, 3))#

Date and time values in database query results can vary in sequence and formatting unless you use functions to
format them. To ensure that application users correctly understand displayed dates and times, Adobe recommends
that you use this function and the LSDateFormat, TimeFormat, and LSTimeFormat functions to format resultset
values. For more information and examples, see TechNote, "ColdFusion Server (5 and 4.5.x) with Oracle:
Formatting Date and Time Query Results," on the website at go.adobe.com/kb/ts_tn_18070_en-us.
Note
The DateFormat function is best used for formatting output, not for formatting input. For
formatting input, use one of the date/time creation functions (for example, CreateDate) instead.

Example

© 2014 Adobe Systems Incorporated. All rights reserved.

1522

Adobe ColdFusion Documentation



DateFormat Example
Today's date is #todayDate#.
Using DateFormat, we can display that date in different ways:


#DateFormat(todayDate)#
#DateFormat(todayDate, "mmm-dd-yyyy")#
#DateFormat(todayDate, "mmmm d, yyyy")#
#DateFormat(todayDate, "mm/dd/yyyy")#
#DateFormat(todayDate, "d-mmm-yyyy")#
#DateFormat(todayDate, "ddd, mmmm dd, yyyy")#
#DateFormat(todayDate, "short")#
#DateFormat(todayDate, "medium")#
#DateFormat(todayDate, "long")#
#DateFormat(todayDate, "full")#



© 2014 Adobe Systems Incorporated. All rights reserved.

1523

Adobe ColdFusion Documentation

DateTimeFormat
Description

Formats date and time values using date and time formatting conventions.
Returns

A formatted date and time value.
History

ColdFusion 10: Added this function.
Syntax

dateTimeFormat (date_)dateTimeFormat (_date [, mask_])dateTimeFormat (_date [_, mask,
_timeZone])
Properties

Parameter

Description

date

Required. A date/time object, in the range 100 AD-9999
AD.

© 2014 Adobe Systems Incorporated. All rights reserved.

1524

Adobe ColdFusion Documentation

mask

Optional. Characters that show how ColdFusion
displays a date:
d: Day of the month as digits; no leading zero for
single-digit days.
dd: Day of the month as digits; leading zero for
single-digit days.
ddd: Day of the week as a three-letter
abbreviation.
dddd: Day of the week as its full name.
m: Month as digits; no leading zero for single-digit
months.
mm: Month as digits; leading zero for single-digit
months.
mmm: Month as a three-letter abbreviation.
mmmm: Month as its full name.
yy: Year as last two digits; leading zero for years
less than 10.
yyyy: Year represented by four digits.
gg: Period/era string.
h: hours; no leading zero for single-digit hours
(12-hour clock)
hh: hours; leading zero for single-digit hours
(12-hour clock)
H: hours; no leading zero for single-digit hours
(24-hour clock)
HH: hours; leading zero for single-digit hours
(24-hour clock)
n: minutes; no leading zero for single-digit minutes
nn: minutes; a leading zero for single-digit minutes
s: seconds; no leading zero for single-digit
seconds
ss: seconds; leading zero for single-digit seconds
l or L: milliseconds, with no leading zeros
t: one-character time marker string, such as A or P
tt: multiple-character time marker string, such as
AM or PM
The following masks tell how to format the full date and
time and cannot be combined with other masks:
short: equivalent to m/d/y h:mm tt
medium: equivalent to mmm d, yyyy h:mm:ss tt
long: medium followed by three-letter time zone; as
in, mmmm d, yyyy h:mm:ss tt EST
full: equivalent to dddd, mmmm d, yyyy h:mm:ss tt
EST
The function also follows Java date time mask. For
details, see the section Date and Time Patterns on this
page.

© 2014 Adobe Systems Incorporated. All rights reserved.

1525

Adobe ColdFusion Documentation

timeZone

The time-zone information. You can specify in either of
the following formats:
Abbreviation such as GMT or PST
Full name such as Europe/Dublin
By default, this is the time-zone followed by the
system.

Example



DateTimeFormat Example
Today's date and time are #todayDateTime#.
Using DateTimeFormat, we can display that date and time in different ways:


#DateTimeFormat(todayDateTime)#
#DateTimeFormat(todayDateTime, "yyyy.MM.dd G 'at' HH:nn:ss z")#
#DateTimeFormat(todayDateTime, "EEE, MMM d, ''yy")#
#DateTimeFormat(todayDateTime, "h:nn a")#
#DateTimeFormat(todayDateTime, "hh 'o''clock' a, zzzz")#
#DateTimeFormat(todayDateTime, "K:nn a, z")#
#DateTimeFormat(todayDateTime, "yyyyy.MMMMM.dd GGG hh:nn aaa")#
#DateTimeFormat(todayDateTime, "EEE, d MMM yyyy HH:nn:ss Z")#
#DateTimeFormat(todayDateTime, "yyMMddHHnnssZ", "GMT")#



© 2014 Adobe Systems Incorporated. All rights reserved.

1526

Adobe ColdFusion Documentation

DatePart
Description

Extracts a part from a date value.
Returns

Part of a date, as an integer.
Category

Date and time functions
Function syntax

DatePart("datepart", "date")

See also

DateAdd, DateConvert
History

ColdFusion MX 6.1: Added the datepart character L or l to represent milliseconds.
Parameters

Parameter

Description

datepart

String:
yyyy: Year
q: Quarter
m: Month
y: Day of year
d: Day
w: Weekday
ww: Week
h: Hour
n: Minute
s: Second
l: Millisecond

date

Date/time object, in the range 100 AD-9999 AD.

Usage

When passing a date/time object as a string, enclose it in quotation marks. Otherwise, it is interpreted as a numeric
representation of a date/time object.
Example

© 2014 Adobe Systems Incorporated. All rights reserved.

1527

Adobe ColdFusion Documentation



DatePart Example
Today's date is #todayDate#.
Using datepart, we extract an integer representing the dateparts from that value


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



© 2014 Adobe Systems Incorporated. All rights reserved.

1528

Adobe ColdFusion Documentation

Day
Description

Determines the day of the month, in a date.
Returns

The ordinal for the day of the month, ranging from 1 to 31.
Category

Date and time functions
Function syntax

Day("date")

See also

DayOfWeek, DayOfWeekAsString, DayOfYear, DaysInMonth, DaysInYear, FirstDayOfMonth
Parameters

Parameter

Description

date

Date/time object, in the range 100 AD-9999 AD.

Usage

When passing a date/time object as a string, enclose it in quotation marks. Otherwise, it is interpreted as a numeric
representation of a date/time object.
Note
You can pass the CreateDate function or Now function as the date parameter of this function;
for example: #Day(CreateDate(2001, 3, 3))#

Example

© 2014 Adobe Systems Incorporated. All rights reserved.

1529

Adobe ColdFusion Documentation

Day Example

More information about your date:


Date: #DateFormat(yourDate)#. 

It is #DayofWeekAsString(DayOfWeek(yourDate))#,
day #DayOfWeek(yourDate)# in the week.

This is day #Day(YourDate)#
in the month of #MonthAsString(Month(yourDate))#,
which has #DaysInMonth(yourDate)# days.

We are in week #Week(yourDate)# of #Year(YourDate)#
(day #DayofYear(yourDate)# of #DaysinYear(yourDate)#).

This is a leap year
This is not a leap year



© 2014 Adobe Systems Incorporated. All rights reserved.

1530

Adobe ColdFusion Documentation

DayOfWeek
Description

Determines the day of the week, in a date.
Returns

The ordinal for the day of the week, as an integer in the range 1 (Sunday) to 7 (Saturday).
Category

Date and time functions
Function syntax

DayOfWeek("date")

See also

Day, DayOfWeekAsString, DayOfYear, DaysInMonth, DaysInYear, FirstDayOfMonth
Parameters

Parameter

Description

date

Date/time object, in the range 100 AD-9999 AD.

Usage

When passing a date/time object as a string, enclose it in quotation marks. Otherwise, it is interpreted as a numeric
representation of a date/time object.
Note
You can pass the CreateDate function or Now function as the date parameter of this function;
for example, #DayOfWeek(CreateDate(2001, 3, 3))#

Example

© 2014 Adobe Systems Incorporated. All rights reserved.

1531

Adobe ColdFusion Documentation

DayOfWeek Example

More information about your date:


Your date, #DateFormat(yourDate)#.

It is #DayofWeekAsString(DayOfWeek(yourDate))#, day
#DayOfWeek(yourDate)# in the week.

This is day #Day(YourDate)# in the month of
#MonthAsString(Month(yourDate))#, which has
#DaysInMonth(yourDate)# days.

We are in week #Week(yourDate)# of #Year(YourDate)# (day
#DayofYear(yourDate)# of #DaysinYear(yourDate)#).

This is a leap year
This is not a leap year



© 2014 Adobe Systems Incorporated. All rights reserved.

1532

Adobe ColdFusion Documentation

DayOfWeekAsString
Description

Determines the day of the week, in a date, as a string function.
Returns

The day of the week, as a string in the current locale, that corresponds to day_of_week.
Category

Date and time functions, String functions
Function syntax

DayOfWeekAsString(day_of_week [, locale])

See also

Day, DayOfWeek, DayOfYear, DaysInMonth, DaysInYear, FirstDayOfMonth
History

ColdFusion 8: Added the locale parameter.
ColdFusion MX 7: Changed behavior. The returned string is now in the language of the current locale.
Parameters

Parameter

Description

day_of_week

Integer, in the range 1 (Sunday) - 7 (Saturday).

locale

Locale to use instead of the locale of the page when
processing the function

Example

The following example shows the use of the DayOfWeekAsString function. It is the action page for a form that
submits year, month, and day fields.

© 2014 Adobe Systems Incorporated. All rights reserved.

1533

Adobe ColdFusion Documentation

DayOfWeekAsString Example

More information about your date:


Your date, #DateFormat(yourDate)#.

It is #DayofWeekAsString(DayOfWeek(yourDate))#, day
#DayOfWeek(yourDate)# in the week.

This is day #Day(YourDate)# in the month of
#MonthAsString(Month(yourDate))#, which has
#DaysInMonth(yourDate)# days.

We are in week #Week(yourDate)# of #Year(YourDate)# (day #DayofYear(yourDate)#
of #DaysinYear(yourDate)#).

This is a leap year
This is not a leap year



© 2014 Adobe Systems Incorporated. All rights reserved.

1534

Adobe ColdFusion Documentation

DayOfYear
Description

Determines the day of the year, in a date.
Returns

The ordinal value of day of the year, as an integer.
Category

Date and time functions
Function syntax

DayOfYear("date")

See also

Day, DayOfWeek, DayOfWeekAsString, DaysInMonth, DaysInYear, FirstDayOfMonth
Parameters

Parameter

Description

date

Date/time object, in the range 100 AD-9999 AD.

Usage

This function accounts for leap years. When passing a date/time object as a string, enclose it in quotation marks.
Otherwise, it is interpreted as a numeric representation of a date/time object.
Note
You can pass the CreateDate function or Now function as the date parameter of this function;
for example, #DayOfYear(CreateDate(2001, 3, 3))#

Example

© 2014 Adobe Systems Incorporated. All rights reserved.

1535

Adobe ColdFusion Documentation

Day7OfYear Example

More information about your date:


Your date, #DateFormat(yourDate)#.

It is #DayofWeekAsString(DayOfWeek(yourDate))#,
day #DayOfWeek(yourDate)# in the week.

This is day #Day(yourDate)# in the month of
#MonthAsString(Month(yourDate))#, which has
#DaysInMonth(yourDate)# days.

We are in week #Week(yourDate)# of #Year(yourDate)#
(day #DayofYear(yourDate)# of #DaysinYear(yourDate)#).

This is a leap year
This is not a leap year



© 2014 Adobe Systems Incorporated. All rights reserved.

1536

Adobe ColdFusion Documentation

DaysInMonth
Description

Determines the number of days in a month.
Returns

The number of days in the month in Date.
Category

Date and time functions
Function syntax

DaysInMonth("date")

See also

Day, DayOfWeek, DayOfWeekAsString, DayOfYear, DaysInYear, FirstDayOfMonth
Parameters

Parameter

Description

date

Date/time object, in the range 100 AD-9999 AD.

Usage

When passing a date/time object as a string, enclose it in quotation marks. Otherwise, it is interpreted as a numeric
representation of a date/time object.
Note
You can pass the Now function or the CreateDate function as the date parameter of this
function; for example: #DaysInMonth(CreateDate(2001, 3, 3))#

Example

© 2014 Adobe Systems Incorporated. All rights reserved.

1537

Adobe ColdFusion Documentation

DaysInMonth Example

More information about your date:


Your date, #DateFormat(yourDate)#.

It is #DayofWeekAsString(DayOfWeek(yourDate))#, day
#DayOfWeek(yourDate)# in the week.

This is day #Day(YourDate)# in the month of
#MonthAsString(Month(yourDate))#, which has
#DaysInMonth(yourDate)# days.

We are in week #Week(yourDate)# of #Year(YourDate)#
(day #DayofYear(yourDate)# of #DaysinYear(yourDate)#).

This is a leap year
This is not a leap year



© 2014 Adobe Systems Incorporated. All rights reserved.

1538

Adobe ColdFusion Documentation

DaysInYear
Description

Determines the number of days in a year.
Returns

The number of days in a year.
Category

Date and time functions
Function syntax

DaysInYear("date")

See also

Day, DayOfWeek, DayOfWeekAsString, DayOfYear, DaysInMonth, FirstDayOfMonth, IsLeapYear
Parameters

Parameter

Description

date

Date/time object, in the range 100 AD-9999 AD.

Usage

DaysInYear accounts for leap years.When passing a date/time object as a string, enclose it in quotation marks.
Otherwise, it is interpreted as a numeric representation of a date/time object.
Note
You can pass the CreateDate function or the Now function as the date parameter of this
function; for example: #DaysInYear(CreateDate(2001, 3, 3))#

Example

© 2014 Adobe Systems Incorporated. All rights reserved.

1539

Adobe ColdFusion Documentation

DaysInYear Example

More information about your date:


Your date, #DateFormat(yourDate)#.

It is #DayofWeekAsString(DayOfWeek(yourDate))#, day
#DayOfWeek(yourDate)# in the week.

This is day #Day(YourDate)# in the month of
#MonthAsString(Month(yourDate))#, which has
#DaysInMonth(yourDate)# days.

We are in week #Week(yourDate)# of #Year(yourDate)# (day
#DayofYear(yourDate)# of #DaysinYear(yourDate)#).


© 2014 Adobe Systems Incorporated. All rights reserved.

1540

Adobe ColdFusion Documentation

DE
Description

Escapes any double-quotation marks in the parameter and wraps the result in double-quotation marks.
Returns

Parameter, surrounded by double-quotation marks, with any inner double-quotation marks escaped.
Category

Dynamic evaluation functions
Function syntax

DE(string)

See also

Evaluate, IIf, PrecisionEvaluate, Using Expressions and Number Signs in the Developing ColdFusion
Applications
Parameters

Parameter

Description

string

String to evaluate, after delay

Usage

The DE function postpones evaluation of a string that is passed as a parameter to the IIf, Evaluate, or Precisi
onEvaluate functions. This function is especially useful with the IIf function, which automatically evaluates its
second and third parameters as expressions. You can use the DE function to prevent the function from evaluating a
string parameter that is to be output as a variable, and must not be treated as an expression. The following example
shows this use; it uses IIF to alternate table-row background colors, white and gray, and uses the DE function to
prevent ColdFusion from evaluating the color strings.






hello #i#






The DE function does not delay evaluation of variable names that are surrounded by number signs (#). The

© 2014 Adobe Systems Incorporated. All rights reserved.

1541

Adobe ColdFusion Documentation

ColdFusion function evaluates the variable regardless of whether the DE function is present.The following example
shows how you can use the DE function and number signs together, and shows how the function works with an IIF
function:





The expression is #myresult#


ColdFusion processes this code as follows:
1. ColdFusion sets the variables var1 and var2 to be the strings Blue and Green.
2. In the fourth line, ColdFusion evaluates the variables surrounded by number signs first, replacing them with
the strings Blue and Green, the values of the variables.
3. The IIF function evaluates the test expression, determines that it is False, and then evaluates the third
parameter.
4. The third parameter is a DE function, which takes the string Green and surrounds it in quotation marks
5. The IIF function returns the string "Green", including the quotation marks.
6. The cfset tag gets the expression result="Green", and sets the value of the myresult variable to the string
Green.
7. ColdFusion evaluates #myresult# in the output text, replaces the variable with its value, the string Green,
and displays the result.
Example

© 2014 Adobe Systems Incorporated. All rights reserved.

1542

Adobe ColdFusion Documentation


DE Example




Evaluate the Expression #FORM.MyExpression#

The code:

#Evaluate(FORM.myExpression)#



The result:


#Evaluate(FORM.myExpression)#

Use DE to prevent the Evaluate function from evaluating
The code:

#Evaluate(DE(FORM.MyExpression))#


The result:


#Evaluate(DE(FORM.MyExpression))#




Sorry, there's been an Error.
Try a simple expression, such as "2+2".


#cfcatch.message#




Enter any valid ColdFusion expression





© 2014 Adobe Systems Incorporated. All rights reserved.

1543

Adobe ColdFusion Documentation

DecimalFormat
Description

Converts a number to a decimal-formatted string.
Returns

A number as a string formatted with two decimal places and a thousands separator.
Category

Display and formatting functions
Function syntax

DecimalFormat(number)

See also

DollarFormat, NumberFormat
Parameters

Parameter

Description

number

Number to format

Example

DecimalFormat Function
Returns a number to two decimal places.



#counter# * Square Root of 2:
#DecimalFormat(counter * sqr(2))#





© 2014 Adobe Systems Incorporated. All rights reserved.

1544

Adobe ColdFusion Documentation

DecodeForHTML
Description

Decodes an HTML encoded string.
Returns

Decoded HTML string.
Category

Display and formatting functions.
Function syntax

DecodeforHTML(String encodedinput)

See also

Canonicalize,EncodeForHTMLAttribute, EncodeForJavaScript, EncodeForCSS, EncodeForURL
History

ColdFusion 10: Added this function.
Parameters

Parameter

Description

inputString

Required. The encoded string to decode.

Example



Output:#DecodeForHTML(form.encodedUserName)#









© 2014 Adobe Systems Incorporated. All rights reserved.

1545

Adobe ColdFusion Documentation

DecodeFromURL
Description

Decodes an encoded HTML URL string.
Returns

Decoded HTML URL string.
Category

Display and formatting functions.
Function syntax

DecodeFromURL(String encodedinput)

See also

Canonicalize,EncodeForHTMLAttribute, EncodeForJavaScript, EncodeForCSS, EncodeForURL
History

ColdFusion 10: Added this function.
Parameters

Parameter

Description

inputString

Required. The encoded URL string to decode.

Example





String: #string# 

URL Encoded: #urlencoded#

URL Decoded: #urldecoded#



© 2014 Adobe Systems Incorporated. All rights reserved.

1546

Adobe ColdFusion Documentation

DecrementValue
Description

Decrements the integer part of a number.
Returns

Integer part of number, decremented by one.
Category

Mathematical functions
Function syntax

DecrementValue(number)

See also

IncrementValue
Parameters

Parameter

Description

number

Number to decrement

Example

DecrementValue Example
Returns the integer part of a number decremented by one.
DecrementValue(0):
#DecrementValue(0)#
DecrementValue("1"):
#DecrementValue("1")#
DecrementValue(123.35):
#DecrementValue(123.35)#

© 2014 Adobe Systems Incorporated. All rights reserved.

1547

Adobe ColdFusion Documentation

Decrypt
Description

Decrypts a string that is encrypted using a standard encryption technique, including strings encrypted by the Encry
pt function.
Returns

An unencrypted string.
Category

Security functions, String functions
Function syntax

Decrypt(encrypted_string, key[, algorithm, encoding, IVorSalt, iterations])

See also

Duplicate, Encrypt
History

ColdFusion 8: Added support for encryption using the RSA BSafe Crypto-J library on Enterprise Edition.
ColdFusion MX 7.01: Added the IVorSalt and iterations parameters.
ColdFusion MX 7: Added the algorithm and encoding parameters.
Parameters

Parameter

Description

encrypted_string

String to decrypt.

key

String. For the CFMX_COMPAT algorithm, the seed
that was used to encrypt the string; for all other
algorithms, the string generated by the generateSecr
etKey() method.

© 2014 Adobe Systems Incorporated. All rights reserved.

1548

Adobe ColdFusion Documentation

algorithm

(Optional) The Enterprise Edition of ColdFusion installs
the RSA BSafe Crypto-J library, which provides
FIPS-140 Compliant Strong Cryptography. For a list of
algorithms, see the Encrypt function.The Standard
Edition of ColdFusion installs a cryptography library
with the following algorithms:
CFMX_COMPAT: the algorithm used in ColdFusion
MX and prior releases. This algorithm is the least
secure option (default).
AES: the Advanced Encryption Standard specified by
the National Institute of Standards and Technology
(NIST) FIPS-197.
BLOWFISH: the Blowfish algorithm defined by Bruce
Schneier.
DES: the Data Encryption Standard algorithm
defined by NIST FIPS-46-3.
DESEDE: the "Triple DES" algorithm defined by
NIST FIPS-46-3.
If you install a security provider with additional
cryptography algorithms, you can also specify any of
its string encryption and decryption algorithms.

encoding

(Optional; if you specify this parameter, also specify the
algorithm parameter.) The binary encoding used to
represent the data as a string. Must be the same as the
algorithm used to encrypt the string.
Base64: the Base64 algorithm, as specified by IETF
RFC 2045.
Hex: the characters A-F and 0-9 represent the
hexadecimal byte values.
UU: the UNIX standard UUEncode algorithm
(default).

IVorSalt

(Optional) Specify this parameter to adjust ColdFusion
encryption to match the details of other encryption
software. If you specify this parameter, also specify the
algorithm parameter.
For Block Encryption Algorithms: The binary
Initialization Vector value to use with the algorithm.
The algorithm must contain a Feedback Mode other
than ECB. This must be a binary value that is exactly
the same size as the algorithm block size.
For Password Based Encryption Algorithms: The
binary Salt value to transform the password into a
key.

© 2014 Adobe Systems Incorporated. All rights reserved.

1549

Adobe ColdFusion Documentation

iterations

(Optional) The number of iterations to transform the
password into a binary key. Specify this parameter to
adjust ColdFusion encryption to match the details of
other encryption software. If you specify this parameter,
also specify the algorithm parameter with a Password
Based Encryption (PBE) algorithm. Do not specify this
parameter for Block Encryption Algorithms. Use the
same value to encrypt and decrypt the data.

Usage

This function uses a symmetric key-based algorithm, in which the same key is used to encrypt and decrypt a string.
The parameter values must match the values used to encode string. The security of the encrypted string depends
on maintaining the secrecy of the key. ColdFusion uses the Java Cryptography Extension (JCE) and installs a Sun
Java runtime that includes the Sun JCE default security provider. This provider includes the algorithms listed in the
Parameters section. The JCE framework includes facilities for using other provider implementations; however,
Adobe cannot provide technical support for third-party security providers.
Example

Decrypt Example



/* GenerateSecretKey does not generate key for the CFMX_COMPAT algorithm,
so use the key from the form.
*/
if (Form.myAlgorithm EQ "CFMX_COMPAT")
theKey=Form.MyKey;
// For all other encryption techniques, generate a secret key.
else
theKey=generateSecretKey(Form.myAlgorithm);
//Encrypt the string
encrypted=encrypt(Form.myString, theKey, Form.myAlgorithm,
Form.myEncoding);
//Decrypt it
decrypted=decrypt(encrypted, theKey, Form.myAlgorithm, Form.myEncoding);



The algorithm: #Form.myAlgorithm#

The key: #theKey#



The string: #Form.myString# 



Encrypted: #encrypted#



Decrypted: #decrypted#





© 2014 Adobe Systems Incorporated. All rights reserved.

1550

Adobe ColdFusion Documentation


Select the encoding


UU
Base64
Hex




Select the algorithm


CFMX_COMPAT
AES
DES
DESEDE




Input your key (used for CFMX_COMPAT encryption only)





Enter string to encrypt

This string is encrypted (you can replace it with more typing).



© 2014 Adobe Systems Incorporated. All rights reserved.

1551

Adobe ColdFusion Documentation




© 2014 Adobe Systems Incorporated. All rights reserved.

1552

Adobe ColdFusion Documentation

DecryptBinary
Description

Decrypts encrypted binary data with the specified key, value, algorithm, salt, and iterations.
Returns

Unencrypted binary data.
Category

Security functions, String functions
Function syntax

DecryptBinary(bytes, key[, algorithm, IVorSalt, iterations])

See also

Duplicate, Encrypt, Decrypt
History

ColdFusion 8: Added support for encryption using the RSA BSafe Crypto-J library on Enterprise Edition.
ColdFusion MX 7.01: Added this function.
Parameters

Parameter

Description

bytes

Binary data to decrypt.

key

String. For the CFMX_COMPAT algorithm, the seed
that was used to encrypt the binary data; for all other
algorithms, the string generated by the generateSecr
etKey() method.

© 2014 Adobe Systems Incorporated. All rights reserved.

1553

Adobe ColdFusion Documentation

algorithm

(Optional) The Enterprise Edition of ColdFusion installs
the RSA BSafe Crypto-J library, which provides
FIPS-140 Compliant Strong Cryptography. For a list of
algorithms, see the Encrypt function.The Standard
Edition of ColdFusion installs a cryptography library
with the following algorithms:
CFMX_COMPAT: the algorithm used in ColdFusion
MX and prior releases. This algorithm is the least
secure option (default).
AES: the Advanced Encryption Standard specified by
the National Institute of Standards and Technology
(NIST) FIPS-197.
BLOWFISH: the Blowfish algorithm defined by Bruce
Schneier.
DES: the Data Encryption Standard algorithm
defined by NIST FIPS-46-3.
DESEDE: the "Triple DES" algorithm defined by
NIST FIPS-46-3.
If you install a security provider with additional
cryptography algorithms, you can also specify any of
its string encryption and decryption algorithms.

IVorSalt

(Optional) Specify this parameter to adjust ColdFusion
encryption to match the details of other encryption
software. If you specify this parameter, also specify the
algorithm parameter.
For Block Encryption Algorithms: The binary
Initialization Vector value to use with the algorithm.
The algorithm must contain a Feedback Mode other
than ECB. This must be a binary value that is exactly
the same size as the algorithm block size.
For Password Based Encryption Algorithms:- This is
the binary Salt value to transform the password into a
key.

iterations

(Optional) The number of iterations to transform the
password into a binary key. Specify this parameter to
adjust ColdFusion encryption to match the details of
other encryption software. If you specify this parameter,
also specify the algorithm parameter with a
Password Based Encryption (PBE) algorithm. Do not
specify this parameter for Block Encryption Algorithms.
Use the same value to encrypt and decrypt the data.

Usage

This function uses a symmetric key-based algorithm, in which the same key is used to encrypt and decrypt data.
The parameter values must match the values used to encode the string. The security of the encrypted string
depends on maintaining the secrecy of the key. ColdFusion uses the Java Cryptography Extension (JCE) and

© 2014 Adobe Systems Incorporated. All rights reserved.

1554

Adobe ColdFusion Documentation

installs a Sun Java runtime that includes the Sun JCE default security provider. This provider includes the algorithms
listed in the Parameters section. The JCE framework includes facilities for using other provider implementations;
however, Adobe cannot provide technical support for third-party security providers.
Example

© 2014 Adobe Systems Incorporated. All rights reserved.

1555

Adobe ColdFusion Documentation

DecryptBinary Example
< !--- Do the following if the form has been submitted. --->



/* GenerateSecretKey does not generate key for the CFMX_COMPAT algorithm,
so use the key from the form.
*/
if (Form.myAlgorithm EQ "CFMX_COMPAT")
theKey=Form.MyKey;
// For all other encryption techniques, generate a secret key.
else
theKey=generateSecretKey(Form.myAlgorithm);
//Encrypt the string
encrypted=encryptBinary(myData, theKey, Form.myAlgorithm);
//Decrypt it
decrypted=decryptBinary(encrypted, theKey, Form.myAlgorithm);







The algorithm: #Form.myAlgorithm#

The key: #theKey#



The InputFile: #Form.myfile# 



Encrypted: #encfile#



Decrypted: #decfile#





Select the algorithm


CFMX_COMPAT
AES
DES
DESEDE




Input your key (used for CFMX_COMPAT encryption only)





Enter filename to encrypt






© 2014 Adobe Systems Incorporated. All rights reserved.

1556

Adobe ColdFusion Documentation

DeleteClientVariable
Description

Deletes a client variable. (To test for the existence of a variable, use IsDefined.)
Returns

True, if the variable is successfully deleted; false, otherwise.
Category

Other functions
Function syntax

DeleteClientVariable("name")

See also

GetClientVariablesList
History

ColdFusion MX: Changed behavior: if the variable is not present, this function now returns False. (In earlier
releases, it threw an error.)
Parameters

Parameter

Description

name

Name of a client variable to delete, surrounded by
double-quotation marks

Example

© 2014 Adobe Systems Incorporated. All rights reserved.

1557

Adobe ColdFusion Documentation


DeleteClientVariable Example
This view-only example deletes a client variable called "User_ID", if it
exists in the list of client variables returned by GetClientVariablesList.
This example requires the existence of an Application.cfm file and client
management to be in effect.


© 2014 Adobe Systems Incorporated. All rights reserved.

1558

Adobe ColdFusion Documentation

DeserializeJSON
Description

Converts a JSON (JavaScript Object Notation) string data representation into CFML data, such as a CFML structure
or array.
Returns

The data value in ColdFusion format: a structure, array, query, or simple value.
Category

Conversion functions
Syntax

DeserializeJSON(JSONVar[, strictMapping, useCustomSerializer])

See also

IsJSON, SerializeJSON, cfajaxproxy, Using Ajax Data and Development Features in the Developing
ColdFusion Applications, http://www.json.org
History

ColdFusion 11: Added the attribute, useCustomSerializer.
ColdFusion 8: Added this function
Parameters

Parameter

Description

JSONVar

A string that contains a valid JSON construct, or
variable that represents one.

strictMapping

A Boolean value that specifies whether to convert the
JSON strictly, as follows:
true: (Default) Convert the JSON string to
ColdFusion data types that correspond directly to the
JSON data types.
false: Determine if the JSON string contains
representations of ColdFusion queries, and if so,
convert them to queries.

useCustomSerializer

© 2014 Adobe Systems Incorporated. All rights reserved.

true/false. Whether to use the customSerializer or not.
The default value is true. The custom serializer will
always be used for deserialization. If false, the JSON
deserialization will be done using the default
ColdFusion behavior.

1559

Adobe ColdFusion Documentation
Usage

This function is useful any time a ColdFusion page receives data as JSON strings. It is useful in ColdFusion
applications that use Ajax to represent data on the client browser, and lets you consume on the server JSON format
data from the client-side Ajax JavaScript. You can also use it on pages that get data from services that supply data
as JavaScript function calls with JSON parameters; the example shows this use case.The DeserializeJSON funct
ion converts each JSON data type directly into the equivalent ColdFusion data type, as follows:
If the strictMapping parameter is true (the default), all JSON objects become CFML structures.
If the strictMapping parameter is false, ColdFusion determines if JSON objects represent queries and, if
so, converts them to ColdFusion query object. All other JSON objects become ColdFusion structures. The De
serializeJSON function recognizes a JSON structure as a query and converts it properly if the structure
uses either of the two query representation formats described in the SerializeJSON reference.
JSON Arrays, Strings, and Numbers become ColdFusion arrays, strings, and numbers.
The JSON null value becomes the string null.
JSON string representations of a dates and times remain strings, but ColdFusion date/time handling code can
recognize them as representing dates and times.
Example

This example displays weather information from a JSON-format data feed that is generated by the example for the S
erializeJSON function. Similar code might consume data that is exported as a JavaScript page. The feed is in the
form of a JavaScript function call where the parameter is a JSON string that contains the feed data. The example
does the following operations:
1. Uses a cfhttp tag to get the feed (in the cfhttp.fileContent variable).
2. Strips the function call wrapper from the text.
3. Uses the IsJSON function to check whether the result of the previous step is a valid JSON format string. If it
is not, it displays a message and stops processing.
4. If the string is valid JSON text, uses the DeserializeJSON function to convert the string to a ColdFusion
variable; in this case, a structure that contains two arrays that represent a ColdFusion query. The first array
has the query column names, the second has the query data.
5. Parses the object and displays the contents of its arrays.
To run this example, put this file and the example for the SerializeJSONfunction in an appropriate location
under your ColdFusion web root, replace the URL with the correct URL for the serialization example, and run
this page.

© 2014 Adobe Systems Incorporated. All rights reserved.

1560

Adobe ColdFusion Documentation








The URL you requested does not provide valid JSON













#cfData.DATA[i][cityIdx]#
Current Temperature: #cfData.DATA[i][tempIdx]#


Forecasts



Day #j#

Outlook: #cfData.DATA[i][fcstIdx][j].WEATHER#

High: #cfData.DATA[i][fcstIdx][j].HIGH#

Low: #cfData.DATA[i][fcstIdx][j].LOW#







© 2014 Adobe Systems Incorporated. All rights reserved.

1561

Adobe ColdFusion Documentation

DirectoryCopy
Description

Copies the contents of a directory to a destination directory.
Returns

Nothing
History

ColdFusion 10: Added this function.
Syntax

directoryCopy (source, destination[ , recurse][, filter])
Properties

Parameter

Description

source

Absolute pathname of directory from which you copy
content.

destination

Path of the destination directory. If not an absolute
path, it is relative to the source directory.

recurse

By default, false. If true, copies the subdirectories.

filter

File extension filter applied, for example, *.cfm.

Example

directoryCopy(sourceDirExists,destDirExists,true,"*.cfm")

© 2014 Adobe Systems Incorporated. All rights reserved.

1562

Adobe ColdFusion Documentation

DirectoryCreate
Description

Creates on-disk or in-memory directory.
Category

System functions
Function Syntax

DirectoryCreate(path)
See Also

DirectoryDelete, DirectoryExists, DirectoryList, DirectoryRename
History

ColdFusion 9: Added this function
Parameters

Parameter

Description

path

Absolute path of the directory to be created.
Alternatively, you can specify IP address, as in the
following example: DirectoryCreate("//12.3.12
3.123/c_drive/test");

Usage

Ensure that you have the required permissions to run this function.
Example

The following code illustrates how to create a directory:

© 2014 Adobe Systems Incorporated. All rights reserved.

1563

Adobe ColdFusion Documentation

DirectoryCreate Example
Enter a directory to create.











Directory #createDirectory# successfully created.

Error Message:#cfcatch.message#

Error Detail:#cfcatch.Detail#





© 2014 Adobe Systems Incorporated. All rights reserved.

1564

Adobe ColdFusion Documentation

DirectoryDelete
Description

Deletes on-disk or in-memory directory.
Category

System functions
Function syntax

DirectoryDelete(path [, recurse])
See also

DirectoryCreate, DirectoryExists, DirectoryList, DirectoryRename
History

ColdFusion 9: Added this function
Parameters

Parameter

Description

path

Absolute path of the directory to be deleted.
Alternatively, you can specify IP address, as in the
following example:
{{DirectoryDelete("//12.3.123.123/c_drive/test"); }}.

recurse

This is an optional parameter and the default value is f
alse.If true, the directory and the sub-directories are
deleted. If the directory (being deleted) has
sub-directories and you set recurse to false, an
exception occurs.

Usage

Ensure that you have the required permissions to run this function.
Example

© 2014 Adobe Systems Incorporated. All rights reserved.

1565

Adobe ColdFusion Documentation

DirectoryDelete Example
Enter a directory to delete.

Directory Path: 


Recurse: 













Directory #delDirectory# has been deleted.

Error Message:#cfcatch.message#

Error Detail:#cfcatch.Detail#





© 2014 Adobe Systems Incorporated. All rights reserved.

1566

Adobe ColdFusion Documentation

DirectoryExists

Description

Determines whether on-disk or in-memory directory exists.
Returns

Yes, if the specified directory exists; No, otherwise.
Category

System functions
Function syntax

DirectoryExists(absolute_path)

See also

DirectoryCreate, DirectoryDelete, DirectoryList, DirectoryRename
Parameters

Parameter

Description

absolute_path

An absolute on-disk or in-memory path. Alternatively,
you can specify IP address as in the following example:
DirectoryExists("//12.3.123.123/c_drive/
test");

Example

© 2014 Adobe Systems Incorporated. All rights reserved.

1567

Adobe ColdFusion Documentation

DirectoryExists Example
Enter a directory to check for existence.











Your directory exists. Directory name: #yourDirectory#


Your directory does not exist.




© 2014 Adobe Systems Incorporated. All rights reserved.

1568

Adobe ColdFusion Documentation

DirectoryList
Description

Lists the contents of on-disk or in-memory directory. Also lists the contents of the sub-directories if recurse is set to
true.
Returns

Contents of the directory based on the parameter listInfo:
If listInfo="query", query object
If listInfo="name", array of names
If listInfo="path", array of path
Category

System functions
Function Syntax

DirectoryList(path [,recurse] [,listInfo] [,filter] [,sort] [,type] )
See Also

DirectoryCreate, DirectoryDelete, DirectoryExists, DirectoryRename
History

ColdFusion 11: Added the type argument.
Parameters

Parameter

Description

path

The absolute path of the directory for which to list the
contents. Alternatively, you can specify IP address as
in the following example: DirectoryList("//12.3.
123.123/c_drive/test");.

recurse

Whether ColdFusion performs the action on
subdirectories: If true, contents of all subdirectories
are also listed.

listInfo

© 2014 Adobe Systems Incorporated. All rights reserved.

name: returns an array of names of files and
directories.
path: returns an array of paths of files and
directories.
query: returns a query.

1569

Adobe ColdFusion Documentation

filter

File extension filter applied to returned names, for
example, *.cfm. Multiple filters can be applied by using
a pipe delimiter. For example: *.beer|*.cookies
Also, you can pass a function in the filter argument:


boolean function
filterBySize(path, type,
extension) {
var sizeLimit = 1024 * 100;
//more than 10 KB
var extensionList =
"jpg,jpeg,gif,png";
if(type is "dir") return false;

if(listFindNoCase(extensionList,ex
tension)) {
var fileInfo =
getFileInfo(path);
var size = fileInfo.size;
if(size >= sizeLimit) return
true;
}
return false;
}
filteredResults =
directorylist(expandPath("."),
true, "path", filterBySize);
writeDump(filteredResults);


The arguments of the passed functions must have:
path: The file path
type: The values (file or dir )
extension: The file extension if any otherwise an
empty string
Additionally, it can also accept the instances of Java Fi
leFilter Objects.

© 2014 Adobe Systems Incorporated. All rights reserved.

1570

Adobe ColdFusion Documentation

sort

Query columns by which to sort a directory listing.
Delimited list of columns from query output.To qualify a
column, use one of the following values:
asc: ascending (a to z) sort order.
dec: descending (z to a) sort order.
For example:sort = "directory ASC, size
DESC, datelastmodified"

type

file: includes only filenames.
dir: includes only directory names.
all: includes both filenames and directory names.

Usage

Ensure that you have the required permissions to run this function.
Example

The following code dumps the contents of a directory:

© 2014 Adobe Systems Incorporated. All rights reserved.

1571

Adobe ColdFusion Documentation

DirectoryList Example
Enter a directory for Listing.

Directory Path: 


Recurse: 


List Info: 

name
path
query



Filter: 















Content of Directory #listDirectory#: 


Error Message:#cfcatch.message#

Error Detail:#cfcatch.Detail#





© 2014 Adobe Systems Incorporated. All rights reserved.

1572

Adobe ColdFusion Documentation

DirectoryRename
Description

Renames on-disk or in-memory directory.
Category

System functions
Function Syntax

DirectoryRename(currentName,newName)
See Also

DirectoryCreate, DirectoryDelete, DirectoryExists, DirectoryList
Usage

Ensure that you have the required permissions to run this function.
History

ColdFusion 9: Added this function
Parameters

Parameter

Description

currentName

Absolute path of the directory to be renamed.
Alternatively, you can specify IP address, for example,
DirectoryRename("//12.3.123.123/c_drive/
test");

newName

Name with which the directory has to be renamed.

Example

© 2014 Adobe Systems Incorporated. All rights reserved.

1573

Adobe ColdFusion Documentation

DirectoryRename Example
Enter a directory to rename.

Directory to rename: 


New Name: 










Directory #renameDirectory# renamed to newName

Error Message:#cfcatch.message#

Error Detail:#cfcatch.Detail#





© 2014 Adobe Systems Incorporated. All rights reserved.

1574

Adobe ColdFusion Documentation

DollarFormat
Description

Formats a string in U.S. format. (For other currencies, use LSCurrencyFormat or LSEuroCurrencyFormat.
Returns

A number as a string, formatted with two decimal places, thousands separator, and dollar sign. If number is
negative, the return value is enclosed in parentheses. If number is an empty string, returns zero.
Category

Display and formatting functions
Function syntax

DollarFormat(number)

See also

DecimalFormat, NumberFormat
Parameters

Parameter

Description

number

Number to format

Example


...
DollarFormat Example






bill #DollarFormat(full)# #DollarFormat(quarter)#
#DollarFormat(half)# #DollarFormat(threefourth)#
18% tip #DollarFormat(full * (18/100))#
#DollarFormat(quarter * (18/100))#
#DollarFormat(half * (18/100))#
#DollarFormat(threefourth * (18/100))#



...

© 2014 Adobe Systems Incorporated. All rights reserved.

1575

Adobe ColdFusion Documentation

DotNetToCFType
Description

Explicitly converts a value returned by a .NET method to the corresponding ColdFusion data type.
Returns

A ColdFusion data value.
Category

Structure functions, System functions
Function syntax

DotNetToCFType(variable_name)

See also

Converting between .NET and ColdFusion data types in Using .NET classes in the Developing ColdFusion
Applications
History

ColdFusion 8: Added this function
Parameters

Parameter

Description

variable_name

Name of the .NET variable to convert

Usage

For detailed information on when and why you use this function, see Working with complex .NET data types in Using
.NET classes in the Developing ColdFusion Applications.
Example

The following example creates a .NET System.Data.DataTable object and converts it to a ColdFusion query.

© 2014 Adobe Systems Incorporated. All rights reserved.

1576

Adobe ColdFusion Documentation











© 2014 Adobe Systems Incorporated. All rights reserved.

1577

Adobe ColdFusion Documentation

Duplicate
Description

Returns a clone, also known as a deep copy, of a variable. There is no reference to the original variable.
Returns

A clone of a variable.
Category

Structure functions, System functions
Function syntax

Duplicate(variable_name)

See also

StructCopy, other Structure functions; Modifying a ColdFusion XML object in the Developing ColdFusion
Applications
History

ColdFusion 8: Changed behavior: this function can duplicate CFCs.
ColdFusion MX: Changed behavior: this function can be used on XML objects.
Parameters

Parameter

Description

variable_name

Name of a variable to duplicate

Usage

Use this function to duplicate complex structures, such as nested structures and queries.When you duplicate a CFC
instance, the entire CFC contents is copied, including the values of the variables in the this scope at the time you
call the Duplicate function. Thereafter, the two CFC instances are independent, and changes to one copy, for
example by calling one of its functions, have no effect on the other copy.
Note
With this function, you cannot duplicate a COM, CORBA, or JAVA object returned from the cfob
ject tag or the CreateObject function. If an array element or structure field is a COM,
CORBA, or JAVA object, you cannot duplicate the array or structure.

Example

© 2014 Adobe Systems Incorporated. All rights reserved.

1578

Adobe ColdFusion Documentation

Duplicate Example








The copy contains the modified value: #copy.nested.item#
The duplicate contains the original value: #clone.nested.item#


#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

1579

Adobe ColdFusion Documentation

Deserialize
Description

Deserializes a String
Returns

A string
Function syntax

deserialize( String StringToBeDeserialized, String type, boolean useCustomSerializer
)

History
ColdFusion 11: Added this function. For more information see REST Enhancements in ColdFusion 11.
Parameters

Parameter

Description

StringToBeDeserialized

A string that needs to be deserialized.

type

String. The type of the data to be deserialized.
ColdFusion by default supports XML and JSON
formats. You can also implement support for other
types in the CustomSerializer CFC. See REST
Enhancements in ColdFusion 11.

useCustomSerializer

Boolean. Whether to use the custom serializer or not.
The default value is true. The custom serializer will be
always used for deserialization. If false, the XML/JSON
deserialization will be done using the default
ColdFusion behavior. If any other type is passed with
useCustomSerializer as false, then
TypeNotSupportedException will be thrown.

For more information on usage, see this document.

© 2014 Adobe Systems Incorporated. All rights reserved.

1580

Adobe ColdFusion Documentation

DeserializeXML
Description

Deserializes a string in XML format to a ColdFusion object.
Returns

Object
Function syntax

deserializeXML( String strToDeserialize, boolean useCustomSerializer )

History

ColdFusion 11: Added this function. For more information see REST Enhancements in ColdFusion 11.
Parameters

Parameter

Description

StringToBeDeserialized

Required. A string that needs to be deserialized.

useCustomSerializer

Boolean. Whether to use the custom serializer or not.
The default value is true. The custom serializer will be
always used for XML deserialization. If false, the
XML/JSON deserialization will be done using the
default ColdFusion behavior. If any other type is
passed with useCustomSerializer as false, then
TypeNotSupportedException will be thrown.

For more information on usage, see this document.

© 2014 Adobe Systems Incorporated. All rights reserved.

1581

Adobe ColdFusion Documentation

Functions e-g
EncodeForCSS
EncodeForHTML
EncodeForHTMLAttribute
EncodeForJavaScript
EncodeForURL
EncodeForXML
EncodeForXMLAttribute
EncodeForXpath
Encrypt
EncryptBinary
EntityDelete
EntityLoad
EntityLoadByExample
EntityLoadByPK
EntityMerge
EntityNew
EntityReload
EntitySave
EntityToQuery
Evaluate
Exp
ExpandPath
FileClose
FileCopy
FileDelete
FileExists
FileGetMimeType
FileIsEOF
FileMove
FileOpen
FileRead
FileReadBinary
FileReadLine
FileSeek
FileSetAccessMode
FileSetAttribute
FileSetLastModified
FileSkipBytes
FileUpload
FileUploadAll
FileWrite
FileWriteLine
Find
FindNoCase
FindOneOf
FirstDayOfMonth
Fix
FormatBaseN
GeneratePBKDFKey
GenerateSecretKey
GetApplicationMetadata

© 2014 Adobe Systems Incorporated. All rights reserved.

1582

Adobe ColdFusion Documentation

GetAuthUser
GetBaseTagData
GetBaseTagList
GetBaseTemplatePath
GetClientVariablesList
GetComponentMetaData
GetContextRoot
GetCPUUsage
GetCurrentTemplatePath
GetDirectoryFromPath
GetEncoding
GetException
GetFileFromPath
GetFileInfo
GetFreeSpace
GetFunctionCalledName
GetFunctionList
GetGatewayHelper
GetHttpRequestData
GetHttpTimeString
GetK2ServerDocCount
GetK2ServerDocCountLimit
GetLocale
GetLocaleDisplayName
GetLocalHostIP
GetMetaData
GetMetricData
GetPageContext
GetPrinterInfo
GetPrinterList
GetProfileSections
GetProfileString
GetReadableImageFormats
GetSafeHTML
GetSOAPRequest
GetSOAPRequestHeader
GetSOAPResponse
GetSOAPResponseHeader
GetSystemFreeMemory
GetSystemTotalMemory
GetTempDirectory
GetTempFile
GetTemplatePath
GetTickCount
GetTimeZoneInfo
GetToken
GetTotalSpace
GetUserRoles
GetVFSMetaData
GetWriteableImageFormats

© 2014 Adobe Systems Incorporated. All rights reserved.

1583

Adobe ColdFusion Documentation

EncodeForCSS
Description

Encodes the input string for use in CSS.
Returns

Encoded string
Category

Display and formatting functions
Syntax

encodeForCSS(inputString [,canonicalize])
See also

EncodeForHTML,EncodeForHTMLAttribute,EncodeForURL,Canonicalize
History

ColdFusion 10: Added this function.
Parameters

Parameter

Description

inputString

Required. The string to encode.

canonicalize

Optional. If set to true, canonicalization happens before
encoding. If set to false, the given input string will just
be encoded. The default value for canonicalize is false.
When this parameter is not specified, canonicalization
will not happen. By default, when canonicalization is
performed, both mixed and multiple encodings will be
allowed. To use any other combinations you should
canonicalize using canonicalize method and then do
encoding.

Example

© 2014 Adobe Systems Incorporated. All rights reserved.

1584

Adobe ColdFusion Documentation










This div element is styled!!!!




Background Color : 





© 2014 Adobe Systems Incorporated. All rights reserved.

1585

Adobe ColdFusion Documentation

EncodeForHTML
Description

Encodes the input string for use in HTML.
Returns

Encoded string
Category

Display and formatting functions
Syntax

encodeForHTML(inputString [,canonicalize])
See also

Canonicalize,EncodeForHTMLAttribute,EncodeForJavaScript,EncodeForCSS,EncodeForURL
History

ColdFusion 10: Added this function.
Parameters

Parameter

Description

inputString

Required. The string to encode.

canonicalize

Optional. If set to true, canonicalization happens before
encoding. If set to false, the given input string will just
be encoded. The default value for canonicalize is false.
When this parameter is not specified, canonicalization
will not happen. By default, when canonicalization is
performed, both mixed and multiple encodings will be
allowed. To use any other combinations you should
canonicalize using canonicalize method and then do
encoding.

Example

© 2014 Adobe Systems Incorporated. All rights reserved.

1586

Adobe ColdFusion Documentation



Output:#encodeForHTML(form.userName)#









© 2014 Adobe Systems Incorporated. All rights reserved.

1587

Adobe ColdFusion Documentation

EncodeForHTMLAttribute
Description

Encodes the input string for use in HTML attribute, such as table width or image height.
Returns

Encoded string
Category

Display and formatting functions
Syntax

encodeForHTMLAttribute(inputString [,canonicalize])
See also

Canonicalize,EncodeForJavaScript,EncodeForCSS,EncodeForURLEncodeForHTML
History

ColdFusion 10: Added this function.
Parameters

Parameter

Description

inputString

Required. The string to encode.

canonicalize

Optional. If set to true, canonicalization happens before
encoding. If set to false, the given input string will just
be encoded. The default value for canonicalize is false.
When this parameter is not specified, canonicalization
will not happen. By default, when canonicalization is
performed, both mixed and multiple encodings will be
allowed. To use any other combinations you should
canonicalize using canonicalize method and then do
encoding.

Example

© 2014 Adobe Systems Incorporated. All rights reserved.

1588

Adobe ColdFusion Documentation








Enter the value in the below text field.









© 2014 Adobe Systems Incorporated. All rights reserved.

1589

Adobe ColdFusion Documentation

EncodeForJavaScript
Description

Encodes the input string for use in JavaScript.
Returns

Encoded string
Category

Display and formatting functions
Syntax

encodeForJavaScript(inputString [,canonicalize])
See also

Canonicalize,EncodeForHTMLAttribute,EncodeForHTML,EncodeForCSS,EncodeForURL
History

ColdFusion 10: Added this function.
Parameters

Parameter

Description

inputString

Required. The string to encode.

canonicalize

Optional. If set to true, canonicalization happens before
encoding. If set to false, the given input string will just
be encoded. The default value for canonicalize is false.
When this parameter is not specified, canonicalization
will not happen. By default, when canonicalization is
performed, both mixed and multiple encodings will be
allowed. To use any other combinations you should
canonicalize using canonicalize method and then do
encoding.

Example

© 2014 Adobe Systems Incorporated. All rights reserved.

1590

Adobe ColdFusion Documentation














© 2014 Adobe Systems Incorporated. All rights reserved.

1591

Adobe ColdFusion Documentation

EncodeForURL
Description

Encodes the input string for use in URLs.
Returns

Encoded string
Category

Display and formatting functions
Syntax

encodeForURL(inputString [,canonicalize])
See also

Canonicalize,EncodeForHTMLAttribute,EncodeForHTML,EncodeForCSS,EncodeForJavaScript
History

ColdFusion 10: Added this function.
Parameters

Parameter

Description

inputString

Required. The string to encode.

canonicalize

Optional. If set to true, canonicalization happens before
encoding. If set to false, the given input string will just
be encoded. The default value for canonicalize is false.
When this parameter is not specified, canonicalization
will not happen. By default, when canonicalization is
performed, both mixed and multiple encodings will be
allowed. To use any other combinations you should
canonicalize using canonicalize method and then do
encoding.

Example

© 2014 Adobe Systems Incorporated. All rights reserved.

1592

Adobe ColdFusion Documentation










LINK to URL: #encodeForURL(form.url)#


© 2014 Adobe Systems Incorporated. All rights reserved.

1593

Adobe ColdFusion Documentation

EncodeForXML
Description

Encodes a string for XML.
Returns

Encoded XML string.
Category

Display and formatting functions.
Function syntax

encodeforXML(Inputstring , [canonicalize])

See also

Canonicalize,EncodeForHTMLAttribute,EncodeForJavaScript,EncodeForCSS,EncodeForURL
History

ColdFusion 10: Added this function.
Parameters

Parameter

Description

inputString

Required. The string to encode.

canonicalize

Optional. If set to true, canonicalization happens before
encoding. If set to false, the given input string will just
be encoded. The default value for canonicalize is false.
When this parameter is not specified, canonicalization
will not happen. By default, when canonicalization is
performed, both mixed and multiple encodings will be
allowed. To use any other combinations you should
canonicalize using canonicalize method and then do
encoding.

Example

© 2014 Adobe Systems Incorporated. All rights reserved.

1594

Adobe ColdFusion Documentation


MyDoc = XmlNew();
MyDoc.xmlRoot = XmlElemNew(MyDoc,"MyRoot");
MyDoc.MyRoot.XmlText = #encodeForXML(form.userName)#;

Output:#encodeForXML(form.userName)#









© 2014 Adobe Systems Incorporated. All rights reserved.

1595

Adobe ColdFusion Documentation

Encrypt
Description

Encrypts a string using a specific algorithm and encoding method.
Returns

String; can be much longer than the original string.
Category

Security functions, String functions
Function syntax

Encrypt(string, key [, algorithm, encoding, IVorSalt, iterations])

See also

Decrypt,EncryptBinary,DecryptBinary
History

ColdFusion 8: Added support for encryption using the RSA BSafe Crypto-J library on Enterprise Edition.
ColdFusion MX 7.01: Added the IVorSalt and iterations parameters.
ColdFusion MX 7: Added the algorithm and encoding parameters.
Parameters

Parameter

Description

string

String to encrypt.

© 2014 Adobe Systems Incorporated. All rights reserved.

1596

Adobe ColdFusion Documentation

key

String. Key or seed used to encrypt the string.
For the CFMX_COMPAT algorithm, any
combination of any number of characters; used
as a seed used to generate a 32-bit encryption
key.
For all other algorithms, a key in the format used
by the algorithm. For these algorithms, use theG
enerateSecretKeyfunction to generate the
key.

algorithm

(Optional) The algorithm to use to encrypt the string.
The Enterprise Edition of ColdFusion installs the RSA
BSafe Crypto-J library, which provides FIPS-140
Compliant Strong Cryptography. It includes the
following algorithms:
AES: the Advanced Encryption Standard
specified by the National Institute of Standards
and Technology (NIST) FIPS-197.
DES: the Data Encryption Standard algorithm
defined by NIST FIPS-46-3.
DES-EDE: the "Triple DES" algorithm defined by
NIST FIPS-46-3.
DESX: The extended Data Encryption Standard
symmetric encryption algorithm.
RC2: The RC2 block symmetric encryption
algorithm defined by RFC 2268.
RC4: The RC4 symmetric encryption algorithm.
RC5: The RC5 encryption algorithm.
PBE: Password-based encryption algorithm
defined in PKCS #5.
In addition to these algorithms, you can use the
algorithms provided in the Standard Edition of
ColdFusion.

© 2014 Adobe Systems Incorporated. All rights reserved.

1597

Adobe ColdFusion Documentation

The Standard Edition of ColdFusion installs a
cryptography library with the following algorithms:
CFMX_COMPAT: the algorithm used in
ColdFusion MX and prior releases. This
algorithm is the least secure option (default).
AES: the Advanced Encryption Standard
specified by the National Institute of Standards
and Technology (NIST) FIPS-197.
BLOWFISH: the Blowfish algorithm defined by
Bruce Schneier.
DES: the Data Encryption Standard algorithm
defined by NIST FIPS-46-3.
DESEDE: the "Triple DES" algorithm defined by
NIST FIPS-46-3.
If you install a security provider with additional
cryptography algorithms, you can also specify any of its
string encryption and decryption algorithms.
encoding

(Optional; if you specify this parameter, also specify the
algorithm parameter). The binary encoding in which to
represent the data as a string.
Base64: the Base64 algorithm, as specified by
IETF RFC 2045.
Hex: the characters A-F0-9 represent the
hexadecimal byte values.
UU: the UUEncode algorithm (default).

IVorSalt

(Optional) Specify this parameter to adjust ColdFusion
encryption to match the details of other encryption
software. If you specify this parameter, also specify the
algorithmparameter.
For Block Encryption algorithms: This is the
binary Initialization Vector value to use with the
algorithm. The algorithm must contain a
Feedback Mode other than ECB. This must be a
binary value that is exactly the same size as the
algorithm block size. Use the same value in theD
ecryptfunction to successfully decrypt the data.
For Password Based Encryption algorithms: This
is the binary Salt value to transform the
password into a key. The same value must be
used to decrypt the data.

© 2014 Adobe Systems Incorporated. All rights reserved.

1598

Adobe ColdFusion Documentation

iterations

(Optional) The number of iterations to transform the
password into a binary key. Specify this parameter to
adjust ColdFusion encryption to match the details of
other encryption software. If you specify this parameter,
also specify the algorithm parameter with a Password
Based Encryption (PBE) algorithm. Do not specify this
parameter for Block Encryption algorithms. Use the
same value to encrypt and decrypt the data.

Usage

This function uses a symmetric key-based algorithm, in which the same key is used to encrypt and decrypt a string.
The security of the encrypted string depends on maintaining the secrecy of the key.
The following are the FIPS-140 approved algorithms included in the RSA BSafe Crypto-J library that are used by
ColdFusion. Some of these are not used with the encrypt function, but are used with other functions:
AES – ECB, CBC, CFB (128), OFB (128) – [128, 192, 256-bit key sizes]
AES – CTR
Diffie-Hellman Key Agreement
DSA
FIPS 186-2 General Purpose [(x-Change Notice); (SHA-1)]
FIPS 186-2 [(x-Change Notice); (SHA-1)]
HMAC-SHAx (where x is 1, 224, 256, 384, or 512)
RSA PKCS#1 v1.5 (sign, verify) (SHA-1,SHA-224,SHA-256,SHA-384,SHA-512)
Secure Hash Standard (SHA-1, SHA-224, SHA-256, SHA-384, SHA-512)
Triple DES - ECB, CBC, CFB (64 bit), and OFB (64 bit)
All algorithms included in the RSA BSafe Crypto-J library are available for use in the Enterprise Edition. In certain
cases, you may want to disable some algorithms. To disable the DESX, RC5, and MD5PRNG algorithms, specify
the following in the JVM arguments on the Java and JVM page of the ColdFusion Administrator:

-Dcoldfusion.enablefipscrypto=true

FIPS-140 approved cryptography is not available if you are running ColdFusion on WebSphere of JBoss.
To use the IBM/Lotus Sametime Instant Messaging Gateway in the Enterprise edition, disable the FIPS-140-only
cryptography setting by specifying the following in the JVM arguments on the Java and JVM page of the ColdFusion
Administrator:

© 2014 Adobe Systems Incorporated. All rights reserved.

1599

Adobe ColdFusion Documentation

-Dcoldfusion.disablejsafe=true

In Standard Edition, for all algorithms except the default algorithm, ColdFusion uses the Java Cryptography
Extension (JCE) and installs a Sun Java runtime that includes the Sun JCE default security provider. This provider
includes the algorithms listed in the Parameters section. The JCE framework includes facilities for using other
provider implementations; however, Adobe cannot provide technical support for third-party security providers.
The default algorithm, which is the same one used in ColdFusion 5 and ColdFusion MX, uses an XOR-based
algorithm that uses a pseudo-random 32-bit key, based on a seed passed by the user as a function parameter. This
algorithm is less secure than the other available algorithms.
Example

The following example encrypts and decrypts a text string. It lets you specify the encryption algorithm and encoding
technique. It also has a field for a key seed to use with the CFMX_COMPAT algorithm. For all other algorithms, it
generates a secret key.

© 2014 Adobe Systems Incorporated. All rights reserved.

1600

Adobe ColdFusion Documentation

Encrypt Example



/* GenerateSecretKey does not generate key for the CFMX_COMPAT algorithm,
so use the key from the form.
*/
if (Form.myAlgorithm EQ "CFMX_COMPAT")
theKey=Form.MyKey;
// For all other encryption techniques, generate a secret key.
else
theKey=generateSecretKey(Form.myAlgorithm);
//Encrypt the string
encrypted=encrypt(Form.myString, theKey, Form.myAlgorithm,
Form.myEncoding);
//Decrypt it
decrypted=decrypt(encrypted, theKey, Form.myAlgorithm, Form.myEncoding);



The algorithm: #Form.myAlgorithm#

The key: #theKey#



The string: #Form.myString# 



Encrypted: #encrypted#



Decrypted: #decrypted#





Select the encoding


UU
Base64
Hex




Select the algorithm


CFMX_COMPAT
AES
DES
DESEDE




Input your key (used for CFMX_COMPAT encryption only)





Enter string to encrypt

This string
will be encrypted (you can replace it with more typing).





© 2014 Adobe Systems Incorporated. All rights reserved.

1601

Adobe ColdFusion Documentation

© 2014 Adobe Systems Incorporated. All rights reserved.

1602

Adobe ColdFusion Documentation

GetTempDirectory
Description

Gets the path of the directory that ColdFusion uses for temporary files. The directory depends on the account under
which ColdFusion is running and other factors. Before using this function in an application, test to determine the
directory it returns under your account.
Returns

The absolute pathname of a directory, including a trailing slash, as a string.
Category

System functions
Function syntax

GetTempDirectory()
See also

GetTempFile
History

ColdFusion MX: Changed behavior: on Windows, this function now returns the temporary directory of the embedded
Java application server. On other platforms, it returns the temporary directory of the operating system.
Example

GetTempDirectory Example
The temporary directory for this ColdFusion server is
#GetTempDirectory()#.
We have created a temporary file called:
#GetTempFile(GetTempDirectory(),"testFile")#

© 2014 Adobe Systems Incorporated. All rights reserved.

1603

Adobe ColdFusion Documentation

GetApplicationMetadata
Description

Returns the application settings that you have specified in the application, either in the Application.cfc or
Application.cfm. For details, see Application Variables section in CFML Reference.
If you have turned on Enable Global Script Protection in ColdFusion Administrator (Server
Settings > Settings), the value returned is the default scopes protected (form, URL, CGI,
or Cookie). If you specify an invalid value, none, or if Enable Global Script Protection is
turned off in ColdFusion Administrator, none is returned.
If you have specified memory limit for VFS in ColdFusion Administrator and if Memory
Limit per Application for In-Memory Virtual File System (Server Settings > Settings) has a
value lesser than what you have specified in the Application.cfc (this.inmemoryfiles
ystem.size), then the returned value is the one specified in the ColdFusion
Administrator and not the Application.cfc.
If ColdFusion does not find the Application.cfc/Application.cfm ColdFusion searches for
the application in the order in which you have set Application.cfm/Application.cfc look up
order (ColdFusion Administrator > Settings > Server Settings). If no application is found,
an empty struct is returned.

Returns

A struct that contains application settings such as name, sessionManagement, or invokeImplicitAccessor.
Category

Other functions
Syntax

getApplicationMetadata()
Example

The example shows how you can access application settings in the CFM using the function getApplicationMeta
data:
Application.cfc

© 2014 Adobe Systems Incorporated. All rights reserved.

1604

Adobe ColdFusion Documentation

component
{
this.name = "myapp";
this.applicationtimeout = createtimespan(0, 0, 0, 10);
this.sessiontimeout = createtimespan(0, 0, 0, 10);
this.sessionmanagement = true;
this.clientmanagement = true;
this.datasource = "cfartgallery";
this.ormenabled = true;
this.secureJSON = true;
this.secureJSONPrefix = "///";
this.setClientCookies = true;
this.setDomainCookies = true;
this.setClientStorage = "Registry";
this.setLoginStorage = "Cookies";
this.scriptProtect = "all";
this.mappings["mymapping"] = getdirectoryfrompath(cgi.cf_template_path);
this.customTagPaths = "path1,path2,path3";
this.invokeImplicitAccessor = true;
this.inmemoryfilesystem.enabled = true;
this.inmemoryfilesystem.size = 10;
}

AppMetaData.cfm


writedump(getApplicationMetadata());


© 2014 Adobe Systems Incorporated. All rights reserved.

1605

Adobe ColdFusion Documentation

EncryptBinary
Description

Encrypts binary data using a specific algorithm and encoding method.
Returns

Binary data.
Category

Security functions, String functions
Function syntax

EncryptBinary(bytes, key [, algorithm, IVorSalt, iterations])

See also

Decrypt, DecryptBinary, Encrypt
History

ColdFusion 8: Added support for encryption using the RSA BSafe Crypto-J library on Enterprise Edition.
ColdFusion MX 7.01: Added this function.
Parameters

Parameter

Description

bytes

Binary data to encrypt.

key

String. Key or seed used to encrypt the string.
For the CFMX_COMPAT algorithm, any combination
of any number of characters; used as a seed used to
generate a 32-bit encryption key.
For all other algorithms, a key in the format used by
the algorithm. For these algorithms, use the Genera
teSecretKey function to generate the key.

© 2014 Adobe Systems Incorporated. All rights reserved.

1606

Adobe ColdFusion Documentation

algorithm

(Optional) The algorithm to use to decrypt the
string.The Enterprise Edition of ColdFusion installs the
RSA BSafe Crypto-J library, which provides FIPS-140
Compliant Strong Cryptography. For a list of
algorithms, see the Encrypt function.The Standard
Edition of ColdFusion installs a cryptography library
with the following algorithms:
CFMX_COMPAT: the algorithm used in ColdFusion
MX and prior releases. This algorithm is the least
secure option (default).
AES: the Advanced Encryption Standard specified by
the National Institute of Standards and Technology
(NIST) FIPS-197.
BLOWFISH: the Blowfish algorithm defined by Bruce
Schneier.
DES: the Data Encryption Standard algorithm
defined by NIST FIPS-46-3.
DESEDE: the "Triple DES" algorithm defined by
NIST FIPS-46-3.
If you install a security provider with additional
cryptography algorithms, you can also specify any of
its string encryption and decryption algorithms.

IVorSalt

(Optional) Specify this parameter to adjust ColdFusion
encryption to match the details of other encryption
software. If you specify this parameter, also specify the
algorithm parameter.
For Block Encryption algorithms: This is the binary
Initialization Vector value to use with the algorithm.
The algorithm must contain a Feedback Mode other
than ECB. This must be a binary value that is exactly
the same size as the algorithm block size. Use the
same value in the Decrypt function to successfully
decrypt the data.
For Password Based Encryption algorithms: This is
the binary Salt value to transform the password into a
key. The same value must be used to decrypt the
data.

iterations

(Optional) The number of iterations to transform the
password into a binary key. Specify this parameter to
adjust ColdFusion encryption to match the details of
other encryption software. If you specify this parameter,
also specify the algorithm parameter with a
Password Based Encryption (PBE) algorithm. Do not
specify this parameter for Block Encryption algorithms.
Use the same value to encrypt and decrypt the data.

Usage

© 2014 Adobe Systems Incorporated. All rights reserved.

1607

Adobe ColdFusion Documentation

This function uses a symmetric key-based algorithm, in which the same key is used to encrypt and decrypt binary
data. The security of the encrypted data depends on maintaining the secrecy of the key. For all algorithms except
the default algorithm, ColdFusion uses the Java Cryptography Extension (JCE) and installs a Sun Java runtime that
includes the Sun JCE default security provider. This provider includes the algorithms listed in the Parameters
section. The JCE framework includes facilities for using other provider implementations; however, Adobe cannot
provide technical support for third-party security providers.The default algorithm, which is the same as was used in
ColdFusion 5 and ColdFusion MX, uses an XOR-based algorithm that uses a pseudo-random 32-bit key, based on a
seed passed by the user as a function parameter. This algorithm is less secure than the other available algorithms.
Example

The following example encrypts and decrypts binary data. It encrypts the binary data contained in a file and then
decrypts the encrypted file. It lets you specify the encryption algorithm and encoding technique. It also has a field for
a key seed to use with the CFMX_COMPAT algorithm. For all other algorithms, it generates a secret key.

© 2014 Adobe Systems Incorporated. All rights reserved.

1608

Adobe ColdFusion Documentation

EncryptBinary Example




/* GenerateSecretKey does not generate key for the CFMX_COMPAT algorithm,
so use the key from the form.
*/
if (Form.myAlgorithm EQ "CFMX_COMPAT")
theKey=Form.MyKey;
// For all other encryption techniques, generate a secret key.
else
theKey=generateSecretKey(Form.myAlgorithm);
//Encrypt the string
encrypted=encryptBinary(myData, theKey, Form.myAlgorithm);
//Decrypt it
decrypted=decryptBinary(encrypted, theKey, Form.myAlgorithm);







The algorithm: #Form.myAlgorithm#

The key: #theKey#



The InputFile: #Form.myfile# 



Encrypted: #encfile#



Decrypted: #decfile#





Select the algorithm


CFMX_COMPAT
AES
DES
DESEDE




Input your key (used for CFMX_COMPAT encryption only)





Enter filename to encrypt






© 2014 Adobe Systems Incorporated. All rights reserved.

1609

Adobe ColdFusion Documentation

EntityDelete
Description

Deletes the record from the database for the specified entity. Depending on the cascade attribute specified in the
mapping, it deletes the associated objects also.
Category

ORM functions
Function Syntax

EntityDelete(entity)

See Also

EntityLoad, EntitySave
History

ColdFusion 9: Added this function.
Parameters

Parameter

Description

entity

Name of the entity being deleted.

Example


EntityDelete(employee)>
employee = CreateObject('component', 'employee')>
employee.setEmployeeID(100)>
EntityDelete(employee)>

© 2014 Adobe Systems Incorporated. All rights reserved.

1610

Adobe ColdFusion Documentation

EntityLoad
Description

Loads and returns an array of entities for the specified entity name. You can also specify a filter criteria and sort
order. All EntityLoad methods take the entity name as input.
Returns

Array (if unique=false)Single entity (if unique=true)
Category

ORM functions
Function syntax

EntityLoad (entityname)
EntityLoad (entityname, id [, unique])
EntityLoad (entityname, filtercriteria [,unique]
EntityLoad(entityname, filtercriteria, sortorder [, options])

See Also

EntityLoadByExample, EntityReload, EntityDelete
Parameters

Parameter

Description

entity name

Name of the entity to be loaded.

ID

The primary key value of the entity that must be loaded.
If the entity has a composite key, then the id has to be
specified as key-value pairs (ColdFusion struct).

unique

If unique is set to true, then the entity is returned. If
you are sure that only one record exists that matches
this filtercriteria, then you can specify unique=
true, so that a single entity is returned instead of an
array. If you set unique=true and multiple records
are returned, then an exception occurs.

filtercriteria

Key-value pair (ColdFusion Struct) of property names
and values. If there are more than one key-value pair,
then the AND operator is used.
If specified, loads and returns an array of entities of the
specified entity name that matches the filtercriteria.

© 2014 Adobe Systems Incorporated. All rights reserved.

1611

Adobe ColdFusion Documentation

sortorder

String used to specify the sortorder of the entities that
are returned.
If specified, loads and returns an array of entities that
satisfy the filtercriteria sorted as specified by
the sortorder.

options

The following options to customize the output:
ignorecase: Ignores the case of sort order when
set to true. Use only if you specify the sortorder
parameter.
offset: Specifies the position from which to retrieve
the objects.
maxResults: Specifies the maximum number of
objects to be retrieved.
cacheable: Whether the result has to be cached in
the secondary cache. Default is false.
cachename: Name of the cache in secondary cache.
timeout: Specifies the timeout value (in seconds)
for the query.

History

ColdFusion 9: Added this function.
Usage

For pagination, you can use the options offset and maxResults as shown in the example:

EntityLoad('employee', {department='qa'} , {offset=21, maxResults=10})

This example retrieves the (next) 10 objects of employees whose department is qa from offset 22.
Example

Example with only entity name specified:



Example with EntityName, id, and unique set to true. Instead of true, if you set unique as false, then array
is returned with one entity.


Entity name, composite key.


© 2014 Adobe Systems Incorporated. All rights reserved.

1612

Adobe ColdFusion Documentation

Example which describes how to retrieve objects whose country is UK, and sorted by Department ascending and A
ge descending:



Example that describes how to retrieve details of all the employees who live in 'UK':



Example that describes how to retrieve a unique object. If you specify unique= "true" and more than one object
satisfies the condition, then an exception occurs.



© 2014 Adobe Systems Incorporated. All rights reserved.

1613

Adobe ColdFusion Documentation

EntityLoadByExample
Description

Loads and returns an array of objects that match the sampleentity.The filter criteria is constructed by ANDing all
the non-null properties of the sampleentity.
Returns

Array of objects
Category

ORM functions
Function Syntax

entityloadbyexample(sampleentity [, unique])

See Also

EntityLoad, EntityReload
History

ColdFusion 9: Added this function.
Parameters

Parameter

Description

sampleentity

Name of the sample entity that is used to match and
filter similar entities to load.

Example


employee.setDepartment("ColdFusion")>
employee.setCountry("USA")>
employee=EntityLoadByExample(employee)>

© 2014 Adobe Systems Incorporated. All rights reserved.

1614

Adobe ColdFusion Documentation

EntityLoadByPK
Description

Loads and returns an array of objects for the specified primary key. Use this function to avoid specifying the boolean
parameter that you must specify with the EntityLoad() function.
Returns

object
Category

ORM functions
Function Syntax

entityLoadByPK( entityName ,id)

Parameters

Parameter

Description

entity name

Name of the entity to be loaded.

id

Primary key id

See Also

EntityLoad, EntityReload, EntityLoadByExample, EntityDelete, ColdFusion ORM chapter in Developin
g ColdFusion Applications
History

ColdFusion 9: Added this function.
Example


art = EntityLoadByPK("Art", 1);
writedump(art);


© 2014 Adobe Systems Incorporated. All rights reserved.

1615

Adobe ColdFusion Documentation

EntityMerge
Description

Attaches the specified entity to the current ORM session. It copies the state of the given object onto the persistent
object with the same identifier and returns the persistent object. If there is no persistent instance currently
associated with the session, it is loaded. The given instance is not associated with the session. User have to use the
returned object from this session.
Returns

object
Category

ORM functions
Function Syntax

entityMerge( entity)

Parameters

Parameter

Description

entity

The entity that must be attached to the ORM session.

See Also

EntityLoad, EntityLoadByExample, EntityDelete, ColdFusion ORM chapter in Developing ColdFusion
Applications
History

ColdFusion 9: Added this function.

© 2014 Adobe Systems Incorporated. All rights reserved.

1616

Adobe ColdFusion Documentation

EntityNew
Note
This function has been enhanced in ColdFusion 9.0.1 to support multiple data sources in the
same application. Install the ColdFusion 9 update to use the feature.

Description

Creates an instance of the persistent CFC with the entity name that you provide.
Returns

Object
Category

ORM functions
Function Syntax

entityNew(entityName [ ,properties])
Parameters

Parameter

Description

entityName

Entity name of the persistent CFC.

properties

Key-value pair (ColdFusion struct) of property names
and values.

See Also

EntityLoad, EntityLoadByExample, EntityDelete, ColdFusion ORM chapter in Developing ColdFusion
Applications
History

ColdFusion 9: Added this function.
Usage

The enhancement in ColdFusion 9.0.1 allows the application to initialize the object that is being created. properti
es takes a struct with key being the property name. When the object is created, all the properties are populated with
the passed struct.For example,

cfset artistObj = entityNew("Artists",{FirstName="Tom",LastName="Ron"})>

Example

© 2014 Adobe Systems Incorporated. All rights reserved.

1617

Adobe ColdFusion Documentation

newArtistObj = EntityNew("Artists");
newArtistObj.setfirstname("John");
newArtistObj.setlastname("Smith");
newArtistObj.setaddress("5 Newport lane");
newArtistObj.setcity("San Francisco");
newArtistObj.setstate("CA");
newArtistObj.setPostalCode("90012");
newArtistObj.setphone("612-832-2343");
newArtistObj.setfax("612-832-2344");
newArtistObj.setemail("jsmith@company.com");
newArtistObj.setThePassword("jsmith");
EntitySave(newartistobj);
ormflush();

© 2014 Adobe Systems Incorporated. All rights reserved.

1618

Adobe ColdFusion Documentation

EntityReload
Description

Reloads data for an entity that is already loaded. This method refetches data from the database and repopulates the
entity with the refreshed data.
Category

ORM functions
Function Syntax

entityreload()

See Also

EntityLoad, EntityLoadByExample, EntityDelete
History

ColdFusion 9: Added this function.

© 2014 Adobe Systems Incorporated. All rights reserved.

1619

Adobe ColdFusion Documentation

EntitySave
Description

Saves or updates data of the entity and all related entities to the database. ColdFusion automatically tries to find if a
new record should be inserted or an existing record be updated for the given entity. If you set forceinsert=true,
then ColdFusion tries to insert the entity as a new record.
Returns

Void
Category

ORM functions
Function Syntax

EntitySave(entity, [forceinsert])

See Also

EntityLoad, EntityLoadByExample, EntityDelete
History

ColdFusion 9: Added this function.
Parameters

Parameter

Description

entity

Name of the entity that must be saved in the database.

forceinsert

If true, then ColdFusion always tries to insert the entity
as a new record.

Example

To save an entity:


employee.setFirstName("Marcia")>
employee.setlastName("Em")>
EntitySave(employee)>

To update an entity:

© 2014 Adobe Systems Incorporated. All rights reserved.

1620

Adobe ColdFusion Documentation





© 2014 Adobe Systems Incorporated. All rights reserved.

1621

Adobe ColdFusion Documentation

EntityToQuery
Description

Converts the input entity object or the input array of entity objects to a query object.
Returns

Query
Category

ORM functions
Function Syntax

EntityToQuery (orm_object, [entity_name])
EntityToQuery (orm_object_array, [entity_name])

Parameter

Parameter

Description

orm_object

Entity object that needs to be converted to a query
object.

orm_object_array

Array that needs to be converted to a query object.

entity_name

Name of the entity. Use this optional parameter to
return the query of the given entity in the case of
inheritance mapping.

See Also

EntityLoad, EntityDelete
History

ColdFusion 9: Added this function.
Usage

The following conditions apply for this function:
In the case of array input, all objects in the array must be of the same type.
The result query will not contain any relation data.
Example

© 2014 Adobe Systems Incorporated. All rights reserved.

1622

Adobe ColdFusion Documentation




© 2014 Adobe Systems Incorporated. All rights reserved.

1623

Adobe ColdFusion Documentation

Evaluate
Description

Evaluates one or more string expressions, dynamically, from left to right. (The results of an evaluation on the left can
have meaning in an expression to the right.) Returns the result of evaluating the rightmost expression.
Returns

An object; the result of the evaluations.
Category

Dynamic evaluation functions
Function syntax

Evaluate(string_expression1 [, string_expression2 , … ])

See also

DE, IIf, PrecisionEvaluate, Using Expressions and Number Signs in the Developing ColdFusion Applications
Parameters

Parameter

Description

string_expression1, string_expression2...

Expressions to evaluate

Usage

String expressions can be complex. If a string expression contains a single- or double-quotation mark, the mark
must be escaped.This function is useful for forming one variable from multiple variables. For example, to reference a
column of the query qNames with a variable, var, using an index value to traverse rows, you could use the following
code:



Example

© 2014 Adobe Systems Incorporated. All rights reserved.

1624

Adobe ColdFusion Documentation


Evaluate Example






The value of the expression #Evaluate(DE(FORM.MyExpression))#
is #theExpression#.


The value of the expression #FORM.MyExpression#
is #theExpression#.



Could not evaluate the expression #Form.myExpression#.

Make sure you enter a valid ColdFusion Expression.





Enter a ColdFusion expression for evaluation







© 2014 Adobe Systems Incorporated. All rights reserved.

1625

Adobe ColdFusion Documentation

Exp
Description

Calculates the exponent whose base is e that represents number. The constant e equals 2.71828182845904, the
base of the natural logarithm. This function is the inverse of Log, the natural logarithm of number.
Returns

The constant e, raised to the power of number.
Category

Mathematical functions
Function syntax

Exp(number)

See also

Log, Log10
Parameters

Parameter

Description

number

Exponent to apply to the base e

Usage

To calculate powers of other bases, use the exponentiation operator (^).
Example

© 2014 Adobe Systems Incorporated. All rights reserved.

1626

Adobe ColdFusion Documentation

Exp Example


Your number, #FORM.number#

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


You must enter a positive real number to see its natural logarithm


The natural logarithm of #FORM.number#: #log(FORM.number)#



You must enter a positive real number to see its logarithm to base 10


The logarithm of #FORM.number# to base 10: #log10(FORM.number)#




Enter a number to see its value raised to the E power, its natural logarithm,
and the logarithm of number to base 10.




© 2014 Adobe Systems Incorporated. All rights reserved.

1627

Adobe ColdFusion Documentation

ExpandPath
Description

Creates an absolute, platform-appropriate path that is equivalent to the value of relative_path, appended to the base
path. This function (despite its name) can accept an absolute or relative path in the relative_path parameterThe
base path is the currently executing page’s directory path. It is stored in pageContext.getServletContext().
Returns

A string. If the relative path contains a trailing forward slash or backward slash, the return value contains the same
trailing character.
Category

System functions
Function syntax

ExpandPath(relative_path)

See also

FileExists, GetCurrentTemplatePath, GetFileFromPath
History

ColdFusion MX: Changed behavior for the relative_path parameter: this function can now accept an absolute or
relative path in the relative_path parameter. To resolve a path, this function uses virtual mappings that are defined in
the ColdFusion Administrator. This function does not reliably use virtual mappings that are defined in IIS, Apache, or
other web servers.
Parameters

Parameter

Description

relative_path

Relative or absolute directory reference or filename,
within the current directory, (.\ and ..) to convert to an
absolute path. Can include forward or backward
slashes.Files in the custom tag directory are also
resolved. For instance, if there is a file test.txt in the
custom tag directory (C:\Zeus), the function (with
\test.txt) returns C:\Zeus\test.txt.

Usage

If the parameter or the returned path is invalid, the function throws an error. You cannot use this function with
in-memory files.These examples show the valid constructions of relative_path:
ExpandPath( "*.*")
ExpandPath( "/")
ExpandPath( "\")

© 2014 Adobe Systems Incorporated. All rights reserved.

1628

Adobe ColdFusion Documentation

ExpandPath(
ExpandPath(
ExpandPath(
ExpandPath(
ExpandPath(

"/mycfpage.cfm")
"mycfpage.cfm")
"myDir/mycfpage.cfm")
"/myDir/mycfpage.cfm")
"../../mycfpage.cfm")

Enhancement in ColdFusion 10 lets files in the custom tag directory to also resolve. For instance, if there is a file
test.txt in the custom tag directory (C:\Zeus), the function (with \test.txt) returns C:\Zeus\test.txt.
Example

ExpandPath Example



The current directory is: #GetDirectoryFromPath(thisPath)#



Your file exists in this directory. You entered
the correct filename, #GetFileFromPath("#thisPath#/#yourfile#")#

Your file was not found in this directory:

Here is a list of the other files in this directory:











Enter the name of a file in this directory 
(try expandpath.cfm)




© 2014 Adobe Systems Incorporated. All rights reserved.

1629

Adobe ColdFusion Documentation

FileClose
Description

Closes an on-disk or in-memory file that is open. When you use the FileOpen function, ColdFusion returns a
handle to a file object.When you close the file, the handle is still available; however, it lists the file as closed.
Category

System functions
Function syntax

FileClose(fileObj)

See also

FileCopy, FileIsEOF, FileOpen, FileRead, FileReadLine, FileWrite
History

ColdFusion 8: Added this function.
Parameters

Parameter

Description

fileobj

The file to close.

Usage

Always close a file after opening it. When you use the FileOpen function to open a file, the file stream is opened
and contents are read from or written to it. The FileClose function closes the stream. If you do not close a file, the
stream remains open; in that case, the operating system can lock the file, which results in the file not being usable
until the server is restarted.
Example

The following example checks to see if a file is still open and closes it.

© 2014 Adobe Systems Incorporated. All rights reserved.

1630

Adobe ColdFusion Documentation


myfile = FileOpen("c:\ColdFusion9\wwwroot\test1.txt", "read");
while(NOT FileIsEOF(myfile))
{
x = FileReadLine(myfile);
WriteOutput("#x# 
");
}



The file #myfile.filepath# is #myfile.status#


FileClose(myfile);



© 2014 Adobe Systems Incorporated. All rights reserved.

1631

Adobe ColdFusion Documentation

FileCopy
Description

Copies the specified on-disk or in-memory source file to the specified destination file.
Category

System functions
Function syntax

FileCopy(source, destination)

See also

FileClose, FileIsEOF, FileOpen, FileRead, FileReadLine, FileWrite, cffile
History

ColdFusion 8: Added this function.
Parameters

Parameter

Description

source

Pathname of the on-disk or in-memory file to copy. If
not an absolute path (starting with a drive letter and a
colon, or a forward or backward slash), it is relative to
the ColdFusion temporary directory, which is returned
by the getTempDirectory function.

destination

Pathname of an on-disk or in-memory directory or file
on the web server where the file is copied. If you
specify a filename without a directory path, ColdFusion
copies it relative to the source directory.

Usage

Use the following syntax to specify an in-memory file or directory, which is not written to disk. In-memory files speed
processing of transient data.

ram:///filepath

The filepath can include directories, for example ram:///petStore/images/poodle.jpg. Create the directories
in the path before you specify the file. For more information on using in-memory files, see Working with in-memory
files in the Developing ColdFusion Applications.
Example

© 2014 Adobe Systems Incorporated. All rights reserved.

1632

Adobe ColdFusion Documentation

The following example copies the test1.txt file from the c:\testingdir\ directory to the c:\productiondir\ directory in
Windows and names the new copy of the file test2.txt:

FileCopy Example




A copy of #destinationfile# already exists.


FileCopy(#sourcefile#, #destinationfile#);

Copied: #sourcefile# 

To: #destinationfile#



The source file does not exist.



© 2014 Adobe Systems Incorporated. All rights reserved.

1633

Adobe ColdFusion Documentation

FileDelete
Description

Deletes the specified on-disk or in-memory file on the server.
Category

System functions
Function syntax

FileDelete(filepath)

See also

FileClose, FileIsEOF, FileOpen, FileRead, FileReadLine, FileWrite, cffile
History

ColdFusion 8: Added this function.
Parameters

Parameter

Description

filepath

Pathname of the on-disk or in-memory file to delete. If
not an absolute path (starting with a drive letter and a
colon, or a forward or backward slash), it is relative to
the ColdFusion temporary directory, which is returned
by the getTempDirectory function.

Usage

Use this function to free the memory used by an in-memory file. For more information on using in-memory files, see
Working with in-memory files in the Developing ColdFusion Applications.
Example

The following example deletes the file c:\productiondir\test1.txt before moving c:\testdir\test1.txt:

© 2014 Adobe Systems Incorporated. All rights reserved.

1634

Adobe ColdFusion Documentation

FileDelete Example




The destination file already exists.

Deleting previous copy of #destinationfile#.

Moving: #sourcefile# 

To: 
 #destinationfile#.


FileDelete(#destinationfile#);
FileMove(#sourcefile#, #destinationfile#);



FileMove(#sourcefile#, #destinationfile#);

Moved: #sourcefile# 

To: 
 #destinationfile#.



The source file does not exist.



© 2014 Adobe Systems Incorporated. All rights reserved.

1635

Adobe ColdFusion Documentation

FileExists
Description

Determines whether an on-disk or in-memory file exists.
Returns

Yes, if the file specified in the parameter exists; No, otherwise.
Category

System functions, Decision functions
Function syntax

FileExists(absolute_path)

See also

DirectoryExists, ExpandPath, GetTemplatePath
Parameters

Parameter

Description

absolute_path

The absolute path of the on-disk or in-memory file.

Usage

To access a file on a remote system, the account (for Windows) or user (for UNIX and Linux) that is running
ColdFusion must have permission to access the file, directory, and remote system. For example, if you run
ColdFusion in the Server Configuration as a Windows service, by default it runs under the local system account,
which does not have sufficient privileges to access remote systems. You can change this, however, on the Log On
page of the Services Properties dialog box.
Example

© 2014 Adobe Systems Incorporated. All rights reserved.

1636

Adobe ColdFusion Documentation

FileExists Example



The current directory is: #GetDirectoryFromPath(thisPath)#




Your file exists in this directory. You entered
the correct filename, #GetFileFromPath("#thisPath#/#yourfile#")#


© 2014 Adobe Systems Incorporated. All rights reserved.

1637

Adobe ColdFusion Documentation

FileGetMimeType
Description

Gets the MIME type for the file path/file object you have specified.
Returns

Returns MIME type.
Syntax

{{fileGetMimeType(path, strict)
fileGetMimeType(fileObject,strict)}}
Parameters

Parameter

Description

path

Full path on disk to the file if strict is set to true.
If you do not specify the full path, the file is assumed to
be present in the temp directory, as returned by the
function getTempDirectory.

fileObject

Name of the file object.

strict

If false, determines the file type by extension. The
default value is true.

Example

Assume that you have a file named test.pdf in /folder1 and test.txt in the same folder, and you want to check the
MIME type. Here test.txt is a copy of test.pdf with extension renamed to txt.


//Case 1.
mime.mimeType1 =
//Case 2.
mime.mimeType2 =
//Case 3.
mime.mimeType3 =
//Case 4.
mime.mimeType4 =
writeDump(mime);


FilegetMimeType(expandPath(‘/folder1/test.pdf’));
FilegetMimeType(expandPath(‘/folder1/test.pdf’),false);
FilegetMimeType(expandPath(‘/folder1/test.txt’));
FilegetMimeType(expandPath(‘/folder1/test.txt’),false);

Case 1 and Case 2: Returns application/pdf no matter if strict = true or false because the file is
originally a PDF file.
Case 3: Returns application/pdf since by default{{ strict = true}} and the file is originally a PDF which is
renamed as TXT.
Case 4: Returns text/plain since strict = false.

© 2014 Adobe Systems Incorporated. All rights reserved.

1638

Adobe ColdFusion Documentation

© 2014 Adobe Systems Incorporated. All rights reserved.

1639

Adobe ColdFusion Documentation

FileIsEOF
Description

Determines whether ColdFusion has reached the end of an on-disk or in-memory file while reading it.
Returns

Yes, if the end of the file has been reached; No, otherwise.
Category

System functions, Decision functions
Function syntax

FileIsEOF(fileObj)

See also

FileClose, FileOpen, FileRead, FileReadLine
History

ColdFusion 8: Added this function.
Parameters

Parameter

Description

fileobj

The file object.

Example

The following example reads a file until it reaches the end of the file:

FileIsEOF Example

myfile = FileOpen("c:\ColdFusion9\wwwroot\test1.txt", "read");
while(NOT FileIsEOF(myfile))
{
x = FileReadLine(myfile);
WriteOutput("#x# 
");
}
FileClose(myfile);


© 2014 Adobe Systems Incorporated. All rights reserved.

1640

Adobe ColdFusion Documentation

© 2014 Adobe Systems Incorporated. All rights reserved.

1641

Adobe ColdFusion Documentation

FileMove
Description

Moves an on-disk or in-memory file from one location to another on the server.
Category

System functions
History

ColdFusion 8: Added this function.
Function syntax

FileMove(source, destination)

See also

FileClose, FileCopy, FileOpen, FileRead, FileReadLine, FileWrite, cffile
History

ColdFusion 8: Added this function.
Parameters

Parameter

Description

source

Pathname of the on-disk or in-memory file to move. If
not an absolute path (starting with a drive letter and a
colon, or a forward or backward slash), it is relative to
the ColdFusion temporary directory, which is returned
by the getTempDirectory function.

destination

Pathname of the destination on-disk or in-memory
directory or file. If not an absolute path, it is relative to
the source directory.

Usage

Use the following syntax to specify an in-memory file, which is not written to disk. In-memory files speed processing
of transient data.

ram:///filepath

The filepath can include directories, for example ram:///petStore/images/poodle.jpg. Create the directories
in the path before you specify the file. For more information on using in-memory files, see Working with in-memory

© 2014 Adobe Systems Incorporated. All rights reserved.

1642

Adobe ColdFusion Documentation

files in the Developing ColdFusion Applications.
Example

The following example moves the test1.txt file from the c:\testingdir\ directory to the c:\productiondir\ directory in
Windows and renames the file test2.txt:

FileMove Example




The destination file already exists.


FileMove(#sourcefile#, #destinationfile#);

Moved: #sourcefile# 

To: 
 #destinationfile#.



The source file does not exist.



© 2014 Adobe Systems Incorporated. All rights reserved.

1643

Adobe ColdFusion Documentation

FileOpen
Description

Opens an on-disk or in-memory file to read, write, or append. Use this function with the FileRead function to read
large files.
Returns

A file object that represents the open file.
Category

System functions
Function syntax

FileOpen(filepath, [mode, charset])

See also

FileClose, FileCopy, FileReadBinary, FileRead, FileReadLine, FileWrite, cffile
History

ColdFusion 8: Added this function.
Parameters

Parameter

Description

filepath

An absolute path of an on-disk or in-memory file on the
server.

mode

Action to perform on the file, including the following:
read
readBinary
write
append
If you do not specify the mode, ColdFusion opens
the file in read mode.

charset

The character set of the file.

Usage

The file does not have to exist before you open it. To write a new file, open it for writing, and then write it.The file
object is a handle to a file. You can use the object as a structure to access the following information:
filenameName of the file you opened
filepathAbsolute path and filename

© 2014 Adobe Systems Incorporated. All rights reserved.

1644

Adobe ColdFusion Documentation

lastmodifiedThe time when the file was most recently modified
modeThe action for which the file was opened
sizeThe file size in bytes
statusWhether the file object is open or closed
The following opens a file, and then displays the absolute path and filename of that file:


myfile = FileOpen("c:\temp\test1.txt", "read");

myfile refers to:


Use the following syntax to specify an in-memory file, which is not written to disk. In-memory files speed processing
of transient data.

ram:///filepath

The filepath can include directories, for example ram:///petStore/images/poodle.jpg. Create the directories
in the path before you specify the file. For more information on using in-memory files, see Working with in-memory
files in the Developing ColdFusion Applications.Always close a file after opening it. When you use the FileOpen fun
ction to open a file, the file stream from the disk is opened and contents are read from or written to it. The FileClo
se function closes the stream. If you do not close a file, the stream remains open; in that case, the operating system
can lock the file, which results in the file not being usable until the server is restarted.
Example

The following example opens a file, reads and outputs each line of the file, then closes the file.

FileOpen Example

myfile = FileOpen("c:\temp\test1.txt", "read");
while(NOT FileIsEOF(myfile))
{
x = FileReadLine(myfile);
WriteOutput("#x# 
"); }
FileClose(myfile);


© 2014 Adobe Systems Incorporated. All rights reserved.

1645

Adobe ColdFusion Documentation

FileRead
Description

Reads an on-disk or in-memory text file or a file object created with the FileOpen function. You use this function
either as an alternative to the cffile tag with the action="read" attribute. You can also use this function to
improve performance when reading a large file, because FileRead does not read the entire file into memory.
Returns

If you specify a filepath, the full text content of the file.
If you specify a file object, the character or byte buffer of the specified size. If the file was opened in read mode, Fil
eRead returns the character data (a string), otherwise it returns binary data.
Category

System functions
Function syntax

FileRead(filepath [, charset])
OR
FileRead(fileobj [, buffersize])

See also

FileClose, FileIsEOF, FileReadBinary, FileReadLine, FileWrite
History

ColdFusion 8: Added this function.
Parameters

Parameter

Description

filepath

An absolute path to an on-disk or in-memory text file on
the server.

© 2014 Adobe Systems Incorporated. All rights reserved.

1646

Adobe ColdFusion Documentation

charset

The character encoding in which the file contents is
encoded. The following list includes commonly used
values:
utf-8
iso-8859-1
windows-1252
us-ascii
shift_jis
iso-2022-jp
euc-jp
euc-kr
big5
euc-cn
utf-16
If the file starts with a byte order mark and you set
this attribute to a conflicting character encoding,
ColdFusion generates an error.

fileobj

The file object from which to read.

buffersize

The number of characters to read.

Usage

You can read a text file or a file object with the FileRead function. When you specify an absolute path of a text file,
ColdFusion reads the entire contents of the file. When you specify a file object, which you created using the FileOp
en function, ColdFusion reads the number of characters specified in buffersize.
Example

FileRead Example - Reading a file


myfile = FileRead("c:\temp\myfile.txt");
WriteOutput("#myfile#");




myfile = FileOpen("c:\temp\test1.txt", "read");
x = FileRead(myfile, 100);
WriteOutput("#x#");
FileClose(myfile);


© 2014 Adobe Systems Incorporated. All rights reserved.

1647

Adobe ColdFusion Documentation

FileReadBinary
Description

Reads an on-disk or in-memory binary file (such as an executable or image file) on the server, into a binary object
parameter that you can use in the page. To send it through a web protocol (such as HTTP or SMTP) or store it in a
database, first convert it to Base64 by using the ToBase64 function.
Note
This action reads the file into a variable in the local Variables scope. It is not intended for use
with large files, such as logs, because they can bring down the server.

Returns

The entire contents of a binary file.
Category

System functions
Function syntax

FileReadBinary(filepath)

See also

FileClose, FileIsEOF, FileRead, FileReadLine, FileWrite
History

ColdFusion 8: Added this function.
Parameters

Parameter

Description

filepath

An absolute path to an on-disk or in-memory binary file
on the server

Usage

You convert the binary file to Base64 to transfer it to another site. ColdFusion 8 supports reading an image file as a
binary and passing the result to a cfimage.
Example

The following example reads a binary file.

© 2014 Adobe Systems Incorporated. All rights reserved.

1648

Adobe ColdFusion Documentation

FileReadBinary Example

myfile = FileReadBinary("c:\testingdir\test3.jpg");


© 2014 Adobe Systems Incorporated. All rights reserved.

1649

Adobe ColdFusion Documentation

FileReadLine
Description

Reads a line from an on-disk or in-memory file.
Returns

The line of the file.
Category

System functions
Function syntax

FileReadLine(fileObj)

See also

FileClose, FileIsEOF, FileRead, FileWrite
History

ColdFusion 8: Added this function.
Parameters

Parameter

Description

fileobj

The file object

Example

The following example opens a file, reads each line, outputs each line, and then closes the file.

FileReadLIne Example

myfile = FileOpen("c:\ColdFusion9\wwwroot\test1.txt", "read");
while(NOT FileisEOF(myfile))
{
x = FileReadLine(myfile); // read line
WriteOutput("#x#");
}
FileClose(myfile);

NewFile = FileOpen(ExpandPath(".") & "\test.txt","write","",true);
FileSeek(#NewFile#,0);
FileWrite(#NewFile#,"Hello World.. This is for FileOpen, FileSeek,
FileSkipBytes.");
FileClose(#NewFile#);
WriteOutput("
Opening in Read Mode.
");
NewFile = FileOpen(ExpandPath(".") & "\test.txt","read","",true);
ReadFile = FileRead(#NewFile#,100);
WriteOutput("#ReadFile#
");
FileClose(#NewFile#);
WriteOutput("
Opening in Read-Write Mode.
");
NewFile = FileOpen(ExpandPath(".") & "\test.txt","readwrite","",true);
FileSeek(#NewFile#,2);
FileSkipBytes(#NewFile#,4);
FileWrite(#NewFile#,"Earth");
ReadFile = FileRead(#NewFile#,100);
WriteOutput("#ToString(ReadFile)#
");
FileClose(#NewFile#);


© 2014 Adobe Systems Incorporated. All rights reserved.

1652

Adobe ColdFusion Documentation

FileSetAccessMode
Description

Sets the attributes of an on-disk file on UNIX or Linux. This function does not work with in-memory files.
Category

System functions
Function syntax

FileSetAccessMode(filepath, mode)

See also

FileCopy, FileDelete, FileExists, FileMove
History

ColdFusion 8: Added this function.
Parameters

Parameter

Description

filepath

An absolute path to the file on the server.

mode

A three-digit value, in which each digit specifies the file
access for individuals and groups:
The first digit represents the owner.
The second digit represents a group.
The third digit represents anyone.
Each digit of this code sets permissions for the
appropriate individual or group:
4 specifies read permission.
2 specifies write permission.
1 specifies execute permission.
You use the sums of these numbers to indicate
combinations of the permissions:
3 specifies write and execute permission.
5 specifies read and execute permission.
6 indicates read and write permission.
7 indicates read, write, and execute permission.
For example, 400 specifies that only the owner can
read the file; 004 specifies that anyone can read the
file.

Example

© 2014 Adobe Systems Incorporated. All rights reserved.

1653

Adobe ColdFusion Documentation

The following example sets the access mode of a file so that only the owner can read the file.

FileSetAccessMode Example

FileSetAccessMode("test1.txt", "004");


© 2014 Adobe Systems Incorporated. All rights reserved.

1654

Adobe ColdFusion Documentation

FileSetAttribute
Description

Sets the attributes of an on-disk file in Windows. This function does not work with in-memory files.
Category

System functions
Function syntax

FileSetAttribute(filepath, attribute)

See also

FileCopy, FileDelete, FileExists, FileMove
History

ColdFusion 8: Added this function.
Parameters

Parameter

Description

filepath

An absolute path to a file on the server.

attribute

One of the following:
readOnly
hidden
normal
Set the attribute to normal to make a file not
read-only and not hidden.

Example

The following example sets the access mode of a file to be read-only.

FileSetAttribute Example

FileSetAttribute("c:\temp\test1.txt", "readOnly");


© 2014 Adobe Systems Incorporated. All rights reserved.

1655

Adobe ColdFusion Documentation

FileSetLastModified
Description

Sets the date when an on-disk or in-memory file was most recently modified.
Category

System functions
Function syntax

FileSetLastModified(filepath, date)

See also

FileCopy, FileDelete, FileExists, FileMove, FileSetAccessMode, FileSetAttribute
History

ColdFusion 8: Added this function.
Parameters

Parameter

Description

filepath

An absolute path to an on-disk or in-memory file on the
server.

date

A valid ColdFusiondate or datetime.

Example


FileSetLastModified("c:\temp\test1.txt", "#Now()#");
WriteOutput(#GetFileInfo("c:\temp\test1.txt").lastmodified#);


© 2014 Adobe Systems Incorporated. All rights reserved.

1656

Adobe ColdFusion Documentation

FileSkipBytes
Description

Skips over the data before a read or write operation of an on-disk or in-memory file on the server.
Category

System functions
Function syntax

FileSkipBytes(fileObj, noOfBytesToSkip)
See Also

FileCopy, FileDelete, FileExists, FileMove, FileSetAccessMode, FileSetAttribute, FileSeek
History

ColdFusion 9: Added this function.
Parameters

Parameter

Description

fileobj

The file object.

noOfBytesToSkip

The number of bytes that must be skipped before the
next file operation.

Usage

For noOfBytesToSkip, if you specify a value greater than the actual number of bytes, all bytes are skipped.
Example

See the Example section for the function FileSeek.

© 2014 Adobe Systems Incorporated. All rights reserved.

1657

Adobe ColdFusion Documentation

FileUpload
Description

Uploads file to a directory on the server.
Returns

Struct that contains the result (or status) of file upload.For details of what the struct contains, see the usage section
of cffile action = "upload".
Function syntax

FileUpload(destination)
FileUpload(destination, filefield)
FileUpload(destination, filefield, accept)
FileUpload(destination, filefield, accept, nameconflict)
History

ColdFusion 9.0.1: Added this function.
Parameters

Value

Description

destination

Path of directory in which to upload the file. If not an
absolute path (starting with a drive letter and a colon, or
a forward or backward slash), it is relative to the
ColdFusion temporary directory returned by the
function getTempDirectory. If the destination you
specify does not exist, ColdFusion creates a file with
the specified destination name. For example, if you
specify the destination C:\XYZ, ColdFusion creates a
file XYZ in the C: drive.

accept

Limits the MIME types to accept. Comma-delimited list.
For example, the following code permits JPEG and
Microsoft Word file uploads:"image/jpg,applicati
on/msword".The browser uses the filename extension
to determine file type.

© 2014 Adobe Systems Incorporated. All rights reserved.

1658

Adobe ColdFusion Documentation

nameConflict

Action to take if file has the same name of a file in the
directory.
Error: File is not saved. ColdFusion stops
processing the page and returns an error.
Skip: File is not saved. This option permits custom
behavior based on file properties.
Overwrite: Replaces file.
MakeUnique: Forms a unique filename for the
upload; name is stored in the file object variable ser
verFile.

fileField

Name of form field used to select the file. Do not use
number signs (#) to specify the field name.

See also

FileUploadAll
Usage

cffile action = "upload"
Example



hello = FileUpload("","","unique");










© 2014 Adobe Systems Incorporated. All rights reserved.

1659

Adobe ColdFusion Documentation

FileUploadAll
Description

Uploads all files sent to the page in an HTTP request to a directory on the server.
Returns

An array of struct that provides the file upload status.For details of what the struct contains, see the Usage Section
of cffile action = "uploadAll".
Function Syntax

FileUploadAll(destination)
FileUploadAll(destination, accept)
FileUploadAll(destination, accept, nameConflict)
History

ColdFusion 11: Added ContinueOnError and Errors attribute.
ColdFusion 9.0.1: Added this function.
Parameter

Value

Description

destination

Path of directory in which to upload the file. If not an
absolute path (starting with a drive letter and a colon, or
a forward or backward slash), it is relative to the
ColdFusion temporary directory, returned by the
function getTempDirectory.
If the destination you specify does not exist,
ColdFusion creates a file with the specified destination
name. For example, if you specify the destination
C:\XYZ, ColdFusion creates a file XYZ in the C: drive.

accept

Limits the MIME types to accept. Comma-delimited list.
For example, the following code permits JPEG and
Microsoft Word file uploads:{{"image/jpg,
application/msword"}}The browser uses the filename
extension to determine file type.

© 2014 Adobe Systems Incorporated. All rights reserved.

1660

Adobe ColdFusion Documentation

nameConflict

Action to take if file has the same name of a file in the
directory.
Error: File is not saved. ColdFusion stops
processing the page and returns an error.
Skip: File is not saved. Permits custom behavior
based on file properties.
Overwrite: Replaces file.
MakeUnique: Forms a unique filename for the
upload; name is stored in the file object variable ser
verFile.

Added in ColdFusion 11:
Value

Required

Default

Description

ContinueOnError

Optional

False

By default, when
uploading one of the files
fail, the remaining files will
not be uploaded. If this
value is set to true, file
upload continues evern
after encountering an
upload error. A file upload
error happens due to the
following reasons:
1. Empty file
2. Invalid file type
3. Invalid MIME or
extension
4. File already exists
In the case of an upload
failure, the error details
will be stored in the errors
attribute.

Errors

Optional

© 2014 Adobe Systems Incorporated. All rights reserved.

cffile.uploadAllErrors

The name of the variable
in which the file upload
errors will be stored.
Errors will be populated in
the specfied variable
name when
continueOnError is
true.After the file upload is
completed, this tag
creates an array of
structures that contains
upload failure information
for each upload failure.

1661

Adobe ColdFusion Documentation

The upload failure
information error structure
contains the following
fields:

© 2014 Adobe Systems Incorporated. All rights reserved.

1662

Adobe ColdFusion Documentation

REASON - The reason
for the failure
DETAIL - File upload
failure detail
MESSAGE - A detailed
message depicting the
failure
CLIENTFILE - Name of
the file uploaded from
the client's system
CLIENTFILEEXT Extension of the
uploaded file on the
client system (without a
period)
CLIENTFILENAME Name of the uploaded
file on the client system
(without an extension)
INVALID_FILE_TYPE If the file mime type or
extension is not in the s
pecified accept
attribute. If the reason is
INVALID_FILE_TYPE,
two additional keys will
be available in the
structure.
ACCEPT: list of
mime types or
file extensions
given in the tag
MIMETYPE:
mime type of the
uploaded file
EMPTY_FILE - If the
uploaded file is an
empty file
FILE_EXISTS - If any
file with the given name
already exists in the
destination and the
overwritepolicy is error.
DEST - The destination
where file is copied
FORM_FILE_NOT_FO
UND - If the uploaded
file is not found on the
server

See also

© 2014 Adobe Systems Incorporated. All rights reserved.

1663

Adobe ColdFusion Documentation

FileUpload
Usage

cffile action = "uploadAll"

© 2014 Adobe Systems Incorporated. All rights reserved.

1664

Adobe ColdFusion Documentation

FileWrite
Description

If you specify a file path, writes the entire content to the specified on-disk or in-memory file. If you specify a file
object, writes text or binary data to the file object.
Category

System functions
Function syntax

FileWrite(filepath, data [, charset])
OR
FileWrite(fileobj, data)

See also

FileCopy, FileDelete, FileExists, FileMove, cffile
History

ColdFusion 8: Added this function.
Parameters

Parameter

Description

charset

The character encoding in which the file contents is
encoded. The following list includes commonly used
values:
utf-8
iso-8859-1
windows-1252
us-ascii
shift_jis
{{iso-2022-jp }}
euc-jp
euc-kr
big5
euc-cn
utf-16
If the file starts with a byte order mark and you set
this attribute to a conflicting character encoding,
ColdFusion generates an error.

data

© 2014 Adobe Systems Incorporated. All rights reserved.

Content of the file or file object to create.

1665

Adobe ColdFusion Documentation

fileobj

Name of the file object to write.

filepath

Pathname of the on-disk or in-memory file to write. If
not an absolute path (starting with a drive letter and a
colon, or a forward or backward slash), it is relative to
the ColdFusion temporary directory, which is returned
by the getTempDirectory function.

Usage

Use the following syntax to specify an in-memory file, which is not written to disk. In-memory files speed processing
of transient data.

ram:///filepath

The filepath can include directories, for example ram:///petStore/images/poodle.jpg. Create the directories
in the path before you specify the file. For more information on using in-memory files, see Working with in-memory
files in the Developing ColdFusion Applications.
Example

FileWrite Example





SELECT EMAIL
FROM Employees






FileWrite("mail_list", "#companymail#");
mlist = FileRead("mail_list");
FileWrite("c:\temp\mail_list.txt", "#mlist#");


© 2014 Adobe Systems Incorporated. All rights reserved.

1666

Adobe ColdFusion Documentation

FileWriteLine
Description

Appends the specified text to the file object.
Category

System functions
Function syntax

FileWriteLine(fileobj, text)

See also

FileCopy, FileDelete, FileExists, FileMove, FileWrite, cffile
History

ColdFusion 8: Added this function.
Parameters

Parameter

Description

text

Content to add to the file object.

fileobj

The file object to which to write the line.

Example

FileWriteLine Example

myfile = FileOpen("c:\temp\test1.txt", "write");
FileWriteLine(myfile,"This line is new.");
FileClose(myfile);


© 2014 Adobe Systems Incorporated. All rights reserved.

1667

Adobe ColdFusion Documentation

Find
Description

Finds the first occurrence of a substring in a string, from a specified start position. The search is case sensitive.
Returns

A number; the position of substring in string; or 0, if substring is not in string.
Category

String functions
Function syntax

Find(substring, string [, start ])

See also

FindNoCase, Compare, FindOneOf, REFind, Replace
Parameters

Parameter

Description

substring

A string or a variable that contains one. String for which
to search.

string

A string or a variable that contains one. String in which
to search.

start

Start position of search.

Example



#find("the",stringToSearch)#

#find("the",stringToSearch,35)#

#find("no such substring",stringToSearch)#



#findnocase("the",stringToSearch)#

#findnocase("the",stringToSearch,5)#

#findnocase("no such substring",stringToSearch)#



#findoneof("aeiou",stringToSearch)#

#findoneof("aeiou",stringToSearch,4)#

#findoneof("@%^*()",stringToSearch)#



© 2014 Adobe Systems Incorporated. All rights reserved.

1668

Adobe ColdFusion Documentation

© 2014 Adobe Systems Incorporated. All rights reserved.

1669

Adobe ColdFusion Documentation

FindNoCase
Description

Finds the first occurrence of a substring in a string, from a specified start position. If substring is not in string, returns
zero. The search is case-insensitive.
Returns

The position of substring in string; or 0, if substring is not in string.
Category

String functions
Function syntax

FindNoCase(substring, string [, start ])

See also

Find, CompareNoCase, FindOneOf, REFind, Replace
Parameters

Parameter

Description

substring

A string or a variable that contains one. String for which
to search.

string

A string or a variable that contains one. String in which
to search.

start

Start position of search.

Example

In the following example, the Find function returns 33 as the first position found because "the" is lowercase. The Fi
ndNoCase function returns 1 as the first position because the case is ignored.

© 2014 Adobe Systems Incorporated. All rights reserved.

1670

Adobe ColdFusion Documentation


stringToSearch = #stringToSearch#


Find Function:

Find("the",stringToSearch) returns
#find("the",stringToSearch)#


FindNoCase Function:

FindNoCase("the",stringToSearch) returns
#FindNoCase("the",stringToSearch)#

© 2014 Adobe Systems Incorporated. All rights reserved.

1671

Adobe ColdFusion Documentation

FindOneOf
Description

Finds the first occurrence of any one of a set of characters in a string, from a specified start position. The search is
case sensitive.
Returns

The position of the first member of set found in string; or 0, if no member of set is found in string.
Category

String functions
Function syntax

FindOneOf(set, string [, start ])

See also

Find, Compare, REFind
Parameters

Parameter

Description

set

A string or a variable that contains one. String that
contains one or more characters to search for.

string

A string or a variable that contains one. String in which
to search.

start

Start position of search.

Example

© 2014 Adobe Systems Incorporated. All rights reserved.

1672

Adobe ColdFusion Documentation



#find("the",stringToSearch)#

#find("the",stringToSearch,35)#

#find("no such substring",stringToSearch)#



#findnocase("the",stringToSearch)#

#findnocase("the",stringToSearch,5)#

#findnocase("no such substring",stringToSearch)#



#findoneof("aeiou",stringToSearch)#

#findoneof("aeiou",stringToSearch,4)#

#findoneof("@%^*()",stringToSearch)#



© 2014 Adobe Systems Incorporated. All rights reserved.

1673

Adobe ColdFusion Documentation

FirstDayOfMonth
Description

Determines the ordinal (day number, in the year) of the first day of the month in which a given date falls.
Returns

A number that corresponds to a day-number in a year.
Category

Date and time functions
Function syntax

FirstDayOfMonth(date)

See also

Day, DayOfWeek, DayOfWeekAsString, DayOfYear, DaysInMonth, DaysInYear
Parameters

Parameter

Description

date

Date/time object, in the range 100 AD–9999 AD.

Usage

When passing a date/time value as a string, enclose it in quotation marks. Otherwise, it is interpreted as a number
representation of a date/time object.
Example

FirstDayOfMonth Example

The first day of #MonthAsString(Month(Now()))#, #Year(Now())# was
day #FirstDayOfMonth(Now())# of the year.


© 2014 Adobe Systems Incorporated. All rights reserved.

1674

Adobe ColdFusion Documentation

Fix

Description

Converts a real number to an integer.
Returns

If number is greater than or equal to 0, the closest integer less than or equal to number. If number is less than 0, the
closest integer greater than or equal to number.
Category

Mathematical functions
Function syntax

Fix(number)

See also

Ceiling, Int, Round
Parameters

Parameter

Description

number

A number

Example

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

The fix of 3.4 is #Fix(3.4)#
The fix of 3 is #Fix(3)#
The fix of 3.8 is #Fix(3.8)#
The fix of -4.2 is #Fix(-4.2)#


© 2014 Adobe Systems Incorporated. All rights reserved.

1675

Adobe ColdFusion Documentation

FormatBaseN
Description

Converts number to a string, in the base specified by radix.
Returns

String that represents number, in the base radix.
Category

Display and formatting functions, Mathematical functions, String functions
Function syntax

FormatBaseN(number, radix)

See also

InputBaseN
Parameters

Parameter

Description

number

Number to convert

radix

Base of the result

Example

© 2014 Adobe Systems Incorporated. All rights reserved.

1676

Adobe ColdFusion Documentation

FormatBaseN Example
Converts a number to a string in the base specified by Radix.



FormatBaseN(10,2): #FormatBaseN(10,2)#

FormatBaseN(1024,16): #FormatBaseN(1024,16)#

FormatBaseN(125,10): #FormatBaseN(125,10)#

FormatBaseN(10.75,2): #FormatBaseN(10.75,2)#

InputBaseN Example
InputBaseN returns the number obtained by converting a string,
using base specified by Radix (an integer from 2 to 36).


InputBaseN("1010",2): #InputBaseN("1010",2)#

InputBaseN("3ff",16): #InputBaseN("3ff",16)#

InputBaseN("125",10): #InputBaseN("125",10)#

InputBaseN(1010,2): #InputBaseN(1010,2)#


© 2014 Adobe Systems Incorporated. All rights reserved.

1677

Adobe ColdFusion Documentation

GenerateSecretKey
Description

Gets a secure key value for use in the Encrypt function.
Returns

A string that contains the encryption key.
Category

Security functions, String functions
Function syntax

GenerateSecretKey(algorithm [,keysize])

See also

Decrypt, Encrypt
History

ColdFusion 8: Added the keysize attribute.
ColdFusion MX 7: Added this function.
Parameters

Parameter

Description

algorithm

The encryption algorithm for which to generate the key.
ColdFusion installs a cryptography library with the
following algorithms:
AES: the Advanced Encryption Standard specified by
the National Institute of Standards and Technology
(NIST) FIPS-197.
BLOWFISH: the Blowfish algorithm defined by Bruce
Schneier.
DES: the Data Encryption Standard algorithm
defined by NIST FIPS-46-3.
DESEDE: the "Triple DES" algorithm defined by
NIST FIPS-46-3.

© 2014 Adobe Systems Incorporated. All rights reserved.

1678

Adobe ColdFusion Documentation

keysize

Number of bits requested in the key for the specified
algorithm.You can use this to request longer keys when
allowed by the JDK. For example, the AES algorithm
keys are limited to 128 bits unless the Java Unlimited
Strength Jurisdiction Policy Files are installed. For
more information, see http://java.sun.com/products/jce/i
ndex-14.html.

Usage

You cannot use the GenerateSecretKey function to generate a key for the ColdFusion default encryption
algorithm (CFMX_COMPAT) of the Encrypt and Decrypt functions.
ColdFusion uses the Java Cryptography Extension (JCE) and installs a Sun Java runtime that includes the Sun JCE
default security provider. This provider includes the algorithms listed in the Parameters section. The JCE framework
includes facilities for using other provider implementations; however, Adobe cannot provide technical support for
third-party security providers.
Example

The following example encrypts and decrypts a text string. It lets you specify the encryption algorithm and encoding
technique. It also has a field for a key seed to use with the CFMX_COMPAT algorithm. For all other algorithms, it
uses the GenerateSecretKey function to generate a secret key.

Decrypt Example



/* GenerateSecretKey does not generate keys for the CFMX_COMPAT algorithm,
so we use a key from the form.
*/
if (Form.myAlgorithm EQ "CFMX_COMPAT")
theKey=Form.MyKey;
// For all other encryption techniques, generate a secret key.
else
theKey=generateSecretKey(Form.myAlgorithm);
//Encrypt the string.
encrypted=encrypt(Form.myString, theKey, Form.myAlgorithm,
Form.myEncoding);
//Decrypt it.
decrypted=decrypt(encrypted, theKey, Form.myAlgorithm, Form.myEncoding);



The algorithm: #Form.myAlgorithm#

The key: #theKey#



The string: #Form.myString# 



Encrypted: #encrypted#



Decrypted: #decrypted#



© 2014 Adobe Systems Incorporated. All rights reserved.

1679

Adobe ColdFusion Documentation




Select the encoding


UU
Base64
Hex




Select the algorithm


CFMX_COMPAT
AES
DES
DESEDE




Input your key (used for CFMX_COMPAT encryption only)





Enter string to encrypt

This string
will be encrypted (you can replace it with more typing).



© 2014 Adobe Systems Incorporated. All rights reserved.

1680

Adobe ColdFusion Documentation




© 2014 Adobe Systems Incorporated. All rights reserved.

1681

Adobe ColdFusion Documentation

GetAuthUser
Description

Gets the name of an authenticated user.
Returns

The name of an authenticated user.
Category

Security functions
Function syntax

GetAuthUser()

See also

cflogin, cfloginuser, cflogout, GetUserRoles, IsUserInAnyRole, IsUserInRole, IsUserLoggedIn,
ColdFusion security features in the Developing ColdFusion Applications
History

ColdFusion MX: Added this function.
Usage

This function works with cflogin authentication or web server authentication. It checks for a logged-in user as
follows:
1. It checks for a login made with cfloginuser.
2. If no user was logged in with cfloginuser, it checks for a web server login (cgi.remote_user).
Example

GetAuthUser Example
Authenticated User: #GetAuthUser()#

© 2014 Adobe Systems Incorporated. All rights reserved.

1682

Adobe ColdFusion Documentation

GetBaseTagData
Description

Used within a custom tag. Finds calling (ancestor) tag by name and accesses its data.
Returns

An object that contains data (variables, scopes, and so on) from an ancestor tag. If there is no ancestor by the
specified name, or if the ancestor does not expose data (for example, cfif), an exception is thrown.
Category

Other functions
Function syntax

GetBaseTagData(tagname [, instancenumber ])

See also

GetBaseTagList; High-level data exchange in the Developing ColdFusion Applications
Parameters

Parameter

Description

tagname

(Required) Ancestor tag name for which to return data

instancenumber

(Optional) Number of ancestor levels to jump before
returning data. The default value is 1 (closest
ancestor).

Example

© 2014 Adobe Systems Incorporated. All rights reserved.

1683

Adobe ColdFusion Documentation


...


Running in the context of a custom
tag named #inCustomTag#.





Located inside the

template

BODY


© 2014 Adobe Systems Incorporated. All rights reserved.

1684

Adobe ColdFusion Documentation

GetBaseTagList
Description

Gets ancestor tag names, starting with the parent tag.
Returns

A comma-delimited list of uppercase ancestor tag names, as a string. The first list element is the current tag. If the
current tag is nested, the next element is the parent tag. If the function is called for a top-level tag, it returns an
empty string. If an ancestor does not expose data (see GetBaseTagData), its name might not be returned.
Category

Other functions
Function syntax

GetBaseTagList()

See also

GetBaseTagData; High-level data exchange in the Developing ColdFusion Applications
Usage

This function does not display the following tags or end tags in the ancestor tag list:
cfif, cfelseif, cfelse
cfswitch, cfcase, cfdefaultcase
cftry, cfcatch
This function displays the following tags only under the following conditions:
cfloop: if it uses a query attribute
cfoutput: if at least one of its children is a complex expression
cfprocessingdirective: if it has at least one other attribute besides pageencoding
Example

© 2014 Adobe Systems Incorporated. All rights reserved.

1685

Adobe ColdFusion Documentation







Dump of GetBaseTagList output:





This is custom tag#ListGetAt(ancestorList,1)#




Running in the context of a cfloop tag.




© 2014 Adobe Systems Incorporated. All rights reserved.

1686

Adobe ColdFusion Documentation

GetBaseTemplatePath
Description

Gets the absolute path of an application’s base page.
Returns

The absolute path of the application base page, as a string.
Category

Other functions, System functions
Function syntax

GetBaseTemplatePath()

See also

GetCurrentTemplatePath, GetDirectoryFromPath, F
ileExists, ExpandPath
Usage

Contrast this with the GetCurrentTemplatePath function, which returns if called from an included page returns
the page path of the included template rather than the base (including) template .
Example

GetBaseTemplatePath Example
The template path of the current page is:
#GetBaseTemplatePath()#

The directory containing the current template is:
#GetDirectoryFromPath(GetBaseTemplatePath())#

© 2014 Adobe Systems Incorporated. All rights reserved.

1687

Adobe ColdFusion Documentation

GetClientVariablesList
Description

Finds the client variables to which a page has write access.
Returns

Comma-delimited list of non-read-only client variables, as a string.
Category

List functions, Other functions
Function syntax

GetClientVariablesList()

See also

DeleteClientVariable
Usage

The list of variables returned by this function is compatible with ColdFusion list functions.
Example

GetClientVariablesList Example


This example creates two client variables and deletes the User_ID client
variable,
if it exists in the list of client variables returned by
GetClientVariablesList().


Client variable list: #GetClientVariablesList()#

Delete client.User_ID variable.

Was variable "User_ID" Deleted? #temp#

Amended Client variable list: #GetClientVariablesList()#


© 2014 Adobe Systems Incorporated. All rights reserved.

1688

Adobe ColdFusion Documentation

© 2014 Adobe Systems Incorporated. All rights reserved.

1689

Adobe ColdFusion Documentation

GetComponentMetaData
Description

Gets metadata (such as the functions and implemented interfaces of a component) for a CFC or ColdFusion
interface.
Returns

A structure containing the metadata for the CFC or interface. For information on the structure contents, see the
component entry in the table in the GetMetaData Usage section.
Category

Extensibility functions
Function syntax

GetComponentMetaData(path)

See also

GetMetaData
History

ColdFusion 8: Added this function.
Parameters

Parameter

Description

path

The dot-delimited path of the interface or CFC
definition. The path can be relative to the current
directory or the web root. For example, if a cfm page
that calls this function is in web_root/my_apps/interface
s, the interface file is in web_root/my_apps/interfaces/d
efinitions, and you want to get the metadata for the
interface defined in I2.cfc, specify either of the following
values in this parameter:
definitions.I2
my_apps.interface.definitions.I2.cfc

Usage

This function and the getMetaData function return the same data. This function, however, takes a path to the CFC
or Interface definition file, and does not use or create an object instance. Also, this function can get data about CFCs
and interfaces only, and you cannot specify an interface in the getMetaData function.

© 2014 Adobe Systems Incorporated. All rights reserved.

1690

Adobe ColdFusion Documentation

GetContextRoot
Description

Returns path to the JEE server context root for the current request.
Returns

The path from the web root to the context root for the current page. The path starts with a forward slash character
but does not end with a forward slash character
. For applications in the default (root) context, returns the
empty string.
Category

System functions
History

ColdFusion MX 7: Added this function.
Function syntax

GetContextRoot()

See also

GetPageContext
Usage

This function is equivalent to calling GetPageContext().GetRequest().GetContextPath(). On JEE
configurations, it returns the path from the Web root to the JEE context root of the ColdFusion JEE application. On
server configurations, it returns the empty string, because the context root is at the web root.This function is useful in
applications that might be installed at varying JEE context roots.
Example

The ColdFusion Administrator uses the following line to get the location of the administrator directory:



The Administrator uses the returned value in places where it uses a URL to access Administrator resources, such as
images, as in the following line:



© 2014 Adobe Systems Incorporated. All rights reserved.

1691

Adobe ColdFusion Documentation

GetCPUUsage
Description

Gets the CPU usage with default or custom snapshot interval. The default interval is 1000 milli-seconds.
Syntax

getCPUUsage()
getCPUUsage(long ms)
Parameters

Parameter

Description

long ms

Time in milli-seconds. This is the time delay between
two snapshots.

© 2014 Adobe Systems Incorporated. All rights reserved.

1692

Adobe ColdFusion Documentation

GetCurrentTemplatePath
Description

Gets the path of the page that calls this function.
Returns

The absolute path of the page that contains the call to this function, as a string.
Category

System functions
Function syntax

GetCurrentTemplatePath()

See also

GetBaseTemplatePath, GetDirectoryFromPath, File
Exists, ExpandPath
Usage

If the function call is made from a page included with a cfinclude tag, this function returns the page path of an
included page. Contrast this with the GetBaseTemplatePath function, which returns the path of the top-level
page, even if it is called from an included page.
Example


GetCurrentTemplatePath Example
The template path of the current page is:
#GetCurrentTemplatePath()#

The directory containing the current template is:
#GetDirectoryFromPath(GetCurrentTemplatePath())#

© 2014 Adobe Systems Incorporated. All rights reserved.

1693

Adobe ColdFusion Documentation

GetDirectoryFromPath
Description

Extracts a directory from an absolute on-disk or in-memory path.
Returns

Absolute path, without the filename. The last character is a forward or backward slash, depending on the operating
system.
Category

System functions
Function syntax

GetDirectoryFromPath(path)

See also

ExpandPath, GetFileFromPath
Parameters

Parameter

Description

path

Absolute on-disk or in-memory path.

Usage
Example

© 2014 Adobe Systems Incorporated. All rights reserved.

1694

Adobe ColdFusion Documentation

GetDirectoryFromPath Example



The current directory is: #GetDirectoryFromPath(thisPath)#




Your file exists in this directory. You entered the correct filename,
#GetFileFromPath("#thisPath#/#yourfile#")#

Your file was not found in this directory:

Here is a list of the other files in this directory:










Please enter a filename



Enter the name of a file in this directory 
(try expandpath.cfm)


 --->

© 2014 Adobe Systems Incorporated. All rights reserved.

1695

Adobe ColdFusion Documentation

GetEncoding
Description

Returns the encoding (character set) of the Form or URL scope.
Returns

String; the character encoding of the specified scope.
Category

International functions, System functions
Function syntax

GetEncoding(scope_name)

See also

cfcontent, cfprocessingdirective, URLDecode, URLEncodedFormat
History

ColdFusion MX: Added this function.
Parameters

Parameter
scope_name

Description
Form
URL.

Usage

Use this function to determine the character encoding of the URL query string or the fields of a form that was
submitted to the current page. The default encoding, if none has been explicitly set, is UTF-8.For more information,
see www.iana.org/assignments/character-sets.
Example

© 2014 Adobe Systems Incorporated. All rights reserved.

1696

Adobe ColdFusion Documentation










SetEncoding("url", "big5");
WriteOutput("URL.XXX is " & URL.xxx & "
");
WriteOutput("URL.YYY is " & URL.yyy & "
");
theEncoding = GetEncoding("URL");
WriteOutput("The URL variables were decoded using '" & theEncoding & "'
encoding.");
WriteOutput("The encoding is " & theEncoding);



© 2014 Adobe Systems Incorporated. All rights reserved.

1697

Adobe ColdFusion Documentation

GetException
Description

Used with the cftry and cfcatch tags. Retrieves a Java exception object from a Java object.
Returns

Any Java exception object raised by a previous method call on the Java object.
Category

System functions
Syntax

GetException(object)

Parameters

Parameter

Description

object

A Java object.

Usage

ColdFusion stores a Java exception object for each method call on a Java object. Subsequent method calls reset
the exception object. To get the current exception object, call GetException on the Java object before other
methods are invoked on it.
Example












Error

I got exception 


 The exception message is: #message# 





© 2014 Adobe Systems Incorporated. All rights reserved.

1698

Adobe ColdFusion Documentation

GetFileFromPath
Description

Extracts a filename from an absolute on-disk or in-memory path.
Returns

Filename, as a string.
Category

System functions
Function syntax

GetFileFromPath(path)

See also

ExpandPath, GetCurrentTemplatePath
Parameters

Parameter

Description

path

Absolute on-disk or in-memory path.

Example

© 2014 Adobe Systems Incorporated. All rights reserved.

1699

Adobe ColdFusion Documentation

GetFileFromPath Example



The current directory is: #GetDirectoryFromPath(thisPath)#




Your file exists in this directory. You entered the correct file
name, #GetFileFromPath("#thisPath#/#yourfile#")#

Your file was not found in this directory:

Here is a list of the other files in this directory:






...

© 2014 Adobe Systems Incorporated. All rights reserved.

1700

Adobe ColdFusion Documentation

GetFileInfo
Description

Retrieves information about on-disk or in-memory file.
Returns

The filename, path, parent directory, type, size, when the file was most recently modified, whether the file has read
permission, write permission, and is hidden.
Category

System functions
Function syntax

GetFileInfo(path)

See also

FileOpen
History

ColdFusion 8: Added this function.
Parameters

Parameter

Description

path

Absolute on-disk or in-memory path.

Usage

The function returns a structure that includes the following keys:
Name: name of the file
Path: absolute path of the file
Parent: path to the file’s parent directory
Type: either "directory" or "file"
Size: file size in bytes
Lastmodified: datetime when it was the file was most recently modified
canRead: whether the file can be read
canWrite: whether the file has write permission
isHidden: whether the file is a hidden
Example

© 2014 Adobe Systems Incorporated. All rights reserved.

1701

Adobe ColdFusion Documentation


FileSetLastModified("c:\temp\test1.txt", "#Now()#");
WriteOutput(GetFileInfo("c:\temp\test1.txt").lastmodified);


© 2014 Adobe Systems Incorporated. All rights reserved.

1702

Adobe ColdFusion Documentation

GetFreeSpace
Description

Gets information about free hard disk space or free in-memory VFS space.
Returns

Returns the free space in bytes.
Syntax

getFreeSpace(path)
Parameters

Parameter

Description

path

Path to the
Hard disk drive, for example C: }}for Windows
or {{/ for UNIX. Note that for Windows, you have
to explicitly use colon (:) and not just C. Only the
space of the entire hard disk drive is returned. If you
mention a directory in the path, for example, /opt/,
it is ignored and only {{/ }}is considered.
For in-memory file system, the path is ram:.

Usage

See the usage section for GetTotalSpace.
Example

In the following example, in-memory file system memory for the application is set to 20 MB in ColdFusion
Administrator. The function returns 20, which means the total space considered is 20 MB. This is because the value
specified in the ColdFusion Administrator (Memory Limit per Application for In-Memory Virtual File System) is lesser
than the value specified in the Application.cfc (20 MB).Application.cfc






space.cfm

© 2014 Adobe Systems Incorporated. All rights reserved.

1703

Adobe ColdFusion Documentation







Total Hard Disk Space = #DecimalFormat(totalDiskSpace / (1024 *

Free Hard Disk Space = #DecimalFormat(freeDiskSpace / (1024
GB

Total Application RAM Memory = #DecimalFormat(totalRAMSpace
MB

Free Application RAM Memory = #DecimalFormat(freeRAMSpace /

1024 * 1024))# GB
* 1024 * 1024))#
/ (1024 * 1024))#
(1024 * 1024))# MB






#cfcatch.message#

#cfcatch.detail#






© 2014 Adobe Systems Incorporated. All rights reserved.

1704

Adobe ColdFusion Documentation

GetFunctionCalledName
Description

Returns the name of the variable used to call a defined function.
Returns

Name of the variable.
Category

System functions
Function syntax

GetFunctionCalledName()

History

ColdFusion 9: Added this function
Usage

This function can be used to return data from CFCs by simulating getters and setters. This applies only if the CFC
does not use implicit getters and setters provided by ColdFusion 9.
Example

The following example shows how you can use this function to return data without defining explicit setters and
getters:

© 2014 Adobe Systems Incorporated. All rights reserved.

1705

Adobe ColdFusion Documentation

//callednamedemo.cfc
component
{
variables.x1 = 1;
variables.y1 = 2;
function init()
{
return this;
}
function get()
{
var name = getFunctionCalledName();
return variables[mid(name,4,len(name)-3)];
}
function set(value)
{
var name = getFunctionCalledName();
variables[mid(name,4,len(name)-3)] = value;
}
this.getX1 = get;
this.getY1 = get;
this.setX1 = set;
this.setY1 = set;
}


function test()
{
return getFunctionCalledName();
}
WriteOutput(test() & "
"); // test
a = test;
WriteOutput(variables.a() & "
"); // a
o = new callednamedemo();
// shows *real* methods get(), SetX1() and getY1(), etc.
writeDump(o);
o.setX1(10);
o.setY1(20);
WriteOutput(o.getX1() & "
"); // 10
WriteOutput(o.getY1() & "
") ; // 20 

© 2014 Adobe Systems Incorporated. All rights reserved.

1706

Adobe ColdFusion Documentation

GetFunctionList
Description

Displays a list of the functions that are available in ColdFusion.
Returns

A structure of functions.
Category

System functions
Function syntax

GetFunctionList()

Example



#StructCount(fList)# functions




#key#




© 2014 Adobe Systems Incorporated. All rights reserved.

1707

Adobe ColdFusion Documentation

GetGatewayHelper
Description

Gets a Java GatewayHelper object that provides methods and properties for use with a ColdFusion event gateway.
Returns

A Java GatewayHelper object.
Category

Extensibility functions
Function syntax

GetGatewayHelper(gatewayID)

See also

SendGatewayMessage
History

ColdFusion MX 7: Added the function.
Parameters

Parameter

Description

gatewayID

Identifier of the gateway that provides the
GatewayHelper object. Must be the Gateway ID of one
of the ColdFusion event gateway instances configured
on the ColdFusion Administrator Event Gateways
section’s Gateways page.

Usage

The ColdFusion GetGatewayHelper function returns a Java GatewayHelper object that provides event
gateway-specific helper methods and properties. To use this function, the event gateway must provide access to a
class that implements the GatewayHelper class. For example, an instant messaging event gateway might make
buddy-list management functions available in a GatewayHelper object. An event gateway listener CFC can get the g
atewayID value from the CFEvent structure of the incoming message.You access the GatewayHelper object’s
methods and properties using standard ColdFusion Java object access techniques. For more information, see The
role of the GatewayHelper object in the Developing ColdFusion Applications.
Example

If an event gateway’s helper class includes an addBuddy method that takes a single String parameter, you could
use the following code to get the GatewayHelper object and add a buddy to the buddies list:

© 2014 Adobe Systems Incorporated. All rights reserved.

1708

Adobe ColdFusion Documentation

GetGatewayHelper Example

myHelper = getGatewayHelper(myGatewayID);
status = myHelper.addBuddy(“jsmith”);


© 2014 Adobe Systems Incorporated. All rights reserved.

1709

Adobe ColdFusion Documentation

GetHttpRequestData
Description

Makes HTTP request headers and body available to CFML pages. Useful for capturing SOAP request data, which
can be delivered in an HTTP header.
Returns

A ColdFusion structure.
Category

System functions
Function syntax

GetHttpRequestData()

Returns

The function returns a structure that contains the following entries:
Structure element

Description

content

Raw content from form submitted by client, in string or
binary format. For content to be considered string data,
the FORM request header "CONTENT_TYPE" must
start with "text/" or be special case
"application/x-www-form-urlencoded". Other types are
stored as a binary object.

headers

Structure that contains HTTP request headers as value
pairs. Includes custom headers, such as SOAP
requests.

method

String that contains the CGI variable Request_Method.

protocol

String that contains the Server_Protocol CGI variable.

Usage

To determine whether data is binary, use IsBinary(x.content). To convert data to a string value, if it can be
displayed as a string, use ToString(x.content).
Example

The following example shows how this function can return HTTP header information.

© 2014 Adobe Systems Incorporated. All rights reserved.

1710

Adobe ColdFusion Documentation






HTTP Request item
Value
 

#http_item#
#StructFind(x.headers, http_item)#
 


request_method
#x.method#

server_protocol
#x.protocol#

http_content --- #x.content#


© 2014 Adobe Systems Incorporated. All rights reserved.

1711

Adobe ColdFusion Documentation

GetHttpTimeString
Description

Gets the current time, in the Universal Time code (UTC).
Returns

The time, as a string, according to the HTTP standard described in RFC 1123 and its underlying RFC, 822. This
format is commonly used in Internet protocols, including HTTP.
Category

Date and time functions, International functions
Function syntax

GetHttpTimeString(date_time_object)

See also

GetLocale, GetTimeZoneInfo, SetLocale
Parameters

Parameter

Description

date_time_object

A ColdFusion date-time object string or Java Date
object

Usage

The time in the returned string is UTC, consistent with the HTTP standard.
Example


#GetHttpTimeString(now())#


© 2014 Adobe Systems Incorporated. All rights reserved.

1712

Adobe ColdFusion Documentation

GetK2ServerDocCount
Description

This function is deprecated.
Returns

The number of collection metadata items stored in Verity collections.
Category

Full-text search functions, Query functions
Function syntax

GetK2ServerDocCount()

See also

GetK2ServerDocCountLimit
History

ColdFusion MX 6.1: Deprecated this function. It might not work, and it might cause an error, in later releases.
ColdFusion MX: Added this function.
Example

GetK2ServerDocCount =
$*#GetK2ServerDocCount()#*$

© 2014 Adobe Systems Incorporated. All rights reserved.

1713

Adobe ColdFusion Documentation

GetK2ServerDocCountLimit
Description

This function is deprecated.
Returns

Number of collection metadata items that the K2 server permits, as an integer
Category

Full-text search functions, Query functions
Function syntax

GetK2ServerDocCountLimit()

History

ColdFusion MX 6.1: Deprecated this function. It might not work, and it might cause an error, in later releases.
ColdFusion MX: Added this function.
Usage

If a search generates a larger number of documents than the limit, ColdFusion puts a warning message in the
Administrator and in the log file.
Example

GetK2ServerDocCountLimit =
$*#GetK2ServerDocCountLimit()#*$

© 2014 Adobe Systems Incorporated. All rights reserved.

1714

Adobe ColdFusion Documentation

GetLocale
Description

Gets the current ColdFusion geographic/language locale value. To set the default display format of date, time,
number, and currency values in a ColdFusion application session, you use the SetLocale function.
Returns

The current locale value, as an English string. If a locale has a Java name and a name that ColdFusion used prior to
the ColdFusion MX 7 release (for example, en_US and English (US)), ColdFusion returns the ColdFusion name (for
example, English (US)).
Category

Display and formatting functions, International functions, System functions
Function syntax

GetLocale()

See also

GetLocaleDisplayName, SetLocale
History

ColdFusion MX 7: Added support for all Java locales and locale names. ColdFusion MX: Changed behavior to that
described in usage.
Usage

This function returns the locale name as it is represented in ColdFusion; for example, Portuguese (Brazilian), or
ca_ES. To get a locale name in the language of the locale, use the GetLocaleDisplayName function, which
returns português (Brasil) and(Espanya).This function determines whether a locale value is set for ColdFusion. (The
value is set with the SetLocale function.)
If the ColdFusion locale value is present, the function returns it.
If the ColdFusion locale has not been explicitly set, ColdFusion now determines whether the default locale of
the ColdFusion server computer operating system is among the locale values it supports. (The default locale
is stored in the user environment variables user.language and user.region.)If the default locale value is not
supported, the function returns English (US). ColdFusion sets the locale in the JVM to this value; it persists
until the server is restarted or it is reset with the SetLocale function.
This function does not access a web browser’s Accept-Language HTTP header setting.
Note
When ColdFusion is started, it stores the supported locale values in the variable
Server.ColdFusion.SupportedLocales. ColdFusion supports the locales supported by its Java
runtime environment. The SupportedLocales value lists the Java names for the supported locales
and the corresponding names that ColdFusion used prior to the ColdFusion MX 7 release.

© 2014 Adobe Systems Incorporated. All rights reserved.

1715

Adobe ColdFusion Documentation

For more information, see Locales in the Developing ColdFusion Applications.
Example

Example: Using SetLocale and GetLocale


Initial locale's ColdFusion name: #GetLocale()#





Changing locale to #form.mylocale#






New locale: #GetLocale()#




Please select the new locale:



#i#









© 2014 Adobe Systems Incorporated. All rights reserved.

1716

Adobe ColdFusion Documentation

GetLocaleDisplayName
Description

Gets a locale value and displays the name in a manner that is appropriate to a specific locale. By default, gets the
current locale in the current locale’s language.
Returns

The localized display name of the locale, in the language of the specified locale.
Category

Display and formatting functions, International functions, System functions
Function syntax

GetLocaleDisplayName([locale, inLocale])

See also

GetLocale, SetLocale
History

ColdFusion MX 7: Added this function.
Parameters

Parameter

Description

locale

The locale whose name you want. The default is the
current ColdFusion locale, or if no ColdFusion locale
has been set, the JVM locale.

inlocale

The locale in which to return the name. The default is
the current ColdFusion locale, or if no ColdFusion
locale has been set, the JVM locale.

Example

The following example expands on the GetLocale example to show the use of the GetLocaleDisplayName func
tion to display locale names in the current locale and in other locales. It lets you select a locale from all supported
locales, changes the ColdFusion locale to the selected locales, and displays the old and new locale names.

© 2014 Adobe Systems Incorporated. All rights reserved.

1717

Adobe ColdFusion Documentation






Example: Changing and Displaying Locales


Initial locale's ColdFusion name: #GetLocale()#

Initial locale's display name: #GetLocaleDisplayName()#





Changing locale to #form.mylocale#







New locale's ColdFusion name: #newlocale#

New locale's display name in current locale: #GetLocaleDisplayName()#

New locale's display name in old locale:
#GetLocaleDisplayName(newlocale, oldlocale)#

New locale's display name in en_US:
#GetLocaleDisplayName(newlocale, "en_US")#



Old locale's display name in current locale:
#GetLocaleDisplayName(oldlocale)#

Old locale's display name in en_US:
#GetLocaleDisplayName(oldlocale, "en_US")#




Please select the new locale:




#GetLocaleDisplayName(i, "en_US")#











© 2014 Adobe Systems Incorporated. All rights reserved.

1718

Adobe ColdFusion Documentation

GetLocalHostIP
Description

Returns the localhost IP address, which is 127.0.0.1 for IPv4 and :1 for IPv6 addresses.
Returns

The localhost IP address.
Category

Decision functions
Function syntax

GetLocalHostIP()

See also

IsLocalHost
History

ColdFusion MX 7.01: Added this function.
Example

GetLocalHostIP Example
The localhost IP address is #GetLocalHostIP()#.

© 2014 Adobe Systems Incorporated. All rights reserved.

1719

Adobe ColdFusion Documentation

GetMetaData
Description

Gets metadata (such as the methods, properties, and parameters of a component) associated with an object that is
deployed on the ColdFusion server.
Returns

Structured metadata information: for ColdFusion components (CFCs) and user-defined functions (UDFs), a
structure; for query objects, an array of structures.
Category

System functions
Function syntax

GetMetaData(object)

See also

CreateObject, GetComponentMetaData, QueryAddColumn, QueryNew
History

ColdFusion MX 7: Added support for getting query object metadata.
ColdFusion MX: Added this function.
Parameters

Parameter

Description

object

A ColdFusion component, user-defined function, or
query object. Within a CFC, the parameter can also
specify the This scope.

Usage

This function provides information about application data, and lets applications dynamically determine the structure
of an object and how to use it. This function is useful for CFCs and query objects. The metadata for a CFC includes
information on the component and its functions, arguments, and properties. The getMetaData function also returns
metadata for user-defined functions that are not part of CFCs. Use the GetComponentMetaData function to get
information about ColdFusion interfaces, or about CFC definitions that you have not instantiated.The following table
lists the data returned by the function for supported object types:
Object

Field

© 2014 Adobe Systems Incorporated. All rights reserved.

Description

1720

Adobe ColdFusion Documentation

Component

A structure containing the following
fields:

Value of the cfcomponent tag dis
playname attribute, if any.

displayname
extends

Metadata for the component’s
ancestor component. Components
that do not explicitly extend another
component extend the
WEB-INF.cftags.component.

fullname

The dot delimited path from the cf_
webroot of the component.

functions

Array of metadata structures for the
component’s functions.

hint

Value of the cfcomponent tag dis
playname attribute, if any.

implements

A structure containing the metadata
of the interfaces that the component
implements. The key of the
structure is the interface name, and
the value is a structure containing
the interface metadata.

name

Component name, including the
period-delimited path from a
component search root such as the
web root or a directory specified in
the administrator Custom Tag Paths
page.

output

Value of the cfcomponent tag out
put attribute, if any

path

Absolute path to the component.

properties

Array of structures containing
metadata specified by the
component’s cfproperty tags, if
any.

type

Always, component.

userMetadata

User-specified attributes in the cfc
omponent tag

© 2014 Adobe Systems Incorporated. All rights reserved.

1721

Adobe ColdFusion Documentation

function

A structure containing the following
fields.

Value of the cffunction tag acce
ss attribute, if any.

access
displayname

Value of the cffunction tag disp
layname attribute, if any.

hint

Value of the cffunction tag hint
attribute, if any.

name

Function name.

output

Value of the cffunction tag outp
ut attribute, if any.

parameters

Array of structures containing
metadata for the function
parameters.

returnformat

The format in which to return values
to a remote caller. This attribute has
no effect on values returned to a
local caller.

returntype

Value of the cffunction tag retu
rntype attribute, if any.

roles

Value of the cffunction tag outp
ut attribute, if any.

userMetadata

User-specified attributes in the cff
unction tag.

Parameter or Property

A structure containing the following
fields:

Value of the cfargument or cfpr
operty tag default attribute, if
any.

default
displayname

Value of the cfargument or cfpr
operty tag displayname attribut
e, if any.

hint

Value of the cfargument or cfpr
operty tag hint attribute, if any.

name

Function parameter or CFC
property name.

© 2014 Adobe Systems Incorporated. All rights reserved.

1722

Adobe ColdFusion Documentation

required

Value of the cfargument or cfpr
operty tag required attribute, if
any.

type

Value of the cfargument or cfpr
operty tag type attribute, if any.

userMetadata

User-specified attributes in the arg
ument tag.

Query

An array of structures containing
the following elements:

Boolean value indicating whether
character data must be case
correct.

IsCaseSensitive
name

The column name.

TypeName

The SQL data type (Omitted if the
query object is created with
QueryNew without specifying
types.)

Note
Use the This scope to access component metadata inside the CFC. The This scope is available
at runtime in the component body and in the CFC methods. It is used to read and write variables
that are present during the life of the component.

For more information, see Using introspection to get information about components in the Developing ColdFusion
Applications.
Example

The following example uses the cfdump tag to display metadata for the utilities CFC that is used by the ColdFusion
component browser. It also displays the names and data types of the fields in the cfdocexamples database
Employees table.

© 2014 Adobe Systems Incorporated. All rights reserved.

1723

Adobe ColdFusion Documentation



componentutils = createObject("component", "cfide.componentutils.utils");
utilmetadata = getMetaData(componentutils);

Metadata for the CFC component utilities



SELECT *
FROM Employees


The Employees table has the following columns


#employeemeta[i].name# #employeemeta[i].TypeName#
#employeemeta[i].isCaseSensitive#




© 2014 Adobe Systems Incorporated. All rights reserved.

1724

Adobe ColdFusion Documentation

GetMetricData
Description

Gets server performance metrics.
Returns

ColdFusion structure that contains metric data, depending on the mode value.
Category

System functions
Function syntax

GetMetricData(mode)

History

ColdFusion MX: Deprecated the cachepops parameter. It might not work, and it might cause an error, in later
releases.
Parameters

Parameter

Option

Description

mode

perf_monitor

Returns internal data, in a
structure.To receive data, enable
PerfMonitor in ColdFusion
Administrator before executing the
function. On Windows, this data is
otherwise displayed in the Windows
PerfMonitor.

simple_load

Returns an integer value that is
computed from the state of the
server's internal queues. Indicates
the overall server load.

prev_req_time

Returns the time, in milliseconds,
that it took the server to process the
previous request.

© 2014 Adobe Systems Incorporated. All rights reserved.

1725

Adobe ColdFusion Documentation

Returns the average time, in
milliseconds, that it takes the server
to process a request.Changing the
setting to 0 prevents the server from
calculating the average and
removes overhead associated with
gathering data.The default value is
120 seconds.

avg_req_time

Usage

If mode = "perf_monitor", the function returns a structure with these data fields:
Field

Description

InstanceName

The name of the ColdFusion server. The default value
is cfserver.

PageHits

Number of HTTP requests received since ColdFusion
was started.

ReqQueued

Number of HTTP requests in the staging queue, waiting
for processing.

DBHits

Number of database requests since the server was
started.

ReqRunning

Number of HTTP requests currently running. In the
ColdFusion Administrator, you can set the maximum
number of requests that run concurrently.

ReqTimedOut

Number of HTTP requests that timed out while in the
staging queue or during processing.

BytesIn

Number of bytes in HTTP requests to ColdFusion.

BytesOut

Number of bytes in HTTP responses from ColdFusion.

AvgQueueTime

For the last two HTTP requests (current and previous),
the average length of time the request waited in the
staging queue.

AvgReqTime

For the last two HTTP requests (current and previous),
the average length of time the server required to
process the request

AvgDBTime

For the last two HTTP requests (current and previous),
the average length of time the server took to process
CFQueries in the request.

© 2014 Adobe Systems Incorporated. All rights reserved.

1726

Adobe ColdFusion Documentation

cachepops

This parameter is deprecated. ColdFusion
automatically sets its value to -1.

Example




Current PerfMonitor data is: 

InstanceName: #pmData.InstanceName# 

PageHits: #pmData.PageHits# 

ReqQueued:
#pmData.ReqQueued# 

DBHits: #pmData.DBHits# 

ReqRunning:
#pmData.ReqRunning# 

ReqTimedOut: #pmData.ReqTimedOut# 

BytesIn:
#pmData.BytesIn# 

BytesOut:
#pmData.BytesOut# 

AvgQueueTime: #pmData.AvgQueueTime# 

AvgReqTime:
#pmData.AvgReqTime# 

AvgDBTime:
#pmData.AvgDBTime# 



© 2014 Adobe Systems Incorporated. All rights reserved.

1727

Adobe ColdFusion Documentation

GeneratePBKDFKey
GeneratePBKDFKey has been added in ColdFusion 11 to allow users to support PBKDF2 key derivation.

Returns

A string that contains the encryption key.
History

ColdFusion 11: Added this function
Category

Security functions, String functions
Function syntax

GeneratePBKDFKey(String algorithm, String
string, String salt, int iterations, int
keysize)
Parameters

Parameter

Description

algorithm

The encryption algorithm for which to generate the key.
The supported algorithms are
PBKDF2WithHmacSHA1, PBKDF2WithSHA1,
PBKDF2WithSHA224, PBKDF2WithSHA256,
PBKDF2WithSHA384, PBKDF2WithSHA512

string

The string to be used for conversion

salt

A random salt. The standard recommends a salt length
of at least 64 bits (8 characters). The salt needs to be
generated using a pseudo random number generator
(e.g SHA1PRNG).

iterations

The number of PBKDEF iterations to perform. The reco
mmended value for iterations is 1000 or more.

keysize

The key size in number of bits.

Example
Encryption using PBKDF2:

© 2014 Adobe Systems Incorporated. All rights reserved.

1728

Adobe ColdFusion Documentation


salt="A41n9t0Q";
password = "Password@123";
PBKDFalgorithm = "PBKDF2WithSHA224";
dataToEncrypt= "Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do
eiusmod tempor incididunt ut labore et dolore magna aliqua";
encryptionAlgorithm = "AES";
derivedKey = GeneratePBKDFKey(PBKDFalgorithm ,password ,salt,4096,128);
writeOutput("Generated PBKDFKey (Base 64) : " & derivedKey);
encryptedData = encrypt(dataToEncrypt, derivedKey, encryptionAlgorithm, "BASE64");
writeoutput("Data After Encryption using PBKDF2: " & encryptedData);


Decryption using PBKDF2:


salt="A41n9t0Q";
password = "Password@123";
PBKDFalgorithm = "PBKDF2WithSHA224";
derivedKey = GeneratePBKDFKey(PBKDFalgorithm ,password ,salt,4096,128);
decryptedData = decrypt(encryptedData, derivedKey, encryptionAlgorithm, "BASE64");
writeoutput("Data After Decryption using PBKDF2: " & decryptedData);


© 2014 Adobe Systems Incorporated. All rights reserved.

1729

Adobe ColdFusion Documentation

GetPageContext
Description

Gets the current ColdFusion PageContext object that provides access to page attributes and configuration, request,
and response objects.
Returns

The current ColdFusion Java PageContext Java object.
Category

System functions
Function syntax

GetPageContext()

History

ColdFusion MX: Added this function.
Usage

The ColdFusion PageContext class is a wrapper class for the Java PageContext object that can resolve scopes and
perform case-insensitive variable lookups.The PageContext object exposes fields and methods that can be useful in
J2EE integration. It includes the include and forward methods that provide the equivalent of the corresponding
standard JSP tags. You use these methods to call JSP pages and servlets. For example, you use the following code
in CFScript to include the JSP page hello.jsp and pass it a name parameter:

GetPageContext().include("hello.jsp?name=Bobby"); ===

When you use GetPageContext to include a JSP page in a CFML page on WebLogic, you may need to flush the
output of the CFML page with cfflush before calling the JSP page. Otherwise, the ColdFusion output appears
after the JSP output.The methods supported on the returned PageContext are only the ones mandated by the JSP
specification. To look up scopes by name, use the StructGet function, for example:




For more information, see your Java Server Pages (JSP) documentation.On WebLogic, you may need to flush the
output of the CFML page (using cfflush) before calling a JSP page. If you do not, the ColdFusion output appears
after the JSP output.On JBOSS, if you use this function and you include any JSP file, the content of the JSP file is
processed prior to the processing of any CFML tags before the function.
Example

© 2014 Adobe Systems Incorporated. All rights reserved.

1730

Adobe ColdFusion Documentation




name: #variables.name#

Language of the current locale is
#pc.getRequest().getLocale().getDisplayLanguage()#.

© 2014 Adobe Systems Incorporated. All rights reserved.

1731

Adobe ColdFusion Documentation

GetPrinterInfo

Description

Determines which print attributes are supported by a selected printer.
Returns

A structure that contains the attributes supported by the printer. If the printer is not specified, the structure contains
attributes supported by the default printer, if one exists.
Category

System functions
Function syntax

GetPrinterInfo("printer")

See also

cfpdf, cfprint
History

ColdFusion 8: Added this function.
Parameters

Parameter

Description

printer

The name of a printer. An example in Windows is
“\\s1001prn02\NTN-2W-HP_BW02”. The default is the
default printer for the account where the ColdFusion
server is running. Printer names are case sensitive and
must be entered exactly as they appear in the System
Information page of the ColdFusion Administrator.
If you specify an empty string, for example GetPrinte
rInfo(""), ColdFusion generates an error. Use the
following code to retrieve information on the default
printer:{{ GetPrinterInfo().}}

Usage

Use this function in conjunction with the cfprint tag when processing large print jobs. Not all printers support the
complete list of print attributes allowed by the cfprint tag. If the selected printer does not support a print attribute,
the printer ignores the attribute.In Windows systems, the account running the ColdFusion server must have PRINTE

© 2014 Adobe Systems Incorporated. All rights reserved.

1732

Adobe ColdFusion Documentation

R_ACCESS_USE access rights for each printer it uses. Even if the printer is configured locally on the system, the
printer is not available if the account in which ColdFusion is running does not have the proper permissions.For more
information on attributeStruct, see cfprint.
Example






© 2014 Adobe Systems Incorporated. All rights reserved.

1733

Adobe ColdFusion Documentation

GetPrinterList
Description

Gets the list of printers that are accessible by ColdFusion server.
Returns

A list of accessible printers.
Category

System functions
Function Syntax

getPrinterList()

See Also

cfpdf, cfprint
History

ColdFusion 8: Added this function.
Usage

Ensure that you run ColdFusion server using an account that has appropriate permissions to access all desired
printers.

© 2014 Adobe Systems Incorporated. All rights reserved.

1734

Adobe ColdFusion Documentation

GetProfileSections
Description

Gets all the sections of an initialization file. An initialization file assigns values to configuration variables, also known
as entries, that are set when the system boots, the operating system comes up, or an application starts. An
initialization file has the suffix INI; for example, boot.ini, Win32.ini.
Returns

An initialization file, as a structure whose format is as follows:
Each initialization file section name is a key in the structure
Each list of entries in a section of an initialization file is a value in the structure
If there is no value, returns an empty string.
History

ColdFusion 11: Added this function
Category

System functions
Function syntax

GetProfileSections(iniFile, [encoding])

See also

GetProfileString, SetProfileString
History

ColdFusion 11: Added the optional parameter, encoding.
ColdFusion MX: Added this function.
Parameters

Parameter

Description

iniFile

Absolute path (drive, directory, filename, extension) of
initialization file; for example, C:\boot.ini

encoding

(Optional) Encoding of the initialization (ini) file. For
instance "UTF-8" For a list of encodings, see cffile
action = "read".

Example

© 2014 Adobe Systems Incorporated. All rights reserved.

1735

Adobe ColdFusion Documentation

GetProfileSections(expandPath("./russian.ini"),"UTF-8");

© 2014 Adobe Systems Incorporated. All rights reserved.

1736

Adobe ColdFusion Documentation

GetProfileString
Description

Gets an initialization file entry. An initialization file assigns values to configuration variables, also known as entries,
that are set when the system boots, the operating system comes up, or an application starts. An initialization file has
the suffix INI; for example, boot.ini, Win32.ini.
Returns

An entry in an initialization file, as a string. If there is no value, returns an empty string.
History

ColdFusion 11: Added the encoding attribute.
Category

System functions
Function syntax

GetProfileString(iniPath, section, entry, [encoding])

See also

GetProfileSections, SetProfileString
Parameters

Parameter

Description

iniPath

Absolute path (drive, directory, filename, extension) of
initialization file; for example, C:\boot.ini

section

Section of initialization file from which to extract
information

entry

Name of value to get

encoding

Encoding of the initialization (ini) file. For instance
"UTF-8". For a list of encodings, see cffile action =
"read"

Example

© 2014 Adobe Systems Incorporated. All rights reserved.

1737

Adobe ColdFusion Documentation

GetProfileString Example
Uses GetProfileString to get the value of timeout in an initialization file. Enter
the full path of your initialization file, and submit the form.





Boot Loader

Timeout is set to: #timeout#.




Full Path of Init File









© 2014 Adobe Systems Incorporated. All rights reserved.

1738

Adobe ColdFusion Documentation

GetReadableImageFormats
Description

Returns a list of image formats that ColdFusion can read on the operating system where ColdFusion is deployed.
Returns

A list of image file formats.
Category

System functions
History

ColdFusion 8: Added this function.
Function syntax

GetReadableImageFormats()

See also

GetWriteableImageFormats, cfimage (for supported image file formats)
Usage

Use this function to determine image file compatibility on the ColdFusion server.
Example

#GetReadableImageFormats()#

© 2014 Adobe Systems Incorporated. All rights reserved.

1739

Adobe ColdFusion Documentation

GetSOAPRequest
Description

Returns an XML object that contains the entire SOAP request. Usually called from within a web service CFC.
Returns

An XML object that contains the entire SOAP request.
Category

XML functions
History

ColdFusion MX 7: Added this function.
Function syntax

GetSOAPRequest()

See also

AddSOAPRequestHeader, AddSOAPResponseHeader, GetSOAPRequestHeader, GetSOAPResponse, GetSOA
PResponseHeader, IsSOAPRequest; Basic web service concepts in the Developing ColdFusion Applications
Parameters

Parameter

Description

webservice

Optional. A webservice object as returned from the c
fobject tag or the CreateObject function.Required
if the function is called from the client.

Usage

Call this function to obtain a web service request object after the web service has been invoked. If you call this
function from outside a web service CFC without the webservice parameter, it throws the following expression
error:

Unable to use getSOAPRequest: not processing a web service request.

If you call this function from within a web service CFC, you can omit the webservice argument. The function
executes against the request that it is currently processing.You can use CFML XML functions to examine the
returned XML object.
Example

This example makes a request to execute the echo_me function of the headerservice.cfc web service. For

© 2014 Adobe Systems Incorporated. All rights reserved.

1740

Adobe ColdFusion Documentation

information on implementing the headerservice.cfc web service and also to see the echo_me function and the
content of the web service CFC, see the example for either the AddSOAPResponseHeader function or the GetSOA
PRequestHeader function.



ws = CreateObject("webservice",
"http://localhost/soapheaders/headerservice.cfc?WSDL");
ws.echo_me("hello world");
req = getSOAPRequest(ws);



© 2014 Adobe Systems Incorporated. All rights reserved.

1741

Adobe ColdFusion Documentation

GetSOAPRequestHeader
Description

Obtains a SOAP request header. Call only from within a CFC web service function that is processing a request as a
SOAP web service.
Returns

A SOAP request header.
Category

XML functions
History

ColdFusion MX 7: Added this function.
Function syntax

GetSOAPRequestHeader(namespace, name [, asXML])

See also

AddSOAPRequestHeader, AddSOAPResponseHeader, GetSOAPRequest, GetSOAPResponse, GetSOAPRespo
nseHeader, IsSOAPRequest; Basic web service concepts in the Developing ColdFusion Applications
Parameters

Parameter

Description

namespace

A String that is the namespace for the header.

name

A String that is the name of the header.

asXML

If true, the header is returned as a CFML XML object; if
false (default), the header is returned as a Java object.

Usage

If you specify false for the asXML parameter, ColdFusion first attempts to retrieve the header using the data type
specified in the header’s xsi:type attribute. If the xsi:type attribute is not available, ColdFusion attempts to
retrieve the header as a string. If you specify true for the asXML parameter, ColdFusion retrieves the header as
raw XML.This function throws an error if it is invoked in a context that is not a web service request. Use the IsSOAP
Request function to determine whether the CFC is running as a web service.
Example

This example creates a CFC web service that illustrates the operation of the GetSOAPRequestHeader function
and also provides a web service that illustrates the operation of other ColdFusion SOAP functions. Save the

© 2014 Adobe Systems Incorporated. All rights reserved.

1742

Adobe ColdFusion Documentation

following code as headerservice.cfc in a folder called soapheaders under your web root. Test its operation, and
specifically the operation of the GetSOAPRequestHeader function, by executing the examples that invoke this web
service. For example, see the example for AddSOAPRequestHeader.

GetSOAPRequestHeader Example









 as XML: " & xmlusername>




 as XML: " & xmlpassword>
















© 2014 Adobe Systems Incorporated. All rights reserved.

1743

Adobe ColdFusion Documentation

© 2014 Adobe Systems Incorporated. All rights reserved.

1744

Adobe ColdFusion Documentation

GetSOAPResponse
Description

Returns an XML object that contains the entire SOAP response after invoking a web service.
Returns

An XML object that contains the entire SOAP response.
Category

XML functions
History

ColdFusion MX 7: Added this function.
Function syntax

GetSOAPResponse(webservice)

See also

AddSOAPRequestHeader, AddSOAPResponseHeader, GetSOAPRequest, GetSOAPRequestHeader, GetSOAP
ResponseHeader, IsSOAPRequest; Basic web service concepts in the Developing ColdFusion Applications
Parameters

Parameter

Description

webservice

A webservice object as returned from the cfobject ta
g or the CreateObject function.

Usage

Invoke the web service before attempting to get the response. You can use CFML XML functions to examine the
XML response.
Example

This example makes a request to execute the echo_me function of the headerservice.cfc web service. Following the
request, the example calls the GetSOAPResponse function to get the SOAP response, and then calls cfdump to
display its content. for information on implementing the headerservice.cfc web service and also to see the echo_me
function and the content of the web service CFC, see the example for either the AddSOAPResponseHeader functio
n or the GetSOAPRequestHeader function.

© 2014 Adobe Systems Incorporated. All rights reserved.

1745

Adobe ColdFusion Documentation



ws = CreateObject("webservice",
"http://localhost/soapheaders/headerservice.cfc?WSDL");
ws.echo_me("hello world");
resp = getSOAPResponse(ws);



© 2014 Adobe Systems Incorporated. All rights reserved.

1746

Adobe ColdFusion Documentation

GetSOAPResponseHeader
Description

Returns a SOAP response header. Call this function from within code that is invoking a web service after making a
web service request.
Returns

A SOAP response header.
Category

XML functions
History

ColdFusion MX 7: Added this function.
Function syntax

GetSOAPResponseHeader(webservice, namespace, name [, asXML])

See also

AddSOAPRequestHeader, AddSOAPResponseHeader, GetSOAPRequest, GetSOAPRequestHeader, GetSOAP
Response, IsSOAPRequest; Basic web service concepts in the Developing ColdFusion Applications
Parameters

Parameter

Description

webservice

A webservice object as returned from the cfobject ta
g or the CreateObject function.

namespace

A String that is the namespace for the header.

name

A String that is the name of the SOAP header.

asXML

If True, the header is returned as a CFML XML object.
If False (default), the header is returned as a Java
object.

Usage

If you specify false for the asXML parameter, ColdFusion first attempts to retrieve the header using the data type
specified in the header’s type attribute. If the type attribute is not available, ColdFusion attempts to retrieve the
header as a string. If you specify true for the asXML parameter, ColdFusion retrieves the header as raw XML.Used
within CFML code by a consumer of a web service after it calls the web service with cfinvoke.
Example

© 2014 Adobe Systems Incorporated. All rights reserved.

1747

Adobe ColdFusion Documentation

There are two parts to this example. The first part is the web service CFC that this function (as well as the other
ColdFusion SOAP functions) uses to demonstrate its interaction with a web service. To implement the web service
for this function, see the example for either the AddSOAPResponseHeader function or the GetSOAPRequestHead
er function.Execute the following example to see how the GetSOAPResponseHeader function operates:


GetSOAPResponseHeader Example

// Create the web service object
ws = CreateObject("webservice",
"http://localhost/soapheaders/headerservice.cfc?WSDL");
// Set the username header as a string
addSOAPRequestHeader(ws, "http://mynamespace/", "username", "tom", false);
// Set the password header as a CFML XML object
doc = XmlNew();
doc.password = XmlElemNew(doc, "http://mynamespace/", "password");
doc.password.XmlText = "My Voice is my Password";
doc.password.XmlAttributes["xsi:type"] = "xsd:string";
addSOAPRequestHeader(ws, "ignoredNameSpace", "ignoredName", doc);
// Invoke the web service operation
ret = ws.echo_me("argument");
// Get the first header as an object (string) and as XML
header = getSOAPResponseHeader(ws, "http://www.tomj.org/myns", "returnheader");
XMLheader = getSOAPResponseHeader(ws, "http://www.tomj.org/myns", "returnheader",
true);
// Get the second header as an object (string) and as XML
header2 =getSOAPResponseHeader(ws, "http://www.tomj.org/myns", "returnheader2");
XMLheader2 = getSOAPResponseHeader(ws, "http://www.tomj.org/myns", "returnheader2",
true);



Soap Header value: #HTMLCodeFormat(header)#

Soap Header XML value: #HTMLCodeFormat(XMLheader)#

Soap Header 2 value: #HTMLCodeFormat(header2)#

Soap Header 2 XML value: #HTMLCodeFormat(XMLheader2)#

Return value: #HTMLCodeFormat(ret)#





Cfinvoke returned: #ret#

© 2014 Adobe Systems Incorporated. All rights reserved.

1748

Adobe ColdFusion Documentation

GetSystemFreeMemory
Description

Gets details of free memory.
Returns

Memory, in bytes, that is currently free.
Syntax

getSystemFreeMemory()

© 2014 Adobe Systems Incorporated. All rights reserved.

1749

Adobe ColdFusion Documentation

GetSystemTotalMemory
Description

Gets details of the memory that is available for the operating system, in bytes.
Returns

Memory that is available in bytes.
Syntax

getSystemTotalMemory()

© 2014 Adobe Systems Incorporated. All rights reserved.

1750

Adobe ColdFusion Documentation

GetTempFile
Description

Creates a temporary file in a directory whose name starts with (at most) the first three characters of prefix.
Returns

Name of a temporary file, as a string.
Category

System functions
Function syntax

GetTempFile(dir, prefix)

See also

getTempDirectory
Parameters

Parameter

Description

dir

Directory name

prefix

Prefix of a temporary file to create in the dir directory

Example

GetTempFile Example
The temporary directory for this ColdFusion Server is
#GetTempDirectory()#.
We have created a temporary file called:
#GetTempFile(GetTempDirectory(),"testFile")#

© 2014 Adobe Systems Incorporated. All rights reserved.

1751

Adobe ColdFusion Documentation

GetTemplatePath
Description

This function is deprecated. Use the GetBaseTemplatePath function instead.Gets the absolute path of an
application’s base page.
History

ColdFusion MX: Deprecated this function. It might not work, and it might cause an error, in later releases.

© 2014 Adobe Systems Incorporated. All rights reserved.

1752

Adobe ColdFusion Documentation

GetTickCount
Description

Returns the current value of an internal millisecond timer.
Returns

A string representation of the system time, in milliseconds.
Category

Date and time functions, System functions
Function syntax

GetTickCount()

Usage

This function is useful for timing CFML code segments or other page processing elements. The value of the counter
has no meaning. To generate useful timing values, take the difference between the results of two GetTickCount c
alls.
Example









Loop time (#iterationCount# iterations) was: #loopTime#
milliseconds

© 2014 Adobe Systems Incorporated. All rights reserved.

1753

Adobe ColdFusion Documentation

GetTimeZoneInfo
Description

Gets local time zone information for the computer on which it is called, relative to Universal Time Coordinated
(UTC). UTC is the mean solar time of the meridian of Greenwich, England, used as the basis for calculating
standard time throughout the world.
ColdFusion stores date and time values as date-time objects: real numbers on a universal time line. It converts an
object to a time zone when it formats an object; it converts a date/time value from a time zone to a real number
when it parses a value.
Returns

Structure that contains these elements and keys:
utcTotalOffset: offset of local time, in seconds, from UTC
A plus sign indicates a time zone west of UTC (such as a zone in North America)
A minus sign indicates a time zone east of UTC (such as a zone in Germany)
utcHourOffset: offset, in hours of local time, from UTC
utcMinuteOffset: offset, in minutes, beyond the hours offset. For North America, this is 0. For countries that
are not exactly on the hour offset, the number is from 0 through 60. For example, standard time in Adelaide,
Australia is offset 9 hours and 30 minutes from UTC.
isDSTOn: True, if Daylight Savings Time (DST) is on in the host; False, otherwise
Category

Date and time functions, International functions
Function syntax

GetTimeZoneInfo()

See also

DateConvert, CreateDateTime, DatePart
Example

© 2014 Adobe Systems Incorporated. All rights reserved.

1754

Adobe ColdFusion Documentation

GetTimeZoneInfo Example


The local date and time are #now()#.



Total offset in seconds is #info.utcTotalOffset#.
Offset in hours is #info.utcHourOffset#.
Offset in minutes minus the offset in hours is
#info.utcMinuteOffset#.
Is Daylight Savings Time in effect? #info.isDSTOn#.


© 2014 Adobe Systems Incorporated. All rights reserved.

1755

Adobe ColdFusion Documentation

GetToken
Description

Determines whether a token of the list in the delimiters parameter is present in a string.
Returns

The token found at position index of the string, as a string. If index is greater than the number of tokens in the string,
returns an empty string.
Category

String functions
Function syntax

GetToken(string, index

[, delimiters ])

See also

Left, Right, Mid, SpanExcluding, SpanIncluding
Parameters

Parameter

Description

string

A string or a variable that contains one. String in which
to search.

index

Positive integer or a variable that contains one. The
position of a token.

delimiters

A string or a variable that contains one. A delimited list
of delimiters. Elements may consist of multiple
characters.Default list of delimiters: space character,
tab character, newline character; or their codes:
"chr(32)", "chr(9)", chr(10). Default list delimiter: comma
character.

Usage

The following examples show how this function works.
Example 1

In the following example, the function call requests element number 2 from the string, using the delimiter " [:;".

GetToken("red,blue:;red,black,tan:;red,pink,brown:;red,three", 2, ":;")

© 2014 Adobe Systems Incorporated. All rights reserved.

1756

Adobe ColdFusion Documentation

The output is as follows:

red,black,tan

Example 2



#HTMLCodeFormat(mystring)#




The output is as follows:

four,
,five, nine,zero:;
nine,ten:, eleven:;twelve:;thirteen,
,four

The GetToken function recognizes explicit spaces, tabs, or newline characters as the parameter delimiters. (To
specify a space character, the code is chr(32); a tab character, chr(9); and a newline character, chr(10).)In
the example string mystring, there is:
A forced space between the substrings "four," }}and{{ ",five"
A literal space between "five," and "nine"
A literal space between "ten:," and "eleven,"
A forced space between "thirteen," and ",four"
In the following call against mystring, no spaces are specified in delimiters (it is omitted), so the function uses
the space character as the string delimiter:




GetToken(mystring, 3) is : #GetToken(mystring, 3)#



The output of this code is as follows:

© 2014 Adobe Systems Incorporated. All rights reserved.

1757

Adobe ColdFusion Documentation

GetToken(mystring, 3) is : nine,zero:;

The function finds the third delimiter, and returns the substring just before it that is between the second and third
delimiter. This substring is ";".
Example 3



#HTMLCodeFormat(mystring2)#



The output is as follows:

four,
,five,nine,zero:;
nine,ten:,eleven:;twelve:;thirteen,
,four

The following is a call against mystring2:


GetToken(mystring2, 2) is : #GetToken(mystring2, 2)#


The output is as follows:

GetToken(mystring2, 2) is : ,five,nine,zero:;

The function finds the second delimiter, and returns the substring just before it that is between the first and second
delimiter. This substring is ",five,nine,zero:;".
Example

© 2014 Adobe Systems Incorporated. All rights reserved.

1758

Adobe ColdFusion Documentation

GetToken Example










Element #FORM.ReturnElement# in #FORM.yourString#,
delimited by "#yourDelimiter#"

is:#GetToken(FORM.yourString, FORM.returnElement, yourDelimiter)#

...

© 2014 Adobe Systems Incorporated. All rights reserved.

1759

Adobe ColdFusion Documentation

GetTotalSpace
Description

Returns the total hard disk space or in-memory space available for an application.
Returns

Total space in bytes
Category

System functions
See also

getVFSMetadata
Syntax

getTotalSpace(path)
Parameters

Parameter

Description

path

Path to the
Hard disk drive, for example C: for Windows or /
}}for UNIX. Note that for Windows, you
have to explicitly use colon ({{:) and
not just C. Only the space of the entire hard disk
drive is returned. If you mention a directory in the
path, for example, /opt/, it is ignored and only {{/
}}is considered.
For in-memory file system, the path is ram:.

Usage

Application memory is determined by the following settings for RAM:
In the ColdFusion Administrator, the value specified for Memory Limit per Application for In-Memory Virtual
File System (Server Settings > Settings). The default value is 20 MB.
The value specified in the Application.cfc for this.inmemoryfilesystem.size
If you have set values in both the places, the lesser value is considered.
Note
Even if the value specified in Application.cfc is lesser, ensure that Server Settings > Settings >
Enable In-Memory File System is checked in the ColdFusion Administrator.

Example

© 2014 Adobe Systems Incorporated. All rights reserved.

1760

Adobe ColdFusion Documentation

See the example for GetFreeSpace.

© 2014 Adobe Systems Incorporated. All rights reserved.

1761

Adobe ColdFusion Documentation

GetUserRoles
Description

Retrieves the list of roles for the current user. This function returns only ColdFusion roles, not roles set for the
servlet API.
Returns

The list of roles for the current user.
Category

Security functions
Function syntax

GetUserRoles()

See also

cflogin, cfloginuser, cflogout, GetAuthUser, IsUserInAnyRole, IsUserInRole, IsUserLoggedIn, S
ecuring Applications in the Developing ColdFusion Applications
History

ColdFusion 8: Added this function.
Example



© 2014 Adobe Systems Incorporated. All rights reserved.

1762

Adobe ColdFusion Documentation

GetVFSMetaData
Description

Gets in-memory virtual file system metadata.
Returns

A structure that contains information about in-memory virtual file system.
Category

System functions
Function syntax

getVFSMetaData (fileSystemType)
See also

Working with in-memory files in the Developing ColdFusion Applications.
History

ColdFusion 9: Added this function
Parameters

Parameter

Description

fileSystemType

The in-memory file system type. ColdFusion 9 supports
only RAM.

Usage

The function returns a structure with the following keys:
Parameter

Description

Enabled

If support for in-memory virtual file system is enabled.
This is the only key that is returned within the structure
if in-memory virtual file system is disabled.

Limt

The memory limit in bytes for in-memory virtual file
system.

Used

The memory out of the specified memory limit that is in
use (in bytes).

Free

The free memory in bytes.

Example

© 2014 Adobe Systems Incorporated. All rights reserved.

1763

Adobe ColdFusion Documentation








The example works only if in-memory virtual file system is enabled.

© 2014 Adobe Systems Incorporated. All rights reserved.

1764

Adobe ColdFusion Documentation

GetWriteableImageFormats
Description

Returns a list of image formats that ColdFusion can write on the operating system where ColdFusion is deployed.
Returns

A list of image file formats.
Category

System functions
History

ColdFusion 8: Added this function.
Function syntax

GetWriteableImageFormats()

See also

GetReadableImageFormats, cfimage (for supported image file formats)
Usage

Use this function to determine image file compatibility on the ColdFusion server.
Example

#GetWriteableImageFormats()#

#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

1765

Adobe ColdFusion Documentation

GetSafeHTML
getSafeHTML() sanitizes the given input string based on the the rules specified in an antisamy policy file. This can
be used to prevent unwanted user supplied HTML being used in an application.
Returns

Returns the sanitized input. If throwOnError is set to true, it returns an error. Otherwise, it returns an empty string.
Returns

ColdFusion 11: Added this function
See Also

isSafeHTML
Parameter

Parameter

Description

inputString

Required. The string to be encoded.

PolicyFile

Optional. File path for antisamy policy file which
specifies HTML rules. In case if not specified, there is a
provision to set this at application level. Else the default
policy file shipped with ColdFusion will be used.

throwOnError

Optional. If set to true, exception is thrown.

Example

The following example illustrates a sample Antisamy component:





The following example illustrates isSafeHTML and getSafeHTML validation.
In the example, the input HTML file is a GIF image. On processing it through the functions (isSafeHTML,
getSafeHTML), checks if the given input string violates the rules specified in antiSamy policy file and returns true if
the input does not violate the allowed HTML rules.



 is Safe
: #isSafe# Safe HTML : #SafeHTML#

© 2014 Adobe Systems Incorporated. All rights reserved.



1766

Adobe ColdFusion Documentation

© 2014 Adobe Systems Incorporated. All rights reserved.

1767

Adobe ColdFusion Documentation

EncodeForXMLAttribute
Description

Encodes a string that can be used as an XML attribute.
Returns

Encoded XML string.
Category

Display and formatting functions.
Function syntax

encodeForXMLAttribute(String inputString, boolean canonicalize)

See also
Canonicalize,EncodeForHTMLAttribute,EncodeForJavaScript,EncodeForCSS,EncodeForURL
History

ColdFusion 11: Added this function.
Parameters

Parameter

Description

inputString

Required. The string to encode.

canonicalize

Optional. If set to true, canonicalization happens before
encoding. If set to false, the given input string will just
be encoded. The default value for canonicalize is false.
When this parameter is not specified, canonicalization
will not happen. By default, when canonicalization is
performed, both mixed and multiple encodings will be
allowed. To use any other combinations you should
canonicalize using canonicalize method and then do
encoding.

Example

© 2014 Adobe Systems Incorporated. All rights reserved.

1768

Adobe ColdFusion Documentation



#x#

")>
#x#


#x#

© 2014 Adobe Systems Incorporated. All rights reserved.

1769

Adobe ColdFusion Documentation

EncodeForXpath
Description

Returns an encoded string for using with XPATH.
Returns

Encoded XML string.
Category

Display and formatting functions.
Function syntax

encodeForXpath(String inputString, boolean canonicalize)

See also

Canonicalize,EncodeForHTMLAttribute,EncodeForJavaScript,EncodeForCSS,EncodeForURL
History

ColdFusion 11: Added this function.
Parameters

Parameter

Description

inputString

Required. The string to encode.

canonicalize

Optional. If set to true, canonicalization happens before
encoding. If set to false, the given input string will just
be encoded. The default value for canonicalize is false.
When this parameter is not specified, canonicalization
will not happen. By default, when canonicalization is
performed, both mixed and multiple encodings will be
allowed. To use any other combinations you should
canonicalize using canonicalize method and then do
encoding.

Example

© 2014 Adobe Systems Incorporated. All rights reserved.

1770

Adobe ColdFusion Documentation



#x#

© 2014 Adobe Systems Incorporated. All rights reserved.

1771

Adobe ColdFusion Documentation

Functions h-im
Hash
HMac
HQLMethods
Hour
HTMLCodeFormat
HTMLEditFormat
IIf
ImageAddBorder
ImageBlur
ImageClearRect
ImageCopy
ImageCreateCaptcha
ImageCrop
ImageDrawArc
ImageDrawBeveledRect
ImageDrawCubicCurve
ImageDrawLine
ImageDrawLines
ImageDrawOval
ImageDrawPoint
ImageDrawQuadraticCurve
ImageDrawRect
ImageDrawRoundRect
ImageDrawText
ImageFlip
ImageGetBlob
ImageGetBufferedImage
ImageGetEXIFMetadata
ImageGetEXIFTag
ImageGetHeight
ImageGetIPTCMetadata
ImageGetIPTCTag
ImageGetWidth
ImageGrayscale
ImageInfo
ImageMakeColorTransparent
ImageMakeTranslucent
ImageNegative
ImageNew
ImageOverlay
ImagePaste
ImageRead
ImageReadBase64
ImageResize
ImageRotate
ImageRotateDrawingAxis
ImageScaleToFit
ImageSetAntialiasing
ImageSetBackgroundColor
ImageSetDrawingColor

© 2014 Adobe Systems Incorporated. All rights reserved.

1772

Adobe ColdFusion Documentation

ImageSetDrawingStroke
ImageSetDrawingTransparency
ImageSharpen
ImageShear
ImageShearDrawingAxis
ImageTranslate
ImageTranslateDrawingAxis
ImageWrite
ImageWriteBase64
ImageXORDrawingMode
ImageGetMetadata

© 2014 Adobe Systems Incorporated. All rights reserved.

1773

Adobe ColdFusion Documentation

Hash
Description

Converts a variable-length string to a fixed-length string that can act as a "fingerprint" or identifier for the original
string. It is not possible to convert the hash result back to the source string.
Returns

A string.
Category

Conversion functions, Security functions, String functions
Function syntax

Hash(string [, algorithm [, encoding] [, iterations ]])

History

ColdFusion MX 7: Added the algorithm and encoding parameters.
ColdFusion 10: Added the iterations argument.
Parameters

Parameter

Description

string

String to hash.

© 2014 Adobe Systems Incorporated. All rights reserved.

1774

Adobe ColdFusion Documentation

algorithm

(Optional) The algorithm to use to hash the string.
ColdFusion installs a cryptography library with the
following algorithms:
CFMX_COMPAT: Generates a hash string identical
to that generated by ColdFusion MX and ColdFusion
MX 6.1 (default). It is only a place holder algorithm
that informs ColdFusion to use an algorithm
compatible with CFMX if the user does not have any
option to provide algorithm.
MD5: (default) Generates a 32-character,
hexadecimal string, using the MD5 algorithm (The
algorithm used in ColdFusion MX and prior releases).
SHA: Generates a 40-character string using the
Secure Hash Standard SHA-1 algorithm specified by
Nation Institute of Standards and Technology (NIST)
FIPS-180-2.
SHA-256: Generates a 44-character string using the
SHA-256 algorithm specified by FIPS-180-2.
SHA-384: Generates a 64-character string using the
SHA-384 algorithm specified by FIPS-180-2.
SHA-512: Generates an 128-character string using
the SHA-1 algorithm specified by FIPS-180-2.
The Enterprise Edition of ColdFusion installs the RSA
BSafe Crypto-J library, which provides FIPS-140
Compliant Strong Cryptography. It includes the
following algorithms:
MD2: The MD2 hash algorithm defined by RFC 1319.
MD5: The defined by RFC 1321.
RIPEMD160: RACE Integrity Primitives Evaluation
Message Digest 160-bit message digest algorithm
and cryptographic hash function.
SHA-1: The 160-bit secure hash algorithm defined by
FIPS 180-2 and FIPS 198.
SHA-224: The 224-bit secure hash algorithm defined
by FIPS 180-2 and FIPS 198.
SHA-256: The 256-bit secure hash algorithm defined
by FIPS 180-2 and FIPS 198.
SHA-384: The 384-bit secure hash algorithm defined
by FIPS 180-2 and FIPS 198.
SHA-512: The 512-bit secure hash algorithm defined
by FIPS 180-2 and FIPS 198.
If you install a security provider with additional
cryptography algorithms, you can also specify any of
its hashing algorithms.

© 2014 Adobe Systems Incorporated. All rights reserved.

1775

Adobe ColdFusion Documentation

encoding

(Optional; to use this attribute, also specify the algorith
m parameter) A string specifying the encoding to use
when converting the string to byte data used by the
hash algorithm. Must be a character encoding name
recognized by the Java runtime. The default value is
the value specified by the defaultCharset entry in the
neo-runtime.xml file, which is normally UTF-8. Ignored
when using the CFMX_COMPAT algorithm.

iterations

(Optional) The number of times to iterate hashing, to
increase hash computation time. CF10+

Usage

The result of this function is useful for comparison and validation. For example, you can store the hash of a
password in a database without exposing the password. You can check the validity of the password by hashing the
entered password and comparing the result with the hashed password in the database.ColdFusion uses the Java
Cryptography Extension (JCE) and installs a Sun Java runtime that includes the Sun JCE default security provider.
This provider includes the algorithms listed in the Parameters section. The JCE framework includes facilities for
using other provider implementations; however, Adobe cannot provide technical support for third-party security
providers.The encoding attribute is normally not required. It provides a mechanism for generating identical hash
values on systems with different default encodings. ColdFusion uses a default encoding of UTF-8 unless you modify
the defaultCharset entry in the neo-runtime.xml file.
Example

The following example lets you enter a password and compares the hashed password with a hash value saved in
the SecureData table of the cfdocexamples database. This table has the following entries:
User ID

Password

blaw

blaw

dknob

dknob

© 2014 Adobe Systems Incorporated. All rights reserved.

1776

Adobe ColdFusion Documentation

Hash Example




SELECT PasswordHash
FROM SecureData
WHERE UserID = 




User ID #Form.userID# or password is not valid. Try again.

Password is valid for User ID #Form.userID#.





User ID: 


Password: 






© 2014 Adobe Systems Incorporated. All rights reserved.

1777

Adobe ColdFusion Documentation

HMac
Description

Creates Hash-based Message Authentication Code for the given string based on the algorithm and encoding.
Hash-based Message Authentication Code (HMAC) is used to verify the data integrity and authenticity of a message
transmitted. It involves a cryptographic hash function in combination with a secret key. The cryptographic hash
function can be Message Digest 5 (MD5), Secure Hash Algorithm (SHA), and so on.
Returns

An encoded string
Category

Display and formatting functions
History

ColdFusion 10: Added this function.
Syntax

HMac(message, key [,algorithm] [,encoding])
See also

SessionInvalidate, SessionRotate
History

ColdFusion 10: Added this function.
Parameters

Parameter

Required\Optional

Description

message

Required

The message to transmit. The
message can be a String or a byte
array.

key

Required

The secret key to create HMAC.
The key can be a String or a byte
array.

algorithm

Optional

Algorithm used.

encoding

Optional

Encoding to be used.

Usage

Use this function to create Hash-based Message Authentication Code for the given string based on the algorithm
and encoding.
Example

© 2014 Adobe Systems Incorporated. All rights reserved.

1778

Adobe ColdFusion Documentation

HMAC Test

#x#

© 2014 Adobe Systems Incorporated. All rights reserved.

1779

Adobe ColdFusion Documentation

HQLMethods
The Hibernate Query Language (HQL) methods return a single or multi-dimensional array of values or entities,
based on what the HQL query returns. If you are sure that only one record exists that matches this filter criteria,
specify unique=true so that a single entity is returned instead of an array.
If unique=true and multiple records are returned, then an exception is thrown.
Note
entityname and properties used in HQL are case sensitive.

The following HQL methods are available:
ORMExecuteQuery(hql, [,unique][, queryoptions])
ORMExecuteQuery(hql, params [,unique] [,queryOptions])
ORMExecuteQuery(hql, namedparams [, unique] [, queryOptions])
ORMExecuteQuery(hql, [,unique] [, queryoptions])
Description

Runs HQL on the default data source specified for the application. You can specify several options to control the
behavior of retrieval using queryOptions:
ignorecase: Ignores the case of sort order when you set it to true. Use this option only when you specify
the sortorder parameter.
maxResults: Specifies the maximum number of objects to be retrieved.
offset: Specifies the start index of the resultset from where it has to start the retrieval.
cacheable: Whether the result of this query is to be cached in the secondary cache. Default is false.
cachename: Name of the cache in secondary cache.
timeout: Specifies the timeout value (in seconds) for the query
Note
Maxresults and timeout are used for pagination.

Category

ORM functions
Example


 40")>






ORMExecuteQuery(hql, params [,unique] [,queryOptions])

© 2014 Adobe Systems Incorporated. All rights reserved.

1780

Adobe ColdFusion Documentation

Description

This type of ORMExecuteQuery lets you pass parameters to the query. Use '?' (question mark) as the placeholder
for the parameters. The values to the parameters must be passed as an array to params.In addition, you can specify
several options to control the behavior of retrieval using queryOptions:
ignorecase: Ignores the case of sort order when you set it to true. Use this option only when you specify
the sortorder parameter.
maxResults: Specifies the maximum number of objects to be retrieved.
offset: Specifies the start index of the resultset from where it has to start the retrieval.
cacheable: Whether the result of this query is to be cached in the secondary cache. Default is false.
cachename: Name of the cache in secondary cache.
timeout: Specifies the timeout value (in seconds) for the query
Note
Maxresults and timeout are used for pagination.

Category

ORM functions
Example

 ?", [40])>

 ? and age < ?", [40,
80])>

ORMExecuteQuery(hql, namedparams [, unique] [, queryOptions])
Description

This type of ORMExecuteQuery lets you pass named parameters to the query. The placeholder for the parameter
must be a name and must start with ":" as in ":age" or ":id". The values to the names must be passed as key-value
pairs.In addition, you can specify several options to control the behavior of retrieval using queryOptions:
ignorecase: Ignores the case of sort order when you set it to true. Use this option only when you specify
the sortorder parameter.
maxResults: Specifies the maximum number of objects to be retrieved.
offset: Specifies the start index of the resultset from where it has to start the retrieval.
cacheable: Whether the result of this query is to be cached in the secondary cache. Default is false.
cachename: Name of the cache in secondary cache.
timeout: Specifies the timeout value (in seconds) for the query
Note
Maxresults and timeout are used for pagination.

Category

© 2014 Adobe Systems Incorporated. All rights reserved.

1781

Adobe ColdFusion Documentation

ORM functions
Example

To retrieve employee details of all employees whose reside in USA and are also citizens of USA:




© 2014 Adobe Systems Incorporated. All rights reserved.

1782

Adobe ColdFusion Documentation

Hour
Description

Gets the current hour of the day.
Returns

Ordinal value of the hour, in the range 0-23.
Category

Date and time functions
Function syntax

Hour(date)

See also

DatePart, Minute, Second
Parameters

Parameter

Description

date

Date/time object, in the range 100 AD-9999 AD.

Usage

When passing a date/time value as a string, enclose it in quotation marks. Otherwise, it is interpreted as a number
representation of a date/time object.
Example


Hour Example

The time is currently #TimeFormat(Now())#.
We are in hour #Hour(Now())#, Minute #Minute(Now())#
and Second #Second(Now())# of the day.


© 2014 Adobe Systems Incorporated. All rights reserved.

1783

Adobe ColdFusion Documentation

HTMLCodeFormat
Description

Replaces special characters in a string with their HTML-escaped equivalents and inserts 
 and 
 tags at
the beginning and end of the string.
Returns

HTML-escaped string string, enclosed in 
 and 
 tags. Return characters are removed; line feed
characters are preserved. Characters with special meanings in HTML are converted to HTML character entities such
as >.
Category

Display and formatting functions
Function syntax

HTMLCodeFormat(string [, version ])

See also

HTMLEditFormat
Parameters

Parameter

Description

string

A string or a variable that contains one.

version

HTML version to use; currently ignored.
-1: The latest implementation of HTML
2.0: HTML 2.0 (default)
3.2: HTML 3.2

Usage

This function converts the following characters to HTML character entities:
Text character

Encoding

<

<

>

>

&

&

"

"

© 2014 Adobe Systems Incorporated. All rights reserved.

1784

Adobe ColdFusion Documentation

This function typically increases the length of a string. This can cause unpredictable results when performing certain
string functions (Left, Right, and Mid, for example) against the expanded string.The only difference between this
function and HTMLEditFormat is that HTMLEditFormat does not surround the text in an HTML pre tag.
Example




The text without processing
#testString#

Using HTMLCodeFormat
#HTMLCodeFormat(testString)#
Using HTMLEditFormat
#HTMLEditFormat(testString)#


© 2014 Adobe Systems Incorporated. All rights reserved.

1785

Adobe ColdFusion Documentation

HTMLEditFormat
Adobe recommends that you use the EncodeForHTML function, not the HTMLEditFormat
function, to escape special characters in a string for use in HTML in all new applications.

THIS FUNCTION HAS BEEN DEPRECATED
Description

Replaces special characters in a string with their HTML-escaped equivalents.
Returns

HTML-escaped string string. Return characters are removed; line feed characters are preserved. Characters with
special meanings in HTML are converted to HTML character entities such as >.
Category

Display and formatting functions
Function syntax

HTMLEditFormat(string [, version ])

See also

HTMLCodeFormat, cfapplication
Parameters

Parameter

Description

string

A string or a variable that contains one.

version

HTML version to use; currently ignored.
-1: The latest implementation of HTML
2.0: HTML 2.0 (default)
3.2: HTML 3.2

Usage

This function converts the following characters to HTML character entities:
Text character

Encoding

<

<

>

>

© 2014 Adobe Systems Incorporated. All rights reserved.

1786

Adobe ColdFusion Documentation

&

&

"

"

This function can be used to help protect ColdFusion pages that return user-provided data to the client browser from
cross-site scripting attacks. However, the scriptprotect attribute of the cfapplication tag or the equivalent
This.scriptProtect variable setting in Application.cfc can be preferable in most instances, because you only need to
specify it once for an application.This function typically increases the length of a string. This can cause unpredictable
results when performing certain string functions (Left, Right, and Mid, for example) against the expanded
string.The only difference between this function and HTMLCodeFormat is that HTMLCodeFormat surrounds the text
in an HTML pre tag.
Example




The text without processing
#testString#

Using HTMLCodeFormat
#HTMLCodeFormat(testString)#
Using HTMLEditFormat
#HTMLEditFormat(testString)#


© 2014 Adobe Systems Incorporated. All rights reserved.

1787

Adobe ColdFusion Documentation

IIf
Description

Evaluates a Boolean conditional dynamic expression. Depending on whether the expression is yes or no,
dynamically evaluates one of two string expressions and returns the result. This function is convenient for
incorporating a cfif tag in-line in HTML.For general conditional processing, see cfif. For error handling, see cft
ry. For more information, see the Developing ColdFusion Applications.
Returns

If result is yes, returns the value of Evaluate(string_expression1); otherwise, returns the value of Evaluate
(string_expression2).
Category

Decision functions, Dynamic evaluation functions
Function syntax

IIf(condition, string_expression1, string_expression2)

See also

DE, Evaluate
Parameters

Parameter

Description

condition

An expression that can be evaluated as a Boolean.

string_expression1

A string or a variable that contains one. Expression to
evaluate and return if condition is yes.

string_expression2

A string or a variable that contains one. Expression to
evaluate and return if condition is no.

Usage

The IIf function is a shortcut for the following construct:







The expressions string_expression1 and string_expression2 must be string expressions, so that they are not
evaluated immediately as the parameters of IIf. For example:

© 2014 Adobe Systems Incorporated. All rights reserved.

1788

Adobe ColdFusion Documentation

IIf(y is 0, DE("Error"), x/y)

If y = 0, this generates an error, because the third expression is the value of x/0 (invalid expression).ColdFusion
evaluates string_expression1 and string_expression2. To return the string itself, use the DE function.
Note
If you use number signs (#) in string_expression1 or string_expression2, ColdFusion
evaluates the part of the expression in number signs first. If you misuse the number signs, you
can cause unexpected results from the IIf function. For example, if you use number signs around
the whole expression in string_expression1, and if there is an undefined variable in string
_expression1, the function might fail, with the error "Error Resolving Parameter."

If a variable is undefined, ColdFusion throws an error when it processes this function. The following example shows
this problem:

#IIf(IsDefined("Form.Deliver"), DE(Form.Deliver), DE("no"))#

This returns "Error resolving parameter FORM.DELIVER".To avoid this problem, use the DE and Evaluate function
s in code such as the following:

#IIf(IsDefined("Form.Deliver"), Evaluate(DE("Form.Deliver")), DE("no"))#

This returns "no"; ColdFusion does not throw an error.In the following example, LocalVar is undefined; however, if
you omit number signs around LocalVar, the code works properly:


#IIf(IsDefined("LocalVar"), "LocalVar",
DE("The variable is not defined."))#


The output is:

The variable is not defined.

The number signs around LocalVar in the following code cause it to fail with the error message 'Error Resolving
Parameter', because ColdFusion never evaluates the original condition IsDefined("LocalVar").Here is another
example:

© 2014 Adobe Systems Incorporated. All rights reserved.

1789

Adobe ColdFusion Documentation


#IIf(IsDefined("LocalVar"), DE("#LocalVar#"), DE("The variable is not defined."))#


The error message would be as follows:

Error resolving parameter LOCALVAR

The DE function has no effect on the evaluation of LocalVar, because the number signs cause it to be evaluated
immediately.
Example

IIf Function Example
IIf evaluates a condition, and does an Evaluate on string
expression 1 or string expression 2 depending on the Boolean
outcome (yes: run expression 1; no: run expression 2).
The result of the expression
IIf( Hour(Now()) GTE 12,
DE("It is afternoon or evening"),
DE("It is morning"))
is:


#IIf( Hour(Now()) GTE 12,
DE("It is afternoon or evening"),
DE("It is morning"))#



© 2014 Adobe Systems Incorporated. All rights reserved.

1790

Adobe ColdFusion Documentation

ImageAddBorder
Description

Adds a rectangular border around the outside edge of a ColdFusion image.
Returns

Nothing.
Category

Image functions
Function syntax

ImageAddBorder(name, thickness [, color, borderType])

See also

cfimage, ImageDrawRect, IsImageFile
History

ColdFusion 8: Added this function.
Parameters

Parameter

Description

name

Required. The ColdFusion image on which this
operation is performed.

thickness

Required. Thickness of the border in pixels. The default
value is 1. The border is added to the outside edge of
the image; the image area is increased accordingly.

color

Optional. Border color. The default border color is
black. See Usage.Only valid if the borderType is not
specified or if borderType = "constant".

© 2014 Adobe Systems Incorporated. All rights reserved.

1791

Adobe ColdFusion Documentation

borderType

Optional. The type of border:
zero: Sets the border color to black.
constant: Sets the border to the specified color
(default).
copy: Sets sample values to copies of the nearest
valid pixel. For example, pixels to the left of the valid
rectangle assume the value of the valid edge pixel in
the same row. Pixels both above and to the left of the
valid rectangle assume the value of the upper-left
pixel.
reflect: Mirrors the edges of the source image.
For example, if the left edge of the valid rectangle is
located at x = 10, pixel (9, y) is a copy of pixel (10, y)
and pixel (6, y) is a copy of pixel (13, y).
wrap: Tiles the source image in the plane.

Usage

Thickness of the border in pixels. The default value is 1. The border is added to the outside edge of the image; the
image area is increased accordingly.
Example

Example 1














Example 2

© 2014 Adobe Systems Incorporated. All rights reserved.

1792

Adobe ColdFusion Documentation












Example 3












Example 4











© 2014 Adobe Systems Incorporated. All rights reserved.

1793

Adobe ColdFusion Documentation

ImageBlur
Description

Smooths (blurs) the ColdFusion image.
Returns

Nothing.
Category

Image functions
Function syntax

ImageBlur(name [, blurRadius])

See also

ImageSharpen, IsImageFile
History

ColdFusion 8: Added this function.
Parameters

Parameter

Description

name

Required. The ColdFusion image on which this
operation is performed.

blurRadius

Optional. The size of the blur radius.Value must be
greater than or equal to 3 and less than or equal to 10.
The default value is 3.

Usage

The blurRadius operation affects performance: as the blurRadius value increases, performance decreases.
Example

© 2014 Adobe Systems Incorporated. All rights reserved.

1794

Adobe ColdFusion Documentation












© 2014 Adobe Systems Incorporated. All rights reserved.

1795

Adobe ColdFusion Documentation

ImageClearRect
Description

Clears the specified rectangle by filling it with the background color of the current drawing surface.
Returns

Nothing.
Category

Image functions
Function syntax

ImageClearRect(name, x, y, width, height)

See also

ImageSetBackgroundColor, IsImageFile
History

ColdFusion 8: Added this function.
Parameters

Parameter

Description

name

Required. The ColdFusion image on which this
operation is performed.

x

Required. The x coordinate of the rectangle to clear.

y

Required. The y coordinate of the rectangle to clear.

width

Required. The width of the rectangle to clear.

height

Required. The height of the rectangle to clear.

Usage

Use this function in conjunction with the ImageSetBackgroundColor function.
Example

© 2014 Adobe Systems Incorporated. All rights reserved.

1796

Adobe ColdFusion Documentation

















© 2014 Adobe Systems Incorporated. All rights reserved.

1797

Adobe ColdFusion Documentation

ImageCopy
Description

Copies a rectangular area of an image.
Returns

A ColdFusion image for the copied area.
Category

Image functions
Function syntax

ImageCopy(name, x, y, width, height [, dx, dy])

See also

ImageNew, ImagePaste, IsImageFile
History

ColdFusion 8: Added this function.
Parameters

Parameter

Description

name

Required. The ColdFusion image on which this
operation is performed.

x

Required. The x coordinate of the source rectangle.

y

Required. The y coordinate of the source rectangle.

width

Required. The width of the source rectangle.

height

Required. The height of the source rectangle.

dx

Optional. The x coordinate of the destination rectangle.

dy

Optional. The y coordinate of the destination rectangle.

Usage

The rectangle is specified by (x,y,width,height). The area is copied to the rectangle with the upper-left corner
specified by (dx,dy).
Example

© 2014 Adobe Systems Incorporated. All rights reserved.

1798

Adobe ColdFusion Documentation

Example 1












Example 2

















© 2014 Adobe Systems Incorporated. All rights reserved.

1799

Adobe ColdFusion Documentation

ImageCreateCaptcha
Description

Create a Completely Automated Public Turing test to tell Computers and Humans Apart (CAPTCHA) image, a
distorted text image that is human-readable, but not machine-readable, used in a challenge-response test for
preventing spam.
Returns

Image object
History

ColdFusion 10: Added this function.
Syntax

imageCreateCaptcha (height, width, text)imageCreateCaptcha (height, width, text [,
difficulty])imageCreateCaptcha (height, width, text [, difficulty, fonts, fontsize)
See also

cfimage
Properties

Parameter

Description

height

Required. Height in pixels of the image.

width

Required. Width in pixels of the image.

text

Required. Text string displayed in the CAPTCHA
image. Use capital letters for better readability. Do not
include spaces because users cannot detect them in
the resulting CAPTCHA image.

difficulty

Optional. Level of complexity of the CAPTCHA text.
Specify one of the following levels of text distortion:
low
medium
high

font

© 2014 Adobe Systems Incorporated. All rights reserved.

Optional. One or more valid fonts to use for the
CAPTCHA text. Separate multiple fonts with commas.
ColdFusion supports only the system fonts that the JDK
can recognize. For example, TTF fonts in the Windows
directory are supported on Windows.

1800

Adobe ColdFusion Documentation

Optional. Font size of the text in the CAPTCHA image.
The value must be an integer.

fontsize

Example

ImageCreateCaptcha Method







© 2014 Adobe Systems Incorporated. All rights reserved.

1801

Adobe ColdFusion Documentation

ImageCrop
Description

Crops a ColdFusion image to a specified rectangular area.
Returns

Nothing.
Category

Image functions
Function syntax

ImageCrop(name, x, y, width, height)

See also

ImageFlip, ImageResize, IsImageFile
History

ColdFusion 8: Added this function.
Parameters

Parameter

Description

name

Required. The ColdFusion image on which this
operation is performed.

x

Required. The x origin of the crop area.

y

Required. The y origin of the crop area.

width

Required. The width of the crop area.

height

Required. The height of the crop area.

Usage

The rectangular area cannot be empty, and must be fully contained within the source image bounds.
Example

© 2014 Adobe Systems Incorporated. All rights reserved.

1802

Adobe ColdFusion Documentation












© 2014 Adobe Systems Incorporated. All rights reserved.

1803

Adobe ColdFusion Documentation

ImageDrawArc
Description

Draws a circular or elliptical arc.
Returns

Nothing.
Category

Image functions
Function syntax

ImageDrawArc(name, x, y, width, height, startAngle, arcAngle [, filled])

See also

ImageDrawCubicCurve, ImageDrawOval, ImageDrawQuadraticCurve, ImageSetAntialiasing, ImageSe
tDrawingColor, ImageSetDrawingStroke, IsImageFile
History

ColdFusion 8: Added this function.
Parameters

Parameter

Description

name

Required. The ColdFusion image on which this
operation is performed.

x

Required. The x coordinate of the upper-left corner of
the arc.

y

Required. The y coordinate of the upper-left corner of
the arc.

width

Required. The width of the arc.

height

Required. The height of the arc.

startAngle

Required. The beginning angle in degrees.

arcAngle

Required. The angular extent of the arc, relative to the
start angle.

© 2014 Adobe Systems Incorporated. All rights reserved.

1804

Adobe ColdFusion Documentation

filled

Optional. Specify whether the arc is filled:
yes: The arc is filled with the specified drawing color.
no: Only the outline of the arc is drawn (default).

Usage

The resulting arc begins at startAngle and extends for arcAngle degrees. Degrees start at 0 in the three o'
clock position. A positive value indicates a counter-clockwise rotation; a negative value indicates a clockwise
rotation.The center of the arc is the center of the rectangle whose origin is (x,y) and whose size is specified by the w
idth and height parameters.The angles are specified relative to the non-square extents of the bounding rectangle
so that 45 degrees always falls on the line from the center of the ellipse to the upper-right corner of the bounding
rectangle. As a result, if the bounding rectangle is noticeably longer on one axis than the other, the angles to the
start and end of the arc segment are skewed farther along the longer axis of the bounds.If the filled parameter is
set to yes, the area inside the oval is filled with the current drawing color.Use the ImageSetDrawingColor and I
mageSetDrawingStroke functions to specify the color and line attributes of the arc. Use the ImageSetAntialia
sing function to improve the quality of the rendered image.
Example












© 2014 Adobe Systems Incorporated. All rights reserved.

1805

Adobe ColdFusion Documentation

ImageDrawBeveledRect
Description

Draws a rectangle with beveled edges.
Returns

Nothing.
Category

Image functions
Function syntax

ImageDrawBeveledRect(name, x, y, width, height, raised [, filled])

See also

ImageClearRect, ImageDrawLine, ImageDrawLines, ImageDrawRect, ImageDrawRoundRect, ImageSetA
ntialiasing, ImageSetDrawingColor, ImageSetDrawingStroke
History

ColdFusion 8: Added this function.
Parameters

Parameter

Description

name

Required. The ColdFusion image on which this
operation is performed.

x

Required. The x coordinate of the rectangle.

y

Required. The y coordinate of the rectangle.

width

Required. The width of the rectangle.

height

Required. The height of the rectangle.

raised

Required. Specify whether the rectangle appears
raised above the surface or sunk into the surface:
yes: The rectangle is raised.
no: The rectangle is sunk (default).

© 2014 Adobe Systems Incorporated. All rights reserved.

1806

Adobe ColdFusion Documentation

filled

Optional. Specify whether the rectangle is filled:
yes: The rectangle is filled with the specified drawing
color.
no: Only the outline of the rectangle is drawn
(default).

Usage

The edges of the rectangle are highlighted so that they appear beveled and lit from the upper-left corner. The colors
used for the highlighting effect are determined by the current drawing color.If the filled parameter is set to yes,
the cuboid area is filled with the current drawing color.Use the ImageSetDrawingColor and ImageSetDrawingS
troke functions to specify the color and line attributes of the rectangle. Use the ImageSetAntialiasing function
to improve the quality of the rendered image.
Example













© 2014 Adobe Systems Incorporated. All rights reserved.

1807

Adobe ColdFusion Documentation

ImageDrawCubicCurve
Description

Draws a cubic curve.
Returns

Nothing.
Category

Image functions
Function syntax

ImageDrawCubicCurve(name, ctrlx1, ctrly1, ctrlx2, ctrly2, x1, y1, x2, y2)

See also

ImageDrawQuadraticCurve, ImageDrawRect, ImageDrawRoundRect, ImageSetAntialiasing, ImageSet
DrawingColor, ImageSetDrawingStroke, IsImageFile
History

ColdFusion 8: Added this function.
Parameters

Parameter

Description

name

Required. The ColdFusion image on which this
operation is performed.

ctrlx1

Required. The xcoordinate of the first control point of
the cubic curve segment.

ctrly1

Required. The y coordinate of the first control point of
the cubic curve segment.

ctrlx2

Required. The x coordinate of the second control point
of the cubic curve segment.

ctrly2

Required. The y coordinate of the second control point
of the cubic curve segment.

x1

Required. The x coordinate of the start point of the
cubic curve segment.

y1

Required. The y coordinate of the start point of the
cubic curve segment.

© 2014 Adobe Systems Incorporated. All rights reserved.

1808

Adobe ColdFusion Documentation

x2

Required. The x coordinate of the end point of the cubic
curve segment.

y2

Required. The y coordinate of the end point of the cubic
curve segment.

Usage

Coordinates can be integers or real numbers.

Use the ImageSetDrawingColor and ImageSetDrawingStroke functions to specify the color and line
attributes of the cubic curve. Use the ImageSetAntialiasing function to improve the quality of the rendered
image.
Example













© 2014 Adobe Systems Incorporated. All rights reserved.

1809

Adobe ColdFusion Documentation

ImageDrawLine
Description

Draws a single line defined by two sets of x and y coordinates on a ColdFusion image.
Returns

Nothing.
Category

Image functions
Function syntax

ImageDrawLine(name, x1, y1, x2, y2)

See also

ImageDrawLines, ImageSetAntialiasing, ImageSetDrawingColor, ImageSetDrawingStroke
History

ColdFusion 8: Added this function.
Parameters

Parameter

Description

name

Required. The ColdFusion image on which this
operation is performed.

x1

Required. The x coordinate for the start point of the
line.

y1

Required. The y coordinate for the start point of a line.

x2

Required. The x coordinate for the end point of the line.

y2

Required. The y coordinate for the end point of the line.

Usage

Each pair of coordinates, (x1,y1) and (x2,y2), defines a point. The start and end points cannot be the same.This
function is affected by the attributes defined in the ImageSetDrawingStroke and ImageSetDrawingColor func
tions. Use the ImageSetAntialiasing function to improve the quality of the rendered image.
Example

© 2014 Adobe Systems Incorporated. All rights reserved.

1810

Adobe ColdFusion Documentation











© 2014 Adobe Systems Incorporated. All rights reserved.

1811

Adobe ColdFusion Documentation

ImageDrawLines
Description

Draws a sequence of connected lines defined by arrays of x and y coordinates.
Returns

Nothing.
Category

Image functions
Function syntax

ImageDrawLines(name, xcoords, ycoords [, isPolygon, filled])

See also

ImageDrawBeveledRect, ImageDrawCubicCurve, ImageDrawLine, ImageDrawRect, ImageDrawRoundRec
t, ImageSetAntialiasing, ImageSetDrawingColor, ImageSetDrawingStroke, IsImageFile
History

ColdFusion 8: Added this function.
Parameters

Parameter

Description

name

Required. The ColdFusion image on which this
operation is performed.

xcoords

Required. A CFML array of x coordinates.

ycoords

Required. A CFML array of y coordinates.

isPolygon

Optional. Specify whether the lines form a polygon:
yes: The lines are connected to form a polygon.
no: The lines do not form a polygon (default).

filled

Optional. Specify whether the polygon is filled:
yes: The polygon is filled with the specified drawing
color.
no: Only the outline of the polygon is drawn (default).

Usage

Each pair of (x,y) coordinates defines a point.To draw a polygon, set isPolygon to yes. The start point cannot be

© 2014 Adobe Systems Incorporated. All rights reserved.

1812

Adobe ColdFusion Documentation

the same value as the end point. If isPolygon is yes, a line joining start point and the end point is drawn to
complete a polygon. If isPolygon is no, line completing the polygon is not drawn.Set the isPolygon and filled
parameters to yes to draw a polygon filled with the current drawing color.Use the ImageSetDrawingColor and I
mageSetDrawingStroke functions to control the color and line attributes. Use the ImageSetAntialiasing func
tion to improve the quality of the rendered image.
Example

























© 2014 Adobe Systems Incorporated. All rights reserved.

1813

Adobe ColdFusion Documentation

ImageDrawOval
Description

Draws an oval.
Returns

Nothing.
Category

Image functions
Function syntax

ImageDrawOval(name, x, y, width, height [, filled])

See also

ImageDrawArc, ImageDrawCubicCurve, ImageDrawQuadraticCurve, ImageDrawRoundRect, ImageSetAn
tialiasing, ImageSetDrawingColor, ImageSetDrawingStroke, IsImageFile
History

ColdFusion 8: Added this function.
Parameters

Parameter

Description

name

Required. The ColdFusion image on which this
operation is performed.

x

Required. The x coordinate of the upper left corner of
the oval to draw.

y

Required. The y coordinate of the upper left corner of
the oval to draw.

width

Required. The width of the oval to draw.

height

Required. The height of the oval to draw.

filled

Optional. Specify whether the oval is filled:
yes: The oval is filled with the specified drawing
color.
no: Only the outline of the oval is drawn (default).

Usage

© 2014 Adobe Systems Incorporated. All rights reserved.

1814

Adobe ColdFusion Documentation

The result is a circle or ellipse that fits within the rectangle specified by the x, y, width, and height arguments.If the f
illed parameter is set to yes, the area inside the oval is filled with the current drawing color.Use the ImageSetDr
awingColor and ImageSetDrawingStroke functions to specify the color and line attributes of the oval. Use the
ImageSetAntialiasing function to improve the quality of the rendered image.
Example

Example 1













Example 2



















© 2014 Adobe Systems Incorporated. All rights reserved.

1815

Adobe ColdFusion Documentation

ImageDrawPoint
Description

Draws a point at the specified (x,y) coordinate.
Returns

Nothing.
Category

Image functions
Function syntax

ImageDrawPoint(name, x, y)

See also

ImageDrawLine, ImageDrawLines, ImageSetAntialiasing, ImageSetDrawingColor, ImageSetDrawing
Stroke
History

ColdFusion 8: Added this function.
Parameters

Parameter

Description

name

Required. The ColdFusion image on which this
operation is performed.

x

Required. The x coordinate of the point.

y

Required. The y coordinate of the point.

Usage

Use the ImageSetDrawingStroke and ImageSetDrawingColor functions to control the appearance of the
drawing point. For example, set the width attribute of the ImageSetDrawingStroke function to 10 pixels to draw
a 20-pixel-square centered at (x,y). Use the ImageSetAntialiasing function to improve the quality of the
rendered image.
Example

© 2014 Adobe Systems Incorporated. All rights reserved.

1816

Adobe ColdFusion Documentation

















© 2014 Adobe Systems Incorporated. All rights reserved.

1817

Adobe ColdFusion Documentation

ImageDrawQuadraticCurve
Description

Draws a curved line. The curve is controlled by a single point.
Returns

Nothing.
Category

Image functions
Function syntax

ImageDrawQuadraticCurve(name, ctrlx1, ctrly1, ctrlx2, ctrly2, x1, y1, x2, y2)

See also

ImageDrawArc, ImageDrawOval, ImageDrawRoundRect,ImageSetAntialiasing, ImageSetDrawingColo
r, ImageSetDrawingStroke
History

ColdFusion 8: Added this function.
Parameters

Parameter

Description

name

Required. The ColdFusion image on which this
operation is performed.

ctrlx1

Required. The x coordinate of the first control point of
the quadratic curve segment.

ctrly1

Required. The y coordinate of the first control point of
the quadratic curve segment.

ctrlx2

Required. The x coordinate of the second control point
of the quadratic curve segment.

ctrly2

Required. The y coordinate of the second control point
of the quadratic curve segment.

x1

Required. The x coordinate of the start point of the
quadratic curve segment.

y1

Required. The y coordinate of the start point of the
quadratic curve segment.

© 2014 Adobe Systems Incorporated. All rights reserved.

1818

Adobe ColdFusion Documentation

x2

Required. The x coordinate of the end point of the
quadratic curve segment.

y2

Required. The y coordinate of the end point of the
quadratic curve segment.

Usage

A quadratic curve is a curve controlled by a single control point. The curve is drawn from the last point in the shape
to the target x and y coordinates. Coordinates can be integers or real numbers.Use the ImageSetDrawingColor a
nd ImageSetDrawingStroke functions to specify the color and lines of the quadratic curve. Use the ImageSetAn
tialiasing function to improve the quality of the rendered image.
Example













© 2014 Adobe Systems Incorporated. All rights reserved.

1819

Adobe ColdFusion Documentation

ImageDrawRect
Description

Draws a rectangle.
Returns

Nothing.
Category

Image functions
Function syntax

ImageDrawRect(name, x, y, width, height [, filled])

See also

ImageDrawBeveledRect, ImageDrawCubicCurve, ImageDrawLine, ImageDrawLines, ImageDrawOval, Im
ageDrawQuadraticCurve, ImageDrawRoundRect, ImageSetAntialiasing, ImageSetDrawingColor, Ima
geSetDrawingStroke, ImageDrawText, IsImageFile
History

ColdFusion 8: Added this function.
Parameters

Parameter

Description

name

Required. The ColdFusion image on which this
operation is performed.

x

Required. The x coordinate of the rectangle.

y

Required. The y coordinate of the rectangle.

width

Required. The width of the rectangle.

height

Required. The height of the rectangle.

filled

Optional. Specify whether the rectangle is filled:
yes: The rectangle is filled with the specified drawing
color.
no: Only the outline of the rectangle is drawn
(default).

Usage

© 2014 Adobe Systems Incorporated. All rights reserved.

1820

Adobe ColdFusion Documentation

The left and right edges of the rectangle are at x and x plus width, respectively. The upper and lower edges are at y
and y plus height, respectively.Set the filled parameter to yes to fill the rectangle with the current drawing
color.Use the ImageSetDrawingColor and ImageSetDrawingStroke functions to format the color and lines of
the rectangle. Use the ImageSetAntialiasing function to improve the quality of the rendered image.
Example













© 2014 Adobe Systems Incorporated. All rights reserved.

1821

Adobe ColdFusion Documentation

ImageDrawRoundRect
Description

Draws a rectangle with rounded corners.
Returns

Nothing.
Category

Image functions
Function syntax

ImageDrawRoundRect(name, x, y, width, height, arcWidth, arcHeight [, filled])

See also

ImageDrawBeveledRect, ImageDrawCubicCurve, ImageDrawLine, ImageDrawLines, ImageDrawOval, Im
ageDrawQuadraticCurve, ImageDrawRect, ImageSetAntialiasing, ImageSetDrawingColor, ImageSet
DrawingStroke, IsImageFile
History

ColdFusion 8: Added this function.
Parameters

Parameter

Description

name

Required. The ColdFusion image on which this
operation is performed.

x

Required. The x coordinate of the rectangle.

y

Required. The y coordinate of the rectangle.

width

Required. The width of the rectangle.

height

Required. The height of the rectangle.

arcWidth

Required. The horizontal diameter of the arc at the four
corners.

arcHeight

Required. The vertical diameter of the arc at the four
corners.

© 2014 Adobe Systems Incorporated. All rights reserved.

1822

Adobe ColdFusion Documentation

filled

Optional. Specify whether the rectangle is filled:
yes: The rectangle is filled with the specified drawing
color.
no: Only the outline of the rectangle is drawn
(default).

Usage

The left and right edges of the rectangle are at x and x plus width, respectively. The upper and lower edges are at y
and y plus height, respectively.Set the filled parameter to yes to fill the rectangle with the current drawing
color.Use the ImageSetDrawingColor and ImageSetDrawingStroke functions to control the color and line
attributes of the rectangle. Use the ImageSetAntialiasing function to improve the quality of the rendered image.
Example

Example 1













Example 2

© 2014 Adobe Systems Incorporated. All rights reserved.

1823

Adobe ColdFusion Documentation





























© 2014 Adobe Systems Incorporated. All rights reserved.

1824

Adobe ColdFusion Documentation

ImageDrawText
Description

Draws a text string on a ColdFusion image with the baseline of the first character positioned at (x,y) in the image.
Returns

A struct that contains width and height of the text drawn.
Category

Image functions
Function syntax

ImageDrawText(name, str, x, y [, attributeCollection])

See also

ImageDrawArc, ImageDrawBeveledRect, ImageDrawCubicCurve, ImageDrawLine, ImageDrawLines, Ima
geDrawOval, ImageDrawQuadraticCurve, ImageDrawRect, ImageDrawRoundRect, ImageSetAntialiasi
ng, ImageSetDrawingColor, ImageTranslateDrawingAxis, IsImageFile
History

ColdFusion 8: Added this function.
Parameters

Parameter

Description

name

Required. The ColdFusion image on which this
operation is performed.

str

Required. The text string to draw.

x

Required. The x coordinate for the start point of the
string.

y

Required. The y coordinate for the start point of the
string.

attributeCollection

Optional. The structure used to specify the text
characteristics. See the Usage section.

Usage

Specify all the optional key-value pairs in an attributeCollection structure. To specify the text color, use the I
mageSetDrawingColor function.
attributeCollection

© 2014 Adobe Systems Incorporated. All rights reserved.

1825

Adobe ColdFusion Documentation

Element

Description

font

The name of the font used to draw the text string. If you
do not specify the font attribute{{,}} the text is drawn
in the default system font.

size

The font size for the text string. The default value is 10
points.

style

The style to apply to the font:
bold
italic
boldItalic
plain (default)

strikethrough

Specify whether strikethrough is applied to the text
image:
yes: For vertical text, strikethrough is applied to each
character individually.
no (default)

underline

Specify whether underline is applied to the text image:
yes: For vertical text, underline is applied to each
character individually.
no (default)

Example

Example 1











Example 2

© 2014 Adobe Systems Incorporated. All rights reserved.

1826

Adobe ColdFusion Documentation































© 2014 Adobe Systems Incorporated. All rights reserved.

1827

Adobe ColdFusion Documentation

ImageFlip
Description

Flips an image across an axis.
Returns

Nothing.
Category

Image functions
Function syntax

ImageFlip(name [, transpose])

See also

ImageBlur, ImageClearRect, {{[ ImageCrop]}}, ImageNegative, ImageNew, ImageOverlay, ImagePaste, I
mageResize, ImageRotate, ImageScaleToFit, ImageSetAntialiasing, ImageSharpen, ImageShear, Im
ageTranslate, IsImageFile
History

ColdFusion 8: Added this function.
Parameters

Parameter

Description

name

Required. The ColdFusion
image on which this
operation is performed.

© 2014 Adobe Systems Incorporated. All rights reserved.

1828

Adobe ColdFusion Documentation

transpose

Optional. Transpose the
image:
vertical: Flip an
image across an
imaginary horizontal
line that runs through
the center of the image
(default).
horizontal: Flip an
image across an
imaginary vertical line
that runs through the
center of the image.
diagonal: Flip an
image across its main
diagonal that runs from
the upper-left to the
lower-right corner.
antidiagonal: Flip
an image across its
main diagonal that runs
from the upper-right to
the lower-left corner.
{{("90

180

270"- Rotate an image
clockwise by 90, 180, or
270 degrees.

Usage

If you do not specify the transpose parameter for the ImageFlip function, the image is transposed on a vertical
axis, creating an image that is an upside-down version of the source. Use the ImageSetAntialiasing function to
improve the quality of the rendered image.
Example

Example 1











Example 2

© 2014 Adobe Systems Incorporated. All rights reserved.

1829

Adobe ColdFusion Documentation











Example 3











Example 4











Example 5











© 2014 Adobe Systems Incorporated. All rights reserved.

1830

Adobe ColdFusion Documentation

ImageGetBlob
Description

Retrieves the bytes of the underlying image. The bytes are in the same image format as the source image.
Returns

The bytes of the underlying image of a BLOB.
Category

Image functions
Function syntax

ImageGetBlob(source)

See also

cfimage, ImageGetBufferedImage, ImageGetEXIFTag, ImageGetHeight, ImageGetIPTCTag, ImageGetW
idth, ImageInfo, IsImage
History

ColdFusion 8: Added this function.
Parameters

Parameter

Description

source

Required. The ColdFusion image on which this
operation is performed.

Usage

Use this function to insert ColdFusion images into BLOB columns of databases.
Note
If you do not specify a source image, you get a parameter validation error.

Example

Example 1

© 2014 Adobe Systems Incorporated. All rights reserved.

1831

Adobe ColdFusion Documentation






INSERT into EMPLOYEES (FirstName,LastName,Photo)
VALUES ('Aiden','Quinn',)


Example 2The following example shows how to use the ImageNew function to generate thumbnail images in JPEG
format from BLOB data retrieved from a database:



SELECT EMLPOYEEID, PHOTO FROM Employees








© 2014 Adobe Systems Incorporated. All rights reserved.

1832

Adobe ColdFusion Documentation

ImageGetBufferedImage
Description

Returns the java.awt.BufferedImage object underlying the current ColdFusion image.
Returns

The java.awt.BufferedImage object.
Category

Image functions
Function syntax

ImageGetBufferedImage(name)

See also

cfimage, ImageGetBlob, ImageGetEXIFTag, ImageGetHeight, ImageGetIPTCTag, ImageGetWidth, Imag
eInfo, IsImage, IsImageFile
History

ColdFusion 8: Added this function.
Parameters

Parameter

Description

name

Required. The ColdFusion image on which this
operation is performed.

Usage

Use this function to return an image object that can be used with other Java Abstract Windowing Toolkit (AWT)
objects embedded in the page.
Example

© 2014 Adobe Systems Incorporated. All rights reserved.

1833

Adobe ColdFusion Documentation









#x.getWidth()#


© 2014 Adobe Systems Incorporated. All rights reserved.

1834

Adobe ColdFusion Documentation

ImageGetEXIFMetadata
Description

Retrieves the Exchangeable Image File Format (EXIF) headers in an image as a CFML structure.
Returns

A structure with the EXIF header values.
Category

Image functions
Function syntax

ImageGetEXIFMetadata(name)

See also

cfimage, ImageGetEXIFTag, ImageGetBlob, ImageGetBufferedImage, ImageGetHeight, ImageGetIPTC
Tag, ImageGetWidth, ImageInfo, IsImage, IsImageFile
History

ColdFusion 8: Added this function.
Parameters

Parameter

Description

name

Required. The ColdFusion image on which this
operation is performed.

Usage

The EXIF is a standard for storing interchange information in image files, especially those using JPEG compression.
Most digital cameras use the EXIF format.EXIF metadata includes information pertaining to the creation of the
image, such as the creation date, the software used to create the image, the aperture, the make and model, and the
resolution of the image.The result of the ImageGetEXIFMetadata function is cached in the ColdFusion image to
optimize performance.The ImageGetEXIFMetadata function applies only to JPEG images. If you try to retrieve
metadata for Base64, BLOB, or other types of images, ColdFusion generates errors.
Example

© 2014 Adobe Systems Incorporated. All rights reserved.

1835

Adobe ColdFusion Documentation











© 2014 Adobe Systems Incorporated. All rights reserved.

1836

Adobe ColdFusion Documentation

ImageGetEXIFTag
Description

Retrieves the specified EXIF tag in an image.
Returns

The value of the specified EXIF tag.
Category

Image functions
Function syntax

ImageGetEXIFTag(name, tagName)

See also

cfimage, ImageGetBlob, ImageGetBufferedImage, ImageGetHeight, ImageGetIPTCTag, ImageGetWidt
h, ImageGetEXIFMetadata, ImageGetIPTCMetadata, ImageInfo, IsImage, IsImageFile
History

ColdFusion 8: Added this function.
Parameters

Parameter

Description

name

Required. The ColdFusion image on which this
operation is performed.

tagName

Required. The EXIF tag name to be returned.

Usage

The ImageGetEXIFTag function applies only to JPEG images. If you try to retrieve metadata for Base64, BLOB, or
other types of images, ColdFusion generates errors.
Example

© 2014 Adobe Systems Incorporated. All rights reserved.

1837

Adobe ColdFusion Documentation









© 2014 Adobe Systems Incorporated. All rights reserved.

1838

Adobe ColdFusion Documentation

ImageGetHeight
Description

Retrieves the height of the ColdFusion image in pixels.
Returns

The height of the specified ColdFusion image in pixels.
Category

Image functions
Function syntax

ImageGetHeight(name)

See also

cfimage, ImageGetBlob, ImageGetBufferedImage, ImageGetEXIFTag, ImageGetIPTCTag, ImageGetWid
th, ImageInfo, IsImage, IsImageFile
History

ColdFusion 8: Added this function.
Parameters

Parameter

Description

name

Required. The ColdFusion image on which this
operation is performed.

Usage

Use this function to retrieve the height of a ColdFusion image.
Example









© 2014 Adobe Systems Incorporated. All rights reserved.

1839

Adobe ColdFusion Documentation

ImageGetIPTCMetadata
Description

Retrieves the International Press Telecommunications Council (IPTC )headers in a ColdFusion image as a
structure. The IPTC metadata contains text that describes the image that is stored with it. IPTC metadata includes,
but is not limited to, caption, keywords, credit, copyright, object name, created date, byline, headline, and source.
Returns

A structure containing IPTC header values.
Category

Image functions
Function syntax

ImageGetIPTCMetadata(name)

See also

cfimage, ImageGetBlob, ImageGetBufferedImage, ImageGetEXIFMetadata, ImageGetEXIFTag, ImageG
etHeight,ImageGetWidth, ImageGetIPTCTag, ImageInfo, IsImage, IsImageFile
History

ColdFusion 8: Added this function.
Parameters

Parameter

Description

name

Required. The ColdFusion image on which this
operation is performed.

Usage

The IPTC metadata contains text that describes the image that is stored with it. IPTC metadata includes, but is not
limited to, caption, keywords, credit, copyright, object name, created date, byline, headline, and source.The result of
the ImageGetIPTCMetadata function is cached in the ColdFusion image to optimize performance.The ImageGet
IPTCMetada function applies only to JPEG images. If you try to retrieve metadata for Base64, BLOB, or other types
of images, ColdFusion generates errors.
Example

© 2014 Adobe Systems Incorporated. All rights reserved.

1840

Adobe ColdFusion Documentation











© 2014 Adobe Systems Incorporated. All rights reserved.

1841

Adobe ColdFusion Documentation

ImageGetIPTCTag
Description

Retrieves the value of the IPTC tag for a ColdFusion image.
Returns

The value of the IPTC tag.
Category

Image functions
Function syntax

ImageGetIPTCTag(name, tagName)

See also

cfimage, ImageGetBlob, ImageGetBufferedImage, ImageGetEXIFMetadata, ImageGetEXIFTag, ImageG
etHeight, ImageGetIPTCMetadata, ImageGetWidth, ImageInfo, IsImage, IsImageFile
History

ColdFusion 8: Added this function.
Parameters

Parameter

Description

name

Required. The ColdFusion image on which this
operation is performed.

tagName

Required. The IPTC tag name whose value is returned.

Usage

The ImageGetIPTCTag function applies only to JPEG images. If you try to retrieve metadata for Base64, BLOB, or
other image types, ColdFusion generates errors.
Example














© 2014 Adobe Systems Incorporated. All rights reserved.

1843

Adobe ColdFusion Documentation

ImageGrayscale
Description

Converts a ColdFusion image to grayscale.
Returns

Nothing.
Category

Image functions
Function syntax

ImageGrayscale(name)

See also

ImageBlur, ImageNegative, ImageSetAntialiasing, ImageSharpen, IsImageFile
History

ColdFusion 8: Added this function.
Parameters

Parameter

Description

name

Required. The ColdFusion image on which this
operation is performed.

Usage

Use the ImageSetAntialiasing function to improve the quality of the rendered image.
Example














© 2014 Adobe Systems Incorporated. All rights reserved.

1844

Adobe ColdFusion Documentation

© 2014 Adobe Systems Incorporated. All rights reserved.

1845

Adobe ColdFusion Documentation

ImageInfo
Description

Returns a structure that contains information about the image, such as height, width, color model, size, and
filename.
Returns

A structure that contains information for image parameters.
Category

Image functions
Function syntax

ImageInfo(name)

See also

cfimage, ImageGetHeight, ImageGetWidth, IsImage, IsImageFile
History

ColdFusion 8: Added this function.
Parameters

Parameter

Description

name

Required. The ColdFusion image on which this
operation is performed.

Usage

Use this function to determine whether images are compatible. For example, to use the ImageOverlay function to
overlay two images, both images must have the same color model.
Example

© 2014 Adobe Systems Incorporated. All rights reserved.

1846

Adobe ColdFusion Documentation







height = #info.height#
width = #info.width#
source = #info.source#"
pixel size = #info.colormodel.pixel_size#
transparency = #info.colormodel.transparency#

© 2014 Adobe Systems Incorporated. All rights reserved.

1847

Adobe ColdFusion Documentation

ImageMakeColorTransparent
Description

Creates an image and sets a transparent color.
Returns

Image object
Syntax

imageMakeColorTransparent(img, color__)
History

ColdFusion 10: Added this function
Properties

Parameter

Description

img

Required. The ColdFusion image on which this
operation is performed.

color

Required. The transparent color:
Hexadecimal value of RGB color. For example,
specify the color white as "##FFFFFF" or "FFFFFF".
String value of color (for example, "black", "red",
"green").
The default value of the transparent color is
"black".List of three numbers for (R,G,B) values.
Each value must be in the range 0-255.

Example









PNG image







© 2014 Adobe Systems Incorporated. All rights reserved.

1848

Adobe ColdFusion Documentation

ImageMakeTranslucent
Description

Create a new translucent image with given percentage of translucence.
Returns

Image object
History

ColdFusion 10: Added this function
Syntax

imageMakeTranslucent (img, percent__)
Properties

Parameter

Description

img

Required. Required. The ColdFusion image on which
this operation is performed.

percentage

Required. The percent of translucence:
. 0 = opaque
100 = transparent
Decimal values are supported.

Example

The following example illustrates three images with the second one translucent than first and the thrid one
translucent than the second.

© 2014 Adobe Systems Incorporated. All rights reserved.

1849

Adobe ColdFusion Documentation









PNG image























© 2014 Adobe Systems Incorporated. All rights reserved.

1852

Adobe ColdFusion Documentation

ImageNew
Description

Creates a ColdFusion image.
Returns

A ColdFusion image.
Category

Image functions
Function syntax

ImageNew([source, width, height, imageType, canvasColor])

See also

cfimage, ImageCopy, ImageRead, ImageReadBase64, ImageSetDrawingColor, IsImageFile
History

ColdFusion 8: Added this function.
Parameters

Parameter

Description

source

Optional. The source image on-disk or in-memory
pathname, URL, a ColdFusion variable that is read into
the new ColdFusion image, or a Java buffered image.

width

Optional. The width of the new ColdFusion image. Valid
when the height is specified and the source is not.

height

Optional. The height of the new ColdFusion image.
Valid when the width is specified and the source is not.

imageType

Optional. The type of the ColdFusion image to create:
rgb
argb
grayscale
Valid only when width and height are specified.

© 2014 Adobe Systems Incorporated. All rights reserved.

1853

Adobe ColdFusion Documentation

Optional. Color of the image canvas:

canvasColor

Hexadecimal value of RGB color. For example,
specify the color white as ##FFFFFF or FFFFFF.
String value of color (for example, "black", "red",
"green"). The default value of the drawing color is
"black".
List of three numbers for (R,G,B) values. Each value
must be in the range 0-255.

Usage

You can pass the ImageNew function any of the following parameters:
Absolute or relative pathname: The image file located at the specified pathname on a disk is read and
returned as a ColdFusion image.
URL: The image from the specified URL is read and returned as a ColdFusion image.
Width and height (imageType is optional): A blank ColdFusion image with the specified attributes is returned.
ColdFusion image variable: An image variable in memory; for example, #myImage#.
A BLOB from a database that contains image data.
A byte array that contains Base64 image data.
A Java buffered image.ColdFusion generates an error when the passed attributes cannot create a valid
ColdFusion image.The ImageNew function and the{{cfimage}} read action support the SQL Server Image
Column data type.To read Base64 images, use the ImageReadBase64 function.If the color value is a string,
specify a supported named color; see the valid HTML named colors in cfimage. For a hexadecimal value, use
the form "##xxxxxx" or "xxxxxx", where x = 0-9 or A-F; use two number signs or none.
Note
If you specify the ARGB image type, the image is white; however, if you specify RGB or
grayscale, the image is black. To create blank images consistently, use the canvasColo
r parameter.

Example

Example 1




Example 2

© 2014 Adobe Systems Incorporated. All rights reserved.

1854

Adobe ColdFusion Documentation



SELECT LastName,Photo
FROM Employees






#LastName#










Example 3






Example 4







Example 5

© 2014 Adobe Systems Incorporated. All rights reserved.

1855

Adobe ColdFusion Documentation












Example 6



bufferedImage = createObject("java", "java.awt.image.BufferedImage");
bufferedImage.init(JavaCast("int", 100), JavaCast("int", 100),
BufferedImage.TYPE_4BYTE_ABGR);
myImage = imageNew(bufferedImage);


© 2014 Adobe Systems Incorporated. All rights reserved.

1856

Adobe ColdFusion Documentation

ImageOverlay
Description

Reads two source ColdFusion images and overlays the second source image on the first source image.
Returns

Nothing.
Category

Image functions
Function syntax

ImageOverlay(source1, source2 [, rule, alpha])

See also

ImageCopy, ImagePaste, ImageSetAntialiasing, IsImageFile
History

ColdFusion 8: Added this function.
Parameters

Parameter

Description

source1

Required. The ColdFusion image that is the bottom
layer in the ColdFusion image.

source2

Required. The ColdFusion image that is the top layer
(overlaid on the source1 image) in the ColdFusion
image.

rule

Optional. The following are the supported values: SRC,
DST_IN, DST_OUT, DST_OVER, SRC_IN, SRC_OVER,
or SRC_OUT. For details, see Java documentation.

alpha

Optional. The percentage value of transparency.

Usage

The destination image always has the same bounding rectangle as the first source image and the same image type
as the two sources. If the two source images do not intersect, the destination image is the same as the first source
image.The two source images must have the same color models. For example, you can overlay an RGB image over
another RGB image, but you cannot overlay an RGB image on a grayscale image. To verify the color model of an
image, use the ImageInfo function.Use the ImageSetAntialiasing function to improve the quality of the
rendered image.

© 2014 Adobe Systems Incorporated. All rights reserved.

1857

Adobe ColdFusion Documentation
Example













© 2014 Adobe Systems Incorporated. All rights reserved.

1858

Adobe ColdFusion Documentation

ImagePaste
Description

Takes two images and an (x,y) coordinate and draws the second image over the first image with the upper-left
corner at coordinate (x,y).
Returns

None
Category

Image functions
Function syntax


ImagePaste(image1, image2, x, y)

See also

ImageCopy, ImageOverlay, ImageSetAntialiasing, IsImageFile
History

ColdFusion 8: Added this function.
Parameters

Parameter

Description

image1

Required. The bottom ColdFusion image.

Image2

Required. The ColdFusion image that is pasted on top
of image1.

x

Required. The x coordinate where the upper-left corner
of image2 is pasted.

y

Required. The y coordinate where the upper-left corner
of image2 is pasted.

Usage

Use the ImageSetAntialiasing function to improve the quality of the rendered image.
Example

© 2014 Adobe Systems Incorporated. All rights reserved.

1859

Adobe ColdFusion Documentation

















© 2014 Adobe Systems Incorporated. All rights reserved.

1860

Adobe ColdFusion Documentation

ImageRead
Description

Reads the on-disk or in-memory source pathname or URL and creates a ColdFusion image.
Returns

A ColdFusion image.
Category

Image functions
Function syntax

ImageRead(path)

History

ColdFusion 8: Added this function.
See also

cfimage, ImageNew, ImageReadBase64, ImageWrite, IsImageFile
Parameters

Parameter

Description

path

Required. On-disk or in-memory pathname or URL of
the source image.

Usage

The ImageRead function performs the same operation as the cfimage read action. However, you cannot use the
cfimage tag to read and create a ColdFusion image variable in the cfscript tag. Use the ImageRead function
within the cfscript tag to read ColdFusion images.The following example reads the image file aiden01.jpg into a
variable called myImage and displays the image in the browser:




For a list of valid image formats, see the supported image file formats listed in cfimage. To retrieve a list of readable
formats on the server where the ColdFusion application is deployed, use the GetReadableImageFormats functio
n.
Example

© 2014 Adobe Systems Incorporated. All rights reserved.

1861

Adobe ColdFusion Documentation



myImage=ImageRead("http://www.google.com/images/logo.gif");
ImageWrite(myImage,"google-logo.gif");

This image has been downloaded by ColdFusion:

This is the original image:


© 2014 Adobe Systems Incorporated. All rights reserved.

1862

Adobe ColdFusion Documentation

ImageReadBase64
Description

Creates a ColdFusion image from a Base64 string.
Returns

A ColdFusion image.
Category

Image functions
Function syntax

ImageReadBase64(string)

See also

ImageNew, ImageRead, ImageWrite, ImageWriteBase64, BinaryDecode, BinaryEncode, IsImageFile
History

ColdFusion 8: Added this function.
Parameters

Parameter

Description

string

Required. The ColdFusion variable or Base64 string.

Usage

Base64 is a way to describe binary data as a printable string of characters. The ImageReadBase64 function takes
Base64 strings as input and creates images from the strings.The strings can be with or without the headers used to
pass Base64 images to an HTML  tag.Use this function to convert any Base64 string to a ColdFusion
image. Some databases store images as Base64 strings instead of BLOB data. You can query the database and
use the ImageReadBase64 function to convert the string into a ColdFusion image. This eliminates the intermediary
step of converting images with the BinaryEncode and BinaryDecode functions.Really Simple Syndication (RSS)
feeds transfer images in the form of embedded Base64 strings in the XML file. Use the ImageReadBase64 function
to read these images in ColdFusion.
Example

Example 1{{}}




© 2014 Adobe Systems Incorporated. All rights reserved.

1863

Adobe ColdFusion Documentation

Example 2{{}}




© 2014 Adobe Systems Incorporated. All rights reserved.

1864

Adobe ColdFusion Documentation

ImageResize
Description

Resizes a ColdFusion image.
Returns

Nothing.
Category

Image functions
Function syntax

ImageResize(name, width, height [, interpolation, blurFactor])

See also

cfimage, ImageSetAntialiasing, ImageScaleToFit, IsImageFile
History

ColdFusion 8: Added this function.
Parameters

Parameter

Description

name

Required. The ColdFusion image on which this
operation is performed.

width

Required. New width of the ColdFusion image.If this
value is blank, the width is calculated proportionately to
the height.

height

Required. New height of the ColdFusion image.If this
value is blank, the height is calculated proportionately
to the width.

© 2014 Adobe Systems Incorporated. All rights reserved.

1865

Adobe ColdFusion Documentation

Optional. The interpolation method for resampling. You
can specify a specific interpolation algorithm by name
(for example, hamming), by image quality (for example,
mediumQuality), or by performance (for example, hi
ghestPerformance). Valid values are:

interpolation

highestQuality (default)
highQuality
mediumQuality
highestPerformance
highPerformance
mediumPerformance
nearest
bilinear
bicubic
bessel
blackman
hamming
hanning
hermite
lanczos
mitchell
quadratic
See Interpolation algorithms in the Usage section for
more information.
Optional. The blur factor used for resampling. The
higher the blur factor, the more blurred the image (also,
the longer it takes to resize the image). This value must
be from 1 through 10.

blurFactor

Usage

You can use this function to enlarge an image or create a thumbnail image.To specify the height or width in pixels,
enter the integer, for example, 100. To specify the height or width as a percentage, enter the percentage followed by
the percent symbol, for example, 50%.To resize an image by one dimension (for example, height), specify the height
and leave width value blank (""). ColdFusion calculates the width proportionally to the height.Use the ImageSetAn
tialiasing function to improve the quality of the rendered image.
Interpolation algorithms

Interpolation algorithms let you fine-tune how images are resampled. Each algorithm balances image quality against
performance: in general, the higher the image quality, the slower the performance. Quality and performance differ
based on image type and the size of the source file. The following table describes the algorithms and their named
equivalents based on average test results:
Value

Named equivalents

Description

highestQuality (default)

lanczos

Highest image quality with low
performance

© 2014 Adobe Systems Incorporated. All rights reserved.

1866

Adobe ColdFusion Documentation

highQuality, mediumPerformance

mitchell, quadratic

Good image quality with slightly
higher performance

mediumQuality, highPerformance

hamming, hanning, hermite

Medium quality image with medium
performance

blackman, bessel

Slightly distorted image quality with
high performance

nearest, bicubic, bilinear

Poor image quality with highest
performance

highestPerformance

Example










© 2014 Adobe Systems Incorporated. All rights reserved.

1867

Adobe ColdFusion Documentation

ImageRotate
Description

Rotates a ColdFusion image at a specified point by a specified angle.
Returns

Nothing.
Category

Image functions
Function syntax

ImageRotate(name, angle [, x, y, interpolation])

See also

cfimage, ImageFlip, ImageSetAntialiasing, IsImageFile
History

ColdFusion 8: Added this function.
Parameters

Parameter

Description

name

Required. The ColdFusion image on which this
operation is performed.

angle

Required. The rotation angle in degrees.

x

Optional. The x coordinate for the point of rotation. The
default value is 2.

y

Optional. The y coordinate for the point of rotation. The
default value is 2.

© 2014 Adobe Systems Incorporated. All rights reserved.

1868

Adobe ColdFusion Documentation

interpolation

Optional. Type of interpolation:
nearest: Applies the nearest neighbor method of
interpolation. Image quality is lower than the other
interpolation methods, but processing is fastest
(default).
bilinear: Applies the bilinear method of
interpolation. The quality of the image is less
pixelated than the default, but processing is slower.
bicubic: Applies the bicubic method of
interpolation. Generally, the quality of image is
highest with this method and processing is slowest.

Usage

Specify both the x and the y coordinates or neither. If you do not specify the x and y coordinates, the point of rotation
is the center of the image, which is the default position. Use the ImageSetAntialiasing function to improve the
quality of the rendered image.
Example

Example 1









Example 2








© 2014 Adobe Systems Incorporated. All rights reserved.

1869

Adobe ColdFusion Documentation

ImageRotateDrawingAxis
Description

Rotates all subsequent drawing on a ColdFusion image at a specified point by a specified angle.
Returns

A ColdFusion image.
Category

Image functions
Function syntax

ImageRotateDrawingAxis(name, angle [, x, y])

See also

ImageRotate, ImageSetAntialiasing, ImageSetBackgroundColor, ImageSetDrawingColor, ImageSet
DrawingStroke, ImageSetDrawingTransparency, ImageShearDrawingAxis, IsImageFile
History

ColdFusion 8: Added this function.
Parameters

Parameter

Description

name

Required. The ColdFusion image on which this
operation is performed.

angle

Required. The rotation angle in degrees.

x

Optional. The x coordinate for the point of rotation. The
default value is 0.

y

Optional. The y coordinate for the point of rotation. The
default value is 0.

Usage

The default position of the origin is 0,0. To revert to the original drawing axis, call the same (x,y) parameters with the
negative of the original angle. Use the ImageSetAntialiasing function to improve the quality of the rendered
image.
Example

© 2014 Adobe Systems Incorporated. All rights reserved.

1870

Adobe ColdFusion Documentation
















© 2014 Adobe Systems Incorporated. All rights reserved.

1871

Adobe ColdFusion Documentation

ImageScaleToFit
Description

Creates a resized image with the aspect ratio maintained.
Returns

Nothing.
Category

Image functions
Function syntax

ImageScaleToFit(name, fitWidth, fitHeight [, interpolation , blurFactor])

See also

cfimage, ImageResize, ImageSetAntialiasing, IsImageFile
History

ColdFusion 8: Added this function.
Parameters

Parameter

Description

name

Required. The ColdFusion image on which this
operation is performed.

fitWidth

Required. The width of the bounding box in pixels. You
can specify an integer, or an empty string ("") if the fit
Height is specified. See the Usage section for more
information.

fitHeight

Required. The height of the bounding box in pixels. You
can specify an integer, or an empty string ("") if the fit
Width is specified. See the Usage section for more
information.

© 2014 Adobe Systems Incorporated. All rights reserved.

1872

Adobe ColdFusion Documentation

interpolation

Optional. The interpolation method for resampling. You
can specify a specific interpolation algorithm by name
(for example, hamming), by image quality (for example,
mediumQuality), or by performance (for example, hi
ghestPerformance). Valid values are:
highestQuality (default)
highQuality
mediumQuality
highestPerformance
highPerformance
mediumPerformance
nearest
bilinear
bicubic
bessel
blackman
hamming
hanning
hermite
lanczos
mitchell
quadratic
See Interpolation algorithms in the Usage section for
more information.

blurFactor

Optional. The blur factor used for resampling. The
higher the blur factor, the more blurred the image (also,
the longer it takes to resize the image). Valid values are
1-10.

Usage

Use this operation to resize images or create thumbnail images while maintaining the aspect ratio. Specify the fitW
idth and FitHeight parameters; either the fitWidth or the fitHeight can be an empty string:



In this example, the ImageScaleToFit function resizes the image so that it fits in a 100x100-pixel square; the
width of the resulting image is 100 pixels and the height is less than or equal to 100 pixels. For example, if the
source image is 400x200 pixels, the resulting image is 100x50 pixels.Likewise, if you specify the fitHeight param
eter and an empty string for the fitWidth parameter, the ImageScaleToFit function resizes the image so that
the height equals the fitHeight parameter and the width of the image is scaled proportionately:



In this example, a 400x200-pixel source image is resized to 200x100 pixels, and a 200x400-pixel image is resized to

© 2014 Adobe Systems Incorporated. All rights reserved.

1873

Adobe ColdFusion Documentation

50x100 pixels.If you set both the fitWidth and the fitHeight parameters, the ImageScaleToFit function
resizes the image proportionately so that both conditions are true: the width of the resulting image is less than or
equal to the fitWidth, and the height is less than or equal to the fitHeight:



In this example, a 400x200-pixel source image is resized to 100x50 pixels, and a 200x400-pixel source image is
resized to 100x200 pixels.Use the ImageSetAntialiasing function to improve the quality of the rendered image.
Example










© 2014 Adobe Systems Incorporated. All rights reserved.

1874

Adobe ColdFusion Documentation

ImageSetAntialiasing
Description

Switches antialiasing on or off in rendered graphics.
Returns

Nothing.
Category

Image functions
Function syntax

ImageSetAntialiasing(name [, antialias])

See also

ImageRotateDrawingAxis, ImageSetBackgroundColor, ImageSetDrawingColor, ImageSetDrawingSt
roke, ImageSetDrawingTransparency, IsImageFile
History

ColdFusion 8: Added this function.
Parameters

Parameter

Description

name

Required. The ColdFusion image on which this
operation is performed.

antialias

Optional. Antialiasing switch:
on (default)
off

Usage

The ImageSetAntialiasing function is used to turn antialiasing on and off when drawing shapes and text in an
image. Antialiasing is a technique used to soften jagged edges. Turn on antialiasing when using other image
functions, such as ImageDrawRoundRect and ImageRotate, to improve the quality of the rendered image. Notice
that antialiasing decreases performance.
Example

Example 1

© 2014 Adobe Systems Incorporated. All rights reserved.

1875

Adobe ColdFusion Documentation









Example 2















© 2014 Adobe Systems Incorporated. All rights reserved.

1876

Adobe ColdFusion Documentation

ImageSetBackgroundColor
Description

Sets the background color for the ColdFusion image. The background color is used for clearing a region. Setting the
background color only affects the subsequent ImageClearRect calls.
Returns

Nothing.
Category

Image functions
Function syntax

ImageSetBackgroundColor(name, color)

See also

ImageClearRect, ImageSetAntialiasing, IsImageFile
History

ColdFusion 8: Added this function.
Parameters

Parameter

Description

name

Required. The ColdFusion image on which this
operation is performed.

color

Required. Background color:
Hexadecimal value of RGB color. For example,
specify the color white as ##FFFFFF or FFFFFF.
String value of color (for example, "black", "red",
"green"). The default value of the drawing color is
"black".
List of three numbers for (R,G,B) values. Each value
must be in the range 0-255.

Usage

If the color value is a string, specify a supported named color; see the list of valid HTML named colors in cfimage.
For a hexadecimal value, use the form "##xxxxxx" or "xxxxxx", where x = 0-9 or A-F; use two number signs or
none.Use this function in conjunction with the ImageClearRect function to clear a rectangular area of an image
and set it to a specified color.
Example

© 2014 Adobe Systems Incorporated. All rights reserved.

1877

Adobe ColdFusion Documentation













© 2014 Adobe Systems Incorporated. All rights reserved.

1878

Adobe ColdFusion Documentation

ImageSetDrawingColor
Description

Sets the current drawing color for ColdFusion images. All subsequent graphics operations use the specified color.
Returns

Nothing.
Category

Image functions
Function syntax

ImageSetDrawingColor(name, color)

See also

ImageSetAntialiasing, ImageSetBackgroundColor, ImageSetDrawingStroke, ImageSetDrawingTra
nsparency, IsImageFile
History

ColdFusion 8: Added this function.
Parameters

Parameter

Description

name

Required. The ColdFusion image on which this
operation is performed.

color

Required. Drawing color:
Hexadecimal value of RGB color. For example,
specify the color white as "##FFFFFF" or "FFFFFF
".
String value of color (for example, "black", "red",
"green"). The default value of the drawing color is
"black".
List of three numbers for (R,G,B) values. Each value
must be in the range 0-255.

Usage

Use the ImageSetDrawingColor function to control the color of all subsequent drawing objects in ColdFusion
images. For example, you can use this function to set the drawing color to red once, and then draw a circle, a
square, and 10 lines in that color.If the color value is a string, specify a supported named color; see the list of valid
HTML named colors in cfimage. For a hexadecimal value, use the form "##xxxxxx" or "xxxxxx", where x = 0-9 or
A-F; use two number signs or none.

© 2014 Adobe Systems Incorporated. All rights reserved.

1879

Adobe ColdFusion Documentation
Example



















© 2014 Adobe Systems Incorporated. All rights reserved.

1880

Adobe ColdFusion Documentation

ImageSetDrawingStroke
Description

Sets the drawing stroke for points and lines in subsequent ColdFusion images.
Returns

Nothing.
Category

Image functions
Function syntax

ImageSetDrawingStroke(name [, attributeCollection])

See also

ImageDrawText, ImageSetAntialiasing, ImageSetBackgroundColor, ImageSetDrawingColor, ImageS
etDrawingTransparency, IsImageFile
History

ColdFusion 8: Added this function.
Parameters

Parameter

Description

name

Required. The ColdFusion image on which this
operation is performed.

attributeCollection

Optional. The structure used to specify the line
attributes. See the Usage section.

Usage

Use the ImageSetDrawingStroke function to control the line attributes of all subsequent drawing objects in a
ColdFusion image. For example, you can use this function to set the drawing stroke to a dash pattern once, and
then create a rectangle, two ovals, and five lines with that pattern.If a blank or no attribute structure is passed, the
drawing stroke is reset to the default values.
attributeCollection

Element

Description

width

Pen width, which is measured perpendicularly to the
pen trajectory.

© 2014 Adobe Systems Incorporated. All rights reserved.

1881

Adobe ColdFusion Documentation

endcaps

Decoration applied to the ends of unclosed subpaths
and dash segments. Subpaths that start and end on
the same point are considered unclosed if they do not
have a close segment:
butt
round
square

lineJoins

Type of line joins:
bevel
miter
join

miterLimit

The limit to trim a line join that has a mitered join
decoration. (Use only when lineJoins = "miter".)
A line join is trimmed when the ratio of miter length to
stroke width is greater than the miterLimit value.
The miter length is the diagonal length of the miter,
which is the distance between the inside corner and the
outside corner of the intersection. The smaller the
angle formed by two line segments, the longer the miter
length and the sharper the angle of intersection. The
default value is 10.0, which trims all angles less than 11
degrees. Trimming miters converts the decoration of
the line join to bevel.

dashArray

An array of numbers that indicates the dash pattern.
For example. if dashArray is (8,4), the dash pattern is
8 pixels solid, 4 pixels blank, 8 pixels solid, 4 pixels
blank, and so on.

dash_phases

An offset into the dash pattern. For example, a dash_p
hase of 2, and a dashArray of (8,4) produces the
dash pattern of 6 pixels solid, 4 pixels blank, 8 pixels
solid, 4 pixels blank, and so on.

Example

Example 1

© 2014 Adobe Systems Incorporated. All rights reserved.

1882

Adobe ColdFusion Documentation



















Example 2

© 2014 Adobe Systems Incorporated. All rights reserved.

1883

Adobe ColdFusion Documentation






























© 2014 Adobe Systems Incorporated. All rights reserved.

1884

Adobe ColdFusion Documentation

ImageSetDrawingTransparency
Description

Specifies the degree of transparency of drawing functions.
Returns

Nothing.
Category

Image functions
Function syntax

ImageSetDrawingTransparency(name, percent)

See also

ImageSetAntialiasing, ImageSetBackgroundColor, ImageSetDrawingColor, ImageSetDrawingStro
ke, IsImageFile
History

ColdFusion 8: Added this function.
Parameters

Parameter

Description

name

Required. The ColdFusion image on which this
operation is performed.

percent

Required. Percent of transparency:
0 = opaque
100 = transparent
Decimal values are valid.

Usage

By default drawing images are opaque. Use this function to create watermarks or other translucent images. Use the
ImageSetAntialiasing function to improve the quality of the rendered image.
Example

Example 1

© 2014 Adobe Systems Incorporated. All rights reserved.

1885

Adobe ColdFusion Documentation

















Example 2


















Example 3

© 2014 Adobe Systems Incorporated. All rights reserved.

1886

Adobe ColdFusion Documentation

















© 2014 Adobe Systems Incorporated. All rights reserved.

1887

Adobe ColdFusion Documentation

ImageSharpen
Description

Sharpens a ColdFusion image by using the unsharp mask filter.
Returns

Nothing.
Category

Image functions
Function syntax

ImageSharpen(name [, gain])

See also

ImageBlur, ImageSetAntialiasing, IsImageFile
History

ColdFusion 8: Added this function.
Parameters

Parameter

Description

name

Required. The ColdFusion image on which this
operation is performed.

gain

Optional. -1 <= gain <= 2.Gain values can be integers
or real numbers. The default value is 1.0.The value
determines whether the image is blurred or sharpened:
If > 0, the image is sharpened.
If = 0, no effect
If < 0, the image is blurred.

Usage

Use this function to sharpen outlines in photographs. Use the ImageSetAntialiasing function to improve the
quality of the rendered image.
Example

© 2014 Adobe Systems Incorporated. All rights reserved.

1888

Adobe ColdFusion Documentation













© 2014 Adobe Systems Incorporated. All rights reserved.

1889

Adobe ColdFusion Documentation

ImageShear
Description

Shears an image either horizontally or vertically. For each pixel (x, y) of the destination, the source value at the
fractional subpixel position (x', y') is constructed with an Interpolation object and written to the destination.
Returns

Nothing.
Category

Image functions
Function syntax

ImageShear(name, shear [, direction, interpolation])

See also

ImageSetAntialiasing, ImageShearDrawingAxis, IsImageFile
History

ColdFusion 8: Added this function.
Parameters

Parameter

Description

name

Required. The ColdFusion image on which this
operation is performed.

shear

Required. Shear value. Coordinates can be integers or
real numbers.

direction

Optional. Shear direction:
horizontal (default)
vertical

© 2014 Adobe Systems Incorporated. All rights reserved.

1890

Adobe ColdFusion Documentation

interpolation

Optional. Type of interpolation:
nearest: Applies the nearest neighbor method of
interpolation. Image quality is lower than the other
interpolation methods, but processing is fastest
(default).
bilinear: Applies the bilinear method of
interpolation. The quality of the image is less
pixelated than the default, but processing is slower.
bicubic: Applies the bicubic method of
interpolation. Generally, the quality of image is
highest with this method and processing is slowest.

Usage

Use this function to distort an image.If the direction parameter is set to horizontal, x' = (x - y*shear) and y' =
y.If the direction parameter is set to vertical, x' = x and y' = (y - x*shear).Use the ImageSetAntialiasing f
unction to improve the quality of the rendered image.
Example











© 2014 Adobe Systems Incorporated. All rights reserved.

1891

Adobe ColdFusion Documentation

ImageShearDrawingAxis
Description

Shears the drawing canvas.
Returns

Nothing.
Category

Image functions
Function syntax

ImageShearDrawingAxis(name, shx, shy)

See also

ImageRotateDrawingAxis, ImageSetAntialiasing, ImageShear, IsImageFile
History

ColdFusion 8: Added this function.
Parameters

Parameter

Description

name

Required. The ColdFusion image on which this
operation is performed.

shx

Required. The multiplier by which coordinates are
shifted in the positive x axis direction as a function of
the y coordinate.

shy

Required. the multiplier by which coordinates are
shifted in the positive y axis direction as a function of
the x coordinate.

Usage

For each pixel (x,y) of the destination, the source value at the fractional subpixel position (x',y') is constructed with
an interpolation object and written to the destination.If the direction parameter is equal to horizontal, x' =
(x - y*shear) and y' = y. If the direction parameter is equal to vertical, x' = x and y' = (y x*shear).Use the ImageSetAntialiasing function to improve the quality of the rendered image.
Example

© 2014 Adobe Systems Incorporated. All rights reserved.

1892

Adobe ColdFusion Documentation












© 2014 Adobe Systems Incorporated. All rights reserved.

1893

Adobe ColdFusion Documentation

ImageTranslate
Description

Copies an image to a new location on the plane.
Returns

Nothing.
Category

Image functions
Function syntax

ImageTranslate(name, xTrans, yTrans [, interpolation])

See also

ImageSetAntialiasing, ImageShear, ImageTranslateDrawingAxis, IsImageFile
History

ColdFusion 8: Added this function.
Parameters

Parameter

Description

name

Required. The ColdFusion image on which this
operation is performed.

xTrans

Required. Displacement in the x direction.

yTrans

Required. Displacement in the y direction.

interpolation

Optional. Type of interpolation used for resampling:
nearest: Applies the nearest neighbor method of
interpolation. Image quality is lower than the other
interpolation methods, but processing is fastest
(default).
bilinear: Applies the bilinear method of
interpolation. The quality of the image is less
pixelated than the default, but processing is slower.
bicubic: Applies the bicubic method of
interpolation. Generally, the quality of image is
highest with this method and processing is slowest.

Usage

© 2014 Adobe Systems Incorporated. All rights reserved.

1894

Adobe ColdFusion Documentation

For each pixel (x, y) of the destination, the source value at the fractional subpixel position (x - xTrans, y yTrans) is constructed with an interpolation object and written to the destination. If both xTrans and yTrans are
integral, the operation wraps the source image to change the image's position in the coordinate plane.Use the Imag
eSetAntialiasing function to improve the quality of the rendered image.
Example










© 2014 Adobe Systems Incorporated. All rights reserved.

1895

Adobe ColdFusion Documentation

ImageTranslateDrawingAxis
Description

Translates the origin of the image context to the point (x,y) in the current coordinate system. Modifies the image
context so that its new origin corresponds to the point (x,y) in the image's original coordinate system.
Returns

Nothing.
Category

Image functions
Function syntax

ImageTranslateDrawingAxis(name, x, y)

See also

ImageSetAntialiasing, ImageSetDrawingColor, ImageSetDrawingStroke, ImageSetDrawingTransp
arency, ImageShearDrawingAxis, ImageTranslate, IsImageFile
History

ColdFusion 8: Added this function.
Parameters

Parameter

Description

name

Required. The ColdFusion image on which this
operation is performed.

x

x coordinate

y

y coordinate

Usage

All coordinates used in subsequent rendering operations on this image context are relative to the new origin. Use
the ImageSetAntialiasing function to improve the quality of the rendered image.
Example

© 2014 Adobe Systems Incorporated. All rights reserved.

1896

Adobe ColdFusion Documentation












© 2014 Adobe Systems Incorporated. All rights reserved.

1897

Adobe ColdFusion Documentation

ImageWrite
Description

Writes a ColdFusion image to the specified on-disk or in-memory destination.
Returns

Nothing.
Category

Image functions
Function syntax

ImageWrite(name [, destination, quality, overwrite])

See also

cfimage, GetWriteableImageFormats, ImageNew, ImageRead, IsImageFile
History

ColdFusion 8: Added this function.
Parameters

Parameter

Description

name

Required. The ColdFusion image on which this
operation is performed.

destination

Optional. The absolute or relative on-disk or in-memory
pathname where you write the file.If you create the
image with the ImageNew function or another operation
where you do not specify the filename, specify the des
tination parameter.The file format is derived from
the extension of the filename. The default value for this
parameter is the filename of the original image source.

quality

Optional. Defines the JPEG quality used to encode the
image. This parameter applies only to destination files
with an extension of JPG or JPEG. Valid values are
fractions that range from 0 through 1 (the lower the
number, the lower the quality). The default value is
0.75.

overwrite

Optional. If set to true, overwrites the destination file.

Usage

© 2014 Adobe Systems Incorporated. All rights reserved.

1898

Adobe ColdFusion Documentation

Use the following syntax to specify an in-memory file, which is not written to disk. In-memory files speed processing
of transient data.

ram:///filepath

The filepath can include directories, for example ram:///petStore/images/poodle.jpg. Create the directories
in the path before you specify the file. For more information on using in-memory files, see Working with in-memory
files in Optimizing ColdFusion applications in the Developing ColdFusion Applications.The file format is derived from
the file extension, therefore, use this function to convert images.For a list of valid formats to write, see the supported
image file formats listed in cfimage. To retrieve a list of writable formats on the server where the ColdFusion
application is deployed, use the GetWriteableImageFormats function.
Note
Converting images between one file format to another is time-consuming. Also, image quality can
degrade; for example, PNG images support 24-bit color, but GIF images support only 256 colors.
Converting transparent images (images with alpha) can degrade image quality.

Example









© 2014 Adobe Systems Incorporated. All rights reserved.

1899

Adobe ColdFusion Documentation

ImageWriteBase64
Description

Writes Base64 images to the specified on-disk or in-memory destination.
Returns

Base64 string.
Category

Image functions
Function syntax

ImageWriteBase64(name, destination, format [, inHTMLFormat, optional])

See also

cfimage, ImageReadBase64, IsImageFile
History

ColdFusion 8: Added this function.
Parameters

Parameter

Description

name

Required. The ColdFusion image on which this
operation is performed.

destination

Required. The absolute or relative on-disk or
in-memory pathname where you write the file.

format

Required. The format

inHTMLFormat

Optional. Specify whether Base64 output includes the
headers used by the Base64 images in the HTML  tag ("data:image/;base64,...") :
yes
no (default)

overwrite

Optional. If set to true, overwrites the destination file.

Usage

You use the ImageWriteBase64 function to encode image data as a string of printable characters. This is useful
for several applications, including sending images by e-mail and storing images in database text fields.Use the
following syntax to specify an in-memory file, which is not written to disk. In-memory files speed processing of

© 2014 Adobe Systems Incorporated. All rights reserved.

1900

Adobe ColdFusion Documentation

transient data.

ram:///filepath

The filepath can include directories, for example ram:///petStore/images/poodle.jpg. Create the directories
in the path before you specify the file. For more information on using in-memory files, see Working with in-memory
files in Optimizing ColdFusion applications in the Developing ColdFusion Applications. If you do not specify a file
format, ColdFusion cannot recognize the format required to encode the image before converting to Base64, and
generates errors.You can verify whether ColdFusion reads a Base64 string properly in the following ways:
Use the cfdump tag. For example: 
Use the ImageInfo function. For example: 
Use the ImageWrite function and save the image as a JPEG file. Then open the JPEG file in a browser or
imaging application.
Example







© 2014 Adobe Systems Incorporated. All rights reserved.

1901

Adobe ColdFusion Documentation

ImageXORDrawingMode
Description

Sets the paint mode of the image to alternate between the image's current color and the new specified color.
Returns

Nothing.
Category

Image functions
Function syntax

ImageXORDrawingMode(name, c1)

See also

ImageSetDrawingColor, IsImageFile
History

ColdFusion 8: Added this function.
Parameters

Parameter

Description

name

Required. The ColdFusion image on which this
operation is performed.

c1

Required. XOR alternation color:
Hexadecimal value of the RGB color. For example,
specify the color white as "##FFFFFF" or "FFFFFF
".
String value of color (for example, "black", "red",
"green").

Usage

This function alternates pixels between the current color and a new specified XOR (exclusive Or) color.When
drawing operations are performed, pixels that are the current color are changed to the specified color, and vice
versa.Pixels that are of colors other than current color or the new specified color are changed in an unpredictable
but reversible manner. If the same figure is drawn twice, all pixels are restored to their original values.If the color
value is a string, specify a supported named color; see the list of valid HTML named colors in cfimage. For a
hexadecimal value, use the form "##xxxxxx" or "xxxxxx", where x = 0-9 or A-F; use two number signs or none.
Example

© 2014 Adobe Systems Incorporated. All rights reserved.

1902

Adobe ColdFusion Documentation



























#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

1903

Adobe ColdFusion Documentation

ImageGetMetadata
You can use this function to retrieve all metadata about the image including exif, IPTC, camera-specific information.
Returns

Returns a struct containing the information about the image.
Parameter

Parameter
image

Description
Required. An Image object.

Example




AF Area Mode : #StructFind(All,"AF Area Mode")#

Camera Uptime : #StructFind(All,"Camera Uptime")#

Exif Version : #StructFind(All,"Exif Version")#



© 2014 Adobe Systems Incorporated. All rights reserved.

1904

Adobe ColdFusion Documentation

Functions in-k
IncrementValue
InputBaseN
Insert
Int
Invoke
IsArray
IsAuthenticated
IsAuthorized
IsBinary
IsBoolean
IsClosure
IsCustomFunction
IsDate
IsDDX
IsDebugMode
IsDefined
IsImage
IsImageFile
IsInstanceOf
IsIPv6
IsJSON
IsK2ServerABroker
IsK2ServerDocCountExceeded
IsK2ServerOnline
IsLeapYear
IsLocalHost
IsNull
IsNumeric
IsNumericDate
IsObject
isOnline
IsPDFFile
IsPDFObject
IsProtected
IsQuery
IsSimpleValue
IsSOAPRequest
IsSpreadsheetFile
IsSpreadsheetObject
IsStruct
IsUserInAnyRole
IsUserInRole
IsUserLoggedIn
IsValid
IsWDDX
IsXML
IsXmlAttribute
IsXmlDoc
IsXmlElem
IsXmlNode

© 2014 Adobe Systems Incorporated. All rights reserved.

1905

Adobe ColdFusion Documentation

IsXmlRoot
JavaCast
JSStringFormat
isSafeHTML
InvalidateOauthAccesstoken
IsValidOauthAccesstoken
InvokeCFClientFunction

© 2014 Adobe Systems Incorporated. All rights reserved.

1906

Adobe ColdFusion Documentation

IncrementValue
Description

Adds one to an integer.
Returns

The integer part of number, incremented by one.
Category

Mathematical functions
Function syntax

IncrementValue(number)

See also

DecrementValue
Parameters

Parameter

Description

number

Number to increment

Example

IncrementValue Example
Returns the integer part of a number incremented by one.
IncrementValue(0): #IncrementValue(0)#
IncrementValue("1"): #IncrementValue("1")#
IncrementValue(123.35): #IncrementValue(123.35)#

© 2014 Adobe Systems Incorporated. All rights reserved.

1907

Adobe ColdFusion Documentation

InputBaseN
Description

Converts string, using the base specified by radix, to an integer.
Returns

A number in the range 2-36, as a string.
Category

Mathematical functions
Function syntax

InputBaseN(string, radix)

See also

FormatBaseN
Parameters

Parameter

Description

string

A string or a variable that contains one. String that
represents a number, in the base specified by radix.

radix

Base of the number represented by string, in the
range 2-36.

Example

© 2014 Adobe Systems Incorporated. All rights reserved.

1908

Adobe ColdFusion Documentation

InputBaseN Example
FormatBaseN converts a number to a string in the base specified by Radix.



FormatBaseN(10,2): #FormatBaseN(10,2)#

FormatBaseN(1024,16): #FormatBaseN(1024,16)#

FormatBaseN(125,10): #FormatBaseN(125,10)#

FormatBaseN(10.75,2): #FormatBaseN(10.75,2)#

InputBaseN Example
InputBaseN returns the number obtained by converting a string,
using the base specified by Radix,.


InputBaseN("1010",2): #InputBaseN("1010",2)#

InputBaseN("3ff",16): #InputBaseN("3ff",16)#

InputBaseN("125",10): #InputBaseN("125",10)#

InputBaseN(1010,2): #InputBaseN(1010,2)#


© 2014 Adobe Systems Incorporated. All rights reserved.

1909

Adobe ColdFusion Documentation

Insert
Description

Inserts a substring in a string after a specified character position. If position = 0, prefixes the substring to the
string.
Returns

A string.
Category

String functions
Function syntax

Insert(substring, string, position)

See also

RemoveChars, Len
Parameters

Parameter

Description

substring

A string or a variable that contains one. String to insert.

string

A string or a variable that contains one. String into
which to insert substring.

position

Integer or variable; position in string after which to
insert substring.

Example

© 2014 Adobe Systems Incorporated. All rights reserved.

1910

Adobe ColdFusion Documentation

Insert Example




This string only has #Len(MyString)# characters; therefore,
you cannot insert the substring
#FORM.mySubString# at position
#FORM.insertPosition#.




You inserted the substring #FORM.MySubstring# into the string
#FORM.MyString#, resulting in the following string:

#Insert(FORM.MySubString, FORM.myString,
FORM.insertposition)#



© 2014 Adobe Systems Incorporated. All rights reserved.

1911

Adobe ColdFusion Documentation

Int
Description

Calculates the closest integer that is smaller than number. For example, it returns 3 for Int(3.3) and for Int(3.7
); it returns -4 for Int(-3.3) and for Int(-3.7)
Returns

An integer, as a string.
Category

Mathematical functions
Function syntax

Int(number)

See also

Ceiling, Fix, Round
Parameters

Parameter

Description

number

Real number to round down to an integer.

Example

Int Example
Int returns the closest integer smaller than a number.
Int(11.7) : #Int(11.7)#
Int(-11.7) : #Int(-11.7)#
Int(0) : #Int(0)#

© 2014 Adobe Systems Incorporated. All rights reserved.

1912

Adobe ColdFusion Documentation

Invoke
Description

Does either of the following:
Invokes a component method from within a ColdFusion page or component
Invokes a web service
Returns

Returns what is returned by the invoked method.
History

ColdFusion 10: Added this function
Syntax

invoke(cfcinstance, methodname [, arguments])
Properties

Parameter

Description

cfcinstance

Required. String or component object; a reference to a
component, or component to instantiate.

methodname

Required. Name of a method. For a web service, the
name of an operation.

arguments

Optional. Arguments to pass to the method.

Example


obj = createObject("component","TestComponent");
invoke(obj,"function1",{a1="ColdFusion"});


© 2014 Adobe Systems Incorporated. All rights reserved.

1913

Adobe ColdFusion Documentation

IsArray
Description

Determines whether a value is an array.
Returns

True, if value is an array, or a query column object.
Category

Array functions, Decision functions
Function syntax

IsArray(value [, number ])

See also

Array functions; Modifying a ColdFusion XML object in the Developing ColdFusion Applications
History

ColdFusion MX:
Changed behavior: if the value parameter contains a reference to a query result column, this function now
returns True. For example: isArray(MyQuery Column1) returns True. (In earlier releases, it returns
False.)
Changed behavior: this function can be used on XML objects.
Parameters

Parameter

Description

value

Variable or array name

number

Dimension; function tests whether the array has exactly
this dimension

Usage

Use this function to determine whether a value is an array or query column. This function evaluates a Java array
object, such as a vector object, as having one dimension.
Example

© 2014 Adobe Systems Incorporated. All rights reserved.

1914

Adobe ColdFusion Documentation

IsArray Example








Is this an array? #IsArray(MyNewArray)#
It has #ArrayLen(MyNewArray)# elements.
Contents: #ArrayToList(MyNewArray)#


© 2014 Adobe Systems Incorporated. All rights reserved.

1915

Adobe ColdFusion Documentation

IsAuthenticated
Description

This function is obsolete. Use the newer security tools; see Conversion functions and Securing Applications in the D
eveloping ColdFusion Applications.
History

ColdFusion MX: This function is obsolete. It does not work in ColdFusion MX and later ColdFusion releases.

© 2014 Adobe Systems Incorporated. All rights reserved.

1916

Adobe ColdFusion Documentation

IsAuthorized
Description

This function is obsolete. Use the newer security tools; see Conversion functions and Securing Applications in the D
eveloping ColdFusion Applications
History

ColdFusion MX: This function is obsolete. It does not work in ColdFusion MX and later releases.

© 2014 Adobe Systems Incorporated. All rights reserved.

1917

Adobe ColdFusion Documentation

IsBinary
Description

Determines whether a value is stored as binary data.
Returns

True, if the value is binary; False, otherwise.
Category

Decision functions
Function syntax

IsBinary(value)

See also

ToBinary, ToBase64, IsNumeric, YesNoFormat
Parameters

Parameter

Description

value

Number or string

Example

© 2014 Adobe Systems Incorporated. All rights reserved.

1918

Adobe ColdFusion Documentation







The following string is the concatenation of all characters (32 to 255) from the
ASCII table.


#htmleditformat(charData)#









The binaryData variable is binary!





The another64 variable is NOT binary!




Base 64 representation of binary data is identical to the Base 64
representation of string data.

Conversion error.


© 2014 Adobe Systems Incorporated. All rights reserved.

1919

Adobe ColdFusion Documentation

IsBoolean
Description

Determines whether a value can be converted to Boolean
Returns

True, if the parameter can be converted to Boolean; False, otherwise.
Category

Decision functions
Function syntax

IsBoolean(value)

See also

IsNumeric, IsValid, YesNoFormat
Parameters

Parameter

Description

value

Number or string

Example

IsBoolean Example


The expression #DE(FORM.theTestValue)# is
Boolean

The expression #DE(FORM.theTestValue)# is not
Boolean



Enter an expression, and discover whether it can be evaluated to a
Boolean value.




© 2014 Adobe Systems Incorporated. All rights reserved.

1920

Adobe ColdFusion Documentation

IsClosure
Description

Determines whether a value or expression references a function defined via a function expression, as opposed to a f
unction statement.
Returns

True, if the value represents a function expression; otherwise False.
Category

Decision functions
Syntax

isClosure(value)
See also

Other decision functions.
History

ColdFusion 10: Added this function.
Parameters

Parameter

Description

value

A value.

Usage

Use this function to determine whether the value or expression represents a function defined via a function
expression.
Example


// a custom function defined via a function statement
function multiplier(x,y){
return x * y;
}
// a custom function defined via a function expression
adder = function(x,y){
return x + y;
};
// a string containing the name of the function reference
name = "multiplier";



© 2014 Adobe Systems Incorporated. All rights reserved.

1921

Adobe ColdFusion Documentation



isCustomFunction(referenceToDeclaredFunction):
#isCustomFunction(multiplier)#
 
isClosure(referenceToDeclaredFunction):
#isClosure(multiplier)#
 

isCustomFunction(referenceToFunctionExpression):
#isCustomFunction(adder)#
 
isClosure(referenceToFunctionExpression):
#isClosure(adder)#
 



isCustomFunction(stringContainingNameOfFunctionReference):
#isCustomFunction(name)#
 
isClosure(stringContainingNameOfFunctionReference):
#isClosure(name)#
 

isCustomFunction("adder"):
#isCustomFunction("adder")#
 
isClosure("adder"):
#isClosure("adder")#
 


// an expression can be evaluated directly
result = isCustomFunction(function(x,y){
return x-y;
}
);
writeOutput("isCustomFunction(inlineExpression): #result#
"); // false
result = isClosure(function(x,y){
return x-y;
}
);

© 2014 Adobe Systems Incorporated. All rights reserved.

1922

Adobe ColdFusion Documentation

writeOutput("isClosure(inlineExpression): #result#
"); // true


© 2014 Adobe Systems Incorporated. All rights reserved.

1923

Adobe ColdFusion Documentation

IsCustomFunction
Description

Determines whether a name represents a custom function.
Returns

True, if name can be called as a custom function; False, otherwise.
Category

Decision functions
Function syntax

IsCustomFunction(name)

Parameters

Parameter

Description

name

Name of a custom function. Must not be in quotation
marks. If not a defined variable or function name,
ColdFusion generates an error.

Usage

The IsCustomFunction function returns True for any function that can be called as a custom function, including
functions defined using CFScript function declarations and cffunction tags, and functions that are ColdFusion
component methods. For CFC methods, first instantiate the component.
Note
To prevent undefined variable exceptions, always precede IsCustomFunction with an IsDef
ined test, as shown in the example.

Note
This function does not return true if the function was defined using a function expression, eg:
realUDF = function() {
return 1;
}
For functions defined using function expressions, use isClosure().

Example

© 2014 Adobe Systems Incorporated. All rights reserved.

1924

Adobe ColdFusion Documentation

IsCustomFunction Example

function realUDF() {
return 1;
}




Foo is a UDF.




X is a UDF.




realUDF is a function.





myTestCFCobject.testFunc is a function.


© 2014 Adobe Systems Incorporated. All rights reserved.

1925

Adobe ColdFusion Documentation

IsDate
Description

Determines whether a string or Java object can be converted to a date/time value.
Returns

True, if string can be converted to a date/time value; False, otherwise. ColdFusion converts the Boolean return value
to its string equivalent, "Yes" or "No."
Category

Date and time functions, Decision functions
Function syntax

IsDate(string)

See also

CreateDateTime, IsNumericDate, IsValid, LSDateFormat, LSIsDate, ParseDateTime
Parameters

Parameter

Description

string

A string or a variable that contains one.

Usage

This function checks against U.S. date formats only. For other date support, see LSDateFormat.A date/time object
falls in the range 100 AD-9999 AD.
Example

© 2014 Adobe Systems Incorporated. All rights reserved.

1926

Adobe ColdFusion Documentation

IsDate Example


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

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



Enter a string, find whether it can be evaluated to a date value.




© 2014 Adobe Systems Incorporated. All rights reserved.

1927

Adobe ColdFusion Documentation

IsDDX
Description

Determines whether a DDX file exists and is valid, or if a string contains valid DDX instructions.
Returns

True, if the value represents a valid DDX file or string. False, otherwise.
Category

Decision functions
Function syntax

IsDDX("path or string")

See also

IsPDFObject, IsPDFFile, cfpdf
History

ColdFusion 8: Added this function.
Parameters

Parameter

Description

path or string

Pathname to the DDX file or a string of DDX
instructions. The pathname can be absolute or relative
to the CFM page that calls it and must be enclosed in
quotation marks.

Usage

This function returns False if the pathname to the DDX file is invalid, the pathname to the DDX file is null, the DDX
file does not conform to the schema supported by ColdFusion, or the DDX instructions are invalid.
Example

© 2014 Adobe Systems Incorporated. All rights reserved.

1928

Adobe ColdFusion Documentation



inputStruct.Doc0="title.pdf">
inputStruct.Doc1="Chap1.pdf">
inputStruct.Doc2="Chap2.pdf">
inputStruct.Doc3="Chap3.pdf">
inputStruct.Doc4="Chap4.pdf">




#ddxVar.Out1#

This is not a valid DDX file.


© 2014 Adobe Systems Incorporated. All rights reserved.

1929

Adobe ColdFusion Documentation

IsDebugMode
Description

Determines whether debugging output is enabled.
Returns

True, if debugging mode is set in the ColdFusion Administrator; False if debugging mode is disabled.
Category

Decision functions
Function syntax

IsDebugMode()

See also

cfsetting
Description

If debugging output is enabled in ColdFusion Administrator and has not been overridden by setting the cfsetting t
ag showDebugOutput attribute to No, the IsDebugMode function returns Yes; No, otherwise.
Example

IsDebugMode Example

Debugging is set in the ColdFusion Administrator

Debugging is disabled


© 2014 Adobe Systems Incorporated. All rights reserved.

1930

Adobe ColdFusion Documentation

IsDefined
Description

Evaluates a string value to determine whether the variable named in it exists. This function is an alternative to the P
arameterExists function, which is deprecated.
Returns

True, if the variable is found; False, otherwise.
Category

Decision functions
Function syntax

IsDefined("variable_name")

See also

Evaluate
History

ColdFusion MX: Changed behavior: this function can process only the following constructs:
A simple variable
A named variable with dot notation
A named structure with dot notation (for example: mystruct.key)
Parameters

Parameter

Description

variable_name

String, enclosed in quotation marks. Name of variable
to test for.

Usage

Passing an array entry, such as myArray3 to this function causes an error. To check whether a specific entry exists
in an array, use the ArrayIsDefined function.You can test whether a specific key exists in a structure by using this
function or the StructKeyExists function. For example, when working with scopes that ColdFusion exposes as
structures, the StructKeyExists function can sometimes replace this function. The following lines are equivalent:

if(isDefined("form.myVariable"))
if(structKeyExists(form,"myVariable"))

Example

© 2014 Adobe Systems Incorporated. All rights reserved.

1931

Adobe ColdFusion Documentation


The variable form.myString has been defined, so show its contents.
This construction allows us to place a form and its resulting action code
on the same page and use IsDefined to control the flow of execution.
The value of "form.myString" is 
#form.myString#

During the first time through this template, the variable "form.myString"
has not yet been defined, so we do not try to evaluate it.






© 2014 Adobe Systems Incorporated. All rights reserved.

1932

Adobe ColdFusion Documentation

IsImage
Description

Determines whether a variable returns a ColdFusion image.
Returns

True, if the value is a ColdFusion image; False, otherwise.
Category

Image functions
Function syntax

IsImage(name)

See also

cfimage, ImageGetBlob, ImageInfo, ImageNew
History

ColdFusion 8: Added this function.
Parameters

Parameter

Description

name

Required. The ColdFusion variable that is checked.

Usage

Use this function to determine whether a variable returns a ColdFusion image.
Example



...




© 2014 Adobe Systems Incorporated. All rights reserved.

1933

Adobe ColdFusion Documentation

IsImageFile
Description

Verifies whether an image file is valid.
Returns

True, if the value is a valid image file; False, otherwise.
Category

Image functions
Function syntax

IsImageFile("path")

See also

cfimage, ImageGetBlob, ImageInfo, ImageNew, IsImage
History

ColdFusion 8: Added this function.
Parameters

Parameter

Description

path

Required. The pathname of the on-disk or in-memory
file, or URL, to be checked. The pathname can be
absolute or relative to the CFM page and must be
enclosed in quotation marks.

Usage

Use this function to determine whether an image file is valid. This function returns a False value if the image file
format is not supported by the server where ColdFusion is deployed, or if the pathname to the image file is null or
invalid.For a list of standard image file formats supported by ColdFusion, see the supported image file formats
provided in cfimage. To determine which image file formats are supported on the server where ColdFusion is
deployed, use the GetReadableImageFormats and GetWriteableImageFormats.
Example

© 2014 Adobe Systems Incorporated. All rights reserved.

1934

Adobe ColdFusion Documentation







I'm sorry, there is no image associated with the title you selected. Please
click the Back button and try again.



© 2014 Adobe Systems Incorporated. All rights reserved.

1935

Adobe ColdFusion Documentation

IsInstanceOf
Description

Determines whether an object is an instance of a ColdFusion interface or component, or of a Java class.
Returns

Returns true if any of the following is true:
The object specified by the first parameter is an instance of the interface or component specified by the
second parameter.
The Java object specified by the first parameter was created by using the cfobject tag or CreateObject
method and is an instance of the Java class specified by the second parameter.
The object specified by the first parameter is an instance of a component that extends the component
specified in the second parameter.
The object specified by the first parameter is an instance of a component that extends a component that
implements the interface specified in the second parameter.
The Java object specified by the first parameter was created by using the cfobject tag or CreateObject
method and is an instance of a Java class that extends the class specified by the second parameter.Returns
false otherwise.
Note
The isInstanceOf function returns false if the CFC specified by the object paramet
er does not define any functions.

Category

Decision functions, Extensibility functions
Function syntax

IsInstanceOf(object, typeName)

See also

cfcomponent, cfinterface, cfobject
History

ColdFusion 8: Added this function.
Parameters

Parameter

Description

object

The CFC instance or Java object that you are testing

typeName

The name of the interface, component, or Java class of
which the object might be an instance

© 2014 Adobe Systems Incorporated. All rights reserved.

1936

Adobe ColdFusion Documentation
Usage

For Java objects, the comparison is valid only if you created the object specified in the first parameter by using a cf
object tag or CreateObject method.
Example









C1.method1 called








IsInstanceOf(c1obj,"C1") = #IsInstanceOf(c1obj,"C1")#
(Expected = YES)


IsInstanceOf(c1obj,"I1") = #IsInstanceOf(c1obj,"I1")#
(Expected = YES)


IsInstanceOf(c1obj,"C2") = #IsInstanceOf(c1obj,"C2")#
(Expected = NO)


IsInstanceOf(javaObj,"java.lang.System") =
#IsInstanceOf(javaObj,"java.lang.System")# (Expected = YES)


IsInstanceOf(javaObj,"java.lang.String") =
#IsInstanceOf(javaObj,"java.lang.String")# (Expected = NO)




© 2014 Adobe Systems Incorporated. All rights reserved.

1937

Adobe ColdFusion Documentation

IsIPv6
Description

Determines whether the host supports IPv6.
Returns

True if the host supports IPv6.
Category

Decision functions
Syntax

IsIPv6()
IsIPv6(hostname)

See also

GetLocalHostIP, IsLocalHost
History

ColdFusion 9: Added this function
Usage

When you use this function to verify if the remote host supports IPv6, pass the hostname and not the IP
address.This function applies only if the server that places the request is IPv6-enabled.
Example

The following example checks whether the localhost supports IPv6:




localhost supports IPv6


The following example checks whether the remote host supports IPv6:




#hostname# supports IPv6


© 2014 Adobe Systems Incorporated. All rights reserved.

1938

Adobe ColdFusion Documentation

IsJSON
Description

Evaluates whether a string is in valid JSON (JavaScript Object Notation) data interchange format.
Returns

True if the parameter is a valid JSON value.False if the parameter is not a valid JSON data representation.
Category

Conversion functions
Syntax

IsJSON(var)

See also

DeserializeJSON, SerializeJSON, cfajaxproxy, Using Ajax Data and Development Features in the Developi
ng ColdFusion Applications, http://www.json.org
History

ColdFusion 8: Added function
Parameters

Parameter

Description

var

A string or variable that represents one.

Example

This example checks whether the data feed that is generated by the example for the SerializeJSON function
contains valid JSON data.The feed is in the form of a JavaScript function call where the parameter is a JSON string
that contains the feed data. The example does the following operations:
1.
2.
3.
4.

Uses a cfhttp tag to get the feed (in the cfhttp.fileContent variable).
Strips the function call wrapper from the text.
Uses the IsJSON function to check whether the result of the previous step is a valid JSON format string.
Displays a message that indicates whether the text is valid JSON data, followed by the feed text string.To run
this example, put this file and the example for the SerializeJSONfunction in an appropriate location under
your ColdFusion web root, replace the URL with the correct URL for the serialization example, and run this
page.

© 2014 Adobe Systems Incorporated. All rights reserved.

1939

Adobe ColdFusion Documentation








The URL you requested provides valid JSON

The URL you requested does not provide valid JSON


#theData#

For a more complex example that then converts the JSON data, see DeserializeJSON.

© 2014 Adobe Systems Incorporated. All rights reserved.

1940

Adobe ColdFusion Documentation

IsK2ServerABroker
Description

This function is deprecated.
Returns

True, if K2Broker is in configured with ColdFusion; False, otherwise.
Category

Decision functions, Full-text search functions, Query functions
Function syntax

IsK2ServerABroker()

See also

GetK2ServerDocCountLimit, IsK2ServerDocCountExceeded, IsK2ServerOnline
History

ColdFusion MX 6.1: Deprecated this function. It might not work, and it might cause an error, in later
releases.ColdFusion MX: Added this function.
Example

IsK2ServerABroker =
$*#IsK2ServerABroker()#*$

© 2014 Adobe Systems Incorporated. All rights reserved.

1941

Adobe ColdFusion Documentation

IsK2ServerDocCountExceeded
Description

This function is deprecated.
Returns

True, if the document count limit is exceeded; False, otherwise.
Category

Decision functions, Full-text search functions, Query functions
Function syntax

IsK2ServerDocCountExceeded()

See also

GetK2ServerDocCountLimit, IsK2ServerABroker
History

ColdFusion MX 6.1: Deprecated this function. It might not work, and it might cause an error, in later
releases.ColdFusion 5: Added this function.
Example

IsK2ServerDocCountExceeded =
$*#IsK2ServerDocCountExceeded()#*$

© 2014 Adobe Systems Incorporated. All rights reserved.

1942

Adobe ColdFusion Documentation

IsK2ServerOnline
Description

This function is deprecated because the K2Server is always running when ColdFusion is running.
Returns

True, if the K2Server is available to perform a search; False, otherwise.
Category

Decision functions, Full-text search functions, Query functions
Function syntax

IsK2ServerOnline()

See also

IsK2ServerABroker
History

ColdFusion MX 6.1: Deprecated this function. It might not work, and it might cause an error, in later releases.
ColdFusion MX: Added this function.
Example

IsK2ServerOnline =
$*#IsK2ServerOnline()#*$

© 2014 Adobe Systems Incorporated. All rights reserved.

1943

Adobe ColdFusion Documentation

IsLeapYear
Description

Determines whether a year is a leap year.
Returns

True, if year is a leap year; False, otherwise.
Category

Date and time functions, Decision functions
Function syntax

IsLeapYear(year)

See also

DaysInYear
Parameters

Parameter

Description

year

Number representing a year

Example

IsLeapYear Example


The year value #DE(FORM.theTestValue)# is a Leap
Year

The year value #DE(FORM.theTestValue)# is not a Leap
Year



Enter a year value, and find out whether it is a Leap Year.




© 2014 Adobe Systems Incorporated. All rights reserved.

1944

Adobe ColdFusion Documentation

IsLocalHost
Description

Determines whether the specified IP address is the localhost. This supports both IPv4 and IPv6 addresses.
Returns

True, if the IP address is the localhost; False, otherwise.
Category

Decision functions
Function syntax

IsLocalHost(ipaddress)

See also

GetLocalHostIP
History

ColdFusion MX 7.01: Added this function.
Parameters

Parameter

Description

ipaddress

Valid IP address.

Example

IsLocalHost Example


The IP address #FORM.theTestIPAddress)# is the
localhost

The IP address #DE(FORM.theTestIPAddress)# is not the
localhost.



Enter an IP address to find out if it is the localhost.



© 2014 Adobe Systems Incorporated. All rights reserved.

1945

Adobe ColdFusion Documentation

IsNull
Description

Used to check if the given object or expression evaluates to null.
Returns

True, if the given object is null or if the given expression evaluates to null; False, otherwise.
Category

Decision functions
Function syntax

IsNull(obj)

History

ColdFusion 9: Added this function
Parameters

Parameter

Description

obj

Object for which you perform the null check.

© 2014 Adobe Systems Incorporated. All rights reserved.

1946

Adobe ColdFusion Documentation

IsNumeric
Description

Determines whether a string can be converted to a numeric value. Supports numbers in U.S. number format. For
other number support, use LSIsNumeric.
Returns

True, if string can be converted to a number; False, otherwise.
Category

Decision functions
Function syntax

IsNumeric(string)

See also

IsBinary, IsValid
Parameters

Parameter

Description

string

A string or a variable that contains one.

Example

IsNumeric Example


The string #DE(FORM.theTestValue)# can be
converted to a number

The string #DE(FORM.theTestValue)# cannot be
converted to a number



Enter a string, and find out whether it can be evaluated to a numeric value.




© 2014 Adobe Systems Incorporated. All rights reserved.

1947

Adobe ColdFusion Documentation

IsNumericDate
Description

Evaluates whether a real number is a valid representation of a date (date/time object).
Returns

True, if the parameter represents a valid date/time object; False, otherwise.
Category

Date and time functions, Decision functions
Function syntax

IsNumericDate(number)

See also

IsDate, ParseDateTime
Parameters

Parameter

Description

number

A real number

Usage

ColdFusion, by default, evaluates any input parameter and attempts to convert it to a real number before it passes
the parameter to the IsNumericDate function. As a result, parameter values such as 12/12/03 and {ts '2003-01-14
10:04:13'} return True, because ColdFusion converts valid date string formats to date/time objects, which are real
numbers.
Example

© 2014 Adobe Systems Incorporated. All rights reserved.

1948

Adobe ColdFusion Documentation

IsNumericDate Example





The string #DE(form.theTestValue)# can be converted to a
valid numeric date

The string #DE(form.theTestValue)# can not be converted
to a valid numeric date


The string #DE(form.theTestValue)# is not a valid numeric
date



Enter a value, and discover if it can be evaluated to a date value.





© 2014 Adobe Systems Incorporated. All rights reserved.

1949

Adobe ColdFusion Documentation

IsObject
Description

Determines whether a value is an object.
Returns

True, if the value represents a ColdFusion object. False if the value is any other type of data, such as an integer,
string, date, or struct.
Category

Decision functions
Function syntax

IsObject(value)

See also

IsDate, IsImage, IsNumeric, IsNumericDate, IsQuery, IsSimpleValue, IsStruct, IsWDDX, IsXmlDoc,
IsXmlElem, IsXmlRoot
History

ColdFusion MX: Added this function.
Parameters

Parameter

Description

value

A value, typically the name of a variable.

Usage

This function returns False for query and XML objects.
Example

© 2014 Adobe Systems Incorporated. All rights reserved.

1950

Adobe ColdFusion Documentation







--->








The value of myColor = #myColor#




© 2014 Adobe Systems Incorporated. All rights reserved.

1951

Adobe ColdFusion Documentation

isOnline
Description

Determines whether the gateway is connected to the instant messaging server.
Syntax

Boolean = isOnline()

See also

getCustomAwayMessage, getStatusAsString, getStatusTimeStamp, setStatus, Using the
GatewayHelper object in the Developing ColdFusion Applications
Returns

True, if the gateway is connected to the IM server; False, otherwise.
Example

See GatewayHelper example, in the Developing ColdFusion Applications, which uses all GatewayHelper class
methods.---#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

1952

Adobe ColdFusion Documentation

IsPDFFile
Description

Verifies whether a PDF file is valid.
Returns

True, if the value returns a valid PDF file. False, otherwise.
Category

Decision functions
Function syntax

IsPDFFile("path")

See also

IsDate, IsImage, IsImageFile, IsNumeric, IsNumericDate, IsObject, IsPDFObject, IsQuery, IsSimp
leValue, IsStruct, IsWDDX, IsXmlDoc, IsXmlElem, IsXmlRoot, cfpdf, cfpdfform, cfprint
History

ColdFusion 8: Added this function.
Parameters

Parameter

Description

path

Pathname to an on-disk or in-memory PDF file. The
pathname can be absolute or relative to the CFM page
and must be enclosed in quotation marks.

Usage

This function returns False if the value is not a valid pathname to a PDF file, the pathname is null, the PDF file is not
valid, or the PDF file is corrupted.
Example





This is not a valid PDF file or the PDF document you have chosen is not
available.


© 2014 Adobe Systems Incorporated. All rights reserved.

1953

Adobe ColdFusion Documentation

IsPDFObject
Description

Determines whether a value is a PDF object.
Returns

True, if the value represents a PDF object. False if the value is any other type of data, such as an integer, string,
date, or structure.
Category

Decision functions
Function syntax

IsPDFObject(value)

See also

IsDate, IsImage, IsNumeric, IsNumericDate, IsObject, IsPDFFile, IsQuery, IsSimpleValue, IsStru
ct, IsWDDX, IsXmlDoc, IsXmlElem, IsXmlRoot, cfpdf, cfpdfform
History

ColdFusion 8: Added this function.
Parameters

Parameter

Description

value

A value, typically the PDF object stored as a variable
name.

Usage

This function returns False for query and XML objects.
Example





This is not a PDF.


© 2014 Adobe Systems Incorporated. All rights reserved.

1954

Adobe ColdFusion Documentation

IsProtected
Description

This function is obsolete. Use the newer security tools; see Conversion functions and Securing Applications in the D
eveloping ColdFusion Applications
History

ColdFusion MX: This function is obsolete. It does not work in ColdFusion MX and later releases.

© 2014 Adobe Systems Incorporated. All rights reserved.

1955

Adobe ColdFusion Documentation

IsQuery
Description

Determines whether value is a query.
Returns

True, if_ value_ is a query.
Category

Decision functions, Query functions
Function syntax

IsQuery(value)

See also

QueryAddRow
Parameters

Parameter

Description

value

Query variable

Example

© 2014 Adobe Systems Incorporated. All rights reserved.

1956

Adobe ColdFusion Documentation


IsQuery Example


Before the query is run, the value of GetEmployees is
#GetEmployees#

GetEmployees is currently a simple value



SELECT *
FROM employees

After the query is run, GetEmployees contains a number of rows
that look like this (display limited to three rows):

#Emp_ID# #FirstName# #LastName#


GetEmployees is no longer a simple value, but the name of a query


© 2014 Adobe Systems Incorporated. All rights reserved.

1957

Adobe ColdFusion Documentation

IsSimpleValue
Description

Determines the type of a value.
Returns

True, if value is a string, number, Boolean, or date/time value; False, otherwise.
Category

Decision functions
Function syntax

IsSimpleValue(value)

See also

IsValid
Parameters

Parameter

Description

value

Variable or expression

Example

© 2014 Adobe Systems Incorporated. All rights reserved.

1958

Adobe ColdFusion Documentation


IsSimpleValue Example


Before the query is run, the value of GetEmployees is
#GetEmployees#

GetEmployees is currently a simple value



SELECT *
FROM employees

After the query is run, GetEmployees contains a number of rows
that look like this (display limited to three rows):

#Emp_ID# #FirstName# #LastName#


GetEmployees is no longer a simple value, but the name of a query


© 2014 Adobe Systems Incorporated. All rights reserved.

1959

Adobe ColdFusion Documentation

IsSOAPRequest
Description

Determines whether a CFC is being called as a web service.
Returns

True if CFC is being called as a web service; False, otherwise.
Category

XML functions
History

ColdFusion MX 7: Added this function.
Function syntax

IsSOAPRequest()

See also

AddSOAPRequestHeader, AddSOAPResponseHeader, GetSOAPRequest, GetSOAPRequestHeader, GetSOAP
Response, GetSOAPResponseHeader; Basic web service concepts in Web services in the Developing ColdFusion
Applications
Usage

Call this function within a CFC to determine if it is running as a web service.
Example

This example creates a CFC web service that illustrates the operation of the IsSOAPRequest function and also
provides a web service that illustrates the operation of other ColdFusion SOAP functions. Save the following code
as headerservice.cfc in a folder called soapheaders under your web root. Test its operation, and specifically the
operation of the IsSOAPRequest function, by executing the examples that invoke this web service. For example,
see the example for AddSOAPRequestHeader.

© 2014 Adobe Systems Incorporated. All rights reserved.

1960

Adobe ColdFusion Documentation

IsSOAPRequest Example









 as XML: " & xmlusername>




 as XML: " & xmlpassword>
















© 2014 Adobe Systems Incorporated. All rights reserved.

1961

Adobe ColdFusion Documentation

IsSpreadsheetFile
Description

Returns a value that determines if the input is a spreadsheet file.
Returns

A Boolean value. True if the input is a spreadsheet file; False if it is a spreadsheet object.
Category

Microsoft Office Integration
Function syntax

IsSpreadsheetFile(spreadsheetfile)

See also
History

ColdFusion 9: Added.
Parameters

Parameter

Description

spreadsheefile

Specifies the spreadsheet file.

Example


# isSpreadSheetObject(filepath)# NOT an Object

# isSpreadSheetFile(filepath)# a File


© 2014 Adobe Systems Incorporated. All rights reserved.

1962

Adobe ColdFusion Documentation

IsSpreadsheetObject
Description

Returns a value that determines if the input is a spreadsheet object.
Returns

A Boolean value. True if the input is a spreadsheet object; False if it is a spreadsheet file.
Category

Microsoft Office Integration
Function syntax

IsSpreadsheetObject(spreadsheetobject)

See also

IsSpreadsheetFile
History

ColdFusion 9: Added.
Parameters

Parameter

Description

spreadsheetobject

Specifies the spreadsheet object.

Example


# isSpreadSheetObject(SpreadsheetObj)# an Object

# isSpreadSheetFile(SpreadsheetObj)# NOT a File


© 2014 Adobe Systems Incorporated. All rights reserved.

1963

Adobe ColdFusion Documentation

IsStruct
Description

Determines whether a variable is a structure.
Returns

True, if variable is a ColdFusion structure or is a Java object that implements the java.lang.Map interface. The return
value is False if the object in variable is a user-defined function (UDF).
Category

Decision functions, Structure functions
Function syntax

IsStruct(variable)

See also

Structure functions; Modifying a ColdFusion XML object in the Developing ColdFusion Applications
History

ColdFusion MX: Changed behavior: this function can be used on XML objects.
Parameters

Parameter

Description

variable

Variable name

Example

© 2014 Adobe Systems Incorporated. All rights reserved.

1964

Adobe ColdFusion Documentation


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


© 2014 Adobe Systems Incorporated. All rights reserved.

1965

Adobe ColdFusion Documentation

IsUserInAnyRole
Description

Determines whether an authenticated user belongs to any role in a list of roles.
Returns

True, if the authenticated user, belongs to any Role in the list; False, otherwise.
Category

Security functions, Decision functions
Function syntax

IsUserInAnyRole(role_list)

See also

cflogin, cfloginuser, cflogout, GetAuthUser, GetUserRoles, IsUserInRole, IsUserLoggedIn, Sec
uring Applications in the Developing ColdFusion Applications
History

ColdFusion 8: Added this function.
Parameters

Parameter

Description

role_list

A comma-delimited list of one or more roles to be
tested.

Example


Authenticated user is in these roles: #GetUserRoles()#

Authenticated user is in no roles


© 2014 Adobe Systems Incorporated. All rights reserved.

1966

Adobe ColdFusion Documentation

IsUserInRole
Description

Determines whether an authenticated user belongs to the specified Role.
Returns

True, if the authenticated user, belongs to the specified Role; False, otherwise.
Category

Security functions, Decision functions
Function syntax

IsUserInRole("role_name")

See also

cflogin, cfloginuser, GetAuthUser, GetUserRoles, IsUserInAnyRole, IsUserLoggedIn, Securing
Applications in the Developing ColdFusion Applications
History

ColdFusion MX: Added this function.
Parameters

Parameter

Description

role_name

Name of a security role

Usage

Role names are not case-sensitive.To check if a user is in multiple roles, specify them in a comma-delimited list,
such as "Admin,HR". Lists with multiple roles cannot contain spaces as separators; for example, do not use "Admin,
HR".
Example


Authenticated user is an administrator

Authenticated user is a user


© 2014 Adobe Systems Incorporated. All rights reserved.

1967

Adobe ColdFusion Documentation

IsUserLoggedIn
Description

Determines whether a user is logged in.
Returns

True, if the user, is logged in; False, otherwise.
Category

Security functions, Decision functions
Function syntax

IsUserLoggedIn()

See also

cflogin, cfloginuser, GetAuthUser, GetUserRoles, IsUserInAnyRole, IsUserInRole, Securing
Applications in the Developing ColdFusion Applications
History

ColdFusion 8: Added this function.
Example








© 2014 Adobe Systems Incorporated. All rights reserved.

1968

Adobe ColdFusion Documentation

IsValid
Description

Tests whether a value meets a validation or data type rule.
Returns

True, if the value conforms to the rule; False, otherwise.
Category

Decision functions
Function syntax

IsValid(type, value)
isValid("range", value, min, max)
isValid("regex" or "regular_expression", value, pattern)

See also

cfparam, cfform, IsBoolean, IsDate, IsNumeric, IsSimpleValue; Validating data with the
IsValid function and the cfparam tag in the Developing ColdFusion Applications
History

ColdFusion 11: Behavioral change
Prior to ColdFusion 11, this function allowed currency symbols at the start and commas inside the number. Starting
from ColdFusion 11, this function evaluates on a more strict basis. To revert to the old behavior use the
application-level setting STRICTNUMBERVALIDATION to false.
ColdFusion 8: Added the component value for to the type attribute.
ColdFusion MX 7: Added this function.
Parameters

Parameter

Description

type

The valid format for the data; one of the following. For
detailed information on validation algorithms, see Valid
ating form data using hidden fields in the Developing
ColdFusion Applications.

© 2014 Adobe Systems Incorporated. All rights reserved.

1969

Adobe ColdFusion Documentation

any: any simple value. Returns false for complex
values, such as query objects;; equivalent to the IsS
impleValue function.
array: an ColdFusion array; equivalent to the IsArra
y function.
binary: a binary value;; equivalent to the IsBinary f
unction.
boolean: a Boolean value: yes, no, true, false, or a
number; equivalent to the IsBoolean function.
component: a ColdFusion component (CFC).
creditcard: a 13-16 digit number conforming to the
mod10 algorithm.
date or time: any date-time value, including dates or
times; equivalent to the IsNumericDateIsDate fu
nction.
email: a valid email address.
eurodate: any date-time value, including US date
formats and time values,
numeric: a numeric value; equivalent to the IsNumer
ic function.
guid: a Universally Unique Identifier of the form "XXX
XXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX" where
X is a hexadecimal number.
integer: an integer.
query: a query object; equivalent to the IsQuery fun
ction.
range: a numeric range, specified by the min and ma
x attributes.
regex or regular_expression: matches input against p
attern attribute.
ssn or social_security_number: A U.S. social security
number.
string: a string value, including single characters and
numbers
struct: a structure; equivalent to the IsStruct functi
on.
telephone: a standard US telephone number.
URL: an http, https, ftp, file, mailto, or news URL,
UUID: a ColdFusion Universally Unique Identifier,
formatted XXXXXXXX-XXXX-XXXX-XXXXXXXXXXXX
XXX, where X is a hexadecimal number. See Create
UUID.
USdate: a U.S. date of the format mm/dd/yy, with 1-2
digit days and months, 1-4 digit years.
variableName: a string formatted according to
ColdFusion variable naming conventions.
zipcode: U.S., 5- or 9-digit format ZIP codes.
value

© 2014 Adobe Systems Incorporated. All rights reserved.

The value to test

1970

Adobe ColdFusion Documentation

min

The minimum valid value; used only for range validatio
n

max

The maximum valid value; used only for range validati
on

pattern

A JavaScript regular expression that the parameter
must match; used only for regex or regular_expres
sion validation.

Usage

The IsValid function lets you assure that validation is performed on the server. You can use the cfparam tag to
perform equivalent validation.
Example

The following example checks whether a user has submitted a numeric ID and a valid e-mail address and phone
number. If any of the submitted values does not meet the validation test, it displays an error message.





The email address and phone number for user #Form.UserID#
have been added


You must supply a valid User ID, phone number, and email address.




User ID:

Phone: 

email: 





In ColdFusion 11, the isValid function behaves in a different way. Setting strictnumbervalidation to false makes the
isValid function to behave in a way just like in the previous versions (ColdFusion 10 or earlier). Starting from
ColdFusion 11, a more strict approach will be followed for validation. However, if you need the isValid function
behavior to be of ColdFusion 10, set the key/tag attribute strictnumbervalidation to false in application cfc/cfm.
Application.cfm



© 2014 Adobe Systems Incorporated. All rights reserved.

1971

Adobe ColdFusion Documentation
Application.cfc



{
this.STRICTNUMBERVALIDATION = false;
}



© 2014 Adobe Systems Incorporated. All rights reserved.

1972

Adobe ColdFusion Documentation

IsWDDX
Description

Determines whether a value is a well-formed WDDX packet.
Returns

True, if the value is a well-formed WDDX packet; False, otherwise.
Category

Decision functions, XML functions
Syntax

IsWDDX(value)

See also

Using WDDX in the Developing ColdFusion Applications
History

ColdFusion MX: Changed behavior: if the value parameter is not a WDDX packet, ColdFusion returns False. (In
earlier releases, ColdFusion threw an error.)
Parameters

Parameter

Description

value

A WDDX packet

Usage

This function processes a WDDX packet with a validating XML parser, which uses the WDDX Document Type
Definition (DTD). To prevent CFWDDX deserialization errors, you can use this function to validate WDDX packets
from unknown sources.
Example

© 2014 Adobe Systems Incorporated. All rights reserved.

1973

Adobe ColdFusion Documentation




<cfoutput>#packet#

IsWDDX() returns #IsWDDX(packet)#



© 2014 Adobe Systems Incorporated. All rights reserved.

1974

Adobe ColdFusion Documentation

IsXML
Description

Determines whether a string is well-formed XML text.
Returns

True, if the function parameter is a string that contains well-formed XML text; False, otherwise.
Category

Decision functions, XML functions
Function syntax

IsXML(value)

See also

IsXmlAttribute, IsXmlDoc, IsXmlElem, IsXmlNode, IsXmlRoot, XmlParse, XmlValidate; Using XML
and WDDX in the Developing ColdFusion Applications
History

ColdFusion MX 7: Added this function.
Parameters

Parameter

Description

value

A string containing the XML document text

Usage

This function determines whether text is well-formed XML, that is, it conforms to all XML syntax and structuring
rules. The string does not have to be a complete XML document. The function does not validate against a Document
Type Definition (DTD) or XML Schema.
Example

The following example creates two strings, and tests whether they are well-formed XML text:

© 2014 Adobe Systems Incorporated. All rights reserved.

1975

Adobe ColdFusion Documentation







xmlString1 contains the following text:


#HTMLCodeFormat(xmlstring1)#
Is it well formed XML text? #IsXML(xmlString1)#



xmlString2 contains the following text:


#HTMLCodeFormat(xmlstring2)#
Is it well formed XML text? #IsXML(xmlString2)#


© 2014 Adobe Systems Incorporated. All rights reserved.

1976

Adobe ColdFusion Documentation

IsXmlAttribute
Description

Determines whether the function parameter is an XML Document Object Model (DOM) attribute node.
Returns

True, if the function argument is an XML attribute node; False, otherwise.
Category

Decision functions, XML functions
Function syntax

IsXmlAttribute(value)

See also

IsXML, IsXmlDoc, IsXmlElem, IsXmlNode, IsXmlRoot, XmlGetNodeType, XmlValidate, Using XML and
WDDX in the Developing ColdFusion Applications
History

ColdFusion MX 7: Added this function.
Parameters

Parameter

Description

value

Name of an XML attribute

Usage

This function determines whether the parameter is an XML DOM attribute node, a node with an XMLType value of A
TTRIBUTE. It is useful for determining whether a value returned by the XmlSearch function is an XML attribute.
The DOM, and therefore ColdFusion, treats XML attributes as properties of an element and does not directly expose
them as DOM nodes. For this reason, the XmlAttributes entries in ColdFusion XML document objects do not
represent DOM attribute nodes, and tests such as the following always return False:

IsXmlAttribute(myxmlelement.XMlAttributes);
IsXmlAttribute(myxmlelement.XMlAttributes.myattribute);

The XmlSearch function does return attributes as XML DOM attribute nodes. For example, the following line
returns an array of attribute nodes containing the quantity attributes in the xmlobject document object:

quantities = XmlSearch(xmlobject, '//@quantity');

© 2014 Adobe Systems Incorporated. All rights reserved.

1977

Adobe ColdFusion Documentation

Example

The following example creates an XML document object and gets parts of it. It then tests whether these parts are
attribute nodes.







1
15.95








Are the following XML Attribute nodes?

node.xmlobject.order.XmlAttributes.id:
#IsXmlAttribute(xmlobject.order.XmlAttributes.id)#


xmlobject.order.items: #IsXmlAttribute(xmlobject.order.items)#

lastnames[1] returned by XmlSearch:
#isXmlAttribute(lastnames[1])#



© 2014 Adobe Systems Incorporated. All rights reserved.

1978

Adobe ColdFusion Documentation

IsXmlDoc
Description

Determines whether the function parameter is a ColdFusion XML document object.
Returns

True, if the function argument is an XML document object; False, otherwise.
Category

Decision functions, XML functions
Function syntax

IsXmlDoc(value)

See also

IsXML, IsXmlAttribute, IsXmlElem, IsXmlNode, IsXmlRoot, XmlValidate; Using XML and WDDX in the
Developing ColdFusion Applications
History

ColdFusion MX: Added this function.
Parameters

Parameter

Description

value

Name of an XML document object

Example

The following example creates an XML Document object and a Java object and tests whether they are XML
document objects:

© 2014 Adobe Systems Incorporated. All rights reserved.

1979

Adobe ColdFusion Documentation







1
15.95








Is xmlobject an XML document object? #IsXmlDoc(xmlobject)#

Is javaobject an XML document object? #IsXmlDoc(javaobject)#



© 2014 Adobe Systems Incorporated. All rights reserved.

1980

Adobe ColdFusion Documentation

IsXmlElem
Description

Determines whether the function parameter is an XML document object element.
Returns

True, if the function argument is an XML document object element; False, otherwise.
Category

Decision functions, XML functions
Function syntax

IsXmlElem(value)

See also

IsXML, IsXmlAttribute, IsXmlDoc, IsXmlNode, IsXmlRoot, XmlGetNodeType, XmlValidate; Using XML
and WDDX in the Developing ColdFusion Applications
History

ColdFusion MX: Added this function.
Parameters

Parameter

Description

value

Name of an XML document object element

Example

The following example tests whether an XML document object, the document root, and an element are elements:

© 2014 Adobe Systems Incorporated. All rights reserved.

1981

Adobe ColdFusion Documentation







1
15.95






Are the following XML document object elements?
xmlobject: #IsXmlElem(xmlobject)#

xmlobject.XMLRoot: #IsXmlElem(xmlobject.XMLRoot)#

xmlobject.order.items: #IsXmlElem(xmlobject.order.items)#



© 2014 Adobe Systems Incorporated. All rights reserved.

1982

Adobe ColdFusion Documentation

IsXmlNode
Description

Determines whether the function parameter is an XML document object node.
Returns

True, if the function argument is an XML document object node, including an element; False, otherwise.
Category

Decision functions, XML functions
Function syntax

IsXmlNode(value)

See also

IsXML, IsXmlAttribute, IsXmlDoc, IsXmlElem, IsXmlRoot, XmlGetNodeType, XmlSearch, XmlValidate
; Using XML and WDDX in the Developing ColdFusion Applications
History

ColdFusion MX 7: Added this function.
Parameters

Parameter

Description

value

Name of an XML document object node.

Usage

This function returns True for the following components of an XML document object:
The document object
Elements in the object
XmlNode objects in an element's XmlNodes arrayIt also returns True for XML node objects returned by the X
mlSearch function. It does not return True for most entries in an element, including XmlText, XmlComment,
XmlCdata, or the XmlAttributes array (or individual XML attributes).
Example

The following example tests whether an XML document object, an element, an attribute in the object, and an
attribute returned by an XmlSearch function are nodes:

© 2014 Adobe Systems Incorporated. All rights reserved.

1983

Adobe ColdFusion Documentation








1
15.95








Are the following XML nodes?
xmlobject: #IsXmlNode(xmlobject)#


xmlobject.order.items: #IsXmlNode(xmlobject.order.items)#


xmlobject.order.XmlAttributes.id:
#IsXmlNode(xmlobject.order.XmlAttributes.id)#

lastnames[1] returned by XmlSearch:
#isXmlNode(lastnames[1])#


© 2014 Adobe Systems Incorporated. All rights reserved.

1984

Adobe ColdFusion Documentation

IsXmlRoot
Description

Determines whether the function parameter is the root element of an XML document object.
Returns

True, if the function argument is the root object of an XML document object; False, otherwise.
Category

Decision functions, XML functions
Function syntax

IsXmlRoot(value)

See also

IsXML, IsXmlAttribute, IsXmlDoc, IsXmlElem, IsXmlNode, XmlGetNodeType, XmlValidate; Using XML
and WDDX in the Developing ColdFusion Applications
History

ColdFusion MX: Added this function.
Parameters

Parameter

Description

value

Name of an XML document object

Example

The following example tests whether an XML document object, its root element, and a child element are XML root
elements:

© 2014 Adobe Systems Incorporated. All rights reserved.

1985

Adobe ColdFusion Documentation








1
15.95






Are the following the XML Root?
xmlobject: #IsXmlRoot(xmlobject)#

xmlobject.order: #IsXmlRoot(xmlobject.order)#


xmlobject.order.XmlAttributes.id:
#IsXmlRoot(xmlobject.order.XmlAttributes.id)#



© 2014 Adobe Systems Incorporated. All rights reserved.

1986

Adobe ColdFusion Documentation

JavaCast
Description

Converts the data type of a ColdFusion variable to a specified Java type to pass as an argument to Java or .NET
object. Use only for scalar, string, and array arguments.
Returns

The variable, as type type.
Category

String functions
Function syntax

JavaCast(type, variable)

History

ColdFusion MX 8: Added support for bigdecimal, byte, char, and short data types and for casting Arrays.ColdFusion
MX 7: Added support for nulls.
See also

CreateObject, cfobject, Converting between .NET and ColdFusion data types in Using .NET classes and Java
and ColdFusion data type conversions in Using Java objects in the Developing ColdFusion Applications
Parameters

Parameter

Description

type

Data type to which to convert variable:
bigdecimal (converts to java.math.BigDecimal)
boolean
byte
char
int
long
float
double
short
string
null
xxx where xxxis one of the following:
any of the preceding types, except for null
a Java class name

variable

© 2014 Adobe Systems Incorporated. All rights reserved.

A ColdFusion variable that holds a scalar or string type.
Must be "" if type is null.

1987

Adobe ColdFusion Documentation
Usage

Use this method to specify the Java type to use for a variable that you use when calling a Java or .NET method
when the conversion between types is ambiguous; for example, if a method is overloaded and differs only in
parameter type or a .NET method is declared as taking a System.Object class parameter.Use after creating a Java
object with the cfobject tag, before calling one of its methods. If the method takes more than one overloaded
argument, call JavaCast for each one. Use JavaCast only when a method is overloaded (because its arguments
can take more than one data type, not because the method can take a variable number of arguments). JavaCast c
annot be used to cast between complex objects, nor to cast to a super-class. Because there is not a one-to-one
correspondence between internally stored ColdFusion types and Java scalar types, some conversions cannot be
performed. Use the result of this function only on calls to Java or .NET objects. The following example shows the
use when calling a Java method.


x = CreateObject("java", "test.Hello");
x.init();
ret = x.sayHello(JavaCast("null", ""));


Note
Do not assign the results of JavaCast("null","") to a ColdFusion variable. Unexpected
results will occur.

The format JavaCast(type[], variable) casts a ColdFusion Array variable to a single dimensional Array of the
specified type. It cannot convert multi-dimensional arrays. You can specify a primitive type or the name of a Class as
the type to cast to. For example, you can use the following format to cast a ColdFusion Array to an Array of
vom.x.yMyClass objects.

javacast("vom.x.y.MyClass[]", myCFArr)

Use an array in the first JavaCast parameter in any of the following circumstances:
You have two functions with signatures with the same number of parameters, and a parameter takes different
types of Arrays in different signatures; for example, if you have both of the following functions: foo(int[]
x) and foo(String[] strs).
The method parameter requires a class array in its signature; for example, foo(com.x.y.MyClass[]).
The method parameter requires an Object in its signature and you must pass an array of any particular
type.The following example shows the use of the JavaCastfunction to cast arrays:You might have a
fooClass class that defines the following two methods, each with two arguments where the first argument
differs in the type of the array:

© 2014 Adobe Systems Incorporated. All rights reserved.

1988

Adobe ColdFusion Documentation

public class fooClass {
public fooClass () {
}
public String foo(long[] arg) {
return "Argument was a long array";
}
public String foo(int[] arg) {
return "Argument was an Integer array";
}
}

To be able to use these functions in your CFML, use the JavaCastfunction to convert the ColdFusion Arrray
to the array type required by one of the functions, as shown in the following code snippet:






Example

The method fooMethod in the class fooClass takes one overloaded argument. The fooClass class is defined as
follows:

public class fooClass {
public fooClass () {
}
public String fooMethod(String arg) {
return "Argument was a String";
}
public String fooMethod(int arg) {
return "Argument was an Integer";
}

}Within ColdFusion, you use the following code:

© 2014 Adobe Systems Incorporated. All rights reserved.

1989

Adobe ColdFusion Documentation




Perform an explicit cast to an int and call fooMethod:


#obj.fooMethod(myInt)#



Perform an explicit cast to a string and call fooMethod:


#obj.fooMethod(myString)#

© 2014 Adobe Systems Incorporated. All rights reserved.

1990

Adobe ColdFusion Documentation

JSStringFormat
Description

Escapes special JavaScript characters, such as single-quotation mark, double-quotation mark, and newline.
Returns

A string that is safe to use with JavaScript.
Category

String functions
Function syntax

JSStringFormat(string)

Parameters

Parameter

Description

string

A string or a variable that contains one.

Usage

Escapes special JavaScript characters, so you can put arbitrary strings safely into JavaScript.
Example


JSStringFormat

This is the string we have created:

#stringValue#





#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

1991

Adobe ColdFusion Documentation

isSafeHTML
This function validates for allowed HTML according to the rules specified in the antisamy policy file. This can be
used to prevent unwanted user supplied HTML being used in an application.
Returns

Returns false if the input is violating the allowed HTML rules.
Parameter

Parameter

Description

inputString

Required. The string to be encoded.

PolicyFile

Optional. File path for antisamy policy file which
specifies HTML rules. In case if not specified, there is a
provision to set this at application level. Else the default
policy file shipped with ColdFusion will be used.

throwOnError

Optional. If set to true, exception is thrown.

Example

This example illustrates a sample Antisamy component.





The following example illustrates a isSafeHTML and getSafeHTML validation.
In the following example, the input HTML file is a GIF image ( http://www.techsite.com/img.gif). On processing it
through the functions (isSafeHTML, getSafeHTML) checks if the given input string violates the rules specified in the
Antisamy policy file and returns true if the input does not violate the allowed HTML rules.





is Safe
: #
isSafe#
Safe HTML : #
SafeHTML#


© 2014 Adobe Systems Incorporated. All rights reserved.

1992

Adobe ColdFusion Documentation

© 2014 Adobe Systems Incorporated. All rights reserved.

1993

Adobe ColdFusion Documentation

InvalidateOauthAccesstoken
Description

Invalidates the access token generated by the OAUTH servers.
Returns

None
Function syntax

InvalidateOauthAccesstoken(token,type)

History
ColdFusion 11: Added this function
Parameters

Parameter

Description

token

Required. The access token to invalidate.

type

Required. The type of the OAUTH server
(facebook/google).

Usage
Example

InvalidateOauthAccesstoken(“any_token_value”,”facebook”)

© 2014 Adobe Systems Incorporated. All rights reserved.

1994

Adobe ColdFusion Documentation

IsValidOauthAccesstoken
Description

Checks if the OAUTH access token is still valid.
Returns

Boolean
Function syntax

IsValidOauthAccesstoken(token,type)

History

ColdFusion 11: Added this function
Parameters

Parameter

Description

token

Required. The access token to check.

type

Required. The type of the OAUTH server
(facebook/google).

Usage
Example

IsValidOauthAccesstoken(“any_token_value”,”facebook”)

© 2014 Adobe Systems Incorporated. All rights reserved.

1995

Adobe ColdFusion Documentation

InvokeCFClientFunction
Description

ColdFusion automatically determines whether a function call is synchronous or asynchronous. However, if you need
to invoke an asynchronous function in a synchronous mode, you can use the invokeInSyncMode function. The
function call just needs to be wrapped around with the invokeInSyncMode function call. For instance,
invokeInSyncMode (myAsyncFunc(arg1,arg2)).
The invokeCFClientFunction function can be used to invoke both synchronous and asynchronous CFML functions
from JavaScript.
History

ColdFusion 11: Added this function
Syntax

invokeCFClientFunction(funcName, arg1, arg2, …., successCallback)

Properties

Parameter

Description

funcname

Required. The function to be invoked.

arguments

Optional. Arguments to pass to the function.

succesCallback

The callback handler when the function gets invoked
successfully. The successCallback argument is
mandatory. If there is no successCallback, use null.

Example

The following code depicts a simple usage of file creation on the device. Since file creation is an asynchronous
operation, we are using the invokeCFClientFunction to invoke this function.

© 2014 Adobe Systems Incorporated. All rights reserved.

1996

Adobe ColdFusion Documentation








File name : 
Create a file

 Result :




For more information on using this function, see this community blog post.

© 2014 Adobe Systems Incorporated. All rights reserved.

1997

Adobe ColdFusion Documentation

Functions l
LCase
Left
Len
ListAppend
ListChangeDelims
ListContains
ListContainsNoCase
ListDeleteAt
ListFilter
ListFind
ListFindNoCase
ListFirst
ListGetAt
ListInsertAt
ListLast
ListLen
ListPrepend
ListQualify
ListRemoveDuplicates
ListRest
ListSetAt
ListSort
ListToArray
ListValueCount
ListValueCountNoCase
LJustify
Location
Log
Log10
LSCurrencyFormat
LSDateFormat
LSDateTimeFormat
LSEuroCurrencyFormat
LSIsCurrency
LSIsDate
LSIsNumeric
LSNumberFormat
LSParseCurrency
LSParseDateTime
LSParseEuroCurrency
LSParseNumber
LSTimeFormat
LTrim
ListEach
ListReduce
ListMap

© 2014 Adobe Systems Incorporated. All rights reserved.

1998

Adobe ColdFusion Documentation

LCase
Description

Converts the alphabetic characters in a string to lowercase.
Returns

A string, converted to lowercase.
Category

String functions
Function syntax

LCase(string)

See also

UCase
Parameters

Parameter

Description

string

A string or a variable that contains one

Example

LCase Example



Your text, #FORM.sampleText#, returned in lowercase is
#LCase(FORM.sampleText)#.
< /cfoutput>

< p>Please enter some text.



Enter your text. Press "submit" to see it returned in lowercase: 





© 2014 Adobe Systems Incorporated. All rights reserved.

1999

Adobe ColdFusion Documentation

Left
Description

Returns up to the leftmost count characters in a string.
Returns

String; up to the first count characters in the string parameter.
Category

String functions
Function syntax

Left(string, count)

See also

Right, Mid, Len
Parameters

Parameter

Description

string

A string or a variable that contains one.

count

A positive integer or a variable that contains one.
Maximum number of characters to return.

Example

© 2014 Adobe Systems Incorporated. All rights reserved.

2000

Adobe ColdFusion Documentation

Left Example




Your string #Form.myText# only
has #Len(Form.myText)# characters. You cannot output
the #Form.removeChars# leftmost characters of this string because it is
not long enough.

Your original string: #Form.myText#
Your changed string, showing only the #Form.removeChars#
 leftmost characters:
#Left(Form.myText, Form.removeChars)#



Please enter a string of more than 0
(zero) characters.



Type in some text


How many characters from the left do you want to show?

1
3
5
7
9



© 2014 Adobe Systems Incorporated. All rights reserved.

2001

Adobe ColdFusion Documentation

Len
Description

Determines the length of a string or binary object.
Returns

Number; length of a string or a binary object.
Category

String functions
Function syntax

Len(string or binary object)

See also

ToBinary, Left, Right, Mid
History

ColdFusion MX: Changed Unicode support: ColdFusion supports the Java UCS-2 representation of Unicode
character values 0-65535. (ColdFusion 5 and earlier releases supported ASCII values 1-255. When calculating a
length, some string-processing functions processed the ASCII 0 (NUL) character, but did not process subsequent
characters of the string.)
Parameters

Parameter

Description

string

A string, the name of a string, or a binary object

Example

© 2014 Adobe Systems Incorporated. All rights reserved.

2002

Adobe ColdFusion Documentation

Len Example



Your string, "#FORM.myText#",
has #Len(FORM.myText)# characters.

Please enter a string of more
than 0 characters.



Type in some text to see the length of your string.






© 2014 Adobe Systems Incorporated. All rights reserved.

2003

Adobe ColdFusion Documentation

ListAppend
Description

Concatenates a list or element to a list.
Returns

A copy of the list_,_ with value appended. If value = "", returns a copy of the list, unchanged.
Category

List functions
Function syntax

ListAppend(list, value [, delimiters ])

See also

ListPrepend, ListInsertAt, ListGetAt, ListLast, ListSetAt; Lists in the Developing ColdFusion
Applications
Parameters

Parameter

Description

list

A list or a variable that contains one.

value

An element or a list of elements.

delimiters

A string or a variable that contains one. Characters that
separate list elements. The default value is comma. If
this parameter contains more than one character,
ColdFusion uses only the first character.

Usage

ColdFusion inserts a delimiter character before value. The following table shows examples of ListAppend processi
ng:
Statement

Output

Comment

ListAppend('elem1,elem2',
'' )

elem1,elem2,

Appended element is empty;
delimiter is last character in list; list
length is 2.

ListAppend('',
'elem1,elem2' )

elem1,elem2

List length is 2.

© 2014 Adobe Systems Incorporated. All rights reserved.

2004

Adobe ColdFusion Documentation

ListAppend("one__two",
"three", "__")

"one___two_three"

Inserted the first character of delim
iters before "three."

Example

ListAppend Example


SELECT PARKNAME,CITY,STATE
FROM PARKS WHERE PARKNAME LIKE 'AL%'



The original list: #temp#




© 2014 Adobe Systems Incorporated. All rights reserved.

2005

Adobe ColdFusion Documentation

ListChangeDelims
Description

Changes a list delimiter.
Returns

A copy of the list, with each delimiter character replaced by new_delimiter.
Category

List functions
Function syntax

ListChangeDelims(list, new_delimiter [, delimiters, includeEmptyValues ])

See also

ListFirst, ListQualify; Lists in the Developing ColdFusion Applications
Parameters

Parameter

Description

includeEmptyValues

Optional. Set to yes to include empty values.

list

A list or a variable that contains one.

new_delimiter

Delimiter string or a variable that contains one. Can be
an empty string. ColdFusion processes the string as
one delimiter.

delimiters

A string or a variable that contains one. Characters that
separate list elements. The default value is comma. If
this parameter contains more than one character,
ColdFusion processes each occurrence of each
character as a delimiter.

Example

© 2014 Adobe Systems Incorporated. All rights reserved.

2006

Adobe ColdFusion Documentation

ListChangeDelims Example
ListChangeDelims lets you change the delimiters of a list.


SELECT PARKNAME,CITY,STATE
FROM Parks
WHERE PARKNAME LIKE 'BA%'



The original list: 
#temp#




After executing the statement
ListChangeDelims(Temp, "|:P|", ","),
the updated list: 
#temp2#


© 2014 Adobe Systems Incorporated. All rights reserved.

2007

Adobe ColdFusion Documentation

ListContains
Description

Determines the index of the first list element that contains a specified substring.
Returns

Index of the first list element that contains substring. If not found, returns zero.
Category

List functions
Function syntax

ListContains(list, substring [, delimiters, includeEmptyValues ])

See also

ListContainsNoCase, ListFind; Lists in Data types- Developing guide in the Developing ColdFusion
Applications
Parameters

Parameter

Description

includeEmptyValues

Optional. Set to yes to include empty values.

list

A list or a variable that contains one.

substring

A string or a variable that contains one. The search is
case sensitive.

delimiters

A string or a variable that contains one. Characters that
separate list elements. The default value is comma. If
this parameter contains more than one character,
ColdFusion processes each occurrence of each
character as a delimiter.

Usage

ColdFusion ignores empty list elements; thus, the list "a,b,c,,,d" has four elements.
Example

© 2014 Adobe Systems Incorporated. All rights reserved.

2008

Adobe ColdFusion Documentation






Here is a list: #aList#
ListContains checks for substring "wo" in the list elements:

   Substring "wo" is in
element #ListContains(aList, "wo")# of list.

ListFind cannot check for a substring within an element; therefore, in the
code, it does not find substring "wo" (it returns 0):

   Substring "wo" is in element #ListFind(aList, "wo")#
 of the list.
If you specify a string that exactly equals an entire list element, such
as "two", both ListContains and ListFind find it, in the second element:
   ListContains:

The string "two" is in element #ListContains(aList, "two")# of the list.

   
ListFind:

The string "two" is in element #ListFind(aList, "two")# of the list.


© 2014 Adobe Systems Incorporated. All rights reserved.

2009

Adobe ColdFusion Documentation

ListContainsNoCase
Description

Determines the index of the first list element that contains a specified substring.
Returns

Index of the first list element that contains substring, regardless of case. If not found, returns zero.
Category

List functions
Function syntax

ListContainsNoCase(list, substring [, delimiters, includeEmptyValues ])

See also

ListContains, ListFindNoCase; Lists in Data types- Developing guide in the Developing ColdFusion
Applications
Parameters

Parameter

Description

includeEmptyValues

Optional. Set to yes to include empty values.

list

A list or a variable that contains one.

substring

A string or a variable that contains one. The search is
case-insensitive.

delimiters

A string or a variable that contains one. Characters that
separate list elements. The default value is comma. If
this parameter contains more than one character,
ColdFusion processes each occurrence of each
character as a delimiter.

Usage

ColdFusion ignores empty list elements; thus, the list "a,b,c,,,d" has four elements.
Example

© 2014 Adobe Systems Incorporated. All rights reserved.

2010

Adobe ColdFusion Documentation

ListContainsNoCase Example



SELECT PARKNAME,CITY,STATE
FROM Parks
WHERE PARKNAME LIKE '#form.letter#%'



There are parks in your city!

Sorry, there were no parks found for your city.
Try searching under a different letter.



© 2014 Adobe Systems Incorporated. All rights reserved.

2011

Adobe ColdFusion Documentation

ListDeleteAt
Description

Deletes an element from a list.
Returns

A copy of the list, without the specified element.
Category

List functions
Function syntax

ListDeleteAt(list, position [, delimiters ])
ListDeleteAt(list, position [, delimiters, includeEmptyValues ])

See also

ListGetAt, ListSetAt, ListLen; Lists in Data types- Developing guide in the Developing ColdFusion
Applications
Parameters

Parameter

Description

list

A list or a variable that contains one.

position

A positive integer or a variable that contains one.
Position at which to delete element. The first list
position is 1.

delimiters

A string or a variable that contains one. Characters that
separate list elements. The default value is comma. If
this parameter contains more than one character,
ColdFusion processes each occurrence of each
character as a delimiter.

includeEmptyValues

If includeEmptyValues is set to false, the list will
contain only nonempty elements and the element
would be deleted at the specified position.

Usage

To use this and other functions with the default delimiter (comma), you can code as follows:



© 2014 Adobe Systems Incorporated. All rights reserved.

2012

Adobe ColdFusion Documentation

To specify another delimiter, you code as follows:



ColdFusion ignores empty list elements; thus, the list "a,b,c,,,d" has four elements.
Example



SELECT PARKNAME,CITY,STATE
FROM Parks
WHERE PARKNAME LIKE 'CHI%'



The original list: #temp#



The changed list: #temp2#
This list element:
#deleted_element#
 is no longer present
at position three of the list. 

writeOutput(listDeleteAt("1,,3", 2, ",", true));//outputs 1,3

© 2014 Adobe Systems Incorporated. All rights reserved.

2013

Adobe ColdFusion Documentation

ListFilter
Description

Used to filter the elements in list.
Returns

A new list
Category

Closure functions
Syntax

listFilter(list,function(listElement){return true|false;});
See also

Other closure functions.
History

ColdFusion 10: Added this function.
Parameters

Parameter

Description

list

Name of the list object.

function

Inline function executed for each element in the list.
Returns true if the list element has to be included in
the resultant list.

listElement

LIst element being accessed.

© 2014 Adobe Systems Incorporated. All rights reserved.

2014

Adobe ColdFusion Documentation

ListFind
Description

Determines the index of the first list element in which a specified value occurs. Case sensitive.
Returns

Index of the first list element that contains value, with matching case. If not found, returns zero. The search is case
sensitive.
Category

List functions
Function syntax

ListFind(list, value [, delimiters, includeEmptyValues ])

See also

ListContains, ListFindNoCase; Lists in Data types- Developing guide in the Developing ColdFusion
Applications
Parameters

Parameter

Description

includeEmptyValues

Optional. Set to yes to include empty values.

list

A list or a variable that contains one

value

A string, a number, or a variable that contains one. Item
for which to search. The search is case sensitive.

delimiters

A string or a variable that contains one. Characters that
separate list elements. The default value is comma. If
this parameter contains more than one character,
ColdFusion processes each occurrence of each
character as a delimiter.

Usage

ColdFusion ignores empty list elements; thus, the list "a,b,c,,,d" has four elements.
Example

© 2014 Adobe Systems Incorporated. All rights reserved.

2015

Adobe ColdFusion Documentation



Try changing the case in Leary's last name:


Pick a search type:

Case-Sensitive
Case-Insensitive






SELECT FirstName, RTrim(LastName) AS LName, Phone, Department
FROM Employees






An employee with that exact last name was not found


Employee #ListGetAt(ValueList(SearchEmpLastName.FirstName), temp)#
#ListGetAt(ValueList(SearchEmpLastName.LName), temp)#, of the
#ListGetAt(ValueList(SearchEmpLastName.Department), temp)# Department,
can be reached at #ListGetAt(ValueList(SearchEmpLastName.Phone),
temp)#.
This was the first employee found under this case-sensitive last name
search.





An employee with that exact last name was not found


Employee #ListGetAt(ValueList(SearchEmpLastName.FirstName), temp)#
#ListGetAt(ValueList(SearchEmpLastName.LName), temp)#, of the
#ListGetAt(ValueList(SearchEmpLastName.Department), temp)#
Department, can be reached at
#ListGetAt(ValueList(SearchEmpLastName.Phone), temp)#.
This was the first employee found under this case-insensitive last
name search.





© 2014 Adobe Systems Incorporated. All rights reserved.

2016

Adobe ColdFusion Documentation

ListFindNoCase
Description

Determines the index of the first list element in which a specified value occurs.
Returns

Index of the first list element that contains value. If not found, returns zero. The search is case-insensitive.
Category

List functions
Function syntax

ListFindNoCase(list, value [, delimiters, includeEmptyValues ])

See also

ListContains, ListFind; Lists in Data types- Developing guide in the Developing ColdFusion Applications
Parameters

Parameter

Description

includeEmptyValues

Optional. Set to yes to include empty values.

list

A list or a variable that contains one.

value

Number or string for which to search. The search is
case-insensitive.

delimiters

A string or a variable that contains one. Characters that
separate list elements. The default value is comma. If
this parameter contains more than one character,
ColdFusion processes each occurrence of each
character as a delimiter.

Usage

ColdFusion ignores empty list elements; thus, the list "a,b,c,,,d" has four elements.
Example

© 2014 Adobe Systems Incorporated. All rights reserved.

2017

Adobe ColdFusion Documentation



Try changing the case in Leary's last name:


Pick a search type:

Case-Sensitive
Case-Insensitive






SELECT FirstName, RTrim(LastName) AS LName, Phone, Department
FROM Employees






An employee with that exact last name was not found


Employee #ListGetAt(ValueList(SearchEmpLastName.FirstName), temp)#
#ListGetAt(ValueList(SearchEmpLastName.LName), temp)#, of the
#ListGetAt(ValueList(SearchEmpLastName.Department), temp)# Department,
can be reached at #ListGetAt(ValueList(SearchEmpLastName.Phone),
temp)#.
This was the first employee found under this case-sensitive last name
search.





An employee with that exact last name was not found


Employee #ListGetAt(ValueList(SearchEmpLastName.FirstName), temp)#
#ListGetAt(ValueList(SearchEmpLastName.LName), temp)#, of the
#ListGetAt(ValueList(SearchEmpLastName.Department), temp)#
Department, can be reached at
#ListGetAt(ValueList(SearchEmpLastName.Phone), temp)#.
This was the first employee found under this case-insensitive last
name search.





© 2014 Adobe Systems Incorporated. All rights reserved.

2018

Adobe ColdFusion Documentation

ListFirst
Description

Gets the first element of a list.
Returns

The first element of a list. If the list is empty, returns an empty string.
Category

List functions
Function syntax

ListFirst(list [, delimiters, includeEmptyValues ])

See also

ListGetAt, ListLast, ListQualify; Lists in Data types- Developing guide in the Developing ColdFusion
Applications
Parameters

Parameter

Description

includeEmptyValues

Optional. Set to yes to include empty values.

list

A list or a variable that contains a list.

delimiters

A string or a variable that contains one. Characters that
separate list elements. The default value is comma. If
this parameter contains more than one character,
ColdFusion processes each occurrence of each
character as a delimiter.

Usage

ColdFusion ignores empty list elements; thus, the list "a,b,c,,,d" has four elements.
Example

© 2014 Adobe Systems Incorporated. All rights reserved.

2019

Adobe ColdFusion Documentation

ListFirst Example


SELECT Username, Subject, Posted
FROMMessages


Before editing the list, it is: 
#ValueList(GetMessageUser.Username)#.
(Users who posted more than once are listed more than once.)

The first user in the list is:
#ListFirst(temp)#
The rest of the list is: #ListRest(temp)#.
(Users who posted more than once are listed more than once.)
The last user in the list is: #ListLast(temp)#

© 2014 Adobe Systems Incorporated. All rights reserved.

2020

Adobe ColdFusion Documentation

ListGetAt
Description

Gets a list element at a specified position.
Returns

Value of the list element at position position.
Category

List functions
Function syntax

ListGetAt(list, position [, delimiters, includeEmptyValues ])

See also

ListFirst, ListLast, ListQualify, ListSetAt; Lists in Data types- Developing guide in the Developing
ColdFusion Applications
Parameters

Parameter

Description

list

A list or a variable that contains one.

position

A positive integer or a variable that contains one.
Position at which to get element. The first list position is
1.

delimiters

A string or a variable that contains one. Characters that
separate list elements. The default value is comma. If
this parameter contains more than one character,
ColdFusion processes each occurrence of each
character as a delimiter.

includeEmptyValues

Optional. Set to yes to include empty values.

Usage

If you use list functions on strings that are delimited by a delimiter character and a space, a returned list element
might contain a leading space; you use the trim function to remove such spaces from a returned element. For
example, consider this list:



© 2014 Adobe Systems Incorporated. All rights reserved.

2021

Adobe ColdFusion Documentation

To get a value from this list, use the trim function to remove the space before the returned value:



With this usage, MyValue = "two hundred", not " two hundred", and spaces within a list element are preserved.
ColdFusion ignores empty list elements; thus, the list "a,b,c,,,d" has four elements.
Example

ListGetAt Example


SELECT Username, Subject, Posted
FROMMessages



This list of usernames who have posted messages numbers
#ListLen(temp)# users.


Username #Counter#: #ListGetAt(temp, Counter)# 



© 2014 Adobe Systems Incorporated. All rights reserved.

2022

Adobe ColdFusion Documentation

ListInsertAt
Description

Inserts an element in a list.
Returns

A copy of the list_,_ with value inserted at the specified position.
Category

List functions
Function syntax

ListInsertAt(list, position, value [, delimiters, includeEmptyValues ])

See also

ListDeleteAt, ListAppend, ListPrepend, ListSetAt; Lists in Data types- Developing guide in the Developin
g ColdFusion Applications
Parameters

Parameter

Description

includeEmptyValues

Optional. Set to yes to include empty values.

list

A list or a variable that contains one.

position

A positive integer or a variable that contains one.
Position at which to insert element. The first list position
is 1.

value

An element or a list of elements.

delimiters

A string or a variable that contains one. Characters that
separate list elements. The default value is comma. If
this parameter contains more than one character,
ColdFusion processes each occurrence of each
character as a delimiter.

Usage

When inserting an element, ColdFusion inserts a delimiter. If delimiters contains more than one delimiter,
ColdFusion uses the first delimiter in the string; if delimiters is omitted, ColdFusion uses a comma. ColdFusion
ignores empty list elements; thus, the list "a,b,c,,,d" has four elements.
Example

© 2014 Adobe Systems Incorporated. All rights reserved.

2023

Adobe ColdFusion Documentation



SELECT PARKNAME,CITY,STATE
FROM PARKS
WHERE PARKNAME LIKE 'DE%'




The original list: #temp#



© 2014 Adobe Systems Incorporated. All rights reserved.

2024

Adobe ColdFusion Documentation

ListLast
Description

Gets the last element of a list.
Returns

The last element of the list.
Category

List functions
Function syntax

ListLast(list [, delimiters, includeEmptyValues ])

See also

ListGetAt, ListFirst; Lists in Data types- Developing guide in the Developing ColdFusion Applications
Parameters

Parameter

Description

includeEmptyValues

Optional. Set to yes to include empty values.

list

A list or a variable that contains a list.

delimiters

A string or a variable that contains one. Characters that
separate list elements. The default value is comma. If
this parameter contains more than one character,
ColdFusion processes each occurrence of each
character as a delimiter; you cannot specify a
multicharacter delimiter.

Usage

If you use list functions on strings that separated by a delimiter character and a space, a returned list element might
contain a leading space; use the trim function to remove leading and trailing spaces from a returned element. For
example, consider this list:



To get a value from this list, use the trim function to remove the space before the returned value:

© 2014 Adobe Systems Incorporated. All rights reserved.

2025

Adobe ColdFusion Documentation



With this usage, the MyValue variable gets the value "three hundred", not " three hundred", and spaces within a list
element are preserved.ColdFusion ignores empty list elements; thus, the list "a,b,c,,,d" has four elements.
Example

ListFirst, ListLast, and ListRest Example


SELECT Username, Subject, Posted
FROMMessages


Before editing the list, it is: 
#ValueList(GetMessageUser.Username)#.
(Users who posted more than once are listed more than once.)

The first user in the list is: #ListFirst(temp)#
The rest of the list is: #ListRest(temp)#.
(Users who posted more than once are listed more than once.)
The last user in the list is: #ListLast(temp)#

© 2014 Adobe Systems Incorporated. All rights reserved.

2026

Adobe ColdFusion Documentation

ListLen
Description

Determines the number of elements in a list. Integer; the number of elements in a list.
Category

List functions
Function syntax

ListLen(list [, delimiters ])
ListLen(list [, delimiters, includeEmptyValues ])

See also

ListAppend, ListDeleteAt, ListInsertAt, ListPrepend; Lists in Data types- Developing guide in the Devel
oping ColdFusion Applications
Parameters

Parameter

Description

list

A list or a variable that contains one.

delimiters

A string or a variable that contains one. Characters that
separate list elements. The default value is comma. If
this parameter contains more than one character,
ColdFusion processes each occurrence of each
character as a delimiter.

includeEmptyValues

If includeEmptyValues is set to true, all empty
values in the list will be considered when computing
length. If set to false, the empty list elements are
ignored.

Usage

ColdFusion ignores empty list elements; thus, the list "a,b,c,,,d" has four elements.Here are some examples of
ListLen processing:
Statement

Output

Comment

ListLen('a,b, c,,,d')

4

Third element is " c"

ListLen('a,b, c,,,d',',')

4

Fourth element is "d'"

ListLen('elem_1__elem_2__e
lem_3')

1

© 2014 Adobe Systems Incorporated. All rights reserved.

2027

Adobe ColdFusion Documentation

ListLen('elem*1**elem*2**e
lem*3')

1

ListLen('elem_1__elem_2_el
em_3','')

6

ListLen("1,,3", ",", true)

3

Example

ListLen Example


SELECT Username, Subject, Posted
FROMMessages



This is a list of usernames who have posted messages
#ListLen(temp)# users.


Username #Counter#:
#ListGetAt(temp, Counter)#



© 2014 Adobe Systems Incorporated. All rights reserved.

2028

Adobe ColdFusion Documentation

ListPrepend
Description

Inserts an element at the beginning of a list.
Returns

A copy of the list_,_ with value inserted at the first position.
Category

List functions
Function syntax

ListPrepend(list, value [, delimiters ])

See also

ListAppend, ListInsertAt, ListSetAt; Lists in Data types- Developing guide in the Developing ColdFusion
Applications
Parameters

Parameter

Description

list

A list or a variable that contains one.

value

An element or a list of elements.

delimiters

A string or a variable that contains one. Characters that
separate list elements. The default value is comma. If
this parameter contains more than one character,
ColdFusion only uses the first character and ignores
the others.

Usage

When prepending an element to a list, ColdFusion inserts a delimiter. If delimiters_ contains more_ than one
delimiter character, ColdFusion uses the first delimiter in the string; if delimiters is omitted, ColdFusion uses a
comma.ColdFusion ignores empty list elements; thus, the list "a,b,c,,,d" has four elements.If the delimiters para
meter is the empty string (""), ColdFusion returns the contents of the value parameter.
Example

© 2014 Adobe Systems Incorporated. All rights reserved.

2029

Adobe ColdFusion Documentation



SELECT PARKNAME,CITY,STATE
FROM PARKS
WHERE PARKNAME LIKE 'DE%'



The original list: #temp#



© 2014 Adobe Systems Incorporated. All rights reserved.

2030

Adobe ColdFusion Documentation

ListQualify
Description

Inserts a string at the beginning and end of list elements.
Returns

A copy of the list, with qualifier before and after the specified elements.
Category

List functions
Function syntax

ListQualify(list, qualifier [, delimiters, elements, includeEmptyValues ])

See also

Lists in Using ColdFusion Variables in the Developing ColdFusion Applications
History

ColdFusion MX: Changed behavior: as the elements parameter value, you must specify "all" or "char";
otherwise, ColdFusion throws an exception. (In earlier releases, the function ignored an invalid value, and used "al
l"; this was inconsistent with other functions.)
Parameters

Parameter

Description

includeEmptyValues

Optional. Set to yes to include empty values.

list

A list or a variable that contains one.

qualifier

A string or a variable that contains one. Character or
string to insert before and after the list elements
specified in the elements parameter.

delimiters

A string or a variable that contains one. Characters that
separate list elements. The default value is comma. If
this parameter contains more than one character,
ColdFusion uses the first character as the delimiter and
ignores the remaining characters.

elements

all: all elements
char: elements that are composed of alphabetic
characters

Usage

© 2014 Adobe Systems Incorporated. All rights reserved.

2031

Adobe ColdFusion Documentation

The new list might not preserve all of the delimiters in the list.ColdFusion ignores empty list elements; thus, the list
"a,b,c,,,d" has four elements.
Example


SELECT FirstName, LastName
FROM Employees

ListQualify Example
This example uses ListQualify to put the full names of the
employees in the query within quotation marks.










The contents of the unqualified list are as follows: 
#myList#





The contents of the qualified list are as follows: 
#qualifiedList1#





The contents of the second qualified list are: 
#qualifiedList2#


© 2014 Adobe Systems Incorporated. All rights reserved.

2032

Adobe ColdFusion Documentation

ListRemoveDuplicates
Description

Removes duplicate values (if they exist) in a list.
Returns

List sans duplicate values
History

ColdFusion 10: Added this function
Syntax

ListRemoveDuplicates(list[, delimiter] [, ignoreCase])
Properties

Parameter

Description

list

Required. List of objects.

delimiter

Optional. Character(s) that separate list elements. The
default value is comma. .

ignoreCase

Optional. If true, ignores the case of strings in the list.
By default the value is set to false.

Example


myList = "one,two,three,four,five,one,five,three"
newList = listremoveduplicates(myList);
//default delimeter is ","
//newList contains "one,two,three,four,five"



myList = "one,two,three,four,five,ONE,TWO,THREE"
newList = listremoveduplicates(myList, ",", true);
//newList contains "one,two,three,four,five"


© 2014 Adobe Systems Incorporated. All rights reserved.

2033

Adobe ColdFusion Documentation

ListRest
Description

Gets a list, without its first element.
Returns

A copy of list, without the first element. If list has one element, returns an empty list.
Category

List functions
Function syntax

ListRest(list [, delimiters, includeEmptyValues ])

See also

ListFirst, ListGetAt, ListLast; Lists in Data types- Developing guide in the Developing ColdFusion
Applications
Parameters

Parameter

Description

includeEmptyValues

Optional. Set to yes to include empty values.

list

A list or a variable that contains one.

delimiters

A string or a variable that contains one. Characters that
separate list elements. The default value is comma. If
this parameter contains more than one character,
ColdFusion processes each occurrence of each
character as a delimiter.

Usage

If the list begins with one or more empty entries, this function drops them, as well as the first element. ColdFusion
ignores empty list elements; thus, the list "a,b,c,,,d" has four elements.
Example

© 2014 Adobe Systems Incorporated. All rights reserved.

2034

Adobe ColdFusion Documentation

ListFirst, ListLast, and ListRest Example


SELECT Username, Subject, Posted
FROMMessages


Before editing the list, it is: 
#ValueList(GetMessageUser.Username)#.
(Users who posted more than once are listed more than once.)
The first user in the list is:
#ListFirst(temp)# 
The rest of the list is: #ListRest(temp)#.
(Users who posted more than once are listed more than once.)
The last user in the list is: #ListLast(temp)#

© 2014 Adobe Systems Incorporated. All rights reserved.

2035

Adobe ColdFusion Documentation

ListSetAt
Description

Replaces the contents of a list element.
Returns

A copy of a list, with a new value assigned to the element at a specified position.
Category

List functions
Function syntax

ListSetAt(list, position, value [, delimiters, includeEmptyValues ])

See also

ListDeleteAt, ListGetAt, ListInsertAt; Lists in Data types- Developing guide in the Developing ColdFusion
Applications
History

ColdFusion MX: Changed delimiter modification: ColdFusion MX does not modify delimiters in the list. (In earlier
releases, in some cases, replaced delimiters with the first character in the delimiters parameter.)
Parameters

Parameter

Description

includeEmptyValues

Optional. Set to yes to include empty values.

list

A list or a variable that contains one.

position

A positive integer or a variable that contains one.
Position at which to set a value. The first list position is
1.

value

An element or a list of elements.

delimiters

A string or a variable that contains one. Characters that
separate list elements. The default value is comma. If
this parameter contains more than one character,
ColdFusion processes each occurrence of each
character as a delimiter.

Usage

When assigning an element to a list, ColdFusion inserts a delimiter. If delimiters contains more than one

© 2014 Adobe Systems Incorporated. All rights reserved.

2036

Adobe ColdFusion Documentation

delimiter, ColdFusion uses the first delimiter in the string, or, if delimiters was omitted, a comma. ColdFusion
ignores empty list elements; thus, the list "a,b,c,,,d" has four elements.
Example

ListSetAt Example


SELECT Username, Subject, Posted
FROMMessages



This is a list of #ListLen(temp)#
subjects posted in messages.




(#Counter#) SUBJECT: #ListGetAt(temptoo, Counter)#



Note that element 2, "#changedElement#",
has been altered to "I changed this subject" using ListSetAt.

© 2014 Adobe Systems Incorporated. All rights reserved.

2037

Adobe ColdFusion Documentation

ListSort
Description

Sorts list elements according to a sort type and sort order.
Returns

A copy of a list, sorted.
Category

List functions
Function syntax

ListSort(list, sort_type [, sort_order, delimiters, includeEmptyValues ])

See also

Lists in Using ColdFusion Variables in the Developing ColdFusion Applications
History

ColdFusion 10: Added support for all Java supported locale-specific characters (including support for umlaut
characters). A flag for this support has been added for sorttype = "text" or sorttype = "textnocase".ColdFusion MX:
Changed the order in which sorted elements are returned: in a textnocase, descending sort, this function might
return elements in a different sort order than in earlier releases. If sort_type = "textnocase" and s{{ort_order}}
= "desc", ColdFusion MX processes elements that differ only in case differently from earlier releases. ColdFusion
MX outputs the elements in the reverse of the ascending order. Earlier releases do not change order of elements
that differ only in case. Both operations are correct. The new operation ensures that an ascending and descending
sort output elements in exactly reverse order.For example, in a textnocase, desc sort of d,a,a,b,A, the
following occurs:
ColdFusion MX returns d,b,A,a,a
Earlier ColdFusion releases return d,b,a,a,A(In a textnocase, asc sort, all ColdFusion releases return a
,a,A,b,d.)
Parameters

Parameter

Description

includeEmptyValues

Optional. Set to yes to include empty values.

list

A list or a variable that contains one.

localeSensitive

Specify if you wish to do a locale sensitive sorting. The
default value is false.

© 2014 Adobe Systems Incorporated. All rights reserved.

2038

Adobe ColdFusion Documentation

sort_type

numeric: sorts numbers
text: sorts text alphabetically, taking case into
account (also known as case sensitive). All letters of
one case precede the first letter of the other case:
aabzABZ, if sort_order = "asc" (ascending
sort)- ZBAzbaa, if sort_order = "desc" (descen
ding sort)
textnocase: sorts text alphabetically, without regard
to case (also known as case-insensitive). A letter in
varying cases precedes the next letter:
aAaBbBzzZ, in an ascending sort; preserves original
intra-letter order - ZzzBbBaAa, in a descending sort;
reverses original intra-letter order

sort_order

asc - ascending sort order. Default.
aabzABZ or aAaBbBzzZ, depending on value of sor
t_type, for letters- from smaller to larger, for
numbers
desc - descending sort order.
ZBAzbaa or ZzzBbBaAa, depending on value of sor
t_type, for letters- from larger to smaller, for
numbers

delimiters

A string or a variable that contains one. Characters that
separate list elements. The default value is comma. If
this parameter contains more than one character,
ColdFusion uses the first character in the string as the
delimiter, and ignores the rest.

Usage

ColdFusion ignores empty list elements; thus, the list "a,b,c,,,d" has four elements.
Example

© 2014 Adobe Systems Incorporated. All rights reserved.

2039

Adobe ColdFusion Documentation

ListSort Example


SELECT
Username, Subject, Posted
FROM
Messages


Here is the unsorted list. 
#myList#

Here is the list sorted alphabetically:

#sortedList#

Here is a numeric list that is to be sorted in descending order.

#sortedNums# 
Here is a list that must be sorted numerically, since it contains
negative and positive numbers, and decimal numbers. 

#sortedNums2# 
Here is a list to be sorted alphabetically without consideration of case.

#sortedMix# 

© 2014 Adobe Systems Incorporated. All rights reserved.

2040

Adobe ColdFusion Documentation

ListToArray
Description

Copies the elements of a list to an array.
Returns

An array
Category

Array functions, Conversion functions, List functions
Function syntax

ListToArray(list [, delimiters[, includeEmptyFields[, multiCharacterDelimiter]]])

See also

ArrayToList; Using Arrays and Structures in the Developing ColdFusion Applications
History

ColdFusion 9: Added the multiCharacterDelimiter parameter.
Parameters

Parameter

Description

list

A list or a variable that contains one.You define a list
variable with a cfset statement.

delimiters

A string or a variable that contains one. ColdFusion
treats each character in the string as a delimiter. The
default value is comma.

includeEmptyFields

A Boolean value specifying whether to create empty
array entries if there are two delimiters in a row.
false-(Default) ignore empty elements in a list; for
example, convert a,,c into an array with only two
elements.
true-Convert empty elements in a list to empty array
entries; for example, convert a,,c into an array with
three elements, the second of which is empty.

© 2014 Adobe Systems Incorporated. All rights reserved.

2041

Adobe ColdFusion Documentation

multiCharacterDelimiter

A Boolean value specifying whether the delimiters p
arameter specifies a multi-character delimiter. The
default is false. If this parameter is true, the delimi
ters parameter must specify a single delimiter
consisting of multiple characters. This parameter
enables the ListToArray function to convert a list such
as the following to an array of color names:
red:|orange:|yellow:|green:|blue:|indigo:|violet.

Usage

ColdFusion, by default, ignores empty list elements; thus, the list "a,b,c,,,d" has four elements.ColdFusion treats
each character in the delimiters parameter as a separate delimiter. Therefore, if the parameter is ",+" ColdFusion will
break the list at either a comma or a plus sign.If you specify a multiCharacterDelimiter parameter, all list
elements must be separated by exactly the specified characters. For example, the following code creates an array
with three entries, "red, orange", "yellow, green" and "blue, violet".




Example

ListToArray Example


SELECT Username, Subject, Posted
FROMMessages


My list is a list with #ListLen(myList)#
elements.

My array list is an array with #ArrayLen(myArrayList)#
 elements.

© 2014 Adobe Systems Incorporated. All rights reserved.

2042

Adobe ColdFusion Documentation

ListValueCount
Description

Counts instances of a specified value in a list. The search is case sensitive.
Returns

The number of instances of value in the list.
Category

List functions, String functions
Function syntax

ListValueCount(list, value [, delimiters ])

See also

ListValueCountNoCase; Lists in Data types- Developing guide in the Developing ColdFusion Applications
Parameters

Parameter

Description

list

A list or a variable that contains one.

value

String or number, or a variable that contains one. Item
for which to search. The search is case sensitive.

delimiters

A string or a variable that contains one. Characters that
separate list elements. The default value is comma. If
this parameter contains more than one character,
ColdFusion processes each occurrence of each
character as a delimiter.

Example

© 2014 Adobe Systems Incorporated. All rights reserved.

2043

Adobe ColdFusion Documentation


SELECT Department
FROM Employees

ListValueCount Example
This example uses ListValueCount to count employees in a department.

Select a department:


Accounting


Administration


Engineering


Sales









There are no employees in #FORM.departmentName#

 
There is only one person in #FORM.departmentName#.


 
There are #numberInDepartment# people in #FORM.departmentName#.




© 2014 Adobe Systems Incorporated. All rights reserved.

2044

Adobe ColdFusion Documentation

ListValueCountNoCase
Description

Counts instances of a specified value in a list. The search is case-insensitive.
Returns

The number of instances of value in the list.
Category

List functions
Function syntax

ListValueCountNoCase(list, value [, delimiters ])

See also

ListValueCount; Lists in Data types- Developing guide in the Developing ColdFusion Applications
Parameters

Parameter

Description

list

A list or a variable that contains one.

value

String or number, or a variable that contains one. Item
for which to search. The search is case-insensitive.

delimiters

A string or a variable that contains one. Characters that
separate list elements. The default value is comma. If
this parameter contains more than one character,
ColdFusion processes each occurrence of each
character as a delimiter.

Example

© 2014 Adobe Systems Incorporated. All rights reserved.

2045

Adobe ColdFusion Documentation


SELECT Department
FROM Employees

ListValueCountNoCase Example
This example uses ListValueCountNoCase to count employees in a department.

Select a department:


Accounting


Administration


Engineering


Sales










There are no employees in #FORM.departmentName# 

 
There is only one person in #FORM.departmentName#.


 
There are #numberInDepartment# people in #FORM.departmentName#.




© 2014 Adobe Systems Incorporated. All rights reserved.

2046

Adobe ColdFusion Documentation

LJustify
Description

Left justifies characters in a string of a specified length.
Returns

A copy of a string, left-justified.
Category

Display and formatting functions, String functions
Function syntax

LJustify(string, length)

See also

CJustify, RJustify
Parameters

Parameter

Description

string

A string or a variable that contains one

length

Length of field in which to justify string

Example

© 2014 Adobe Systems Incorporated. All rights reserved.

2047

Adobe ColdFusion Documentation











LJustify Function
Enter a string, and it will be left justified within the sample field


 


© 2014 Adobe Systems Incorporated. All rights reserved.

2048

Adobe ColdFusion Documentation

Location
Description

A function equivalent of the cflocation tag and is used in the  mode.
Parameters

Same as the  tag.
Category

Data output functions
Function syntax

location("url", addtoken, statusCode);

For positional notations, the sequence must be followed exactly in the same manner as provided in the syntax. If
you do not provide one of the parameters, use an empty string instead. This does not apply to Boolean values for
which you must provide proper values even if you have to skip them.
See also

cfscript, cflocation
Usage

You can call this function as name=value pair or as positional argument.
Example



© 2014 Adobe Systems Incorporated. All rights reserved.

2049

Adobe ColdFusion Documentation

Log
Description

Calculates the natural logarithm of a number. Natural logarithms are based on the constant e (2.71828182845904).
Returns

The natural logarithm of a number.
Category

Mathematical functions
Function syntax

Log(number)

See also

Exp, Log10
Parameters

Parameter

Description

number

Positive real number for which to calculate the natural
logarithm

Example

© 2014 Adobe Systems Incorporated. All rights reserved.

2050

Adobe ColdFusion Documentation

Log Example


Your number, #FORM.number#

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

Enter a positive real number to get its
natural logarithm

The natural logarithm of #FORM.number#: #log(FORM.number)#


Enter a positive real number to get its
logarithm to base 10

The logarithm of #FORM.number# to base 10: #log10(FORM.number)#




Enter a number to see its value raised to the E power, its natural logarithm,
and the logarithm of number to base 10.




© 2014 Adobe Systems Incorporated. All rights reserved.

2051

Adobe ColdFusion Documentation

Log10
Description

Calculates the logarithm of number, to base 10.
Returns

Number; the logarithm of number, to base 10.
Category

Mathematical functions
Function syntax

Log10(number)

See also

Exp, Log
Parameters

Parameter

Description

number

Positive real number for which to calculate the
logarithm

Example

© 2014 Adobe Systems Incorporated. All rights reserved.

2052

Adobe ColdFusion Documentation

Log10 Example


Your number, #FORM.number#

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

You must enter a positive real number to
see the natural logarithm of that number

The natural logarithm of #FORM.number#: #log(FORM.number)#


You must enter a positive real number to
see the logarithm of that number to base 10

The logarithm of #FORM.number# to base 10: #log10(FORM.number)#




Enter a number to find its value raised to the E power, its natural
logarithm, and the logarithm of number to base 10.




© 2014 Adobe Systems Incorporated. All rights reserved.

2053

Adobe ColdFusion Documentation

LSCurrencyFormat
Description

Formats a number in a locale-specific currency format. For countries that use the euro, the result depends on the
JVM.
Returns

A formatted currency value.
Category

Display and formatting functions, International functions
Function syntax

LSCurrencyFormat(number [, type, locale])

See also

LSEuroCurrencyFormat, LSIsCurrency, LSParseCurrency, LSParseEuroCurrency, SetLocale; Handli
ng data in ColdFusion in the Developing ColdFusion Applications
History

ColdFusion 8: Added the locale parameter.
ColdFusion MX: Changed formatting behavior: this function might return different formatting than in earlier releases.
If a negative number is passed to it, it returns a negative number. If type = "local", it returns the value in the
current locale's standard format. If type = "international", it returns the value in the current locale's
international standard format. This function uses Java standard locale formatting rules on all platforms.
Parameters

Parameter

Description

number

Currency value

type

local: the currency format and currency symbol used
in the locale.
With JDK 1.3, the default for Euro Zone countries is
their local currency.- With JDK 1.4, the default for
Euro Zone countries is the euro.
international: the international standard currency
format and currency symbol of the locale.
none: the currency format used in the locale; no
currency symbol

© 2014 Adobe Systems Incorporated. All rights reserved.

2054

Adobe ColdFusion Documentation

Locale to use instead of the locale of the page when
processing the function

locale

Usage

This function uses Java standard locale formatting rules on all platforms.
Note
With a Sun 1.3.1-compliant JVM, use the LSEuroCurrencyFormat function to format euro
currency values.

Currency output

The following table shows sample currency output. For locales that use Euro, the Local and International columns
contains two entries. The first is entry is the result with a Sun the 1.4.1 or later compliant JVM, the second entry is
the result with a 1.3.1-compliant JVM.
Locale

Type = Local

Type = International

Type = None

Chinese (China)

100,000.00

CNY100,000.00

100,000.00

Chinese (Hong Kong)

HK$100,000.00

HKD100,000.00

100,000.00

Chinese (Taiwan)

NT$100,000.00

TWD100,000.00

100,000.00

Dutch (Belgian)

100.000,00 - 100.000,00
BF

BEF100.000,00EUR100.0
00,00

100.000,00

Dutch (Standard)

100.000,00fl 100.000,00

NLG100.000,00EUR100.0
00,00

100.000,00

English (Australian)

$100,000.00

AUD100,000.00

100,000.00

English (Canadian)

$100,000.00

CAD100,000.00

100,000.00

English (New Zealand)

$100,000.00

NZD100,000.00

100,000.00

English (UK)

100,000.00

GBP100,000.00

100,000.00

English (US)

$100,000.00

USD100,000.00

100,000.00

French (Belgian)

100.000,00 - 100.000,00
FB

EUR100.000,00BEF100.0
00,00

100.000,00

French (Canadian)

100 000,00 $

CAD100 000,00

100 000,00

French (Standard)

100 000,00 - 100 000,00
F

EUR100 000,00FRF100
000,00

100 000,00

© 2014 Adobe Systems Incorporated. All rights reserved.

2055

Adobe ColdFusion Documentation

French (Swiss)

SFr. 100'000.00

CHF100'000.00

100'000.00

German (Austrian)

100.000,00-S 100.000,00

EUR100.000,00ATS100.0
00,00

100.000,00

German (Standard)

100.000,00 - 100.000,00
DM

EUR100.000,00DEM100.
000,00

100.000,00

German (Swiss)

SFr. 100'000.00

CHF100'000.00

100'000.00

Italian (Standard)

100.000,00L. 10.000.000

EUR10.000.000ITL10.000
.000

10.000.000

Italian (Swiss)

SFr. 100'000.00

CHF100'000.00

100'000.00

Japanese

100,000

JPY100,000

JPY100,000

Korean

W100,000

KRW100,000

100,000

Norwegian (Bokmal)

kr 100 000,00

NOK100 000,00

100 000,00

Norwegian (Nynorsk)

kr 100 000,00

NOK100 000,00

100 000,00

Portuguese (Brazilian)

R$100.000,00

BRC100.000,00

100.000,00

Portuguese (Standard)

100.000,00 R$100.000,00

EUR100.000,00BRC100.
000,00

100.000,00

Spanish (Mexican)

$100,000.00

MXN100,000.00

100,000.00

Spanish (Modern)

100.000,00 - 10.000.000
Pts

EUR10.000.000ESP10.00
0.000

10.000.000

Spanish (Standard)

100.000,00 - 10.000.000
Pts

ESP10.000.000EUR10.00
0.000

10.000.000

Swedish

100.000,00 kr

SEK100.000,00

100.000,00

Note
ColdFusion maps Spanish (Modern) to the Spanish (Standard) format.

To set the default display format of date, time, number, and currency values, use the SetLocale function.
Example

© 2014 Adobe Systems Incorporated. All rights reserved.

2056

Adobe ColdFusion Documentation

LSCurrencyFormat Example
LSCurrencyFormat returns a currency value using the locale
convention. Default value is "local."



#locale#

Local: #LSCurrencyFormat(100000, "local")#

International: #LSCurrencyFormat(100000, "international")#

None: #LSCurrencyFormat(100000, "none")#





© 2014 Adobe Systems Incorporated. All rights reserved.

2057

Adobe ColdFusion Documentation

LSDateFormat
Description

Formats the date part of a date/time value in a locale-specific format.
Returns

A formatted date/time value. If no mask is specified, the value is formatted according to the locale setting of the
client computer.
Category

Date and time functions, Display and formatting functions, International functions
Function syntax

LSDateFormat(date [, mask, locale])

See also

LSParseDateTime, LSTimeFormat, DateFormat, SetLocale; Handling data in ColdFusion in the Deve
loping ColdFusion Applications
History

ColdFusion 8: Added the locale parameter.ColdFusion MX:
Changed formatting behavior: this function might return different formatting than in earlier releases. This
function uses Java standard locale formatting rules on all platforms.
Added support for the following mask parameter options: short, medium, long, and full.
Parameters

Parameter

Description

date

A date/time object, in the range 100 AD-9999 AD.

© 2014 Adobe Systems Incorporated. All rights reserved.

2058

Adobe ColdFusion Documentation

mask

Characters that show how ColdFusion displays the
date:
d: Day of month. Digits; no leading zero for
single-digit days
dd: Day of month. Digits; leading zero for single-digit
days
ddd: Day of week, abbreviation
dddd: Day of week. Full name
m: Month. Digits; no leading zero for single-digit
months
mm: Month. Digits; leading zero for single-digit
months
mmm: Month. abbreviation (if appropriate)
mmmm: Month. Full name
y: Year. Last two digits; no leading zero for years
less than 10
yy: Year. Last two digits; leading zero for years less
than 10
yyyy: Year. Four digits
gg: Period/era string. Not processed. Reserved for
future use
The following conform to Java locale-specific time
encoding standards. Their exact formats depend on
the locale:
short: dd, mm, and yy separated by / marks
medium: text format using mmm, d, and yyyy
long: text format using mmmm, d, and yyyy
full: text format using dddd, mmmm, d, and yyyy
The default value is mediumFor more information on
formats, see LSParseDateTime.

locale

Locale to use instead of the locale of the page when
processing the function

Usage

This function uses Java standard locale formatting rules on all platforms. When passing date/time value as a string,
enclose it in quotation marks. Otherwise, it is interpreted as a number representation of a date/time object.To
calculate a difference between time zones, use the GetTimeZoneInfo function.
Example

© 2014 Adobe Systems Incorporated. All rights reserved.

2059

Adobe ColdFusion Documentation

LSDateFormat Example
LSDateFormat formats the date part of a date/time value using the
locale convention.



#locale#

#LSDateFormat(Now(), "mmm-dd-yyyy")#

#LSDateFormat(Now(), "mmmm d, yyyy")#

#LSDateFormat(Now(), "mm/dd/yyyy")#

#LSDateFormat(Now(), "d-mmm-yyyy")#

#LSDateFormat(Now(), "ddd, mmmm dd, yyyy")#

#LSDateFormat(Now(), "d/m/yy")#

#LSDateFormat(Now())#





© 2014 Adobe Systems Incorporated. All rights reserved.

2060

Adobe ColdFusion Documentation

LSDateTimeFormat
Description

Formats date and time values using locale-specific date and time formatting conventions.
Returns

A formatted date and time value.
Category

Date and time functions, Display and formatting functions, International functions
Syntax

LSDateTimeFormat (date , mask)
LSDateTimeFormat (date [, mask, locale])
LSDateTimeFormat (date [, mask, locale, timeZone])

See also

LSParseDateTime, LSTimeFormat, DateFormat, SetLocale; Handling data in ColdFusion in the Deve
loping ColdFusion Applications
History

ColdFusion 10: Added the function.
Parameters

Parameter

Description

date

Required. A date/time object, in the range 100 AD-9999
AD.

mask

Optional. Mask that has to be used for formatting. See
DateTimeFormat.

timeZone

The time-zone information. You can specify in either of
the following formats:
Abbreviation such as GMT or PST
Full name such as Europe/Dublin
By default, this is the time-zone followed by the
system.

locale

Locale to use instead of the locale of the page when
processing the function.

Example

© 2014 Adobe Systems Incorporated. All rights reserved.

2061

Adobe ColdFusion Documentation



DateTimeFormat Example
Today's date and time are #todayDateTime#.
Using DateTimeFormat, we can display that date and time in different ways:


#DateTimeFormat(todayDateTime, "yyyy.MM.dd G 'at' HH:nn:ss z")#
#DateTimeFormat(todayDateTime, "EEE, MMM d, ''yy")#
#DateTimeFormat(todayDateTime, "h:nn a")#
#DateTimeFormat(todayDateTime, "hh 'o''clock' a, zzzz")#
#DateTimeFormat(todayDateTime, "K:nn a, z")#
#DateTimeFormat(todayDateTime, "yyyyy.MMMMM.dd GGG hh:nn aaa")#
#DateTimeFormat(todayDateTime, "EEE, d MMM yyyy HH:nn:ss Z")#
#DateTimeFormat(todayDateTime, "yyMMddHHnnssZ", "English (UK)", "GMT")#



© 2014 Adobe Systems Incorporated. All rights reserved.

2062

Adobe ColdFusion Documentation

LSEuroCurrencyFormat
Description

Formats a number in a locale-specific currency format.
Returns

A formatted currency value. For countries in the Euro currency zone, the function uses the locale's rule's for
formatting currency in euros.
Category

Display and formatting functions, International functions
Function syntax

LSEuroCurrencyFormat(currency-number [, type, locale])

See also

LSParseEuroCurrency, LSCurrencyFormat, SetLocale; Locale-specific content in the Developing
ColdFusion Applications
History

ColdFusion 8: Added the locale parameter.
ColdFusion MX: Changed formatting behavior: this function might return different formatting than in earlier releases.
This function uses Java locale formatting rules on all platforms, except that it uses the rule detailed in the Usage
section for countries in the Euro currency zone. As a result, it format currencies for non-Euro zone locales using the
country's currency, not euros.
Parameters

Parameter

Description

currency-number

Currency value.

locale

Locale to use instead of the locale of the page when
processing the function

type

local: the currency format used in the locale.
(Default.)
international: the international standard currency
format of the locale. For example, EUR10.00
none: the currency format used in the locale; no
currency symbol

Usage

This function uses euro currency formatting rules for all JVM versions, as follows:

© 2014 Adobe Systems Incorporated. All rights reserved.

2063

Adobe ColdFusion Documentation

If the country of the current locale belongs to the Euro Zone (whose members have converted to the euro) the
formatted output for the local type includes the Euro currency sign; for the international type, the output
includes the euro currency symbol (EUR). If the value is negative, the format includes a negative sign before
the value or parentheses around the value, according to the formatting rules of the current locale.
If the country of the current locale is not in the Euro Zone, the currency sign or symbol of the current locale
displays. If the value is negative, the format includes a negative sign before the value or parentheses around
the value, according to the formatting rules of the current locale.For a list of the locale options that
ColdFusion supports, and information on setting the default display format of date, time, number, and
currency values, see SetLocale.
Currency output

The following table shows examples of currency output:
Locale

Type = Local

Type = International

Type = None

Chinese (China)

100,000.00

CNY100,000.00

100,000.00

Chinese (Hong Kong)

HK$100,000.00

HKD100,000.00

100,000.00

Chinese (Taiwan)

NT$100,000.00

TWD100,000.00

100,000.00

Dutch (Belgian)

100.000,00

EUR100.000,00

100.000,00

Dutch (Standard)

100.000,00

EUR100.000,00

100.000,00

English (Australian)

$100,000.00

AUD100,000.00

100,000.00

English (Canadian)

$100,000.00

CAD100,000.00

100,000.00

English (New Zealand)

$100,000.00

NZD100,000.00

100,000.00

English (UK)

100,000.00

GBP100,000.00

100,000.00

English (US)

$100,000.00

USD100,000.00

100,000.00

French (Belgian)

100.000,00

EUR100.000,00

100.000,00

French (Canadian)

100 000,00 $

CAD100 000,00

100 000,00

French (Standard)

100 000,00

EUR100 000,00

100 000,00

French (Swiss)

SFr. 100'000.00

CHF100'000.00

100'000.00

German (Austrian)

100.000,00

EUR100.000,00

100.000,00

German (Standard)

100.000,00

EUR100.000,00

100.000,00

German (Swiss)

SFr. 100'000.00

CHF100'000.00

100'000.00

© 2014 Adobe Systems Incorporated. All rights reserved.

2064

Adobe ColdFusion Documentation

Italian (Standard)

100.000,00

EUR10.000.000

10.000.000

Italian (Swiss)

SFr. 100'000.00

CHF100'000.00

100'000.00

Japanese

100,000

JPY100,000

JPY100,000

Korean

W100,000

KRW100,000

100,000

Norwegian (Bokmal)

kr 100 000,00

NOK100 000,00

100 000,00

Norwegian (Nynorsk)

kr 100 000,00

NOK100 000,00

100 000,00

Portuguese (Brazilian)

R$100.000,00

BRC100.000,00

100.000,00

Portuguese (Standard)

100.000,00

EUR100.000,00

100.000,00

Spanish (Mexican)

$100,000.00

MXN100,000.00

100,000.00

Spanish (Modern)

100.000,00

EUR10.000.000

10.000.000

Spanish (Standard)

100.000,00

ESP10.000.000

10.000.000

Swedish

100.000,00 kr

SEK100.000,00

100.000,00

Note
ColdFusion uses the Spanish (Standard) formats for Spanish (Modern) and Spanish (Standard).

The following example shows how the function formats negative values. The format includes a negative sign before
the value, or parentheses around the value, according to the formatting rules of the current locale.
Input value

Output if locale = French (Standard)

Output if locale = English (US)

-1234.56

-1 234,56

($1,234.56)

Example

© 2014 Adobe Systems Incorporated. All rights reserved.

2065

Adobe ColdFusion Documentation

LSEuroCurrencyFormat Example
LSEuroCurrencyFormat returns a currency value using the locale
convention. Default value is "local."



#locale#

Local: #LSEuroCurrencyFormat(100000, "local")#

International: #LSEuroCurrencyFormat(100000, "international")#

None: #LSEuroCurrencyFormat(100000, "none")#





© 2014 Adobe Systems Incorporated. All rights reserved.

2066

Adobe ColdFusion Documentation

LSIsCurrency
Description

Determines whether a string is a valid representation of a currency amount in the current locale.
Returns

True, if the parameter is formatted as a valid currency amount, including the appropriate currency indicator. The
return value is True for amounts in the local, international, or none currency formats.
Category

Display and formatting functions, Decision functions, International functions
Function syntax

LSIsCurrency(string [, locale])

See also

GetLocale, SetLocale, LSCurrencyFormat
History

ColdFusion 8: Added the locale parameter.
ColdFusion MX: Changed formatting behavior: this function might return a different result than in earlier releases.
This function uses Java standard locale formatting rules on all platforms; the results might vary depending upon the
JVM; for example, Sun JVM 1.4.1 requires euro format the local currency if the current locale's country belongs to
the Euro Zone.
Parameters

Parameter

Description

string

A currency string or a variable that contains one.

locale

Locale to use instead of the locale of the page when
processing the function

Usage

For examples of ColdFusion code and output that shows differences between earlier ColdFusion releases and
ColdFusion MX in accepting input formats and displaying output, see LSCurrencyFormat.

© 2014 Adobe Systems Incorporated. All rights reserved.

2067

Adobe ColdFusion Documentation

Note
If the locale belongs to a Euro zone country and the currency is a correctly formatted euro value
for the locale, this function returns True for all JVMs, including Sun 1.3.1. As a result, with
1.3.1-compliant JVMs, the LSIsCurrency function does not ensure that LSParseCurrency retur
ns a value. If a currency uses the older country-specific format for Euro Zone locales, the
LSIsCurrency function returns False for newer JVMs, such as Sun 1.4.1 and 1.6, and True for
older JVMs, such as Sun 1.3.1.
Note
To set the default display format of date, time, number, and currency values, use the SetLocal
e function.

Example

LSIsCurrency Example



Is the value "#FORM.myValue#"
a proper currency value for #GetLocale()#?
Answer: #LSIsCurrency(FORM.myValue)#


Select a locale for which you would like to check a currency value:



© 2014 Adobe Systems Incorporated. All rights reserved.

2068

Adobe ColdFusion Documentation

LSIsDate
Description

Determines whether a string is a valid representation of a date/time value in the current locale.
Returns

True, if the string can be formatted as a date/time value in the current locale; False, otherwise.
Category

Date and time functions, Display and formatting functions, International functions
Function syntax

LSIsDate(string [, locale])

See also

CreateDateTime, GetLocale, IsNumericDate, LSDateFormat, ParseDateTime, SetLocale; Handling
data in ColdFusion in the Developing ColdFusion Applications
History

ColdFusion 8: Added the locale parameter.ColdFusion MX:
Changed formatting behavior: this function might return a different result than in earlier releases. This function
uses Java standard locale formatting rules on all platforms.
Changed behavior: this function accepts a dash or hyphen character only in the Dutch(Standard) and
Portuguese (Standard) locales. If called this way (for example, LsIsDate("3-1-2002") in any other locale, this
function returns False. (Earlier releases returned True.)
Changed behavior: when using the SUN JRE 1.3.1 on an English(UK) locale, this function returns False for a
date that has a one-digit month or day (for example, 1/1/01). To work around this, insert a zero in a one-digit
month or day (for example, 01/01/01).
Parameters

Parameter

Description

string

A string or a variable that contains one

locale

Locale to use instead of the locale of the page when
processing the function

Usage

A date/time object is in the range 100 AD-9999 AD.To set the default display format of date, time, number, and
currency values, use the SetLocale function.
Example

© 2014 Adobe Systems Incorporated. All rights reserved.

2069

Adobe ColdFusion Documentation

LSIsDate Example



Is the value "#FORM.myValue#" a proper date
value for #GetLocale()#?
Answer: #LSIsDate(FORM.myValue)#


Select a locale for which you would like to check a date value:



© 2014 Adobe Systems Incorporated. All rights reserved.

2070

Adobe ColdFusion Documentation

LSIsNumeric
Description

Determines whether a string is a valid representation of a number in the current locale.
Returns

True, if the string represents a number the current locale; False, otherwise.
Category

Decision functions, International functions, String functions
Function syntax

LSIsNumeric(string [, locale])

See also

GetLocale, SetLocale; Handling data in ColdFusion in the Developing ColdFusion Applications
History

ColdFusion 8: Added the locale parameter.
ColdFusion MX: Changed formatting behavior: this function might return a different result than in earlier releases.
This function uses Java standard locale formatting rules on all platforms.
Parameters

Parameter

Description

string

A string or a variable that contains one

locale

Locale to use instead of the locale of the page when
processing the function

Usage

To set the default display format of date, time, number, and currency values, use the SetLocale function.
Example

© 2014 Adobe Systems Incorporated. All rights reserved.

2071

Adobe ColdFusion Documentation

LSIsNumeric Example



Is the value "#FORM.myValue#"
a proper numeric value for #GetLocale()#?
Answer: #LSIsNumeric(FORM.myValue)#


Select a locale for which to check a numeric value:
...

© 2014 Adobe Systems Incorporated. All rights reserved.

2072

Adobe ColdFusion Documentation

LSNumberFormat
Description

Formats a number in a locale-specific format.
Returns

A formatted number.
If no mask is specified, it returns the number formatted as an integer
If no mask is specified, truncates the decimal part; for example, it truncates 34.57 to 35
If the specified mask cannot correctly mask a number, it returns the number unchanged
If the parameter value is "" (an empty string), it returns 0.
Category

Display and formatting functions, International functions
Function syntax

LSNumberFormat(number [, mask, locale])

See also

GetLocale, SetLocale; Handling data in ColdFusion in the Developing ColdFusion Applications
History

ColdFusion 8: Added the locale parameter.
ColdFusion MX:
Changed behavior: if the specified mask format cannot correctly mask a number, this function returns the
number unchanged. (In earlier releases, it truncated the number or threw an error.) (If no mask is specified,
ColdFusion MX truncates the decimal part as ColdFusion 5 does. For example, it truncates 1234.567 to
1235.)
Changed formatting behavior: this function might return different formatting than in earlier releases. This
function uses Java standard locale formatting rules on all platforms.
Parameters

Parameter

Description

number

Number to format

mask

LSNumberFormat mask characters apply, except:
dollar sign, comma, and dot are mapped to their
locale-specific equivalents.

locale

Locale to use instead of the locale of the page when
processing the function

© 2014 Adobe Systems Incorporated. All rights reserved.

2073

Adobe ColdFusion Documentation

The following table lists the LSNumberFormat mask characters:
Character

Meaning

_

(Underscore.) Digit placeholder.

9

Digit placeholder. (Shows decimal places more clearly
than _ .)

.

Location of a mandatory decimal point (or
locale-appropriate symbol).

0

Located to the left or right of a mandatory decimal
point. Pads with zeros.

()

If number is less than zero, puts parentheses around
the mask.

+

Puts plus sign before positive number; minus sign
before negative number.

-

Puts space before positive number; minus sign before
negative number.

,

Separates every third decimal place with a comma (or
locale-appropriate symbol).

L,C

Left-justifies or center-justifies number within width of
mask column. First character of mask must be L or C.
The default value is right-justified.

$

Puts a dollar sign (or locale-appropriate symbol) before
formatted number. First character of mask must be the
dollar sign ($).

^

Separates left and right formatting.

Note
If you do not specify a sign for the mask, positive and negative numbers do not align in columns.
To put a plus sign or space before positive numbers and a minus sign before negative numbers,
use the plus or hyphen mask character, respectively.

Usage

This function uses Java standard locale formatting rules on all platforms. The position of symbols in format masks
determines where the codes take effect. For example, if you put a dollar sign at the far left of a format mask,
ColdFusion displays a dollar sign at the left edge of the formatted number. If you separate the dollar sign on the left
edge of the format mask by at least one underscore, ColdFusion displays the dollar sign just to the left of the digits
in the formatted number. These examples show how symbols determine formats:

© 2014 Adobe Systems Incorporated. All rights reserved.

2074

Adobe ColdFusion Documentation

Number

Mask

Result

4.37

$___._

"$ 4.37"

4.37

$_._

" $4.37"

The positioning can also show where to put a minus sign for negative numbers:
Number

Mask

Result

-4.37

-___._

"- 4.37"

-4.37

-_._

" -4.37"

The positions for a symbol are: far left, near left, near right, and far right. The left and right positions are determined
by the side of the decimal point on which the code character is shown. For formats that do not have a fixed number
of decimal places, you can use a caret (^) to separate the left fields from the right.An underscore determines
whether the code is placed in the far or near position. Most code characters effect is determined by the field in which
they are located. This example shows how to specify where to put parentheses to display negative numbers:
Number

Mask

Result

3.21

C(_^_)

"( 3.21 )"

3.21

C_(^_)

" (3.21 )"

3.21

C(_^)_

"( 3.21) "

3.21

C_(^)_

" (3.21) "

To set the default display format of date, time, number, and currency values, use the SetLocale function. When
converting from string to double, to prevent rounding errors, this function adds a rounding factor of
1.5543122344752E-014 to the converted number. For example, without adding the rounding factor, converting the
string value 1.275 to double with two digits of precision results in a value of 1.27499999999999999, which would be
rounded up to 1.27. By adding the rounding factor, the conversion correctly results in a value of 1.28. If you round off
a double, such as 1.99499999999999999999999999999, where the last decimal is 10E-14, the rounding factor can
cause an incorrect result.
Example

© 2014 Adobe Systems Incorporated. All rights reserved.

2075

Adobe ColdFusion Documentation

LSNumberFormat Example
LSNumberFormat returns a number value using the locale convention.



#locale#

#LSNumberFormat(-1234.5678, "_________")#

#LSNumberFormat(-1234.5678, "_________.___")#

#LSNumberFormat(1234.5678, "_________")#

#LSNumberFormat(1234.5678, "_________.___")#

#LSNumberFormat(1234.5678, "$_(_________.___)")#

#LSNumberFormat(-1234.5678, "$_(_________.___)")#

#LSNumberFormat(1234.5678, "+_________.___")#

#LSNumberFormat(1234.5678, "-_________.___")#




© 2014 Adobe Systems Incorporated. All rights reserved.

2076

Adobe ColdFusion Documentation

LSParseCurrency
Description

Converts a locale-specific currency string into a formatted number. Attempts conversion by comparing the string with
each the three supported currency formats (none, local, international) and using the first that matches.
Returns

A formatted number (string representation of a number) that matches the value of the parameter.
Category

International functions, String functions
Function syntax

LSParseCurrency(string [, locale])

See also

LSParseEuroCurrency, LSCurrencyFormat, LSEuroCurrencyFormat, LSIsCurrency; Locale-specifi
c content in the Developing ColdFusion Applications
History

ColdFusion 8: Added the locale parameter.
ColdFusion MX: Changed formatting behavior: this function might return different formatting than in earlier releases.
This function uses Java standard locale formatting rules on all platforms.
Parameters

Parameter

Description

string

A locale-specific string a variable that contains one

locale

Locale to use instead of the locale of the page when
processing the function

Usage

This function uses the locale formatting rules of the JVM (specified in the ColdFusion Administrator Java and JVM
page) on all platforms. These rules changed between Sun JVM 1.3.1 and JVM 1.4.1:
JVM 1.3.1 requires that the local and international versions of currencies of countries in the Euro zone be
formatted using the older, country-specific designations, such as 100.000,00 DM or DEM100.000,00 for the
German (Standard) locale. Use the LSParseEuroCurrency function to parse euro currencies in these
locales with JVM 1.3.1.
JVM 1.4.1 requires that currencies for Euro zone countries be expressed as euros; for example 100.000,00
BADCHAR or EUR100.000,00.

© 2014 Adobe Systems Incorporated. All rights reserved.

2077

Adobe ColdFusion Documentation

Note
The LSIsCurrency function always returns True if the locale is in the Euro currency
zone and the currency is expressed in euros, including when using JVM 1.3.1. As a result,
with older JVMs, LSIsCurrency does not ensure that LSParseCurrency returns a
value.

To set the default display format of date, time, number, and currency values, use the SetLocale function.
For a list of the locale-specific formats used to parse the currency, see LSCurrencyFormat.
Example

LSParseCurrency Example
LSParseCurrency coverts a locale-specific currency string to a number.
Attempts conversion through each of the three default currency formats.



#locale#

Local: #LSCurrencyFormat(123456.78, "local")#

Parsed local Currency:
#LSParseCurrency(LSCurrencyFormat(123456,"local"))#

International: #LSCurrencyFormat(123456.78999, "international")#

Parsed International Currency:
#LSParseCurrency(LSCurrencyFormat(123456.78999,"international"))#

None: #LSCurrencyFormat(123456.78999, "none")#

Parsed None formatted currency:
#LSParseCurrency(LSCurrencyFormat(123456.78999,"none"))#





© 2014 Adobe Systems Incorporated. All rights reserved.

2078

Adobe ColdFusion Documentation

LSParseDateTime
Description

Converts a string that is a valid date/time representation in the current locale into a date/time object.
Returns

A date/time object.
Category

Date and time functions, Display and formatting functions, International functions, String functions
Function syntax

LSParseDateTime(date/time-string [, locale, format])

See also

LSDateFormat, ParseDateTime, SetLocale, GetLocale; Locales in the Developing ColdFusion Applications
History

ColdFusion 10: Added the format parameter.
ColdFusion 8: Added the locale parameter.ColdFusion MX:
Changed formatting behavior: this function might not parse string formats that worked with earlier releases.
This function uses Java standard locale formatting rules on all platforms.
Changed how the date/time-string parameter value is processed: ColdFusion processes the date/tim
e-string parameter value time zone information differently than in earlier releases, as described in the
Usage section.
Parameters

Parameter

Description

date/time-string

A string a variable that contains one, in a format that is
readable in the current locale.

format

Optional, provides the format of the string. This string is
used to parse the given date string to date time object.

locale

Locale to use instead of the locale of the page when
processing the function

Usage

This function can parse any date, time, or date/time combination that conforms to Java standard locale formatting
rules for the current locale.The following table lists some of the date/time values you can pass to this function in the
English (US) locale. You can also pass only the date or the time parts of these formats:

© 2014 Adobe Systems Incorporated. All rights reserved.

2079

Adobe ColdFusion Documentation

Format

Example

m/dd/yy h:mm:ss

1/30/02 7:02:33

m/dd/yy h:mm tt

1/30/02 7:02 AM

m/dd/yyyy h:mm

1/30/2002 7:02 AM

mmm dd, yyyy h:mm:ss tt

Jan 30, 2002 7:02:12 AM

mmmm dd, yyyy h:mm:ss tt zzz

January 30, 2002 7:02:23 AM PST

ddd, mmm dd, yyyy hh:mm:ss

Wed, Jan 30, 2002 07:02:12

dddd, mmmm dd, yyyy h:mm:ss tt zzz

Wednesday, January 30, 2002 7:02:12 AM PST

Valid dates are in the range 100 AD-9999 AD. Two-digit years in the range 00-29 are interpreted as being
2000-2029. Two-digit years in the range 30-99 are interpreted as being 1930-1999. This function corrects for
differences between the current time zone and any time zone specified in the input parameter.
If a time zone specified in the date/time-string parameter is different from the time zone setting of the
computer, ColdFusion adjusts the time value to its equivalent in the computer time zone.
If a time zone is not specified in the date/time-stringparameter, ColdFusion does not adjust the time
value.
Note
This function does not accept POP dates, which include a time zone offset value.

In the following example, the parameter formatspecifies the way in which the given date string should be
read:

#lsParseDateTime("01/08/2011","en","MM/dd/yyyy")#

Example

© 2014 Adobe Systems Incorporated. All rights reserved.

2080

Adobe ColdFusion Documentation

LSParseDateTime Example - returns a locale-specific date/time object



#locale#

Locale-specific formats:

#LSDateFormat(Now(), "mmm-dd-yyyy")# #LSTimeFormat(Now())#

#LSDateFormat(Now(), "mmmm d, yyyy")# #LSTimeFormat(Now())#

#LSDateFormat(Now(), "mm/dd/yyyy")# #LSTimeFormat(Now())#

#LSDateFormat(Now(), "d-mmm-yyyy")# #LSTimeFormat(Now())#

#LSDateFormat(Now(), "ddd, mmmm dd, yyyy")# #LSTimeFormat(Now())#

#LSDateFormat(Now(), "d/m/yy")# #LSTimeFormat(Now())#

#LSDateFormat(Now())# #LSTimeFormat(Now())#

Standard Date/Time:
#LSParseDateTime("#LSDateFormat(Now())# #LSTimeFormat(Now())#")#




© 2014 Adobe Systems Incorporated. All rights reserved.

2081

Adobe ColdFusion Documentation

LSParseEuroCurrency
Description

Formats a locale-specific currency string as a number. Attempts conversion through each of the default currency
formats (none, local, international). Ensures correct handling of euro currency for Euro zone countries.
Returns

A formatted number that matches the value of the string.
Category

International functions, String functions
Function syntax

LSParseEuroCurrency(currency-string [, locale])

See also

LSParseCurrency, LSEuroCurrencyFormat, SetLocale; Locale-specific content in the Developing
ColdFusion Applications
History

ColdFusion 8: Added the locale parameter.ColdFusion MX: Changed formatting behavior: this function might
return different formatting than in earlier releases. This function uses Java locale formatting rules on all platforms,
except that it uses the rule detailed in the Usage section for countries in the Euro currency zone.
Parameters

Parameter

Description

currency-string

Locale-specific string or a variable that contains one.

locale

Locale to use instead of the locale of the page when
processing the function

Usage

This function determines whether the current locale's country belongs to the Euro Zone, whose members have
converted to the euro; if so, the currency-string parameter must be formatted in euros on all JVMs, including
Sun JVM 1.3.1. If the country is not in the Euro zone, the string must follow the locale formatting rules of the JVM.
For examples of valid currency formats in all supported locales, see LSEuroCurrencyFormat.For a list of the locale
options that ColdFusion supports, and information on setting the default display format of date, time, number, and
currency values, see SetLocale.
Example

© 2014 Adobe Systems Incorporated. All rights reserved.

2082

Adobe ColdFusion Documentation

LSParseEuroCurrency Example
Loop through all available locales. Create string representations of the value
123,456 in the three supported currency formats,
and parse the results back to numbers.



Current Locale: #locale#


Value in local currency: #localCurrency#

Parsed using LSParseEuroCurrency:
#LSParseEuroCurrency(localCurrency)#


Value with International currency formatting: #IntlCurrency#

Parsed using LSParseEuroCurrency:
#LSParseEuroCurrency(IntlCurrency)#


Value with no currency formatting: #currency#

Parsed using LSParseEuroCurrency:
#LSParseEuroCurrency(Currency)#





© 2014 Adobe Systems Incorporated. All rights reserved.

2083

Adobe ColdFusion Documentation

LSParseNumber
Description

Converts a string that is a valid numeric representation in the current locale into a formatted number.
Returns

A formatted number that matches the value of the string.
Category

International functions, String functions
Function syntax

LSParseNumber(string [, locale])

See also

LSParseDateTime, SetLocale; Locales in the Developing ColdFusion Applications
History

ColdFusion 8: Added the locale parameter.ColdFusion MX: Changed formatting behavior: this function might
return different formatting than in earlier releases. This function uses Java standard locale formatting rules on all
platforms.
Parameters

Parameter

Description

string

A string or a variable that contains one

locale

Locale to use instead of the locale of the page when
processing the function

Usage

This function uses Java standard locale formatting rules on all platforms.To set the default display format of date,
time, number, and currency values, use the SetLocale function.
Example

© 2014 Adobe Systems Incorporated. All rights reserved.

2084

Adobe ColdFusion Documentation

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



#locale#

#LSNumberFormat(-1234.5678, "_________")#

#LSNumberFormat(-1234.5678, "_________.___")#

#LSNumberFormat(1234.5678, "_________")#

#LSNumberFormat(1234.5678, "_________.___")#

#LSNumberFormat(1234.5678, "$_(_________.___)")#

#LSNumberFormat(-1234.5678, "$_(_________.___)")#

#LSNumberFormat(1234.5678, "+_________.___")#

#LSNumberFormat(1234.5678, "-_________.___")#

The actual number:
#LSParseNumber(LSNumberFormat(1234.5678, "_________"))#





© 2014 Adobe Systems Incorporated. All rights reserved.

2085

Adobe ColdFusion Documentation

LSTimeFormat
Description

Formats the time part of a date/time string into a string in a locale-specific format.
Returns

A string representing the time value.
Category

Date and time functions, Display and formatting functions, International functions
Function syntax

LSTimeFormat(time [, mask ])

See also

LSParseDateTime, LSDateFormat, TimeFormat; Locales in the Developing ColdFusion Applications
History

ColdFusion MX 6.1: Added the mask character L or l to represent milliseconds.
ColdFusion MX:
Changed formatting behavior: this function might return different formatting than in earlier releases. This
function uses Java standard locale formatting rules on all platforms.
Added support for the following mask parameter options: short, medium, long, and full.
Parameters

Parameter
string

© 2014 Adobe Systems Incorporated. All rights reserved.

Description
A date/time value
A string that is convertible to a time value
A date/time object is in the range 100 AD-9999 AD.

2086

Adobe ColdFusion Documentation

mask

Masking characters that determine the format:
h: Hours; no leading zero for single-digit hours
(12-hour clock)
hh: Hours; leading zero for single-digit hours.
(12-hour clock)
H: Hours; no leading zero for single-digit hours
(24-hour clock)
HH: Hours; leading zero for single-digit hours
(24-hour clock)
m: Minutes; no leading zero for single-digit minutes
mm: Minutes; leading zero for single-digit minutes
s: Seconds; no leading zero for single-digit seconds
ss: Seconds; leading zero for single-digit seconds
l: Milliseconds
t: One-character time marker string, such as A or P.
tt: Multiple-character time marker string, such as AM
or PM
The following conform to Java locale-specific time
encoding standards. Their exact formats depend on
the locale:
short: includes hours, minutes; may include AM or
PM
medium: includes hours, minutes; may include AM or
PM
long: medium plus time zone
full: long, may also include an hour designator
The default value is short.

Usage

This function uses Java standard locale formatting rules on all platforms. When passing date/time value as a string,
enclose it in quotation marks. Otherwise, it is interpreted as a number representation of a date/time object.To
calculate a difference between time zones, use the GetTimeZoneInfo function. To set the default display format of
date, time, number, and currency values, use the SetLocale function. If no seconds value is passed to this
function, and the mask value is s, the default output seconds format is one zero; for example, lstimeformat(6:3
9, "h:m:s") returns 6:39:0. If the mask value is ss, it returns 6:39:00.
Example

© 2014 Adobe Systems Incorporated. All rights reserved.

2087

Adobe ColdFusion Documentation

LSTimeFormat Example
LSTimeFormat returns a time value using the locale convention.



#locale#

#LSTimeFormat(Now())#

#LSTimeFormat(Now(), hh:mm:ss)#

#LSTimeFormat(Now(), hh:mm:sst)#

#LSTimeFormat(Now(), hh:mm:sstt)#

#LSTimeFormat(Now(), HH:mm:ss)#





© 2014 Adobe Systems Incorporated. All rights reserved.

2088

Adobe ColdFusion Documentation

LTrim
Description

Removes leading spaces from a string.
Returns

A copy of the string_,_ without leading spaces.
Category

Display and formatting functions, String functions
Function syntax

LTrim(string)

See also

RTrim, ToBase64,Trim
Parameters

Parameter

Description

string

A string or a variable that contains one

Example

LTrim Example


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




Type in some text, and it will be modified by LTrim to remove
leading spaces from the left




© 2014 Adobe Systems Incorporated. All rights reserved.

2089

Adobe ColdFusion Documentation

#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

2090

Adobe ColdFusion Documentation

ListEach
Description
Iterates over every element of a List object and can call a UDF function, passed as the second argument.
Returns

None
Category

List functions
Function syntax

ListEach(String str, UDFMethod function [, String delim, boolean
includeEmptyFields])

Parameters
Parameter

Description

str

An input list object.

function

UDF or closure object.

delim

A list delimiter to be used. The default value is comma
(,).

includeEmptyFields

Boolean. Whether to allow empty fields. Default is
false.

Example 1

empArray = ["awdhesh", "kumar", "agrawal"];
listS = "'awdhesh', 'kumar', 'agrawal'";
ArrayEach(empArray, xclosure);
ListEach(listS, xclosure);
function xclosure(empname, index)
{
writeOutput(empName & " at index: " & index);
}


© 2014 Adobe Systems Incorporated. All rights reserved.

2091

Adobe ColdFusion Documentation

Also, the original array can also be passed to the closure function. So the following code is also valid:

...
function xclosure(empname, index, empArray)
{
}
...

Example 2

cityList = "San Jose,New york, Boston, Las Vegas";
function printCity(String city)
{
writeOutput("
Current city: " & city);
}
ListEach(cityList ,printCity);


© 2014 Adobe Systems Incorporated. All rights reserved.

2092

Adobe ColdFusion Documentation

ListReduce
Description
Iterates over each item of the list and calls the closure to work on the item. This function will reduce the list to a
single value and will return the value.
Returns

any
Syntax

ListReduce(list, function(result, item [,index, list]) [,initialValue, delimiter,
includeEmptyFields])

History

ColdFusion 11: Added this function.
Attributes

Attribute

Req/Opt

Default

Description

list

Required

The input list.

function

Required

Closure or a function
reference that will be
called for each of the
iteration. The arguments
passed to the callback are
item: value
index : current index for
the iteration
list : reference of the
original list

initialValue

Optional

Initial value which will be
used for the reduce
operation. The type is
any.

delimter

Optional

comma (,)

The list delimiter The type
is string..

includeEmptyFields

Optional

false

Include empty values. The
type is boolean.

Example

© 2014 Adobe Systems Incorporated. All rights reserved.

2093

Adobe ColdFusion Documentation



list = "red, blue, green, yellow";
ucaseList = listMap(list, function(item)
{
return ucase(item);
});

writeDump(ucaseList);
writeOutput("
");

concatValues = listReduce(list, function(result, item, index, mylist, delimiter)
{
result = result?:"";
if(index == 1)
delimiter = "";
result&= delimiter & item;
return result;
});
writeDump(concatValues);


© 2014 Adobe Systems Incorporated. All rights reserved.

2094

Adobe ColdFusion Documentation

ListMap
Description
Iterates over every entry of the List and calls the closure function to work on the item of the list. The returned value
will be set at the same index in a new list and the new list will be returned.
Returns

List
Syntax

ListMap(list, function(item [,index, list]) [,delimiter, includeEmptyFields)

History

ColdFusion 11: Added this function.
Attributes

Attribute

Req/Opt

Default

Description

list

Required

The input list.

function

Required

Closure or a function
reference that will be
called for each of the
iteration. The arguments
passed to the callback are
item: value
index : current index for
the iteration
list : reference of the
original list

initialValue

Optional

delimter

Optional

comma (,)

The list delimiter The type
is string..

includeEmptyFields

Optional

false

Include empty values. The
type is boolean.

© 2014 Adobe Systems Incorporated. All rights reserved.

Initial value which will be
used for the reduce
operation. The type is
any.

2095

Adobe ColdFusion Documentation

Functions m-r
Max
Mid
Min
Minute
Month
MonthAsString
Now
NumberFormat
ObjectEquals
ObjectLoad
ObjectSave
OnWSAuthenticate
ORMClearSession
ORMCloseAllSessions
ORMCloseSession
ORMEvictCollection
ORMEvictEntity
ORMEvictQueries
ORMExecuteQuery
ORMFlush
ORMFlushall
ORMGetSession
ORMGetSessionFactory
ORMIndex
ORMIndexPurge
ORMReload
ORMSearch
ORMSearchOffline
ParagraphFormat
ParameterExists
ParseDateTime
Pi
PrecisionEvaluate
Quarter
PreserveSingleQuotes
QueryAddColumn
QueryAddRow
QueryNew
QueryConvertForGrid
QuerySetCell
QuotedValueList
Rand
Randomize
RandRange
ReEscape
REFind
REFindNoCase
REMatch
REMatchNoCase
ReleaseComObject
RemoveCachedQuery

© 2014 Adobe Systems Incorporated. All rights reserved.

2096

Adobe ColdFusion Documentation

RemoveChars
RepeatString
Replace
ReplaceList
ReplaceNoCase
REReplace
REReplaceNoCase
RestDeleteApplication
RestSetResponse
RestInitApplication
Reverse
Right
RJustify
Round
RTrim
QueryGetRow
QueryExecute

© 2014 Adobe Systems Incorporated. All rights reserved.

2097

Adobe ColdFusion Documentation

Max
Description

Determines the greater of two numbers.
Returns

The greater of two numbers.
Category

Mathematical functions
Function syntax

Max(number1, number2)

See also

Min
Parameters

Parameter

Description

number1, number2

Numbers

Example


#max(17,19)# 





© 2014 Adobe Systems Incorporated. All rights reserved.

2098

Adobe ColdFusion Documentation

Mid
Description

Extracts a substring from a string.
Returns

A string; the set of characters from string, beginning at start, of length count.
Category

String functions
Function syntax

Mid(string, start, count)

See also

Left, Len, Right
Parameters

Parameter

Description

string

A string or a variable that contains one. Must be
single-quotation mark or double-quotation mark
delimited.

start

A positive integer or a variable that contains one.
Position at which to start count. Positions start with 1,
not 0.

count

A positive integer or a variable that contains one.
Number of characters to return. (Zero is not valid, but it
does not throw an error.)

Example

© 2014 Adobe Systems Incorporated. All rights reserved.

2099

Adobe ColdFusion Documentation

Mid Example




Your string
#Form.myText# only has #Len(Form.myText)# characters. You cannot output
the #Form.removeChars# middle characters of this string because it is
not long enough.

Your string
#Form.myText# only has #Len(Form.myText)# characters. You cannot start
at position #Form.startPos#.

Your original string: #Form.myText#
Your changed string, showing only the #Form.removeChars#
 middle characters: #Mid(Form.myText,
Form.startPos, Form.removeChars)#


Please enter a string of more
than 0 (zero) characters.



Type in some text


Enter a starting position (from the beginning of the entered text)


How many characters do you want to show?

1
3
5
7
9



© 2014 Adobe Systems Incorporated. All rights reserved.

2100

Adobe ColdFusion Documentation

Min
Description

Determines the lesser of two numbers.
Returns

The lesser of two numbers.
Category

Mathematical functions
Function syntax

Min(number1, number2)

See also

Max
Parameters

Parameter

Description

number1, number2

Numbers

Example

Min Example


The maximum of the two numbers is #Max(FORM.myNum1,
FORM.myNum2)#
The minimum of the two numbers is #Min(FORM.myNum1,
FORM.myNum2)#

Please enter two numbers



Enter two numbers, and see the maximum and minimum of the two numbers
Number 1 

Number 2 




© 2014 Adobe Systems Incorporated. All rights reserved.

2101

Adobe ColdFusion Documentation

Minute
Description

Extracts the minute value from a date/time object.
Returns

The ordinal value of the minute, in the range 0-59.
Category

Date and time functions
Function syntax

Minute(date)

See also

DatePart, Hash, Second
Parameters

Parameter

Description

date

A date/time object, in the range 100 AD-9999 AD.

Usage

When passing a date/time value as a string, enclose it in quotation marks. Otherwise, it is interpreted as a number
representation of a date/time object.
Example

Minute Example

The time is currently #TimeFormat(Now())#.
We are in hour #Hour(Now())#, Minute #Minute(Now())#
and Second #Second(Now())# of the day.


© 2014 Adobe Systems Incorporated. All rights reserved.

2102

Adobe ColdFusion Documentation

Month
Description

Extracts the month value from a date/time object.
Returns

The ordinal value of the month, in the range 1 (January) - 12 (December).
Category

Date and time functions
Function syntax

Month(date)

See also

DatePart, MonthAsString, Quarter
Parameters

Parameter

Description

date

Date/time object, in the range 100 AD-9999 AD.

Usage

When passing a date/time value as a string, enclose it in quotation marks. Otherwise, it is interpreted as a number
representation of a date/time object.
Note
You can pass the CreateDate function or the Now function as the date parameter of this
function; for example: #Month(CreateDate(2001, 3, 3))#.

Example

© 2014 Adobe Systems Incorporated. All rights reserved.

2103

Adobe ColdFusion Documentation

Month Example

More information about your date:


Your date, #DateFormat(yourDate)#.

It is #DayofWeekAsString(DayOfWeek(yourDate))#, day
#DayOfWeek(yourDate)# in the week.

This is day #Day(yourDate)# in the month of
#MonthAsString(Month(yourDate))#, which has
#DaysInMonth(yourDate)# days.

We are in week #Week(yourDate)# of #Year(yourDate)#
(day #DayofYear(yourDate)# of #DaysinYear(yourDate)#). 

This is a leap year
This is not a leap year




© 2014 Adobe Systems Incorporated. All rights reserved.

2104

Adobe ColdFusion Documentation

MonthAsString
Description

Determines the name of the month that corresponds to month_number.
Returns

A string; the name of the specified month, in the current locale.
Category

Date and time functions, String functions
Function syntax

MonthAsString(month_number [, locale])

See also

DatePart, Month, Quarter
History

ColdFusion 8: Added the locale parameter.
Parameters

Parameter

Description

month_number

An integer in the range 1 - 12.

locale

Locale to use instead of the locale of the page when
processing the function

Example

© 2014 Adobe Systems Incorporated. All rights reserved.

2105

Adobe ColdFusion Documentation

MonthAsString Example

More information about your date:


Your date, #DateFormat(yourDate)#.

It is #DayofWeekAsString(DayOfWeek(yourDate))#, day
#DayOfWeek(yourDate)# in the week.

This is day #Day(YourDate)# in the month of
#MonthAsString(Month(yourDate))#, which has
#DaysInMonth(yourDate)# days.

We are in week #Week(yourDate)# of #Year(yourDate)#
(day #DayofYear(yourDate)# of #DaysinYear(yourDate)#). 

This is a leap year
This is not a leap year




© 2014 Adobe Systems Incorporated. All rights reserved.

2106

Adobe ColdFusion Documentation

Now
Description

Gets the current date and time of the computer running the ColdFusion server. The return value can be passed as a
parameter to date functions such as DaysInYear or FirstDayOfMonth.
Returns

A date/time object; the current date and time of the computer running the ColdFusion server.
Category

Date and time functions
Function syntax

Now()

See also

CreateDateTime, DatePart
Example

Now Example
Now returns the current date and time as a valid date/time object.
The current date/time value is #Now()#
You can also represent this as #DateFormat(Now())#,
#TimeFormat(Now())#

© 2014 Adobe Systems Incorporated. All rights reserved.

2107

Adobe ColdFusion Documentation

NumberFormat
Description

Creates a custom-formatted number value. Supports the numeric formatting used in the U.S. For international
number formatting, see LSNumberFormat.
Returns

A formatted number value:
If no mask is specified, returns the value as an integer with a thousands separator.
If the parameter value is "" (an empty string), returns 0.
Category

Display and formatting functions
Function syntax

NumberFormat(number [, mask ])

See also

DecimalFormat, DollarFormat, IsNumeric, LSNumberFormat
History

ColdFusion MX: Changed behavior: if the mask format cannot correctly mask a number, this function returns the
number unchanged. (It does not truncate the number nor throw an error.) (If no mask is selected, ColdFusion MX
rounds the decimal part as ColdFusion 5 does. For example, it rounds 34.567 to 35.)
Parameters

Parameter

Description

number

A number.

mask

A string or a variable that contains one. Set of
characters that determine how ColdFusion displays the
number

The following table explains mask characters:
Mask character

Meaning

_ (underscore)

Optional. Digit placeholder.

9

Optional. Digit placeholder. (Shows decimal places
more clearly than _.). Note that when ‘9’ or ‘_’ is used
after the decimal place, 0 will be padded, if required.

© 2014 Adobe Systems Incorporated. All rights reserved.

2108

Adobe ColdFusion Documentation

.

Location of a mandatory decimal point.

0

Located to the left or right of a mandatory decimal
point. Pads with zeros.

()

If number is less than zero, puts parentheses around
the mask.

+

Puts plus sign before positive number; minus sign
before negative number.

-

Puts a space before positive number; minus sign
before negative number.

,

Separates every third decimal place with a comma.

L,C

Left-justifies or center-justifies number within width of
mask column. First character of mask must be L or C.
The default value is right-justified.

$

Puts a dollar sign before formatted number. First
character of mask must be the dollar sign ($).

^

Separates left and right formatting.

Note
If you do not specify a sign for the mask, positive and negative numbers do not align in columns.
To put a plus sign or space before positive numbers and a minus sign before negative numbers,
use the plus or minus sign, respectively.

Usage

This function uses Java standard locale formatting rules on all platforms. The position of symbols in format masks
determines where the codes take effect. For example, if you put a dollar sign at the far left of a format mask,
ColdFusion displays a dollar sign at the left edge of the formatted number. If you separate the dollar sign on the left
edge of the format mask by at least one underscore, ColdFusion displays the dollar sign just to the left of the digits
in the formatted number. These examples show how symbols determine formats:
Number

Mask

Result

4.37

$___._

"$ 4.37"

4.37

$_._

" $4.37"

The positioning can also show where to place the minus sign for negative numbers:
Number

Mask

© 2014 Adobe Systems Incorporated. All rights reserved.

Result

2109

Adobe ColdFusion Documentation

-4.37

-___._

"- 4.37"

-4.37

-_._

" -4.37"

The positions for a symbol are: far left, near left, near right, and far right. The left and right positions are determined
by the side of the decimal point on which the code character is shown. For formats that do not have a fixed number
of decimal places, you can use a caret (^) to separate the left fields from the right.An underscore determines
whether the code is placed in the far or near position. Most code characters' effect is determined by the field in
which they are located. This example shows how to specify where to put parentheses to display negative numbers:
Number

Mask

Result

3.21

C(_^_)

"( 3.21 )"

3.21

C_(^_)

" (3.21 )"

3.21

C(_^)_

"( 3.21) "

3.21

C_(^)_

" (3.21) "

When converting from string to double, to prevent rounding errors, this function adds a rounding factor of
1.5543122344752E-014 to the converted number. For example, without adding the rounding factor, converting the
string value 1.275 to double with two digits of precision results in a value of 1.27499999999999999, which would be
rounded up to 1.27. By adding the rounding factor, the conversion correctly results in a value of 1.28. If you round off
a double such as 1.99499999999999999999999999999, where the last decimal is 10E-14, the rounding factor can
cause an incorrect result. To set the default display format of date, time, number, and currency values, use the SetL
ocale function.
Example

NumberFormat Example




#counter# * Square Root of 2: #NumberFormat(CounterRoot2,
_____.__)#
#counter# * Square Root of 2: #NumberFormat(CounterRoot2)#



© 2014 Adobe Systems Incorporated. All rights reserved.

2110

Adobe ColdFusion Documentation

ObjectEquals
Description

Identifies any conflict between CFC instances on the client and the server.
Returns
Category

Other functions
Function Syntax

objectEquals( Param1 ,Param2)

See Also

Conflict management in Developing ColdFusion Applications.
Parameters

Parameter

Description

param 1

New instance of the CFC on the client.

param 2

Original instance of the CFC.

Example




















© 2014 Adobe Systems Incorporated. All rights reserved.

2111

Adobe ColdFusion Documentation

ObjectLoad
Description

Loads a serialized ColdFusion array, CFC, DateTime object, Java object, query, or structure into memory as the
corresponding object.
Returns

The deserialized ColdFusion object, such as a CFC or a query object.
Category

Other functions
Function syntax

ObjectLoad(binaryObject)
ObjectLoad(filepath)

See also

ObjectSave
Parameters

Parameter

Description

binaryObject

A binary object returned by ObjectSave function.

filepath

A string specifying the path to a file containing a
serialized complexobject, such as a query or CFC, or a
variable that is a serializable binary representation of a
complex object.This parameter must be the name of a
file or an object returned by the SaveCFObject functio
n.

Usage

This function is useful for handling dynamic data that has a relatively long period of usefulness and takes substantial
time or resources to obtain. It lets you save the data in a file and use it in multiple application instances. For
example, you can create a CFC that stores a query that takes long time to run and retrieves infrequently updated
data. If you use the ObjectSave function to initially save the CFC as a file, you can then deserialize the CFC file on
future application starts and improve application performance.
Example

© 2014 Adobe Systems Incorporated. All rights reserved.

2112

Adobe ColdFusion Documentation

Loading and saving an object.










Time Display Page

Server's Local Time: #localTime#

Calculated UTC Time: #UTCTime#


© 2014 Adobe Systems Incorporated. All rights reserved.

2113

Adobe ColdFusion Documentation

ObjectSave
Description

Converts a ColdFusion array, CFC, DateTime object, Java object, query, or structure into a serializable binary object
and optionally saves the object in a file.
Returns

A serializable binary representation of the object.
Category

Other functions
Function syntax

ObjectSave(object[, filePath])

See also

ObjectLoad
Parameters

Parameter

Description

object

The complex object, such as a query or CFC, that will
be serialized.

filePath

The path of the file in which to save the serialized data.

Usage

This function is useful for handling dynamic data that has a relatively long period of usefulness and takes substantial
time or resources to obtain. It lets you save the data in a file and use it in multiple application instances. For
example, you can create a CFC that stores a query that takes long time to run and retrieves infrequently updated
data. If you use the ObjectSave function to initially save the CFC as a file, and deserialize the CFC file on future
application starts, you can improve application performance.
Example

© 2014 Adobe Systems Incorporated. All rights reserved.

2114

Adobe ColdFusion Documentation

Saving and loading an object










Time Display Page

Server's Local Time: #localTime#

Calculated UTC Time: #UTCTime#


© 2014 Adobe Systems Incorporated. All rights reserved.

2115

Adobe ColdFusion Documentation

OnWSAuthenticate
Description

Authenticates the user
History

ColdFusion 10: Added this function
Syntax

OnWSAuthenticate(username, password, connectionInfo)
Parameters

Parameter

Description

username

Name of the user that has to be
authenticated.

password

Password for the user.

connectionInfo

A struct that contains the following
keys:
Authenticated: {{YES

NO}}
ConnectionTime: Connection
time stamp.
clientID: Unique ID of the
client.
Custom keys are also supported.
For example, you can specify the
user's role, status, or age.The co
nnectionInfo is shared across
all the channels for a given
WebSocket client. Also,
modifications are persisted
across all the subscriptions for
that client.

Example

The following example uses the function onWSAuthenticate, validates the user, and associates a user role.
Note
For this example to work, ensure that you implement the user-defined functions.

© 2014 Adobe Systems Incorporated. All rights reserved.

2116

Adobe ColdFusion Documentation

component
{
this.name="websocketsampleapp23";
this.wschannels=[{name="stocks",cfclistener="stocksListener"}];
function
{

onWSAuthenticate(username, password, connectionInfo)
//write appropriate logic to fetch user password in funtion checkPassword

If(checkPassword(username) eq password)
{
connectionInfo.authenticated="YES";
//Role is the custom information that you provide
connectionInfo.role= "admin";
return true;
}
else{
connectionInfo.authenticated="NO";
return false;
}
writedump("#connectionInfo#","console");
}
}

© 2014 Adobe Systems Incorporated. All rights reserved.

2117

Adobe ColdFusion Documentation

ORMClearSession
ORMClearSession removes all the entities that are loaded or created in the session. This clears the first level cache
and removes the objects that are not yet saved to the database.

© 2014 Adobe Systems Incorporated. All rights reserved.

2118

Adobe ColdFusion Documentation

ORMCloseAllSessions
Description

Closes all Hibernate sessions in the request.
Function Syntax

ormcloseallsessions()
See Also

ORMGetSession, ORMClearSession, ORMFlush, ORMGetSessionFactory, ORMCloseSession in Developing
ColdFusion Applications.

© 2014 Adobe Systems Incorporated. All rights reserved.

2119

Adobe ColdFusion Documentation

ORMCloseSession
Description

Closes the Hibernate session associated with the data source in the request. If you do not specify a data source, the
Hibernate session associated with the default data source is closed.
Category

ORM functions
Function Syntax

ormclosesession(datasource)
See Also

ORMGetSession, ORMClearSession, ORMFlush, ORMGetSessionFactory, ORMCloseSession in Developing
ColdFusion Applications.

© 2014 Adobe Systems Incorporated. All rights reserved.

2120

Adobe ColdFusion Documentation

ORMEvictCollection
Description

This method is used to evict all the collection or association data for the given entity name and collection name, from
the secondary cache. If the primary key is specified, then, the collection or association data of the entity with the
primary key is evicted.
Category

ORM functions
See Also

ORMEvictEntity, ORMEvictQueries, Evict content from secondary cache in Caching in the Developing ColdFusion
Applications
Function Syntax

ormevictcollection("", "", [primarykey])

Parameters

Parameter

Description

entity name

Entity name of the persistent CFC.

collection name

Name of the collection in the component

primary key

Primary key of the collection or association data of the
entity

Example

To evict all the association or collection data of collection arts belonging to the component CArtists:



© 2014 Adobe Systems Incorporated. All rights reserved.

2121

Adobe ColdFusion Documentation

ORMEvictEntity
Description

This method is used to evict items for the given entity name, from the secondary cache. If the primary key is
specified, then the data of the entity with that primary key is evicted. Primary key should be a value in case of simple
primary key or should be a struct in case of composite primary key.
Category

ORM functions
See Also

ORMEvictCollection, ORMEvictQueries, Evict content from secondary cache in Caching in the Developing
ColdFusion Applications
Function Syntax

ORMEvictEntity("", [primarykey])

Parameters

Parameter

Description

component name

Entity name of the persistent CFC

primary key

Primary key value of the component

Example

To evict all the cache data of CArtist entity:



To evict the cache data of CArtists entity whose primary key is 1:



© 2014 Adobe Systems Incorporated. All rights reserved.

2122

Adobe ColdFusion Documentation

ORMEvictQueries
Description

This method is used to evict the data of all the queries from the default query cache of the specified data source. If
cache name is specified, then the data of all queries belonging to the cache region with the given cache name are
evicted.If no data source is specified, the default query cache of the default data source is evicted.
Category

ORM functions
See Also

ORMEvictEntity, ORMEvictCollection, Evict content from secondary cache in Caching in the Developing ColdFusion
Applications
Syntax

ORMEvictQueries(cachename) ORMEvictQueries(cachename, datasource)
Parameters

Parameter

Description

cachename

Name of the cache region that you want to evict.

datasource

Name of the data source whose cache you want to
evict. If you do not specify the cache, the default query
cache is evicted.

Example

Evicts the data of all the queries from the default query cache.



Evicts the data of all the queries from the cache region with the name availableArtsCache.



© 2014 Adobe Systems Incorporated. All rights reserved.

2123

Adobe ColdFusion Documentation

ORMExecuteQuery
Description
Executes a Hibernate Query Language (HQL) query.By default, this function works on ORM's default data source.
To use this function for another data source, specify the data source key-value pair within the queryoptions.
Syntax

ORMExecuteQuery(hql, params [,unique])
ORMExecuteQuery(hql, [,unique] [, queryoptions])
ORMExecuteQuery(hql, params [,unique] [,queryOptions])
Parameters

Parameter

Description

Hql

The HQL query that has to be executed.

Params

Object parameter for the entity.

Unique

Specifies if the object parameter is unique.

Queryoptions

Key-value pair of options for the query.
You can specify several options to control the behavior
of retrieval using queryOptions:
ignorecase: Ignores the case of sort order
when you set it to true. Use this option only
when you specify the sortorder parameter.
maxResults: Specifies the maximum number
of objects to be retrieved.
offset: Specifies the start index of the resultset
from where it has to start the retrieval.
cacheable: Whether the result of this query is
to be cached in the secondary cache. Default is
false.
cachename: Name of the cache in secondary
cache.
timeout: Specifies the timeout value (in
seconds) for the query
Note: Maxresults and timeout are used for pagination.

Example

© 2014 Adobe Systems Incorporated. All rights reserved.

2124

Adobe ColdFusion Documentation

ORMExecuteQuery("from cemployees where EmployeeID=2");
ORMExecuteQuery("from cemployees where EmployeeID IN (?, ?, ?)", [1, 3, 5]);
ORMExecuteQuery("select count(*) from cemployees", [], false);
ORMExecuteQuery("from Artists where artistid=1", true, {datasource="cfartgallery"});
ORMExecuteQuery("select count(*) from Authors", [], false,
{datasource="cfbookclub"});

© 2014 Adobe Systems Incorporated. All rights reserved.

2125

Adobe ColdFusion Documentation

ORMFlush
Flushes the current ORM session associated with the data source specified in the application. ORMFlush flushes all
the pending CRUD operations in that request.

© 2014 Adobe Systems Incorporated. All rights reserved.

2126

Adobe ColdFusion Documentation

ORMFlushall
Description

Flushes all the current Hibernate sessions in the request.
Function syntax

ormflushall()
See Also

ORMCloseSession, ORMClearSession, ORMGetSession, ORMGetSessionFactory, ORMFlush in Developing
ColdFusion Applications.

© 2014 Adobe Systems Incorporated. All rights reserved.

2127

Adobe ColdFusion Documentation

ORMGetSession
Returns the current ORM session. That is, the Hibernate Session associated with the data source specified in the
application. This returns the underlying Hibernate Session that can be used to call the API, which otherwise is not
exposed by ColdFusion.

© 2014 Adobe Systems Incorporated. All rights reserved.

2128

Adobe ColdFusion Documentation

ORMGetSessionFactory
ORMGetSessionFactory returns the underlying Hibernate SessionFactory object.

#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

2129

Adobe ColdFusion Documentation

ORMIndex
Description

Performs offline indexing.
History

ColdFusion 10: Added this function
Syntax

ORMIndex(_);ORMIndex("_entity_name");ORMIndex("entityName_list");ORMIndex (entityObje
ct__);
Parameters

Parameter

Description

entityName

Name of the entity that has to be indexed.

entityName_list

Comma-separated list of entity names for indexing.

entityObject

Variable name of a specific entity instance for indexing.

Usage

If you use this function without specifying any parameters, all persistent entities of a given application are indexed.
Example

EmpObjs = EntityLoad("Employee",{lastname="Bond"});
for(EmpObj in EmpObjs)
{
ormindex(EmpObj);
}

© 2014 Adobe Systems Incorporated. All rights reserved.

2130

Adobe ColdFusion Documentation

ORMIndexPurge
Description

Clears all indexed data for all entities or specified entities in the current application scope.
History

ColdFusion 10: Added this function
Syntax

ORMIndexPurge();ORMIndexPurge("entityName");ORMIndexPurge("entityName_list");
Parameters

Parameter

Description

entityName

Name of the entity to be loaded.

entityName_list

Comma-separated list of entity names for purging.

Usage

If you use this function without specifying entityName, all persistent entities of the application are purged.
Example

ORMIndexPurge();

ORMIndexPurge("Employee");

© 2014 Adobe Systems Incorporated. All rights reserved.

2131

Adobe ColdFusion Documentation

ORMReload
Description

Reinitializes ORM for the application.If you make any change to the persistent metadata of the CFCs, then you
might want to reload the ORM.
Returns

Returns ORM session factory instance.
Category

ORM functions
Function Syntax

ORMReload()

Usage

Adobe recommends that you use this function only during the time of development.
See Also

ColdFusion ORM
Example

component
{
this.name = Hash( GetCurrentTemplatePath() );
/* define the application wide datasource */
this.datasource = "cfartgallery";
/* enable hibernate support for this application */
this.ormenabled = true;
/* create a struct of ORM settings */
this.ormsettings = {};
/* turn on event handling */
this.ormsettings.eventhandling = true;
/**
* @output true
*/
public boolean function onRequestStart( targetPage )
{
/* this is to ensure that ORM is up-to-date for demo */
ORMReload();
return true;
}
}

© 2014 Adobe Systems Incorporated. All rights reserved.

2132

Adobe ColdFusion Documentation

ORMSearch
Description

Searches for given text in specific properties or entities.
Returns

A struct that contains the following:
An array of structs (with the entity and scorebeing the keys) in the following format:

data -[{entity: entity1, score: entity1_score}, {entity: entity2, score:
entity2_score}, ..... ]

maxTotalRecord (number of possible results)
History

ColdFusion 10: Added this function
Syntax

ORMSearch("query_text", "entityName")ORMSearch("query_text", "entityName", fields)ORM
Search("query_text", "entityName", fields, optionMap)
Parameters

Parameter

Description

query_text

The text to be searched for or a complete Lucene
query.In the case of ORMSearch("query_text",
"entityName"), only Lucene query is supported.For
details of Lucene query, see http://lucene.apache.org/c
ore/old_versioned_docs/versions/3_0_0/queryparsersy
ntax.html

entityName

Name of the entity to be searched.

fields

Fields in which search has to be performed. This can
be an array of strings.If you are performing a Lucene
query, you need not specify this field. In other words, if
you do not specify this value, a Lucene query is
performed.Field name is case-sensitive.

© 2014 Adobe Systems Incorporated. All rights reserved.

2133

Adobe ColdFusion Documentation

optionMap

Extra options that can be passed while executing
Lucene query.The options are:
sort: Sorts based on indexfieldname you
specified.
offSet: Specifies the position from which to
retrieve the objects.
maxResults: Specifies the maximum number of
objects to be retrieved.

Usage

When you perform a date search, use the format yyyymmdd as shown in the following example:

objs = ORMSearch("datecheck:[#dateformat(dateadd("d",5,now()),"yyyymmdd")# TO
#dateformat(dateadd("d",35,now()),"yyyymmdd")#]","C2",[],{maxresults=2});

If you are performing a time search, use the UTC format.
Example 1: ORM search based on Lucene query

ORMSearch("FirstName:ch*","Employee");
ORMSearch("ch*","Employee",["FirstName"]);
objs =
ORMSearch('FirstName:ch*',"Employee",[],{sort="salary",maxresults=5,offset=2});

Example 2: ORM search on multiple entities

ORMSearch("john*","DeveloperEntity,UserEntity",["firstname"]);

In this example, first name is searched in the DeveloperEntity and UserEntity and a composite array of
entities are returned.
Example 3: ORM search on all subentities based on Lucene query

This example shows how to perform ORM search on all subentities that inherit a super entity. Assume that USEmplo
yeeEntity and UKEmpoyeeEntity are extending EmployeeEntity. You can search both the subentities using
the following code:

ORMSearch("john*","EmployeeEntity",["FirstName"]);

Example 4: ORM search in relationships

In this example, products and categories have a many-to-one relationship. You can search all products of a specific
category using the following code:

© 2014 Adobe Systems Incorporated. All rights reserved.

2134

Adobe ColdFusion Documentation

ORMSearch("CategoryID.CategoryName:In*","cproducts",[]);

Note that search in related objects works only for many-to-one relationship and one-to-one relationship.

© 2014 Adobe Systems Incorporated. All rights reserved.

2135

Adobe ColdFusion Documentation

ORMSearchOffline
Description

Performs search on the indexed properties but returns only the stored fields.For this function to work, specify index
Store=true on the properties on which you want to perform the search.
History

ColdFusion 10: Added this function
Returns

A struct that contains the following:
An array of structs (with the entity and scorebeing the keys) in the following format:

data -[{entity: entity1, score: entity1_score}, {entity: entity2, score:
entity2_score}, ..... ]

maxTotalRecord (number of possible results)
fields_to_be_selected as keys.
Syntax

ORMSearchOffline(query_text, entityName, fields_to_be_selected);ORMSearchOffline(quer
y_text, entityName, fields_to_be_selected, fields);ORMSearchOffline(query_text,
entityName, fields_to_be_selected, fields, optionMap);
Parameters

Parameter

Description

query_text

The text to be searched for or a complete Lucene
query.For details of Lucene query, see http://lucene.ap
ache.org/core/old_versioned_docs/versions/.

entityName

Name of the entity to be searched.

fieldss_to_be_selected

Fields to be returned as keys in the resultant struct.

fields

Fields in which search has to be performed.

optionMap

© 2014 Adobe Systems Incorporated. All rights reserved.

2136

Adobe ColdFusion Documentation

Extra options that can be passed while executing
Lucene query. The options can be:
sort: Sorts based on indexfieldname you
specified.
offSet: Specifies the position from which to
retrieve the objects.
maxResults: Specifies the maximum number of
objects to be retrieved.

Example 1

ORMSearchOffline('FirstName:"ch*"',"Employee",["id","firstname"]);

Example 2

In the following example, offline search is performed on the property FirstName and first name and last name are
returned as keys in the resultant struct.

ORMSearchOffline("ch*","Employee",["FirstName","LastName"],["FirstName"],{sort="sala
ry",maxresults=5,offset=2});

Example 3

In this example, the resultObj in the query is an array of structs. The individual structs contain all the selected
fields (passed as third parameter).



© 2014 Adobe Systems Incorporated. All rights reserved.

2137

Adobe ColdFusion Documentation

ParagraphFormat
Description

Replaces characters in a string:
Single newline characters (CR/LF sequences) with spaces
Double newline characters with HTML paragraph tags (
)
Returns

A copy of the string, with characters converted.
Category

Display and formatting functions, String functions
Function syntax

ParagraphFormat(string)

See also

StripCR
Parameters

Parameter

Description

string

A string or a variable that contains one

Usage

This function is useful for displaying data entered in textarea fields.
Example

© 2014 Adobe Systems Incorporated. All rights reserved.

2138

Adobe ColdFusion Documentation

ParagraphFormat Example
Enter text into this textarea, and see it returned as HTML.

Your text area, formatted
#ParagraphFormat(FORM.myTextArea)#



This is sample text and you see how it scrolls
<cfoutput>#Chr(10)##Chr(13)#</cfoutput>
From one line
<cfoutput>#Chr(10)##Chr(13)##Chr(10)##Chr(13)#</cfoutput>
to the next




© 2014 Adobe Systems Incorporated. All rights reserved.

2139

Adobe ColdFusion Documentation

ParameterExists
Deprecated
THIS FUNCTION HAS BEEN DEPRECATED
Description

This function is deprecated. Use the IsDefined function.Determines whether a parameter exists. ColdFusion does
not evaluate the argument.
History

ColdFusion MX: Deprecated this function. It might not work, and might cause an error, in later releases.

© 2014 Adobe Systems Incorporated. All rights reserved.

2140

Adobe ColdFusion Documentation

ParseDateTime
Description

Parses a date/time string according to the English (U.S.) locale conventions. (To format a date/time string for other
locales, use the LSParseDateTime function.)
Returns

A date/time object
Category

Date and time functions, Display and formatting functions
Function syntax

ParseDateTime(date/time-string [, pop-conversion ])

See also

IsDate, IsNumericDate, SetLocale
Parameters

Parameter

Description

date/time string

A string containing a date/time value formatted
according to U.S. locale conventions. Can represent a
date/time in the range 100 AD-9999 AD. Years 0-29
are interpreted as 2000-2029; years 30-99 are
interpreted as 1930-1999.

© 2014 Adobe Systems Incorporated. All rights reserved.

2141

Adobe ColdFusion Documentation

pop-conversion

pop: specifies that the date/time string is in POP
format, which includes the local time of the sender
and a time-zone offset from UTC. ColdFusion applies
the offset and returns a value with the UTC time.
standard: (the default) function does no conversion.
Apart from these 2 values, this parameter allows you to
specify the format in which to parse the given string.
Valid letters that can be used to specify the format are
described here http://docs.oracle.com/javase/7/docs/ap
i/java/text/SimpleDateFormat.html
For instance:




Another example:




Usage

This function is similar to CreateDateTime, but it takes a string instead of enumerated date/time values. These
functions are provided primarily to increase the readability of code in compound expressions.To calculate a
difference between time zones, use the GetTimeZoneInfo function. To set the default display format of date, time,
number, and currency values, use the SetLocale function.
Example

© 2014 Adobe Systems Incorporated. All rights reserved.

2142

Adobe ColdFusion Documentation

ParseDateTime Example


The expression #DE(form.theTestValue)# is a valid
date
The parsed date/time is:
#ParseDateTime(form.theTestValue)#

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



Enter an expression, and discover if it can be evaluated to a date value.




© 2014 Adobe Systems Incorporated. All rights reserved.

2143

Adobe ColdFusion Documentation

Pi
Description

Gets the mathematical constant p, accurate to 15 digits.
Returns

The number 3.14159265358979.
Category

Mathematical functions
Function syntax

Pi()

See also

ASin, Cos, Sin, Tan
Example

Pi Example

The Pi function Returns the number

#NumberFormat(Pi(), "_._______________")#,
 the mathematical constant pi, accurate to 15 digits.

© 2014 Adobe Systems Incorporated. All rights reserved.

2144

Adobe ColdFusion Documentation

PrecisionEvaluate
Description

Evaluates one or more string expressions, dynamically, from left to right, using BigDecimal precision arithmetic to
calculate the values of arbitrary precision arithmetic expressions.
Returns

An object; the result of the evaluations.
Category

Mathematical functions, Dynamic evaluation functions
Function syntax

PrecisionEvaluate(string_expression1 [, string_expression2 , ... ])

See also

Evaluate, Using Expressions and Number Signs in the Developing ColdFusion Applications
Parameters

Parameter

Description

string_expression1, string_expression2...

Expressions to evaluate

Usage

The PrecisionEvaluate function lets you calculate arbitrarily long decimal (BigDecimal precision) values.
BigDecimal precision arithmetic accepts and generates decimal numbers of any length, and does not use
exponential notation. The PrecisionEvaluate function calculates arbitrary precision results only for addition,
subtraction, multiplication, and division. If you use any of the following operations, ColdFusion performs normal
integer or floating point arithmetic and does not return BigDecimal values.
exponentiation (^)
modulus (MOD or %)
integer division
This function differs from the Evaluatefunction only in its use of BigDecimal precision arithmetic to calculate
numeric values; otherwise the two functions are identical. The results of an evaluation on the left can have
meaning in an expression to the right, and the function returns the result of evaluating the rightmost
expression. If a string expression contains a single- or double-quotation mark, the mark must be escaped.If
an expression, such as 1/3, results in an infinitely repeating decimal value, ColdFusion limits the decimal part
to 20 digits.

© 2014 Adobe Systems Incorporated. All rights reserved.

2145

Adobe ColdFusion Documentation

Note
To increase processing efficiency, do not put the arithmetic expressions to evaluate in
quotation marks ("). ColdFusion compiles PrecisionEvaluate(a*b) more efficiently
than it compiles PrecisionEvaluate("a*b"), although both formats produce the
same results.

Example

PrecisionEvaluate Example





The value of the expression #FORM.MyExpression#
is #theExpression#.



Could not evaluate the expression #Form.myExpression#.





Enter a ColdFusion expression for evaluation.
Try using some really big decimal numbers.







© 2014 Adobe Systems Incorporated. All rights reserved.

2146

Adobe ColdFusion Documentation

Quarter
Description

Calculates the quarter of the year in which a date falls.
Returns

An integer, 1-4.
Category

Date and time functions
Function syntax

Quarter(date)

See also

DatePart, Month
Parameters

Parameter

Description

date

A date/time object in the range 100 AD-9999 AD.

Usage

When passing a date/time value as a string, enclose it in quotation marks. Otherwise, it is interpreted as a number
representation of a date/time object.
Example

Quarter Example
Today, #DateFormat(Now())#,
is in Quarter #Quarter(Now())#.

© 2014 Adobe Systems Incorporated. All rights reserved.

2147

Adobe ColdFusion Documentation

PreserveSingleQuotes
Description

Prevents ColdFusion from automatically escaping single-quotation mark characters that are contained in a variable.
ColdFusion does not evaluate the argument.
Returns

(None)
Category

Other functions
Function syntax

PreserveSingleQuotes(variable)

History

ColdFusion MX: Changed behavior: ColdFusion automatically escapes simple-variable, array-variable, and
structure-variable references within a cfquery tag body or block. (Earlier releases did not automatically escape
array-variable references.)
Parameters

Parameter

Description

variable

Variable that contains a string in which to preserve
single-quotation marks.

Usage

This function is useful in SQL statements to defer evaluation of a variable reference until runtime. This prevents
errors that result from the evaluation of a single-quote or apostrophe data character (for example, "Joe's Diner") as a
delimiter. Example A: Consider this code:


PreserveSingleQuotes(#mystring#) is

#PreserveSingleQuotes(mystring)#


The output is as follows:

PreserveSingleQuotes(#mystring#) is 'Newton's Law', 'Fermat's Theorem'

© 2014 Adobe Systems Incorporated. All rights reserved.

2148

Adobe ColdFusion Documentation

Example B: Consider this code:




ColdFusion escapes the single-quote characters in the list as follows:

""1"", ""2"", ""3""

The cfquery tag throws an error.You code this function correctly as follows:


**tharwood 11/16

This function ensures that ColdFusion evaluates the code as follows:

'1', '2', '3'

Example

PreserveSingleQuotes Example
This is a useful function for
creating lists of information to return from a query. In this example,
we pick the list of Centers in Suisun, San Francisco, and San Diego,
using the SQL grammar IN to modify a WHERE clause, rather than looping
through the result set after the query is run.


SELECT Name, Address1, Address2, City, Phone
FROM Centers
WHERE City IN (#PreserveSingleQuotes(List)#)

We found #GetCenters.RecordCount# records.

#Name#

#Address1#

#Address2#

#City#

#Phone#



© 2014 Adobe Systems Incorporated. All rights reserved.

2149

Adobe ColdFusion Documentation

QueryAddColumn
Description

Adds a column to a query and populates its rows with the contents of a one-dimensional array. Pads query columns,
if necessary, to ensure that all columns have the same number of rows.
Returns

The number of the column that was added.
Category

Query functions
Function syntax

QueryAddColumn(query, column-name [, datatype], array-name)

See also

QueryNew, QueryAddRow, QuerySetCell; Managing data types for columns in Query of Queries user
guide in the Developing ColdFusion Applications
History

ColdFusion MX 7: Added the datatype parameter.
ColdFusion MX: Changed behavior: if a user attempts to add a column whose name is invalid, ColdFusion throws an
error. (In earlier releases, ColdFusion permitted the add operation, but the user could not reference the column after
adding it.)
Parameters

Parameter

Description

query

Name of a query object.

column-name

Name of the new column.

© 2014 Adobe Systems Incorporated. All rights reserved.

2150

Adobe ColdFusion Documentation

datatype

(Optional) Column data type. ColdFusion generates an
error if data you add to the column is not of this type, or
if it cannot convert the data to this type. The following
data types are valid:
Integer: 32-bit integer
BigInt: 64-bit integer
Double: 64-bit decimal number
Decimal: Variable length decimal, as specified by
java.math.BigDecimal
VarChar: String
Binary: Byte array
Bit: Boolean (1=True, 0=False)
Time: Time
Date: Date (can include time information)

array-name

Name of an array whose elements populate the new
column.

Usage

You can add columns to query objects, such as queries retrieved with the cfquery tag or queries created with the Q
ueryNew function. You cannot use the QueryAddColumn function on a cached query. This function is useful for
generating a query object from the arrays of output parameters that Oracle stored procedures can generate.Adobe
recommends that you use the optional datatype parameter. Without this parameter, ColdFusion must try to
determine the column's data type when it uses the query object in a query of queries. Determining the data type
requires additional processing, and can result in errors if ColdFusion does not guess the type correctly.
Example

The following example creates a query object, uses the QueryAddColumn function to add three columns to the
object, and displays the results. Because two of the arrays that provide the data are shorter than the third,
QueryAddColumn adds padding to the corresponding columns in the query.

© 2014 Adobe Systems Incorporated. All rights reserved.

2151

Adobe ColdFusion Documentation




























Fast Food
Fine Cuisine
Health Food


#FastFood#
#FineCuisine#
#HealthFood#




© 2014 Adobe Systems Incorporated. All rights reserved.

2152

Adobe ColdFusion Documentation

QueryAddRow
Description

Adds a specified number of empty rows to a query.
Returns

The number of rows in the query
Category

Query functions
Function syntax

QueryAddRow(query [, number])

See also

QueryAddColumn, QuerySetCell, QueryNew; Creating a recordset with the QueryNew() function
in the Developing ColdFusion Applications
Parameters

Parameter

Description

query

Name of an executed query.

number

Number of rows to add to the query. The default value
is 1.

Usage

Enhancements in ColdFusion 10 lets you specify a struct, an array of structs, or arrays with single or
multiple dimensions to add rows to the query as shown in the following example:

queryAddRow(myQuery1,
[
{id=2,name="Two"},
{id=3,name="Three"},
{id=4,name="Four"}
]);
queryAddRow(myQuery2,{id=4,name="Four"});

© 2014 Adobe Systems Incorporated. All rights reserved.

2153

Adobe ColdFusion Documentation

queryAddRow(myQuery1,
[
[1,"One"],
[2,"Two"],
[3,"Three"]
]);

Example

QueryAddRow Example


SELECT Course_ID, Number, Descript
FROM Courses

The Query "GetCourses" has #GetCourses.RecordCount# rows.







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

#Course_ID# #Number# #Descript#


© 2014 Adobe Systems Incorporated. All rights reserved.

2154

Adobe ColdFusion Documentation

QueryNew
Description

Creates an empty query (query object).
Returns

An empty query with a set of named columns, or an empty query.
Category

Query functions
Function syntax

QueryNew(columnlist [, columntypelist[, rowData]])

History

ColdFusion MX 7: Added columntypelist parameter.
ColdFusion 10: Added rowData parameter.
See also

QueryAddColumn, QueryAddRow, QuerySetCell; Managing data types for columns in Query of Queries
user guide in the Developing ColdFusion Applications
Parameters

Parameter

Description

columnlist

Comma-delimited list of column names, or an empty
string.

columntypelist

(Optional) Comma-delimited list specifying column data
types. ColdFusion generates an error if the data you
add to the column is not of this type, or if it cannot
convert the data to this type. The following data types
are valid:
Integer: 32-bit integer
BigInt: 64-bit integer
Double: 64-bit decimal number
Decimal: Variable length decimal, as specified by
java.math.BigDecimal
VarChar: String
Binary: Byte array
Bit: Boolean (1=True, 0=False)
Time: Time
Date: Date (can include time information)

© 2014 Adobe Systems Incorporated. All rights reserved.

2155

Adobe ColdFusion Documentation

(Optional) Specifies data to add to the new query. Can
be one of:

rowData

A struct with key/value pairs representing a single
row of data, where the key is the column name and
the value is the data;
an array of structs as per above, for adding multiple
rows of data;
an array of arrays where each inner array are values
for a row of data, in the same order as the columns
are specified in the columntypelist parameter.
See "Usage" for examples.
Usage

If you specify an empty string in the columnlist parameter, use the QueryAddColumn function to add columns to the
query.Adobe recommends that you use the optional columntypelist parameter. Without this parameter, ColdFusion
must try to determine data types when it uses the query object in a query of queries. Determining data types
requires additional processing, and can result in errors if ColdFusion does not guess a type correctly.Enhancements
in ColdFusion 10 lets you initialize the query data. You can specify a struct, an array of structs, or arrays
with single or multiple dimensions to initialize the query as shown in the following example:

myQuery1
myQuery2
[

= queryNew("id,name","Integer,Varchar", {id=1,name="One"});
= queryNew("id,name","Integer,Varchar",
{id=1,name="One"},
{id=2,name="Two"},
{id=3,name="Three"}

]);
myQuery3 = queryNew("id,name","Integer,Varchar", [ [1,"One"], [2,"Two"],
[3,"Three"] ]);

Example

The following example uses the QueryNew function to create an empty query with three columns. It populates two
rows of the query and displays the contents of the query object and its metadata.

© 2014 Adobe Systems Incorporated. All rights reserved.

2156

Adobe ColdFusion Documentation












The query object contents

#Name# #Time# #Advanced#





Using individual query data values

#MyQuery.name[2]# is at #MyQuery.Time[2]#





The query metadata



© 2014 Adobe Systems Incorporated. All rights reserved.

2157

Adobe ColdFusion Documentation

QueryConvertForGrid
Description

Converts query data to a structure that contains a paged subset of the query. Used in CFC functions that return data
to Ajax format cfgrid controls in response to a bind expression.
Returns

A structure that contains one page of data from the query.
Category

Query functions
Function syntax

QueryConvertForGrid(query, page, pageSize)

See also

cfgrid, Dynamically filling form data in Using Ajax form controls and features in the Developing ColdFusion
Applications
History

ColdFusion 8: Added this function.
Parameters

Parameter

Description

query

Name of the query whose data is returned.

page

The specific page of query data to be returned. Pages
are numbered starting with 1.

pageSize

Number of rows of query data on a page.

Usage

You can also create the return value for a cfgrid bind CFC without using this function if your query returns only a
single grid page of data at a time. For more information see Using Ajax User Interface Components and Features in
the Developing ColdFusion Applications.
Example

The following example shows how a CFC function that is called by an Ajax format cfgrid tag bind attribute. uses
the QueryConvertForGrid function to prepare query data to return to the grid. The CFML page with the cfgrid t
ag has the following code:

© 2014 Adobe Systems Incorporated. All rights reserved.

2158

Adobe ColdFusion Documentation









The getData function in the places.cfc page has the following code:











#query#




© 2014 Adobe Systems Incorporated. All rights reserved.

2159

Adobe ColdFusion Documentation

QuerySetCell
Description

Sets a cell to a value. If no row number is specified, the cell on the last row is set. Starting with ColdFusion MX 7,
you cannot add a string literal (for example, "All") to a column that is of type numeric, although this was allowed in
previous versions of ColdFusion.
Returns

True, if successful; False, otherwise.
Category

Query functions
Function syntax

QuerySetCell(query, column_name, value [, row_number ])

See also

QueryAddColumn, QueryAddRow, QueryNew; Creating a recordset with the QueryNew() function i
n About recordsets in the Developing ColdFusion Applications
History

ColdFusion MX 7: Changed the behavior of the function so that it does type validation.
Parameters

Parameter

Description

query

Name of an executed query.

column_name

Name of a column in the query.

value

Value to set in the cell.

row_number

Row number. The default value is last row.

Example

© 2014 Adobe Systems Incorporated. All rights reserved.

2160

Adobe ColdFusion Documentation




SELECT Course_ID, Descript
FROM Courses

The Query "GetCourses" has #GetCourses.RecordCount# rows.








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

#Course_ID# #Course_Number# #Descript#
 

© 2014 Adobe Systems Incorporated. All rights reserved.

2161

Adobe ColdFusion Documentation

QuotedValueList
Description

Gets the values of each record returned from an executed query. ColdFusion does not evaluate the arguments.
Returns

A delimited list of the values of each record returned from an executed query. Each value is enclosed in
single-quotation marks.
Category

Query functions, List functions
Function syntax

QuotedValueList(query.column [, delimiter ])

See also

ValueList
Parameters

Parameter

Description

query.column

Name of an executed query and column. Separate
query name and column name with a period.

delimiter

A string or a variable that contains one. Character(s)
that separate column data.

Example

© 2014 Adobe Systems Incorporated. All rights reserved.

2162

Adobe ColdFusion Documentation





SELECT Dept_ID FROM Departments
WHERE Dept_ID IN (#PreserveSingleQuotes(List)#)



SELECT *
FROM CourseList
WHERE Dept_ID IN ('#GetDepartments.Dept_ID#')


List the course numbers that are in BIOL and CHEM (uses semicolon (;) as the
delimiter):


#QuotedValueList(GetCourseList.CorNumber,";")#



© 2014 Adobe Systems Incorporated. All rights reserved.

2163

Adobe ColdFusion Documentation

Rand
Description

Generates a pseudo-random number.
Returns

A pseudo-random decimal number, in the range 0-1.
Category

Mathematical functions, Security functions
Function syntax

Rand([algorithm])

History

ColdFusion MX 7: Added the algorithm parameter.
See also

Randomize, RandRange
Parameters

Parameter

Description

algorithm

(Optional) The algorithm to use to generate the random
number. ColdFusion installs a cryptography library with
the following algorithms:
CFMX_COMPAT: the algorithm used in ColdFusion
(default).
SHA1PRNG: generates a number using the Sun
Java SHA1PRNG algorithm. This algorithm provides
greater randomness than the default algorithm
IBMSecureRandom: for IBM WebSphere (IBM JVM
does not support the SHA1PRNG algorithm).

Usage

Call the Randomize function before calling this function to seed the random number generator. Seeding the
generator ensures that the Rand function always generates the same sequence of pseudo-random numbers. This
behavior is useful if you must reproduce a pattern consistently.ColdFusion MX uses the Java Cryptography
Extension (JCE) and installs a Sun Java 1.4.2 runtime that includes the Sun JCE default security provider. This
provider includes the algorithms listed in the Parameters section (except the default algorithm). The JCE framework
includes facilities for using other provider implementations; however, cannot provide technical support for third-party
security providers.
Example

© 2014 Adobe Systems Incorporated. All rights reserved.

2164

Adobe ColdFusion Documentation

The following example uses the SHA1PRNG algorithm to generate a single random number:

Rand Example

Rand("SHA1PRNG") returned: #Rand("SHA1PRNG")#
Try again


© 2014 Adobe Systems Incorporated. All rights reserved.

2165

Adobe ColdFusion Documentation

Randomize
Description

Seeds the pseudo-random number generator with an integer number, ensuring repeatable number patterns.
Returns

A pseudo-random decimal number, in the range 0-1.
Category

Mathematical functions, Security functions
Function syntax

Randomize(number[, algorithm])

History

ColdFusion MX 7: Added the algorithm parameter.
See also

Rand, RandRange
Parameters

Parameter

Description

number

Integer number. If the number is not in the range
-2,147,483,648 -2,147,483,647, ColdFusion generates
an error.

algorithm

(Optional) The algorithm to use to generate the seed
number. ColdFusion installs a cryptography library with
the following algorithms:
CFMX_COMPAT: the algorithm used in ColdFusion
(default).
SHA1PRNG: generates a number using the Sun
Java SHA1PRNG algorithm. This algorithm provides
greater randomness than the default algorithm. Note:
due to a bug in ColdFusion 9, 10 and 11, this option
does not work as prescribed. See bug 3792283 for
details.
IBMSecureRandom: for IBM WebSphere (IBM JVM
does not support the SHA1PRNG algorithm).

Usage

Call this function before calling Rand to seed the random number generator. Seeding the generator ensures that the
Rand function always generates the same sequence of pseudo-random numbers. This behavior is useful if you must

© 2014 Adobe Systems Incorporated. All rights reserved.

2166

Adobe ColdFusion Documentation

reproduce a pattern consistently.In Standard Edition, for all algorithms except the default algorithm, ColdFusion uses
the Java Cryptography Extension (JCE) and installs a Sun Java runtime that includes the Sun JCE default security
provider. This provider includes the algorithms listed in the Parameters section. The JCE framework includes
facilities for using other provider implementations; however, Adobe cannot provide technical support for third-party
security providers.In Enterprise Edition, ColdFusion also installs the RSA BSafe Crypto-J library. This provider adds
the following algorithms: FIPS186PRNG, MD5PRNG, DummyPRNG, OBFPRNG. DummyPRNG always returns 0.
Example

The following example calls the Randomize function to seed the random number generator and generates 10
random numbers.

 

#rand()#



© 2014 Adobe Systems Incorporated. All rights reserved.

2167

Adobe ColdFusion Documentation

RandRange
Description

Generates a pseudo-random integer in the range between two specified numbers.
Returns

A pseudo-random integer.
Category

Mathematical functions, Security functions
Function syntax

RandRange(number1, number2[, algorithm])

History

ColdFusion MX 7: Added the algorithm parameter.
See also

Rand, Randomize
Parameters

Parameter

Description

number1, number2

Integer numbers. If the numbers are not in the range
-2,147,483,648 - 2,147,483,647, ColdFusion generates
an error.

algorithm

(Optional) The algorithm to use to generate the random
number. ColdFusion installs a cryptography library with
the following algorithms:
CFMX_COMPAT: the algorithm used in ColdFusion
(default).
SHA1PRNG: generates a number using the Sun
Java SHA1PRNG algorithm. This algorithm provides
greater randomness than the default algorithm
IBMSecureRandom: for IBM WebSphere (IBM JVM
does not support the SHA1PRNG algorithm.)

Usage

Very large positive or negative values for the number1 and number2 parameters might result in poor randomness in
the results. To prevent this problem, do not specify numbers outside the range -1,000,000,000 1,000,000,000.ColdFusion uses the Java Cryptography Extension (JCE) and installs a Sun Java 1.4.2 runtime that

© 2014 Adobe Systems Incorporated. All rights reserved.

2168

Adobe ColdFusion Documentation

includes the Sun JCE default security provider. This provider includes the algorithms listed in the Parameters
section (except the default algorithm). The JCE framework includes facilities for using other provider
implementations; however, cannot provide technical support for third-party security providers.
Example

The following example contains a form that requires random number range values, and lets you optionally specify a
random number seed value. It uses cfform controls and attributes to specify a default range, ensure that the range
fields have values, and validate that the field values are in a specified integer range. When you submit the form, it
checks whether the seed field has an empty string; if the field has a value, the code uses the number to seed the
random number generator. It then generates and displays the random number.

RandRange Example





Seed value is #FORM.mySeed#







No Seed value submitted




RandRange returned: #RandRange(FORM.myInt, FORM.myInt2, "SHA1PRNG")#




Enter the random number Range: From

To

Enter a number to seed the randomizer:




© 2014 Adobe Systems Incorporated. All rights reserved.

2169

Adobe ColdFusion Documentation

ReEscape
Description

Takes a string and escapes characters that match regular expression control characters.
Returns

String appended with the escape characters
History

ColdFusion 10: Added this function
Syntax

reEscape(string____)
Properties

Parameter

Description

string

The string in which you have to escape characters that
match regular expression characters.

Example


#reescape("*.{}[]exam?ple")#


© 2014 Adobe Systems Incorporated. All rights reserved.

2170

Adobe ColdFusion Documentation

REFind
Description

Uses a regular expression (RE) to search a string for a pattern. The search is case sensitive. For more information
on regular expressions, including escape sequences, anchors, and modifiers, see Using Regular Expressions in
Functions in the Developing ColdFusion Applications.
Returns

Depends on the value of the returnsubexpressions__parameter:
If returnsubexpressions__= "False":
The position in the string where the match begins
0, if the regular expression is not matched in the string
If returnsubexpressions = "True": a structure that contains two arrays, len and pos. The array
elements are as follows:
If the regular expression is found in the string, the first element of the len and pos arrays contains the
length and position, respectively, of the first match of the entire regular expression.
If the regular expression contains parentheses that group subexpressions, each subsequent array
element contains the length and position, respectively, of the first occurrence of each group.
If the regular expression is not found in the string, the first element of the len and pos arrays contains
0.
Category

String functions
Function syntax

REFind(reg_expression, string [, start, returnsubexpressions ] )

See also

Find, FindNoCase, REFindNoCase, REReplace, REReplaceNoCase
Parameters

Parameter

Description

reg_expression

Regular expression for which to search. Case sensitive.

string

A string, or a variable that contains one, in which to
search.

start

Optional. A positive integer, or a variable that contains
one. Position in the string at which to start search. The
default value is 1.

© 2014 Adobe Systems Incorporated. All rights reserved.

2171

Adobe ColdFusion Documentation

returnsubexpressions

Optional. Boolean. Whether to return substrings of
reg_expression, in arrays named len and pos:
True: if the regular expression is found, the first array
element contains the length and position,
respectively, of the first match. If the regular
expression contains parentheses that group
subexpressions, each subsequent array element
contains the length and position, respectively, of the
first occurrence of each group. If the regular
expression is not found, the arrays each contain one
element with the value 0.
False: the function returns the position in the string
where the match begins. Default.

Usage

This function finds the first occurrence of a regular expression in a string. To find the second and subsequent
instances of the expression or of subexpressions in it, you call this function more than once, each time with a
different start position. To determine the next start position, use the returnsubexpressions__parameter, and
add the value returned in the first element of the length array to the value in the first element of the position array.
Example

REFind Example
This example shows the use of the REFind function with and without the
returnsubexpressions parameter set to True.
If you do not use the returnsubexpressions parameter,
REFind returns the position of the first occurrence of a regular
expression in a string starting from the specified position.
Returns 0 if no occurrences are found.
REFind("a+c+", "abcaaccdd"):
#REFind("a+c+", "abcaaccdd")#
REFind("a+c*", "abcaaccdd"):
#REFind("a+c*", "abcaaccdd")#
REFind("[[:upper:]]", "abcaacCDD"):
#REFind("[[:upper:]]", "abcaacCDD")#
REFind("[\?&]rep = ", "report.cfm?rep = 1234&u = 5"):
#REFind("[\?&]rep = ", "report.cfm?rep = 1234&u = 5")#




If you use the returnssubexpression parameter, REFind returns the
position and length of the first occurrence of a regular expression
in a string starting from the specified position. The position and
length variables are stored in a structure. To access position and length
information, use the keys pos and len, respectively.

The string in which the function is to search is:
#teststring#.
The first call to REFind to search this string is:
REFind("[A-Za-z]+",testString,1,"TRUE")
This function returns a structure that contains two arrays: pos and len.

© 2014 Adobe Systems Incorporated. All rights reserved.

2172

Adobe ColdFusion Documentation

To create this structure you can use a CFSET statement, for example: 
<CFSET st = REFind("[[:alpha:]]",testString,1,"TRUE")>



The number of elements in each array: #ArrayLen(st.pos)#.

The number of elements in the pos and len arrays is always one
if you do not use parentheses in the regular expression.
The value of st.pos[1] is: #st.pos[1]#.
The value of st.len[1] is: #st.len[1]#.


Substring is [#Mid(testString,st.pos[1],st.len[1])#]


However, if you use parentheses in the regular expression, the first
element contains the position and length of the first instance
of the whole expression. The position and length of the first instance
of each parenthesized subexpression within is included in additional
array elements.
For example:
<CFSET st1 = REFind("([[:alpha:]])[ ]+(\1)",testString,1,"TRUE")>

The number of elements in each array is #ArrayLen(st1.pos)#
.
First whole expression match; position is
#st1.pos[1]#;
length is #st1.len[1]#; whole expression match is
[#Mid(testString,st1.pos[1],st1.len[1])#]

Subsequent elements of the arrays provide the position and length of
the first instance of each parenthesized subexpression therein.

Position is #st1.pos[i]#; Length is #st1.len[i]#;
Substring is [#Mid(testString,st1.pos[i],st1.len[i])#]

© 2014 Adobe Systems Incorporated. All rights reserved.

2173

Adobe ColdFusion Documentation





© 2014 Adobe Systems Incorporated. All rights reserved.

2174

Adobe ColdFusion Documentation

REFindNoCase
Description

Uses a regular expression (RE) to search a string for a pattern, starting from a specified position. The search is
case-insensitive. For more information on regular expressions, including escape sequences, anchors, and modifiers,
see Using Regular Expressions in Functions in the Developing ColdFusion Applications.
Returns

Depends on the value of the returnsubexpressions__parameter:
If returnsubexpressions__= "False":
The position in the string where the match begins
0, if the regular expression is not matched in the string
If returnsubexpressions = "True": a structure that contains two arrays, len and pos. The array
elements are as follows:
If the regular expression is found in the string, the first element of the len and pos arrays contains the
length and position, respectively, of the first match of the entire regular expression.
If the regular expression contains parentheses that group subexpressions, each subsequent array
element contains the length and position, respectively, of the first occurrence of each group.
If the regular expression is not found in the string, the first element of the len and pos arrays contains
0.
Category

String functions
Function syntax

REFindNoCase(reg_expression, string [, start, returnsubexpressions])

See also

Find, FindNoCase, REFind, REReplace, REReplaceNoCase
Parameters

Parameter

Description

reg_expression

Regular expression for which to search.
Case-insensitive.For more information, see Using
Regular Expressions in Functions in the Developing
ColdFusion Applications.

string

A string or a variable that contains one. String in which
to search.

start

Optional. A positive integer or a variable that contains
one. Position at which to start search. The default value
is 1.

© 2014 Adobe Systems Incorporated. All rights reserved.

2175

Adobe ColdFusion Documentation

returnsubexpressions

Optional. Boolean. Whether to return substrings of
reg_expression, in arrays named len and pos:
True: if the regular expression is found, the first array
element contains the length and position,
respectively, of the first match. If the regular
expression contains parentheses that group
subexpressions, each subsequent array element
contains the length and position, respectively, of the
first occurrence of each group. If the regular
expression is not found, the arrays each contain one
element with the value 0.
False: the function returns the position in the string
where the match begins. Default.

Usage

This function finds the first occurrence of a regular expression in a string. To find the second and subsequent
instances of the expression or of subexpressions in it, you call this function more than once, each time with a
different start position. To determine the next start position, use the returnsubexpressions__parameter, and
add the value returned in the first element of the length array to the value in the first element of the position array.
Example

REFindNoCase Example
This example demonstrates the use of the REFindNoCase function with and
without the returnsubexpressions parameter set to True.
If you do not use the returnsubexpressions parameter, REFindNoCase
returns the position of the first occurrence of a regular expression
in a string starting from the specified position. Returns 0 if no
occurrences are found. 
REFindNoCase("a+c+", "abcaaccdd"):
#REFindNoCase("a+c+", "abcaaccdd")#
REFindNoCase("a+c*", "abcaaccdd"):
#REFindNoCase("a+c*", "abcaaccdd")#
REFindNoCase("[[:alpha:]]+", "abcaacCDD"):
#REFindNoCase("[[:alpha:]]+", "abcaacCDD")#
REFindNoCase("[\?&]rep = ", "report.cfm?rep = 1234&u = 5"):
#REFindNoCase("[\?&]rep = ", "report.cfm?rep = 1234&u = 5")#



If you do use the returnssubexpression parameter, REFindNoCase returns
the position and length of the first occurrence of a regular expression
in a string starting from the specified position. The position and length
variables are stored in a structure. To access position and length
information, use the keys pos and len, respectively.

The string in which the function is to search is:
#teststring#.
The first call to REFindNoCase to search this string is:
REFindNoCase("[[:alpha:]]+",testString,1,"True")
This function returns a structure that contains two arrays: pos and len.
To create this structure you can use a CFSET statement,

© 2014 Adobe Systems Incorporated. All rights reserved.

2176

Adobe ColdFusion Documentation

for example:
<CFSET st = REFindNoCase("[[:alpha:]]+",testString,1,"True")>



The number of elements in each array: #ArrayLen(st.pos)#.

The number of elements in the pos and len arrays will always be one,
if you do not use parentheses to denote subexpressions in the regular
expression.
The value of st.pos[1] is: #st.pos[1]#.
The value of st.len[1] is: #st.len[1]#.


Substring is [#Mid(testString,st.pos[1],st.len[1])#]


However, if you use parentheses to denote subexpressions in the regular
expression, the first element contains the position and length of
the first instance of the whole expression. The position and length
of the first instance of each subexpression within will be included
in additional array elements.
For example:
<CFSET st1 = REFindNoCase("([[:alpha:]]+)[ ]+(\1)",testString,1,"True")>

The number of elements in each array is

#ArrayLen(st1.pos)#
.
First whole expression match; position is

#st1.pos[1]#; length is #st1.len[1]#;
whole expression match is [#Mid(testString,st1.pos[1],st1.len[1])#]

Subsequent elements of the arrays provide the position and length of the
first instance of each parenthesized subexpression therein.

Position is #st1.pos[i]#; Length is #st1.len[i]#;
Substring is [#Mid(testString,st1.pos[i],st1.len[i])#]

© 2014 Adobe Systems Incorporated. All rights reserved.

2177

Adobe ColdFusion Documentation





© 2014 Adobe Systems Incorporated. All rights reserved.

2178

Adobe ColdFusion Documentation

REMatch
Description

Uses a regular expression (RE) to search a string for a pattern, starting from a specified position. The search is case
sensitive. For more information on regular expressions, including escape sequences, anchors, and modifiers, see U
sing Regular Expressions in Functions in the Developing ColdFusion Applications.
Returns

An array of strings that match the expression.
Category

String functions
Function syntax

REMatch(reg_expression, string)

See also

Find, FindNoCase, REFind, REReplace, REReplaceNoCase, REMatchNoCase
Parameters

Parameter

Description

reg_expression

Regular expression for which to search. Case
sensitive.For more information, see Using Regular
Expressions in Functions in the Developing ColdFusion
Applications.

string

A string or a variable that contains one. String in which
to search.

Usage

This function finds all occurrence of a regular expression in a string.
Example



result = REMatch("https?://([-\w\.]+)+(:\d+)?(/([\w/_\.]*(\?\S+)?)?)?",
cfhttp.filecontent);

© 2014 Adobe Systems Incorporated. All rights reserved.

2179

Adobe ColdFusion Documentation

REMatchNoCase
Description

Uses a regular expression (RE) to search a string for a pattern, starting from a specified position. The search is
case-insensitive. For more information on regular expressions, including escape sequences, anchors, and modifiers,
see Using Regular Expressions in Functions in the Developing ColdFusion Applications.
Returns

An array of strings that match the expression.
Category

String functions
Function syntax

REMatchNoCase(reg_expression, string)

See also

Find, FindNoCase, REFind, REReplace, REReplaceNoCase, REMatch
Parameters

Parameter

Description

reg_expression

Regular expression for which to search.
Case-insensitive.For more information, see Using
Regular Expressions in Functions in the Developing
ColdFusion Applications.

string

A string or a variable that contains one. String in which
to search.

Example


result = REMatch("https?://([-\w\.]+)+(:\d+)?(/([\w/_\.]*(\?\S+)?)?)?",
cfhttp.filecontent);

© 2014 Adobe Systems Incorporated. All rights reserved.

2180

Adobe ColdFusion Documentation

ReleaseComObject
Description

Releases a COM Object and frees up resources that it used.
Returns

Nothing.
Category

Extensibility functions
Function syntax

ReleaseComObject(objectName)

See also

CreateObject, cfobject
History

ColdFusion MX 6.1: Added this function.
Parameters

Parameter

Description

objectName

Variable name of a COM object that was created using
the CreateObject function or cfobject tag.

Usage

This function forcefully terminates and releases the specified COM object and all COM objects that it created. Use
this function when the object is no longer in use, to quickly free up resources. If the COM object has a method, such
as a quit method, that terminates the program, call this method before you call the ReleaseComObject function.
This function can improve processing efficiency, but is not required for an application to work. If you do not use this
function, the Java garbage collection mechanism eventually frees the resources. If you use this function on an object
that is in use, the object is prematurely released and your application will get exceptions.
Example

ReleaseComObject Example

obj = CreateObject("Com", "excel.application.9");
//code that uses the object goes here???I'd like to fill this in with something???
obj.quit();
ReleaseComObject(obj);


© 2014 Adobe Systems Incorporated. All rights reserved.

2181

Adobe ColdFusion Documentation

© 2014 Adobe Systems Incorporated. All rights reserved.

2182

Adobe ColdFusion Documentation

RemoveCachedQuery
Description

Removes the query with the details you provide from query cache.
Returns

Nothing
Syntax

removeCachedQuery(SQL_, datasource, params, region___)
History

ColdFusion 10: Added this function.
Properties

Parameter

Description

SQL

The query SQL.

datasource

The datasource you ran the query on.

params

(Optional) Array of parameter values passed to SQL.

region

(Optional) Specifies the cache region where you can
place the cache object

Example



SELECT * from art where artid = 





© 2014 Adobe Systems Incorporated. All rights reserved.

2183

Adobe ColdFusion Documentation

RemoveChars
Description

Removes characters from a string.
Returns

A copy of the string, with count characters removed from the specified start position. If no characters are found,
returns zero.
Category

String functions
Function syntax

RemoveChars(string, start, count)

See also

Insert, Len
Parameters

Parameter

Description

string

A string or a variable that contains one. String in which
to search.

start

A positive integer or a variable that contains one.
Position at which to start search.

count

Number of characters to remove.

Example

© 2014 Adobe Systems Incorporated. All rights reserved.

2184

Adobe ColdFusion Documentation

RemoveChars Example
Returns a string with count characters removed from the
start position. Returns 0 if no characters are found.


Your string is only #Len(FORM.myString)#
 characters long.
Please enter a longer string, select fewer characters to remove or
begin earlier in the string.


Your original string: #FORM.myString#
Your modified string: #RemoveChars(FORM.myString,
FORM.start, FORM.numChars)#




© 2014 Adobe Systems Incorporated. All rights reserved.

2185

Adobe ColdFusion Documentation

RepeatString
Description

Creates a string that contains a specified number of repetitions of the specified string.
Returns

A string.
Category

String functions
Function syntax

RepeatString(string, count)

See also

CJustify, LJustify, RJustify
Parameters

Parameter

Description

string

A string or a variable that contains one.

count

Number of repeats.

Example

RepeatString Example
RepeatString returns a string created from string, repeated
a specified number of times.

RepeatString("-", 10): #RepeatString("-", 10)#
RepeatString("<BR>", 3): #RepeatString("
", 3)#

RepeatString("", 5): #RepeatString("", 5)#
RepeatString("abc", 0): #RepeatString("abc", 0)#
RepeatString("Lorem Ipsum", 2):
#RepeatString("Lorem Ipsum", 2)#


© 2014 Adobe Systems Incorporated. All rights reserved.

2186

Adobe ColdFusion Documentation

Replace
Description

Replaces occurrences of substring1 in a string with substring2, in a specified scope. The search is case sensitive.
Returns

The string, after making replacements.
Category

String functions
Function syntax

Replace(string, substring1, substring2 \[, scope ])

See also

Find, REFind, ReplaceNoCase, ReplaceList, REReplace
Parameters

Parameter

Description

string

A string or a variable that contains one. String in which
to search.

substring1

A string or a variable that contains one. String for which
to search

substring2

String that replaces substring1

scope

one: replaces the first occurrence (default)
all: replaces all occurrences

Usage

To remove a string, specify the empty string ("") as substring2.You do not need to escape comma characters in
strings. For example, the following code deletes the commas from the sentence:

replace("The quick brown fox jumped over the lazy cow, dog, and cat.",",","","All")

Example

© 2014 Adobe Systems Incorporated. All rights reserved.

2187

Adobe ColdFusion Documentation

Replace Example
The Replace function returns string with substring1
replaced by substring2 in the specified scope. This
is a case-sensitive search.

Your original string, #FORM.MyString#
You wanted to replace the substring #FORM.MySubstring1#

with the substring #FORM.MySubstring2#.
The result: #Replace(FORM.myString,
FORM.MySubstring1, FORM.mySubString2)#


© 2014 Adobe Systems Incorporated. All rights reserved.

2188

Adobe ColdFusion Documentation

ReplaceList
Description

Replaces occurrences of the elements from a delimited list in a string with corresponding elements from another
delimited list. The search is case sensitive.
Returns

A copy of the string, after making replacements.
Category

List functions, String functions
Function syntax

ReplaceList(string, list1, list2)
ReplaceList(string, list1, list2, delimiter)
ReplaceList(string, list1, list2, delimiter_list1, delimiter_list2)

See also

Find, REFind, Replace, REReplace
Parameters

Parameter

Description

string

A string, or a variable that contains one, within which to
replace substring

list1

Comma-delimited list of substrings for which to search

list2

Comma-delimited list of replacement substrings

delimiter

Common delimiter for both search and replacement.

delimiter_list1

Delimiter for search.

delimiter_list2

Delimiter for replacement.

Usage

The list of substrings to replace is processed sequentially. If a list1 element is contained in list2 elements, recursive
replacement might occur. The second example shows this.
Example 1

© 2014 Adobe Systems Incorporated. All rights reserved.

2189

Adobe ColdFusion Documentation

The ReplaceList function returns string with
substringlist1 (e.g. "a,b") replaced by substringlist2
(e.g. "c,d") in the specified scope.

Your original string, #FORM.MyString#
You wanted to replace the substring #FORM.MySubstring1#

with the substring #FORM.MySubstring2#.
The result: #Replacelist(FORM.myString,
FORM.MySubstring1, FORM.mySubString2)#


String 1


Substring 1 (find this list of substrings)


Substring 2 (replace with this list of substrings)




Replacelist Example Two


#ReplaceList(stringtoreplace,"dog,brown,fox,black", "cow,black,ferret,white")#


Example 2

In the following example, the delimiter applies to both the lists:

Replacelist Example One


#ReplaceList(stringtoreplace,"dog:brown:fox:black", "cow:black:ferret:white", ":")#


Example 3

In the following example, delimiter is specific to individual lists:

Replacelist Example Two


#ReplaceList(stringtoreplace,"dog:brown:fox:black", "cow-black-ferret-white", ":" ,
"-")#


© 2014 Adobe Systems Incorporated. All rights reserved.

2190

Adobe ColdFusion Documentation

ReplaceNoCase
Description

Replaces occurrences of substring1 with substring2, in the specified scope. The search is case-insensitive.
Returns

A copy of the string, after making replacements.
Category

String functions
Function syntax

ReplaceNoCase(string, substring1, substring2 [, scope ])

See also

Find, REFind, Replace, ReplaceList, REReplace
Parameters

Parameter

Description

string

A string (or variable that contains one) within which to
replace substring.

substring1

String (or variable that contains one) to replace, if
found.

substring2

String (or variable that contains one) that replaces sub
string1.

scope

one: replaces the first occurrence (default).
all: replaces all occurrences.

Example

© 2014 Adobe Systems Incorporated. All rights reserved.

2191

Adobe ColdFusion Documentation

ReplaceNoCase Example
The ReplaceNoCase function returns string with substring1
replaced by substring2 in the specified scope.
The search/replace is case-insensitive.

Your original string, #FORM.MyString#
You wanted to replace the substring #FORM.MySubstring1#

with the substring #FORM.MySubstring2#.
The result: #ReplaceNoCase(FORM.myString,
FORM.MySubstring1, FORM.mySubString2)#


© 2014 Adobe Systems Incorporated. All rights reserved.

2192

Adobe ColdFusion Documentation

REReplace
Description

Uses a regular expression (RE) to search a string for a string pattern and replace it with another. The search is case
sensitive.
Returns

If the scope parameter is set to one, returns a string with the first occurrence of the regular expression replaced by
the value of substring.If the scope parameter is set to all, returns a string with all occurrences of the regular
expression replaced by the value of substring. If the function finds no matches, it returns a copy of the string
unchanged.
Category

String functions
Function syntax

REReplace(string, reg_expression, substring [, scope ])

See also

REFind, Replace, ReplaceList, REReplaceNoCase
History

ColdFusion MX: Added supports for the following special codes in a replacement substring, to control case
conversion:
\u - uppercase the next character
\l - lowercase the next character
\U - uppercase until \E
\L - lowercase until \E
\E - end \U or \L
For more information on new features, see REFind.
Parameters

Parameter

Description

string

A string or a variable that contains one. String within
which to search.

reg_expression

Regular expression to replace. The search is case
sensitive.

substring

A string or a variable that contains one. Replaces reg_
expression.

© 2014 Adobe Systems Incorporated. All rights reserved.

2193

Adobe ColdFusion Documentation

scope

one: replaces the first occurrence (default).
all: replaces all occurrences.

Usage

For details on using regular expressions, see Using Regular Expressions in Functions in the Developing ColdFusion
Applications.
Example

The REReplace function returns string with a regular expression replaced
with substring in the specified scope. Case-sensitive search.
REReplace("CABARET","C|B","G","ALL"):
#REReplace("CABARET","C|B","G","ALL")#
REReplace("CABARET","[A-Z]","G","ALL"):
#REReplace("CABARET","[A-Z]","G","ALL")#
REReplace("I love jellies","jell(y|ies)","cookies"):
#REReplace("I love jellies","jell(y|ies)","cookies")#

REReplace("I love jelly","jell(y|ies)","cookies"):
#REReplace("I love jelly","jell(y|ies)","cookies")#

© 2014 Adobe Systems Incorporated. All rights reserved.

2194

Adobe ColdFusion Documentation

REReplaceNoCase
Description

Uses a regular expression to search a string for a string pattern and replace it with another. The search is
case-insensitive.
Returns

If scope = "one": returns a string with the first occurrence of the regular expression replaced by the value
of substring.
If scope = "all": returns a string with all occurrences of the regular expression replaced by the value of su
bstring.
If the function finds no matches: returns a copy of the string, unchanged.
Category

String functions
Function syntax

REReplaceNoCase(string, reg_expression, substring [, scope ])

See also

REFind, REFindNoCase, Replace, ReplaceList
History

ColdFusion MX: Changed behavior: this function inserts the following special characters in regular expression
replacement strings, to control case conversion: \u, \U, \l, \L, and \E. If any of these strings is present in a
ColdFusion 5 application, insert a backslash before it (for example, change "\u" to "
u").
Parameters

Parameter

Description

string

A string or a variable that contains one.

reg_expression

Regular expression to replace. For more information,
see Using Regular Expressions in Functions in the Dev
eloping ColdFusion Applications.

substring

A string or a variable that contains one. Replaces reg_
expression.

scope

© 2014 Adobe Systems Incorporated. All rights reserved.

one: replaces the first occurrence of the regular
expression. Default.
all: replaces all occurrences of the regular
expression.

2195

Adobe ColdFusion Documentation
Usage

For details on using regular expressions, see Using Regular Expressions in Functions in the Developing ColdFusion
Applications.
Example

The REReplaceNoCase function returns string with a regular
expression replaced with substring in the specified scope.
This is a case-insensitive search.
REReplaceNoCase("cabaret","C|B","G","ALL"):
#REReplaceNoCase("cabaret","C|B","G","ALL")#
REReplaceNoCase("cabaret","[A-Z]","G","ALL"):
#REReplaceNoCase("cabaret","[A-Z]","G","ALL")#
REReplaceNoCase("I LOVE JELLIES","jell(y|ies)","cookies"):
#REReplaceNoCase("I LOVE JELLIES","jell(y|ies)","cookies")#

REReplaceNoCase("I LOVE JELLY","jell(y|ies)","cookies"):
#REReplaceNoCase("I LOVE JELLY","jell(y|ies)","cookies")#


© 2014 Adobe Systems Incorporated. All rights reserved.

2196

Adobe ColdFusion Documentation

RestDeleteApplication
Description

Unregisters the directory path if it is already registered.
Returns

Nothing
History

ColdFusion 10: Added this function
Syntax

RestDeleteApplication("dirPath")
Properties

Parameter

Description

dirPath

Required. Path to the directory to be unregistered. If
the path is not valid, it results in an error.

Example



© 2014 Adobe Systems Incorporated. All rights reserved.

2197

Adobe ColdFusion Documentation

RestSetResponse
Description

Sets the custom responses.
History

ColdFusion 10: Added this function
Syntax

restSetResponse(response)
Parameters

Parameter

Description

response

A struct that contains the response details.

Warning

restSetResponse() can only be used on function with a return type of void. It will cause
errors if it is used on functions that have any other return type.
Example




"&name&"">,
headers={
location="http://localhost:8500/rest/CustomerService/customers/123",
}
}>



© 2014 Adobe Systems Incorporated. All rights reserved.

2198

Adobe ColdFusion Documentation

RestInitApplication
Description

Registers the directory path with the service mapping provided. If no service mapping is provided, the application
name is used. If the rest application is already registered, it is refreshed.
Returns

Nothing
History

ColdFusion 11: Added the options attribute.
ColdFusion 10: Added this function
Syntax

RestInitApplication( "dirPath" [, "serviceMapping", "options"] )
Properties

Parameter

Description

dirPath

Required. Path to the directory to be registered.

serviceMapping

Optional. Alternate string to be used for application
name while calling the REST service.

options

Optional. Additional options passed for initializing the
application.
"host" - The application will be registered for the
particular host.
"useHost" - true/false - The application will extract
the host from the URL and it will be used as the host
name.
"isdefault" - Specifies whether the application should
be registered as a default application or not. For
accessing a default application, the URL should not
contain the application name.

Example



© 2014 Adobe Systems Incorporated. All rights reserved.

2199

Adobe ColdFusion Documentation

Reverse
Description

Reverses the order of items, such as the characters in a string or the digits in a number.
Returns

A copy of string, with the characters in reverse order.
Category

String functions
Function syntax

Reverse(string)

See also

Left, Mid, Right
Parameters

Parameter

Description

string

A string or a variable that contains one

Usage

You can call this function on a number with code such as the following:

reverse(6*2) equals #reverse(6*2)#

This code outputs the following:

reverse(6*2) equals 21

Example

© 2014 Adobe Systems Incorporated. All rights reserved.

2200

Adobe ColdFusion Documentation

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


Reverse returned:
#Reverse(FORM.myString)#

Please enter a string to be reversed.



Enter a string to be reversed:




© 2014 Adobe Systems Incorporated. All rights reserved.

2201

Adobe ColdFusion Documentation

Right
Description

Gets a specified number of characters from a string, beginning at the right.Returns the specified number of
characters from the end (or right side) of the specified string.
Returns

If the length of the string is greater than or equal to count, the rightmost count characters of the string
If count is greater than the length of the string, the whole string
If count is greater than 1, and the string is empty, an empty string
Category

String functions
Function syntax

Right(string, count)

See also

Left, Mid, Reverse
Parameters

Parameter

Description

string

A string or a variable that contains one.

count

A positive integer that specifies the maximum number
of characters to return.

Example

© 2014 Adobe Systems Incorporated. All rights reserved.

2202

Adobe ColdFusion Documentation



#Right("See the quick red fox jump over the fence", 9)#


#Right("ColdFusion", 6)#


Right Example




Your string
#FORM.myText# only has #Len(FORM.myText)# characters. You cannot output
the #FORM.removeChars# rightmost characters of this string because it
is not long enough.

Your original string: #FORM.myText#
Your changed string, showing only the #FORM.removeChars#
 rightmost characters:
#right(Form.myText, FORM.removeChars)#



Please enter a string of more
than 0 (zero) characters.



Type in some text


How many characters from the right do you want to show?

1
3
5
7
9



© 2014 Adobe Systems Incorporated. All rights reserved.

2203

Adobe ColdFusion Documentation

RJustify
Description

Right justifies characters of a string.
Returns

A copy of a string, right-justified in the specified field length.
Category

Display and formatting functions, String functions
Function syntax

RJustify(string, length)

See also

CJustify, LJustify
Parameters

Parameter

Description

string

A string enclosed in quotation marks, or a variable that
contains one.

length

A positive integer or a variable that contains one.
Length of field in which to justify string.

Example

© 2014 Adobe Systems Incorporated. All rights reserved.

2204

Adobe ColdFusion Documentation











RJustify Function
Enter a string. It will be right justified within the sample field


 


© 2014 Adobe Systems Incorporated. All rights reserved.

2205

Adobe ColdFusion Documentation

Round
Description

Rounds a number to the closest integer.
Returns

An integer.
Category

Mathematical functions
Function syntax

Round(number)

See also

Ceiling, Fix, Int
Parameters

Parameter

Description

number

Number to round

Usage

Use this function to round a number. This function rounds numbers that end with .5 up to the nearest integer. It
rounds 3.5 to 4 and -3.5 to -3.
Example

Round Example
This function rounds a number to the closest integer.

Round(7.49) : #Round(7.49)#
Round(7.5) : #Round(7.5)#
Round(-10.775) : #Round(-10.775)#
Round(-35.5) : #Round(-35.5)#
Round(35.5) : #Round(35.5)#
Round(1.2345*100)/100 : #Round(1.2345*100)/100#


© 2014 Adobe Systems Incorporated. All rights reserved.

2206

Adobe ColdFusion Documentation

RTrim
Description

Removes spaces from the end of a string.
Returns

A copy of string, after removing trailing spaces.
Category

String functions
Function syntax

RTrim(string)

See also

LTrim, Trim
Parameters

Parameter

Description

string

A string or a variable that contains one

Example

RTrim Example


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




Enter some text. It will be modified by Rtrim to remove spaces from the right.




#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

2207

Adobe ColdFusion Documentation

© 2014 Adobe Systems Incorporated. All rights reserved.

2208

Adobe ColdFusion Documentation

QueryGetRow
A new function, QueryGetRow, has been introduced in ColdFusion 11. This function returns a struct having all the
columns as keys and their corresponding values:

row_struct = QueryGetRow(queryName, row_index);
See the following example:

select * from art where ARTID > 3




Example


select * from art where ARTID >






© 2014 Adobe Systems Incorporated. All rights reserved.

2209

Adobe ColdFusion Documentation

QueryExecute
Description

Apart from the generic script syntax for the tag, there is another script alternative to cfquery tag, provided by the
QueryExecute function. This function simplifies the query execution in the CFScript block.
The usage:

QueryExecute(sql_str, queryParams, queryOptions);

See the following example:

QueryExecute ("select * from Employees where empid=1");
QueryExecute("select * from Employee where country=:country and
citizenship=:country", {country='USA'});
QueryExecute("select * from Employee where country=:country and
citizenship=:country", {country={value='USA',
CFSQLType='CF_SQL_CLOB', list=true, otherqueryParam_attributes}, });
QueryExecute("select * from Employee where country=:country and
citizenship=:country", {country='USA'},
{datasource=”cfartgallery”, cachename=”employees”})
QueryExecute ("select * from Artists where artistid=? and country=?", [1, “USA”],
{datasource="cfartgallery"});

Note the function:

QueryExecute(sql [,a struct or array of struct for all named parameters ]);

This function lets you pass unnamed parameters to the query. Use '?' (question mark) as the place-holder for the
parameters. The values to the parameters should be passed as an array toparams.
For more information on using the unnamed parameters, see this document.
Note that the following points are applicable:
If there are any Query parameters, they must be passed as the second argument of the function. It can be
either a struct or an array.
If you need to provide additional attribute as a Query parameter (like CFSQLType, list, and separator), you
can pass these as struct against that column name.
The Query and datasource properties will be passed as the third argument.
The Query tag is also available as a ColdFusion function apart from the generic script syntax for the CFQuery tag.
This function simplifies the query execution in the CFScript block.

© 2014 Adobe Systems Incorporated. All rights reserved.

2210

Adobe ColdFusion Documentation
Usage

QueryExecute(sql_str, queryParams, queryOptions);

History

ColdFusion 11: Added this function
Example 1


fetchclientinfo="yes"}>

from art where ARTID < 5", [] ,qoptions)>



from art where ARTID < ?", [4] ,qoptions)>




from art where ARTID < :artid

and artistid=:aid ",

Example 2

QueryExecute ("select from Employees where empid=1");
QueryExecute("select from Employee where country=:country and citizenship=:country",
{country='USA'});
QueryExecute("select from Employee where country=:country and citizenship=:country",
{country={value='USA',
CFSQLType='CF_SQL_CLOB', list=true, otherqueryParam_attributes}, });
QueryExecute("select from Employee where country=:country and citizenship=:country",
{country='USA'},
{datasource=”cfartgallery”, cachename=”employees”})
QueryExecute ("select from Artists where artistid=? and country=?", [1, “USA”],
{datasource="cfartgallery"});

Note the function:
QueryExecute(sql [,a struct or array of struct for all named parameters ]);

This function lets you pass unnamed parameters to the query. Use '?' (question mark) as the place-holder for the
parameters. The values to the parameters should be passed as an array to params.
For more information on using the unnamed parameters, see this document.

© 2014 Adobe Systems Incorporated. All rights reserved.

2211

Adobe ColdFusion Documentation

Note that the following points are applicable:
If there are any Query parameters, they must be passed as the second argument of the function. It can be
either a struct or an array.
If you need to provide additional attribute as a Query parameter (like CFSQLType, list, and separator), you
can pass these as struct against that column name.
The Query and datasource properties will be passes as the third argument.
You can write the SQL statement with a positional parameter.

© 2014 Adobe Systems Incorporated. All rights reserved.

2212

Adobe ColdFusion Documentation

Functions s
Second
SendGatewayMessage
Serialize
SerializeJSON
SerializeXML
SessionGetMetaData
SessionInvalidate
SessionRotate
SetEncoding
SetLocale
SetProfileString
SetVariable
Sgn
Sin
Sleep
SpanExcluding
SpanIncluding
SpreadSheetAddAutofilter
SpreadsheetAddColumn
SpreadsheetAddFreezePane
SpreadsheetAddImage
SpreadsheetAddInfo
SpreadSheetAddPagebreaks
SpreadsheetAddRow
SpreadsheetAddRows
SpreadsheetAddSplitPane
SpreadsheetCreateSheet
SpreadsheetDeleteColumn
SpreadsheetDeleteColumns
SpreadsheetDeleteRow
SpreadsheetDeleteRows
SpreadsheetFormatCell
SpreadsheetFormatCellRange
SpreadsheetFormatColumn
SpreadsheetFormatColumns
SpreadsheetFormatRow
SpreadsheetFormatRows
SpreadsheetGetCellComment
SpreadsheetGetCellFormula
SpreadsheetGetCellValue
SpreadsheetInfo
SpreadsheetMergeCells
SpreadsheetNew
SpreadsheetRead
SpreadsheetReadBinary
SpreadsheetRemoveSheet
SpreadsheetSetActiveSheet
SpreadsheetSetActiveSheetNumber
SpreadsheetSetCellComment
SpreadsheetSetCellFormula
SpreadsheetSetCellValue

© 2014 Adobe Systems Incorporated. All rights reserved.

2213

Adobe ColdFusion Documentation

SpreadsheetSetColumnWidth
SpreadsheetSetFooter
SpreadsheetSetHeader
SpreadsheetSetRowHeight
SpreadsheetShiftColumns
SpreadsheetShiftRows
SpreadsheetWrite
Sqr
StripCR
StructAppend
StructClear
StructCopy
StructCount
StructDelete
StructEach
StructFilter
StructFind
StructFindKey
StructFindValue
StructGet
StructInsert
StructIsEmpty
StructKeyArray
StructKeyExists
StructKeyList
StructMap
StructNew
StructReduce
StructSort
StructUpdate

© 2014 Adobe Systems Incorporated. All rights reserved.

2214

Adobe ColdFusion Documentation

Second
Description

Extracts the ordinal for the second from a date/time object.
Returns

An integer in the range 0-59.
Category

Date and time functions
Function syntax

Second(date)

See also

DatePart, Hash, Minute
Parameters

Parameter

Description

date

A date/time object

Usage

When passing a date/time object as a string, enclose it in quotation marks. Otherwise, it is interpreted as a number
representation of a date/time object.
Example


Second Example

The time is currently #TimeFormat(Now())#.
We are in hour #Hour(Now())#, Minute #Minute(Now())#
and Second #Second(Now())# of the day.


© 2014 Adobe Systems Incorporated. All rights reserved.

2215

Adobe ColdFusion Documentation

SendGatewayMessage
Description

Sends an outgoing message through a ColdFusion event gateway.
Returns

String. The value returned depends on the gateway type.
Category

Extensibility functions
Function syntax

SendGatewayMessage(gatewayID, data)

See also

GetGatewayHelper; IM gateway message sending commands, SMS Gateway CFEvent structure and commands,
CFML event gateway SendGatewayMessage data parameter, and Sending a message using the
SendGatewayMessage function in Developing an event gateway application in the Developing ColdFusion
Applications
History

ColdFusion MX 7: Added this function.
Parameters

Parameter

Description

gatewayID

Identifier of the gateway to send the message. Must be
the Gateway ID of one of the ColdFusion event
gateway instances configured on the ColdFusion
Administrator Event Gateways section's Gateways
page.

data

A ColdFusion structure. The contents of the structure
depend on the event gateway type, but typically include
a MESSAGE field that contains the message to send
and a field that contains the destination address.

Usage

The SendGatewayMessage function calls the specified gateway's outgoingMessage method. The value returned
by the function depends on the gateway type. The following table describes the return values for standard
ColdFusion gateway types:
Gateway type

© 2014 Adobe Systems Incorporated. All rights reserved.

Return values

2216

Adobe ColdFusion Documentation

Asynchronous CFML

If the message was queued for delivery to the CFC,
returns True; False, otherwise.

Lotus SameTime

If the message or command was successful, returns
OK.If an error occurred, returns a string indicating the
cause.

SMS

If the gateway is in asynchronous mode, returns the
empty string immediately.If the gateway is in
synchronous mode, the function waits for the gateway
to return a response. If the message was successfully
sent to the short message service center (SMSC),
returns the message ID from the SMSC. If an error
occurred, returns a string indicating the cause.

XMPP

If the message or command was successful, returns
OKIf an error occurred, returns a string indicating the
cause.

Example

The following example uses an instance of the CFML gateway to log messages asynchronously to a file. To use this
example, configure an instance of the CFML gateway with the name "Asynch Logger" in the ColdFusion
Administrator. This gateway instance must use a CFC that takes the message and logs it. For sample CFC code,
see Using the CFML event gateway for asynchronous CFCs in the Developing ColdFusion Applications.

Sending an event to the CFML event gateway that is registered in the
ColdFusion Administrator as Asynch Logger.


status = false;
props = structNew();
props.message = "Replace me with a variable with data to log";
status = SendGatewayMessage("Asynch Logger", props);
if (status IS True) WriteOutput(Event Message "#props.message#" has been sent.);


© 2014 Adobe Systems Incorporated. All rights reserved.

2217

Adobe ColdFusion Documentation

SerializeJSON
Description

Converts ColdFusion data into a JSON (JavaScript Object Notation) representation of the data.
Returns

A string that contains a JSON representation of the parameter value.
Category

Conversion functions
Syntax

SerializeJSON(var [, serializeQueryByColumns, useCustomSerializer])

See also

DeserializeJSON, IsJSON, cfajaxproxy, Using data interchange formats in the Developing ColdFusion
Applications, http://www.json.org
History

ColdFusion 11: Added the attribute. useCustomSerializer.
ColdFusion 8: Added function
Parameters

Parameter

Description

var

A ColdFusion data value or variable that represents
one.

serializeQueryByColumns

A Boolean value that specifies how to serialize
ColdFusion queries.
false (the default): Creates an object with two
entries: an array of column names and an array of
row arrays. This format is required by the HTML
format cfgrid tag.
true: Creates an object that corresponds to WDDX
query format.
For more information, see the Usage section.

useCustomSerializer

© 2014 Adobe Systems Incorporated. All rights reserved.

true/false. Whether to use the customSerializer or not.
The default value is true. Note that the custom serialize
will always be used for serialization. If false, the JSON
serialization will be done
using the default ColdFusion behavior.

2218

Adobe ColdFusion Documentation
Usage

This function is useful for generating JSON format data to be consumed by an Ajax application.The SerializeJSO
N function converts ColdFusion dates and times into strings that can be easily parsed by the JavaScript Date object.
The strings have the following format:

MonthName, DayNumber Year Hours:Minutes:Seconds

The SerializeJSON function converts the ColdFusion date time object for October 3, 2007 at 3:01 PM, for
example, into the JSON string "October, 03 2007 15:01:00".The SerializeJSON function with a false serializ
eQueryByColumns parameter (the default) converts a ColdFusion query into a row-oriented JSON Object with the
following elements:
Element

Description

COLUMNS

An array of the names of the columns.

DATA

A two-dimensional array, where:
Each entry in the outer array corresponds to a row of
query data.
Each entry in the inner arrays is a column field value
in the row, in the same order as the COLUMNS array
entries.

For example, the SerializeJSON function with a serializeQueryByColumns parameter value of false conve
rts a ColdFusion query with two columns, City, and State, and two rows of data into following format:

{"COLUMNS":["CITY","STATE"],"DATA":[["Newton","MA"],["San Jose","CA"]]}

The SerializeJSON function with a serializeQueryByColumns parameter value of true converts a
ColdFusion query into a column-oriented JSON Object that is equivalent to the WDDX query representation. The
JSON Object has three elements:
Element

Description

ROWCOUNT

The number of rows in the query.

COLUMNS

An array of the names of the columns.

DATA

An Object with the following:
The keys are the query column names
The values are arrays that contain the column data

The SerializeJSON function with a serializeQueryByColumns parameter value of true converts a
ColdFusion query with two columns, City, and State, and two rows of data into following format:

© 2014 Adobe Systems Incorporated. All rights reserved.

2219

Adobe ColdFusion Documentation

{"ROWCOUNT":2, "COLUMNS":["CITY","STATE"],"DATA":{"City":["Newton","San
Jose"],"State":["MA","CA"]}}

Note
The SerializeJSON function generates an error if you try to convert binary data into JSON
format.

The SerializeJSON function converts all other ColdFusion data types to the corresponding JSON types. It
converts structures to JSON Objects, arrays to JSON Arrays, numbers to JSON Numbers, and strings to JSON
Strings.
Note
ColdFusion internally represents structure key names using all-uppercase characters, and,
therefore, serializes the key names to all-uppercase JSON representations. Any JavaScript that
handles JSON representations of ColdFusion structures must use all-uppercase structure key
names, such as CITY or STATE. You also use the all-uppercase names COLUMNS and DATA as
the keys for the two arrays that represent ColdFusion queries in JSON format.

Example

This example creates a JSON-format data feed with simple weather data for two cities. The data feed is in the form
of a JavaScript application that consists of a single function call that has a JSON Object as its parameter. The
example code does the following:
i. Creates a query object with two rows of weather data. Each row has a city, the current
temperature, and an array of forecast structures, with each with the high, low, and weather
prediction for one day. Normally, datasource provides the data; to keep the example simple, the
example uses the same prediction for all cites and days.
ii. Converts the query to a JSON format string and surrounds it in a JavaScript function call.
Writes the result to the output.
If you view this page in your browser, you see the resulting JavaScript function and JSON parameter. To use the
results of this page in an application, put this file and the example for the DeserializeJSON function in an
appropriate location under your ColdFusion web root, replace the URL in the DeserializeJSON example code
with the correct URL for this page, and run the DeserializeJSONexample.

© 2014 Adobe Systems Incorporated. All rights reserved.

2220

Adobe ColdFusion Documentation







// Construct a weather query with information on cities.
// To simplify the code, we use the same weather for all cities and days.
// Normally this information would come from a data source.
weatherQuery = QueryNew("City, Temp, Forecasts");
QueryAddRow(weatherQuery, 2);
theWeather=StructNew();
theWeather.High=73;
theWeather.Low=53;
theWeather.Weather="Partly Cloudy";
weatherArray=ArrayNew(1);
for (i=1; i<=5; i++) weatherArray[i]=theWeather;
querySetCell(weatherQuery, "City", "Newton", 1);
querySetCell(weatherQuery, "Temp", "65", 1);
querySetCell(weatherQuery, "ForeCasts", weatherArray, 1);
querySetCell(weatherQuery, "City", "San Jose", 2);
querySetCell(weatherQuery, "Temp", 75, 2);
querySetCell(weatherQuery, "ForeCasts", weatherArray, 2);
// Convert the query to JSON.
// The SerializeJSON function serializes a ColdFusion query into a JSON
// structure.
theJSON = SerializeJSON(weatherQuery);
// Wrap the JSON object in a JavaScript function call.
// This makes it easy to use it directly in JavaScript.
writeOutput("onLoad( "&theJSON&" )");



ColdFusion 11 has enhanced the JSON serialization to support the following new features:
1.
2.
3.
4.

Case preservation of struct keys
Data type preservation
Key-value serialization of CF Query
Custom serializers

Case preservation of struct keys

Currently, the cases for struct keys are not preserved in ColdFusion. The struct keys get converted to upper case
automatically.
For instance, consider the following code:

© 2014 Adobe Systems Incorporated. All rights reserved.

2221

Adobe ColdFusion Documentation


data = {empName="James", age="26"};
serializedStr = serializeJSON(data);
writeoutput(serializedStr);


In ColdFusion 10 and earlier vesions, the output generated by the above code will be:

{'EMPNAME'='', 'AGE'=''}

For the release after ColdFusion 11, the output generated will be:

{'empName'='', 'age'=''}

To enable case preservation of struct keys at the application level, modify the application.cfc file by setting:

this.serialization.preservecaseforstructkey = true

The default behavior is true. To switch back to the old behavior, set this value to false.
To enable case preservation of struct keys at the server level, perform the following tasks:
1. From the ColdFusion Administrator page, click Server Settings > Settings
2. Click Preserve case for Struct keys for Serialization

Note that this setting is used during compilation of the CFML page and therefore if this flag is changed (in the
administrator or programmatically), any pages relying on the change must be recompiled. This is done typically by
simply editing the file (make any change at all) and re-executing it. If "trusted cache" is enabled in the ColdFusion
Administrator, you must clear the template cache (of at least those affected files), which can also be done from
within the ColdFusion Administrator Caching page.
Data type preservation

The ColdFusion language is typeless and does not evaluate or preserve the type information at the time of code
generation. At runtime, ColdFusion tries to make its best guess to determine the datatype, which may cause some
unexpected behavior. For example, at the time of JSON serialization, ColdFusion attempts at converting a string to a

© 2014 Adobe Systems Incorporated. All rights reserved.

2222

Adobe ColdFusion Documentation

number. If the attempt is successful, then the passed data type is treated as number irrespective of whether you
wanted it to be a string or not.
Starting from ColdFusion 11, the data type is preserved during the code execution time for Query and CFCs.
SerializeJSON considers datatypes defined in the database for serialization. If the database defines a column as a
string, any number inserted into the column will still be treated as a string by SerializeJSON.
For instance,


select * from users

#SerializeJSON(qry_Users)#


Serializing query

SerializeJSON honors the datatypes of columns defined in the database. The same would work for in-memory
queries created using QueryNew() as long as the datatype is specified for the columns.
Consider the CFC property type example:
Employee.cfc

Component accessors="true"
{
property string empName;
property numeric age;
property string dept;
}

Index.cfm


emp = new Employee({empName="James", age=26, dept="000"});
writeOutput(SerializeJSON(emp));


OUTPUT: {"dept":"000","empName":"James","age":26}
In the previous version of ColdFusion, 000 will be automatically coverted to a number at runtime.

© 2014 Adobe Systems Incorporated. All rights reserved.

2223

Adobe ColdFusion Documentation

Additional format for query serialization

ColdFusion 10 supports 2 different ways to serialize a query object to a JSON string:
Using row
Using column
However, these 2 types are not the easiest to use with AJAX applications. ColdFusion 11 introduces a new way to
serialize a query object to a JSON string:
Using struct
All the 3 ways, can be defined at the application-level and will be used in serialized JSON functions if the type is not
defined explicitly. In application.cfc, define:

this.serialization.serializeQueryAs = [row|column|struct]

Note that "struct" is also available to be accessible through an AJAX argument. Now you can pass struct in an
AJAX URL to serialize a query object as struct.
ColdFusion 11 now supports serializing the query object to a JSON string that is AJAX-friendly:

[
{"colour":"red","id":1},
{"colour":"green","id":2},
{"colour":"blue","id":3}
]

The current SerializeJSON function has been enhanced to support the 'key-value' format.

SerializeJSON( Object o, Object serializeQueryByColumns, boolean secure, boolean
useCustomSerializer);

If you are using the serialzeQueryAs property in application.cfc, you do not need to specify the
serialzeQueryByColumns property unless you need to override the functionality.
Custom serializers

In the application.cfc file, you can register your own handler for serializing and deserializing the complex types. If the
serializer is not specified, ColdFusion uses the default mechanism for serialization. For more information see Suppor
t for pluggable serializer and deserializer.

© 2014 Adobe Systems Incorporated. All rights reserved.

2224

Adobe ColdFusion Documentation

SessionInvalidate
Description

Invalidates or cleans up the current session.
Note
The sessionInvalidate() method does not invalidate the underlying J2EE session.

Returns

None
Category

Display and formatting functions
Syntax

sessionInvalidate()
See also

SessionRotate
History

ColdFusion 10: Added this function.
Parameters

None
Usage

Use this function to invalidate the existing session.
Example

Application.cfc






sessionInvalidate.cfm

© 2014 Adobe Systems Incorporated. All rights reserved.

2225

Adobe ColdFusion Documentation









Set session.name = BOB  

Invalidate the session


© 2014 Adobe Systems Incorporated. All rights reserved.

2226

Adobe ColdFusion Documentation

SessionRotate
Description

Renews the session when started. For example, you want to generate a new session after a successful login. It
prevents session attacks, because the session before and after a successful authentication is different.The method,
Creates a session
Copies the data from the old session to the new session
Invalidates the old session
Invalidates or overwrites the old session cookies
Creates new session cookies if the old session cookies are invalidated
Copies and updates client storage data to new session keys
Does not rotate jsessionid when JEE sessions are enabled. This only works with ColdFusion
sessions (CFID, CFTOKEN).
Returns

None
Category

Display and formatting functions
Syntax

SessionRotate()
See also

SessionInvalidate
History

ColdFusion 10: Added this function.
Parameters

None
Usage

Use this function to rotate the session.
Example

Application.cfc






sessionRotate.cfm

© 2014 Adobe Systems Incorporated. All rights reserved.

2227

Adobe ColdFusion Documentation









Set session.name = BOB  

Rotate the session


© 2014 Adobe Systems Incorporated. All rights reserved.

2228

Adobe ColdFusion Documentation

SessionGetMetaData
Description

Returns meta data related to the current session.
Returns

Meta data structure related to the current session
Structure element

Description

starttime

The start time of the current session.

Syntax

sessionGetMetaData()
History

ColdFusion 10: Added this function.
Example



© 2014 Adobe Systems Incorporated. All rights reserved.

2229

Adobe ColdFusion Documentation

SetEncoding
Description

Sets the character encoding (character set) of Form and URL scope variable values; used when the character
encoding of the input to a form, or the character encoding of a URL, is not in UTF-8 encoding.
Returns

None
Category

International functions, System functions
Function syntax

SetEncoding(scope_name,charset)

See also

GetEncoding, cfcontent, cfprocessingdirective, URLDecode, URLEncodedFormat; Locales in the Devel
oping ColdFusion Applications
History

ColdFusion MX: Added this function.
Parameters

Parameter
scope_name

charset

Description
url
form
The character encoding in which text in the scope
variables is encoded. The following list includes
commonly used values:
utf-8
iso-8859-1
windows-1252
us-ascii
shift_jis
iso-2022-jp
euc-jp
euc-kr
big5
euc-cn
utf-16

Usage

© 2014 Adobe Systems Incorporated. All rights reserved.

2230

Adobe ColdFusion Documentation

Use this function when the character encoding of the input to a form or the character encoding of a URL is not in
UTF-8 encoding. For example, Traditional Chinese characters are often in Big5 encoding. This function resets URL
and Form variables, so you should call it before using these variables (typically, in the Application.cfm page or
Application.cfc file). Calling this function first also avoids interpreting the characters of the variables incorrectly. For
more information on character encoding, see the following web pages:
www.w3.org/International/O-charset.html provides general information on character encoding and the web,
and has several useful links.
www.iana.org/assignments/character-sets is a complete list of character sets names used on the Internet,
maintained by the Internet Assigned Numbers Authority.
java.sun.com/j2se/1.4.1/docs/guide/intl/encoding.doc.html lists the character encoding that Java 1.4.1, and
therefore the default ColdFusion configuration, can interpret. If you use a JVM that does not conform to the
Sun Java 2 Platform, Standard Edition, v 1.4.1, the supported locales may differ. The list uses Java internal
names, not the IANA character encoding names that you normally use in the SetEncoding charset param
eter and other ColdFusion attributes and parameters. Java automatically converts standard IANA names to
its internal names as needed.
Example










SetEncoding("url", "big5");
WriteOutput("URL.XXX is " & URL.xxx & "
");
WriteOutput("URL.YYY is " & URL.yyy & "
");
theEncoding = GetEncoding("URL");
WriteOutput("The URL variables were decoded using '" &
theEncoding & "' encoding.");
WriteOutput("The encoding is " & theEncoding);



© 2014 Adobe Systems Incorporated. All rights reserved.

2231

Adobe ColdFusion Documentation

SetLocale
Description

Sets the country/language locale for ColdFusion processing and the page returned to the client. The locale value
determines the default format of date, time, number, and currency values, according to language and regional
conventions.
Returns

The locale value prior to setting the new locale, as a string.
Category

International functions, System functions
Function syntax

SetLocale(new_locale)

See also

GetHttpTimeString, GetLocale, GetLocaleDisplayName; Locales in the Developing ColdFusion
Applications
History

ColdFusion MX 7: Added support for all locales supported by the ColdFusion Java runtime.ColdFusion MX:
Changed formatting behavior: this function might return a different value than in earlier releases. This function
uses Java standard locale determination and formatting rules on all platforms.
Deprecated the Spanish (Mexican) locale option. It might not work, and it might cause an error, in later
releases.
Changed the Spanish (Modern) option: it now sets the locale to Spanish (Standard).
Parameters

Parameter

Description

new_locale

The name of a locale; for example, "English (US)"

Usage

You can specify any locale name that is listed in the Server.Coldfusion.SupportedLocales variable. This variable is a
comma-delimited list of all locale names supported by the JVM, plus the locale names that were required by
ColdFusion prior to ColdFusion MX 7.The following locale names were used in ColdFusion releases through
ColdFusion MX 6.1, and continue to be supported. If you use any of these values in the SetLocale function, the Ge
tLocale function returns the name you set, not the corresponding Java locale name.
Chinese (China)

French (Belgian)

Korean

Chinese (Hong Kong)

French (Canadian)

Norwegian (Bokmal)

© 2014 Adobe Systems Incorporated. All rights reserved.

2232

Adobe ColdFusion Documentation

Chinese (Taiwan)

French (Standard)

Norwegian (Nynorsk)

Dutch (Belgian)

French (Swiss)

Portuguese (Brazilian)

Dutch (Standard)

German (Austrian)

Portuguese (Standard)

English (Australian)

German (Standard)

Spanish (Modern)

English (Canadian)

German (Swiss)

Spanish (Standard)

English (New Zealand)

Italian (Standard)

Swedish

English (UK)

Italian (Swiss)

English (US)

Japanese

ColdFusion determines the locale value as follows:
By default, ColdFusion uses the JVM locale, and the default JVM locale is the operating system locale. You
can set JVM locale value explicitly in ColdFusion in the ColdFusion Administrator Java and JVM Settings
page JVM Arguments field; for example:

-Duser.language=de -Duser.region=DE.

A locale set using the SetLocale function persists for the current request or until it is reset by another SetL
ocale function in the request.
If a request has multiple SetLocale functions, the current locale setting affects how locale-sensitive
ColdFusion tags and functions, such as the functions that start with LS format data. The last SetLocale func
tion that ColdFusion processes before sending a response to the requestor (typically the client browser)
determines the value of the response Content-Language HTTP header. The browser that requested the
page displays the response according to the rules for the language specified by the Content-Language he
ader.
ColdFusion ignores any SetLocale functions that follow a cfflush tag.
Because this function returns the previous locale setting, you can save the original locale value. You can
restore the original locale by calling SetLocaleagain with the saved variable. For example, the following line
saves the original locale ins a Session variable:



The variable server.ColdFusion.SupportedLocales is initialized at startup with a comma-delimited list
of the locales that ColdFusion and the operating system support. If you call SetLocalewith a locale that is
not in the list, the call generates an error.

© 2014 Adobe Systems Incorporated. All rights reserved.

2233

Adobe ColdFusion Documentation

Note
ColdFusion uses the Spanish (Standard) formats for Spanish (Modern) and Spanish
(Standard).

Example

SetLocale Example
SetLocale sets the locale to the specified new locale for the current session.
A locale encapsulates the set of attributes that govern the display and
formatting of date, time, number, and currency values.
The locale for this system is #GetLocale()#
the old locale was #SetLocale("English (UK)")#
The locale is now #GetLocale()#

© 2014 Adobe Systems Incorporated. All rights reserved.

2234

Adobe ColdFusion Documentation

SetProfileString
Description

Sets the value of a profile entry in an initialization file.
Returns

An empty string, upon successful execution; otherwise, an error message.
History

ColdFusion 11: Added the encoding attribute.
Category

System functions
Function syntax

SetProfileString(iniPath, section, entry, value, encoding)

See also

GetProfileSections, GetProfileString
Parameters

Parameter

Description

iniPath

Absolute path of initialization file

section

Section of the initialization file in which the entry is to
be set

entry

Name of the entry to set

value

Value to which to set the entry

encoding

Encoding of the initialization (ini) file. For instance
"UTF-8"

Example

SetProfileString Example
This example uses SetProfileString to set the time-out value in an
initialization file. Enter the full path of your initialization
file, specify the time-out value, and submit the form.



© 2014 Adobe Systems Incorporated. All rights reserved.

2235

Adobe ColdFusion Documentation


"boot loader">
= FORM.MyTimeout>
GetProfileString(IniPath, Section, "timeout")>




Setting the time-out value to #MyTimeout#


Value returned from SetProfileString:
#code#


The time-out value should be greater than zero in order to
provide time for user response.



The time-out value in your initialization file is already
#MyTimeout#.



Boot Loader
The time-out is set to: #timeout#.
Default directory is: #default#.





© 2014 Adobe Systems Incorporated. All rights reserved.

2236

Adobe ColdFusion Documentation



Full Path of Init File



Time-out








© 2014 Adobe Systems Incorporated. All rights reserved.

2237

Adobe ColdFusion Documentation

SetVariable
Description

Sets a variable in the name parameter to the value of the value parameter.
Returns

The new value of the variable.
Category

Dynamic evaluation functions
Function syntax

SetVariable(name, value)

See also

DE, Evaluate, IIf
Parameters

Parameter

Description

name

Variable name

value

A string, the name of a string, or a number

Usage

You can use direct assignment statements in place of this function to set values of dynamically named variables. To
do so, put the dynamically named variable in quotation marks and number signs (#); for example:




Also, the following lines are equivalent:


SetVariable("myVar" & i, myVal)

For more information, see Using Expressions and Number Signs in the Developing ColdFusion Applications.
Example

© 2014 Adobe Systems Incorporated. All rights reserved.

2238

Adobe ColdFusion Documentation

SetVariable Example








Your variable, #varName#
The value of #varName# is #varNameValue#



© 2014 Adobe Systems Incorporated. All rights reserved.

2239

Adobe ColdFusion Documentation

Sgn
Description

Determines the sign of a number.
Returns

1, if number is positive.
0, if number is 0.
-1, if number is negative.
Category

Mathematical functions
Function syntax

Sgn(number)

See also

Abs
Parameters

Parameter

Description

number

A number

Example

Sgn Example
Sgn determines the sign of a number. Returns 1 if number is positive;
0 if number is 0; -1 if number is negative.
Sgn(14): #Sgn(14)#
Sgn(21-21): #Sgn(21-21)#
Sgn(-0.007): #Sgn(-0.007)#

© 2014 Adobe Systems Incorporated. All rights reserved.

2240

Adobe ColdFusion Documentation

Sin
Description

Calculates the sine of an angle that is entered in radians.
Returns

A number; the sine of the angle.
Category

Mathematical functions
Function syntax

Sin(number)

See also

ASin, Cos, ACos, Tan, Atn, Pi
Parameters

Parameter

Description

number

Angle, in radians for which to calculate the sine.

Usage

The range of the result is -1 to 1. To convert degrees to radians, multiply degrees by p/180. To convert radians to
degrees, multiply radians by 180/p.
Note
Because the function uses floating point arithmetic, it returns a very small number (such as
6.12323399574E-017) for angles that should produce 0. To test for a 0 value, check whether the
value is less than 0.0000000000001.

Example

© 2014 Adobe Systems Incorporated. All rights reserved.

2241

Adobe ColdFusion Documentation

Sin Example











Sin(#FORM.sinNum#) = #sinValue#





You must enter a numeric angle in degrees.



Enter an angle in degrees to get its sine:





  


© 2014 Adobe Systems Incorporated. All rights reserved.

2242

Adobe ColdFusion Documentation

Sleep
Description

Causes the current thread to stop processing for a specified period of time.
Returns

Does not return a value.
Category

System functions
Syntax

Sleep(duration)

See also

cfthread, Using ColdFusion Threads in the Developing ColdFusion Applications
History

ColdFusion 8: Added function
Parameters

Parameter

Description

duration

Time, in milliseconds, to stop processing the thread.

Description

The Sleep function is useful when one thread must wait until another thread performs some action. The thread that
must wait uses the Sleep function to stop processing for a time, and, when it awakens, checks to see if the other
thread is ready. If it is not, the thread can sleep again. This type of action is useful, for example, when one thread
must wait for another thread to complete initialization operations that apply to both threads.The Sleep function
behaves identically to the cfthread tag with an action attribute value of sleep.
Example

The following example has two threads. The second thread (threadB) uses the sleep function to ensure that the
first thread (threadA) has completed before it starts processing.

© 2014 Adobe Systems Incorporated. All rights reserved.

2243

Adobe ColdFusion Documentation











thread.sleepTimes=0;
thread.initialized=false;
while ((threadA.Status != "COMPLETED") && (threadA.Status
!= "TERMINATED")) {
sleep(500);
thread.sleeptimes++;
}
// Only do the post-initilization code if the threadA completed.
If (threadA.Status == "COMPLETED") {
thread.initialized=true;
// Post-initialization code would go here.
}







threadA index value: #threadA.j#

threadA status: #threadA.Status#

threadB status: #threadB.Status#

threadB sleepTimes: #threadB.sleepTimes#

threadB initialized: #threadB.initialized#



© 2014 Adobe Systems Incorporated. All rights reserved.

2244

Adobe ColdFusion Documentation

SpanExcluding
Description

Gets characters from a string_,_ from the beginning and stops when it encounters any of the characters in a
specified set of characters. The search is case sensitive. For example, SpanExcluding("MyString", "inS") excludes
"String" from "MyString" and returns "My". Because, in the string "MyString", after "My", the character 'S' (which is
present in the second string "inS") is encountered.
Returns

A string; characters from string, from the beginning to a character that is in set.
Category

String functions
Function syntax

SpanExcluding(string, set)

See also

GetToken, SpanIncluding; Caching parts of ColdFusion pages in Optimizing ColdFusion applications in the Dev
eloping ColdFusion Applications
Parameters

Parameter

Description

string

A string or a variable that contains one

set

A string or a variable that contains one. Must contain
one or more characters

Example

© 2014 Adobe Systems Incorporated. All rights reserved.

2245

Adobe ColdFusion Documentation

SpanExcluding Example

Your string was #FORM.myString#
Your set of characters was #FORM.mySet#
Your string up until one of the characters in the set is:
#SpanExcluding(FORM.myString, FORM.mySet)#

Returns all characters from string from beginning to a character
from the set of characters. The search is case-sensitive.

Enter a string:


And a set of characters:






© 2014 Adobe Systems Incorporated. All rights reserved.

2246

Adobe ColdFusion Documentation

SpanIncluding
Description

Gets characters from a string_,_ from the beginning and stops when it encounters any character that is not in a
specified set of characters. The search is case sensitive. For example, SpanIncluding("mystring", "mystery") returns
"mystr". Because, in the string "mystring", after "mystr", the character 'i' (which is not present in the second string
"mystery") is encountered.
Returns

A string; characters from string, from the beginning to a character that is not in set.
Category

String functions
Function syntax

SpanIncluding(string, set)

See also

GetToken, SpanExcluding; Caching parts of ColdFusion pages in Optimizing ColdFusion applications in the Dev
eloping ColdFusion Applications
Parameters

Parameter

Description

string

A string or a variable that contains the search string.

set

A string or a variable that contains a set of characters.
Must contain one or more characters.

Example

© 2014 Adobe Systems Incorporated. All rights reserved.

2247

Adobe ColdFusion Documentation

SpanIncluding Example

Your string was #FORM.myString#
Your set of characters was #FORM.mySet#
Your string, until the characters in the set have been found, is:
#SpanIncluding(FORM.myString, FORM.mySet)#

Returns characters of a string, from beginning to a character
that is not in set. The search is case-sensitive.

Enter a string:


And a set of characters:






© 2014 Adobe Systems Incorporated. All rights reserved.

2248

Adobe ColdFusion Documentation

SpreadsheetAddColumn
Description

Adds a column or column data to an Excel spreadsheet object.
Returns

Does not return a value.
Category

Microsoft Office Integration
Function syntax

SpreadsheetAddColumn(SpreadsheetObj, data[, startRow, startColumn, insert],
datatype);

See also

SpreadsheetAddImage, SpreadsheetAddRow, SpreadsheetAddRows, SpreadsheetDeleteColumn, Sprea
dsheetDeleteColumns, SpreadsheetFormatColumn, SpreadsheetFormatColumns, SpreadsheetShift
Columns
History

ColdFusion 11: Added the datatype attribute.
ColdFusion 9: Added the function.
Parameters

Parameter

Description

spreadsheetObj

The Excel spreadsheet object to which to add the
column.

data

A comma delimited list of cell entries, one per row
being added to the column.

startRow

This parameter is optional.The number of the row at
which to start adding the column data. If insert="tru
e", all rows in the column above the start row have
empty cells.If you omit this parameter the columns are
inserted starting at the first row, following the last
current column, and you cannot specify a column.

startColumn

This parameter is optional.The number of the column in
which to add the column data.

© 2014 Adobe Systems Incorporated. All rights reserved.

2249

Adobe ColdFusion Documentation

insert

This parameter is optional.A Boolean value specifying
whether to insert a column. If false, the function
replaces data in the specified column entries.

datatype

The data type denoted by the column. The allowed
values are NUMERIC, DATE, and STRING.

Usage

The spreadsheetaddcolumn function can accept either two or five arguments.You can specify the spreadsheet
addcolumn function using two parameters as follows:



You can specify the spreadsheetaddcolumn function using five parameters as follows:



Example

The following example creates an Excel spreadsheet object from a query and inserts a new column 2, with data
starting at row 3. The existing columns 2 and greater increment by one.



SELECT CORNUMBER,DEPT_ID,COURSE_ID,CORNAME
FROM COURSELIST


///We need an absolute path, so get the current directory path.
theFile=GetDirectoryFromPath(GetCurrentTemplatePath()) & courses.xls";
//Create a new Spreadsheet object and add the query data.
theSheet = SpreadsheetNew("CourseData");
SpreadsheetAddRows(theSheet,courses);
//Insert a new second column to the sheet, with data starting in row 3.
SpreadsheetAddColumn(theSheet,
"Basic,Intermediate,Advanced,Basic,Intermediate,Advanced,Basic,Intermediate,Advance
d"
,3,2,true);




© 2014 Adobe Systems Incorporated. All rights reserved.

2250

Adobe ColdFusion Documentation

SpreadsheetAddImage
Description

Adds an image to an Excel spreadsheet object.
Returns

Does not return a value.
Category

Microsoft Office Integration
Function syntax

SpreadsheetAddImage(SpreadsheetObj, imageFilePath, anchor)
SpreadsheetAddImage(SpreadsheetObj, imageData, imageType, anchor)

See also

SpreadsheetAddColumn, SpreadsheetAddRow, SpreadsheetAddRows
History

ColdFusion 9: Added the function.
Parameters

Parameter

Description

spreadsheetObj

The Excel spreadsheet object to which to add the
column.

anchor

The image location, as a comma delimited list in either
of the following formats:
startRow,startColumn,endRow,endColumn
startXPosition,startYPosition,endXPosit
ion,endYPositions,startRow,startColumn,
endRow,endColumn
The first format specifies only the row and column
numbers, the second also specifies the positions in
the cell, using pixel X and Y coordinates relative to
the cell upper left corner. If you use the first format,
the image corner positions within the top left and
bottom right cell are 0,0 and ,0,255.

imageData

A ColdFusion image object.

imageFilePath

The absolute path to the image file.

© 2014 Adobe Systems Incorporated. All rights reserved.

2251

Adobe ColdFusion Documentation

imageType

The image format, one of the following:
jpg or jpeg
png
dib

Usage
Example

The following example creates a PNG format chart, puts it in a new spread sheet as rows 5-12 and column 5-10,
and saves the sheet to disk.













theDir=GetDirectoryFromPath(GetCurrentTemplatePath());
SpreadsheetObj=SpreadsheetNew();
SpreadsheetAddImage(SpreadsheetObj,test,"png","5,5,12,10");



© 2014 Adobe Systems Incorporated. All rights reserved.

2252

Adobe ColdFusion Documentation

SpreadsheetAddFreezePane
Description

Locks or freezes specific rows or columns in the worksheet.
Returns

Does not return a value.
Category

Microsoft Office Integration
Function syntax

SpreadsheetAddFreezePane(spreadsheetobj, freezcol, freezrow[, col, row])

See also

SpreadsheetAddColumn, SpreadsheetAddImage, SpreadsheetAddRow, SpreadsheetDeleteRow, Spread
sheetDeleteRows, SpreadsheetFormatRow, SpreadsheetFormatRows, SpreadsheetShiftRows
History

ColdFusion 9: Added the function.
Parameters

Parameter

Description

spreadsheetobj

The Excel spreadsheet object to which to add the
freeze pane.

freezcol

Specifies the column boundary of the freeze pane. The
columns contained within the column boundary are
frozen, while the rest of the worksheet scrolls.

freezrow

Specifies the row boundary of the freeze pane. The
rows contained within the row boundary are frozen,
while the rest of the worksheet scrolls.

col

This parameter is optional.The column that should
appear next to the freezcol that you specify. This
parameter is useful in hiding data. For example, in a
worksheet, you can specify column 5 to appear
immediately after column 2, and hide column 3 and
column 4.

© 2014 Adobe Systems Incorporated. All rights reserved.

2253

Adobe ColdFusion Documentation

row

This parameter is optional. The row that should appear
next to the freezrow that you specify. This parameter
is useful in hiding data. For example, in a worksheet,
you can specify row 10 to appear immediately after row
7, and hide row 8 and row 9.

Usage

You can keep an area of the worksheet visible while scrolling to another area of the worksheet by freezing panes.
When you freeze a pane, you lock or freeze specific rows and columns in the worksheet. The rows and columns that
are frozen in the worksheet are indicated by a solid line.
Note
You cannot split the pane into two worksheet areas.

Example

The following example freezes the spreadsheet at column 3 and row 2 of the worksheet.

SpreadSheetAddFreezePane(SpreadsheetObj,3,2);

The following example freezes the spreadsheet at column 3 and row 2, and hides data in column 4 and rows 3 to
10.

SpreadSheetAddFreezePane(SpreadsheetObj,3,2,5,10);

© 2014 Adobe Systems Incorporated. All rights reserved.

2254

Adobe ColdFusion Documentation

SpreadsheetAddInfo
Description

Sets document properties for a new spreadsheet or modifies properties for an existing spreadsheet.
Returns

This function does not return a value.
Category

Microsoft Office Integration
Function syntax

SpreadsheetAddInfo(spreadsheetobj, property_struct)

See also

SpreadsheetAddColumn, SpreadsheetAddImage, SpreadsheetAddRow, SpreadsheetDeleteRow, Spread
sheetDeleteRows, SpreadsheetFormatRow, SpreadsheetFormatRows, SpreadsheetShiftRows
History

ColdFusion 9: Added the function.
Parameters

Parameter

Description

spreadsheetobj

The Excel spreadsheet object from which to get the
value.

property_struct

The following properties of the spreadsheet can be
modified or set:
AUTHOR
CATEGORY
LASTAUTHOR
COMMENTS
KEYWORDS
MANAGER
COMPANY
SUBJECT
TITLE

Usage

This function is supported by Microsoft Office Excel 2007 (.xlsx) and Microsoft Office 2003 (.xls).
Example

© 2014 Adobe Systems Incorporated. All rights reserved.

2255

Adobe ColdFusion Documentation










© 2014 Adobe Systems Incorporated. All rights reserved.

2256

Adobe ColdFusion Documentation

SpreadsheetAddRow
Description

Adds a row to an Excel spreadsheet object.
Returns

Does not return a value.
Category

Microsoft Office Integration
Function syntax

SpreadsheetAddrow(spreadsheetObj, data [,row, column, insert, datatype])

See also

SpreadsheetAddColumn, SpreadsheetAddImage, SpreadsheetAddRows, SpreadsheetDeleteRow, Sprea
dsheetDeleteRows, SpreadsheetFormatRow, SpreadsheetFormatRows, SpreadsheetShiftRows
History

ColdFusion 11: Added the datatype attribute.
ColdFusion 9: Added the function.
Parameters

Parameter

Description

spreadsheetObj

The Excel spreadsheet object to which to add the
column.

data

A comma delimited list of cell entries, one per column.

row

The number of the row to insert. The row numbers of
any existing rows with numbers equal to or greater than
this value are incremented by one. If you specify a
value for this parameter, you must also specify a value
for column.If you omit this parameter the rows are
inserted following the last current row, and you cannot
specify a column.

column

The number of the column in which to add the column
data. All columns in the row to the left of the start
column have empty cells. If you specify a value for this
parameter, you must also specify a value for row.

© 2014 Adobe Systems Incorporated. All rights reserved.

2257

Adobe ColdFusion Documentation

insert

This parameter is optional. The default value is true.A
Boolean value specifying whether to insert a row. If fa
lse, the function replaces data in the specified row
entries.

datatype

The data type denoted by the row. The allowed values
are NUMERIC, DATE, and STRING.

Usage
Example

The following example adds a row of data as row 10. The data starts at column 2, and any existing row numbers 10
and higher increment by one.



SELECT CORNUMBER,DEPT_ID,COURSE_ID,CORNAME
FROM COURSELIST


///We need an absolute path, so get the current directory path.
theFile=GetDirectoryFromPath(GetCurrentTemplatePath()) & courses.xls";
//Create a new Spreadsheet object and add the query data.
theSheet = SpreadsheetNew("CourseData");
SpreadsheetAddRows(theSheet,courses);
//Insert a new eighth row to the sheet, with data starting in column 1.
SpreadsheetAddRow(theSheet,"150,ENGL,95,Poetry 1",8,1);




© 2014 Adobe Systems Incorporated. All rights reserved.

2258

Adobe ColdFusion Documentation

SpreadsheetAddRows
Description

Adds multiple rows from a query to an Excel spreadsheet object.
Returns

Does not return a value.
Category

Microsoft Office Integration
Function syntax

SpreadsheetAddrows(spreadsheetObj, data[, row, column, insert], datatype)

See also

SpreadsheetAddColumn, SpreadsheetAddImage, SpreadsheetAddRow, SpreadsheetDeleteRow, Spread
sheetDeleteRows, SpreadsheetFormatRow, SpreadsheetFormatRows, SpreadsheetShiftRows
History

ColdFusion 11: Added the datatype attribute
ColdFusion 9: Added the function.
Parameters

Parameter

Description

spreadsheetObj

The Excel spreadsheet object to which to add the
column.

data

A query object with the row data or an array.

row

The number of the row at which to insert the rows. The
row numbers of any existing rows with numbers equal
to or greater than this value are incremented by
number of added rows. If you specify a value for this
parameter, you must also specify a value for
{{column.}}If you omit this parameter the rows are
inserted following the last current row.

column

The number of the column in which to add the column
data. All columns in the row to the left of the start
column have empty cells. If you specify a value for this
parameter, you must also specify a value for row.

© 2014 Adobe Systems Incorporated. All rights reserved.

2259

Adobe ColdFusion Documentation

insert

This parameter is optional. The default value is true.A
Boolean value specifying whether to insert a row. If fa
lse, the function replaces data in the specified row
entries.

datatype

The data type denoted by the row. The allowed values
are NUMERIC, DATE, and STRING.

Example

The following example creates a spreadsheet by creating a new Excel spreadsheet object and using the AddRows f
unction to add the data from a query.



SELECT CORNUMBER,DEPT_ID,COURSE_ID,CORNAME
FROM COURSELIST


///We need an absolute path, so get the current directory path.
theFile=GetDirectoryFromPath(GetCurrentTemplatePath()) & courses.xls";
//Create a new Excel spreadsheet object and add the query data.
theSheet = SpreadsheetNew("CourseData");
SpreadsheetAddRows(theSheet,courses);
SpreadsheetAddRows(theSheet,["1,a", "2,B,b"]);




The following example shows the usage of the datatype parameter:








© 2014 Adobe Systems Incorporated. All rights reserved.

2260

Adobe ColdFusion Documentation

SpreadsheetAddSplitPane
Description

Splits panes into four separate worksheet areas.
Returns

Does not return a value.
Category

Microsoft Office Integration
Function syntax

SpreadsheetAddSplitPane(spreadsheetobj, x-position, y-position, splitcol, splitrow
[,position])

See also

SpreadsheetAddColumn, SpreadsheetAddImage, SpreadsheetAddRow, SpreadsheetDeleteRow, Spread
sheetDeleteRows, SpreadsheetFormatRow, SpreadsheetFormatRows, SpreadsheetShiftRows
History

ColdFusion 9: Added the function.
Parameters

Parameter

Description

spreadsheetobj

The Excel spreadsheet object to which to add the split
pane.

x-position

Specifies the x-axis position of the first quadrant. The
x-position value is 1/20th the value of a pixel in the
worksheet.

y-position

Specifies the y-axis position of the first quadrant. The
y-position value is 1/20th the value of a pixel in the
worksheet.

splitcol

Specifies the columns that appear in quadrant 2 of the
spreadsheet.

splitrow

Specifies the rows that appear in quadrant 3 of the
spreadsheet.

© 2014 Adobe Systems Incorporated. All rights reserved.

2261

Adobe ColdFusion Documentation

position

This attribute is optional.Specifies the position to apply
the split bar to split the pane. It can be one of the
following:
LOWER_LEFT
LOWER_RIGHT
UPPER_RIGHT
UPPER_LEFT

Usage

You can split the pane into four worksheet areas in the spread sheet. The split is applied at the pixel level. You can
adjust the worksheet area by dragging the split bar, as required.
Note
You cannot split the pane into two worksheet areas.

Example

The following example splits the spreadsheet into four quadrants. The x and y positions are at 2000 and 2000
values. Column 5 of the spreadsheet appears in quadrant 2; and row 7 of the spreadsheet appears in quadrant 7.
The split bar appears at the lower left side of the spreadsheet.

SpreadSheetAddSplitPane(spreadsheetobj, 2000, 2000, 5, 7, LOWER_LEFT );

© 2014 Adobe Systems Incorporated. All rights reserved.

2262

Adobe ColdFusion Documentation

SpreadsheetCreateSheet
Description

Creates an additional spreadsheet.
Returns

Does not return a value.
Category

Microsoft Office Integration
Function syntax

SpreadsheetCreateSheet(spreadsheetObj, [sheetname])

See also

SpreadsheetAddColumn, SpreadsheetDeleteColumns, SpreadsheetDeleteRow, SpreadsheetDeleteR
ows, SpreadsheetFormatColumn, SpreadsheetFormatColumns, SpreadsheetShiftColumns, Spreadshe
etSetActiveSheet
History

ColdFusion 9: Added the function.
Parameters

Parameter

Description

spreadsheetObj

The Excel spreadsheet object from which you create
the additional sheet.

sheetname

Name of the new sheet. This is optional.

Example

The following example creates two sheets: CourseData and EvaluationSheet.

© 2014 Adobe Systems Incorporated. All rights reserved.

2263

Adobe ColdFusion Documentation



SELECT CORNUMBER,DEPT_ID,COURSE_ID,CORNAME
FROM COURSELIST


///We need an absolute path, so get the current directory path.
theFile=GetDirectoryFromPath(GetCurrentTemplatePath()) & courses.xls";
//Create a new Excel spreadsheet object and add the query data.
theSheet = SpreadsheetNew("CourseData");
SpreadsheetAddRows(theSheet,courses);
//Add a new sheet.
SpreadsheetCreateSheet (theSheet, "EvaluationSheet");




© 2014 Adobe Systems Incorporated. All rights reserved.

2264

Adobe ColdFusion Documentation

SpreadsheetDeleteColumn
Description

Deletes the data from a column of an Excel spreadsheet object. It does not delete the column.
Returns

Does not return a value.
Category

Microsoft Office Integration
Function syntax

SpreadsheetDeleteColumn(spreadsheetObj, column)

See also

SpreadsheetAddColumn, SpreadsheetDeleteColumns, SpreadsheetDeleteRow, SpreadsheetDeleteR
ows, SpreadsheetFormatColumn, SpreadsheetFormatColumns, SpreadsheetShiftColumns
History

ColdFusion 9: Added the function.
Parameters

Parameter

Description

spreadsheetObj

The Excel spreadsheet object from which to delete the
columns.

column

The column to delete.

Example

The following example deletes the data from column 2 from a spreadsheet.

© 2014 Adobe Systems Incorporated. All rights reserved.

2265

Adobe ColdFusion Documentation



SELECT CORNUMBER,DEPT_ID,COURSE_ID,CORNAME
FROM COURSELIST


///We need an absolute path, so get the current directory path.
theFile=GetDirectoryFromPath(GetCurrentTemplatePath()) & courses.xls";
//Create a new Excel spreadsheet object and add the query data.
theSheet = SpreadsheetNew("CourseData");
SpreadsheetAddRows(theSheet,courses);
//Delete the second column of the sheet.
SpreadsheetDeleteColumn(theSheet,2);




© 2014 Adobe Systems Incorporated. All rights reserved.

2266

Adobe ColdFusion Documentation

SpreadsheetDeleteColumns
Description

Deletes the data from multiple columns of an Excel spreadsheet object. This function does not remove the columns.
Returns

Does not return a value.
Category

Microsoft Office Integration
Function syntax

SpreadsheetDeleteColumns(spreadsheetObj, range)

See also

SpreadsheetAddColumn, SpreadsheetDeleteColumn, SpreadsheetDeleteRow, SpreadsheetDeleteRo
ws, SpreadsheetFormatColumn, SpreadsheetFormatColumns, SpreadsheetShiftColumns
History

ColdFusion 9: Added the function.
Parameters

Parameter

Description

spreadsheetObj

The Excel spreadsheet object from which to delete the
columns.

range

A string containing the columns to delete, using any
combination of the following formats:
startColumn-endColumn - Delete columns in a
single range.
column,column,column... - Delete one or more
individual columns.
You can also provide both the formats together. For
example, 1{{, 2, 3-5, 7-12}}.

Example

The following example deletes the data from columns 2-4 and column 6 from a spreadsheet.

© 2014 Adobe Systems Incorporated. All rights reserved.

2267

Adobe ColdFusion Documentation



SELECT CORNUMBER,DEPT_ID,CORLEVEL,COURSE_ID,CORNAME,CORDESC,LASTUPDATE
FROM COURSELIST


///We need an absolute path, so get the current directory path.
theFile=GetDirectoryFromPath(GetCurrentTemplatePath()) & courses.xls";
//Create a new Excel spreadsheet object and add the query data.
theSheet = SpreadsheetNew("CourseData");
SpreadsheetAddRows(theSheet,courses);
//Delete columns 2 though 4 and 6.
SpreadsheetDeleteColumns(theSheet,"2-4,6");




© 2014 Adobe Systems Incorporated. All rights reserved.

2268

Adobe ColdFusion Documentation

SpreadsheetDeleteRow
Description

Deletes all data from a row of an Excel spreadsheet object. It does not delete the row.
Returns

Does not return a value.
Category

Microsoft Office Integration
Function syntax

SpreadsheetDeleteRow(spreadsheetObj, row)

See also

SpreadsheetDeleteColumn, SpreadsheetDeleteColumns, SpreadsheetDeleteRows, SpreadsheetForm
atRows, SpreadsheetShiftRows
History

ColdFusion 9: Added the function.
Parameters

Parameter

Description

spreadsheetObj

The Excel spreadsheet object from which to delete the
row.

row

The row to delete.

Example

The following example deletes row 10 from a spreadsheet.

© 2014 Adobe Systems Incorporated. All rights reserved.

2269

Adobe ColdFusion Documentation



SELECT CORNUMBER,DEPT_ID,CORLEVEL,COURSE_ID,CORNAME,CORDESC,LASTUPDATE
FROM COURSELIST


///We need an absolute path, so get the current directory path.
theFile=GetDirectoryFromPath(GetCurrentTemplatePath()) & courses.xls";
//Create a new Excel spreadsheet object and add the query data.
theSheet = SpreadsheetNew("CourseData");
SpreadsheetAddRows(theSheet,courses);
//Delete row 10.
SpreadsheetDeleteRow(theSheet,"10");




© 2014 Adobe Systems Incorporated. All rights reserved.

2270

Adobe ColdFusion Documentation

SpreadsheetDeleteRows
Description

Deletes all data from multiple rows of an Excel spreadsheet object. It does not delete the row.
Returns

Does not return a value.
Category

Microsoft Office Integration
Function syntax

SpreadsheetDeleteRows(spreadsheetObj, range)

See also

SpreadsheetDeleteColumn, SpreadsheetDeleteColumns, SpreadsheetDeleteRow, SpreadsheetForma
tRow, SpreadsheetFormatRows, SpreadsheetShiftRows
History

ColdFusion 9: Added the function.
Parameters

Parameter

Description

spreadsheetObj

The Excel spreadsheet object in which to delete the
rows.

range

The rows to delete, using any combination of the
following form:
startRow-endRow - Insert rows in a single range.
row,row,row... - Insert one or more individual rows.
You can also provide both the formats together. For
example, 1, 2, 3-5, 7-12.

Example

The following example deletes rows 1 and 5-10 from a spreadsheet.

© 2014 Adobe Systems Incorporated. All rights reserved.

2271

Adobe ColdFusion Documentation



SELECT CORNUMBER,DEPT_ID,CORLEVEL,COURSE_ID,CORNAME,CORDESC,LASTUPDATE
FROM COURSELIST


///We need an absolute path, so get the current directory path.
theFile=GetDirectoryFromPath(GetCurrentTemplatePath()) & courses.xls";
//Create a new Excel spreadsheet object and add the query data.
theSheet = SpreadsheetNew("CourseData");
SpreadsheetAddRows(theSheet,courses);
//Delete rows 1 and 5 though 10.
SpreadsheetDeleteRows(theSheet,"1,5-10");




© 2014 Adobe Systems Incorporated. All rights reserved.

2272

Adobe ColdFusion Documentation

SpreadsheetFormatCell
Description

Formats the contents of a single cell of an Excel spreadsheet object.
Returns

Does not return a value.
Category

Microsoft Office Integration
Function syntax

SpreadsheetFormatCell(spreadsheetObj, format, row, column)

See also

SpreadsheetFormatColumn, SpreadsheetFormatColumns, SpreadsheetFormatRow, SpreadsheetForma
tRowsSpreadsheetShiftRows
History

ColdFusion 9: Added the function.
Parameters

Parameter

Description

spreadsheetObj

The Excel spreadsheet object to which to set the
format.

format

A structure containing the format information. For
details see Usage.

row

The row number of the cell.

column

The column number of the cell.

Usage

The format structure can specify any or all of the following values
Name

Valid values

alignment

left (default), right, center, justify, general, fill, and
center_selection

bold

A Boolean value. The default value is false.

© 2014 Adobe Systems Incorporated. All rights reserved.

2273

Adobe ColdFusion Documentation

bottomborder

A border format, any of the following:none (default),
thin, medium, dashed, hair, thick, double, dotted,
medium_dashed, dash_dot, medium_dash_dot,
dash_dot_dot, medium_dash_dot_dot,
slanted_dash_dot

bottombordercolor

See the color field for the complete list of colors.

color

Any value in the org.apache.poi.hssf.util.HSS
FColor class:black, brown, olive_green, dark_green,
dark_teal, dark_blue, indigo, grey_80_percent, orange,
dark_yellow, green, teal, blue, blue_grey,
grey_50_percent, red, light_orange, lime, sea_green,
aqua, light_blue, violet, grey_40_percent, pink, gold,
yellow, bright_green, turquoise, dark_red, sky_blue,
plum, grey_25_percent, rose, light_yellow, light_green,
light_turquoise, light_turquoise, pale_blue, lavender,
white, cornflower_blue, lemon_chiffon, maroon, orchid,
coral, royal_blue, light_cornflower_blue

© 2014 Adobe Systems Incorporated. All rights reserved.

2274

Adobe ColdFusion Documentation

dataformat

An Excel data format. Most of the formats supported by
MS Excel are supported. The following are the built-in
formats:

General
0
0.00
#,##0
#,##0.00
($#,##0_($#,##0)
($#,##0_[Red]($#,##0)
($#,##0.00($#,##0.00)
($#,##0.00_[Red]($#,##0.00)
0%
0.00%
0.00E+00
# ?/?
# ??/??
m/d/yy
d-mmm-yy
d-mmm
mmm-yy
h:mm AM/PM
h:mm:ss AM/PM
h:mm
h:mm:ss
m/d/yy h:mm
(#,##0_(#,##0)
(#,##0_[Red](#,##0)
(#,##0.00_(#,##0.00)
(#,##0.00_[Red](#,##0.00)
_(*#,##0__(*(#,##0_(* \-\__(@_)
_($*#,##0__($*(#,##0_($*
\-\__(@_)
_(*#,##0.00__(*(#,##0.00_(*\-\??_
_(@_)
_($*#,##0.00__($*(#,##0.00_($*\-\?
?__(@_)
mm:ss
[h]:mm:ss
mm:ss.0
##0.0E+0
@

fgcolor

See the color field for the complete list of colors.

fillpattern

Any of the following:big_spots (default), squares, nofill,
solid_foreground, fine_dots, alt_bars, sparse_dots,
thick_horz_bands, thick_vert_bands,
thick_backward_diag, thick_forward_diag, diamonds,
less_dots, least_dots

font

A valid system font name.

© 2014 Adobe Systems Incorporated. All rights reserved.

2275

Adobe ColdFusion Documentation

fontsize

An integer point value.

hidden

A Boolean value. The default value is false.

indent

A positive integer number of default character spaces.

italic

No value required.

leftborder

A border format. See bottomborder for valid values.

leftbordercolor

See the color field for the complete list of colors.

locked

A Boolean value. The default value is false.

rightborder

A border format. See bottomborder for valid values.

rightbordercolor

See the color field for the complete list of colors.

rotation

An integer number of degrees in the range -90 - 90.

strikeout

No value required.

textwrap

A Boolean value. The default value is false.

topborder

A border format. See bottomborder for valid values.

topbordercolor

See the color field for the complete list of colors.

verticalalignment

Any of the following: vertical_top, vertical_bottom,
vertical_center, vertical_justifyFor example,SpreadsheetFormatCellRange(theSheet,{ve
rticalalignment="VERTICAL_TOP"},
3,4,30,10);

underline

A Boolean value. The default value is false.

Enhancements made in ColdFusion 9.0.1

You can preformat a cell while you use SpreadSheetformatcell as shown in the following example:


sheet= SpreadSheetNew();
Spreadsheetformatcell(sheet,{dataformat="@"},1,1);
spreadsheetSetCellValue(sheet,'000006534',1,1);


Here, the cell is preformatted and the data is taken as it is provided.

© 2014 Adobe Systems Incorporated. All rights reserved.

2276

Adobe ColdFusion Documentation
Example

The following example creates a sheet, sets a simple format for the cell at row 3 column 4, and writes the result to a
file:



SELECT CORNUMBER,DEPT_ID,CORLEVEL,COURSE_ID,CORNAME,CORDESC,LASTUPDATE
FROM COURSELIST


///We need an absolute path, so get the current directory path.
theFile=GetDirectoryFromPath(GetCurrentTemplatePath()) & "courses.xls";
//Create a new Excel spreadsheet object and add the query data.
theSheet = SpreadsheetNew("CourseData");
SpreadsheetAddRows(theSheet,courses);
// Define a format for the cell.
format1-SructNew();
format1.font="serif";
format1.fontsize="12";
format1.color="dark_green";
format1.bold="true";
format1.alignment="center";
SpreadsheetFormatCell(theSheet,format1,3,4);




The following examples show how to use dataformat:

© 2014 Adobe Systems Incorporated. All rights reserved.

2277

Adobe ColdFusion Documentation


























© 2014 Adobe Systems Incorporated. All rights reserved.

2278

Adobe ColdFusion Documentation

SpreadsheetFormatColumn
Description

Formats the contents of a single column of an Excel spreadsheet object.
Returns

Does not return a value.
Category

Microsoft Office Integration
Function syntax

SpreadsheetFormatColumn(spreadsheetObj, format, column)

See also

SpreadsheetFormatCell, SpreadsheetFormatColumns, SpreadsheetFormatRow, SpreadsheetFormat
Rows
History

ColdFusion 9: Added the function.
Parameters

Parameter

Description

spreadsheetObj

The Excel spreadsheet object in which to set the
format.

format

A structure containing the format information. For
details see SpreadsheetFormatCell.

column

The column number.

Example

The following example creates a sheet, sets a format for column 5, and writes the result to a file:

© 2014 Adobe Systems Incorporated. All rights reserved.

2279

Adobe ColdFusion Documentation



SELECT CORNUMBER,DEPT_ID,CORLEVEL,COURSE_ID,CORNAME,CORDESC,LASTUPDATE
FROM COURSELIST


///We need an absolute path, so get the current directory path.
theFile=GetDirectoryFromPath(GetCurrentTemplatePath()) & "courses.xls";
//Create a new Excel spreadsheet object and add the query data.
theSheet = SpreadsheetNew("CourseData");
SpreadsheetAddRows(theSheet,courses);
// Define a format for the column.
format1-SructNew()
format1.font="Courier";
format1.fontsize="10";
format1.color="dark_blue;";
format1.italic="true";
format1.bold="true";
format1.alignment="left";
format1.textwrap="true";
format1.fgcolor="pale_blue";
format1.bottomborder="dotted";
format1.bottombordercolor="blue_grey";
format1.leftborder="thick";
format1.leftbordercolor="blue_grey";
format1.rightborder="thick";
format1.rightbordercolor="blue_grey";
SpreadsheetFormatColumn(theSheet,format1,5);




© 2014 Adobe Systems Incorporated. All rights reserved.

2280

Adobe ColdFusion Documentation

SpreadsheetFormatCellRange
Description

Formats the cells within the given range.
Returns

Nothing
Category

Microsoft Office Integration
Function syntax

SpreadsheetFormatCellRange (spreadsheetObj, format, startRow, startColumn, endRow,
endColumn)
See also

SpreadsheetFormatCell, SpreadsheetFormatColumns, SpreadsheetFormatRow, SpreadsheetFormat
Rows
History

ColdFusion 9.0.1: Added the function. Supports preformatting of a cell while you use this function.
Parameters

Parameter

Description

spreadsheetObj

The Excel spreadsheet object for which you want to
format the cells.

format

A structure that contains format information.

startRow

The number of the first row to format.

startColumn

The number of the first column to format.

endRow

The number of the last row to format.

endColumn

The number of the last column to format.

Example

© 2014 Adobe Systems Incorporated. All rights reserved.

2281

Adobe ColdFusion Documentation



SELECT CORNUMBER,DEPT_ID,CORLEVEL,COURSE_ID,CORNAME,CORDESC,LASTUPDATE
FROM COURSELIST


///We need an absolute path, so get the current directory path.
theFile=GetDirectoryFromPath(GetCurrentTemplatePath()) & "courses.xls";
//Create a new Excel spreadsheet object and add the query data.
theSheet = SpreadsheetNew("CourseData");
SpreadsheetAddRows(theSheet,courses);
// Define a format for the column.
format1=SructNew()
format1.font="Courier";
format1.fontsize="10";
format1.color="dark_blue;";
format1.italic="true";
format1.bold="true";
format1.alignment="left";
SpreadsheetFormatCellRange(theSheet,format1, 3,4,30,10);




© 2014 Adobe Systems Incorporated. All rights reserved.

2282

Adobe ColdFusion Documentation

SpreadsheetFormatColumns
Description

Formats the contents of multiple columns of an Excel spreadsheet object.
Returns

Does not return a value.
Category

Microsoft Office Integration
Function syntax

SpreadsheetFormatColumns(spreadsheetObj, format, columns)

See also

SpreadsheetFormatCell, SpreadsheetFormatColumn, SpreadsheetFormatRow, SpreadsheetFormatR
ows
History

ColdFusion 9: Added the function.
Parameters

Parameter

Description

spreadsheetObj

The Excel spreadsheet object in which to set the
format.

format

A structure containing the format information. For
details see SpreadsheetFormatCell.

columns

The columns to format, in one of the following formats:
startColumn-endColumn - Insert columns in a
single range.
column,column,column... - Insert one or more
individual columns.

Example

The following example creates a sheet, sets a format for columns 1-5, and writes the result to a file:

© 2014 Adobe Systems Incorporated. All rights reserved.

2283

Adobe ColdFusion Documentation



SELECT CORNUMBER,DEPT_ID,CORLEVEL,COURSE_ID,CORNAME,CORDESC,LASTUPDATE
FROM COURSELIST


///We need an absolute path, so get the current directory path.
theFile=GetDirectoryFromPath(GetCurrentTemplatePath()) & "courses.xls";
//Create a new Excel spreadsheet object and add the query data.
theSheet = SpreadsheetNew("CourseData");
SpreadsheetAddRows(theSheet,courses);
// Define a format for the column.
format1-SructNew()
format1.font="Courier";
format1.fontsize="10";
format1.color="dark_blue;";
format1.italic="true";
format1.bold="true";
format1.alignment="left";
format1.textwrap="true";
format1.fgcolor="pale_blue";
format1.bottomborder="dotted";
format1.bottombordercolor="blue_grey";
format1.leftborder="thick";
format1.leftbordercolor="blue_grey";
format1.rightborder="thick";
format1.rightbordercolor="blue_grey";
SpreadsheetFormatColumns(theSheet,format1,"1-5");




© 2014 Adobe Systems Incorporated. All rights reserved.

2284

Adobe ColdFusion Documentation

SpreadsheetFormatRow
Description

Formats the contents of a single row of an Excel spreadsheet object.
Returns

Does not return a value.
Category

Microsoft Office Integration
Function syntax

SpreadsheetFormatRow(spreadsheetObj, format, row)

See also

Other Spreadsheet* functions{{SpreadsheetFormatCell}}, SpreadsheetFormatColumn, SpreadsheetFormatCo
lumns, SpreadsheetFormatRows
History

ColdFusion 9: Added the function.
Parameters

Parameter

Description

spreadsheetObj

The Excel spreadsheet object in which to set the
format.

format

A structure containing the format information. For
details see SpreadsheetFormatColumn.

row

The row number.

Example

The following example creates a sheet, sets a format for rows 1, 3, and 5, and writes the result to a file:

© 2014 Adobe Systems Incorporated. All rights reserved.

2285

Adobe ColdFusion Documentation



SELECT CORNUMBER,DEPT_ID,CORLEVEL,COURSE_ID,CORNAME,CORDESC,LASTUPDATE
FROM COURSELIST


///We need an absolute path, so get the current directory path.
theFile=GetDirectoryFromPath(GetCurrentTemplatePath()) & "courses.xls";
//Create a new Excel spreadsheet object and add the query data.
theSheet = SpreadsheetNew("CourseData");
SpreadsheetAddRows(theSheet,courses);
// Define a format for the column.
format1-SructNew()
format1.font="Courier";
format1.fontsize="10";
format1.color="dark_blue;";
format1.italic="true";
format1.bold="true";
format1.alignment="left";
format1.textwrap="true";
format1.fgcolor="pale_blue";
format1.bottomborder="thick";
format1.bottombordercolor="blue_grey";
format1.topbordercolor="blue_grey";
format1.topborder="thick";
format1.leftborder="dotted";
format1.leftbordercolor="blue_grey";
format1.rightborder="dotted";
format1.rightbordercolor="blue_grey";
SpreadsheetFormatRow(theSheet,format1,"5");




© 2014 Adobe Systems Incorporated. All rights reserved.

2286

Adobe ColdFusion Documentation

SpreadsheetFormatRows
Description

Formats the contents of multiple rows of an Excel spreadsheet object.
Returns

Does not return a value.
Category

Microsoft Office Integration
Function syntax

SpreadsheetFormatRows(spreadsheetObj, format, rows)

See also

SpreadsheetFormatCell, SpreadsheetFormatColumn, SpreadsheetFormatColumns, SpreadsheetForm
atRow
History

ColdFusion 9: Added the function.
Parameters

Parameter

Description

spreadsheetObj

The Excel spreadsheet object in which to set the
format.

format

A structure containing the format information. For
details see SpreadsheetFormatColumn.

row

The rows to format, in one of the following formats:
startRow-endRow - Insert rows in a single range.
row,row,row... - Insert one or more individual rows.
You can also provide the formats together. For
example, 1-5, 6, 7, 9-12.

Example

The following example creates a sheet, sets a format for rows 1, 3, and 5, and writes the result to a file:

© 2014 Adobe Systems Incorporated. All rights reserved.

2287

Adobe ColdFusion Documentation



SELECT CORNUMBER,DEPT_ID,CORLEVEL,COURSE_ID,CORNAME,CORDESC,LASTUPDATE
FROM COURSELIST


///We need an absolute path, so get the current directory path.
theFile=GetDirectoryFromPath(GetCurrentTemplatePath()) & "courses.xls";
//Create a new Excel spreadsheet object and add the query data.
theSheet = SpreadsheetNew("CourseData");
SpreadsheetAddRows(theSheet,courses);
// Define a format for the column.
format1-SructNew()
format1.font="Courier";
format1.fontsize="10";
format1.color="dark_blue;";
format1.italic="true";
format1.bold="true";
format1.alignment="left";
format1.textwrap="true";
format1.fgcolor="pale_blue";
format1.bottomborder="thick";
format1.bottombordercolor="blue_grey";
format1.topbordercolor="blue_grey";
format1.topborder="thick";
format1.leftborder="dotted";
format1.leftbordercolor="blue_grey";
format1.rightborder="dotted";
format1.rightbordercolor="blue_grey";
SpreadsheetFormatRows(theSheet,format1,"1,3,5");




© 2014 Adobe Systems Incorporated. All rights reserved.

2288

Adobe ColdFusion Documentation

SpreadsheetGetCellComment
Description

Gets the comment for an Excel spreadsheet object cell as a structure with formatting information, or all comments
for the object.
Returns

If the parameters include the row and column: a structure containing the comment information for the specified cell.
If the function has only a spreadsheetObj parameter, an array containing a structure for each comment. Each
structure has the following information:
Field

Contents

Author

A string containing the name of the comment author.

Column

The cell column number.

Comment

A string containing the comment text.

Row

The cell row number.

Category

Microsoft Office Integration
Function syntax

SpreadsheetGetCellComment(spreadsheetObj[, row, column])

See also

SpreadsheetFormatCell, SpreadsheetGetCellFormula, SpreadsheetGetCellValue, SpreadsheetMer
geCells, SpreadsheetSetCellComment, SpreadsheetSetCellFormula, SpreadsheetSetCellValue
History

ColdFusion 9: Added the function.
Parameters

Parameter

Description

spreadsheetObj

The Excel spreadsheet object from which to get the
comment.

row

The row number of the cell from which to get the
comment.

© 2014 Adobe Systems Incorporated. All rights reserved.

2289

Adobe ColdFusion Documentation

column

The column number of the cell from which to get the
comment.

Example

The following example sets and gets a comment for the cell at row 3 column 5.


///We need an absolute path, so get the current directory path.
theFile=GetDirectoryFromPath(GetCurrentTemplatePath()) & "comment.xls";
//Create an Excel spreadsheet object.
theSheet = SpreadsheetNew();
// Define a cell comment.
comment1.anchor="1,1,15,20";
comment1.author="Adobe Systems";
comment1.bold="true";
comment1.color="lavender";
comment1.comment="This is the cell in row three, column 5 (E).";
comment1.fillcolor="yellow";
comment1.font="Courier";
comment1.horizontalalignment="left";
comment1.linestyle="dashsys";
comment1.size="10";
comment1.verticalalignment="top";
//Set the comment.
SpreadsheetSetCellComment(theSheet,comment1,3,5);
//Get the comment from the Excel spreadsheet object.
theComment=SpreadsheetGetCellComment(theSheet,3,5);


Row,Column: #theComment.row#,#theComment.column#

Author: #theComment.author#

Comment: #theComment.comment#




© 2014 Adobe Systems Incorporated. All rights reserved.

2290

Adobe ColdFusion Documentation

SpreadsheetGetCellFormula
Description

Gets the formula for an Excel spreadsheet object cell, or all formulas for the object.
Returns

If the parameters include the row and column: a string containing the formula. If the function has the spreadsheet
Obj parameter, an array containing structures for each formula.
Category

Microsoft Office Integration
Function syntax

SpreadsheetGetCellFormula(spreadsheetObj[, row, column])

See also

SpreadsheetGetCellComment, SpreadsheetFormatCell, SpreadsheetGetCellValue, SpreadsheetMer
geCells, SpreadsheetSetCellComment, SpreadsheetSetCellFormula, SpreadsheetSetCellValue
History

ColdFusion 9: Added the function.
Parameters

Parameter

Description

spreadsheetObj

The Excel spreadsheet object from which to get the
formula.

row

The row number of the cell from which to get the
formula.

column

The column number of the cell from which to get the
formula.

Usage

If you specify only the spreadsheetObj parameter, the function returns an array of the structures with the
following contents. The array has one entry for each cell that contains a formula.
Field

Valid values

formula

The formula for the cell.

row

The row number of the cell.

© 2014 Adobe Systems Incorporated. All rights reserved.

2291

Adobe ColdFusion Documentation

column

The column number of the cell.

Example

The following example sets a cell formula, and gets the cell formula and value.


//Create a new Excel spreadsheet object.
theSheet=SpreadsheetNew();
//Set the values of column 3 rows 1-10 to the row number.
for (i=1; i<= 10; i=i+1)
SpreadsheetSetCellValue(theSheet,i,i,3);
//Set the formula for the cell in row 11 column 3 to be the sum of
//Columns 1-10.
SpreadsheetSetCellFormula(theSheet,"SUM(C1:C10)",11,3);
//Get the formula from the Excel spreadsheet object.
theValue=SpreadsheetGetCellFormula(theSheet,11,3);
//Get the value of row 11 column 5 from the Excel spreadsheet object.
theValue=SpreadsheetGetCellValue(theSheet,11,3);


Row 11, Column 3 value: #SpreadsheetGetCellValue(theSheet,11,3)#

Row 11, Column 3 formula: #SpreadsheetGetCellFormula(theSheet,11,3)#



© 2014 Adobe Systems Incorporated. All rights reserved.

2292

Adobe ColdFusion Documentation

SpreadsheetGetCellValue
Description

Gets the Value for an Excel spreadsheet object cell.
Returns

A string containing the cell value.
Category

Microsoft Office Integration
Function syntax

SpreadsheetGetCellValue(spreadsheetObj, row, column)

See also

SpreadsheetGetCellComment, SpreadsheetFormatCell, SpreadsheetGetCellFormula, SpreadsheetM
ergeCells, SpreadsheetSetCellComment, SpreadsheetSetCellFormula, SpreadsheetSetCellValue
History

ColdFusion 9: Added the function.
Parameters

Parameter

Description

spreadsheetObj

The Excel spreadsheet object from which to get the
value.

row

The row number of the cell from which to get the
formula.

column

The column number of the cell from which to get the
formula.

Example

The following lines create an Excel spreadsheet object, set the value of the cell at row 3, column 5 - 365, gets the
value and displays it:

© 2014 Adobe Systems Incorporated. All rights reserved.

2293

Adobe ColdFusion Documentation


//Create a new Excel spreadsheet object.
theSheet=SpreadsheetNew();
//Set the value of the cell at row 3 column 5.
SpreadsheetSetCellValue(theSheet,365,3,5);
//Get the value from the Excel spreadsheet object.
theValue=SpreadsheetGetCellValue(theSheet,3,5);
WriteOutput("The value of column 5 row 3 is: " & theValue);


© 2014 Adobe Systems Incorporated. All rights reserved.

2294

Adobe ColdFusion Documentation

SpreadsheetInfo
Description

Gets the property of an Excel spreadsheet object.
Returns

Returns a spreadsheet property that can be one of the following:
AUTHOR
CATEGORY
COMMENTS
CREATIONDATE
LASTEDITED
LASTAUTHOR
LASTSAVED
KEYWORDS
MANAGER
COMPANY
SUBJECT
TITLE
SHEETS
SHEETNAMES
SPREADSHEETTYPES
Category

Microsoft Office Integration
Function syntax

SpreadsheetInfo(spreadsheetobj)

See also

SpreadsheetAddColumn, SpreadsheetAddImage, SpreadsheetAddRow, SpreadsheetDeleteRow, Spread
sheetDeleteRows, SpreadsheetFormatRow, SpreadsheetFormatRows, SpreadsheetShiftRows
History

ColdFusion 9: Added the function.
Parameters

Parameter

Description

spreadsheetobj

The Excel spreadsheet object from which to get the
value.

Usage

This function is supported by Microsoft Office Excel 2007 and Microsoft Office 2003.

© 2014 Adobe Systems Incorporated. All rights reserved.

2295

Adobe ColdFusion Documentation
Example




 AUTHOR : #info.author#
 
 Creation Date : #info.creationdate#
 
 LAST AUTHOR : #info.lastauthor#
 
 SHEETS : #info.sheets#
 
 SPREADSHEETTYPE : #info.SPREADSHEETTYPE#
 
SUBJECT : #info.SUBJECT#

TITLE : #info.TITLE#


© 2014 Adobe Systems Incorporated. All rights reserved.

2296

Adobe ColdFusion Documentation

SpreadsheetMergeCells
Description

Merges a rectangular block of two or more Excel spreadsheet object cells.
Returns

Does not return a value.
Category

Microsoft Office Integration
Function syntax

SpreadsheetMergeCells(spreadsheetObj, startRow, endRow, startColumn, endColumn)

See also

SpreadsheetGetCellComment, SpreadsheetFormatCell, SpreadsheetGetCellFormula, SpreadsheetG
etCellValue, SpreadsheetSetCellComment, SpreadsheetSetCellFormula, SpreadsheetSetCellVal
ue
History

ColdFusion 9: Added the function.
Parameters

Parameter

Description

spreadsheetObj

The Excel spreadsheet object containing the cells to
merge.

startRow

The number of the first row to merge.

endRow

The row number of the last row to merge.

startColumn

The column number of the first cell to merge.

endColumn

The column number of the last cell to merge.

Usage

If you merge two cells using this function, the merged cell by default displays the value in the cell that is on the
left-hand side of the spreadsheet. For example, if you merge the cell (20,3) and cell (20,4), then the value in the cell
(20, 3) is displayed. If the cell (20, 3) is blank, then after merging, the cell displays blank.
Example

The following example merges cells 4-6 in rows 1-3 of an Excel spreadsheet object. It puts text in the merged cells

© 2014 Adobe Systems Incorporated. All rights reserved.

2297

Adobe ColdFusion Documentation

and saves the sheet to a file so you can see the result.


///We need an absolute path, so get the current directory path.
theFile=GetDirectoryFromPath(GetCurrentTemplatePath()) & "mergecells.xls";
//Create a new Excel spreadsheet object and add the query data.
theSheet = SpreadsheetNew("CourseData");
//Merges cells 4-6 in the first three rows of the Excel spreadsheet object.
SpreadsheetMergeCells(theSheet,1,3,4,6);
//Set the value of the merged cell.
SpreadsheetSetCellValue(theSheet,"Columns 4-6 of rows 1-3 are merged",1,4);




© 2014 Adobe Systems Incorporated. All rights reserved.

2298

Adobe ColdFusion Documentation

SpreadsheetNew
Description

Creates a ColdFusionExcel spreadsheet object, which represents a single sheet of an Excel document.
Returns

ColdFusionExcel spreadsheet object.
Category

Microsoft Office Integration
Function syntax

SpreadsheetNew([sheetName, xmlformat])

See also

All Other Spreadsheet functions; see Microsoft Office Integration list.
History

ColdFusion 9: Added the function.
Parameters

Parameter

Description

sheetName

A string containing the sheet name to assign to the
Excel spreadsheet object.

xmlformat

A Boolean value.True or Yes: Creates a .xlsx file that is
supported by Microsoft Office Excel 2007.False or No:
Creates a .xls file.

Usage

This function supports Microsoft Office Excel 2007. To create a simple .xls spreadsheet object with a default
worksheet name, your code can be as follows:



To create a simple .xls spreadsheet object by specifying the worksheet name as "mySheet", your code can be as
follows:



© 2014 Adobe Systems Incorporated. All rights reserved.

2299

Adobe ColdFusion Documentation

To create spreadsheet objects that are supported by Microsoft Office Excel 2007 (.xlsx), your code can be as
follows:





Note
You can specify either "true" or "yes" to create a .xlsx file.

Example

The following example creates an Excel spreadsheet object with the sheet name Expenses, sets a cell value, and
saves the result to a file.


///We need an absolute path, so get the current directory path.
theFile=GetDirectoryFromPath(GetCurrentTemplatePath()) & "newSpreadsheet.xls";
//Create a new Excel spreadsheet object.
theSheet = SpreadsheetNew("Expenses");
//Set the value a cell.
SpreadsheetSetCellValue(theSheet,"365",1,4);




© 2014 Adobe Systems Incorporated. All rights reserved.

2300

Adobe ColdFusion Documentation

SpreadsheetRead
Description

Reads a sheet from a spreadsheet file and stores it in a ColdFusion spreadsheet object.
Returns

Returns spreadsheet object.
Category

Microsoft Office Integration
Function syntax

SpreadSheetRead(fileName [, sheetName|sheet])

See also

SpreadsheetWrite, SpreadsheetAddColumn, SpreadsheetAddImage, SpreadsheetAddRow, Spreadshee
tDeleteRow, SpreadsheetDeleteRows, SpreadsheetFormatRow, SpreadsheetFormatRows, Spreadshee
tShiftRows
History

ColdFusion 9: Added the function.
Parameters

Parameter

Description

fileName

A string specifying the path to the spreadsheet file.

sheetName

Optional parameter; name of the sheet. You can
specify sheet or sheetName.

sheet

Optional parameter; number of the sheet. You can
specify sheet or sheetName.

Usage

Use this function to read an Excel file with multiple sheets.
Example

{{
a = SpreadSheetRead("C:\Files\Report.xls","Annual Report")
}}

© 2014 Adobe Systems Incorporated. All rights reserved.

2301

Adobe ColdFusion Documentation

SpreadsheetReadBinary
Description

Reads and stores content from a spreadsheet object and returns it as a byte array.
Returns

Returns a byte array of the stored spreadsheet information using the cfcontent tag.
Category

Microsoft Office Integration
Function syntax

SpreadsheetReadBinary(spreadsheetobj)

See also

SpreadsheetAddColumn, SpreadsheetAddImage, SpreadsheetAddRow, SpreadsheetDeleteRow, Spread
sheetDeleteRows, SpreadsheetFormatRow, SpreadsheetFormatRows, SpreadsheetShiftRows
History

ColdFusion 9: Added the function.
Parameters

Parameter

Description

spreadSheetObject

The Excel spreadsheet object to read.

Usage
Example








© 2014 Adobe Systems Incorporated. All rights reserved.

2302

Adobe ColdFusion Documentation

SpreadsheetRemoveSheet
Description

Deletes a spreadsheet.
Returns

Nothing
Category

Microsoft Office Integration
Function syntax

SpreadsheetRemoveSheet (spreadsheetObj, sheetname)
See also

SpreadsheetSetActiveSheetNumber, SpreadsheetAddColumn, SpreadsheetAddImage, SpreadsheetAd
dRow, SpreadsheetDeleteRow, SpreadsheetDeleteRows, SpreadsheetFormatRow, SpreadsheetFormat
Rows, SpreadsheetShiftRows
History

ColdFusion 9.0.1: Added the function.
Parameters

Parameter

Description

spreadsheetObj

The Excel spreadsheet object from which you delete
the sheet.

sheetname

Name of the sheet that must be removed.

Example









© 2014 Adobe Systems Incorporated. All rights reserved.

2303

Adobe ColdFusion Documentation

SpreadsheetSetActiveSheet
Description

Sets a specified sheet as active sheet.
Returns

Does not return a value.
Category

Microsoft Office Integration
Function syntax

SpreadsheetSetActiveSheet(spreadsheetobj, sheetname)

See also

SpreadsheetSetActiveSheetNumber, SpreadsheetAddColumn, SpreadsheetAddImage, SpreadsheetAd
dRow, SpreadsheetDeleteRow, SpreadsheetDeleteRows, SpreadsheetFormatRow, SpreadsheetFormat
Rows, SpreadsheetShiftRows
History

ColdFusion 9: Added the function.
Parameters

Parameter

Description

spreadsheetobj

The Excel spreadsheet object to which to add the split
pane.

sheetname

The spreadsheet that must be set as active.

Usage

You can set only one sheet as active at a time. Therefore, any sheet operation is limited to a particular sheet. For
operations in any other sheet, you must set that sheet as active.
Example

The following example shows how to switch from one sheet to another and perform operations.

© 2014 Adobe Systems Incorporated. All rights reserved.

2304

Adobe ColdFusion Documentation



SELECT CORNUMBER,DEPT_ID,COURSE_ID,CORNAME
FROM COURSELIST


///We need an absolute path, so get the current directory path.
theFile=GetDirectoryFromPath(GetCurrentTemplatePath()) & courses.xls";
//Create a new Excel spreadsheet object and add the query data.
theSheet = SpreadsheetNew("CourseData");
SpreadsheetAddRows(theSheet,courses);
//Create a new sheet.
SpreadsheetCreateSheet (theSheet, "EvaluationSheet");
//Set the sheet as active.
SpreadsheetSetActiveSheet (theSheet, "EvaluationSheet");
//Add a new row to the sheet.
SpreadsheetAddRows(theSheet,courses);




© 2014 Adobe Systems Incorporated. All rights reserved.

2305

Adobe ColdFusion Documentation

SpreadsheetSetActiveSheetNumber
Description

Sets a specified sheetnumber as active sheet.
Returns

Does not return a value.
Category

Microsoft Office Integration
Function syntax

SpreadsheetSetActiveSheetNumber(spreadsheetobj, sheetnumber)

See also

SpreadsheetSetActiveSheet, SpreadsheetAddColumn, SpreadsheetAddImage, SpreadsheetAddRow, S
preadsheetDeleteRow, SpreadsheetDeleteRows, SpreadsheetFormatRow, SpreadsheetFormatRows, S
preadsheetShiftRows
History

ColdFusion 9: Added the function.
Parameters

Parameter

Description

spreadsheetobj

The Excel spreadsheet object to which to add the split
pane.

sheetnumber

The spreadsheet number that must be set as active.

Usage

You can set only one sheet as active at a time. Therefore, any sheet operation is limited to a particular sheet. For
operations in any other sheet, you must set that sheet as active.
Example

The following example shows how to switch from one sheet to another and perform operations.

© 2014 Adobe Systems Incorporated. All rights reserved.

2306

Adobe ColdFusion Documentation



SELECT CORNUMBER,DEPT_ID,COURSE_ID,CORNAME
FROM COURSELIST




SpreadsheetAddRows(theSheet,courses);
//Set the sheetnumber 2 as active.
SpreadsheetSetActiveSheetNumber (theSheet, 2);
//Add a new row to the sheet 2.
SpreadsheetAddRows(theSheet,courses);




© 2014 Adobe Systems Incorporated. All rights reserved.

2307

Adobe ColdFusion Documentation

SpreadsheetSetCellComment
Description

Specifies the comment for an Excel spreadsheet object cell.
Returns

Does not return a value.
Category

Microsoft Office Integration
Function syntax

SpreadsheetSetCellComment(spreadsheetObj, comment, row, column)

See also

SpreadsheetGetCellComment, SpreadsheetFormatCell, SpreadsheetGetCellFormula, SpreadsheetG
etCellValue, SpreadsheetMergeCells, SpreadsheetSetCellFormula, SpreadsheetSetCellValue
History

ColdFusion 9: Added the function.
Parameters

Parameter

Description

spreadsheetObj

The Excel spreadsheet object to which to add the
comment.

comment

A structure containing the comment including text,
formatting, and placement in the cell. See Usage for
the structure contents.

row

The row number of the cell to which to add the
comment.

column

The column number of the cell to which to add the
comment.

Usage

The comment structure can have the following fields. Excel determines the default field values.
Field

© 2014 Adobe Systems Incorporated. All rights reserved.

Valid values

2308

Adobe ColdFusion Documentation

anchor

A comma separated list of integers specifying the
position and size of the comment, in rows and columns,
in the order top column, left row,bottom column, right
row. For example: "4,8,6,11" specifies a comment with
an upper left corner in row 4 column 8 and a lower right
corner in row 6 column 11.

author

The author's name.

bold

A Boolean value specifying whether the text is bold.

color

The text color, Any value in the Apache org.apache.poi.
hssf.util.HSSFColor class:black, brown,
olive_green, dark_green, dark_teal,
dark_blue, indigo, grey_80_percent,
orange, dark_yellow, green, teal, blue,
blue_grey, grey_50_percent, red,
light_orange, lime, sea_green, aqua,
light_blue, violet, grey_40_percent,
pink, gold, yellow, bright_green,
turquoise, dark_red, sky_blue, plum,
grey_25_percent, rose, light_yellow,
light_green, light_turquoise,
light_turquoise, pale_blue, lavender,
white, cornflower_blue, lemon_chiffon,
maroon, orchid, coral, royal_blue,
light_cornflower_blue.

comment

A string containing the comment text.

fillcolor

A J2SE v1.4 java.awt.Color class color value: white, l
ightGray, light_gray, gray, darkGray, dark_gr
ay, black, red, pink, orange, yellow, green, mag
enta, cyan, blue. (Because ColdFusion is case
independent, you do not need to specify the values if
defined in the Java class.)

font

Any valid system font name.

horizontalalignment

The horizontal alignment of the text: left, center,
right, justify, distributed.

italic

A Boolean value specifying whether the text is italic.

© 2014 Adobe Systems Incorporated. All rights reserved.

2309

Adobe ColdFusion Documentation

linestyle

The style of the top and right borders of the comment
box: solid, dashsys, dotsys, dashdotsys,
dashdotdotsys, dotgel, dashgel,
longdashgel, dashdotgel, longdashdotgel,
longdashdotdotgel.

linestylecolor

A Java color value (Does not work: BUG 72501).

size

The size of the text in points.

strikeout

A Boolean value specifying whether the text is struck
out.

underline

A Boolean value specifying whether the text is
underlined.

verticalalignment

The vertical alignment of the text: top, center,
bottom, justify, distributed.

visible

A Boolean value specifying whether the text is visible.

Example

The following example sets and gets a comment for the cell at row 3column 5.

© 2014 Adobe Systems Incorporated. All rights reserved.

2310

Adobe ColdFusion Documentation


///We need an absolute path, so get the current directory path.
theFile=GetDirectoryFromPath(GetCurrentTemplatePath()) & "comment.xls";
//Create an Excel spreadsheet object.
theSheet = SpreadsheetNew();
// Define a cell comment.
comment1-structNew()
comment1.anchor="0,0,5,8";
comment1.author="Adobe Systems";
comment1.bold="true";
comment1.color="dark_green";
comment1.comment="This is the cell in row three, column 5 (E).";
comment1.fillcolor="light_gray";
comment1.font="Courier";
comment1.horizontalalignment="left";
comment1.linestyle="dashsys";
comment1.size="10";
comment1.verticalalignment="top";
//Set the comment.
SpreadsheetSetCellComment(theSheet,comment1,3,5);
//Get the comment from the Excel spreadsheet object.
theComment=SpreadsheetGetCellComment(theSheet,3,5);


Row,Column: #theComment.row#,#theComment.column#

Author: #theComment.author#

Comment: #theComment.comment#




© 2014 Adobe Systems Incorporated. All rights reserved.

2311

Adobe ColdFusion Documentation

SpreadsheetSetCellFormula
Description

Specifies the formula for an Excel spreadsheet object cell.
Returns

Does not return a value.
Category

Microsoft Office Integration
Function syntax

SpreadsheetSetCellFormula(spreadsheetObj, formula, row, column)

See also

SpreadsheetGetCellComment, SpreadsheetFormatCell, SpreadsheetGetCellFormula, SpreadsheetG
etCellValue, SpreadsheetMergeCells, SpreadsheetSetCellComment, SpreadsheetSetCellValue
History

ColdFusion 9: Added the function.
Parameters

Parameter

Description

spreadsheetObj

The Excel spreadsheet object to which to add the
comment.

formula

A string containing the formula.

row

The row number of the cell to which to add the formula.

column

The column number of the cell to which to add the
formula.

Usage

This function replaces any existing value, including specific entered values.
Example

The following line sets the formula for the cell at row 2 column 11 to be the sum of the cells in the column's rows 1
through 12.The following example sets a cell formula, and gets the cell formula and value.

© 2014 Adobe Systems Incorporated. All rights reserved.

2312

Adobe ColdFusion Documentation


//Create a new Excel spreadsheet object.
theSheet=SpreadsheetNew();
//Set the values of column 3 rows 1-10 to the row number.
for (i=1; i<= 10; i=i+1)
SpreadsheetSetCellValue(theSheet,i,i,3);
//Set the fomula for the cell in row 11 column 3 to be the sum of
//Columns 1-10.
SpreadsheetSetCellFormula(theSheet,"SUM(C1:C10)",11,3);
//Get the formula from the Excel spreadsheet object.
theValue=SpreadsheetGetCellFormula(theSheet,11,3);
//Get the value of row 11 column 5 from the Excel spreadsheet object.
theValue=SpreadsheetGetCellValue(theSheet,11,3);


Row 11, Column 3 value: #SpreadsheetGetCellValue(theSheet,11,3)#

Row 11, Column 3 formula: #SpreadsheetGetCellFormula(theSheet,11,3)#



© 2014 Adobe Systems Incorporated. All rights reserved.

2313

Adobe ColdFusion Documentation

SpreadsheetSetCellValue
Description

Specifies the value of an Excel spreadsheet object cell.
Category

Microsoft Office Integration
Function syntax

SpreadsheetSetCellValue(spreadsheetObj, value, row, column, datatype)

See also

SpreadsheetGetCellComment, SpreadsheetFormatCell, SpreadsheetGetCellFormula, SpreadsheetG
etCellValue, SpreadsheetMergeCells, SpreadsheetSetCellComment, SpreadsheetSetCellFormula
History

ColdFusion 11: Added the datatype attribute.
ColdFusion 9: Added the function.
Parameters

Parameter

Description

spreadsheetObj

The Excel spreadsheet object to which to add the
comment.

value

A string containing the cell value.

row

The row number of the cell to which to set the value.

column

The column number of the cell to which to set the
value.

datatype

The data type denote by the cell. The allowed values
are NUMERIC, DATE, and STRING.

Example

The following lines create an Excel spreadsheet object, set the value of the cell at row 3, column 5 to 365, and get
the value:

© 2014 Adobe Systems Incorporated. All rights reserved.

2314

Adobe ColdFusion Documentation


//Create a new Excel spreadsheet object.
theSheet=SpreadsheetNew();
//Set the value of the cell at row 3 column 5.
SpreadsheetSetCellValue(theSheet,365,3,5);
//Get the value from the Excel spreadsheet object.
theValue=SpreadsheetGetCellValue(theSheet,3,5);
WriteOutput("The value of column 5 row 3 is: " & theValue);


© 2014 Adobe Systems Incorporated. All rights reserved.

2315

Adobe ColdFusion Documentation

SpreadsheetSetColumnWidth
Description

Sets the width of a column in a worksheet.
Returns

Nothing
Category

Microsoft Office Integration
Function syntax

SpreadSheetSetColumnWidth(spreadhsheetobj, column number, width)

See also

SpreadsheetGetCellComment, SpreadsheetFormatCell, SpreadsheetGetCellFormula, SpreadsheetG
etCellValue, SpreadsheetMergeCells, SpreadsheetSetCellFormula, SpreadsheetSetCellValue
History

ColdFusion 9: Added the function.
Parameters

Parameter

Description

spreadsheetobj

The Excel spreadsheet object to which to set the
column width.

column number

Specifies the column to set the width. The

width

Specifies the width in points.

Example

The following example creates a spreadsheet, adds columns to the spreadsheet, and sets the column width for the
newly added columns.

© 2014 Adobe Systems Incorporated. All rights reserved.

2316

Adobe ColdFusion Documentation


a=SpreadSheetNew();
SpreadSheetAddRow(a,"1,2,3,4,5,6,7,8");
SpreadSheetAddRow(a,"1,2,3,4,5,6,7,8",2,1);





© 2014 Adobe Systems Incorporated. All rights reserved.

2317

Adobe ColdFusion Documentation

SpreadsheetSetFooter
Description

Adds a footer to the specified worksheet.
Category

Microsoft Office Integration
Function syntax

SpreadsheetSetFooter(spreadhsheetobj, left footer, center footer, right footer)

See also

SpreadsheetGetCellComment, SpreadsheetFormatCell, SpreadsheetGetCellFormula, SpreadsheetG
etCellValue, SpreadsheetMergeCells, SpreadsheetSetCellFormula, SpreadsheetSetCellValue
History

ColdFusion 9: Added the function.
Parameters

Parameter

Description

spreadsheetobj

The Excel spreadsheet object to which to add the
footer.

left footer

Adds the footer in the left side of the worksheet.

center footer

Adds the footer in the center of the worksheet.

right footer

Adds the footer in the right side of the worksheet.

Usage

The footer that you add appears on the printed worksheet document.
Example

The following example adds a footer in the left side of the worksheet.

© 2014 Adobe Systems Incorporated. All rights reserved.

2318

Adobe ColdFusion Documentation

{{


}}

© 2014 Adobe Systems Incorporated. All rights reserved.

2319

Adobe ColdFusion Documentation

SpreadsheetSetHeader
Description

Adds a header to the specified worksheet.
Returns

Nothing
Category

Microsoft Office Integration
Function syntax

SpreadsheetSetHeader(spreadhsheetobj, left header, center header, right header)

See also

SpreadsheetGetCellComment, SpreadsheetFormatCell, SpreadsheetGetCellFormula, SpreadsheetG
etCellValue, SpreadsheetMergeCells, SpreadsheetSetCellFormula, SpreadsheetSetCellValue
History

ColdFusion 9: Added the function.
Parameters

Parameter

Description

spreadsheetobj

The Excel spreadsheet object to which to add the
header.

left header

Adds the header in the left side of the worksheet.

center header

Adds the header in the center of the worksheet.

right header

Adds the header in the right side of the worksheet.

Usage

The header that you add appears on the printed worksheet document.
Example

The following example adds a header in the center of the worksheet.

© 2014 Adobe Systems Incorporated. All rights reserved.

2320

Adobe ColdFusion Documentation

{{}}

© 2014 Adobe Systems Incorporated. All rights reserved.

2321

Adobe ColdFusion Documentation

SpreadsheetSetRowHeight
Description

Sets the height of a row in a worksheet.
Returns

Nothing
Category

Microsoft Office Integration
Function syntax

SpreadSheetSetRowHeight(spreadhsheetobj, row number, height)

See also

SpreadsheetGetCellComment, SpreadsheetFormatCell, SpreadsheetGetCellFormula, SpreadsheetG
etCellValue, SpreadsheetMergeCells, SpreadsheetSetCellFormula, SpreadsheetSetCellValue
History

ColdFusion 9: Added the function.
Parameters

Parameter

Description

spreadsheetobj

The Excel spreadsheet object to which to set the
column width.

row number

Specifies the row to set the height.

height

Specifies the height in points.

Usage
Example

The following example creates a spreadsheet, adds rows to the spreadsheet, and sets the row height for the newly
added rows.

© 2014 Adobe Systems Incorporated. All rights reserved.

2322

Adobe ColdFusion Documentation


a=SpreadSheetNew();
SpreadSheetAddRow(a,"1,2,3,4,5,6,7,8");
SpreadSheetAddRow(a,"1,2,3,4,5,6,7,8",2,1);





© 2014 Adobe Systems Incorporated. All rights reserved.

2323

Adobe ColdFusion Documentation

SpreadsheetShiftColumns
Description

Shifts one or more columns in Excel spreadsheet object left or right.
Returns

Does not return a value.
Category

Microsoft Office Integration
Function syntax

SpreadsheetShiftColumns(spreadsheetObj, start[, cols]
SpreadsheetShiftColumns(spreadsheetObj, start, end [, cols])

See also

SpreadsheetAddColumn, SpreadsheetDeleteColumn, SpreadsheetDeleteColumns, SpreadsheetForma
tColumn, SpreadsheetFormatColumns, SpreadsheetShiftRows
History

ColdFusion 9: Added the function.
Parameters

Parameter

Description

spreadsheetObj

The Excel spreadsheet object in which to make the
shift.

start

The number of the first, or only, column to shift

end

The number of the last column to shift. If you omit this
parameter, the function shifts a single column.

columns

The positive (right) or negative (left) number of columns
by which to shift the columns. If you omit this
parameter, the function shifts the column right by one
unit.

Usage
Example

The following line shifts columns 6 and 7 two columns to the left.

© 2014 Adobe Systems Incorporated. All rights reserved.

2324

Adobe ColdFusion Documentation


///We need an absolute path, so get the current directory path.
theFile=GetDirectoryFromPath(GetCurrentTemplatePath()) & "shiftcolumns.xls";
//Create a new Excel spreadsheet object.
theSheet = SpreadsheetNew("Expenses");
//Set some cell values, indicating their initial location.
SpreadsheetSetCellValue(theSheet,"Cell D10",10,4);
SpreadsheetSetCellValue(theSheet,"Cell E12",12,5);
SpreadsheetSetCellValue(theSheet,"Cell F12",12,6);
SpreadsheetSetCellValue(theSheet,"Cell G13",13,7);
//Shift columns 6 and 7 left 2 columns.
SpreadsheetShiftColumns(theSheet,6,7,-2);




© 2014 Adobe Systems Incorporated. All rights reserved.

2325

Adobe ColdFusion Documentation

SpreadsheetShiftRows
Description

Shifts one or more rows in Excel spreadsheet object up or down. The contents of the shifted row, including empty
cells, overwrites data in the column to which it is shifted.
Returns

Does not return a value.
Category

Microsoft Office Integration
Function syntax

SpreadsheetShiftRows(spreadsheetObj, start[, rows]
SpreadsheetShiftRows(spreadsheetObj, start, end, rows)

See also

SpreadsheetAddRow, SpreadsheetAddRows, SpreadsheetDeleteRow, SpreadsheetDeleteRows, Spread
sheetFormatRow, SpreadsheetFormatRows, SpreadsheetShiftColumns
History

ColdFusion 9: Added the function.
Parameters

Parameter

Description

spreadsheetObj

The Excel spreadsheet object in which to make the
shift.

start

The number of the first row to shift

end

The number of the last row to shift. If you omit this
parameter, the function shifts a single row.

rows

The positive (down) or negative (up) number of rows by
which to shift the rows. If you omit this parameter, the
function shifts the row down by one unit.

Usage
Example

The following line shifts 10 and 11 down two rows. Notice that the shifted rows completely overwrite the previous
rows 12 and 13.

© 2014 Adobe Systems Incorporated. All rights reserved.

2326

Adobe ColdFusion Documentation


///We need an absolute path, so get the current directory path.
theFile=GetDirectoryFromPath(GetCurrentTemplatePath()) & "shiftrows.xls";
//Create a new Excel spreadsheet object.
theSheet = SpreadsheetNew("Expenses");
//Set some cell values, indicating their initial location.
SpreadsheetSetCellValue(theSheet,"Cell D10",10,4);
SpreadsheetSetCellValue(theSheet,"Cell E11",11,5);
SpreadsheetSetCellValue(theSheet,"Cell A12",12,1);
SpreadsheetSetCellValue(theSheet,"Cell B13",13,2);
//Shift rows 10 and 11 down 2 rows.
SpreadsheetShiftRows(theSheet,10,11,2);




© 2014 Adobe Systems Incorporated. All rights reserved.

2327

Adobe ColdFusion Documentation

SpreadsheetWrite
Description

Writes single sheet to a new XLS file from a ColdFusion spreadsheet object.
Category

Microsoft Office Integration
Function syntax

SpreadSheetWrite(SpreadsheetObj,
SpreadSheetWrite(SpreadsheetObj,
SpreadSheetWrite(SpreadsheetObj,
SpreadSheetWrite(SpreadsheetObj,

fileName)
fileName [,overwrite])
fileName [, password])
fileName [, password,overwrite])

SpreadSheetWrite(SpreadsheetObj, fileName [, password,overwrite,autosize])

See also

SpreadsheetRead, SpreadsheetAddRow, SpreadsheetAddRows, SpreadsheetDeleteRow, SpreadsheetD
eleteRows, SpreadsheetFormatRow, SpreadsheetFormatRows, SpreadsheetShiftColumns
History

ColdFusion 11: Added the autosize attribute.
ColdFusion 9: Added the function.
Parameters

Parameter

Description

spreadSheetObj

The Excel spreadsheet object to which to write.

fileName

The pathname of the file that is written.

overwrite

A Boolean value specifying whether to overwrite an
existing file. Specify yes to overwrite.

password

Password to protect the active sheet. Password is
applicable only for Excel 97 - 2003 file formats. It will
be ignored for XML file format (Excel 2007).

autosize

Auto re-size the column, if required. You can specify
either a Boolean value or an array of integers denoting
the columns to expand. If you specify an array, it must
contain the column numbers that needs to be re-sized.

Usage

© 2014 Adobe Systems Incorporated. All rights reserved.

2328

Adobe ColdFusion Documentation

Use this function to:
Write multiple sheets to a single file.
Update an existing file, read all sheets in the file, modify one or more sheets, and to rewrite the entire file.
Example


spreadsheet = SpreadSheetRead("C:\Files\Report.xls","Annual Report");
SpreadSheetWrite(spreadsheet,"C:\Files\Report.xls","P@ssword","yes");


Example 2


spObj = spreadsheetread("#dirname#SingleSheet.xls","Sheet2");
spreadsheetCreateSheet(spObj,"A");
spreadsheetaddrow(spObj,"x,x,x,x,x",3,1);
spreadsheetsetActiveSheet(spObj,"A");
spreadsheetaddrow(spObj,"z,z,z,z,z",3,1);
spreadsheetsetActiveSheetNumber(spObj,1);
spreadsheetaddrow(spObj,"a,b,c,d,e",3,1);
SpreadsheetWrite(spObj,"#dirname#SingleSheet1.xls","yes");


Example 3

© 2014 Adobe Systems Incorporated. All rights reserved.

2329

Adobe ColdFusion Documentation



password, overwrite, autosize)














© 2014 Adobe Systems Incorporated. All rights reserved.

2330

Adobe ColdFusion Documentation

Sqr
Description

Calculates the square root of a number.
Returns

Number; square root of number.
Category

Mathematical functions
Function syntax

Sqr(number)

See also

Abs
Parameters

Parameter

Description

number

A positive integer or a variable that contains one.
Number whose square root to get.

Usage

The value in number must be greater than or equal to 0.
Example

Sqr Example
Returns the square root of a positive number.
Sqr(2): #Sqr(2)#
Sqr(Abs(-144)): #Sqr(Abs(-144))#
Sqr(25^2): #Sqr(25^2)#

© 2014 Adobe Systems Incorporated. All rights reserved.

2331

Adobe ColdFusion Documentation

StripCR
Description

Deletes return characters from a string.
Returns

A copy of string, after removing return characters.
Category

Display and formatting functions, String functions
Function syntax

StripCR(string)

See also

ParagraphFormat
Parameters

Parameter

Description

string

A string or a variable that contains one

Usage

Useful for preformatted (between 
 and 
 tags) HTML display of data entered in textarea fields.
Example

© 2014 Adobe Systems Incorporated. All rights reserved.

2332

Adobe ColdFusion Documentation

StripCR Example
Function StripCR is useful for preformatted HTML display of data
(PRE) entered in textarea fields.

#StripCR(Form.myTextArea)#




This is sample text and you see how it scrolls
<cfoutput>#Chr(10)##Chr(13)#</cfoutput>
From one line
<cfoutput>#Chr(10)##Chr(13)##Chr(10)##Chr(13)#</cfoutput>
to the next




© 2014 Adobe Systems Incorporated. All rights reserved.

2333

Adobe ColdFusion Documentation

StructAppend
Description

Appends one structure to another.
Returns

True, upon successful completion; False, otherwise.
Category

Structure functions
Function syntax

StructAppend(struct1, struct2, overwriteFlag)

See also

Structure functions; Modifying a ColdFusion XML object in the Developing ColdFusion Applications
History

ColdFusion MX: Changed behavior: this function can be used on XML objects.
Parameters

Parameter

Description

struct1

Structure to which struct2 is appended.

struct2

Structure that contains the data to append to struct1

overwriteFlag

True or Yes: values in struct2 overwrite
corresponding values in struct1. Default.
False or No: values in struct2 do not overwrite
corresponding values in struct1.

Usage

This function appends the fields and values of struct2 to struct1; struct2 is not modified. If struct1 already
contains a field of struct2, overwriteFlag determines whether the value in struct2 overwrites it. A structure's
keys are unordered.
Example

© 2014 Adobe Systems Incorporated. All rights reserved.

2334

Adobe ColdFusion Documentation




















The person struct before the Append call:



#myItem#







The person struct after the Append call:



#myItem#




© 2014 Adobe Systems Incorporated. All rights reserved.

2335

Adobe ColdFusion Documentation

StructClear
Description

Removes all data from a structure.
Returns

True, on successful execution; False, otherwise.
Category

Structure functions
Function syntax

StructClear(structure)

See also

Structure functions; Modifying a ColdFusion XML object in the Developing ColdFusion Applications
History

ColdFusion MX: Changed behavior: this function can be used on XML objects.
Parameters

Parameter

Description

structure

Structure to clear

Usage

Do not call this function on a session variable. For more information, see TechNote, " ColdFusion 4.5 and the
StructClear(Session) function," at go.adobe.com/kb/ts_tn_17479_en-us. (The article applies to ColdFusion 4.5, 5.x,
and ColdFusion MX.)
Example

© 2014 Adobe Systems Incorporated. All rights reserved.

2336

Adobe ColdFusion Documentation



Add New Employees







Please fill out the form.



employee = StructNew();
StructInsert(employee, "firstname", Form.firstname);
StructInsert(employee, "lastname", Form.lastname);
StructInsert(employee, "email", Form.email);
StructInsert(employee, "phone", Form.phone);
StructInsert(employee, "department", Form.department);




StructClear(employee);


© 2014 Adobe Systems Incorporated. All rights reserved.

2337

Adobe ColdFusion Documentation

StructCopy
Description

Copies a structure. Copies top-level keys, values, and arrays in the structure by value; copies nested structures by
reference.
Returns

A copy of a structure, with the same keys and values; if structure does not exist, throws an exception.
Category

Structure functions
Function syntax

StructCopy(structure)

See also

Structure functions; Structure functions in the Developing ColdFusion Applications
Parameters

Parameter

Description

structure

Structure to copy

Usage

The following code shows how this function copies a structure that contains a string field, a number field, and a
two-dimensional array at the top-level:










The following code shows how StructCopy copies a nested structure:





© 2014 Adobe Systems Incorporated. All rights reserved.

2338

Adobe ColdFusion Documentation

To copy a structure entirely by value, use Duplicate.The following table shows how variables are assigned:
Variable type

Assigned by

structure.any_simple_valueBooleanBinaryBase64

Value

structure.array

Value

structure.nested_structure

Reference

structure.object

Reference

structure.query

Reference

Example


// This script creates a structure that StructCopy copies by value. 


// Create elements.
s = StructNew();
s.array = ArrayNew(2);
// Assign simple values to original top-level structure fields.
s.number = 99;
s.string = "hello tommy";
// Assign values to original top-level array.
s.array[1][1] = "one one";
s.array[1][2] = "one two";



Original Values


// Simple values 

s.number = #s.number#

s.string = #s.string#

// Array value 

s.array[1][1] = #s.array[1][1]#

s.array[1][2] = #s.array[1][2]#


// Copy this structure to a new structure. 



// Change the values of the original structure. 

s.number = 100;
s.string = "hello tommy (modified)";
s.array[1][1] = "one one (modified)";
s.array[1][2] = "one two (modified)";


© 2014 Adobe Systems Incorporated. All rights reserved.

2339

Adobe ColdFusion Documentation


Modified Original Values


// Simple values 

s.number = #s.number#

s.string = #s.string#

// Array value 

s.array[1][1] = #s.array[1][1]#

s.array[1][2] = #s.array[1][2]#



Copied structure values should be the same as the original.


// Simple values 

copied.number = #copied.number#

copied.string = #copied.string#

// Array value 

copied.array[1][1] = #copied.array[1][1]#

copied.array[1][2] = #copied.array[1][2]#


// This script creates a structure that StructCopy copies by reference.

// Create elements.
s = StructNew();
s.nested = StructNew();
s.nested.array = ArrayNew(2);
// Assign simple values to nested structure fields.
s.nested.number = 99;
s.nested.string = "hello tommy";
// Assign values to nested array.
s.nested.array[1][1] = "one one";
s.nested.array[1][2] = "one two";



Original Values


// Simple values 

s.nested.number = #s.nested.number#

s.nested.string = #s.nested.string#

// Array values 

s.nested.array[1][1] = #s.nested.array[1][1]#

s.nested.array[1][2] = #s.nested.array[1][2]#


// Use

copied = StructCopy(s)>
Duplicate to clone this structure to a new structure. 

duplicated = Duplicate(s)>


// Change the values of the original structure.
s.nested.number = 100;
s.nested.string = "hello tommy (modified)";
s.nested.array[1][1] = "one one (modified)";
s.nested.array[1][2] = "one two (modified)";

© 2014 Adobe Systems Incorporated. All rights reserved.

2340

Adobe ColdFusion Documentation



Modified Original Values


// Simple values 

s.nested.number = #s.nested.number#

s.nested.string = #s.nested.string#

// Array value 

s.nested.array[1][1] = #s.nested.array[1][1]#

s.nested.array[1][2] = #s.nested.array[1][2]#



Copied structure values should reflect changes to original.


// Simple values 

copied.nested.number = #copied.nested.number#

copied.nested.string = #copied.nested.string#

// Array values 

copied.nested.array[1][1] = #copied.nested.array[1][1]#

copied.nested.array[1][2] = #copied.nested.array[1][2]#



Duplicated structure values should remain unchanged.


// Simple values 

duplicated.nested.number = #duplicated.nested.number#

duplicated.nested.string = #duplicated.nested.string#

// Array value 

duplicated.nested.array[1][1] = #duplicated.nested.array[1][1]#


© 2014 Adobe Systems Incorporated. All rights reserved.

2341

Adobe ColdFusion Documentation

duplicated.nested.array[1][2] = #duplicated.nested.array[1][2]#



© 2014 Adobe Systems Incorporated. All rights reserved.

2342

Adobe ColdFusion Documentation

StructCount
Description

Counts the keys in a structure.
Returns

A number; if structure does not exist, throws an exception.
Category

Structure functions
Function syntax

StructCount(structure)

See also

Structure functions; Modifying a ColdFusion XML object in the Developing ColdFusion Applications
History

ColdFusion MX: Changed behavior: this function can be used on XML objects.
Parameters

Parameter

Description

structure

Structure to access

Example

© 2014 Adobe Systems Incorporated. All rights reserved.

2343

Adobe ColdFusion Documentation


This file is similar to addemployee.cfm, which is called by
StructNew, StructClear, and StructDelete. To test, copy
StructCount function to appropriate place in addemployee.cfm.


© 2014 Adobe Systems Incorporated. All rights reserved.

2344

Adobe ColdFusion Documentation

StructDelete
Description

Removes an element from a structure.
Returns

Boolean value. The value depends on the indicatenotexisting parameter value.
Category

Structure functions
Function syntax

StructDelete(structure, key [, indicatenotexisting ])

See also

Structure functions; Modifying a ColdFusion XML object in the Developing ColdFusion Applications
History

ColdFusion MX: Changed behavior: this function can be used on XML objects.
Parameters

Parameter

Description

structure

Structure or a variable that contains one. Contains
element to remove.

key

Element to remove.

indicatenotexisting

True: returns Yes if key exists; No if it does not.
False: returns Yes regardless of whether key exists.
Default.

Example

© 2014 Adobe Systems Incorporated. All rights reserved.

2345

Adobe ColdFusion Documentation

StructDelete Function








Field to be deleted: #form.field#



employee = StructNew();
StructInsert(employee, "firstname", firstname);
StructInsert(employee, "lastname", lastname);
StructInsert(employee, "email", email);
StructInsert(employee, "phone", phone);
StructInsert(employee, "department", department);

Before deletion, employee structure looks like this:





Did I delete the field "#form.field#"? The code indicates: #rc#

The structure now looks like this:










Select the field to be deleted: 

first name
last name
email
phone
department



Delete this comment to make this page work --->

© 2014 Adobe Systems Incorporated. All rights reserved.

2346

Adobe ColdFusion Documentation

StructEach
Description

Used to loop over elements in a structure by accessing key-value pairs.
Returns

Nothing
Category

Closure functions
Syntax

structEach(struct,function(key, value) {});
See also

Other closure functions.
History

ColdFusion 10: Added this function.
Parameters

Parameter

Description

struct

Name of the structure object.

function

Inline function executed for each key - value pair in the
struct.

key

Key in a struct.

value

Value in a struct.

© 2014 Adobe Systems Incorporated. All rights reserved.

2347

Adobe ColdFusion Documentation

StructFilter
Description

Used to filter the key value pairs in a struct.
Returns

A new struct
Category

Closure functions
Syntax

structFilter(struct,function(key, value){return true|false;});
See also

Other closure functions.
History

ColdFusion 10: Added this function.
Parameters

Parameter

Description

struct

Name of the struct object.

function

Inline function executed for each element in the array.
Returns true if the key value pair in the struct has to
be included in the resultant struct.

key

Key in a struct.

value

Value in a struct.

© 2014 Adobe Systems Incorporated. All rights reserved.

2348

Adobe ColdFusion Documentation

StructFind
Description

Determines the value associated with a key in a structure.
Returns

The value associated with a key in a structure; if structure does not exist, throws an exception.
Category

Structure functions
Function syntax

StructFind(structure, key)

See also

Structure functions; Structure functions in the Developing ColdFusion Applications
Parameters

Parameter

Description

structure

Structure that contains the value to return

key

Key whose value to return

Usage

A structure's keys are unordered.
Example

© 2014 Adobe Systems Incorporated. All rights reserved.

2349

Adobe ColdFusion Documentation


This file is identical to addemployee.cfm, which is called by StructNew,
StructClear, and StructDelete. It adds employees. Employee information
is passed through the employee structure (EMPINFO attribute). In UNIX,
you must also add the Emp_ID.


© 2014 Adobe Systems Incorporated. All rights reserved.

2350

Adobe ColdFusion Documentation

StructFindKey
Description

Searches recursively through a substructure of nested arrays, structures, and other elements, for structures whose
keys match the search key in the value parameter.
Returns

An array that contains structures with keys that match value.
Category

Structure functions
Function syntax

StructFindKey(top, value, scope)

See also

Structure functions; Structure functions in the Developing ColdFusion Applications
Parameters

Parameter

Description

top

ColdFusion object (structure or array) from which to
start search. This parameter requires an object, not a
name of an object.

value

String or a variable that contains one for which to
search.

scope

one: returns one matching key. Default.
all: returns all matching keys.
If the key is not found, an empty array is returned.

Usage

Returns an array that includes one structure for each of the specified keys it finds. The fields of each of these
structures are:
Value: value held in the found key
Path: string that can be used to reach the found key
Owner: parent object that contains the found key
A structure's keys are unordered.
Example

© 2014 Adobe Systems Incorporated. All rights reserved.

2351

Adobe ColdFusion Documentation



© 2014 Adobe Systems Incorporated. All rights reserved.

2352

Adobe ColdFusion Documentation

StructFindValue
Description

Searches recursively through a substructure of nested arrays, structures, and other elements for structures with
values that match the search key in the value parameter.
Returns

An array that contains structures keys whose values match the search key value. If none are found, returns an array
of size 0.
Category

Structure functions
Function syntax

StructFindValue( top, value [, scope])

See also

Structure functions; Structure functions in the Developing ColdFusion Applications
Parameters

Parameter

Description

top

ColdFusion structure from which to start search. This
parameter requires an object, not a name of an object.

value

String or a variable that contains one for which to
search. The type must be a simple object. Arrays and
structures are not supported.

scope

one: function returns one matching key (default).
all: function returns all matching keys.

Usage

The fields of each structure in the returned array are:
Key: name of the key in which the value was found
Path: string which could be used to reach the found key
Owner: parent object that contains the found key
A structure's keys are unordered.
Example



© 2014 Adobe Systems Incorporated. All rights reserved.

2353

Adobe ColdFusion Documentation

© 2014 Adobe Systems Incorporated. All rights reserved.

2354

Adobe ColdFusion Documentation

StructGet
Description

Gets a structure(s) from a specified path.
Returns

An alias to the variable in the pathDesired parameter. If necessary, StructGet creates structures or arrays to
make pathDesired a valid variable "path."
Category

Structure functions
Function syntax

StructGet(pathDesired)

See also

Structure functions; Modifying a ColdFusion XML object in the Developing ColdFusion Applications
History

ColdFusion MX:
Changed behavior: this function can be used on XML objects.
Changed behavior: if there is no structure or array present in pathDesired, this function creates structures or
arrays to make pathDesired a valid variable "path."
Parameters

Parameter

Description

pathDesired

Pathname of variable that contains structure or array
from which ColdFusion retrieves structure.

Usage

You can inadvertently create invalid structures using this function. For example, if array notation is used to expand
an existing array, the specified new element is created, regardless of the type currently held in the array.
Example

© 2014 Adobe Systems Incorporated. All rights reserved.

2355

Adobe ColdFusion Documentation





Dog is not defined



Dog.Myscope is not defined



Dog.Myscope.Test is not defined



Dog.Myscope.Test.Foo is not defined



#dog.myscope.test.foo#





#request.myscope[1].test.foo#





#request.myscope[1].test[2].foo#



© 2014 Adobe Systems Incorporated. All rights reserved.

2356

Adobe ColdFusion Documentation

StructInsert
Description

Inserts a key-value pair into a structure.
Returns

True, upon successful completion. If structure does not exist, or if key exists and allowoverwrite =
"False", ColdFusion throws an exception.
Category

Structure functions
Function syntax

StructInsert(structure, key, value [, allowoverwrite ])

See also

Structure functions; Modifying a ColdFusion XML object in the Developing ColdFusion Applications
History

ColdFusion MX: Changed behavior: this function can be used on XML objects.
Parameters

Parameter

Description

structure

Structure to contain the new key-value pair.

key

Key that contains the inserted value.

value

Value to add.

allowoverwrite

Optional. Whether to allow overwriting a key. The
default value is False.

Usage

A structure's keys are unordered.
Example

© 2014 Adobe Systems Incorporated. All rights reserved.

2357

Adobe ColdFusion Documentation

Add New Employees







Please fill out the form.



employee = StructNew();
StructInsert(employee, "firstname", FORM.firstname);
StructInsert(employee, "lastname", FORM.lastname);
StructInsert(employee, "email", FORM.email);
StructInsert(employee, "phone", FORM.phone);
StructInsert(employee, "department", FORM.department);

First name is #StructFind(employee, "firstname")#
Last name is #StructFind(employee, "lastname")#
EMail is #StructFind(employee, "email")#
Phone is #StructFind(employee, "phone")#
Department is #StructFind(employee, "department")#






First Name: 

Last Name: 

EMail: 

Phone: 

Department: 





© 2014 Adobe Systems Incorporated. All rights reserved.

2358

Adobe ColdFusion Documentation

StructIsEmpty
Description

Determines whether a structure contains data.
Returns

True, if structure is empty; if structure does not exist, ColdFusion throws an exception.
Category

Decision functions, Structure functions
Function syntax

StructIsEmpty(structure)

See also

Structure functions; Modifying a ColdFusion XML object in the Developing ColdFusion Applications
History

ColdFusion MX: Changed behavior: this function can be used on XML objects.
Parameters

Parameter

Description

structure

Structure to test

Example

© 2014 Adobe Systems Incorporated. All rights reserved.

2359

Adobe ColdFusion Documentation


This file is identical to addemployee.cfm, which is called by StructNew,
StructClear, and StructDelete. It adds employees. Employee information
is passed through employee structure (EMPINFO attribute). In UNIX, you
must also add the Emp_ID.



Error. No employee data was passed.




INSERT INTO Employees
(FirstName, LastName, Email, Phone, Department)
VALUES

(
'#StructFind(attributes.EMPINFO, "firstname")#' ,
'#StructFind(attributes.EMPINFO, "lastname")#' ,
'#StructFind(attributes.EMPINFO, "email")#' ,
'#StructFind(attributes.EMPINFO, "phone")#' ,
'#StructFind(attributes.EMPINFO, "department")#'
)



Employee Add Complete



© 2014 Adobe Systems Incorporated. All rights reserved.

2360

Adobe ColdFusion Documentation

StructKeyArray
Description

Finds the keys in a ColdFusion structure.
Returns

An array of keys; if structure does not exist, ColdFusion throws an exception.
Category

Structure functions
Function syntax

StructKeyArray(structure)

See also

Structure functions; Modifying a ColdFusion XML object in the Developing ColdFusion Applications
Parameters

Parameter

Description

structure

Structure from which to extract a list of keys

Usage

A structure's keys are unordered.
Example


StructKeyArray Example
Extracting the Keys from the Employee Structure














© 2014 Adobe Systems Incorporated. All rights reserved.

2361

Adobe ColdFusion Documentation

 This example uses the StructNew function to create a structure called
"employee" that supplies employee info. Its fields are filled by
the form. After you enter employee information in structure, the
example uses StructKeyArray function to copy all of the keys from
the structure into an array. 




First Name:



Last Name:



EMail



Phone:



Company:




After you submit the FORM, scroll down to see the array.








Key#i# is #keysToStruct[i]#
Value#i# is #employee[keysToStruct[i]]#


© 2014 Adobe Systems Incorporated. All rights reserved.

2362

Adobe ColdFusion Documentation




© 2014 Adobe Systems Incorporated. All rights reserved.

2363

Adobe ColdFusion Documentation

StructKeyExists
Description

Determines whether a specific key is present in a structure.
Returns

True, if key is in structure.
Category

Decision functions, Structure functions
Function syntax

StructKeyExists(structure, "key")

See also

Structure functions; Structure functions in the Developing ColdFusion Applications
Parameters

Parameter

Description

structure

Name of structure to test

key

Key to test

Usage

This function can sometimes be used in place of the IsDefined function, when working with the URL and Form
scopes, which are structures. The following pieces of code are equivalent:

cfif IsDefined("Form.JediMaster")>


A structure's keys are unordered.
Example

© 2014 Adobe Systems Incorporated. All rights reserved.

2364

Adobe ColdFusion Documentation


This file is similar to addemployee.cfm, which is called by StructNew,
StructClear, and StructDelete. To test, copy the <CFELSEif>
statement to the appropriate place in addemployee.cfm. It is a custom tag
to add employees. Employee information is passed through the employee
structure (the EMPINFO attribute). In UNIX, you must also add the Emp_ID.



Error. No employee data was passed.


StructUpdate(attributes.EMPINFO, "department",
"Unassigned");




© 2014 Adobe Systems Incorporated. All rights reserved.

2365

Adobe ColdFusion Documentation

StructKeyList
Description

Extracts keys from a ColdFusion structure.
Returns

A list of keys; if structure does not exist, ColdFusion throws an exception.
Category

Structure functions
Function syntax

StructKeyList(structure [, delimiter])

See also

Structure functions; Modifying a ColdFusion XML object in the Developing ColdFusion Applications
Parameters

Parameter

Description

structure

Structure from which to extract a list of keys.

delimiter

Optional. Character that separates keys in list. The
default value is comma.

Usage

A structure's keys are unordered.
Example














© 2014 Adobe Systems Incorporated. All rights reserved.

2366

Adobe ColdFusion Documentation








StructKeyList Function
Listing the Keys in the Employees Structure
This example uses StructNew function to create structure "employee" that
supplies employee information. The fields are filled with the
contents of the following form.
After you enter employee information into structure, example uses
StructKeyList function to list keys in structure.
This code does not show how to insert information into a database.
See cfquery for more information about database insertion.




First Name:



Last Name:



EMail



Phone:



Company:




After you submit form, scroll down
to see the list.





")>
Here are the keys to the structure:

 #keysToStruct#

If fields are correct, we can process new employee information.

© 2014 Adobe Systems Incorporated. All rights reserved.

2367

Adobe ColdFusion Documentation

If they are not correct, consider rewriting application.


© 2014 Adobe Systems Incorporated. All rights reserved.

2368

Adobe ColdFusion Documentation

StructNew
Description

Creates a structure.
Returns

A structure.
Category

Structure functions
Function syntax

StructNew()

See also

Structure functions; Structure functions in the Developing ColdFusion Applications
Parameters

None
Example

© 2014 Adobe Systems Incorporated. All rights reserved.

2369

Adobe ColdFusion Documentation


Add New Employees






Please fill out the form.



employee = StructNew();
StructInsert(employee, "firstname", FORM.firstname);
StructInsert(employee, "lastname", FORM.lastname);
StructInsert(employee, "email", FORM.email);
StructInsert(employee, "phone", FORM.phone);
StructInsert(employee, "department", FORM.department);

First name is #StructFind(employee, "firstname")#
Last name is #StructFind(employee, "lastname")#
EMail is #StructFind(employee, "email")#
Phone is #StructFind(employee, "phone")#
Department is #StructFind(employee, "department")#





© 2014 Adobe Systems Incorporated. All rights reserved.

2370

Adobe ColdFusion Documentation

StructSort
Description

Returns a sorted array of the top level keys in a structure. Sorts using alphabetic or numeric sorting, and can sort
based on the values of any structure element.
Returns

An array of top-level key names (strings), sorted by the value of the specified subelement.
Category

Structure functions
Function syntax

StructSort(base[, sortType[, sortOrder[, pathToSubElement[, localeSensitive]]]])

See also

Structure functions; Structure functions in the Developing ColdFusion Applications
Parameters

Parameter

Description

base

A ColdFusion structure

sortType

numeric
text: case sensitive (all lowercase letters precede the
first uppercase letter). Default.
textnocase

sortOrder

asc: ascending (a to z) sort order. Default.
desc: descending (z to a) sort order

pathToSubElement

String or a variable that contains one.Path to apply to
each top-level key, to reach element value by which to
sort. The default value is nothing (top-level entries
sorted by their own values).

localeSensitive

Specify if you wish to do a locale sensitive sorting. The
default value is false.

Usage

The pathToSubElement string does not support array notation, and only supports substructures of structures.This
function does not sort or change the structure.In ColdFusion 10, added support for all Java supported locale-specific
characters (including support for umlaut characters). A flag for this support has been added for sorttype =
"text" or sorttype = "textnocase".

© 2014 Adobe Systems Incorporated. All rights reserved.

2371

Adobe ColdFusion Documentation
Example


salaries = StructNew() ;
employees = StructNew() ;
departments = StructNew() ;
for ( i=1; i lt 6; i=i+1 )
{
salary = 120000 - i*10000 ;
salaries["employee#i#"] = salary ;
employee = StructNew() ;
employee["salary"] = salary ;
// employee.salary = salary ;
employees["employee#i#"] = employee ;
departments["department#i#"] = StructNew() ;
departments["department#i#"].boss = employee ;
}


list of employees based on the salary (text search): 

1) #ArrayToList( StructSort( salaries ) )#

2) #ArrayToList( StructSort( salaries, "text", "ASC" ) )#

3) #ArrayToList( StructSort( salaries, "textnocase", "ASC" ) )#

4) #ArrayToList( StructSort( salaries, "text", "DESC" ) )#

list of employees based on the salary (numeric search): 

5) #ArrayToList( StructSort( salaries, "numeric", "ASC" ) )#

6) #ArrayToList( StructSort( salaries, "numeric", "DESC" ) )#

list of employees based on the salary (subfield search): 

7) #ArrayToList( StructSort( employees, "numeric", "DESC", "salary" ) )#

8) #ArrayToList( StructSort( employees, "text", "ASC","salary" ) )#

list of departments based on the salary (sub-sub-field search): 

9) #ArrayToList( StructSort( departments, "text", "ASC", "boss.salary" ) )#







We have a problem - this was supposed to throw an exception!




ERROR: This error was expected!

#cfcatch.message# - #cfcatch.detail#





© 2014 Adobe Systems Incorporated. All rights reserved.

2372

Adobe ColdFusion Documentation

StructUpdate
Description

Updates a key with a value.
Returns

True, on successful execution; if the structure does not exist, ColdFusion throws an error.
Category

Structure functions
Function syntax

StructUpdate(structure, key, value)

See also

Structure functions; Modifying a ColdFusion XML object in the Developing ColdFusion Applications
History

ColdFusion MX: Changed behavior: this function can be used on XML objects.
Parameters

Parameter

Description

structure

Structure to update

key

Key, the value of which to update

value

New value

Example

© 2014 Adobe Systems Incorporated. All rights reserved.

2373

Adobe ColdFusion Documentation


This file is similar to addemployee.cfm, which is called by StructNew,
StructClear, and StructDelete. To test this file, copy the
<CFELSEIF> statement to the appropriate place in
addemployee.cfm. It is an example of a custom tag used to add
employees. Employee information is passed through the employee
structure (the EMPINFO attribute). In UNIX, you must also add the Emp_ID.



Error. No employee data was passed.



StructUpdate(attributes.EMPINFO, "department", "Unassigned");




#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

2374

Adobe ColdFusion Documentation

SpreadSheetAddPagebreaks
Description

A function to add page breaks for rows and columns.
Returns

Does not return a value.
Category

Microsoft Office Integration
Function syntax

SpreadSheetAddPagebreaks(Spreadsheetobj, rowbreaks, colbreaks )

History
ColdFusion 11: Added the function.
Parameters

Parameter

Description

spreadsheetObj

The Excel spreadsheet object to which to add the
column.

rowbreaks

Comma-delimited row numbers where the page breaks
will be applied.

colbreaks

Comma-delimited column numbers where the page
breaks will be applied.

Example

© 2014 Adobe Systems Incorporated. All rights reserved.

2375

Adobe ColdFusion Documentation















© 2014 Adobe Systems Incorporated. All rights reserved.

2376

Adobe ColdFusion Documentation

SpreadSheetAddAutofilter
Description

A function to add auto filters to the spreadsheet.
Returns

Does not return a value.
Category

Microsoft Office Integration
Function syntax

SpreadSheetAddAutofilter(Spreadsheetobj, autofilter )

History

ColdFusion 11: Added the function.
Parameters

Parameter

Description

spreadsheetObj

The Excel spreadsheet object to which to add the
column.

autofilter

The Excel filter that needs to be applied to the sheet.
Note that the value should not contain spaces or invalid
characters.

Example

© 2014 Adobe Systems Incorporated. All rights reserved.

2377

Adobe ColdFusion Documentation


rowCount = 100>
qryObj = QueryNew("#colList#")>
QueryAddRow(qryObj, #rowCount#)>












© 2014 Adobe Systems Incorporated. All rights reserved.

2378

Adobe ColdFusion Documentation

StructReduce
Description
Iterates over every entry of the struct and calls the closure to work on the key value pair of the struct. This function
will reduce the struct to a single value and will return the value.
Returns

any
Syntax

StructReduce(struct, function(result, key, value [,struct]), initialVal)

History

ColdFusion 11: Added this function.
Attributes

Attribute

Req/Opt

Default

Description

struct

Required

The input struct.

function

Required

Closure or a function
reference that will be
called for each of the
iteration. The arguments
passed to the callback are
result: the result of the
reduce operation after
the previous iteration
key: key for the current
iteration
value: the value for the
current iteration
struct: a reference of
the original struct

initialVal

Optional

Initial value which will be
used for the reduce
operation. The type is
any.

Example

© 2014 Adobe Systems Incorporated. All rights reserved.

2379

Adobe ColdFusion Documentation



person = {fname="John", lname="Doe"};

ucaseStruct = structMap(person, function(key, value)
{
return ucase(value);
});

writeDump(ucaseStruct);
concatValues = structReduce(person, function(result, key, value)
{
result = result?:"";
result&= value & " ";
return result;
});

writeDump(concatValues);


© 2014 Adobe Systems Incorporated. All rights reserved.

2380

Adobe ColdFusion Documentation

StructMap
Description
Iterates over every entry of the Struct and calls the closure function to work on the key value pair of the struct. The
returned value will be set for the same key in a new struct and the new struct will be returned.
Returns

Struct
Syntax

StructMap(struct, function(key, value [,struct]))

History

ColdFusion 11: Added this function.
Attributes

Attribute

Req/Opt

Default

Description

struct

Required

The input struct.

function

Required

Closure or a function
reference that will be
called for each of the
iteration. The arguments
passed to the callback are
key: key for the current
iteration
value: the value for the
current iteration
struct: a reference of
the original struct

© 2014 Adobe Systems Incorporated. All rights reserved.

2381

Adobe ColdFusion Documentation

Serialize
Description

Serializes the object to a specified type
Returns

String
Function syntax

serialize( Object objToBeSerialized, String type, boolean useCustomSerializer )

History

ColdFusion 11: Added this function. For more information see REST Enhancements in ColdFusion 11.
Parameters

Parameter

Description

objToBeSerialized

Required. An object to be serialized.

type

A type to which the object will be serialized.
ColdFusion, by default supports XML and JSON
formats. You can also implement support for other
types in the CustomSerializer CFC.

useCustomSerializer

Boolean. Whether to use the custom serializer or not.
The default value is true. The custom serializer will be
always used for XML deserialization. If false, the
XML/JSON deserialization will be done using the
default ColdFusion behavior. If any other type is
passed with useCustomSerializer as false, then
TypeNotSupportedException will be thrown.

For more information on usage, see this document.

© 2014 Adobe Systems Incorporated. All rights reserved.

2382

Adobe ColdFusion Documentation

SerializeXML
Description

Serializes a ColdFusion object to XML.
Returns

String
Function syntax

serializeXml( Object objToBeSerialized, boolean useCustomSerializer )

History

ColdFusion 11: Added this function. For more information see REST Enhancements in ColdFusion 11.
Parameters

Parameter

Description

objToBeSerialized

Required. An object to be serialized.

useCustomSerializer

Boolean. Whether to use the custom serializer or not.
The default value is true. The custom serializer will be
always used for XML deserialization. If false, the
XML/JSON deserialization will be done using the
default ColdFusion behavior. If any other type is
passed with useCustomSerializer as false, then
TypeNotSupportedException will be thrown.

For more information on usage, see this document.

© 2014 Adobe Systems Incorporated. All rights reserved.

2383

Adobe ColdFusion Documentation

Functions t-z
Tan
ThreadJoin
ThreadTerminate
Throw
TimeFormat
ToBase64
ToBinary
ToScript
ToString
Trace
Transactionandconcurrency
TransactionCommit
TransactionRollback
TransactionSetSavePoint
Trim
UCase
URLDecode
URLEncodedFormat
URLSessionFormat
Val
ValueList
VerifyClient
Week
Wrap
WriteDump
WriteLog
WriteOutput
WSGetAllChannels
WSGetSubscribers
WSPublish
WSSendMessage
XmlChildPos
XmlElemNew
XmlFormat
XmlGetNodeType
XmlNew
XmlParse
XmlSearch
XmlTransform
XmlValidate
Year
YesNoFormat

© 2014 Adobe Systems Incorporated. All rights reserved.

2384

Adobe ColdFusion Documentation

Tan
Description

Calculates the tangent of an angle that is entered in radians.
Returns

A number; the tangent of an angle.
Category

Mathematical functions
Function syntax

Tan(number)

See also

Atn, Cos, ACos, Sin, ASin, Pi
Parameters

Parameter

Description

number

Angle, in radians, for which to calculate the tangent.

Usage

To convert degrees to radians, multiply degrees by p/180. To convert radians to degrees, multiply radians by 180/p.
Note
Because the function uses floating point arithmetic, it can return a small number (such as
6.12323399574E-017) for angles that must produce 0 and can return a large number (such as
1.63312393532E+016) for infinity or not a number. To test for a 0 value, check whether the value
is less than 0.0000000000001. To test for an infinite value, check whether the value is more than
1E15.

Example

© 2014 Adobe Systems Incorporated. All rights reserved.

2385

Adobe ColdFusion Documentation

Tan Example











Tan(#FORM.tanNum#) = #tanValue#





You must enter a numeric angle in degrees.



Enter an angle in degrees to get its tangent:





  


© 2014 Adobe Systems Incorporated. All rights reserved.

2386

Adobe ColdFusion Documentation

ThreadJoin
Description

Makes the current thread wait until the thread or threads specified complete processing.
Category

Exception handling functions, Data output functions
Function syntax

ThreadJoin([threadName], [timeout])

See also

cfscript, cfthrow, cftry, cfcatch
History

ColdFusion 9: Added this function.
Parameters

Parameter

Description

threadName

The name of the thread or threads to join to the current
thread. To specify multiple threads, use a
comma-separated list.

timeout

The number of milliseconds for which to suspend
thread processing.

Usage

Makes the current thread wait until the thread or threads specified in the {{threadName}}parameter complete
processing, or until the period specified in the {{timeout}}parameter passes, before continuing processing.
ThreadJoin(): Current thread waits for all ColdFusion threads to complete processing.
ThreadJoin(threadName): Makes current thread wait for the specified thread to finish execution.
ThreadJoin(threadName, timeout): Makes the current thread wait until execution timeout for one or
many threads specified by threadName. If you do not specify a timeout and the thread you are joining to
does not finish, the current thread also cannot finish processing.
Example

© 2014 Adobe Systems Incorporated. All rights reserved.

2387

Adobe ColdFusion Documentation


thread name="t1"
{
sleep(5000);
}
thread name="t2"
{
threadjoin("t1",1000);
}
threadjoin("t2");

Status of the thread T1 = #t1.Status#

Status of the thread T2 = #t2.Status#


© 2014 Adobe Systems Incorporated. All rights reserved.

2388

Adobe ColdFusion Documentation

ThreadTerminate
Description

Terminates the thread specified by threadName. Behaves same as cfthread action="terminate".
Category

Exception handling functions, Data output functions
Function syntax

ThreadTerminate(threadName)

See also

cfscript, cfthrow, cftry, cfcatch
History

ColdFusion 9: Added this function.
Parameters

Parameter

Description

threadName

The name of the thread to stop.

Usage

Use this function to stop processing of the thread specified in the threadName. If you terminate a thread, the thread
scope includes an ERROR metadata structure that provides information about the termination.
Example


thread name="t1"
{
sleep(3000);
}
sleep(1000);
threadTerminate("t1");
sleep(1000);

Status of the thread = #t1.Status#


© 2014 Adobe Systems Incorporated. All rights reserved.

2389

Adobe ColdFusion Documentation

Throw
Description

A function equivalent of the cfthrow tag and is used in the  mode.
Parameters

Same as the  tag.
Category

Exception handling functions, Data output functions
Function syntax

For name=value pair:

throw (message = "message", type = "exception type", detail, errorCode = "error
code", extendedInfo = "additional info", object = "java exception object")

For positional notations, the sequence must be followed exactly in the same manner as provided in the syntax. If
you do not provide one of the attributes, use an empty string instead.
History

ColdFusion 11: Attributes passed to this function needs to be in a comma-separated format.
ColdFusion 9: Added this function.
See also

cfscript, cfthrow, cftry, cfcatch
Usage

You can call this function by passing arguments as name=value pair or as positional arguments. For positional
notations, specify the arguments in the sequence mentioned in the function syntax.
Example

© 2014 Adobe Systems Incorporated. All rights reserved.

2390

Adobe ColdFusion Documentation


function TotalInterest(principal, annualRate, months)
{ var years = 0;
var interestRate = 0;
var totalInterest = 0;
principal = REReplace(trim(principal), "[\$]", "", "ALL");
annualRate = Replace(trim(annualRate), "%", "", "ALL");
if ((principal <= 0) OR (annualRate <= 0) OR (months <= 0)) {
Throw(type="InvalidData",message="All values must be greater than 0.");
//Use of Throw function in cfscript
}
interestRate = annualRate / 100;
years = months / 12;
totalInterest = principal * (((1 + interestRate) ^ years) - 1);
return DollarFormat(totalInterest);
}
try {
WriteOutput(TotalInterest("$2500.00", "5.5%", "12"));
} catch(InvalidData ex) {
//Displayig exception details on screen
WriteOutput("
An InvalidData exception was thrown.
");
WriteOutput("
#ex.message#
");
}


From ColdFusion 11, attributes passed to this function needs to be in a comma-separated
format.

© 2014 Adobe Systems Incorporated. All rights reserved.

2391

Adobe ColdFusion Documentation

TimeFormat
Description

Formats a time value using U.S. English time formatting conventions.
Returns

A custom-formatted time value. If no mask is specified, returns a time value using the hh:nn tt format. For
international time formatting, see LSTimeFormat.
Category

Date and time functions, Display and formatting functions
Function syntax

TimeFormat(time [, mask ])

See also

CreateTime, Now, ParseDateTime, LSTimeFormat, DateFormat
History

ColdFusion 10: The mask "m or M" for minute is deprecated. Recommended "n or N".
ColdFusion MX 6.1: Added the mask character L or l to represent milliseconds.
ColdFusion MX:
Changed the way extra characters are processed: this function processes extra characters within the maskval
ue differently than in earlier releases, as follows:
ColdFusion 5 and earlier: the function returns the time format and an apostrophe-delimited list of the
extra characters. For example, TimeFormat(Now(), "hh:mm:ss dog") returns 8:17:23 d'o'g.
ColdFusion MX: the function returns the time format and the extra characters. For example, for the call
above, it returns 8:17:23 dog.
If the extra characters are single-quoted (for example, hh:mm:ss 'dog'), ColdFusion 5 and
ColdFusion MX return the time format and the extra characters: 8:17:23 dog.
Added support for the following mask parameter options: short, medium, long, and full.
Parameters

Parameter

Description

time

A date/time value or string to convert

© 2014 Adobe Systems Incorporated. All rights reserved.

2392

Adobe ColdFusion Documentation

mask

Masking characters that determine the format:
h: hours; no leading zero for single-digit hours
(12-hour clock)
hh: hours; leading zero for single-digit hours (12-hour
clock)
H: hours; no leading zero for single-digit hours
(24-hour clock)
HH: hours; leading zero for single-digit hours
(24-hour clock)
n: minutes; no leading zero for single-digit minutes
nn: minutes; a leading zero for single-digit minutes
s: seconds; no leading zero for single-digit seconds
ss: seconds; leading zero for single-digit seconds
l or L: milliseconds, with no leading zeros
t: one-character time marker string, such as A or P
tt: multiple-character time marker string, such as AM
or PM
short: equivalent to h:mm tt
medium: equivalent to h:mm:ss tt
long: medium followed by three-letter time zone; as
in, 2:34:55 PM EST
full: same as long

Usage

When passing a date/time value as a string, enclose it in quotation marks. Otherwise, it is interpreted as a number
representation of a date/time object.Database query results for date and time values can vary in sequence and
formatting unless you use functions to format the results. To ensure that dates and times display with appropriate
formatting, and that users of your ColdFusion application are not confused by dates and times displayed, Adobe
recommends that you use the DateFormat and TimeFormat functions to format date and time values from
queries. For more information and examples, see TechNote, " ColdFusion (5 and 4.5.x) with Oracle: Formatting
Date and Time Query Results," at go.adobe.com/kb/ts_tn_18070_en-us.
Example

© 2014 Adobe Systems Incorporated. All rights reserved.

2393

Adobe ColdFusion Documentation



TimeFormat Example
Today's date is #todayDate#.
Using Timeformat, we can display the value in different ways:


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


To generate a standard ISO 8601 W3C Date and Time string like
1997-07-16T19:20, concatenate a DateFormat function, the character T, and a
TimeFormat function.
For example: dateformat(now(), "yyyy-mm-dd")#T#TimeFormat(now(), "HH:nn:ss")
produces:
#dateformat(now(), "yyyy-mm-dd")#T#TimeFormat(now(),
"HH:nn:ss")#


© 2014 Adobe Systems Incorporated. All rights reserved.

2394

Adobe ColdFusion Documentation

ToBase64
Description

Calculates the Base64 representation of a string or binary object. The Base64 format uses printable characters,
allowing binary data to be sent in forms and e-mail, and stored in a database or file.
Returns

The Base64 representation of a string or binary object.
Category

Conversion functions, String functions
Function syntax

ToBase64(string or binary_object[, encoding])

See also

BinaryEncode for conversion of binary data to base64
cffile for information about loading and reading binary data
cfwddx for information about serializing and deserializing binary data
IsBinary and ToBinary for checking for binary data and converting a Base64 object to binary format
History

ColdFusion MX: Added the encoding parameter.
Parameters

Parameter

Description

string or binary_object

A string, the name of a string, or a binary object.

© 2014 Adobe Systems Incorporated. All rights reserved.

2395

Adobe ColdFusion Documentation

encoding

For a string, defines how characters are represented in
a byte array. The following list includes commonly used
values:
utf-8
iso-8859-1
windows-1252
us-ascii
shift_jis
iso-2022-jp
euc-jp
euc-kr
big5
euc-cn
utf-16
For more information on character encoding, see: ww
w.w3.org/International/O-charset.html. The default
value is the encoding of the page on which the
function is called. See cfcontent. For a binary
object, this parameter is ignored.

Usage

Adobe recommends that you use the BinaryEncode function to convert binary data to Base64-encoded data in all
new applications.

ToBase64 Example








The following string is the concatenation of all characters (32 to 255)
from the ASCII table.

#charData#









Base64 representations are identical.

Conversion error.


© 2014 Adobe Systems Incorporated. All rights reserved.

2396

Adobe ColdFusion Documentation

ToBinary
Adobe recommends that you use the BinaryDecode function to convert Base64 encoded data to
binary data in all new applications.

Description
Calculates the binary representation of Base64-encoded data, PDF document, or a spreadsheet.
Returns

A binary representation of the data.
Category

Conversion functions, String functions
Function syntax

ToBinary(Data)

See also

BinaryDecode for conversion of binary-encoded data, including Base64, to binary data
cffile for information about loading and reading binary data
{{cfwddx}}for information about serializing and deserializing binary data
IsBinary and ToBase64 for checking format and converting to Base64
Len for determining the length of a binary object
Binary data type and binary encoding in Data types- Developing guide in the Developing ColdFusion
Applications
Parameters

Parameter

Description

Data

A variable representing data in Base64-encoded format
or a PDF document.

Usage

The ToBinary function can take as a parameter a PDF document variable (specified by the cfpdf tag name
attribute). In this case, the ToBinary function returns a byte array (byte[]) representation of the document. You can
use the results of this function, for example, to store the PDF in a database as a BLOB, or, in a cfcontent tag, to
write the PDF to the browser. You can use this binary representation with a read operation in the cfpdf tag to
create a variable.The following example reads an unprotected PDF file, applies protections, and displays it in the
browser:

© 2014 Adobe Systems Incorporated. All rights reserved.

2397

Adobe ColdFusion Documentation





Adobe recommends that you use the BinaryDecode function to convert Base64 encoded data to binary data in all
new applications.If you pass a binary value to this function, it returns the input value.
Example

ToBinary Example







The following string is the concatenation of all characters (32 to 255)
from the ASCII table.

#charData#








Base64 representation of binary data is identical to the Base64
representation of string data.

Conversion error.


© 2014 Adobe Systems Incorporated. All rights reserved.

2398

Adobe ColdFusion Documentation

ToScript
Description

Creates a JavaScript or ActionScript expression that assigns the value of a ColdFusion variable to a JavaScript or
ActionScript variable. This function can convert ColdFusion strings, numbers, arrays, structures, and queries to
JavaScript or ActionScript syntax that defines equivalent variables and values.
Returns

A string that contains a JavaScript or ActionScript variable definition corresponding to the specified ColdFusion
variable value.
Category

Conversion functions, Extensibility functions
Function syntax

ToScript(cfvar, javascriptvar, outputformat, ASFormat)

See also

cfwddx; WDDX JavaScript Objects__
History

ColdFusion MX 7: Added this function.
Parameters

Parameter

Description

cfvar

A ColdFusion variable. This can contain one of the
following:
String
Number
Array
Structure
Query

javascriptvar

A string that specifies the name of the JavaScript
variable that the ToScript function creates.

outputformat

Optional. A Boolean value that determines whether to
create WDDX (JavaScript) or ActionScript style output
for structures and queries:
True: creates WDDX-style output (default).
False: creates ActionScript-style output.

© 2014 Adobe Systems Incorporated. All rights reserved.

2399

Adobe ColdFusion Documentation

ASFormat

Optional. A Boolean value that specifies whether to use
ActionScript shortcuts in the script:
True: creates new Objects and Arrays with
ActionScript shortcuts:
for New Array(), and {} for New Object. Using
ActionScript shortcuts
allows you to pass ActionScript into cfform attribute
s
without triggering ActionScript validation.
False: does not use ActionScript shortcuts to create
new Objects and new Arrays when generating the
script. Instead, generates New Object() and New
Array() in the script (default).

Usage

To use a ColdFusion variable in JavaScript or ActionScript, the ToScript function must be in a cfoutput region
and be surrounded by number signs (#). For example, the following code uses the ToScript function to convert a
ColdFusion variable to a JavaScript variable:




When ColdFusion runs this code, it sends the following to the client:



An HTML script tag must enclose the JavaScript code. The cfoutput tag does not need to be inside the script
block; it can also surround the block.WDDX-style output generates JavaScript code that creates a WDDXRecordset
object, where the key of each record set entry is a column name, and the value of the recordlist entry is an array of
the corresponding query column entries, as follows:

© 2014 Adobe Systems Incorporated. All rights reserved.

2400

Adobe ColdFusion Documentation

WDDXQuery = new WddxRecordset();
col0 = new Array();
col0[0] = "John";
col0[1] = "John";
WDDXQuery["firstname"] = col0;
col0 = null;
col1 = new Array();
col1[0] = "Lund";
col1[1] = "Allen";
WDDXQuery["lastname"] = col1;
col1 = null;

To use WDDX-style output, first load the cf_webroot/CFIDE/scripts/wddx.js script, which defines JavaScript WDDX
objects, as in the following line:



For more information on WDDX in JavaScript, see WDDX JavaScript Objects.ActionScript-style output generates
code that creates an array of objects, where the array is indexed by row number, and the objects consist of column
name - column value pairs, as follows:

ActionScriptQuery = new Array();
ActionScriptQuery[0] = new Object();
ActionScriptQuery[0]['firstname'] = "John";
ActionScriptQuery[0]['lastname'] = "Lund";
ActionScriptQuery[1] = new Object();
ActionScriptQuery[1]['firstname'] = "John";
ActionScriptQuery[1]['lastname'] = "Allen";

An ActionScript-style array does not require you to include the wddx.js file, and creates a variable that you can use
in ActionScript on a Flash format form, for example, in an onChange attribute.If
the outputformat parameter is False, setting ASFormat to
True causes ToScript to use the ActionScript shortcut [] in
place of New Array() and the shortcut {} in
place of New Object(). Using these
shortcuts allows you to pass ActionScript into cfform attributes
without triggering ActionScript validation. If ASFormat is
False, ToScript generates New Array() and New Object() in
the script.
Example

The following example shows the results of converting a ColdFusion string, array, and query object to JavaScript
variables. It also uses the string and array in JavaScript code.

ToScript

© 2014 Adobe Systems Incorporated. All rights reserved.

2401

Adobe ColdFusion Documentation

Converting a string variable


The thisString variable in ColdFusion

#thisString#



The output of ToScript(thisString, "jsVar")

#ToScript(thisString, "jsVar")#



In a JavaScript script, convert thisString Variable to JavaScript
and output the resulting variable:



Converting an array






The ColdFusion myArray Array



myArry[#i#]: #myArray[i]#




The output of ToScript(myArray, "jsArray")

#toScript(myArray, "jsArray")#



In JavaScript, convert myArray to a JavaScript variable and write it's
contents




Converting a query
This section converts the following query object to both WDDX format
and ActionScript type JavaScript objects.



SELECT FirstName,LastName
FROM employee
WHERE FirstName = 'John'



The Query in ColdFusion



© 2014 Adobe Systems Incorporated. All rights reserved.

2402

Adobe ColdFusion Documentation



JavaScript generated by ToScript(thisQuery, "WDDXQuery"):

#toScript(thisQuery, "WDDXQuery")#;



JavaScript generated by ToScript(thisQuery, "ActionScriptQuery",
False):

#toScript(thisQuery, "ActionScriptQuery", False)#








© 2014 Adobe Systems Incorporated. All rights reserved.

2403

Adobe ColdFusion Documentation

ToString
Description

Converts a value to a string.
Returns

A string.
Category

Conversion functions, String functions
Function syntax

ToString(value[, encoding])

See also

ToBase64, ToBinary, CharsetEncode; Using XML and WDDX in the Developing ColdFusion Applications
History

ColdFusion MX:
Changed Unicode support: ColdFusion supports the Java UCS-2 representation of Unicode character values
0-65535. (ColdFusion 5 and earlier releases supported ASCII values 1-255.)
Added the encoding parameter.
Added ability to convert an XML document object to a string.
Parameters

Parameter

Description

value

Value to convert to a string; can be a simple value such
as an integer, a binary object, or an XML document
object.

© 2014 Adobe Systems Incorporated. All rights reserved.

2404

Adobe ColdFusion Documentation

encoding

The character encoding (character set) of the string.
Optional for binary data, Generates an error if used for
a simple value or XML document object.The following
list includes commonly used values:
utf-8
iso-8859-1
windows-1252
us-ascii
shift_jis
iso-2022-jp
euc-jp
euc-kr
big5
euc-cn
utf-16
For more information on character encoding, see: ww
w.w3.org/International/O-charset.html. The default
value is the encoding of the page on which the
function is called. See cfcontent.

Usage

This function can convert simple values and binary values that do not contain Byte zero. If this function cannot
convert a value, it throws an exception. This function can also convert an XML document object to a string XML
representation.Adobe recommends that you use the CharsetEncode function to convert binary data to a string.
Example

ToString Example







The following string is the concatenation of characters (32 to 255)
from the ASCII table.

#charData#



The following string is the Base64 representation of the string.

#data64#




The following is the string representation of the binary data.

#dataString#

© 2014 Adobe Systems Incorporated. All rights reserved.

2405

Adobe ColdFusion Documentation

© 2014 Adobe Systems Incorporated. All rights reserved.

2406

Adobe ColdFusion Documentation

Trace
Description

A function equivalent of the  tag and is used in the  mode.
Parameters

Same as the  tag.
Category

Debugging functions
Function syntax

trace (var, text, type, category, inline, abort)

For positional notations, the sequence must be followed exactly in the same manner as provided in the syntax. If
you do not provide one of the parameters, use an empty string instead. This does not apply to Boolean values for
which you must provide proper values even if you have to skip them.
History

ColdFusion 11: Attributes passed to this function needs to be in a comma-separated format.
ColdFusion 9: Added this function.
See also

cfscript, cftrace
Usage

You can call this function as name=value pair or as positional argument.
Example

© 2014 Adobe Systems Incorporated. All rights reserved.

2407

Adobe ColdFusion Documentation


function TotalInterest(principal, annualRate, months) {
var years = 0;
var interestRate = 0;
var totalInterest = 0;
principal = REReplace(trim(principal), "[\$]", "", "ALL");
annualRate = Replace(trim(annualRate), "%", "", "ALL");
if ((principal <= 0) OR (annualRate <= 0) OR (months <= 0)) {
Throw(type="InvalidData",message="All values must be greater than 0.");
}
interestRate = annualRate / 100;
years = months / 12;
totalInterest = principal * (((1 + interestRate) ^ years) - 1);
return DollarFormat(totalInterest);
}
try {
Trace(type="Information", inline="true", text="Calculating interest."); //Use of
trace function in cfsript
WriteOutput(TotalInterest("$2500.00", "5.5%", "12"));
Trace(type="Information", inline="true", text="Interest calculation done.");
}
catch(InvalidData ex) {
//Displayig exception details on screen
WriteOutput("
An InvalidData exception was thrown.
");
WriteOutput("
#ex.message#
");
//Writting the exception to log file under logs folder of web server.
WriteLog(type="Error", file="myapp.log", text="[#ex.type#] #ex.message#");
}

From ColdFusion 11, attributes passed to this function needs to be in a comma-separated
format.

© 2014 Adobe Systems Incorporated. All rights reserved.

2408

Adobe ColdFusion Documentation

Transactionandconcurrency
When ORM methods are invoked without any transaction, all the data is committed to the database when the ORM
session is flushed. ORM session is flushed when ORMFlush() is called or if autoflush is enabled when the request
ends.
This works fine when there is not much concurrency, however in most practical scenarios you would need to use
transaction in your application so that the data in your database is always in a consistent state.
With ColdFusion ORM, you can manage transactions in the following two ways:
Using Hibernate transaction: User has full control and ColdFusion does not intervene. The application has
to flush/close the session and commit/rollback the transaction.For more information on transactions, go to the
following URL: http://community.jboss.org/wiki/sessionsandtransactions
Using CFTransaction: ColdFusion manages the transaction. Since a transaction cannot be distributed
(across different data sources), application must ensure that the changes made in the transaction affect only
one Hibernate session. That is, only one data source. ColdFusion allows reading of data from other sessions
(data source) in a transaction but changes must be made in only one session. Multiple dirty sessions at any
time in the transaction can result in exceptions and the transaction is rolled back. Before transaction begins,
all existing sessions in the request are flushed.
The previous session (if any) is reused. When the transaction is committed, the dirty session is automatically
flushed (before committing the transaction). When the transaction is rolled back, the changed session cannot
be used any longer because it can cause rolled back data to get committed later. Therefore, the session
participating in the transaction is cleared when transaction is rolled back.
A description of transaction is beyond the scope of this document. For more information on transactions, see
the hibernate documentation.
To run the ORM methods inside a transaction, they must be inside . A simple example snippet
of using ORM with  is as follows:










Because we have not called commit on the  specifically, it is automatically committed when the
 ends.
All  semantics including savepoint, multiple rollbacks, multiple commits, and nested transactions
work with ORM. You can also have both queries and ORM in the same .
When  begins, any existing ORM session is flushed and closed, and a new ORM session is
created. The  can be committed or rolled back using appropriate ColdFusion tags in . When the transaction ends and has not been committed or rolled back explicitly, it is automatically
committed and the ORM session is closed. If there is any error inside the transaction, without any exception
handling, the transaction is rolled back.
For more details on , see the CFML Reference Guide.

© 2014 Adobe Systems Incorporated. All rights reserved.

2409

Adobe ColdFusion Documentation

Note
Even if ORMFlush() is called explicitly inside a  tag, the SQL runs but the data is
committed only when the transaction commits.

© 2014 Adobe Systems Incorporated. All rights reserved.

2410

Adobe ColdFusion Documentation

TransactionCommit
Description

Commits the current active transaction.
Returns

Nothing
Category

Transaction functions
Function Syntax

TransactionCommit()
See also

TransactionRollback, TransactionSetSavePoint
History

ColdFusion 9: Added this function.
Usage

You can call this function only from within an active transaction.
Example

© 2014 Adobe Systems Incorporated. All rights reserved.

2411

Adobe ColdFusion Documentation


q = new query();
q.setDatasource("cfartgallery");
WriteDump(q.execute(sql="select * from art where artid = 60").getResult());
transaction
{
q.execute(sql="insert into art (artid,artistid,artname,description,price) values
(60,3,'tom','tom',2000)");
transactionSetSavePoint('sp1');
WriteDump(q.execute(sql="select * from art where artid = 60").getResult());
transaction
{
q.execute(sql="update art set artistid=4 where artid = 60");
transactionSetSavePoint('sp2');
WriteDump(q.execute(sql="select * from art where artid = 60").getResult());
transaction
{
try
{
q.execute(sql="update art set artistid='badvalue' where artid = 60");
}
catch(any e)
{
WriteLog("rolling back the transaction");
transactionRollback("sp1");
}
}
}
}
WriteDump(q.execute(sql="select * from art where artid = 60").getResult());
transaction
{
WriteLog("deleting the record");
q.execute(sql="delete from art where artid = 60");
WriteDump(q.execute(sql="select * from art where artid = 60").getResult());
}


© 2014 Adobe Systems Incorporated. All rights reserved.

2412

Adobe ColdFusion Documentation

TransactionRollback
Description

Rolls back the current active transaction to the specified savepoint.
Returns

Nothing
Category

Transaction functions
Function Syntax

TransactionRollback(savepoint)
See also

TransactionCommit, TransactionSetSavePoint
History

ColdFusion 9: Added this function.
Parameters

Parameter

Description

savepoint

An optional string identifier for the savepoint.
Savepoints let you roll back portions of a transaction.

Usage

You can call this function only from within an active transaction. If you do not specify a savepoint, the current active
transaction rolls back to the top-level (original) transaction.
Example

See the example for TransactionCommit.

© 2014 Adobe Systems Incorporated. All rights reserved.

2413

Adobe ColdFusion Documentation

TransactionSetSavePoint
Description

Creates and stores a new savepoint for the current transaction. You can add multiple savepoints by calling this
function multiple times.
Returns

Nothing
Category

Transaction functions
Function Syntax

TransactionSetSavepoint(savepoint)
See also

TransactionCommit, TransactionRollback
History

ColdFusion 9: Added this function.
Parameters

Parameter

Description

savepoint

An optional string identifier for the savepoint.
Savepoints let you roll back portions of a transaction.

Usage

You can call this function only from within an active transaction.
Example

See the example for TransactionCommit.

© 2014 Adobe Systems Incorporated. All rights reserved.

2414

Adobe ColdFusion Documentation

Trim
Description

Removes leading and trailing spaces and control characters from a string.
Returns

A copy of the string parameter, after removing leading and trailing spaces and control characters.
Category

String functions
Function syntax

Trim(string)

See also

LTrim, RTrim
Parameters

Parameter

Description

string

A string or a variable that contains a string.

Example

Trim Example


Your string: "#FORM.myText#"
Your string: "#Trim(FORM.myText)#"
(trimmed on both sides)




Type in some text, and it will be modified by trim to remove leading
spaces from the left and right




© 2014 Adobe Systems Incorporated. All rights reserved.

2415

Adobe ColdFusion Documentation

UCase
Description

Converts the alphabetic characters in a string to uppercase.
Returns

A copy of a string, converted to uppercase.
Category

String functions
Function syntax

UCase(string)

See also

LCase
Parameters

Parameter

Description

string

A string or a variable that contains one

Example

UCase Example


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

Please enter some text.



Enter your sample text, and press "submit" to see the text returned in
uppercase:




© 2014 Adobe Systems Incorporated. All rights reserved.

2416

Adobe ColdFusion Documentation

URLDecode
Description

Decodes a URL-encoded string.
Returns

A copy of a string, decoded.
Category

Conversion functions, Other functions, String functions
Function syntax

URLDecode(urlEncodedString[, charset])

See also

URLEncodedFormat; Tags and functions for globalizing applications in the Developing ColdFusion Applications
History

ColdFusion MX 6.1: Changed the default charset: the default charset is the character encoding of the URL scope.
ColdFusion MX:
Changed Unicode support: ColdFusion supports the Java UCS-2 representation of Unicode character values
0-65535. (Earlier releases supported ASCII values.)
Added the charset parameter.
Parameters

Parameter

Description

urlEncodedString

URL-encoded string or a variable that contains one.

© 2014 Adobe Systems Incorporated. All rights reserved.

2417

Adobe ColdFusion Documentation

charset

The character encoding in which the URL is encoded.
Optional.The following list includes commonly used
values:
utf-8
iso-8859-1
windows-1252
us-ascii
shift_jis
iso-2022-jp
euc-jp
euc-kr
big5
euc-cn
utf-16
For more information on character encoding, see: ww
w.w3.org/International/O-charset.html.The default
value is the character encoding of the URL scope.

Usage

URL encoding formats some characters with a percent sign and the two-character hexadecimal representation of
the character. For example, a character whose code is 129 is encoded as %81. A space is encoded with a plus sign.
Query strings in HTTP are always URL-encoded.
Example

This example creates, encodes, and decodes a string that contains ASCII character codes:


// Build string
s = "";
for (c = 1; c lte 256; c = c + 1)
{
s = s & chr(c);
}
// Encode string and display result
enc = URLEncodedFormat(s);
WriteOutput("Encoded string is: '#enc#'.
");
// Decode and compare result with original
dec = URLDecode(enc);
if (dec neq s)
{
WriteOutput("Decoded is not the same as encoded.");
}
else
{
WriteOutput("All's quiet on the Western front.");
}


© 2014 Adobe Systems Incorporated. All rights reserved.

2418

Adobe ColdFusion Documentation

URLEncodedFormat
Adobe recommends that you use the EncodeForURL function, not the URLEncodedFormat
function, to escape special characters in a string for use in a URL in all new applications.

Description
Generates a URL-encoded string. For example, it replaces spaces with %20, and non-alphanumeric characters with
equivalent hexadecimal escape sequences. Passes arbitrary strings within a URL (ColdFusion automatically
decodes URL parameters that are passed to a page).
Returns

A copy of a string, URL-encoded.
Category

Conversion functions, Other functions, String functions
Function syntax

URLEncodedFormat(string [, charset ])

See also

URLDecode; Tags and functions for globalizing applications in the Developing ColdFusion Applications
History

ColdFusion MX 6.1: Changed the default encoding to be the response character encoding.
ColdFusion MX: Added the charset parameter.
Parameters

Parameter

Description

string

A string or a variable that contains one

© 2014 Adobe Systems Incorporated. All rights reserved.

2419

Adobe ColdFusion Documentation

charset

The character encoding in which the string is encoded.
Optional.The following list includes commonly used
values:
utf-8
iso-8859-1
windows-1252
us-ascii
shift_jis
iso-2022-jp
euc-jp
euc-kr
big5
euc-cn
utf-16
For more information on character encoding, see: ww
w.w3.org/International/O-charset.html. The default
value is the character encoding of the response. See
cfcontent.

Usage

URL encoding formats some characters with a percent sign and the two-character hexadecimal representation of
the character. For example, a character whose code is 129 is encoded as %81. A space is replaced with %20. Query
strings in HTTP are always URL-encoded.
Example

URLEncodedFormat Example

The url variable url.myExample was passed from the previous link ...
its value is:

"#url.myExample#"

This function returns a URL encoded string.

 Click me

© 2014 Adobe Systems Incorporated. All rights reserved.

2420

Adobe ColdFusion Documentation

URLSessionFormat
Description

Depending on whether a client computer accepts cookies, this function does the following:
If the client does not accept cookies: automatically appends all required client identification information to a
URL
If the client accepts cookies: does not append information
This function automatically determines which identifiers are required, and sends only the required information.
It provides a more secure and robust method for supporting client identification than manually encoding the
information in each URL, because it sends only required information, when it is required, and it is easier to
code.
Returns

A URL; if cookies are disabled for the browser, client and session data are appended.
Category

Other functions; Maintaining client identity in the Developing ColdFusion Applications
Function syntax

URLSessionFormat(request_URL)

Parameters

Parameter

Description

request_URL

URL of a ColdFusion page

Usage

If the detected cookie is not turned on, or cookie support cannot be reliably detected. And if the J2EE sessions form
of session variable management is enabled in the ColdFusion Administrator, the function return value is as follows:

myactionpage.cfm;jsessionid=xxxx (a semicolon is used instead of a question mark)

If the detected cookie is not turned on, or cookie support cannot be reliably detected, and if ColdFusion session
management is used, the function return value is as follows:

myactionpage.cfm?CFID=xxxx&CFTOKEN=xxxxxxxx

© 2014 Adobe Systems Incorporated. All rights reserved.

2421

Adobe ColdFusion Documentation

J2EE session management is used - Both Enable Session Variables and Use J2EE session
variables are checked in the ColdFusion Administrator.
ColdFusion session management is used - Only Enable Session Variables is checked in
ColdFusion Administrator (default).

Example




© 2014 Adobe Systems Incorporated. All rights reserved.

2422

Adobe ColdFusion Documentation

Val
Description

Converts numeric characters that occur at the beginning of a string to a number.
Returns

A number. If conversion fails, returns zero.
Category

Conversion functions, String functions
Function syntax

Val(string)

See also

IsNumeric
Parameters

Parameter

Description

string

A string or a variable that contains one

Usage

This function works as follows:
If TestValue
If TestValue
If TestValue
If TestValue

=
=
=
=

"234A56?7'", Val(TestValue) returns 234.
"234'5678'9?'", Val(TestValue) returns 234.
"BG234", Val(TestValue) returns the value 0, (not an error).
"0", Val(TestValue) returns the value 0, (not an error).

Example

© 2014 Adobe Systems Incorporated. All rights reserved.

2423

Adobe ColdFusion Documentation

Val Example


The string #DE(FORM.theTestValue)#
can be converted to a number:
#Val(FORM.theTestValue)#

The beginning of the string #DE(FORM.theTestValue)#
 cannot be converted to a number



Enter a string, and determine whether its beginning can be evaluated
to a numeric value.





© 2014 Adobe Systems Incorporated. All rights reserved.

2424

Adobe ColdFusion Documentation

ValueList
Description

Inserts a delimiter between each value in an executed query. ColdFusion does not evaluate the arguments.
Returns

A delimited list of the values of each record returned from an executed query.
Category

List functions, Query functions
Function syntax

ValueList(query.column [, delimiter ])

See also

QuotedValueList
Parameters

Parameter

Description

query.column

Name of an executed query and column. Separate
query name and column name with a period.

delimiter

A delimiter character to separate column data items.
The default value is comma (,).

Example

© 2014 Adobe Systems Incorporated. All rights reserved.

2425

Adobe ColdFusion Documentation

ValueList Example


SELECT Dept_ID FROM Departments
WHERE Dept_ID IN ('BIOL')


SELECT *
FROM CourseList
WHERE Dept_ID IN ('#GetDepartments.Dept_ID#')

Value list of all BIOL Course ID's using (--) as the delimiter:


#ValueList(GetCourseList.Course_ID,"--")#


Value list of all BIOL Course Numbers using (;) as the delimiter:


#ValueList(GetCourseList.CorNumber,";")#



© 2014 Adobe Systems Incorporated. All rights reserved.

2426

Adobe ColdFusion Documentation

VerifyClient
Description

Requires remote invocations of the page or calls to functions on the page to include an encrypted security token.
Returns

Does not return a value.
Category

Security functions
Function syntax

VerifyClient()

See also

cffunction, Improving security in Ajax programming rules and techniques in the Developing ColdFusion
Applications
History

ColdFusion 8: Added this function.
Parameters

Does not take any parameters
Usage

Use this function to help prevent security attacks where an unauthorized party attempts to perform an action on the
server, such as changing a password. As a general rule, use this feature for Ajax requests to the server to perform
sensitive actions, such as updating passwords.If you call this function, you must enable client management or
session management in your application; otherwise, you do not get an error, but ColdFusion does not verify clients.
Use this function only on pages that respond to client-side ColdFusion Ajax features, such as bind expressions.
These features include code that correctly sends the security token when needed.

© 2014 Adobe Systems Incorporated. All rights reserved.

2427

Adobe ColdFusion Documentation

Week
Description

From a date/time object, determines the week number within the year.
Returns

An integer in the range 1-53; the ordinal of the week, within the year.
Category

Date and time functions
Function syntax

Week(date)

See also

DatePart
Parameters

Parameter

Description

date

A date/time object in the range 100 AD-9999 AD.

Usage

When passing date as a string, enclose it in quotation marks. Otherwise, it is interpreted as a number representation
of a date.
Example

Week Example

More information about your date:


Your date, #DateFormat(yourDate)#.

It is #DayOfWeekAsString(DayOfWeek(yourDate))#, day
#DayOfWeek(yourDate)# in the week.

This is day #Day(YourDate)# in the month of
#MonthAsString(Month(yourDate))#, which has #DaysInMonth(yourDate)# days.

We are in week #Week(yourDate)# of #Year(yourDate)# (day
#DayOfYear(yourDate)# of #DaysInYear(yourDate)#). 

This is a leap year
This is not a leap year




© 2014 Adobe Systems Incorporated. All rights reserved.

2428

Adobe ColdFusion Documentation

© 2014 Adobe Systems Incorporated. All rights reserved.

2429

Adobe ColdFusion Documentation

Wrap
Description

Wraps text so that each line has a specified maximum number of characters.
Note
The wrap function does not insert line breaks by placing the 
 tag in HTML text. Instead, it
wraps the text in the display without adding the 
 tag.

Returns

String containing the wrapped text.
Category

String functions
Function syntax

Wrap(string, limit[, strip])

See also

cfmail
History

ColdFusion MX 6.1: Added this function.
Parameters

Parameter

Description

string

String or variable that contains one. The text to wrap.

limit

Positive integer maximum number of characters to
allow on a line.

strip

Boolean value specifying whether to remove all existing
newline and carriage return characters in the input
string with spaces before wrapping the text. The default
value is False.

Usage

Inserts line break at the location of the first white space character (such as a space, tab, or new line) before the
specified limit on a line. If a line has no whitespace characters before the limit, inserts a line break at the limit. Uses
the operating-system specific line break: newline for UNIX, carriage return and newline on Windows.If you specify
the strip parameter, all existing line breaks are removed, so any paragraph formatting is lost.Use this function to

© 2014 Adobe Systems Incorporated. All rights reserved.

2430

Adobe ColdFusion Documentation

limit the length of text lines, such as text to be included in a mail message. The cfmail and cfmailpart tag wrap
text attributes use this function
Example

Wrap Example

#Wrap(inputText, 59)#

© 2014 Adobe Systems Incorporated. All rights reserved.

2431

Adobe ColdFusion Documentation

WriteDump
Description

A function equivalent to the  tag which can be used in .
Parameters

Same as  tag.
Category

Other functions, Data output functions
Function syntax

WriteDump (var, output, format, abort, label, metainfo, top, show, hide, keys,
expand, showUDFs);

See also

cfdump, cfscript
History

ColdFusion 11: Attributes passed to this function needs to be in a comma-separated format.
ColdFusion 9: Added this function.
Usage

You can call this function providing arguments as name=value pair or as positional arguments.For positional
notations, the sequence must be followed exactly in the same manner as provided in the syntax. If you do not
provide one of the parameters, use an empty string instead. This does not apply to Boolean values for which you
must provide proper values even if you have to skip them.
Example


filename = "log.txt";
try {
result = FileOpen(expandpath(filename));
WriteDump(result);
}
catch(Expression exception) {
WriteOutput("
An Expression exception was thrown.
");
WriteOutput("
#exception.message#
");
WriteLog(type="Error", file="myapp.log", text="[exception.type]
#exception.message#");
}


© 2014 Adobe Systems Incorporated. All rights reserved.

2432

Adobe ColdFusion Documentation

From ColdFusion 11, attributes passed to this function needs to be in a comma-separated
format.

© 2014 Adobe Systems Incorporated. All rights reserved.

2433

Adobe ColdFusion Documentation

WriteLog
Description

A function equivalent of the cflog tag, which can be used in .
Parameters

Same as the  tag:
Attribute

Req/Opt

Default

Description

text

Required

application

Optional

file

Optional

Message file. Specify only
the main part of the
filename. For example, to
log to the Testing.log file,
specify "Testing". The file
must be located in the
default log directory. You
cannot specify a directory
path. If the file does not
exist, it is created
automatically, with the
extension .log.

log

Optional

If you omit the file attrib
ute, writes messages to
standard log file. Ignored,
if you specify file attribu
te.

Message text to log.
yes

yes: logs the
application name, if it is
specified in a cfappli
cation tag or
Application.cfc file.
no

Application: writes
to Application.log,
normally used for
application-specific
messages.
Scheduler: writes to
Scheduler.log, normally
used to log the
execution of scheduled
tasks.

© 2014 Adobe Systems Incorporated. All rights reserved.

2434

Adobe ColdFusion Documentation

Optional

type

Information

Type (severity) of the
message:
Information
Warning
Error
Fatal

Category

Data output functions
Function syntax

WriteLog (text, type, application, file, log)

For positional notation, the sequence must be followed exactly in the same manner as provided in the syntax. If you
do not provide one of the parameters, use an empty string instead. This does not apply to Boolean values for which
you must provide proper values even if you have to skip them.
See also

cfscript, cflog
Usage

You can call this function as name=value pair or as positional argument.
Example

© 2014 Adobe Systems Incorporated. All rights reserved.

2435

Adobe ColdFusion Documentation


//Example: 1
function TotalInterest(principal, annualRate, months) {
var years = 0;
var interestRate = 0;
var totalInterest = 0;
principal = REReplace(trim(principal), "[\$]", "", "ALL");
annualRate = Replace(trim(annualRate), "%", "", "ALL");
if ((principal <= 0) OR (annualRate <= 0) OR (months <= 0)) {
Throw(type="InvalidData",message="All values must be greater than 0.");
}
interestRate = annualRate / 100;
years = months / 12;
totalInterest = principal * (((1 + interestRate) ^ years) - 1);
return DollarFormat(totalInterest);
}
try {
Trace(type="Information", inline="true", text="Calculating interest.");
WriteOutput(TotalInterest("$2500.00", "5.5%", "12"));
Trace(type="Information", inline="true", text="Interest calculation done.");
}
catch(InvalidData ex) {
//Writting the exception to log file under logs folder of web server.
WriteLog(type="Error", file="myapp.log", text="[#ex.type#] #ex.message#");
}


From ColdFusion 11, attributes passed to this function needs to be in a comma-separated
format.

© 2014 Adobe Systems Incorporated. All rights reserved.

2436

Adobe ColdFusion Documentation

WriteOutput
Description

Appends text to the page-output stream. This function writes to the page-output stream regardless of conditions
established by the cfsetting tag.
Category

Other functions, System functions, Data output functions
Function syntax

WriteOutput(string)

Parameters

Parameter

Description

string

A string or a variable that contains one

Usage

Within the cfquery and cfmail tags, this function does not output to the current page; it writes to the current SQL
statement or mail text. Do not use WriteOutput within cfquery and cfmail.Although you can call this function
anywhere within a page, it is most useful inside a cfscript block.
Example

...

employee = StructNew();
StructInsert(employee, "firstname", FORM.firstname);
StructInsert(employee, "lastname", FORM.lastname);
StructInsert(employee, "email", FORM.email);
StructInsert(employee, "phone", FORM.phone);
StructInsert(employee, "department", FORM.department);
WriteOutput("About to add " & FORM.firstname & " " & FORM.lastname);


© 2014 Adobe Systems Incorporated. All rights reserved.

2437

Adobe ColdFusion Documentation

WSGetAllChannels
Description

Sends messages to a specific channel based on the filter criteria (which is a struct).
Returns

Nothing
History

ColdFusion 10: Added this function
Syntax

WSGetAllChannels()
WSGetAllChannels("channelName")

Parameters

Parameter

Description

channelName

If specified, returns all sub-channels listed under the
entered channel name. If left unspecified, the funtion
returns all channels registered under the current
application.

© 2014 Adobe Systems Incorporated. All rights reserved.

2438

Adobe ColdFusion Documentation

WSGetSubscribers
Description

Returns an array of struct with clientID and subscriberInfo as the keys.
Returns

Nothing
History

ColdFusion 10: Added this function
Syntax

WSgetSubscribers(channel)

Parameters

Parameter

Description

channel

Channel whose list of subscribers you wish to retrieve.

© 2014 Adobe Systems Incorporated. All rights reserved.

2439

Adobe ColdFusion Documentation

WSPublish
Description

Sends messages to a specific channel based on the filter criteria (which is a struct).
Category

Other functions, System functions, Data output functions
History

ColdFusion 10: Added this function
Syntax

WSPublish(String channel, Object message)
WSPublish(channel,message [,filterCriteria])

Parameters

Parameter

Description

channel

Specific channel to which the server publishes its
response.

message

Response sent by the server to all clients subscribed to
a specific channel.

filterCriteria

Conditions to filter eligible clients that need to be
notified for a given channel.

Example

© 2014 Adobe Systems Incorporated. All rights reserved.

2440

Adobe ColdFusion Documentation


if(isdefined("form.publish"))
WsPublish(#form.channel#, #form.message#);




stocks


news


products


Message:




© 2014 Adobe Systems Incorporated. All rights reserved.

2441

Adobe ColdFusion Documentation

WSSendMessage
Description

Sends messages to a specific client that invokes the method. This can be included as a part of the function that is
called by the invoke WebSocket JavaScript method.
Returns

Nothing
History

ColdFusion 10: Added this function
Syntax

WSSendMessage(message)
Parameters

Parameters

Description

message

Required. The message object. This can be of type An
y.

© 2014 Adobe Systems Incorporated. All rights reserved.

2442

Adobe ColdFusion Documentation

XmlChildPos
Description

Gets the position of a child element within an XML document object.
Returns

The position, in an XmlChildren array, of the _N_th child that has the specified name.
Category

XML functions
Function syntax

XmlChildPos(elem, childName, N)

See also

IsXmlElem, XmlElemNew, XmlSearch, XmlTransform; Using XML and WDDX in the Developing ColdFusion
Applications
History

ColdFusion MX: Added this function.
Parameters

Parameter

Description

elem

XML element within which to search.

childName

XML child element for which to search. Must be an
immediate child of the elem parameter.

N

Index of XMLchild element for which to search.

Usage

You can use the returned index in the ArrayInsertAt and ArrayDeleteAt functions to change XML document
objects. If the specified child is not found, the function returns -1.
Example

The following example searches XML document element, xmlobject.employee.name1, for its second Status e
lement child and uses the position in an ArrayDeleteAt function to remove the element:

© 2014 Adobe Systems Incorporated. All rights reserved.

2443

Adobe ColdFusion Documentation






Almanzo
Wilder
Medical Absence
Extended Leave


Laura
Ingalls





elempos=XMLChildPos(xmlobject.employee.name[1], "Status", 2);
ArrayDeleteAt(xmlobject.employee.name[1].XmlChildren, elempos);




© 2014 Adobe Systems Incorporated. All rights reserved.

2444

Adobe ColdFusion Documentation

XmlElemNew
Description

Creates an XML document object element.
Returns

An XML document object element.
Category

XML functions
Function syntax

XmlElemNew(xmlObj[, namespace], childName)

See also

cfxml, IsXmlElem, XmlChildPos, XmlFormat, XmlNew, XmlParse; Using XML and WDDX in the Developing
ColdFusion Applications
History

ColdFusion MX 7: Added the namespace parameter.
ColdFusion MX: Added this function.
Parameters

Parameter

Description

xmlObj

Name of the XML document object in which you are
creating the element

namespace

(Optional) URI of the namespace to which this element
belongs

childName

Name of the element to create

Usage

The function's return variable specifies the location of the new element in the document object. It must specify a
valid location in the document object identified by the xmlObj parameter. The following statements show this use:

MyDoc.MyRoot.XmlChildren[2] = XmlElemNew(MyDoc,"childNode");
ArrayAppend(MyDoc.MyRoot.XmlChildren, XmlElemNew(MyDoc,"childNode"));

If you do not specify a namespace URI and use a namespace prefix in the childName parameter, ColdFusion

© 2014 Adobe Systems Incorporated. All rights reserved.

2445

Adobe ColdFusion Documentation

checks to see if a namespace URI has already been specified for the prefix, and if so, uses that namespace.
Example

The following example creates and displays a ColdFusion document object:


MyDoc = XmlNew();
MyDoc.xmlRoot = XmlElemNew(MyDoc,"MyRoot");
if (testVar IS TRUE)
MyDoc.MyRoot.XmlText = "The value of testVar is True.";
else
MyDoc.MyRoot.XmlText = "The value of testVar is False.";
for (i = 1; i LTE 4; i = i + 1)
{
MyDoc.MyRoot.XmlChildren[i] = XmlElemNew(MyDoc,"childNode");
MyDoc.MyRoot.XmlChildren[i].XmlText = "This is Child node " & i &".";
}



© 2014 Adobe Systems Incorporated. All rights reserved.

2446

Adobe ColdFusion Documentation

XmlFormat
Adobe recommends that you use the EncodeForXML function, not the XmlFormat function, to
escape special characters in a string for use in XML in all new applications.

Description
Escapes special XML characters in a string so that the string can be used as text in XML.
Returns

A copy of the string parameter that is safe to use as text in XML.
Category

String functions, XML functions
Function syntax

XmlFormat(string, escapeChars)

See also

cfxml, XmlNew, XmlParse, XmlValidate; Using XML and WDDX in the Developing ColdFusion Applications
History

ColdFusion MX: Added this function.
Parameters

Parameter

Description

string

A string or a variable that contains one

escapeChars

Set to true to escape the characters restricted as per
XML standards. For details, see http://www.w3.org/TR/
2006/REC-xml11-20060816/#NT-RestrictedChar.

Usage

This function escapes characters as follows:
Text character

Escaped representation

Greater than symbol (>)

>

Less than symbol (<)

<

Single-quotation mark (')

'

© 2014 Adobe Systems Incorporated. All rights reserved.

2447

Adobe ColdFusion Documentation

Double-quotation mark (")

"

Ampersand symbol (&)

&

Carriage return (but not line feed)

Removed from the text.

High ASCII characters in the range 159-255.

Replaced by unicode escape sequence; for example,
(capital E with an Acute symbol) is replaced by É.

Example

The following example shows how XmlFormat escapes special XML characters. Use the View Source command in
the browser to see the results. ColdFusion interprets the "" in the second text string as representing a
single-quotation mark in text before it applies the XmlFormat function.





#XmlFormat("Body of element with <, >, "" and & goes here.", "true")#




© 2014 Adobe Systems Incorporated. All rights reserved.

2448

Adobe ColdFusion Documentation

XmlGetNodeType
Description

Determines the type of an XML document object node.
Returns

A string identifying the XML node type. The following values are valid:
ATTRIBUTE_NODE

CDATA_SECTION_NODE

COMMENT_NODE

DOCUMENT_FRAGMENT_NODE

DOCUMENT_NODE

DOCUMENT_TYPE_NODE

ELEMENT_NODE

ENTITY_NODE

ENTITY_REFERENCE_NODE

NOTATION_NODE

PROCESSING_INSTRUCTION_NODE

TEXT_NODE

If the argument is not a document object node, the function generates an error.
Category

XML functions
Function syntax

XmlGetNodeType(xmlNode)

See also

IsXmlAttribute, IsXmlDoc, IsXmlElem, IsXmlNode, IsXmlRoot, XmlChildPos, XmlValidate; Using XML
and WDDX in the Developing ColdFusion Applications
History

ColdFusion MX 7: Added this function.
Parameters

Parameter

Description

xmlNode

An XML DOM object node

Usage

The XmlGetNodeType function can determine the types of the nodes returned by the XmlSearch function, or the
types of the entries in an element's XmlNodes array.

© 2014 Adobe Systems Incorporated. All rights reserved.

2449

Adobe ColdFusion Documentation

Example

The following example checks the node types of various parts of an XML document object:









 Imported from France
1
15.95






Node Types
xmlobject: #XMLGetNodeType(xmlobject)#

xmlobject.order: #XMLGetNodeType(xmlobject.order)#



Now check the types of all the nodes in the xmlobject.order.items.item
element's XmlNodes array.

Note the many apparently empty Text nodes generated by whitespace characters in the
XML text source.




#i# Node type is: #XMLGetNodeType(descnodes[i])#

#i# Node name is: #descnodes[i].XmlName#


#i# Node value is: #descnodes[i].XmlValue#







© 2014 Adobe Systems Incorporated. All rights reserved.

2450

Adobe ColdFusion Documentation

XmlNew
Description

Creates an XML document object.
Returns

An empty XML document object.
Category

XML functions
Function syntax

XmlNew([caseSensitive])

See also

cfxml, IsXmlDoc, ToString, XmlFormat, XmlParse, XmlValidate; Using XML and WDDX in the Developing
ColdFusion Applications
History

ColdFusion MX: Added this function.
Parameters

Parameter

Description

caseSensitive

Determines how ColdFusion processes the case of
XML document object component identifiers:
True: maintains case
False: ColdFusion ignores case. Default.

Usage

An XML document object is represented in ColdFusion as a structure.The caseSensitive parameter value
determines whether identifiers whose characters are of varying case, but are otherwise the same, refer to different
components; for example:
If True, the element or attribute names "name" and "NAME" refer to different elements or attributes.
If False, these names refer to the same elements or attributes.
If your XML object is case sensitive, you cannot use dot notation to reference an element or attribute name.
Use the name in associative array (bracket) notation, or a reference that does not use the case-sensitive
name (such as xmlChildren1) instead. In the following code, the first line will work with a case-sensitive XML
object. The second and third lines cause errors:

© 2014 Adobe Systems Incorporated. All rights reserved.

2451

Adobe ColdFusion Documentation

MyDoc.xmlRoot.XmlAttributes["Version"] = "12b";
MyDoc.xmlRoot.XmlAttributes.Version = "12b";
MyDoc.MyRoot.XmlAttributes["Version"] = "12b";

To convert an XML document object into a string, use the ToString function.
Example

The following example creates and displays a ColdFusion document object:



MyDoc = XmlNew();
MyDoc.xmlRoot = XmlElemNew(MyDoc,"MyRoot");
if (testVar IS TRUE)
MyDoc.MyRoot.XmlText = "The value of testVar is True.";
else
MyDoc.MyRoot.XmlText = "The value of testVar is False.";
for (i = 1; i LTE 4; i = i + 1) {
MyDoc.MyRoot.XmlChildren[i] = XmlElemNew(MyDoc,"childNode");
MyDoc.MyRoot.XmlChildren[i].XmlText = "This is Child node " & i &".";
}



© 2014 Adobe Systems Incorporated. All rights reserved.

2452

Adobe ColdFusion Documentation

XmlParse
Description

Converts XML text into an XML document object.
Returns

An XML document object.
Category

Conversion functions, XML functions
Function syntax

XmlParse(xmlText [, caseSensitive ], validator])

See also

cfxml, IsXML, ToString, XmlFormat, XmlNew, XmlSearch, XmlTransform, XmlValidate; Using XML and
WDDX in the Developing ColdFusion Applications
History

ColdFusion MX 7:
Added the validator parameter.
Added support for filenames and URLs in the xmlText parameter.
Added support for relative URLs and pathnames.
ColdFusion MX: Added this function.
Parameters

Parameter

Description

xmlText

Any of the following:
A string containing XML text.
The name of an XML file.
The URL of an XML file; valid protocol identifiers
include http, https, ftp, and file.

caseSensitive

© 2014 Adobe Systems Incorporated. All rights reserved.

Yes: maintains the case of document elements and
attributes.
No: Default

2453

Adobe ColdFusion Documentation

Any of the following:

validator

The name of a Document Type Definition (DTD) or
XML Schema file.
The URL of a DTD or Schema file; valid protocol
identifiers include http, https, ftp, and file.
A string representation of a DTD or Schema.
An empty string; in this case, the XML file must
contain an embedded DTD or Schema identifier,
which is used to validate the document.

Usage

If you specify a relative URL or pathname in a parameter, ColdFusion uses the directory (or, for URLs, the logical
directory) that contains the current ColdFusion page as the path root. The caseSensitive parameter value
determines whether identifiers whose characters are of varying case, but are otherwise the same, refer to different
components; for example:
If true, the element or attribute names "name" and "NAME" refer to different elements or attributes.
If false, these names refer to the same elements or attributes.
If your XML object is case sensitive, you cannot use dot notation to reference an element or attribute name.
Use the name in associative array (bracket) notation, or a reference that does not use the case-sensitive
name (such as xmlChildren1) instead. In the following code, the first line will work with a case-sensitive XML
object. The second and third lines cause errors:

MyDoc.xmlRoot.XmlAttributes["Version"] = "12b";
MyDoc.xmlRoot.XmlAttributes.Version = "12b";
MyDoc.MyRoot.XmlAttributes["Version"] = "12b";

The optional validator parameter specifies a DTD or Schema to use to validate the document. If the parser
encounters a validation error, ColdFusion generates an error and stops parsing the document. Specify a valid
ator parameter to make the XmlParse function validate your document. If you do not specify a validator para
meter, the XML file must specify the DTD or schema using the xsi:noNamespaceSchemaLocation tag. If
you specify a validator parameter, also specify a caseSensitiveparameter.
Note
If you specify an empty string as the third parameter to the XMLParse function and specify
a validator such as xsi:noNamespaceSchemaLocation within an XML document, it
must specify a complete URL. However, with XMLValidate, it can be just a filename that is
found relative to the CFML template doing validation.

If you do not specify a validator parameter, the xmlTextparameter can specify a well-formed XML fragment,
and does not have to specify a complete document.
Note
To convert an XML document object back into a string, use the ToString function.

Example

© 2014 Adobe Systems Incorporated. All rights reserved.

2454

Adobe ColdFusion Documentation

The following example has three parts: an XML file, a DTD file, and a CFML page that parses the XML file and uses
the DTD for validation. The CFML file displays the returned XML document object. To show the results of invalid
XML, modify the bmenuD.xml.
Note
The DTD used in the following example represents the same XML structure as the Schema used
in the XmlValidate example

The custorder.xml file is as follows:







 Deluxe Carpenter's Hammer
1
15.95


 36" Plastic Rake
2
6.95


 Standard paint thinner
3
8.95




The custorder.dtd file is as follows:












© 2014 Adobe Systems Incorporated. All rights reserved.

2455

Adobe ColdFusion Documentation

The CFML file is as follows. It uses a filename for the XML file and a URL for the DTD. Note that the XML and URL
paths must be absolute.


Dump of myDoc XML document object



© 2014 Adobe Systems Incorporated. All rights reserved.

2456

Adobe ColdFusion Documentation

XmlSearch
Description

Uses an XPath language expression to search an XML document object.
Returns

The results of the XPath search. For details, see Usage.
Category

XML functions
Function syntax

XmlSearch(xmlDoc, xPathString, params)

See also

cfxml, IsXML, XmlChildPos, XmlParse, XmlTransform; Using XML and WDDX in the Developing ColdFusion
Applications
History

ColdFusion 10: Added support for XPath 2.0 syntax and for passing variables to XPath expressions.
ColdFusion 8: Added support for returning any valid XPath result, not just arrays of XML object nodes.
ColdFusion MX 7: Added support for attribute searches.
ColdFusion MX: Added this function.
Parameters

Parameter

© 2014 Adobe Systems Incorporated. All rights reserved.

Description

2457

Adobe ColdFusion Documentation

params

Optional. A struct that contains key-value pair (variable
name and value) document object as shown in the
following example:


params = structNew();
params["test"] = "food";




xmlDoc

XML document object

xPathString

XPath expression

Usage

The XmlSearch function attempts to return the values returned by the search whenever possible. For example, if
the XPath expression returns a Boolean, the CFML variable is assigned a true or false value.The following table
lists XPath expression result data types and how they are represented in the CFML return value.
XPath return type

ColdFusion representation

Boolean

Boolean

Null

"" (empty string)

Number

Number

String

String

NodeSet

Array of XML nodes

Result Tree Fragment

Array of XML nodes

Results that are Unknown or have an unresolved variable in the expression throw an error.XPath is specified by the
World Wide Web Consortium (W3C). For detailed information on XPath, including XPath expression syntax, see the
W3C website at www.w3.org/TR/xpath.
Example

The following example extracts the elements named last, which contain employee last names, from an XML file, and
displays the names.The employeesimple.xml file contains the following XML:

© 2014 Adobe Systems Incorporated. All rights reserved.

2458

Adobe ColdFusion Documentation





Almanzo
Wilder


Laura
Ingalls



The CFML file contains the following lines:


myxmldoc = XmlParse("C:\CFusionMX7\wwwroot\examples\employeesimple.xml");
selectedElements = XmlSearch(myxmldoc, "/employee/name/last");
for (i = 1; i LTE ArrayLen(selectedElements); i = i + 1)
writeoutput(selectedElements[i].XmlText & "
");


© 2014 Adobe Systems Incorporated. All rights reserved.

2459

Adobe ColdFusion Documentation

XmlTransform
Description

Applies an Extensible Stylesheet Language Transformation (XSLT) to XML. The XML can be in string format or an
XML document object.
Returns

A string containing the results of applying the XSLT to the XML.
Category

Conversion functions, XML functions
Function syntax

XmlTransform(xml, xsl[, parameters])

See also

cfxml, XmlFormat, XmlNew, XmlParse, XmlSearch, XmlValidate; Using XML and WDDX in the Developing
ColdFusion Applications
History

ColdFusion 10: Added support for XSLT 2.0 syntax
ColdFusion MX 7: Added the parameters parameter and the ability to use a file for the XSL.
ColdFusion MX: Added this function.
Parameters

Parameter

Description

xml

An XML document in string format, or an XML
document object

xsl

XSLT transformation to apply; can be any of the
following:Any of the following:
A string containing XSL text.
The name of an XSTLT file. Relative paths start at
the directory containing the current CFML page.
The URL of an XSLT file; valid protocol identifiers
include http, https, ftp, and file. Relative paths start at
the directory containing the current CFML page.

© 2014 Adobe Systems Incorporated. All rights reserved.

2460

Adobe ColdFusion Documentation

parameters

A structure containing XSL template parameter
name-value pairs to use in transforming the document.
The XSL transform defined in the xslString parameter
uses these parameter values in processing the XML.

Usage

An XSLT converts an XML document to another format or representation by applying an Extensible Stylesheet
Language (XSL) stylesheet to it. XSL, including XSLT syntax is specified by the World Wide Web Consortium
(W3C). For detailed information on XSL and XSLT, see the W3C website at www.w3.org/Style/XSL/.If the XSLT
code contains include statements with relative paths, ColdFusion resolves them relative to the location of the XSLT
file, or for an XSL string, the location of the current ColdFusion page.
Example

The following example converts an XML document that represents a customer order into an HTML document with
the customer name and a table with the order items and quantities:The custorder.xml file that represents a customer
order has the following lines:






Deluxe Carpenter's Hammer
1
15.95


36" Plastic Rake
2
6.95


Standard paint thinner
3
8.95




The custorder.xsd XSLT file that transforms the XML to HTML that displays the customer's name, and the items and
quantities ordered has the following lines:

© 2014 Adobe Systems Incorporated. All rights reserved.

2461

Adobe ColdFusion Documentation










Name
Price
















The CFML file has the following lines:



#XmlTransform(xmldoc, xmltrans)#

© 2014 Adobe Systems Incorporated. All rights reserved.

2462

Adobe ColdFusion Documentation

XmlValidate
Description

Uses a Document Type Definition (DTD) or XML Schema to validate an XML text document or an XML document
object.
Returns

The following validation structure:
Field

Description

Errors

An array containing any validator error messages.
These messages indicate that the document does not
conform to the DTD or Schema (is not valid).

FatalErrors

An array containing any validator fatal error messages.
Fatal errors indicate that the document contains XML
formatting errors (is not well-formed XML).

Status

A Boolean value:
True if the document is valid.
False if the validation check failed.

Warning

An array containing any validator warnings. A
well-formed and valid document can produce warning
messages.

Category

XML functions
Function syntax

XmlValidate(xmlDoc[, validator])

See also

cfxml, IsXmlDoc, IsXML, XmlFormat, XmlNew, XmlParse, XmlSearch, XmlTransform; Using XML and
WDDX in the Developing ColdFusion Applications
History

ColdFusion MX 7: Added this function.
Parameters

Parameter

© 2014 Adobe Systems Incorporated. All rights reserved.

Description

2463

Adobe ColdFusion Documentation

Any of the following:

xmlDoc

A string containing an XML document.
The name of an XML file.
The URL of an XML file; valid protocol identifiers
include http, https, ftp, and file.
An XML document object, such as one generated by
the XmlParse function.
validator

Any of the following:
A string containing a DTD or Schema.
The name of a DTD or Schema file.
The URL of a DTD or Schema file; valid protocol
identifiers include http, https, ftp, and file.

Usage

If you specify a relative URL or filename in a parameter, ColdFusion uses the directory (or, for URLs, the virtual
directory) that contains the current ColdFusion page as the path root. The validator parameter specifies a DTD or
Schema to use to validate the document. If you omit the parameter, the XML document must contain one of the
following:
A !DOCTYPE tag to specify the DTD or its location
An xsi:schemaLocation or xsi:noNamespaceSchemaLocation tag to specify the Schema location
If you use a validator parameter and the XML document specifies a DTD or Schema, the XmlValidate funct
ion uses the validator parameter, and ignores the specification in the XML document.If you do not use a valid
ator parameter, and the XML document does not specify a DTD or Schema, the function returns a structure
with an error message in the Errors field.This function attempts to process the complete XML document, and
reports all errors found during the processing. As a result, the returned structure can have a combination of
Warning, Error, and FatalError fields, and each field can contain multiple error messages.
Example

The following example has three parts: an XML file, an XSD Schema file, and a CFML page that parses the XML file
and uses the Schema for validation. The CFML file displays the value of the returned structure's Status field and
displays the returned structure. To show the results of invalid XML, modify the custorder.xml file.
Note
The Schema used in the following example represents the same XML structure as the DTD used
in the XmlParse example.

The custorder.xml file is as follows:

© 2014 Adobe Systems Incorporated. All rights reserved.

2464

Adobe ColdFusion Documentation






 Deluxe Carpenter's Hammer
1
15.95


 36" Plastic Rake
2
6.95


 Standard paint thinner
3
8.95




The custorder.xsd file is as follows:

© 2014 Adobe Systems Incorporated. All rights reserved.

2465

Adobe ColdFusion Documentation










































The CFML file is as follows. It uses a filename for the XML file and a URL for the Schema. The XML and URL paths
must be absolute.

© 2014 Adobe Systems Incorporated. All rights reserved.

2466

Adobe ColdFusion Documentation



Did custorder.xml validate against custorder.xsd? #myResults.status#



Dump of myResults structure returned by XMLValidate



© 2014 Adobe Systems Incorporated. All rights reserved.

2467

Adobe ColdFusion Documentation

Year
Description

From a date/time object, gets the year value.
Returns

The year value of date.
Category

Date and time functions
Function syntax

Year(date)

See also

DatePart, IsLeapYear
Parameters

Parameter

Description

date

A date/time object in the range 100 AD-9999 AD.

Usage

When passing a date as a string, enclose it in quotation marks. Otherwise, it is interpreted as a number
representation of a date.
Example

© 2014 Adobe Systems Incorporated. All rights reserved.

2468

Adobe ColdFusion Documentation

Year Example

More information about your date:


Your date, #DateFormat(yourDate)#.

It is #DayOfWeekAsString(DayOfWeek(yourDate))#,
day #DayOfWeek(yourDate)# in the week.

This is day #Day(yourDate)#
in the month of #MonthAsString(Month(yourDate))#,
which has #DaysInMonth(yourDate)# days.

We are in week #Week(yourDate)# of #Year(YourDate)#
(day #DayOfYear(yourDate)# of #DaysInYear(yourDate)#). 


This is a leap year
This is not a leap year




© 2014 Adobe Systems Incorporated. All rights reserved.

2469

Adobe ColdFusion Documentation

YesNoFormat
Description

Evaluates a number or Boolean value.
Returns

Yes, for a nonzero value; No for zero, false, and no Boolean values, and an empty string ("").
Category

Decision functions, Display and formatting functions
Function syntax

YesNoFormat(value)

See also

IsBinary, IsNumeric
Parameters

Parameter

Description

value

A number or Boolean value

Example

YesNoFormat Example
The YesNoFormat function returns non-zero values as "Yes"; zero, false and no
Boolean values, and empty strings ("") as "No".


YesNoFormat(1): #YesNoFormat(1)#
YesNoFormat(0): #YesNoFormat(0)#
YesNoFormat("1123"): #YesNoFormat("1123")#
YesNoFormat("No"): #YesNoFormat("No")#
YesNoFormat(True): #YesNoFormat(True)#



© 2014 Adobe Systems Incorporated. All rights reserved.

2470

Adobe ColdFusion Documentation

Description
Returns
Category
Function syntax
See also
Parameters
Example

© 2014 Adobe Systems Incorporated. All rights reserved.

2471

Adobe ColdFusion Documentation

Ajax JavaScript Functions
You can use the JavaScript functions listed below on pages that use ColdFusion Ajax features.
Function summary Ajax
ColdFusion.Ajax.submitForm
ColdFusion.Autosuggest.getAutosuggestObject
ColdFusion.Layout.enableSourceBind
ColdFusion.MessageBox.getMessageBoxObject
ColdFusion.MessageBox.isMessageBoxDefined
ColdFusion.ProgressBar.getProgressBarObject
JavaScriptFunctionsinColdFusion9Update1

#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

2472

Adobe ColdFusion Documentation

Function summary Ajax
The following table briefly describes the JavaScript functions that you can use in ColdFusion pages that use Ajax
features:
Function

Description

ColdFusion.Ajax.submitForm

Submits form data without refreshing the entire page
when the results are returned.

ColdFusion.Autosuggest.getAutosuggestObject

Lets you access underlying YUI AutoComplete object
thereby providing fine-grained control over the object,
for example attaching an event.

ColdFusion.FileUpload.cancelUpload

Cancels the file upload at any point during the file
upload.

ColdFusion.FileUpload.clearAllFiles

Clears all the files selected for upload.

Coldfusion.fileUpload.setUrl

Sets URL for the fileupload control dynamically.

ColdFusion.FileUpload.startUpload

Starts uploading the selected files.

ColdFusion.getElementValue

Gets the value of an attribute of a bindable ColdFusion
control.

ColdFusion.grid.clearSelectedRows

Clears the selected rows in the grid.

ColdFusion.Grid.getBottomToolbar

Gets bottom toolbar that can be used to add a control,
for example icon or button.

ColdFusion.Grid.getGridObject

Gets the underlying Ext JS - JavaScript Library object
for the specified HTML cfgrid control.

ColdFusion.grid.getSelectedRows

Fetches data for the selected rows in the grid.

ColdFusion.Grid.getTopToolbar

Gets the top toolbar that can be used to add a control,
for example icon or button.

ColdFusion.Grid.hideBottomToolbar

Hides the bottom toolbar that can be used to add a
control, for example icon or button.

ColdFusion.Grid.hideTopToolbar

Hides the top toolbar that can be used to add a control,
for example icon or button.

ColdFusion.Grid.refresh

Manually refreshes a displayed grid.

ColdFusion.Grid.refreshBottomToolbar

Refreshes the bottom toolbar that can be used to add a
control, for example icon or button.

© 2014 Adobe Systems Incorporated. All rights reserved.

2473

Adobe ColdFusion Documentation

ColdFusion.Grid.refreshTopToolbar

Refreshes the top toolbar that can be used to add a
control, for example icon or button.

ColdFusion.Grid.showBottomToolbar

Shows bottom toolbar that can be used to add a
control, for example icon or button.

ColdFusion.Grid.showTopToolbar

Displays the top toolbar that can be used to add a
control, for example icon or button.

ColdFusion.Grid.sort

Sorts the specified HTML grid.

ColdFusion.JSON.decode

Converts a JSON-encoded string into a JavaScript
variable

ColdFusion.JSON.encode

converts a JavaScript variable into a JSON string.

ColdFusion.Layout.collapseAccordion

Collapses an area of an accordion layout.

ColdFusion.Layout.collapseArea

Collapses an area of a border layout (cflayout tag
with a type attribute of border).

ColdFusion.Layout.createAccordionPanel

Creates a panel in an existing accordion layout (cflay
out tag with a type attribute of accordion).

ColdFusion.Layout.createTab

Creates a tab in an existing tabbed layout (cflayout t
ag with a type attribute of tab).

ColdFusion.Layout.disableSourceBind

Disables the source bind.

ColdFusion.Layout.disableTab

Disables the specified tab so it cannot be selected.

ColdFusion.Layout.enableSourceBind

If disabled, enables the source bind.

ColdFusion.Layout.enableTab

Enables the specified tab so users can select it and
display the area contents.

ColdFusion.Layout.expandAccordion

Expands a collapsed area of an accordion layout.

ColdFusion.Layout.expandArea

Expands a collapsed area of a border layout.

ColdFusion.Layout.getAccordionLayout

Gets the underlying Ext JS - JavaScript Library object
for the specified accordion type cflayout control.

ColdFusion.Layout.getBorderLayout

Gets the underlying Ext JS - JavaScript Library object
for the specified border type cflayout control.

© 2014 Adobe Systems Incorporated. All rights reserved.

2474

Adobe ColdFusion Documentation

ColdFusion.Layout.getTabLayout

Gets the underlying Ext JS - JavaScript Library object
for the specified tab type cflayout control.

ColdFusion.Layout.hideAccordion

Hides an accordion.

ColdFusion.Layout.hideArea

Hides a bordered layout area.

ColdFusion.Layout.hideTab

Hides a tab.

ColdFusion.Layout.selectAccordion

Selects an accordion and displays the layout area
contents.

ColdFusion.Layout.selectTab

Selects a tab and displays the layout area contents.

ColdFusion.Layout.showAccordion

Shows an accordion that was hidden using the inithi
de attribute or the hideArea() function.

ColdFusion.Layout.showArea

Shows an area of a border layout that was hidden
using the inithide attribute or the hideArea() funct
ion.

ColdFusion.Layout.showTab

Shows a tab that was hidden using the inithide attri
bute or the hideTab() function.

ColdFusion.Log.debug

Displays a debug-level message in the log window.

ColdFusion.Log.dump

Displays information about a complex variable in the
log window.

ColdFusion.Log.error

Displays an error-level message in the log window.

ColdFusion.Log.info

Displays an information-level message in the log
window.

ColdFusion.Map.addEvent

Enables event handling in a map.

ColdFusion.Map.addMarker

Adds a marker to the map.

ColdFusion.Map.getLatitudeLongitude

Gets the latitude/longitude coordinates for a given
address.

ColdFusion.Map.getMapObject

Gets the Google map component.

ColdFusion.Map.hide

Hides the map if displayed.

ColdFusion.Map.refresh

Reloads the map.

© 2014 Adobe Systems Incorporated. All rights reserved.

2475

Adobe ColdFusion Documentation

ColdFusion.Map.setCenter

Sets the center of map to the address that you specify.

ColdFusion.Map.setZoomlevel

Sets the zoom level of the map to the new value.

ColdFusion.Map.show

Shows the map if it is hidden.

ColdFusion.Mediaplayer.resize

Changes the current size of the media player.

ColdFusion.Mediaplayer.setMute

Mutes or unmutes the sound of the media player.

ColdFusion.Mediaplayer.setSource

Sets the URL of the FLV file.

ColdFusion.Mediaplayer.setVolume

Sets the volume of sound of the media player.

ColdFusion.Mediaplayer.startPlay

Plays the FLV file.

ColdFusion.Mediaplayer.stopPlay

Stops playing the FLV file.

ColdFusion.MessageBox.create

Creates a ColdFusion message box. Equivalent to the
cfmessagebox tag.

ColdFusion.MessageBox.getMessageBoxObject

Gets the underlying Ext JS - JavaScript Library object
for the specified HTML cfmessagebox control.

ColdFusion.MessageBox.isMessageBoxDefined

Checks if a message box is defined.

ColdFusion.MessageBox.show

Displays a ColdFusion message box.

ColdFusion.MessageBox.update

Updates message box properties.

ColdFusion.MessageBox.updateMessage

Updates the message property.

ColdFusion.MessageBox.updateTitle

Updates the message box title.

ColdFusion.navigate

Displays the output of a link URL in a specified cfdiv,
cflayoutarea, cfpod, or cfwindow container.

ColdFusion.ProgressBar.getProgressBarObject

Gets the progress bar object.

ColdFusion.ProgressBar.hide

Hides the progress bar if it is displayed.

ColdFusion.ProgressBar.reset

Resets the progress.

ColdFusion.ProgressBar.show

Shows the progress bar if it is hidden.

ColdFusion.ProgressBar.start

Stops the underlying progress bar object that is
running.

© 2014 Adobe Systems Incorporated. All rights reserved.

2476

Adobe ColdFusion Documentation

ColdFusion.ProgressBar.stop

Starts the underlying progress bar object.

ColdFusion.ProgressBar.update

Updates the attributes duration, interval, and onc
omplete.

ColdFusion.ProgressBar.updatestatus

Lets you manually update the status and message of
the progress bar.

ColdFusion.setGlobalErrorHandler

Replaces the global JavaScript error handler for
displaying information about ColdFusion Ajax errors.

ColdFusion.Slider.disable

Disables the slider control.

ColdFusion.Slider.enable

Enables the slider control.

ColdFusion.Slider.getSliderObject

Gets the slider control.

ColdFusion.Slider.getValue

Gets the numeric value of the slider control.

ColdFusion.Slider.hide

Hides the slider control.

ColdFusion.Slider.setValue

Sets the numeric value of the slider control.

ColdFusion.Slider.show

Shows the slider control.

ColdFusion.Tree.getTreeObject

Gets the underlying Yahoo YUI Library object for the
specified HTML cftree control.

ColdFusion.Tree.refresh

Manually refreshes a displayed HTML tree.

ColdFusion.Window.create

Creates a ColdFusion pop-up window. Equivalent to
the cfwindow tag.

ColdFusion.Window.getWindowObject

Gets the underlying Ext JS - JavaScript Library object
for the specified HTML cfwindow control.

ColdFusion.Window.hide

Hides a window

ColdFusion.Window.onHide

Specifies a JavaScript function to run each time a
specific window hides.

ColdFusion.Window.onShow

Specifies a JavaScript function to run each time a
specific window shows.

ColdFusion.Window.show

Shows a hidden window.

© 2014 Adobe Systems Incorporated. All rights reserved.

2477

Adobe ColdFusion Documentation

#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

2478

Adobe ColdFusion Documentation

ColdFusion.Ajax.submitForm
Description
Submits form data without refreshing the page when the results are returned.
Function syntax

ColdFusion.Ajax.submitForm(formId, URL[, callbackhandler, errorHandler, httpMethod,
asynch])

See also
cfajaxproxy, ColdFusion.navigate, Using the ColdFusion.Ajax.submitForm function in Using Ajax form
controls and features in the Developing ColdFusion Applications
History
ColdFusion 8: Added this function.
Parameters
Parameter

Description

formId

The ID or name attribute of the form.

URL

The URL to which to submit the form.

callbackhandler

The JavaScript function to handle a normal response.
The function must take a single argument, that contains
the response body. This method is used only if the form
submission is asynchronous.

errorHandler

The JavaScript function to handle an HTTP error
response. The function must take two arguments: the
HTTP status code, and the error message. This
method is used only if the form submission is
asynchronous.

httpMethod

The HTTP method to use for the submission, must be
one of the following:
GET
POST (the default)

asynch

© 2014 Adobe Systems Incorporated. All rights reserved.

A Boolean value specifying whether to submit the form
asynchronously. The default value is true.

2479

Adobe ColdFusion Documentation

Returns
If the asynch argument is false, returns the response body. Otherwise, the function does not return a value.
Usage
If the page that calls this function does not have any ColdFusion AJAX-based controls, use a cfajaximport tag
on the page to ensure that the page includes the JavaScript definition for this function.
Note
This function does not submit the contents of file fields.

Example
See Using the ColdFusion.Ajax.submitForm function in Using Ajax form controls and features in the Developing
ColdFusion Applications.
#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

2480

Adobe ColdFusion Documentation

ColdFusion.Autosuggest.getAutosuggestObject
Description
Lets you access underlying YUI AutoComplete object thereby providing fine-grained control over the object, for
example attaching an event.
Returns
The underlying AutoComplete object.
Function syntax
ColdFusion.Autosuggest.getAutosuggestObject (Id)
Parameters
Id: Name of the auto-suggest object.
Example

© 2014 Adobe Systems Incorporated. All rights reserved.

2481

Adobe ColdFusion Documentation








Attaching an event handler to the autosuggest object

State:







#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

2482

Adobe ColdFusion Documentation

ColdFusion.Chart.getChartHandle
Description

Used to get chart object for various JavaScript operations that you want to perform, for example adding or removing
a series or nodes in charts.
Returns

JavaScript object
Function syntax

ColdFusion.Chart.getChartHandle()

History

ColdFusion 10: Added this function
Example

The following example shows how to add a new value to the first series of a chart with chart ID interactivebar:

ColdFusion.Chart.getChartHandle().exec('interactivebar', 'appendseriesvalues',
'{"plotindex": 0, "values" : [40]}' );

Example

The following example shows how to add a new value to the register a click event on a chart:

ColdFusion.Chart.getChartHandle().click = function(dataObj){
alert("Chart Clicked - ID: " + data["id"]);
}

#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

2483

Adobe ColdFusion Documentation

ColdFusion.FileUpload.cancelUpload
Description

At any point during the upload of files, you can choose to cancel the upload. When you cancel the upload, any
further upload of files stops.
Function syntax

ColdFusion.FileUpload.cancelUpload(name)

See also

ColdFusion.FileUpload.clearAllFiles, ColdFusion.FileUpload.startUpload
History

ColdFusion 9: Added this function
Parameters

Parameter

Description

name

The value of the name attribute in the cffileupload t
ag.

Returns

This function does not return a value.
Example

This example includes a button for the Cancel Upload action. When you click this button, the file upload is canceled.

© 2014 Adobe Systems Incorporated. All rights reserved.

2484

Adobe ColdFusion Documentation

This is an example of the FileUpload.cancelUpload function. Add a few files to
upload and click Upload. During upload, click the Cancel Upload HTML button to
cancel the upload.






#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

2485

Adobe ColdFusion Documentation

ColdFusion.FileUpload.clearAllFiles
Description

Before upload or after you cancel upload, you can choose to clear all the files selected for upload. When you do this,
the selected files are removed from the Upload view list.
Function syntax

ColdFusion.FileUpload.clearAllFiles(name)

See also

ColdFusion.FileUpload.cancelUpload, ColdFusion.FileUpload.startUpload
History

ColdFusion 9: Added this function
Parameters

Parameter

Description

name

The value of the name attribute in the cffileupload t
ag.

Returns

This function does not return a value.
Example

This example includes a button for the ClearAllFiles action. When you click this button, the files selected for upload
are removed.

© 2014 Adobe Systems Incorporated. All rights reserved.

2486

Adobe ColdFusion Documentation

This is an example of the FileUpload.clearAllFiles function. Add a few files to
upload and click Upload. During upload, click the Clear Upload HTML button to clear
all the files selected for upload.






#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

2487

Adobe ColdFusion Documentation

Coldfusion.fileUpload.setUrl
Description

Used to set URL for the fileupload control dynamically.
Returns

Nothing
Function syntax

ColdFusion.fileUpload.setUrl(id, url)
Parameters

Id: Name of upload control.
Url: URL can be an absolute URL, relative URL, or fully qualified URL.
Example

© 2014 Adobe Systems Incorporated. All rights reserved.

2488

Adobe ColdFusion Documentation











#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

2489

Adobe ColdFusion Documentation

ColdFusion.FileUpload.startUpload
Description

Starts uploading the selected files.
Function syntax

ColdFusion.FileUpload.startUpload(name)

See also

ColdFusion.FileUpload.cancelUpload, ColdFusion.FileUpload.clearAllFiles
History

ColdFusion 9: Added this function
Parameters

Parameter

Description

name

The value of the name attribute in the cffileupload t
ag.

Returns

This function does not return a value.
Example

This example includes a button to start the Upload action. When you click this button, the selected files start
uploading.

© 2014 Adobe Systems Incorporated. All rights reserved.

2490

Adobe ColdFusion Documentation







#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

2491

Adobe ColdFusion Documentation

ColdFusion.getElementValue
Description

Gets the value of an attribute of a bindable ColdFusion control.
Function syntax

ColdFusion.getElementValue(elementId [, formId, attributeName])

History

ColdFusion 8: Added this function
Parameters

Parameter

Description

elementId

The ID or name attribute of the control.

formId

The ID attribute of the form that contains the control.
Omit this attribute if the element ID is unique on the
page. If you omit this attribute and the element ID is not
unique, the function uses the first element on the page
with the specified ID.

attributeName

The control attribute to get; by default, the value attrib
ute, or, for cfselect, the value of the selected
element in the control. For cfgrid controls, use this
attribute and specify the name of the column whose
value you are getting; the function returns the entry in
the currently selected row.For cftree controls, use
this attribute and specify PATH or NODE. The function
returns the item path or node value of the currently
selected tree item.

Returns

The value of the specified attribute.
Usage

You can bind to, and get the attribute values of, the following HTML controls:
cfgrid
cfinput controls with checkbox, datefield, file, hidden, radio, or text types
cfselect
cftextarea
cftree
#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

2492

Adobe ColdFusion Documentation

© 2014 Adobe Systems Incorporated. All rights reserved.

2493

Adobe ColdFusion Documentation

ColdFusion.grid.clearSelectedRows
Description

Used to clear the selected rows in the grid.
Returns

Nothing
Function syntax

ColdFusion.grid.clearSelectedRows(id)
Parameters

Id: Name of the grid defined using cfgrid.
Usage

See the following example.
Example

Employee.cfm























© 2014 Adobe Systems Incorporated. All rights reserved.

2495

Adobe ColdFusion Documentation




Employee.cfc



empQuery = new query(name="emps", datasource="cfdocexamples");
remote any function
getEmployees(page,pageSize,gridsortcolumn="EMP_ID",gridsortdirection="ASC",empName)
{
var orderBy = "EMP_ID";
var mysql = "SELECT Emp_ID, FirstName, LastName, EMail, Department, Email
FROM Employees";
if(isdefined("arguments.empName") and trim(arguments.empName) neq ""){
mysql = mysql & " WHERE " & "firstname = '#arguments.empName#'";
}
if(arguments.gridsortcolumn eq ""){
mysql = mysql & " ORDER BY " & orderBy;
}
mysql = mysql & " " & gridsortdirection;
return QueryConvertForGrid(empQuery.execute(sql=mysql).getResult(), page,
pageSize);
}
remote void function editEmployees(gridaction,gridrow,gridchanged)
{
switch(gridaction)
{
case "I":
{
var eFName = gridrow["FIRSTNAME"];
var eLNAme = gridrow["LASTNAME"];
var eDept = gridrow["DEPARTMENT"];
var eEmail = gridrow["EMAIL"];
var insertSql = "insert into Employees(FirstName,LastName,Department,Email)
values (" & "'" & eFName & "', '" & eLName & "', '" & eDept & "', '" & eEmail &
"')";
empQuery.execute(sql=insertSql);
break;
}
case "U":
{
var empId = gridrow["EMP_ID"];
var changedCol = structkeylist(gridchanged);
var updateSql = "UPDATE Employees SET " & changedCol & "='" &
gridchanged[changedCol] & "' WHERE emp_id=" & empId;
empQuery.execute(sql=updateSql);
break;
}
case "D":
{
deleteEmployees(gridrow);
}
}
}
remote void function deleteEmployees(empdata)

© 2014 Adobe Systems Incorporated. All rights reserved.

2496

Adobe ColdFusion Documentation

{
var i = 1;
var emp = {};
if(isArray(empdata) and not ArrayIsEmpty(empdata)){
for(emp in empdata){
if(isStruct(emp) and structkeyexists(emp,"emp_id")){
empid = emp["emp_id"];
writelog("deleting " & empid);
//var deleteSql = "delete from Employees where emp_id=" & empid;
//empQuery.execute(sql=deleteSql);
}
}
}
}

© 2014 Adobe Systems Incorporated. All rights reserved.

2497

Adobe ColdFusion Documentation




In this example, setting multirowselect=true enables performing of batch operations on grid data, such as
deleting multiple records.In the deleteemployees functions, two lines have been commented out to prevent
accidental deletion of data (since it is a batch operation). To see deletion, uncomment the code.The form has a del
eteAllSelectedRows button that illustrates how records can be deleted externally. That is, without using the
delete button built in to the grid. The same approach can be used to perform other batch operations such as moving
multiple files to another folder or batch updates.
Note
Set the httpMethod to POST on the Proxy object carefully to avoid "request URI too large"
errors as shown in the deleteAllSelectedRows method in Employee.cfm.

#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

2498

Adobe ColdFusion Documentation

ColdFusion.Grid.getBottomToolbar
Description

Gets bottom toolbar that can be used to add a control, for example icon or button.
Function syntax

ColdFusion.Grid.getBottomToolbar(Id)
Parameters

Id: Name of the grid.
Example

See example in ColdFusion.Grid.refreshBottomToolbar. ---#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

2499

Adobe ColdFusion Documentation

ColdFusion.Grid.getGridObject
Description

Gets the underlying Ext (Ext JS JavaScript library) object for the specified HTML grid.
Function syntax

ColdFusion.Grid.getGridObject(name)

See also

cfgrid, ColdFusion.Grid.refresh, ColdFusion.Grid.sort, [Ext
JS - JavaScript Library Documentation|http://extjs.com/deploy/ext/docs/], Using HTML grids in the Developing
ColdFusion Applications
History

ColdFusion 8: Added this function
Parameters

Parameter

Description

name

The value of the name attribute of the cfgrid tag for
which you want the object.

Returns

If the grid is editable, an object of type Ext.grid.EditableGrid; otherwise, an object of type Ext.grid.Grid.
Usage

Use this function to get the Ext toolkit (Ext.grid) object that underlies the ColdFusion HTML cfgrid control. You
can then use the raw object to modify the displayed grid. For documentation on the objects and how to manage
them, see the [Ext
documentation|http://extjs.com/deploy/ext/docs/]. ---#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

2500

Adobe ColdFusion Documentation

ColdFusion.grid.getSelectedRows
Description

Used to fetch data for the selected rows in the grid.
Returns

An array of objects that contains row data.
Function syntax

ColdFusion.grid.getSelectedRows(id)
Parameters

Id: Name of the grid defined using cfgrid.
See also

FileUpload
Usage

See the example in ColdFusion.grid.clearSelectedRows.
Example

See the example in ColdFusion.grid.clearSelectedRows.
#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

2501

Adobe ColdFusion Documentation

ColdFusion.Grid.getTopToolbar
Description

Gets the top toolbar that can be used to add a control, for example icon or button.
Function syntax

ColdFusion.getTopToolbar(Id)
Parameters

Id: Name of the grid.
Example

See example in ColdFusion.Grid.refreshBottomToolbar.
#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

2502

Adobe ColdFusion Documentation

ColdFusion.Grid.hideBottomToolbar
Description

Hides the bottom toolbar that can be used to add a control, for example icon or button.
Function syntax

ColdFusion.Grid.hideBottomToolbar(Id)
Parameters

Id: Name of the grid.
Example

See example in ColdFusion.Grid.refreshBottomToolbar.
#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

2503

Adobe ColdFusion Documentation

ColdFusion.Grid.hideTopToolbar
Description

Hides the top toolbar that can be used to add a control, for example icon or button.
Function syntax

ColdFusion.Grid.hideTopToolbar(Id)
Parameters

Id: Name of the grid.
Example

See example in ColdFusion.Grid.refreshBottomToolbar.
#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

2504

Adobe ColdFusion Documentation

ColdFusion.Grid.refresh
Description

Manually refreshes a displayed grid.
Function syntax

ColdFusion.Grid.refresh(name [, preservePage])

See also

cfgrid, ColdFusion.Grid.getGridObject, ColdFusion.Grid.sort, [Ext
JS - JavaScript Library Documentation|http://extjs.com/deploy/ext/docs/], Using HTML grids in the Developing
ColdFusion Applications
History

ColdFusion 8: Added this function
Parameters

Parameter

Description

name

The value of the name attribute of the cfgrid tag to
refresh.

preservePage

A Boolean value specifying whether to redisplay the
current page of data (true), or display the first page of
data (false, the default). This attribute applies only if
the grid data requires multiple grid pages to display.

Returns

This function does not return a value.
Usage

This function is useful to refresh a grid when an event occurs that changes the underlying data but does not
normally trigger a grid update.
Example

The following code snippet comes from an example that lets users delete rows from a grid. When the user selects a
grid row and clicks the delete button, the Ajax proxy calls a mycfc.deleteRow function to delete the row from the
database. When the function returns successfully, the proxy calls ColdFusion.Grid.refresh to update the grid
and remove the row.

© 2014 Adobe Systems Incorporated. All rights reserved.

2505

Adobe ColdFusion Documentation



#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

2506

Adobe ColdFusion Documentation

ColdFusion.Grid.refreshBottomToolbar
Description

Refreshes the bottom toolbar that can be used to add a control, for example icon or button. This function internally
calls the JavaScript function ColdFusion.Grid.showBottomToolbar.
Function syntax

ColdFusion.Grid.refresheBottomToolbar(Id)
Parameters

Id: Name of the grid control.
Example

grid.cfc



remote any function
getEmployees(page,pageSize,gridsortcolumn="EMP_ID",gridsortdirection="ASC"){
var startRow = (page-1)*pageSize;
var endRow = page*pageSize;
if(!isdefined("arguments.gridsortcolumn") or
isdefined("arguments.gridsortcolumn") and trim(arguments.gridsortcolumn) eq "")
gridsortcolumn = "EMP_ID";
if(!isdefined("arguments.gridsortdirection") or
isdefined("arguments.gridsortdirection") and arguments.gridsortdirection eq "")
gridsortdirection = "ASC";
var mysql = "SELECT Emp_ID, FirstName, EMail, Department FROM
Employees";
if(isdefined("arguments.gridsortcolumn") and
arguments.gridsortcolumn neq "")
mysql = mysql & " ORDER BY " & gridsortcolumn;
if(isdefined("arguments.gridsortdirection") and
arguments.gridsortdirection neq "")
mysql = mysql & " " & gridsortdirection ;
rs1 = new query(name="team", datasource="cfdocexamples",
sql=mysql).execute();
return QueryConvertForGrid(rs1.getResult(), page, pageSize);
}

remote any function editEmployees(gridaction,gridrow,gridchanged){
writelog("edit employee info");
}



grid.cfm

© 2014 Adobe Systems Incorporated. All rights reserved.

2507

Adobe ColdFusion Documentation













© 2014 Adobe Systems Incorporated. All rights reserved.

2508

Adobe ColdFusion Documentation
















#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

2510

Adobe ColdFusion Documentation

ColdFusion.Grid.refreshTopToolbar
Description

Refreshes the top toolbar that can be used to add a control, for example icon or button. This function internally calls
the JavaScript function ColdFusion.Grid.showTopToolbar.
Function syntax

ColdFusion.Grid.refreshTopToolbar(Id)
Parameters

Id: Name of the grid.
Example

See example in ColdFusion.Grid.refreshBottomToolbar.
#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

2511

Adobe ColdFusion Documentation

ColdFusion.Grid.showBottomToolbar
Description

Shows bottom toolbar that can be used to add a control, for example icon or button.
Function syntax

ColdFusion.Grid.showBottomToolbar(Id)
Parameters

Id: Name of the grid.
Example

See example in ColdFusion.Grid.refreshBottomToolbar.
#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

2512

Adobe ColdFusion Documentation

ColdFusion.Grid.showTopToolbar
Description

Displays the top toolbar that can be used to add a control, for example icon or button.
Function syntax

ColdFusion.Grid.showTopToolbar(Id)
Parameters

Id: Name of the grid.
Example

See example in ColdFusion.Grid.refreshBottomToolbar.
#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

2513

Adobe ColdFusion Documentation

ColdFusion.Grid.sort
Description

Sorts the specified HTML grid.
Function syntax

ColdFusion.Grid.sort(name [, columnName, direction])

See also

cfgrid, ColdFusion.Grid.getGridObject, ColdFusion.Grid.refresh, [Ext
JS - JavaScript Library Documentation|http://extjs.com/deploy/ext/docs/], Using HTML grids in the Developing
ColdFusion Applications
History

ColdFusion 8: Added this function
Parameters

Parameter

Description

name

The value of the name attribute of the cfgrid tag to
sort.

columnName

The name of the column that determines the sort order.

direction

The sort direction. Must be one for these values:
ASC (default)
DESC

Returns

This function does not return a value.
Usage

This function sorts the data displayed by the grid by using a case-insensitive sort for string data, or a numeric sort
for numeric data. It uses the specified column contents to determine the displayed grid order. When a grid has a
remote data source, the bound CFC function that provides the data gets the column name and sort direction in the c
fgridsortcolumn and cfgridsortdirection bind attributes. The CFC function must use these values and
perform the sort appropriately.
#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

2514

Adobe ColdFusion Documentation

ColdFusion.JSON.decode
Description

Converts a JSON-encoded string to a JavaScript variable.
Function syntax

ColdFusion.JSON.decode(string)

See also

ColdFusion.JSON.encode, DeserializeJSON, SerializeJSON, Using Ajax Data and Development Features
in the Developing ColdFusion Applications, http://www.json.org
History

ColdFusion 8: Added this function
Parameters

Parameter

Description

string

The string to encode.

Returns

A Javascript variable containing the data in the JSON encoded string.
Usage

Use this function when you must explicitly convert between JavaScript and JSON format, for example, when you
must call a remote function that is not in a CFC.If the JSON string has a security prefix as defined by the Server
Settings > Settings page of the ColdFusion Administrator or specified in the cfapplication or cffunction tags,
the function strips the prefix before decoding the string.
Example

The following example uses the ColdFusion.JSON.decode and ColdFusion.JSON.encode functions When
the user clicks the "Call" link, the callMe function encodes the String as JSON and calls the echo CFC's plainEcho
function with the result. The function also sets the return format to plain, so that the CFC function does not
automatically convert its return value to JSON, and sends plain text instead.The echo.cfc component has two
functions:
The plainEcho function converts its argument from JSON to a ColdFusion variable, calls the echo function,
converts the result to JSON, and returns it to the caller.
The echo function creates a structure, sets the structure's entry to the input parameter, and returns the result.
(You could call this function remotely using to see the result of calling a function that does not encode JSON
when you request a plain return type. To see the results, use the cfdebug HTTP parameter when you run the
main page.)The main page has the following lines:

© 2014 Adobe Systems Incorporated. All rights reserved.

2515

Adobe ColdFusion Documentation








Call



The echo.cfc file has the following lines:
















#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

2516

Adobe ColdFusion Documentation

ColdFusion.JSON.encode
Description

Converts a JavaScript expression to a JSON-encoded string.
Function syntax

ColdFusion.JSON.encode(expression)

See also

ColdFusion.JSON.decode, DeserializeJSON, SerializeJSON, Using Ajax Data and Development Features
in the Developing ColdFusion Applications, http://www.json.org
History

ColdFusion 8: Added this function
Parameters

Parameter

Description

name

An expression with the data to encode.

Returns

A String containing the data in JSON encoded format.
Usage

Use this function when you must explicitly convert between JavaScript and JSON format, for example, when you
must call a remote function that is not in a CFC.
Example

See the example in ColdFusion.JSON.decode.
#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

2517

Adobe ColdFusion Documentation

ColdFusion.Layout.createTab
Description

Creates a tab and layout area in a ColdFusion tabbed layout.
Function syntax

ColdFusion.Layout.createTab(layout, layoutArea, Title, URL [, configObject])

See also

cflayout, cflayoutarea, ColdFusion.Layout.disableTab, ColdFusion.Layout.enableTab, ColdFus
ion.Layout.showArea, ColdFusion.Layout.hideTab, ColdFusion.Layout.selectTab, ColdFusion.L
ayout.showTab, Using layouts in Controlling Ajax user interface layout the Developing ColdFusion Applications
History

ColdFusion 8: Added this function
Parameters

Parameter

Description

layout

The name attribute of the tabbed layout in which to add
the tab

layoutArea

The name to assign to the layout area that is created
for the new tab. Must be unique on the page.

title

The text to display on the tab. You can use HTML
mark-up to control the title appearance.

URL

The URL from which to get the layout area contents.
This attribute can use URL parameters to pass data to
the page. ColdFusion uses standard page path
resolution rules to locate the page.

configObject

An object containing window configuration parameters.
For details, see "Usage".

Returns

This function does not return a value.
Usage

This function dynamically creates tabs in a tabbed layout; it is equivalent to putting a cflayoutarea tag inside a c
flayout tag with a type attribute of tab. The configuration parameter defines tab characteristics; it can have any
or all the following entries:

© 2014 Adobe Systems Incorporated. All rights reserved.

2518

Adobe ColdFusion Documentation

Entry

Default

Description

align

The cflayout tag align attribute
value

Specifies how to align child controls
within the layout area. The following
values are valid:
center
justify
left
right

callbackhandler

A function that is called when the
layout tab body has loaded. This
function must not take any
arguments.

closable

false

A Boolean value specifying whether
the user can close the window. If tr
ue, the tab has an X close icon.

disabled

false

A Boolean value specifying whether
the tab is disabled, that is, whether
user can select the tab to display its
contents. Disabled tabs are grayed
out. Ignored if there is a true sele
cted entry.

errorHandler

A function that is called if an error
occurs in loading the tab body. This
function must take two arguments:
The HTTP status code, or -1 if
the error is not an HTTP error
An error message

inithide

false

© 2014 Adobe Systems Incorporated. All rights reserved.

A Boolean value specifying whether
the tab is initially hidden. To show
an initially hidden tab, use the Cold
Fusion.Layout.showTab functio
n.

2519

Adobe ColdFusion Documentation

overflow

auto

Specifies how to display child
content whose size would cause the
tab layout area to overflow the
window boundaries. The following
values are valid:
auto: Show scroll bars when
necessary.
hidden: Do not allow access to
overflowing content.
scroll: Always show horizontal
and vertical scroll bars, even if
they are not needed.
visible: Content can display
outside the bounds of the layout
area.
Note: In Internet Explorer, layout
areas with the visible setting
expand to fit the size of the
contents, rather than having the
contents extend beyond the layout
area.

selected

false

style

A Boolean value specifying whether
this tab is initially selected so that
its contents appears in the layout.
A CSS style specification that
controls the appearance of the
layout area.

Example

The following example creates a tabbed layout with one tab. When you click the button it creates a second tab that
is immediately visible and selected.The main page looks as follows:

© 2014 Adobe Systems Incorporated. All rights reserved.

2520

Adobe ColdFusion Documentation










Default Tab





The _tabURL.cfm page looks as follows:

Tab 2
This is a simple tab

#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

2521

Adobe ColdFusion Documentation

ColdFusion.Layout.collapseArea
Description

Collapses an area of a border layout.
Function syntax

ColdFusion.Layout.collapseArea(layout, layoutArea)

See also

cflayout, cflayoutarea, ColdFusion.Layout.expandArea, ColdFusion.Layout.getTabLayout, Cold
Fusion.Layout.showArea, Using layouts in Controlling Ajax user interface layout the Developing ColdFusion
Applications
History

ColdFusion 8: Added this function
Parameters

Parameter

Description

layout

The name attribute of the border layout that contains
the area to collapse.

layoutArea

The position in the layout of the area to collapse. Must
be one of the following: bottom, left, right, or top.

Returns

This function does not return a value.
Usage

This function has no effect if the area is already collapsed.
Example

The following code snippet collapses the left area of the layout border layout when the user clicks the button.



#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

2522

Adobe ColdFusion Documentation

ColdFusion.Layout.collapseAccordion
Description

Collapses an area of an accordion layout.
Function syntax

ColdFusion.Layout.collapseAccordion(layoutname, layoutareaname)

See also

cflayout,ColdFusion.Layout.createAccordionPanel, ColdFusion.Layout.expandAccordion, Cold
Fusion.Layout.getAccordionLayout, ColdFusion.Layout.hideAccordion, ColdFusion.Layout.se
lectAccordion, ColdFusion.Layout.showAccordion, Using layouts in Controlling Ajax user interface layout
the Developing ColdFusion Applications
History

ColdFusion 9: Added this function
Parameters

Parameter

Description

layoutname

The name attribute of the accordion layout that contains
the panel to collapse.

layoutareaname

The name of the panel in the accordion layout to
collapse.

Returns

This function does not return a value.
Usage

This function has no effect if the accordion is already collapsed.
Example

The following code snippet collapses the accordion layout when the user clicks the button.










Default Panel





The _tabURL.cfm page looks as follows:

Panel 2
This is an accordion panel

#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

2526

Adobe ColdFusion Documentation

ColdFusion.Layout.disableSourceBind
Description

Disables the source bind.
Function syntax

ColdFusion.Layout.disableSourceBind(Id)
Parameters

Id: Name of the layout area.
Usage

Assume that you are using Coldfusion.navigate to populate content into tab or accordion panels. You can
have instances where content comes from the source bind call if the source attribute is defined for cflayoutarea
(and is not from ColdFusion.navigate).In such instances, you might disable the source bind to get content using
Coldfusion.navigate.
Example

layout.cfm uses the templates Tab1_Src.cfm, Tab2_Src.cfm, and Tab3_Src.cfm. If you run layout.cfm, you notice
that clicking
navigate populates content of tab2_src.cfm instead of navigate.cfm
Disable Source bind ensures that the content of navigate.cfm is populated in tab2_src
Enable Source Bind and then clicking tab2_src would again populate the content of tab2_src
Tab1_Src.cfm





Tab2_Src.cfm





Tab3_Src.cfm





Tab4_Src.cfm__





© 2014 Adobe Systems Incorporated. All rights reserved.

2527

Adobe ColdFusion Documentation

layout.cfm













#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

2528

Adobe ColdFusion Documentation

ColdFusion.Layout.enableSourceBind
Description
If disabled, enables the source bind.
Function syntax
ColdFusion.Layout.enableSourceBind(Id)
Parameters
Id: Name of the layout area.
Usage
See usage in ColdFusion.Layout.disableSourceBind.
Example
See example in ColdFusion.Layout.disableSourceBind.
ColdFusion.FileUpload.getSelectedFiles
Description

Returns an array of objects containing the filename and size of the files selected for upload. The file size is returned
in bytes. The function also returns file upload status as YES|NO|Error.
Function syntax

ColdFusion.FileUpload.getSelectedFiles(Id)
Parameters

Id: Name of the cffileupload control.
Usage

In a real life scenario, you normally use the uploader with other controls. For example, a form with three fields:
name, email, and uploader. Assume that you upload the files, but forget to click Submit or you select the files,
submit the form, but forget to click Upload. You can use this function to inform the user that there are files that have
been selected for upload and provide the following details:
FILENAME: Name of the file selected for upload.
SIZE: Size of the file in bytes.
STATUS: YES|NO|Error; YES indicates a successful upload, NO indicates that the upload is yet to occur,
and Error indicates that an exception has occurred during the upload operation.
Example

The following example illustrates a scenario where the user clicks Submit and is informed about the files selected for
upload:

© 2014 Adobe Systems Incorporated. All rights reserved.

2529

Adobe ColdFusion Documentation









First Name: 

Last Name: 










#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

2530

Adobe ColdFusion Documentation

ColdFusion.Layout.expandAccordion
Description

Expands a panel in an accordion layout.
Function syntax

ColdFusion.Layout.expandAccordion(layoutname, layoutareaname)

See also

cflayout, ColdFusion.Layout.collapseAccordion, ColdFusion.Layout.createAccordionPanel, Co
ldFusion.Layout.getAccordionLayout, ColdFusion.Layout.hideAccordion, ColdFusion.Layout.
selectAccordion, ColdFusion.Layout.showAccordion, Using layouts in Controlling Ajax user interface
layout the Developing ColdFusion Applications
History

ColdFusion 9: Added this function
Parameters

Parameter

Description

layoutname

The name attribute of the accordion layout that contains
the panel to expand.

layoutareaname

The name of the panel to expand. Must be one of the
following: bottom, left, right, or top.

Returns

This function does not return a value.
Usage

This function has no effect if the panel is already expanded.
Example

The following code snippet expands the left area of the panel when the user clicks the button.



#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

2531

Adobe ColdFusion Documentation

© 2014 Adobe Systems Incorporated. All rights reserved.

2532

Adobe ColdFusion Documentation

ColdFusion.Layout.disableTab
Description

Disables the specified tab so it cannot be selected.
Function syntax

ColdFusion.Layout.disableTab(layout, layoutArea)

See also

cflayout, cflayoutarea, ColdFusion.Layout.createTab, ColdFusion.Layout.enableTab, ColdFusi
on.Layout.showArea, ColdFusion.Layout.hideTab, ColdFusion.Layout.selectTab, ColdFusion.La
yout.showTab, Using layouts in Controlling Ajax user interface layout the Developing ColdFusion Applications
History

ColdFusion 8: Added this function
Parameters

Parameter

Description

layout

The name attribute of the tabbed layout that contains
the area to disable.

layoutArea

The name attribute of the tab layout area to disable.

Returns

This function does not return a value.
Usage

This function has no effect on the currently selected tab. A disabled tab appears grayed out.
Example

The following example lets you enable and disable a tab by clicking a link.

© 2014 Adobe Systems Incorporated. All rights reserved.

2533

Adobe ColdFusion Documentation








The First Tab
Here are the contents of the first tab.


The Second Tab
This is the content of the second tab.



Use these links to test disabling/enabling via JavaScript.
Note that you cannot disable the currently selected tab.

Click here to enable tab 1.

Click here to disable tab 1.





#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

2534

Adobe ColdFusion Documentation

ColdFusion.Layout.enableTab
Description

Enables the specified tab so it can be selected.
Function syntax

ColdFusion.Layout.enableTab(layout, layoutArea)

See also

cflayout, cflayoutarea, ColdFusion.Layout.createTab, ColdFusion.Layout.disableTab, ColdFus
ion.Layout.showArea, ColdFusion.Layout.hideTab, ColdFusion.Layout.selectTab, ColdFusion.L
ayout.showTab, Using layouts in Controlling Ajax user interface layout the Developing ColdFusion Applications
History

ColdFusion 8: Added this function
Parameters

Parameter

Description

layout

The name attribute of the tabbed layout that contains
the area to enable.

layoutArea

The name attribute of the tab layout area to enable.

Returns

This function does not return a value.
Example

See ColdFusion.Layout.disableTab
#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

2535

Adobe ColdFusion Documentation

ColdFusion.Layout.expandArea
Description

Expands an area of a border layout.
Function syntax

ColdFusion.Layout.expandArea(layout, layoutArea)

See also

cflayout, cflayoutarea, ColdFusion.Layout.collapseArea, ColdFusion.Layout.getTabLayout, Co
ldFusion.Layout.showArea, Using layouts in Controlling Ajax user interface layout the Developing ColdFusion
Applications
History

ColdFusion 8: Added this function
Parameters

Parameter

Description

layout

The name attribute of the border layout that contains
the area to expand.

layoutArea

The position in the layout of the area to expand. Must
be one of the following: bottom, left, right, or top.

Returns

This function does not return a value.
Usage

This function has no effect if the area is already expanded.
Example

The following code snippet expands the left area of the layout border layout when the user clicks the button.



#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

2536

Adobe ColdFusion Documentation

ColdFusion.Layout.getAccordionLayout
Description

Gets the underlying Ext (Ext JS JavaScript library) object for the specified accordion layout.
Function syntax

ColdFusion.Layout.getAccordionLayout(name)

See also

cflayout, ColdFusion.Layout.collapseAccordion, ColdFusion.Layout.createAccordionPanel, Co
ldFusion.Layout.expandAccordion, ColdFusion.Layout.hideAccordion, ColdFusion.Layout.sel
ectAccordion, ColdFusion.Layout.showAccordion, Using layouts in Controlling Ajax user interface layout t
he Developing ColdFusion Applications
History

ColdFusion 9: Added this function
Parameters

Parameter

Description

name

The value of the name attribute of the accordion type c
flayout tag for which you want the object.

Returns

An object of type Ext.AccordionLayout.
Usage

Use this function to get the Ext toolkit (Ext.AccordionLayout) object that underlies the ColdFusion HTML cflay
out control. You can then use the raw object to modify the displayed layout. For documentation on the objects and
how to manage them, see the [Ext
documentation|http://extjs.com/deploy/ext/docs/].
#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

2537

Adobe ColdFusion Documentation

ColdFusion.Layout.getBorderLayout
Description

Gets the underlying Ext (Ext JS JavaScript library) object for the specified bordered layout.
Function syntax

ColdFusion.Layout.getBorderLayout(name)

See also

cflayout, cflayoutarea, ColdFusion.Layout.getTabLayout, [Ext JS
JavaScript Library Documentation|http://extjs.com/deploy/ext/docs/], Using layouts in Controlling Ajax user
interface layout the Developing ColdFusion Applications
History

ColdFusion 8: Added this function
Parameters

Parameter

Description

name

The value of the name attribute of the border type cfla
yout tag for which you want the object.

Returns

An object of type Ext.BorderLayout.
Usage

Use this function to get the Ext toolkit (Ext.BorderLayout) object that underlies the ColdFusion HTML cflayout
control. You can then use the raw object to modify the displayed layout. For documentation on the objects and how
to manage them, see the [Ext
documentation|http://extjs.com/deploy/ext/docs/].
#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

2538

Adobe ColdFusion Documentation

ColdFusion.Layout.getTabLayout
Description

Gets the underlying Ext (Ext JS JavaScript library) object for the specified tabbed layout.
Function syntax

ColdFusion.Layout.getTabLayout(name)

See also

cflayout, cflayoutarea, ColdFusion.Layout.getBorderLayout, [Ext
JS - JavaScript Library Documentation|http://extjs.com/deploy/ext/docs/], Using layouts in Controlling Ajax user
interface layout the Developing ColdFusion Applications
History

ColdFusion 8: Added this function
Parameters

Parameter

Description

name

The value of the name attribute of the border type cfla
yout tag for which you want the object.

Returns

An object of type Ext.BorderLayout.
Usage

Use this function to get the Ext toolkit (Ext.BorderLayout) object that underlies the ColdFusion HTML cflayout
control. You can then use the raw object to modify the displayed layout. For documentation on the objects and how
to manage them, see the [Ext
documentation|http://extjs.com/deploy/ext/docs/].
#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

2539

Adobe ColdFusion Documentation

ColdFusion.Layout.hideAccordion
Description

Hides the specified panel and its accordion layout.
Function syntax

ColdFusion.Layout.hideAccordion(layoutname, layoutareaname)

See also

cflayout, ColdFusion.Layout.collapseAccordion, ColdFusion.Layout.createAccordionPanel, Co
ldFusion.Layout.expandAccordion, ColdFusion.Layout.getAccordionLayout, ColdFusion.Layou
t.selectAccordion, ColdFusion.Layout.showAccordion, Using layouts in Controlling Ajax user interface
layout the Developing ColdFusion Applications
History

ColdFusion 9: Added this function
Parameters

Parameter

Description

layoutname

The name attribute of the accordion layout that contains
the panel to hide.

layoutareaname

The name attribute of the panel to hide.

Returns

This function does not return a value.
Example

The following example creates an accordion layout with two panels. Click the buttons to show and hide the second
panel.

© 2014 Adobe Systems Incorporated. All rights reserved.

2540

Adobe ColdFusion Documentation







The First Panel
Here are the contents of the first panel.


The Second Panel
This is the content of the second panel.











#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

2541

Adobe ColdFusion Documentation

ColdFusion.Layout.hideArea
Description

Hides an area of a border layout.
Function syntax

ColdFusion.Layout.hideArea(layout, layoutArea)

See also

cflayout, cflayoutarea, ColdFusion.Layout.collapseArea, ColdFusion.Layout.expandArea, Cold
Fusion.Layout.showArea, Using layouts in Controlling Ajax user interface layout the Developing ColdFusion
Applications
History

ColdFusion 8: Added this function
Parameters

Parameter

Description

layout

The name attribute of the border layout that contains
the area to hide.

layoutArea

The position in the layout of the area to hide. Must be
one of the following: bottom, left, right, or top.

Returns

This function does not return a value.
Usage

This function has no effect if the area is already hidden.
Example

The following code snippet hides the left area of the layout border layout when the user clicks the button.



#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

2542

Adobe ColdFusion Documentation

ColdFusion.Layout.hideTab
Description

Hides the specified tab and its layout area.
Function syntax

ColdFusion.Layout.hideTab(layout, layoutArea)

See also

cflayout, cflayoutarea, ColdFusion.Layout.createTab, ColdFusion.Layout.disableTab, ColdFus
ion.Layout.enableTab, ColdFusion.Layout.selectTab, ColdFusion.Layout.showTab, Using layouts i
n Controlling Ajax user interface layout the Developing ColdFusion Applications
History

ColdFusion 8: Added this function
Parameters

Parameter

Description

layout

The name attribute of the tabbed layout that contains
the area to hide.

layoutArea

The name attribute of the tab layout area to hide.

Returns

This function does not return a value.
Example

The following example creates a layout with two tabs. Click the buttons to show and hide the second tab.

© 2014 Adobe Systems Incorporated. All rights reserved.

2543

Adobe ColdFusion Documentation







The First Tab
Here are the contents of the first tab.


The Second Tab
This is the content of the second tab.











#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

2544

Adobe ColdFusion Documentation

ColdFusion.Layout.selectAccordion
Description

Selects the specified accordion layout and displays its panels.
Function syntax

ColdFusion.Layout.selectAccordion(layoutname, layoutareaname)

See also

cflayout, ColdFusion.Layout.collapseAccordion, ColdFusion.Layout.createAccordionPanel, Co
ldFusion.Layout.expandAccordion, ColdFusion.Layout.getAccordionLayout, ColdFusion.Layou
t.hideAccordion, ColdFusion.Layout.showAccordion, Using layouts in Controlling Ajax user interface
layout the Developing ColdFusion Applications
History

ColdFusion 9: Added this function
Parameters

Parameter

Description

layoutname

The name attribute of the accordion layout that contains
the area to select.

layoutareaname

The name attribute of the panel to select.

Returns

This function does not return a value.
Usage

This function has no effect on a disabled panel.
Example

The following code lets you select each of the two panels in an accordion layout.

© 2014 Adobe Systems Incorporated. All rights reserved.

2545

Adobe ColdFusion Documentation







The First Panel
Here are the contents of the first panel.


The Second Panel
This is the content of the second panel.



Use these links to test selecting tabs via JavaScript:

Click here to select panel 1.

Click here to select panel 2.





#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

2546

Adobe ColdFusion Documentation

ColdFusion.Layout.selectTab
Description

Selects the specified tab and displays its layout area.
Function syntax

ColdFusion.Layout.selectTab(layout, layoutArea)

See also

cflayout, cflayoutarea, ColdFusion.Layout.createTab, ColdFusion.Layout.disableTab, ColdFus
ion.Layout.enableTab, ColdFusion.Layout.hideTab, ColdFusion.Layout.showTab, Using layouts in
Controlling Ajax user interface layout the Developing ColdFusion Applications
History

ColdFusion 8: Added this function
Parameters

Parameter

Description

layout

The name attribute of the tabbed layout that contains
the area to select.

layoutArea

The name attribute of the tab layout area to select.

Returns

This function does not return a value.
Usage

This function has no effect on a disabled tab.
Example

The following code lets you select each of the two tabs in a layout.

© 2014 Adobe Systems Incorporated. All rights reserved.

2547

Adobe ColdFusion Documentation







The First Tab
Here are the contents of the first tab.


The Second Tab
This is the content of the second tab.



Use these links to test selecting tabs via JavaScript:

Click here to select tab 1.

Click here to select tab 2.





#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

2548

Adobe ColdFusion Documentation

ColdFusion.Layout.showAccordion
Description

Shows a panel in the accordion layout that was hidden using the coldfusion.layout.hideAccordion function.
Function syntax

ColdFusion.Layout.showAccordion(layoutname, layoutareaname)

See also

cflayout, ColdFusion.Layout.collapseAccordion, ColdFusion.Layout.createAccordionPanel, Co
ldFusion.Layout.expandAccordion, ColdFusion.Layout.getAccordionLayout, ColdFusion.Layou
t.hideAccordion, ColdFusion.Layout.selectAccordion, Using layouts in Controlling Ajax user interface
layout the Developing ColdFusion Applications
History

ColdFusion 9: Added this function
Parameters

Parameter

Description

layoutname

The name attribute of the accordion layout that contains
the panels to show.

layoutareaname

The name attribute of the accordion layout area whose
panels you want to show.

Returns

This function does not return a value.
Usage

This function shows only the panel of an accordion layout area; it does not show the display area. To show the
display area of a hidden panel, call this function, followed by ColdFusion.Layout.selectAccordion.This function does
not show a panel that a user closed by clicking the x icon on the panel.
Example

See ColdFusion.Layout.hideAccordion.
#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

2549

Adobe ColdFusion Documentation

ColdFusion.Layout.showArea
Description

Shows an area of a border layout that was hidden by using the cflayoutarea tag inithide attribute or the Cold
Fusion.Layout.hideArea() JavaScript function.
Function syntax

ColdFusion.Layout.showArea(layout, layoutArea)

See also

cflayout, cflayoutarea, ColdFusion.Layout.collapseArea, ColdFusion.Layout.expandArea, Cold
Fusion.Layout.getTabLayout, Using layouts in Controlling Ajax user interface layout the Developing
ColdFusion Applications
History

ColdFusion 8: Added this function
Parameters

Parameter

Description

layout

The name attribute of the border layout that contains
the area to show.

layoutArea

The position in the layout of the area to show. Must be
one of the following: bottom, left, right, or top.

Returns

This function does not return a value.
Usage

This function does not show an area that a user closed by clicking the X icon on the title bar. Other areas move, if
needed, to accommodate the area.This function has no effect if the area is already visible.
Example

The following code snippet shows the left area of the layout border layout when the user clicks the button.



#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

2550

Adobe ColdFusion Documentation

ColdFusion.Layout.showTab
Description

Shows a tab that was hidden by using the inithide attribute of the cflayoutarea tag or the hideTab() JavaSc
ript function.
Function syntax

ColdFusion.Layout.showTab(layout, layoutArea)

See also

cflayout, cflayoutarea, ColdFusion.Layout.createTab, ColdFusion.Layout.disableTab, ColdFus
ion.Layout.enableTab, ColdFusion.Layout.hideTab, ColdFusion.Layout.selectTab, Using layouts i
n Controlling Ajax user interface layout the Developing ColdFusion Applications
History

ColdFusion 8: Added this function
Parameters

Parameter

Description

layout

The name attribute of the tabbed layout that contains
the tab to show.

layoutArea

The name attribute of the tab layout area whose tab
you want to show.

Returns

This function does not return a value.
Usage

This function shows only the tab of a layout area; it does not show the display area. To show the display area of a
hidden tab, call this function, followed by ColdFusion.Layout.selectTab.This function does not show a tab that
a user closed by clicking the x icon on the tab.
Example

See ColdFusion.Layout.hideTab.
#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

2551

Adobe ColdFusion Documentation

ColdFusion.Log.debug
Description

Displays a debug-level message in a log window.
Function syntax

ColdFusion.Log.debug(message [, category])

See also

ColdFusion.Log.dump, ColdFusion.Log.error, ColdFusion.Log.info, Logging information in Debugging
Ajax applications the Developing ColdFusion Applications
History

ColdFusion 8: Added this function
Parameters

Parameter

Description

message

The text message to display in the log window. The log
message can include HTML markup and JavaScript
variables.

category

A category identifier that you can use in the logging
window to filter the output. You can specify any
arbitrary category in this function. The default value is g
lobal.

Returns

This function does not return a value.
Usage

If the page that calls this function does not have any ColdFusion AJAX-based controls, you use a cfajaximport ta
g on the page to ensure that the page includes the JavaScript definition for this function.The log window appears if
you specify a URL parameter of the format cfdebug or cfdebug="true" in your page request and you select the
Enable Ajax Debug Log Window option on the ColdFusion Administrator Debugging & Logging > Debug Output
Settings page.
Example

ColdFusion.Log.debug("Debug argument:
" + arg.A, "Pod A");

#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

2552

Adobe ColdFusion Documentation

© 2014 Adobe Systems Incorporated. All rights reserved.

2553

Adobe ColdFusion Documentation

ColdFusion.Log.dump
Description

Displays a debug-level message in the log window that shows a cfdump-like representation of a complex
JavaScript object. The log window does not have a separate dump level.
Function syntax

ColdFusion.Log.dump(object [, category])

See also

ColdFusion.Log.debug, ColdFusion.Log.error, ColdFusion.Log.info, Logging information in Debuggin
g Ajax applications the Developing ColdFusion Applications
History

ColdFusion 8: Added this function
Parameters

Parameter

Description

object

The variable whose contents you want to display. You
cannot specify additional contents, such as a text
message, when you dump a complex object. To
provide additional information, also use the ColdFusi
on.Log.debug function.

category

A category identifier that you can use in the logging
window to filter the output. You can specify any
arbitrary category in this function. The default value is g
lobal.

Returns

This function does not return a value.
Usage

If the page that calls this function does not have any ColdFusion AJAX-based controls, you use a cfajaximport ta
g on the page to ensure that the page includes the JavaScript definition for this function.The log window appears if
you specify a URL parameter of the format cfdebug or cfdebug="true" in your page request and you select the
Enable Ajax Debug Log Window option on the ColdFusion Administrator Debugging & Logging > Debug Output
Settings page.
Example

© 2014 Adobe Systems Incorporated. All rights reserved.

2554

Adobe ColdFusion Documentation

ColdFusion.Log.dump(objArg, "Pod A");

#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

2555

Adobe ColdFusion Documentation

ColdFusion.Log.error
Description

Displays an error-level message in a log window.
Function syntax

ColdFusion.Log.error(message [, category])

See also

ColdFusion.Log.debug, ColdFusion.Log.dump, ColdFusion.Log.info, Logging information in Debugging
Ajax applications the Developing ColdFusion Applications
History

ColdFusion 8: Added this function
Parameters

Parameter

Description

message

The text message to display in the log window. The log
message can include HTML markup and JavaScript
variables.

category

A category identifier that you can use in the logging
window to filter the output. You can specify any
arbitrary category in this function. The default value is g
lobal.

Returns

This function does not return a value.
Usage

If the page that calls this function does not have any ColdFusion AJAX-based controls, you use a cfajaximport ta
g on the page to ensure that the page includes the JavaScript definition for this function.The log window appears if
you specify a URL parameter of the format cfdebug or cfdebug="true" in your page request and you select the
Enable Ajax Debug Log Window option on the ColdFusion Administrator Debugging & Logging > Debug Output
Settings page.
Example

ColdFusion.Log.error("Invalid value:
" + arg.A, "Pod A");

#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

2556

Adobe ColdFusion Documentation

© 2014 Adobe Systems Incorporated. All rights reserved.

2557

Adobe ColdFusion Documentation

ColdFusion.Log.info
Description

Displays an information-level message in a log window.
Function syntax

ColdFusion.Log.info(message [, category])

See also

ColdFusion.Log.debug, ColdFusion.Log.dump, ColdFusion.Log.error, Logging information in Debuggin
g Ajax applications the Developing ColdFusion Applications
History

ColdFusion 8: Added this function
Parameters

Parameter

Description

message

The text message to display in the log window. The log
message can include HTML markup and JavaScript
variables.

category

A category identifier that you can use in the logging
window to filter the output. You can specify any
arbitrary category in this function. The default value is g
lobal.

Returns

This function does not return a value.
Usage

If the page that calls this function does not have any ColdFusion AJAX-based controls, you use a cfajaximport ta
g on the page to ensure that the page includes the JavaScript definition for this function.The log window appears if
you specify a URL parameter of the format cfdebug or cfdebug="true" in your page request and you select the
Enable Ajax Debug Log Window option on the ColdFusion Administrator Debugging & Logging > Debug Output
Settings page.
Example

ColdFusion.Log.info("arg.A is:
" + arg.A, "Window Z");

#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

2558

Adobe ColdFusion Documentation

© 2014 Adobe Systems Incorporated. All rights reserved.

2559

Adobe ColdFusion Documentation

ColdFusion.Map.addEvent
Description

Executes a custom JavaScript function to enable event handling in a map.
Function syntax

ColdFusion.Map.addEvent(name, event, listener, scopeObject)

See also

ColdFusion.Map.getLatitudeLongitude, ColdFusion.Map.getMapObject, ColdFusion.Map.setCen
ter, ColdFusion.Map.setZoomlevel
History

ColdFusion 9: Added this function
Parameters

Parameter

Description

name

Name of the map.

event

The event to handle, for example click, dblclick,
singleRightClick and mapTypeChange. For more
events, refer to the Events section in the Google Maps
API Reference documentation.

listener

The function that is called when the event is fired.

scopeObject

A JavaScript object that is set in the this scope.

Usage

This function does not return a value.
Example

© 2014 Adobe Systems Incorporated. All rights reserved.

2560

Adobe ColdFusion Documentation

This is an example of the Map.addmarker function. Click the HTML button labeled
"Add marker" to set the marker to the specified Address.

MAP 1






#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

2561

Adobe ColdFusion Documentation

ColdFusion.Map.addMarker
Description

Adds a marker to the map.
Function syntax

ColdFusion.Map.addMarker(name, markerObj)

See also

ColdFusion.Map.getLatitudeLongitude, ColdFusion.Map.getMapObject, ColdFusion.Map.setCen
ter, ColdFusion.Map.setZoomlevel
History

ColdFusion 9: Added this function
Parameters

Parameter

Description

name

Specifies the value of the name attribute of the cfmap t
ag.

markerObj

Specifies the marker object for a given address. The
following are the associated properties: latitude, lo
ngitude, address, title, markercolor, markeri
con, address, markerwindowcontent, and showm
arkerwindow

Returns

This function does not return a value.
Example

© 2014 Adobe Systems Incorporated. All rights reserved.

2562

Adobe ColdFusion Documentation

This is an example of the Map.addmarker function. Click the HTML button labeled
"Add marker" to set the marker to the specified Address.

MAP 1






#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

2563

Adobe ColdFusion Documentation

ColdFusion.Map.getLatitudeLongitude
Description

Gets the latitude/longitude coordinates for a given address.
Function syntax

ColdFusion.Map.getLatitudeLongitude("address", "callBack")

See also

ColdFusion.Map.addMarker, ColdFusion.Map.getMapObject, ColdFusion.Map.setCenter, ColdFusi
on.Map.setZoomlevel
History

ColdFusion 9: Added this function
Parameters

Parameter

Description

address

Specifies the value in the address attribute of the cfm
ap tag.

callBack

The callback function that runs after the
longitude/latitude values are successfully located.

Returns

This function returns a callback function that gets the latitude and longitude values of the specified address.
Example

© 2014 Adobe Systems Incorporated. All rights reserved.

2564

Adobe ColdFusion Documentation

This is an example of the Map.getLatitudeLongitude function. Click the HTML
button labeled "GetLatitude-Longitude" to get the latitude and longitude of Ann
Arbor,MI.

MAP 1






#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

2565

Adobe ColdFusion Documentation

ColdFusion.Map.getMapObject
Description

Gets the Google map component. You can manipulate the map using supported Google Map APIs.
Function syntax

ColdFusion.Map.getMapObject("name")

See also

ColdFusion.Map.addMarker, ColdFusion.Map.getLatitudeLongitude, ColdFusion.Map.setCenter,
ColdFusion.Map.setZoomlevel
History

ColdFusion 9: Added this function
Parameters

Parameter

Description

name

Specifies the value of the name attribute of the cfmap t
ag.

Returns

This function returns the Google map component. The map type can be map, satellite, or hybrid.
Example

© 2014 Adobe Systems Incorporated. All rights reserved.

2566

Adobe ColdFusion Documentation

This is an example of the Map.getmapObject function. Click the HTML button
labeled "GetMap" to get the map object and set the center to Palo Alto.

MAP 1






#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

2567

Adobe ColdFusion Documentation

ColdFusion.Map.hide
Description

If displayed, hides the map.
Function syntax

ColdFusion.Map.hide(Id)
Parameters

Id: Name of the map.
Example

See example in ColdFusion.Map.show.
#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

2568

Adobe ColdFusion Documentation

ColdFusion.Map.refresh
Description

Reloads the map.
Function syntax

ColdFusion.Map.refresh (Id)
Parameters

Id: Name of the map.
Usage

If the map is embedded within spry collapsible panels or divs that are hidden on display, that is the map container is
displayed while the actual map is hidden, use this function to force the map to display.
Example




SHOW MAP







© 2014 Adobe Systems Incorporated. All rights reserved.

2569

Adobe ColdFusion Documentation

#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

2570

Adobe ColdFusion Documentation

ColdFusion.Map.setCenter
Description

Sets the center of map to the address that you specify.
Function syntax

ColdFusion.Map.setCenter("name", centerConfigObject)

See also

ColdFusion.Map.addMarker, ColdFusion.Map.getLatitudeLongitude, ColdFusion.Map.getMapObj
ect, ColdFusion.Map.setZoomlevel
History

ColdFusion 9: Added this function
Parameters

Parameter

Description

name

Specifies the value of the name attribute of the cfmap t
ag.

centerConfigObject

The Center Address object. The value of this object can
either be the longitude/latitude value or the address
property.

Returns

This function does not return any value.
Example 1

© 2014 Adobe Systems Incorporated. All rights reserved.

2571

Adobe ColdFusion Documentation

This is an example of the Map.setcenter function using latitude-longitude and
address values

MAP 1

Click this button to set the center using Latitude and Longitude.


Click this button to set the center using Address.





#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

2572

Adobe ColdFusion Documentation

ColdFusion.Map.setZoomlevel
Description

Sets the zoom level of the map to the new value.
Function syntax

ColdFusion.Map.setZoomlevel("name", zoomLevelValue)

See also

ColdFusion.Map.addMarker, ColdFusion.Map.getLatitudeLongitude, ColdFusion.Map.getMapObj
ect, ColdFusion.Map.setCenter
History

ColdFusion 9: Added this function
Parameters

Parameter

Description

name

Specifies the value of the name attribute of the cfmap t
ag.

zoomLevelValue

The value of the integer in the zoomlevel attribute of
the cfmap tag.

Returns

This function does not return any value.
Example

© 2014 Adobe Systems Incorporated. All rights reserved.

2573

Adobe ColdFusion Documentation

This is an example of the Map.setzoomlevel function. Click the Set Zoom Level
button to set the zoom level to 6.

MAP 1






#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

2574

Adobe ColdFusion Documentation

ColdFusion.Map.show
Description

Shows the map if it is hidden.
Function syntax

ColdFusion.Map.show(Id)
Parameters

Id: Name of the map.
Example


Show Map | Hide Map


#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

2575

Adobe ColdFusion Documentation

ColdFusion.MediaPlayer.getPlayer
Description

Returns the player object that is used to invoke Strobe media player JavaScript API.
Function syntax

ColdFusion.MediaPlayer.getPlayer("Name")

See also

ColdFusion.Mediaplayer.resize, ColdFusion.Mediaplayer.setMute, ColdFusion.Mediaplayer.s
etSource, ColdFusion.Mediaplayer.setVolume, ColdFusion.Mediaplayer.startPlay, ColdFusion.
Mediaplayer.getType, ColdFusion.Mediaplayer.stopPlay
History

ColdFusion 10: Added this function
Parameters

Parameter

Description

Name

Specifies the value of the name attribute of the cfmedi
aplayer tag.

Example

See the example for Dynamic streaming.
#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

2576

Adobe ColdFusion Documentation

ColdFusion.Mediaplayer.getType
Description

Used to get the current playback type, if Flash or HTML player.
Function syntax

ColdFusion.MediaPlayer.getType("name")

See also

ColdFusion.Mediaplayer.resize, ColdFusion.Mediaplayer.setMute, ColdFusion.Mediaplayer.s
etSource, ColdFusion.Mediaplayer.setVolume, ColdFusion.Mediaplayer.startPlay, ColdFusion.
Mediaplayer.stopPlay
History

ColdFusion 10: Added this function
Parameters

Parameter

Description

name

Specifies the value of the name attribute of the cfmedi
aplayer tag.

Returns

This function returns the playback type as Flash or HTML 5.
Example

© 2014 Adobe Systems Incorporated. All rights reserved.

2577

Adobe ColdFusion Documentation

















#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

2578

Adobe ColdFusion Documentation

ColdFusion.Mediaplayer.logError
Description

Lets you show custom error message on the media player, if an error occurs during playback.
Function syntax

ColdFusion.MediaPlayer.logError("Name", "Error")

See also

[]ColdFusion.Mediaplayer.resize, ColdFusion.Mediaplayer.setMute, ColdFusion.Mediaplayer
.setSource, ColdFusion.Mediaplayer.setVolume, ColdFusion.Mediaplayer.startPlay, ColdFusio
n.Mediaplayer.getType, ColdFusion.Mediaplayer.stopPlay
History

ColdFusion 10: Added this function
Parameters

Parameter

Description

Name

Specifies the value of the name attribute of the cfmedi
aplayer tag.

Error

The custom error message that you want to display.

Example

See the example for ColdFusion.Mediaplayer.getType.
#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

2579

Adobe ColdFusion Documentation

ColdFusion.Mediaplayer.resize
Description

Changes the current size of the media player.
Function syntax

ColdFusion.Mediaplayer.resize("name", "height", "width")

See also

ColdFusion.Mediaplayer.setMute, ColdFusion.Mediaplayer.setSource, ColdFusion.Mediaplaye
r.setVolume, ColdFusion.Mediaplayer.startPlay, ColdFusion.Mediaplayer.stopPlay
History

ColdFusion 9: Added this function
Parameters

Parameter

Description

name

Specifies the value of the name attribute of the cfmedi
aplayer tag.

height

The height (in pixels) to set for the media player. The
height is 360 pixels, by default.

width

The width (in pixels) to set for the media player. The
width is 480 pixels, by default.

Returns

This function does not return any value.
Example

In this example, the FLV file is stored in the web root used by the ColdFusion server. Store an FLV file - video.flv in
the location _web_root\xyz_.

© 2014 Adobe Systems Incorporated. All rights reserved.

2580

Adobe ColdFusion Documentation

This is an example of the Mediaplayer.resize function. Clicking the Resize
Mediaplayer button resizes the media player component.










#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

2581

Adobe ColdFusion Documentation

ColdFusion.Mediaplayer.setTitle
Description

Assigns a title for the media player on the top left corner.
Function syntax

ColdFusion.Mediaplayer.setTile("name", "title")

See also

ColdFusion.Mediaplayer.setMute, ColdFusion.Mediaplayer.setSource, ColdFusion.Mediaplaye
r.setVolume, ColdFusion.Mediaplayer.startPlay, ColdFusion.Mediaplayer.stopPlay
History

ColdFusion 10: Added this function
Parameters

Parameter

Description

name

Specifies the value of the name attribute of the cfmedi
aplayer tag.

title

Specifies the title to be displayed at the top left corner
of the media player.

Returns

This function does not return any value.
Example

© 2014 Adobe Systems Incorporated. All rights reserved.

2582

Adobe ColdFusion Documentation

This is an example of the Mediaplayer.setTitle function. Clicking the Resize
Mediaplayer button resizes the media player component.










#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

2583

Adobe ColdFusion Documentation

ColdFusion.Mediaplayer.setMute
Description

Mutes or unmutes the sound of the media player.
Function syntax

ColdFusion.Mediaplayer.setMute("name", mute)

See also

ColdFusion.Mediaplayer.resize, ColdFusion.Mediaplayer.setSource, ColdFusion.Mediaplayer
.setVolume, ColdFusion.Mediaplayer.startPlay, ColdFusion.Mediaplayer.stopPlay
History

ColdFusion 9: Added this function
Parameters

Parameter

Description

name

Specifies the value of the name attribute of the cfmedi
aplayer tag.

mute

A Boolean value specifying whether to mute the sound
(true), or to turn off the mute (false).

Returns

This function does not return any value.
Example

In this example, the FLV file is stored in the web root used by the ColdFusion server. Store an FLV file - video.flv in
the location _web_root\xyz_.

© 2014 Adobe Systems Incorporated. All rights reserved.

2584

Adobe ColdFusion Documentation

This is an example of the Mediaplayer.setmute function. Clicking the Mute button
mutes the media player.








#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

2585

Adobe ColdFusion Documentation

ColdFusion.Mediaplayer.setSource
Description

Sets the URL of the FLV file. The URL can point to a location on the ColdFusion server or any other server.
Function syntax

ColdFusion.Mediaplayer.setSource("name", newURL)

See also

ColdFusion.Mediaplayer.setMute, ColdFusion.Mediaplayer.setMute, ColdFusion.Mediaplayer.
setVolume, ColdFusion.Mediaplayer.startPlay, ColdFusion.Mediaplayer.stopPlay
History

ColdFusion 9: Added this function
Parameters

Parameter

Description

name

Specifies the value of the name attribute of the cfmedi
aplayer tag.

newURL

The URL to the FLV file. This can be a URL relative to
the current page. You can store the FLV file on the
ColdFusion server or any other streaming server.

Returns

This function does not return any value.
Example

In this example, the source of the FLV file is changed from video.flv to newvideo. flv. The media player then plays
the newvideo.flv file.

© 2014 Adobe Systems Incorporated. All rights reserved.

2586

Adobe ColdFusion Documentation

This is an example of the Mediaplayer.setsource function. Clicking the Set
Source button changes the video playing in the media player.








#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

2587

Adobe ColdFusion Documentation

ColdFusion.Mediaplayer.setVolume
Description

Sets the volume of sound of the media player.
Function syntax

ColdFusion.Mediaplayer.setVolume("name", "volume")

See also

ColdFusion.Mediaplayer.resize, ColdFusion.Mediaplayer.setMute, ColdFusion.Mediaplayer.s
etSource, ColdFusion.Mediaplayer.startPlay, ColdFusion.Mediaplayer.stopPlay
History

ColdFusion 9: Added this function
Parameters

Parameter

Description

name

Specifies the value of the name attribute of the cfmedi
aplayer tag.

volume

The value of the volume. It can take any value from 0.
0 through 1.0.

Returns

This function does not return any value.
Example

In this example, the FLV file is stored in the web root used by the ColdFusion server. Store an FLV file - video.flv in
the location _web_root\xyz_.

© 2014 Adobe Systems Incorporated. All rights reserved.

2588

Adobe ColdFusion Documentation

This is an example of the Mediaplayer.setvolume function. Clicking the Set
Volume button increases the volume of the media player.








#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

2589

Adobe ColdFusion Documentation

ColdFusion.Mediaplayer.startPlay
Description

Plays the FLV file.
Function syntax

ColdFusion.Mediaplayer.startPlay("name")

See also

ColdFusion.Mediaplayer.resize, ColdFusion.Mediaplayer.setMute, ColdFusion.Mediaplayer.s
etSource, ColdFusion.Mediaplayer.setVolume, ColdFusion.Mediaplayer.stopPlay
History

ColdFusion 9: Added this function
Parameters

Parameter

Description

name

Specifies the value of the name attribute of the cfmedi
aplayer tag.

Returns

This function does not return any value.
Example

In this example, the FLV file is stored in the web root used by the ColdFusion server. Store an FLV file - video.flv in
the location _web_root\xyz_.

This is an example of the Mediaplayer.startplay function. Clicking the Start
Play button plays the video.








© 2014 Adobe Systems Incorporated. All rights reserved.

2590

Adobe ColdFusion Documentation

#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

2591

Adobe ColdFusion Documentation

ColdFusion.Mediaplayer.stopPlay
Description

Stops playing the FLV file.
Function syntax

ColdFusion.Mediaplayer.stopPlay("name")

See also

ColdFusion.Mediaplayer.resize, ColdFusion.Mediaplayer.setMute, ColdFusion.Mediaplayer.s
etSource, ColdFusion.Mediaplayer.setVolume, ColdFusion.Mediaplayer.startPlay
History

ColdFusion 9: Added this function
Parameters

Parameter

Description

name

Specifies the value of the name attribute of the cfmedi
aplayer tag.

Returns

This function does not return any value.
Example

In this example, the FLV file is stored in the web root used by the ColdFusion server. Store an FLV file - video.flv in
the location _web_root\xyz_.

This is an example of the Mediaplayer.stopplay function. Clicking the Stop Play
button stops playing the video.








© 2014 Adobe Systems Incorporated. All rights reserved.

2592

Adobe ColdFusion Documentation

#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

2593

Adobe ColdFusion Documentation

ColdFusion.MessageBox.create
Description

Creates a ColdFusion message box. This function is equivalent to the cfmessagebox tag.
Function syntax

ColdFusion.MessageBox.create(name, type, title, message, callbackhandler [,
configuration])

See also

ColdFusion.MessageBox.isMessageBoxDefined, ColdFusion.MessageBox.getMessageBoxObject, Co
ldFusion.MessageBox.update, ColdFusion.MessageBox.updateMessage, ColdFusion.MessageBox.
updateTitle, ColdFusion.MessageBox.show
History

ColdFusion 9: Added this function
Parameters

Parameter

Description

name

The name of the message box. This attribute is
required to show and update the message box. The
message box name must be unique on the page.

type

The control type. Must be one of the following:
alert - A message with a single OK button.
confirm - A message box with two buttons YES and
NO or three buttons YES, NO, and CANCEL.
prompt - A message box with a single-line or
multiline text input area and OK and CANCEL
buttons.

title

The text to display on the message box title bar.

message

The text to display inside the message box.

callbackhandler

The function that the control calls when a user clicks
one of the buttons.

configuration

An object containing message box configuration
parameters. For details, see "Usage".

Returns

© 2014 Adobe Systems Incorporated. All rights reserved.

2594

Adobe ColdFusion Documentation

This function does not return a value.
Usage

This function is equivalent to the cfmessagebox tag. If you do not also use a cfmessagebox tag on a page that
calls this function, specify a cfajaximport tag on the page and specify cfmessagebox in the tags attribute.
Doing so ensures that the page includes the necessary JavaScript to create the message box. For example, use the
following line if you do not have to import the JavaScript for any other ColdFusion Ajax features:



The configuration parameter defines the message box characteristics; it can have any or all the following entries:
Entry

Default

A CSS style specification for the
body of the message box.
Generally, you use this attribute to
set color and font styles.

bodystyle

buttontype

Description

yesno

Applies to the control type - confir
m.The buttons to display on the
message box:
yesno: displays the buttons Yes
and No
yesnocancel: displays the
buttons Yes, No, and Cancel
*
Specifies the following CSS
classes:

icon

error: Provides the error icon.
You can use this icon when
displaying error messages.
info: Provides the info icon. You
can use this icon when displaying
any information.
question: Provides the question
icon. You can use this icon in a
confirmation message box that
prompts a user response.
warning: Provides the warning
icon. You can use this icon when
displaying a warning message.
labelcancel

Cancel

© 2014 Adobe Systems Incorporated. All rights reserved.

The text to put on the cancel button
of a prompt message box.

2595

Adobe ColdFusion Documentation

labelok

OK

The text to put on an alert button
and prompt message box OK
button.

labelno

No

The text to put on the button used
for a negative response in a confirm
message box.

labelyes

Yes

The text to put on the button used
for a positive response a confirm
message box.

modal

yes

A Boolean value that specifies if the
message box is a modal window:
yes
no

multiline

false

Valid only for prompt type message
boxes. A Boolean value specifying
whether the prompt input text box
has a single or multiple lines for text
input.

width

Width of the message box in pixels.

x

The X (horizontal) coordinate of the
upper-left corner of the message
box.ColdFusion ignores this
attribute if you do not set the y attrib
ute.

y

The Y (vertical) coordinate of the
upper-left corner of the message
box.ColdFusion ignores this
attribute if you do not set the x attrib
ute.

Note
Entry names in the configuration object must be all-lowercase.

Example

The following minimal CFML application creates a message box of type confirmation.

© 2014 Adobe Systems Incorporated. All rights reserved.

2596

Adobe ColdFusion Documentation







#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

2597

Adobe ColdFusion Documentation

ColdFusion.MessageBox.show
Description

Used to display a ColdFusion message box.
Function syntax

ColdFusion.MessageBox.show(name)
See also

ColdFusion.MessageBox.isMessageBoxDefined, ColdFusion.MessageBox.getMessageBoxObject, Co
ldFusion.MessageBox.update, ColdFusion.MessageBox.updateMessage, ColdFusion.MessageBox.
updateTitle, ColdFusion.MessageBox.create
History

ColdFusion 9: Added this function
Parameters

Parameter

Description

name

Name of the message box that you want to display.

Returns

This function does not return a value.
Usage

You can create a messagebox using the cfmessagebox tag or the JavaScript function ColdFusion.MessageBox
.create. But to show it, you must use this function.
Example







#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

2598

Adobe ColdFusion Documentation

ColdFusion.MessageBox.getMessageBoxObject
Description
Gets the underlying Ext JS - JavaScript Library object for the specified HTML cfmessagebox control.
Function syntax

ColdFusion.MessageBox.getMessageBoxObject(name)

See also
ColdFusion.MessageBox.create, ColdFusion.MessageBox.isMessageBoxDefined, ColdFusion.Mes
sageBox.update, ColdFusion.MessageBox.updateMessage, ColdFusion.MessageBox.updateTitle
History
ColdFusion 9: Added this function
Parameters
Parameter

Description

name

The name of the message box object.

Returns
A JavaScript object.
Usage
Use this function to get the JavaScript object that contains all the defined properties. ---#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

2599

Adobe ColdFusion Documentation

ColdFusion.MessageBox.isMessageBoxDefined
Description
Checks if a message box is defined.
Function syntax

ColdFusion.MessageBox.isMessageBoxDefined(name)

See also
ColdFusion.MessageBox.create, ColdFusion.MessageBox.getMessageBoxObject, ColdFusion.Mes
sageBox.update, ColdFusion.MessageBox.updateMessage, ColdFusion.MessageBox.updateTitle
History
ColdFusion 9: Added this function
Parameters
Parameter

Description

name

The name of the message box object.

Returns
A Boolean value, that is, true or false.
Usage
Use this function to check if the message box is defined for a specific name.
#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

2600

Adobe ColdFusion Documentation

ColdFusion.MessageBox.update
Description

Updates the ColdFusion message box properties. This JavaScript function lets you update all the message box
properties except name and type.
Function syntax

ColdFusion.MessageBox.update(name, configuration)

See also

ColdFusion.MessageBox.create, ColdFusion.MessageBox.getMessageBoxObject, ColdFusion.Mes
sageBox.isMessageBoxDefined, ColdFusion.MessageBox.updateMessage, ColdFusion.MessageBox
.updateTitle
History

ColdFusion 9: Added this function
Parameters

Parameter

Description

name

The name of the message box. This attribute is
required to show and update the message box. The
message box name must be unique on the page.

configuration

An object containing message box configuration
parameters. For details, see "Usage".

Returns

This function does not return a value.
Usage

This function is used to update a set of message box properties. For example, you can update the width, message,
and title of the message box using the configuration parameter.The configuration parameter defines the message
box characteristics; it can have any or all the following entries:
Entry

Description

bodystyle

A CSS style specification for the body of the message
box. Generally, you use this attribute to set color and
font styles.

© 2014 Adobe Systems Incorporated. All rights reserved.

2601

Adobe ColdFusion Documentation

buttontype

Applies to the control type - confirm.The buttons to
display on the message box:
yesno: displays the buttons Yes and No
yesnocancel: displays the buttons Yes, No, and
Cancel
*

callbackhandler

The function that the control calls when a user clicks
one of the buttons. For more information see Usage.

icon

Specifies the following CSS classes:
error: Provides the error icon. You can use this icon
when displaying error messages.
info: Provides the info icon. You can use this icon
when displaying any information.
question: Provides the question icon. You can use
this icon in a confirmation message box that prompts
a user response.
warning: Provides the warning icon. You can use this
icon when displaying a warning message.

labelcancel

The text to put on the cancel button of a prompt
message box.

labelok

The text to put on an alert button and prompt message
box OK button.

labelno

The text to put on the button used for a negative
response in a confirm message box.

labelyes

The text to put on the button used for a positive
response in a confirm message box.

modal

A Boolean value that specifies if the message box is a
modal window:
yes
no

message

The text to display inside the message box.

multiline

Valid only for prompt type message boxes. A Boolean
value specifying whether the prompt input text box has
a single or multiple lines for text input.

title

The title for the message box. If you do not specify a
title, ColdFusion assigns the control type value as the
default title.

© 2014 Adobe Systems Incorporated. All rights reserved.

2602

Adobe ColdFusion Documentation

width

Width of the message box in pixels.

x

The X (horizontal) coordinate of the upper-left corner of
the message box.ColdFusion ignores this attribute if
you do not set the y attribute.

y

The Y (vertical) coordinate of the upper-left corner of
the message box.ColdFusion ignores this attribute if
you do not set the x attribute.

Note
Entry names in the configuration object must be all-lowercase.

Example

The following minimal CFML application updates a message box.






#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

2603

Adobe ColdFusion Documentation

ColdFusion.MessageBox.updateMessage
Description

Updates the message property of the ColdFusion message box component.
Function syntax

ColdFusion.MessageBox.updateMessage(name, newmessage)

See also

ColdFusion.MessageBox.create, ColdFusion.MessageBox.getMessageBoxObject, ColdFusion.Mes
sageBox.isMessageBoxDefined, ColdFusion.MessageBox.update, ColdFusion.MessageBox.update
Title
History

ColdFusion 9: Added this function
Parameters

Parameter

Description

name

The name of the message box object.

newmessage

Overwrites an existing message.

Returns

This function does not return a value.
Usage

Use this function to update or change the message property of the message box. ---#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

2604

Adobe ColdFusion Documentation

ColdFusion.MessageBox.updateTitle
Description

Updates the title property of the ColdFusion message box component.
Function syntax

ColdFusion.MessageBox.updateTitle(name, newtitle)

See also

ColdFusion.MessageBox.create, ColdFusion.MessageBox.getMessageBoxObject, ColdFusion.Mes
sageBox.isMessageBoxDefined, ColdFusion.MessageBox.update, ColdFusion.MessageBox.update
Message
History

ColdFusion 9: Added this function
Parameters

Parameter

Description

name

The name of the message box object.

newmessage

Overwrites an existing title.

Returns

This function does not return a value.
Usage

Use this function to update or change the title property of the message box.
#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

2605

Adobe ColdFusion Documentation

ColdFusion.navigate
Description

Displays the output of a link target in an Ajax cfdiv, cflayoutarea, cfpod, or cfwindow container. When the
browser follows a link that is populated by this function, the link does not replace the current page. Instead, it
populates the control specified by the container attribute.
Function syntax

ColdFusion.navigate(URL [, container, callbackhandler, errorHandler, httpMethod,
formId])

See also

AjaxLink, cfajaximport, ColdFusion.Ajax.submitForm, Control container contents in Controlling Ajax user
interface layout in the Developing ColdFusion Applications
History

ColdFusion 8: Added this function
Parameters

Parameter

Description

URL

The URL of the link.

container

The name attribute value of the control in which to
display the link output. The control must be a container
control such as cfdiv, cflayoutarea, cfpod, or cf
window.If you omit this argument, the link is treated as
a normal URL and the entire page is refreshed.

callbackhandler

The name of a JavaScript function to call after the
target has been displayed.

errorHandler

The name of a JavaScript function to call if an error
occurs when this function executes. The function can
take two parameters: an HTTP error code, and an error
message.

formId

The ID or name attribute of a form to submit to the
URL.

httpMethod

The HTTP method to use when navigating to the URL:
GET (the default)
POST

© 2014 Adobe Systems Incorporated. All rights reserved.

2606

Adobe ColdFusion Documentation

Returns

This function does not return a value.
Usage

If the page that calls this function does not have any ColdFusion AJAX-based controls, you must use a cfajaximp
ort tag on the page to ensure that the page includes the JavaScript definition for this function.The callbackhand
ler parameter can be useful for changing the display after the contents has been displayed. For example, before
you make the ColdFusion.navigate call you might make a pod's title bar italic to indicate loading; you could
then use the callbackhandler function to switch it back to normal or make it bold once navigate completes.
Similarly, you could use a callbackhandler to update the page number in a book reader.The FormID attribute
lets you specify a form to submit to the specified URL. You can use the ColdFusion.Navigate function with this
attribute to submit form data asynchronously from outside the form, for example, when the user clicks a menu item,
and to direct the returned results to a specific container control.
Example

When the user clicks the link in window 1, the ColdFusion.navigate function replaces the text in window 2 with
the contents of windowsrc.cfm, and then calls the myCallback callback handler, which changes the innerHTML of
the callback div region.The main application page looks as follows:








This is a cfwindow control.


Click to navigate Window 2


This is a second cfwindow control.




© 2014 Adobe Systems Incorporated. All rights reserved.

2607

Adobe ColdFusion Documentation

The windowsource.cfm page looks as follows:

This is markup from "windowsource.cfm"



#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

2608

Adobe ColdFusion Documentation

ColdFusion.ProgressBar.getProgressBarObject
Description
Gets the progress bar object.
Function syntax

ColdFusion.ProgressBar.getProgressBarObject(name)

See also
ColdFusion.ProgressBar.start, ColdFusion.ProgressBar.stop
History
ColdFusion 9: Added this function
Parameters
Parameter

Description

name

The name of the progress bar object.

Returns
This function returns the underlying Ext JavaScript progress bar object.
Usage
You call this function to get the progress bar object. ---#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

2609

Adobe ColdFusion Documentation

ColdFusion.ProgressBar.hide
Description

Hides the progress bar if it is displayed.
Function syntax

ColdFusion.ProgressBar.hide(progressBarId)

See also

ColdFusion.ProgressBar.show, ColdFusion.ProgressBar.update
History

ColdFusion 9: Added this function
Parameters

Parameter

Description

progressBarId

Name of the progress bar object. This must be a valid
ColdFusion identifier.

Returns

This function does not return a value.
Usage

This function lets you hide the progress bar if it is displayed.You display the progressbar using the function ColdFu
sion.ProgressBar.show or by setting the attribute autodisplay to true in the tag cfprogressbar.The
following example shows how to use this function:




#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

2610

Adobe ColdFusion Documentation

ColdFusion.ProgressBar.reset
Description

Resets the progress status and messages.
Function syntax

ColdFusion.ProgressBar.reset(progressBarId)

See also

ColdFusion.ProgressBar.start, ColdFusion.ProgressBar.stop
History

ColdFusion 9: Added this function
Parameters

Parameter

Description

progressBarId

Name of the progress bar object. This must be a valid
ColdFusion identifier.

Returns

This function does not return a value.
Usage

Resets the progress on a progress bar as shown in the following example:






#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

2611

Adobe ColdFusion Documentation

ColdFusion.ProgressBar.show
Description

Shows the progress bar if it is hidden.
Function syntax

ColdFusion.ProgressBar.show(progressBarId)

See also

ColdFusion.ProgressBar.hide, ColdFusion.ProgressBar.update
History

ColdFusion 9: Added this function
Parameters

Parameter

Description

progressBarId

Name of the progress bar object. This must be a valid
ColdFusion identifier.

Returns

This function does not return a value.
Usage

This function lets you display the progress bar if it is hidden.You hide the progress bar using the function ColdFusi
on.ProgressBar.hide or by setting the attribute autodisplay to false in the cfprogressbar tag.The
following example shows how to use this function:




#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

2612

Adobe ColdFusion Documentation

ColdFusion.ProgressBar.start
Description

Starts the underlying Ext JS - JavaScript Library progress bar object.
Function syntax

ColdFusion.ProgressBar.start(name)

See also

ColdFusion.ProgressBar.getProgressBarObject, ColdFusion.ProgressBar.stop
History

ColdFusion 9: Added this function
Parameters

Parameter

Description

name

The name of the progress bar object.

Returns

This function does not return a value.
Usage

The cfprogressbar tag creates the HTML markup; at runtime, you use this function to initiate the progress bar
object. On initialization, ColdFusion calls the underlying CFC, which is defined using a bind expression, at specified
intervals. The CFC returns the progress status, which is passed to the underlying Ext progress bar object to update
the progress bar value. The progress status object that the CFC returns must have STATUS and MESSAGE
properties. The STATUS property has a numeric value from 0.0 to 1.0.
#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

2613

Adobe ColdFusion Documentation

ColdFusion.ProgressBar.stop
Description

Stops the underlying progress bar object that is running.
Function syntax

ColdFusion.ProgressBar.stop(name, calloncomplete)

See also

ColdFusion.ProgressBar.getProgressBarObject, ColdFusion.ProgressBar.start
History

ColdFusion 9: Added this function
Parameters

Parameter

Description

name

The name of the progress bar object.

calloncomplete

A Boolean value that specifies whether to call
oncomplete function:
true
false
The default value is true.

Returns

This function does not return a value.
Usage

You call this function to stop the progress bar object.
#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

2614

Adobe ColdFusion Documentation

ColdFusion.ProgressBar.update
Description

Updates attribute values.
Function syntax

ColdFusion.ProgressBar.update(progressBarId,config)

See also

ColdFusion.ProgressBar.hide, ColdFusion.ProgressBar.show
History

ColdFusion 9: Added this function
Parameters

Parameter

Description

progressBarId

Name of the progress bar object. This must be a valid
ColdFusion identifier.

configObject

An object containing configuration parameters, interv
al, duration, and oncomplete.

Returns

This function does not return a value.
Usage

Updates any of the attribute values duration , interval, or oncomplete as shown in the following example:




#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

2615

Adobe ColdFusion Documentation

ColdFusion.ProgressBar.updatestatus
Description

Lets you manually update the status and message of the progress bar.
Function syntax

ColdFusion.ProgressBar.updatestatus(progressBarId, status, message)

See also

ColdFusion.ProgressBar.update, ColdFusion.ProgressBar.reset
History

ColdFusion 9: Added this function
Parameters

Parameter

Description

progressBarId

Name of the progress bar object. This must be a valid
ColdFusion identifier.

message

Text to be displayed in the progress bar.

status

Progress status.

Returns

This function does not return a value.
Usage

This function helps you to manually set the message and status in the progress bar. For instance, in the case of file
upload, you can manually control the progress using this function.The following snippet illustrates how to use the
function:






#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

2616

Adobe ColdFusion Documentation

ColdFusion.RichText.getEditorObject
Description

Returns the FCKEditor instance that underlies an existing textarea control's rich text editor.
Function syntax

object = ColdFusion.RichText.getEditorObject(textareaName)

See also

ColdFusion.ProgressBar.update, ColdFusion.ProgressBar.reset
History

ColdFusion 8 update 1: Added this function
Parameters

Parameter

Description

textareaName

The value of the name attribute of the textarea tag that
specifies a rich text editor.

Returns

An object.
Usage

This function returns an object thet provides access to the operations of the internal FCKEditor.
#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

2617

Adobe ColdFusion Documentation

ColdFusion.RichText.onComplete
Description

When a rich text editor instance completes initializing, ColdFusion calls this function and passes it the FCKEditor
instance that underlies the rich text editor.
Function syntax

ColdFusion.RichText.onComplete(editorInstance)

See also

ColdFusion.ProgressBar.update, ColdFusion.ProgressBar.reset
History

ColdFusion 8 update 1: Added this function
Parameters

Parameter

Description

editorInstance

the FCKEditor instance that underlies the rich text
editor.

Returns

This function does not return a value.
Usage

When a rich text editor instance completes initializing, ColdFusion calls this function and passes it the FCKEditor
instance that underlies the rich text editor. The function can then perform any needed post-initialization operations.
Examples

© 2014 Adobe Systems Incorporated. All rights reserved.

2618

Adobe ColdFusion Documentation












#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

2619

Adobe ColdFusion Documentation

ColdFusion.setGlobalErrorHandler
Description

Specifies a function that gets called, in place of the ColdFusion Ajax default error handler, if an error occurs when
using a ColdFusion Ajax feature.
Function syntax

ColdFusion.setGlobalErrorHandler(functionName)

History

ColdFusion 8: Added this function
Parameters

Parameter

Description

functionName

The name of the JavaScript function to execute when
there is an error in ColdFusion Ajax code, such as a
binding error. This function must take a single
argument, the error message string.

Returns

This function does not return a value.
Usage

If the page that calls this function does not have any ColdFusion AJAX-based controls, use a cfajaximport tag
on the page to ensure that the page includes the JavaScript definition for this function.The global error handler
displays information about errors that occur in ColdFusion Ajax features. The default global error handler displays an
alert with the error message. You can use this function to create a custom global error handler, for example, to
display a custom error window with additional information about your application.
#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

2620

Adobe ColdFusion Documentation

ColdFusion.Slider.disable
Description

Disables the slider control.
Function syntax

ColdFusion.Slider.disable(name)

See also

ColdFusion.Slider.enable, ColdFusion.Slider.getValue, ColdFusion.Slider.getSliderObject,
ColdFusion.Slider.hide, ColdFusion.Slider.show, ColdFusion.Slider.setValue
History

ColdFusion 9: Added this function
Parameters

Parameter

Description

name

Specifies the value of the name attribute in the cfslid
er tag.

Returns

This function does not return any value.
Example

This is an example of the Slider.disable function. Click the Disable Slider
button to disable the slider.










#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

2621

Adobe ColdFusion Documentation

ColdFusion.Slider.enable
Description

Enables the slider control.
Function syntax

ColdFusion.Slider.enable(name)

See also

ColdFusion.Slider.disable, ColdFusion.Slider.getValue, ColdFusion.Slider.getSliderObject
, ColdFusion.Slider.hide, ColdFusion.Slider.show, ColdFusion.Slider.setValue
History

ColdFusion 9: Added this function
Parameters

Parameter

Description

name

Specifies the value of the name attribute in the cfslid
er tag.

Returns

This function does not return any value.
Example

© 2014 Adobe Systems Incorporated. All rights reserved.

2622

Adobe ColdFusion Documentation

This is an example of the Slider.enable function. Click the Enable Slider button
to enable the slider.










#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

2623

Adobe ColdFusion Documentation

ColdFusion.Slider.getSliderObject
Description

Gets the underlying Ext JavaScript slider control.
Function syntax

ColdFusion.Slider.getSliderObject(name)

See also

ColdFusion.Slider.disable, ColdFusion.Slider.enable, ColdFusion.Slider.getValue, ColdFusi
on.Slider.hide, ColdFusion.Slider.show, ColdFusion.Slider.setValue
History

ColdFusion 9: Added this function
Parameters

Parameter

Description

name

Specifies the value of the name attribute in the cfslid
er tag.

Returns

This function returns the underlying Ext JavaScript slider control.
#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

2624

Adobe ColdFusion Documentation

ColdFusion.Slider.getValue
Description

Gets the numeric value of the slider control.
Function syntax

ColdFusion.Slider.getValue(name)

See also

ColdFusion.Slider.disable, ColdFusion.Slider.enable, ColdFusion.Slider.getSliderObject, C
oldFusion.Slider.hide, ColdFusion.Slider.show, ColdFusion.Slider.setValue
History

ColdFusion 9: Added this function
Parameters

Parameter

Description

name

Specifies the value of the name attribute in the cfslid
er tag.

Returns

This function returns a numeric value.
Example

This is an example of the Slider.getvalue function. Click the Get Value button
to get the value of the slider.










© 2014 Adobe Systems Incorporated. All rights reserved.

2625

Adobe ColdFusion Documentation

#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

2626

Adobe ColdFusion Documentation

ColdFusion.Slider.hide
Description

Hides the slider control.
Function syntax

ColdFusion.Slider.hide(name)

See also

ColdFusion.Slider.disable,ColdFusion.Slider.enable, ColdFusion.Slider.getSliderObject, C
oldFusion.Slider.getValue, ColdFusion.Slider.show, ColdFusion.Slider.setValue
History

ColdFusion 9: Added this function
Parameters

Parameter

Description

name

Specifies the value of the name attribute in the cfslid
er tag.

Returns

This function does not return any value.
Example

This is an example of the Slider.hide function. Click the Hide button to hide
the slider.










© 2014 Adobe Systems Incorporated. All rights reserved.

2627

Adobe ColdFusion Documentation

#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

2628

Adobe ColdFusion Documentation

ColdFusion.Slider.setValue
Description

Sets the numeric value of the slider control.
Function syntax

ColdFusion.Slider.setValue(name, newValue)

See also

ColdFusion.Slider.disable, ColdFusion.Slider.enable, ColdFusion.Slider.getSliderObject, C
oldFusion.Slider.getValue, ColdFusion.Slider.hide, ColdFusion.Slider.show
History

ColdFusion 9: Added this function
Parameters

Parameter

Description

name

Specifies the value of the name attribute of the cfmedi
aplayer tag.

newValue

The numeric value of the slider control.

Returns

This function does not return any value.
Example

© 2014 Adobe Systems Incorporated. All rights reserved.

2629

Adobe ColdFusion Documentation

This is an example of the Slider.setValue function. Click the Set Value button
to set the pointer to a new value,150.










#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

2630

Adobe ColdFusion Documentation

ColdFusion.Slider.show
Description

Shows the slider control.
Function syntax

ColdFusion.Slider.show(name)

See also

ColdFusion.Slider.disable, ColdFusion.Slider.enable, ColdFusion.Slider.getSliderObject, C
oldFusion.Slider.getValue, ColdFusion.Slider.hide, ColdFusion.Slider.setValue
History

ColdFusion 9: Added this function
Parameters

Parameter

Description

name

Specifies the value of the name attribute in the cfslid
er tag.

Returns

This function does not return any value.
Example

© 2014 Adobe Systems Incorporated. All rights reserved.

2631

Adobe ColdFusion Documentation

This is an example of the Slider.show function. Click the Show Slider button to
show the slider.










#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

2632

Adobe ColdFusion Documentation

ColdFusion.Tree.getTreeObject
Description

Gets the underlying object for the specified HTML tree.
Function syntax

ColdFusion.Tree.getTreeObject(name)

See also

cftree, cfajaximport, ColdFusion.Tree.refresh, Using HTML trees in Using Ajax form controls and
features in the Developing ColdFusion Applications
History

ColdFusion 8: Added this function
Parameters

Parameter

Description

name

The value of the name attribute of the cftree tag for
which you want the object.

Returns

An object of type YAHOO.widget.TreeView.
Usage

Use this function to get the Yahoo User Interface Library YAHOO.widget.TreeView object that underlies the
HTML cftree control. You can then use the raw object to modify the displayed tree. For documentation on the
objects and how to manage them, see the [Yahoo
toolkit documentation|http://developer.yahoo.com/yui/].
#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

2633

Adobe ColdFusion Documentation

ColdFusion.Tree.refresh
Description

Refreshes an HTML tree and updates it with the latest values of all items.
Function syntax

ColdFusion.Tree.refresh(name)

See also

cftree, cfajaximport, ColdFusion.Tree.getTreeObject, Using HTML trees in Using Ajax form controls
and features in the Developing ColdFusion Applications
History

ColdFusion 8: Added this function
Parameters

Parameter

Description

name

The value of the name attribute of the cftree tag for
which you want the object.

Returns

An object of type YAHOO.widget.TreeView.
Usage

Use this function to manually update the tree. If you populate the tree by using a bind expression, the refresh call
causes the bind expression to be re-evaluated and repopulates the tree root nodes. Use this function any time you
must get the latest data from the server independent of an event that triggers the cftree bind expression, for
example, use this function to periodically refresh a file/folder tree to represent the status of the server.
#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

2634

Adobe ColdFusion Documentation

ColdFusion.Window.create
Description

Creates a ColdFusion pop-up window. This function is equivalent to the cfwindow tag.
Function syntax

ColdFusion.Window.create(name, title, URL [, configuration])

See also

cfwindow, ColdFusion.Window.getWindowObject, ColdFusion.Window.hide, ColdFusion.Window.o
nHide, ColdFusion.Window.onShow, ColdFusion.Window.show, ColdFusion.Tree.getTreeObject, Us
ing pop-up windows in Using Ajax form controls and features in the Developing ColdFusion Applications
History

ColdFusion 8: Added this function
Parameters

Parameter

Description

name

The name of the window. This attribute is required to
interact with the window, including to dynamically show
or hide it. If a window with the specified name exists,
the function shows that window, and ignores the
remaining parameters; otherwise, the name must be
unique on the page.

title

The text to display on the window title bar. You can use
HTML mark-up to control the title appearance.

URL

The URL from which to get the window body contents.
This attribute can use URL parameters to pass data to
the page. ColdFusion uses standard page path
resolution rules to locate the page.Note: If the page
specified in this attribute contains tags that use
ColdFusion Ajax features, such as the cfform, cfgri
d, and cfpod tags, identify the tags in a cfajaximpo
rt tag on the page that includes this function. For more
information, see cfajaximport.

configuration

An object containing window configuration parameters.
For details, see "Usage".

refreshonshow

The default value is false.

Returns

© 2014 Adobe Systems Incorporated. All rights reserved.

2635

Adobe ColdFusion Documentation

This function does not return a value.
Usage

This function is equivalent to the cfwindow tag. If you do not also use a cfwindow tag on a page that calls this
function, specify a cfajaximport tag on the page and specify cfwindow in the tags attribute. Doing so ensures
that the page includes the necessary JavaScript to create the window. For example, use the following line if you do
not have to import the JavaScript for any other ColdFusion Ajax features.:



The configuration parameter defines the window characteristics; it can have any or all the following entries:
Entry

Default

callbackhandler

center

Description
A function that is called when the
window body loads. This function
must not take any arguments.

false

A Boolean value that specifies
whether to center the window over
the browser window.
If true, ColdFusion ignores the x
and y attribute values.
If false, and you do not specify
x and y attributes, ColdFusion
centers the window.

closable

true

A Boolean value that specifies
whether the user can close the
window. If true, the window has an
X close icon.

draggable

true

A Boolean value that specifies
whether the user can drag the
window. To drag the window, click
the mouse on the title bar and hold
the button down while dragging. If
the window does not have a title,
users cannot drag it.

© 2014 Adobe Systems Incorporated. All rights reserved.

2636

Adobe ColdFusion Documentation

errorHandler

A function that is called if an error
occurs in loading the window body.
This function must take two
arguments:
The HTTP status code, or -1 if
the error is not an HTTP error
An error message

height

300

Height of the window in pixels. If
you specify a value greater than the
available space, the window
occupies the available space and
the resize handles do not appear.

initshow

false

A Boolean value that specifies
whether to display the window when
the containing page first displays. If
this value is false, use the ColdF
usion.Window.show JavaScript
function to display the window.

minheight

0

The minimum height, in pixels, to
which users can resize the
window.Specifying this parameter
and a resizable="false" para
meter causes an error.

minwidth

0

The minimum width, in pixels, to
which users can resize the
window.Specifying this parameter
and a resizable="false" para
meter causes an error.

modal

false

A Boolean value that specifies
whether the window is modal, that
is, whether the user can interact
with the main window while this
window is displaying. If true, the
user cannot interact with the main
window.

resizable

true

A Boolean value that specifies
whether the user can resize the
window.

© 2014 Adobe Systems Incorporated. All rights reserved.

2637

Adobe ColdFusion Documentation

width

500

Width of the window in pixels. If you
specify a value greater than the
available space, the window
occupies the available space and
the resize handles do not appear.

x

The X (horizontal) coordinate of the
upper-left corner of the window,
relative to the browser window.
ColdFusion ignores this attribute if
the center attribute value is true,
and if you do not set the y attribute
value.

y

The Y (vertical) coordinate of the
upper-left corner of the window,
relative to the browser
window.ColdFusion ignores this
attribute if the center attribute
value is true, and if you do not set
the x attribute value.

Note
Entry names in the configuration object must be all-lowercase.

Example

The following minimal CFML application creates a window and gets the window contents from the hello1.cfm file.






The hello1.cfm file can be as simple as the following line:

Hello from hello1.cfm

#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

2638

Adobe ColdFusion Documentation

ColdFusion.Window.destroy
Description

Destroys a window instance
Function syntax

ColdFusion.Window.destroy(windowName[, destroyElement])

See also

cfwindow, ColdFusion.Window.create, ColdFusion.Window.getWindowObject, ColdFusion.Window
.onHide, ColdFusion.Window.onShow, ColdFusion.Window.show, ColdFusion.Tree.getTreeObject,
Using pop-up windows in Using Ajax form controls and features in the Developing ColdFusion Applications
History

ColdFusion 8 update 1: Added this function
Parameters

Parameter

Description

windowName

The name of the window to destroy

destroyElement

A Boolean value specifying whether the HTML element
associated with the window should also be destroyed.
The default value is false.

Returns

This function does not return a value.
Usage

Use this function to destroy a window instance. ---#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

2639

Adobe ColdFusion Documentation

ColdFusion.Window.getWindowObject
Description

Gets the underlying object for the specified window.
Function syntax

ColdFusion.Window.getWindowObject(name)

See also

cfwindow, ColdFusion.Window.create, ColdFusion.Window.onHide, ColdFusion.Window.onShow, Co
ldFusion.Window.show, ColdFusion.Tree.getTreeObject, Using pop-up windows in Using Ajax form
controls and features in the Developing ColdFusion Applications
History

ColdFusion 8: Added this function
Parameters

Parameter

Description

name

The value of the name attribute of the cfwindow tag
for which you want the object.

Returns

An object of type Ext.BasicDialog.
Usage

Use this function to get the Ext JavaScript Library Ext.BasicDialog object that underlies the HTML cfwindow co
ntrol. You can then use the raw object to modify the displayed window. For documentation on the objects and how to
manage them, see the [Ext
JavaScript library documentation|http://extjs.com/deploy/ext-1.1.1/docs/].
#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

2640

Adobe ColdFusion Documentation

ColdFusion.Window.hide
Description

Hides a window that is currently displayed.
Function syntax

ColdFusion.Window.hide(name)

See also

cfwindow, ColdFusion.Window.create, ColdFusion.Window.getWindowObject, ColdFusion.Window
.onHide, ColdFusion.Window.onShow, ColdFusion.Window.show, ColdFusion.Tree.getTreeObject,
Using pop-up windows in Using Ajax form controls and features in the Developing ColdFusion Applications
History

ColdFusion 8: Added this function
Parameters

Parameter

Description

name

The name attribute of the window to hide.

Returns

This function does not return a value.
Usage

This tag has no effect if the window is already hidden.
Example

The following code lets you show and hide a window by clicking buttons:

© 2014 Adobe Systems Incorporated. All rights reserved.

2641

Adobe ColdFusion Documentation






Window contents








#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

2642

Adobe ColdFusion Documentation

ColdFusion.Window.onHide
Description

Specifies a function to run each time a specific window hides.
Function syntax

ColdFusion.Window.onHide(windowName, handler)

See also

cfwindow, ColdFusion.Window.create, ColdFusion.Window.getWindowObject, ColdFusion.Window
.hide, ColdFusion.Window.onShow, ColdFusion.Window.show, ColdFusion.Tree.getTreeObject, Us
ing pop-up windows in Using Ajax form controls and features in the Developing ColdFusion Applications
History

ColdFusion 8: Added this function
Parameters

Parameter

Description

windowName

The name of the window. The handler function runs
whenever this window hides.

handler

The JavaScript function to run when the window hides.

Returns

This function does not return a value.
Usage

The function specified in the handler parameter can optionally take one parameter, which contains the window
name.
Example

The following example uses the ColdFusion.Window.onHide function to display an alert with information about
the window when you click a button that hides the window:

© 2014 Adobe Systems Incorporated. All rights reserved.

2643

Adobe ColdFusion Documentation






Window contents







#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

2644

Adobe ColdFusion Documentation

ColdFusion.Window.onShow
Description

Specifies a function to run each time a specific window shows, including when you create a window and specify an i
nitShow attribute or configuration entry value of true.
Function syntax

ColdFusion.Window.onShow(windowName, handler)

See also

cfwindow, ColdFusion.Window.create, ColdFusion.Window.getWindowObject, ColdFusion.Window
.onHide, ColdFusion.Window.hide, ColdFusion.Window.show, ColdFusion.Tree.getTreeObject, Us
ing pop-up windows in Using Ajax form controls and features in the Developing ColdFusion Applications
History

ColdFusion 8: Added this function
Parameters

Parameter

Description

windowName

The name of the window. The handler function runs
whenever this window shows.

handler

The JavaScript function to run when the window shows.

Returns

This function does not return a value.
Usage

The function specified in the handler parameter can optionally take one parameter, which contains the window
name.One use for this function is to fetch window data only when the window shows. You could use a cfajaxprox
y tag to create a JavaScript proxy for a CFC function that provides the data, and then a ColdFusion.Window.onS
how function to specify a function that calls the proxy function and updates the window contents with the new data.
Example

The following example uses the ColdFusion.Window.onShow function to display an alert with information about the
window when you click a button that shows the window:

© 2014 Adobe Systems Incorporated. All rights reserved.

2645

Adobe ColdFusion Documentation







Window contents







#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

2646

Adobe ColdFusion Documentation

ColdFusion.Window.show
Description

Shows a window that is currently hidden.
Function syntax

ColdFusion.Window.show(name)

See also

cfwindow, ColdFusion.Window.create, ColdFusion.Window.getWindowObject, ColdFusion.Window
.hide, ColdFusion.Window.onHide, ColdFusion.Window.onShow, ColdFusion.Tree.getTreeObject,
Using pop-up windows in Using Ajax form controls and features in the Developing ColdFusion Applications
History

ColdFusion 8: Added this function
Parameters

Parameter

Description

name

The name attribute of the window to show.

Returns

This function does not return a value.
Usage

This function shows a window that you created with an initShow attribute or parameter value of false, or that you
hid by calling the ColdFusion.Window.hide function. It does not show a window that a user closed by clicking
the X icon on the title bar.This function has no effect if the window is already shown.
Example

See the example at ColdFusion.Window.hide
#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

2647

Adobe ColdFusion Documentation

JavaScriptFunctionsinColdFusion9Update1
The following are the Ajax JavaScript functions added in this release:
ColdFusion.Autosuggest.getAutosuggestObject
Description

Lets you access underlying YUI AutoComplete object thereby providing fine-grained control over the object, for
example attaching an event.
Returns

The underlying AutoComplete object.
Function syntax

ColdFusion.Autosuggest.getAutosuggestObject (Id)
Parameters

Id: Name of the auto-suggest object.
Example

© 2014 Adobe Systems Incorporated. All rights reserved.

2648

Adobe ColdFusion Documentation








Attaching an event handler to the autosuggest object

State:







ColdFusion.Layout.disableSourceBind
Description

Disables the source bind.
Function syntax

ColdFusion.Layout.disableSourceBind(Id)
Parameters

Id: Name of the layout area.

© 2014 Adobe Systems Incorporated. All rights reserved.

2649

Adobe ColdFusion Documentation

Usage

Assume that you are using Coldfusion.navigate to populate content into tab or accordion panels. You can
have instances where content comes from the source bind call if the source attribute is defined for cflayoutarea
(and is not from ColdFusion.navigate).In such instances, you might disable the source bind to get content using
Coldfusion.navigate.
Example

layout.cfm uses the templates Tab1_Src.cfm, Tab2_Src.cfm, and Tab3_Src.cfm. If you run layout.cfm, you notice
that clicking
navigate populates content of tab2_src.cfm instead of navigate.cfm
Disable Source bind ensures that the content of navigate.cfm is populated in tab2_src
Enable Source Bind and then clicking tab2_src would again populate the content of tab2_src
Tab1_Src.cfm





Tab2_Src.cfm





Tab3_Src.cfm





Tab4_Src.cfm__





layout.cfm

© 2014 Adobe Systems Incorporated. All rights reserved.

2650

Adobe ColdFusion Documentation













ColdFusion.Layout.enableSourceBind
Description

If disabled, enables the source bind.

© 2014 Adobe Systems Incorporated. All rights reserved.

2651

Adobe ColdFusion Documentation

Function syntax

ColdFusion.Layout.enableSourceBind(Id)
Parameters

Id: Name of the layout area.
Usage

See usage in ColdFusion.Layout.disableSourceBind.
Example

See example in ColdFusion.Layout.disableSourceBind.
ColdFusion.FileUpload.getSelectedFiles
Description

Returns an array of objects containing the filename and size of the files selected for upload. The file size is returned
in bytes. The function also returns file upload status as YES|NO|Error.
Function syntax

ColdFusion.FileUpload.getSelectedFiles(Id)
Parameters

Id: Name of the cffileupload control.
Usage

In a real life scenario, you normally use the uploader with other controls. For example, a form with three fields:
name, email, and uploader. Assume that you upload the files, but forget to click Submit or you select the files,
submit the form, but forget to click Upload. You can use this function to inform the user that there are files that have
been selected for upload and provide the following details:
FILENAME: Name of the file selected for upload.
SIZE: Size of the file in bytes.
STATUS: YES|NO|Error; YES indicates a successful upload, NO indicates that the upload is yet to occur,
and Error indicates that an exception has occurred during the upload operation.
Example

The following example illustrates a scenario where the user clicks Submit and is informed about the files selected for
upload:

© 2014 Adobe Systems Incorporated. All rights reserved.

2652

Adobe ColdFusion Documentation









First Name: 

Last Name: 










Coldfusion.fileUpload.setUrl
Description

Used to set URL for the fileupload control dynamically.
Returns

Nothing
Function syntax

© 2014 Adobe Systems Incorporated. All rights reserved.

2653

Adobe ColdFusion Documentation

ColdFusion.fileUpload.setUrl(id, url)
Parameters

Id: Name of upload control.
Url: URL can be an absolute URL, relative URL, or fully qualified URL.
Example











ColdFusion.grid.getSelectedRows

© 2014 Adobe Systems Incorporated. All rights reserved.

2654

Adobe ColdFusion Documentation

Description

Used to fetch data for the selected rows in the grid.
Returns

An array of objects that contains row data.
Function syntax

ColdFusion.grid.getSelectedRows(id)
Parameters

Id: Name of the grid defined using cfgrid.
See also

FileUpload
Usage

See the example in ColdFusion.grid.clearSelectedRows.
Example

See the example in ColdFusion.grid.clearSelectedRows.
ColdFusion.grid.clearSelectedRows
Description

Used to clear the selected rows in the grid.
Returns

Nothing
Function syntax

ColdFusion.grid.clearSelectedRows(id)
Parameters

Id: Name of the grid defined using cfgrid.
Usage

See the following example.
Example

Employee.cfm























© 2014 Adobe Systems Incorporated. All rights reserved.

2656

Adobe ColdFusion Documentation




Employee.cfc



empQuery = new query(name="emps", datasource="cfdocexamples");
remote any function
getEmployees(page,pageSize,gridsortcolumn="EMP_ID",gridsortdirection="ASC",empName)
{
var orderBy = "EMP_ID";
var mysql = "SELECT Emp_ID, FirstName, LastName, EMail, Department, Email
FROM Employees";
if(isdefined("arguments.empName") and trim(arguments.empName) neq ""){
mysql = mysql & " WHERE " & "firstname = '#arguments.empName#'";
}
if(arguments.gridsortcolumn eq ""){
mysql = mysql & " ORDER BY " & orderBy;
}
mysql = mysql & " " & gridsortdirection;
return QueryConvertForGrid(empQuery.execute(sql=mysql).getResult(), page,
pageSize);
}
remote void function editEmployees(gridaction,gridrow,gridchanged)
{
switch(gridaction)
{
case "I":
{
var eFName = gridrow["FIRSTNAME"];
var eLNAme = gridrow["LASTNAME"];
var eDept = gridrow["DEPARTMENT"];
var eEmail = gridrow["EMAIL"];
var insertSql = "insert into Employees(FirstName,LastName,Department,Email)
values (" & "'" & eFName & "', '" & eLName & "', '" & eDept & "', '" & eEmail &
"')";
empQuery.execute(sql=insertSql);
break;
}
case "U":
{
var empId = gridrow["EMP_ID"];
var changedCol = structkeylist(gridchanged);
var updateSql = "UPDATE Employees SET " & changedCol & "='" &
gridchanged[changedCol] & "' WHERE emp_id=" & empId;
empQuery.execute(sql=updateSql);
break;
}
case "D":
{
deleteEmployees(gridrow);
}
}
}
remote void function deleteEmployees(empdata)

© 2014 Adobe Systems Incorporated. All rights reserved.

2657

Adobe ColdFusion Documentation

{
var i = 1;
var emp = {};
if(isArray(empdata) and not ArrayIsEmpty(empdata)){
for(emp in empdata){
if(isStruct(emp) and structkeyexists(emp,"emp_id")){
empid = emp["emp_id"];
writelog("deleting " & empid);
//var deleteSql = "delete from Employees where emp_id=" & empid;
//empQuery.execute(sql=deleteSql);
}
}
}
}

© 2014 Adobe Systems Incorporated. All rights reserved.

2658

Adobe ColdFusion Documentation




In this example, setting multirowselect=true enables performing of batch operations on grid data, such as
deleting multiple records.In the deleteemployees functions, two lines have been commented out to prevent
accidental deletion of data (since it is a batch operation). To see deletion, uncomment the code.The form has a del
eteAllSelectedRows button that illustrates how records can be deleted externally. That is, without using the
delete button built in to the grid. The same approach can be used to perform other batch operations such as moving
multiple files to another folder or batch updates.
Note
Set the httpMethod to POST on the Proxy object carefully to avoid "request URI too large"
errors as shown in the deleteAllSelectedRows method in Employee.cfm.

ColdFusion.Map.show
Description

Shows the map if it is hidden.
Function syntax

ColdFusion.Map.show(Id)
Parameters

Id: Name of the map.
Example

© 2014 Adobe Systems Incorporated. All rights reserved.

2659

Adobe ColdFusion Documentation


Show Map | Hide Map


ColdFusion.Map.hide
Description

If displayed, hides the map.
Function syntax

ColdFusion.Map.hide(Id)
Parameters

Id: Name of the map.
Example

See example in ColdFusion.Map.show
ColdFusion.Map.refresh
Description

Reloads the map.
Function syntax

ColdFusion.Map.refresh (Id)
Parameters

Id: Name of the map.

© 2014 Adobe Systems Incorporated. All rights reserved.

2660

Adobe ColdFusion Documentation

Usage

If the map is embedded within spry collapsible panels or divs that are hidden on display, that is the map container is
displayed while the actual map is hidden, use this function to force the map to display.
Example




SHOW MAP







ColdFusion.Grid.getTopToolbar
Description

Gets the top toolbar that can be used to add a control, for example icon or button.
Function syntax

ColdFusion.getTopToolbar(Id)
Parameters

Id: Name of the grid.
Example

© 2014 Adobe Systems Incorporated. All rights reserved.

2661

Adobe ColdFusion Documentation

See example in ColdFusion.Grid.refreshBottomToolbar.
ColdFusion.Grid.getBottomToolbar
Description

Gets bottom toolbar that can be used to add a control, for example icon or button.
Function syntax

ColdFusion.Grid.getBottomToolbar(Id)
Parameters

Id: Name of the grid.
Example

See example in ColdFusion.Grid.refreshBottomToolbar.
ColdFusion.Grid.showTopToolbar
Description

Displays the top toolbar that can be used to add a control, for example icon or button.
Function syntax

ColdFusion.Grid.showTopToolbar(Id)
Parameters

Id: Name of the grid.
Example

See example in ColdFusion.Grid.refreshBottomToolbar.
ColdFusion.Grid.hideTopToolbar
Description

Hides the top toolbar that can be used to add a control, for example icon or button.
Function syntax

ColdFusion.Grid.hideTopToolbar(Id)
Parameters

Id: Name of the grid.
Example

See example in ColdFusion.Grid.refreshBottomToolbar.
ColdFusion.Grid.showBottomToolbar

© 2014 Adobe Systems Incorporated. All rights reserved.

2662

Adobe ColdFusion Documentation

Description

Shows bottom toolbar that can be used to add a control, for example icon or button.
Function syntax

ColdFusion.Grid.showBottomToolbar(Id)
Parameters

Id: Name of the grid.
Example

See example in ColdFusion.Grid.refreshBottomToolbar.
ColdFusion.Grid.hideBottomToolbar
Description

Hides the bottom toolbar that can be used to add a control, for example icon or button.
Function syntax

ColdFusion.Grid.hideBottomToolbar(Id)
Parameters

Id: Name of the grid.
Example

See example in ColdFusion.Grid.refreshBottomToolbar.
ColdFusion.Grid.refreshTopToolbar
Description

Refreshes the top toolbar that can be used to add a control, for example icon or button. This function internally calls
the JavaScript function ColdFusion.Grid.showTopToolbar.
Function syntax

ColdFusion.Grid.refreshTopToolbar(Id)
Parameters

Id: Name of the grid.
Example

See example in ColdFusion.Grid.refreshBottomToolbar.
ColdFusion.Grid.refreshBottomToolbar
Description

Refreshes the bottom toolbar that can be used to add a control, for example icon or button. This function internally

© 2014 Adobe Systems Incorporated. All rights reserved.

2663

Adobe ColdFusion Documentation

calls the JavaScript function ColdFusion.Grid.showBottomToolbar.
Function syntax

ColdFusion.Grid.refresheBottomToolbar(Id)
Parameters

Id: Name of the grid control.
Example

grid.cfc



remote any function
getEmployees(page,pageSize,gridsortcolumn="EMP_ID",gridsortdirection="ASC"){
var startRow = (page-1)*pageSize;
var endRow = page*pageSize;
if(!isdefined("arguments.gridsortcolumn") or
isdefined("arguments.gridsortcolumn") and trim(arguments.gridsortcolumn) eq "")
gridsortcolumn = "EMP_ID";
if(!isdefined("arguments.gridsortdirection") or
isdefined("arguments.gridsortdirection") and arguments.gridsortdirection eq "")
gridsortdirection = "ASC";
var mysql = "SELECT Emp_ID, FirstName, EMail, Department FROM
Employees";
if(isdefined("arguments.gridsortcolumn") and
arguments.gridsortcolumn neq "")
mysql = mysql & " ORDER BY " & gridsortcolumn;
if(isdefined("arguments.gridsortdirection") and
arguments.gridsortdirection neq "")
mysql = mysql & " " & gridsortdirection ;
rs1 = new query(name="team", datasource="cfdocexamples",
sql=mysql).execute();
return QueryConvertForGrid(rs1.getResult(), page, pageSize);
}

remote any function editEmployees(gridaction,gridrow,gridchanged){
writelog("edit employee info");
}



grid.cfm



























ColdFusion.Autosuggest.getAutosuggestObject
Description
Returns
Function syntax
Parameters
Example
ColdFusion.Layout.disableSourceBind
Description
Function syntax
Parameters
Usage
Example
ColdFusion.Layout.enableSourceBind
Description
Function syntax
Parameters
Usage
Example
ColdFusion.FileUpload.getSelectedFiles
Description
Function syntax
Parameters
Usage
Example
Coldfusion.fileUpload.setUrl
Description
Returns
Function syntax
Parameters
Example
ColdFusion.grid.getSelectedRows
Description
Returns
Function syntax
Parameters
See also
Usage
Example
ColdFusion.grid.clearSelectedRows
Description
Returns
Function syntax
Parameters
Usage
Example

© 2014 Adobe Systems Incorporated. All rights reserved.

2667

Adobe ColdFusion Documentation

ColdFusion.Map.show
Description
Function syntax
Parameters
Example
ColdFusion.Map.hide
Description
Function syntax
Parameters
Example
ColdFusion.Map.refresh
Description
Function syntax
Parameters
Usage
Example
ColdFusion.Grid.getTopToolbar
Description
Function syntax
Parameters
Example
ColdFusion.Grid.getBottomToolbar
Description
Function syntax
Parameters
Example
ColdFusion.Grid.showTopToolbar
Description
Function syntax
Parameters
Example
ColdFusion.Grid.hideTopToolbar
Description
Function syntax
Parameters
Example
ColdFusion.Grid.showBottomToolbar
Description
Function syntax
Parameters
Example
ColdFusion.Grid.hideBottomToolbar
Description
Function syntax
Parameters
Example
ColdFusion.Grid.refreshTopToolbar

© 2014 Adobe Systems Incorporated. All rights reserved.

2668

Adobe ColdFusion Documentation

Description
Function syntax
Parameters
Example
ColdFusion.Grid.refreshBottomToolbar
Description
Function syntax
Parameters
Example

© 2014 Adobe Systems Incorporated. All rights reserved.

2669

Adobe ColdFusion Documentation

Script Functions Implemented as CFCs
Script functions were added in ColdFusion 9. They are implemented as ColdFusion Components. These functions
extend the usage of the tags cfmail, cfpdf, cfquery, cfhttp, cfstoredproc, and cfftp to CFScript.
Accessing the functions
Function summary
ftp
http
mail
pdf
query
storedproc
Script functions implemented as CFCs in ColdFusion 9 Update 1

#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

2670

Adobe ColdFusion Documentation

Accessing the functions
Script functions are available in the following location: cf_root\CustomTags\com\adobe\coldfusion.
Ensure that you do not delete the default custom tag mapping listed in the ColdFusion Administrator (Extensions >
Custom Tag Paths > Custom tag mappings).
Script functions work if they are either in the default location or web root. If you have the functions in any other
location, add a /com mapping in the ColdFusion Administrator that points to the new location (for example C:\com).
Note
Values of the attributes set in a service action, for example, mail.send(body="test mail")
are transient in nature. They are not accessible after the action completes. Accessing the
attributes using implicit getters results in error whereas any attributes set using either implicit
setters or the init method call are retained and can be accessed using implicit getters.

#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

2671

Adobe ColdFusion Documentation

Function summary
The following table lists the script functions and the equivalent ColdFusion tag.
Function

Equivalent ColdFusion Tag

ftp

cfftp

http

cfhttp

mail

cfmail

pdf

cfpdf

query

cfquery

storedproc

cfstoredproc

#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

2672

Adobe ColdFusion Documentation

ftp
Description
Used to implement File Transfer Protocol (FTP) operations using CFScript.
Syntax
Mode

Syntax

Creating the service

new ftp() or createObject("component","ftp
")

Initializing the attributes

Any one of the following:
ftpService=new ftp(attribute-value pair
)
ftpService.setAttributes(_attribute-val
ue pair_)
ftpService.setA_ttributeName_(attribute
_value)
ftpService.action_method(attribute-valu
e_pair)

Executing the service action

ftpService.action_method(attribute-value
_pair)

Properties
actionparam

buffersize

connection

passive

password

port

proxyserver

retrycount

server

stoponerror

timeout

username

fingerprint

key

passphrase

secure

ASCIIExtensionList

directory

existing

failifexists

item

localfile

name

new

remotefile

result

transfermode

allosize

All attributes supported by the tag cfftp can be used as attribute-value pairs. For example,



© 2014 Adobe Systems Incorporated. All rights reserved.

2673

Adobe ColdFusion Documentation

can be used as

ftpService.setUserName("myUserName");

For details, see the Attributes section for the cfftp tag.
See also
cfftp, Function summary
History
ColdFusion 9: Added this function.
Methods
The following FTP actions are available as methods. All methods have similar arguments and syntax.
open

close

quote

site

allo

acct

changeDir

createDir

listDir

removeDir

getFile

putFile

rename

remove

getCurrentDir

getCurrentUrl

existDir

existsFile

exists

Description

All methods correspond to the FTP actions
supported by the tag cfftp. For details of each
method, refer to the relevant section for the tag cff
tp.

Returns

All methods return a component with the following
properties set:

prefix: Equivalent to the result attribute or cfftp scope
result: Applicable only for action="listdir"
Syntax

ftpService.methodName(attribute-value
pair)

Arguments

All attributes supported by the tag cfftp.

setAttributes
Description

© 2014 Adobe Systems Incorporated. All rights reserved.

Sets attributes for the ftp function.

2674

Adobe ColdFusion Documentation

Returns

Nothing

Syntax

ftpService.setAttributes (attribute-va
lue pair)

Arguments

All attributes supported by the tag cfftp.

getAttributes
Description

Gets the attributes that were set for the ftp functio
n.

Returns

Returns a struct with all or some attribute values.

Syntax

ftpService.get_Attributes_ (attributel
ist)

Arguments

A comma-separated list of attributes. If no list is
specified, all defined attributes are returned.

clear
Description

Removes all attributes added for the ftp function.

Returns

Nothing

Syntax

ftpService.clear()

Arguments

None

Usage
This function corresponds to the cfftp tag. For details, see the Usage section for the tag cfftp.
Example

© 2014 Adobe Systems Incorporated. All rights reserved.

2675

Adobe ColdFusion Documentation


/* Create a new ftp Service*/
ftpService = new ftp();
/* Set attributes using implicit setters */
ftpService.setUsername("myUsername");
ftpService.setPassword("myPassword");
ftpService.setServer("myFtpServer");
ftpService.setStopOnError("true");
ftpService.setConnection("conn");
/* Open connection to ftp server */
WriteOutput("
Open a connection
");
result = ftpService.open();
WriteOutput("
Did it succeed? " & result.getPrefix().succeeded & "
");
/* Get current directory */
WriteOutput("
Get current directory
");
result = ftpService.getcurrentdir();
WriteOutput("
Current Directory: " & "'" & result.getPrefix().returnvalue & "'" &
"
");
/* List contents of the current directory */
WriteOutput("
List directory contents
");
result = ftpService.listdir(directory = "/",name="listDirs");
displayListing(result.getResult());
/* Move a file to the ftp server */
WriteOutput("
Move File to Remote Server
");
lFile = "C:\temp\artifacts.xml";
rFile = "artifacts.xml";
result = ftpService.putFile(transferMode="binary", localfile=lFile,
remoteFile=rFile);
WriteOutput("
Did it succeed? " & result.getPrefix().succeeded & "
");
/* Close connection to the ftp server */
WriteOutput("
Close the connection
");
ftpService.close(connection="conn");
WriteOutput("
Did it succeed? " & result.getPrefix().succeeded & "
");













#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

2676

Adobe ColdFusion Documentation

http
Description
Used in CFScript to generate an HTTP request and handle the response from the server.
Syntax
Mode

Syntax

Creating the service

new http() or createObject("component","ht
tp")

Initializing the attributes

Any one of the following:
httpService=new http(_attribute-value_p
air_)
httpService.setAttributes(_attribute-va
lue_pair_)
httpService.set_AttributeName_(attribut
e_value)
httpService.send(attribute-value_pair)

Executing the service action

httpService.send(_attribute-value_pair_)

Properties
url

charset

clientcert

clientcertpassword

columns

delimiter

file

firstrowasheaders

getasbinary

method

multipart

multiparttype

name

password

path

port

proxyserver

proxyport

proxyuser

proxypassword

redirect

resolveurl

result

textqualifier

throwonerror

timeout

useragent

username

All attributes supported by the tag cfhttp can be used as attribute-value pairs. For example,



can be used as

© 2014 Adobe Systems Incorporated. All rights reserved.

2677

Adobe ColdFusion Documentation

httpService.setName("onerow");

For details of the attributes, see the Attributes section for the tag cfhttp.
See also
cfhttp__, Function summary
History
ColdFusion 9: Added this function.
Methods
addParam
Description

Used to add cfhttpparam tags. For example, to
specify http POST operations in CFScript. Specifies
parameters to build an HTTP request.

Syntax

httpService.addParam(attribute-value
pair)

Returns

Nothing

Arguments

All attributes supported by cfhttpparam tag can
be used as attribute-value pairs.

send
Description

Used to generate an HTTP request and handle the
response from the server.

Returns

A component on which the following methods can
be invoked:

GetResult(): To access the query object returned by the server if a name attribute is specified.
GetPrefix(): To access the cfhttp scope. This is equivalent to the result attribute of the cfhttptag.
Syntax

httpService.send(attribute_value pair)

Arguments

All attributes supported by the cfhttpparam tag.

setAttributes
Description

© 2014 Adobe Systems Incorporated. All rights reserved.

Sets attributes for the http function.

2678

Adobe ColdFusion Documentation

Returns

Nothing

Syntax

httpService.setAttributes (attribute-v
alue pair)

Arguments

All arguments supported by the cfhttp tag.

getAttributes
Description

Gets attributes that were set for the http function.

Returns

Returns a struct with all or some of the service tag
attribute values.

Syntax

httpService.get_Attributes_(attribute_
list)

Arguments

A comma-separated list of attributes. If no list is
specified, all defined attributes are returned.

clearAttributes
Description

Removes all attributes added for the http function.

Returns

Nothing

Syntax

httpService.clearAttributes(attribute_
list)

Arguments

A comma-separated list of attributes.

clearParams
Description

Removes cfhttpparam}}tags that were
added using the {{addParam method.

Returns

Nothing

Syntax

httpService.clearParams()

Arguments

None

clear
Description

© 2014 Adobe Systems Incorporated. All rights reserved.

Removes all attributes and cfhttpparam tags that
were added using the addParam method.

2679

Adobe ColdFusion Documentation

Returns

Nothing

Syntax

httpService.clear()

Arguments

None

Usage
This function corresponds to the cfhttp tag. For usage details, see the Usage section for cfhttp in the CFML
Reference.
Example






/* youtube uplaod url */
youTubeUploadURL =
"http://uploads.gdata.youtube.com/feeds/api/users/default/uploads";
/* video to upload */
videoName = ExpandPath('./hello.wmv');
videoFileName = "hello.wmv";
/* set user account data */
clientKey = "enter client key from google";
devKey = "ewnter dev key from google";
/* create new http service */
httpService = new http();
/* set attributes using implicit setters */
httpService.setMethod("post");
httpService.setCharset("utf-8");
httpService.setUrl("https://www.google.com/accounts/ClientLogin");
/* add httpparams using addParam() */
httpService.addParam(type="formfield",name="accountType",value="HOSTED_OR_GOOGLE");
httpService.addParam(type="formfield",name="Email",value="enter gmail id");
httpService.addParam(type="formfield",name="Passwd",value="enter password");
httpService.addParam(type="formfield",name="service",value="youtube");
httpService.addParam(type="formfield",name="source",value="youtubecode");
/* make the http call to the URL using send() */
result = httpService.send().getPrefix();
/* process the filecontent returned */
content = listtoarray(result.filecontent,chr(10));
for(i=1;i lte arraylen(content);i++)
{
item = content[i];
authdata[listFirst(item, "=")] = listRest(item, "=");

© 2014 Adobe Systems Incorporated. All rights reserved.

2680

Adobe ColdFusion Documentation

}






WithOutQuotes
Test Description
People

yourvideo





tmpfile = expandPath("./meta.xml");
FileWrite(tmpfile,trim(meta));
/* use the httpService created above */
httpService.setUrl("http://uploads.gdata.youtube.com/feeds/api/users/default/upload
s");
httpService.setTimeOut(450);
httpService.setMultipartType("related");
/* clear params first */
httpService.clearParams();
/* add httpparams using addParam() */
httpService.addParam(type="header",name="Authorization", value="GoogleLogin
auth=#authdata.auth#");
httpService.addParam(type="header",name="X-GData-Client",
value="#variables.clientkey#");
httpService.addParam(type="header",name="X-GData-Key",
value="key=#variables.devkey#");
httpService.addParam(type="header",name="Slug",value="#videoFileName#");
httpService.addParam(type="file",name="API_XML_Request",file="#tmpfile#",mimetype="
application/atom+xml");
httpService.addParam(type="file",name="file",file="#videoName#",mimetype="video/*")
;
/* make the http call to the URL using send() */
result = httpService.send().getPrefix();
if(result.statuscode contains "201")
{
WriteOutput("Your video has been successfully uploaded to YouTube");
}
else
{
WriteOutput("There was a problem uploading the video. Status code returned was " &
result.statuscode);

© 2014 Adobe Systems Incorporated. All rights reserved.

2681

Adobe ColdFusion Documentation

}


#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

2682

Adobe ColdFusion Documentation

mail
Description
Used to sends an e-mail message, that optionally contains query output, using an SMTP server.
Syntax
Mode

Syntax

Creating the service

new mail() or createObject("component",
"mail")

Initializing the attributes

Any one of the following:
mailService=new mail(_attribute-value_p
air_)
mailService.setAttributes(_attribute-va
lue_pair_)
mailService.set_AttributeName_(attribut
e_value)
mailService.send(attribute-value_pair)

Executing the service action

mailService.send(_attribute-value_pair_)

Properties
from

to

subject

bcc

cc

charset

debug

failto

group

groupcasesensitive

mailerid

maxrows

mimeattach

password

port

priority

query

replyto

server

spoolenable

startrow

timeout

type

username

useSSL

useTLS

wraptext

remove

body

All attributes supported by the tag cfmail can be used as attribute-value pairs. For example,



© 2014 Adobe Systems Incorporated. All rights reserved.

2683

Adobe ColdFusion Documentation

can be used as

mailerService.setFrom(form.mailFrom);

See also
cfmail, Function summary
History
ColdFusion 9: Added this function.
Methods
addParam
Description

Used to add cfmailparam tags. For example, to
attach a file or add a header to an e-mail message.

Syntax

mailService.addParam(attribute-value
pair)

Returns

Nothing

Arguments

All attributes supported by the cfmailparam tag
can be used as attribute-value pairs.

addPart
Description

Used to add cfmailpart tags. For example, one
part of a multipart e-mail message.

Syntax

mailService.addPart(attribute-value
pair)

Returns

Nothing

Arguments

All attributes supported by the cfmailpart tag can
be used as attribute-value pairs.

send
Description

Used to invoke the mail service to send an e-mail
message.

Returns

Nothing

Syntax

mailService.send(attribute-value pair)

© 2014 Adobe Systems Incorporated. All rights reserved.

2684

Adobe ColdFusion Documentation

Arguments

All attributes supported by the cfmail tag.

setAttributes
Description

Sets attributes for the mail function.

Returns

Nothing

Syntax

mailService.setAttributes (attribute-v
alue pair)

Arguments

All attributes supported by the cfmail tag.

getAttributes
Description

Gets attributes that were set for the mail function.

Returns

Returns a struct with all or some of the attribute
values.

Syntax

mailService.get_Attributes_ (attribute
list)

Arguments

A comma-separated list of attributes. If no list is
specified, all defined attributes are returned.

clearAttributes
Description

Removes all attributes added for the mail function.

Returns

Nothing

Syntax

mailService.clearAttributes(attribute_
list)

Arguments

A comma-separated list of attributes.

clearParams
Description

Removes cfmailparam tags that were added
using the addParam method.

Returns

Nothing

Syntax

mailService.clearParams()

Arguments

None

© 2014 Adobe Systems Incorporated. All rights reserved.

2685

Adobe ColdFusion Documentation

clearParts
Description

Removes cfmailpart tags that were added using
the addPart method.

Returns

Nothing

Syntax

mailService.clearProcResults()

Arguments

None

clear
Description

Removes all attributes, cfmailparam tags, and cf
mailpart tags that were added using the methods
addParam and addPart.

Returns

Nothing

Syntax

mailService.clear()

Arguments

None

Usage
This function corresponds to the tag cfmail. For usage details, see the Usage section for cfmail.
Example

Sending mail in cfscript

/* create mailer service */
mailerService = new mail();
if(IsDefined("form.mailto"))
{
if(form.mailto is not "" AND form.mailfrom is not "" AND form.Subject is not ""
and form.attachment is not "")
{
savecontent variable="mailBody"{
WriteOutput("This message was sent by an automatic mailer built with
cfmail:= = = = = = = = = = = = = = = = = = = = = = = = = = =" & "

" &
form.body);
}
/* set mail attributes using implicit setters provided */
mailerService.setTo(form.mailto);
mailerService.setFrom(form.mailFrom);
mailerService.setSubject(form.subject);
mailerService.setType("html");
/* add mailparams */
mailerService.addParam(file=expandpath(form.attachment),type="text/plain",remove=fal

© 2014 Adobe Systems Incorporated. All rights reserved.

2686

Adobe ColdFusion Documentation

se);
/* send mail using send(). Attribute values specified in an end action like
"send" will not persist after the action is performed */
mailerService.send(body=mailBody);
writeoutput("
Thank you
" & "
Thank you, " & mailfrom & "
" & "Your
message, " & subject & ", has been sent to " & mailto & "
");
}
}





TO



FROM



SUBJECT



ATTACHMENT




MESSAGE BODY:











© 2014 Adobe Systems Incorporated. All rights reserved.

2687

Adobe ColdFusion Documentation




#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

2688

Adobe ColdFusion Documentation

pdf
Description
Provides services to manipulate existing PDF documents in CFScript.
Syntax
Mode

Syntax

Creating the service

new pdf()}}or {{createObject("component",
"pdf")

Initializing the attributes

Any one of the following:
pdfService=new pdf(attribute-value pair
)
pdfService.setAttributes(attribute-valu
e pair)
pdfService.set_AttributeName(attribute_
value_)
pdfService.action_method(attribute-valu
e pair)

Executing the service action

pdfService.action_method(attribute-value
pair)

Properties
addQuads

algo

align

ascending

bottomMargin

compressTiffs

copyFrom

ddxfile

destination

directory

encodeAll

encrypt

flatten

foreground

format

height

hires

honourSpaces

hScale

image

imagePrefix

info

inputFiles

isBase64

jpgDpi

keepBookmark

leftMargin

maxBreadth

maxLength

maxScale

name

newOwnerPassword

newUserPassword

noAttachments

noBookmarks

noComments

noJavascripts

noLinks

noMetadata

noThumbnails

© 2014 Adobe Systems Incorporated. All rights reserved.

2689

Adobe ColdFusion Documentation

numberFormat

opacity

order

outputFiles

overridePage

overwrite

package

pages

password

permissions

position

resolution

rightMargin

rotation

saveOption

scale

showOnPrint

source

stopOnError

text

topMargin

transparent

type

useStructure

version

vscale

width

All attributes supported by the tag cfpdf can be used as attribute-value pairs. For example,



can be used as

pdfInfo = pdfService.getPdfInfo(source="myBook.pdf", name="pdfinfo");

For details, see the Attributes section for the cfpdf tag__.
Methods
addParam
Description

Used in CFScript to add cfpdfparam tags.
Applicable only to action="merge".

Returns

Nothing

Syntax

pdfService.addParam(attribute-value
pair)

Arguments

All attributes supported by the cfpdfparam tag can
be used as attribute-value pairs.

The following PDF actions are available as methods. All these methods have similar arguments and syntax.
addWatermark

removeWatermark

deletePages

getPDFInfo

setPDFInfo

merge

processDDX

protect

© 2014 Adobe Systems Incorporated. All rights reserved.

2690

Adobe ColdFusion Documentation

read

write

thumbnail

transform

optimize

extractImage

extractText

addHeader

addFooter

removeHeaderFooter

Note
In the list, setPDFInfo and getPDFInfo do not have identical actions in cfpdf. cfpdf
action="setinfo" and cfpdf action="getinfo" represent them respectively.

Description

All methods correspond to the PDF actions specified
for the tag cfpdf. For details of each method, refer to
the corresponding section for cfpdf.

Returns

Depends on the action. If the name attribute is
specified, the result of the pdf operation is returned.
Else, an empty string. For example, the following code
returns a structure containing the pdf information for "b
ook.pdf":
pdfinfo =
pdfService.getPDFInfo(source="book.pdf",
name="var")}}PDF manipulation is done
using the {{cfpdf tag. This is why, you must
specify the name attribute. Accessing "var" directly
does not work since "var" does not exist in the page
variables scope.

Syntax

serviceName.methodName(attribute-value
pair)

Arguments

All attributes supported by the cfpdf tag for a given
action are supported.

setAttributes
Description

Sets attributes for the pdf function.

Returns

Nothing

Syntax

pdfService.setAttributes (attribute-va
lue pair)

Arguments

All attributes supported by the cfpdf tag.

getAttributes

© 2014 Adobe Systems Incorporated. All rights reserved.

2691

Adobe ColdFusion Documentation

Description

Gets the attributes that were set for the pdf functio
n.

Returns

Returns a struct with all or some of the attribute
values.

Syntax

pdfService.get_Attributes_ (attributel
ist)

Arguments

A comma-separated list of attributes. If no list is
specified, all defined attributes are returned.

clearAttributes
Description

Removes all attributes added for the pdf function.

Returns

Nothing

Syntax

pdfService.clearAttributes(attribute_l
ist)

Arguments

A comma-separated list of attributes that must be
removed.

clearParams
Description

Removes params that were added using addParam
method.

Returns

Nothing

Syntax

pdfService.clearParams()

Arguments

None

clear
Description

Removes all attributes and params added using the
addParam method.

Returns

Nothing

Syntax

pdfService.clear()

Arguments

None

See also

© 2014 Adobe Systems Incorporated. All rights reserved.

2692

Adobe ColdFusion Documentation

cfpdf, Function summary
History
ColdFusion 9: Added this function.
Usage
This function corresponds to the cfpdf tag. For usage details, refer to the Usage section for cfpdf.
Example

PDF Thumbnail

// Create a variable for the name of the PDF document.
mypdf = "book";
thumbnailsDirectory = ExpandPath(".") & "\" & "#mypdf#_thumbnails";
//create new PDF service
pdfService = new pdf();
//set attributes using implicit setters
pdfService.setSource(expandpath('./#mypdf#.pdf'));
//Use the getPdfInfo action to retrieve the total page count for the PDF document.
PDFInfo = pdfService.getPdfInfo(name="pdfinfo");
pageCount = PDFInfo.TotalPages;
WriteOutput("pageCount=" & pageCount);
//Generate a thumbnail image for each page in the PDF source document,
//create a directory (if it does not exist) in the web root that is
//a concatenation of the PDF source name and the word "thumbnails", and
//save the thumbnail images in that directory.
pdfService.thumbnail(destination=thumbnailsDirectory, scale=60, overwrite=true);
//Loop through the images in the thumbnail directory and generate a link
//from each image to the corresponding page in the PDF document.
for(i="1";i lte pageCount;i++)
{
//Click the thumbnail image to navigate to the page in the PDF document.
WriteOutput("");
}
 

can be used as

queryService.setName("myName");

© 2014 Adobe Systems Incorporated. All rights reserved.

2694

Adobe ColdFusion Documentation

See also
cfquery, Function summary
History
ColdFusion 9: Added this function.
Methods
addParam
Description

Used in CFScript to add cfqueryparam tags to:

Verify the data type of a query parameter
For DBMSs that support bind variables, to enable ColdFusion to use bind variables in the SQL statement
Syntax

serviceName.addParam(attribute-value
pair)

Returns

Nothing

Arguments

All attributes supported by cfqueryparam tag can
be used as attribute-value pairs.

execute
Description

Used to execute SQL statements.

Returns

A component with the following properties set:

Result: For SQL queries that return a result set, for example, a "SELECT" SQL query.
Prefix: Equivalent to the result attribute for the cfquerytag.
Syntax

queryService.execute(attribute-value
pair)

Arguments

All attributes supported by the cfquery tag.

setAttributes
Description

Sets attributes for the query function.

Returns

Nothing

Syntax

queryService.setAttributes (attributevalue pair)

Arguments

All attributes supported by the cfquery tag.

© 2014 Adobe Systems Incorporated. All rights reserved.

2695

Adobe ColdFusion Documentation

getAttributes
Description

Gets attributes that were set for the query function.

Returns

Returns a struct with all or some of the attribute
values.

Syntax

queryService.get_Attributes_ (attribut
elist)

Arguments

A comma-separated list of attributes. If no list is
specified, all defined attributes are returned.

clearAttributes
Description

Removes all attributes added for the query functio
n.

Returns

Nothing

Syntax

queryService.clearAttributes(attribute
_list)

Arguments

A comma-separated list of attributes.

clearParams
Description

Removes queryparams that were added using the a
ddParam method.

Returns

Nothing

Syntax

queryService.clearParams()

Arguments

None

clear
Description

Removes all attributes and queryparms that were
added using the addParam method.

Returns

Nothing

Syntax

queryService.clear()

Arguments

None

Usage

© 2014 Adobe Systems Incorporated. All rights reserved.

2696

Adobe ColdFusion Documentation

This function corresponds to the cfquery tag. For usage information, see Usage details for cfquery.
Example


/*
This example shows how to create a query service in cfscript, set/get attributes
using implict setters/getters, and also
how to execute the query and access the resultset
*/
param MaxRows="10";
param StartRow="1";
/*
Query database for information if cached database information has
not been updated in the last six hours; otherwise, use cached data.
*/
/* create a quey service */
queryService = new query();
/* set properties using implict setters */
queryService.setDatasource("cfdocexamples");
queryService.setName("GetParks");
queryService.setcachedwithin(CreateTimeSpan(0, 6, 0, 0));
/* Add sql queryparams using named and positional notation */
queryService.addParam(name="state",value="MD",cfsqltype="cf_sql_varchar");
queryService.addParam(value="National Capital Region",cfsqltype="cf_sql_varchar");
/* invoke execute() on the query object to execute the query and return a component
with properties result and prefix (which can be accessed as implcit getters) */
result = queryService.execute(sql="SELECT PARKNAME, REGION, STATE FROM Parks WHERE
STATE = :state and REGION = ? ORDER BY ParkName, State ");
GetParks = result.getResult();
/* getPrefix() returns information like recordcount,sql etc (typically whatever one
gets if one uses the result attribute of the cfquery tag */
metaInfo = result.getPrefix();


Found #metaInfo.recordcount# records for '#metainfo.sqlparameters[2]#' in the
state '#metainfo.sqlparameters[1]#' 




© 2014 Adobe Systems Incorporated. All rights reserved.

2697

Adobe ColdFusion Documentation




#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

2699

Adobe ColdFusion Documentation

storedproc
Description
Used to execute a stored procedure in a server database using CFScript. It specifies database connection
information and identifies the stored procedure.
Syntax
Mode

Syntax

Creating the service

new storedProc() or createObject("componen
t", "storedproc")

Initializing the attributes

Any one of the following:
storedProcService=new storedproc(attrib
ute-value_pair)
storedprocService.setAttributes(attribu
te-value_pair)
storedProcService.set_AttributeName_(at
tribute_value)
storedProcService.execute(attribute-val
ue_pair)

Executing the service action

storedProcService.execute(_attribute-valu
e_pair_)

Properties
datasource

procedure

debug

cachedafter

cachedwithin

blockfactor

password

result

returncode

username

All attributes supported by the tag cfstoredproc are supported as attribute-value pairs. For example,



can be used as

spService.setProcedure("sp_proc");

For details of the cfstoredproc tag attributes, see the Attributes section for cfstoredproc__.

© 2014 Adobe Systems Incorporated. All rights reserved.

2700

Adobe ColdFusion Documentation

See also
cfstoredproc, Function summary
History
ColdFusion 9: Added this function.
Methods
addParam
Description

Used to add cfprocparam tags.

Syntax

storedprocService.addParam(attribute-v
alue pair)

Returns

Nothing

Arguments

All attributes supported by cfprocparam tag can
be used as attribute-value pairs.

addProcResult
Description

Used to add cfprocresult tags to associate a
query object with a result set returned by a stored
procedure.

Syntax

storedprocService.addProcResult(attrib
ute-value pair)

Returns

Nothing

Arguments

All attributes supported by the cfprocresult tag
can be used as attribute-value pairs.

execute
Description

Used to execute a stored procedure.

Returns

A component on which the following methods can
be invoked:

getProcResultSets(): To access result sets returned by the procedure.
getProcOutVariables(): To access OUT or INOUTvariables returned by the procedure.
Syntax

storedprocService.execute(attribute-val
ue pair)

Arguments

All attributes supported by the cfstoredproc tag.

© 2014 Adobe Systems Incorporated. All rights reserved.

2701

Adobe ColdFusion Documentation

setAttributes
Description

Sets attributes for the storedproc function.

Returns

Nothing

Syntax

storedProcService.setAttributes (attri
bute-value pair)

Arguments

All attributes supported by the cfstoredproc tag.

getAttributes
Description

Gets attributes that were set for the storedproc fu
nction.

Returns

Returns a struct with all or some of the attribute
values.

Syntax

storedProcService.get_Attributes_ (att
ributelist)

Arguments

A comma-separated list of attributes. If no list is
specified, all defined attributes are returned.

clearAttributes
Description

Removes all attributes added for the storedProc f
unction.

Returns

Nothing

Syntax

storedProcService.clearAttributes(attr
ibute_list)

Arguments

A comma-separated list of attributes.

clearParams
Description

Removes cfprocparam tags added using the add
Param method.

Returns

Nothing

Syntax

storedProcService.clearParams()

Arguments

None

© 2014 Adobe Systems Incorporated. All rights reserved.

2702

Adobe ColdFusion Documentation

clearProcResults
Description

Removes cfprocresult tags added using the ad
dProcResults method.

Returns

Nothing

Syntax

storedProcService.clearProcResults()

Arguments

None

clear
Description

Removes all attributes and params that were added
using the methods addProcResults and addPar
am.

Returns

Nothing

Syntax

storedProcService.clear()

Arguments

None

Usage
This function corresponds to the cfstoredproc tag. For usage details, refer to the Usage section for cfstoredproc.
Example

© 2014 Adobe Systems Incorporated. All rights reserved.

2703

Adobe ColdFusion Documentation


//If submitting a new book, insert the record and display confirmation
if(isDefined("form.title"))
{
//create a new storedproc service
spService = new storedproc();
//set attributes using implicit setters
spService.setDatasource("books");
spService.setProcedure("Insert_Book");
//add procparams using addParam
spService.addParam(cfsqltype="cf_sql_varchar", type="in",value=form.title);
spService.addParam(cfsqltype="cf_sql_numeric",type="in",value=form.price);
spService.addParam(cfsqltype="cf_sql_date", type="in",value=form.publishDate);
spService.addParam(cfsqltype="cf_sql_numeric",type="out",variable="bookId");
//add procresults using addProcResult
spService.addProcResult(name="rs1",resultset=1);
//execute the stored procedure
result = spService.execute();
//getprocOutVariables() returns any OUT or INOUT varibles added using addParams()
bookId = result.getprocOutVariables().bookId;
//getProcResultSets() returns resultsets added using addProcresult()
listOfBooks = result.getProcResultSets().rs1;
WriteOutput("
List of Books
");
writeDump(listOfBooks);
//output data
WriteOutput("
" & "'" & form.title & "'" & " inserted into database. The ID is "
& bookId & ".
");
}


Insert a new book



 


Park Name


Region


State




#GetParks.CurrentRow#


#ParkName#


#Region#


#State#








See next #MaxRows# rows


© 2014 Adobe Systems Incorporated. All rights reserved.

2698

Adobe ColdFusion Documentation




Title:



Price:



Publish Date:







#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

2704

Adobe ColdFusion Documentation

Script functions implemented as CFCs in ColdFusion 9 Update 1
Function summary
The following table lists the script functions and the equivalent ColdFusion tag.
Function

Equivalent ColdFusion Tag

dbinfo

cfdbinfo

imap

cfimap

pop

cfpop

ldap

cfldap

feed

cffeed

dbinfo
Description

Used in CFScript to retrieve information about a data source such as database details, tables, queries, procedures,
foreign keys, indexes, and version information about the database, driver, and JDBC.
Syntax

Mode

Syntax

Creating the service

new dbinfo() or createObject("component",
"dbinfo");

Executing the service action

dbinfoService.action_method(attribute-va
lue_pair);

Initializing the attributes

See Initializing the attributes below.

Getting the CFC properties

See Getting the CFC Properties below.

Working with the data returned

data=dbinfoService.action_method(attribut
e-value_pair);writedump(data);

Properties

datasource

dbname

name

pattern

table

username

© 2014 Adobe Systems Incorporated. All rights reserved.

password

2705

Adobe ColdFusion Documentation

All attributes supported by the tag cfdbinfo can be used as attribute-value pairs. For example,



can be used as

dbinfoService.setUserName("myUserName");

For details, see the Attributes section for the cfdbinfo tag.
See also

Function summary
History

ColdFusion 9.0.1: Added this function.
Methods

The following dbinfo types are available as methods. All methods have similar arguments and syntax.
dbnames

tables

columns

procedures

foriegnkeys

index

version

Description

All methods correspond to the type of information
supported by the tag cfdbinfo. For details of each
method, see the relevant section for the tag cfdbin
fo in ColdFusion 9 CFML Reference.

Returns

All methods return a query object.

Syntax

dbinfoService.methodName(attribute-val
ue pair);

Arguments

All attributes supported by the tag cfdbinfo.

setAttributes, getAttributes, clearAttributes, clear, setProperties, getProperties, cle
arProperties, and clearProperties. For details, see Methods common to all functions.
Usage

This function corresponds to the tag cfdbinfo. For details, see the Usage section for the tag cfdbinfo.
Example

© 2014 Adobe Systems Incorporated. All rights reserved.

2706

Adobe ColdFusion Documentation


d = new dbinfo(datasource=" cfartgallery ").dbnames(datasource="ajax");
writedump(d);
d = new dbinfo(datasource=" ajax").dbnames();
writedump(d);


imap
Description

Used in CFScript to query an IMAP server to retrieve and manage mails within multiple folders.
Syntax

Mode

Syntax

Creating the service

new imap(); or createObject("component",
"imap");

Initializing the attributes

See Initializing the attributes below.

Executing the service action

imapService.methodName(_attribute-value_
pair_)

Getting the CFC properties

See Getting the CFC Properties below.

Working with returned data

imapResult=imapService.action_method(_att
ribute-value_pair_);

Properties

attachmentpath

connection

folder

generateuniquefilen
ames

maxrows

messagenumber

name

newfolder

password

port

recurse

secure

server

startrow

stoponerror

timeout

uid

username

All attributes supported by the tag cfimap can be used as attribute-value pairs. For example,

© 2014 Adobe Systems Incorporated. All rights reserved.

2707

Adobe ColdFusion Documentation



can be used as

imapService = new
imap(server="myimapserver",username="myusername",password="mypassword",port="myport"
,secure="yes");
imapService.open();

Note
If connection properties such as server, username, password, port, and secure are specified
either during initialization or when open method is called, a connection is created implicitly.
Therefore, you need not specify the properties for further actions. If sandbox security is turned
on, the directory referred to by the property attachmentPath must be given the required
permission. By default, the temp directory is used.

For details of the attributes, see the Attributes section for the tag cfimap.
See also

Function summary
History

ColdFusion 9.0.1: Added this function.
Methods

The following imap actions are available as methods. All methods have similar arguments and syntax.
getAll

delete

open

close

markRead

createFolder

deleteFolder

renameFolder

listAllFolders

moveMail

getHeaderOnly

Description

All methods correspond to the type of information
supported by the tag cfimap. For details of each
method, see the relevant section of cfimap in the
ColdFusion 9 CFML Reference.

Returns

A query object for methods getAll, getHeaderOn
ly, and listAllFolders. Else, nothing.

© 2014 Adobe Systems Incorporated. All rights reserved.

2708

Adobe ColdFusion Documentation

Syntax

imapService.methodName(attribute-value
pair);

Arguments

All attributes supported by the tag cfimap.

setAttributes, getAttributes, clearAttributes, clear, setProperties, getProperties, an
d clearProperties. For details, see Methods common to all functions.
Usage

This function corresponds to the tag cfimap. See the Usage section for cfimap in the ColdFusion 9 CFML
Reference for details.
Example


m = new imap();
m.setAttributes(server="#REQUEST.server#",username="#REQUEST.username#",
password="#REQUEST.password#",secure="#REQUEST.secure#",
connection="#REQUEST.connectionname#",stoponerror="#REQUEST.stoponerror#");
m.open();
master = m.getAll(connection = "#REQUEST.connectionname#",name = "queryname",
stoponerror = "#REQUEST.stoponerror#" );
writedump(master);


pop
Description

Used in CFScript to retrieve or delete e-mail messages from a POP mail server.
Syntax

Mode

Syntax

Creating the service

new pop(); or createObject("component",
"pop");

Initializing the attributes

See Initializing the attributes below.

Executing the service action

popService.action_method(_attribute-valu
e_pair_);

Getting the CFC properties

See Getting the CFC Properties below.

© 2014 Adobe Systems Incorporated. All rights reserved.

2709

Adobe ColdFusion Documentation

Working with data returned

popresult = popService.action_method (att
ribute-value pair); where popresult is a
query object if the action_method is getAll or get
HeaderOnly. For any other method, nothing is
returned.

Properties

server

attachmentPath

debug

generateUniqueFilen
ames

maxRows

messageNumber

name

password

port

startRow

timeout

uid

username

All attributes supported by the tag cfpop can be used as attribute-value pairs. For example,



can be used as

popHeaders = popService.getHeaderOnly(server="#form.popserver#");

Note
name is a required attribute in cfpop, but not in CFScript.

See also

Function summary
History

ColdFusion 9.0.1: Added this function.
Methods

The following pop actions are available as methods. All methods have similar arguments and syntax.
getHeaderOnly

© 2014 Adobe Systems Incorporated. All rights reserved.

getAll

delete

2710

Adobe ColdFusion Documentation

Description

All methods correspond to the type of information
supported by the tag cfpop. For details of each
method, see the relevant section of cfpop in the Co
ldFusion 9 CFML Reference.

Returns

All methods except delete returns a query object.

Syntax

popService.methodName(attribute-value
pair)

Arguments

All attributes supported by the tag cfpop.

setAttributes, getAttributes, clearAttributes, clear, setProperties, getProperties, an
d clearProperties. For details, see Methods common to all functions.
Usage

This function corresponds to the tag cfpop. For usage details, see the Usage section for cfpop__.
Example


p = createObject("component","pop");
p.setAttributes(server="#popServer#",username="failoveruser",password="#popPassword
#");
r = p.GetAll(name="results",maxRows = "2");
writeoutput("getAll Passed
");
r = p.GetAll(messageNumber = "2");
writeoutput(#r.FROM# & "
");

r= p.GETHEADERONLY(messageNumber = "1");
writeoutput(#r.subject# & "
");



ldap
Description

Used in CFScript to provide an interface to a Lightweight Directory Access Protocol (LDAP) directory server, such as
the Netscape Directory Server.
Syntax

Mode

© 2014 Adobe Systems Incorporated. All rights reserved.

Syntax

2711

Adobe ColdFusion Documentation

Creating the service

new ldap(); or createObject("component",
"ldap");

Initializing the attributes

See Initializing the attributes below.

Executing the service action

ldapService.action_method(attribute-value
pair);

Getting the CFC properties

See Getting the CFC Properties below.

Working with data

ldapresult = ldapService.query(attributevalue pair).For other methods, nothing is returned.

Properties

server

attributes

delimiter

dn

filter

maxRows

modifyType

name

password

port

rebind

referral

returnAsBinary

scope

secure

separator

sort

sortcontrol

start

startRow

timeout

userName

All attributes supported by the tag cfldap can be used as attribute-value pairs. For example,



can be used as

ldapService.add(server="ldap.uconn.edu");

For details, see the Attributes section for the tag cfldap.
Methods

The following ldap actions are available as methods. All methods have similar arguments and syntax.
query

add

modify

modifyDn

delete

© 2014 Adobe Systems Incorporated. All rights reserved.

2712

Adobe ColdFusion Documentation

Description

All methods correspond to the actions supported by
the tag cfldap. For details of each method, see
the relevant section of cfldap in the ColdFusion 9
CFML Reference.

Returns

If method is query, returns a query object. Else,
none.

Syntax

ldapService.methodName(attribute-value
pair)

Arguments

All attributes supported by the tag cfldap.

setAttributes. For details, see Methods common to all functions
getAttributes, clearAttributes, clear, setProperties, getProperties, and clearProperti
es. For details, see Methods common to all functions.
setLdapAttributes
Description

Sets the property attributes.

Returns

Nothing

Syntax

ldapService.setLdapAttributes(attribut
e-value);

Arguments

A string that contains the value of the property attr
ibutes.

getLdapAttributes
Description

Gets the property attributes.

Returns

A string that contains the value of the property attr
ibutes.

Syntax

myattributes = ldapService.getLdapAttri
butes(__);

See also

Function summary
History

ColdFusion 9.0.1: Added this function.
Usage

This function corresponds to the tag cfldap. For usage details, see the Usage section for cfldap.

© 2014 Adobe Systems Incorporated. All rights reserved.

2713

Adobe ColdFusion Documentation

Example


l = new ldap();
l.setLdapAttributes("objectclass=top, person, organizationalPerson,
inetOrgPerson;cn=Joe Smith; sn=Smith; mail=spenella@allaire.com;
telephonenumber=(617) 761 - 2128");
l.setUsername("uid=admin,ou=system");
l.setPassword("administrator");
l.setPort(port);
l.setServer(ldapserver);
l.setdn("ou=People+o=aribus.com,dc=example,dc=com");
l.add();l.clearAttributes(); result = l.query(name="apache",
attributes="dn,cn,o,ou,c,mail,telephonenumber",
start="dc=example,dc=com",
scope="SUBTREE",
filter="(&(cn=Joe Smith)(ou=people))";
writeoutput("Adding and Querying a LDAP entry : " & "CN = " & result.CN & "
DN = " & result.DN & "
 ");
l.clearAttributes();
l.delete(
DN="ou=People+o=aribus.com,dc=example,dc=com",
);



feed
Description

Used in CFScript to read or create an RSS or Atom syndication feed. This service reads RSS versions 0.90, 0.91,
0.92, 0.93, 0.94, 1.0, and 2.0, and Atom 0.3 or 1.0. It can create RSS 2.0 or Atom 1.0 feeds.
Syntax

Mode

Syntax

Creating the service

new feed() or createObject("component"
"feed")

Initializing the attributes

See Initializing the attributes below.

Executing the service action

feedService.action_method(attribute-valu
e_pair)

© 2014 Adobe Systems Incorporated. All rights reserved.

2714

Adobe ColdFusion Documentation

Getting the CFC properties

See Getting the CFC Properties below.

Working with the data returned

feedresult = feedService.read(attribute
-value_pair) where feedresult is a struct with
the keys name, query, properties, and xmlvar.
feedresult =
feedService.create(attribute-value_pair
) where feedresult is a string that contains the xm
lvar.

Properties

columnMap

enclosureDir

escapeChar

ignoreEnclosureErro
r

name (optional in
CFScript)

outputFile

overwrite

overwriteEnclosure

properties (optional in
CFScript)

proxyPassword

proxyPort

proxyServer

proxyUser

query (optional in
CFScript)

source

timeout

useragent

xmlvar (optional in
CFScript)

All attributes supported by the tag cffeed can be used as attribute-value pairs. For example,



can be used as

feedservice.read(source="http://googleblog.blogspot.com/atom.xml",
query="feedQuery", properties="feedMetadata");

See also

Function summary
History

ColdFusion 9.0.1: Added this function.
Methods

© 2014 Adobe Systems Incorporated. All rights reserved.

2715

Adobe ColdFusion Documentation

create
Description

Creates an RSS 2.0 or Atom 1.0 feed XML
document and saves it in a variable, writes it to a
file, or both.

Returns

String representing the xmlvar

Syntax

feedService.create (attribute-value
pair);

Arguments

All attributes supported by the tag cffeed.

read
Description

Parses an RSS or Atom feed from a URL or an XML
file and saves it in a structure or query. You can
also get feed metadata in a separate structure.

Returns

Struct with the following keys:

name
query
properties
xmlvar
Syntax

feedService.read (attribute-value pair
);

Arguments

All attributes supported by the tag cffeed.

setAttributes, getAttributes, clearAttributes, clear, setProperties, getProperties, and
clearProperties. For details, see Methods common to all functionsMethods common to all functions.
getFeedProperties
Description

Returns the value of the property properties.

Returns

Struct or error (if property is not set)

Syntax

feedService.getFeedProeprties()

Arguments

None

setFeedProperties
Description

Sets the value of the property properties.

Returns

Nothing

© 2014 Adobe Systems Incorporated. All rights reserved.

2716

Adobe ColdFusion Documentation

Syntax

feedService.setFeedProperties()

Arguments

properties struct

Usage

This service corresponds to the tag cffeed. For usage, see Usage section for cffeed.
Example


f = new feed();
r = f.read(source=feedpath);
writeoutput("Name : " & r.name.title & "
");
writeoutput("Properties : " & r.properties.version & "
");
writeoutput("Query : " & r.query.recordcount & "
");
writeoutput("XMLVar : " & r.xmlvar.length() & "
");


Methods common to all functions
The following methods are common to all script functions:
setAttributes
Description

Sets attributes for the function.

Returns

Nothing

Syntax

service_name.setAttributes (attributevalue pair);

Arguments

All attributes supported by the equivalent tag.

getAttributes
Description

Gets the attributes set for the function.

Returns

Returns a struct with all or some attribute values.

Syntax

service_name.get_Attributes_ (attribut
elist);

Arguments

A comma-separated list of attributes. If no list is
specified, all defined attributes are returned.

clearAttributes

© 2014 Adobe Systems Incorporated. All rights reserved.

2717

Adobe ColdFusion Documentation

Description

Removes all attributes added for the function.

Returns

Nothing

Syntax

_service_name.clearAttributes(_attribu
te_list);

Arguments

A comma-separated list of attributes.

clear
Description

Removes all attributes added for the function.

Returns

Nothing

Syntax

service_name.clear();

Arguments

None

clearProperties
Description

Removes all properties added for the function.

Returns

Nothing

Syntax

service_name.clearProperties(attribute
_list);

Arguments

If nothing is specified, all properties are cleared.

setProperties
Description

Sets properties for the function.

Returns

Nothing

Syntax

service_name.setproperties (attributevalue pair);

Arguments

All attributes supported by the equivalent tag.

getProperties
Description

Gets the properties set for the function.

Returns

Returns a struct with all or some attribute values.

© 2014 Adobe Systems Incorporated. All rights reserved.

2718

Adobe ColdFusion Documentation

Syntax

service_name.getproperties (attributel
ist);

Arguments

A comma-separated list of attributes. If no list is
specified, all defined attributes are returned.

Initializing the attributes
You can initialize the attributes using one of the following ways:
service_name=new dbinfo(attribute-value pair)
service_name=new dbinfo().init(attribute-value pair)
service_name.setAttributes(_attribute-value pair_)
service_name.setA_ttributeName_(attribute_value)
service_name.action_method(attribute-value_pair)
service_name.setProperties (attribute_value)
Getting the CFC Properties
Get the CFC properties using one of the following ways:
service_name.getAttributeName(attributelist)
service_name.getProperties (attributelist)
service_name.getAttributes(attributelist)
Function summary
dbinfo
Description
Syntax
Properties
See also
History
Methods
Usage
Example
imap
Description
Syntax
Properties
See also
History
Methods
Usage
Example
pop
Description
Syntax
Properties
See also
History
Methods
Usage

© 2014 Adobe Systems Incorporated. All rights reserved.

2719

Adobe ColdFusion Documentation

Example
ldap
Description
Syntax
Properties
Methods
See also
History
Usage
Example
feed
Description
Syntax
Properties
See also
History
Methods
Usage
Example
Methods common to all functions
Initializing the attributes
Getting the CFC Properties

© 2014 Adobe Systems Incorporated. All rights reserved.

2720

Adobe ColdFusion Documentation

ColdFusion Flash Form Style Reference
You can specify styles in ColdFusion forms tags when you display the form or form element in Flash format.
Note
The column labeled Inh indicates whether a style is inherited by child controls, such as the form
controls in a vbox.

Styles valid for all controls
Styles for cfform
Styles for cfformgroup with horizontal or vertical type attributes
Styles for box-style cfformgroup elements
Styles for cfformgroup with accordion type attribute
Styles for cfformgroup with tabnavigator type attribute
Styles for cfformitem with hrule or vrule type attributes
Styles for cfinput with radio, checkbox, button, image, or submit type attributes
Styles for cftextarea tag and cfinput with text, password, or hidden type attributes
Styles for cfselect with size attribute value of 1
Styles for cfselect with size attribute value greater than 1
Styles for cfcalendar tag and cfinput with dateField type attribute
Styles for the cfgrid tag
Styles for the cftree tag
#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

2721

Adobe ColdFusion Documentation

Styles valid for all controls
The following styles are valid for all ColdFusion Flash format form tags except for cfformitem tags with the
following type attributes, which do not take style attributes:
html
space
These styles do not cause errors when used in all other tags. However, many styles do not have any effect
when used in some tags.
Style

Inh

Description

backgroundAlpha

N

Alpha (transparency) level of the
SWF file or image defined by back
groundImage. Valid values range
from 0 (transparent) to 100
(opaque). The default value is 100.

backgroundColor

Y

Format: color; background color of
the control. Has no effect if
specified in a cfform control tag,
which uses the background-colo
r style to control the color. Also
ignored by cfinput tags of type b
utton, img, submit, radio, and
checkbox, because they are filled
with the button face or other
graphics.

backgroundDisabledColor

Y

Format: color; background color of
components when disabled. The
default value is ##EFEEEF (light
gray).

backgroundSize

N

Scales the image specified by back
groundImage to different
percentage sizes. By default, the
value is auto, which maintains the
original size of the image. A value
of 100% stretches the image to fit
the entire screen. Include the
percent sign with the value.

barColor

Y

Format: color; color of the outer bar.

borderCapColor

Y

Format: color; outside left and
outside right color for skins.

© 2014 Adobe Systems Incorporated. All rights reserved.

2722

Adobe ColdFusion Documentation

borderColor

Y

Format: color; black section of a
three-dimensional border or the
color section of a two-dimensional
border.

borderSides

N

Bounding box sides. Only used
when borderStyle="solid".
Space-delimited string containing
the sides of the border to show.
Order is not important. The default
value is "left top right bottom".

borderStyle

Y

Bounding box style. The possible
values are:
inset (default)
none
outset
solid

borderThickness

N

Bounding box thickness. Only used
when borderStyle="solid".
The default value is 1.

color

Y

Format: color; text color of a
component's label.

cornerRadius

N

Radius of component corners. The
default value is 0.

disabledColor

Y

Format: color; color of the
component if it is disabled.

dropShadow

N

Format: Boolean; controls the
visibility of the component's drop
shadow. The default value is false
. This style must be used with bord
erStyle="solid". For drop
shadows to appear on containers,
set backgroundColor or backgr
oundImage. Otherwise, since the
default background of a container is
transparent, the shadow appears
behind the container.

errorColor

Y

Format: color; color of the error text.

© 2014 Adobe Systems Incorporated. All rights reserved.

2723

Adobe ColdFusion Documentation

fillColors

N

Format: color; colors used to tint the
background of the control. Pass the
same color for both values for "flat"
looking control. The default value is
##E6EEEE,##FFFFFF.

fontFamily

Y

Comma-separated list of fonts to
use, in descending order of
desirability. You can use any font
family name. If you specify a
generic font name, it is converted to
an appropriate device font. Flash
can only use fonts that are installed
on the client system.

fontSize

Y

Format: length; size of the text.

fontStyle

Y

Determines whether the text is
italic. Recognized values are norma
l and italic. The default value is
normal.

fontWeight

Y

Determines whether the text is bold.
Recognized values are normal and
bold. The default value is normal.

highlightColor

Y

Format: color; color of the control
when it is in focus.

horizontalGap

N

Format: length; number of pixels
between children in the horizontal
direction.

leading

N

Additional vertical space between
lines of text. The default value is no
leading.

marginLeft

N

Format: length; number of pixels
between the container's left border
and its content area.

marginRight

N

Format: length; number of pixels
between the container's right border
and its content area.

scrollTrackColor

Y

Format: color; scroll track for a
scroll bar. The default value is ##EF
EEEF (light gray).

© 2014 Adobe Systems Incorporated. All rights reserved.

2724

Adobe ColdFusion Documentation

selectedFillColors

N

Format: colors; two colors used to
tint the background of the control
when in its selected state. Pass the
same color for both values for "flat"
looking control. The default value is
undefined, which means the colors
are derived from themeColor.

textAlign

Y

Aligns text in a container.
Recognized values are left, righ
t, and center. The default value is
right.

textDecoration

N

Determines whether the text is
underlined or not. Recognized
values are none and underline.
The default value is none.

textIndent

Y

Format: length; offset of first line of
text from the left side of the
container. The default value is 0.

themeColor

Y

Format: color; background color of
a component. The possible values
are:
haloGreen
haloBlue
haloOrange
haloSilver

verticalGap

N

Format: length; number of pixels
between children in the vertical
direction.

#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

2725

Adobe ColdFusion Documentation

Styles for cfform
The following styles apply to the cfform tag:
Style

Inh

Description
Format: color; background color of
the form.

background-color

indicatorGap

Y

Format: length; number of pixels
between the label and child
components. The default value is
14.

labelWidth

Y

Format: length; width of the form
labels. The default value is the
length of the longest label in the
form.

marginBottom

N

Format: length; number of pixels
between the container's bottom
border and its content area. The
default value is 16.

marginTop

N

Format: length; number of pixels
between the container's top border
and its content area. The default
value is 16.

verticalGap

N

Format: length; number of pixels
between children in the vertical
direction. The default value is 8.

#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

2726

Adobe ColdFusion Documentation

Styles for cfformgroup with horizontal or vertical type attributes
The following styles apply to the cfformgroup tag with type attributes horizontal or vertical:
Style

Inh

Description

horizontalAlign

N

Horizontal alignment of children.
Possible values are left, center, and
right. The default value is left.

horizontalGap

N

Format: length; number of pixels
between children in the horizontal
direction. The default value is 6.

indicatorGap

Y

Format: length; number of pixels
between the label and child
components. The default value is
14.

labelWidth

Y

Format: length; width of the form
labels. The default value is the
length of the longest label in the
form.

marginBottom

N

Format: length; number of pixels
between the container`s bottom
border and its content area. The
default value is 0.

marginTop

N

Format: length; number of pixels
between the container`s top border
and its content area. The default
value is 0.

verticalGap

N

Format: length; number of pixels
between children in the vertical
direction. The default value is 6.

#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

2727

Adobe ColdFusion Documentation

Styles for box-style cfformgroup elements
The following styles apply to the cfformgroup tag with the following type attributes. Some types have additional
attributes, which are listed in the following sections.
hbox
vbox
hdividedbox
vdividedbox
panel
tile
page
Style

Inh

Description

horizontalAlign

N

Horizontal alignment of children in
the container. The default value is l
eft. Possible values are left, ce
nter, and right.

horizontalGap

N

Format: length; number of pixels
between children in the horizontal
direction. The default value is 8 (6
for a tile container).

marginBottom

N

Format: length; number of pixels
between the container's bottom
border and its content area. The
default value is 0.

marginTop

N

Format: length; number of pixels
between the container's top border
and its content area. The default
value is 0.

verticalAlign

N

Vertical alignment of children in the
container. The default value is top.
Possible values are top, middle,
and bottom.

verticalGap

N

Format: length; number of pixels
between children in the vertical
direction. The default value is 8 (6
for a tile container).

Styles specific to cfformgroup with hdividedbox or vdividedbox type attributes
The following additional styles apply to the cfformgroup tag with type="hdividedbox", or type="vdividedb
ox":

© 2014 Adobe Systems Incorporated. All rights reserved.

2728

Adobe ColdFusion Documentation

Style

Inh

Description

dividerAffordance

N

Format: length; width (hdividedbox)
or height (vdividedbox) in pixels of
the area of the divider that the user
can select with the mouse pointer.
The default value is 6.

dividerColor

Y

Format: color; color of the dividers
in their up state. The default value
is ##AAAAAA.

dividerThickness

N

Format: length; thickness in pixels
of the dividers. The default value is
4.

Styles specific to cfformgroup with panel type attribute
The following additional styles apply to the cfformgroup tag with type="panel":
Style

Inh

Description

cornerRadius

N

Format: length; radius of corners of
the window frame. The default
value is 8.

dropShadow

N

Boolean value specifying whether
the panel has a drop shadow. The
default value is true.

footerColors

Y

Format: color; comma-delimited list
of two colors used to draw the
footer (ControlBar) background.
The first color is the top color. The
second color is the bottom color.
The default value is ##F4F5F7,{{
##E1E5EB}}.

headerColors

Y

Format: color; comma-delimited list
of two colors used to draw the
header. The first color is the top
color. The second color is the
bottom color. The default value is #
#E1E5EB, ##F4F5F7.

headerHeight

N

Format: length; height of the
header. The default value is 28.

© 2014 Adobe Systems Incorporated. All rights reserved.

2729

Adobe ColdFusion Documentation

panelBorderStyle

N

Border style for the bottom two
corners of the container. The top
two corners are always round.
Possible values are default, which
configures the container to have
square corners, and roundCorners,
which defines rounded corners. To
configure the top corners to be
square, set cornerRadius to 0. The
default value is default.

shadowDirection

N

Direction of drop shadow. Possible
values are "left", "center", and
"right". The default value is "center".

shadowDistance

N

Distance of drop shadow. Negative
values move shadow above the
panel. The default value is 2.

#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

2730

Adobe ColdFusion Documentation

Styles for cfformgroup with accordion type attribute
The following styles apply to the cfformgroup tag with type="accordion":
Style

Inh

Description

headerHeight

N

Format: length; height of the
accordion container buttons, in
pixels. The default value is 22.

marginBottom

N

Format: length; number of pixels
between the container`s bottom
border and its content area. The
default value is -1.

marginTop

N

Format: length; number of pixels
between the container`s top border
and its content area. The default
value is -1.

openDuration

N

Format: time; duration, in
milliseconds, of the transition from
one child panel to another. The
default value is 250.

verticalGap

N

Format: length; number of pixels
between children in the vertical
direction. The default value is -1.

#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

2731

Adobe ColdFusion Documentation

Styles for cfformgroup with tabnavigator type attribute
The following styles apply to the cfformgroup tag with the type="tabnavigator":
Style

Inh

Description

horizontalAlign

N

Horizontal alignment of children.
The default value is left. Possible
values are left, center, and right.
Because the preferred width of
each tab in the tab navigator
container is the size of the label
text, use the tabWidth style to
increase the width of the tab to a
size larger than its preferred width
to see different alignments.

horizontalGap

N

Format: length; number of pixels
between children in the horizontal
direction. The default value is 6.

tabHeight

N

Format: length; default tab height, in
pixels. The default value is 22.

tabWidth

N

Format: length; width of the tabs, in
pixels. If undefined, the default tab
widths are automatically calculated
from the label text. If the width of
the container is smaller than the
width of the label text, the labels are
truncated. If a tab label is truncated,
Flash displays a tooltip with the full
label text when a user moves the
mouse pointer over the tab. If you
specify an explicit tab width, labels
do not automatically shrink to fit if
they do not fit in the available
space.

#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

2732

Adobe ColdFusion Documentation

Styles for cfformitem with hrule or vrule type attributes
The following styles apply to the formitem tag with type="hrule" or type="vrule":
Style

Inh

Description

color

Y

Format: color; color of the line.
according to the following rules:
If strokeWidth is 1, the color of
the entire line.
If strokeWidth is 2 (default),
the color of the top line.
If strokeWidth is greater than
2, the color of the top and left
edges of the rectangle.
The default value is ##C4CCCC.

shadowColor

Y

Format: color; shadow color of the
line, as follows:.
If strokeWidth is 1, does
nothing.
If strokeWidth is 2 (default),
the color of the bottom line.
If strokeWidth is greater than
2, the color of the bottom and
right edges of the rectangle.
The default value is ##D4D0C8.

strokeWidth

Y

Thickness of the rule in pixels, as
follows:
If strokeWidth is 1, the rule is a
1-pixel-wide line.
If strokeWidth is 2 (default),
the rule is two adjacent
1-pixel-wide horizontal lines.
If strokeWidth is greater than
2, the rule is a hollow rectangle
with 1-pixel-wide edges.
The default value is 2.

#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

2733

Adobe ColdFusion Documentation

Styles for cfinput with radio, checkbox, button, image, or submit type
attributes
The following styles apply cfinput tags with the following type attribute values:
button
checkbox
image
radio
submit
In some cases, a style applies only to the subset of these input types, as specified in the description.
Style

Inh

Description

borderThickness

N

Thickness of border "ring". A value
of 0 means no border. Any value
greater than 2 creates a glowing
"ring" around the button. The
default value is 3.

cornerRadius

N

Radius of corners. The default
value is 5.

horizontalGap

N

Gap between the label and the
image in an img input when label
Placement = "left" or "right
". The default value is 2.

repeatDelay

N

Format: time; number of
milliseconds to wait after the first
buttonDown event before repeating
buttonDown events at the
repeatInterval. The default value is
500.

repeatInterval

N

Format: time; number of
milliseconds between buttonDown
events if you press and hold a
button. The default value is 35.

symbolBackgroundColor

Y

Format: color; background color of
check boxes and radio buttons. The
default value is ##FFFFFF (white).

symbolBackgroundDisabledCo
lor

Y

Format: color; background color of
check boxes and radio buttons
when disabled. The default value is
##EFEEEF (light gray).

© 2014 Adobe Systems Incorporated. All rights reserved.

2734

Adobe ColdFusion Documentation

symbolBackgroundPressedCol
or

Y

Format: color; background color of
check boxes and radio buttons
when pressed. The default value is
##FFFFFF (white).

symbolColor

Y

Format: color; the check mark of a
check box or the dot of a radio
button. The default value is ##0000
00 (black).

symbolDisabledColor

Y

Format: color; check mark or radio
button dot color if the control is
disabled. The default value is ##84
8384 (dark gray).

texRollOverColor

Y

Format: color; text color of the label
as you move the mouse pointer
over the control. The default value
is ##2B333C.

textSelectColor

Y

Format: color; text color of the label
as you select the control. The
default value is ##000000.

verticalGap

N

Gap between the label and the
image in an img input when label
Placement = "top" or "bottom
". The default value is 2.

#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

2735

Adobe ColdFusion Documentation

Styles for cftextarea tag and cfinput with text, password, or hidden type
attributes
The following style applies to the following tags and tag-attribute combinations:
textarea
cfinput type="hidden"
cfinput type="password"
cfinput type="text"
Style

Inh

Description

disabledColor

Y

Format: color; disabled color of the
Text Area.

#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

2736

Adobe ColdFusion Documentation

Styles for cfselect with size attribute value of 1
The following styles apply to the cfselect tag when the size attribute is 1; that is, if the control displays one
option at a time, with a drop-down list (also known as a combobox):
Style

Inh

Description

alternatingRowColors

Y

Format: comma delimited list of
colors for rows in an alternating
pattern. Value can be a list of two or
more colors. Use only if you do not
specify a backgroundColor style.

closeDuration

N

Time to close the drop-down list, in
milliseconds. The default value is
250.

openDuration

N

Time to close the drop-down list, in
milliseconds. The default value is
250.

rollOverColor

Y

Format: color; color of the
background when the user rolls
over an item. The default value is #
#0EFFD6.

selectionColor

Y

Format: color; color of the
background when the user selects
an item. The default value is ##0DF
FC1.

#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

2737

Adobe ColdFusion Documentation

Styles for cfselect with size attribute value greater than 1
The following styles apply to the cfselect tag when the size attribute is greater than 1; that is, if the control is a
list box that displays two or more options at a time:
Style

Inh

Description

alternatingRowColors

Y

Type: comma-delimited list of colors
for rows in an alternating pattern.
Value can be a list of two or more
colors.

marginBottom

N

Format: length; number of pixels
between the bottom of the row and
the bottom of the text in the row.
The default value is 0.

marginTop

N

Format: length; number of pixels
between the top of the row and the
top of the text in the row. The
default value is 0.

rollOverColor

Y

Format: color; color of the
background when the user moves
the mouse pointer over the link. The
default value is ##0EFFD6.

selectionColor

Y

Format: color; color of the
background when the user selects
the link. The default value is ##0DF
FC1.

selectionDuration

N

The duration of the selection
animation, in milliseconds. The
default value is 250. Set to 0 to
disable animation.

textRollOverColor

Y

Format: color; text color when the
user moves the mouse pointer over
the selection. The default value is #
#02B33C.

textSelectedColor

Y

Format: color; text color when
selected. The default value is ##00
5F33.

#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

2738

Adobe ColdFusion Documentation

Styles for cfcalendar tag and cfinput with dateField type attribute
The following styles apply to the cfcalendar tag and dateField type of the cfinput tag:
Style

Inh

Description

headerColors

Y

Format: color; colors of the band at
the top of the DateChooser control
. Specify two values, separated by a
comma. For a solid band, use the
same color for both values. The
default value is ##E6EEEE,##FFFF
FF.

rollOverColor

Y

Format: color; color of the
background when the user moves
the mouse pointer over the DateFi
eld. The default value is ##E3FFD
6.

selectionColor

Y

Format: color; color of the
background when the user selects
the DateField. The default value
is ##CDFFC1.

todayColor

Y

Format: color; color of today's date.
The default value is{{ ##2B333C}}.

#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

2739

Adobe ColdFusion Documentation

Styles for the cfgrid tag
The following styles apply to the cfgrid tag:
Style

Inh

Description

horizontalAlign

N

Horizontal alignment of children in
the container. The default value is l
eft. Possible values are left, ce
nter, and right.

horizontalGap

N

Number of pixels between children
in the horizontal direction. The
default value is 8.

marginBottom

N

Number of pixels between the
container's bottom border and its
content area. The default value is 0.

marginTop

N

Number of pixels between the
container's top border and its
content area. The default value is 0.

verticalAlign

N

Vertical alignment of children in the
container. The default value is top.
Possible values are top, middle,
and bottom.

verticalGap

N

Number of pixels between children
in the vertical direction. The default
value is 8.

#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

2740

Adobe ColdFusion Documentation

Styles for the cftree tag
The following styles apply to the cftree tag:
Style

Inh

Description

alternatingRowColors

Y

Type: Array; colors for rows in an
alternating pattern. Value can be an
Array of two or more colors.

depthColors

Y

Type: Array; array of colors used in
the Tree control, in descending
order.

indentation

N

Indentation for each tree level, in
pixels. The default value is 8.

openDuration

N

Format: time; length of an open or
close transition, in milliseconds. The
default value is 250.

rollOverColor

Y

Format: color; color of the
background when the user moves
the mouse pointer over the link. The
default value is ##E3FFD6.

selectionColor

Y

Format: color; color of the
background when the user selects
the link. The default value is ##CDF
FC1.

selectionDuration

N

The duration of the selection
animation, in milliseconds. The
default value is 250. Set to 0 to
disable animation.

textRollOverColor

Y

Format: color; color of the text when
the user moves the mouse pointer
over the entry. The default value is
##02B33C.

textSelectedColor

Y

Format: color; color of the text when
the user selects the entry. The
default value is ##005F33.

© 2014 Adobe Systems Incorporated. All rights reserved.

2741

Adobe ColdFusion Documentation

Application.CFC Reference
You implement methods in Application.cfc to handle ColdFusion application events and set variables in the CFC to
configure application characteristics.
Application variables
Method summary
onAbort
onApplicationEnd
onApplicationStart
onCFCRequest
onError
onMissingTemplate
onRequest
onRequestEnd
onRequestStart
onServerStart
onSessionEnd
onSessionStart

#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

2742

Adobe ColdFusion Documentation

Application variables
The This scope for the Application.cfc contains several built-in variables, which correspond to the attributes that you
set in the cfapplication tag. You set the values of these variables in the CFC initialization code, before you
define the CFC methods. You can access the variables in any method.
Note
Although Windows is case-insensitive, you must always start the Application.cfc filename with an
uppercase A. Both application.cfc and Application.cfc are reserved words.
Note
If your application has an Application.cfc, and an Application.cfm or onRequestend.cfm page,
ColdFusion ignores the CFM pages

The following table briefly describes the variables that you can set to control the application behavior. For more
details, see the cfapplication tag.
Variable

Default

Description

name

no name

The application name. If you do not
set this variable, or set it to the
empty string, your CFC applies to
the unnamed application scope,
which is the ColdFusion J2EE
servlet context. For more
information on unnamed scopes
see Integrating JSP and servlets in
a ColdFusion application in Interope
rating with JSP pages and servlets i
n the Developing ColdFusion
Applications.

applicationTimeout

Administrator value

Life span, as a real number of days,
of the application, including all
Application scope variables. Use
the CFML CreateTimeSpan functi
on to generate this variable's value.

authcookie.disableupdate

False

Disable update of cfauthorization
cookie using cfcookie or cfhead
er tag

authcookie.timeout

-1

Auth Cookie age in days.

chartStyleDirectory

© 2014 Adobe Systems Incorporated. All rights reserved.

Application specific client side
charting styles directory.

2743

Adobe ColdFusion Documentation

clientManagement

no

yes: enables client variables.
no

clientStorage

Administrator value

Where Client variables are stored;
can be cookie, registry, or the name
of a data source.

customtagpaths

Administrator value

Contains ColdFusion custom tag
paths. It is a comma delimited list
with absolute path.To use this
variable, select the Enable Per App
Settings option in the Administrator
Server > Settings page.The
settings that you define here take
precedence over the custom tag
paths defined in the Administrator S
erver Settings > Mappings page
for the current application.

googleMapKey

The Google Maps API key required
to embed Google Maps in your web
pages.

datasource

Name of the data source from
which the query retrieves data.

loginStorage

cookie

Whether to store login information
in the Cookie scope or the Session
scope.

mappings

Administrator value

A structure that contains
ColdFusion mappings. Each
element in the structure consists of
a key and a value. The logical path
is the key and the absolute path is
the value. To use this variable,
select the Enable Per App Settings
option in the Administrator Server
Settings > Settings page.The
mappings that you define here take
precedence over the mappings
defined in the Administrator Server
Settings > Mappings page for the
current application.

© 2014 Adobe Systems Incorporated. All rights reserved.

2744

Adobe ColdFusion Documentation

restSettings.cfclocation

To publish the CFCs only in a
particular location, provide
comma-separated list of directories
where the REST CFCs are located.
The directory paths can be absolute
or relative.If not set, all the CFCs
from the application root are
published.

restSettings.skipCFCWithError

When an error occurs, continue
publishing, ignoring the CFC that
has caused the exception.If true,
the CFC with error is ignored and
the rest of the CFCs are published.
By default it is false.If set to false, in
case of an error, the application
itself is not published. But other
registered application are
published.If an error occurs during
application startup, the error is
printed in console.Each application
has separate log files for logging
the issues.

sessioncookie.httponly

True

Specify whether session cookies
have to be set as httponly or not.
i.e. accessible only to Http requests

sessioncookie.secure

False

Specify whether session cookies
have to be set as secure or not. i.e.
returned on any type of connection
or only secured (https) connections

sessioncookie.domain

Domain for which the cookie should
be set. This should match exactly
with the domain, with which
application would be accessed

sessioncookie.timeout

30 years

Session Cookie age in days

sessioncookie.disableupdate

False

Disable update of cfid and cftok
en cookie using cfcookie or cfhe
ader tag

serverSideFormValidation

yes

Whether to enable validation on
cfform fields when the form is
submitted.

sessionManagement

no

Whether the application supports
Session scope variables.

© 2014 Adobe Systems Incorporated. All rights reserved.

2745

Adobe ColdFusion Documentation

sessionTimeout

Administrator value

Life span, as a real number of days,
of the user session, including all
Session variables. Use the CFML C
reateTimeSpan function to
generate this variable's value.

setClientCookies

True

Whether to send CFID and
CFTOKEN cookies to the client
browser.

setDomainCookies

False

Whether to set CFID and
CFTOKEN cookies for a domain
(not just a host).

scriptProtect

Administrator value

Whether to protect variables
fromcross-site scripting attacks.

security.antisamypolicy

Specify the location of antisamy file
to be used when no antisamy policy
file is passed to the getSafeHTML o
r isSafeHTML functions. The policy
file can be relative to the Application
CFC path or an absolute path can
be provided.

compileextforinclude

Specify the list of allowed file
extensions as a comma-separated
list for the cfinclude tag. Specifying
a wildcard * in the list makes any
file included using the cfinclude tag
to be compiled. If any file included
using the cfinclude tag is not found
in this list, their content will be
statically included. By default, files
with the cfm and cfml extensions
are always compiled irrespective of
this setting.

© 2014 Adobe Systems Incorporated. All rights reserved.

2746

Adobe ColdFusion Documentation

strictnumbervalidation

True/False. Default is true. The IsV
alid function for the integer and
numeric types allowed the currency
symbols at the start and commas
inside the number.
In ColdFusion 11, the isValid functio
n behaves in a different way.
Setting strictnumbervalidation to
false makes the isValid function to
behave in a way just like in the
previous versions (ColdFusion 10 or
earlier). Note that this setting also
changes the behavior of the
following tags:
cfargument
cfparam
cfform

secureJSON

Administrator value

A Boolean value that specifies
whether to add a security prefix in
front of the value that a ColdFusion
function returns in JSON-format in
response to a remote call. The
default value is the value of the
Prefix serialized JSON setting in the
Administrator Server Settings >
Settings page (which defaults to fa
lse). You can override this value
in the cffunction tag.For more
information see Improving security i
n Ajax programming rules and
techniques in the Developing
ColdFusion Applications.

secureJSONPrefix

Administrator value

The security prefix to put in front of
the value that a ColdFusion function
returns in JSON-format in response
to a remote call if the secureJSON
setting is true. The default value is
the value of the Prefix serialized
JSON setting in the Administrator
Server Settings > Settings page
(which defaults to //, the
JavaScript comment character).For
more information see Improving
security in Ajax programming rules
and techniques in the Developing
ColdFusion Applications.

© 2014 Adobe Systems Incorporated. All rights reserved.

2747

Adobe ColdFusion Documentation

serialization.preservecaseforstructk
eys

False

Boolean that determines if case for
struct keys should be preserved
when serializing a struct to JSON.

serialization.serializequeryas

row

Determines how queries should be
serialized to JSON. Possible values
are row, column, and struct.

welcomeFileList

A comma-delimited list of names of
files. Tells ColdFusion not to call the
onMissingTemplate method if
the files are not found. Use this
variable to prevent ColdFusion from
invoking the onMissingTemplate
handler if all of the following items
are true:
Your web server (for example,
web.xml file) has a welcome file
list with CFML pages such as
index.cfm that it tries to run if a
URL specifies a path ending in a
directory.
The web server sends a request
for CFML pages the welcome list
to ColdFusion without first
determining if the page exists.
You want to support directory
browsing in directories that do not
have any of the files on the
welcome file list.
You specify this variable only if
the Application.cfc file also
specifies an onMissingTempla
te handler. It must have the
same list of files as your web.xml
welcome file list.Note: You do not
need to use the welcomeFileList
variable with most "pure" web
servers, such as Apache. The
welcomeFileList variable has to
be used with most integrated web
and application servers.

smtpServersettings

© 2014 Adobe Systems Incorporated. All rights reserved.

A struct that contains the following
values: server, username, and p
assword.If no value is specified,
takes the value in the administrator.

2748

Adobe ColdFusion Documentation

sameformfieldsasarray

false

If the form fields have the same
name, ColdFusion converts the
form fields as an array instead of a
list. To do this, in the
Application.cfc, specify the
following: this.sameformfields
asarray = "true". Note: The
empty string values will be
preserved only if this is set to true.

timeout

The lifespan. Timeout set using 
overrides the timeout in the
Application.cfc using this.timeou
t="".

debuggingIPAddresses

A list of IP addresses that need
debugging.

enablerobustexception

Overrides the default administrator
settings. It does not report
compile-time exceptions.

javaSettings

A structure allowing you to specify
Java class paths to be made
available to your code. Valid keys
are: loadPaths (an array of paths to
include when searching for Java
libraries), loadColdFusionClassPath
(a boolean indicating if the default
class path should be used, defaults
to false), and reloadOnChange (a
boolean indicating if the classpaths
should be reloaded when they
change, the default is false).

Form fields with same name
Assume that the form fields have same name. In this case, ColdFusion converts the form fields as an array instead
of a list.To do this, in the Application.cfc, specify the following: this.sameformfieldsasarray = "true".The
default value is false.
Enhancements made in ColdFusion 11
In ColdFusion 11, you can register application-specific datasources in Application.cfc. These datasources will be
specific to that application and will not be available through the Administrator. If there is a name clash with a
server-wide datasource, the one specific to the application will be given the priority.

© 2014 Adobe Systems Incorporated. All rights reserved.

2749

Adobe ColdFusion Documentation

this.datasources.dsn1={"database"="regression","host"="localhost\MSSQL2008","driver"
="MSSQLServer","username"="sa","password"="password"};
this.datasources.dsn2={"driver"="MSSQLServer",url="jdbc:macromedia:sqlserver://local
host\MSSQL2008;databaseName=regression;;sendStringParametersAsUnicode=false;querytim
eout=0;MaxPooledStatements=1000","username"="sa","password"="pass"};

With a custom driver:

this.datasources.dsn3 = { "driver" = "other", "url" =
"jdbc:sqlserver://localhost\MSSQL2008;databaseName=pubs;sendStringParametersAsUnicod
e=false;querytimeout=0;MaxPooledStatements=1000", "username" = "sa", "password" =
"S33N0Ev!l", "class" = "com.microsoft.sqlserver.jdbc.SQLServerDriver"};

The following drivers are supported:
MSSQLServer
Oracle
Sybase
DB2
Informix
MySQL_DD
PostgreSQL
MSAccess
Apache Derby Embedded
Apache Derby Client
MySQL5
ODBCSocket
Other (for custom driver)
Enhancements made in ColdFusion 9.0.1
Application.cfc lets you specify data source authentication details for the data source. The data source settings can
now be a string or a struct. When string, it is considered to be the data source name and authentication information
is taken from the data source defined in the ColdFusion Administrator.
You can specify the authentication information using a struct value for data source. The following are the key
names:
name: data source name
username: Username for the data source
password: Password for the data source
Example

© 2014 Adobe Systems Incorporated. All rights reserved.

2750

Adobe ColdFusion Documentation



or



Note
The same convention is used for ORM default data source where you can specify the data
source authentication information in the ormsettings.

The following application-specific attributes have been added for Amazon S3 integration:
accessKeyId: ID for Amazon S3 account.
awsSecretKey: Secret key for S3 account.
defaultLocation:}}The default location of Amazon S3 bucket creation. A bucket on
S3 storage can be in one of the following regions: {{US, EU, or US-WEST.The defaultLo
cation provided in the Application.cfc defines the default location for the bucket that you create. The default
value is US.
Example


this.s3.accessKeyId = "key_ID";
this.s3.awsSecretKey = "secret_key";
this.s3.defaultLocation="location";


Application-specific In-memory file system
You can use in-memory file system specific to applications. This enables application isolation for your virtual file
system. That is, the file created in the in-memory file system by one application will not be accessible to another
application.
The settings can be specified in the Application.cfc as follows:
Variable

Description

this.inmemoryfilesystem.enabled

Set the value to true to enable in-memory file system
for application. This is the default setting.

this.inmemoryfilesystem.size

Specify the memory limit in MB for the in-memory file
system.You can also specify the value in the
ColdFusion Administrator (Server Settings > Settings >
Memory Limit per Application for In-Memory Virtual File
System).The lesser value is considered.

© 2014 Adobe Systems Incorporated. All rights reserved.

2751

Adobe ColdFusion Documentation

#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

2752

Adobe ColdFusion Documentation

Method summary
The following table briefly describes the application event methods that you can implement in Application.CFC:
Method name

Method runs when

onAbort

Runs when you execute the tag cfabort

onApplicationEnd

The application ends: the application times out, or the
server is stopped

onApplicationStart

The application first starts: the first request for a page is
processed or the first CFC method is invoked by an
event gateway instance, or a web services or Flash
Remoting CFC.

onCFCRequest

HTTP or AMF calls are made to an application.

onError

An exception that is not caught by a try/catch block
occurs.

onMissingTemplate

ColdFusion received a request for a non-existent page.

onRequest

The onRequestStart method finishes. (This method
can filter request contents.)

onRequestEnd

All pages in the request have been processed:

onRequestStart

A request starts

onSessionEnd

A session ends

onSessionStart

A session starts

onServerStart

A ColdFusion server starts

All parameters to these methods are positional. You can use any names for these parameters.
When a request executes, ColdFusion runs the CFC methods in the following order:
1.
2.
3.
4.
5.

onApplicationStart (if not run before for this application)
onSessionStart (if not run before for this session)
onRequestStart
onRequest/onCFCRequest
onRequestEnd
The onApplicationEnd, onSessionEnd, and onError CFCs are triggered by specific events.
#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

2753

Adobe ColdFusion Documentation

onAbort
Description
Runs when you execute the tag cfabort.
Note
If showError attribute is specified in cfabort, onError method is executed instead of OnAbort.

Note
When using cfabort, cflocation, or cfcontent tags, the OnAbort method is invoked
instead on OnRequestEnd.

Returns
Nothing
Syntax



...



Parameters
Parameter

Description

targetPage

The path from the web root to the requested CFML
page.

Example
Application.cfc

© 2014 Adobe Systems Incorporated. All rights reserved.

2754

Adobe ColdFusion Documentation




 Target Page: #targetPage#




Test.cfm



#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

2755

Adobe ColdFusion Documentation

onApplicationEnd
Description
Runs when an application times out or the server is shutting down.
Syntax



...


See also
onApplicationStart, Method summary, Managing the application with Application.cfc in Defining the
application and its event handlers in Application.cfc in the Developing ColdFusion Applications
Parameters
ColdFusion passes the following parameters to the method:
Parameters

Description

ApplicationScope

The application scope.

Returns
This method does not return a value; do not use the cfreturn tag.
Usage
Use this method for any clean-up activities that your application requires when it shuts down, such as saving data in
memory to a database, or to log the application end to a file. You cannot use this method to display data on a user
page, because it is not associated with a request. The application ends, even if this method throws an exception.If
you call this method explicitly, ColdFusion does not end the application; it does execute the method code, but does
not lock the Application scope while the method executes.Use the ApplicationScope parameter to access the
application scope; you cannot reference the scope directly; for example, use
Arguments.ApplicationScope.myVariable, not Application.myVariable. This method can access the Server scope
directly, but it does not have access to Session or Request scopes.
Note
The application times out only if it is inactive for the time-out period. Sessions do not end, and
the onSessionEnd method is not called when an application ends. For more information, see o
nSessionEnd.

Example

© 2014 Adobe Systems Incorporated. All rights reserved.

2756

Adobe ColdFusion Documentation






#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

2757

Adobe ColdFusion Documentation

onApplicationStart
Description
Runs when ColdFusion receives the first request for a page in the application.
Syntax


...



See also
onApplicationEnd, Method summary, Managing the application with Application.cfc in Defining the application
and its event handlers in Application.cfc in the Developing ColdFusion Applications
Returns
A Boolean value: True if the application startup code ran successfully; False, otherwise. You do not need to explicitly
return a True value if you omit the cffunction tag returntype attribute.
Usage
Use this method for application initialization code; for example, use it to set Application scope variables, to
determine whether a required data source or other resource is available, or to log the application start. You do not
have to lock the Application scope if you set Application variables in this method, and you can reference Application
scope variables as you normally do; for example, as Application.myVariable. This method can access the requested
page's Variables scope only if the Application.cfc file includes an onRequest method that calls the page. If you call
this method explicitly, ColdFusion does not start the application; it does execute the method code, but does not lock
the Application scope while the method executes.If this method throws an uncaught exception or returns False, the
application does not start and ColdFusion does not process any pages in the application. In this case, ColdFusion
runs the onApplicationStart method the next time a user requests a page in the application.
Example
The following example tests for the availability of a database. If the database is not available it reports and logs the
error, and does not start the application; if it is available, the method initializes two Application scope variables.

© 2014 Adobe Systems Incorporated. All rights reserved.

2758

Adobe ColdFusion Documentation





SELECT Emp_ID FROM employee




This application encountered an error

Please contact support.








Application.availableResources=0;
Application.counter1=1;




#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

2759

Adobe ColdFusion Documentation

onCFCRequest
Description
Intercepts any HTTP or AMF calls to an application based on CFC request.
Syntax







See also
Method summary, Handling errors in Application.cfc in Defining the application and its event handlers in
Application.cfc in the Developing ColdFusion Applications
Parameters
ColdFusion passes the following parameters to the method:
Parameter

Description

cfcname

Fully qualified dotted path to the CFC.

method

The name of the method invoked.

args

The arguments (struct) with which the method is
invoked.

Usage
Whereas onRequest handles only requests made to ColdFusion templates, this function controls Ajax, Web Service,
and Flash Remoting requests.
Example
Create a folder onCFCRequest in your web root. Place test.cfc and Application.cfm in this directory and make an
HTTP call to the CFC using the following URL:http://localhost:8500/onCFCRequest/test.cfc?method=foo&arg1=1&ar
g2=2&arg3=3When you run the URL, the method onCFCRequest is called and the function name foo is passed
along with the arguments arg1, arg2, and arg3.You can then invoke the test.cfc as shown in the following
example:

© 2014 Adobe Systems Incorporated. All rights reserved.

2760

Adobe ColdFusion Documentation




























#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

2761

Adobe ColdFusion Documentation

onError
Description
Runs when an uncaught exception occurs in the application.
Syntax




...


See also
Method summary, Handling errors in Application.cfc in Defining the application and its event handlers in
Application.cfc in the Developing ColdFusion Applications
Parameters
ColdFusion passes the following parameters to the method:
Parameter

Description

Exception

The ColdFusion Exception object. For information on
the structure of this object, see the description of the c
fcatch variable in the cfcatch description.

EventName

The name of the event handler that generated the
exception. If the error occurs during request processing
and you do not implement an onRequest method,
EventName is the empty string.

Returns
This method does not return a value; do not use the cfreturn tag.
Usage
Use this method to handle errors in an application-specific manner. This method overrides any error handlers that
you set in the ColdFusion Administrator or in cferror tags. It does not override try/catch blocks.Whether the onEr
ror method can display output depends on where the error takes place, as follows:
The onError method can display a message to the user if an error occurs during an onApplicationStar
t, onSessionStart, onRequestStart, onRequest, or onRequestEnd event method, or while
processing a request.
The onError method cannot display output to the user if the error occurs during an onApplicationEnd or
onSessionEnd event method, because there is no available page context; however, it can log an error

© 2014 Adobe Systems Incorporated. All rights reserved.

2762

Adobe ColdFusion Documentation

message.
If the onError event handler is triggered by a scope-specific event method, such as onSessionStart, the
error prevents further processing at the level of that scope and any lower scopes. An onError event
triggered by an onSessionStart method, for example, prevents further processing in the session, but not in
the application.If an exception occurs while processing the onError method, or if the onError method uses
a cfthrow tag, the ColdFusion standard error handling mechanisms handle the exception. These
mechanisms include: any error handlers specified by cferror tags in the Application.cfc initialization code,
the site-wide error handler specified in the ColdFusion Administrator, and ColdFusion default error page.
Therefore, you can use the onError method as a filter to handle selected errors, and use other ColdFusion
error-handling techniques for the remaining errors.
Example











An unexpected error occurred.
Please provide the following information to technical support:
Error Event: #Arguments.EventName#
Error details:






#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

2763

Adobe ColdFusion Documentation

onMissingTemplate
Description
Runs when a request specifies a non-existent CFML page.
Syntax



...



See also
Method summary, Handling errors in Application.cfc in Defining the application and its event handlers in
Application.cfc in the Developing ColdFusion Applications
Parameters
ColdFusion passes the following parameters to the method:
Parameter

Description

targetPage

The path from the web root to the requested CFML
page.

Returns
A Boolean value. True or no return value specifies that the event has been processed. False specifies that the
event was not processed.
Usage
ColdFusion invokes this method when it encounters a file not found condition, that is, when a URL specifies a CFML
page that does not exist. The onMissingTemplate function must return true to indicate that the event has been
processed, or return false to indicate that the event has not been processed. If the function does not return a
value, it is assumed to be true. If the function returns false, ColdFusion invokes the standard error handler. If an
error occurs within the onMissingTemplate function, the error handler is not invoked. Therefore, you must use
try/catch blocks in your missing template handler and, if the catch block cannot handle the error, it must set the
function return value to false so the standard error handler can report the error. If the onMissingTemplate functi
on is invoked, the onApplicationStart and onSessionStart event handlers are first invoked, if appropriate,
but the onRequestStart, onRequest and onRequestEnd handlers are not invoked, and processing of the
request terminates when the onMissingTemplate handler returns.All standard scopes, including the Application,
Session, and Client scopes, are available in the onMissingTemplate function, if they are enabled.To include the
contents of a page in the onMissingTemplate function, use the cfinclude tag. Do not any other method to

© 2014 Adobe Systems Incorporated. All rights reserved.

2764

Adobe ColdFusion Documentation

include or redirect other page content, including tags and functions such as cflocation, GetPageContext().fo
rward(), and GetPageContext().include().}}Use the {{This.welcomeFileList variable to keep this
function from executing if all of the following are true:
Your web server uses a welcome file list with one or more CFML files (such as index.cfm), that it tries to
access when a user enters a URL that ends with a directory name
The web server sends a request for a CFML page on the welcome list to ColdFusion without first determining
if the page exists.
You want to allow users to browse web directories that do not have any files on the list.
For more information, see welcomeFileList in Application variables.
Example











#Arguments.targetPage# could not be found.
You requested a non-existent ColdFusion page.

Please check the URL.









#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

2765

Adobe ColdFusion Documentation

onRequest
Description
Runs when a request starts, after the onRequestStart event handler. If you implement this method, it must explic
itly call the requested page to process it.
Syntax



...

...


See also
onRequestStart, onRequestEnd, Method summary, Managing requests in Application.cfc in Defining the
application and its event handlers in Application.cfc in the Developing ColdFusion Applications
Parameters
ColdFusion passes the following parameters to the method:
Parameter

Description

targetPage

Path from the web root to the requested page.

Returns
This method does not return a value; do not use the cfreturn tag.
Usage
This event handler provides an optional request filter mechanism for CFML page requests (that is, .cfm pages
requested using a browser). Use it to intercept requests to target pages and override the default behavior of running
the requested pages. The following rules specify where and how you use the onRequest method.
Implement this method only if the following are true:
The directory, and any subdirectories affected by this Application.cfc contain CFM files. The affected
directory and subdirectories do not contain any CFC files that are intended to be accessed as web
services, AJAX bind, using Flash Remoting, or using an event gateway.
You want to intercept the request and process it in a special way.
If you do not implement this method, ColdFusion automatically calls the target page (or the CFC for a web
service, Flash Remoting, or event gateway event).
If you implement this method, it must explicitly call the target page, normally by using a cfinclude tag.
Do not implement the onRequest method in any Application.cfc file that affects .cfc files that implement web
services, process Flash Remoting or event gateway requests; ColdFusion does not execute the requests if
you implement this method.

© 2014 Adobe Systems Incorporated. All rights reserved.

2766

Adobe ColdFusion Documentation

Code in this method that precedes the call to the target page can perform the same functions as the onRequ
estStart method, and shares the Variables scope with the target page.
Code in this method that follows the call to the target page can perform the same functions as the onReques
tEnd method, and shares the Variables scope with the target page.
If you implement this method, you can also implement the onRequestStart and onRequestEnd methods.
You can use this method to do preprocessing that is required for all requests. Typical uses include filtering
and modifying request page contents (such as removing extraneous white space), or creating a switching
mechanism that determines the exact page to display based on available parameters.
Example








#replace(content, "report", "MyCompany Quarterly Report", "all")#



#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

2767

Adobe ColdFusion Documentation

onRequestEnd
Description
Runs at the end of a request, after all other CFML code.
Syntax



...


See also
onRequestStart, onRequest, Method summary, Managing requests in Application.cfc in Defining the application
and its event handlers in Application.cfc in the Developing ColdFusion Applications
Parameters
ColdFusion passes the following parameters to the method:
Parameter

Description

targetPage

Path from the web root to the requested page.

Returns
This method does not return a value; do not use the cfreturn tag.
Usage
This method has the same purpose as the onRequestEnd.cfm page. (You cannot use an onRequestEnd.cfm page if
you have an Application.cfc file for your application.) This method runs before the request terminates; therefore, it
can access the page context, and can generate output.This method can be useful for gathering performance
metrics, or for displaying dynamic footer information.This method can access the requested page's Variables scope
only if the Application.cfc file includes an onRequest method that calls the page. You can use Request scope
variables to share data with the requested page, even if the Application.cfc file does not have an onRequest metho
d.If you call this method explicitly, ColdFusion does not end the request, but does execute the method code.
Example
The following example displays one of two footer pages depending on whether the user has logged in:The onReque
stEnd method in Application.cfc contains the following code:

© 2014 Adobe Systems Incorporated. All rights reserved.

2768

Adobe ColdFusion Documentation











A simple authuserfooter.cfm page consists of the following code:


Thank you for shopping at our store, #theAuthUser#!


A simple noauthuserfooter.cfm page consists of the following code:


Remember, only registered users get all our benefits!


To test this example, implement code for logging in a user, or try the example with and without the following line in
the onRequestStart Application.cfc method:



#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

2769

Adobe ColdFusion Documentation

onRequestStart
Description
Runs when a request starts.
Syntax



...



See also
onRequest, onRequestEnd, Method summary, Managing requests in Application.cfc in Defining the application
and its event handlers in Application.cfc in the Developing ColdFusion Applications
Parameters
ColdFusion passes the following parameters to the method:
Parameters

Description

targetPage

Path from the web root to the requested page.

Returns
A Boolean value. Return False to prevent ColdFusion from processing the request. You do not need to explicitly
return a True value if you omit the cffunction tag returntype attribute.
Usage
This method runs at the beginning of the request. It is useful for user authorization (login handling), and for
request-specific variable initialization, such as gathering performance statistics.If this method throws an exception
(for example, if it uses the cfthrow tag), ColdFusion handles the error and does not process the request further.If
you call this method explicitly, ColdFusion does not start a request, but does execute the method code.This method
can access the requested page's Variables scope only if the Application.cfc file includes an onRequest method that
calls the page. You can use Request scope variables to share data with the requested page even if Application.cfc
does not have an onRequest method.
Example
This example uses the authentication code generated by the ColdFusion Dreamweaver Login wizard to ensure that
the user is logged in. The wizard generates code that is appropriate for Application.cfm only. To use this code with
the Application.CFC, delete the generated Application.CFM

© 2014 Adobe Systems Incorporated. All rights reserved.

2770

Adobe ColdFusion Documentation





if ((Hour(now()) gt 1) and (Hour(now()) lt 3)) {
WriteOutput("The system is undergoing periodic maintenance.
Please return after 3:00 AM Eastern time.");
return false;
} else {
this.start=now();
return true;
}



#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

2771

Adobe ColdFusion Documentation

onServerStart
Note
Despite being documented in this section of the manual, this onServerStart method is NOT a
method of Application.cfc. See below for more details on where, why, and how to use this
method.

ColdFusion now supports a CFC with an onServerStart method that runs only when the server starts. The
onServerStart method takes no parameters, and is the only function in the CFC. The function is useful for
application-independent tasks, such as instantiating the applications, configuring logging, or setting up the
scheduler.
By default, ColdFusion looks for the onServerStart method in cf_webroot/Server.cfc. To specify a different
filepath:
1. Launch ColdFusion Administrator.
2. Click ColdFusion Administrator Server Settings > Settings.
3. Specify the absolute filepath under the web root on the Settings page such as c:\Server.cfc. Alternatively, you
can use a dot-delimited path under the web root, such as a.b.Server.
Note
If you use an absolute path, the filename must end with .cfc. If you use a relative path or
dotted path, do not end the name with the .cfc suffix.

You select an option on the Settings page to enable and disable the onServerStart method. By default, the
method is disabled.
You can also specify a timeout limit (in seconds) for the onServerStart method. The timeout limit determines
the duration for which the method would be allowed to run during server start up. This setting can be
specified in server.cfc.
The onServerStart method can use most CFML features, but not any features that require full server start.
For example, the method cannot use a cfhttp tag with a URL that specifies a location on the same server.
You also cannot use Application or Request scope variables in the method.
By default, all errors, including any serverCFC errors, are logged in /WEB-INF/cfus
ion/logs directory for standalone and /logs directory for J2EE configurations.
You can also specify a different location for logging by configuring the log directory setting in ColdFusion
Administrator > Debugging and Logging > Logging Settings.
The server.log file contains server startup information. So,
any server.CFC startup errors are logged in it, but for details
about the error, you have to see the exception.log file. In addition,
server startup information is logged in {appserver_root}/logs directory.
For WebSphere, it is logged in the SystemOut.log file.

© 2014 Adobe Systems Incorporated. All rights reserved.

2772

Adobe ColdFusion Documentation

onSessionEnd
Description
Runs when a session ends.
Syntax




...


See also
onSessionStart, Method summary, Managing requests in Application.cfc in Defining the application and its event
handlers in Application.cfc in the Developing ColdFusion Applications
Parameters
ColdFusion passes the following parameters to the method:
Parameter

Description

SessionScope

The Session scope

ApplicationScope

The Application scope

Returns
This method does not return a value; do not use the cfreturn tag.
Usage
Use this method for any clean-up activities when the session ends. A session ends when the session is inactive for
the session time-out period. You can, for example, save session-related data, such as shopping cart contents or
whether the user has not completed an order, in a database, or do any other required processing based on the
user's status. You might also want to log the end of the session, or other session-related information, to a file for
diagnostic use.If you call this method explicitly, ColdFusion does not end the session; it does execute the method
code, but does not lock the Session.You cannot use this method to display data on a user page, because it is not
associated with a request.You can access shared scope variables as follows:
Use the SessionScope parameter to access the Session scope. You cannot reference the Session scope
directly; for example, use Arguments.SessionScope.myVariable, not Session.myVariable.
You must use the ApplicationScope parameter to access the Application scope. You cannot reference the
Application scope directly; for example, use Arguments.ApplicationScope.myVariable, not
Application.myVariable. Use a named lock when you reference variables in the Application scope, as shown
in the example.
You can access the Server scope directly; for example, Server.myVariable.

© 2014 Adobe Systems Incorporated. All rights reserved.

2773

Adobe ColdFusion Documentation

You cannot access the Request scope.
Sessions do not end, and the onSessionEnd method is not called when an application ends. The onSessi
onEnd does not execute if there is no active application, however.
Example
The following method decrements an Application scope session count variable and logs the session length.











#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

2774

Adobe ColdFusion Documentation

onSessionStart
Description
Runs when a session starts.
Syntax


...


See also
onSessionEnd, Method summary, Managing requests in Application.cfc in Defining the application and its event
handlers in Application.cfc in the Developing ColdFusion Applications
Returns
This method does not return a value; do not use the cfreturn tag.
Usage
This method is useful for initializing Session scope data, such as a shopping cart, or setting session-specific
Application scope variables, such as for tracking the number of active sessions. You need not lock the Session
scope to set its variables using this method.If you call this method explicitly, ColdFusion does not start a session; it
does execute the method code, but does not lock the Session scope.This method can access the requested page's
Variables scope only if the Application.cfc file includes an onRequest method that calls the page.
Example
The following onSessionStart example initializes some Session scope variables and increments an Application
scope counter of active sessions.



Session.started = now();
Session.shoppingCart = StructNew();
Session.shoppingCart.items =0;






#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

2775

Adobe ColdFusion Documentation

ColdFusion Event Gateway Reference
Java interfaces are available for building ColdFusion custom CFXs in Java.
Note
The following CFML functions also apply to gateway application development: GetGatewayHel
per, SendGatewayMessage.

addEvent
CFEvent
CFEventclass
Constructor
Gateway development interfaces and classes
GatewayHelper interface
Gateway interface
GatewayServices class
getCFCMethod
getCFCPath
setCFCTimeout
getCFCTimeout
getData
getGatewayID
getGatewayID_1
getGatewayServices
getGatewayType
getHelper
getLogger
getMaxQueueSize
getOriginatorID
setCFCMethod
setCFCPath
getQueueSize
getStatus
outgoingMessage
restart
setCFCListeners
setData
setGatewayID
setGatewayType
setOriginatorID
start
stop
Logger class
debug
error
fatal
info
warn
CFML CFEvent structure
IM gateway methods and commands
IM Gateway CFC incoming message methods

© 2014 Adobe Systems Incorporated. All rights reserved.

2776

Adobe ColdFusion Documentation

onAddBuddyRequest
onAddBuddyResponse
onBuddyStatus
onIMServerMessage
onIncomingMessage
IM Gateway GatewayHelper class methods
IM gateway message sending commands
addBuddy
addDeny
addPermit
getBuddyInfo
getBuddyList
getCustomAwayMessage
getDenyList
getName
getNickName
getPermitList
getPermitMode
getProtocolName
getStatusAsString
getStatusTimeStamp
numberOfMessagesReceived
numberOfMessagesSent
removeBuddy
removeDeny
removePermit
setNickName
setPermitMode
setStatus
SMS Gateway CFEvent structure and commands
SMS Gateway incoming message CFEvent structure
SMS gateway message sending commands
submit command
submit Multi command
data command
CFML event gateway SendGatewayMessage data parameter
#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

2777

Adobe ColdFusion Documentation

addEvent
Description
Sends a CFEvent instance to ColdFusion for dispatching to a listener CFC.
Category
Event Gateway Development
Syntax

boolean addEvent(CFEvent msg)

See also
getMaxQueueSize, getMaxQueueSize, Responding to incoming messages in Building an event gateway i
n the Developing ColdFusion Applications
Parameters
Parameter

Description

msg

The CFEvent object containing the message to be
queued for delivery to the listener CFC.

Returns
True if the event was added to the gateway services queue for delivery, false, otherwise. Therefore, a true response
does not indicate that the message was delivered.
Usage
The event gateway must use this method to send incoming messages to the application for processing.
Example
The following example from the ColdFusion SocketGateway code sends an event to all listener CFCs:

© 2014 Adobe Systems Incorporated. All rights reserved.

2778

Adobe ColdFusion Documentation

for (int i = 0; i < listeners.length; i++) {
String path = listeners[i];
CFEvent event = new CFEvent(gatewayID);
Hashtable mydata = new Hashtable();
mydata.put("MESSAGE", theInput);
event.setData(mydata);
event.setGatewayType("SocketGateway");
event.setOriginatorID(theKey);
event.setCfcMethod(cfcEntryPoint);
event.setCfcTimeOut(10);
if (path != null)
event.setCfcPath(path);
boolean sent = gatewayService.addEvent(event);
if (!sent)
log.error("SocketGateway(" + gatewayID + ") Unable to put message on
event queue. Message not sent from " + gatewayID + ", thread " +
theKey + ".Message was " + theInput);
}

#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

2779

Adobe ColdFusion Documentation

CFEvent
Description
CFEvent constructor.
Category
Event Gateway Development
Syntax

CFEvent(String gatewayID)

See also
getGatewayID, CFML CFEvent structure, CFEvent class in the Developing ColdFusion Applications
Parameters
Parameter

Description

gatewayID

The ID of the gateway. This parameter indicates the
source of the message and must be the value that is
passed in the Gateway constructor or set using the
Gateway setGatewayID method. The SMS gateway
ID must be 21 characters or fewer.

Usage
This method creates a container for an event gateway message that you send to ColdFusion gateway services in a
gatewayServices.addEvent method for delivery to a CFC listener method.
Example
The following example, based on code for the ColdFusion asynchronous CFML gateway, sends a message to that
the gateway has received to a CFC:

© 2014 Adobe Systems Incorporated. All rights reserved.

2780

Adobe ColdFusion Documentation

public String outgoingMessage(coldfusion.eventgateway.CFEvent cfmsg)
{
// Get the data
Map data = cfmsg.getData();
boolean status = true;
if (data != null)
{
// create an event
CFEvent event = new coldfusion.eventgateway.CFEvent(gatewayID);
//set the event field values
event.setGatewayType("CFMLGateway");
event.setOriginatorID("CFMLGateway");
event.setData(data);
// send it to the event service
status = gatewayService.addEvent(event);
}
return new Boolean(status).ToString();
}

#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

2781

Adobe ColdFusion Documentation

CFEventclass
coldfusion.gateway.CFEvent

The Gateway class sends and receives CFEvent instances to communicate with the ColdFusion listener CFC or
application. The CFEvent instances correspond to CFML CFEvent structure that ColdFusion application listener
CFC methods receive and contain the message structures that ColdFusion application code sends to the gateway.
The Gateway notifies ColdFusion of a message by sending a CFEvent instance in GatewayServices.addE
vent method.
The Gateway receives a CFEvent instance when ColdFusion calls the gateway's outgoingMessage method
.
The CFEvent Class extends the java.util.Hashtable class and has the following methods:
Methods

Description

CFEvent(String gatewayID)

CFEvent constructor.

String getGatewayID()

Returns the gateway ID (set in the CFEvent
constructor).

void setCFCMethod(String method)String get
CFCMethod()

Sets or gets the name of the CFC method that receives
an incoming message.

void setCFCPath(String path)String getCFC
Path()

Sets or gets the path to the application listener CFC
that processes the event.

void setCFCTimeout(String seconds)String
getCFCTimeout()

Sets or gets the time-out, in seconds, for the listener
CFC to process the event request.

void setData(Map data)Map getData()

Sets or gets the event data structure, which contains
the message contents and any other gateway-specific
information.

void setGatewayType(String type)String ge
tGatewayType()

Sets or gets the event gateway type identifier, such as
SMS.

void setOriginatorID(String id)String get
OriginatorID()

Sets or gets the gateway- or protocol-specific Identity of
the originator of a message.

#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

2782

Adobe ColdFusion Documentation

Constructor
Description
Instantiates a gateway.
Category
Event Gateway Development
Syntax

public void gatewayName()
public void gatewayName(String id)
public void gatewayName(String id, String configFile)

See also
setGatewayID, Class constructor in Building an event gateway in the Developing ColdFusion Applications.
Parameters
Parameter

Description

id

The identifier for the gateway instance

configFile

The absolute path to the gateway configuration file.

Usage
If your gateway requires a configuration file, use the constructor with two parameters. Otherwise, you can use either
the default constructor or the single parameter version; ColdFusion always uses the setGatewayID method to set
the ID.
Example
The following example shows the two argument constructor implemented in the ColdFusion SocketGateway class:

© 2014 Adobe Systems Incorporated. All rights reserved.

2783

Adobe ColdFusion Documentation

public SocketGateway(String id, String configpath) {
propsFilePath=configpath;
try {
FileInputStream propsFile = new FileInputStream(propsFilePath);
properties.load(propsFile);
propsFile.close();
this.loadProperties();
}
catch (FileNotFoundException f) {
// do nothing. use default value for port.
}
catch (IOException e) {
e.printStackTrace();
}
gatewayID = id;
gatewayService = GatewayServices.getGatewayServices();
}

#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

2784

Adobe ColdFusion Documentation

Gateway development interfaces and classes
The ColdFusion event gateway system is defined in the coldfusion.eventgateway package. Gateway developers
implement two interfaces and use several classes, as follows:

#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

2785

Adobe ColdFusion Documentation

GatewayHelper interface
coldfusion.eventgateway.GatewayHelper
ColdFusion includes a coldfusion.eventgateway.GatewayHelper Java marker interface, with no methods. Implement
this interface to define a class that provides gateway-specific utility methods to the ColdFusion application or listener
CFC. For example, an instant messaging event gateway might use a helper class to provide buddy list management
methods to the application. The Gateway class must implement a getHelper method that returns the helper class,
or null if you do not implement the interface.
For information on GatewayHelper classes, see GatewayHelper class.

#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

2786

Adobe ColdFusion Documentation

Gateway interface
coldfusion.eventgateway.Gateway

Interface for implementing ColdFusion event gateways.
A class that implements this interface defines a ColdFusion event gateway type that you can use in ColdFusion
applications. The class must implement the following methods:
Signature

Description

GatewayName([String id[,
StringconfigFile]])

The gateway constructor.

String getGatewayID()

Returns the gateway ID.

GatewayHelper getHelper()

Returns an instance of the GatewayHelper class for
this gateway type. instance, or null if the gateway does
not have a GatewayHelper class.

int getStatus()

Gets the event gateway status.

String outgoingMessage(coldfusion.eventg
ateway.CFEvent cfmessage)

Handles a message sent by ColdFusion and processes
it to send to a message receiver.

void restart()

Restarts a running event gateway.

void setCFCListeners(String[] listeners)

Identifies the CFCs that listen for incoming messages
from the event gateway.

void setGatewayID(String id)

Sets the gateway ID that uniquely identifies the
Gateway instance.

void start()

Starts the event gateway.

void stop()

Stops the event gateway.

#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

2787

Adobe ColdFusion Documentation

GatewayServices class
coldfusion.eventgateway.GatewayServices

The Gateway class uses the coldfusion.eventgateway.GatewayServices class to interact with the ColdFusion event
gateway services. This class has the following methods:
Signature

Description

GatewayServices getGatewayServices()

Static method that returns the GatewayServices object.

boolean addEvent(CFEvent msg)

Sends a CFEvent instance to ColdFusion for
dispatching to a listener CFC.

coldfusion.eventgateway.LoggergetLogger([
String logfile])

Returns a ColdFusion logger object that the event
gateway can use to log information in a file.

int getMaxQueueSize()

Returns the maximum size of the ColdFusion event
queue, as set in the ColdFusion Administrator.

int getMaxQueueSize()

Returns the current size of the ColdFusion event queue
that handles all messages for all gateways.

#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

2788

Adobe ColdFusion Documentation

getCFCMethod
Description
Gets the name of the CFC method that processes the message.
Category
Event Gateway Development
Syntax

String getCFCMethod()

See also
getCFCPath, getCFCTimeout, setCFCMethod, CFML CFEvent structure, CFEvent class in Event gateway
elements in the Developing ColdFusion Applications
Returns
For incoming messages, the name of the method that gateway services call in the listener CFC, as set by the setCF
CMethod method. If setCFCMethod has not been called, returns null, and not onIncomingMessge, which
ColdFusion gateway services uses by default. Outgoing messages that are returned by a CFC in response to an
incoming message also have the CFC method name in this field if the gateway set the field on the incoming
message.
Usage
Most event gateways do not need to use this method. This method could be useful if a gateway sends messages to
multiple CFC Methods and must determine which method is responding.
#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

2789

Adobe ColdFusion Documentation

getCFCPath
Description
Gets the path to the listener CFC that processes this message.
Category
Event Gateway Development
Syntax

String getCFCPath()

See also
getCFCMethod, getCFCTimeout, setCFCPath, CFML CFEvent structure, CFEvent class in Event gateway
elements in the Developing ColdFusion Applications
Returns
An absolute path to the application listener CFC that processes the event, as set by the setCFCPath method. If the
setCFCPath method has not been called, returns null, not the path specified in the ColdFusion Administrator and
used by default by gateway services. Outgoing messages that are returned by a CFC in response to an incoming
message also have the CFC method name in this field if the gateway set the field on the incoming message.
Usage
Most event gateways do not need to use this method. This method could be useful if a gateway sends messages to
multiple CFCs and must determine which CFC is responding.---#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

2790

Adobe ColdFusion Documentation

setCFCTimeout
Description
Sets the time-out, in seconds, during which the listener CFC must process the event request and return before
ColdFusion gateway services terminates the request.
Category
Event Gateway Development
Syntax

void setCFTimeout(String timeout)

See also
getCFCTimeout, setCFCMethod, setCFCPath, CFEvent class in Event gateway elements in the Developing
ColdFusion Applications
Parameters
Parameter

Description

timeout

The CFC time-out period, in seconds.

Usage
When ColdFusion calls a listener CFC method to process the event, and the CFC does not return in the specified
time-out period, ColdFusion terminates the request and logs an error in the application.log file. If you do not use this
method, ColdFusion uses the Timeout Request value set on the Server Settings page in the ColdFusion
Administrator. Use this method if your messages require a longer or shorter time-out period than standard
ColdFusion HTML requests.
Example
The following example code is based on the Socket gateway processInput method that takes input from the socket
and sends it to the CFC listener methods. It sets the CFC time-out to 10 seconds.

© 2014 Adobe Systems Incorporated. All rights reserved.

2791

Adobe ColdFusion Documentation

for (int i = 0; i < listeners.length; i++)
{
String path = listeners[i];
CFEvent event = new CFEvent(gatewayID);
Hashtable mydata = new Hashtable();
mydata.put("MESSAGE", theInput);
event.setData(mydata);
event.setGatewayType("SocketGateway");
event.setOriginatorID(theKey);
event.setCfcMethod(cfcEntryPoint);
event.setCfcTimeOut(10);
if (path != null)
event.setCfcPath(path);
boolean sent = gatewayService.addEvent(event);
}

#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

2792

Adobe ColdFusion Documentation

getCFCTimeout
Description
Gets the time-out, in seconds, for the listener CFC to process the event request.
Category
Event Gateway Development
Syntax

String getCFCTimeout()

See also
getCFCMethod, getCFCPath, setCFCTimeout, CFML CFEvent structure, CFEvent class in Event gateway
elements in the Developing ColdFusion Applications
Returns
The listener CFC time-out, in seconds, as set by the setCFCTimeout method, or null.
Usage
Most gateways do not need to use this function.When ColdFusion calls a listener CFC method to process the event,
and the CFC does not process the event in the specified time-out period, ColdFusion terminates the request and
logs an error in application.log file. By default ColdFusion uses the Timeout Request value set on the Server
Settings page in the ColdFusion Administrator. ---#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

2793

Adobe ColdFusion Documentation

getData
Description
Returns the data Map that contains the message contents and other gateway-specific information.
Category
Event Gateway Development
Syntax

Map getData()

See also
setData, CFML CFEvent structure, CFEvent class in Event gateway elements in the Developing ColdFusion
Applications
Returns
The event data structure, or null. This structure includes the message contents being passed by the gateway and
any other gateway-specific information.
Usage
The contents of the data Map depends on the event gateway type. Typical fields include the message contents,
originator ID, destination ID, and if a gateway (such as the ColdFusion SMS gateway) supports multiple commands,
the command.
Note
The returned Map object has case-insensitive keys.

Example
The following outgoingMessage method from the SocketGateway example gateway gets the message contents from
the CFEvent data field of an outgoing message. If the CFEvent object does not include an OriginatorID field, it also
tries to get the originator ID from the data field.

© 2014 Adobe Systems Incorporated. All rights reserved.

2794

Adobe ColdFusion Documentation

public String outgoingMessage(coldfusion.eventgateway.CFEvent cfmsg)
{
String retcode="ok";
// Get the table of data returned from the event handler
Map data = cfmsg.getData();
String message = (String) data.get("MESSAGE");
// find the right socket to write to from the socketRegistry hashtable
if (cfmsg.getOriginatorID() != null)
((SocketServerThread)socketRegistry.get(cfmsg.getOriginatorID())).
writeOutput(message);
else if (data.get("OriginatorID") != null)
((SocketServerThread)socketRegistry.get(data.get("OriginatorID"))).
writeOutput(message);
else {
System.out.println("cannot send outgoing message. OriginatorID is not
available.");
retcode="failed";
}
return retcode;
}

#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

2795

Adobe ColdFusion Documentation

getGatewayID
Description
Returns the gateway ID that identifies the Gateway instance.
Category
Event Gateway Development
Syntax

public String getGatewayID()

See also
setGatewayID, Providing Gateway class service and information routines in Building an event
gateway in the Developing ColdFusion Applications.
Usage
This method returns a string value that is set by the setGatewayID method.
Example
The following example is the ColdFusion SocketGateway class getGatewayID method:

public String getGatewayID()
{
return gatewayID;
}

#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

2796

Adobe ColdFusion Documentation

getGatewayID_1
Description
Returns the gateway ID field of the CFEvent object.
Category
Event Gateway Development
Syntax

String getGatewayID(CFEvent event)

See also
CFEvent, CFML CFEvent structure, CFEvent class in Event gateway elements in the Developing ColdFusion
Applications
Returns
The gateway ID of the CFEvent object, or null.
Usage
Most gateways do not need to use this method. The gateway ID is set in the CFEvent constructor and normally
corresponds to the gateway that is handling the event.---#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

2797

Adobe ColdFusion Documentation

getGatewayServices
Description
Static method that returns the GatewayServices object. Gateway code can call this method at any time, if
necessary.
Category
Event Gateway Development
Syntax

GatewayServices getGatewayServices()

See also
GatewayServices class in the Developing ColdFusion Applications
Returns
The GatewayServices object.
Usage
Gateway constructors can call this method to get a convenient reference to the GatewayServices class and its
methods.
Example
The following Socket gateway constructor code sets the GatewayServices variable:

public SocketGateway(String id)
{
gatewayID = id;
gatewayService = GatewayServices.getGatewayServices();
}

Calls to GatewayServices methods, such as the following, use the returned value.

boolean sent = gatewayService.addEvent(event);

#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

2798

Adobe ColdFusion Documentation

getGatewayType
Description
Returns the gateway type field of the CFEvent object.
Category
Event Gateway Development
Syntax

String getGatewayType()

See also
setGatewayType, CFML CFEvent structure, CFEvent class in Event gateway elements in the Developing
ColdFusion Applications
Returns
The gateway type of the CFEvent object, or null.
Usage
Most gateways do not need to use this method.---#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

2799

Adobe ColdFusion Documentation

getHelper
Description
Returns an instance of the gatewayHelper class, if any for the gateway type.
Category
Event Gateway Development
Syntax

public GatewayHelper getHelper()

See also
GatewayHelper interface; Providing Gateway class service and information routines in Building an
event gateway in the Developing ColdFusion Applications.
Returns
A coldfusion.eventgateway.GatewayHelper class instance, or null if the gateway does not have a GatewayHelper
class.
Usage
ColdFusion calls this method when a ColdFusion application calls the CFML GetGatewayHelper function. The
application then uses the gatewayHelper object methods to call gateway-specific utility methods, such as instant
message buddy management methods.
Example
The following example is the ColdFusion SocketGateway class getHelper method:

public GatewayHelper getHelper()
{
// SocketHelper class implements the GatewayHelper interface
return new SocketHelper();
}

#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

2800

Adobe ColdFusion Documentation

getLogger
Description
Returns a ColdFusion Logger object that the event gateway can use to log information in a file.
Category
Event Gateway Development
Syntax

coldfusion.eventgateway.Logger getLogger([String logfile])

See also
Logger class, Logging events and using log files in Building an event gateway the Developing ColdFusion
Applications
Parameters
Parameter

Description

logfile

The name, without an extension, of a log file in the
ColdFusion logs directory. ColdFusion automatically
appends a .log extension to the name. If the file does
not exist, ColdFusion creates it when it logs the first
message. By default, ColdFusion logs to the
eventgateway.log file.

Returns
A ColdFusion logger object
Usage
The Logger class has five methods: debug, info, warn, error, and fatal, that correspond to the severity level
that is set in the log message. Each method takes a message string, a Throwable class object, or both.If you pass a
Throwable object to these methods, ColdFusion writes the exception information in the exceptions.log file.
Example
The ColdFusion example DirectoryWatcherGateway includes the following line in the constructor to get a logger
object:

// We create our own log file, which will be named "watcher.log"
logger = gatewayService.getLogger("watcher");

© 2014 Adobe Systems Incorporated. All rights reserved.

2801

Adobe ColdFusion Documentation

The following code, from the start of the routine that loads information from the configuration file, uses this object to
log the initialization.

// Load the properties file to get our settings
protected void loadconfig() throws ServiceRuntimeException
{
// load config
logger.info("DirectoryWatcher (" + gatewayID + ") Initializing
DirectoryWatcher gateway with configuration file " + config);
.
.
.

#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

2802

Adobe ColdFusion Documentation

getMaxQueueSize
Description
Returns the maximum size of the ColdFusion event queue, as set in the ColdFusion Administrator.
Category
Event Gateway Development
Syntax

int getMaxQueueSize()

See also
addEvent, getQueueSize
Returns
The integer maximum number of messages that the gateway services queue can hold.
Usage
If the queue length reaches this value, the addEvent method does not add its message to the processing queue.
You can use this method and the getQueueSize method to control the rate of event queuing and to help diagnose
any throughput problems in your gateways.
Example
The following example logs the queue size, maximum queue size, and other information if a
gatewayService.addEvent method fails to queue a message for delivery to a listener CFC. (It uses an internal
method to construct the error message string.)

boolean sent = gatewayService.addEvent(cfmsg);
if (!sent)
{
logger.error(RB.getString(this, "IMGateway.cantAddToQueue",
gatewayType, gatewayID, ((path != null) ? path : "default"),
Integer.ToString(gatewayService.getQueueSize()),
Integer.ToString(gatewayService.getMaxQueueSize())));
}

#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

2803

Adobe ColdFusion Documentation

getOriginatorID
Description
Identifies the originator of an incoming message. Some gateway types also use this field for the destination of an
outgoing message.
Category
Event Gateway Development
Syntax

String getOriginatorID()

See also
setOriginatorID, CFML CFEvent structure, CFEvent class in Event gateway elements in the Developing
ColdFusion Applications
Returns
The protocol-specific identifier of the message originator, or null.
Example
The outgoingMessage method of the SocketGateway example gateway uses the getOriginatorID method to
determine the destination of an outgoing message. This way, a listener CFC that sends a response back to the
originator does not have to explicitly set a destination in the return variable. If the field is empty, (as it is in messages
sent by the CFML SendGatewayMessage function) the gateway tries to get the destination from the CFevent data
field.

© 2014 Adobe Systems Incorporated. All rights reserved.

2804

Adobe ColdFusion Documentation

public String outgoingMessage(coldfusion.eventgateway.CFEvent cfmsg)
{
String retcode="ok";
// Get the table of data returned from the event handler
Map data = cfmsg.getData();
String message = (String) data.get("MESSAGE");
// find the right socket to write to from the socketRegistry hashtable
if (cfmsg.getOriginatorID() != null)
((SocketServerThread)socketRegistry.get(cfmsg.getOriginatorID())).
writeOutput(message);
else if (data.get("OriginatorID") != null)
((SocketServerThread)socketRegistry.get(data.get("OriginatorID"))).
writeOutput(message);
else
{
System.out.println("cannot send outgoing message. OriginatorID is not
available.");
retcode="failed";
}
return retcode;
}

#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

2805

Adobe ColdFusion Documentation

setCFCMethod
Description
Sets the name of the CFC method that processes an incoming message.
Category
Event Gateway Development
Syntax

void setCFCMethod(String method)

See also
getCFCMethod, setCFCPath, setCFCTimeout, CFML CFEvent structure, CFEvent class in the Developing
ColdFusion Applications
Parameters
Parameter

Description

method

The method in the listener CFC that ColdFusion calls to
process this event. If you do not use this method in
your gateway, ColdFusion invokes the onIncomingMe
ssage method.

Usage
Gateways that use a single CFC listener method do not need to use this method if the listener CFC method is
named onIncomingMessage. For the sake of consistency, Adobe recommends that any event gateway with a
single listener not override this default. A gateway, such as the ColdFusion XMPP gateway, that uses different
listener methods for different message types uses this method to identify the destination method.
Example
The following example code comes from the ColdFusion XMPP gateway incoming message handler. It creates a
CFEvent object and sets the method that handles tests based on the message type.

© 2014 Adobe Systems Incorporated. All rights reserved.

2806

Adobe ColdFusion Documentation

CFEvent cfmsg = new CFEvent(gatewayID);
cfmsg.setOriginatorID(sender);
cfmsg.setGatewayType(gatewayType);
if(messageType == IMessage.IM)
{
// default for normal messages
cfmsg.setCfcMethod(onIncomingMessageFunction);
}
//if the message is an authorization request
else if(messageType == IMessage.AUTH_REQUEST)
{
cfmsg.setCfcMethod(onAddBuddyRequestFunction);
message = "Requesting authorization to add '" + recipient + "' to '"
+ sender + "' buddy list and view '" + recipient + "' presence.";
} // Code snipped here for brevity.

#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

2807

Adobe ColdFusion Documentation

setCFCPath
Description
Specifies the listener CFC that processes this event.
Category
Event Gateway Development
Syntax

void setCFCPath(String path)

See also
getCFCPath, setCFCMethod, setCFCTimeout, CFEvent class in the Developing ColdFusion Applications
Parameters
Parameter

Description

path

An absolute path to the application listener CFC that
processes the event. If you do not call this method in
your gateway, ColdFusion uses the first path
configured for the event gateway instance on the Event
Gateways page in the ColdFusion Administrator.

Usage
By default, ColdFusion delivers messages to the CFC in the first path configured for the event gateway instance on
the Event Gateways page in the ColdFusion Administrator.If your application supports multiple listener CFCs, use
this method to set each listener CFC and then call the gatewayService.addEvent method to send the event to
the CFC.
Example
The following example code is based on the Socket gateway processInput method that takes input from the socket
and sends it to the CFC listener methods. The listeners variable contains an array of listener CFCS and is set by the
gateways setCFCListeners method, which ColdFusion calls when it starts the gateway.

© 2014 Adobe Systems Incorporated. All rights reserved.

2808

Adobe ColdFusion Documentation

for (int i = 0; i < listeners.length; i++)
{
String path = listeners[i];
CFEvent event = new CFEvent(gatewayID);
Hashtable mydata = new Hashtable();
mydata.put("MESSAGE", theInput);
event.setData(mydata);
event.setGatewayType("SocketGateway");
event.setOriginatorID(theKey);
event.setCFCMethod(cfcEntryPoint);
event.setCFCTimeout(10);
if (path != null)
event.setCFCPath(path); boolean sent = gatewayService.addEvent(event);
}

#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

2809

Adobe ColdFusion Documentation

getQueueSize
Description
Returns the current size of the ColdFusion event queue that handles all messages for all gateways.
Category
Event Gateway Development
Syntax

int getQueueSize()

See also
addEvent, getMaxQueueSize
Returns
The integer number of messages in the gateway message queue that are waiting to be delivered to CFCs.
Usage
You can use this method and the getMaxQueueSize method to control the rate of event queuing and to help
diagnose any throughput problems in your gateways.
Example
The following example logs the queue size, maximum queue size, and other information if a
gatewayService.addEvent method fails to queue a message for delivery to a listener CFC. (It uses an internal
method to construct the error message string.)

boolean sent = gatewayService.addEvent(cfmsg);
if (!sent)
{
logger.error(RB.getString(this, "IMGateway.cantAddToQueue",
gatewayType, gatewayID, ((path != null) ? path : "default"),
Integer.ToString(gatewayService.getQueueSize()),
Integer.ToString(gatewayService.getMaxQueueSize())));
}

#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

2810

Adobe ColdFusion Documentation

getStatus
Description
Returns the gateway status.
Category
Event Gateway Development
Syntax

public int getStatus()

See also
Providing Gateway class service and information routines in the Developing ColdFusion Applications
Returns
An integer status value. The Gateway interface defines the following status constants:
STARTING
RUNNING
STOPPING
STOPPED
FAILED
Example
The following example is the ColdFusion SocketGateway class getStatus method:

public int getStatus()
{
return status;
}

#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

2811

Adobe ColdFusion Documentation

outgoingMessage
Description
Sends a message from ColdFusion to a message receiver.
Category
Event Gateway Development
Syntax

public String outgoingMessage(coldfusion.eventgateway.CFEvent message)

See also
Responding to a ColdFusion function or listener CFC in the Developing ColdFusion Applications
Parameters
Parameter

Description

message

A coldfusion.eventgateway.CFEvent instance
containing the message to be sent.

Returns
A gateway-specific string, such as a message ID or a status indicator.
Usage
This method handles a message sent by ColdFusion and processes it as needed by the gateway type to send a
message to the (usually external) message receiver. ColdFusion calls this method when the listener method of a
listener CFC returns a message or when a ColdFusion application calls the SendGatewayMessage function.
ColdFusion passes the String returned by this method back as the return value of a CFML SendGatewayMessage f
unction.
Example
The following example is the ColdFusion SocketGateway class outgoingMessage method:

© 2014 Adobe Systems Incorporated. All rights reserved.

2812

Adobe ColdFusion Documentation

public String outgoingMessage(coldfusion.eventgateway.CFEvent cfmsg)
{
String retcode="ok";
// Get the table of data returned from the event handler
Map data = cfmsg.getData();
String message = (String) data.get("MESSAGE");
// find the right socket to write to from the socketRegistry hashtable
if (cfmsg.getOriginatorID() != null && message != null)
{
SocketServerThread st =
((SocketServerThread)socketRegistry.get(cfmsg.getOriginatorID()));
if(st != null)
st.writeOutput(message);
else
{
log.error("Cannot send outgoing message. OriginatorID '" +
cfmsg.getOriginatorID() + "' is not a valid socket id.");
retcode="failed";
}
}
else if (data.get("OriginatorID") != null && message != null)
{
SocketServerThread st =
((SocketServerThread)socketRegistry.get(data.get("OriginatorID")));
if(st != null)
st.writeOutput(message);
else
{
log.error("Cannot send outgoing message. OriginatorID '" +
data.get("OriginatorID") + "' is not a valid socket id.");
retcode="failed";
}
}
else
{
log.error("Cannot send outgoing message. OriginatorID/MESSAGE is not
available.");
retcode="failed";
}
return retcode;
}

#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

2813

Adobe ColdFusion Documentation

restart
Description
Stops a gateway if it is running and starts it up.
Category
Event Gateway Development
Syntax

public void restart()

See also
start, stop
Usage
In most cases, you implement this method as a call to the stop method followed by a start method, but you may be
able to optimize the restart method based on the type of gateway.
Example
The following example is the ColdFusion SocketGateway class restart method:

public void restart()
{
stop();
start();
}

#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

2814

Adobe ColdFusion Documentation

setCFCListeners
Description
Sets the array of listener CFCs that the gateway sends messages to.
Category
Event Gateway Development
Syntax

public void setCFCListeners(String[] listeners)

See also
Constructor, getGatewayID, setCFCPath, Providing Gateway class service and information
routines in the Developing ColdFusion Applications
Parameters
Parameter

Description

listeners

Array of absolute file paths to CFCs to which the
gateway forwards messages when it gets events.

Usage
When ColdFusion starts a gateway instance, it calls this method with the names in the instances listener list in the
ColdFusion Administrator. ColdFusion can also call this method if the ColdFusion Administrator listener list changes
while the gateway is running.
Example
The following example is the ColdFusion SocketGateway class setCFCListeners method:

© 2014 Adobe Systems Incorporated. All rights reserved.

2815

Adobe ColdFusion Documentation

public void setCFCListeners(String[] listeners)
{
ArrayList aListeners = new ArrayList();
for(int i = 0; i
information


to the following:

© 2014 Adobe Systems Incorporated. All rights reserved.

2829

Adobe ColdFusion Documentation


debug


With debug priority, ColdFusion writes messages with a severity of "debug" to the log file specified in the getLogge
r method that returned the Logger instance (or the default log file).
Example
The ColdFusion instant messaging gateways use the following line to log information about incoming administrative
messages or errors only when debugging priority is on.

// code to process incoming administrative messages or errors
logger.debug(gatewayType + "Gateway (" + gatewayID + ") admin message: " +
msg.getMessage());

#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

2830

Adobe ColdFusion Documentation

error
Description
Writes a log entry with an error severity to the ColdFusion logger. The entry includes the severity, thread ID, date,
time, and a text message.
Category
Event Gateway Development
Syntax

error(String message)
error(Throwable th)
error(String message, Throwable th)

See also
debug, fatal, info, warn, getLogger, Logging events and using log files in Building an event gateway in the De
veloping ColdFusion Applications
Parameters
Parameter

Description

message

The message to include in the log entry.

th

A throwable object, normally an exception. ColdFusion
logs the exception information in the exception.log file
in the ColdFusion logs directory.

Usage
Use this method to send an error message to the ColdFusion logging subsystem. ColdFusion writes messages with
a severity of "error" to the log file specified in the getLogger method that returned the Logger instance (or the
default log file).
Example
The ColdFusion example SocketGateway class includes the following code in the outgoingMessage method. It
writes an error message if the message's originator ID does not correspond to an open socket.

© 2014 Adobe Systems Incorporated. All rights reserved.

2831

Adobe ColdFusion Documentation

SocketServerThread st =
((SocketServerThread)socketRegistry.get(cfmsg.getOriginatorID()));
if(st != null)
st.writeOutput(message);
else {
log.error("Cannot send outgoing message. OriginatorID '" +
cfmsg.getOriginatorID() + "' is not a valid socket id.");
retcode="failed";
}

#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

2832

Adobe ColdFusion Documentation

fatal
Description
Writes a log entry with a fatal severity to the ColdFusion logger. The entry includes the severity, thread ID, date,
time, and a text message.
Category
Event Gateway Development
Syntax

fatal(String message)
fatal(Throwable th)
fatal(String message, Throwable th)

See also
debug, error, info, warn, getLogger, Logging events and using log files in Building an event gateway in the De
veloping ColdFusion Applications
Parameters
Parameter

Description

message

The message to include in the log entry.

th

A throwable object, normally an exception. ColdFusion
logs the exception information in the exception.log file
in the ColdFusion logs directory.

Usage
Use this method to send a fatal error message to the ColdFusion logging subsystem. ColdFusion writes message
with a severity of "fatal" to the log file specified in the getLogger method that returned the Logger instance (or the
default log file).
#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

2833

Adobe ColdFusion Documentation

info
Description
Writes a log entry with an information severity to the ColdFusion logger. The entry includes the severity, thread ID,
date, time, and a text message.
Category
Event Gateway Development
Syntax

info(String message)
info(Throwable th)
info(String message, Throwable th)

See also
debug, error, fatal, warn, getLogger, Logging events and using log files in Building an event gateway in the D
eveloping ColdFusion Applications
Parameters
Parameter

Description

message

The message to include in the log entry.

th

A throwable object, normally an exception. ColdFusion
logs the exception information in the exception.log file
in the ColdFusion logs directory. Not normally used
with this method.

Usage
Use this method to send an informational message to the ColdFusion logging subsystem. ColdFusion writes
messages with a severity of "information" to the log file specified in the getLogger method that returned the Logger
instance (or the default log file).ColdFusion normally logs all information severity messages. So do not use this
severity for debugging messages or for events that happen frequently.
Example
The ColdFusion example DirectoryWatcherGateway class includes the following line at the top of its loadconfig m
ethod that loads the gateway's configuration file. It writes a message including the gateway ID and configuration file.

logger.info("DirectoryWatcher (" + gatewayID + ") Initializing
DirectoryWatcher gateway with configuration file " + config);

© 2014 Adobe Systems Incorporated. All rights reserved.

2834

Adobe ColdFusion Documentation

#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

2835

Adobe ColdFusion Documentation

warn
Description
Writes a log entry with a warning severity to the ColdFusion logger. The entry includes the severity, thread ID, date,
time, and a text message.
Category
Event Gateway Development
Syntax

warn(String message)
warn(Throwable th)
warn(String message, Throwable th)

See also
debug, error, fatal, info, getLogger, Logging events and using log files in Building an event gateway in the D
eveloping ColdFusion Applications
Parameters
Parameter

Description

message

The message to include in the log entry.

th

A throwable object, normally an exception. ColdFusion
logs the exception information in the exception.log file
in the ColdFusion logs directory.

Usage
Use this method to send a warning message to the ColdFusion logging subsystem. ColdFusion writes messages
with a severity of "warning" to the log file specified in the getLogger method that returned the Logger instance (or
the default log file).
Example
The ColdFusion example SocketWatcherGateway class includes the following code in its constructor to load a
configuration file. If it cannot load the file, it converts the exception information to a string and logs a warning that
includes the gateway ID, and the exception information. It also passes the exception to the warn method

© 2014 Adobe Systems Incorporated. All rights reserved.

2836

Adobe ColdFusion Documentation

propsFilePath=configpath;
try {
FileInputStream propsFile = new FileInputStream(propsFilePath);
properties.load(propsFile);
propsFile.close();
this.loadProperties();
}
catch (IOException e) {
// do nothing. use default value for port.
log.warn("SocketGateway(" + gatewayID + ") Unable to read configuration file
" + propsFilePath + ": " + e.ToString() + ".Using default port.", e);
}

#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

2837

Adobe ColdFusion Documentation

CFML CFEvent structure
The CFML listener CFC methods receive messages in the form of a CFEvent structure that corresponds to the CFE
vent class in Event gateway elements in the Developing ColdFusion Applications that gateway developers use. This
structure has the following fields. Some of the fields might not be used by all gateways. All fields contain text or
numeric values except the Data field, which contains a structure.
Field

Description

GatewayID

The event gateway that sent the event or will handle
the outgoing message. The value is the ID of an event
gateway instance configured on the ColdFusion
Administrator Gateways page. If the application calls
the SendGatewayMessage function to respond to the
event gateway, it uses this ID as the function's first
parameter.

Data

A structure containing the event data, including the
message. The Data structure contents depend on the
event gateway type. This field corresponds to the Send
GatewayMessage function's second parameter.

OriginatorID

The originator of the message. The value depends on
the protocol or event gateway type. Some event
gateways might require this value in response
messages to identify the destination of the response.
Identifies the sender of the message.

GatewayType

The type of event gateway, such as SMS. An
application that can process messages from multiple
event gateway types can use this field. This value is the
gateway type name that is specified by the event
Gateway class. It is not necessarily the same as the
gateway type name in the ColdFusion Administrator.

CFCPath

The location of the listener CFC. The listener CFC does
not need to use this field.

CFCMethod

The listener method that ColdFusion invokes to
process the event. The listener CFC does not need to
use this field.

CFCTimeout

The time-out, in seconds, for the listener CFC to
process the event request. The listener CFC does not
need to use this field.

#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

2838

Adobe ColdFusion Documentation

IM gateway methods and commands
The XMPP and IBM Sametime gateways implement CFC methods to receive messages, use the gatewayHelper
object methods to manage the gateway, and use outgoing message commands to send messages.

#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

2839

Adobe ColdFusion Documentation

IM Gateway CFC incoming message methods
You write the following CFC methods to handle incoming messages from an XMPP or Lotus Sametime instant
messaging gateway.
Note
The method names assume a default gateway configuration. ColdFusion lets you change the
method names and disable event types in the gateway configuration file.

Method

Message type

onAddBuddyRequest

Requests from other IM users to add the gateway ID as
their buddy

onAddBuddyResponse

Responses from others to requests from your gateway
to add them to your buddy lists. Also used by buddies
to ask to be removed from your list.

onBuddyStatus

Online status information messages

onIMServerMessage

Error and administrative messages from the IM server

onIncomingMessage

Instant messages

#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

2840

Adobe ColdFusion Documentation

onAddBuddyRequest
Description
Handles incoming requests for users to add the gateway user name as one of their buddies.
Syntax

onAddBuddyRequest(CFEvent)

See also
onIncomingMessage, onAddBuddyResponse, onBuddyStatus, onIMServerMessage
Parameters
The method must take one parameter, a CFEvent structure with the following fields:
Field

Description

gatewayType

Gateway type, either XMPP or SAMETIME

gatewayID

The ID of the gateway instance, as configured in
ColdFusion Administrator

originatorID

The IM ID of the message originator

cfcMethod

This CFC method; by default, onAddBuddyRequest.

data.MESSAGE

The message that was sent with the request

data.SENDER

The sender's ID; identical to the originatorID field value

data.RECIPIENT

The recipient's ID, as specified in the gateway's
configuration file

data.TIMESTAMP

The date and time when the message was sent

Returns
The function can optionally return a value to send a response message. The return structure must contain the
following fields:
Field

© 2014 Adobe Systems Incorporated. All rights reserved.

Description

2841

Adobe ColdFusion Documentation

command

One of the following:
accept - Accept the request to add you as a buddy.
ColdFusion adds the user to the permit list of users
that can get status information.
decline - Deny request to add you as a buddy.
ColdFusion adds the user to the deny list of users
that can get status information.
noact - Take no action. ColdFusion does not respond
to the requestor.

buddyID

ID to which to send the message. Normally, the value
of the CFEvent.data.SENDER field. Not used with the n
oact command.

reason

A text message describing the reason for the action.
Not used with the noact command.

Example
The following example searches for the requested buddy's name in a data source and, if it finds a unique entry, adds
the buddy and updates the buddy's status information in an Application scope buddyStatus structure. If it doesn't
find the name, it declines the buddy. If there are multiple entries for the buddy name in the database, it tells the
gateway not to respond. It logs all actions.

© 2014 Adobe Systems Incorporated. All rights reserved.

2842

Adobe ColdFusion Documentation




SELECT IM_ID
FROM Employees
WHERE IM_ID = '#CFEvent.Data.SENDER#'



// If the name is in the DB once, accept; if it is missing, decline.
// If it is in the DB multiple times, take no action.
if (buddysearch.RecordCount IS 0) {
action="decline";
reason="Invalid ID";
}
else if (buddysearch.RecordCount IS 1) {
action="accept";
reason="Valid ID";
//Add the buddy to the buddy status structure only if accepted.
if (NOT StructKeyExists(Application,
"buddyStatus")) {
Application.buddyStatus=StructNew();
}
if (NOT StructKeyExists(Application.buddyStatus,
CFEvent.Data.SENDER)) {
Application.buddyStatus[#CFEvent.Data.SENDER#]=StructNew();
}
Application.buddyStatus[#CFEvent.Data.SENDER#].status=
"Accepted Buddy Request";
Application.buddyStatus[#CFEvent.Data.SENDER#].timeStamp=
CFEvent.Data.TIMESTAMP;
Application.buddyStatus[#CFEvent.Data.SENDER#].message=
CFEvent.Data.MESSAGE;
}
else {
action="noact";
}












#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

2843

Adobe ColdFusion Documentation

onAddBuddyResponse
Description
Handles incoming responses from other users to requests from the gateway to be added to their buddy lists. Also
receives requests from buddies to have you remove them from your buddy list.
Syntax

onAddBuddyResponse(CFEvent)

See also
onIncomingMessage, onAddBuddyRequest, onBuddyStatus, onIMServerMessage
Parameters
The method must take one parameter, a CFEvent structure with the following fields:
Field

Description

gatewayType

Gateway type, either XMPP or SAMETIME.

gatewayID

The ID of the gateway instance, as configured in
ColdFusion Administrator.

originatorID

The IM ID of the message originator.

cfcMethod

This CFC method; by default, onAddBuddyResponse.

data.MESSAGE

One of the following:
accept - The request was accepted.
decline - The request was declined, or the buddy is
asking you to remove them from your list.

data.SENDER

The sender's ID; identical to the originatorID.

data.RECIPIENT

The recipient's ID, as specified in the gateway's
configuration file.

data.TIMESTAMP

The date and time when the message was sent.

Returns
The function does not return a value.
Example

© 2014 Adobe Systems Incorporated. All rights reserved.

2844

Adobe ColdFusion Documentation

The following example adds the buddy's status to the Application scope buddyStatus structure if the message
sender accepted an add buddy request. It logs all responses.





//Do the following only if the buddy accepted the request.
if (NOT StructKeyExists(Application, "buddyStatus")) {
Application.buddyStatus=StructNew();
}
if (#CFEVENT.Data.MESSAGE# IS "accept") {
//Create a new entry in the buddyStatus record for the buddy.
if (NOT StructKeyExists(Application.buddyStatus,
CFEvent.Data.SENDER)) {
Application.buddyStatus[#CFEvent.Data.SENDER#]=StructNew();
}
//Set the buddy status information to indicate buddy was added.
Application.buddyStatus[#CFEvent.Data.SENDER#].status=
"Buddy accepted us";
Application.buddyStatus[#CFEvent.Data.SENDER#].timeStamp=
CFEvent.Data.TIMESTAMP;
Application.buddyStatus[#CFEvent.Data.SENDER#].message=
CFEvent.Data.MESSAGE;
}






#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

2845

Adobe ColdFusion Documentation

onBuddyStatus
Description
Handles incoming messages indicating online status (presence) changes of users on the gateway's buddy list.
Syntax

onBuddyStatus(CFEvent)

See also
onIncomingMessage, onAddBuddyRequest, onAddBuddyResponse, onIMServerMessage
Parameters
The method must take one parameter, a CFEvent structure with the following fields:
Field

Description

gatewayType

Gateway type, either XMPP or SAMETIME.

gatewayID

The ID of the Gateway instance, as configured in
ColdFusion Administrator.

originatorID

The IM ID (buddy name) of the message originator.

cfcMethod

This CFC method; by default, onIMServerMessage.

data.BUDDYNAME

The sender's buddy name, or ID; identical to the
originatorID.

data.BUDDYNICKNAME

The buddy's display name or nickname.

© 2014 Adobe Systems Incorporated. All rights reserved.

2846

Adobe ColdFusion Documentation

data.BUDDYSTATUS

The buddy's status; one of the following:
ONLINE
OFFLINE
AWAY
DO NOT DISTURB
NOT AVAILABLE
FREE TO CHAT
IDLE
XMPP only
NOT AVAILABLE
FREE TO CHAT
IDLE
Sametime only
IDLE
Use the IMGatewayHelper getCustomAwayMess
age method to get any custom message that the
buddy sent when changing status.

data.BUDDYGROUP

The group that the buddy belongs to.

data.RECIPIENT

The recipient's ID, as specified in the gateway's
configuration file.

data.TIMESTAMP

The date and time when the message was sent.

Note
You configure the buddy's nickname and group when you use the gatewayHelper object addBud
dy method to add a buddy.

Returns
The function does not return a value.
Example
The following example keeps an Application scope structure up-to-date with a buddy's status. It also uses the
gatewayhelper object getBuddyStatus method to get the buddy's custom away message, if any.

© 2014 Adobe Systems Incorporated. All rights reserved.

2847

Adobe ColdFusion Documentation










// Create the status structures if they don't exist.
if (NOT StructKeyExists(Application, "buddyStatus")) {
Application.buddyStatus=StructNew();
}
if (NOT StructKeyExists(Application.buddyStatus,
CFEvent.Data.BUDDYNAME)) {
Application.buddyStatus[#CFEvent.Data.BUDDYNAME#]=StructNew();
}
// Save the buddy status, timestamp, and custom away message
Application.buddyStatus[#CFEvent.Data.BUDDYNAME#].status=
CFEvent.Data.BUDDYSTATUS;
Application.buddyStatus[#CFEvent.Data.BUDDYNAME#].timeStamp=
CFEvent.Data.TIMESTAMP;
// The following assumes that the buddy is in only one group.
Application.buddyStatus[#CFEvent.Data.BUDDYNAME#].customAway=
mybuddyinfo[1].BUDDYCUSTOMAWAYMESSAGE;










#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

2848

Adobe ColdFusion Documentation

onIMServerMessage
Description
Handles incoming error and status messages from the IM server.
Syntax

onIMServerMessage(CFEvent)

See also
onIncomingMessage, onAddBuddyRequest, onAddBuddyResponse, onBuddyStatus
Parameters
This method must take one parameter, a CFEvent structure with the following fields:
Field

Description

gatewayType

Gateway type, either XMPP or SAMETIME

gatewayID

The ID of the gateway instance, as configured in
ColdFusion Administrator

originatorID

The IM ID (buddy name) of the message originator

cfcMethod

This CFC method; by default, onIMServerMessage

data.MESSAGE

The message sent by the server

data.SENDER

The sender's ID; identical to the originatorID

data.RECIPIENT

The recipient's ID, as specified in the gateway's
configuration file

data.TIMESTAMP

The date and time when the message was sent

Example
The following example logs the sender, message, and a timestamp when an IM server sends an error or status
message:

© 2014 Adobe Systems Incorporated. All rights reserved.

2849

Adobe ColdFusion Documentation







#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

2850

Adobe ColdFusion Documentation

onIncomingMessage
Description
Handles incoming instant messages from other users. Optionally returns a response to the message sender.
Syntax

onIncomingMessage(CFEvent)

See also
onAddBuddyRequest, onAddBuddyResponse, onBuddyStatus, onIMServerMessage, Handling incoming
messages in the Developing ColdFusion Applications
Parameters
The method must take one parameter, a CFEvent structure with the following fields:
Field

Description

gatewayType

Gateway type, either XMPP or SAMETIME.

gatewayID

The ID of the Gateway instance as configured in
ColdFusion Administrator.

originatorID

The IM ID of the message originator.

cfcMethod

This CFC method; by default, onIncomingMessage.

data.MESSAGE

The message that was received.

data.SENDER

The sender's ID; identical to the originatorID

data.RECIPIENT

The recipient's ID, as specified in the gateway's
configuration file

data.TIMESTAMP

The date and time when the message was sent

Returns
The function can optionally return a value to send a response message. The return structure must contain the
following fields:
Field

Description

command

Normally omitted. You can also specify submit.

© 2014 Adobe Systems Incorporated. All rights reserved.

2851

Adobe ColdFusion Documentation

buddyID

ID to which to send the message. Normally, the value
of the input parameter's Data.SENDER field.

message

The message contents.

Example
The following example shows a simple onIncomingMessage method that echoes a message back to the sender.











#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

2852

Adobe ColdFusion Documentation

IM Gateway GatewayHelper class methods
The GatewayHelper class returned by the CFML GetGatewayHelper function includes the following methods:
addBuddy

getDenyList

getStatusAsString

removeDeny

addDeny

getName

getStatusTimeStamp

removePermit

addPermit

getNickName

isOnline

setNickName

getBuddyInfo

getPermitList

numberOfMessagesRec
eived

setPermitMode

getBuddyList

getPermitMode

numberOfMessagesSen
t

setStatus

getCustomAwayMessag
e

getProtocolName

removeBuddy

#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

2853

Adobe ColdFusion Documentation

IM gateway message sending commands
You use the SendGatewayMessage CFML function or the return value of a CFC listener method to send outgoing
messages. The ColdFusion IM gateway accepts the following outgoing message commands:
Command

Description

submit

(Default) Sends a normal message to another IM user.

accept

Accepts an add buddy request. Adds the buddy to the
list of IDs that get your presence information and sends
an acceptance message to the buddy ID.

decline

Declines an add buddy request and sends a rejection
message to the buddy ID.

noact

Tells the gateway to take no action. The gateway logs a
message that indicates that it took no action, and
contains the gateway type, gateway ID, and buddy ID.

The message structure that you return in the gateway listener CFC function or use as the second parameter in the
CFML SendGatewayMessage function can have the following fields. The table lists the fields and the commands in
which they are used, and describes the field's use.
Field

Commands

Description

buddyID

All

The destination user ID

command

All

The command; defaults to submit if
omitted

message

submit

A text message to send to the
destination user

reason

accept, decline

A text description of the reason for
the action or other message to send
to the add buddy requestor

In typical use, a ColdFusion application uses the accept, decline, and noact commands in the return value of the on
AddBuddyRequest method, and uses the submit command (or no command, because submit is the default
command) in SendGatewayMessage CFML functions and the return value of the onIncomingMessage CFC
method.

#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

2854

Adobe ColdFusion Documentation

addBuddy
Description
Adds a buddy to the buddy list for the gateway user ID and asks to have the IM server send messages with the
buddy's online presence state to the gateway.
Syntax

Boolean = addBuddy(name, nickname, group)

See also
getBuddyInfo, getBuddyList, removeBuddy, Using the GatewayHelper object in the Developing ColdFusion
Applications
Parameters
Parameter

Description

name

The unique instant messaging user name for the
person about whom you want to receive periodic status
messages.

nickname

The nickname that the application can use to refer to
the user.

group

The name of the group you wish to add the user to in
your Buddy List. If the group specified does not exist, it
will be created. If the group parameter is the empty
string, the gateway uses the General group.

Returns
True if the ID was added to the gateway's buddy list; False, otherwise.
Usage
This method adds the buddy to the buddy list for the gateway's ID and sends a subscription request (to automatically
get presence information about the buddy's online status) to the remote buddy. It does not wait for a response from
the buddy, so it returns True (and the gateway adds the buddy to the list) even if the buddy denies the subscription
request. Use the listener CFC onAddBuddyResponse method to monitor the buddy's response. If the
CFEvent.data.MESSAGE field value is decline, the listener method can call the gatewayHelper object removeBudd
y method to remove the buddy from the buddy list.
Example
See GatewayHelper example in Using the GatewayHelper object the Developing ColdFusion Applications, which
uses all GatewayHelper class methods.

© 2014 Adobe Systems Incorporated. All rights reserved.

2855

Adobe ColdFusion Documentation

#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

2856

Adobe ColdFusion Documentation

addDeny
Description
Tells the IM server to add the specified user to the deny list for the gateway's user ID. If the gateway's permit mode
value is DENY_SOME, the specified user cannot receive messages on the gateway's presence state.
Syntax

Boolean = addDeny(name, nickname, group)

See also
addPermit, getDenyList, getPermitList, getPermitMode, removeDeny, removePermit, setPermitMod
e, Using the GatewayHelper object in the Developing ColdFusion Applications
Parameters
Parameter

Description

name

The unique instant messaging user name for the
person about whom you want to deny access to status
messages.

nickname

The nickname that the application can use to refer to
the user. Can be the empty string.

group

The name of the group that you want to add the user to
in your buddy list. If the group specified does not exist,
it is created. If the group parameter is the empty string,
the gateway uses the General group.

Returns
True if the ID was added to the deny list; False, otherwise.
Note
If the XMPP server does not support permission management, this function always returns False

Example
See GatewayHelper example in Using the GatewayHelper object in the Developing ColdFusion Applications, which
uses all GatewayHelper class methods.
#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

2857

Adobe ColdFusion Documentation

addPermit
Description
Tells the IM server to add the specified user to the permit list for the gateway's user ID. If the gateway's permit mode
is PERMIT_SOME, the specified user receive messages on the gateway's presence state.
Syntax

Boolean = addPermit(name, nickname, group)

See also
addDeny, getDenyList, getPermitList, getPermitMode, removeDeny, removePermit, setPermitMode,
Using the GatewayHelper object in the Developing ColdFusion Applications
Parameters
Parameter

Description

name

The unique instant messaging user name for the
person about whom you want to deny access to status
messages.

nickname

The nickname that the application can use to refer to
the user. Can be the empty string.

group

The name of the group you want to add the user to in
your Buddy List. If the group specified does not exist, it
is created. If the group parameter is the empty string,
the gateway uses the General group.

Returns
True if the ID was added to the permit list; false, otherwise.
Note
If the XMPP server does not support permission management, this function always returns False.

Example
See GatewayHelper example, in Using the GatewayHelper object in the Developing ColdFusion Applications, which
uses all GatewayHelper class methods.
#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

2858

Adobe ColdFusion Documentation

getBuddyInfo
Description
Gets information about the specified user from the buddy list, deny list, and permit list.
Syntax

array = getBuddyInfo(name)

See also
addBuddy, getBuddyList, removeBuddy, Using the GatewayHelper object in the Developing ColdFusion
Applications
Parameters
Parameter

Description

name

The unique instant messaging user name for the
person about whom you want to get information.

Returns
An array of structures, with one structure for each information record found. The method finds one record for each
group that the user belongs to in each of the lists (buddy, permit, deny) that contains the specified name. Each
structure has the following fields. Some fields might not be meaningful for some IM protocols. If there is no
information for a field, it is blank.
Field

Description

BUDDYNAME

The user's unique ID.

BUDDYGROUP

The group to which the user belongs.

BUDDYNICKNAME

The nickname that you have assigned to the user.

BUDDYPROTOCOL

The instant messaging protocol. JABBER (for XMPP) or
SAMETIME, or an empty string (if the server did not
return a value).

© 2014 Adobe Systems Incorporated. All rights reserved.

2859

Adobe ColdFusion Documentation

BUDDYSTATUS

The user's presence state, can by any of the following:
ONLINE
OFFLINE
AWAY
DND (displays as DO NOT DISTURB)
NA (displays as NOT AVAILABLE)
FREE_TO_CHAT (displays as FREE TO CHAT)
IDLE
XMPP only
NA (displays as NOT AVAILABLE)
FREE_TO_CHAT (displays as FREE TO CHAT)
IDLE
Sametime only
IDLE

BUDDYSIGNONTIME

The date and time when the user signed onto the IM
server. Empty if the user is not currently signed on.
Always an empty string for XMPP and Sametime.

BUDDYSTATUSTIME

The date and time when the user's status most recently
changed.

BUDDYCUSTOMAWAYMESSAGE

The custom away message that the user has set to
explain the current status, if any.

BUDDYOWNER

A string representing the client and protocol associated
with this ID, in the format client@protocol.

BUDDYLISTTIYPE

The type of list that this buddy record is in; one of the
following:
BUDDY_LIST- The list of users whose presence
status information the gateway can receive.
DENY_LIST - The list of users who cannot get
presence information about the gateway ID.
PERMIT_LIST - The list of users who can send
presence information messages to the gateway ID.
REVERSE_LIST - The list of users who do not allow
messages to us.

BUDDYIDLETIME

If the buddy status is IDLE, how long the buddy has
been idle. Always 0 for XMPP or SameTime.

BUDDYISMOBILE

True or False, indicating whether the user is on a
mobile device. Always False for XMPP or SameTime.

BUDDYWARNINGPERCENT

The user's warning percentage value. Always 0 for
XMPP or SameTime.

Example

© 2014 Adobe Systems Incorporated. All rights reserved.

2860

Adobe ColdFusion Documentation

See Using the GatewayHelper object in the Developing ColdFusion Applications, which uses all GatewayHelper
class methods. For an example of using this method to get the buddy custom away message, see onBuddyStatus
.---#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

2861

Adobe ColdFusion Documentation

getBuddyList
Description
Gets the buddy list for the gateway's user ID.
Syntax

array = getBuddyList()

See also
addBuddy, getBuddyInfo, removeBuddy, Using the GatewayHelper object in the Developing ColdFusion
Applications
Returns
An array of IDs (buddy names) of the users on the gateway's buddy list, a list of instant messaging IDs that this
gateway normally communicates with.
Example
See GatewayHelper example in Using the GatewayHelper object in the Developing ColdFusion Applications which
uses all GatewayHelper class methods.
#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

2862

Adobe ColdFusion Documentation

getCustomAwayMessage
Description
Returns the gateway's custom away message if it has been set by the gatewayHelper object setStatus method.
Syntax

string = getCustomAwayMessage()

See also
getStatusAsString, getStatusTimeStamp, isOnline, setStatus, Using the GatewayHelper object in the D
eveloping ColdFusion Applications
Returns
The gateway's custom away message if it has been set by the GatewayHelper object setStatus method.
Example
See GatewayHelper example in Using the GatewayHelper object in the Developing ColdFusion Applications , which
uses all GatewayHelper class methods.
#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

2863

Adobe ColdFusion Documentation

getDenyList
Description
Returns the list of users that the IM server has been told not to send state information about the gateway, if the
permit mode is set to DENY_SOME.
Syntax

array = getDenyList()

See also
addDeny, addPermit, getPermitList, getPermitMode, removeDeny, removePermit, setPermitMode, Us
ing the GatewayHelper object in the Developing ColdFusion Applications
Returns
An array of IDs (buddy names) of the users on the gateway's deny list, the list of IDs to which the IM server does not
send presence status information.
Note
If the XMPP server does not support permission management, this function always returns False.

Example
See GatewayHelper example in Using the GatewayHelper object in the Developing ColdFusion Applications, which
uses all GatewayHelper class methods.
#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

2864

Adobe ColdFusion Documentation

getName
Description
Returns the gateway's user name.
Syntax

string = getName()

See also
getProtocolName, numberOfMessagesReceived, numberOfMessagesSent, setNickName, Using the
GatewayHelper object in the Developing ColdFusion Applications
Returns
The gateway's user name, as specified in gateway configuration file.
Example
See GatewayHelper example in Using the GatewayHelper object in the Developing ColdFusion Applications, which
uses all GatewayHelper class methods.
#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

2865

Adobe ColdFusion Documentation

getNickName
Description
Returns the gateway's nickname (display name), if it has been set using the gatewayHelper object setNickName m
ethod.
Syntax

string = getNickName()

See also
getName, getProtocolName, numberOfMessagesReceived, numberOfMessagesSent, setNickName, Usin
g the GatewayHelper object in the Developing ColdFusion Applications
Returns
The gateway's nickname, if any; empty string, otherwise.
Example
See GatewayHelper example in Using the GatewayHelper object in the Developing ColdFusion Applications, which
uses all GatewayHelper class methods.
#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

2866

Adobe ColdFusion Documentation

getPermitList
Description
Returns the list of users that the IM server has been told to send state information about the gateway.
Syntax

array = getPermitList()

See also
addDeny, addPermit, getDenyList, getPermitMode, removeDeny, removePermit, setPermitMode, Using
the GatewayHelper object in the Developing ColdFusion Applications
Returns
An array of IDs (buddy names) of the users on the gateway's permit list, the list of IDs to which the IM server sends
presence status information if the permit mode is set to PERMIT_SOME.
Note
If the XMPP server does not support permission management, this function always returns False.

Example
See GatewayHelper example in Using the GatewayHelper object in the Developing ColdFusion Applications, which
uses all GatewayHelper class methods.
#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

2867

Adobe ColdFusion Documentation

getPermitMode
Description
Gets the gateway's permit mode from the IM server. The permit mode determines whether all users can get the
gateway's online state information, or whether the server uses a permit list or a deny list to control which users get
state information.
Syntax

string = getPermitMode()

See also
addDeny, addPermit, getDenyList, getPermitList, removeDeny, removePermit, setPermitMode, Using
the GatewayHelper object in the Developing ColdFusion Applications
Returns
The gateway's permit mode; one of the following values:
Mode

Description

PERMIT_ALL

(Default) Permits all users to be aware of the gateway's
online presence and state.

PERMIT_SOME

Permits only users in the permit list to be aware of the
gateway's online presence and state.

DENY_SOME

Prevents the users in the deny list from being aware of
the gateway's online presence and state.

Note
If the XMPP server does not support permission management, this function always returns
PERMIT_ALL.

Example
See GatewayHelper example in Using the GatewayHelper object in the Developing ColdFusion Applications, which
uses all GatewayHelper class methods.
#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

2868

Adobe ColdFusion Documentation

getProtocolName
Description
Gets the name of the gateway's instant messaging protocol.
Syntax

string = getProtocolName()

See also
getName, getNickName, numberOfMessagesReceived, numberOfMessagesSent, setNickName, Using the
GatewayHelper object in the Developing ColdFusion Applications
Returns
The gateway's protocol, as determined by the gateway type; one of the following values:
JABBER (for XMPP)
SAMETIME
Example
See GatewayHelper example in Using the GatewayHelper object in the Developing ColdFusion Applications, which
uses all GatewayHelper class methods.
#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

2869

Adobe ColdFusion Documentation

getStatusAsString
Description
Gets the online status of the gateway as a text string.
Syntax

string = getStatusAsString()

See also
getCustomAwayMessage, getStatusTimeStamp, isOnline, setStatus, Using the GatewayHelper object in
the Developing ColdFusion Applications
Returns
The gateway's online status; one of the following:
ONLINE
OFFLINE
AWAY
DO NOT DISTURBXMPP only
NOT AVAILABLE
FREE TO CHATSametime only
IDLE
Usage
The DO NOT DISTURB, NOT AVAILABLE, and FREE TO CHAT strings differ from the status values that you use in
the setStatus method, which does not allow spaces in the status names.
Example
See GatewayHelper example in Using the GatewayHelper object in the Developing ColdFusion Applications, which
uses all GatewayHelper class methods.
#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

2870

Adobe ColdFusion Documentation

getStatusTimeStamp
Description
Gets the date and time that the gateway changed its online status.
Syntax

date-time object = getStatusTimeStamp()

See also
getCustomAwayMessage, getStatusAsString, isOnline, setStatus, Using the GatewayHelper object in
the Developing ColdFusion Applications
Returns
The date and time that the gateway changed its online status, normally by calling the setStatus gatewayHelper
object method.
Example
See GatewayHelper example in Using the GatewayHelper object in the Developing ColdFusion Applications, which
uses all GatewayHelper class methods.
#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

2871

Adobe ColdFusion Documentation

numberOfMessagesReceived
Description
Gets the number of messages received by the gateway since it was started.
Syntax

integer = numberOfMessagesReceived()

See also
getName, getNickName, getProtocolName, numberOfMessagesSent, setNickName, Using the
GatewayHelper object in the Developing ColdFusion Applications
Returns
The number of messages received by the gateway since it was started.
Example
See GatewayHelper example in Using the GatewayHelper object in the Developing ColdFusion Applications, which
uses all GatewayHelper class methods.
#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

2872

Adobe ColdFusion Documentation

numberOfMessagesSent
Description
Gets the number of messages sent by the gateway since it was started.
Syntax

integer = numberOfMessagesSent()

See also
getName, getNickName, getProtocolName, numberOfMessagesReceived, setNickName, Using the
GatewayHelper object in the Developing ColdFusion Applications
Returns
The number of messages sent by the gateway since it was started.
Example
See GatewayHelper example in Using the GatewayHelper object in the Developing ColdFusion Applications, which
uses all GatewayHelper class methods.
#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

2873

Adobe ColdFusion Documentation

removeBuddy
Description
Removes an ID from a group in the buddy list for the gateway and tells the IM server not to send the gateway
messages with the buddy's online presence state.
Syntax

Boolean = removeBuddy(name, group)

See also
addBuddy, getBuddyInfo, getBuddyList, removeDeny, removePermit, Using the GatewayHelper object in
the Developing ColdFusion Applications
Parameters
Parameter

Description

name

The unique instant messaging user name for the
person to remove from the buddy list.

group

The name of the group from which you want to remove
the user. If the parameter is the empty string, the
gateway uses the General group.

Returns
True if the ID was removed from the group; False, otherwise.
Usage
If the user is in multiple groups in your buddy list, you remove the buddy separately from each group. The IM server
does not stop sending status updates until you remove the name from all groups.
Example
See GatewayHelper example in Using the GatewayHelper object in the Developing ColdFusion Applications, which
uses all GatewayHelper class methods.
#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

2874

Adobe ColdFusion Documentation

removeDeny
Description
Removes an ID from a group in the deny list for the gateway. If the gateway's permit mode is DENY_SOME, the
specified user can receive messages on the gateway's presence state.
Syntax

Boolean = removeDeny(name, group)

See also
addDeny, addPermit, getDenyList, getPermitList, getPermitMode, removeBuddy, removePermit, set
PermitMode, Using the GatewayHelper object in the Developing ColdFusion Applications
Parameters
Parameter

Description

name

The unique instant messaging user name for the
person to remove from the deny list.

group

The name of the group from which you want to remove
the user. If the parameter is the empty string, the
gateway uses the General group.

Returns
True if the ID was removed from the group; False, otherwise.
Note
If the XMPP server does not support permission management, this function always returns False.

Usage
If the user is in multiple groups in your deny list, you remove the user separately from each group. The IM server
enables sending status updates if you remove the name any group.
Example
See GatewayHelper example in Using the GatewayHelper object in the Developing ColdFusion Applications, which
uses all GatewayHelper class methods.
#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

2875

Adobe ColdFusion Documentation

removePermit
Description
Removes an ID from a group in the permit list for the gateway. If the gateway's permit mode is PERMIT_SOME, the
specified user cannot receive messages on the gateway's presence state.
Syntax

Boolean = removePermit(name, group)

See also
addDeny, addPermit, getDenyList, getPermitList, getPermitMode, removeBuddy, removeDeny, setPe
rmitMode, Using the GatewayHelper object in the Developing ColdFusion Applications
Parameters
Parameter

Description

name

The unique instant messaging user name for the
person to remove from the permit list.

group

The name of the group from which you want to remove
the user. If the parameter is the empty string, the
gateway uses the General group.

Returns
True if the ID was removed from the group; False, otherwise.
Note
If the XMPP server does not support permission management, this function always returns False.

Usage
If the user is in multiple groups in your permit list, you remove the user separately from each group. However, the IM
server stops sending status updates when you remove the user from the first group.
Example
See GatewayHelper example in Using the GatewayHelper object in the Developing ColdFusion Applications, which
uses all GatewayHelper class methods.
#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

2876

Adobe ColdFusion Documentation

setNickName
Description
Sets the gateway's nickname (display name).
Syntax

Boolean = setNickName(name)

See also
getName, getNickName, getProtocolName, numberOfMessagesReceived, numberOfMessagesSent, Usin
g the GatewayHelper object in the Developing ColdFusion Applications
Parameters
Parameter

Description

name

The display name that you want to associate with this
gateway. This name is not guaranteed to be unique for
the protocol.

Returns
True if the nickname got set; false, otherwise.
Example
See GatewayHelper example in Using the GatewayHelper object in the Developing ColdFusion Applications, which
uses all GatewayHelper class methods.
#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

2877

Adobe ColdFusion Documentation

setPermitMode
Description
Sets the gateway's permit mode on the IM server. The permit mode determines whether all users can get the
gateway's online state information, or whether the server uses a permit list or a deny list to control which users get
state information.
Syntax

Boolean = setPermitMode(permitMode)

See also
addDeny, addPermit, getDenyList, getPermitList, getPermitMode, removeDeny, removePermit, Using
the GatewayHelper object in the Developing ColdFusion Applications
Parameters
Parameter

Description

permitMode

The permission mode, one of the following:
PERMIT_ALL-Permits all users to be aware of the
gateway's online presence and state. This is the
default mode if you do not call this function.
PERMIT_SOME-Permits only users in the permit list to
be aware of the gateway's online presence and state.
DENY_SOME-Prevents all users in the deny list from
being aware of the gateway's online presence and
state.

Returns
True if the permit mode was set; False otherwise.
Note
If the XMPP server does not support permission management, this function returns False to all
values except PERMIT_ALL.

Example
See GatewayHelper example in Using the GatewayHelper object in the Developing ColdFusion Applications, which
uses all GatewayHelper class methods.
#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

2878

Adobe ColdFusion Documentation

setStatus
Description
Sets the online presence status of the gateway, including any custom away message.
Syntax

Boolean = setStatus(status, customAwayMsg)

See also
getCustomAwayMessage, getStatusAsString, getStatusTimeStamp, isOnline, Using the GatewayHelper
object in the Developing ColdFusion Applications
Parameters
Parameter

Description

status

The gateway's online presence status; one of the
following:
ONLINE
AWAY
DND (Do Not Disturb)
NA (Not Available)
FREE_TO_CHAT
IDLE
XMPP only
NA (Not Available)
FREE_TO_CHAT
IDLE
Sametime only:
IDLE

customAwayMsg

A text string containing a custom message for the
status. Can be the empty string if you do not need a
custom away message.

Returns
True, if the operation was successful; False. otherwise. Passing an invalid status for the protocol causes this method
to return False.
Usage

© 2014 Adobe Systems Incorporated. All rights reserved.

2879

Adobe ColdFusion Documentation

Do not use the setStatus method to go offline. Although the method accepts a parameter of OFFLINE, the
gateway immediately resets itself to be online. To set the gateway offline, stop the gateway instance in the
ColdFusion Administrator, or use the stopGatewayInstance method in the CFIDE.adminapi.eventgateway CFC.
Example
See GatewayHelper example in Using the GatewayHelper object in the Developing ColdFusion Applications, which
uses all GatewayHelper class methods.
#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

2880

Adobe ColdFusion Documentation

SMS Gateway CFEvent structure and commands
This section describes the detailed contents of the following structures that you use in the SMS Gateway listener
CFCs and CFML SendGatewayMessage functions.

#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

2881

Adobe ColdFusion Documentation

SMS Gateway incoming message CFEvent structure
The SMS gateway puts the following information in a CFEvent instance that it sends to the CFC listener method:
Field

Value

OriginatorID

Contents of the PDU source_addr field, the address
of the device that sent the message.

CfcMethod

Listener CFC method name. Value of the configuration
file cfc-method entry, or onIncomingMessage if the
configuration file does not have this entry.

Data.MESSAGE

Contents of the short_message field of the PDU.

Data.sourceAddress

The address of the device that sent this message.

Data.destAddress

The address to which the message was sent; an
address in the range specified by the gateway
configuration file address-range setting.

Data.esmClass

Contents of the PDU esm_class field. Identifies the
message type. A number in the range 0-255
representing a Byte value, where bits 2-5 (0-indexed)
indicate the message type, and therefore the contents
of the data.MESSAGE field, as follows. (Reserved
values are omitted.)xx0000xx-Normal
message{{xx0001xx}}-SMSC delivery
receipt{{xx0010xx}}SME Delivery
Acknowledgement{{xx0100xx}}-SME Manual/User
Acknowledgement{{xx0110xx}}-Conversation abort
(Korean CDMA only)xx1000xx-Intermediate Delivery
NotificationFor more information on this field, see the
SMPP specification.

Data.protocol

Contents of the PDU protocol_id field. Meaningful for
messages sent from GSM networks only. For more
information, see the GSM 03.40 specification.

Data.priority

Contents of the PDU priority_flag field. A message
priority level set by the originating SME, in the range
0-3; 0 is the lowest priority and 3 is the highest priority.
The specific priority level meaning depends on the
originating network. For more details, see the SMPP
specification.

© 2014 Adobe Systems Incorporated. All rights reserved.

2882

Adobe ColdFusion Documentation

Data.registeredDelivery

Contents of the PDU registered_delivery field,
indicating the type of delivery receipt or
acknowledgement that the sender requested. A number
in the range 0-32, representing the sum of the following
values:0: No SMS delivery receipt requested or_1:
SMSC delivery receipt requested on delivery success
or failure _or_2: SMSC delivery receipt requested on
delivery failure onlyPlus0: No SME acknowledgement
requested _or_4: SME Delivery Acknowledgement
requested _or_8: SME Manual/User Acknowledgement
requested _or 12: Both Delivery and Manual/User
Acknowledgements requestedPlus0: No Intermediate
notification requested _or_16: Intermediate notification
requested

Data.DataCoding

Contents of the PDU data_coding field. Indicates the
character set or the noncharacter data type of the
message contents, as follows:00000000--SMSC
Default Alphabet00000001--IA5 (CCITT T.50)/ASCII
(ANSI X3.4)00000010--Octet unspecified (8-bit
binary)00000011--Latin 1 (ISO-8859-1)00000100--Octe
t unspecified (8-bit binary)00000101--JIS (X
0208-1990)00000110--Cyrillic (ISO-8859-5)00000111-Latin/Hebrew (ISO-8859-8)00001000--UCS2
(ISO/IEC-10646)00001001--Pictogram
Encoding00001010--ISO-2022-JP (Music
Codes)00001101--Extended Kanji JIS(X
0212-1990)00001110--KS C 560111xxxxxx--GSM
control use only; see the GSM 03.38 specificationFor
more details, see the SMPP specification.

Data.messageLength

The length of the short_message field.

GatewayType

Always SMS.

For more information on the meanings of some of these fields and how to handle incoming SMS messages an SMS
gateway listener CFC method, see Handling incoming messages in the Developing ColdFusion Applications.

#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

2883

Adobe ColdFusion Documentation

SMS gateway message sending commands
ColdFusion applications that use gateways of the Short Message Service (SMS) type can send the commands
(described in this section) to the event gateway in an outgoing message.

#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

2884

Adobe ColdFusion Documentation

submit command
To send a message to a single destination address in an SMPP SUBMIT_SM PDU, the structure that you used in
the Data parameter of a SendGatewayMessage function or the return variable of the CFC listener method has the
following fields. For more information about these fields, see the documentation for the SUBMIT_MULTI PDU in the
SMPP3.4 specification, which you can download from the SMS Forum at www.smsforum.net/.
Required fields
Field

Contents

command

If present, the value must be submit. If you omit this
field, the event gateway sends a submit message.

shortMessageormessagePayload

The message contents. You must specify one of these
fields, but not both. The SMPP specification imposes a
maximum size of 254 bytes on the shortMessage field,
and some carriers might limit its size further. The
messagePayload field can contain up to 64K bytes; it
must start with 0x0424, followed by two bytes
specifying the payload length, followed by the message
contents.

destAddress

Required. The address to which to send the message.

sourceAddress

The address of this application. You can omit this field;
the configuration file specifies the application address.

Optional fields
You can set default values for the following optional fields in the SMS event gateway configuration file. For
information on the default values, see Configuring an SMS event gateway in the Developing ColdFusion
Applications.
destAddress_npi

destAddress_ton

serviceType

The following optional fields do not have default values:
alertOnMsgDelivery

EsmClass

priorityFlag

smDefaultMsgId

callbackNum

ItsReplyType

PrivacyIndicator

SmsSignal

callbackNumAtag

ItsSessionInfo

protocolId

SourceAddrSubunit

callbackNumPresInd

LanguageIndicator

registeredDelivery

SourcePort

dataCoding

MoreMsgsToSend

replaceIfPresent

SourceSubaddress

© 2014 Adobe Systems Incorporated. All rights reserved.

2885

Adobe ColdFusion Documentation

DestAddrSubunit

MsMsgWaitFacilities

SarMsgRefNum

UserMessageReferenc
e

DestinationPort

MsValidity

SarSegmentSeqnum

UserResponseCode

DestSubaddress

NumberOfMessages

SarTotalSegments

UssdServiceOp

DisplayTime

PayloadType

scheduleDeliveryTim
e

validityPeriod

Example
The following example onIncomingMessage method of a listener CFC uses the submit command to echo
incoming SMS messages to the message originator:












#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

2886

Adobe ColdFusion Documentation

submit Multi command
To send a single text message to multiple recipients using an SMPP SUBMIT_MULTI PDU, the Data parameter of a
SendGatewayMessage function or the return variable of the CFC listener method usually has the following fields.
For more information about these fields, see the documentation for the SUBMIT_MULTI PDU in the SMPP3.4
specification, which you can download from the SMS Forum at www.smsforum.net/.
Required fields
Field

Contents

command

Must be submitMulti.

shortMessageormessagePayload

The message contents. You must specify one of these
fields, but not both. The SMPP specification imposes a
maximum size of 254 bytes on the shortMessage field,
and some carriers might limit its size further. The
messagePayload field can contain up to 64K bytes; it
must start with 0x0424, followed by two bytes
specifying the payload length, followed by the message
contents.

destAddress

A ColdFusion array of destination addresses
(required).You cannot specify individual TON and NPI
values for these addresses; all must conform to a
single setting.

sourceAddress

The address of this application. You can omit this field;
the configuration file specifies the application address.

Optional fields
The following optional fields can have default values set in the SMS event gateway configuration file. For information
on the default values see Configuring an SMS event gateway in the Developing ColdFusion Applications.
destAddress_npi

destAddress_ton

serviceType

The following optional fields do not have default values:
alertOnMsgDelivery

DisplayTime

protocolId

SmsSignal

callbackNum

EsmClass

registeredDelivery

SourceAddrSubunit

callbackNumAtag

LanguageIndicator

replaceIfPresent

SourcePort

callbackNumPresInd

MsMsgWaitFacilities

SarMsgRefNum

SourceSubaddress

dataCoding

MsValidity

SarSegmentSeqnum

UserMessageReferenc
e

© 2014 Adobe Systems Incorporated. All rights reserved.

2887

Adobe ColdFusion Documentation

DestAddrSubunit

PayloadType

SarTotalSegments

DestinationPort

priorityFlag

scheduleDeliveryTim
e

DestSubaddress

PrivacyIndicator

smDefaultMsgId

validityPeriod

Example
The following example onIncomingMessage method sends a response that echoes an incoming message to the
originator address, and sends a copy of the response to a second address:

















#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

2888

Adobe ColdFusion Documentation

data command
To send binary data to a single destination address in an SMPP DATA_SM PDU, the Data parameter of a SendGat
ewayMessage function or the return variable of the CFC listener method must have the following fields. For more
information about these fields, see the documentation for the SUBMIT_MULTI PDU in the SMPP3.4 specification,
which you can download from the SMS Forum at www.smsforum.net/.
Required fields
Field

Contents

command

Must be data.

messagePayload

The message data. To convert data to binary format,
use the ColdFusion ToBinary function.

destAddress

The address to which to send the message.

sourceAddress

The address of this application. You can omit this field;
the configuration file specifies the application address.

Optional fields
The following optional fields can have default values set in the SMS event gateway configuration file. For information
on the default values see Configuring an SMS event gateway in the Developing ColdFusion Applications.
destAddress_npi

destAddress_ton

serviceType

The following optional fields do not have default values:
alertOnMsgDelivery

DestTelematicsId

NetworkErrorCode

SetDpf

callbackNum

DisplayTime

NumberOfMessages

SmsSignal

callbackNumAtag

EsmClass

PayloadType

SourceAddrSubunit

callbackNumPresInd

ItsReplyType

PrivacyIndicator

SourceBearerType

dataCoding

ItsSessionInfo

QosTimeToLive

SourceNetworkType

DestAddrSubunit

LanguageIndicator

ReceiptedMessgeId

SourcePort

DestBearerType

MessageState

registeredDelivery

SourceSubaddress

DestNetworkType

MoreMsgsToSend

SarMsgRefNum

SourceTelematicsId

DestinationPort

MsMsgWaitFacilities

SarSegmentSeqnum

UserMessageReferenc
e

© 2014 Adobe Systems Incorporated. All rights reserved.

2889

Adobe ColdFusion Documentation

DestSubaddress

MsValidity

SarTotalSegments

UserResponseCode

Example
The following example onIncomingMessage method converts an incoming message to binary data, and sends the
binary version of the message back to the originator address:















#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

2890

Adobe ColdFusion Documentation

CFML event gateway SendGatewayMessage data parameter
The ColdFusion CFML gateway type enables you to invoke CFC methods asynchronously. The structure that you
use in the SendGatewayMessage function data parameter can include two types of fields:
Any number of fields can contain arbitrary contents for use in by the CFC.
Several optional fields can configure how the gateway delivers the information to the CFC. The CFML
gateway looks for the following optional fields, and, if they exist, uses them to determine how it delivers the
message. Do not use these field names for data that you send to your CFC method.
Field

Use

cfcpath

Overrides the CFC path specified in the ColdFusion
Administrator. This field lets you use a single gateway
configuration in the ColdFusion Administrator multiple
CFCs. This field sets the CFEvent object CFCPath
variable.

method

Specifies the name of the method to invoke in the CFC.
The default method is onIncomingMessage. This
field lets you use a single gateway configuration in the
ColdFusion Administrator for a CFC that has several
methods. This field sets the CFEvent object
CFCMethod variable.

originatorID

Sets the originatorID field of the CFEvent object that
ColdFusion delivers to the CFC. The default value is
CFMLGateway.

timeout

Sets the time-out, in seconds, during which the listener
CFC must process the event request and return before
ColdFusion gateway services terminates the request.
The default value is the Timeout Request value set on
the Server Settings page in the ColdFusion
Administrator. Set this value if a request might validly
take longer to process than the default time-out; for
example, if the request involves a long processing time.
This field sets the CFEvent object CFCTimeout
variable.

Example
The following example consists of a CFML page that sends a message to a logevent method in the file logger.CFC.
The CFML page specifies the CFC and method to call, and sets the OriginatorID.

© 2014 Adobe Systems Incorporated. All rights reserved.

2891

Adobe ColdFusion Documentation

Sending an event using a generic CFML event gateway and specifying the CFC and
method.

status = False;
props = structNew();
props.cfcpath="C:\CFusionMX7\gateway\cfc\MyCFCs\logger.cfc";
props.method="logEvent";
props.OriginatorID=CGI.SCRIPT_NAME;
props.Message="Replace me with a variable with data to log";
props.file="GenericCFCtest";
props.type="warning";
status = SendGatewayMessage("DefaultCFC", props);
if (status IS True)
WriteOutput('Event Message "#props.Message#" has been sent.');


The CFC method uses the OriginatorID and the message, file, and type fields of the CFEvent parameter's data field
to specify the log file and message.





if (NOT IsDefined("CFEvent.Data.file")) {
CFEvent.Data.file="defaultEventLog"; }
if (NOT IsDefined("CFEvent.Data.type")) {
CFEvent.Data.type="information"; }





Example

© 2014 Adobe Systems Incorporated. All rights reserved.

2892

Adobe ColdFusion Documentation

ColdFusion C++ CFX Reference
ColdFusion includes CFXAPI classes and methods for building ColdFusion extensions.
C++ class overview
Deprecated class methods
CCFXException class
CCFXQuery class
CCFXRequest class
CCFXStringSet class

#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

2893

Adobe ColdFusion Documentation

C++ class overview
The following table lists the CFXAPI classes and methods:
Class

Methods

CCFXException class

:GetError
:GetDiagnostics

CCFXQuery class

:AddRow
:GetColumns
:GetData
:GetName
:GetRowCount
:SetData

CCFXRequest class

:AddQuery
:AttributeExists
:CreateStringSet
:Debug
:GetAttribute
:GetAttributeList
:GetCustomData
:GetQuery
:ReThrowException
:SetCustomData
:SetVariable
:ThrowException
:Write
:WriteDebug

CCFXStringSet class

:AddString
:GetCount
:GetIndexForString
:GetString

#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

2894

Adobe ColdFusion Documentation

Deprecated class methods
The following CFXAPI classes and methods are deprecated. They do not work, and might cause an error, in later
releases.
Class

Deprecated member

Deprecated as of this ColdFusion
release

CCFXQuery Class

CCFXQuery::SetQueryStringCCFX
Query::SetTotalTime

ColdFusion MXColdFusion MX

CCFXRequest Class

CCFXRequest::GetSetting

ColdFusion MX

#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

2895

Adobe ColdFusion Documentation

CCFXException class
An abstract class that represents an exception thrown during processing of a ColdFusion Extension (CFX)
procedure.
The CCFXRequest class, CCFXQuery class, and CCFXStringSet class can throw exceptions of this type.
Your ColdFusion Extension code must be written to handle exceptions of this type.
Class methods
virtual LPCSTR GetError()

The :GetError function returns a general error
message.

virtual LPCSTR GetDiagnostics()

The :GetDiagnostics function returns detailed error
information.

CCFXException::GetError
Description

Provides basic user output for exceptions that occur during processing.
CCFXException::GetDiagnostics
Description

Provides detailed user output for exception that occur during processing.
Example

This code block shows how GetError and GetDiagnostics work with ThrowException and ReThrowException.

© 2014 Adobe Systems Incorporated. All rights reserved.

2896

Adobe ColdFusion Documentation

// Write output back to the user here...
pRequest->Write( "Hello from CFX_FOO2!" ) ;
pRequest->ThrowException("User Error", "You goof'd...");
// Output optional debug info
if ( pRequest->Debug() )
{
pRequest->WriteDebug( "Debug info..." ) ;
}
// Catch ColdFusion exceptions & re-raise them
catch( CCFXException* e )
{
// This is how you would pull the error information
LPCTSTR strError = e->GetError();
LPCTSTR strDiagnostic = e->GetDiagnostics();
pRequest->ReThrowException( e ) ;
}
// Catch ALL other exceptions and throw them as
// ColdFusion exceptions (DO NOT REMOVE! -// this prevents the server from crashing in
// case of an unexpected exception)
catch( ... )
{
pRequest->ThrowException(
"Error occurred in tag CFX_FOO2",
"Unexpected error occurred while processing tag." ) ;
}

#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

2897

Adobe ColdFusion Documentation

CCFXQuery class
An abstract class that represents a query used or created by a ColdFusion Extension (CFX). Queries contain one or
more columns of data that extend over a varying number of rows.
Class methods
virtual int AddRow()

:AddRow adds a row to a query.

virtual CCFXStringSet* GetColumns

:GetColumns retrieves a list of a query's column
names.

virtual LPCSTR GetData( int iRow, int
iColumn )

:GetData retrieves a data element from a row and
column of a query.

virtual LPCSTR GetName()

:GetName retrieves the name of a query.

virtual int GetRowCount()

:GetRowCount retrieves the number of rows in a
query.

virtual void SetData( int iRow, int
iColumn, LPCSTR lpszData )

:SetData sets a data element within a row and
column of a query.

virtual void SetQueryString( LPCSTR
lpszQuery )

This function is deprecated. It might not work, and
might cause an error, in later releases.

virtual void SetTotalTime( DWORD
dwMilliseconds )

This function is deprecated. It might not work, and
might cause an error, in later releases.

CCFXQuery::AddRow
Syntax

int CCFXQuery::AddRow(void)

Description

Add a row to the query. Call this function to append a row to a query.
Returns

Returns the index of the row that was appended to a query.
Example

The following example shows the addition of two rows to a three-column ('City', 'State', and 'Zip') query:

© 2014 Adobe Systems Incorporated. All rights reserved.

2898

Adobe ColdFusion Documentation

// First row
int iRow ;
iRow = pQuery->AddRow()
pQuery->SetData( iRow,
pQuery->SetData( iRow,
pQuery->SetData( iRow,

;
iCity, "Minneapolis" ) ;
iState, "MN" ) ;
iZip, "55345" ) ;

// Second row
iRow = pQuery->AddRow() ;
pQuery->SetData( iRow, iCity, "St. Paul" ) ;
pQuery->SetData( iRow, iState, "MN" ) ;
pQuery->SetData( iRow, iZip, "55105" ) ;

CCFXQuery::GetColumns
Syntax

CCFXStringSet* CCFXQuery::GetColumns(void)

Description

Retrieves a list of the column names contained in a query.
Returns

Returns an object of CCFXStringSet class that contains a list of the columns in the query. ColdFusion
automatically frees the memory that is allocated for the returned string set, after the request is completed.
Example

The following example gets the list of columns, then iterates over the list, writing each column name back to the
user:

// Get the list of columns from the query
CCFXStringSet* pColumns = pQuery->GetColumns() ;
int nNumColumns = pColumns->GetCount() ;
// Print the list of columns to the user
pRequest->Write( "Columns in query: " ) ;
for( int i=1; i<=nNumColumns; i++ )
{
pRequest->Write( pColumns->GetString( i ) ) ;
pRequest->Write( " " ) ;
}

CCFXQuery::GetData
Syntax

© 2014 Adobe Systems Incorporated. All rights reserved.

2899

Adobe ColdFusion Documentation

LPCSTR CCFXQuery::GetData(int iRow, int iColumn)

Description

Gets a data element from a row and column of a query. Row and column indexes begin with 1. You can determine
the number of rows in a query by calling :GetRowCount. You can determine the number of columns in a query by
retrieving the list of columns using :GetColumns, and then calling :GetCount on the returned string set.
Returns

Returns the value of the requested data element.
Parameters

Parameter

Description

iRow

Row to retrieve data from (1-based)

iColumn

Column to retrieve data from (1-based)

Example

The following example iterates over the elements of a query and writes the data in the query back to the user in a
simple, space-delimited format:

int iRow, iCol ;
int nNumCols = pQuery->GetColumns()->GetCount() ;
int nNumRows = pQuery->GetRowCount() ;
for ( iRow=1; iRow<=nNumRows; iRow++ )
{
for ( iCol=1; iCol<=nNumCols; iCol++ )
{
pRequest->Write( pQuery->GetData( iRow, iCol ) ) ;
pRequest->Write( " " ) ;
}
pRequest->Write( "
" ) ;
}

CCFXQuery::GetName
Syntax

LPCSTR CCFXQuery::GetName(void)

Description

© 2014 Adobe Systems Incorporated. All rights reserved.

2900

Adobe ColdFusion Documentation

Returns the name of a query.
Example

The following example retrieves the name of a query and writes it back to the user:

CCFXQuery* pQuery = pRequest->GetQuery() ;
pRequest->Write( "The query name is: " ) ;
pRequest->Write( pQuery->GetName() ) ;

CCFXQuery::GetRowCount
Syntax

int CCFXQuery::GetRowCount(void)

Description

Returns the number of rows contained in a query.
Example

The following example retrieves the number of rows in a query and writes it back to the user:

CCFXQuery* pQuery = pRequest->GetQuery() ;
char buffOutput[256] ;
wsprintf( buffOutput,
"The number of rows in the query is %ld.",
pQuery->GetRowCount() ) ;
pRequest->Write( buffOutput ) ;

CCFXQuery::SetData
Syntax

void CCFXQuery::SetData(int iRow, int iColumn, LPCSTR lpszData)

Description

Sets a data element within a row and column of a query. Row and column indexes begin with 1. Before calling SetD
ata for a given row, call :AddRow and use the return value as the row index for your call to SetData.
Parameters

Parameter

© 2014 Adobe Systems Incorporated. All rights reserved.

Description

2901

Adobe ColdFusion Documentation

iRow

Row of data element to set (1-based)

iColumn

Column of data element to set (1-based)

lpszData

New value for data element

Example

The following example shows the addition of two rows to a three-column ('City', 'State', and 'Zip') query:

// First row
int iRow ;
iRow = pQuery->AddRow() ;
pQuery->SetData( iCity, iRow, "Minneapolis" ) ;
pQuery->SetData( iState, iRow, "MN" ) ;
pQuery->SetData( iZip, iRow, "55345" ) ;
// Second row
iRow = pQuery->AddRow() ;
pQuery->SetData( iCity, iRow, "St. Paul" ) ;
pQuery->SetData( iState, iRow, "MN" ) ;
pQuery->SetData( iZip, iRow, "55105" ) ;

#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

2902

Adobe ColdFusion Documentation

CCFXRequest class
Abstract class that represents a request made to a ColdFusion Extension (CFX). An instance of this class is passed
to the main function of your extension DLL. The class provides interfaces that can be used by the custom extension
for the following actions:
Reading and writing variables
Returning output
Creating and using queries
Throwing exceptions
Class methods
virtual BOOL AttributeExists( LPCSTR
lpszName )

:AttributeExists checks whether the attribute was
passed to the tag.

virtual LPCSTR GetAttribute( LPCSTR
lpszName )

:GetAttribute gets the value of the passed
attribute.

virtual CCFXStringSet* GetAttributeList()

:GetAttributeList gets an array of attribute names
passed to the tag.

virtual CCFXQuery* GetQuery()

:GetQuery gets the query that was passed to the tag.

virtual LPCSTR GetSetting( LPCSTR
lpszSettingName )

{{CCFXRequest::GetSetting}}This method is
deprecated. It might not work, and might cause an
error, in later releases.

virtual void Write( LPCSTR lpszOutput )

:Write writes text output back to the user.

virtual void SetVariable( LPCSTR lpszName
, LPCSTR lpszValue )

:SetVariable sets a variable in the template that
contains this tag.

virtual CCFXQuery* AddQuery( LPCSTR
lpszName, CCFXStringSet* pColumns )

:AddQuery adds a query to the template that contains
this tag.

virtual BOOL Debug()

:Debug checks whether the tag contains the Debug att
ribute.

virtual void WriteDebug( LPCSTR
lpszOutput )

:WriteDebug writes text output into the debug
stream.

virtual CCFXStringSet* CreateStringSet()

:CreateStringSet allocates and returns a CCFXStr
ingSet instance.

virtual void ThrowException( LPCSTR
lpszError, LPCSTR lpszDiagnostics )

:ThrowException throws an exception and ends
processing of this request.

© 2014 Adobe Systems Incorporated. All rights reserved.

2903

Adobe ColdFusion Documentation

virtual void ReThrowException(
CCFXException* e )

:ReThrowException rethrows an exception that has
been caught.

virtual void SetCustomData( LPVOID
lpvData )

:SetCustomData sets custom (tag specific) data to
carry with a request.

virtual LPVOID GetCustomData()

:GetCustomData gets custom (tag specific) data for a
request.

CCFXRequest::AddQuery
Syntax

CCFXQuery* CCFXRequest::AddQuery(LPCSTR lpszName, CCFXStringSet* pColumns)

Description

Adds a query to the calling template. The query can be accessed by CFML tags (for example, cfoutput or cftabl
e) within the template. After calling AddQuery, the query is empty (it has 0 rows). To populate the query with data,
call the :AddRow and :SetData functions.
Returns

Returns a pointer to the query that was added to the template (an object of class CCFXQuery). The memory
allocated for the returned query is freed automatically by ColdFusion after the request is completed.
Parameters

Parameter

Description

lpszName

Name of query to add to the template (must be unique)

pColumns

List of column names to be used in the query

Example

The following example adds a query named 'People' to the calling template. The query has two columns
('FirstName' and 'LastName') and two rows:

© 2014 Adobe Systems Incorporated. All rights reserved.

2904

Adobe ColdFusion Documentation

// Create a string set and add the column names to it
CCFXStringSet* pColumns = pRequest->CreateStringSet() ;
int iFirstName = pColumns->AddString( "FirstName" ) ;
int iLastName = pColumns->AddString( "LastName" ) ;
// Create a query that contains these columns
CCFXQuery* pQuery = pRequest->AddQuery( "People", pColumns ) ;
// Add data to the query
int iRow ;
iRow = pQuery->AddRow() ;
pQuery->SetData( iRow, iFirstName, "John"
pQuery->SetData( iRow, iLastName, "Smith"
iRow = pQuery->AddRow() ;
pQuery->SetData( iRow, iFirstName, "Jane"
pQuery->SetData( iRow, iLastName, "Doe" )

) ;
) ;
) ;
;

CCFXRequest::AttributeExists
Syntax

BOOL CCFXRequest::AttributeExists(LPCSTR lpszName)

Description

Checks whether the parameter was passed to the tag. Returns True if the parameter is available; False, otherwise.
Parameters

Parameter

Description

lpszName

Name of the parameter to check (case insensitive)

Example

The following example checks whether the user passed an attribute named DESTINATION to the tag, and throws an
exception if the attribute was not passed:

if ( pRequest->AttributeExists("DESTINATION")==FALSE )
{
pRequest->ThrowException(
"Missing DESTINATION parameter",
"You must pass a DESTINATION parameter in "
"order for this tag to work correctly." ) ;
}

CCFXRequest::CreateStringSet

© 2014 Adobe Systems Incorporated. All rights reserved.

2905

Adobe ColdFusion Documentation

Syntax

CCFXStringSet* CCFXRequest::CreateStringSet(void)

Description

Allocates and returns an instance. Always use this function to create string sets, as opposed to directly using the ne
w operator.
Returns

Returns an object of CCFXStringSet class. The memory allocated for the returned string set is freed
automatically by ColdFusion after the request is completed
Example

The following example creates a string set and adds three strings to it:

CCFXStringSet* pColors = pRequest->CreateStringSet() ;
pColors->AddString( "Red" ) ;
pColors->AddString( "Green" ) ;
pColors->AddString( "Blue" ) ;

CCFXRequest::Debug
Syntax

BOOL CCFXRequest::Debug(void)

Description

Checks whether the tag contains the Debug attribute. Use this function to determine whether to write debug
information for a request. For more information, see :WriteDebug.
Returns

Returns True if the tag contains the Debug attribute; False, otherwise.
Example

The following example checks whether the Debug attribute is present, and if it is, it writes a brief debug message:

© 2014 Adobe Systems Incorporated. All rights reserved.

2906

Adobe ColdFusion Documentation

if ( pRequest->Debug() )
{
pRequest->WriteDebug( "Top secret debug info" ) ;
}

CCFXRequest::GetAttribute
Syntax

LPCSTR CCFXRequest::GetAttribute(LPCSTR lpszName)

Description

Retrieves the value of the passed attribute. Returns an empty string if the attribute does not exist. (To test whether
an attribute was passed to the tag, use :AttributeExists.)
Returns

Returns the value of the attribute passed to the tag. If no attribute of that name was passed to the tag, an empty
string is returned.
Parameters

Parameter

Description

lpszName

Name of the attribute to retrieve (case insensitive)

Example

The following example retrieves an attribute named DESTINATION and writes its value back to the user:

LPCSTR lpszDestination = pRequest->GetAttribute("DESTINATION") ;
pRequest->Write( "The destination is: " ) ;
pRequest->Write( lpszDestination ) ;

CCFXRequest::GetAttributeList
Syntax

CCFXStringSet* CCFXRequest::GetAttributeList(void)

Description

© 2014 Adobe Systems Incorporated. All rights reserved.

2907

Adobe ColdFusion Documentation

Gets an array of attribute names passed to the tag. To get the value of one attribute, use :GetAttribute.
Returns

Returns an object of class CCFXStringSet class that contains a list of attributes passed to the tag. The memory
allocated for the returned string set is freed automatically by ColdFusion after the request is completed.
Example

The following example gets the list of attributes and iterates over the list, writing each attribute and its value back to
the user.

LPCSTR lpszName, lpszValue ;
CCFXStringSet* pAttribs = pRequest->GetAttributeList() ;
int nNumAttribs = pAttribs->GetCount() ;
for( int i=1; i<=nNumAttribs; i++ )
{
lpszName = pAttribs->GetString( i ) ;
lpszValue = pRequest->GetAttribute( lpszName ) ;
pRequest->Write( lpszName ) ;
pRequest->Write( " = " ) ;
pRequest->Write( lpszValue ) ;
pRequest->Write( "
" ) ;
}

CCFXRequest::GetCustomData
Syntax

LPVOID CCFXRequest::GetCustomData(void)

Description

Gets the custom (tag specific) data for the request. This method is typically used from within subroutines of a tag
implementation to extract tag data from a request.
Returns

Returns a pointer to the custom data, or NULL if no custom data has been set during this request using :SetCusto
mData.
Example

The following example retrieves a pointer to a request specific data structure of hypothetical type MYTAGDATA:

© 2014 Adobe Systems Incorporated. All rights reserved.

2908

Adobe ColdFusion Documentation

void DoSomeGruntWork( CCFXRequest* pRequest )
{
MYTAGDATA* pTagData =
(MYTAGDATA*)pRequest->GetCustomData() ;
... remainder of procedure ...
}

CCFXRequest::GetQuery
Syntax

CCFXQuery* CCFXRequest::GetQuery(void)

Description

Retrieves a query that was passed to a tag. To pass a query to a custom tag, you use the QUERY attribute. Set the
attribute to the name of a query (created using the cfquery tag or another custom tag). The QUERY attribute is
optional and must be used only by tags that process an existing data set.
Returns

Returns an object of the CCFXQuery class that represents the query passed to the tag. If no query was passed to
the tag, NULL is returned. The memory allocated for the returned query is freed automatically by ColdFusion after
the request is completed.
Example

The following example retrieves the query that was passed to the tag. If no query was passed, an exception is
thrown:

CCFXQuery* pQuery = pRequest->GetQuery() ;
if ( pQuery == NULL )
{
pRequest->ThrowException(
"Missing QUERY parameter",
"You must pass a QUERY parameter in "
"order for this tag to work correctly." ) ;
}

CCFXRequest::ReThrowException
Syntax

© 2014 Adobe Systems Incorporated. All rights reserved.

2909

Adobe ColdFusion Documentation

void CCFXRequest::ReThrowException(CCFXException* e)

Description

Rethrows an exception that has been caught within an extension procedure. This function is used to avoid having
C++ exceptions that are thrown by DLL extension code propagate back into ColdFusion. Catch ALL C++ exceptions
that occur in extension code, and either re-throw them (if they are of the CCFXException class) or create and
throw a new exception pointer using :ThrowException.
Parameters

Parameter

Description

e

A CCFXException that has been caught

Example

The following code demonstrates how to handle exceptions in ColdFusion Extension DLL procedures:

try
{
...Code that could throw an exception...
}
catch( CCFXException* e )
{
...Do appropriate resource cleanup here...
// Re-throw the exception
pRequest->ReThrowException( e ) ;
}
catch( ... )
{
// Something nasty happened
pRequest->ThrowException(
"Unexpected error occurred in CFX tag", "" ) ;
}

CCFXRequest::SetCustomData
Syntax

void CCFXRequest::SetCustomData(LPVOID lpvData)

Description

Sets custom (tag specific) data to carry with the request. Use this function to store request specific data to pass to

© 2014 Adobe Systems Incorporated. All rights reserved.

2910

Adobe ColdFusion Documentation

procedures within your custom tag implementation.
Parameters

Parameter

Description

lpvData

Pointer to custom data

Example

The following example creates a request-specific data structure of hypothetical type MYTAGDATA and stores a
pointer to the structure in the request for future use:

void ProcessTagRequest( CCFXRequest* pRequest )
try
{
MYTAGDATA tagData ;
pRequest->SetCustomData( (LPVOID)&tagData ) ;
... remainder of procedure ...
}

CCFXRequest::SetVariable
Syntax

void CCFXRequest::SetVariable(LPCSTR lpszName, LPCSTR lpszValue)

Description

Sets a variable in the calling template. If the variable name already exists in the template, its value is replaced. If it
does not exist, a variable is created. The values of variables created using SetVariable can be accessed in the
same manner as other template variables (for example, #MessageSent#).
Parameters

Parameter

Description

lpszName

Name of variable

lpszValue

Value of variable

Example

The following example sets the value of a variable named 'MessageSent' based on the success of an operation
performed by the custom tag:

© 2014 Adobe Systems Incorporated. All rights reserved.

2911

Adobe ColdFusion Documentation

BOOL bMessageSent;
...attempt to send the message...
if ( bMessageSent == TRUE )
{
pRequest->SetVariable( "MessageSent", "Yes" ) ;
}
else
{
pRequest->SetVariable( "MessageSent", "No" ) ;
}

CCFXRequest::ThrowException
Syntax

void CCFXRequest::ThrowException(LPCSTR lpszError, LPCSTR lpszDiagnostics)

Description

Throws an exception and ends processing of a request. Call this function when you encounter an error that does not
allow you to continue processing the request. This function is almost always combined with the :ReThrowExcepti
on to protect against resource leaks in extension code.
Parameters

Parameter

Description

lpszError

Short identifier for error

lpszDiagnostics

Error diagnostic information

Example

The following example throws an exception indicating that an unexpected error occurred while processing a request:

char buffError[512] ;
wsprintf( buffError,
"Unexpected Windows NT error number %ld "
"occurred while processing request.", GetLastError() ) ;
pRequest->ThrowException( "Error occurred", buffError ) ;

CCFXRequest::Write
Syntax

© 2014 Adobe Systems Incorporated. All rights reserved.

2912

Adobe ColdFusion Documentation

void CCFXRequest::Write(LPCSTR lpszOutput)

Description

Writes text output back to the user.
Parameters

Parameter

Description

lpszOutput

Text to output

Example

The following example creates a buffer to hold an output string, fills the buffer with data, and writes the output back
to the user:

CHAR buffOutput[1024] ;
wsprintf( buffOutput, "The destination is: %s",
pRequest->GetAttribute("DESTINATION") ) ;
pRequest->Write( buffOutput ) ;

CCFXRequest::WriteDebug
Syntax

void CCFXRequest::WriteDebug(LPCSTR lpszOutput)

Description

Writes text output into the debug stream. The text is only displayed to the end user if the tag contains the Debug attri
bute. (For more information, see :Debug.)
Parameters

Parameter

Description

lpszOutput

Text to output

Example

The following example checks whether the Debug attribute is present; if so, it writes a brief debug message:

© 2014 Adobe Systems Incorporated. All rights reserved.

2913

Adobe ColdFusion Documentation

if ( pRequest->Debug() )
{
pRequest->WriteDebug( "Top secret debug info" ) ;
}

#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

2914

Adobe ColdFusion Documentation

CCFXStringSet class
Abstract class that represents a set of ordered strings. You can add strings to a set and retrieve them by a numeric
index (index values for strings are 1-based). To create a string set, use :CreateStringSet.
Class methods
virtual int AddString( LPCSTR lpszString )

:AddString adds a string to the end of a list.

virtual int GetCount()

:GetCount gets the number of strings contained in a
list.

virtual LPCSTR GetString( int iIndex )

:GetString gets the string located at the passed
index.

virtual int GetIndexForString( LPCSTR lps
zString )

:GetIndexForString gets the index for the passed
string.

CCFXStringSet::AddString
Syntax

int CCFXStringSet::AddString(LPCSTR lpszString)

Description

Adds a string to the end of the list.
Returns

The index of the string that was added.
Parameters

Parameter

Description

lpszString

String to add to the list

Example

The following example demonstrates adding three strings to a string set and saving the indexes of the items that are
added:

CCFXStringSet* pSet = pRequest->CreateStringSet() ;
int iRed = pSet->AddString( "Red" ) ;
int iGreen = pSet->AddString( "Green" ) ;
int iBlue = pSet->AddString( "Blue" ) ;

© 2014 Adobe Systems Incorporated. All rights reserved.

2915

Adobe ColdFusion Documentation

CCFXStringSet::GetCount
Syntax

int CCFXStringSet::GetCount(void)

Description

Gets the number of strings in a string set. The value can be used with :GetString to iterate over the strings in the
set (recall that the index values for strings in the list begin at 1).
Returns

Returns the number of strings contained in the string set.
Example

The following example demonstrates using GetCount with :GetString to iterate over a string set and write the
contents of the list back to the user:

int nNumItems = pStringSet->GetCount() ;
for ( int i=1; i<=nNumItems; i++ )
{
pRequest->Write( pStringSet->GetString( i ) ) ;
pRequest->Write( "
" ) ;
}

CCFXStringSet::GetIndexForString
Syntax

int CCFXStringSet::GetIndexForString(LPCSTR lpszString)

Description

Searches for a passed string. The search is case-insensitive.
Returns

If the string is found, its index within the string set is returned. If it is not found, the constant CFX_STRING_NOT_FOU
ND is returned.
Parameters

Parameter

© 2014 Adobe Systems Incorporated. All rights reserved.

Description

2916

Adobe ColdFusion Documentation

lpszString

String to search for

Example

The following example demonstrates a search for a string and throwing an exception if it is not found:

CCFXStringSet* pAttribs = pRequest->GetAttributeList() ;
int iDestination = pAttribs->GetIndexForString("DESTINATION") ;
if ( iDestination == CFX_STRING_NOT_FOUND )
{
pRequest->ThrowException(
"DESTINATION attribute not found."
"The DESTINATION attribute is required "
"by this tag." ) ;
}

CCFXStringSet::GetString
Syntax

LPCSTR CCFXStringSet::GetString(int iIndex)

Description

Retrieves the string located at the passed index (index values are 1-based).
Returns

Returns the string located at the passed index.
Parameters

Parameter

Description

iIndex

Index of string to retrieve

Example

The following example demonstrates GetString with :GetCount to iterate over a string set and write the contents
of a list back to the user:

© 2014 Adobe Systems Incorporated. All rights reserved.

2917

Adobe ColdFusion Documentation

int nNumItems = pStringSet->GetCount() ;
for ( int i=1; i<=nNumItems; i++ )
{
pRequest->Write( pStringSet->GetString( i ) ) ;
pRequest->Write( "
" ) ;
}

Class methods
CCFXStringSet::AddString
Syntax
Description
Returns
Parameters
Example
CCFXStringSet::GetCount
Syntax
Description
Returns
Example
CCFXStringSet::GetIndexForString
Syntax
Description
Returns
Parameters
Example
CCFXStringSet::GetString
Syntax
Description
Returns
Parameters
Example

© 2014 Adobe Systems Incorporated. All rights reserved.

2918

Adobe ColdFusion Documentation

ColdFusion Java CFX Reference
ColdFusion includes Java interfaces for building ColdFusion custom CFXs in Java.
Class libraries overview
Custom tag interface
Query interface
Request interface
Response interface
Debugging classes reference

#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

2919

Adobe ColdFusion Documentation

Class libraries overview
The following Java interfaces are available for building ColdFusion custom CFXs in Java:
Interface

Methods

Custom tag interface

processRequest

Query interface

addRow
getColumnIndex
getColumns
getData
getName
getRowCount
setData

Request interface

attributeExists
debug
getAttribute
getAttributeList
getIntAttribute
getQuery
getSetting

Response interface

addQuery
SetVariable
write
writeDebug

#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

2920

Adobe ColdFusion Documentation

Custom tag interface
public abstract interface CustomTag

Interface for implementing custom tags.
Classes that implement this interface can be specified in the CLASS attribute of the Java CFX tag. For example, in a
class MyCustomTag, which implements this interface, the following CFML code calls the MyCustomTag.processR
equest method:



Other attributes can be passed to the Java CFX tag. Their values are available using the Request object passed to
the processRequest method.
Methods
Returns

Syntax

Description

void

processRequest(Request reque
st{{, Response}} response)

Processes a request originating
from the CFX_mycustomtag tag

processRequest
Description

Processes a request originating from the Java CFX tag.
Category

Custom tag interface
Syntax

public void processRequest(Request request, Response response)

Throws

Exception If an unexpected error occurs while processing the request.
Parameters

Parameter

Description

request

Parameters (attributes, query, and so on.) for this
request

© 2014 Adobe Systems Incorporated. All rights reserved.

2921

Adobe ColdFusion Documentation

response

Interface for generating response to request (output,
variables, queries, and so on)

#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

2922

Adobe ColdFusion Documentation

Query interface
public abstract interface Query

Interface to a query used or created by a custom tag. A query contains tabular data organized by named columns
and rows.
Methods
Returns

Method

Description

int

addRow()(in CCFXQuery
class)

Adds a row to the query

int

getColumnIndex(String name)

Gets the index of a column given its
name

String[]

getColumns()

Gets a list of the column names in a
query

String

getData(int iRow, int
iCol)

Gets a data element from a row and
column of a query

String

getName()

Gets the name of a query

int

getRowCount()

Gets the number of rows in a query

void

setData(int iRow, int
iCol, String data)

Sets a data element in a row and
column of a query

addRow
Description

Adds a row to a query. Call this method to append a row to a query. Returns the index of the row that was appended
to the query.
Category

Query interface
Syntax

public int addRow()

See also

© 2014 Adobe Systems Incorporated. All rights reserved.

2923

Adobe ColdFusion Documentation

setData, getData
Example

The following example demonstrates the addition of two rows to a query that has three columns, City, State, and Zip
:

// Define column indexes
int iCity = 1, iState = 2, iZip = 3 ;
// First row
int iRow = query.addRow() ;
query.setData( iRow, iCity, "Minneapolis" ) ;
query.setData( iRow, iState, "MN" ) ;
query.setData( iRow, iZip, "55345" ) ;
// Second row
iRow = query.addRow() ;
query.setData( iRow, iCity, "St. Paul" ) ;
query.setData( iRow, iState, "MN" ) ;
query.setData( iRow, iZip, "55105" ) ;

getColumnIndex
Description

Returns the index of the column, or 0 if no such column exists.
Category

Query interface
Syntax

public int getColumnIndex(String name)

See also

getColumns, getData
Parameters

Parameter

Description

name

Name of column to get index of (lookup is
case-insensitive)

Example

The following example retrieves the index of the EMAIL column and uses it to output a list of the addresses
contained in the column:

© 2014 Adobe Systems Incorporated. All rights reserved.

2924

Adobe ColdFusion Documentation

// Get the index of the EMAIL column
int iEMail = query.getColumnIndex( "EMAIL" ) ;
// Iterate over the query and output list of addresses
int nRows = query.getRowCount() ;
for( int iRow = 1; iRow <= nRows; iRow++ )
{
response.write( query.getData( iRow, iEMail ) + "
" ) ;
}

getColumns
Description

Returns an array of strings containing the names of the columns in the query.
Category

Query interface
Syntax

public String[] getColumns()

Example

The following example retrieves the array of columns, then iterates over the list, writing each column name back to
the user:

// Get the list of columns from the query
String[] columns = query.getColumns() ;
int nNumColumns = columns.length ;
// Print the list of columns to the user
response.write( "Columns in query: " ) ;
for( int i=0; i" ) ;
}

getName
Description

Returns the name of a query.
Category

Query interface

© 2014 Adobe Systems Incorporated. All rights reserved.

2926

Adobe ColdFusion Documentation

Syntax

public String getName()

Example

The following example retrieves the name of a query and writes it back to the user:

Query query = request.getQuery() ;
response.write( "The query name is: " + query.getName() ) ;

getRowCount
Description

Retrieves the number of rows in a query. Returns the number of rows contained in a query.
Category

Query interface
Syntax

public int getRowCount()
Example

The following example retrieves the number of rows in a query and writes it back to the user:

Query query = request.getQuery() ;
int rows = query.getRowCount() ;
response.write( "The number of rows in the query is "
+ Integer.ToString(rows) ) ;

setData
Description

Sets a data element in a row and column of a query. Row and column indexes begin with 1. Before calling setData
for a given row, call addRow and use the return value as the row index for your call to setData.
Category

Query interface
Syntax

© 2014 Adobe Systems Incorporated. All rights reserved.

2927

Adobe ColdFusion Documentation

public void setData(int iRow, int iCol, String data)

Throws

IndexOutOfBoundsException if an invalid index is passed to the method.
See also

getData, addRow
Parameters

Parameter

Description

iRow

Row of data element to set (1-based)

iCol

Column of data element to set (1-based)

data

New value for data element

Example

The following example demonstrates the addition of two rows to a query that has three columns, City, State, and Zip
:

// Define column indexes
int iCity = 1, iState = 2, iZip = 3 ;
// First row
int iRow = query.addRow() ;
query.setData( iRow, iCity, "Minneapolis" ) ;
query.setData( iRow, iState, "MN" ) ;
query.setData( iRow, iZip, "55345" ) ;

// Second row
iRow = query.addRow() ;
query.setData( iRow, iCity, "St. Paul" ) ;
query.setData( iRow, iState, "MN" ) ;
query.setData( iRow, iZip, "55105" ) ;

#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

2928

Adobe ColdFusion Documentation

Request interface
public abstract interface Request

Interface to a request made to a CustomTag. The interface includes methods for retrieving attributes passed to the
tag (including queries) and reading global tag settings.
Methods
Returns

Syntax

Description

boolean

attributeExists(String name
)

Checks whether the attribute was
passed to this tag.

boolean

debug()

Checks whether the tag contains
the debug attribute.

String

getAttribute(String name)

Retrieves the value of the passed
attribute.

String[]

getAttributeList()

Retrieves a list of attributes passed
to the tag.

int

getIntAttribute(String name
)

Retrieves the value of the passed
attribute as an integer.

int

getIntAttribute(String name
, int def)

Retrieves the value of the passed
attribute as an integer (returns
default if the attribute does not exist
or is not a valid number).

Query

getQuery()

Retrieves the query that was
passed to this tag.

attributeExists
Description

Checks whether the attribute was passed to this tag. Returns True if the attribute is available; otherwise returns
False.
Category

Request interface
Syntax

© 2014 Adobe Systems Incorporated. All rights reserved.

2929

Adobe ColdFusion Documentation

public boolean attributeExists(String name)

See also

getAttribute, getAttributeList
Parameters

Parameter

Description

name

Name of the attribute to check (case-insensitive)

Example

The following example checks whether the user passed an attribute named DESTINATION to the tag; if not, it
throws an exception:

if ( ! request.attributeExists("DESTINATION") )
{
throw new Exception(
"Missing DESTINATION parameter",
"You must pass a DESTINATION parameter in "
"order for this tag to work correctly." ) ;
} ;

debug
Description

Checks whether the tag contains the debug attribute. Use this method to determine whether to write debug
information for this request. For more information, see writeDebug. Returns True if the tag contains the debug attr
ibute; False, otherwise.
Category

Request interface
Syntax

public boolean debug()

See also

writeDebug
Example

© 2014 Adobe Systems Incorporated. All rights reserved.

2930

Adobe ColdFusion Documentation

The following example checks whether the debug attribute is present, and if so, it writes a brief debug message:

if ( request.debug() )
{
response.writeDebug( "debug info" ) ;
}

getAttribute
Description

Retrieves the value of a passed attribute. Returns an empty string if the attribute does not exist (use attributeEx
ists to test whether an attribute was passed to the tag). Use getAttribute(String,String) to return a
default value rather than an empty string. Returns the value of the attribute passed to the tag. If no attribute of that
name was passed to the tag, an empty string is returned.
Category

Request interface
Syntax

public String getAttribute(String name)

See also

attributeExists, getAttributeList, getIntAttribute
Parameters

Parameter

Description

name

The attribute to retrieve (case-insensitive)

Example

The following example retrieves an attribute named DESTINATION and writes its value back to the user:

String strDestination = request.getAttribute("DESTINATION") ;
response.write( "The destination is: " + strDestination ) ;

getAttributeList
Description

Retrieves a list of attributes passed to the tag. To retrieve the value of one attribute, use the getAttribute metho

© 2014 Adobe Systems Incorporated. All rights reserved.

2931

Adobe ColdFusion Documentation

d. Returns an array of strings containing the names of the attributes passed to the tag.
Category

Request interface
Syntax

public String[] getAttributeList()

See also

attributeExists
Example

The following example retrieves the list of attributes, then iterates over the list, writing each attribute and its value
back to the user:

String[] attribs = request.getAttributeList() ;
int nNumAttribs = attribs.length ;
for( int i = 0; i < nNumAttribs; i++ )
{
String strName = attribs[i] ;
String strValue = request.getAttribute( strName ) ;
response.write( strName + "=" + strValue + "
" ) ;
}

getIntAttribute
Description

Retrieves the value of the passed attribute as an integer. Returns -1 if the attribute does not exist. Use attributeE
xists to test whether an attribute was passed to the tag. Use getIntAttribute(String,int) to return a
default value rather than throwing an exception or returning -1. Returns the value of the attribute passed to the tag. If
no attribute of that name was passed to the tag, -1 is returned.
Category

Request interface
Syntax

public int getIntAttribute(String name)

Throws

© 2014 Adobe Systems Incorporated. All rights reserved.

2932

Adobe ColdFusion Documentation

NumberFormatException if the attribute is not a valid number.
See also

attributeExists, getAttributeList
Parameters

Parameter

Description

name

The attribute to retrieve (case-insensitive)

Example

The following example retrieves an attribute named PORT and writes its value back to the user:

int nPort = request.getIntAttribute("PORT") ;
if ( nPort != -1 )
response.write( "The port is: " + String.valueOf(nPort) ) ;

getQuery
Description

Retrieves the query that was passed to this tag. To pass a query to a custom tag, you use the query attribute. It
should be set to the name of a query (created using the cfquery tag). The query attribute is optional and should be
used only by tags that process an existing dataset. Returns the Query that was passed to the tag. If no query was
passed, returns null.
Category

Request interface
Syntax

public Query getQuery()

Example

The following example retrieves a query that was passed to a tag. If no query was passed, an exception is thrown:

© 2014 Adobe Systems Incorporated. All rights reserved.

2933

Adobe ColdFusion Documentation

Query query = request.getQuery() ;
if ( query == null )
{
throw new Exception(
"Missing QUERY parameter. " +
"You must pass a QUERY parameter in "
"order for this tag to work correctly." ) ;
}

getSetting
Description

Retrieves the value of a global custom tag setting. Custom tag settings are stored in the CustomTags section of the
ColdFusion Registry key.Returns the value of the custom tag setting. If no setting of that name exists, an empty
string is returned.
Category

Request interface
Syntax

public String getSetting(String name)
Parameters

Parameter

Description

name

The name of the setting to retrieve (case-insensitive)

Usage

All custom tags implemented in Java share a registry key for storing settings. To avoid name conflicts, preface the
names of settings with the name of your custom tag class. For example, the code below retrieves the value of a
setting named VerifyAddress for a custom tag class named MyCustomTag:

String strVerify = request.getSetting("MyCustomTag.VerifyAddress") ;
if ( Boolean.valueOf(strVerify) )
{
// Do address verification...
}

#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

2934

Adobe ColdFusion Documentation

Response interface
public abstract interface Response

Interface to response generated from a custom tag. This interface includes methods for writing output, generating
queries, and setting variables in the calling page.
Methods
Returns

Syntax

Description

Query

addQuery(String name,
String[] columns)

Adds a query to the calling
template.

void

SetVariable(String name{{,
String}} value)

Sets a variable in the calling
template.

void

write(String output)

Outputs text back to the user.

void

writeDebug(String output)

Writes text output into the debug
stream.

addQuery
Description

Adds a query to the calling template. The query can be accessed by CFML tags in the template. After calling addQu
ery, the query is empty (it has 0 rows). To populate the query with data, call the Query methods addRow and setD
ata. Returns the Query that was added to the template.
Category

Response interface
Syntax

public Query addQuery(String name, String[] columns)

Throws

IllegalArgumentException If the name parameter is not a valid CFML variable name.
See also

addRow, setData
Parameters

© 2014 Adobe Systems Incorporated. All rights reserved.

2935

Adobe ColdFusion Documentation

Parameter

Description

name

The name of the query to add to the template

columns

The column names to use in the query

Example

The following example adds a query named People to the calling template. The query has two columns (FirstName
and LastName) and two rows:

// Create string array with column names (also track columns indexes)
String[] columns = { "FirstName", "LastName" } ;
int iFirstName = 1, iLastName = 2 ;
// Create a query which contains these columns
Query query = response.addQuery( "People", columns ) ;
// Add data to the query
int iRow = query.addRow() ;
query.setData( iRow, iFirstName, "John"
query.setData( iRow, iLastName, "Smith"
iRow = query.addRow() ;
query.setData( iRow, iFirstName, "Jane"
query.setData( iRow, iLastName, "Doe" )

) ;
) ;
) ;
;

setVariable
Description

Sets a variable in the calling template. If the variable name specified exists in the template, its value is replaced. If it
does not exist, a new variable is created.
Category

Response interface
Syntax

public void setVariable(String name, String value)

Throws

IllegalArgumentException If the name parameter is not a valid CFML variable name.
Parameters

Parameter

© 2014 Adobe Systems Incorporated. All rights reserved.

Description

2936

Adobe ColdFusion Documentation

name

The name of the variable to set

value

The value to set the variable to

Example

For example, this code sets the value of a variable named MessageSent based on the success of an operation
performed by the custom tag:

boolean bMessageSent ;
...attempt to send the message...
if ( bMessageSent == true )
{
response.setVariable( "MessageSent", "Yes" ) ;
}
else
{
response.setVariable( "MessageSent", "No" ) ;
}

write
Description

Outputs text back to the user.
Category

Response interface
Syntax

public void write(String output)

Parameters

Parameter

Description

output

Text to output

Example

The following example outputs the value of the DESTINATION attribute:

© 2014 Adobe Systems Incorporated. All rights reserved.

2937

Adobe ColdFusion Documentation

response.write( "DESTINATION = " +
request.getAttribute("DESTINATION") ) ;

writeDebug
Description

Writes text output into the debug stream. This text is displayed to the end-user only if the tag contains the debug attr
ibute (check for this attribute using the Request.debug method).
Category

Response interface
Syntax

public void writeDebug(String output)

See also

debug
Parameters

Parameter

Description

output

The text to output

Example

The following example checks whether the debug attribute is present; if so, it writes a brief debug message:

if ( request.debug() )
{
response.writeDebug( "debug info" ) ;
}

#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

2938

Adobe ColdFusion Documentation

Debugging classes reference
The constructors and methods supported by the DebugRequest, DebugResponse, and DebugQuery classes are
as follows. These classes also support the other methods of the Request, Response, and Query interfaces,
respectively.
DebugRequest

// initialize a debug request with attributes
public DebugRequest( Hashtable attributes ) ;
// initialize a debug request with attributes and a query
public DebugRequest( Hashtable attributes, Query query ) ;
// initialize a debug request with attributes, a query, and settings
public DebugRequest( Hashtable attributes, Query query, Hashtable settings ) ;

DebugResponse

// initialize a debug response
public DebugResponse() ;
// print the results of processing
public void printResults() ;

DebugQuery

// initialize a query with name and columns
public DebugQuery( String name, String[] columns )
throws IllegalArgumentException ;
// initialize a query with name, columns, and data
public DebugQuery( String name, String[] columns, String[][] data )
throws IllegalArgumentException ;

DebugRequest
DebugResponse
DebugQuery

© 2014 Adobe Systems Incorporated. All rights reserved.

2939

Adobe ColdFusion Documentation

WDDX JavaScript Objects
You use JavaScript objects and functions to use with WDDX in a ColdFusion application.
JavaScript object overview
WddxRecordset object
WddxSerializer object

#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

2940

Adobe ColdFusion Documentation

JavaScript object overview
These are the JavaScript objects and functions:
Class

Functions

WddxSerializer object

serialize
serializeVariable
serializeValue
write

WddxRecordset object

addColumn
addRows
getField
getRowCount
setField
wddxSerialize

WDDX JavaScript objects are defined in the wddx.js file; this file is installed in the CFIDE/scripts directory.
To use these objects, you must put a JavaScript tag before the code that refers to the objects; for example:



#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

2941

Adobe ColdFusion Documentation

WddxRecordset object
Includes functions that you call as needed when constructing a WDDX record set. For more information on using
this object, see Using WDDX in the Developing ColdFusion Applications.

Functions

Function syntax

Description

object.addColumn(name)

Adds a column to all rows in a WddxRecordset
instance.

object.addRows(n)

Adds rows to all columns in a WddxRecordset instance.

object.dump(escapeStrings)

Displays WddxRecordset object data.

object.getField(row,col)

Returns the element in a row/column position.

object.getRowCount()

Indicates the number of rows in a WddxRecordset
instance.

object.setField(row, col, value)

Sets the element in a row/column position.

object.wddxSerialize(serializer)

Serializes a record set.

Returns
HTML table of the WddxRecordset object data.
Usage

Convenient for debugging and testing record sets. The boolean parameterescapeStringsdetermines whether<>&
characters in string values are escaped as<>&in HTML.
Example

© 2014 Adobe Systems Incorporated. All rights reserved.

2942

Adobe ColdFusion Documentation



SELECT Message_Id, Thread_id, Username, Posted
FROM messages





addColumn
Description

Adds a column to all rows in a WddxRecordset instance.
Syntax

object.addColumn( name )
Parameters

Parameter

Description

object

Instance name of the WddxRecordset object

name

Name of the column to add

Return value
None.
Usage

Adds a column to every row of the WDDX record set. Initially the new column’s values are set to NULL.
Example

This example calls theaddColumnfunction:

© 2014 Adobe Systems Incorporated. All rights reserved.

2943

Adobe ColdFusion Documentation

// Create a new record set
rs = new WddxRecordset();
// Add a new column
rs.addColumn("NewColumn");
// Extend the record set by 3 rows
rs.addRows(3);
// Set an element in the first row
// newValue is a previously defined variable
rs.setField(0, "NewColumn", newValue);

addRows
Description

Adds rows to all columns in a WddxRecordset instance.
Syntax

object.addRows( n )
Parameters

Parameter

Description

object

Instance name of the WddxRecordset object

n

Integer; number of rows to add

Return value
None.
Usage

This function adds the specified number of rows to every column of a WDDX record set. Initially, the row/column
values are set to NULL.
Example

This example calls theaddRowsfunction:

© 2014 Adobe Systems Incorporated. All rights reserved.

2944

Adobe ColdFusion Documentation

// Create a new record set
rs = new WddxRecordset();
// Add a new column
rs.addColumn("NewColumn");
// Extend the record set by 3 rows
rs.addRows(3);
// Set an element in the first row
// newValue is a previously defined variable
rs.setField(0, "NewColumn", newValue);

getField
Description

Returns the element in the specified row/column position.
Syntax

object.getField( row, col )

Parameters

Parameter

Description

object

Instance name of the WddxRecordset object

row

Integer; zero-based row number of the value to return

col

Integer or string; column of the value to be returned.

Return value
Returns the value in the specified row/column position.
Usage

Call this function to access a value in a WDDX record set.
Example

This example calls thegetFieldfunction (the variable r is a reference to a WddxRecordset instance):

© 2014 Adobe Systems Incorporated. All rights reserved.

2945

Adobe ColdFusion Documentation

for (row = 0; row < nRows; ++row)
{
o += "";
for (i = 0; i < colNames.length; ++i)
{
o += "" + r.getField(row, colNames[i]) + "";
}
o += "";
}

getRowCount
Description

Indicates the number of rows in a WddxRecordset instance.
Syntax

object.getRowCount( )

Parameters
Parameter

Description

object

Instance name of a WddxRecordset object

Return value
Integer. Returns the number of rows in the WddxRecordset instance.
Usage

Call this function before a looping construct to determine the number of rows in a record set.
Example

This example calls thegetRowCountfunction:

© 2014 Adobe Systems Incorporated. All rights reserved.

2946

Adobe ColdFusion Documentation

function dumpWddxRecordset(r)
{
// Get row count
nRows = r.getRowCount();
...
for (row = 0; row < nRows; ++row)
...

setField
Description

Sets the element in the specified row/column position.
Syntax

object.setField( row, col, value )

Parameters
Parameter

Description

object

Instance name of a WddxRecordset object

row

Integer; row that contains the element to set

col

Integer or string; the column containing the element to
set

value

Value to set

Return value
None.
Usage

Call this function to set a value in a WddxRecordset instance.
Example

This example calls thesetFieldfunction:

© 2014 Adobe Systems Incorporated. All rights reserved.

2947

Adobe ColdFusion Documentation

// Create a new recordset
rs = new WddxRecordset();
// Add a new column
rs.addColumn("NewColumn");
// Extend the record set by 3 rows
rs.addRows(3);
// Set an element in the first row
// newValue is a previously defined variable
rs.setField(0, "NewColumn", newValue);

wddxSerialize
Description

Serializes a record set.
Syntax

object.wddxSerialize( serializer )

Parameters
Parameter

Description

object

Instance name of the WddxRecordset object

serializer

WddxSerializer instance

Return value
Returns a Boolean True if serialization was successful; False, otherwise.
Usage

This is an internal function; you do not typically call it.
Example

This example is from the WddxSerializerserializeValuefunction:

© 2014 Adobe Systems Incorporated. All rights reserved.

2948

Adobe ColdFusion Documentation

...
else if (typeof(obj) == "object")
{
if (obj == null)
{
// Null values become empty strings
this.write("");
}
else if (typeof(obj.wddxSerialize) == "function")
{
// Object knows how to serialize itself
bSuccess = obj.wddxSerialize(this);
}
...

© 2014 Adobe Systems Incorporated. All rights reserved.

2949

Adobe ColdFusion Documentation

WddxSerializer object
The WddxSerializer object includes functions that serialize any JavaScript data structure. For more information on
using this object, see Using WDDX in the Developing ColdFusion Applications.
Functions
The only function that developers typically call is serialize.
Function syntax

Description

object.serialize(rootobj)

Creates a WDDX packet for a passed WddxRecordset
instance.

object.serializeVariable(name, obj)

Serializes a property of a structure. If an object is not a
string, number, array, Boolean, or a date,
WddxSerializer treats it as a structure.

object.serializeValue(obj)

Recursively serializes eligible data in a passed
instance.

object.write(str)

Appends data to the serialized data stream.

serialize
Description

Creates a WDDX packet for a passed WddxRecordset instance.
Syntax

object.serialize( rootobj )

Parameters

Parameter

Description

object

Instance name of the WddxSerializer object

rootobj

JavaScript data structure to serialize

Return value

Returns a serialized WDDX packet as a string if the function succeeds, or a null value if an error occurs.
Usage

Call this function to serialize the data in a WddxRecordset instance.

© 2014 Adobe Systems Incorporated. All rights reserved.

2950

Adobe ColdFusion Documentation

Example

This example shows a JavaScript function that you can call to serialize a WddxRecordset instance. It copies
serialized data to a form field for display:

function serialize(data, formField)
{
wddxSerializer = new WddxSerializer();
wddxPacket = wddxSerializer.serialize(data);
if (wddxPacket != null)
{
formField.value = wddxPacket;
}
else
{
alert("Couldn't serialize data");
}
}

serializeVariable
Description

Serializes a property of a structure. If an object is not a string, number, array, Boolean, or date, WddxSerializer
treats it as a structure.
Syntax

object.serializeVariable( name, obj )

Parameters

Parameter

Description

object

Instance name of a WddxSerializer object

name

Property to serialize

obj

Instance name of the value to serialize

Return value

Returns a Boolean True if serialization was successful; False, otherwise.This is an internal function; you do not
typically call it.
Example

This example is from the WddxSerializer serializeValue function:

© 2014 Adobe Systems Incorporated. All rights reserved.

2951

Adobe ColdFusion Documentation

...
// Some generic object; treat it as a structure
this.write("");
for (prop in obj)
{
bSuccess = this.serializeVariable(prop, obj[prop]);
if (! bSuccess)
{
break;
}
}
this.write("");
...

serializeValue
Description

Recursively serializes eligible data in a passed instance. Eligible data includes:
String
Number
Boolean
Date
Array
Recordset
Any JavaScript objectThis function serializes null values as empty strings.
Syntax

object.serializeValue( obj )

Parameters

Parameter

Description

object

Instance name of the WddxSerializer object

obj

Instance name of the WddxRecordset object to
serialize

Return value

Returns a Boolean True if obj was serialized successfully; False, otherwise.
Usage

This is an internal function; you do not typically call it.

© 2014 Adobe Systems Incorporated. All rights reserved.

2952

Adobe ColdFusion Documentation

Example

This example is from the WddxSerializer serialize function:

...
this.wddxPacket = "";
this.write("
");
bSuccess = this.serializeValue(rootObj);
this.write("");
if (bSuccess)
{
return this.wddxPacket;
}
else
{
return null;
}
...

write
Description

Appends data to a serialized data stream.
Syntax

object.write( str )

Parameters

Parameter

Description

object

Instance name of the WddxSerializer object

str

String to be copied to the serialized data stream

Return value

Returns an updated serialized data stream as a String.
Usage

This is an internal function; you do not typically call it.
Example

This example is from the WddxSerializer serializeValue function:

© 2014 Adobe Systems Incorporated. All rights reserved.

2953

Adobe ColdFusion Documentation

...
else if (typeof(obj) == "number")
{
// Number value
this.write("" + obj + "");
}
else if (typeof(obj) == "boolean")
{
// Boolean value
this.write("");
}
...

#back to top

© 2014 Adobe Systems Incorporated. All rights reserved.

2954

Adobe ColdFusion Documentation

ColdFusion ActionScript Functions
ColdFusion includes two server-side ActionScript functions,CF.queryandCF.http., including specific syntax and
methods.

CF.http
CF.query

© 2014 Adobe Systems Incorporated. All rights reserved.

2955

Adobe ColdFusion Documentation

CF.http
Description

Executes HTTP POST and GET operations on files. (POST operations upload MIME file types to a server, or post
cookie, formfield, URL, file, or CGI variables directly to a server.)
Return value

Returns an object containing properties that you reference to access data.
Syntax

CF.http
({
method:"get or post",
url:"URL",
username:"username",
password:"password",
resolveurl:"yes or no",
params:arrayvar,
path:"path",
file:"filename"
})

Arguments

Arguments

Req/Opt

Description

method

Required

One of two arguments:
get: downloads a text or
binary file or creates a query
from the contents of a text
file.
post: sends information to
the server page or CGI
program for processing.
Requires theparamsargume
nt.

url

Required

© 2014 Adobe Systems Incorporated. All rights reserved.

The absolute URL of the host name
or IP address of the server on which
the file resides. The URL must
include the protocol (http or https)
and host name.

2956

Adobe ColdFusion Documentation

username

Optional

When required by a server, a
username.

password

Optional

When required by a server, a
password.

resolveurl

Optional

ForGetandPostmethods.
Yes or No. Default is No.
For GET and POST operations, if
Yes, the page reference that is
returned into the Filecontent
property has its internal URLs fully
resolved, including port number, so
that links remain intact. The
following HTML tags, which can
contain links, are resolved:
-img src
-a href
-form action
-applet code
-script src
-embed src
-embed pluginspace
-body background
-frame src
-bgsound src
-object data
-object classid
-object codebase
-object usemap

© 2014 Adobe Systems Incorporated. All rights reserved.

2957

Adobe ColdFusion Documentation

params

Optional

HTTP parameters passed as an
array of objects. Supports the
following parameter types:
name
type
value
CF.httpparams are passed as an
array of objects. Theparamsargum
ent is required for POST operations.

path

Optional

The path to the directory in which to
store files. When using thepatharg
ument, thefileargument is
required.

file

Optional

Name of the file that is accessed.
For GET operations, defaults to the
name specified in theurlargument.
Enter path information in thepathar
gument. This argument is required if
you are using thepathargument.

Usage

You can write theCF.httpfunction using named arguments or positional arguments. You can invoke all supported
arguments using the named argument style, as follows:

CF.http({method:"method", url:"URL", username:"username", password:"password",
resolveurl:"yes or no", params:arrayvar,
path:"path", file:"filename"});

The named argument style uses curly braces {} to surround the function arguments.

Positional arguments let you use a shorthand coding style. However, not all arguments are supported for the
positional argument style. Use the following syntax to code theCF.httpfunction using positional arguments:

CF.http(url);
CF.http(method, url);
CF.http(method, url, username, password);
CF.http(method, url, params, username, password);

© 2014 Adobe Systems Incorporated. All rights reserved.

2958

Adobe ColdFusion Documentation

Do not use curly braces {} with positional arguments.

The following parameters can only be passed as an array of objects in the paramsargument in theCF.httpfunction:

Parameter

Description

name

The variable name for data that is passed

type

The transaction type:
URL
FormField
Cookie
CGI
File

value

Value of URL, FormField, Cookie, File, or CGI variables
that are passed

The CF.http function returns data as a set of object properties, as described in the following table:

Property

Description

Text

A Boolean value that indicates whether the specified
URL location contains text data.

Charset

The charset used by the document specified in the
URL.
HTTP servers normally provide this information, or the
charset is specified in the charset parameter of the
Content-Type header field of the HTTP protocol. For
example, the following HTTP header announces that
the character encoding is EUC-JP:
Content-Type: text/html; charset=EUC-JP

© 2014 Adobe Systems Incorporated. All rights reserved.

2959

Adobe ColdFusion Documentation

Header

Raw response header. For example:
HTTP/1.1 200 OK
Date: Mon, 04 Mar 2002 17:27:44 GMT
Server: Apache/1.3.22 (Unix) mod_perl/1.26
Set-Cookie:
MM_cookie=207.22.48.162.4731015262864476;
path=/; expires=Wed, 03-Mar-04 17:27:44 GMT;
domain=adobe.com
Connection: close
Content-Type: text/html

Filecontent

File contents, for text and MIME files.

Mimetype

MIME type. Examples of MIME types include text/html,
image/png, image/gif, video/mpeg, text/css, and
audio/basic.

responseHeader

Response header. If there is only one header key, its
value can be accessed as simple type. If there are
multiple header keys, the values are put in an array in a
responseHeader structure.

Statuscode

HTTP error code and associated error string. Common
HTTP status codes returned in the response header
include:
400: Bad Request
401: Unauthorized
403: Forbidden
404: Not Found
405: Method Not Allowed

You access these attributes using thegetfunction:

© 2014 Adobe Systems Incorporated. All rights reserved.

2960

Adobe ColdFusion Documentation

function basicGet()
{
url = "http://localhost:8100/";
// Invoke with just the url. This is an HTTP GET.
result = CF.http(url);
return result.get("Filecontent");
}

For more information on using server-side ActionScript, see Using Server-Side ActionScript in
the Developing ColdFusion Applications.

Example

The following examples show a number of the ways to use theCF.httpfunction:

© 2014 Adobe Systems Incorporated. All rights reserved.

2961

Adobe ColdFusion Documentation

function postWithNamedArgs()
{
// Set up the array of Post parameters.
params = new Array();
params[1] = {name:"arg1", type:"FormField", value:"value1"};
params[2] = {name:"arg2", type:"URL", value:"value2"};
params[3] = {name:"arg3", type:"CGI", value:"value3"};
url = "http://localhost:8100/";
path = application.getContext("/").getRealPath("/");
file = "foo.txt";
result = CF.http({method:"post", url:url, username:"karl", password:"salsa",
resolveurl:true, params:params, path:path, file:file});
if (result)
return result.get("Statuscode");
return null;
}
// Example of a basic HTTP GET operation
// Shows that HTTP GET is the default
function basicGet()
{
url = "http://localhost:8100/";
// Invoke with just the url. This is an HTTP GET.
result = CF.http(url);
return result.get("Filecontent");
}
// Example showing simple array created to pass params arguments
function postWithParams()
{
// Set up the array of Post parameters. These are just like cfhttpparam tags.
params = new Array();
params[1] = {name:"arg2", type:"URL", value:"value2"};
url = "http://localhost:8100/";
// Invoke with the method, url, and params
result = CF.http("post", url, params);
return result.get("Filecontent");
}
// Example with username and params arguments
function postWithParamsAndUser()
{
// Set up the array of Post parameters. These are just like cfhttpparam tags.
params = new Array();
params[1] = {name:"arg2", type:"URL", value:"value2"};
url = "http://localhost:8100/";
// Invoke with the method, url, params, username, and password
result = CF.http("post", url, params, "karl", "salsa");
return result.get("Filecontent");
}

© 2014 Adobe Systems Incorporated. All rights reserved.

2962

Adobe ColdFusion Documentation

© 2014 Adobe Systems Incorporated. All rights reserved.

2963

Adobe ColdFusion Documentation

CF.query
Description

Performs queries against ColdFusion data sources.
Return value

Returns a RecordSet object.
Syntax

CF.query
({
datasource:"data source name",
sql:"SQL stmts",
username:"username",
password:"password",
maxrows:number,
timeout:milliseconds
})

Arguments

Arguments

Req/Opt

Description

datasource

Required

Name of the data source from
which the query retrieves data.

sql

Required

SQL statement.

username

Optional

Username. Overrides the username
specified in the data source setup.

password

Optional

Password. Overrides the password
specified in the data source setup.

maxrows

Optional

Maximum number of rows to return
in the record set.

timeout

Optional

Maximum number of seconds for
the query to execute before
returning an error indicating that the
query has timed out. Can only be
used in named arguments.

© 2014 Adobe Systems Incorporated. All rights reserved.

2964

Adobe ColdFusion Documentation

Usage

You can code theCF.queryfunction using named or positional arguments. You can invoke all supported arguments
using the named argument style, as follows:

CF.query({datasource:"datasource", sql:"sql stmt",
username:"username", password:"password", maxrows:"maxrows",
timeout:"timeout"});

The named argument style uses curly braces {} to surround the function arguments.

Positional argument style, which is a shorthand coding style, does not support all arguments. Use the following
syntax to code theCF.queryfunction using positional arguments:

CF.query(datasource,
CF.query(datasource,
CF.query(datasource,
CF.query(datasource,

sql);
sql, maxrows);
sql, username, password);
sql, username, password, maxrows);

Do not use curly braces {} with positional arguments.

You can manipulate the record set returned by theCF.queryfunction using methods in the RecordSet ActionScript
class. The following are some of the methods available in the RecordSet class:
RecordSet.getColumnnames
RecordSet.getLength
RecordSet.getItemAt
RecordSet.getItemID
RecordSet.sortItemsBy
RecordSet.getNumberAvailable
RecordSet.filter
RecordSet.sort
For more information on using server-side ActionScript, see Using Server-Side ActionScript in the Developing
ColdFusion Applications. For more detailed information about the RecordSet ActionScript class, see Using
Flash Remoting.
Example

© 2014 Adobe Systems Incorporated. All rights reserved.

2965

Adobe ColdFusion Documentation

// Define a function to do a basic query
// Note use of positional arguments
function basicQuery()
{
result = CF.query("myquery", "cust_data", "SELECT * from tblParks");
return result;
}
// Example function declaration using named arguments
function basicQuery()
{
result = CF.query({datasource:"cust_data", sql:"SELECT * from tblParks"});
return result;
}
// Example of the CF.query function using maxrows argument
function basicQueryWithMaxRows()
{
result = CF.query("cust_data", "SELECT * from tblParks", 25);
return result;
}
// Example of the CF.query function with username and password
function basicQueryWithUser()
{
result = CF.query("cust_data", "SELECT * from tblParks",
"wsburroughs", "migraine1");
return result;
}

© 2014 Adobe Systems Incorporated. All rights reserved.

2966

Adobe ColdFusion Documentation

ColdFusion Mobile Functions
Accelerometer Functions
Camera Functions
Connection Functions
Contact Functions
Event Functions
File System Functions
Geolocation Functions
Media and Capture Functions
Notification Functions
Splash Screen Functions
Storage Functions

© 2014 Adobe Systems Incorporated. All rights reserved.

2967

Adobe ColdFusion Documentation

Accelerometer Functions
The Accelerometer API allows you to capture the device motion in the X, Y, and Z direction. The ColdFusion
Accelerometer API dispatches certain events based on the activity detected by the device’s motion sensor
(accelerometer). The data returned by the API represents the device’s location or movement along a 3-dimensional
axis. When the device moves, the sensor detects this movement and returns acceleration data.
cfclient.accelerometer.clearWatch
cfclient.accelerometer.getOptions
cfclient.accelerometer.setOptions
cfclient.accelerometer.watch

© 2014 Adobe Systems Incorporated. All rights reserved.

2968

Adobe ColdFusion Documentation

cfclient.accelerometer.clearWatch
Stop watching position changes

You can stop watching the device position using the clearWacth() function.
Method summary

clearWatch(watchID)
returns – None
params
watchID – String
For instance,



Example

See Using the Accelerometer APIs

© 2014 Adobe Systems Incorporated. All rights reserved.

2969

Adobe ColdFusion Documentation

cfclient.accelerometer.getOptions
Getting Accelerometer options

You can get the Accelerometer options using the getOptions() function
Method summary

getOptions()
returns – Options object
params
None
For instance,



The Options object

The Options object contains the following parameter:
frequency – The time delay for invoking the callback function to obtain the Accelerometer data (in
milliseconds)
Example

See Using the Accelerometer APIs

© 2014 Adobe Systems Incorporated. All rights reserved.

2970

Adobe ColdFusion Documentation

cfclient.accelerometer.setOptions
Setting Accelerometer options

You can also set the Accelerometer options using the setOptions() function.
Method summary

setOptions(options)
returns – None
params
Options object
For instance,




The Options object
The Options object contains the following parameter:
frequency – The time delay for invoking the callback function to obtain the Accelerometer data (in
milliseconds)
Example

See Using the Accelerometer APIs

© 2014 Adobe Systems Incorporated. All rights reserved.

2971

Adobe ColdFusion Documentation

cfclient.accelerometer.watch
Watching for change in position
You can get the acceleration data (X, Y, and Z) at regular intervals by watching for the change in device position.
Method summary

watch(callback, [options])

returns – watchID - String
params
callback – Function that will be called whenever there is a change in location
Options object (Optional)
For instance,



The returned watch ID references the accelerometer's watch interval, and can be used with
accelerometer.clearWatch to stop watching the accelerometer.








The callback function passed to the watch function will be invoked based on the frequency provided in the options
object. The callback function will receive an argument 'acceleration' with the following properties:
x - Amount of acceleration on the x-axis
y - Amount of acceleration on the x-axis
z - Amount of acceleration on the z-axis
timestamp - The creation timestamp in milliseconds
The 'acceleration' object has the accelerometer data captured at a specific time.

The Options object
The Options object contains the following parameter:
frequency – The time delay for invoking the callback function to obtain the Accelerometer data (in
milliseconds)
Example

© 2014 Adobe Systems Incorporated. All rights reserved.

2972

Adobe ColdFusion Documentation

See Using the Accelerometer APIs

© 2014 Adobe Systems Incorporated. All rights reserved.

2973

Adobe ColdFusion Documentation

Camera Functions
ColdFusion allows you to access the camera of the mobile device through simple CFML code.
The following sections describe how you can invoke the camera using .
cfclient.camera.cleanup
cfclient.camera.getOptions
cfclient.camera.getPicture
cfclient.camera.getPictureFromAlbum
cfclient.camera.getPictureFromPhotoLibrary
cfclient.camera.setOptions
options Object
The image quality of pictures taken using the camera on newer devices is quite good, and
images from the Photo Album will not be downscaled to a lower quality, even if a quality
parameter is specified. Encoding such images using Base64 can cause memory issues on many
newer devices. Therefore, using FILE_URI for images captured is highly recommended.

© 2014 Adobe Systems Incorporated. All rights reserved.

2974

Adobe ColdFusion Documentation

cfclient.camera.cleanup
Removing intermediate photos

You can remove the intermediate photos taken by the camera from the temporary storage.



Note: This function is supported only on iOS devices.
Method summary
cleanup
returns – None
params
None
Example

See Using the Camera APIs

© 2014 Adobe Systems Incorporated. All rights reserved.

2975

Adobe ColdFusion Documentation

cfclient.camera.getOptions
Getting the camera options

You can get the camera options to customize the camera settings using the getOptions() function as shown below:



Method summary
getOptions
returns – Returns the Options object
params
None
Example

See Using the Camera APIs

© 2014 Adobe Systems Incorporated. All rights reserved.

2976

Adobe ColdFusion Documentation

cfclient.camera.getPicture
The image quality of pictures taken using the camera on newer devices is quite good, and
images from the Photo Album will not be downscaled to a lower quality, even if a quality
parameter is specified. Encoding such images using Base64 can cause memory issues on many
newer devices. Therefore, using FILE_URI for images captured is highly recommended.

Getting the image from the camera

By invoking the default camera application on the device, this function takes a photo using the camera as the
source.
The following example shows how you can get an image from the camera using the getPicture function:



The following example depicts the usage:










Get a picture




In the above example, on the click of a button, the default camera application is opened and after capturing an
image, the image is rendered in the  tag.
Note: If you pass true as a param indicating that the returned object should be a Base-64 encoded string, its content

© 2014 Adobe Systems Incorporated. All rights reserved.

2977

Adobe ColdFusion Documentation

has to be prefixed with “data:image/jpeg;base64,” before rendering it.
Method summary

getPicture(Options, base64)
returns – Returns the image file URI or a Base-64 encoded string
params
Options – Object
base64 – A Boolean flag to indicate that the returned object should be a base-64 encoded string.
Format for the Options object

The following table has the list of the properties for the Options object (ColdFusion sets defaults for these
properties):
Property

Type

allowEdit

Boolean

encodingType

JPEG or PNG

popoverOptions

Object

savePhotoToAlbum

boolean

Quality

Number (0-100)

For all supported properties, check this document.
Example

See Using the Camera APIs

© 2014 Adobe Systems Incorporated. All rights reserved.

2978

Adobe ColdFusion Documentation

cfclient.camera.getPictureFromAlbum
Getting the image from the album

Using the getPictureFromAlbum function, you can get the image stored in the album.
Method summary

getPictureFromAlbum(Options, [base64])
returns – Returns the file URI or a base-64 encoded string
params
Options – Object
base64 – A Boolean flag to indicate that the returned object should be a base-64 encoded string. The
default value is false. When it is false, it will return the file URI.
Note: If you pass true as a parameter indicating that the returned object should be a Base-64 encoded string, its
content has to be prefixed with “data:image/jpeg;base64,” before rendering it.

The following example shows how you can get an image from the local file system using the getPictureFromAlbum
function:










Get a picture




Example

See Using the Camera APIs

© 2014 Adobe Systems Incorporated. All rights reserved.

2979

Adobe ColdFusion Documentation

cfclient.camera.getPictureFromPhotoLibrary
Getting the image from the photo library

Using the getPictureFromPhotoLibrary function, you can get the image stored in the photo library.
Method summary

getPictureFromPhotoLibrary(Options, base64)
returns – Returns the file URI or a base-64 encoded string
params
Options – Object
base64 – A Boolean flag to indicate that the returned object should be a base-64 encoded string.
Note: If you pass true as a param indicating that the returned object should be a Base-64 encoded string, its content
has to be prefixed with “data:image/jpeg;base64,” before rendering it.

The following example shows how you can get an image from the local file system using the
getPictureFromPhotoLibrary function:










Get a picture




Example

See Using the Camera APIs

© 2014 Adobe Systems Incorporated. All rights reserved.

2980

Adobe ColdFusion Documentation

© 2014 Adobe Systems Incorporated. All rights reserved.

2981

Adobe ColdFusion Documentation

cfclient.camera.setOptions
Setting the camera options

You can set the options to customize the camera settings using the setOptions() function as shown below:




Method summary
setOptions(options)
returns – None
params
Options object
Example

See Using the Camera APIs

© 2014 Adobe Systems Incorporated. All rights reserved.

2982

Adobe ColdFusion Documentation

options Object
Format for the Options object

The following table has the list of properties for which ColdFusion sets defaults:
Property

Type

encodingType

JPEG or PNG

quality

Number (0-100)

height

Number

width

Number

For a complete list of supported properties, see this document.

© 2014 Adobe Systems Incorporated. All rights reserved.

2983

Adobe ColdFusion Documentation

Connection Functions
The connection API allows you to detect the type of phone connection. Using these APIs, you can find out the
connection type (2G, 3G, or 4G) and register for events when the phone goes online or offline.
cfclient.connection.getType
cfclient.connection.onOffline
cfclient.connection.onOnline

© 2014 Adobe Systems Incorporated. All rights reserved.

2984

Adobe ColdFusion Documentation

cfclient.connection.getType
Getting the type of connection

You can get the connection type of the device using the getType() function.
Method summary

getType()
returns – Number
params
None
For instance,



The connection types returned by these functions will be one of the following constants:
cfclient.connection.UNKNOWN
cfclient.connection.ETHERNET
cfclient.connection.WIFI
cfclient.connection.CELL_2G
cfclient.connection.CELL_3G
cfclient.connection.CELL_4G
cfclient.connection.NONE

© 2014 Adobe Systems Incorporated. All rights reserved.

2985

Adobe ColdFusion Documentation

cfclient.connection.onOffline
Getting notification when the device goes offline

You can register a callback function to be invoked when the device goes offline using the onOffline() function.
Method summary

onOffline(callBackFunction)
returns – None
params
Name of the callback function that gets invoked when the device goes offline.
For instance,






Method summary
directoryExists (path)
Params
path An absolute or relative path of the directory (including directory name).
Returns – a Boolean value indicating the existence of the specified directory

© 2014 Adobe Systems Incorporated. All rights reserved.

3009

Adobe ColdFusion Documentation

cfclient.file.download
Download a file

You can download a file from a remote server..
Method summary

cfclient.file.download(url,localFilePath,successCallback, errorCallback,[options])
returns - FileEntry object
params
url - The remote server URL (CFM page)
localFilePath – Absolute or relative path of a file name (including file name)
successCallback - The function to be invoked upon success/completion
errorCallback - The function to be invoked if there is a file transfer error
options object (see below for the supported options)
Options object

Optional parameters, currently only supports headers (such as Authorization (Basic Authentication), etc).
Example

See Getting Started Examples

© 2014 Adobe Systems Incorporated. All rights reserved.

3010

Adobe ColdFusion Documentation

cfclient.file.exists
Checking if the file exists

You can determine if the specified file exists by using the exists function as shown in the following example:



Method summary
exists(filePath) - check if file exists at specified location
returns - true/false
params - filePath Absolute or relative path of the file to be checked (including file name).

© 2014 Adobe Systems Incorporated. All rights reserved.

3011

Adobe ColdFusion Documentation

cfclient.file.get
Looking up the file

You can look up for the file using the get function as shown in the following example:



Method summary
get(filePath) – Lookup for the file in the given path
returns – A FileEntry object
params
-

filePath – An absolute or relative path of the file (including the file name).

© 2014 Adobe Systems Incorporated. All rights reserved.

3012

Adobe ColdFusion Documentation

cfclient.file.getDirectory
Looking up the directory

You can look up for the directory using the getDirectory function as shown in the following example:



Method summary

getDirectory(dirPath) – Lookup for the directory in the given path
returns – A DirectoryEntry object
params
-

dirPath – An absolute or relative path of the directory (including directory name).

© 2014 Adobe Systems Incorporated. All rights reserved.

3013

Adobe ColdFusion Documentation

cfclient.file.getWorkingDirectory
Getting the current directory

You can get the current working directory by using the getWorkingDirectory() function.
Method summary

getWorkingDirectory() – Lookup for the current working directory
returns – A String containing the path to the current working directory
params
-

None.

For instance,



© 2014 Adobe Systems Incorporated. All rights reserved.

3014

Adobe ColdFusion Documentation

cfclient.file.listDirectory
Listing a directory

You can list the content of a directory using the listDirectory function.



Method summary
listDirectory(dirPath) - lists contents of directory specified by dirPath
returns – An array of FileEntry and DirectoryEntry objects
params
dirPath – Absolute or relative path of the directory to be listed (including the directory name).
sortType - A string representing the type of directory sorting. For instance ("name ASC/DESC",
"datemodified ASC/DESC")

© 2014 Adobe Systems Incorporated. All rights reserved.

3015

Adobe ColdFusion Documentation

cfclient.file.move
Moving a file

You can move a file from one location to another location on the device by using the move function as shown in the
following example:



Method summary
move(source, destination) – moves a file from source to destination
returns - FileEntry object
params
-

source – Absolute or relative path of the source filename (including the file name)

-

destination – Absolute or relative path of the destination filename (including the file name)

© 2014 Adobe Systems Incorporated. All rights reserved.

3016

Adobe ColdFusion Documentation

cfclient.file.moveDirectory
Moving a directory

You can move a directory by using the moveDirectory function as shown in the following example:



Method summary
moveDirectory(source, destination) - move a directory from source to destination
returns - DirectoryEntry object
params
source – Source directory name (absolute or relative path)
destination – Absolute or relative path of the destination location (excluding the directory name)
For instance,



© 2014 Adobe Systems Incorporated. All rights reserved.

3017

Adobe ColdFusion Documentation

cfclient.file.read
Reading a file

You can read a text file with the read function. The following example shows a simple usage:



Method summary

read(filename) - Reads the content of a given file
returns – Content of file in the form of a string
params
filename - Absolute or relative path of the file (including file name)

© 2014 Adobe Systems Incorporated. All rights reserved.

3018

Adobe ColdFusion Documentation

cfclient.file.readAsBase64
Reading a file as a Base64 string

You can read a text file with the read function. The following example shows a simple usage:





Method summary

readAsBase64(filename) - Reads the content of a given file
returns – Content of file in the form of a base64 encoded string
params
filename - Absolute or relative path of the file (including file name)

© 2014 Adobe Systems Incorporated. All rights reserved.

3019

Adobe ColdFusion Documentation

cfclient.file.remove
Deleting a file

You can delete a specified file on the device as shown by the following example:



Method summary

remove(fileName) - deletes file specified by filename
returns - true for successful removal
params
filename – Absolute or relative path of the file to be deleted (including the file name)

© 2014 Adobe Systems Incorporated. All rights reserved.

3020

Adobe ColdFusion Documentation

cfclient.file.removeDirectory
Deleting a directory

You can delete a directory by using the removeDirectory function as shown in the following example:



Method summary
removeDirectory(dirPath,recurse) - Delete specified directory
returns – a boolean to indicate the success of operation
params
dirPath – The absolute or relative path to the directory that needs to be deleted (including the directory
name).
recurse - boolean to indicate whether the directory should be removed recursively.

© 2014 Adobe Systems Incorporated. All rights reserved.

3021

Adobe ColdFusion Documentation

cfclient.file.renameDirectory
Renaming a directory

You can rename a directory using the renameDirectory function as shown in the following example:



Method summary
renameDirectory(oldName,newName) - renames the directory with newName
returns – A DirectoryEntry object
params
oldName – The name of directory with absolute or relative path to be renamed
newName – The new name for the directory with absolute path
For instance,



© 2014 Adobe Systems Incorporated. All rights reserved.

3022

Adobe ColdFusion Documentation

cfclient.file.setFileSystem
Setting the file system

You can set the underlying filesystem for a persistent or temporary storage depending upon how long you want to
store the files.
To set the device file system, use the setFileSystem() function.

Method summary
setFileSystem(fileSystem)
returns – None
params - String (PERSISTENT/TEMPORARY)
PERSISTENT – Permanent storage. Used for storage that should not be removed by the user agent without
application or user permission.
-

TEMPORARY – Temporary storage. Used for storage with no guarantee of persistence

Example








© 2014 Adobe Systems Incorporated. All rights reserved.

3023

Adobe ColdFusion Documentation

cfclient.file.setWorkingDirectory
Setting the current directory

You can set the current working directory by using the setWorkingDirectory() function.
Method summary

setWorkingDirectory() – Set the current working directory
returns – None
params
-

dirPath – Absolute or relative path of the directory

For instance,



© 2014 Adobe Systems Incorporated. All rights reserved.

3024

Adobe ColdFusion Documentation

cfclient.file.upload
Upload a file

You can upload a file to a remote server using an HTTP multi-part POST request.
Method summary

cfclient.file.upload(fileName,url,successCallback, errorCallback,[options])
returns - None
params
fileName – Absolute or relative path of a file name (including file name)
url - The remote server URL
successCallback - The function to be invoked upon success/completion
errorCallback - The function to be invoked if there is a file transfer error
options - See this document for more information
Options object

Apart from the options mentioned in this document, the following options are also supported:
-trustAllHosts - Defaults to false. If set to true, it accepts all the security certificates. This is useful because Android
rejects self-signed certificates. It is not recommended to set this as true for production use.

Example
See Getting Started Examples

//A function to capture and uplaod an image to a remote server
function uploadImageToServer(imageURI)
{
var uploadOptions = new FileUploadOptions();
uploadOptions.fileKey="uploadedImageFile";
uploadOptions.fileName=imageURI.substr(imageURI.lastIndexOf('/')+1);
uploadOptions.mimeType="image/jpeg";
uploadOptions.chunkedMode = false;
var fileTransferObj = new FileTransfer();
fileTransferObj.upload(imageURI,
"http://:8500/ImageReceiver/receiveImage.cfm",
function(){
alert("File uploaded to the server");
},
function (e){
alert("Error uploading file to the server");
}, uploadOptions);
}

© 2014 Adobe Systems Incorporated. All rights reserved.

3025

Adobe ColdFusion Documentation

cfclient.file.write
Writing to a file

You can write text to a file using the write function. This function creates a file if a given file name does not exist.
See the following example:



Method summary

write(name, data) - write data to a given file
returns - None
params
name – Absolute or relative path of the file name (including file name)
data - data to be written to the file

© 2014 Adobe Systems Incorporated. All rights reserved.

3026

Adobe ColdFusion Documentation

DirectoryEntry Object
The DirectoryEntry object represents a directory on a file system of the mobile device.
The properties of DirectoryEntry object are :
isFile: Always false (boolean).
isDirectory: Always true (boolean).
name: The name of the directory, excluding the path leading to it.
fullPath: The full absolute path from the root to the directory.

© 2014 Adobe Systems Incorporated. All rights reserved.

3027

Adobe ColdFusion Documentation

FileEntry Object
FileEntry object represents a file on a file system of the mobile device.
The properties of FileEntry object are:
isFile: Always true (boolean).
isDirectory: Always false (boolean).
name: The name of the file, excluding the path leading to it.
fullPath: The full absolute path from the root to the file.

© 2014 Adobe Systems Incorporated. All rights reserved.

3028

Adobe ColdFusion Documentation

rename Function
Renaming a file

You can rename a file using the rename function as shown in the following example:



Method summary
rename(oldName,newName) - renames the file with newName
returns – A FileEntry object
params
oldName – The name of file (absolute/relative path) to be renamed
newName – The new name for the file with absolute/relative path

© 2014 Adobe Systems Incorporated. All rights reserved.

3029

Adobe ColdFusion Documentation

Geolocation Functions
The Geolocation APIs allow your mobile application to connect and get details from the location sensor.
cfclient.geolocation.clearWatch
cfclient.geolocation.getCurrentPosition
cfclient.geolocation.getOptions
cfclient.geolocation.setOptions
cfclient.geolocation.watchPosition

© 2014 Adobe Systems Incorporated. All rights reserved.

3030

Adobe ColdFusion Documentation

cfclient.geolocation.clearWatch
Stop watching location changes

You can stop watching for location changes using the clearWatch() function.
Method summary

clearWatch(watchid)
returns – None
params
watchID (String)
For instance,



Example

See Using the Geolocation APIs

© 2014 Adobe Systems Incorporated. All rights reserved.

3031

Adobe ColdFusion Documentation

cfclient.geolocation.getCurrentPosition
Getting current position

You can get the device’s current position using the getCurrentPosition() function.
Method summary

getCurrentPostion(options)
returns – Returns a Position object containing the location information
params
Geolocation Options
For instance,



Example
See Using the Geolocation APIs

© 2014 Adobe Systems Incorporated. All rights reserved.

3032

Adobe ColdFusion Documentation

cfclient.geolocation.getOptions
Getting Geolocation options

You can get the current Geolocation options using the getOptions() function.
Method summary

getOptions()
returns – An object representing the Options object
params
None
For instance,


opt=cfclient.geolocation.getOptions();
/*Populating the content of the 
 with
document.getElementById('divId').innerHTML="
"+opt.enableHighAccuracy);
document.getElementById('divId').innerHTML="
document.getElementById('divId').innerHTML="

the ID divId*/
Enable high accuracy:
Maximum age: "+opt.maximumAge);
Maximum age: "+opt.maximumAge);



Geolocation Options structure
The Geolocation Options object contains the following parameters:
enableHighAccuracy (Boolean) - By default, the device attempts to retrieve a position using the
network-based methods. Setting this property to true enables ColdFusion to use more accurate methods,
such as satellite positioning.
timeOut (Number) – The maximum time length (milliseconds) that is allowed to pass from the call
to getCurrentPosition or watchPosition until the corresponding geolocationSuccess callback gets executed.
maximumAge (Number) - Accept a cached position whose age is no greater than the specified time in
milliseconds.
Example

See Using the Geolocation APIs

© 2014 Adobe Systems Incorporated. All rights reserved.

3033

Adobe ColdFusion Documentation

cfclient.geolocation.setOptions
Setting Geolocation options

You can set the Geolocation options using the setOptions() function.
Method summary

setOptions(options)
returns – None
params
An object representing the Geolocations options
For instance,


opt. maximumAge=2000>
opt. timeOut=4000>
cfclient.geolocation.setOptions(opt)>

Geolocation Options structure
The Geolocation Options object contains the following parameters:
enableHighAccuracy(Boolean) - By default, the device attempts to retrieve a position using the
network-based methods. Setting this property to true enables ColdFusion to use more accurate methods,
such as satellite positioning.
timeOut (Number) – The maximum time length (milliseconds) that is allowed to pass from the call to getCurr
entPosition or watchPosition until the corresponding geolocationSuccess callback gets executed.
maximumAge (Number) - Accept a cached position whose age is no greater than the specified time in
milliseconds.
Example

See Using the Geolocation APIs

© 2014 Adobe Systems Incorporated. All rights reserved.

3034

Adobe ColdFusion Documentation

cfclient.geolocation.watchPosition
Watching for change in location

Using the watchPosition function, you can constantly watch and get notification whenever the location of the device
changes.
Method summary

watchPosition(callback, options)
returns – watchID (String)
params
callback (function), options (object)
For instance,



opt=cfclient.geolocation.getOptions();
watchId=cfclient.geolocation.
watchPosition(wtchposcallback,opt);
/*Populating the content of the 
 with the ID divId*/
document.getElementById('divId').innerHTML="Watch Id: "+watchId;





alert("Longitude "+position.coords.longitude+" Latitude
:"+position.coords.latitude);



Note: We have used alert() in the above example. alert() may not work on iOS devices.
Example

See Using the Geolocation APIs

© 2014 Adobe Systems Incorporated. All rights reserved.

3035

Adobe ColdFusion Documentation

Media and Capture Functions
ColdFusion enables you to build mobile applications capable of capturing audio and video. APIs are made available
for playback and control of audio files.
Audio Functions
Video Functions

© 2014 Adobe Systems Incorporated. All rights reserved.

3036

Adobe ColdFusion Documentation

Audio Functions
Supported audio Functions

http://docs.phonegap.com/en/2.5.0/cordova_media_capture_capture.md.html#CaptureAudioOptions
API

capture([opti
ons],
[callback])

createMedia(s
rc,
[statusCallba
ck])

Description

Returns

Parameters

Record audio based
on provided options

Array of MediaFile o
bject or null based
on whether callback
function is provided
or not

options (Audio
Options, callBack)

Media Object

src fullpath of media
file

Create media object
for playback

The audio options
are listed here.

statusCallback
function to get
Media Playback
status events
Get current position
for given media
object

position (Number)

Media Object

getCurrentPos
ition(media)

Start or resume
given audio file

Media object

play(src)

fullpath or Media
Object

Pause given audio
file

void

Media Object

pause(media)

Release underlying
audio resources

void

Media Object

Set current position
within audio file

void

Media Object

release(media
)

seekTo(media,
duration)

stop(media)

© 2014 Adobe Systems Incorporated. All rights reserved.

duration in
milliseconds
Stop playing given
audio file

void

Media Object

3037

Adobe ColdFusion Documentation

Record to file

void

Media Object

Stop recording to
given audio file

void

Media Object

record(media)

stopRecording
(media)

Recording audio














Note: The duration parameter of audio options is not supported on Android. The Mode parameter is not supported
on both platforms.
Playing audio




cfclient.audio.pause(media) >
cfclient.audio.stop(media) >
cfclient.audio.release(media) >

More examples

See Using the Audio capture APIs.

© 2014 Adobe Systems Incorporated. All rights reserved.

3038

Adobe ColdFusion Documentation

© 2014 Adobe Systems Incorporated. All rights reserved.

3039

Adobe ColdFusion Documentation

Video Functions
Supported video APIs

API name

capture([opti
ons],
[callback])

Description

Return Type

Parameters

Record video based
on provided options

Array of MediaFile o
bject or null based
on whether callback
function is provided
or not

options (Video
Options, callBack)
The video options
are listed here.

For capturing video,




Example

Using the Video capture APIs

© 2014 Adobe Systems Incorporated. All rights reserved.

3040

Adobe ColdFusion Documentation

Notification Functions
Visual, audible and tactile device notification support
cfclient.notification.alert
cfclient.notification.beep
cfclient.notification.confirm
cfclient.notification.vibrate

© 2014 Adobe Systems Incorporated. All rights reserved.

3041

Adobe ColdFusion Documentation

cfclient.notification.alert
Displaying alert messages

Show an alert dialog
Method summary

alert (message, title, buttonLabels)
returns – None
params
message (String)
title (String)
buttonLabels (String)
For instance,



© 2014 Adobe Systems Incorporated. All rights reserved.

3042

Adobe ColdFusion Documentation

cfclient.notification.beep
Creating a beep sound

beep
Method summary

beep (count)
returns – None
params
count - Number of times to repeat the beep sound.
For instance,



© 2014 Adobe Systems Incorporated. All rights reserved.

3043

Adobe ColdFusion Documentation

cfclient.notification.confirm
Showing a confirm alert dialog

Shows a confirm alert dialog
Method summary

confirm (message, title, buttonLabels)
returns – None
params
message (String) – The message on the dialog
title (String) – The title of the dialog
buttonLabels (String) - Comma-separated string specifying button labels. (String) (Optional, defaults to
OK,Cancel)
For instance,



© 2014 Adobe Systems Incorporated. All rights reserved.

3044

Adobe ColdFusion Documentation

cfclient.notification.vibrate
Showing a vibrate alert dialog

Provides a vibration alert
Method summary

vibrate (milliseconds)
returns – None
params
milliseconds - The number of milliseconds to vibrate the device.
For instance,



© 2014 Adobe Systems Incorporated. All rights reserved.

3045

Adobe ColdFusion Documentation

Splash Screen Functions
You can show or hide a splash screen image that you have configured as part of your PhoneGap build using the
show() and hide() functions.
cfclient.splashscreen.hide
cfclient.splashscreen.show

© 2014 Adobe Systems Incorporated. All rights reserved.

3046

Adobe ColdFusion Documentation

cfclient.splashscreen.hide
To hide a splash screen on your device, use this function:



© 2014 Adobe Systems Incorporated. All rights reserved.

3047

Adobe ColdFusion Documentation

cfclient.splashscreen.show
To show a splash screen in your application, use:



The show() function requires the duration in milliseconds.

© 2014 Adobe Systems Incorporated. All rights reserved.

3048

Adobe ColdFusion Documentation

Storage Functions
ColdFusion supports PhoneGap storage APIs that are based on the Web storage specification. Web storage is an
important aspect of any client application running on a browser or a device.
This section describes how you can access and manage web storage through ColdFusion.
Support for local storage is provided through key-value pairs.
cfclient.localstorage.clear
cfclient.localstorage.getItem
cfclient.localstorage.removeItem
cfclient.localstorage.setItem

© 2014 Adobe Systems Incorporated. All rights reserved.

3049

Adobe ColdFusion Documentation

cfclient.localstorage.clear
Clearing the storage

Remove all the items from the local storage.
Method summary

clear()
returns – None
params
None
Usage



Example

See Using the Storage APIs

© 2014 Adobe Systems Incorporated. All rights reserved.

3050

Adobe ColdFusion Documentation

cfclient.localstorage.getItem
Getting an item from storage

Get an item from the local storage identified by a key.
Method summary

getItem(key)
returns – An item (String)
params
Key (String)
Usage



Example

See Using the Storage APIs

© 2014 Adobe Systems Incorporated. All rights reserved.

3051

Adobe ColdFusion Documentation

cfclient.localstorage.removeItem
Removing an item from storage

Remove an item from the local storage identified by a key.
Method summary

removeItem(key,value)
returns – None
params
Key (String)
Usage



Example
See Using the Storage APIs

© 2014 Adobe Systems Incorporated. All rights reserved.

3052

Adobe ColdFusion Documentation

cfclient.localstorage.setItem
Persisting an item in storage

Set an item in the local storage identified by a key.
Method summary

setItem(key,value)
returns – None
params
Key (String), Value (String)
Usage



Example
See Using the Storage APIs

© 2014 Adobe Systems Incorporated. All rights reserved.

3053



---

Source Exif Data:

File Type                       : PDF
File Type Extension             : pdf
MIME Type                       : application/pdf
PDF Version                     : 1.4
Linearized                      : Yes
Create Date                     : 2014:09:02 23:41:53-07:00
Modify Date                     : 2015:09:10 14:49:51+02:00
XMP Toolkit                     : Adobe XMP Core 4.2.1-c043 52.372728, 2009/01/18-15:56:37
Metadata Date                   : 2015:09:10 14:49:51+02:00
Producer                        : iText 2.0.8 (by lowagie.com)
Format                          : application/pdf
Document ID                     : uuid:95a1936d-1a60-fe42-91aa-ddf65ea835ed
Instance ID                     : uuid:e6a4ab68-8200-0542-9f9f-83b480dbcdbd
Page Mode                       : UseOutlines
Page Count                      : 3053

EXIF Metadata provided by EXIF.tools