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.

Database operations 11
Connecting to a data source with ODBC Socket
In ColdFusion 5, an ODBC Data Source Name (DSN) entry that was created with the ODBC
Data Source Administrator would automatically appear in the list of data sources in the
ColdFusion Administrator. It does not appear automatically in ColdFusion MX; you must
manually add the ODBC DSN entry.
To manually add the ODBC DSN entry:
1. In the ColdFusion MX Administrator, select Data & Services > Data Sources.
2. In the Add New Data Source Name box, do the following:
a In the Data Source Name text box, enter the data source name.
You can use the same name as the ODBC DSN entry.
b In the Driver drop-down list box, select ODBC Socket.
c Click Add.
3. In the ODBC DSN drop-down list box, select the ODBC DSN name.
4. Click Submit.
For more information, see the “Data Source Management” chapter of Configuring and
Administering ColdFusion MX.
Session management
ColdFusion MX lets you use J2EE sessions for session management. For backward compatibility,
J2EE session management is disabled by default. However, you should enable this feature
whenever possible. For more information, see “Using Persistent Data and Locking” in ColdFusion
MX Developer’s Guide.
QueryColumn object
In ColdFusion MX, the QueryColumn object is even more like an array than in ColdFusion 5, as
the following examples show:
•The QueryColumn object is derived by referencing a query using associative array notation;
for example:
query1['firstName']
•You can set a query column to an array element; for example:
<cfset query1['col'] = array2['moo']>
Data type of query results
ColdFusion 5 stores data in the query object as a string, regardless of how the data is stored in the
database. When it outputs a piece of data, it just writes out the string. ColdFusion MX stores data
in the query object differently, depending on its database type (for example, it might store a
number as a Java Double). ColdFusion MX outputs the data by converting the stored type to a
string, which might differ from the string that ColdFusion 5 outputs. If you need your output to
be in a particular format, use the number and/or date format functions.

12 Chapter 1: Migrating Applications from ColdFusion 5
Localization and character handling
This section describes the changes between ColdFusion 5 and ColdFusion MX that affect locale
functions. It contains the following topics:
•Extended character code and encoding support
•Support for new currency formats
•Changes to formatting functions
•Other locale-specific changes
Note: Results from localization functions might differ, depending on your Java Runtime Environment
(JRE).
Extended character code and encoding support
ColdFusion MX uses Java Unicode as its internal character representation and supports character
code values 0–65535, whereas ColdFusion 5 supports 1-255. This affects string-processing
functions. For more information, see Len in “New functions, parameters, values, and changes”
on page 51.
ColdFusion MX uses the UTF-8 character set encoding as its default web page encoding.
ColdFusion 5 used the ISO-8859-1 character set encoding. This can affect the way that
characters in the range 128–255 are displayed in the browser. To restore the ColdFusion 5 default
encoding, place the following cfcontent tag in your page (or in the application’s Application.cfm
page):
<cfcontent type="text/html; charset=ISO-8859-1">
Note: UTF-8 (USC Transformation Format, where USC is the Universal Character Set) enables
computers to handle both ASCII and Unicode. Unicode (Unicode Worldwide Character Standard) is
a system of setting up binary codes for text or script characters, so that the characters from the
principal written languages of the world can be displayed and processed.
ColdFusion MX and ColdFusion MX 6.1 have added several attributes, parameters, and
functions for determining the character encoding used in tags and functions, as follows:
Additionally, an option has been added to the Mail page of ColdFusion MX Administrator that
specifies the default mail character encoding.
Tag or function Attribute or parameter
cfhttp charset
cfmail charset
cfprocessingdirective pageEncoding
GetEncoding all
SetEncoding all
URLDecode charset
URLEncodedFormat charset

Localization and character handling 13
For more information on support for character encodings see the “Developing Globalized
Applications” chapter in ColdFusion MX Developer’s Guide and the individual tag and function
descriptions in the CFML Reference.
Support for new currency formats
ColdFusion MX recognizes new currency formats for locales. For example, when a euro currency
is passed to the LSIsCurrency function, ColdFusion MX returns Yes if the locale is a Euro
member, and No if not. Support for currency formats is JVM dependent. For more information,
see the LSCurrencyFormat and LSIsCurrency discussions in CFML Reference.
Changes to formatting functions
ColdFusion MX uses Java standard locale formatting rules on all platforms. ColdFusion 5 uses
Windows or UNIX locale formatting rules, depending on the ColdFusion platform. For
information on Java standard locale formatting rules, see the Java documentation for the Locale
class (java.util.Locale) for your JVM at http://java.sun.com/j2se/.
Some functions in ColdFusion MX produce slightly different results than in ColdFusion 5. For
example, in ColdFusion MX, LSCurrencyFormat returns the correct international currency code
for countries other than the US, and correctly rounds the currency values for countries whose
currency does not include cents. The same code now produces the same results, regardless of the
platform.
Some of the differences might require adjusting your ColdFusion applications. For example,
LSCurrencyFormat in ColdFusion MX formats some negative currency values differently than in
ColdFusion 5, such as inserting a leading minus sign (–) instead of enclosing the value in
parentheses.

14 Chapter 1: Migrating Applications from ColdFusion 5
Changes to formatting functions
The following table outlines changes to formatting functions. For more information, see CFML
Reference for the appropriate function.
Function Description of change
LSEuroCurrencyFormat In ColdFusion 5, the LSEuroCurrencyFormat function used EUR or the
euro symbol (€) for every locale, even if the locale did not support the euro.
For example, LSEuroCurrencyFormat(123.45, "international") returned
"EUR123.45", even for an English (US) locale.
In ColdFusion MX, LSEuroCurrencyFormat returns the euro currency
format if the set locale is a Euro member country . Otherwise, it returns the
set locale’s currency format or symbol. For example,
LSEuroCurrencyFormat(-1234.56) returns -1 234,56 €for the French
(Standard) locale, but returns ($1,234.56) for the English (US) locale.
LSCurrencyFormat In ColdFusion 5 this function had numerous errors where it used the
wrong international currency designator. For example, in an English
(Australian) locale, LSCurrencyFormat(123456.78,"international")
returned USD123,456.78. This problem has been corrected, and this
example now returns AUD.
The format returned for negative currency values has also been corrected
to use JVM format for the locale. For example, in the Australian(English)
locale, LSCurrencyFormat(-123456.78, "local") now returns
-$123,456.78 instead of ($123,456.78).
In ColdFusion 5, the LSCurrencyFormat tag used the pre-euro currency
identifiers for all countries in the Euro zone.
ColdFusion MX uses the Java standard locales, and its behavior depends
upon the JVM version.
If you have a 1.4 level JVM, including the JVM that is included in the
ColdFusion MX 6.1 server configuration, LSCurrencyFormat returns the
euro currency format for all locales in the Euro Zone. If you have a 1. 3 level
JVM , LSCurrencyFormat returns the non-euro currency format for all
locales, even if the locale is a member of the Euro countries.

Localization and character handling 15
LSDateFormat In ColdFusion MX, LSDateFormat returns the appropriate date for the set
locale. For example, LSDateFormat(12/01/02) returns Jan-12-2002 if the
locale is set to English (UK), and Dec-01-2002 if the set locale is
English(US).
In ColdFusion 5, LSDateFormat throws an error or returns an incorrect
format.
When no mask is specified, ColdFusion MX returns the Java medium date
format for the locale. ColdFusion 5 returns one of two default masks,
depending on the locale:
•For a locale where the date ends with the year, the default mask is
dd-mmm-yy.
•For a locale where the date begins with the year, the default mask is
yyyy-mmm-dd.
The medium date format for English (US) has changed to the Java
standard; for example, “Sept 4, 1998 11:15:16 PM" and "11:15:16 PM Sept.
4, 1998" are valid. However, "23:15:16 4 Sept. 1998" is not valid; for
example, LSParseDateTime("23:15:16 4 Sept. 2003") causes an error.
For a list of valid date formats, see the Java documentation for the
java.text.DateFormat class at http://java.sun.com/j2se/1.3/docs/api/
index.html.
If you pass an invalid mask (for example, "dd-mm-yymm"), LSDateFormat
outputs the invalid characters in both ColdFusion 5 and ColdFusion MX.
However, ColdFusion 5 delimits each character of the output with an
apostrophe (') character.
LSTimeFormat ColdFusion MX supports the following masks for LSTimeFormat:
•h:m:s LSTimeFormat("6:39","h:m:s") returns 6:39:0
•hh:mm:ss LSTimeFormat("6:39","hh:mm:ss") returns 06:39:00
•hh:mm:ss t LSTimeFormat("6:28:26","hh:mm:ss t") returns
06:28:26 A
•hh:mm:ss tt LSTimeFormat("6:28:26","hh:mm:ss tt") returns
06:28:26 AM
If you pass an invalid mask, LSTimeFormat outputs the invalid characters in
both ColdFusion 5 and ColdFusion MX. However, ColdFusion 5 delimits
each character of the output with an apostrophe (') character.
LSIsCurrency When a euro currency is passed into the LSIsCurrency function,
ColdFusion MX returns Yes if the locale is a Euro member, and No if not,
independent of the JVM version. With 1.3 level JVMs only, this function
also returns Yes if the currency is in a Euro zone country’s pre-Euro
currency format.
LSIsDate In ColdFusion MX, you can pass in dates with the full date and full
datetime parameters. These formats include the name of the day (for
example, Wednesday).
Function Description of change

16 Chapter 1: Migrating Applications from ColdFusion 5
For more information, see CFML Reference for the relevant function.
Other locale-specific changes
Following are other locale-specific issues that could cause an incompatibility in your
ColdFusion 5 applications:
•For the Japanese version, sort functions such as ListSort and ArraySort return items in a
slightly different order in ColdFusion MX than they do in the Japanese version of
ColdFusion 5. This is because ColdFusion MX sorts characters by their Unicode char number,
and the Japanese version of ColdFusion 5 sorts characters by their shift_jis char number.
•The format for how decimal numbers appear in a browser depends on the system locale of the
computer that is hosting ColdFusion MX, not on the locale of ColdFusion MX. For example,
if you run the English version of ColdFusion MX on a computer whose system locale is set to
German or French, the decimal point displays as a comma, not a period. ColdFusion 5
displays a period for the decimal point, regardless of the system locale.
•The GetLocale function checks if the locale was explicitly set; for example, from Setlocale.
If not, ColdFusion MX gets the default locale for the operating system from the JVM. If the
operating system has no set locale, or if ColdFusion MX does not support the operating
system’s default locale, GetLocale returns en_US "English (US)". (ColdFusion MX sets the
locale in the JVM to en_US "English (US)"; this value persists until the server is restarted or
the value is reset with the SetLocale function. This setting does not affect anything but
ColdFusion MX.)
LSParseDateTime In earlier versions, you could not pass in a time-zone value such, as “EST”.
Now you can, but ColdFusion MX processes this information as follows:
•If the time zone specified in the date/time string parameter is different
from the time zone setting of the computer hosting ColdFusion MX,
ColdFusion MX changes the time value in the parameter to its
equivalent value in the computer’s time zone.
•If the time zone is not specified in the date/time string parameter,
ColdFusion MX does not adjust the time value.
When developing an application, Macromedia recommends that you
evaluate the entered time string for a time zone setting and, if necessary,
change your application to adjust the value. You can use a cfcatch block
to do this; for more information, see LSParseDateTime and “CFCATCH
variables” in CFML Reference.
If you use the IBM JRE version 1.3.0 with ColdFusion MX,
LSParseDateTime("Quarta-feira, 23 de Janeiro de 2002 12h34min56s
PST") fails when passing the month Janeiro.
Function Description of change

Other changes 17
Other changes
This section describes other changes between ColdFusion 5 and ColdFusion MX.
Advanced security
ColdFusion MX provides a new and easy way for you to build user authentication and roles-based
security into your applications. However, it is based on a completely different security model than
ColdFusion 5. Also, ColdFusion MX no longer includes a licensed version of Netegrity
Siteminder. Therefore, any existing Advanced Security code—including the cfauthenticate
and cfimpersonate tags, and the authenticatedContext, authenticatedUser,
isAuthenticated, isProtected, and isAuthorized functions—no longer works in
ColdFusion MX. These tags and functions are obsolete in ColdFusion MX.
For more information, see Configuring and Administering ColdFusion MX and the “Application
Security” chapter in ColdFusion MX Developer’s Guide.
SNMP support
ColdFusion MX no longer supports Simple Network Management Protocol (SNMP) for
monitoring ColdFusion applications from enterprise management systems.
Variables
ColdFusion MX includes the following changes to variables:
•You can no longer use a dot (.) in a variable name, because ColdFusion MX supports the dot
notation as a dot operator to create a struct. For example, last.name creates a struct called
last with a key called name, instead of creating a simple variable with a period in the name.
To work around this, use underscores in variable names instead.
•The following cfcatch variables have changed: Message, NativeErrorCode, and SQLState.
For more information, see cfcatch in “New tags, attributes, values, and changes” on page 34.
Operators
ColdFusion MX includes the following changes to operands:
•Exponent results differ; for example, ColdFusion 5 returns an error for 0 ^ 3, and
ColdFusion MX only returns 1.
•ColdFusion MX supports the dot notation as a dot operator. For example, if your
ColdFusion 5 application has a variable called last.name, ColdFusion MX reads this code
and creates a struct called last with a key called name.
In addition, ColdFusion MX does not create keys with dots in them like ColdFusion 5 does,
but instead creates cascading structs with non-dotted names. For example, ColdFusion 5
interprets a.b.c="foo" to be a["b.c"]="foo", whereas ColdFusion MX interprets it to be
a["b"]["c"]="foo".

18 Chapter 1: Migrating Applications from ColdFusion 5
CFML data types
ColdFusion MX preserves the case of a struct key, whereas ColdFusion 5 sets every struct key to
uppercase. However, you cannot use dot notation with different case to create more than one key.
For example, the following code produces one key, not two:
x.Foo = 1;
x.FOO = 2;
If you specify x['Foo'], ColdFusion MX preserves case. However, for best results, use consistent
case for struct key names.
Template handlers
The Runtime service in Windows has been reimplemented in ColdFusion MX so that you can
specify a template handler in the ColdFusion MX Administrator (Settings page). (A template
handler is a template that executes when ColdFusion MX cannot find the CFM file specified in a
cfinclude tag.) However, you must specify a template handler as a path that is relative to the
web root directory, such as \missing.cfm for the file web_root\missing.cfm. Do not use a full path.
Case in forms
Unlike ColdFusion 5, ColdFusion MX preserves the case of field names submitted by forms,
instead of forcing them to uppercase. Like ColdFusion 5, ColdFusion MX ignores case when
evaluating field names (for example, #form.myfield# is the same as #FORM.MYFIELD#).
However, you should change templates that use Find or ListFind to search through the
Form.Fieldnames variable, to use case-insensitive equivalents.
Objects for date/time
ColdFusion MX no longer strips milliseconds off date/time objects; to do this, use the date
formatting functions.
Date pivot point for two-digit years
When ColdFusion processes a date that has does not include the century, ColdFusion determines
the century. To do this, ColdFusion compares the date to when it processes the date. With a few
exceptions, ColdFusion MX uses 20 as the date pivot point for calculating the century in a two-
digit year. ColdFusion 5 uses 29.
Note: The following locales use 28 as the date pivot point instead of 20: English (Australian), English
(New Zealand), German (Austrian), German (Standard), German (Swiss), Portuguese (Brazilian),
Portuguese (Standard), and Swedish. Macromedia has confirmed this inconsistency using the SUN
JRE version 1.4 and the IBM JRE version 1.3.0.

Other changes 19
So in ColdFusion MX, if the date is within 80 years before and 20 years after the date when it
processes the date, then ColdFusion MX returns the date with the current century. Otherwise, it
returns the previous century. In ColdFusion 5, if the date is within 71 years before and 29 years
after the date when it processes the date, then ColdFusion 5 returns the current century.
Otherwise, it returns the previous century. This can cause incompatible results. For example,
LSParseDateTime("25-12-13 22:10:15") returns a year of 1925 in ColdFusion MX, and
2025 in ColdFusion 5.
Note: Results might differ, depending on your Java Runtime Environment (JRE). This information
reflects tests on the SUN JRE version 1.4 and the IBM JRE version 1.3.0.
For more information, see the version-specific Java documentation for the
java.text.SimpleDateFormat class, at http://java.sun.com/j2se/.
Request variable
ColdFusion MX no longer supports the RequestTimeout attribute in the URL. For pages
expecting the RequestTimeout attribute in the URL, add the following tag:
<cfsetting RequestTimeout = "#URL.RequestTimeout#">
For more information, see the “Reserved Words and Variables” chapter in CFML Reference.
Definition of pi
ColdFusion MX and ColdFusion 5 define pi with slightly different precision. Therefore, you
might obtain slightly different results between the two for trigonometric functions such as sin,
cos, and tan at the boundaries (0, 90, 180, 270, ... degrees).
Null values
ColdFusion 5 converted all null values to an empty string (""). For queries, ColdFusion MX
preserves null values, but converts them to an empty string when you use them as simple values.
However, when you call a Java method that returns a null value, ColdFusion MX destroys the
variable to which the null value was returned.
The thisTag scope
In ColdFusion 5, you can change system values in the thisTag scope that persist throughout the
execution of the tag. This is fixed in ColdFusion MX; it throws an exception if you try to set
thisTag.hasendtag or thisTag.executionmode.
Caching
In ColdFusion MX, in the Caching page of the ColdFusion MX Administrator, the Template
cache size (number of templates) option displays the number of templates in the cache. In
ColdFusion 5, it displays the size of the cached templates in kilobytes.

20 Chapter 1: Migrating Applications from ColdFusion 5
Log files
ColdFusion MX does not support the following ColdFusion 5 log files:
•executive.log
•remote.log
•proxy.log
•cfadmin.log
•install.log
•server.stdout
•rdsservice.stdout
Using cfform in a multihomed environment
In ColdFusion 5, the cfform tag used inline JavaScript code for validation. In ColdFusion MX,
cfform includes the CFIDE/scripts/cfform.js file, which contains all JavaScript. However, if your
application runs in a hosted environment with multiple virtual websites, your virtual website may
not contain a CFIDE directory, which causes JavaScript errors when using cfform.
If you encounter this problem, use one of the following solutions:
•Use the Default CFFORM ScriptSrc Directory field on the ColdFusion MX Administrator to
specify the default path (relative to the web root) of the directory containing the cfform.js file.
•Ask your hosting provider to provide a copy of cfform.js and change your cfform tags to use
the scriptsrc attribute, specifying the location of this file.
•Ask , your hosting provide to modify your virtual website to include a virtual mapping for the
CFIDE directory.
Moving to IBM WebSphere
IBM WebSphere does not use web server virtual mappings to locate CFM pages. If you are
migrating a ColdFusion 5 application to ColdFusion MX running on WebSphere using the J2EE
configuration and your application stores CFM pages in directories that use virtual mappings,
you must reconfigure your application and move these pages to a nonvirtual directory.
For more information, see the WebSphere pages on www.macromedia.com/go/cfmxj2ee-cert.
The application.cfc file
The updated application framework in ColdFusion MX 7 lets you use a file named
Application.cfc to control your application and keep track of application events. You use
Application.cfc instead of Application.cfm. Application.cfc methods are triggered when
application, sessions, and requests start or stop, and when the application encounters an
exception.
If your application already uses a file named Application.cfc, you must rename it.