MACROMEDIA COLFUSION MX 7-MIGRATING APPLICATIONS TO COLDFUSION MX... User manual

COLDFUSION®MX 7
Migrating Applications to ColdFusion MX 7

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 trademarks or trademarks of Macromedia, Inc. and may be registered in the United States or
in other jurisdictions including internationally. Other product names, logos, designs, titles, words, or phrases mentioned within
this publication may be trademarks, service marks, or trade names of Macromedia, Inc. or other entities and may be registered in
certain jurisdictions including internationally.
This product includes code licensed from RSA Data Security.
Third-Party Information
This guide contains links to third-party websites that are not under the control of Macromedia, and Macromedia is not
responsible for the content on any linked site. If you access a third-party website mentioned in this guide, then you do so at your
own risk. Macromedia provides these links only as a convenience, and the inclusion of the link does not imply that Macromedia
endorses or accepts any responsibility for the content on those third-party sites.
Copyright © 2005 Macromedia, Inc. All rights reserved. U.S. Patents Pending. This manual may not be copied,
photocopied, reproduced, translated, or converted to any electronic or machine-readable form in whole or in part without
written approval from Macromedia, Inc. Notwithstanding the foregoing, the owner or authorized user of a valid copy of
the software with which this manual was provided may print out one copy of this manual from an electronic version of this
manual for the sole purpose of such owner or authorized user learning to use such software, provided that no part of this
manual may be printed out, reproduced, distributed, resold, or transmitted for any other purposes, including, without
limitation, commercial purposes, such as selling copies of this documentation or providing paid-for support services.
Acknowledgments
Project Management: Randy Nielsen
Writing: Randy Nielsen
Editing: Linda Adler
Production Management: Patrice O’Neill
Media Design and Production: John Francis, Adam Barnett
Special thanks to Sawako Gensure, Seungmin Lee, Takashi Koto, Nozomi Kugita, Masayo Noda, Hiroshi Okugawa, Bowne
Global Solutions
First Edition: January 2005
Macromedia, Inc.
600 Townsend St.
San Francisco, CA 94103

3
CONTENTS
CHAPTER 1: Migrating Applications from ColdFusion 5. . . . . . . . . . . . . . . . . . . . . 5
Migrating to ColdFusion MX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
Planning your migration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
Web server considerations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
Migration strategy using external web server. . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
Migration strategy using built-in web server . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
Using the Configuration and Settings Wizard . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
Using the ColdFusion Code Compatibility Analyzer. . . . . . . . . . . . . . . . . . . . . . . 10
Database operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
Connecting to Microsoft Access databases . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
Connecting to a data source with ODBC Socket . . . . . . . . . . . . . . . . . . . . . . . 11
Session management. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
QueryColumn object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
Data type of query results . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
Localization and character handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
Extended character code and encoding support . . . . . . . . . . . . . . . . . . . . . . . . 12
Support for new currency formats. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
Changes to formatting functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
Other locale-specific changes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
Other changes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
Advanced security. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
SNMP support. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
Operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
CFML data types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
Template handlers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
Case in forms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
Objects for date/time . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
Date pivot point for two-digit years . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
Request variable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
Definition of pi . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
Null values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
The thisTag scope. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
Caching . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
Log files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
Using cfform in a multihomed environment. . . . . . . . . . . . . . . . . . . . . . . . . . . 20
Moving to IBM WebSphere . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
The application.cfc file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

4 Contents
Tag and function examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
Using ListSort in ColdFusion MX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
Using the cfindex tag in ColdFusion MX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
CHAPTER 2: Changes in ColdFusion MX 7 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
Configurations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
Using cfform in a multihomed environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
The application.cfc file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
Running multiple ColdFusion versions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
Other changes in ColdFusion MX 7 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
CHAPTER 3: Tag and Function Changes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
Tag changes since ColdFusion 5 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
New tags, attributes, values, and changes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
Deprecated tags, attributes, and values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
Obsolete tags, attributes, and values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
Function changes since ColdFusion 5 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
New functions, parameters, values, and changes . . . . . . . . . . . . . . . . . . . . . . . . 51
Deprecated functions, parameters, and values . . . . . . . . . . . . . . . . . . . . . . . . . . 58
Obsolete functions, parameters, and values. . . . . . . . . . . . . . . . . . . . . . . . . . . . 59

5
CHAPTER 1
Migrating Applications from ColdFusion 5
This chapter describes migration and known compatibility issues between ColdFusion Server 5
and later versions, including ColdFusion MX 6.1 and ColdFusion MX 7 (referred to in this
chapter as ColdFusion MX).
Contents
Migrating to ColdFusion MX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
Planning your migration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
Using the Configuration and Settings Wizard . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
Using the ColdFusion Code Compatibility Analyzer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
Database operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
Localization and character handling. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
Other changes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
Tag and function examples. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
Migrating to ColdFusion MX
When you migrate your existing ColdFusion Server 5 applications to ColdFusion MX, you might
encounter a few incompatibilities between ColdFusion 5 and ColdFusion MX. Macromedia
strongly encourages you to develop a migration plan for porting existing ColdFusion 5
applications to ColdFusion MX. For more information, see “Planning your migration” on page 6.
Whether you encounter incompatibilities depends on the features of ColdFusion and the CFML
elements that your existing applications use. This guide lists known incompatibilities and suggests
possible fixes. Also, you can use the Code Compatibility Analyzer to facilitate locating and fixing
incompatible code; for more information, see “Using the ColdFusion Code Compatibility
Analyzer” on page 10.
Note: This guide provides migration and incompatibility information for customers moving from
ColdFusion 5 to ColdFusion MX. Most of this information also applies to ColdFusion 4.5, so
references to ColdFusion 5 also applies to ColdFusion 4.5. For information about earlier versions of
ColdFusion, see the Support section of the Macromedia website (www.macromedia.com/support).

6 Chapter 1: Migrating Applications from ColdFusion 5
Before planning your migration, make sure that you understand the ColdFusion MX
configuration options:
Server configuration Lets you install one instance of ColdFusion MX 7 with an embedded
J2EE server. This configuration most closely resembles the ColdFusion MX base release and other
releases prior to ColdFusion MX, such as ColdFusion 5 and ColdFusion 4.5. This was formerly
known as the stand-alone configuration.
Multiserver configuration (Enterprise Edition only) Installs JRun and automatically deploys
ColdFusion MX 7 in a separate JRun server instance. This configuration supports server instance
creation and ColdFusion deployment in the ColdFusion MX Administrator and lets you manage
ColdFusion MX 7 deployments on multiple JRun servers.
J2EE configuration (Enterprise Edition only) Lets you deploy ColdFusion MX 7 as a Java
application running on a Java 2 Enterprise Edition (J2EE) application server, either using the
bundled license of JRun or using a third-party J2EE server, such as IBM WebSphere or BEA
WebLogic. When you use the J2EE configuration, you can deploy ColdFusion MX 7 multiple
times on a single computer.
Planning your migration
To facilitate the migration process, Macromedia recommends that you develop a migration
strategy. Because every application is different, you must tailor your own migration strategy to
meet your environment’s needs. This section contains two possible migration strategies, following
a discussion of web server differences in ColdFusion MX.
Web server considerations
ColdFusion 5 has a simple relationship with the web server:
•To install ColdFusion, you must have a web server (such as IIS, iPlanet, or Apache) running on
the same computer as ColdFusion.
•The ColdFusion Administrator is located beneath the web root in a directory named CFIDE;
CFM pages are located either within the web root or in a virtual directory that is accessible to
the web server.
•The ColdFusion stub, a web-server specific module that is always configured as part of a
ColdFusion 5 installation, uses extension mappings to route CFM pages to the ColdFusion
application server.
ColdFusion MX provides a web server connector (similar to the ColdFusion stub), which also
uses extension mappings to route CFM pages to ColdFusion MX. However, because both the
ColdFusion stub and the ColdFusion MX web server connector process CFM files, you cannot
configure a web server to handle both ColdFusion 5 and ColdFusion MX.
If you must use a ColdFusion 5 application on the same computer that contains ColdFusion MX,
you can access ColdFusion MX pages through the built-in web server. The built-in web server is
an all-Java, HTTP 1.0 server that is not intended for use in a production environment. However,
the built-in web server is particularly useful when ColdFusion 5 and ColdFusion MX
applications must co-exist on the same computer until you complete the migration process.

Planning your migration 7
When running in the server configuration, ColdFusion MX uses the built-in web server,
as follows:
•The ColdFusion MX Administrator is located under the cf_root/wwwroot directory in a
directory named CFIDE; CFM pages are located within the cf_root/wwwroot directory.
•To access pages through the built-in web server, specify port 8500 in the URL, as the following
example shows:
http://localhost:8500/CFIDE/administrator/index.cfm
Tip: If you upgrade to ColdFusion MX 7 and are already using the built-in web server, the installer
selects a different port number (typically 8501).
When running ColdFusion MX 7 in the multiserver configuration, ColdFusion MX uses the
built-in web server, as follows:
•The ColdFusion MX Administrator is located under the jrun_root/servers/coldfusion/cfusion-
ear/cfusion-war directory in a directory named CFIDE; CFM pages are located within the
jrun_root/servers/coldfusion/cfusion-ear/cfusion-war directory.
•To access pages through the built-in web server, specify port 8300 in the URL, as the following
example shows:
http://localhost:8300/CFIDE/administrator/index.cfm
When running in the J2EE configuration, you use the web server capabilities of the underlying
J2EE application server.
If you are using the built-in web server, you must switch to the web server connector before
moving to production. You do this by running the Web Server Configuration Tool, as explained
in Installing and Using ColdFusion MX and Configuring and Administering ColdFusion MX.
Migration strategy using external web server
If your site has a highly controlled environment with separate development, testing, staging, and
production servers, you can migrate to ColdFusion MX on a testing server before moving to
production. Adapt the following suggested steps to fit your needs:
1. Study the ColdFusion MX Migration section of the Macromedia website
(www.macromedia.com/go/cfmxmigration) and this migration guide to anticipate the
compatibility issues that might affect your system.
2. Copy your existing ColdFusion 5 application to a test computer that contains a web server.
3. Redefine data sources to access a test database. You should not run tests against a production
database.
4. Ensure that your ColdFusion 5 application is functioning properly on the test computer before
upgrading it to ColdFusion MX.

8 Chapter 1: Migrating Applications from ColdFusion 5
5. Install ColdFusion MX on the test computer. The Install Wizard detects the previous version
of ColdFusion and prompts you for the following:
■Location of previous ColdFusion directory.
■Location of CFIDE directory.
■Whether to switch your web server from the previous ColdFusion version to
ColdFusion MX. When using this migration strategy, it’s best to switch your web server to
ColdFusion MX.
6. Open the ColdFusion MX Administrator. When starting the ColdFusion MX Administrator
for the first time, the Configuration and Settings Migration Wizard runs.
7. Answer the Configuration and Settings Migration Wizard questions, selecting all migration
options.
8. Test the code in your application using the ColdFusion Code Compatibility Analyzer.
Ensure that you specify the location of any custom tags or other code outside of the
ColdFusion MX web root directory. For more information, see “Using the ColdFusion Code
Compatibility Analyzer” on page 10.
9. Based on the results of the Code Compatibility Analyzer report and the incompatibilities listed
in this guide, make a migration plan. For example, you might plan to immediately fix code that
causes errors, such as dbtype="dynamic" in query tags, and to schedule and prioritize other
fixes, such as replacing deprecated tags and using new functionality.
10. Make the necessary changes to your ColdFusion application and run the application on your
test computer. Ensure that you test all application features under load, not just with a few users.
If possible, use a source control system to manage these changes.
Tip: Remove the web_root/cfdocs directory before moving to production.
Your application is now ready for production on ColdFusion MX.
Note: A number of testing applications are available for download from the web. For more
information, see the Support section of the Macromedia website (www.macromedia.com/support).
Migration strategy using built-in web server
If your environment does not multiple computers for development, testing, and staging. You can
install ColdFusion MX directly on a staging or production computer and use the built-in web
server to test your application in co-exist mode. Adapt the following suggested steps to fit your
needs:
1. Study the ColdFusion MX Migration section of the Macromedia website
(www.macromedia.com/go/cfmxmigration) and this migration guide to anticipate the
compatibility issues that might affect your system.
2. Install ColdFusion MX on your staging or production computer. Do not configure an external
web server; select the built-in web server instead.
3. Run the Configuration and Settings Migration Wizard to complete the installation. If
ColdFusion 5 is already installed on the computer, the wizard will migrate your settings to
ColdFusion MX.

Using the Configuration and Settings Wizard 9
4. Define data sources in the ColdFusion MX Administrator. If possible, do not run tests against
a production database.
5. Copy CFM files to the cf_root/wwwroot (server configuration) or jrun_root/servers/coldfusion/
cfusion-ear/cfusion-war (multiserver configuration) directory.
6. Test the code in your application using the ColdFusion Code Compatibility Analyzer. For more
information, see “Using the ColdFusion Code Compatibility Analyzer” on page 10.
7. Based on the results of the Code Compatibility Analyzer report and the incompatibilities listed
in this guide, make a migration plan. For example, you might plan to immediately fix code that
causes errors, such as dbtype="dynamic" in query tags, and to schedule and prioritize other
fixes, such as replacing deprecated tags and using new functionality.
8. Make the necessary changes to your ColdFusion application and run the application using the
built-in web server. Ensure that you test all application features under load, not just with a few
users.
9. When the application is ready for production, perform the following steps:
a Run the Web Server Configuration Tool for the web server used in production. For more
information, see Installing and Using ColdFusion MX or Configuring and Administering
ColdFusion MX.
b Rename the CFIDE directory under your production web root.
c Copy the CFIDE directory and the application’s CFM files to your production web root.
Do not copy the cfdocs directory to a production server.
Your application is now ready for production on ColdFusion MX.
Using the Configuration and Settings Wizard
If you have ColdFusion 5 installed on the same computer as ColdFusion MX, the Configuration
and Settings Migration Wizard prompts you to migrate settings to the ColdFusion MX
installation. For Windows, the wizard typically runs immediately after you finish the installation;
for UNIX, the wizard runs the first time that you open the ColdFusion MX Administrator.
If you choose not to migrate settings, you can rerun the wizard at a later time by performing the
following steps:
1. Close the ColdFusion MX Administrator, if it is not already closed.
2. Open cf_root/lib/adminconfig.xml in a text editor, change runmigrationwizard to true, and
save the file.
3. Restart the ColdFusion MX Administrator.
You are prompted again to migrate your settings.
Caution: If you migrate your ColdFusion 5 settings later, you might overwrite new ColdFusion MX
settings.

10 Chapter 1: Migrating Applications from ColdFusion 5
Using the ColdFusion Code Compatibility Analyzer
To isolate compatibility issues between ColdFusion MX and ColdFusion Server 5, use the Code
Compatibility Analyzer to check your ColdFusion pages. Based on diagnostic information, the
Code Compatibility Analyzer issues error and information messages to alert you to the following
compatibility issues:
•Obsolete CFML features in ColdFusion MX
•Deprecated CFML features in ColdFusion MX
•CFML features that might produce different behaviors in ColdFusion MX
•CFML syntax errors
To access the Code Compatibility Analyzer, click the link in the ColdFusion MX Administrator.
When using the Code Compatibility Analyzer, follow these guidelines:
•To avoid time-consuming operations and possibly degraded server performance for an
extended period of time, do not run the Code Compatibility Analyzer on multiple application
directories.
•Use the advanced options to custom the tags, functions, and operators that are analyzed.
Database operations
ColdFusion MX uses JDBC drivers to interact with databases; for example, to query, write, and
update a database. (JDBC is an Application Programming Interface (API) for Java programs to
access data.) To connect to Open Database Connectivity (ODBC) data sources on Windows, you
can use the Data Direct SQL Link Type III ODBC Socket database driver, which is included with
ColdFusion MX.
This section describes the known incompatibilities between the ODBC features of ColdFusion 5
and the JDBC features of ColdFusion MX, in addition to those that are documented in
Chapter 3, “Tag and Function Changes,” on page 33 (for example, cfquery, cfcatch, and
cfreport).
For more information about the Data Direct JDBC drivers included with ColdFusion MX, see
www.datadirect.com/index.ssp.
Connecting to Microsoft Access databases
The ColdFusion MX Administrator includes options that make it easy to define data sources for
Microsoft Access databases. When defining a data source in the ColdFusion MX Administrator,
select Microsoft Access as the driver type. The Administrator automatically configures the ODBC
Socket driver with Access-specific settings.
Note: When using Microsoft Access on a Unicode system, select the Microsoft Access with Unicode
driver. This is a JDBC Type 2 driver that works with Microsoft Access Unicode databases.