MACROMEDIA COLDFUSION 4.5-CFML LANGUAGE Reference - page 295
Chapter 2: ColdFusion Functions
271
ArraySum
Returns the sum of values in the specified array.
Syntax
ArraySum(
array
)
array
Name of the array containing values you want to add together.
Example
ArraySum Example
This example uses ArraySum to add two numbers together.
The sum of the numbers is
id" align = "left" width = 2 text = "#emp_id#"> name/email" align = "left" width = 15 text = "#firstname# #lastname#"> phone number" align = "center" width = 15 text = "#phone#"...
Page 49
Chapter 1: coldfusion tags 25 cfcollection the cfcollection tag allows you to create and administer verity collections. Syntax collection="collection" path="implementation directory" language="language"> action required. Specifies the action to perform: • create — creates a new collection using the ...
Page 50
26 cfml language reference language optional for create. To use the language attribute you must have the coldfusion international search pack installed. Valid entries are: • english (default) • german • finnish • french • danish • dutch • italian • norwegian • portuguese • spanish • swedish usage cf...
Page 51
Chapter 1: coldfusion tags 27 collection="#form.Collectionname#" path="c:\cfusion\verity\collections\"> collection="#form.Collectionname#"> collection repaired. Collection="#form.Collectionname#"> collection="#form.Collectionname#"> collection optimized. Collection="#form.Collectionname#"> collectio...
Page 52
28 cfml language reference cfcontent defines the mime type returned by the current page. Optionally, allows you to specify the name of a file to be returned with the page. Note the coldfusion server basic security settings may prevent cfcontent from executing. These settings are managed using the co...
Page 53
Chapter 1: coldfusion tags 29 file="c:\inetpub\wwwroot\cfdocs\main.Htm" deletefile="no"> file="c:\inetpub\wwwroot\cfdocs\main.Htm" deletefile="no"> cfcontent example 2 this example shows how the reset attribute changes the output for text. Reset = "yes ": 123456 this example shows how the reset attr...
Page 54
30 cfml language reference cfcookie defines cookie variables, including expiration and security options. Syntax value="text" expires="period" secure="yes/no" path="urls" domain=".Domain"> name required. The name of the cookie variable. Value optional. The value assigned to the cookie variable. Expir...
Page 55
Chapter 1: coldfusion tags 31 do not have an expires attribute in a cfcookie, the cookie set exists only as long as the client browser is open. When the browser is closed, the cookie expires. It is never written to the cookies.Txt file. Example select email, fromuser, subject, posted from comments c...
Page 56
32 cfml language reference 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..
Page 57
Chapter 1: coldfusion tags 33 cfdirectory use the cfdirectory tag to handle all interactions with directories. Note the coldfusion server basic security settings may prevent cfdirectoryfrom executing. These settings are managed using the coldfusion administrator basic security page. In order for cfd...
Page 58
34 cfml language reference optional. Used with action="create" to define the permissions for a directory on solaris or hp-ux. Ignored in windows. Valid entries correspond to the octal values (not symbolic) of the unix chmod command. Permissions are assigned for owner, group, and other, respectively....
Page 59
Chapter 1: coldfusion tags 35 example cfdirectory example name="mydirectory" sort="name asc, size desc"> text="#name#"> text="#size#"> name="mydirectory" sort="name asc, size desc"> text="#name#"> text="#size#"> text="#name#"> text="#size#"> text="#size#">.
Page 60
36 cfml language reference cferror provides the ability to display customized html pages when errors occur. This allows you to maintain a consistent look and feel within your application even when errors occur. Syntax type="request" or "validation" or "monitor" or "exception" template="template_path...
Page 61
Chapter 1: coldfusion tags 37 mailto optional. The email address of the administrator who should be notified of the error. This value is available to your custom error page using the mailto property of the error object, such as #error.Mailto#. Exception required if the type is specified as exception...
Page 62
38 cfml language reference error variables for request, exception, and monitor types the following error variables are available when cferror specifies type="request", type="exception" or type="monitor": note if you have specified type="exception" or type="monitor" , you can substitute the prefix cf...
Page 63
Chapter 1: coldfusion tags 39 example cferror provides the ability to display customized html pages when errors occur. This allows you to maintain a consistent look and feel within your application even when errors occur. Note that no cfml can be displayed in the resulting templates except for the s...
Page 64
40 cfml language reference cfexecute enables coldfusion developers to execute any process on the server machine. Syntax name=" applicationname " arguments="commandline arguments" outputfile="output file name” timeout=”timeout interval in seconds”> name required. The full path name of the application...
Page 65
Chapter 1: coldfusion tags 41 usage cfexecute is available on windows nt 4.0 and unix platforms. Do not put any other coldfusion tags or functions between the start and the end tags of cfexecute. Also, cfexecute tags cannot be nested. Exception cfexecute throws the following exceptions: • if the app...
Page 66
42 cfml language reference cfexit cfexit can be used to: • abort the processing of the currently executing cfml custom tag. • exit the template within the currently executing cfml custom tag. • reexecute a section of code within the currently executing cfml custom tag. Syntax method optional. Specif...
Page 67
Chapter 1: coldfusion tags 43 example cfexit can be used to abort the processing of the currently executing cfml custom tag. Execution will resume immediately following the invocation of the custom tag in the page that called the tag. Cfexit is used primarily to perform a conditional stop of process...
Page 68
44 cfml language reference if cfexit is used outside of a custom tag, it functions like a cfabort. For example, the text after this message will not be processed: this text will not be executed due to the existence of the cfexit tag above it..
Page 69
Chapter 1: coldfusion tags 45 cffile use the cffile tag to handle all interactions with files. The attributes you use with cffile depend on the value of the action attribute. For example, if the action is "write, " coldfusion expects the attributes associated with writing a text file. See the indivi...
Page 70
46 cfml language reference cffile action attributes depending on the value you assign to the action attribute of cffile, there are several additional attributes you can set. This table shows which attributes you can use with each cffile action. Sections that follow describe these values and attribut...
Page 71: Cffile Action="upload"
Chapter 1: coldfusion tags 47 cffile action="upload" use cffile with the upload action to upload a file specified in a form field to a directory on the web server. Note the mode attribute applies to coldfusion on solaris and hp-ux, only. Syntax filefield="formfield" destination="full_path_name" name...
Page 72
48 cfml language reference note that the browser uses the file extension to determine file type. Mode optional. Defines permissions for an uploaded file on solaris or hp-ux. Ignored in windows. Valid entries correspond to the octal values (not symbolic) of the unix chmod command. Permissions are ass...
Page 73
Chapter 1: coldfusion tags 49 evaluating the results of a file upload after a file upload is completed, you can retrieve status information using file upload parameters. This status information includes a wide range of data about the file, such as the file’s name and the directory where it was saved...
Page 74
50 cfml language reference tip use the file prefix to refer to these parameters, for example, #file.Fileexisted# . Note file status parameters are read-only. They are set to the results of the most recent cffile operation. (if two cffile tags execute, the results of the first are overwritten by the ...
Page 75: Cffile Action="move"
Chapter 1: coldfusion tags 51 destination="/home/tomj/testing.Txt" mode=666 output="is this a test?"> the next example uploads a file and gives it rwx-rw-rw permissions (owner/group/ other=read/write). Cffile action="upload" filefield="fieldname" destination="/tmp/program.Exe" mode=755> cffile actio...
Page 76: Cffile Action="rename"
52 cfml language reference example the following example moves the keymemo.Doc file from the c:\files\upload\ directory to the c:\files\memo\ directory on windows: source="c:\files\upload\keymemo.Doc" destination="c:\files\memo\"> note on windows, you must include the backward slash (\) after the de...
Page 77: Cffile Action="copy"
Chapter 1: coldfusion tags 53 example the following example renames the file keymemo.Doc to oldmemo.Doc : source="c:\files\memo\keymemo.Doc" destination="c:\files\memo\oldmemo.Doc"> cffile action="copy" the cffile tag can be used to copy a file from one directory to another on the server. Syntax sou...
Page 78: Cffile Action="delete"
54 cfml language reference note on windows, you must include the backward slash (\) after the destination directory name if you do not specify a file name. In this example, the specified destination directory is "backup. " cffile action="delete" the cffile tag can be used to delete a file on the ser...
Page 79: Cffile Action="readbinary"
Chapter 1: coldfusion tags 55 #message# coldfusion supports a number of powerful functions for manipulating the contents of text files. You can also use variable created by a cffile read operation in arraytolist and listtoarray functions. See string functions and array functions for more information...
Page 80
56 cfml language reference file required. The full path name of the file to be created. Output required. The content of the file to be created. Mode optional. Defines permissions for a file on solaris or hp-ux. Ignored in windows. Valid entries correspond to the octal values (not symbolic) of the un...
Page 81
Chapter 1: coldfusion tags 57 example the following example creates a file with the information a user entered into an html insert form: file="c:\files\updates\#form.Updatetitle#.Txt" output="created by: #form.Fullname# date: #form.Date# #form.Content#"> if the user submitted a form where: updatetit...
Page 82: Cffile Action="append"
58 cfml language reference cffile action="append" use cffile with the append action to append additional text to the end of an existing text file, for example, when creating log files. Syntax file="full_path_name" output="string" attributes="file_attributes"> file required. The full path name of the...
Page 83
Chapter 1: coldfusion tags 59 cfform cfform allows you to build a form with cfml custom control tags that provide much greater functionality than standard html form input elements. Syntax action="form_action" enablecab="yes/no" onsubmit="javascript" target="window_name" enctype="type" passthrough="h...
Page 84
60 cfml language reference code that is generated for the cfinput tag. See the usage section for more information about specifying values. Usage the following custom control tags are available: • cfinput — creates a form input element (radio button, text box, or checkbox) and can validate form input...
Page 85
Chapter 1: coldfusion tags 61 example cfform example your radio button answer was yes your radio button answer was no your checkbox answer was yes your checkbox answer was no and form.Textsample is not ""> results of credit card input and form.Textsample is not ""> your credit card number, #form.Tex...
Page 86
62 cfml language reference cfinput text boxes. (this item is optional) please enter a credit card number: card number" validate="creditcard" required="no"> card number" validate="creditcard" required="no"> rate your approval of this example from 1 to 10 by sliding the control. 1 message="please ente...
Page 87
Chapter 1: coldfusion tags 63 cfftp cfftp allows users to implement file transfer protocol operations. By default, cfftp caches an open connection to an ftp server. Note the cfftp tag is for moving files between a coldfusion server and an ftp server. Cfftp cannot move files between a coldfusion serv...
Page 88
64 cfml language reference port="port" connection="name" proxyserver="proxyserver" proxybypass="proxybypass" retrycount="number" stoponerror="yes/no" passive="yes/no"> action required. Determines the ftp operation to perform. To create an ftp connection, use open. To terminate an ftp connection, use...
Page 89
Chapter 1: coldfusion tags 65 retrycount optional. Number of retries until failure is reported. Default is one (1). Stoponerror optional. Yes or no. When yes, halts all processing and displays an appropriate error. Default is yes. When no, three variables are populated: • cfftp.Succeeded – yes or no...
Page 90
66 cfml language reference connection="my_query"> #name# close the connection: connection="my_query" stoponerror="yes"> did it succeed? #cfftp.Succeeded# ---> connection="my_query" stoponerror="yes"> did it succeed? #cfftp.Succeeded# ---> file and directory operations with cfftp use this form of the...
Page 91
Chapter 1: coldfusion tags 67 • createdir • listdir • getfile • putfile • rename • remove • getcurrentdir • getcurrenturl • existsdir • existsfile • exists note: names of objects (files and directories) are case-sensitive; thus, using listdir on " test.Log " will not find a file named " test.Log . "...
Page 92
68 cfml language reference name required for action="listdir". Specifies the query name to hold the directory listing. See usage for more information. Server required if the ftp connection is not already cached. If connection caching is used, the server attribute is not required. The ftp server to c...
Page 93
Chapter 1: coldfusion tags 69 item required for action=exists, and remove. Specifies the object, file or directory, of these actions. Existing required for action=rename. Specifies the current name of the file or directory on the remote server. New required for action=rename. Specifies the new name ...
Page 94
70 cfml language reference cfftp.Returnvalue variable the value of the cfftp.Returnvalue variable is determined by the results of the action attribute used in cfftp. Accessing the columns in a query object when you use cfftp with the listdir action, you must also specify a value for the name attribu...
Page 95
Chapter 1: coldfusion tags 71 connection caching once you’ve established a connection with cfftp, you can reuse the connection to perform additional ftp operations. To do this, you use the connection attribute to define and name an ftp connection object that stores information about the connection. ...
Page 96
72 cfml language reference action="listdir" directory="/*." name="q" stoponerror="yes"> ftp directory listing: name" text="#name#"> text="date(format#lastmodified#)"> action="listdir" directory="/*." name="q" stoponerror="yes"> name" text="#name#"> text="date(format#lastmodified#)"> text="date(forma...
Page 97
Chapter 1: coldfusion tags 73 cfgrid used inside cfform , cfgrid allows you to place a grid control in a coldfusion form. A grid control is a table of data divided into rows and columns. Cfgrid column data is specified with individual cfgridcolumn tags. See also cfgridrow and cfgridupdate tags. Synt...
Page 98
74 cfml language reference deletebutton="text" sortascendingbutton="text" sortdescendingbutton="text"> name required. A name for the grid element. Height optional. Height value of the grid control in pixels. Width optional. Width value of the grid control in pixels. Vspace optional. Vertical margin ...
Page 99
Chapter 1: coldfusion tags 75 italic optional. Yes or no. Yes presents all grid control text in italic. Default is no. Bold optional. Yes or no. Yes presents all grid control text in boldface. Default is no. Href optional. Url to associate with the grid item or a query column for a grid that is popu...
Page 100
76 cfml language reference type="image", you can use rowheight to define enough room for graphics you want to display in the row. Rowheader optional. Yes or no. Yes displays row labels in the grid control. Defaults to yes. Rowheaderalign optional. Enter left, right, or center to position data within...
Page 101
Chapter 1: coldfusion tags 77 a hex value can be entered in the form: bgcolor="## xxxxxx" where x is 0-9 or a-f. Use either two pound signs or no pound signs. Selectcolor optional. Background color for a selected item. See bgcolor for color options. Selectmode optional. Selection mode for items in t...
Page 102
78 cfml language reference usage you can populate a cfgrid with data from a cfquery . If you do not specify any cfgridcolumn entries, a default set of columns is generated. Each column in the query is included in the default column list. In addition, a default header for each column is created by re...
Page 103
Chapter 1: coldfusion tags 79 if the appendkey attribute is set to no, then no grid values are appended to the url. The value of selection is determined by the value of the selectmode attribute: • when selectmode="single", selection is the value of the column clicked. • when selectmode="row", select...
Page 104
80 cfml language reference query="getcourses" insert="yes" delete="yes" sort="yes" font="tahoma" bold="no" italic="no" appendkey="no" highlighthref="no" griddataalign="left" gridlines="yes" rowheaders="yes" rowheaderalign="left" rowheaderitalic="no" rowheaderbold="no" colheaders="yes" colheaderalign...
Page 105
Chapter 1: coldfusion tags 81 cfgridcolumn used with cfgrid in a cfform , you use cfgridcolumn to specify individual column data in a cfgrid control. Font and alignment attributes used in cfgridcolumn override any global font or alignment settings defined in cfgrid. Syntax header="header" width="col...
Page 106
82 cfml language reference bold optional. Yes or no. Yes presents text in the column in boldface. Default is no. Href optional. Url to associate with the grid item. You can specify a url that is relative to the current page: ../mypage.Cfm or an absolute url: http://myserver.Com/mydir/mypage.Cfm. Hre...
Page 107
Chapter 1: coldfusion tags 83 when type="numeric", data in the grid can be sorted by the end user as numeric data rather than as simple character text. When type="string_nocase", data in the grid can be sorted by the end user as case insensitive text data like an excel spreadsheet rather than as cas...
Page 108
84 cfml language reference example ... Query="getcourses" insert="yes" delete="yes" sort="yes" font="tahoma" bold="no" italic="no" appendkey="no" highlighthref="no" griddataalign="left" gridlines="yes" rowheaders="yes" rowheaderalign="left" rowheaderitalic="no" rowheaderbold="no" colheaders="yes" co...
Page 109
Chapter 1: coldfusion tags 85 headerbold="no" headeritalic="no"> headeralign="left" dataalign="left" font="times" bold="no" italic="no" select="yes" display="yes" headerbold="no" headeritalic="no"> headeralign="left" dataalign="left" bold="no" italic="no" select="yes" display="yes" headerbold="no" h...
Page 110
86 cfml language reference cfgridrow cfgridrow allows you to define a cfgrid that does not use a query as source for row data. If a query attribute is specified in cfgrid, the cfgridrow tags are ignored. Syntax data required. A comma-separated list of column values. If a column value contains a comm...
Page 111
Chapter 1: coldfusion tags 87 cfgridupdate used in a cfgrid , cfgridupdate allows you to perform updates to data sources directly from edited grid data. Cfgridupdate provides a direct interface with your data source. Cfgridupdate first applies delete row actions followed by insert row actions and fi...
Page 112
88 cfml language reference dbserver optional. For native database drivers and the sqloledb provider, specifies the name of the database server machine. If specified, dbserver overrides the server specified in the data source. Dbname optional. The database name (sybase system 11 driver and sqloledb p...
Page 113
Chapter 1: coldfusion tags 89 example ... Tablename="courselist" keyonly="yes"> ... Tablename="courselist" keyonly="yes"> ....
Page 114
90 cfml language reference cfheader cfheader generates custom http response headers to return to the client. Syntax name="header_name" value="header_value"> or statuscode="status_code" statustext="status_text"> name required if you do not specify the statuscode attribute. A name for the header. Valu...
Page 115
Chapter 1: coldfusion tags 91 cfhtmlhead cfhtmlhead writes the text specified in the text attribute to the of a generated html page. Cfhtmlhead can be useful for embedding javascript code, or placing other html tags such as meta, link, title, or base in an html page header. Syntax text the text you ...
Page 116
92 cfml language reference cfhttp the cfhttp tag allows you to execute post and get operations on files. Using cfhttp, you can execute standard get operations as well as create a query object from a text file. Post operations allow you to upload mime file types to a server, or post cookie, formfield...
Page 117
Chapter 1: coldfusion tags 93 password optional. When required by a server, a valid password. Name optional. The name to assign to a query when a query is to be constructed from a file. Columns optional. The column names for a query. If no column names are specified, the query returns all rows in th...
Page 118
94 cfml language reference • frame src • bgsound src • object data • object classid • object codebase • object usemap proxyserver optional. Host name or ip address of a proxy server. Proxyport optional. The port number on the proxy server from which the object is being requested. Default is 80. When...
Page 119
Chapter 1: coldfusion tags 95 if there is no timeout set on the url in the browser, no timeout set in the coldfusion administrator, and no timeout set with the timeout attribute, coldfusion processes requests synchronously; thus, coldfusion waits indefinitely for the cfhttp request to process. Note ...
Page 120
96 cfml language reference • encryption — cfhttp is capable of using secure sockets layer (ssl) for negotiating secured transactions over the wire. • cfhttp.Statuscode— cfhttp throws an error and provides the cfhttp.Statuscode variable for access to the http error string associated with the error if...
Page 121
Chapter 1: coldfusion tags 97 url = "http://www.Allaire.Com" resolveurl = 1 throwonerror = yes > url = "http://www.Allaire.Com" resolveurl = 1 throwonerror = yes > #cfhttp.Filecontent# #cfhttp.Mimetype# #cfhttp.Statuscode# #cfhttp.Header# #httpheader# : #value# #httpheader# : #value[counter]#.
Page 122
98 cfml language reference cfhttpparam required for cfhttp post operations, cfhttpparam is used to specify the parameters necessary to build a cfhttp post. Syntax type="type" value="transaction type" file="filename"> name required. A variable name for the data being passed. Type required. The transa...
Page 123
Chapter 1: coldfusion tags 99 form variable: ##form.Form_test## url variable: ##url.Url_test## cookie variable: ##cookie.Cookie_test## cgi variable: ##cgi.Cgi_test## ")#.
Page 124
100 cfml language reference cfif/cfelseif/cfelse used with cfelse and cfelseif, cfif lets you create simple and compound conditional statements in cfml. The value in the cfif tag can be any expression. Syntax html and cfml tags html and cfml tags html and cfml tags usage note that when testing for t...
Page 125
Chapter 1: coldfusion tags 101 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 ...
Page 126
102 cfml language reference cfimpersonate allows you to impersonate a user defined in a security context defined in advanced security. The coldfusion application server enforces all the privileges and restrictions that have been set up for that user with the advanced security rules. Syntax securityc...
Page 127
Chapter 1: coldfusion tags 103 engine enforces the rules and policies specified for the user in the advanced security section of the coldfusion administrator. Therefore, there is no need to make multiple isauthorized() calls in the code to protect each resource. Refer to administering coldfusion ser...
Page 128
104 cfml language reference cfinclude cfinclude lets you embed references to coldfusion pages in your cfml. If necessary, you can embed cfinclude tags recursively. For an additional method of encapsulating cfml, see the cfmodule tag, used to create custom tags in cfml. Syntax template a logical path...
Page 129
Chapter 1: coldfusion tags 105 cfindex use the cfindex tag to populate collections with indexed data. Cfindex and cfsearch encapsulate the verity indexing and searching utilities. Verity collections can be populated from either text files in a directory you specify, or from a query generated by any ...
Page 130
106 cfml language reference • file — indexes files. • path — indexes all files in specified path that pass extensions filter. • custom — indexes custom entities from a coldfusion query. Title required when type="custom". Specifies one of the following: • a title for the collection • a query column n...
Page 131
Chapter 1: coldfusion tags 107 extensions optional. Specifies the comma-separated list of file extensions that coldfusion uses to index files when type="path". Default is htm, html, cfm, cfml, dbm, dbml. An entry of "*." returns files with no extension: extensions=".Htm, .Html, .Cfm, .Cfml, *." retu...
Page 132
108 cfml language reference key="c:\inetpub\wwwroot\cfdocs\snippets" type="path" title="test" urlpath="http://127.0.0.1/cfdocs/snippets/" extensions=".Cfm" recurse="yes"> ... Key="c:\inetpub\wwwroot\cfdocs\snippets" type="path" title="test" urlpath="http://127.0.0.1/cfdocs/snippets/" extensions=".Cf...
Page 133
Chapter 1: coldfusion tags 109 cfinput cfinput is used inside cfform to place radio buttons, checkboxes, or text boxes. Provides input validation for the specified control type. Cfinput supports the javascript onclick event in the same manner as the html input tag: name="radio1" onclick="javascript_...
Page 134
110 cfml language reference • date — verifies us date entry in the form mm/dd/yyyy. • eurodate — verifies valid european date entry in the form dd/mm/yyyy. • time — verifies a time entry in the form hh:mm:ss. • float — verifies a floating point entry. • integer — verifies an integer entry. • telepho...
Page 135
Chapter 1: coldfusion tags 111 if you specify a value in quotation marks, you must escape the quotation marks by doubling them, for example, passthrough= "readonly= " "yes " " " example cfinput example phone number validation (enter a properly formatted phone number): number, formatted xxx-xxx-xxxx ...
Page 136
112 cfml language reference cfinsert cfinsert inserts new records in data sources. Syntax dbtype="type" dbserver="dbms" dbname="database name" tablename="tbl_name" tableowner="owner" tablequalifier="tbl_qualifier" username="username" password="password" provider="comprovider" providerdsn="datasource...
Page 137
Chapter 1: coldfusion tags 113 tablename required. Name of the table you want the form fields inserted in. Note the following: • oracle drivers — this specification must be in uppercase. • sybase driver — this specification is case-sensitive and must be in the same case as that used when the table w...
Page 138
114 cfml language reference select commentid, email, fromuser, subject, commttype, messtext, posted, processed from comments cfinsert example first, we’ll show a list of the available comments in the cfsnippets datasource. Next, we’ll offer the opportunity to enter your own comment: email: from: sub...
Page 139
Chapter 1: coldfusion tags 115 cfldap cfldap provides an interface to ldap (lightweight directory access protocol) directory servers like the netscape directory server. For complete examples of cfldap usage, refer to developing web applications with coldfusion. Syntax port="port_number" username="na...
Page 140
116 cfml language reference • modify — modifies ldap entries on an ldap server with the exception of the distinguished name ("dn") attribute. Requires dn, attributes. See the modifytype attribute for additional controls. • modifydn — modifies the distinguished name attribute for ldap entries on an l...
Page 141
Chapter 1: coldfusion tags 117 filterfile optional. Specifies the name of a filter file and the name of the stanza tag within that file that contains the ldap filter string specification. You can specify either an absolute path name or a simple file name to identify the file. If you use a simple fil...
Page 142
118 cfml language reference secure optional. Identifies the type of security to employ, cfssl_basic or cfssl_client_auth, and additional information that is required by the specified security type. Secure="cfssl_basic, certificate_db" or secure="cfssl_client_auth, certificate_db,certificate_name, ke...
Page 143
Chapter 1: coldfusion tags 119 the cfssl_basic type of security provides v2 ssl, and the cfssl_client_auth type of security provides v3 ssl. V2 ssl provides encryption and server authentication. V3 ssl adds to this certificate-based client authentication. Both forms of security encrypt the conversat...
Page 144
120 cfml language reference.
Page 145
Chapter 1: coldfusion tags 121 cflocation cflocation opens a specified coldfusion page or html file. For example, you might use cflocation to specify a standard message or response that you use in several different coldfusion applications. Use the addtoken attribute to verify client requests. Syntax...
Page 146
122 cfml language reference cflock the cflock tag provides two types of locks to ensure the integrity of shared data: • exclusive lock • read-only lock an exclusive lock single-threads access to the cfml constructs in its body. Single- threaded access implies that the body of the tag can be executed...
Page 147
Chapter 1: coldfusion tags 123 throwontimeout optional. Yes or no. Specifies how timeout conditions should be handled. If the value is yes an exception will be generated to provide notification of the timeout. If the value is no execution continues past the tag. Default is yes. Type optional. Readon...
Page 148
124 cfml language reference following table shows which features are available for server, application, and session scope. Each feature that you select has tradeoffs. • no automatic checking or locking. If you select this button, no reads or writes are locked or checked for correct protection. You s...
Page 149
Chapter 1: coldfusion tags 125 thus, all requests to the protected section of the page are blocked until there is a timeout. The following tables show two scenarios that cause deadlocks. The following deadlock scenario could take place if you tried to nest a write lock after a read lock, as in the f...
Page 150
126 cfml language reference 2. Lock the application scope. In the cflock tag, indicate scope by specifying "application" as the value of the scope attribute. 3. Lock the server scope. In the cflock tag, indicate the scope by specifying "server" as the value of the scope attribute. 4. Unlock the serv...
Page 151
Chapter 1: coldfusion tags 127 e-turtleneck is proud to say that we have sold #application.Number# turtlenecks to date. Cflock example thank you for shopping e-turtleneck. Today you have chosen a turtleneck in size #form.Size# and in the color #form.Color#..
Page 152
128 cfml language reference congratulations! You have just selected the longest wearing, most comfortable turtleneck in the world. Please indicate the color and size that you wish to buy. Red white blue turquoise black forest green xxsmall xsmall small medium large xlarge.
Page 153
Chapter 1: coldfusion tags 129 cfloop looping is a very powerful programming technique that lets you repeat a set of instructions or display output over and over until one or more conditions are met. Cfloop supports five different types of loops: • index loops • conditional loops • looping over a qu...
Page 154
130 cfml language reference from="1" to="5"> the loop index is #loopcount#. The result of this loop in a browser looks like this: the loop index is 1. The loop index is 2. The loop index is 3. The loop index is 4. The loop index is 5. In this example, the step value has a default value of 1. But you...
Page 155
Chapter 1: coldfusion tags 131 the loop index is #countvar#. The result of this loop in a browser would look something like: the loop index is 1. The loop index is 2. The loop index is 3. The loop index is 4. The loop index is 5. Looping over a query a loop over a query repeats for every record in t...
Page 156
132 cfml language reference the following example loops from the tenth through the twentieth record returned by "myquery ": startrow="#start#" endrow="#end#"> #myquery.Mycolname# startrow="#start#" endrow="#end#"> #myquery.Mycolname# the loop is done when there are no more records or when the curren...
Page 157
Chapter 1: coldfusion tags 133 delimiters optional. Specifies the delimiter characters used to separate items in the list. Example this loop will display the names of each of the beatles: list="john,paul,george,ringo"> #listelement# list="john,paul,george,ringo"> #listelement# although cfloop expect...
Page 158
134 cfml language reference examples this example employs a com object to output a list of files. In this example, ffunc is a collection of file2 objects. Name=ffunc action=create> #file2.Name# this example loops through a structure (used as an associative array): ... Employee dept. #person# #struct...
Page 159
Chapter 1: coldfusion tags 135 cfmail cfmail allows you to send email messages via an smtp server. See also cfmailparam . Syntax from="sender" cc="copy_to" bcc="blind_copy_to" subject="msg_subject" type="msg_type" maxrows="max_msgs" mimeattach="path" query="query_name" group="query_column" groupcase...
Page 160
136 cfml language reference type optional. Specifies extended type attributes for the message. Currently, the only valid value for this attribute is "html". Specifying type= "html" informs the receiving email client that the message has embedded html tags that need to be processed. This is only usef...
Page 161
Chapter 1: coldfusion tags 137 timeout optional. The number of seconds to wait before timing out the connection to the smtp server. Example this view-only example shows the use of cfmail. If your cfas mail settings are configured successfully and the comments are removed, you will be able to use thi...
Page 162
138 cfml language reference cfmailparam cfmailparam can either attach a file or add a header to a message. If you use cfmailparam, it is nested within a cfmail tag. You can use more than one cfmailparam tags within a cfmail tag in order to attach one or more files and headers. See also cfmail . Synt...
Page 163
Chapter 1: coldfusion tags 139 important attachments and reply"> please read the text file and view the new logo, and let us know what you think..
Page 164
140 cfml language reference cfmodule use cfmodule to invoke a custom tag for use in your coldfusion application pages. Cfmodule can help deal with any custom tag name conflicts that might arise. Use the template attribute to name a coldfusion page containing the custom tag definition, including its ...
Page 165
Chapter 1: coldfusion tags 141 likewise, 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 the attributes are grouped into a structure by the custom tag’s caller. Example t...
Page 166
142 cfml language reference attributecollection=##attrcollection1## y=4>")# the result: #result# name="mytag" x="3" attributecollection=#attrcollection1# y="4"> here is another way to invoke the custom tag, using the name attribute. Name="mytag" x="3" attributecollection=#attrcollection1# y="4"> her...
Page 167
Chapter 1: coldfusion tags 143 cfobject the cfobject tag allows you to call methods in com, corba, and java objects. Note coldfusion administrators can disable the cfobject tag in the coldfusion administrator basic security page. On unix, com objects are not currently supported by cfobject. Cfobject...
Page 168: Cfobject Type="com"
144 cfml language reference cfobject type="com" cfobject allows you to create and use com (component object model) objects. Any automation server object type that is currently registered on a machine can be invoked. You can use a utility like microsoft’s oleview to browse com objects. Oleview, as we...
Page 169
Chapter 1: coldfusion tags 145 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 collection:.
Page 170: Cfobject Type="corba"
146 cfml language reference last name: #file2.Lastname# ... Cfobject type="corba" cfobject allows you to call methods in corba objects. These corba objects must already have been defined and registered for use. Syntax context="context" class="file or naming service" name="text" locale="type-value ar...
Page 171: Cfobject Type="java"
Chapter 1: coldfusion tags 147 note that each type-value pair has to start with a leading "-". Usage coldfusion enterprise version 4.0 and above supports corba through the dynamic invocation interface (dii). To use cfobject with corba objects, you need to know either the name of the file containing ...
Page 172
148 cfml language reference 1. Call cfobject to load the class. See example. 2. Use the init method with appropriate arguments to call a constructor explicitly. For example: calling a public method on the object without first calling the "init" method results in an implicit call to the default const...
Page 173
Chapter 1: coldfusion tags 149 cfoutput displays the results of a database query or other operation. If you need to nest cfoutput tags, please read the "usage" section. Syntax query="query_name" group="query_column" groupcasesensitive="yes/no" startrow="start_row" maxrows="max_rows_output"> query="q...
Page 174
150 cfml language reference example select dept_id, corname, corlevel from courselist order by dept_id, corlevel, corname cfoutput simply 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...
Page 175
Chapter 1: coldfusion tags 151 cfparam cfparam is used to test for a parameter’s existence, and optionally test its data type, and provide a default value if one is not assigned. Syntax type="data_type"> default="value"> name the name of the parameter you are testing (such as "client.Email " or "coo...
Page 176
152 cfml language reference usage there are three ways to use cfparam: • test for a required variable — use cfparam with only the name attribute to test that a required variable exists. If the variable does not exist, coldfusion server stops processing the page and returns an error. • test for a req...
Page 177
Chapter 1: coldfusion tags 153 type in a new value for tempvar, and hit submit:.
Page 178
154 cfml language reference cfpop cfpop retrieves and deletes email messages from a pop mail server. See also cfmail . Syntax port="port_number" username="username" password="password" action="action" name="queryname" messagenumber="number" attachmentpath="path" timeout="seconds" maxrows="number" st...
Page 179
Chapter 1: coldfusion tags 155 name optional. The name you assign to the index query. Required for action="getheaderonly" and action="getall". Messagenumber optional. Specifies the message number(s) for the given action. Messagenumber is required for action="delete". If it is provided for action="ge...
Page 180
156 cfml language reference message header and body columns the following table lists the message header and body columns that are returned by cfpop when you specify the action attribute to be either getheaderonly or getall. All of the columns are returned if you specify getall, but only header info...
Page 181
Chapter 1: coldfusion tags 157 usage 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 to determine what to do. See also the description of the setlocale function. For complete usage informati...
Page 182
158 cfml language reference enter your mail server: enter your username: enter your password: --->.
Page 183
Chapter 1: coldfusion tags 159 cfprocessingdirective suppresses extraneous white space, and other output, produced by the cfml within the tag’s scope. Syntax suppresswhitespace="yes" or "no"> … any cfml tags here … suppresswhitespace="yes" or "no"> … any cfml tags here … suppresswhitespace required....
Page 184
160 cfml language reference cfprocparam the cfprocparam tag is nested within a cfstoredproc tag. You use it to specify parameter information, including type, name, value, and length. Syntax variable="variable name" dbvarname="db variable name" value="parameter value" cfsqltype="parameter datatype" m...
Page 185
Chapter 1: coldfusion tags 161 maxlength optional. Maximum length of the parameter. Scale optional. Number of decimal places of the parameter. Null optional. Specify yes or no. Indicates whether the parameter is passed as a null. If you specify yes, the tag ignores the value attribute. Usage use thi...
Page 186
162 cfml language reference #name#,#date_col# record count: #rs1.Recordcount# >p>columns: #rs1.Columnlist# #col1#,#col2#,#col3# record count: #rs3.Recordcount# columns: #rs3.Columnlist# the return code for the stored procedure is: ’#cfstoredproc.Statuscode#’ ....
Page 187
Chapter 1: coldfusion tags 163 cfprocresult the cfprocresult tag is nested within a cfstoredproc tag. This tag’s name parameter specifies a result set name that other coldfusion tags, such as cfoutput and cftable, use to access the result set. It also allows you to optionally identify which of the s...
Page 188
164 cfml language reference the output param value: ’#foo#’ #name#,#date_col# record count: #rs1.Recordcount# >p>columns: #rs1.Columnlist# #col1#,#col2#,#col3# record count: #rs3.Recordcount# columns: #rs3.Columnlist# the return code for the stored procedure is: ’#cfstoredproc.Statuscode#’ ....
Page 189
Chapter 1: coldfusion tags 165 cfquery cfquery passes sql statements for any purpose to your data source. Not limited to queries. Syntax datasource="ds_name" dbtype="type" dbserver="dbms" dbname="database name" username="username" password="password" maxrows="number" blockfactor="blocksize" timeout=...
Page 190
166 cfml language reference • db2 —db2 5.2 native database driver. • informix73 —informix73 native database driver. Dbserver optional. For native database drivers and the sqloledb provider, specifies the name of the database server machine. If specified, dbserver overrides the server specified in th...
Page 191
Chapter 1: coldfusion tags 167 when specifying a date value as a string, make sure it is enclosed in quotes. Cachedwithin optional. Enter a timespan using the coldfusion createtimespan function. Cached query data will be used if the original query date falls within the time span you define. The crea...
Page 192
168 cfml language reference example select parkname, region, state from parks order by parkname, state park name region state #getparks.Currentrow# #parkname# #region# #state#.
Page 193
Chapter 1: coldfusion tags 169 maxrows)#">see next #maxrows# rows.
Page 194
170 cfml language reference cfqueryparam cfqueryparam checks the data type of a query parameter. The cfqueryparam tag is nested within a cfquery tag. More specifically, it is embedded within the query sql statement. If you specify its optional parameters, cfqueryparam also performs data validation. ...
Page 195
Chapter 1: coldfusion tags 171 maxlength optional. Maximum length of the parameter. The default value is the length of the string specified in the value attribute. Scale optional. Number of decimal places of the parameter. The default value is zero. Applicable for cf_sql_numeric and cf_sql_decimal. ...
Page 196
172 cfml language reference for a sybase11 data source, the syntax of the sql statement is as follows: select * from courses where col1=10 example select * from courses where course_id= cfsqltype="cf_sql_integer"> course number: #number# description: #descript# cfsqltype="cf_sql_integer"> course num...
Page 197
Chapter 1: coldfusion tags 173 the cfqueryparam tag returns the following error message when this example is executed. Value invalid data ’12; delete courses where course_id=20’ for cfsqltype ’cf_sql_integer’. Note that for string input you must specify the maxlength attribute for validation. ------...
Page 198
174 cfml language reference cfregistry the cfregistry tag reads, writes, and deletes keys and values in the system registry. Cfregistry is supported on all platforms, including solaris and hp-ux. Note the coldfusion server basic security settings may prevent cfregistry from executing. These settings...
Page 199: Cfregistry Action="getall"
Chapter 1: coldfusion tags 175 sections that follow describe these values and attributes in greater detail. Cfregistry action="getall" use cfregistry with the getall action to return all registry keys and values defined in a branch. You can access these values as you would any record set. Syntax bra...
Page 200: Cfregistry Action="get"
176 cfml language reference example branch="hkey_local_machine\software\microsoft\java vm" type="any" name="regquery"> cfregistry action="getall" branch="hkey_local_machine\software\microsoft\java vm" type="any" name="regquery"> entry" width="35" text="#regquery.Entry#"> type" width="10" text="#regq...
Page 201: Cfregistry Action="set"
Chapter 1: coldfusion tags 177 variable required. Variable into which cfregistry places the value. Usage cfregistry does not create the variable if the value does not exist. Example branch="hkey_local_machine\software\microsoft\java vm" entry="classpath" type="string" variable="regvalue"> cfregistry...
Page 202: Cfregistry Action="delete"
178 cfml language reference value optional. The value data to be set. If you omit this attribute, cfregistry creates default value data, as follows: • string — default value is an empty string: "" • dword — default value is 0 (zero) usage cfregistry creates the key or value if it does not exist. Exa...
Page 203
Chapter 1: coldfusion tags 179 usage if you delete a key, cfregistry also deletes values and subkeys defined beneath the key. Example branch="hkey_local_machine\software\cflangref\tempkey" entry="lastcfm01"> cfregistry action="delete" branch="hkey_local_machine\software\cflangref\tempkey" entry="las...
Page 204
180 cfml language reference cfreport cfreport runs a predefined crystal reports report. Syntax orderby="result_order" username="username" password="password" formula="formula"> orderby="result_order" username="username" password="password" formula="formula"> report required. Specifies the path of th...
Page 205
Chapter 1: coldfusion tags 181 the cfreport tag requires the name of the report to run; cfreport can also pass information to the report file being displayed to change the output conditions. This example would run a report called “monthlysales.Rpt " and pass it an optional filter condition to show o...
Page 206
182 cfml language reference cfrethrow rethrows the currently active exception. Preserves the exception’s cfcatch.Type and cfcatch.Tagcontext information. See also cftry/cfcatch . Syntax usage use the tag within a block. This tag is useful in error handling code when the error handler is not able to ...
Page 207
Chapter 1: coldfusion tags 183.
Page 208
184 cfml language reference cfscript the cfscript tag encloses a code segment containing cfscript. Syntax cfscript code goes here usage use cfscript to perform processing in cfscript instead of cfml. Note the following regarding cfscript: • cfscript uses coldfusion functions, expressions, and operat...
Page 209
Chapter 1: coldfusion tags 185 cfsearch use the cfsearch tag to execute searches against data indexed in verity collections. Collections can be created by calling the cfcollection tag, by using the coldfusion administrator, or through native verity indexing tools. Collections are populated with data...
Page 210
186 cfml language reference startrow optional. Specifies the first row number to be retrieved. Default is 1. External optional. Yes or no. Yes indicates that the collection you are searching was created outside of coldfusion using native verity indexing tools. The default is no. Language optional. T...
Page 211
Chapter 1: coldfusion tags 187 • summary — returns the contents of the automatic summary generated by cfindex. The default summarization selects the best three matching sentences, up to a maximum of 500 characters. • recordcount — returns the number of records returned in the record set. • currentro...
Page 212
188 cfml language reference #searchsnippets.Recordcount# "hit s" found out of #searchsnippets.Recordssearched# total record s searched. #form.Maxrows# records returned ... Startrow="1" colheaders htmltable> text="#title#"> startrow="1" colheaders htmltable> text="#title#"> text="#title#"> ....
Page 213
Chapter 1: coldfusion tags 189 cfselect used inside cfform , cfselect allows you to construct a drop-down list box form control. You can populate the drop-down list box from a query, or using the option tag. Use option elements to populate lists. Syntax for the option tag is the same as for its html...
Page 214
190 cfml language reference value optional. The query column value for the list element. Used with the query attribute. Display optional. The query column displayed. Defaults to the value of value. Used with the query attribute. Passthrough optional. Html attributes that are not explicitly supported...
Page 215
Chapter 1: coldfusion tags 191 cfselect example this employee" 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 ....
Page 216
192 cfml language reference cfservlet executes a java servlet on a jrun engine. This tag is used in conjunction with the cfservletparam tag, which passes data to the servlet. Syntax code="class name of servlet" jrunproxy="proxy server" timeout="timeout in seconds" writeoutput="yes/no" debug="yes/no"...
Page 217
Chapter 1: coldfusion tags 193 usage the syntax of the cfservlet tag is designed to be consistent with the html markup and used by some web servers to invoke java servlets from .Shtml pages in what is known as ssi, server-side includes. Note the servlet must exist somewhere in the class path of the ...
Page 218
194 cfml language reference cfservletparam the cfservletparam is a child of cfservlet. It is used to pass data to the servlet. Each cfservletparam tag within the cfservlet block passes a separate piece of data to the servlet. See also cfservlet . Syntax ...> name=”servlet parameter name” value=”serv...
Page 219
Chapter 1: coldfusion tags 195 the first passes name-value pairs by value. This method uses the attributes name and value to pass a simple name-value string pair to the servlet. The name attribute represents the name of the servlet parameter from which the string specified in the value attribute can...
Page 220
196 cfml language reference example code=”myservletname” jrunproxy=”236.3.3.4:8083” timeout=”300” writeoutput=”yes” debug="yes"> code=”myservletname” jrunproxy=”236.3.3.4:8083” timeout=”300” writeoutput=”yes” debug="yes">.
Page 221
Chapter 1: coldfusion tags 197 cfset use the cfset tag to define a coldfusion variable. If the variable already exists, cfset resets it to the specified value. Syntax arrays the following example assigns a new array to the variable "months". This example creates a variable "array_length" that resolv...
Page 222
198 cfml language reference example select * from messages cfset example cfset allows you to set and reassign values to local or global variables within a cf template. For example, the variable numrecords has been declared on this template to hold the amount of records returned from our query (#numr...
Page 223
Chapter 1: coldfusion tags 199 cfsetting cfsetting is used to control various aspects of page processing, such as controlling the output of html code in your pages. One benefit of this option is managing whitespace that can occur in output pages that are served by coldfusion. Syntax showdebugoutput=...
Page 224
200 cfml language reference text within cfoutput is always shown.
Page 225
Chapter 1: coldfusion tags 201 cfsilent cfsilent suppresses all output that is produced by the cfml within the tag’s scope. See also cfsetting . Syntax example #c# ... Even information within cfoutput tags does not appear within the cfsilent block. B-c = #c#.
Page 226
202 cfml language reference cfslider used inside cfform , cfslider allows you to place a slider control in a coldfusion form. A slider control is like a sliding volume control. The slider groove is the area over which the slider moves. Note cfslider incorporates a java applet, so a browser must be j...
Page 227
Chapter 1: coldfusion tags 203 imgstyle optional. Style of the image to appear in the slider groove. Valid entries are: • centered • tiled • scaled default is scaled. Range optional. Determines the values of the left and right slider range. The slider value appears as the slider is moved. Separate v...
Page 228
204 cfml language reference align optional. Alignment value. Valid entries are: • top • left • bottom • baseline • texttop • absbottom • middle • absmiddle • right groovecolor optional. Color value of the slider groove. The slider groove is the area in which the slider box moves. Valid entries are: ...
Page 229
Chapter 1: coldfusion tags 205 fontsize optional. Font size for label text measured in points. Italic optional. Enter yes for italicized label text, no for normal text. Default is no. Bold optional. Enter yes for bold label text, no for medium text. Default is no. Notsupported optional. The text you...
Page 230
206 cfml language reference message="slide the bar to get a value between 1 and 100" height="20" width="150" font="verdana" bgcolor="silver" groovecolor="lime" bold="no" italic="yes" refreshlabel="yes"> 100
Page 231
Chapter 1: coldfusion tags 207 cfstoredproc the cfstoredproc tag is the main tag used for executing stored procedures via an odbc or native connection to a server database. It specifies database connection information and identifies the stored procedure. Syntax datasource="ds_name" username="usernam...
Page 232
208 cfml language reference providerdsn optional. Data source name for the com provider (ole-db only). Debug optional. Yes or no. Specifies whether debug info will be listed on each statement. Default is no. Returncode optional. Yes or no. Specifies whether the tag populates cfstoredproc.Statuscode ...
Page 233
Chapter 1: coldfusion tags 209 the output param value: ’#foo#’ #name#,#date_col# record count: #rs1.Recordcount# >p>columns: #rs1.Columnlist# #col1#,#col2#,#col3# record count: #rs3.Recordcount# columns: #rs3.Columnlist# the return code for the stored procedure is: ’#cfstoredproc.Statuscode#’ ....
Page 234
210 cfml language reference cfswitch/cfcase/cfdefaultcase used with cfcase and cfdefaultcase, the cfswitch tag 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 mat...
Page 235
Chapter 1: coldfusion tags 211 example select emp_id, firstname, lastname, email, phone, department from employees cfswitch example #firstname# #lastname# is in sales #firstname# #lastname# is in accounting #firstname# #lastname# is in administration #firstname# #lastname# is not in sales, accountin...
Page 236
212 cfml language reference cftable builds a table in your coldfusion page. Use the cfcol tag to define column and row characteristics for a table. Cftable renders data either as preformatted text, or, with the htmltable attribute, as an html table. Use cftable to create tables if you don’t want to ...
Page 237
Chapter 1: coldfusion tags 213 usage you can use the cfcol tag to align the data in the table , specify the width of each column, and provide column headers. Note cfcol is the only tag that you can nest within cftable. Example select emp_id, firstname, lastname, email, phone, department from employe...
Page 238
214 cfml language reference cftextinput the cftextinput form custom control allows you to place a single-line text entry box in a cfform . In addition to input validation, the tag gives you control over all font characteristics. Note cftextinput incorporates a java applet, so a browser must be java-...
Page 239
Chapter 1: coldfusion tags 215 • time — verifies a time entry in the form hh:mm:ss. • float — verifies a floating point entry. • integer — verifies an integer entry. • telephone — verifies a telephone entry. Telephone data must be entered as ###- ###-####. The hyphen separator (-) can be replaced wi...
Page 240
216 cfml language reference width optional. Width value of the control, in pixels. Vspace optional. Vertical spacing of the control, in pixels. Hspace optional. Horizontal spacing of the control, in pixels. Align optional. Alignment value. Valid entries are: • top • left • bottom • baseline • textto...
Page 241
Chapter 1: coldfusion tags 217 maxlength optional. The maximum length of text entered. Notsupported optional. The text you want to display if the page containing a java applet-based cfform control is opened by a browser that does not support java or has java support disabled. For example: notsupport...
Page 242
218 cfml language reference cfthrow the cfthrow tag raises a developer-specified exception that can be caught with cfcatch tag having any of the following type specifications: • cfcatch type= "custom_type " • cfcatch type= "application " • cfcatch type= "any " syntax type= "exception_type " message=...
Page 243
Chapter 1: coldfusion tags 219 note in order to see the information displayed by tagcontext, use the coldfusion administrator to enable the cfml stack trace.Under debugging in the coldfusion administrator, choose the checkbox next to "enable cfml stack trace. " example cfthrow example #cfcatch.Messa...
Page 244
220 cfml language reference cftransaction use cftransaction to group multiple queries into a single unit. Cftransaction also provides commit and rollback processing. See usage for details. Syntax action="begin" or "commit" or "rollback" isolation="read_uncommitted" or "read_committed" or "repeatable...
Page 245
Chapter 1: coldfusion tags 221 example cftransaction can be used to group multiple queries using cfquery into a single business event. Changes to data requested by these queries can be committed on the basis of the success or failure of the query by using the actions commit and rollback, respectivel...
Page 246
222 cfml language reference corname, corlevel, lastupdate) values (’#mynumber#’, ’#mydescription#’, ’#mydepartment#’, ’#mydescription#’, ’#mycorlevel#’, #now()#).
Page 247
Chapter 1: coldfusion tags 223 cftree the cftree form custom control allows you to place a tree control in a cfform . User selections can be validated. Individual tree items are created with cftreeitem tags inside the cftree tag block. Note cftree incorporates a java applet, so a browser must be jav...
Page 248
224 cfml language reference appendkey optional. Yes or no. When used with href, yes passes the cftreeitemkey variable along with the value of the selected tree item in the url to the application page specified in the cfform action attribute. The default is yes. Highlighthref optional. Yes highlights...
Page 249
Chapter 1: coldfusion tags 225 • left • bottom • baseline • texttop • absbottom • middle • absmiddle • right border optional. Places a border around the tree. Default is yes. Hscroll optional. Permits horizontal scrolling. Default is yes. Vscroll optional. Permits vertical scrolling. Default is yes....
Page 250
226 cfml language reference cftree example this employee" 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 cftreeitem is use...
Page 251
Chapter 1: coldfusion tags 227 expand="no" queryasroot="no"> queryasroot="no" expand="no"> queryasroot="no"> ... Queryasroot="no" expand="no"> queryasroot="no"> ... Queryasroot="no"> ....
Page 252
228 cfml language reference cftreeitem use cftreeitem to populate a tree control created with cftree with individual elements. You can use the img values supplied with coldfusion or reference your own icons. Note cftreeitem incorporates a java applet, so a browser must be java- enabled for cftree to...
Page 253
Chapter 1: coldfusion tags 229 • folder • floppy • fixed • remote use commas to separate image names corresponding to tree level, for example: img="folder,document" img=",document to specify your own custom image, specify the path and file extension: img="../images/page1.Gif" imgopen optional. Icon ...
Page 254
230 cfml language reference select emp_id, firstname, lastname, email, phone, department from employees where lastname = ’#employeenames#’ cftree example this employee" to see expanded information. Size="#getemployees.Recordcount#" query="getemployees" value="lastname" required="no"> select all size...
Page 255
Chapter 1: coldfusion tags 231 parent="#emp_id#" queryasroot="no" expand="no"> parent="#lastname#" expand="no" queryasroot="no"> parent="#emp_id#" queryasroot="no" expand="no"> expand="no" queryasroot="no"> parent="#emp_id#" queryasroot="no" expand="no"> expand="no" queryasroot="no"> parent="#emp_id...
Page 256
232 cfml language reference cftry/cfcatch used with one or more cfcatch tags, the cftry tag allows developers to catch and process exceptions in coldfusion pages. Exceptions include any event that disrupts the normal flow of instructions in a coldfusion page such as failed database operations, missi...
Page 257
Chapter 1: coldfusion tags 233 • type="any". The custom_type type designates the name of a user-defined type specified with a cfthrow tag. Cfcatch has a catch handler that can catch a custom type by pattern, providing the custom type is defined as a series of strings concatenated together by periods...
Page 258
234 cfml language reference failing database operations. If no sqlstate value was provided, the value of sqlstate is -1. • errnumber — type=expression only. Internal expression error number. • missingfilename — type=missinginclude only. Name of the file that could not be included. • lockname — type=...
Page 259
Chapter 1: coldfusion tags 235 #cfcatch.Message# caught an exception, type = #cfcatch.Type# the contents of the tag stack are: #i# #scurrent["id"]# (#scurrent["line"]#,#scurrent["column"]#) #scurrent["template"]#.
Page 260
236 cfml language reference cfupdate the cfupdate tag updates existing records in data sources. Syntax dbtype="type" dbserver="dbms" dbname="database name" tablename="table_name" tableowner="name" tablequalifier="qualifier" username="username" password="password" provider="comprovider" providerdsn="...
Page 261
Chapter 1: coldfusion tags 237 tablename required. Name of the table you want to update. Note the following: • oracle drivers — this specification must be in uppercase. • sybase driver — this specification is case-sensitive and must be in the same case as that used when the table was created tableow...
Page 262
238 cfml language reference ---> select number, course_id, descript from courses where course_id = #url.Course_id# order by number record, and then click "submit" to use cfupdate and alter the database course number value="#getcourseinfo.Number#"> course description #getcourseinfo.Descript# value="#...
Page 263
Chapter 1: coldfusion tags 239 cfwddx the cfwddx tag serializes and de-serializes cfml data structures to the xml-based wddx format. You can also use it to generate javascript statements instantiating javascript objects equivalent to the contents of a wddx packet or some cfml data structures. Syntax...
Page 264
240 cfml language reference for complete information on wddx, see the "programming with xml " chapter in developing web applications with coldfusion. Example select message_id, thread_id, username from messages the recordset data is:... #message_id# #thread_id# #username# serializing cfml data... Re...
Page 265: Coldfusion Functions
C h a p t e r 2 chapter 2 coldfusion functions this chapter describes each of the functions in the coldfusion markup language (cfml). The introduction contains an alphabetical summary of coldfusion functions, a list of new functions in coldfusion 4.5, and a list of functions by category. The remaind...
Page 266
242 cfml language reference alphabetical list of coldfusion functions abs bitmaskread datepart getbasetaglist acos bitmaskset day getbasetemplatepath arrayappend bitnot dayofweek getclientvariableslist arrayavg bitor dayofweekasstring getcurrenttemplatepath arrayclear bitshln dayofyear getdirectoryf...
Page 267
Chapter 2: coldfusion functions 243 isauthorized listlen minute rereplacenocase isbinary listprepend month reverse isboolean listqualify monthasstring right isdate listrest now rjustify isdebugmode listsetat numberformat round isdefined listsort numberformat rtrim isleapyear listtoarray paragraphfor...
Page 268
244 cfml language reference tan tostring urlencodedformat writeoutput timeformat trim val xmlformat tobase64 ucase valuelist year tobinary urldecode week yesnoformat.
Page 269: Array Functions
Chapter 2: coldfusion functions 245 new functions in coldfusion 4.5 array functions authentication functions createobject tobase64 getfunctionlist tobinary getmetricdata tostring isbinary urldecode jsstringformat xmlformat arrayappend arraymax arraysum arrayavg arraymin arrayswap arrayclear arraynew...
Page 270: Date and Time Functions
246 cfml language reference date and time functions decision functions createdate datepart isleapyear createdatetime day isnumericdate createodbcdate dayofweek minute createodbcdatetime dayofweekasstring month createodbctime dayofyear monthasstring createtime daysinmonth now createtimespan daysinyea...
Page 271: Dynamic Evaluation Functions
Chapter 2: coldfusion functions 247 display and formatting functions dynamic evaluation functions international functions dateformat lseurocurrencyformat decimalformat lsnumberformat dollarformat lstimeformat formatbasen numberformat htmlcodeformat paragraphformat htmleditformat timeformat lscurrenc...
Page 272: List Functions
248 cfml language reference list functions mathematical functions arraytolist listlast listappend listlen listchangedelims listprepend listcontains listqualify listcontainsnocase listrest listdeleteat listsetat listfind listsort listfindnocase listtoarray listfirst listvaluecount listgetat listvalue...
Page 273: Query Functions
Chapter 2: coldfusion functions 249 query functions string functions isquery querysetcell queryaddcolumn quotedvaluelist queryaddrow valuelist querynew asc ljustify replace chr listvaluecount replacelist cjustify listvaluecountnocase replacenocase compare lsparsecurrency rereplace comparenocase lspa...
Page 274: Structure Functions
250 cfml language reference structure functions system functions other functions isstruct structisempty structclear structkeyarray structcopy structkeyexists structcount structkeylist structdelete structnew structfind structupdate structinsert directoryexists getfilefrompath expandpath getmetricdata...
Page 275
Chapter 2: coldfusion functions 251 abs returns the absolute value of a number. The absolute value of a number is the number without its sign. See also sgn . Syntax abs( number ) number any number. Examples abs example the absolute value of the following numbers: 1,3,-4,-3.2,6 is #abs(1)#,#abs(3)#,#...
Page 276
252 cfml language reference acos returns the arccosine of a number in radians. The arccosine is the angle whose cosine is number. See also cos , sin , asin , tan, and pi . Syntax acos( number ) number cosine of the angle that is to be calculated. This value must be between -1 and 1, inclusive. Usage...
Page 277
Chapter 2: coldfusion functions 253 type in a number to get its arccosine in radians and degrees..
Page 278
254 cfml language reference arrayappend appends an array index to the end of the specified array. Returns a boolean true on successful completion. See also arrayprepend . Syntax arrayappend( array , value ) array name of the array to which you want to append an index. Value the value you want to pla...
Page 279
Chapter 2: coldfusion functions 255 arrayavg returns the average of the values in the specified array. Syntax arrayavg( array ) array name of the array containing values you want to average. Example this example uses arrayavg to find the average of the numbers that you enter into an array. If you wo...
Page 280
256 cfml language reference the average of the numbers that you entered is #arrayavg(mynumberarray)#. Try again. You must enter at least two numeric values..
Page 281
Chapter 2: coldfusion functions 257 arrayclear deletes all data in the specified array. Returns a boolean true on successful completion. See also arraydeleteat . Syntax arrayclear( array ) array name of the array in which you want to delete data. Example your array contents are: #arraytolist(myarray...
Page 282
258 cfml language reference arraydeleteat deletes data from the specified array at the specified index position. Note that when an array index is deleted, index positions in the array are recalculated. For example, in an array containing the months of the year, deleting index position [5] removes th...
Page 283
Chapter 2: coldfusion functions 259 arrayinsertat inserts data in the specified array at the specified index position. All array elements with indexes greater than the new position are shifted right by one. The length of the array increases by one index. Returns a boolean true on successful completi...
Page 284
260 cfml language reference arrayisempty determines whether the specified array is empty of data. Returns a boolean true if specified array is empty, false if not empty. See also arraylen . Syntax arrayisempty( array ) array name of the array you want to check for data. Example your array contents a...
Page 285
Chapter 2: coldfusion functions 261 arraylen returns the length of the specified array. See also arrayisempty . Syntax arraylen( array ) array name of the array whose length you want to return. Example select firstname, lastname from employees the contents of the array are as follows: #mylist# this ...
Page 286
262 cfml language reference arraymax returns the largest numeric value in the specified array. Syntax arraymax( array ) array name of the array from which you want to return the largest numeric value. Example this example uses arraymax to find the largest number that you have entered into an array. ...
Page 287
Chapter 2: coldfusion functions 263.
Page 288
264 cfml language reference arraymin returns the smallest numeric value in the specified array. Syntax arraymin( array ) array name of the array from which you want to return the smallest numeric value. Example this example uses arraymin to find the smallest number that you have entered into an arra...
Page 289
Chapter 2: coldfusion functions 265.
Page 290
266 cfml language reference arraynew creates an array of between 1 and 3 dimensions. Array elements are indexed with square brackets: [ ]. Note that coldfusion arrays expand dynamically as data is added. Syntax arraynew( dimension ) dimension an integer value between 1 and 3. Examples is this an arr...
Page 291
Chapter 2: coldfusion functions 267 arrayprepend adds an array element to the beginning of the specified array. Returns a boolean true on successful completion. See also arrayappend . Syntax arrayprepend( array , value ) array name of the array to which you want to prepend data. Value the value you ...
Page 292
268 cfml language reference arrayresize resets an array to a specified minimum number of elements. Arrayresize can provide some performance gains if used to size an array to its expected maximum. Use arrayresize immediately after creating an array with arraynew for arrays greater than 500 elements. ...
Page 293
Chapter 2: coldfusion functions 269 arrayset in a one-dimensional array, sets the elements in a specified range to the specified value. Useful in initializing an array after a call to arraynew. Returns a boolean true on successful completion. See also arraynew . Syntax arrayset( array , start_pos , ...
Page 294
270 cfml language reference arraysort returns the specified array with elements numerically or alphanumerically sorted. Syntax arraysort( array , sort_type [, sort_order ]) array name of the array you want to sort. Sort_type the type of sort to execute. Sort type can be: • numeric — sorts numericall...
Page 295
Chapter 2: coldfusion functions 271 arraysum returns the sum of values in the specified array. Syntax arraysum( array ) array name of the array containing values you want to add together. Example this example uses arraysum to add two numbers together. The sum of the numbers is #arraysum(mynumberarra...
Page 296
272 cfml language reference.
Page 297
Chapter 2: coldfusion functions 273 arrayswap swaps array values for the specified array at the specified positions. Arrayswap can be used with greater efficiency than multiple cfsets. Returns a boolean true on successful completion. Syntax arrayswap( array , position1 , position2 ) array name of th...
Page 298
274 cfml language reference arraytolist converts the specified one dimensional array to a list, delimited with the character you specify. Syntax arraytolist( array [, delimiter ]) array name of the array containing elements you want to use to build a list. Delimiter specify the character(s) you want...
Page 299
Chapter 2: coldfusion functions 275 asc returns the ascii value (character code) of the first character of a string. Returns 0 if stringis empty. See also chr . Syntax asc( string ) string any string. Examples asc example #left(form.Charvals,1)# = #asc(form.Charvals)# type in a character to see its ...
Page 300
276 cfml language reference asin returns the arcsine of a number in radians. The arcsine is the angle whose sine is number. See also sin , cos , pi, and tan . Syntax asin( number ) number sine of the angle that is to be calculated. This value must be between 1 and -1. Usage the range of the result i...
Page 301
Chapter 2: coldfusion functions 277 degrees and radians. This value must be between 1 and -1, inclusive. Type in a number to get its arcsine in radians and degrees..
Page 302
278 cfml language reference atn returns the arctangent of a number. The arctangent is the angle whose tangent is number. See also tan , sin , cos, and pi . Syntax atn( number ) number tangent of the angle you want. Usage the range of the result is - π /2 to π /2 radians. To convert degrees to radian...
Page 303
Chapter 2: coldfusion functions 279 authenticatedcontext returns the name of the security context. See also isauthenticated, authenticateduser, isauthorized, and cfauthenticate . Syntax authenticatedcontext() examples authenticatedcontext example secure context is: authenticatedcontext() . . ..
Page 304
280 cfml language reference authenticateduser returns the name of the authenticated user. See also isauthenticated , authenticatedcontext , and cfauthenticate . Syntax authenticateduser() examples authenticateduser example authenticated user: authenticateduser() . . ..
Page 305
Chapter 2: coldfusion functions 281 bitand returns the bitwise and of two long integers. See also bitnot , bitor, and bitxor . Syntax bitand( number1 , number2 ) number1, number2 any long integers. Usage bit functions operate on 32-bit integers. Examples returns the bitwise and of two long integers....
Page 306
282 cfml language reference bitmaskclear returns number bitwise cleared with length bits beginning from start. See also bitmaskread and bitmaskset . Syntax bitmaskclear( number , start , length ) number long integer to be masked. Start integer specifying the starting bit for masking. Length integer ...
Page 307
Chapter 2: coldfusion functions 283 bitmaskread returns the integer created from length bits of number beginning from start. See also bitmaskclear and bitmaskset . Syntax bitmaskread( number , start , length ) number long integer to be masked. Start integer specifying the starting bit for reading. L...
Page 308
284 cfml language reference bitmaskset returns number bitwise masked with length bits of mask beginning from start. See also bitmaskclear and bitmaskread . Syntax bitmaskset( number , mask , start , length ) number long integer to be masked. Mask long integer specifying the mask. Start integer speci...
Page 309
Chapter 2: coldfusion functions 285 bitnot returns the bitwise not of a long integer. See also bitand , bitor, and bitxor . Syntax bitnot( number ) number any long integer. Usage bit functions operate on 32-bit integers. Examples returns the bitwise not of a long integer. Bitnot(0): #bitnot(0)# bitn...
Page 310
286 cfml language reference bitor returns the bitwise or of two long integers see also bitand , bitnot , and bitxor . Syntax bitor( number1 , number2 ) number1, number2 any long integers. Usage bit functions operate on 32-bit integers. Examples returns the bitwise or of two long integers. Bitor(5,25...
Page 311
Chapter 2: coldfusion functions 287 bitshln returns number bitwise shifted without rotation to the left by count bits. See also bitshrn . Syntax bitshln( number , count ) number long integer to be shifted to the left. Count integer specifying number of bits the number should be shifted. Usage parame...
Page 312
288 cfml language reference bitshrn returns number bitwise shifted without rotation to the right by count bits. See also bitshln . Syntax bitshrn( number , count ) number long integer to be shifted to the right. Count integer specifying number of bits the number should be shifted. Usage parameter co...
Page 313
Chapter 2: coldfusion functions 289 bitxor returns bitwise xor of two long integers. See also bitand , bitnot, and bitor . Syntax bitxor( number1 , number2 ) number1, number2 any long integers. Usage bit functions operate on 32-bit integers. Examples returns the bitwise xor of two long integers. Bit...
Page 314
290 cfml language reference ceiling returns the closest integer greater than a given number. See also int , fix , and round . Syntax ceiling( number ) number any real number. Examples the ceiling of 3.4 is #ceiling(3.4)# the ceiling of 3 is #ceiling(3)# the ceiling of 3.8 is #ceiling(3.8)# the ceili...
Page 315
Chapter 2: coldfusion functions 291 chr returns a character of a given ascii value (character code). See also asc . Syntax chr( number ) number any ascii value (a number in the range 0 to 255 inclusive). Usage numbers from 0 to 31 are the standard, nonprintable ascii codes. For example, chr(10) retu...
Page 316
292 cfml language reference cjustify centers a string in the specified field length. See also ljustify and rjustify . Syntax cjustify( string , length ) string any string to be centered. Length length of field. Examples cjustify example enter a string, and it will be center justified within the samp...
Page 317
Chapter 2: coldfusion functions 293 compare performs a case-sensitive comparison of two strings. Returns a negative number if string1 is less than string2; 0 if string1 is equal to string2; or a positive number if string1 is greater than string2. See also comparenocase and find . Syntax compare( str...
Page 318
294 cfml language reference string 1 string 2.
Page 319
Chapter 2: coldfusion functions 295 comparenocase performs a case-insensitive comparison of two strings. Returns a negative number if string1 is less than string2; 0 if string1 is equal to string2; or a positive number if string1 is greater than string2. See also compare and findnocase . Syntax comp...
Page 320
296 cfml language reference cos returns the cosine of a given angle in radians. See also sin , tan, and pi . Syntax cos( number ) number angle in radians for which you want the cosine. Usage the range of the result is - 1 to 1 . To convert degrees to radians, multiply degrees by π /180. To convert r...
Page 321
Chapter 2: coldfusion functions 297 createdate returns a valid date/time object. See also createdatetime and createodbcdate . Syntax createdate( year , month , day ) year number representing the year in the range 100–9999. Years from 0 to 29 are interpreted as 21 st century values. Years 30 to 99 ar...
Page 322
298 cfml language reference form.Day, 12,13,0)# the same value can be formatted with dateformat: form.Month, form.Day), "mmm-dd-yyyy")# form.Month, form.Day, 12,13,0))# "mmmm d, yyyy")# #dateformat(createodbcdatetime(yourdate), "d/m/yy")# please enter the year, month and day in integer format for th...
Page 323
Chapter 2: coldfusion functions 299 createdatetime returns a valid date/time object. See also createdate , createtime , createodbcdatetime , and now . Syntax createdatetime( year , month , day , hour , minute , second ) year number representing the year in the range 100–9999. Month number representi...
Page 324
300 cfml language reference #createdatetime(form.Year, form.Month, form.Day, form.Hour, form.Minute,form.Second)# the same value can be formatted with dateformat: #dateformat(createdate (form.Year,form.Month,form.Day), "mmm-dd-yyyy")# #dateformat(createdatetime (form.Year, form.Month, form.Day, form...
Page 325: Com
Chapter 2: coldfusion functions 301 createobject allows you tocreate com, corba, and java objects. Note coldfusion administrators can disable the cfobject tag in the coldfusion administrator basic security page, which also disables this function. Note on unix, com objects are not currently supported...
Page 326: Corba
302 cfml language reference oleview, as well as information about com and dcom, can be found at microsoft’s ole development web site http://www.Microsoft.Com/oledev/. To create com objects, you need to know the program id or filename of the object, the methods and properties available through the id...
Page 327: Java
Chapter 2: coldfusion functions 303 • "ior" — coldfusion uses the interoperable object reference (ior) to access the corba server. • "nameservice" — coldfusion uses the naming service to access server. "nameservice" is only valid with the initialcontext of a visibroker orb. Locale optional. Sets arg...
Page 328
304 cfml language reference valid java type (simple, arrays, objects). Coldfusion does the appropriate conversions when strings are passed as arguments, but not when they are received as return values. Overloaded methods are supported as long as the number of arguments are different. Future enhancem...
Page 329
Chapter 2: coldfusion functions 305 createodbcdate returns a date in odbc date format. See also createdate and createodbcdatetime . Syntax createodbcdate( date ) date date/time object in the period from 100 ad to 9999 ad. Years from 0 to 29 are interpreted as 21 st century values. Years 30 to 99 are...
Page 330
306 cfml language reference (form.Year, form.Month, form.Day), "mmm-dd-yyyy")# #dateformat(createdatetime (form.Year, form.Month, form.Day, form.Hour, form.Minute,form.Second))# #dateformat(createodbcdate(yourdate), "mmmm d, yyyy")# #dateformat(createodbcdatetime(yourdate), "d/m/yy")# please enter t...
Page 331
Chapter 2: coldfusion functions 307 createodbcdatetime returns a date/time object in odbc timestamp format. See also createdatetime , createodbcdate , createodbctime , and now . Syntax createodbcdatetime( date ) date date/time object in the period from 100 ad to 9999 ad. Years from 0 to 29 are inter...
Page 332
308 cfml language reference #dateformat(createdatetime (form.Year, form.Month, form.Day, form.Hour, form.Minute, form.Second))# #dateformat(createodbcdate(yourdate), "mmmm d, yyyy")# #dateformat(createodbcdatetime(yourdate), "d/m/yy")# please enter the year, month and day in integer format for the d...
Page 333
Chapter 2: coldfusion functions 309 createodbctime returns a time object in odbc time format. See also createodbcdatetime and createtime . Syntax createodbctime( date ) date date/time object in the period from 100 ad to 9999 ad. Usage when passing a date/time value as a string, make sure it is enclo...
Page 334
310 cfml language reference message="you must enter a minute value (0-59)" validate="integer" required="yes"> second message="you must enter a value for seconds (0-59)" validate="integer" required="yes"> message="you must enter a value for seconds (0-59)" validate="integer" required="yes">.
Page 335
Chapter 2: coldfusion functions 311 createtime returns a valid time variable in coldfusion. See also createodbctime and createdatetime . Syntax createtime( hour , minute , second ) hour number representing the hour, ranging from 0 to 23. Minute number representing the minute, ranging from 0 to 59. S...
Page 336
312 cfml language reference.
Page 337
Chapter 2: coldfusion functions 313 createtimespan creates a date/time object for adding and subtracting other date/time objects. See also createdatetime , dateadd , and dateconvert . Syntax createtimespan( days , hours , minutes , seconds ) days number representing the number of days. Hours number ...
Page 338
314 cfml language reference createuuid returns a universally unique identifier (uuid) formatted as ‘xxxxxxxx-xxxx-xxxx- xxxxxxxxxxxxxxx’ where ‘x’ stands for a hexadecimal digit (0-9 or a-f). Syntax createuuid() usage each uuid returned by the createuuid function is a 35-character-string representat...
Page 339
Chapter 2: coldfusion functions 315 dateadd returns a date to which a specified time interval has been added. See also dateconvert , datepart , and createtimespan . Syntax dateadd( datepart , number , date ) datepart one of the following strings: • yyyy — year • q — quarter • m — month • y — day of ...
Page 340
316 cfml language reference this example uses dateadd to determine when a message in the database will expire. (the value selected is messages older than #value# years quarters months days of year weekdays weeks hours minutes seconds years ). Posted) lt now()>expired ....
Page 341
Chapter 2: coldfusion functions 317 datecompare performs a full date/time comparison of two dates. Returns -1 if date1 is less than date2; returns 0 if date1 is equal to date2; returns 1 if date1 is greater than date2. See the description of datepart for information on specifying the precision of th...
Page 342
318 cfml language reference the datecompare function compares two date/time values. Form.Precision)> #dateformat(form.Date1)# form.Precision)> #timeformat(form.Date1)# (date 1) is earlier than #dateformat(form.Date2)# #timeformat(form.Date2)# (date 2) the dates are not equal #timeformat(form.Date1)#...
Page 343
Chapter 2: coldfusion functions 319 #timeformat(now())# "> specify precision to the: second minute hour day month year.
Page 344
320 cfml language reference dateconvert converts local time to universal coordinated time (utc ) or utc to local time based on the specified parameters. This function uses the daylight savings settings in the executing machine to compute daylight savings time, if required. See also gettimezoneinfo ,...
Page 345
Chapter 2: coldfusion functions 321 form.Hour,form.Minute, form.Second)> your date value, presented as a coldfusion date-time string:#yourdate#. Form.Hour,form.Minute, form.Second)> your date value, presented as a coldfusion date-time string:#yourdate#. Your date and time value, converted into unive...
Page 346
322 cfml language reference message="you must enter a value for seconds (0-59)" validate="integer" required="yes">.
Page 347
Chapter 2: coldfusion functions 323 datediff returns the number of intervals in whole units of type datepart by which date1 is less than date2. See also dateadd , datepart , and createtimespan . Syntax datediff( datepart , date1 , date2 ) datepart one of the following strings: • yyyy — year • q — qu...
Page 348
324 cfml language reference years from 0 to 29 are interpreted as 21 st century values. Years 30 to 99 are interpreted as 20 th century values. Examples ... This example uses datediff to determine the difference in years quarters months days of year days weekdays weeks hours minutes seconds years da...
Page 349
Chapter 2: coldfusion functions 325 dateformat returns a formatted date/time value. If no mask is specified, dateformat function returns date value using the dd-mmm-yy format. See also now , createdate , and parsedatetime . Syntax dateformat( date [, mask ]) date date/time object in the period from ...
Page 350
326 cfml language reference examples dateformat example today’s date is #todaydate#. Using dateformat, we can display that date in a number of different ways:.
Page 351
Chapter 2: coldfusion functions 327 datepart returns the specified part of a date as an integer. See also dateadd and dateconvert . Syntax datepart( datepart , date ) datepart one of the following strings: • yyyy — year • q — quarter • m — month • y — day of year • d — day • w — weekday • ww — week ...
Page 352
328 cfml language reference using datepart, we can extract an integer representing the various dateparts from that value.
Page 353
Chapter 2: coldfusion functions 329 day returns the ordinal for the day of the month, ranging from 1 to 31. See also dayofweek , dayofweekasstring , dayofyear , daysinmonth , daysinyear , and firstdayofmonth . Syntax day( date ) date any date. Usage years from 0 to 29 are interpreted as 21 st centur...
Page 354
330 cfml language reference dayofweek returns the ordinal for the day of the week. The day is given as an integer ranging from 1 (sunday) to 7 (saturday). See also day , dayofweekasstring , dayofyear , daysinmonth , daysinyear , and firstdayofmonth . Syntax dayofweek( date ) date any date. Usage yea...
Page 355
Chapter 2: coldfusion functions 331 dayofweekasstring returns the day of the week corresponding to day_of_week, an integer ranging from 1 (sunday) to 7 (saturday). See also day , dayofweek , dayofyear , daysinmonth , daysinyear , and firstdayofmonth . Syntax dayofweekasstring( day_of_week ) day_of_w...
Page 356
332 cfml language reference dayofyear returns the ordinal for the day of the year. See also day , dayofweek , dayofweekasstring , daysinmonth , daysinyear , and firstdayofmonth . Syntax dayofyear( date ) date any date. Usage dayofyear is aware of leap years. Years from 0 to 29 are interpreted as 21 ...
Page 357
Chapter 2: coldfusion functions 333 daysinmonth returns the number of days in the specified month (date). See also day , dayofweek , dayofweekasstring , dayofyear , daysinyear , and firstdayofmonth . Syntax daysinmonth( date ) date any date. Usage years from 0 to 29 are interpreted as 21 st century ...
Page 358
334 cfml language reference daysinyear returns the number of days in a year. See also day , dayofweek , dayofweekasstring , dayofyear , daysinmonth , daysinyear , firstdayofmonth , and isleapyear . Syntax daysinyear( date ) date any date. Usage daysinyear is aware of leap years. Years from 0 to 29 a...
Page 359
Chapter 2: coldfusion functions 335 de returns its argument with double quotes wrapped around it and all double quotes inside it escaped. The de (delay evaluation) function prevents the evaluation of a string as an expression when it is passed as an argument to iif or evaluate. See also evaluate and...
Page 360
336 cfml language reference decimalformat returns number as a string formatted with two decimal places and thousands separator. See also dollarformat and numberformat . Syntax decimalformat( number ) number number being formatted. Examples decimalformat example returns a number to two decimal places...
Page 361
Chapter 2: coldfusion functions 337 decrementvalue returns integer part of number decremented by one. See also incrementvalue . Syntax decrementvalue( number ) number number being decremented. Examples decrementvalue example returns the integer part of a number decremented by one. Decrementvalue(0):...
Page 362
338 cfml language reference decrypt decrypts an encrypted string. See also encrypt . Syntax decrypt( encrypted_string , key ) encrypted_string string to be decrypted. Key string specifying the key used to encrypt encrypted_string. Examples this function allows for the encryption and decryption of a ...
Page 363
Chapter 2: coldfusion functions 339 deleteclientvariable deletes the client variable specified by name. Returns a boolean true when variable is successfully deleted, even if variable did not previously exist. To test for the existence of a variable, use isdefined. See also getclientvariableslist . S...
Page 364
340 cfml language reference directoryexists returns yes if the directory specified in the argument does exist; otherwise, it returns no. See also fileexists . Syntax directoryexists( absolute_path ) absolute_path any absolute path. Examples directoryexists example 1"))> the current directory is: #ge...
Page 365
Chapter 2: coldfusion functions 341 dollarformat returns number as a string formatted with two decimal places, thousands separator, dollar sign. Parentheses are used if number is negative. See also decimalformat and numberformat . Syntax dollarformat( number ) number number being formatted. Examples...
Page 366
342 cfml language reference encrypt encrypts a string. See also decrypt . Syntax encrypt( string , key ) string string to be encrypted. Key string specifying the key used to encrypt string. Examples this function allows for the encryption and decryption of a string. Try it out by entering your own s...
Page 367
Chapter 2: coldfusion functions 343 evaluate the function evaluates all of its arguments, left to right, and returns the result of evaluating the last argument. See also de and iif . Syntax evaluate( string_expression1 [, string_expression2 [, … ] ] ) string_expression1, string_expression2 valid exp...
Page 368
344 cfml language reference exp returns e raised to the power of number. The constant e equals 2.71828182845904, the base of the natural logarithm. See also log and log10 . Syntax exp( number ) number exponent applied to the base e. Usage to calculate powers of other bases, use ^ (the exponentiation...
Page 369
Chapter 2: coldfusion functions 345 expandpath returns a path equivalent to the relative_path appended to the base template path. Note the following: • expandpath creates a platform-appropriate path. You can use either a slash (/) or a back slash (\) in the specified relative path. • the return valu...
Page 370
346 cfml language reference fileexists returns yes if the file specified in the argument does exist; otherwise, it returns no. See also directoryexists , expandpath , and gettemplatepath . Syntax fileexists( absolute_path ) absolute_path any absolute path. Examples fileexists example the current dir...
Page 371
Chapter 2: coldfusion functions 347 find returns the first index of an occurrence of a substring in a string from a specified starting position. Returns 0 if substring is not in string. The search is case-sensitive. See also findnocase , compare , findoneof , refind , and replace . Syntax find( subs...
Page 372
348 cfml language reference findnocase returns the first index of an occurrence of a substring in a string from a specified starting position. Returns 0 if substring is not in string. The search is case-insensitive. See also find , comparenocase , findoneof , refind , and replace functions. Syntax f...
Page 373
Chapter 2: coldfusion functions 349 findoneof return the first index of the occurrence of any character from set in string. Returns 0 if no characters are found. The search is case-sensitive. See also find , compare , and refind functions. Syntax findoneof( set , string [, start ]) set string contai...
Page 374
350 cfml language reference firstdayofmonth returns the ordinal (the day’s number in the year) for the first day of the specified month. See also day , dayofweek , dayofweekasstring , dayofyear , daysinmonth , and daysinyear . Syntax firstdayofmonth( date ) date any date. Usage years from 0 to 29 ar...
Page 375
Chapter 2: coldfusion functions 351 fix returns the closest integer less than number if number is greater than or equal to 0. Returns the closest integer greater than number if number is less than 0. See also ceiling , int , and round . Syntax fix( number ) number any number. Examples fix example fi...
Page 376
352 cfml language reference formatbasen converts a number to a string in the base specified by radix. See also inputbasen . Syntax formatbasen( number , radix ) number number to be converted. Radix base of the result. Examples formatbasen example formatbasen converts a number to a string in the base...
Page 377
Chapter 2: coldfusion functions 353 getbasetagdata returns an object that contains data (variables, scopes, etc.) from a specified ancestor tag. By default the closest ancestor is returned. If there is no ancestor by the specified name, or if the ancestor does not expose any data (for example, cfif)...
Page 378
354 cfml language reference getbasetaglist returns a comma-delimited list of uppercase ancestor tag names. The first element of the list is the parent tag. If you call this function for a top-level tag, it returns an empty string. See also getbasetagdata . Syntax getbasetaglist() example ... This is...
Page 379
Chapter 2: coldfusion functions 355 getbasetemplatepath returns the fully specified path of the base template. See also getcurrenttemplatepath , fileexists and expandpath . Syntax getbasetemplatepath() example getbasetemplatepath example the template path of the current page is: #getbasetemplatepath...
Page 380
356 cfml language reference getclientvariableslist returns a comma-delimited list of non-readonly client variables available to a template. See also deleteclientvariable . Syntax getclientvariableslist() example this view-only example deletes a client variable called "user_id", if it exists in the l...
Page 381
Chapter 2: coldfusion functions 357 getcurrenttemplatepath returns the fully specified path of the template containing the call to this function. See also getbasetemplatepath , fileexists and expandpath . Syntax getcurrenttemplatepath() usage this function differs from getbasetemplatepath in that it...
Page 382
358 cfml language reference getdirectoryfrompath extracts the directory (with a \ (backslash)) from a fully specified path. See also expandpath and getfilefrompath . Syntax getdirectoryfrompath( path ) path fully specified path (drive, directory, filename, and extension). Examples getdirectoryfrompa...
Page 383
Chapter 2: coldfusion functions 359 getfilefrompath extracts the filename from a fully specified path. See also expandpath and getcurrenttemplatepath . Syntax getfilefrompath( path ) path fully qualified path (drive, directory, filename, and extension). Examples getfilefrompath example the current d...
Page 384
360 cfml language reference getfunctionlist returns a structure of functions that are available in coldfusion. Syntax getfunctionlist( ) examples #structcount(flist)# functions #key#.
Page 385
Chapter 2: coldfusion functions 361 getlocale returns the locale for the current request. Locales are determined by the native operating system. A locale is an encapsulation of the set of attributes that govern the display and formatting of international date, time, number, and currency values. See ...
Page 386
362 cfml language reference request. Locales are determined by the native operating system. A locale is an encapsulation of the set of attributes that govern the display and formatting of international date, time, number, and currency values. The locale for this system is #getlocale()#.
Page 387
Chapter 2: coldfusion functions 363 getmetricdata on windows nt, getmetricdata returns all the internal data that is otherwise displayed in the windows nt perfmonitor. On unix, getmetricdata returns all of the internal data found by using cfstat. For it to work on nt you need to have turned on the p...
Page 388
364 cfml language reference reqrunning: #pmdata.Reqrunning# reqtimedout: #pmdata.Reqtimedout# bytesin: #pmdata.Bytesin# bytesout: #pmdata.Bytesout# avgqueuetime: #pmdata.Avgqueuetime# avgreqtime: #pmdata.Avgreqtime# avgdbtime: #pmdata.Avgdbtime# cachepops: #pmdata.Cachepops#.
Page 389
Chapter 2: coldfusion functions 365 getprofilestring returns the value of an entry in an initialization file or an empty string if the value does not exist. An initialization file assigns values to configuration variables, also known as entries, that need to be set when the system boots, the operati...
Page 390
366 cfml language reference timeout is set to: #timeout#..
Page 391
Chapter 2: coldfusion functions 367 gettempdirectory returns the full path name of a directory, including the trailing slash. The directory that is returned depends on the account under which coldfusion is running as well as a variety of other factors. Before using this function in an application, t...
Page 392
368 cfml language reference gettempfile creates and returns the name of a temporary file in a directory whose name starts with (at most) the first three characters of prefix. See also gettempdirectory . Syntax gettempfile( dir , prefix ) dir directory name. Prefix prefix of a temporary file to be cr...
Page 393
Chapter 2: coldfusion functions 369 gettemplatepath returns the fully specified path of the base template. Note for backward compatibility, gettemplatepath is still supported. However, getbasetemplatepath supersedes this function, and should be used in place of it in all code written after the relea...
Page 394
370 cfml language reference gettickcount returns a millisecond clock counter that can be used for timing sections of cfml code or any other aspects of page processing. Syntax gettickcount() usage the absolute value of the counter has no meaning. Generate useful timing values by taking differences be...
Page 395
Chapter 2: coldfusion functions 371 gettimezoneinfo returns a structure containing time zone information for the machine on which this function is executed. The structure contains four elements with the following keys. • utctotaloffset — total offset of the local time in minutes from utc (universal ...
Page 396
372 cfml language reference gettoken returns the specified token in a string. Default delimiters are spaces, tabs, and newline characters. If index is greater than the number of tokens in string, gettoken returns an empty string. See also left , right , mid , spanexcluding , and spanincluding . Synt...
Page 397
Chapter 2: coldfusion functions 373 hour returns the ordinal value for the hour, ranging from 0 to 23. See also datepart , minute , and second . Syntax hour( date ) date any date. Usage years from 0 to 29 are interpreted as 21 st century values. Years 30 to 99 are interpreted as 20 th century values...
Page 398
374 cfml language reference htmlcodeformat returns html escaped string enclosed in and tags. All carriage returns are removed from string, and all special characters (> see also htmleditformat . Syntax htmlcodeformat( string [, version ]) string string being html escaped and preformatted. Version th...
Page 399
Chapter 2: coldfusion functions 375 /"> because you entered no url or an empty string, the tag /"> will return the following address: http://localhost/cfdocs/ index.Htm method="get" resolveurl=yes> method="get" resolveurl=yes> method="get" resolveurl=yes> method="get" resolveurl=yes> here is an exam...
Page 400
376 cfml language reference htmleditformat returns html escaped string. All carriage returns are removed from string, and all special characters (> see also htmlcodeformat . Syntax htmleditformat( string [, version ]) string string being html escaped. Version the specific html version to use in repl...
Page 401
Chapter 2: coldfusion functions 377 /"> because you entered no url or an empty string, the tag /"> will return the following address: http://localhost/cfdocs/index.Htm method="get" resolveurl=yes> method="get" resolveurl=yes> method="get" resolveurl=yes> method="get" resolveurl=yes> here is an examp...
Page 402
378 cfml language reference iif the function evaluates its condition as a boolean. If the result is true, it returns the value of evaluate(string_expression1); otherwise, it returns the value of evaluate(string_expression2). Prior to using iif, please read the usage section and note carefully. The i...
Page 403
Chapter 2: coldfusion functions 379 error ’error resolving parameter’ if there is an undefined variable in string_expression1. For example, “localvar” is undefined, however, the following logic functions as you would expect if you do not use pound signs around “localval”: #iif(isdefined(“localvar”),...
Page 404
380 cfml language reference de("it is morning"))#.
Page 405
Chapter 2: coldfusion functions 381 incrementvalue returns integer part of number incremented by one. See also decrementvalue . Syntax incrementvalue( number ) number number being incremented. Examples incrementvalue example returns the integer part of a number incremented by one. Incrementvalue(0):...
Page 406
382 cfml language reference inputbasen returns the number obtained by converting string using the base specified by radix, an integer ranging from 2 to 36. See also formatbasen . Syntax inputbasen( string , radix ) string any string representing number in base specified by radix. Radix base of numbe...
Page 407
Chapter 2: coldfusion functions 383 insert inserts a substring in a string after a specified character position. Prepends the substring if position is equal to 0. See also removechars and len . Syntax insert( substring , string , position ) substring string to be inserted. String string to be insert...
Page 408
384 cfml language reference int returns the closest integer smaller than a number. See also ceiling , fix , and round . Syntax int( number ) number real number you want to round down to an integer. Examples int example int returns the closest integer smaller than a number. Int(11.7) : #int(11.7)# in...
Page 409
Chapter 2: coldfusion functions 385 isarray returns true if value is an array. See also “array functions” on page 245 . Syntax isarray( value [, number ]) value variable name or array name. Number tests if the array has exactly the specified dimension. Examples is this an array? #isarray(mynewarray)...
Page 410
386 cfml language reference isauthenticated returns true if the user has been authenticated for any coldfusion security context. If you specify the name of the security context, isauthenticated returns true if the user has been authenticated for the specified coldfusion security context. See also cf...
Page 411
Chapter 2: coldfusion functions 387 isauthorized returns true if the user is authorized to perform the specified action on the specified coldfusion resource. See also isauthenticated . Syntax isauthorized( resourcetype , resourcename [, action ]) resourcetype string specifying the type of resource: ...
Page 412
388 cfml language reference action string specifying the action for which authorization is requested. Do not specify this parameter for component and customtag. For all other resource types, this parameter is required. Usage if you specify throwonfailure=yes in the cfauthenticate tag, you can enclos...
Page 413
Chapter 2: coldfusion functions 389 #customer# - #balancedue#.
Page 414
390 cfml language reference isbinary returns true if value is binary; otherwise, the function returns false. See also tobinary , tobase64 , isnumeric and yesnoformat . Syntax isbinary( value ) value any value. Examples isbinary example ... ....
Page 415
Chapter 2: coldfusion functions 391 isboolean returns true if value can be converted to a boolean; otherwise, false. See also isnumeric and yesnoformat . Syntax isboolean( value ) value any number or string. Examples isboolean example is boolean is not boolean enter an expression, and discover if it...
Page 416
392 cfml language reference isdate returns true if string can be converted to a date/time value; otherwise, false. Note that coldfusion converts the boolean return value to its string equivalent, "yes" and "no." see also parsedatetime , createdatetime , and isnumericdate . Syntax isdate( string ) st...
Page 417
Chapter 2: coldfusion functions 393 isdebugmode returns true if debugging mode was set via the coldfusion administrator and false if debugging mode is disabled. Syntax isdebugmode() examples isdebugmode example.
Page 418
394 cfml language reference isdefined evaluates a string value to determine if the variable named in the string value exists. Isdefined returns true if the specified variable is found, false if not found. Isdefined provides an alternative to the parameterexists function, eliminating the need for cum...
Page 419
Chapter 2: coldfusion functions 395 isleapyear returns true if the year is a leap year; otherwise, false. See also daysinyear . Syntax isleapyear( year ) year number representing the year. Examples isleapyear example is a leap year is not a leap year enter a year value, and find out if it is a valid...
Page 420
396 cfml language reference isnumeric returns true if string can be converted to a number; otherwise, false. See also isbinary . Syntax isnumeric( string ) string any string value. Examples isnumeric example can be converted to a number cannot be converted to a number enter a string, and discover if...
Page 421
Chapter 2: coldfusion functions 397 isnumericdate evaluates "real value" of date/time object. Returns true if the number represents "real value" of the date/time object; otherwise, false. See also isdate and parsedatetime . Syntax isnumericdate( number ) number real number. Examples isnumericdate ex...
Page 422
398 cfml language reference isprotected returns true if the resource is protected in the security context of the authenticated user. See also isauthorized . Syntax isprotected( resourcetype, resourcename [ , action ]) resourcetype string specifying the type of resource: • application • cfml • file •...
Page 423
Chapter 2: coldfusion functions 399 action string specifying the action for which authorization is requested. Do not specify this parameter for component and customtag. For all other resource types, this parameter is required. Usage the isprotected function only returns true if the resource is prote...
Page 424
400 cfml language reference select * from orders authorization succeeded. Order information follows: #customer# - #balancedue#.
Page 425
Chapter 2: coldfusion functions 401 isquery returns true if value is a query. See also queryaddrow . Syntax isquery( value ) value query variable. Example isquery example before the query is run, the value of getemployees is #getemployees# getemployees is currently a simple value select * from emplo...
Page 426
402 cfml language reference issimplevalue returns true if value is a string, number, boolean, or date/time value. Syntax issimplevalue( value ) value variable or expression. Example issimplevalue example before the query is run, the value of getemployees is #getemployees# getemployees is currently a...
Page 427
Chapter 2: coldfusion functions 403 isstruct returns true if variable is a structure. See also “structure functions” on page 250 . Syntax isstruct( variable ) variable variable name. Examples this file is similar to addemployee.Cfm, which is called by structnew, structclear, and structdelete. It is ...
Page 428
404 cfml language reference jsstringformat returns a string that is safe to use with javascript. Syntax jsstringformat( string ) string any string. Usage jsstringformat escapes special javascript characters, such as the single quote (’), double quotes ("), and newline character so that you can put a...
Page 429
Chapter 2: coldfusion functions 405 lcase returns string converted to lowercase. See also ucase . Syntax lcase( string ) string string being converted to lowercase. Examples lcase example your text, #form.Sampletext#, returned in lowercase is #lcase(form.Sampletext)# . Please enter some text. Enter ...
Page 430
406 cfml language reference left returns the count of characters from the beginning of a string argument. See also right , mid , and len . Syntax left( string , count ) string string from which the leftmost characters are retrieved. Count positive integer indicating how many characters to return. Ex...
Page 431
Chapter 2: coldfusion functions 407 len returns the length of a string or a binary object. See also tobinary , left , right , and mid . Syntax len( string or binary object ) string any string or binary object. Examples len example your string, "#form.Mytext#", has #len(form.Mytext)# characters. Plea...
Page 432
408 cfml language reference listappend returns list with value appended behind its last element. See also listprepend , listinsertat , and listsetat . Syntax listappend( list , value [, delimiters ]) list any list. Value number or list being appended. Delimiters set of delimiters used in list. Usage...
Page 433
Chapter 2: coldfusion functions 409 listchangedelims returns list with all delimiter characters changed to new_delimiter string. See also listfirst and listqualify . Syntax listchangedelims( list , new_delimiter [, delimiters ]) list list of delimiters being changed. New_delimiter string being used ...
Page 434
410 cfml language reference listcontains returns the index of the first item that contains the specified substring. The search is case-sensitive. If the substring is not found in any of the list items, it returns zero (0). See also listcontainsnocase and listfind . Syntax listcontains( list , substr...
Page 435
Chapter 2: coldfusion functions 411 however, if you specify the entire string two, both listcontains and listfind will find it in the second item in the list. Listcontains the string "two" is in item #listcontains(alist, "two")# of the list. Listfind the string "two" is in item #listfind(alist, "two...
Page 436
412 cfml language reference listcontainsnocase returns the index of the first element of a list that contains the specified substring within elements. The search is case-insensitive. If no element is found, returns 0. See also listcontains and listfindnocase . Syntax listcontainsnocase( list , subst...
Page 437
Chapter 2: coldfusion functions 413 listdeleteat returns list with element deleted at the specified position. See also listgetat , listsetat , and listlen . Syntax listdeleteat( list , position [, delimiters ]) list any list. Position positive integer indicating the position of the element being del...
Page 438
414 cfml language reference listfind returns the index of the first occurrence of a value within a list. Returns 0 if no value is found. The search is case-sensitive. See also listcontains and listfindnocase . Syntax listfind( list , value [, delimiters ]) list list being searched. Value number or s...
Page 439
Chapter 2: coldfusion functions 415 however, if you specify the entire string two, both listcontains and listfind will find it in the second item in the list. Listcontains the string "two" is in item #listcontains(alist, "two")# of the list. Listfind the string "two" is in item #listfind(alist, "two...
Page 440
416 cfml language reference listfindnocase returns the index of the first occurrence of a value within a list. Returns 0 if no value was found. The search is case-insensitive. See also listcontains and listfind . Syntax listfindnocase( list , value [, delimiters ]) list list being searched. Value nu...
Page 441
Chapter 2: coldfusion functions 417 listfirst returns the first element of the list. See also listgetat , listlast , and listqualify . Syntax listfirst( list [, delimiters ]) list list whose first element is being retrieved. Delimiters set of delimiters used in list. Examples select username, subjec...
Page 442
418 cfml language reference listgetat returns the element at a given position. See also listfirst , listlast , listqualify , and listsetat . Syntax listgetat( list , position [, delimiters ]) list list whose element is being retrieved. Position positive integer indicating the position of the element...
Page 443
Chapter 2: coldfusion functions 419 listinsertat returns list with value inserted at the specified position. See also listdeleteat , listappend , listprepend , and listsetat . Syntax listinsertat( list , position , value [, delimiters ]) list any list. Position position where the value is being inse...
Page 444
420 cfml language reference listlast returns the last element of the list. See also listgetat and listfirst . Syntax listlast( list [, delimiters ]) list list whose last element is being retrieved. Delimiters set of delimiters used in list. Examples select username, subject, posted from messages the...
Page 445
Chapter 2: coldfusion functions 421 listlen returns the number of elements in the list. See also listappend , listdeleteat , listinsertat , and listprepend . Syntax listlen( list [, delimiters ]) list any list. Delimiters set of delimiters used in list. Examples select username, subject, posted from...
Page 446
422 cfml language reference listprepend returns list with value inserted at the first position, shifting all other elements one to the right. See also listappend , listinsertat , and listsetat . Syntax listprepend( list , value [, delimiters ]) list any list. Value number or list being prepended. De...
Page 447
Chapter 2: coldfusion functions 423 listqualify returns a list with a qualifying character around each item in the list, such as double or single quotes. See the list functions table. Syntax listqualify( list , qualifier [, delimiters ] [, elements ]) list any list of items or a variable that names ...
Page 448
424 cfml language reference 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 as follows: #qualifiedlist2#.
Page 449
Chapter 2: coldfusion functions 425 listrest returns list without its first element. Returns an empty list (empty string) if list has only one element. See also listfirst , listgetat , and listlast . Syntax listrest( list [, delimiters ]) list list whose elements are being retrieved. Delimiters set ...
Page 450
426 cfml language reference listsetat returns list with value assigned to its element at specified position. See also listdeleteat , listgetat , and listinsertat . Syntax listsetat( list , position , value [, delimiters ]) list any list. Position any position. The first position in a list is denoted...
Page 451
Chapter 2: coldfusion functions 427 (#counter#) subject: #listgetat(temptoo, counter)# note that item 2, "#changeditem#", has been altered to "i changed this subject" using listsetat..
Page 452
428 cfml language reference listsort sorts and delimits the items in a list according to the specified sort type and sort order. Syntax listsort( list, sort_type [ , sort_order ] [, delimiter ]) list list to be sorted. The items in the list must be separated by commas or otherwise delimited. Sort_ty...
Page 453
Chapter 2: coldfusion functions 429 #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 both negative and positive numbers, as well as decimal numbers. "asc", ";,:")> #sortednums2# here is a list...
Page 454
430 cfml language reference listtoarray converts the specified list into an array. See also arraytolist . Syntax listtoarray( list [, delimiter ]) list name of the list variable that contains the elements to be used to build an array. You can define a list variable with a cfset statement. The items ...
Page 455
Chapter 2: coldfusion functions 431 listvaluecount returns the number of instances of a specified value in a list. The underlying search that finds the instances is case-sensitive. See also listvaluecountnocase . Syntax listvaluecount( list, value [, delimiters ]) list a list or the name of a list t...
Page 456
432 cfml language reference form.Departmentname)> there are no employees in #form.Departmentname# form.Departmentname)> cfoutput> there is only one person in #form.Departmentname#. There are #numberindepartment# people in #form.Departmentname#..
Page 457
Chapter 2: coldfusion functions 433 listvaluecountnocase returns the number of instances of a specified value in a list. The underlying search that finds the instances is not case-sensitive. See also listvaluecount . Syntax listvaluecountnocase( list, value [, delimiters ]) list a list or the name o...
Page 458
434 cfml language reference form.Departmentname)> there are no employees in #form.Departmentname# form.Departmentname)> cfoutput> there is only one person in #form.Departmentname#. There are #numberindepartment# people in #form.Departmentname#..
Page 459
Chapter 2: coldfusion functions 435 ljustify returns left-justified string of the specified field length. See also cjustify and rjustify . Syntax ljustify( string , length ) string string to be left-justified. Length length of field. Example ljustify example enter a string, and it will be left justi...
Page 460
436 cfml language reference log returns the natural logarithm of a number. Natural logarithms are based on the constant e (2.71828182845904). See also exp and log10 . Syntax log( number ) number positive real number for which you want the natural logarithm. Examples log example your number, #form.Nu...
Page 461
Chapter 2: coldfusion functions 437 log10 returns the logarithm of number to base 10. See also exp and log . Syntax log10( number ) number positive real number for which you want the logarithm. Examples log10 example your number, #form.Number# #form.Number# raised to the e power: #exp(form.Number)# ...
Page 462
438 cfml language reference lscurrencyformat returns a currency value using the locale convention. Default value is "local." see, also, lseurocurrencyformat . Syntax lscurrencyformat( number [, type ]) number the currency value. Type currency type. Valid arguments are: • none — (for example, 10.00) ...
Page 463
Chapter 2: coldfusion functions 439 english (us) local: $100,000.00 international: usd100,000.00 none: 100,000.00 french (belgian) local: 100.000,00 fb international: bef100.000,00 none: 100.000,00 french (canadian) local: 100 000,00 $ international: cad100 000,00 none: 100 000,00 french (standard) ...
Page 464
440 cfml language reference example lscurrencyformat returns a currency value using the locale convention. Default value is "local." index="locale" delimiters=","> #locale# local: #lscurrencyformat(100000, "local")# international: #lscurrencyformat(100000, "international")# none: #lscurrencyformat(1...
Page 465
Chapter 2: coldfusion functions 441 lsdateformat formats the date portion of a date/time value using the locale convention. Like dateformat lsdateformat returns a formatted date/time value. If no mask is specified, lsdateformat returns a date value using the locale-specific format. Syntax lsdateform...
Page 466
442 cfml language reference index="locale" delimiters=","> #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")# #lsdatefo...
Page 467
Chapter 2: coldfusion functions 443 lseurocurrencyformat returns a currency value using the convention of the locale and the euro as the currency symbol. Default value is "local." note the locale is set with the setlocale function. See, also, lsparseeurocurrency , lscurrencyformat , and setlocale . ...
Page 468
444 cfml language reference english (australian) local: € 100,000.00 international: eur100,000.00 none: 100,000.00 english (canadian) local: € 100,000.00 international: eur100,000.00 none: 100,000.00 english (new zealand) local: € 100,000.00 international: eur100,000.00 none: 100,000.00 english (uk)...
Page 469
Chapter 2: coldfusion functions 445 example lseurocurrencyformat returns a currency value using the locale convention. Default value is "local." italian (swiss) local: € 100’000.00 international: eur100’000.00 none: 100’000.00 norwegian (bokmal) local: € 100 000,00 international: eur100 000,00 none:...
Page 470
446 cfml language reference index="locale" delimiters=","> #locale# local: #lseurocurrencyformat(100000, "local")# international: #lseurocurrencyformat(100000, "international")# none: #lseurocurrencyformat(100000, "none")# index="locale" delimiters=","> #locale# local: #lseurocurrencyformat(100000, ...
Page 471
Chapter 2: coldfusion functions 447 lsiscurrency checks whether a string is a locale-specific currency string. Returns true if string is a currency string, false otherwise. Syntax lsiscurrency( string ) string the locale-specific currency string. Example is the value "#form.Myvalue#" a proper curren...
Page 472
448 cfml language reference lsisdate like the isdate function, lsisdate returns true if string can be converted to a date/ time value in the current locale, false otherwise. Syntax lsisdate( string ) string any string value. Usage years less than 100 are interpreted as 20 th century values. Examples...
Page 473
Chapter 2: coldfusion functions 449 lsisnumeric like the isnumeric function, lsisnumeric returns true if string can be converted to a number in the current locale; otherwise, false. Syntax lsisnumeric( string ) string any string value. Examples is the value "#form.Myvalue#" a proper numeric value fo...
Page 474
450 cfml language reference lsnumberformat formats a number using the locale convention. If mask is omitted, the number is formatted as an integer. Syntax lsnumberformat( number [, mask ]) number the number you want to format. Mask all lsnumberformat mask characters apply except that ($) dollar, (,)...
Page 475
Chapter 2: coldfusion functions 451 and negative numbers in your application, use either the space or use - (hyphen) to force a space in front of positive numbers and a minus sign in front of negative numbers. Usage the position of codes in format masks determines where those codes will have effect....
Page 476
452 cfml language reference examples lsnumberformat returns a number value using the locale convention. Index="locale" delimiters=","> #locale# #lsnumberformat(-1234.5678, "_________")# #lsnumberformat(-1234.5678, "_________.___")# #lsnumberformat(1234.5678, "_________")# #lsnumberformat(1234.5678, ...
Page 477
Chapter 2: coldfusion functions 453 lsparsecurrency converts a locale-specific currency string to a number. Attempts conversion through each of the three default currency formats (none, local, international). Returns the number matching the value of string. See, also, lscurrencyformat and lsparseeur...
Page 478
454 cfml language reference french (belgian) local: 100.000,00 fb international: bef100.000,00 none: 100.000,00 french (canadian) local: 100 000,00 $ international: cad100 000,00 none: 100 000,00 french (standard) local: 100 000,00 f international: frf100 000,00 none: 100 000,00 french (swiss) local...
Page 479
Chapter 2: coldfusion functions 455 example lsparsecurrency coverts a local-specific currency string to a number. Attempts conversion through each of the three default currency formats. Index="locale" delimiters=","> #locale# local: #lscurrencyformat(123456, "local")# currency number: #lsparsecurren...
Page 480
456 cfml language reference lsparsedatetime a locale-specific version of the parsedatetime function, except that there is no option for pop date/time object parsing. Returns a date/time object. See also parsedatetime and setlocale . Syntax lsparsedatetime( date-time-string ) date-time-string string ...
Page 481
Chapter 2: coldfusion functions 457 lsparsedatetime returns a locale-specific date/time object. Index="locale" delimiters=","> #locale# locale-specific formats: #lsdateformat(now(), "mmm-dd-yyyy")# #lstimeformat(now())# #lsdateformat(now(), "mmmm d, yyyy")# #lstimeformat(now())# #lsdateformat(now(),...
Page 482
458 cfml language reference lsparseeurocurrency converts a locale-specific currency string that contains the euro symbol ( €) or sign (eur) to a number. Attempts conversion through each of the three default currency formats (none, local, international). Returns the number matching the value of strin...
Page 483
Chapter 2: coldfusion functions 459.
Page 484
460 cfml language reference lsparsenumber converts a locale-specific string to a number. Returns the number matching the value of string. Syntax lsparsenumber( string ) string string being converted to a number. Examples lsparsenumber converts a locale-specific string to a number. Returns the number...
Page 485
Chapter 2: coldfusion functions 461 lstimeformat returns a custom-formatted time value using the locale convention. See also lsparsedatetime . Syntax lstimeformat( time [, mask ]) string any date/time value or string convertible to a time value. Mask a set of masking characters determining the forma...
Page 486
462 cfml language reference index="locale" delimiters=","> #locale# #lstimeformat(now())# #lstimeformat(now(), ‘hh:mm:ss’)# #lstimeformat(now(), ‘hh:mm:sst’)# #lstimeformat(now(), ‘hh:mm:sstt’)# #lstimeformat(now(), ‘hh:mm:ss’)# #locale# #lstimeformat(now())# #lstimeformat(now(), ‘hh:mm:ss’)# #lstim...
Page 487
Chapter 2: coldfusion functions 463 ltrim returns string with leading spaces removed. See also rtrim and tobase64 . Syntax ltrim( string ) string string being left-trimmed. Examples ltrim example your string:"#form.Mytext#" your string:"#ltrim(form.Mytext)#" (left trimmed) type in some text, and it ...
Page 488
464 cfml language reference max returns the maximum, or higher, value of two numbers. See also min . Syntax max( number1 , number2 ) number1, number2 any numbers. Examples max example the maximum of the two numbers is #max(form.Mynum1, form.Mynum2)# the minimum of the two numbers is #min(form.Mynum1...
Page 489
Chapter 2: coldfusion functions 465 mid returns count characters from string beginning at start position. See also left , len , and right . Syntax mid( string , start , count ) string any string. Start starting position for count. Count number of characters being returned. Examples mid example your ...
Page 490
466 cfml language reference min returns the minimum, or smaller, value of two numbers. See also max . Syntax min( number1 , number2 ) number1, number2 any numbers. Examples min example the maximum of the two numbers is #max(form.Mynum1, form.Mynum2)# the minimum of the two numbers is #min(form.Mynum...
Page 491
Chapter 2: coldfusion functions 467 minute returns the ordinal for the minute, ranging from 0 to 59. See also datepart , hour , and second . Syntax minute( date ) date any date. Usage years from 0 to 29 are interpreted as 21 st century values. Years 30 to 99 are interpreted as 20 th century values. ...
Page 492
468 cfml language reference month returns the ordinal for the month, ranging from 1 (january) to 12 (december). See also datepart , monthasstring , and quarter . Syntax month( date ) date any date. Usage years from 0 to 29 are interpreted as 21 st century values. Years 30 to 99 are interpreted as 20...
Page 493
Chapter 2: coldfusion functions 469 monthasstring returns the name of the month corresponding to month_number. See also datepart , month , and quarter . Syntax monthasstring( month_number ) month_number an integer ranging from 1 to 12. Examples monthasstring example more information about your date:...
Page 494
470 cfml language reference now returns the current date and time as a valid date time object. See also createdatetime and datepart . Syntax now() examples 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 #datefo...
Page 495
Chapter 2: coldfusion functions 471 numberformat creates a custom-formatted number value. If no mask is specified, returns the value as an integer with a thousands separator. See also decimalformat , dollarformat , and isnumeric . Syntax numberformat( number [, mask ]) number the number you want to ...
Page 496
472 cfml language reference note if you do not specify a sign for the mask, positive and negative numbers will not align in columns. As a result, if you expect to display both positive and negative numbers in your application, use either the space or use - (minus sign) to force a space in front of p...
Page 497
Chapter 2: coldfusion functions 473 of fields they are located in. The following example shows how to use the field to determine exactly where to place parentheses to display negative numbers: examples numberformat example ‘_____.__’)# number mask result 3.21 c(__^__) "( 3.21 )" 3.21 c__(^__) " (3.2...
Page 498
474 cfml language reference paragraphformat returns string with converted single newline characters (cr/lf sequences) into spaces and double newline characters into html paragraph markers ( ). See also stripcr . Syntax paragraphformat( string ) string string being converted to the html paragraph for...
Page 499
Chapter 2: coldfusion functions 475 parameterexists returns true if the specified parameter has been passed to the current template or has already been created during execution of the current template. Otherwise returns no. This function is provided for backward compatibility with previous versions ...
Page 500
476 cfml language reference parsedatetime returns a date/time object from a string. See also lsparsedatetime , isdate and isnumericdate . Syntax parsedatetime( date-time-string [, pop-conversion ] ) date-time-string string being converted to date/time object. Pop-conversion pop or standard. If you s...
Page 501
Chapter 2: coldfusion functions 477 is a valid date the date, parsed for use as a date/time value: #parsedatetime(form.Thetestvalue)# ....
Page 502
478 cfml language reference pi returns the number 3.14159265358979, the mathematical constant π , accurate to 15 digits. See also asin , cos , sin , and tan . Syntax pi() examples pi example returns the number #numberformat(pi(), ‘_._______________’)# , the mathematical constant pi, accurate to 15 d...
Page 503
Chapter 2: coldfusion functions 479 preservesinglequotes prevents coldfusion from automatically “escaping” single quotes contained in variable. Syntax preservesinglequotes( variable ) variable variable containing the string for which single quotes are preserved. Usage preservesinglequotes is useful ...
Page 504
480 cfml language reference quarter returns the number of the quarter, an integer ranging from 1 to 4. See also datepart and month . Syntax quarter( date ) date any date. Usage years from 0 to 29 are interpreted as 21 st century values. Years 30 to 99 are interpreted as 20 th century values. When pa...
Page 505
Chapter 2: coldfusion functions 481 queryaddcolumn adds a new column to a specified query and populates the column’s rows with the contents of a one-dimensional array. Returns the query object with the additional column. Padding is added, if necessary, on the query columns to ensure that all columns...
Page 506
482 cfml language reference after populating the query, the example shows, in tabular format, the contents of the columns. Fastfoodarray)> finecuisinearray)> healthfoodarray)> fast food fine cuisine health food #fastfood# #finecuisine# #healthfood# note: because there are fewer elements in the fine ...
Page 507
Chapter 2: coldfusion functions 483 queryaddrow adds a specified number of empty rows to the specified query. Returns the total number of rows in the query that you are adding rows to. See also querynew , queryaddcolumn and querysetcell . Syntax queryaddrow( query [, number ]) query name of the quer...
Page 508
484 cfml language reference querynew returns an empty query with a set of columns or an empty query with no columns. See usage for more information. See also queryaddcolumn , queryaddrow and querysetcell . Syntax querynew( columnlist ) columnlist comma-separated list of columns you want to add to th...
Page 509
Chapter 2: coldfusion functions 485 querysetcell sets the cell in a specified column to a specified value. If no row number is specified, the cell on the last row will be set. Returns true. See also queryaddcolumn and queryaddrow . Syntax querysetcell( query , column_name , value [, row_number ]) qu...
Page 510
486 cfml language reference "description of variable #countvar#")> after the queryaddrow action, the query has #getcourses.Recordcount# records..
Page 511
Chapter 2: coldfusion functions 487 quotedvaluelist returns a comma-separated list of the values of each record returned from a previously executed query. Each value in the list is enclosed in single quotes. See also valuelist . Syntax quotedvaluelist( query.Column [, delimiter ]) query.Column name ...
Page 512
488 cfml language reference rand returns a random decimal number in the range 0 to 1. See also randomize and randrange . Syntax rand() usage to ensure even greater randomness, call randomize before calling rand. Example rand example rand() returns a random number in the range 0 to 1. Rand() returned...
Page 513
Chapter 2: coldfusion functions 489 randomize seeds the random number generator in coldfusion with the integer part of a number. By seeding the random number generator with a variable value, you help to ensure that the rand function generates highly random numbers. See also rand and randrange . Synt...
Page 514
490 cfml language reference randrange returns a random integer between two specified numbers. Note that requests for random integers greater than 100,000,000 will result in non-random behavior. This restriction prevents overflow during internal computations. See also rand and randomize . Syntax rand...
Page 515
Chapter 2: coldfusion functions 491 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. This search is case sensitive. Returns the position and length of the first occurrence of a regular...
Page 516
492 cfml language reference length of the first instance of each subexpression within the regular expression are returned in subsequent elements of the arrays. Examples refind example this example demonstrates the use of the refind function with and without the returnsubexpressions parameter set to ...
Page 517
Chapter 2: coldfusion functions 493 in order to create this structure you can use a cfset statement, for example: 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 in the regular expression. The...
Page 518
494 cfml language reference refindnocase returns the position of the first occurrence of a regular expression in a string starting from the specified position if the returnsubexpressions parameter is not set to true. Returns 0 if no occurrences are found.The search is case-insensitive. Returns the p...
Page 519
Chapter 2: coldfusion functions 495 length of the first instance of each subexpression within the regular expression are returned in subsequent elements of the arrays. Examples refindnocase example this example demonstrates the use of the refindnocase function with and without the returnsubexpressio...
Page 520
496 cfml language reference in order to create this structure you can use a cfset statement, for example: 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 regula...
Page 521
Chapter 2: coldfusion functions 497 removechars returns string with count characters removed from the specified starting position. Return 0 if no characters are found. See also insert and len . Syntax removechars( string , start , count ) string any string. Start starting position for the search. Co...
Page 522
498 cfml language reference repeatstring returns a string created from string being repeated a specified number of times. See also cjustify , ljustify , and rjustify . Syntax repeatstring( string , count ) string string being repeated. Count number of repeats. Examples repeatstring example repeatstr...
Page 523
Chapter 2: coldfusion functions 499 replace returns string with occurrences of substring1 being replaced with substring2 in the specified scope. See also find , replacenocase , replacelist , and rereplace . Syntax replace( string , substring1 , substring2 [, scope ]) string any string. Substring1 st...
Page 524
500 cfml language reference replacelist returns string with all occurrences of the elements from the specified comma- delimited list being replaced with their corresponding elements from another comma- delimited list. The search is case-sensitive. See also find , replace, and rereplace . Syntax repl...
Page 525
Chapter 2: coldfusion functions 501 string 1 substring 1 (find this list of substrings) substring 2 (replace with this list of substrings).
Page 526
502 cfml language reference replacenocase returns string with occurrences of substring1 being replaced regardless of case matching with substring2 in the specified scope. See also find , replace , replacelist, and rereplace . Syntax replacenocase( string , substring1 , substring2 [, scope ]) string ...
Page 527
Chapter 2: coldfusion functions 503 rereplace returns string with a regular expression being replaced with substring in the specified scope. This is a case-sensitive search. See also refind , replace, replacelist , and rereplacenocase . Syntax rereplace( string , reg_expression , substring [, scope ...
Page 528
504 cfml language reference rereplacenocase returns string with a regular expression being replaced with substring in the specified scope. The search is case-insensitive. See also refind , refindnocase , replace, and replacelist . Syntax rereplacenocase( string , reg_expression , substring [, scope ...
Page 529
Chapter 2: coldfusion functions 505 reverse returns string with reversed order of characters. See also left , mid, and right . Syntax reverse( string ) string string being reversed. Examples reverse example reverse returns your string with the positions of the characters reversed. Reverse returned: ...
Page 530
506 cfml language reference right returns the rightmost count characters of a string. See also left , len, and mid . Syntax right( string , count ) string string from which the rightmost characters are retrieved. Count integer indicating how many characters to return. Examples right example your str...
Page 531
Chapter 2: coldfusion functions 507 rjustify returns right-justified string in the specified field length. See also cjustify and ljustify . Syntax rjustify( string , length ) string string to be right-justified. Length length of field. Example rjustify example enter a string, and it will be right ju...
Page 532
508 cfml language reference round rounds a number to the closest integer. See also ceiling , fix, and int . Syntax round( number ) number number being rounded. Examples round example this function rounds a number to the closest integer. #evaluate(round(1.2345*100)/100)#.
Page 533
Chapter 2: coldfusion functions 509 rtrim returns string with removed trailing spaces. See also ltrim and trim . Syntax rtrim( string ) string string being right-trimmed. Examples rtrim example your string:"#form.Mytext#" your string:"#rtrim(form.Mytext)#" (right trimmed) type in some text, and it w...
Page 534
510 cfml language reference second for a date/time value, returns the ordinal for the second, an integer from 0 to 59. See also datepart , hour, and minute . Syntax second( date ) date any date. Usage when passing a date/time value as a string, make sure it is enclosed in quotes. Otherwise, it is in...
Page 535
Chapter 2: coldfusion functions 511 setlocale sets the locale to the specified new locale for the current session. Note setlocale returns the old locale in case it needs to be restored. See also getlocale . Syntax setlocale( new_locale) new_locale the name of the locale you want to set. Locale suppo...
Page 536
512 cfml language reference setlocale sets the locale to the specified new locale for the current session. A locale is an encapsulation of the set of attributes that govern the display and formatting of international date, time, number, and currency values. The locale for this system is #getlocale()...
Page 537
Chapter 2: coldfusion functions 513 setprofilestring sets the value of a profile entry in an initialization file. This function returns an empty string if the operation succeeds or an error message if the operation fails. See also getprofilestring . Syntax setprofilestring( inipath, section, entry, ...
Page 538
514 cfml language reference setting the timeout value to #mytimeout# cfoutput> mytimeout)> value returned from setprofilestring: #code# cfoutput> mytimeout)> value returned from setprofilestring: #code# cfoutput> timeout value should be greater than zero in order to provide time for user response. T...
Page 539
Chapter 2: coldfusion functions 515 setvariable the function sets the variable specified by name to value and returns the new value of the variable. See also deleteclientvariable and getclientvariableslist . Syntax setvariable( name , value ) name valid variable name. Value string or number assigned...
Page 540
516 cfml language reference sgn determines the sign of a number. Returns 1 if number is positive; 0 if number is 0; and -1 if number is negative. See also abs . Syntax sgn( number ) number any number. Examples sgn determines the sign of a number. Returns 1 if number is positive; 0 if number is 0; an...
Page 541
Chapter 2: coldfusion functions 517 sin returns the sine of the given angle. See also asin , atn , cos , pi, and tan . Syntax sin( number ) number angle in radians for which you want the sine. If the angle is in degrees, multiply it by pi()/180 to convert it to radians. Examples sin example sin(#for...
Page 542
518 cfml language reference spanexcluding returns all characters from string from its beginning until it reaches a character from the set of characters. The search is case-sensitive. See also gettoken and spanincluding . Syntax spanexcluding( string , set ) string any string. Set string containing o...
Page 543
Chapter 2: coldfusion functions 519 spanincluding returns all characters from string from its beginning until it reaches a character that is not included in the specified set of characters. The search is case-sensitive. See also gettoken and spanexcluding . Syntax spanincluding( string , set ) strin...
Page 544
520 cfml language reference sqr returns a positive square root. See also abs . Syntax sqr( number ) number number for which you want the square root. Usage number must be greater than or equal to 0. Examples sqr example returns a positive square root for a number. Sqr(2): #sqr(2)# sqr(abs(-144)):#sq...
Page 545
Chapter 2: coldfusion functions 521 stripcr returns string with all carriage return characters removed. See also paragraphformat . Syntax stripcr( string ) string string being formatted. Usage function stripcr is useful for preformatted html display of data (pre) entered into textarea fields. Exampl...
Page 546
522 cfml language reference structclear removes all data from the specified structure. Always returns yes. See also structdelete , structfind , structinsert , structisempty , structkeyarray , structcount , structkeyarray , and structupdate . Syntax structclear( structure ) structure structure to be ...
Page 547
Chapter 2: coldfusion functions 523 structcopy returns a new structure with all the keys and values of the specified structure. See also structclear , structdelete , structfind , structinsert , structisempty , structkeyarray , structkeyarray , and structupdate . Syntax structcopy( structure ) struct...
Page 548
524 cfml language reference structcount returns the number of keys in the specified structure. See also structclear , structdelete , structfind , structinsert , structisempty , structkeyarray , structkeyarray , and structupdate . Syntax structcount( structure ) structure structure to be accessed. Us...
Page 549
Chapter 2: coldfusion functions 525 structdelete removes the specified item from the specified structure. See also structclear , structfind , structinsert , structisempty , structkeyarray , structcount , structkeyarray , and structupdate . Syntax structdelete( structure , key [, indicatenotexisting ...
Page 550
526 cfml language reference employee is a structure: #isstruct(employee)# did i delete the field "#form.Field#"? The code indicates: #rc# select the field to be deleted: first name last name email phone department.
Page 551
Chapter 2: coldfusion functions 527 structfind returns the value associated with the specified key in the specified structure. See also structclear , structdelete , structinsert , structisempty , structkeyarray , structcount , structkeyarray , and structupdate . Syntax structfind( structure , key ) ...
Page 552
528 cfml language reference structinsert inserts the specified key-value pair into the specified structure. Returns yes if the insert was successful and no if an error occurs. See also structclear , structdelete , structfind , structisempty , structkeyarray , structcount , structkeyarray , and struc...
Page 553
Chapter 2: coldfusion functions 529 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 #stru...
Page 554
530 cfml language reference structisempty indicates whether the specified structure contains data. Returns true if structure is empty and false if it contains data. See also structclear , structdelete , structfind , structinsert , structkeyarray , structcount , structkeyarray , and structupdate . Sy...
Page 555
Chapter 2: coldfusion functions 531 structkeyarray returns an array of the keys in the specified coldfusion structure. See also structclear , structdelete , structfind , structinsert , structisempty , structkeylist , structkeyexists , structcount , and structupdate . Syntax structkeyarray( structure...
Page 556
532 cfml language reference this example uses the structnew function to create a structure that supplies employee information. The data structure is called "employee" and its fields are filled with the contents of the following form. After you have entered employee information into the structure, th...
Page 557
Chapter 2: coldfusion functions 533 value#i# is #employee[keystostruct[i]]#.
Page 558
534 cfml language reference structkeyexists returns true if the specified key is in the specified structure and false if it is not. See also structclear , structdelete , structfind , structinsert , structisempty , structcount , structkeyarray , and structupdate . Syntax structkeyexists( structure , ...
Page 559
Chapter 2: coldfusion functions 535 structkeylist returns the list of keys that are in the specified coldfusion structure. See also structkeyarray , structclear , structdelete , structfind , structinsert , structisempty , structcount , and structupdate . Syntax structkeylist( structure , [ delimiter...
Page 560
536 cfml language reference this example uses the structnew function to create a structure that supplies employee information. The data structure is called "employee" and its fields are filled with the contents of the following form. After you have entered employee information into the structure, th...
Page 561
Chapter 2: coldfusion functions 537 ")> here are the keys to the structure: #keystostruct# if these fields are correct, we can process your new employee information. If they are not correct, you should consider rewriting your application..
Page 562
538 cfml language reference structnew returns a new structure. See also structclear , structdelete , structfind , structinsert , structisempty , structkeyarray , structcount , and structupdate . Syntax structnew() example please fill out the form. Employee=structnew(); structinsert(employee, "firstn...
Page 563
Chapter 2: coldfusion functions 539 structupdate updates the specified key with the specified value. Returns yes if the function is successful and throws an exception if an error occurs. See also structclear , structdelete , structfind , structinsert , structisempty , structkeyarray , structcount , ...
Page 564
540 cfml language reference tan returns the tangent of a given angle. See also atn , asin , cos , sin, and pi . Syntax tan( number ) number angle in radians for which you want the tangent. If the angle is in degrees, multiply it by pi()/180 to convert it to radians. Examples tan example returns the ...
Page 565
Chapter 2: coldfusion functions 541 timeformat returns a custom-formatted time value. If no mask is specified, the timeformat function returns time value using the hh:mm tt format. See also createtime , now, and parsedatetime . Syntax timeformat( time [, mask ]) time any date/time value or string co...
Page 566
542 cfml language reference using timeformat, we can display that date/time value in a number of different ways:.
Page 567
Chapter 2: coldfusion functions 543 tobase64 returns the base 64 representation of the string or binary object. Base64 is a format that uses printable characters, allowing binary data to be sent in forms and email, and stored in a database or file. See also cffile for information about loading and r...
Page 568
544 cfml language reference #chardata#.
Page 569
Chapter 2: coldfusion functions 545 tobinary returns the binary representation of base64 encoded data. See cffile for information about loading and reading binary data, cfwddx for information about serializing and deserializing binary data, and isbinary and tobase64 for checking for binary data and ...
Page 570
546 cfml language reference representation of string data..
Page 571
Chapter 2: coldfusion functions 547 tostring attempts to convert a value of any type, including a binary value, into a string. Syntax tostring( any_value ) any_value the value that is to be converted into a string. Usage if tostring cannot convert the value into a string, it throws an exception. All...
Page 572
548 cfml language reference the following is the string representation of the binary data. #datastring#.
Page 573
Chapter 2: coldfusion functions 549 trim returns string with both leading and trailing spaces removed. See also ltrim and rtrim . Syntax trim( string ) string string being trimmed. Examples trim example your string:"#form.Mytext#" your string:"#trim(form.Mytext)#" (trimmed on both sides) type in som...
Page 574
550 cfml language reference ucase returns string converted to uppercase. See also lcase . Syntax ucase( string ) string string being converted to uppercase. Examples ucase example your text, #form.Sampletext#, returned in uppercase is #ucase(form.Sampletext)# . Please enter some text. Enter your sam...
Page 575
Chapter 2: coldfusion functions 551 urldecode decodes a url-encoded string. See also urlencodedformat . Syntax 85/'hfrghxuo(qfrghg6wulqj urlencodedstring a string that has been url-encoded. Usage url encoding refers to a data format where all high ascii and non-alphanumeric characters are encoded us...
Page 576
552 cfml language reference urlencodedformat returns a url-encoded string. Spaces are replaced with + and all non-alphanumeric characters with equivalent hexadecimal escape sequences. This function enables you to pass arbitrary strings within a url, because coldfusion automatically decodes all url p...
Page 577
Chapter 2: coldfusion functions 553 val returns a number that the beginning of a string can be converted to. Returns 0 if conversion is not possible. See also isnumeric . Syntax val( string ) string any string. Examples val example can be converted to a number: #val(form.Thetestvalue)# enter a strin...
Page 578
554 cfml language reference valuelist returns a comma-separated list of the values of each record returned from a previously executed query. See also quotedvaluelist . Syntax valuelist( query.Column [, delimiter ]) query.Column name of an already executed query and column. Separate query name and co...
Page 579
Chapter 2: coldfusion functions 555 week returns the ordinal for the week number in a year; an integer ranging from 1 to 53. See also datepart . Syntax week( date ) date any date/time value or string convertible to date. Usage years from 0 to 29 are interpreted as 21 st century values. Years 30 to 9...
Page 580
556 cfml language reference writeoutput appends text to the page output stream. Although you can call this function anywhere within a page, it is most useful inside a cfscript block. Note when within the cfquery and cfmail tags, the writeoutput function does not output to the current page, but inste...
Page 581
Chapter 2: coldfusion functions 557 xmlformat returns a string that is safe to use with xml. Syntax xmlformat( string ) string any string. Usage xmlformat escapes special xml characters so that you can put arbitrary strings safely into xml. The characters that are escaped by xmlformat include the fo...
Page 582
558 cfml language reference year returns the year corresponding to date. See also datepart and isleapyear . Syntax year( date ) date any date/time value or string convertible to date. Usage years from 0 to 29 are interpreted as 21 st century values. Years 30 to 99 are interpreted as 20 th century va...
Page 583
Chapter 2: coldfusion functions 559 yesnoformat returns boolean data as yes or no. See also isbinary and isnumeric . Syntax yesnoformat( value ) value any number or boolean value. Usage the yesnoformat function returns all non-zero values as yes and zero values as no. Examples the yesnoformat functi...
Page 584
560 cfml language reference.
Page 585: Wddx Javascript Objects
C h a p t e r 3 chapter 3 wddx javascript objects this chapter provides information about javascript objects and functions used when implementing wddx in a coldfusion application. Contents • wddxserializer object.................................................................................... 562...
Page 586: Wddxserializer Object
562 cfml language reference wddxserializer object the wddxserializer object includes functions that serialize any javascript data structure. The only function that developers typically call is serialize. Serialize creates a wddx packet for a passed wddxrecordset instance. Syntax object .Serialize( r...
Page 587
Chapter 3: wddx javascript objects 563 object instance name of the wddxserializer object. Name property to be serialized. Obj instance name of the value to be serialized. Return value boolean. Returns true if serialization was successful and false if an error occurs. Usage internal. You do not typic...
Page 588
564 cfml language reference object instance name of the wddxserializer object. Obj instance name of the wddxrecordset object to be serialized. Return value boolean. Returns true if obj was serialized successfully and false if an error occurs. Usage internal. You do not typically call this function. ...
Page 589: Wddxrecordset Object
Chapter 3: wddx javascript objects 565 ... Else if (typeof(obj) == "number") { // number value this.Write("" + obj + ""); } else if (typeof(obj) == "boolean") { // boolean value this.Write(""); } ... Wddxrecordset object the wddxrecordset object includes functions that you call as needed when constr...
Page 590
566 cfml language reference // newvalue is a previously defined variable rs.Setfield(0, "newcolumn", newvalue); addrows adds the specified number of rows to all columns in the wddxrecordset instance. Syntax object .Addrows( n ) object instance name of the wddxrecordset object. N integer specifying t...
Page 591
Chapter 3: wddx javascript objects 567 col integer or string specifying the 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 the getfield function (the ...
Page 592
568 cfml language reference setfield sets the element in the specified row/column position. Syntax object .Setfield( row , col , value ) object instance name of the wddxrecordset object. Row integer specifying the row containing the element to be set. Col integer or string specifying the column cont...
Page 593
Chapter 3: wddx javascript objects 569 wddxserializer instance. Return value boolean. Returns true if serialization was successful and false if an error occurs. Usage internal. You do not typically call this function. Example this example is from the wddxserializer serializevalue function: ... Else ...
Page 594
570 cfml language reference.
Page 595: Coldfusion Expressions:
C h a p t e r 4 chapter 4 coldfusion expressions: operators and other constructs this chapter describes coldfusion expressions — language constructs that allow you to create sophisticated applications. Contents • elements of coldfusion expressions .......................................................
Page 596
572 cfml language reference elements of coldfusion expressions the following objects can be used to build expressions: objects used to build coldfusion expressions type description integers numbers with no decimal point. Real numbers numbers with a decimal part. Also known as floating point numbers....
Page 597
Chapter 4: coldfusion expressions: operators and other constructs 573 time values you can directly enter a date-and-time object in any of the following formats: "october 30, 1999 02:34:12" "october 30, 1999 2:34a" "october 30, 1999 2:34am" "october 30, 1999 02:34am" "october 30, 1999 2am" the time p...
Page 598
574 cfml language reference notes on date-and-time values there are a variety of ways in which a date-and-time value can be entered in coldfusion. You can use the functions that create date-and-time objects using various criteria. (see chapter 2 for information about date-and-time functions.) querie...
Page 599
Chapter 4: coldfusion expressions: operators and other constructs 575 21 st century dates two-digit years from 00 to 29 are treated as 21 st century dates; 30 to 99 are treated as 20 th century dates. "october 30, 2015" "october 30, 15" note internally to coldfusion, date-and-time values are represe...
Page 600: Operators
576 cfml language reference (client.Myvariable). Qualifiers are also known as scopes. Thus myvariable is said to belong to the form scope. In some cases, a variable must have pounds signs around it to allow coldfusion to distinguish it from string or html text and to insert its value as opposed to i...
Page 601
Chapter 4: coldfusion expressions: operators and other constructs 577 string operators the is only one string operator, which is the concatenation operator. Decision, or comparison, operators coldfusion’s decision, or comparison, operators produce a boolean true/false. \ divides two integer values. ...
Page 602
578 cfml language reference shorthand notation for boolean operators you can replace some boolean operators with shorthand notations to make your cfml more compact, as shown in the following table: greater than or equal to checks to see if the value on the left is greater than or equal to the value ...
Page 603: Operator Precedence
Chapter 4: coldfusion expressions: operators and other constructs 579 boolean operators boolean, or logical, operators perform logical connective and negation operations. The operands of boolean operators are boolean (true/false) values. Operator precedence the order of precedence controls which ope...
Page 604: Function Syntax
580 cfml language reference xor eqv imp to enforce a specific non-standard order of evaluation, you must parenthesize expressions. For example: • 6 - 3 * 2 is equal to 0 • (6 - 3) * 2 is equal to 6 parenthesized expressions can be arbitrarily nested. When in doubt about the order in which operators ...
Page 605: Pound Signs
Chapter 4: coldfusion expressions: operators and other constructs 581 pound signs pound signs (#) have special meaning in coldfusion. When a cfml application page is processed, coldfusion treats text delimited by pound signs differently from plain text. Two simple and very important points about pou...
Page 606
582 cfml language reference complex expressions complex expressions involving one or more operators cannot be inserted inside cfoutput tags. The following example will produce an error. 1 + 1 is #1 + 1# to insert the value of a complex expression in the output generated by a cfoutput statement, use ...
Page 607
Chapter 4: coldfusion expressions: operators and other constructs 583 to insert the value of a complex expression inside a string, use cfset to set some variable to the value of the expression and use that variable inside the string, or use the string concatenation operator: to insert the pound char...
Page 608
584 cfml language reference all of the above statements result in errors. As a general rule, never put pound signs around function arguments. Pound signs in general expressions allaire recommends that pound signs be used only where necessary. The following example demonstrates the preferred method f...