MACROMEDIA COLDFUSION MX 61-CFML Reference

Page 1

Cfml reference.

Page 3: Contents

3 contents introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 about macromedia coldfusion mx documentation . . . . . . . . . . . . . . . . . . . . . . 17 documentation set . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ....

Page 5

Contents 5 cfexecute . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106 cfexit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108 cffile . . . . . . . . . . . . . . . ....

Page 7

Contents 7 cftreeitem . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 349 cftry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 353 cfupdate . . . . . . . . . . . . . . . ....

Page 9

Contents 9 decrypt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 462 deleteclientvariable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 463 directoryexists . . . . . . . . . . . . . . . . ...

Page 11

Contents 11 listvaluecount . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 590 listvaluecountnocase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 592 ljustify . . . . . . . . . . . . . . . . . . . . . . . ....

Page 13

Contents 13 xmlformat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 741 xmlnew . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 742 xmlparse . . . . . . . . . . . . . . . . . . . ...

Page 15

Contents 15 setfield . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 796 wddxserialize . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 797 chapter 7: coldfusion actionscript functions . . . ...

Page 17: Introduction

17 introduction cfml reference is your primary coldfusion markup language (cfml) reference. Use this book to learn about cfml tags and functions, coldfusion expressions, and using javascript objects for wddx in macromedia coldfusion mx. It also provides detailed references for java and c++ cfx inter...

Page 19: Chapter 1

19 chapter 1 reserved words and variables this chapter provides information on coldfusion reserved words and lists scope variables. Contents reserved words . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20 scope-specific built-...

Page 21

Reserved words 21 column commit connect connection constraint constraints continue convert correspon ding count create cross current current_date current_time current_time stamp current_user cursor date day deallocate dec decimal declare default deferrable deferred delete desc describe descriptor di...

Page 23

Scope-specific built-in variables 23 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...

Page 25

Coldfusion tag-specific variables 25 cfhttp cfindex cfldap cfmail cfpop cfquery cfregistry cfsearch cfstoredproc coldfusion query variables a coldfusion tag that returns a query object supports the following variables, where queryname is the value of the name attribute: queryname.Currentrow querynam...

Page 27

Coldfusion tag-specific variables 27 cfftp.Errorcode cfftp.Errortext 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 ac...

Page 29

Cgi environment variables 29 standard cgi variables this section lists the cgi 1.1 variables that some web servers create when a cgi script is called. The cgi variables that are available for your use vary with the web server and configuration. Some of the following variables may not be available. R...

Page 31

Cgi environment variables 31 cgi client variables the following table describes common cgi environment variables the browser creates and passes in the request header: cgi client certificate variables coldfusion makes available the following client certificate data. These variables are available when...

Page 33: Chapter 2

33 chapter 2 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. This chapter contains categorized and alphabetical lists of th...

Page 35

Tag summary 35 cferror exception handling tags , application framework tags displays custom html error pages when errors occur cfexecute flow-control tags , extensibility tags executes developer-specified process on server computer cfexit flow-control tags aborts processing of executing cfml tag cff...

Page 37

Tag summary 37 cfquery database manipulation tags passes sql statements to a database cfqueryparam database manipulation tags checks data type of a query parameter cfregistry other tags , variable manipulation tags reads, writes, and deletes keys and values in a windows system registry cfreport exce...

Page 39

Tags by function 39 tags by function the following tables list tags by their function or purpose. Application framework tags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39 database manipulation tags . . . . . . . . . . . . . . . . . . . . . ....

Page 41

Tags by function 41 internet protocol tags page processing tags variable manipulation tags other tags cfftp cfldap cfmailpart cfhttp cfmail cfpop cfhttpparam cfmailparam cfcache cfheader cfsetting cfcontent cfhtmlhead cfsilent cfflush cfinclude cfcookie cfregistry cfset cfdump cfsavecontent cfsettin...

Page 43

Tag changes since coldfusion 5 43 cfimport all coldfusion mx cfinvoke all coldfusion mx cfinvokeargument all coldfusion mx cflogin all coldfusion mx cfloginuser all coldfusion mx cflogout all coldfusion mx cfmail spoolenable attribute coldfusion mx charset attribute coldfusion mx 6.1 failto attribut...

Page 45

Tag changes since coldfusion 5 45 cfquery connectstring attribute coldfusion mx dbname attribute coldfusion mx dbserver attribute coldfusion mx the following dbtype attribute values: • dynamic • odbc • oracle73 • oracle80 • sybase11 • oledb • db2 coldfusion mx (the value query is valid.) provider at...

Page 47

Cfabort 47 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 showerror =...

Page 49

Cfapplet 49 cfapplet description this tag references a registered custom java applet. To register a java applet, in the coldfusion administrator, click 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 ...

Page 51

Cfapplication 51 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 timeouts. Category application framework tags syntax n...

Page 53

Cfapplication 53 if you use this tag to activate the application and client scopes, coldfusion saves the application name as a key, whose maximum length is 64 characters. If an application name is longer than this, the client store fails during database processing. Note: the cftoken variable is 8 by...

Page 55

Cfargument 55 usage 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 myargum...

Page 57

Cfauthenticate 57 cfauthenticate description this tag is obsolete. Use the newer security tools; see “authentication functions” on page 367 and chapter 16, “securing applications,” in developing coldfusion mx applications. History coldfusion mx: this tag is obsolete. It does not work in coldfusion m...

Page 59

Cfcache 59 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 eac...

Page 61

Cfcache 61 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 ad...

Page 63

Cfcase 63 your grade is #grade#.

Page 65

Cfcatch 65 attributes usage you must code at least one cfcatch tag within a cftry block. Put cfcatch tags at the end of a cftry block. Coldfusion mx tests cfcatch tags in the order in which they appear. This tag requires an end tag. If type="any" , coldfusion mx catches exceptions from any cfml tag,...

Page 67

Cfcatch 67 advanced exception types you can specify the following advanced exception types in the type attribute: coldfusion advanced exception type com.Allaire.Coldfusion.Cfexecute.Outputerror com.Allaire.Coldfusion.Cfexecute.Timeout com.Allaire.Coldfusion.Fileexception com.Allaire.Coldfusion.Httpa...

Page 69

Cfcatch 69 the contents of the tag stack are: to = #arraylen(cfcatch.Tagcontext)#> #i# #scurrent["id"]# (#scurrent["line"]#,#scurrent["column"]#) #scurrent["template"]# to = #arraylen(cfcatch.Tagcontext)#> #i# #scurrent["id"]# (#scurrent["line"]#,#scurrent["column"]#) #scurrent["template"]#.

Page 71

Cfchart 71 attributes attribute req/opt default description format flash file format in which to save graph. • flash • jpg • png chartheight 240 chart height; integer number of pixels chartwidth 320 chart width; integer number of pixels scalefrom determined by data y-axis minimum value; integer. Sca...

Page 73

Cfchart 73 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 style in which data displays: bar, line, pie, and so on. The cfchartdata tag defines a data point. Tipstyle mouseover determines t...

Page 75

Cfchartdata 75 cfchartdata description used with the cfchart and cfchartseries tags. This tag defines chart data points. Its data is submitted to the cfchartseries tag. Category data output tags , extensibility tags syntax item = "text" value = "number"> see also cfchart , cfchartseries history cold...

Page 77

Cfchartseries 77 usage if a chart has multiple line series, coldfusion interpolates missing data points in the common x axis range. For example, if one series has data points at 0, 10, and 20 on the x axis and a second series has data points at 0, 20, and 30, coldfusion calculates and displays a dat...

Page 79

Cfcol 79 from employees query = "getemployees" startrow = "1" colspacing = "3" htmltable colheaders> align = "left" width = 2 text = "#emp_id#"> align = "left" width = 15 text = "#firstname# #lastname#"> align = "center" width = 15 text = "#phone#"> query = "getemployees" startrow = "1" colspacing =...

Page 81

Cfcollection 81 attributes usage with this tag you can create, register a verity collection and administer a collection that was created by coldfusion or by a verity application. The following table shows the dependence relationships among this tag’s attribute values: if more than instance of the cf...

Page 83

Cfcollection 83 with the european verity locales language pack installed, the language attribute of this tag supports the following options: with the asian verity locales language pack installed, the language attribute of this tag supports the following options: the default location of verity collec...

Page 85

Cfcomponent 85 cfcomponent description creates and defines a component object; encloses functionality that you build in cfml and enclose within 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 execute...

Page 87

Cfcontent 87 cfcontent description does either or both of the following: • sets the mime content encoding header for the current page • sends the contents of a file from the server as the page output note: this tag executes only if it is enabled in the coldfusion administrator. For more information,...

Page 89

Cfcontent 89 usage to set the character encoding (character set) of generated output, use code such as the following: when coldfusion processes an http request, it determines the character encoding of the data returned in the http response. By default, coldfusion returns character data using the uni...

Page 91

Cfcookie 91 cfcookie description defines web browser cookie variables, including expiration and security options. Category forms tags , variable manipulation tags syntax name = "cookie_name" value = "text" expires = "period" secure = "yes" or "no" path = "url" domain = ".Domain"> see also cfdump , c...

Page 93

Cfcookie 93 value = "#now()#" expires = "now"> value = "#email#" expires = "now" > value = "#now()#" expires = "10"> 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. Value = "#now()#" e...

Page 95

Cfdirectory 95 cfdirectory description manages interactions with directories. Category file management tags syntax action = "directory action" directory = "directory name" name = "query name" filter = "list filter" mode = "permission" sort = "sort specification" newdirectory = "new directory name"> ...

Page 97

Cfdirectory 97 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 ca...

Page 99

Cfdump 99 if a table cell is empty, this tag displays "[empty string]". Example this example shows how to use this tag to display a url variable. Url variables contain parameters that are passed in a url string in a page request..

Page 101

Cfelseif 101 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 expression> html and cfml tags expression> html and cfml tags html and cfml tags see also cfif , cfelse , cfabort , cfb...

Page 103

Cferror 103 usage use this tag to provide custom error messages for pages in an application. You generally embed this tag in the application.Cfm file. For more information, see chapter 14, “handling errors,” in developing coldfusion mx applications. To ensure that error pages display successfully, a...

Page 105

Cferror 105 if you continue to have this problem, please contact #error.Mailto# with the following information: #error.Diagnostics#.

Page 107

Cfexecute 107 usage do not put other coldfusion tags or functions between the start and end tags of cfexecute . You cannot nest cfexecute tags. Exceptions throws the following exceptions: • if the application name is not found: application file not found • if the effective user of the coldfusion exe...

Page 109

Cfexit 109 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....

Page 111

Cffile 111 • 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. I...

Page 113

Cffile 113 cffile action = "append" description appends text to a text file on the server. Syntax action = "append" file = "full_path_name" output = "string" addnewline = "yes" or "no" attributes = "file_attributes_list" mode = "mode" charset = "charset_option" > see also cfdirectory history see the...

Page 115

Cffile 115 cffile action = "copy" description copies a file from one directory to another on the server. Syntax action = "copy" source = "full_path_name" destination = "full_path_name" mode = "mode" attributes = "file_attributes_list"> see also cfdirectory history see the history section of the main...

Page 117

Cffile 117 cffile action = "move" description moves a file from one location to another on the server. Syntax action = "move" source = "full_path_name" destination = "full_path_name" mode = "mode" attributes = "file_attributes_list" charset = "charset_option"> see also cfdirectory history see the hi...

Page 119

Cffile 119 cffile action = "read" 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...

Page 121

Cffile 121 cffile action = "readbinary" description reads a binary file (such as an executable or image file) on the serve, 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 usin...

Page 123

Cffile 123 source = "c:\files\memo\keymemo.Doc" destination = "c:\files\memo\oldmemo.Doc"> source = "c:\files\memo\keymemo.Doc" destination = "c:\files\memo\oldmemo.Doc">.

Page 125

Cffile 125 usage after a file upload is completed, you can get status information using file upload parameters. The status parameters use the cffile prefix; for example, cffile.Clientdirectory . Status parameters can be used anywhere other coldfusion parameters can be used. Note: the file prefix is ...

Page 127

Cffile 127 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 action = "write" file = "full_path_name" output = "content" mode = "permission" addnewline = "yes" or "n...

Page 129

Cffile 129 destination = "/home/tomj/testing.Txt" mode = 666 output = "is this a test?"> 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> destination = "/hom...

Page 131

Cfflush 131 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. Magic number number #myindex# is: #randrange( 100000, 999999)#.

Page 133

Cfform 133 in addition to the listed attributes, you can use the following html attributes in the cfform tag. The tag does not use these attributes, but includes them in the form tag that it generates and returns to the browser: • class • enctype • id • onreset • style • target preservedata optional...

Page 135

Cfform 135 • 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 : example your radio button answer was yes your radio button answer was no your checkbox answer was ye...

Page 137

Cfftp 137 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” on page 138 ...

Page 139

Cfftp: opening and closing ftp server connections 139 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 use a cached connection for subseq...

Page 141

Cfftp: connection: file and directory operations 141 cfftp: connection: file and directory operations description use this form of the cfftp tag to perform file and directory operations with cfftp . Syntax action = "action" username = "name" password = "password" name = "query_name" server = "server...

Page 143

Cfftp: connection: file and directory operations 143 the cfftp.Returnvalue variable provides the return value for these actions: • getcurrentdir • getcurrenturl • existsdir • existsfile • exists for more information, see developing coldfusion mx applications. Caution: object (file and directory) nam...

Page 145

Cfftp: connection: file and directory operations 145 cfftp action = "listdir" description to access the columns in a query object, use this tag with action = " listdir" . Usage when you use this action, you must specify a value for the name attribute. This value holds the results of the listdir acti...

Page 147

Cffunction 147 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, you must use a cffunction tag. For information on using the cffunction tag. The following example shows cffunction tag attr...

Page 149

Cfgraph 149 cfgraph description this tag is deprecated. Use the cfchart , cfchartdata , and cfchartseries tags instead. Displays data graphically. History coldfusion mx: deprecated this tag. It works differently than it did in coldfusion 5, and it might not work in later releases. The incompatibilit...

Page 151

Cfgraphdata 151 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 mx: deprecated this tag. It works differently than in coldfusion 5 and might not work in l...

Page 153

Cfgrid 153 deletebutton = "text" sortascendingbutton = "text" sortdescendingbutton = "text"> see also cfgridcolumn , cfgridrow , cfgridupdate , cfapplet , cfform , cfinput , cfselect , cfslider , cftextinput , cftree , cftreeitem history coldfusion mx: changed the rowheaderwidth attribute: coldfusio...

Page 155

Cfgrid 155 rowheight optional minimum row height, in pixels, of grid control. Used with cfgridcolumn type = "image" ; defines space for graphics to display in row. Rowheaders optional yes • yes: displays a column of numeric row labels in grid control • no rowheaderalign optional left • left: left-al...

Page 157

Cfgrid 157 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 s...

Page 159

Cfgrid 159 tablename = "courselist" keyonly = "yes"> select course_id, dept_id, cornumber, corname, corlevel, cordesc from courselist order by dept_id asc, cornumber asc tablename = "courselist" keyonly = "yes"> select course_id, dept_id, cornumber, corname, corlevel, cordesc from courselist order b...

Page 161

Cfgridcolumn 161 cfgridcolumn description used with the cfgrid tag in a cfform . Use this tag to specify column data in a cfgrid control. The font and alignment attributes used in cfgridcolumn override global font or alignment settings defined in cfgrid . Category forms tags syntax name = "column_na...

Page 163

Cfgridcolumn 163 select optional • yes: user can select the column in grid control. • no: user cannot edit column, regardless of cfgrid insert and delete values. If cfgrid selectmode = "row" or "browse" , this value is ignored. Display optional yes • yes • no: hides column type optional • image: gri...

Page 165

Cfgridcolumn 165 numberformat mask characters you can use the following numberformat attribute mask characters, which correspond to those in the numberformat function, to format output in u.S. Numeric and currency styles. For more information, see numberformat on page 631 . (this tag does not suppor...

Page 167

Cfgridrow 167 tablename="courselist" keyonly="yes"> select course_id, dept_id, cornumber, corname, corlevel, cordesc from courselist order by dept_id asc, cornumber asc tablename="courselist" keyonly="yes"> select course_id, dept_id, cornumber, corname, corlevel, cordesc from courselist order by dep...

Page 169

Cfgridupdate 169 cfgridupdate description used within 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,...

Page 171

Cfheader 171 cfheader description generates custom http response headers to return to the client. Category data output tags , page processing tags syntax name = "header_name" value = "header_value" charset="charset"> or statuscode = "status_code" statustext = "status_text"> see also cfcache , cfflus...

Page 173

Cfhtmlhead 173 cfhtmlhead description writes text to the head section of a generated html page. It is useful for embedding javascript code, or putting other html tags, such as meta , link , title , or base in an html page header. Category page processing tags syntax text = "text"> see also cfcache ,...

Page 175

Cfhttp 175 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 ...

Page 177

Cfhttp 177 throwonerror opt no • yes if the server returns an error response code, throws an exception that can be caught using the cftry 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.Status...

Page 179

Cfhttp 179 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: usage the cfhttp tag is a general-purpose tool for creating http requests and handling the returned results. It enables you to ge...

Page 181

Cfhttp 181 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 ...

Page 183

Cfhttpparam 183 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 forms tags , internet protocol tags syntax type = "transaction type" name = "data name" value = "data v...

Page 185

Cfhttpparam 185 • a body type attribute cannot be used with additional body type attributes, or with xml , file , or formfield type attributes. • the xml and body type attributes cannot be used with the cfhttp tag trace method. • the file type attribute is only meaningfulwith the cfhttp tag post and...

Page 187

Cfif 187 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 a...

Page 189

Cfimpersonate 189 cfimpersonate description this tag is obsolete. Use the newer security tools; see “authentication functions” on page 367 and chapter 16, “securing applications,” in developing coldfusion mx applications. History coldfusion mx: this tag is obsolete. It does not work in coldfusion mx...

Page 191

Cfimport 191 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. To use jsp custom tags in a ...

Page 193

Cfindex 193 cfindex description populates a verity search engine collection with an index of documents on a file system or of coldfusion query result sets. A collection must exist before it can be populated. A collection can be indexed in the following ways: • in coldfusion, with the cfindex tag • i...

Page 195

Cfindex 195 usage this tag populates verity search engine collections with metadata from the following sources: • documents stored on a file system • coldfusion query result sets the following table shows the dependent relationships among this tag’s attribute values: query required if type = "custom...

Page 197

Cfindex 197 urlpath="http://localhost/cfdocs/snippets" custom1="custom1" custom2="custom2" recurse="no" extensions=".Htm, .Html, .Cfm, .Cfml" > collection="snippets" action="update" type="path" key="c:\inetpub\wwwroot\cfdocs\snippets" urlpath="http://localhost/cfdocs/snippets" custom1="custom1" cust...

Page 199

Cfindex 199 datasource="book"> select * from book where bookid='file' query="book"> --#description#-- query="book"> --#description#-- collection="snippets" action="delete" type="file" query="book" key="description" > timeout="60"> collection="snippets" action="delete" type="path" key="c:\inetpub\www...

Page 201

Cfinput 201 cfinput description used within the cfform tag, to place radio buttons, check boxes, or text boxes on a form. Provides input validation for the specified control type. Category forms tags syntax type = "input_type" name = "name" value = "initial_value" required = "yes" or "no" range = "m...

Page 203

Cfinput 203 • class • id • onblur • onchange • onclick • ondblclick • onfocus • style • tabindex usage 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. If cfinput check b...

Page 205

Cfinsert 205 cfinsert description inserts records in data sources from data in a coldfusion form or form scope. Category database manipulation tags syntax datasource = "ds_name" tablename = "tbl_name" tableowner = "owner" tablequalifier = "tbl_qualifier" username = "username" password = "password" f...

Page 207

Cfinsert 207 name = "posted" value = "#now()#"> name = "" value = "insert my comment">.

Page 209

Cfinvoke 209 inputparam1 = "value1" inputparam2 = "value2" ... Returnvariable = "var_name" ...> or component = "component name" name = "mystringname for instantiated object"> component = "#mystringname for instantiated component#" method = "method name" returnvariable = "variable name" argumentcolle...

Page 211

Cfinvoke 211 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 inst...

Page 213

Cfinvokeargument 213 cfinvokeargument description passes the name and value of a parameter to a component method or a web service. This tag is used within the cfinvoke tag. Category extensibility tags syntax name="argument name" value="argument value"> see also cfargument , cfcomponent , cffunction ...

Page 215

Cfldap 215 cfldap description provides an interface to a lightweight directory access protocol (ldap) directory server, such as the netscape directory server. Category forms tags , internet protocol tags syntax server = "server_name" port = "port_number" username = "name" password = "password" actio...

Page 217

Cfldap 217 sort optional attribute(s) by which to sort query results. Use a comma delimiter. Sortcontrol optional 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, ...

Page 219

Cfldap 219 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. Server ...

Page 221

Cflock 221 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 ...

Page 223

Cflock 223 these examples show situations that cause deadlocks: the following deadlock could occur if you tried to nest an exclusive lock inside a read lock: the following code shows this scenario: ............... ......... To avoid a deadlock, everyone who nests locks must do so in a well-specified...

Page 225

Cflock 225 e-turtleneck has sold #application.Number# turtlenecks to date. Congratulations! You selected the most comfortable turtleneck in the world. Please select color and size. Red white blue turquoise black forest green xxsmall xsmall small medium large xlarge.

Page 227

Cflog 227 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 suffix .Log and must be located in the c...

Page 229

Cflogin 229 the cflogin tag has a built-in cflogin structure that contains two variables, cflogin.Name and cflogin.Password, 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 use...

Page 231

Cflogout 231 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 extensibility tags syntax see also cflogin , cfloginuser , chapter 16, ...

Page 233

Cfloop: index loop 233 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 index = "parameter_name" from = "beginning_value" to = "ending_value" step = "increment"> ... Html or cfml code ....

Page 235

Cfloop: conditional loop 235 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. Conditio...

Page 237

Cfloop: looping over a query 237 datasource = "library" maxrows = "5"> select templatename from templates.

Page 239

Cfloop: looping over a list or file 239 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 ...

Page 241

Cfmail 241 attributes attribute req/opt default description to required message recipient e-mail addresses. • static address. For example, " support@macromedia.Com " • variable that contains an address. For example, " #form.Email# " . • name of a query column that contains an address. For example, "...

Page 243

Cfmail 243 usage sends a mail message to the specified address. Mail messages can include attachements. The tag body can include cfml code to generate mail output. The cfmailparam and cfmailpart tags can only be used in the cfmail tag body. Mail messages can be single or multipart. If you send a mul...

Page 245

Cfmail 245 --->.

Page 247

Cfmailparam 247 please review the new logo. Tell us what you think..

Page 249

Cfmailpart 249 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 displ...

Page 251

Cfmodule 251 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 ...

Page 253

Cfobject 253 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 basic security, tag restrictions. Category extensibility tags syntax the tag syntax depends on the object type. Some ty...

Page 255

Cfobject: com object 255 example type = "com" class = allaire.Docex1.1 name = "obj"> this object has #obj.Count# items. Type = "com" class = allaire.Docex1.1 name = "obj"> this object has #obj.Count# items. The last name in the third item is #emp.Lastname#. Looping through all items in the collectio...

Page 257

Cfobject: corba object 257 cfobject: corba object description calls methods on a registered corba object. Syntax type = "corba" context = "context" class = "file or naming service" name = "text" locale = "type-value arguments"> see also cfcollection , cfexecute , cfindex , cfreport , cfsearch , cfwd...

Page 259

Cfobject: java or ejb object 259 cfobject: java or ejb object description creates and manipulates a java and enterprise java bean (ejb) object. Syntax type = "java" action = "create" class = "java class" name = "object name"> see also cfcollection , cfexecute , cfindex , cfreport , cfsearch , cfwddx...

Page 261

Cfobject: web service object 261 cfobject: web service object description creates a web service proxy object. Syntax webservice= "http://....?Wsdl" or "name set in administrator" name = "myobjectname"> see also cfcollection , cfexecute , cfindex , cfreport , cfsearch , cfwddx attributes usage instan...

Page 263

Cfoutput 263 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 query = "query_name" group = "query_column" groupcasesensitive = "yes" or "no" startrow = "...

Page 265

Cfparam 265 cfparam description tests for a parameter’s existence, tests its data type, and, if a default value is not assigned, optionally provides one. Category variable manipulation tags syntax name = "param_name" type = "data_type" default = "value"> see also cfcookie , cfregistry , cfsaveconten...

Page 267

Cfpop 267 cfpop description retrieves or deletes e-mail messages from a pop mail server. Category forms tags , internet protocol tags syntax server = "servername" port = "port_number" username = "username" password = "password" action = "action" name = "queryname" messagenumber = "number" uid = "num...

Page 269

Cfpop 269 cfpop query variables the following table describes the variables that provide information about the query that is returned by cfpop : query message header and body columns the following table lists the message header and body columns that are returned if action = " getheaderonly" or " get...

Page 271

Cfprocessingdirective 271 cfprocessingdirective description provides the following insformation to coldfusion on 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 (characte...

Page 273

Cfprocessingdirective 273 • if a page has a byte order mark (bom), and a pageengoding 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...

Page 275

Cfprocparam 275 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 mx supports positional parameters only and you must code cfprocparam tags in th...

Page 277

Cfprocparam 277 the second result set: the output parameter is:'#foo#'.

Page 279

Cfprocresult 279 cfsqltype = cf_sql_integer value = "1" dbvarname = @param1> variable = foo dbvarname = @param2> the output param value: ’#foo#’ the results information #name#,#date_col# cfsqltype = cf_sql_integer value = "1" dbvarname = @param1> variable = foo dbvarname = @param2> the output param ...

Page 281

Cfproperty 281 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, the cfproperty only provides metadata information when the component is viewed using introspection, for example, by ope...

Page 283

Cfquery 283 attributes usage because the timeout parameter only the maximum time for each sub-operation 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 ap...

Page 285

Cfquery 285 state query="getparks" startrow="#startrow#" maxrows="#maxrows#"> #getparks.Currentrow# #parkname# #region# #state# query="getparks" startrow="#startrow#" maxrows="#maxrows#"> #getparks.Currentrow# #parkname# #region# #state# #evaluate(startrow + maxrows)# ">see next #maxrows# rows.

Page 287

Cfqueryparam 287 attributes attribute req/opt default description value required value that coldfusion passes to the right of the comparison operator in a where clause. If cfsqltype is a date or time option, ensure that the date value uses your dbms-specific date format. Use the createodbcdatetime o...

Page 289

Cfqueryparam 289 name="getfirst" datasource="cfsnippets"> select * from employees where lastname= value="#lastname#" cfsqltype="cf_sql_varchar" maxlength="17"> name="getfirst" datasource="cfsnippets"> select * from employees where lastname= value="#lastname#" cfsqltype="cf_sql_varchar" maxlength="17...

Page 291

Cfregistry 291 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 action = "getall" branch = "branch" type = "data type" name = "query name" sort = "criteria"> attributes usage this tag retu...

Page 293

Cfregistry 293 cfregistry action = "set" description adds a registry key, adds a value, or updates a value. Syntax action = "set" branch = "branch" entry = "key or value" type = "value type" value = "data"> attributes usage if it does not exist , cfregistry creates the key or value. Example branch =...

Page 295

Cfreport 295 cfreport description runs a predefined crystal reports report. Applies only to windows systems. Uses the cfcrystal.Exe file to generate reports. Sets parameters in the crystal reports engine according to its attribute values. Category extensibility tags syntax report = "report_path" dat...

Page 297

Cfrethrow 297 cfrethrow description rethrows the currently active exception. Preserves the exception’s cfcatch . Type and cfcatch.Tagcontext variable values. Category exception handling tags , extensibility tags syntax see also cferror , cfthrow , cftry usage use this tag within a cfcatch block. Thi...

Page 299

Cfreturn 299.

Page 301

Cfschedule 301 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, with...

Page 303

Cfschedule 303 usage this tag and the coldfusion mx administrator scheduled task page schedule coldfusion tasks. Tasks that you add or change using this tag are visible in the aministrator. You can disable this tag in the administrator sandbox/resource security page. This tag’s success or failure st...

Page 305

Cfscript 305 you cannot use the elseif construct within a cfscript tag. You can use code such as the following: else if ( condition ) { ... } exception handling with the cfscript tag to handle exceptions with this tag, use try and catch statements, which are equivalent to the cftry and cfcatch tags....

Page 307

Cfsearch 307 cfsearch description searches verity collections using coldfusion or k2server, whichever search engine a collection is registered by. (coldfusion can also search collections that have not been registered, with the cfcollection tag.) a collection must be created and indexed before this t...

Page 309

Cfsearch 309 ■ cf_root\lib\common\style\file • unix: ■ cf_root/lib/common/style (typically, cf_root = /opt/coldfusionmx) ■ cf_root/lib/common/style/custom ■ cf_root/lib/common/style/file note: to search for a character such as an angle bracket (), you must use a criteria attribute value such as "<...

Page 311

Cfsearch 311 criteria = "cf_key=bookid2"> 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.Recordsse...

Page 313

Cfselect 313 in addition to the listed attributes, you can use the following html attributes in the cfform tag without using the passthrough attribute. The tag does not use these attributes, but includes them in the html of the form tag that it generates and returns to the browser: • class • id • on...

Page 315

Cfselect 315 expand="no" queryasroot="no"> queryasroot="no" expand="no"> expand="no" queryasroot="no"> queryasroot="no" expand="no"> expand="no" queryasroot="no"> cfgrid presentation of data width="600" query="getemployees" insert="no" delete="no" sort="no" font="verdana" bold="no" italic="no" appen...

Page 317

Cfservletparam 317 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 s...

Page 319

Cfset 319 function local variables the var keyword specifies that the variable being defined is only available inside the body of a function that you define 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 func...

Page 321

Cfsetting 321 cfsetting description controls aspects of page processing, such as the output of html code in pages. Category page processing tags , variable manipulation tags syntax enablecfoutputonly = "yes" or "no" showdebugoutput = "yes" or "no" requesttimeout = "value in seconds" > see also cfcac...

Page 323

Cfsilent 323 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 usage this tag requires an end tag. Example inside cfsilent block b-a = #c...

Page 325

Cfslider 325 refreshlabel optional yes • yes: when user moves slider, label is refreshed • no range optional "0,100" numeric slider range values. Separate values with a comma. Scale optional unsigned integer. Defines slider scale, within range. For example, if range = "0,1000" and scale = "100" , th...

Page 327

Cfslider 327 usage this tag requires the client to download a java applet. Using this tag may be slightly slower than using an html form element to display the same information. For this tag to work properly. The browser must be javascript-enabled. If the following conditions are true, a user’s sele...

Page 329

Cfstoredproc 329 • cfprocparam if the stored procedure uses input or output parameters, code one cfprocparam tag per parameter. Additionally, you must code cfprocparam tags in the same order as the parameters in the stored procedure definition. If you set returncode = "yes" , this tag sets the varia...

Page 331

Cfswitch 331 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, a...

Page 333

Cftable 333 usage this tag aligns table data, sets column widths, and defines column heads. At least one cfcol tag is required within this tag. You must put cfcol and cftable tags adjacent in a page. The only tag that you can nest within this tag is the cfcol tag. You cannot nest cftable tags. To di...

Page 335

Cftextinput 335 validate optional • date: verifies format mm/dd/yy. • eurodate: verifies date format dd/mm/yyyy. • time: verifies time format hh:mm:ss. • float: verifies floating point format. • integer: verifies integer format. • telephone: verifies telephone format ###-###-####. The separator can ...

Page 337

Cftextinput 337 • 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 cfform . If the cfform preservedata attri...

Page 339

Cfthrow 339 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 s...

Page 341

Cftrace 341 cftrace description displays and logs debugging data about the state of an application at the time the cftrace tag executes. Tracks runtime 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...

Page 343

Cftransaction 343 cftransaction description instructs the database management system to treat multiple database operations as a single transaction. Provides database commit and rollback processing. Category database manipulation tags syntax action = "begin" or "commit" or "rollback" isolation = "rea...

Page 345

Cftree 345 cftree description inserts a tree control in a form. Validates user selections. Used within a cftree tag block. You can use a coldfusion query to supply data to the tree. Category forms tags syntax required = "yes" or "no" delimiter = "delimiter" completepath = "yes" or "no" appendkey = "...

Page 347

Cftree 347 usage this tag requires the client to download a java applet. Downloading an applet takes time; therefore, using this tag might be slightly slower than using an html form element or the cfinput tag to get the same information. For this tag to work properly. The browser must be javascript-...

Page 349

Cftreeitem 349 cftreeitem description populates a form tree control, created with the cftree tag, with elements. To display icons, you can use the img values that coldfusion provides, or reference your own icons. Category forms tags syntax value = "text" display = "text" parent = "parent_name" img =...

Page 351

Cftreeitem 351 to see expanded information. Size = "#getemployees.Recordcount#" query = "getemployees" value = "lastname" required = "no"> select all size = "#getemployees.Recordcount#" query = "getemployees" value = "lastname" required = "no"> select all value = "see information for this employee">...

Page 353

Cftry 353 cftry description used with one or more cfcatch tags. 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...

Page 355

Cfupdate 355 cfupdate description updates records in a data source from data in a coldfusion form or form scope. Category database manipulation tags syntax datasource = "ds_name" tablename = "table_name" tableowner = "name" tablequalifier = "qualifier" username = "username" password = "password" for...

Page 357

Cfupdate 357.

Page 359

Cfwddx 359 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 conversion...

Page 361

Cfxml 361 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, then assigns the resulting text to an xml document object variable. Category extensibility tags s...

Page 363: Chapter 3

363 chapter 3 coldfusion functions this chapter lists and categorizes coldfusion markup language (cfml) functions. Contents function list. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 364 functions by category . . . . . . ....

Page 365

Function list 365 bitxor isdefined reverse ceiling isk2serverabroker right chr isk2serverdoccountexceeded rjustify cjustify isk2serveronline round compare isleapyear rtrim comparenocase isnumeric second cos isnumericdate setencoding createdate isobject setlocale createdatetime isquery setprofilestri...

Page 367

Functions by category 367 functions by category the following tables list functions by their category or purpose. Array functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 367 authentication functions . . . . . . . . . . . ....

Page 369

Functions by category 369 dynamic evaluation functions extensibility functions 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. International functions list functions de evaluate iif setvariable cr...

Page 371

Functions by category 371 see also “conversion functions” on page 367 . Structure functions system functions xml functions compare len refind tobase64 comparenocase ljustify refindnocase tobinary dayofweekasstring listvaluecount removechars tostring decrypt listvaluecountnocase repeatstring trim enc...

Page 373

Function changes since coldfusion 5 373 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. Obsolete functions, pa...

Page 375

Acos 375 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 usage the range of the result is 0 to π ...

Page 377

Arrayavg 377 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 parameters usage the following example...

Page 379

Arrayclear 379 arrayclear description deletes the data in an array. Returns true, on successful completion. Category array functions function syntax arrayclear(array) see also arraydeleteat history coldfusion mx: changed behavior: this function can be used on xml objects. Parameters example your arr...

Page 381

Arrayinsertat 381 arrayinsertat description inserts a value into an array. Array elements whose indexes are 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, p...

Page 383

Arraylen 383 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 history coldfusion mx: changed behavior: this function can be used on child xml objects. Paramet...

Page 385

Arraymin 385 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 example this example uses arraymin to find the smallest number i...

Page 387

Arrayprepend 387 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 parameters example select firstname, lastname from employees #arrayprepend...

Page 389

Arrayset 389 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, valu...

Page 391

Arraysort 391 throws if an array element is 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. Example select firstname, lastname from employees ....

Page 393

Arrayswap 393 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) parameters example show the res...

Page 395

Asc 395 asc description determines the value of a character. Returns the value of the first character of a string; if 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 r...

Page 397

Asin 397.

Page 399

Authenticatedcontext 399 authenticatedcontext description this function is obsolete. Use the newer security tools; see “authentication functions” on page 367 and chapter 16, “securing applications,” in developing coldfusion mx applications. History coldfusion mx: this function is obsolete. It does n...

Page 401

Bitand 401 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 usage bit functions operate on 32-bit signed integers, in the ran...

Page 403

Bitmaskread 403 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 usage bit funct...

Page 405

Bitnot 405 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 usage bit functions operate on 32-bit signed integers, in the range ...

Page 407

Bitshln 407 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 usage bit functions operate on 32-bit...

Page 409

Bitxor 409 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 usage bit functions operate on 32-bit signed integers, in the range -...

Page 411

Chr 411 chr 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 char...

Page 413

Compare 413 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 , ...

Page 415

Comparenocase 415 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 ...

Page 417

Cos 417 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 usage the range of the result is -1 to 1. To convert deg...

Page 419

Createdate 419 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 , createodbcdate parameters usage createdate is a subset of createdatetime . The time in the returned obj...

Page 421

Createdatetime 421 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 parameters example your date value,...

Page 423

Createobject 423 createobject description creates a coldfusion object, of a specified type. Returns an object, of the specified type. Note: you can enable and disable this function in the coldfusion administrator, coldfusion basic security, tag restrictions page. Category extensibility functions his...

Page 425

Createobject 425 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) parameters usage on unix systems, coldfusion searches first for a file ...

Page 427

Createobject 427 myobj = createobject("corba", "macromedia/eng/cf", "nameservice", "visibroker") // uses nameservice myobj = createobject("corba", "d:\temp\tester.Ior", "nameservice") // uses nameservice and default configuration.

Page 429

Createobject 429 createobject: web service object description this function can create a web service object. Returns a web service object. Function syntax createobject (type, urltowsdl) parameters usage you can use the createobject function to create a web service. Example newobject2 = createobject(...

Page 431

Createodbcdate 431 enter the year, month and day, as integers: year required="yes"> month message="please enter a month (1-12)" validate="integer" required="yes"> day message="please enter a day of the month (1-31)" validate="integer" required="yes"> hour message="you must enter an hour (0-23)" vali...

Page 433

Createodbcdatetime 433 enter a year, month and day, as integers: year type="text" name="year" value="1998" validate="integer" required="yes"> month type="text" name="month" value="6" range="1,12" message="enter a month (1-12)" validate="integer" required="yes"> day message="enter a day of the month ...

Page 435

Createtime 435 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 parameters usage createtime is a subset of createdatetime . A time variable is a special ...

Page 437

Createtimespan 437 park name region state maxrows = "#maxrows#"> #getparks.Currentrow# #parkname# #region# #state# maxrows = "#maxrows#"> #getparks.Currentrow# #parkname# #region# #state# #evaluate(startrow + maxrows)#"> see next #maxrows# rows.

Page 439

Dateadd 439 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 ...

Page 441

Datecompare 441 datecompare description performs a full date/time comparison of two dates. Returns • -1, if date1 is less than date2 • 0, if date1 is equal to date2 • 1, if date1 is greater than date2 category date and time functions function syntax datecompare("date1", "date2" [, "datepart"]) see a...

Page 443

Dateconvert 443 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 required. Returns utc- or local-formatted time object. Category date a...

Page 445

Datediff 445 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 coldfu...

Page 447

Datediff 447 #dateformat(now())# cfoutput>"> date 2 #dateformat(now())# cfoutput>"> what kind of unit to show difference? Years quarters months days of year days weekdays weeks hours minutes seconds ..

Page 449

Dateformat 449 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, macromedia recommends that you use this function and the lsdateformat , timeform...

Page 451

Datepart 451.

Page 453

Dayofweek 453 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 , daysinm...

Page 455

Dayofyear 455 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 par...

Page 457

Daysinyear 457 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 , daysinyear , firstdayofmonth , isleapyear ...

Page 459

De 459 for more information and code examples, see chapter 4, “using expressions and pound signs,” in developing coldfusion mx applications. Example the value of the expression #evaluate(de(form.Myexpression))# is #myexpression#. Try a simple expression, such as "2+2". #cfcatch.Message#.

Page 461

Decrementvalue 461 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 example returns the integer part of a number decremente...

Page 463

Deleteclientvariable 463 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 getc...

Page 465

Dollarformat 465 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...

Page 467

Encrypt 467 encrypt description encrypts a string. 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. Uses an xor-based algorithm that uses a pseudo-random 32-bit key...

Page 469

Exp 469 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 ma...

Page 471

Expandpath 471 the current directory is: #getdirectoryfrompath(thispath)# expandpath(yourfile))> 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 dire...

Page 473

Find 473 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...

Page 475

Findoneof 475 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 ...

Page 477

Fix 477 fix description converts a real number to an integer. Returns if number is greater than or equal to 0, the closest integer less than number. If number is less than 0, the closest integer greater than number. Category mathematical functions function syntax fix(number) see also ceiling , int ,...

Page 479

Getauthuser 479 getauthuser description gets the name of an authenticated user. Returns the name of an authenticated user. Category authentication functions function syntax getauthuser() see also isuserinrole , cflogin , cfloginuser , chapter 16, “securing applications,” in developing coldfusion mx ...

Page 481

Getbasetaglist 481 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 functi...

Page 483

Getclientvariableslist 483 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 deletecl...

Page 485

Getdirectoryfrompath 485 getdirectoryfrompath description extracts a directory from an absolute 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...

Page 487

Getencoding 487 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 setencoding , cfcontent , cfproce...

Page 489

Getfilefrompath 489 getfilefrompath description extracts a filename from an absolute path. Returns filename, as a string. Category system functions function syntax getfilefrompath(path) see also expandpath , getcurrenttemplatepath parameters example the current directory is: #getdirectoryfrompath(th...

Page 491

Gethttprequestdata 491 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() paramete...

Page 493

Gethttptimestring 493 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. Category date and time functions , international functions function syntax gethttptimestring(date_time_obj...

Page 495

Getk2serverdoccountlimit 495 getk2serverdoccountlimit description this function is deprecated. Gets the maximum number of documents that the coldfusion registered k2 server is permitted to return from a search. This function is used primarily by the coldfusion verity and k2server administrator pages...

Page 497

Getmetadata 497 getmetadata description gets metadata (the methods, properties, and parameters of a component) associated with an object that is deployed on the coldfusion server. This functionality, called introspection, lets applications dynamically determine how to use a component. Returns key-va...

Page 499

Getmetricdata 499 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...

Page 501

Getpagecontext 501 getpagecontext description gets the current coldfusion mx pagecontext object that provides access to page attributes and configuration, request and response objects. Returns the current coldfusion mx java pagecontext java object. Category system functions function syntax getpageco...

Page 503

Getprofilestring 503 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 su...

Page 505

Gettempdirectory 505 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 return...

Page 507

Gettemplatepath 507 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..

Page 509

Gettimezoneinfo 509 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 worl...

Page 511

Gettoken 511 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 ne...

Page 513

Hash 513 hash description converts a variable-length string to a 32-byte, hexadecimal string, using the md5 algorithm. (it is not possible to convert the hash result back to the source string.) returns 32-byte, hexadecimal string category conversion functions , other functions , string functions fun...

Page 515

Htmlcodeformat 515 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. Returns are removed from string. Special characters ( > ) a...

Page 517

Iif 517 iif description evaluates a boolean conditional dynamic expression. Depending on whether the expression is true or false, 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 conditio...

Page 519

Iif 519.

Page 521

Inputbasen 521 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 example formatbasen converts a number to...

Page 523

Int 523 int description calculates the closest integer that is smaller than number. Returns an integer, as a string. Category mathematical functions function syntax int(number) see also ceiling , fix , round parameters example int returns the closest integer smaller than a number. Int(11.7) : #int(1...

Page 525

Isauthenticated 525 isauthenticated description this function is obsolete. Use the newer security tools; see “authentication functions” on page 367 and chapter 16, “securing applications,” in developing coldfusion mx applications. History coldfusion mx: this function is obsolete. It does not work in...

Page 527

Isbinary 527 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 example the following string is...

Page 529

Iscustomfunction 529 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 usage the iscustomfunction function retu...

Page 531

Isdate 531 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; otherwise, false. Coldfusion converts the boolean return value to its string equivalent, "yes" or "no." category date and tim...

Page 533

Isdefined 533 isdefined description evaluates a string value to determine whether the variable named in it exists. This function is an alternative to the parameterexists function, which is deprecated. Returns true, if the variable is found, or, for a structure, if the specified key is defined; false...

Page 535

Isk2serverabroker 535 isk2serverabroker description this function is deprecated. Determines whether the k2server version is k2 broker. For more information, see getk2serverdoccountlimit on page 495 . This function is used primarily by the coldfusion verity and k2server administrator pages. This func...

Page 537

Isk2serveronline 537 isk2serveronline description this function is deprecated. Determines whether the k2server is running and available to perform a search. This function is used primarily by the coldfusion verity and k2server administrator pages. This function uses verity k2server release k2.2.0. R...

Page 539

Isnumeric 539 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; otherwise, false. Category decision functions function syntax...

Page 541

Isobject 541 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...

Page 543

Isprotected 543 isprotected description this function is obsolete. Use the newer security tools; see “authentication functions” on page 367 and chapter 16, “securing applications,” in developing coldfusion mx applications history coldfusion mx: this function is obsolete. It does not work in coldfusi...

Page 545

Issimplevalue 545 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) parameters example before the query is run, the value of getemployee...

Page 547

Isstruct 547 --->.

Page 549

Iswddx 549 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) history coldfusion mx: changed behavior: if the value parameter is not a ...

Page 551

Isxmldoc 551 isxmldoc description determines whether a function parameter is an extended markup language (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 isx...

Page 553

Isxmlroot 553 isxmlroot description determines whether a function parameter is the root element of an extended markup language (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 fun...

Page 555

Javacast 555 } within coldfusion, you use the following code: action="create" type = "java" class = "fooclass" name = obj> 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)# action="create" ...

Page 557

Lcase 557 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 example your text, #form.Sampletext#, returned in lowercase is #lcase(form.Sampletext)#...

Page 559

Left 559 9.

Page 561

Listappend 561 listappend description concatenates a list or element to a list. Returns a copy of the list , with value appended. If delimiter = "" , returns a copy of the list, unchanged. Category list functions function syntax listappend(list, value [, delimiters ]) see also listprepend , listinse...

Page 563

Listchangedelims 563 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 ]) see also listfirst , listqualify parameters e...

Page 565

Listcontains 565 the string "two" is in element #listfind(alist, "two")# of the list..

Page 567