User Guide

Manuals Brands Macromedia Manuals Other COLFUSION MX 7

Table Of Contents

COLDFUSION

MX 7

ColdFusion MX Developer’s Guide

Summary of content (1140 pages)

PAGE 1

COLDFUSION MX 7 ® ColdFusion MX Developer’s Guide
PAGE 2

Trademarks 1 Step RoboPDF, ActiveEdit, ActiveTest, Authorware, Blue Sky Software, Blue Sky, Breeze, Breezo, Captivate, Central, ColdFusion, Contribute, Database Explorer, Director, Dreamweaver, Fireworks, Flash, FlashCast, FlashHelp, Flash Lite, FlashPaper, Flex, Flex Builder, Fontographer, FreeHand, Generator, HomeSite, JRun, MacRecorder, Macromedia, MXML, RoboEngine, RoboHelp, RoboInfo, RoboPDF, Roundtrip, Roundtrip HTML, Shockwave, SoundEdit, Studio MX, UltraDev, and WebHelp are either registered tradema
PAGE 3

CONTENTS INTRODUCTION: About ColdFusion MX Documentation . . . . . . . . . . . . . . . . . . 13 Using this manual . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 CHAPTER 1: Introducing ColdFusion MX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 About Internet applications and web application servers . . . . . . . . . . . . . . . . . . . . 19 About ColdFusion MX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
PAGE 4

About scopes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64 Ensuring variable existence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70 Validating data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73 Passing variables to custom tags and UDFs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73 CHAPTER 4: Using Expressions and Number Signs .
PAGE 5

CHAPTER 9: Writing and Calling User-Defined Functions. . . . . . . . . . . . . . . . . 171 About user-defined functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171 Creating user-defined functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172 Calling user-defined functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178 Working with arguments and variables in functions . . . . . . . . . . . . . . . . . .
PAGE 6

CHAPTER 14: Handling Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 307 About error handling in ColdFusion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 307 Understanding errors. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 308 Error messages and the standard error format . . . . . . . . . . . . . . . . . . . . . . . . . . . 314 Determining error-handling strategies . . . . . . . . . . . . . . . . . . .
PAGE 7

PART IV: Accessing and Using Data CHAPTER 19: Introduction to Databases and SQL . . . . . . . . . . . . . . . . . . . . . . 447 What is a database? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 447 Using SQL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 452 Writing queries using an editor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
PAGE 8

CHAPTER 25: Using Verity Search Expressions . . . . . . . . . . . . . . . . . . . . . . . . 581 About Verity query types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 581 Using simple queries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 582 Using explicit queries. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 583 Using natural queries. . . . . . . . . . . . . . . . . . . . . .
PAGE 9

CHAPTER 30: Creating Skinnable XML Forms . . . . . . . . . . . . . . . . . . . . . . . . . 709 About XML skinnable forms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Building XML skinnable forms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ColdFusion XML format. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Creating XSLT skins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
PAGE 10

PART VI: Using Web Elements and External Objects CHAPTER 35: Using XML and WDDX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 843 About XML and ColdFusion. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 843 The XML document object. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 844 ColdFusion XML tag and functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 850 Using an XML object . . . . . . . . . .
PAGE 11

PART VII: Using External Resources CHAPTER 39: Sending and Receiving E-Mail . . . . . . . . . . . . . . . . . . . . . . . . . . 973 Using ColdFusion with mail servers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Sending e-mail messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Sample uses of the cfmail tag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using the cfmailparam tag. . . . . . . . . . . . . . .
PAGE 12

CHAPTER 44: Using the SMS Event Gateway . . . . . . . . . . . . . . . . . . . . . . . . 1065 About SMS and ColdFusion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1065 Configuring an SMS event gateway. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1071 Handling incoming messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1073 Sending outgoing messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
PAGE 13

INTRODUCTION About ColdFusion MX Documentation ColdFusion MX Developer’s Guide provides the tools needed to develop Internet applications using Macromedia ColdFusion MX. This manual is intended for web application programmers who are learning ColdFusion MX or wish to extended their ColdFusion MX programming knowledge. It provides a solid grounding in the tools that ColdFusion MX provides to develop web applications.
PAGE 14

Beginning with ColdFusion If you are learning ColdFusion, it might be most effective to read this manual in the following order: 1. Chapter 1, “Introducing ColdFusion MX” through Chapter 4, “Using Expressions and Number Signs” to learn the basics of CFML. 2. Chapter 19, “Introduction to Databases and SQL” through Chapter 21, “Updating Your Database” to learn about using databases. 3.
PAGE 15

• • • • Chapter 42, “Using Event Gateways” Chapter 43, “Using the Instant Messaging Event Gateways” Chapter 44, “Using the SMS Event Gateway” Chapter 45, “Creating Custom Event Gateways” Nearly all chapters contain information that is new in ColdFusion MX 7, so you should also review all other chapters for useful information. The index and the table of contents are useful tools for finding new features or changed documentation. Note: If you are moving from ColdFusion 4.
PAGE 16

Feature Description Chapters ColdFusion application structure 13–17 ColdFusion supports many ways of building an application, and includes specific features, such as the Application.cfc file or Application.cfm page, built-in security features, and shared scopes, that help you optimize your application structure. Error handling mechanisms ColdFusion provides several mechanisms for handling data, including custom error pages and exception-handling tags and functions, such as cftry and cfcatch.
PAGE 17

Feature Description Chapters XML skinnable forms ColdFusion can convert your CFML forms into XML and format the 30 XML using XSLT skins and style sheets. Data graphing You can use the cfchart tag to display your data graphically. 31 Reports and printable output You can create output that is formatted for print as PDF or FlashPaper documents. You can also use ColdFusion reporting to create banded reports for display or printing.
PAGE 18

Feature Description Chapters SMS event gateway 44 Your ColdFusion MX application can communicate with short message service (SMS) devices, such as mobile phones, using the ColdFusion SMS event gateway. Creating gateways You can write your own event gateways in Java and integrate them 45 into ColdFusion MX. Accessing the ColdFusion MX documentation The ColdFusion MX documentation is designed to provide support for the complete spectrum of participants.
PAGE 19

CHAPTER 1 Introducing ColdFusion MX This chapter describes Macromedia ColdFusion MX and the role it plays in developing dynamic Internet applications. This chapter also introduces the topics discussed in this manual. Contents About Internet applications and web application servers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 About ColdFusion MX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
PAGE 20

ColdFusion MX is a rapid application development environment that lets you build dynamic websites and Internet applications quickly and easily. It lets you develop sophisticated websites and Internet applications without knowing the details of many complex technologies, yet it lets advanced developers take advantage of the full capabilities of many of the latest Internet technologies. About web application servers To understand ColdFusion, you must first understand the role of web application servers.
PAGE 21

How a web server and web application server work together The following steps explain how a web server and web application server work together to process a page request: 1. The user requests a page by typing a URL in a browser, and the web server receives the request. 2. The web server looks at the file extension to determine whether a web application server must process the page.
PAGE 22

About ColdFusion MX ColdFusion MX is a rapid scripting environment server for creating dynamic Internet Applications. ColdFusion Markup Language (CFML) is an easy-to-learn tag-based scripting language, with connectivity to enterprise data and powerful built-in search and charting capabilities. ColdFusion MX enables developers to easily build and deploy dynamic websites, content publishing systems, self-service applications, commerce sites, and more.
PAGE 23

CFML includes approximately 110 tags. ColdFusion tags serve many functions. They provide programming constructs, such as conditional processing and loop structures. They also provide services, such as charting and graphing, full-text search, access to protocols such as FTP, SMTP/ POP, and HTTP, and much more.
PAGE 24

Verity Search Server The Verity Search Server (also called the Verity search engine) provides full text search capability for documents and data on a ColdFusion MX site. ColdFusion MX Administrator ColdFusion MX Administrator configures and manages the ColdFusion application server. It is a secure web-based application that you can access using any web browser, from any computer with an Internet connection.
PAGE 25

This part describes the elements of the CFML programming language. It tells you how to use CFML tags, functions, variables and expressions, the CFScript scripting language, and regular expressions. The following chapters are included: Chapter 2: Elements of CFML. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27 Chapter 3: Using ColdFusion Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
PAGE 26
PAGE 27

CHAPTER 2 Elements of CFML This chapter provides an overview of the basic elements of CFML, including tags, functions, constants, variables, expressions, and CFScript. The chapters in Part I of this manual describe these topics in detail. Contents CFML Basics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28 Comments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
PAGE 28

CFML Basics This chapter introduces and describes the basic elements of CFML. These elements make CFML a powerful tool for developing interactive web applications.
PAGE 29

Note: You cannot embed comments inside a tag name or function name, such as CustomTag>. You also cannot embed comments inside strings, as in the following example: IsDefined("MyVariable"). Tags ColdFusion tags tell the ColdFusion server that it must process information. The ColdFusion server only processes tag contents; it returns text outside of ColdFusion to the web server unchanged.
PAGE 30

• Using external tools and objects, including Verity collections, COM, Java, and CORBA objects, and executable programs • Using protocols, such as mail, http, ftp, and pop Much of this document describes how to use these tags effectively. CFML Reference documents each tag in detail. Custom tags ColdFusion lets you create custom tags.
PAGE 31

Functions Functions typically manipulate data and return a result. CFML includes over 280 built-in functions. You can also create user-defined functions (UDFs), sometimes referred to as custom functions. Functions have the following general form: functionName([argument1[, argument2]]...) Some functions, such as the Now function take no arguments. Other functions require one or more comma-separated arguments and can have additional optional arguments. All ColdFusion functions return a value.
PAGE 32

User-defined functions You can write your own functions, user-defined functions (UDFs). You can use these functions in ColdFusion expressions or in CFScript. You can call a user-defined function anywhere you can use a built-in CFML function. You create UDFs using the cffunction tag or the CFScript function statement. UDFs that you create using the cffunction tag can include ColdFusion tags and functions. UDFs that you create in CFScript can only include functions.
PAGE 33

Variables Variables are the most frequently used operands in ColdFusion expressions. Variable values can be set and reset, and can be passed as attributes to CFML tags. Variables can be passed as parameters to functions, and can replace most constants. ColdFusion has a number of built-in variables that provide information about the server and are returned by ColdFusion tags. For a list of the ColdFusion built-in variables, see Chapter 1, “Reserved Words and Variables” in CFML Reference.
PAGE 34

Scope Description Client Variables that are associated with one client. Client variables let you maintain state as a user moves from page to page in an application and are available across browser sessions. Session Variables that are associated with one client and persist only as long as the client maintains a session. Application Variables that are associated with one, named, application on a server. The Application.
PAGE 35

Data types ColdFusion is considered typeless because you do not explicitly specify variable data types. However, ColdFusion data, the constants and the data that variables represent, do have data types, which correspond to the ways the data is stored on the computer. ColdFusion data belongs to the following type categories: Category Description and types Simple Represents one value. You can use simple data types directly in ColdFusion expressions.
PAGE 36

This section provides a basic introduction to using flow-control tags. CFScript also provides a set of flow-control statements. For information on using flow-control statements in CFScript, see Chapter 6, “Extending ColdFusion Pages with CFML Scripting,” on page 123. For more details on using flow-control tags, see the reference pages for these tags in CFML Reference. cfif, cfelseif, and cfelse The cfif, cfelseif, and cfelse tags provide if-then-else conditional processing, as follows: 1.
PAGE 37

The following example shows switch processing: #FirstName# #LastName# is in Sales

#FirstName# #LastName# is in Accounting

#FirstName# #LastName# is in Administration

#FirstName# #LastName# is not in Sales, Accounting, or Administration.
PAGE 38

i is #i#
foundit is #foundit#
Note: You can get an infinite conditional loop if you do not force an end condition.
PAGE 39

Character case ColdFusion is case-insensitive. For example, the following all represent the cfset tag: cfset, CFSET, CFSet, and even cfsEt. However, you should get in the habit of consistently using the same case rules in your programs; for example: • Develop consistent rules for case use, and stick to them. If you use lowercase characters for some tag names, use them for all tag names. • Always use the same case for a variable.
PAGE 40

• Built-in function names, such as Now or Hash • Scope names, such as Form or Session • Any name starting with cf. However, when you call a CFML custom tag directly, you prefix the custom tag page name with cf_.
PAGE 41

{ if(Find("key",strings[i],1)) break; } Entry #i# starts with "key"
You use CFScript to create user-defined functions. For more information on CFScript, see Chapter 6, “Extending ColdFusion Pages with CFML Scripting,” on page 123. For more information on user-defined functions, see Chapter 9, “Writing and Calling User-Defined Functions,” on page 171.
PAGE 42

Chapter 2: Elements of CFML
PAGE 43

CHAPTER 3 Using ColdFusion Variables Macromedia ColdFusion variables are the most frequently used operands in ColdFusion expressions. Variable values can be set and reset, and can be passed as attributes to CFML tags. Variables can be passed as parameters to functions, and can replace most constants. This chapter describes how to create and use ColdFusion variables.
PAGE 44

Creating variables You create most ColdFusion variables by assigning them values. (You must use the ArrayNew function to create arrays.) Most commonly, you create variables by using the cfset tag. You can also use the cfparam tag, and assignment statements in CFScript. Tags that create data objects also create variables. For example, the cfquery tag creates a query object variable. ColdFusion automatically creates some variables that provide information about the results of certain tags or operations.
PAGE 45

Note: In some cases, when you use an existing variable name, you must enclose it with number signs (#) to allow ColdFusion to distinguish it from string or HTML text, and to insert its value, as opposed to its name. For more information, see Chapter 4, “Using number signs,” on page 81.
PAGE 46

Object type See ColdFusion component Chapter 10, “Building and Using ColdFusion Components,” on page 201 Web service Chapter 36, “Using Web Services,” on page 885 Data type notes Although ColdFusion variables do not have types, it is often convenient to use “variable type” as a shorthand for the type of data that the variable represents. ColdFusion can validate the type of data contained in form fields and query parameters.
PAGE 47

Integers ColdFusion supports integers between -2,147,483,648 and 2,147,483,647 (32-bit signed integers). You can assign a value outside this range to a variable, but ColdFusion initially stores the number as a string.
PAGE 48

Escaping quotation marks and number signs To include a single-quotation character in a string that is single-quoted, use two single-quotation marks (known as escaping the single-quotation mark).
PAGE 49

Boolean values A Boolean value represents whether something is true or false. ColdFusion has two special constants—True and False—to represent these values. For example, the Boolean expression 1 IS 1 evaluates to True. The expression "Monkey" CONTAINS "Money" evaluates to False.
PAGE 50

Date and time formats You can directly enter a date, time, or date and time, using standard U.S. date formats. ColdFusion processes the two-digit-year values 0 to 29 as twenty-first century dates; it processes the two-digit-year values 30 to 99 as twentieth century dates. Time values can include units down to seconds. The following table lists valid date and time formats: To specify Use these formats Date October 30, 2003 Oct 30, 2003 Oct.
PAGE 51

How ColdFusion stores dates and times ColdFusion stores and manipulates dates and times as date-time objects. Date-time objects store data on a time line as real numbers. This storage method increases processing efficiency and directly mimics the method used by many popular database systems. In date-time objects, one day is equal to the difference between two successive integers. The time portion of the date-andtime value is stored in the fractional part of the real number.
PAGE 52

Function Description ToBinary Converts Base64 encoded data to binary data. Macromedia recommends using the BinaryDecode function, instead of this function, in new applications. ToString Converts most simple data types to string data. It can convert numbers, date-time objects, and boolean values. (It converts date-time objects to ODBC timestamp strings.) Macromedia recommends that you use the CharsetEncode function to convert binary data to a string in new applications.
PAGE 53

You can also create a structure by assigning a value in the structure. For example, the following line creates a new structure called MyStruct with a key named MyValue, equal to 2: Note: In previous ColdFusion versions, this line created a Variables scope variable named "MyStruct.MyValue" with the value 2. After you create a structure, you can use functions or direct references to manipulate its contents, including adding key-value pairs.
PAGE 54

When you assign a query to a new variable, ColdFusion does not copy the query object. Instead, both names point to the same record set data. For example, the following line creates a new variable, myQuery2, that references the same record set as the myQuery variable: If you make changes to data in myQuery, myQuery2 also shows those changes. You reference query columns by specifying the query name, a period, and the column name; for example: myQuery.
PAGE 55

Assigning objects to scopes You can give a query or structure a different scope by assigning it to a new variable in the other scope. For example, the following line creates a server variable, Server.SScopeQuery, using the local myquery variable: To clear the server scope query variable, reassign the query object, as follows:
PAGE 56

Similarly, the following lines print the name "marjorie", the value of the second row in the column: #mycol[2]#
However, when you make an assignment that requires a simple value, ColdFusion automatically converts the query column to the value of the first row. For example, the following lines display the name "ben" twice: #myQuery.
PAGE 57

4. If a or myVar.a is the name of a complex object, checks whether b is the name of a simple variable, and returns the value of b. If myVar is a complex object but a is not a complex object, checks whether a.b is the name of a simple variable and returns its value. If myVar.a is not a complex object, checks whether myVar.a.b is the name of a simple variable and returns its value. This way, ColdFusion correctly resolves the variable name and can get its value.
PAGE 58

However, if the name before the first period is either Cookie or Client, ColdFusion uses a different rule. It treats all the text (including any periods) that follow the scope name as the name of a simple variable, because Cookie and Client scope variables must be simple. If you have the following code, you see that ColdFusion creates a single, simple Client scope variable named myVar.a.b:
PAGE 59

Data type conversion ColdFusion automatically converts between data types to satisfy the requirements of an expression’s operations, including a function’s argument requirements. As a result, you generally don’t need to be concerned about compatibility between data types and the conversions from one data type to another. However, understanding how ColdFusion evaluates data values and converts data between types can help you prevent errors and create code more effectively.
PAGE 60

Value As Boolean As number As date-time As string False False 0 Error "No" Number True if Number Number is not 0; False otherwise. See “Date-time values” earlier in this chapter. String representation of the number (for example, “8”). String If "Yes", True If "No", False If it can be converted to 0, False If it can be converted to any other number, True If it represents a number (for example, "1,000" or "12.36E-12"), it is converted to the corresponding number.
PAGE 61

Converting date and time data To ensure that a date and time value is expressed as a real number, add zero to the variable.
PAGE 62

However, if myVariable has a numeric value such as 12, only the first example produces a result. In the second case, the value of myVariable is not converted to a Boolean data type, because the IS operator does not require a specific data type and just tests the two values for identity. Therefore, ColdFusion compares the value 12 with the constant True. The two are not equal, so nothing is printed.
PAGE 63

Date-time functions and queries when ODBC is not supported Many CFML functions, including the Now, CreateDate, CreateTime, and CreateDateTime functions, return date-time objects. ColdFusion creates Open Database Connectivity (ODBC) timestamp values when it converts date-time objects to strings. As a result, you might get unexpected results when using dates with a database driver that does not support ODBC escape sequences, or when you use SQL in a query of queries.
PAGE 64

Using quotation marks To ensure that ColdFusion properly interprets string data, surround strings in single- or doublequotation marks. For example, ColdFusion evaluates “10/2/2001” as a string that can be converted into a date-time object. However, it evaluates 10/2/2001 as a mathematical expression, 5/2001, which evaluates to 0.00249875062469. Examples of type conversion in expression evaluation The following examples demonstrate ColdFusion expression evaluation.
PAGE 65

Scope types The following table describes ColdFusion scopes: Scope Description Variables (local) The default scope for variables of any type that are created with the cfset and cfparam tags. A local variable is available only on the page on which it is created and any included pages (see also the Caller scope). Form Contains variables passed from a Form page to its action page as the result of submitting the form. (If you use the HTML form tag, you must use method="post".
PAGE 66

Scope Description Cookie Contains variables maintained in a user’s browser as cookies. Cookies are typically stored in a file on the browser, so they are available across browser sessions and applications. You can create memory-only Cookie variables, which are not available after the user closes the browser. Cookie scope variable names can include periods. Client Contains variables that are associated with one client.
PAGE 67

Creating and using variables in scopes The following table shows how you create and refer to variables in different scopes in your code. For more information on the mechanisms for creating variables in most scopes, see “Creating variables” on page 44. Scope prefix (type) Prefix required to reference Where available Created by Variables (Local) No On the current page. Cannot be accessed by a form’s action page (unless the form page is also the action page).
PAGE 68

Scope prefix (type) Prefix required to reference Where available Created by CGI No On any page. Values are specific to the latest browser request. The web server. Contains the server environment variables that result from the browser request. Cffile Yes Following an invocation of cffile. A cffile tag. Cookie No For one client in one or more applications and pages, over multiple browser sessions. A cfcookie tag.
PAGE 69

Scope prefix (type) Prefix required to reference Where available Created by This Yes Within a ColdFusion component or the body of a user-defined function that was created using the cffunction tag and put in an object, structure, or scope. In the containing page, through the component instance or containing object. Within the component or function by specifying the prefix This when you create the variable.
PAGE 70

The Java setVariable Response interface method and C++ CCFX::SetVariable method return data to the Variables scope of the calling page. Therefore, they are equivalent to setting a Caller scope variable in a custom ColdFusion tag. Using scopes as structures ColdFusion makes all named scopes available as structures. You cannot access the function-local scope for user defined functions (UDFs) that you define using CFScript as a structure. (In ColdFusion 4.
PAGE 71

For example, if you submit a form with an unsettled check box, the action page does not get a variable for the check box. The following example from a form action page makes sure the Contractor check box Form variable exists before using it: Contractor: #Form.Contractor# You must always enclose the argument passed to the IsDefined function in double-quotation marks. For more information on the IsDefined function, see CFML Reference.
PAGE 72

There are two ways to use the cfparam tag to test for variable existence, depending on how you want the validation test to proceed: • With only the name attribute to test that a required variable exists. If it does not exist, the ColdFusion server stops processing the page and displays an error message. • With the name and default attributes to test for the existence of an optional variable. If the variable exists, processing continues and the value is not changed.
PAGE 73

Validating data It is often not sufficient that input data merely exists; it must also have the right format. For example, a date field must have data in a date format. A salary field must have data in a numeric or currency format. There are many ways to ensure the validity of data, including the following methods: • • • • • Use the cfparam tag with the type attribute to validate a variable. Use the IsValid function to validate a variable.
PAGE 74

The following example calls a custom tag using two variables, MyString and MyArray: Passing variables to CFX tags You cannot pass arrays, structures, or cfobject objects to CFX tags. You can pass a query to a CFX tag by using the query attribute when calling the tag. ColdFusion normally converts simple data types to strings when passing them to CFX tags; however, the Java Request Interface getIntAttribute method lets you get a passed integer value.
PAGE 75

CHAPTER 4 Using Expressions and Number Signs This chapter discusses how to use expressions in CFML. It discusses the elements of Macromedia ColdFusion expressions and how to create expressions. It also describes the correct use of number signs to indicate expressions in ColdFusion tags such as cfoutput, in strings, and in expressions. Finally, it describes how to use variables in variable names and strings to create dynamic expressions, and dynamic variables. Contents Expressions . . . . . . . . . . . . .
PAGE 76

Note that the operator is surrounded by expressions. Each expression can be a simple operand (variable or constant) or a subexpression consisting of more operators and expressions. Complex expressions are built up using subexpressions. For example, in the expression (1 + 1)/2, 1 + 1 is a subexpression consisting of an operator and two operands.
PAGE 77

Operator Description OR Return True if any of the arguments is True; return False otherwise. For example, True OR False is True, but False OR False is False. XOR Exclusive or: Return True if one of the values is True and the other is False. Return False if both arguments are True or both are False. For example, True XOR True is False, but True XOR False is True. EQV Equivalence: Return True if both operands are True or both are False. The EQV operator is the opposite of the XOR operator.
PAGE 78

Operator Alternative name(s) LESS THAN LT GREATER THAN OR EQUAL TO GTE, GE LESS THAN OR EQUAL TO LTE, LE Decision operator rules The following rules apply to decision operators: • When ColdFusion evaluates an expression that contains a decision operator other than CONTAINS or DOES NOT CONTAIN, it first determines if the data can be converted to numeric values. If they can be converted, it performs a numeric comparison on the data. If they cannot be converted, it performs a string comparison.
PAGE 79

Operator precedence and evaluation ordering The order of precedence controls the order in which operators in an expression are evaluated. The order of precedence is as follows: Unary +, Unary ^ *, / \ MOD +, & EQ, NEQ, LT, LTE, GT, GTE, CONTAINS, DOES NOT CONTAIN NOT AND OR XOR EQV IMP To enforce a non-standard order of evaluation, you must parenthesize expressions. For example: • 6 - 3 * 2 is equal to 0 • (6 - 3) * 2 is equal to 6 You can nest parenthesized expressions.
PAGE 80

All functions return values. In the following example, the cfset tag sets a variable to the value returned by the Now function: You can use the values returned by functions directly to create more complex expressions, as in the following example: Abs(Myvar)/Round(3.14159) For more information on how to insert functions in expressions, see “Using number signs” on page 81.
PAGE 81

Using number signs Number signs (#) have a special meaning in CFML. When the ColdFusion server encounters number signs in CFML text, such as the text in a cfoutput tag body, it checks to see if the text between the number signs is either a variable or a function. Tip: Number signs are also called pound signs. Is so, it replaces the text and surrounding number signs with the variable value or the result of the function. Otherwise, ColdFusion generates an error.
PAGE 82

Note: You do not need to use number signs when you use the cfset tag to assign one variable’s value to another value. For example, the following tag assigns the value of the oldVar variable to the new variable, newVar: . Using number signs in tag bodies You can put variables or functions freely inside the bodies of the following tags by enclosing each variable or expression with number signs: • • • cfoutput cfquery cfmail For example: Value is #Form.
PAGE 83

If number signs are omitted inside the string, the text, rather than the value, appears in the string.
PAGE 84

In contrast, the following example uses number signs unnecessarily and is less efficient than the previous statement: Dynamic expressions and dynamic variables This section discusses the advanced topics of dynamic expressions, dynamic evaluation, and dynamic variable naming. Many ColdFusion programmers never encounter or need to use dynamic expressions.
PAGE 85

This process enables ColdFusion to interpret dynamic expressions with variable parts. However, it incurs a substantial processing overhead. Dynamic expressions were important in early versions of ColdFusion, before it supported arrays and structures, and they still can be useful in limited circumstances. However, the ability to use structures and the ability to use associative array notation to access structure elements provide more efficient and easier methods for dynamically managing data.
PAGE 86

To construct a variable name this way, all the text on the left side of the equal sign must be in quotation marks. This usage is less efficient than using arrays.
PAGE 87

Using dynamic evaluation The following sections describe how to use dynamic evaluation and create dynamic expressions. ColdFusion dynamic evaluation functions The following table describes the functions that perform dynamic evaluation and are useful in evaluating dynamic expressions: Function Purpose DE Escapes any double-quotation marks in the argument and wraps the result in double-quotation marks.
PAGE 88

About the Evaluate function The Evaluate function takes one or more string expressions, dynamically evaluates their contents as expressions from left to right, and returns the result of evaluating the rightmost argument.
PAGE 89

As you can see, using dynamic expressions can result in substantial expression evaluation overhead, and the code can be confusing. Therefore, you should avoid using dynamic expressions wherever a simpler technique, such as using indexed arrays or structures can serve your purposes. Avoiding the Evaluate function Using the Evaluate function increases processing overhead, and in most cases it is not necessary.
PAGE 90

The following example has the same result as the preceding example and is more efficient: ProductName: #Form["product_" & i]# In this code, ColdFusion does the following: 1. Evaluates the expression in the associative array index brackets as the string "product_" concatenated with the value of the variable i. 2. Determines the value of the variable i; 1. 3. Concatenates the string and the variable value to get product_1. 4.
PAGE 91

The IIF function requires the DE function to prevent ColdFusion from evaluating literal strings, as the following example shows: #IIf(IsDefined("LocalVar"), "LocalVar", DE("The variable is not defined."))# If you do not enclose the string "The variable is not defined." in a DE function, the IIF function tries to evaluate the contents of the string as an expression and generates an error (in this case, an invalid parser construct error).
PAGE 92

Example: a dynamic shopping cart The following example dynamically creates and manipulates variable names without using dynamic expression evaluation by using associative array notation. You need to dynamically generate variable names in applications such as shopping carts, where the required output is dynamically generated and variable. In a shopping cart, you do not know in advance the number of cart entries or their contents.
PAGE 93

2.
PAGE 94

Code Description PAGE 95
3. Save the file as ShoppingCartAction.cfm 4. Open ShoppingCartform.cfm in your browser, change the check box and quantity values, and click Submit. Reviewing the code The following table describes the code: Code Description Run the CFML on this page only if it is called by submitting a form. This is not needed if there are separate form and action pages, but is required if the form and action page were one ColdFusion page. PAGE 96
Chapter 4: Using Expressions and Number Signs
PAGE 97

CHAPTER 5 Using Arrays and Structures Macromedia ColdFusion supports dynamic multidimensional arrays. This chapter explains the basics of creating and handling arrays. It also provides several examples showing how arrays can enhance your ColdFusion application code. ColdFusion also supports structures for managing lists of key-value pairs. Because structures can contain other structures or complex data types as it values, they provide a flexible and powerful tool for managing complex data.
PAGE 98

Basic array concepts The following terms will help you understand subsequent discussions of ColdFusion arrays: • • • Array dimension The relative complexity of the array structure. Index The position of an element in a dimension, ordinarily surrounded by square brackets: my1Darray[1], my2Darray[1][1], my3Darray[1][1][1]. Array element Data stored at an array index. The simplest array is a one-dimensional array, similar to a row in a table.
PAGE 99

A conventional 2D array is like a fixed-size table made up of individual cells, as the following figure shows: The following figure represents a ColdFusion 2D array: A ColdFusion 2D array is actually a one-dimensional array that contains a series of additional 1D arrays. Each of the arrays that make up a row can expand and contract independently of any other column. Similarly, a ColdFusion 3D array is essentially three nested sets of 1D arrays.
PAGE 100

Basic array techniques The following sections describe how to reference array elements, create arrays, add and remove array elements, and copy arrays. Referencing array elements You reference array elements by enclosing the index with brackets: arrayName[x] where x is the index that you want to reference. In ColdFusion, array indexes are counted starting with position 1, which means that position 1 in the firstname array is referenced as firstname[1].
PAGE 101

It is important to know that when you assign one array (array1) to an element of another array (array2), array1 is copied into array2. The original copy of array1 still exists, independent of array2. You can then change the contents of the two arrays independently. The best way to understand an asymmetrical array is by looking at it. The following example creates an asymmetric, multidimensional array and the cfdump tag displays the resulting array structure. Several array elements do not yet contain data.
PAGE 102

Code Description Assign a value to element [3] of myarray.
Use cfdump to view the structure of biggestarray and myarray. Notice that the "Can you see me" entry appears in myarray, but not in biggestarray, because biggestarray has a copy of the original myarray values and is not affected by the change to myarray.
PAGE 103

Because ColdFusion arrays are dynamic, if you add or delete an element from the array, any higher-numbered index values all change. For example, the following code creates a two element array and displays the array contents. It then uses ArrayPrepend to insert a new element at the beginning of the array and displays the result. The data that was originally in indexes 1 and 2 is now in indexes 2 and 3.
PAGE 104

Copying arrays You can copy arrays of simple variables (numbers, strings, Boolean values, and date-time values) by assigning the original array to a new variable name. You do not have to use ArrayNew to create the new array first. When you assign the existing array to a new variable, ColdFusion creates a new array and copies the old array’s contents to the new array. The following example creates and populates a two-element array.
PAGE 105

Populating arrays with data Array elements can store any values, including queries, structures, and other arrays. You can use a number of functions to populate an array with data, including ArraySet, ArrayAppend, ArrayInsertAt, and ArrayPrepend. These functions are useful for adding data to an existing array.
PAGE 106

Using nested loops for 2D and 3D arrays To output values from 2D and 3D arrays, you must employ nested loops to return array data. With a one-dimensional (1D) array, a single cfloop is sufficient to output data, as in the previous example. With arrays of dimension greater than one, you need to maintain separate loop counters for each array level. Nesting cfloop tags for a 2D array The following example shows how to handle nested cfloop tags to output data from a 2D array.
PAGE 107

Populating an array from a query When populating an array from a query, keep the following things in mind: • You cannot add query data to an array all at once. A looping structure is generally required to populate an array from a query. • You can reference query column data using array-like syntax. For example, myquery.col_name[1] references data in the first row in the col_name column of the myquery query.
PAGE 108

Array functions The following functions are available for creating, editing, and handling arrays: Function Description ArrayAppend Appends an array element to the end of a specified array. ArrayAvg Returns the average of the values in the specified array. ArrayClear Deletes all data in a specified array. ArrayDeleteAt Deletes an element from a specified array at the specified index and resizes the array.
PAGE 109

A structure’s key must be a string. The values associated with the key can be any valid ColdFusion value or object. It can be a string or integer, or a complex object such as an array or another structure. Because structures can contain any kind of data they provide a very powerful and flexible mechanism for representing complex data. Structure notation ColdFusion supports two types of notation for referencing structure contents. The notation that you use depends on your requirements.
PAGE 110

key2Var="key2"> key3Var="key3"> var2="2"> Value of the first key
#mystruct.key1#
#mystruct["key1"]#
#mystruct[key1Var]#

Value of the second entry in the key2 array
#myStruct.
PAGE 111

Code Description Value of the first key
#mystruct.key1#
#mystruct["key1"]#
#mystruct[key1Var]#

Output the value of the structure’s key1 (string) entry using the following notation: • object.property notation • associative array notation with a constant • associative array notation with a variable Value of the second entry in the key2 array
#myStruct.
PAGE 112

Creating structures using a function You can create structures by assigning a variable name to the structure with the StructNew function as follows: For example, to create a structure named departments, use the following syntax: This creates an empty structure to which you can add data. Use this technique to create structures if your application must run on ColdFusion server versions 5 and earlier.
PAGE 113

Getting information about structures and keys The following sections describe how to use ColdFusion functions to find information about structures and their keys. Getting information about structures To find out if a given value represents a structure, use the IsStruct function, as follows: IsStruct(variable) This function returns True if variable is a ColdFusion structure. (It also returns True if variable is a Java object that implements the java.util.Map interface.
PAGE 114

However, if the key is dynamic, or contains special characters, you must use the StructKeyExists function. Note: Using StructKeyExists to test for the existence of a structure entry is more efficient than using IsDefined. ColdFusion scopes are available as structures and you can improve efficiency by using StructKeyExists to test for the existence of variables.
PAGE 115

The following example shows the different effects of copying, duplicating, and assigning structure variables: Create a new structure
PAGE 116

Structure reference

Change a string, array element, and structure value in the reference
PAGE 117

myStruct:
myCopy: Looping through structures You can loop through a structure to output its contents, as shown in the following example:
PAGE 118

name="Form.email" default=""> name="Form.phone" default=""> name="Form.department" default="">
Please fill out the form.
employee=StructNew(); employee.firstname = Form.firstname; employee.lastname = Form.lastname; employee.email = Form.email; employee.
PAGE 119

Reviewing the code The following table describes the code: Code name="Form.lastname" default=""> name="Form.email" default=""> name="Form.phone" default=""> name="Form.department" default=""> Set default values of all form fields so that they exist the first time this page is displayed and can be tested. Please fill out the form.
Test the value of the form’s firstname field.
PAGE 120

Code Description Call the cf_addemployee custom tag and pass it a copy of the employee structure in the empinfo attribute. The duplicate function ensures that the custom tag gets a copy of the employee structure, not the original. While this is not necessary in this example, it is good practice because it prevents the custom tag from modifying the calling page’s structure contents.
The data form.
PAGE 121

Employee Add Complete Reviewing the code The following table describes the code: Code Description Error. No employee data was passed. If the custom tag was called without an empinfo attribute, display an error message and exit the tag.
PAGE 122

Function Description StructDelete Removes the specified item from the specified structure. StructFind Returns the value associated with the specified key in the specified structure. This function is redundant with accessing structure elements using associative array notation. StructFindKey Searches through a structure for the specified key name and returns an array containing data on the found key or keys.
PAGE 123

CHAPTER 6 Extending ColdFusion Pages with CFML Scripting Macromedia ColdFusion MX offers a server-side scripting language, CFScript, that provides ColdFusion functionality in script syntax. This JavaScript-like language gives developers the same control flow as ColdFusion, but without tags. You can also use CFScript to write user-defined functions that you can use anywhere that a ColdFusion expression is allowed.
PAGE 124

In addition to variable setting, other operations tend to be slightly faster in CFScript than in tags. ColdFusion 5 and later releases let you use CFScript to create user-defined functions, or UDFs (also known as custom functions). You call UDFs in the same manner that you call standard ColdFusion functions. UDFs are to ColdFusion built-in functions what custom tags are to ColdFusion built-in tags. Typical uses of UDFs include data manipulation and mathematical calculation routines.
PAGE 125

The CFScript language This section explains the syntax of the CFScript language. Identifying CFScript You enclose CFScript regions inside and tags. No other CFML tags are allowed inside a cfscript region. The following lines show a minimal script: a = 2; Variables CFScript variables can be of any ColdFusion type, such as numbers, strings, arrays, queries, and objects.
PAGE 126

Statement blocks Curly brace characters ({ and }) group multiple CFScript statements together so that they are treated as a single unit or statement. This enables you to create code blocks in conditional statements, such as the following: if(score GT 0) { result = "positive"; Positives = Positives + 1; } In this example, both assignment statements are executed if the score is greater than 0. If they were not in the code block, only the first line would execute.
PAGE 127

Reserved words In addition to the names of ColdFusion functions and words reserved by ColdFusion expressions (such as NOT, AND, IS, and so on), the following words are reserved in CFScript. Do not use these words as variables or identifiers in your scripting code: break default function switch case do if try catch else in var continue for return while Differences from JavaScript Although CFScript and JavaScript are similar, they have several key differences.
PAGE 128

Tag CFScript equivalent cftry, cfcatch try and catch statements cfcookie Direct assignment of Cookie scope memory-only variables. You cannot use direct assignment to set persistent cookies that are stored on the user’s system. cfobject CreateObject function For example, the following example loops through a query in CFScript: ... // Loop through the qGetEmails RecordSet for (x = 1; x LTE qGetEmails.RecordCount; x=x+1) { This_id = qGetEmails.Emails_id[x]; This_Subject = qGetEmails.
PAGE 129

Using conditional processing statements CFScript includes the following conditional processing statements: • if and else statements, which serve the same purpose as the cfif, cfelseif, and cfelse tags • switch, case, and default statements, which are the equivalents of the cfswitch, cfcase, and cfdefaultcase tags Using if and else statements The if and else statements have the following syntax: if(expr) statement [else statement] In its simplest form, an if statement looks like this: if(value EQ 2700)
PAGE 130

Using switch and case statements The switch statement and its dependent case and default statements have the following syntax: switch (expression) { case constant: [case constant:]... statement(s) break; [case constant: [case constant:]... statement(s) break;]... [default: statement(s)] } Use the following rules and recommendations for switch statements: • You cannot mix Boolean and numeric constant values in a switch statement.
PAGE 131

The following switch statement takes the value of a name variable: 1. If the name is John or Robert, it sets both the male variable and the found variable to True. 2. If the name is Mary, it sets the male variable to False and the found variable to True. 3. Otherwise, it sets the found variable to False.
PAGE 132

Note: The test expression is re-evaluated before each repeat of the loop. If code inside the loop changes any part of the test expression, it can affect the number of iterations in the loop. The statement can be a single semicolon terminated statement or a statement block in curly braces. When ColdFusion executes a for loop, it does the following: 1. Evaluates the initial expression. 2. Evaluates the test-expression. 3.
PAGE 133

The example also shows two issues with index arithmetic: in this form of loop you must make sure to initialize the index, and you must keep track of where the index is incremented. In this case, because the index is incremented at the top of the loop, you must initialize it to 0 so it becomes 1 in the first loop. Using while loops The while loop has the following format: while (expression) statement The while statement does the following: 1. Evaluates the expression. 2.
PAGE 134

The following example, like the while loop example, populates a 10-element array with multiples of 5: a = ArrayNew(1); loop = 1; do { a[loop] = loop * 5; loop = loop + 1; } while (loop LE 10); Because the loop index increment follows the array value assignment, the example initializes the loop variable to 1 and tests to make sure that it is less than or equal to 10. The following example generates the same results as the previous two examples, but it increments the index before assigning the array value.
PAGE 135

myStruct=StructNew(); myStruct.productName="kumquat"; mystruct.quality="fine"; myStruct.quantity=25; for (keyName in myStruct) { WriteOutput("myStruct." & Keyname & " has the value: " & myStruct[keyName] &"
"); } Note: Unlike the cfloop tag, CFScript for-in loops do not provide built-in support for looping over queries and lists.
PAGE 136

} else if (indx IS ArrayLen(strings)) { WriteOutput("Array ends at index " & indx & ".
"); break; } } Handling exceptions ColdFusion provides two statements for exception handling in CFScript: try and catch. These statements are equivalent to the CFML cftry and cfcatch tags. Note: This section does not explain exception-handling concepts. For a discussion of exception handling in ColdFusion, see Chapter 14, “Handling Errors,” on page 307.
PAGE 137

Exception handling example The following code shows exception handling in CFScript. It uses a CreateObject function to create a Java object. The catch statement executes only if the CreateObject function generates an exception. The displayed information includes the exception message; the except.Message variable is the equivalent of calling the Java getMessage method on the returned Java exception object.
PAGE 138

applicants.accepted=acceptedApplicants; applicants.rejected=rejectedApplicants; rejectCode=StructNew(); rejectCode["David Dalhousie"] = "score"; rejectCode["Franny Farkle"] = "too late"; //Sort and display accepted applicants ArraySort(applicants.accepted,"text","asc"); WriteOutput("The following applicants were accepted:
"); for (j=1;j lte ArrayLen(applicants.accepted);j=j+1) { WriteOutput(applicants.
PAGE 139

Reviewing the code The following table describes the code: Code Description acceptedApplicants[1] = "Cora Cardozo"; acceptedApplicants[2] = "Betty Bethone"; acceptedApplicants[3] = "Albert Albertson"; rejectedApplicants[1] = "Erma Erp"; rejectedApplicants[2] = "David Dalhousie"; rejectedApplicants[3] = "Franny Farkle"; applicants.accepted=acceptedApplicants; applicants.
PAGE 140

Code Description else { WriteOutput("Reject reason was not defined.
"); { If there is no entry for the applicant in the rejectCode structure, displays a message indicating that the reason was not defined. WriteOutput("
"); } //end for Displays a blank line after each rejected applicant. Ends the for loop that handles each rejected applicant. Ends the CFScript.
PAGE 141

CHAPTER 7 Using Regular Expressions in Functions Regular expressions let you perform string matching operations using ColdFusion functions. This chapter describes how regular expressions work with the following functions: • • • • REFind REFindNoCase REReplace REReplaceNoCase This chapter does not apply to regular expressions used in the cfinput and cftextinput tags. These tags use JavaScript regular expressions, which have a slightly different syntax than ColdFusion regular expressions.
PAGE 142

You must provide the exact string pattern to match. If the exact pattern is not found, Find returns an index of 0. Because you must specify the exact string pattern to match, matches for dynamic data can be very difficult, if not impossible, to construct. The next example uses a regular expression to perform the same search.
PAGE 143

Basic regular expression syntax The simplest regular expression contains only a literal characters. The literal characters must match exactly the text being searched. For example, you can use the regular expression function REFind to find the string pattern " BIG ", just as you can with the Find function: In this example, REFind must match the exact string pattern " BIG ".
PAGE 144

The regular expression [A-Z][a-z]* matches any word that starts with an uppercase letter and is followed by zero or more lowercase letters. The special character * after the closing square bracket specifies to match zero or more occurrences of the character set. Note: The * only applies to the character set that immediately precedes it, not to the entire regular expression. A + after the closing square bracket specifies to find one or more occurrences of the character set.
PAGE 145

You use the following syntax to find repeating characters: • {m,n} Where m is 0 or greater and n is greater than or equal to m. Match m through n (inclusive) occurrences. The expression {0,1} is equivalent to the special character ?. • {m,} Where m is 0 or greater. Match at least m occurrences. The syntax {,n} is not allowed. The expression {1,} is equivalent to the special character +, and {0,} is equivalent to *. • {m} Where m is 0 or greater. Match exactly m occurrences.
PAGE 146

Using special characters Regular expressions define the following list of special characters: + * ? . [ ^ $ ( ) { | \ In some cases, you use a special character as a literal character.
PAGE 147

Special Description Character () Parentheses group parts of a regular expression into subexpressions that you can treat as a single unit. For example, (ha)+ matches one or more instances of “ha”. (?x) If at the beginning of a regular expression, it specifies to ignore whitespace in the regular expression and lets you use ## for end-of-line comments. You can match a space by escaping it with a backslash.
PAGE 148

Special Description Character (?=...) If at the beginning of a regular expression, it specifies to use positive lookahead when searching for the regular expression. Positive lookahead tests for the parenthesized subexpression like regular parenthesis, but does not include the contents in the match - it merely tests to see if it is there in proximity to the rest of the expression.
PAGE 149

The following table lists the escape sequences that ColdFusion supports: Escape Description Sequence \b Specifies a boundary defined by a transition from an alphanumeric character to a nonalphanumeric character, or from a nonalphanumeric character to an alphanumeric character. For example, the string " Big" contains boundary defined by the space (nonalphanumeric character) and the "B" (alphanumeric character).
PAGE 150

This code replaces all the spaces with *, producing this string: Macromedia*Web*Site You can combine character classes with other expressions within a character set. For example, the regular expression [[:space:]123] searches for a space, 1, 2, or 3.
PAGE 151

You can use backreferencing when searching for repeated words in a string, such as “the the” or “is is”.
PAGE 152

Note: To use backreferences in either the search string or the replace string, you must use parentheses within the regular expression to create the corresponding subexpression. Otherwise, ColdFusion throws an exception. Using backreferences to perform case conversions in replacement strings The REReplace and REReplaceNoCase functions support special characters in replacement strings to convert replacement characters to uppercase or lowercase.
PAGE 153

This example returns "Hello Mr. Bond". If you did not prohibit the capturing of the Hi/Hello group, the \2 backreference would end up referring to that group instead of " Bond", and the result would be "Hello Mr.ello". Returning matched subexpressions The REFind and REFindNoCase functions return the location in the search string of the first match of the regular expression.
PAGE 154

Element one of the pos array contains the starting index in the search string of the string that matched the regular expression. Element one of the len array contains length of the matched string. For this example, the index of the first " BIG " string is 5 and its length is also 5. If there are no occurrences of the regular expression, the pos and len arrays each contain one element with a value of 0. You can use the returned information with other string functions, such as mid.
PAGE 155

The following figure shows the output of the cfdump tag: The entries sLenPos.pos[1] and sLenPos.len[1] contain information about the match of the entire regular expression. The array elements sLenPos.pos[2] and sLenPos.len[2] contain information about the first subexpression (“is”). Because REFind returns information on the first regular expression match only, the sLenPos structure does not contain information about the second match to the regular expression, "in in".
PAGE 156

For example, you use the regular expression "(.*)" to search the string "one two". The regular expression "(.*)", matches both of the following: • one • one two By default, ColdFusion always tries to match the regular expression to the largest string in the search string. The following code shows the results of this example: (.
PAGE 157

The following figure shows the output of the cfdump tag: Thus, the length of the string found by the regular expression is 10, corresponding to the string "one". Regular expression examples The following examples show some regular expressions and describe what they match: Expression Description [\?&]value= A URL parameter value in a URL. [A-Z]:(\\[A-Z0-9_]+)+ An uppercase DOS/Windows path in which (a) is not the root of a drive, and (b) has only letters, numbers, and underscores in its text.
PAGE 158

Expression Returns REFind ("[Uu]\.?[Ss]\.?[Aa}\.?", Report ) The position in the variable Report of the first occurrence of the abbreviation USA. The letters can be in either case and the abbreviation can have a period after any letter. REFindNoCase("a+c","ABCAACCDD") 4 REReplace("There is is coffee in the the kitchen", There * coffee in * kitchen "([A-Za-z]+)[ ]+\1","*","ALL") REReplace(report, "<[^>]*>", "", "All") Removes all HTML tags from a string value of the report variable.
PAGE 159

This part describes building blocks of Coldfusion applications. These building blocks let you organize and reuse code, and include the cfinclude tag, user-defined functions, ColdFusion components, custom tags, and ColdFusion Extension (CFX) tags. The following chapters are included: Chapter 8: Creating ColdFusion Elements. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161 Chapter 9: Writing and Calling User-Defined Functions . . . . . . . . . . . . . . . . . . . . . . . . . . .
PAGE 160
PAGE 161

CHAPTER 8 Creating ColdFusion Elements This chapter describes ColdFusion elements that you create. These elements let you to organize your code. When you create any of these elements, you write your code once and use it, without copying it, in many places. This chapter describes the elements that you can create and their features, and provides advice on selecting among the elements. Contents About CFML elements you create . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
PAGE 162

ColdFusion can also use elements developed using other technologies, including the following: • JSP tags from JSP tag libraries For information on using JSP tags, see Chapter 37, “Integrating J2EE and Java Elements in CFML Applications,” on page 917. • Java objects, including objects in the Java runtime environment and JavaBeans For information on using Java objects, see Chapter 37, “Integrating J2EE and Java Elements in CFML Applications,” on page 917.
PAGE 163

Using the cfinclude tag When you use the cfinclude tag to include one ColdFusion page in another ColdFusion page, the page that includes another page is referred to as the calling page. When ColdFusion encounters a cfinclude tag it replaces the tag on the calling page with the output from processing the included page. The included page can also set variables in the calling page. The following line shows a sample cfinclude tag: PAGE 164
Recommended uses Consider using the cfinclude tag in the following cases: • For page headers and footers • To divide a large page into multiple logical chunks that are easier to understand and manage • For large “snippets” of code that are used in many places but do not require parameters or fit into the model of a function or tag About user-defined functions User-defined functions (UDFs) let you create application elements in a format in which you pass in arguments and get a return a value.
PAGE 165

If you can create either a UDF or a custom CFML tag for a particular purpose, first consider creating a UDF because invoking it requires less system overhead than using a custom tag. For more information For more information on user-defined functions, see Chapter 9, “Writing and Calling UserDefined Functions,” on page 171. Using ColdFusion components ColdFusion components (CFCs) are ColdFusion templates that contain related functions and arguments that each function accepts.
PAGE 166

Using custom CFML tags Custom tags written in CFML behave like ColdFusion tags. They can do all of the following: • • • • Take arguments. Have tag bodies with beginning and ending tags. Do specific processing when ColdFusion encounters the beginning tag. Do processing that is different from the beginning tag processing when ColdFusion encounters the ending tag.
PAGE 167

If your tag takes a body, end it with the same tag name preceded with a forward slash (/), as follows: For information on using the cfmodule and cfimport tags to call custom CFML tags, see Chapter 11, “Creating and Using Custom CFML Tags,” on page 241. Recommended uses ColdFusion custom tags let you abstract complex code and programming logic into simple units. These tags let you maintain a CFML-like design scheme for your code.
PAGE 168

• Dynamically generate HTML to be returned to the client. • Set variables within the ColdFusion page from which they are called. • Throw exceptions that result in standard ColdFusion error messages. Calling CFX tags To use a CFX tag, precede the class name with cfx_ and put the name in angle brackets. For example, use the following line to call the CFX tag defined by the MyCFXClass class and pass it one attribute.
PAGE 169

Selecting among ColdFusion code reuse methods The following table lists common reasons to employ code reuse methods and indicates the techniques to consider for each purpose. The letter P indicates that the method is preferred. (There can be more than one preferred method.) The letter A means that the method provides an alternative that might be useful in some circumstances. This table does not include CFX tags. You use CFX tags only when you should code your functionality in C++ or Java.
PAGE 170

Chapter 8: Creating ColdFusion Elements
PAGE 171

CHAPTER 9 Writing and Calling User-Defined Functions This chapter describes how to create and call user-defined functions (UDFs). Contents About user-defined functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171 Creating user-defined functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172 Calling user-defined functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
PAGE 172

• Mathematical calculation routines, including standard trigonometric and statistical operations or calculating loan amortization • Routines that call functions externally, for example using COM or CORBA, including routines to determine the space available on a Windows file system drive For information about selecting among User-defined functions, ColdFusion components, and custom tags, see Chapter 8, “Creating ColdFusion Elements,” on page 161. Note: The Common Function Library Project at www.cflib.
PAGE 173

The following is a CFScript definition for a function that returns a power of 2: function twoPower(exponent) { return 2^exponent; } For more information on how to use CFScript to define a function, see “Defining functions in CFScript” on page 173. Defining functions in CFScript You define functions using CFScript in a manner similar to defining JavaScript functions. You can define multiple functions in a single CFScript block.
PAGE 174

The following two statements are allowed only in function definitions: Statement Description var variableName = expression; Creates and initializes a variable that is local to the function (function variable). This variable has meaning only inside the function and is not saved between calls to the function. It has precedence in the function body over any variables with the same name that exist in any other scopes.
PAGE 175

• You can embed CFScript code inside the function definition. • The cffunction tag provides attributes that enable you to easily limit the execution of the tag to authorized users or specify how the function can be accessed.
PAGE 176

Attribute Description roles (Optional) A comma-delimited list of security roles that can invoke this method. If you omit this attribute, ColdFusion does not restrict user access to the function. If you use this attribute, the function executes only if the current user is logged in using the cfloginuser tag and is a member of one or more of the roles specified in the attribute. Otherwise, ColdFusion throws an unauthorized access exception.
PAGE 177

Using a CFML tag in a user-defined function The most important advantage of using the cffunction tag over defining a function in CFScript is that you can include CFML tags in the function. Thus, UDFs can encapsulate activities, such as database lookups, that require ColdFusion tags. Also, you can use the cfoutput tag to display output on the calling page with minimal coding. Tip: To improve performance, avoid using the cfparam tag in ColdFusion functions. Instead, use the cfset tag.
PAGE 178

Calling user-defined functions You can call a function anywhere that you can use an expression, including in number signs (#) in a cfoutput tag, in a CFScript, or in a tag attribute value. One function can call another function, and you can use a function as an argument to another function. You can call a UDF in two ways: • With unnamed, positional arguments, as you would call a built-in function • With named arguments, as you would use attributes in a tag You can use either technique for any function.
PAGE 179

Passing arguments ColdFusion passes the following data types to the function by value: • • • • • Integers Real numbers Strings (including lists) Date-time objects Arrays As a result, any changes that you make in the function to these arguments do not affect the variable that was used to call the function, even if the calling code is on the same ColdFusion page as the function definition. ColdFusion passes queries, structures, and external objects such as COM objects into the function by reference.
PAGE 180

a[1]=2; a[2]=22; //Define the function. function doubleOneDArray(OneDArray) { var i = 0; for ( i = 1; i LE arrayLen(OneDArray); i = i + 1) { OneDArray[i] = OneDArray[i] * 2; } return OneDArray; } //Call the function. a = doubleOneDArray(a); This solution is simple, but it is not always optimal: • This technique requires ColdFusion to copy the entire array twice, once when you call the function and once when the function returns.
PAGE 181

About the Arguments scope All function arguments exist in their own scope, the Arguments scope. The Arguments scope exists for the life of a function call. When the function returns, the scope and its variables are destroyed. However, destroying the Argument scope does not destroy variables, such as structures or query objects, that ColdFusion passes to the function by reference.
PAGE 182

The resulting Arguments scope looks like the following: As an array As a structure Entry Value Entry Value 1 1 Arg1 1 2 undefined Arg2 undefined In this example, the following functions return the value 2 because there are two defined arguments: ArrayLen(Arguments) StructCount(Arguments) However, the following tests return the value False, because the contents of the second element in the Arguments scope is undefined. Isdefined("Arguments.
PAGE 183

Argument #i#: #Arguments[i]#
One Unnamed argument
Two Unnamed arguments
Three Unnamed arguments
Arg1:
Arg2:
Arg1=8, Arg2=9:

PAGE 184

Using the Arguments scope in CFScript A function can have optional arguments that you do not have to specify when you call the function. To determine the number of arguments passed to the function, use the following function: ArrayLen(Arguments) When you define a function using CFScript, the function must use the Arguments scope to retrieve the optional arguments. For example, the following SumN function adds two or more numbers together.

PAGE 185

Function-only variables In addition to the Arguments scope, each function can have a number of variables that exist only inside the function, and are not saved between times the function gets called. As soon as the function exits, all the variables in this scope are removed. In CFScript, you create function-only variables with the var statement. Unlike other variables, you never prefix function-only variables with a scope name.

PAGE 186

As with many programming practice, there are valid exceptions to this recommendation. For example you might do any of the following: • Use a shared scope variable, such as an Application or Session scope counter variable. • Use the Request scope to store variables used in the function, as shown in “Using the Request scope for static variables and constants” on page 196.). • Create context-specific functions that work directly with caller data if you always synchronize variable names.

PAGE 187

For example, the following variation on a “Hello world” function displays an error message if you do not enter a name in the form:
Enter your Name: function HelloFriend(Name) { if (Name is "") WriteOutput("You forgot your name!"); else WriteOutput("Hello " & name &"!"); return ""; } if (IsDefined("Form.

PAGE 188

Consider the following mechanisms for providing status information: • Use the return value to indicate the function status only. The return value can be a Boolean success/failure indicator. The return value can also be a status code, for example where 1 indicates success, and various failure types are assigned known numbers. With this method, the function must set a variable in the caller to the value of a successful result.

PAGE 189

Reviewing the code The following table describes the code that has been changed or added to the previous version of this example. For a description of the initial code, see “A user-defined function example” on page 192. Code Description function TotalInterest(principal, annualPercent, months, status) The function now takes an additional argument, a status structure. Uses a structure for the status variable so that changes that the function makes affect the status structure in the caller.

PAGE 190

Code Description ERROR: #status.errorMsg#
If the function returns -1, there must be an error. Displays the message that the function placed in the status.errorMsg structure key. Loan amount: #Form.Principal#
Annual percentage rate: #Form.AnnualPercent#
Loan duration: #Form.Months# months
TOTAL INTEREST: #myInterst#
If the function does not return -1, it returns an interest value.

PAGE 191

• If the UDF is defined using the cffunction tag, throw a custom exception, or rethrow the exception so that it will be caught by the calling ColdFusion page. For more information on throwing and rethrowing exceptions, see “Handling runtime exceptions with ColdFusion tags” on page 322. Generating exceptions in UDFs If you define your function using the cffunction tag, you can use the cfthrow and cfrethrow tags to throw errors to the page that called the function.

PAGE 192

#cfcatch.message#
A user-defined function example The following simple function takes a principal amount, an annual percentage rate, and a loan duration in months and returns the total amount of interest to be paid over the period. You can optionally use the percent sign for the percentage rate, and include the dollar sign and comma separators for the principal amount.

PAGE 193

Reviewing the code The following table describes the code: Code Description function TotalInterest(principal, annualPercent, months) { Starts the TotalInterest function definition. Requires three variables: the principal amount, the annual percentage rate, and the loan duration in months. Var years = 0; Var interestRate = 0; Var totalInterest = 0; Declares intermediate variables used in the function and initializes them to 0. All var statements must precede the rest of the function code.

PAGE 194

Using UDFs effectively This section provides information that will help you use user-defined functions more effectively. Using functions in ColdFusion component In many cases, the most effective use of UDFs is within a CFC. For more information on CFCs, see Chapter 10, “Building and Using ColdFusion Components,” on page 201. Using Application.

PAGE 195

Selecting a function scope The following table describes the advantages and disadvantages of scopes that you might considering using for your functions: Scope Considerations Application Makes the function available across all invocations of the application. Access to UDFs in Application scope is multithreaded and you can execute multiple copies of the UDF at one time. Request Makes the function available for the life of the current HTTP request, including in all custom tags and nested custom tags.

PAGE 196

Using the Request scope for static variables and constants This section describes how to partially break the rule described in the section “Referencing caller variables” on page 185. Here, the function defines variables in the Request scope. However, it is a specific solution to a specific issue, where the following circumstances exist: • Your function initializes a large number of variables.

PAGE 197

Handling query results using UDFs When you call a UDF in the body of a tag that has a query attribute, such as a cfloop query=... tag, any function argument that is a query column name passes a single element of the column, not the entire column. Therefore, the function must manipulate a single query element. For example, the following code defines a function to combine a single first name and last name to make a full name.

PAGE 198

Identifying and checking for UDFs You can use the IsCustomFunction function to determine whether a name represents a UDF. The IsCustomFunction function generates an error if its argument does not exist. As a result, you must ensure that the name exists before calling the function, for example, by calling the IsDefined function.

PAGE 199

A recursive function, like looping code, must have an end condition that always stops the function. Otherwise, the function will continue until a system error occurs or you stop the ColdFusion server. The following example calculates the factorial of a number, that is, the product of all the integers from 1 through the number; for example, 4 factorial is 4 X 3 X 2 X 1 = 24.

PAGE 200

Chapter 9: Writing and Calling User-Defined Functions

PAGE 201

CHAPTER 10 Building and Using ColdFusion Components This chapter describes Macromedia ColdFusion component (CFC) concepts and elements and tells you how to create and use CFCs. It provides you with all the tools to create and use CFCs; however, it does not discuss CFC methodologies or provide information on designing applications for CFC use. For more information on creating applications that use CFCs, see the Macromedia website: www.macromedia.com. Contents About ColdFusion components . . . . . . . . . .

PAGE 202

This section describes the following topics: • CFCs and object-oriented programming • When to use CFCs CFCs and object-oriented programming CFCs are building blocks that let you develop ColdFusion code in an object-oriented manner, although CFCs do not require you to do object-oriented programming. Some of the objectoriented features of CFCs include encapsulation, inheritance, and introspection. CFC objectoriented features are similar to the object-oriented elements in other languages, like JavaScript.

PAGE 203

CFCs have several advantages over UDFs and custom tags.

PAGE 204

Using asynchronous CFCs ColdFusion MX 7 provides an event gateway that lets you send a message to a CFC asynchronously. This gateway lets you initialize processing by a CFC without waiting for the CFC to complete or return a value. You can use asynchronous CFCs that use this gateway for the following: • Reindexing a Verity collection • Logging information • Running batch processes For more information on using asynchronous CFCs, see Chapter 42, “About event gateways,” on page 1020.

PAGE 205

• The component page defines methods (functions), properties (data), or both. Most CFCs have methods, or methods and properties, but you can also have a CFC that contains only properties. • You use the cffunction tag to define CFC methods. The CFScript function statement can create simple methods, but it does not provide options to control access to the method, provide metadata, specify a return type, or control generated output.

PAGE 206

Because component methods are ColdFusion functions, most of their features and coding techniques are identical to those of user-defined functions. For more information on using the cffunction tag to create functions, see Chapter 9, “Writing and Calling User-Defined Functions,” on page 171. Like other ColdFusion functions, CFC methods can display information directly by generating output, or can return a value to the code or client that invoked the method.

PAGE 207

Putting executable code in a separate file You can put executable code in a separate file from the main component definition page. By placing the method execution code in a separate file, you can separate property initialization code, meta information, and the method definition shell from the executable method definition code. This technique lets you modularize your code and helps prevent CFML pages from getting too long and complex.

PAGE 208

You can refer to instance data of a CFC only if you create an instance of the CFC. From inside the CFC, you refer to instance data of the CFC using the this prefix, for example this.firstvariable. From the calling page, you refer to instance data using dot notation, including the name of the instance of the component and the name of the instance data, as in objectname.ivarname. Components whose methods you invoke without first instantiating the component do not typically have instance data.

PAGE 209

Defining and using method parameters You pass data to a method by using parameters. To define a component method parameter, use the cfargument tag in the cffunction tag body. To define multiple parameters, use multiple cfargument tags.

PAGE 210

Code Description Defines the value that the method returns. Ends the method definition. Ends the component definition. Example: tempConversion.cfm The ColdFusion page tempConversion.cfm is an HTML form in which the user enters the temperature to convert, and selects the type of conversion to perform. When the user clicks the Submit button, ColdFusion performs the actions on the processForm.cfm page. The file tempConversion.

PAGE 211

Reviewing the code The file processForm.cfm invokes the appropriate component method. The following table describes the code and its function: Code Description Executes the code in the cfif block if the user selected Celsius to Fahrenheit as the conversion type in the form on the tempConversion.cfm page. PAGE 212
To run the example, display the tempConversion.cfm page in your browser. When you enter a value in the text box of the form, the value is stored in the form.temperature variable. Processing is then performed on the processForm.cfm page, which refers to the value as form.temperature. When you invoke either method, the cfinvoke tag assigns the value form.temperature to temp; temp is the argument specified in the cfargument tag of the appropriate method.

PAGE 213

In the example, the cfargument attributes specify the following: • The name attributes define the parameter names. • The type attribute for the lastName argument specifies that the parameter must be a text string. The type attribute for the cost argument specifies that the parameter must be a numeric value. These attributes validate the data before it is submitted to the database. • The required attributes indicate that the parameters are required or an exception will be thrown.

PAGE 214

The ColdFusion page or other client, such as a Flash application, that receives the result then uses the variable data as appropriate. Note: If a CFC is invoked using a URL or by submitting a form, ColdFusion MX returns the variable as a WDDX packet. A CFC that is invoked by Flash Remoting MX, or any other instance of a CFC, must not return the This scope. You can return values of all data types, including strings, integers, arrays, structures, and instances of CFCs.

PAGE 215

Metadata attributes are not used by ColdFusion MX for processing; they also do not appear in standard ColdFusion introspection displays; however, you can access and display them by using the GetMetaData function to get the metadata. Each attribute name is a key in the metadata structure of the CFC element. Metadata attributes are used for more than documentation. Your application can use the GetMetadata function to get the metadata attributes and act based on the values.

PAGE 216

When you store components in the same directory, they are members of a component package. You can group related CFCs into packages. Your application can refer to any component in a directory specifically by using a qualified component name that starts with a subdirectory of one of the accessible directories and uses a period to delimit each directory in the path to the directory that contains the component. For example, the following example is a qualified name of a component named price: catalog.product.

PAGE 217

• • • • • Invoking CFC methods with the cfinvoke tag Using components directly in CFScript and CFML Invoking CFC methods using forms and URLs Accessing CFCs from outside ColdFusion and basic HTML Specifying the CFC location Tags for using CFCs The following table lists the tags that you use to instantiate or invoke a CFC. You use these tags on the CFML page on which you instantiate or invoke the CFC. Tag Description cfinvoke Invokes a method of a CFC.

PAGE 218

Instantiating CFCs If you use a CFC multiple times in a ColdFusion request, or if you use a CFC with persistent properties, use the cfobject tag or CreateObject function to instantiate the CFC before you call its methods. The following example uses the cfobject tag to create an instance of the tellTime CFC.

PAGE 219

2. Create a new ColdFusion page, with the following code and save it in the same directory as the tellTime component: tellTimeObj=CreateObject("component","tellTime"); WriteOutput("Server's Local Time: " & tellTimeObj.getLocalTime()); WriteOutput("
Calculated UTC Time: " & tellTimeObj.

PAGE 222

Invoking component methods using a URL To invoke a component method using a URL, you must append the method name to the URL in standard URL query-string, name-value syntax. You can invoke only one component method per URL request; for example: http://localhost:8500/tellTime.cfc?method=getLocalTime Note: To use URL invocation, you must set the access attribute of the cffunction tag to remote.

PAGE 223

To invoke component methods using a form: 1. Create a corpFind.cfm file with the following contents:
Find People

Enter employee's last Name:

In the example, the form tag’s action attribute points to the corpQuery component and invokes the getEmp method. 2. Create a corpQuery.

PAGE 224

Invoking components as web services Any application, whether it is a ColdFusion application, a Java application, JSP page, or a .Net application, can access well-formed ColdFusion components as web services by referencing the WSDL file that ColdFusion automatically generates. To see a component’s WSDL definition, specify the component web address in a URL, followed by ?wsdl; for example: http://localhost:8500/MyComponents/arithCFC.

PAGE 225

Passing parameters to methods This section describes how to pass parameters to a method in a CFC, including: • Passing parameters to methods using the cfinvoke tag • Passing parameters in direct method invocations • Passing parameters in a URL Passing parameters to methods using the cfinvoke tag When you use the cfinvoke tag, ColdFusion MX provides several methods for passing parameters to CFC methods: • As cfinvoke tag attributes, in name="value" format • In the cfinvoke tag argumentcollection attribute

PAGE 226

The following example passes the Form scope to the addUser method of the UserDataCFC component. In the method, each form field name is a parameter name; the method can use the contents of the form fields to add a user to a database. Passing parameters using the cfinvokeargument tag To pass parameters in the cfinvoke tag body, use the cfinvokeargument tag.

PAGE 227

• You can pass positional parameters to a method by separating them with commas. The following example calls the getAuth method, and passes the name and password as positional parameters: authorized = securityCFC.getAuth("Almonzo", "LauRa123"); Note: For more information on using positional parameters and component methods in ColdFusion functions, see “Creating user-defined functions” on page 172. Passing parameters in a URL ColdFusion lets you pass parameters to CFC methods in a URL.

PAGE 228

The Variables scope The Variables scope in a CFC is private to the CFC. It includes variables defined in the CFC body (initialization or constructor code) and in the CFC methods. When you set Variables scope variables in the CFC, they cannot be seen by pages that invoke the CFC. The CFC Variables scope does not include any of the Variables scope variables that are declared or available in the page that instantiates or invokes the CFC.

PAGE 229

In this example, the callGreetMe.cfm page does the following: 1. Sets the MyName variable in its Variables scope to Wilson. 2. Displays the Variables.MyName value. 3. Calls the greetMe CFC and passes its Variables scope as a parameter. 4. Displays the value returned by the greetMe CFC. 5. Displays the Variables.MyName value. 6. Invokes the VarScopeInCfc method, which displays the value of Variables.MyName within the CFC. When you browse the callGreetMe.

PAGE 230

Tip: You should always use the Var keyword on variables that are only used inside of the function in which they are declared. You must define all function local variables at the top of the function definition, before any other CFML code; for example: Any arguments declared with the cfargument tag must appear before any variables defined with the cfset tag.

PAGE 231

Using component inheritance Component inheritance lets you import component methods and properties from one component to another component. Inherited components share any component methods or properties that they inherit from other components, and ColdFusion MX initializes instance data in the parent CFC when you instantiate the CFC that extends it. When using component inheritance, inheritance should define an is a relationship between components. For example, a component named president.

PAGE 232

When you browse the inherit.cfm file, the manager component refers to the basesalary defined in employee.cfc, which is the base component; the president component refers to both the basesalary defined in the employee component, and the mgrBonus defined in the manager component. The manager component is the parent class of the president component. Using the component.cfc file All CFCs automatically extend the ColdFusion WEB-INF/cftags/component.cfc component.

PAGE 233

3. Create the president.cfc file with the following content: 4. Create the payday.

PAGE 234

To invoke a packaged component method using the cfinvoke tag: 1. In your web root directory, create a directory named appResources. 2. In the appResources directory, create a directory named components. 3. Copy the tellTime2.cfc file you created in “Invoking methods of a CFC instance” on page 218 and the getUTCTime.cfm file that you created in “Putting executable code in a separate file” on page 207 to the components directory. 4. Create the timeDisplay.

PAGE 235

Code that manipulates persistent scope CFC properties must be locked, just as all other code that manipulates persistent scope properties must be locked.

PAGE 236

The following example creates a component method that deletes files: In the example, the cffunction tag includes the roles attribute to specify the user roles allowed to access it. In this example, only users in the role admin and manager can access the function.

PAGE 237

Requesting a component page from the browser When you access a CFC directly with a web browser without specifying a component method, the following chain of events occurs: 1. The request is redirected to the cfcexplorer.cfc file, which is located in the cf_root/wwwroot/ CFIDE/componentutils directory. 2. The cfcexplorer component prompts users for the ColdFusion RDS or Administrator password, if necessary. 3. The cfcexplorer component renders an HTML description and returns it to the browser.

PAGE 238

multiply* private numeric multiply ( numeric argA, numeric argB ) Output: enabled Parameters: argA: numeric, optional, argA argB: numeric, optional, argB Using the ColdFusion component browser You can also browse the components available in ColdFusion using the component browser, which is located at cf_root/wwwroot/CFIDE/componentutils/componentdoc.cfm. The browser has three panes: • The upper-left pane lists all CFC packages that ColdFusion can access, and has all components and refresh links.

PAGE 239

• Within each function structure, a Parameters element that contains an array of parameters specified by cfargument tags. Information on each parameter includes any metadata-only attributes. • Information about any properties that are specified using the cfproperty tag. To display metadata for a CFC: 1. Create the tellAboutCfcs.cfm file in the same directory as the telltime.cfc file, with the following code: You then use this tag to convert the text to bold: This is bold text You can also use cfswitch to determine the execution mode of a custom tag:

PAGE 253

A custom tag can access and modify the generated content of any of its instances using the thisTag.GeneratedContent variable. In this context, the term generated content means the results of processing the body of a custom tag. This includes all text and HTML code in the body, the results of evaluating ColdFusion variables, expressions, and functions, and the results generated by descendant tags. Any changes to the value of this variable result in changes to the generated content.

PAGE 254

The following example shows a cftreeitem tag nested within a cftree tag: The calling tag is known as an ancestor, parent, or base tag, while the tags that ancestor tags call are known as descendant, child, or sub tags. Together, the ancestor and all descendant tags are called collaborating tags. In order to nest tags, the parent tag must have a closing tag.

PAGE 255

What data is accessible? To enable developers to obtain maximum productivity in an environment with few restrictions, CFML custom tags can expose all their data to collaborating tags. When you develop custom tags, you should document all variables that collaborating tags can access and/or modify. When your custom tags collaborate with other custom tags, you should make sure that they do not modify any undocumented data.

PAGE 256

The baseTag attribute specifies the name of the base tag that gets access to this tag’s attributes. The dataCollection attribute specifies the name of the structure in which the base tag stores the sub-tag data. Its default value is AssocAttribs. You only need to specify a dataCollection attribute if the base tag can have more than one type of subtag. It is convenient for keeping separate collections of attributes, one per tag type.

PAGE 257

Example: ancestor data access This example creates two custom tags and a simple page that calls each of the custom tags. The first custom tag calls the second. The second tag reports on its status and provides information about its ancestors. To create the calling page: 1. Create a ColdFusion page (the calling page) with the following content: Call cf_nesttag1 which calls cf_nesttag2

Call cf_nesttag2 directly

2. Save the page as nesttest.cfm.

PAGE 258

I'm running in the context of a custom tag named #inCustomTag#.
I'm located inside the custom tag code either because it is in its start or end execution mode.

PAGE 259

CHAPTER 12 Building Custom CFXAPI Tags Sometimes, the best approach to application development is to develop elements of your application by building executables to run with Macromedia ColdFusion. Perhaps the application requirements go beyond what is currently feasible in CFML. Perhaps you can improve application performance for certain types of processing. Or, you have existing code that already solves an application problem and you want to incorporate it into your ColdFusion application.

PAGE 260

• • • • Generate ColdFusion queries for interfacing with non-ODBC based information sources. Dynamically generate HTML to be returned to the client. Set variables within the ColdFusion application page from which they are called. Throw exceptions that result in standard ColdFusion error messages. You can build CFX tags using C++ or Java. Note: ColdFusion MX provides several different techniques to create reusable code, including custom tags.

PAGE 261

Configuring the classpath To configure your development environment to build Java CFX tags, you must ensure that the supporting classes are visible to your Java compiler. These classes are located in the cfx.jar archive, located in one of the following directories: Server configuration J2EE configuration cf_root/wwwroot/WEB-INF/lib cf_webapp_root/WEB-INF/lib Consult your Java development tool documentation to determine how to configure the compiler classpath for your particular environment. The cfx.

PAGE 262

3. Compile the java source file into a class file using the Java compiler. If you are using the command-line tools bundled with the JDK, use the following command line, which you execute from within the classes directory: javac -classpath cf_root\WEB-INF\lib\cfx.jar MyHelloColdFusion.java Note: The previous command works only if the Java compiler (javac.exe) is in your path. If it is not in your path, specify the fully qualified path; for example, c:\jdk1.3.

PAGE 263

ColdFusion processes the page and returns a page that displays the text “Hello, Les.” If an error is returned instead, check the source code to make sure you have entered it correctly. To delete a CFX tag in the ColdFusion MX Administrator: 1. In the ColdFusion MX Administrator, select Extensions > CFX Tags to open the CFX Tags page. 2. For the tag you want to delete, click the Delete icon in the Controls column of the Registered CFX Tags list.

PAGE 264

Response object The Response object is passed to the processRequest method of the CustomTag interface. The following table lists the methods of the Response object for writing output, generating queries, and setting variables within the calling page: Method Description write Outputs text to the calling page. setVariable Sets a variable in the calling page. addQuery Adds a query to the calling page. writeDebug Outputs text to the debug stream.

PAGE 265

Note: The Java source file that implements cfx_ZipBrowser, ZipBrowser.java, is included in the cf_root/cfx/java/distrib/examples (server configuration) or cf_webapp_root/WEB-INF/cfusion/cfx/ java/distrib/examples (J2EE configuration) directory. Compile ZipBrowser.java to implement the tag. The tag’s archive attribute specifies the fully qualified path of the zip archive to browse. The tag’s name attribute must specify the query to return to the calling page.

PAGE 266

files.setData( iRow, iSize, String.valueOf(entry.getSize()) ) ; files.setData( iRow, iCompressed, String.valueOf(entry.getCompressedSize()) ) ; // finish up with entry zin.closeEntry() ; } // close the archive zin.close() ; } } Approaches to debugging Java CFX tags Java CFX tags are not stand-alone applications that run in their own process, like typical Java applications. Rather, they are created and invoked from an existing process.

PAGE 267

To determine whether a CFX tag is invoked with the debug attribute, use the Request.debug method. To write debugging output in a special debugging block after the tag finishes executing, use the Response.writeDebug method. For information on using these methods, see Chapter 8, “ColdFusion Java CFX Reference,” in CFML Reference. Debugging in a Java IDE You can use a Java IDE to debug your Java CFX tags. This means you can develop your Java CFX tag and debug it in a single environment.

PAGE 268

After you implement a main method as described previously, you can debug your Java CFX tag using an interactive, single-step debugger. Specify your Java CFX class as the main class, set breakpoints as appropriate, and begin debugging. Debugging classes example The following example demonstrates how to use the debugging classes: import java.util.Hashtable ; import com.allaire.cfx.

PAGE 269

Developing CFX tags in C++ The following sections provide information to help you develop CFX tags in C++. Sample C++ CFX tags Before you begin development of a CFX tag in C++, you might want to study the two CFX tags included with ColdFusion MX. These examples will help you get started working with the CFXAPI. The two example tags are as follows: • • CFX_DIRECTORYLIST CFX_NTUSERDB Queries a directory for the list of files it contains. (Windows only) Lets you add and delete Windows NT users.

PAGE 270

Debugging C++ CFX tags After you configure a debugging session, you can run your custom tag from within the debugger, set breakpoints, single-step, and so on. Debugging in Windows You can debug custom tags within the Visual C++ environment. To debug C++ CFX tags in Windows: 1. Build your C++ CFX tag using the debug option. 2. Restart ColdFusion. 3. Start Visual C++. 4. Select Build > Start Debug > AttachProcess. 5. Select jrunsvc.exe. Macromedia recommends that you shut down all other Java programs. 6.

PAGE 271

To delete a CFX tag: 1. In the ColdFusion MX Administrator, select Extensions > CFX Tags to open the CFX Tags page. 2. For the tag you want to delete, click the Delete icon in the Controls column of the Registered CFX Tags list.

PAGE 272

Chapter 12: Building Custom CFXAPI Tags

PAGE 273

This part describes how to develop ColdFusion applications. It describes the elements of a ColdFusion application and how to structure an application, handle errors, use variables that are shared among pages, lock code segments, and secure your application. It also describes how to create a globalized application, and debug and troubleshoot application problems. The following chapters are included: Chapter 13: Designing and Optimizing a ColdFusion Application . . . . . . . . . . . . . . . . . . . .

PAGE 274

PAGE 275

CHAPTER 13 Designing and Optimizing a ColdFusion Application This chapter describes the elements that make your ColdFusion pages into an effective Internet application. It provides an overview of application elements, describes how you can structure an application on your server, and provides detailed information on using the Application.cfc and Application.cfm files. It also describes coding methods for optimizing application efficiency. Contents About applications . . . . . . . . . . . . . . . . . . . .

PAGE 276

What appears to a user to be a single application (for example, a company’s website), might consist of multiple ColdFusion MX applications. ColdFusion MX applications are not J2EE applications. If you do not specify an application name in your Application.cfc file or cfapplication tag, however, the Application scope corresponds to the J2EE application servlet context. ColdFusion MX applications end when the application has been inactive for the application timeout period or the server stops.

PAGE 277

The application framework The application framework is the overall structure of the application and how your directory structure and application pages reflect that structure. You can use a single application framework to structure multiple ColdFusion applications into a single website or Internet application. You can structure a ColdFusion application by using many methodologies. For example, the Fusebox application development methodology is one popular framework for developing ColdFusion web applications.

PAGE 278

Application events and the Application.cfc file. In ColdFusion MX 7, Macromedia introduced application events and the Application.cfc file, which defines application settings and implements methods to handle the application events. Application events are specific occurrences during the life cycle of an application. Each time one of these events occurs, ColdFusion MX runs the corresponding method in your Application.cfc file (also referred to as the application CFC).

PAGE 279

The Application.cfm page can define the application. It can contain the cfapplication tag that specifies the application name, and code on this page is processed for all pages in the application. This page can define application-level settings, functions, and features. The OnRequestEnd.cfm page is used in fewer applications than the Application.cfm page. It lets you provide common clean-up code that gets processed after all application pages, or specify dynamic footer pages. Tip: The OnRequestEnd.

PAGE 280

How ColdFusion MX finds and process application definition pages ColdFusion MX uses the following rules to locate and process the Application.cfc, Application.cfm, and OnRequestEnd.cfm pages that define application-specific elements. The way ColdFusion MX locates these files helps determine how you structure an application. Each time ColdFusion MX processes a page request it does the following: 1.

PAGE 281

• You can have multiple Application.cfc files, Application.cfm files, and cfapplication tags that use the same application name. In this case, all pages that have the same name share the same application settings and Application scope and can set and get all the variables in this scope. ColdFusion uses the parameter settings of the cfapplication tag or the most recently processed file, if the settings, such as the session time-out, differ among the files.

PAGE 282

• In the example on the right, Bandwidth Associates uses the settings in individual Application.cfc files to create individual ColdFusion applications at the departmental level. Only the Products application pages are processed using the settings in the root Application.cfc file. The Consulting, Marketing, and Sales directories each have their own Application.cfc file. Web Wonder, Inc. Bandwith Associates Application.cfc Products Application.cfc Products Orders Consulting Support Application.

PAGE 283

This section describes the following topics: • Naming the application • Setting application properties • Setting page processing options For information on setting default variables, see “You can set default variables and applicationlevel constants in Application.cfc. For example, you can do the following:” on page 287. Naming the application Define the application and give it a name by setting the This.name variable in the Application.cfc initialization section, before the method definitions.

PAGE 284

Variable Default Description setClientCookies True Whether to send CFID and CFTOKEN cookies to the client browser. setDomainCookies False Whether to use domain cookies for the CFID and CFTOKEN values used for client identification, and for Client scope variables stored using cookies. If False, ColdFusion MX uses host-specific cookies. Set to True for applications running on clusters. The following example code from the top of an Application.

PAGE 285

You can put an application-wide cfsetting tag in the component initialization code, normally following the This scope application property settings, as the following example shows: This.name="MyAppl"; This.clientmanagement="True"; This.loginstorage="Session" ; This.sessionmanagement="True" ; This.sessiontimeout=CreateTimeSpan(0,0,1,0); The cfsetting tag in this example affects all pages in an application.

PAGE 286

When ColdFusion MX receives a request, it instantiates the Application CFC and runs the Application.

PAGE 287

If your Application.cfc defines utility functions that you want available on request pages and does not use an onRequest method, you must explicitly put the functions in a ColdFusion MX scope, such as the Request scope, as the following code shows:

PAGE 288

Managing sessions in Application.cfc You use the onSessionStart and onSessionEnd methods to configure and manage user sessions; that is, to control resources that are used by multiple pages while a user is accessing your site from during a single browser session. The session begins when a user first requests a page in your application, and ends either when the session times out or, if you are using J2EE session management, when the user closes the browser when the user closes the browser.

PAGE 289

The following sections explain how you can use each of the Application.cfc request methods to manage requests. For more information, see entries for onRequestStart, onRequest, and onRequestEnd in CFML Reference. Using the onRequestStart method This method runs at the beginning of the request. It is useful for user authorization (login handling), and for request-specific variable initialization, such as gathering performance statistics.

PAGE 290

Using the onRequestEnd method You use the onRequestEnd method for code that should run at the end of each request. (In ColdFusion versions through ColdFusion MX 6.1, you would use the OnRequestEnd.cfm page for such code.) Typical uses include displaying dynamic footer pages. For an example, see onSessionEnd in CFML Reference. Note: If you do not include an onRequest method in Application.

PAGE 291

To identify a server-side validation error, search the Arguments.Exception.StackTrace field for coldfusion.filter.FormValidationException. You can then handle the error directly in your onError routine, or throw the error so that either the ColdFusion default validation error page or a page specified by an cferror tag in your Application.cfc initialization code handles it. Example: error Handling with the onError method The following Application.

PAGE 292

You entered the following valid data in the field
#form.intinput# Note: For more information on server-side validation errors, see Chapter 28, “Validating Data,” on page 659. Example: a complete Application.cfc The following example is a simplified Application.

PAGE 293

PAGE 294
PAGE 295
• Put in the onSessionStart method any code that initializes Session scope variables, and any other application-specific code that executes only when the session starts. Remove any code that tests for the existence of Session scope variables to be for initialized and the Session scope lock that surrounds the code that sets the Session scope variables. • Put in the onRequestStart method any cflogin tag and related authentication code.

PAGE 296

Defining page processing settings The cfsetting tag lets you specify page processing attributes that you might want to apply to all pages in your application. For more information, see “Setting page processing options” on page 284. Setting application default variables and constants You can set default variables and application-level constants on the Application.cfm page.

PAGE 297

#Application.

PAGE 303

Code Description
Check out the following specials

#ItemNAme# #Item_Link# #Description# #salePrice#

Displays the sale items in a table. Inside a cfoutput tag, calculates each item’s sale price and displays the item information in a table row. Because this code is inside a cfsavecontent tag, ColdFusion does not display the results of the cfoutput tag.

PAGE 304

The following example executes a Sybase stored procedure that returns three result sets, two of which the example uses. The stored procedure returns the status code and one output parameter, which the example displays.

PAGE 305

Reviewing the code The following table describes the code and its function: Code Description Populates the cfstoredproc statusCode variable with the status code returned by stored procedure.

PAGE 306

Using the cfquery tag cachedWithin attribute The cfquery tag cachedWithin attribute tells ColdFusion to save the results of a database query for a specific period of time. This way, ColdFusion accesses the database on the first page request, and does not query the database on further requests until the specified time expires. Using the cachedWithin attribute can significantly limit the overhead of accessing databases that do not change rapidly.

PAGE 307

CHAPTER 14 Handling Errors Macromedia ColdFusion MX includes many tools and techniques for responding to errors that your application encounters. These tools include error handling mechanisms and error logging tools. This chapter describes these tools and how to use them. This chapter does not discuss techniques for preventing errors, including methods for specifying user input validation. It also does not discuss code debugging.

PAGE 308

• Use the cferror tag to specify ColdFusion pages to handle specific types of errors. • Use the cftry, cfcatch, cfthrow, and cfrethrow tags to catch and handle exception errors directly on the page where they occur. • In CFScript, use the try and catch statements to handle exceptions. • Use the onError event in Application.cfc to handle exception errors that are not handled by try/catch code on the application pages. • Log errors. ColdFusion logs certain errors by default.

PAGE 309

Error causes fall in the broad categories listed in the following table: Category Description Program errors Can be in the code syntax or the program logic. The ColdFusion compiler identifies and reports program syntax errors when it compiles CFML into Java classes. Errors in your application logic are harder to locate. For information on debugging tools and techniques, see Chapter 18, “Debugging and Troubleshooting Applications,” on page 423.

PAGE 310

About ColdFusion exceptions You can categorize ColdFusion exceptions in two ways: • When they occur • Their type When exceptions occur ColdFusion errors can occur at two times, when the CFML is compiled into Java and when the resulting Java executes, called runtime exceptions. Compiler exceptions Compiler exceptions are programming errors that ColdFusion identifies when it compiles CFML into Java.

PAGE 311

Basic exception types All ColdFusion exceptions except for custom exceptions belong to a basic type category. These types consist of a broadly-defined categorization of ColdFusion exceptions. The following table describes the basic exception types: Type Type name Description Database failures Database Failed database operations, such as failed SQL statements, ODBC problems, and so on.

PAGE 312

Custom exceptions You can generate an exception with your own type by specifying a custom exception type name, for example MyCustomErrorType, in a cfthrow tag. You then specify the custom type name in a cfcatch or cferror tag to handle the exception. Custom type names must be different from any built-in type names, including basic types and Java exception classes. Advanced exception types The Advanced exceptions consist of a set of specific, narrow exception types.

PAGE 313

For more information on using hidden form field validation, see Chapter 28, “Validating Data,” on page 659. For more information on Application.

PAGE 314

Error messages and the standard error format If your application does not handle an error, ColdFusion displays a diagnostic message in the user’s browser. Error information is also written to a log file for later review. (For information on error logging, see “Logging errors with the cflog tag” on page 321.) The standard error format consists of the information listed in the following table. ColdFusion does not always display all sections.

PAGE 315

The missing error page can use CFML tags and variables. In particular, you can use the CGI.script_name variable in text such as the following to identify the requested page: The page #Replace(CGI.script_name, "/", "")# is not available.
Make sure that you entered the page correctly.
(In this code, the Replace function removes the leading slash sign from the script name to make the display more friendly.

PAGE 316

Handling runtime exceptions You have many choices for handling exceptions, and the exact path you take depends on your application and its needs. The following table provides a guide to selecting an appropriate technique: Technique Use cftry Place cftry blocks around specific code sections where exceptions can be expected and you want to handle those exceptions in a context-specific manner; for example, if you want to display an error message that is specific to that code.

PAGE 317

Specifying custom error messages with the cferror tag Custom error pages let you control the error information that users see. You can specify custom error pages for different types of errors and handle different types of errors in different ways. For example, you can create specific pages to handle errors that could be recoverable, such as request time-outs. You can also make your error messages consistent with the look and feel of your application.

PAGE 318

The following cferror tag specifies a custom error page for exceptions that occur in locking code and informs the error page of the of an e-mail address it can use to send a notification each time this type of error occurs: For detailed information on the cferror tag, see CFML Reference.

PAGE 319

The following table describes the variables available on error pages: Error page type Error variable Description Validation error.invalidFields Unordered list of validation errors that occurred. This includes any text that you specify in the value attribute or a hidden tag used to validate form input. error.validationHeader Text for the header of the default validation message. error.validationFooter Text for the footer of the default validation message. error.

PAGE 320

In general, production Exception and Request pages should not display detailed error information, such as that supplied by the error.diagnostics variable. Typically, Exception pages e-mail detailed error information to an administrative address or log the information using the cflog tag instead of displaying it to the user. For more information on using the cflog tag, see “Logging errors with the cflog tag” on page 321.

PAGE 321

Logging errors with the cflog tag ColdFusion provides extensive capabilities for generating, managing, and viewing log files, as described in Configuring and Administering ColdFusion MX. It also provides the cflog tag which adds entries to ColdFusion logs. ColdFusion automatically logs errors to the default logs if you use the default error handlers. In all other cases, you must use the cflog tag in your error handling code to generate log entries.

PAGE 322

Reviewing the code The following table describes the highlighted code and its function: Code Description When this page is processed, log an entry in the file myapp_errors.log file in the ColdFusion log directory.

PAGE 323

This ability to handle exceptions directly in your application pages enables your application to do the following: • Respond appropriately to specific errors within the context of the current application page • Recover from errors whenever possible.

PAGE 324

Here is an outline for using cftry and cfcatch to handle errors: Put your application code here ... Add exception processing code here ... Add exception processing code here ... ... Add exception processing code appropriate for all other exceptions here ...

PAGE 325

• For cases when a cfcatch block is not able to successfully handle an error, consider using the cfrethrow tag, as described in “Using the cfrethrow tag” on page 333. • If an exception can be safely ignored, use a cfcatch tag with no body; for example: • In particularly problematic cases, you might enclose an exception-prone tag in a specialized combination of cftry and cfcatch tags to immediately isolate the tag's exceptions.

PAGE 326

The structure at position 1 in the array represents the currently executing tag at the time the exception was detected. The structure at position ArrayLen(cfcatch.tagContext) represents the initial tag in the stack of tags that were executing when the compiler detected the exception. The following table lists the tagContext structure attributes: Entry Description Column Obsolete (retained for backwards compatibility). Always 0. ID The tag in which the exception occurred.

PAGE 327

Locking exceptions The following additional information is available for exceptions related to errors that occur in cflock tags: Property variable Description cfcatch.lockName The name of the affected lock. This is set to "anonymous" if the lock name is unknown. cfcatch.lockOperation The operation that failed. This is set to "unknown" if the failed operation is unknown.

PAGE 328

Missing Include File

Message: #cfcatch.Message#
Detail: #cfcatch.Detail#
File name: #cfcatch.MissingFileName#
SELECT * FROM Employee WHERE LastName = ’#attributes.EmpName#’

PAGE 336

Handle all unhandled exceptions, including rethrown exceptions, by displaying a message and exiting to the calling page.--->
Sorry

An unexpected error happened in processing your user inquiry. Please report the following to technical support:
Type: #cfcatch.Type# Message: #cfcatch.

PAGE 337

Code Description If the second database query failed with a database error, gives up silently. Because the Database type cfcatch tag does not have a body, the tag exits. The calling page does not get a getEmpsResult variable. It cannot tell whether the database had no match or an unrecoverable database error occurred, but it does know that no match was found.

PAGE 338

Chapter 14: Handling Errors

PAGE 339

CHAPTER 15 Using Persistent Data and Locking Macromedia ColdFusion MX provides several variable scopes in which data persists past the life of a single request. These are the Client, Application, Session, and Server scopes. These scopes let you save data over time and share data between pages and even applications. (This chapter refers to these scopes as persistent scopes.) In particular, you can use the Client and Session scopes to maintain information about a user across multiple requests.

PAGE 340

About persistent scope variables ColdFusion MX provides four variable scopes, described in the following table, that let you maintain data that must be available to multiple applications or users or must last beyond the scope of the current request. Variable scope Description Client Contains variables that are available for a single client browser over multiple browser sessions in an application. For information about browser sessions, see, “What is a session?” on page 352.

PAGE 341

ColdFusion persistent variables and ColdFusion structures All persistent scopes are available as ColdFusion structures. As a result, you can use ColdFusion structure functions to access and manipulate Client, Session, Application, and Server scope contents. This chapter does not cover using these functions in detail, but does mention features or limitations that apply to specific scopes.

PAGE 342

Using variables in clustered systems Because memory variables are stored in memory, they are not available to all servers in a cluster. As a result, you generally do not use Session, Application, or Server scope variables in clustered environment. However, you might use these scope variables in a clustered system in the following circumstances: • If the clustering system supports “sticky” sessions, in which the clustering system ensures that each user session remains on a single server.

PAGE 343

About client and session variables ColdFusion provides two tools for managing the client state: client variables and session variables. Both types of variables are associated with a specific client, but you manage and use them differently, as described in the following table: Variable type Description Client Data is saved as cookies, database entries, or Registry entries. Data is saved between server restarts, but is initially accessed and saved more slowly than data stored in memory.

PAGE 344

About client identifiers To use client and session variables, ColdFusion must be able to identify the client. It normally does so by setting the following two cookie values on the client’s system: • • CFID A sequential client identifier CFToken A random-number client security token These cookies uniquely identify the client to ColdFusion, which also maintains copies of the variables as part of the Session and Client scopes.

PAGE 345

To use ColdFusion session variables without using cookies, each page must pass the CFID and CFToken values to any page that it calls as part of the request URL. If a page contains any HTML href a= links, cflocation tags, form tags, or cfform tags the tags must pass the CFID and CFToken values in the tag URL. To use J2EE session management, you must pass the jsessionid value in page requests.

PAGE 346

Providing Session security ColdFusion uses the same client identifiers for the Client scope and the standard Session scope. Because the CFToken and CFID values are used to identify a client over a period of time, they are normally saved as cookies on the user’s browser. These cookies persist until the client’s browser deletes them, which can be a considerable length of time. As a result, hackers could have more access to these variables than if ColdFusion used different user identifiers for each session.

PAGE 347

Choosing a client variable storage method By default, Coldfusion stores client variables in the Registry. In most cases, however, it is more appropriate to store the information as client cookies or in a SQL database. The ColdFusion MX Administrator Client Variables page controls the default client variable location. You can override the default location by specifying a This.clientStorage value in Application.cfc or by setting the clientStorage attribute in the cfapplication tag.

PAGE 348

If ColdFusion can identify that the database you are using supports SQL creation of database tables, you only need to create the database in advance. When you click the Add button on the Select Data Source to Add as Client Store box on the Memory Variables page, the Administrator displays a Add/Edit Client Store page which contains a Create Client Database Tables selection box. Select this option to have ColdFusion create the necessary tables in your database.

PAGE 349

This.clientStorage="mydatasource"; The following code from an Application.cfm file does the same thing as the previous example: Using client variables When you enable client variables for an application, you can use them to keep track of long-term information that is associated with a particular client. Client variables must be simple data types: strings, numbers, lists, Booleans, or date and time values.

PAGE 350

Standard client variables The Client scope has the following built-in, read-only variables that your application can use: Variable Description Client.CFID The client ID, normally stored on the client system as a cookie. Client.CFToken The client security token, normally stored on the client system as a cookie. Client.URLToken Value depends on whether J2EE session management is enabled.

PAGE 351

Deleting client variables To delete a client variable, use the StructDelete function or the DeleteClientVariable function. For example, the following lines are equivalent: The Client Variables page in the ColdFusion MX Administrator lets you set a time-out period of inactivity after which ColdFusion removes client variables stored in either the Registry or a data source.

PAGE 352

Configuring and using session variables Use session variables when you need the variables for a single site visit or set of requests. For example, you might use session variables to store a user’s selections in a shopping cart application. (Use client variables if you need a variable in multiple visits.) Caution: Put code that uses session variables inside cflock tags in circumstances that might result in race conditions from multiple accesses to the same variable.

PAGE 353

J2EE session management provides the following advantages over ColdFusion session management: • J2EE session management uses a session-specific session identifier, jsessionid, which is created afresh at the start of each session. • You can share session variables between ColdFusion pages and JSP pages or Java servlets that you call from the ColdFusion pages. • The session automatically ends when the user closes all browser windows.

PAGE 354

Enabling session variables in your application You must also enable session variables in the initialization code of your Application.cfc file or in the cfapplication tag in your Application.cfm file. Do the following in the Application.cfc initialization code, below the cfcomponent tag, to enable session variables: • Set This.sessionManagement="Yes". • Set This.name to specify the application's name. • Optionally, set This.sessionTimeout to set an application-specific session time-out value.

PAGE 355

Standard session variables If you use ColdFusion session variables, the Session scope has four built-in, read-only variables that your application can use. If you use J2EE session management, the Session scope has two built-in variables. Generally, you use these variables in your ColdFusion pages only if your application supports browsers that do not allow cookies. For more information on supporting browsers that do not allow cookies, see “Using client and session variables without cookies” on page 344.

PAGE 356

Creating and deleting session variables Use a standard assignment statement to create a new session variable, as follows:

PAGE 357

• Clearing the Session scope does not clear the session ID, and future requests from the browser continue to use the same session ID until the browser exits. It also does not log the user out, even if you use Session scope storage for login information. Always use the cflogout tag to log users out. • If you use J2EE session management, you can invalidate the session, as follows:

PAGE 358

Configuring and enabling application variables To use application variables, do the following: • Ensure that they are enabled in the ColdFusion MX Administrator. (They are enabled by default.) • Specify the application name by setting the This.name variable in the initialization code of the Application.cfc or by setting the name attribute of the cfapplication tag for the current page. Note: ColdFusion supports unnamed applications for compatibility with J2EE applications.

PAGE 359

Because each Application scope variable is shared in memory by all requests in the application, these variables can become bottlenecks if used inappropriately. Whenever a request is reading or writing an Application scope variable, any other requests that use the variable must wait until the code accessing the variable completes. This problem is increased by the processing time required for locking.

PAGE 360

Variable Description Server.ColdFusion.ProductVersion The version number for the server that is running, such as 6,0,0. Server.ColdFusion.Rootdir Directory under which ColdFusion is installed, such as C:\cfusion. Server.ColdFusion.SerialNumber The serial number assigned to this server installation. Server.ColdFusion.SupportedLocales The locales, such as English (US) and Spanish (Standard), supported by the server. Server.OS.

PAGE 361

Similarly, ColdFusion MX cannot automatically ensure that two sections of code do not attempt to access external resources such as files, databases, or CFX tags that cannot properly handle simultaneous requests. Nor can ColdFusion MX ensure that the order of access to these shared resources is consistent and results in valid data. By locking code that accesses such resources so that only one thread can access the resource at a time, you can prevent race conditions.

PAGE 362

The cflock tag ensures that while ColdFusion performs the processing in the tag body, no other threads can access the Application scope. As a result, the second transaction is not processed until the first one completes. The processing sequence looks something like the following: 1. Order 1 reaches the lock tag, which gets an Application scope lock. 2. Order 1 reads the total tickets sold as 160. 3. Order 2 reaches the lock tag.

PAGE 363

Using the cflock tag with write-once variables You do not need to use cflock when you read a variable or call a user-defined function name in the Session, Application, or Server scope if it is set in only one place in the application, and is only read (or called, for a UDF) everywhere else. Such data is called write-once. If you set an Application or Session scope variable in Application.

PAGE 364

Although ColdFusion does not prevent you from setting shared variables inside read-only lock tag, doing so loses the advantages of locking. As a result, you must be careful not to set any session, application, or server variables inside a read-only cflock tag body. Note: You cannot upgrade or downgrade a lock from one type to another. In other words, do not nest an exclusive lock in a read-only lock of the same name or scope; the exclusive lock will always time out.

PAGE 365

Controlling locking access to files and CFX tags with the name attribute The cflock name attribute provides a second way to identify locks. Use this attribute when you use locks to protect code that manges file access or calls non-thread-safe CFX code. When you use the name attribute, specify the same name for each section of code that accesses a specific file or a specific CFX tag. Controlling and minimizing lock time-outs You must include a timeout attribute in your cflock tag.

PAGE 366

Considering lock granularity When you design your locking strategy, consider whether you should have multiple locks containing small amounts of code or few locks with larger blocks of code. There is no simple rule for making such a decision, and you might do performance testing with different options to help make your decision.

PAGE 367

Copying shared variables into the Request scope You can avoid locking some shared-scope variables multiple times during a request by doing the following: 1. Copy the shared-scope variables into the Request scope in code with an exclusive lock in the Application.cfc onRequestStart method or the Application.cfm page. 2. Use the Request scope variables on your ColdFusion pages for the duration of the request. 3. Copy the variables back to the shared scope in code with an exclusive lock in the Application.

PAGE 368

exclusive lock ---> ... Examples of cflock The following examples show how to use cflock blocks in a variety of situations.

PAGE 369

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

PAGE 370

Congratulations! You have just selected the longest-wearing, most comfortable turtleneck in the world. Please indicate the color and size you want to buy.

Select a color.

PAGE 371

Example of synchronizing access to a file system The following example shows how to use a cflock block to synchronize access to a file system. The cflock tag protects a cffile tag from attempting to append data to a file already open for writing by the same tag executing on another request. If an append operation takes more than 30 seconds, a request waiting to obtain an exclusive lock to this code might time out.

PAGE 372

Chapter 15: Using Persistent Data and Locking

PAGE 373

CHAPTER 16 Securing Applications This chapter provides an overview of Macromedia ColdFusion security features, including brief descriptions of several ColdFusion security features and references to additional documentation not included in this chapter. This chapter includes a summary of resource security (ColdFusion MX Standard) or sandbox security (ColdFusion MX Enterprise), where security restricts access to specific resources, such as tags and files.

PAGE 374

ColdFusion security features ColdFusion provides scalable, granular security for building and deploying your ColdFusion applications. ColdFusion provides the following types of security resources: Development ColdFusion MX Administrator is protected by a password. Additionally, you can specify a password for access to data sources from Macromedia Dreamweaver MX. For more information on configuring Administrator security passwords, see the ColdFusion MX Administrator online Help.

PAGE 375

Note: You can also use the cfencode utility, located in the cf_root/bin directory, to obscure ColdFusion pages that you distribute. Although this technique cannot prevent persistent hackers from determining the contents of your pages, it does prevent inspection of the pages. About resource and sandbox security ColdFusion provides two levels of resource-based security: • ColdFusion MX Standard refers to its resource-based security as resource security.

PAGE 376

Resource Description Files/directories Sets read, write, execute, and delete access to specified directories, directory trees, or files. Server/ports Controls access from ColdFusion to IP addresses and port numbers. You can specify host names or numeric addresses, and you can specify individual ports and port ranges.. Note: For more information on configuring resource and sandbox security, see Configuring and Administering ColdFusion MX and the ColdFusion MX Administrator online Help.

PAGE 377

Roles enable you to control access in your application resources without requiring the application to maintain knowledge about individual users. For example, suppose you use ColdFusion for your company’s intranet. The Human Resources department maintains a page on the intranet on which all employees can access timely information about the company, such as the latest company policies, upcoming events, and job postings.

PAGE 378

Authenticating users You can use either, or both, of the following forms of authentication to secure your ColdFusion application: • Web server authentication, where the web server authenticates the user and does not allow access to the website by users without valid login IDs • Application authentication, where the ColdFusion application authenticates the user and does not allow access to the application by users without valid login IDs 378 Chapter 16: Securing Applications

PAGE 379

About web server authentication All major web servers support basic HTTP authentication. Some web servers also support other authentication methods, including Digest HTTP authentication and Microsoft NTLM authentication. Note: Macromedia Dreamweaver MX and Studio MX do not support NTLM security with RDS. Therefore, you cannot use RDS with these applications if the ColdFusion RDS servlet (cf_root/ CFIDE/main/ide.cfm) is in a directory that is protected using NTLM security.

PAGE 380

About application authentication With application authentication, you do not rely on the web server to enforce application security. The application performs all user authentication and authorization. The application displays a login page, checks the user’s identity and login against its own authorization store, such as an LDAP directory or database, and logs the user into ColdFusion using the cfloginuser tag.

PAGE 381

When ColdFusion maintains login information in the Session scope, it stores the authentication details in a Session.cfauthorization variable, and ColdFusion uses the session cookie information to identify the user. Session-based authentication has the following advantages over less persistent login storage: • After the user logs in, the user ID and password are not passed between the server and the browser. • The login information and the session share a single time-out.

PAGE 382

Tag or function Purpose cflogout Logs out the current user. Removes knowledge of the user ID and roles from the server. If you do not use this tag, the user is automatically logged out as described in “Logging out users” on page 385. The cflogout tag does not take any attributes, and does not have a body. cfNTauthenticate Authenticates a user name and password against the NT domain on which ColdFusion server is running, and optionally retrieves the user’s groups.

PAGE 383

Specifying the Internet domain Use the cookieDomain attribute to specify the domain of the cookie used to mark a user as logged-in. You use cookieDomain if you have a clustered environment (for example, www.acme.com, www2.acme.com, and so on). This lets the cookie work for all computers in the cluster. For example, to ensure that the cookie works for all servers in the acme.com domain, specify cookieDomain=".acme.com". To specify a domain name, start the name with a period.

PAGE 384

In the Application.cfc onRequestStart method, or a ColdFusion page or CFC method called by the method, you have the following: PAGE 385
Note: You must ensure that your web server is configured correctly to support browser-based login forms for this use. For example, in IIS 5, you must enable anonymous access and might have to disable Basic authentication and Integrated Windows authentication. The following cflogin tag tells the browser to display a login form if the user has not logged in:

PAGE 386

Logging a user out by using the cflogout tag does not close the user’s session, but if you use session login storage, it does remove the login information (the Session.cfauthorization variable) from the Session scope. For more information on ending sessions, see “Ending a session” on page 356.

PAGE 387

6. The application uses the IsUserInRole function to check whether the user belongs to a role before it runs protected code that must be available only to users in that role. 7. The application can use the GetAuthUser function to determine the user ID; for example, to display the ID for personalization. It can also use the ID as a database key to get user-specific data.

PAGE 388

Although this scenario shows one method for implementing user security, it is only an example. For example, your application could require users to log in for only some pages, such as pages in a folder that contains administrative functions. When you design your user security implementation, remember the following: • Code in the cflogin tag body executes only if there is no user logged in.

PAGE 389

The wizard asks you to you select how to authenticate the login information. You can select one of the following options: • Simple You specify a single user ID and password in the wizard. All users must enter this information to log in. You can use this option for testing, or you can use the generated files as a template where you can replace the authentication code with more complex code; for example, to verify the ID and password against a database.

PAGE 390

• The logout method logs a user out. If you specified Browser Dialog Box as the login page type, it also calls the closeBrowser method to close the browser window. This behavior is necessary because the browser continues to send the old login credentials after the user logs out, and the cflogin tag will automatically use them and log the user in again. • The closeBrowser method closes the browser window or tells the user to close the browser window to complete the logout, depending on the browser type.

PAGE 391

With code similar to the following: SELECT * FROM Users WHERE UserName =

PAGE 392

roles = "#roles#" />
Authentication data is missing.
Try to reload the page or contact the site administrator. Reviewing the code The Application.cfc onRequestStart method executes before the code in each ColdFusion page in an application. For more information on the Application.cfc page and when it is executed, see Chapter 13, “Designing and Optimizing a ColdFusion Application,” on page 275.

PAGE 393

Example: securitytest.cfm The securitytest.cfm page shows how any application page can use ColdFusion user authorization features. The web server ensures the existence of an authenticated user, and the Application.cfc page ensures that the user is assigned to roles the page content appears. The securitytest.cfm page uses the IsUserInRole and GetAuthUser functions to control the information that is displayed. The securitytest.cfm page consists of the following:

PAGE 394

Application-based user security example The example in this section shows how you might implement user security by authenticating users and then allowing users to see or use only the resources that they are authorized to access. This example has three ColdFusion pages: • The Application.cfc page contains the authentication logic that checks whether a user is logged in, requests the login page if the user is not logged in, and authenticates the data from the login page.

PAGE 395

You must enter text in both the User Name and Password fields.
SELECT UserID, Roles FROM LoginInfo WHERE UserID = '#cflogin.name#' AND Password = '#cflogin.password#' PAGE 396
The following table describes the CFML code in Application.cfc and its function: 396 Code Description Identifies the application, enables session management, and enables storing login information in the Session scope. Begins the definition of the onRequestStart method that runs at the starts of each request.

PAGE 397

Code Description
Your login information is not valid.
Please Try again
Executes if the query did not return a role. If the database is valid, this means there was no entry matching the user ID and password. Displays a message, followed by the login form. The cfabort tag prevents processing of any code that follows on this page. Ends the loginquery.Roles test code.

PAGE 398

Reviewing the code The following table describes the loginform.cfm page CFML code and its function: Code Description
Please Log In

username:

password:

Displays the login form.

PAGE 399

if (IsUserInRole("Manager")) WriteOutput("Managers see this message.

"); if (IsUserInRole("Employee")) WriteOutput("Employees see this message.

"); if (IsUserInRole("Contractor")) WriteOutput("Contractors see this message.

"); Reviewing the code The following table describes the securitytest.

PAGE 400

Starts the cflogin tag body. Sets several variables to the values used as attributes in the cfldap tag.

PAGE 402

Code Description Catches any exceptions.

PAGE 403

CHAPTER 17 Developing Globalized Applications Macromedia ColdFusion MX lets you develop dynamic applications for the Internet. Many ColdFusion applications are accessed by users from different countries and geographical areas. One design detail that you must consider is the globalization of your application so that you can best serve customers in different areas. This chapter contains information that you can use to develop applications that can be accessible to many different users.

PAGE 404

Globalizing your application requires that you perform one or more of the following actions: • Accept input in more than one language. • Process dates, times, currencies, and numbers formatted for multiple locales. • Process data from a form, database, HTTP connection, e-mail message, or other input formatted in multiple character sets. • Create ColdFusion pages containing text in languages other than English. Defining globalization You will probably find several different definitions for globalization.

PAGE 405

How ColdFusion MX supports globalization ColdFusion MX is implemented in Java. As a Java application, ColdFusion MX uses Java globalization features. For example, ColdFusion MX stores all strings internally using the Unicode character set. Because it uses Unicode, ColdFusion can represent any text data from any language. In addition, ColdFusion MX includes many tags and functions designed to support globalizing your applications.

PAGE 406

About character encodings A character encoding maps each character in a character set to a numeric value that can be represented by a computer. These numbers can be represented by a single byte or multiple bytes. For example, the ASCII encoding uses seven bits to represent the Latin alphabet, punctuation, and control characters. You use Japanese encodings, such as Shift-JIS, EUC-JP, and ISO-2022-JP, to represent Japanese text.

PAGE 407

Computers often must convert between character encodings. In particular, the character encodings most commonly used on the Internet are not used by Java or Windows. Character sets used on the Internet are typically single-byte or multiple-byte (including DBCS character sets that allow single-byte characters). These character sets are most efficient for transmitting data, because each character takes up the minimum necessary number of bytes.

PAGE 408

Character encoding conversion issues Because different character encodings support different character sets, you can encounter errors if your application gets text in one encoding and presents it in another encoding. For example, the Windows Latin-1 character encoding, Windows-1252, includes characters with hexadecimal representations in the range 80-9F, while ISO 8859-1 does not include characters in that range.

PAGE 409

The Server.coldfusion.supportedlocales variable is a comma-delimited list of the locale names that you can specify. ColdFusion also includes a GetLocaleDisplayName function that returns a locale name in a format that is meaningful to users. It lets you display the locale using words in the user’s language; for example, français (France).

PAGE 410

LSCurrencyFormat returns a currency value using the locale convention. PAGE 411
Determining the character encoding of a ColdFusion page When a request for a ColdFusion page occurs, ColdFusion opens the page, processes the content, and returns the results back to the browser of the requestor. In order to process the ColdFusion page, though, ColdFusion has to interpret the page content. One piece of information used by ColdFusion is the Byte Order Mark (BOM) in a ColdFusion page.

PAGE 412

Determining the page encoding of server output Before ColdFusion can return a response to the client, it must determine the encoding to use for the data in the response. By default, ColdFusion returns character data using the Unicode UTF-8 format. ColdFusion pages (.cfm pages) default to using the Unicode UTF-8 format for the response, even if you include the HTML meta tag in the page.

PAGE 413

Tags and functions for globalizing ColdFusion MX supplies many tags and functions that you can use to develop globalized applications. Tags and functions for controlling character encoding The following tags and functions let you specify the character encoding of text that ColdFusion generates and interprets: Tag or function Attribute or parameter Use cfprocessingdirective pageencoding Specifies the encoding of a ColdFusion page so ColdFusion can parse it.

PAGE 414

Tag or function Attribute or parameter Use ToBase64 encoding Specifies the character encoding of the string being converted to Base 64. ToString encoding Returns a string encoded in the specified character encoding. URLDecode charset Specifies the character encoding of the URL being decoded. URLEncodedFormat charset Specifies the character encoding to use for the URL.

PAGE 415

Tag or function Use LSTimeFormat Converts the time part of a date/time value into a string in a localespecific date format. SetLocale Specifies the locale setting. Note: Many functions that have names starting with LS have corresponding functions that do not have this prefix: DateFormat, IsDate, IsNumeric, NumberFormat, ParseDateTime, and TimeFormat. These function use English (US) locale rules.

PAGE 416

Handling data in ColdFusion MX Many of the issues involved with globalizing applications deal with processing data from the various sources supported by ColdFusion MX, including the following: • • • • • • • • • • • • General character encoding issues Locale-specific content Input data from URLs and HTML forms File data Databases E-mail HTTP LDAP WDDX COM CORBA Searching and indexing This section describes how to handle data from each of these sources.

PAGE 417

Supporting the euro The euro is the currency of many European countries, and ColdFusion supports the reading and writing of correctly formatted euro values. Unlike other supported currencies, the euro is not tied to any single country (or locale). The LSCurrencyFormat and LSParseCurrency functions rely on the underlying JVM for their operations, and the rules used for currencies depend on the JVM. For Sun JVMs, the 1.3 releases did not support euros and used the older country-specific currencies. The 1.

PAGE 418

You can also use the SetEncoding function to specify the character encoding of URL parameters. The SetEncoding function takes two parameters: the first specifies a variable scope and the second specifies the character encoding used by the scope. Since ColdFusion writes URL parameters to the URL scope, you specify "URL" as the scope parameter to the function.

PAGE 419

File data You use the cffile tag to write to and read from text files. By default, the cffile tag assumes that the text that you are reading, writing, copying, moving, or appending is in the JVM default file character encoding, which is typically the system default character encoding. For cffile action="Read", ColdFusion MX also checks for a byte order mark (BOM) at the start of the file; if there is one, it uses the character encoding that the BOM specifies.

PAGE 420

E-mail ColdFusion sends e-mail messages using the cfmail, cfmailparam, and cfmailpart tags. By default, ColdFusion sends mail in UTF-8 encoding. You can specify a different default encoding on the Mail page in the ColdFusion MX Administrator, and you can use the charset attribute of the cfmail and cfmailpart tags to specify the character encoding for a specific mail message or part of a multipart mail message.

PAGE 421

Searching and indexing ColdFusion MX supports Verity search through the cfindex, cfcollection, and cfsearch tags. To support multilingual searching, the ColdFusion MX product CD-ROM includes the Verity language packs that you install to support different languages.

PAGE 422

Chapter 17: Developing Globalized Applications

PAGE 423

CHAPTER 18 Debugging and Troubleshooting Applications Macromedia ColdFusion MX provides detailed debugging information to help you resolve problems with your application. This chapter describes how you configure ColdFusion MX to provide debugging information, how to understand the information it provides, and how to use the cftrace and cftimer tags to provide detailed information on code execution.

PAGE 424

Debugging Settings page In the Administrator, the following options on the Debugging Settings page determine the information that ColdFusion displays in debugging output: 424 Option Description Enable Robust Exception Information Enables the display of the following information when ColdFusion displays the exception error page. (Cleared by default.

PAGE 425

Option Description Variables Enables the display of ColdFusion variable values. When this option is cleared, disables display of all ColdFusion variables in the debugging output. (Selected by default.) When enabled, ColdFusion displays the values of variables in the selected scopes. You can select to display the contents of any of the ColdFusion scopes except Variables, Attributes, Caller, and ThisTag.

PAGE 426

Debugging IP addresses page By default, when you enable debugging output, the output is visible only to local users (that is, via IP address 127.0.0.1). You can specify additional IP addresses whose users can see debugging output, or even disable output to local users. In the Administrator, use the Debugging IPs page to specify the addresses that can receive debugging messages.

PAGE 427

General debugging information ColdFusion displays general debugging information. In the classic.cfm output format, the information is at the top of the debugging output. In the dockable.cfm output format, it looks like the following figure: (In the classic.cfm output format, the section is first in the debugging output and has no heading.) The general debugging information includes the following values. The table lists the names used in the classic output template view.

PAGE 428

Execution Time The Execution Time section displays the time required to process the request. It displays information about the time required to process all pages required for the request, including the Application.cfc, Application.cfm, and OnRequestEnd.cfm pages, if used, and any CFML custom tags, pages included by the cfinclude tag, and any ColdFusion component (CFC) pages. Tip: To display execution time for a specific block of code, use the cftimer tag.

PAGE 429

Column Description Count The number of times the page is processed for the request. Template The path name of the page. The page icon indicates the requested page. Any page with an average processing time that exceeds the highlight value that you set on the Debugging Settings page in the ColdFusion MX Administrator appears in red. The next to last line of the output displays the time that ColdFusion took to parse, compile, and load pages, and to start and end page processing.

PAGE 430

By looking at this output in this figure you can determine the following information: • ColdFusion took 0 ms to process an Application.cfm page as part of the request. • The requested page was tryinclude.cfm. It took 203 ms to process this page and all pages required to execute it. The code directly on this page took 71 milliseconds (203 - 93 - 16 - 23) to process. • The mytag2.cfm page was processed three times. All processing took 93 milliseconds, and the average processing time was 31 milliseconds.

PAGE 431

The output displays the following information: • • • • • • • • • Page on which the query is located. The time when the query was made. Query name. An indicator if the result came from a cached query. SQL statement, including the results of processing any dynamic elements such as CFML variables and cfqueryparam tags. This information is particularly useful because it shows the results of all ColdFusion processing of the SQL statement. Data source name.

PAGE 432

Exceptions In the Administrator, when Exception Information is selected on the Debugging Settings page, the debugging output includes a list of all ColdFusion exceptions raised in processing the application page. This section looks like the following figure when displaying information about an exception thrown by the cfthrow tag using the dockable.

PAGE 433

Scope variables In the Administrator, when the Variables option and one or more variable scopes are selected on the Debugging Settings page, the debugging output displays the values of all variables in the selected scopes. The debugging output displays the values that result after all processing of the current page. By displaying selected scope variables you can determine the effects of processing on persistent scope variables, such as application variables.

PAGE 434

Application page selections ColdFusion displays two buttons at the bottom of each page, as described in the following table: Button Description Debug This page Tells ColdFusion to display the debugging information for the selected frame. Refreshes the debug pane if you select it for the current frame (or the application does not use frames). Floating/Docked debug pane Toggles the display between a floating window and a pane docked to the left of the selected frame.

PAGE 435

The debug attribute can be useful to disable query debugging information generated by queries in custom tags that you call frequently, so that you only see the debugging information for queries in pages that call the tags. You can also view stored procedure-specific debugging information by specifying the debug attribute in the cfstoredproc tag. Controlling debugging output with the cfsetting tag Use the cfsetting tag showDebugOutput attribute to turn off debugging output for a specific page.

PAGE 436

Using the cftrace tag to trace execution The cftrace tag displays and logs debugging data about the state of your application at the time the cftrace tag executes. You use it to provide “snapshots” of specific information as your application runs.

PAGE 437

An in-line trace messages look like the following: The following table lists the displayed information: Entry Meaning Trace type (severity) specified in the cftrace call; in this case, Information. [CFTRACE 13:21:11.011] Time when the cftrace tag executed. [501 ms] Time taken for processing the current request to the point of the cftrace tag. [C:\CusionMX\wwwroot\MYStuff\ mydocs\tractest.cfm] Path in the web server of the page that contains the cftrace tag.

PAGE 438

Entry Meaning 501 ms (1st trace)] The time ColdFusion took to process the current request up to the cftrace tag, This is the first cftrace tag processed in this request. If there had been a previous cftrace tag, the parentheses would contain the number of milliseconds between when the previous cftrace tag ran and when this tag ran. [C:\CFusionMX7\wwwroot Path of the page on which the trace tag is located and the line number of the cftrace tag on the page. \MYStuff\mydocs\ tracetest.

PAGE 439

Calling the cftrace tag The cftrace tag takes the following attributes. All attributes are optional. Attribute Purpose abort A Boolean value. If you specify True, ColdFusion stops processing the current request immediately after the tag. This attribute is the equivalent of placing a cfabort tag immediately after the cftrace tag. The default is False. If this attribute is True, the output of the cftrace call appears only in the cftrace.log file. The line in the file includes the text “[ABORTED]”.

PAGE 440

Attribute Purpose type A ColdFusion logging severity type. The inline trace display and dockable.cfm output format show a symbol for each type. The default debugging output shows the type name, which is also used in the log file. The type name must be one of the following: Information (default) Warning Error Fatal Information var The name of a single variable that you want displayed. This attribute can specify a simple variable, such as a string, or a complex variable, such as a structure name.

PAGE 441

Calling the cftimer tag You can control where the cftimer tag displays timing information, as follows: • • Inline • Comment • Debug Displays timing information following the tag. Outline Displays timing information at the beginning of the timed code and draws a box around the timed code. (This requires browser support for the HTML FIELDSET attribute.) Displays timing information in an HTML comment in the format . The default label is cftimer.

PAGE 442

Select View > Source to see timing information

#Parkname#

select * from Departments
Scroll down to CFTimer Times heading to see timing information

PAGE 443

Note: The CFML analyzer does not execute the pages that it checks. Therefore, it cannot detect invalid attribute combinations if the attribute values are provided dynamically at runtime. For more information on using the Code Compatibility Analyzer, see Migrating ColdFusion 5 Applications. Troubleshooting common problems This section describes a few common problems that you might encounter and ways to resolve them.

PAGE 444

Use the cfdump tag to generate a table-formatted display of the variable’s structure and contents. For example, to dump a structure named relatives, use the following line. You must surround the variable name with number signs (#). Data source access and queries Problem: You cannot make a connection to the database. You must create the data source before you can connect.

PAGE 445

This part describes how to access and use sources of data, including SQL (Structured Query Language) databases, LDAP (Lightweight Directory Access Protocol) directories, and Verity document collections. It provides an introduction to the SQL language, describes how to query and update SQL data sources, and how to use record sets and the ColdFusion query of queries mechanism to manipulate record sets.

PAGE 446

PAGE 447

CHAPTER 19 Introduction to Databases and SQL Macromedia ColdFusion MX lets you create dynamic applications to access and modify data stored in a database. You do not need a thorough knowledge of databases to develop ColdFusion applications, but you must know some basic concepts and techniques. This chapter contains an overview of many important database and SQL concepts. This chapter does not contain a complete description of database theory and SQL syntax.

PAGE 448

For example, a table might contain the ID, name, title, and other information for individuals employed by a company. Each row, called a data record, corresponds to one employee. The value of a column within a record is referred to as a record field.

PAGE 449

Using multiple database tables In many database designs, information is distributed to multiple tables.

PAGE 450

d In this example, each table contains a column named EmpID. This column associates a row of the employees table with a row in the addresses table. For example, to obtain all information about an employee, you request a row from the employees table and the row from the addresses table with the same value for EmpID. One advantage of using multiple tables is that you can add tables containing new information without modifying the structure of your existing tables.

PAGE 451

Also, an access to a small table is more efficient than an access to a large table. Therefore, if you update the street address of an employee, you update only the addresses table, without having to access any other table in the database. Database permissions In many database environments, a database administrator defines the access privileges for users accessing the database, usually through username and password.

PAGE 452

A bank might use a transaction to encapsulate a transfer from one account to another. For example, if you transfer money from your savings account to your checking account, you do not want the bank to debit the balance of your savings account unless it also credits your checking account. If the update to the checking account fails, the bank can rollback the debit of the savings account as part of the transaction.

PAGE 453

Tip: If you are using Macromedia Dreamweaver MX 2004 or Macromedia HomeSite+, you can use the built-in query builder to build SQL statements graphically by selecting the tables and records to retrieve. For more information, see “Writing queries using an editor” on page 460. In many cases, you do not want all rows from a table, but only a subset of rows.

PAGE 454

Operators The following basic operators specify conditions and perform logical and numeric functions: Operator Description AND Both conditions must be met OR At least one condition must be met NOT Exclude the condition following LIKE Matches with a pattern IN Matches with a list of values BETWEEN Matches with a range of values = Equal to <> Not equal to < Less than > Greater than <= Less than or equal to >= Greater than or equal to + Addition - Subtraction / Division * Multi

PAGE 455

SQL notes and considerations When writing SQL in ColdFusion, keep the following guidelines in mind: • There is a lot more to SQL than what is covered here. It is a good idea to purchase one or several SQL guides for reference. • The data source, columns, and tables that you reference must exist in order to perform a successful query. • Some DBMS vendors use nonstandard SQL syntax (known as a dialect) in their products.

PAGE 456

The next example uses a SELECT statement to return only a specific set of columns from a table: SELECT LastName, FirstName FROM employees WHERE DeptID=3 The query returns the following table: Filtering results The SELECT statement lets you filter the results of a query to return only those records that meet specific criteria.

PAGE 457

However, this query does not to return the table rows in alphabetical order. You can include an ORDER clause in the SQL, as follows: SELECT the FirstName, LastName, Phone FROM employees ORDER BY LastName, FirstName Using column aliases You might have column names that you do not want to retain in the results of your SQL statement. For example, your database is set up with a column that uses a reserved word in ColdFusion, such as EQ.

PAGE 458

Modifying a database You can use SQL to modify a database in the following ways: • • • • Inserting data into a database Updating data in a database Deleting data from a database Updating multiple tables The following sections describe these modifications. Inserting data into a database You use SQL INSERT statement to write information to a database. A write adds a new row to a database table.

PAGE 459

Updating data in a database Use the UPDATE statement in SQL to update the values of a table row. Update lets you update the fields of a specific row or all rows in the table. The UPDATE statement has the following syntax: UPDATE table_name SET column_name1=value1, ... , column_nameN=valueN [ WHERE search_condition ] Note: There are additional options to UPDATE depending on your database. For a complete syntax description for UPDATE, see the product documentation.

PAGE 460

Updating multiple tables The examples in this section all describe how to modify a single database table. However, you might have a database that uses multiple tables to represent information. One way to update multiple tables is to use one INSERT statement per table and to wrap all INSERT statements within a database transaction. A transaction contains one or more SQL statements that can be rolled back or committed as a unit.

PAGE 461

3. In the Data Bindings panel, click the Plus (+) button and choose Recordset (Query) from the pop-up menu. The Simple Recordset dialog box appears: 4. Complete the dialog box. 5. Click the Test button to execute the query and ensure that it retrieves the information you intended. If you defined a filter that uses parameters input by users, the Test button displays the Test Value dialog box. Enter a value in the Test Value text box and click OK.

PAGE 462

4. Complete the dialog box. 5. Click the Test button to execute the query and ensure that it retrieves the information you intended. If you defined a filter that uses parameters input by users, the Test button displays the Test Value dialog box. Enter a value in the Test Value text field and click OK. If an instance of the record set is successfully created, a table displaying the data from your record set appears. 6.

PAGE 463

The SQL Builder is divided into the following four sections: Section Use Toolbar Contains buttons for SQL keywords and commands. Table pane Provides a view of the tables in your query and allows you to create joins between tables. Properties pane Allows you to set the properties of the query, such as the columns that are being selected or the columns that are being updated. SQL pane Shows you the SQL statement as it is built.

PAGE 464

Chapter 19: Introduction to Databases and SQL

PAGE 465

CHAPTER 20 Accessing and Retrieving Data This chapter describes how to retrieve data from a database and work with query data. This chapter also shows how to use the cfquery tag to query a data source, and use the cfoutput tag to output the query results to a web page. This chapter also describes how to use the cfqueryparam tag to help reduce security risks. Contents Working with dynamic data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

PAGE 466

To query a database, you must use: • ColdFusion data sources • The cfquery tag • SQL commands Retrieving data You can query databases to retrieve data at runtime. The retrieved data, called the record set, is stored on that page as a query object. A query object is a special entity that contains the record set values, plus RecordCount, CurrentRow, ColumnList, SQL, Cached, and SQLParameter query variables. You specify the query object’s name in the name attribute of the cfquery tag.

PAGE 467

In this example, the query code tells ColdFusion to do the following: • Connect to the cfdocexamples data source (the cfdocexamples.mdb database). • Execute SQL code that you specify. • Store the retrieved data in the query object EmpList. When creating queries to retrieve data, keep the following guidelines in mind: • You must use opening and ending tags, because the cfquery tag is a block tag. • Enter the query name and datasource attributes within the opening cfquery tag.

PAGE 468

To query the table: 1.

PAGE 469

Reviewing the code The query you just created retrieves data from the cfdocexamples database. The following table describes the highlighted code and its function: Code Description Queries the database specified in the cfdocexamples data source. SELECT FirstName, LastName, Salary, Contract FROM Employee Gets information from the FirstName, LastName, Salary, and Contract fields in the Employee table. Ends the cfquery block.

PAGE 470

2. Save the file and view it in your web browser: A list of employees appears in the browser, with each line displaying one row of data. Note: You might need to refresh your browser to see your changes. You created a ColdFusion application page that retrieves and displays data from a database. At present, the output is raw and needs formatting. For more information, see “Introduction to Retrieving and Formatting Data” on page 609.

PAGE 471

Getting information about query results Each time you query a database with the cfquery tag, you get the data (the record set) and the query variables; together these comprise the query object. The following table describes the query variables, which are sometimes referred to as query properties: Variable Description RecordCount The total number of records returned by the query. ColumnList A comma-delimited list of the query columns, in alphabetical order. SQL The SQL statement executed.

PAGE 472

Reviewing the code You now display the number of records retrieved in the query. The following table describes the code and its function: Code Description Displays what follows. The query returned Displays the text “The query returned”. #EmpList.RecordCount# Displays the number of records retrieved in the EmpList query. records. Displays the text “records.” Ends the cfoutput block.

PAGE 473

The result is that ColdFusion tries to execute the following query: SELECT * FROM Employee WHERE Emp_ID = 7 DELETE FROM Employee In addition to an expected integer for the Emp_ID column, this query also passes malicious string code in the form of a SQL statement. If this query successfully executes, it deletes all rows from the Employee table—something you definitely do not want to enable by this method.

PAGE 474

Using cfSqlType The following table lists the available SQL types against which you can evaluate the value attribute of the cfqueryparam tag: BIGINT BIT CHAR DATE DECIMAL DOUBLE FLOAT IDSTAMP INTEGER LONGVARCHAR MONEY MONEY4 NUMERIC REAL REFCURSOR SMALLINT TIME TIMESTAMP TINYINT VARCHAR Note: Specifying the cfsqltype attribute causes the DBMS to use bind variables, which can greatly enhance performance.

PAGE 475

CHAPTER 21 Updating Your Database This chapter describes how to use ColdFusion to insert, update, and delete information in a database. Contents About updating your database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 475 Inserting data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 475 Updating data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

PAGE 476

Creating an HTML insert form The following procedure creates a form using standard HTML tags. The form looks like the following in your web browser: To create an insert form: 1. Create a ColdFusion page with the following content: Insert Data Form
Insert Data Form

PAGE 477

PAGE 479

Code Description Creates a new row in the Employee table of the cfdocexamples database. Inserts data from the form into the database fields with the same names as the form fields. You have added #Form.FirstName# #Form.Lastname# to the employee database. Informs the user that values were inserted into the database.

PAGE 480

2. Save the page. 3. View insert_form.cfm in your web browser and enter values. 4. Click Submit. ColdFusion inserts your values into the Employee table and displays a confirmation message. Reviewing the code The following table describes the highlighted code and its function: Code Description INSERT INTO Employee VALUES (#Form.Emp_ID#, '#Form.FirstName#', '#Form.LastName#', #Form.Dept_ID#, '#Form.StartDate#', #Form.Salary#, '#Form.

PAGE 481

Creating an update form The following are the key differences between an update form and an insert form: • An update form contains a reference to the primary key of the record that is being updated. A primary key is a field(s) in a database table that uniquely identifies each record. For example, in a table of employee names and addresses, only the Emp_ID is unique to each record. • An update form is usually populated with existing record data.

PAGE 482

Start Date:

Salary:

Contractor: Yes

Contractor: Yes Yes

2. Save the file as update_form.cfm. 3. View update_form.cfm in your web browser by specifying the page URL and an Employee ID; for example, enter the following: http://localhost/myapps/update_form.

PAGE 483

Code Description First Name:
Last Name:
Department Number:
Start Date:
Salary:
Populates the fields of the update form. This example does not use ColdFusion formatting functions.

PAGE 484

Employee Updated
You have updated the information for #Form.FirstName# #Form.LastName# in the employee database. 2. Save the page as update_action.cfm. 3. View update_form.cfm in your web browser by specifying the page URL and an Employee ID; for example, enter the following: http://localhost/myapps/update_form.

PAGE 485

Reviewing the code The following table describes the code and its function: Code Description Sets the value of Form.Contract to No if it is not defined, or to Yes if it is defined. If the Contractor check box is unchecked, no value is passed to the action page; however, the database field must have some value.

PAGE 486

WHERE Emp_ID = #Form.Emp_ID#
Employee Updated
You have updated the information for #Form.FirstName# #Form.LastName# in the employee database. 2. Save the page. 3. View update_form.cfm in your web browser by specifying the page URL and an Employee ID; for example, enter the following: http://localhost/myapps/update_form.cfm?Emp_ID=3 4. Enter new values in any of the fields, and click Update Information.

PAGE 487

Deleting data You use a cfquery tag with a SQL DELETE statement to delete data from a database. ColdFusion has no cfdelete tag. Deleting a single record To delete a single record, use the table’s primary key in the WHERE condition of a SQL DELETE statement. In the following procedure, Emp_ID is the primary key, so the SQL Delete statement is as follows: DELETE FROM Employee WHERE Emp_ID = #Form.Emp_ID# You often want to see the data before you delete it.

PAGE 488

Reviewing the code The following table describes the code and its function: Code Description DELETE FROM Employee WHERE Emp_ID = #Form.Emp_ID# Deletes the record in the database whose Emp_ID column matches the Emp_ID (hidden) field on the form. Since the Emp_ID is the table’s primary key, only one record is deleted. You have deleted #Form.FirstName# #Form.LastName# from the employee database.

PAGE 489

CHAPTER 22 Using Query of Queries A query that retrieves data from a record set is called a Query of Queries. After you generate a record set, you can interact with its results as if they were database tables by using Query of Queries. This chapter describes the benefits and procedures for this feature. Contents About record sets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 489 About Query of Queries. . . . . . . . . . . . . . . . . . .

PAGE 490

• cfmail • cfpop • cfprocresult • cfquery (against a database or against another Query of Queries) • cfsearch • cfstoredproc • cfwddx • The QueryNew function Creating a record set with a function In addition to creating a record set by using a cfquery or other CFML tags, you can create it with the QueryNew() function. To create a record set with the QueryNew() function: 1.

PAGE 491

#qInstruments.name[2]# has played #qInstruments.instrument[2]# for #qInstruments.years_playing[2]# years.
2. Save the page as queryNew.cfm in the myapps directory under the web_root directory. 3. Display queryNew.cfm in your browser About Query of Queries After you have created a record set with a tag or function, you can retrieve data from the record set in one or more dependent queries. A query that retrieves data from a record set is called a Query of Queries.

PAGE 492

Performing a Query of Queries There are four steps to perform a Query of Queries. To perform a Query of Queries: 1. Generate a record set through a master query. You can write a master query using a tag or function that creates a record set. For more information, see “Creating a record set” on page 489. 2. Write a detail query—a cfquery tag that specifies dbtype="query". 3. In the detail query, write a SQL statement that retrieves the relevant records.

PAGE 493

Columns in the detail query:
#detail.columnlist#
2. Save the page as query_of_query.cfm in the myapps directory under the web_root. 3. Display query_of_query.cfm in your browser Reviewing the code The master query retrieves the entire Employee table from the cfdocexamples data source. The detail query selects only the three columns to display for employees with the specified last name.

PAGE 494

To display record set data incrementally: 1.

PAGE 495

#FirstName# #LastName# #LSCurrencyFormat(Salary)#

PAGE 496
To use Query of Queries with a Verity record set: 1.

PAGE 497

action="list" directory="#dir#" filter="*.gif"> SELECT * FROM GetGIF UNION SELECT * FROM GetJPG ORDER BY Name
The #dir# directory contains #GetBoth.

PAGE 498

Using joins A join operation uses a single SELECT statement to return a result set from multiple, related tables, typically those with a primary key - foreign key relationship. There are two SQL clauses that perform joins: • • WHERE clause ColdFusion supports joins through a WHERE clause. INNER JOIN and OUTER JOIN ColdFusion does not support joins through INNER JOIN or OUTER JOIN clauses. Note: Query of Queries supports joins between two tables only.

PAGE 499

To combine Table1 and Table2, use a UNION statement, as follows: SELECT * FROM Table1 UNION SELECT * FROM Table2 The UNION statement produces the following result (UNION) table: Result table Type(int) Name(varchar) 1 Tennis 2 Baseball 3 Football 4 Volleyball 5 PingPong Using aliases for column names The column names of a UNION table are the column names in the result set of the first SELECT statement in the UNION operation; ColdFusion ignores the column names in the other SELECT statement.

PAGE 500

SELECT * FROM TableC ) /* Second statement. */ (SELECT * FROM TableA UNION ALL SELECT * FROM TableB ) UNION SELECT * FROM TableC In the first statement, there are no duplicates in the union between TableB and TableC. Then, in the union between that set and TableA, the ALL keyword includes the duplicates. In the second statement, duplicates are included in the union between TableA and TableB but are eliminated in the subsequent union with TableC.

PAGE 501

Null conditional This conditional tests whether an expression is null. Syntax null_cond ::= expression IS [NOT] NULL Example SELECT bloodVal FROM Standards WHERE bloodVal IS NOT null; Comparison conditional This conditional lets you compare an expression against another expression of the same data type (Numeric, String, Date, or Boolean). You can use it to selectively retrieve only the relevant rows of a record set.

PAGE 502

IN conditional This conditional lets you specify a comma-delimited list of conditions to match. It is similar in function to the OR conditional. In addition to being more legible when working with long lists, the IN conditional can contain another SELECT statement.

PAGE 503

The following examples are select statements that use bracketed ranges: SELECT SELECT SELECT SELECT SELECT lname lname lname lname lname FROM FROM FROM FROM FROM Suspects Suspects Suspects Suspects Suspects WHERE WHERE WHERE WHERE WHERE lname lname lname lname lname LIKE LIKE LIKE LIKE LIKE 'A[^c]%'; '[a-m]%'; '%[]'; 'A[%]%'; 'A[^c-f]%'; Case sensitivity Unlike the rest of ColdFusion, Query of Queries is case-sensitive.

PAGE 504

Managing data types for columns A Query of Queries requires that every column have metadata that defines the column’s data type. All queries that ColdFusion MX creates have metadata. However, a query created with QueryNew function that omits the second parameter does not contain metadata. You use this optional second parameter to define the data type of each column in the query.

PAGE 505

The syntax for the CAST function is as follows: CAST ( expression AS castType ) Where castType is one of the following: • • • • • • • • • • BINARY BIGINIT BIT DATE DECIMAL DOUBLE INTEGER TIME TIMESTAMP VARCHAR For example: PAGE 506
Using aggregate functions Aggregate functions operate on a set of data and return a single value. Use these functions for retrieving summary information from a table, as opposed to retrieving an entire table and then operating on the record set of the entire table.

PAGE 507

Using group by and having expressions ColdFusion supports the use of any arbitrary arithmetic expression, as long as it is referenced by an alias.

PAGE 508

Using aliases ColdFusion supports the use of database column aliases. An alias is an alternate name for a database field or value. ColdFusion lets you reuse an alias in the same SQL statement. One way to create an alias is to concatenate (append) two or more columns to generate a value. For example, you can concatenate a first name and a last name to create the value fullname. Because the new value does not exist in a database, you refer to it by its alias.

PAGE 509

Handling null values ColdFusion uses Boolean logic to handle conditional expressions. Proper handling of NULL values requires the use of ternary logic. The IS [NOT] NULL clause works correctly in ColdFusion. However the following expressions do not work properly when the column breed is NULL: WHERE (breed > 'A') WHERE NOT (breed > 'A') The correct behavior should not include NULL breed columns in the result set of either expression.

PAGE 510

CATALOG CHAR CHARACTER CHARACTER_ LENGTH CHAR_LENGTH CHECK CLOSE COALESCE COLLATE COLLATION COLUMN COMMIT CONNECT CONNECTION CONSTRAINT CONSTRAINTS CONTINUE CONVERT CORRESPONDING COUNT CREATE CROSS CURRENT CURRENT_DATE CURRENT_TIME CURRENT_ TIMESTAMP CURRENT_ USER CURSOR DATE DAY DEALLOCATE DEC DECIMAL DECLARE DEFAULT DEFERRABLE DEFERRED DELETE DESC DESCRIBE DESCRIPTOR DIAGNOSTICS DISCONNECT DISTINCT DOMAIN DOUBLE DROP ELSE END END-EXEC ESCAPE EXCEPT EXC

PAGE 511

SUM SYSTEM USER TABLE TEMPORARY THEN TIME TIMESTAMP TIMEZONE HOUR TIMEZONE_MINUTE TO TRAILING TRANSACTION TRANSLATE TRANSLATION TRIM TRUE UNION UNIQUE UNKNOWN UPDATE UPPER USAGE USER USING VALUE VALUES VARCHAR VARYING VIEW WHEN WHENEVER WHERE WITH WORK WRITE YEAR ZONE Using Queries of Queries with dates If you create a query object with the QueryNew function and populate a column with date constants, ColdFusion MX stores the dates as a string inside the query object until

PAGE 512

• Query of Queries is less efficient for joins in which the predicate contains multiple expressions; for example: SELECT T1.a, b, c, d FROM T1, T2 WHERE T1.a = T2.a AND T1.b + T1.c = T2.b + T2.

PAGE 513

Managing complex objects You cannot use Query Of Queries on a record set that contains complex objects, such as arrays and structures. Note: You can store a record set in a complex objects.

PAGE 514

Chapter 22: Using Query of Queries

PAGE 515

CHAPTER 23 Managing LDAP Directories CFML applications use the cfldap tag to access and manage LDAP (Lightweight Directory Access Protocol) directories. This chapter provides information on how to use this tag to view, query, and update LDAP directories. This chapter teaches you how to query and update an LDAP database. It does not assume that you are familiar with LDAP, and provides an introduction to LDAP directories and the LDAP protocol.

PAGE 516

About LDAP The LDAP protocol enables organizations to arrange and access directory information in a hierarchy. In this context, directory refers to a collection of information, such as a telephone directory, not a collection of files in a folder on a disk drive. LDAP originated in the mid-1990s as a response to the need to access ISO X.500 directories from personal computers that had limited processing power.

PAGE 517

The following figure show such an asymmetric directory: airius.com groups people Bruce Laura Ben Amy HR Managers Directory Managers QA Managers Accounting Managers In this directory structure, the second level of the tree divides the directory into two organizational units: people and groups. The third level contains entries with information that is specific to the organizational unit. Each person’s entry includes a name, e-mail address, and telephone number.

PAGE 518

Entry The basic information object of LDAP is the entry. An entry is composed of one or more attributes. Entries are subject to content rules defined by the directory schema (see “Schema” on page 519). Each node, not just the terminal nodes, of an LDAP directory is an entry. In the preceding figures, each item is an entry. For example, in the first diagram, both USA and Ferrari are entries.

PAGE 519

An entry’s DN consists of an entry’s RDN followed by the DN of its parent. In other words, it consists of the RDNs for the entry and each of the entry’s parent entries, up to the root of the directory tree. The RDNs are separated by commas and optional spaces. For example, in the first figure, the DN for the Ferrari entry is “o=Ferrari, c=Italy”. As with file system pathnames and URLs, entering the correct LDAP name format is essential to successful search operations.

PAGE 520

When you add, modify, or delete a directory entry, you must treat the entry’s object class as a possibly multivalued attribute. For example, when you add a new entry, you specify the object class in the cfldap tag attributes attribute. To retrieve an entry’s object class names, specify “objectclass” in the list of query attributes. To retrieve entries that provide a specific type of information, you can use the object class name in the cfldap tag filter attribute.

PAGE 521

The following table lists the attributes that are required and optional for each action. For more information on each attribute, see the cfldap tag in CFML Reference.

PAGE 522

Operator Example Matches >= (st>=ma) The name “ma” and names appearing after “ma” in an alphabetical state attribute list. <= (st<=ma) The name “ma” and names appearing before “ma” in an alphabetical state attribute list. * (o=macro*) Organization names that start with “macro”. (o=*media) Organization names that end with “media”. (o=mac*ia) Organization names that start with “mac” and end with “ia”. You can use more than one * operator in a string; for example, m*ro*dia.

PAGE 523

Searching and sorting notes • To search for multiple values of a multivalued attribute type, use the & operator to combine expressions for each attribute value.

PAGE 524

This tag returns entries for all the people in the organization and entries for all the groups. The group entries have a different object class, and therefore different attributes from the person entries. If ColdFusion returned both types of entries in one query object, some rows would have only the group-specific attribute values and the other rows would have only person-specific attribute values. Instead, ColdFusion returns a structure in which each attribute is an entry.

PAGE 525

#results.RecordCount# matches found

Name Department E-Mail Phone

#cn# #listFirst(ou)# #mail# #telephonenumber#

2. Change the server attribute from ldap.airius.

PAGE 526

Code Description

PAGE 527

In this query, the ou attribute value consists of two values in a comma-delimited list. One is the department name. The other is People.

PAGE 528

Adding a directory entry When you add an entry to an LDAP directory, you specify the DN, all the required attributes, including the entry’s object class, and any optional attributes. The following example builds a form that adds an entry to an LDAP directory. To add an entry: 1. Create a file that looks like the following: PAGE 529
Update LDAP Form
Manage LDAP Entries
PAGE 530
tabindex="8">

*All fields are required for Add

User List for the Human Resources Department
PAGE 531
Reviewing the code The following table describes the code: Code Description Initializes the LDAP connection information variables. Uses variables for all connection information so that any changes have to be made in only one place.

PAGE 532

Code Description
Entry for User ID #Form.uid# has been added
Adds the new entry to the directory. PAGE 533
Code Description Queries the directory and gets the common name, surname, e-mail address, telephone number, and user ID from the matching entries. Searches the subtree from the entry with the DN of o=Airius.com, and selects all entries in which the organizational unit is Human Resources.

PAGE 534

Entry for User ID #Form.UID# has been deleted
3. At the end of the code for the Add button (the input tag with Value=Add at the bottom of the form), delete the end tag. 4.

PAGE 535

Reviewing the code The following table describes the code: Code Description

PAGE 536

To update an entry: 1. Open update_ldap.cfm, which you created in “Adding a directory entry” on page 528. 2. Between the cfelseif Form.action is "Retrieve" block and the tag, add the following code: PAGE 537
Reviewing the code The following table describes the code: Code Description
Entry for User ID #Form.

PAGE 538

You can add or delete attributes only if the directory schema defines them as optional for the entry’s object class. Changing a directory entry’s DN To change the DN of an entry, you must provide the following information in the cfldap tag: dn="original DN" action="modifyDN" attributes="dn=new DN" For example: PAGE 539
Using cfldap output You can create a searchable Verity collection from LDAP data. For an example of building a Verity collection using an LDAP directory, see Chapter 24, “Indexing query results obtained from an LDAP directory,” on page 578. The ability to generate queries from other queries is very useful when cfldap queries return complex data. For more information on querying queries, see Chapter 22, “Using Query of Queries,” on page 489.

PAGE 540

scope="base" filter="objectclass=*" start=#entryList.subschemaSubentry#>
Object Classes

PAGE 541

PAGE 542

Code Description
Object Classes

Name Superior class Must have May have

PAGE 543

Code Description
Attribute Types

Name Superior class Must have May have

Alias", "all")# delimiters = ","> thiselement = Trim(thisElement); nameloc = Find("NAME", thisElement); descloc = Find("DESC", thisElement); syntaxloc = Find("SYNTAX", thisElement); singleloc = Find("SINGLE", thisElement); endloc = Len(thisElement);

Name Description Multivalued?

#Mi

PAGE 544

The referral attribute value specifies the number of referrals allowed for the request. For example, if the referral attribute is 1, and server A sends a referral to server B, which then sends a referral to server C, ColdFusion returns an error. If the referral attribute is 2, and server C has the information, the LDAP request succeeds. The value to use depends on the topology of the distributed LDAP directory, the importance of response speed, and the value of response completeness.

PAGE 545

Using LDAP security To use security, first ensure that the LDAP server supports SSL v2 security. Specify the cfldap tag secure attribute as follows: secure = "cfssl_basic" For example: The port attribute specifies the server port used for secure LDAP communications, which is 636 by default.

PAGE 546

Chapter 23: Managing LDAP Directories

PAGE 547

CHAPTER 24 Building a Search Interface You can provide a full text search capability for documents and data sources on a ColdFusion site by enabling the Verity search engine. Verity full text search lets people visiting your site use simple one- and two-word searches to quickly find the information thFey need. You can use the more robust Verity Query Language and the Verity advanced search operators to transparently implement business-specific meaning behind searches.

PAGE 548

The ColdFusion implementation of Verity supports collections of the following basic data types: • Text files such as HTML pages and CFML pages • Binary documents (see “Supported file types” on page 549) • Record sets returned from a query and CF query object, including: cfquery, cfldap, and cfpop queries You can build collections from individual documents or from an entire directory tree. Collections can be stored anywhere, so you have a great deal of flexibility in accessing indexed data.

PAGE 549

Advantages of using Verity Verity can index the output from queries so that you or a user can search against the record sets. Searching query results has a clear advantage over using SQL to search a database directly in speed of execution because metadata from the record sets are stored in a Verity index that is optimized for searching.

PAGE 550

Document format Format Version(s) Word processing Adobe Maker Interchange Format (MIF) 5, 5.5, 6, 7 Applix Words (AW) 3.11, 4.2, 4.3, 4.4, 4, 41, 4.2 DisplayWrite (IP) 4 Folio Flat File (FFF) 3.1 Fujitsu Oasys (OA2) 7 JustSystems Ichitaro (JTD) 8, 9, 10, 12 Lotus AMI Pro (SAM) 2, 3 Lotus Word Pro (LWP) (Windows only) 96, 97, Millennium Edition R9 Microsoft Word for PC (DOC) 4, 5, 5.

PAGE 551

Document format Format Presentation formats Applix Presents (AG) Version(s) 4.0, 4.2, 4.3, 4.4 Corel Presentations (SHW) 7, 9, 10, 11, 2000 Lotus Freelance Graphics for Windows (PRE) 2, 96, 97, 98, Millennium Edition R9 Lotus Freelance Graphics 2 (PRE) 2 Microsoft PowerPoint for Windows (PPT) 95, 97, 2000, 2002 Microsoft PowerPoint for PC (PPT) 4 Microsoft PowerPoint for Macintosh (PPT) 98 Microsoft Project (MPP) 98, 2000, 2002 Display formats Adobe Portable Document Format (PDF) 1.

PAGE 552

For English language support, Verity provides two options: English (Basic) and English (Advanced). The default language for Verity collections is English (Basic). Indexing a collection using English (Basic) is faster than using English (Advanced), however, English (Advanced) provides better search results. You must specify a language when you create the collection. The language you specify should match the language the documents were authored in.

PAGE 553

Language Language attribute Norwegian norwegian Norwegian (Bokmal) bokmal Norwegian (Nynorsk) nynorsk Polish polish Portuguese portuguese Russian russian Spanish spanish Swedish swedish Turkish turkish You can register collections in the ColdFusion MX Administrator or by creating a collection with the cfcollection tag.

PAGE 554

3. Enter a path for the directory location of the new collection; for example, C:\CFusionMX7\verity\collections\. By default in the server configuration, ColdFusion stores collections in cf_root\verity\collections\ in Windows and in cf_root/verity/collections on UNIX. In the multiserver configuration, the default location for collections is cf_webapp_root/verity/collections.

PAGE 555

Use the Administrator Use the cfindex tag To create the collection without writing any To dynamically update a collection from a ColdFusion CFML code application page To create a collection once When the collection requires updating by others You can use cfcollection action="optimize" if you notice that searches on a collection take longer than they did previously. Updating an index Documents are modified frequently in many user environments.

PAGE 556

You can create a collection by directly assigning a value to the collection attribute of the cfcollection tag, as shown in the following code: If you want your users to be able to dynamically supply the name and location for a new collection, use the following procedures to create form and action pages. To create a simple collection form page: 1.

PAGE 557

To create a collection action page: 1. Create a ColdFusion page with the following content: cfcollection
Collection creation

The collection #Form.CollectionName# is created.
PAGE 558
You successfully created a collection, named CodeColl, that currently has no data. For information on indexing your collection using CFML, see “Indexing a collection using the cfindex tag” on page 558. Indexing a collection using the cfindex tag You can index a collection in CFML using the cfindex tag, which eliminates the need to use the ColdFusion MX Administrator. The cfindex tag populates the collection with metadata that is then used to retrieve search results.

PAGE 559

Attribute Description URLpath (Optional) The URL path for files if type="file" and type="path". When the collection is searched with the cfsearch tag, ColdFusion MX works as follows: • type="file" The URLpath attribute contains the URL to the file. • type="path" The path name is automatically prefixed to filenames and returned as the URLpath attribute. recurse (Optional) Yes or No.

PAGE 560

To use cfindex to index a collection: 1. Create a ColdFusion page with the following content: Creating Index
Indexing Complete
The collection #Form.IndexColl# has been indexed. 2.

PAGE 561

4. Enter (or Browse to) the directory path that contains the files to be indexed; for example, C:\Inetpub\wwwroot\vw_files. 5. (Optional) To extend the indexing operation to all directories below the selected path, select the Recursively index subdirectories check box. 6. (Optional) Enter a Return URL to prepend to all indexed files. This step lets you create a link to any of the files in the index; for example, http://127.0.0.1/vw_files/. 7. (Optional) Select a language other than English.

PAGE 562

Attribute Description criteria The search target (can be dynamic). maxrows The maximum number of records returned by the search. Always specify this attribute to ensure optimal performance (start with 300 or less, if possible). Each cfsearch returns variables that provide the following information about the search: Attribute Description RecordCount The total number of records returned by the search. CurrentRow The current row of the record set.

PAGE 563

To create a search form: 1. Create a ColdFusion page with the following content: Searching a collection
Searching a collection

Enter search term(s) in the box below. You can use AND, OR, NOT, and parentheses. Surround an exact phrase with quotation marks.

2.

PAGE 564

2. Save the file as collection_search_action.cfm. 3. View collection_search_form.cfm in the web browser. 4. Enter a target word(s) and click Search. Note: As part of the indexing process, Verity automatically produces a summary of every document file or every query record set that gets indexed. The default summary result set column selects the best sentences, based on internal rules, up to a maximum of 500 characters. Every cfsearch operation returns summary information by default.

PAGE 565

To create a search results page using term highlighting: 1. Create a ColdFusion page with the following content: Search Results ContextHighlightBegin="" ContextHighlightEnd="" ContextPassages="1" ContextBytes="500" maxrows = "100">
Search Results
Your search returned #codecoll_results.RecordCount# file(s).

PAGE 566

Note: Using alternative spelling suggestions incurs a small performance penalty. This occurs because the cfsearch tag must also look up alternative spellings in addition to the specified search terms. The following example specifies that if the number of search results returned is less than 5, an alternative search term—which is displayed using the cfif tag—is displayed with a link that the user can click to activate the alternate search.

PAGE 567

Narrowing searches using categories Verity lets you organize your searchable documents into categories. Categories are groups of documents (or database tables) that you define, and then let users search within them. For example, if you wanted to create a search tool for a software company, you might create categories such as whitepapers, documentation, release notes, and marketing collateral. Users can then specify one or more categories in which to search for information.

PAGE 568

Indexing collections that contain categories When you index a collection with support for categories enabled, you must do the following: • Specify a category name using the category attribute. The name (or names) that you provide identifies the category so that users can specify searches on the documents that the collection contains. For example, you might create five categories named taste, touch, sight, sound, and smell.

PAGE 569

Searching collections that contain categories When searching data in a collection created with categories, you specify category and categoryTree. The values supplied to these attributes specify what category should be searched for the specified search string (the criteria attribute). The category attribute can contain a comma separated list of categories to search. Both attributes can be specified at the same time.

PAGE 570

Number of records in query: #sr.recordcount#
Title: #title#
URL: #url#
Score: #score#

#context#

#summary#

For more information on using the cfindex tag to create Verity collections with support for categories, see cfsearch in Chapter 2, “ColdFusion Tags,” in CFML Reference.

PAGE 571

To retrieve information about the categories contained in a collection, you use the cfcollection tag, and create an application page that retrieves category information from the collection and displays the number of documents contained by each category.

PAGE 572

For more information on using the cfcollection tag to create Verity collections with support for categories, see cfcollection in Chapter 2, “ColdFusion Tags,” in CFML Reference. Working with data returned from a query Using Verity, you can search data returned by a query—such as a database record set—as if it were a collection of documents stored on your web server.

PAGE 573

Indexing data returned by a query Indexing the results of a query is similar to indexing physical files located on your website, with the added step that you must write a query that retrieves the data you want to search. The following are the steps to perform a Verity search on record sets returned from a query: 1. Create a collection. 2. Write a query that retrieves the data you want to search, and generate a record set. 3. Index the record set using the cfindex tag.

PAGE 574

Using the cfindex tag to index tabular data is similar to indexing documents, with the exception that you refer to column names from the generated record set in the body attribute. In the following example, the type attribute is set to custom, specifying that the cfindex tag index the contents of the record set columns Emp_ID, FirstName, LastName, and Salary, which are identified using the body attribute. The Emp_ID column is listed as the key attribute, making it the primary key for the record set.

PAGE 575

To search and display the query results: 1. Create a ColdFusion page with the following content: Searching a collection
Searching a collection

Collection name:

Enter search term(s) in the box below. You can use AND, OR, NOT, and parentheses. Surround an exact phrase with quotation marks.

PAGE 576

Custom 1: #Custom1#

Column list: #ColumnList#

4. Save the file as collection_db_results.cfm in the myapps directory under the web_root. 5. View collection_db_search_form.cfm in the web browser and enter the name of the collection and search terms. Indexing a file returned using a query You can index an individual file using a query by retrieving a table row whose contents are a filename.

PAGE 577

Title: #Title# Score: #Score# Key: #Key# Summary: #Summary# Custom 1:#Custom1# Column list: #ColumnList#
Indexing a path returned using a query You can index a directory path to a document (or collection of documents) using a query by retrieving a row whose contents are a full directory path name.

PAGE 578

To search and display the directory path: 1. Create a ColdFusion page that contains the following content: Your search returned #getEmps.RecordCount# file(s).

PAGE 579

DN: #dn#
O: #o#
TELEPHONENUMBER: #telephonenumber#
MAIL: #mail#
=============================

First Name:
Last Name:
Salary:
City