MACROMEDIA ColdFusion MX User Manual

Installing and Using ColdFusion MX for IBM

® WebSphere® Application Server

Trademarks

Afterburner, AppletAce, Attain, Attain Enterprise Learning System, Attain Essentials, Attain Objects for Dreamweaver, Authorware, Authorware Attain, Authorware Interactive Studio, Authorware Star, Authorware Synergy, Backstage, Backstage Designer, Backstage Desktop Studio, Backstage Enterprise Studio, Backstage Internet Studio, ColdFusion, Design in Motion, Director, Director Multimedia Studio, Doc Around the Clock, Dreamweaver, Dreamweaver Attain, Drumbeat, Drumbeat 2000, Extreme 3D, Fireworks, Flash, Fontographer, FreeHand, FreeHand Graphics Studio, Generator, Generator Developer's Studio, Generator Dynamic Graphics Server, JRun, Knowledge Objects, Knowledge Stream, Knowledge Track, Lingo, Live Effects, Macromedia, Macromedia M Logo & Design, Macromedia Flash, Macromedia Xres, Macromind, Macromind Action, MAGIC, Mediamaker, Object Authoring, Power Applets, Priority Access, Roundtrip HTML, Scriptlets, SoundEdit, ShockRave, Shockmachine, Shockwave, Shockwave Remote, Shockwave Internet Studio, Showcase, Tools to Power Your Ideas, Universal Media, Virtuoso, Web Design 101, Whirlwind and Xtra are 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, servicemarks, or tradenames of Macromedia, Inc. or other entities and may be registered in certain jurisdictions including internationally.

This product includes code licensed from RSA Data Security.

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.

Apple Disclaimer

APPLE COMPUTER, INC. MAKES NO WARRANTIES, EITHER EXPRESS OR IMPLIED, REGARDING THE ENCLOSED COMPUTER SOFTWARE PACKAGE, ITS MERCHANTABILITY OR ITS FITNESS FOR ANY PARTICULAR PURPOSE. THE EXCLUSION OF IMPLIED WARRANTIES IS NOT PERMITTED BY SOME STATES. THE ABOVE EXCLUSION MAY NOT APPLY TO YOU. THIS WARRANTY PROVIDES YOU WITH SPECIFIC LEGAL RIGHTS. THERE MAY BE OTHER RIGHTS THAT YOU MAY HAVE WHICH VARY FROM STATE TO STATE.

Copyright © 2002–2003 Macromedia, Inc. All rights reserved. This manual may not be copied, photocopied, reproduced, translated, or converted to any electronic or machine-readable form in whole or in part without prior written approval of Macromedia, Inc. Part Number CT27MNA

Acknowledgments

Project Management: Randy Nielsen

Writing: Hal Lichtin, Randy Nielsen

Editing: Linda Adler, Noreen Maher

Third Edition: February 2003 Fourth Edition: September 2003

Macromedia, Inc. 600 Townsend St. San Francisco, CA 94103

CONTENTS

INTRODUCTION . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

About Macromedia ColdFusion MX documentation . . . . . . . . . . . . . . . . . . . . . . . 5

Documentation set . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

Viewing online documentation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

CHAPTER 1: Essential Information. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

About ColdFusion MX for IBM WebSphere Application Server . . . . . . . . . . . . . . . 8

Overview of the J2EE platform . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

Overview of ColdFusion MX for IBM WebSphere Application Server . . . . . . . . 8

System requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

Operating system and Java requirements. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

Additional requirements and software support . . . . . . . . . . . . . . . . . . . . . . . . . 10

Directory structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

Differences between ColdFusion MX and ColdFusion MX on WebSphere . . . . . . 12

General ColdFusion MX feature differences . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

Differences in directory locations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

Differences in the ColdFusion MX Administrator . . . . . . . . . . . . . . . . . . . . . . 14

Installing ColdFusion MX for IBM WebSphere Application Server. . . . . . . . . . . . 15

Considerations for all platforms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

Considerations for Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

Installation procedure. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

Creating and migrating applications on ColdFusion MX . . . . . . . . . . . . . . . . . . . 16

Learning about ColdFusion MX. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

Migrating existing ColdFusion applications . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

CHAPTER 2: Installing on WebSphere V5 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

Installing and deploying Macromedia ColdFusion MX . . . . . . . . . . . . . . . . . . . . . 18

Installing the ColdFusion MX files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18

Deploying ColdFusion MX on WebSphere. . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

Running the Configuration and Settings Migration Wizard . . . . . . . . . . . . . . . 22

Enabling and configuring specific ColdFusion MX functionality . . . . . . . . . . . . . 23

Enabling features with operating system-specific binaries . . . . . . . . . . . . . . . . . 23

Enabling Access to COM objects (Windows only) . . . . . . . . . . . . . . . . . . . . . . 25

Enabling charting and graphing (UNIX) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26

Disabling RDS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26

Undeploying ColdFusion MX. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28

CHAPTER 3: Installing on WebSphere V4 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29

Installing and deploying Macromedia ColdFusion MX . . . . . . . . . . . . . . . . . . . . . 30

Installing the ColdFusion MX files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30

Deploying ColdFusion MX on WebSphere. . . . . . . . . . . . . . . . . . . . . . . . . . . . 32

Running the Configuration and Settings Migration Wizard . . . . . . . . . . . . . . . 35

Enabling and configuring specific ColdFusion MX functionality . . . . . . . . . . . . . 36

Enabling features with operating system-specific binaries . . . . . . . . . . . . . . . . . 36

Enabling sandbox security (AIX) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38

Enabling access to COM objects (Windows) . . . . . . . . . . . . . . . . . . . . . . . . . . 38

Enabling charting and graphing (Unix) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38

Supporting messages from a POP mail server (pre-FixPak 4) . . . . . . . . . . . . . . 40

Disabling RDS after installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40

Undeploying ColdFusion MX. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41

CHAPTER 4: Enabling and Using ColdFusion MX Features . . . . . . . . . . . . . . . . . 43

Enabling ColdFusion MX functionality . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44

Installing Verity Search Packs for ColdFusion MX . . . . . . . . . . . . . . . . . . . . . . 44

Enabling CORBA support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44

Enabling web services access for Flash Remoting . . . . . . . . . . . . . . . . . . . . . . . 46

Using a third-party JDBC database driver. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46

Managing ColdFusion MX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47

Managing the ColdFusion MX application. . . . . . . . . . . . . . . . . . . . . . . . . . . . 47

Managing ColdFusion MX Windows services . . . . . . . . . . . . . . . . . . . . . . . . . 47

Using the / context root. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48

Accessing the ColdFusion MX Administrator . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49

Migrating a ColdFusion application to IBM WebSphere Application Server . . . . . 49

Using RDS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50

About RDS configuration. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50

Configuring RDS for a new ColdFusion MX context root . . . . . . . . . . . . . . . . 51

4 Contents

INTRODUCTION

Installing and Using ColdFusion MX for IBM WebSphere Application Server is intended for anyone

who needs to configure and manage their ColdFusion development environment.

About Macromedia ColdFusion MX documentation

The ColdFusion MX documentation is designed to provide support for the complete spectrum of

participants.

Documentation set

The ColdFusion MX documentation set includes the following titles:

Book Description

Installing and Using ColdFusion MX for IBM WebSphere Application Server

Configuring and Administering ColdFusion MX

Developing ColdFusion MX Applications

Getting Started Building ColdFusion MX Applications

CFML Reference Provides descriptions, syntax, usage, and code examples for all ColdFusion

CFML Quick Reference A brief guide that shows the syntax of ColdFusion tags, functions, and

Describes system installation and basic configuration for Windows NT, Windows 2000, AIX, Linux, and Solaris.

Part I describes how to use the ColdFusion MX Administrator to manage the ColdFusion environment, including connecting to your data sources and configuring security for your applications, Part II describes Verity search tools and utilities that you can use for configuring the Verity K2 Server search engine, as well as creating, managing, and troubleshooting Verity collections.

Describes how to develop your dynamic web applications, including retrieving and updating your data, using structures, and forms.

Contains an overview of ColdFusion features and application development procedures. Includes a tutorial that guides you through the process of developing an example ColdFusion application.

tags, functions, and variables.

variables.

Viewing online documentation

All ColdFusion MX documentation is available online in HTML and Adobe Acrobat Portable

Document Format (PDF) files. Go to the documentation home page for ColdFusion MX on the

Macromedia website: www.macromedia.com.

6 Introduction

CHAPTER 1

Essential Information

This chapter describes Macromedia ColdFusion MX for IBM WebSphere Application Server and

provides information that applies to all WebSphere installations.

Contents

About ColdFusion MX for IBM WebSphere Application Server . . . . . . . . . . . . . . . . . . . . . . . . 8

System requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

Directory structure. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

Differences between ColdFusion MX and ColdFusion MX on WebSphere

Installing ColdFusion MX for IBM WebSphere Application Server . . . . . . . . . . . . . . . . . . . . . 15

Creating and migrating applications on ColdFusion MX. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

About ColdFusion MX for IBM WebSphere Application Server

Macromedia ColdFusion MX for IBM WebSphere Application Server enables you to add

ColdFusion MX capabilities to your Sun Java 2 Platform, Enterprise Edition (J2EE) application

server. It is a J2EE application that installs on top of your existing Java application server and

provides development, deployment, and management services for ColdFusion applications.

Overview of the J2EE platform

The J2EE platform is a set of detailed specifications and runtime services for developing

enterprise applications. A J2EE-compliant application is based on standardized, modular

components. J2EE provides these components with a complete set of services, and automatically

handles many details of the application behavior; for example, providing pluggable and scalable

database connection pooling and transparently managing web session clustering and failover.

J2EE provides a security model to protect your data and JDBC, an application programming

interface (API) to access your data. Also, J2EE is interoperable with other technologies that follow

the same modularized standard; for example, you can use Enterprise JavaBeans (EJBs), Java

Servlets, JavaServer Pages (JSP), and XML in your applications.

For more information, see http://java.sun.com/j2ee.

Overview of ColdFusion MX for IBM WebSphere Application Server

The ColdFusion MX for IBM WebSphere Application Server runtime environment is a Java

application that takes advantage of the services in the J2EE platform to connect to databases,

manage security, and process application requests. It provides the full scripting environment of

Macromedia ColdFusion MX and lets you develop fully featured Rich Internet Applications

rapidly and efficiently. When ColdFusion MX for IBM WebSphere Application Server is installed

on top of the WebSphere Application Server, it uses that server’s J2EE runtime to compile and

execute ColdFusion applications.

For more information about Macromedia ColdFusion MX, see the ColdFusion MX

documentation.

For information about differences between ColdFusion MX and ColdFusion MX for IBM

WebSphere Application Server on your operating system and application server version, see

“Differences between ColdFusion MX and ColdFusion MX on WebSphere” on page 12.

System requirements

This section lists the system requirements for ColdFusion MX for Windows and UNIX. This

information was up-to-date at the time this document was written. For any updates, see

www.macromedia.com/go/cfmxj2ee-cert.

Note: If you use Macromedia ColdFusion Studio to develop your web applications, note that

ColdFusion MX supports ColdFusion Studio versions 4.5.2 and 5.0 only.

8 Chapter 1: Essential Information

Operating system and Java requirements

The following table lists the operating systems supported by the ColdFusion MX for IBM

WebSphere Application Server editions. The following considerations also apply:

• The supported Java runtime environment is the default runtime installed with the application

server.

• Additional system update requirements follow the table.

For the most up-to-date list of certified platforms, see the Macromedia support site,

www.macromedia.com/support/coldfusion.

Edition Operating systems

IBM WebSphere 4 Windows NT 4.0 Server SP6A

Windows 2000 Server SP3 Windows 2000 Advanced Server SP3 Red Hat Linux 7.2 SuSE Linux 7.2

Solaris 7 Solaris 8 AIX 4.3.3 AIX 5L v5.1

IBM WebSphere 5 Windows NT 4.0 Server SP6A

Windows 2000 Server SP3 Windows 2000 Advanced Server SP3 Red Hat Linux 8.0

RedHat Advanced Server 2.1 SuSE Linux 7.3 Solaris 8 AIX 4.3.3 AIX 5L v 5.1

Include the following updates for your operating system:

• To use Microsoft Access or other databases that require an ODBC driver, on Windows NT 4.0

Server or Windows 2000 Server, you must have the following component installed: MDAC

2.5 SP1 (www.microsoft.com/data/download.htm).

• For all UNIX distributions, install the latest production-level patches, including the kernel,

from the supplier’s download sites: for Red Hat, ftp://ftp.redhat.com/pub; for SuSE, ftp:// ftp.suse.com/pub; for Solaris, http://sunsolve.sun.com/pub-cgi/show.pl?target=patches/patchaccess; for AIX, http://www.ibm.com/software/webservers/appserv/support.html.

• To use C++ CFXs with RedHat Linux 8.0, the Linux installation must have a RedHat libc

compatibility library such as the following: RedHat-8.0 for i386 compat-libstdc++-7.3-2.96.110.i386.rpm Users must have 7.3-2.* or later.

System requirements 9

Additional requirements and software support

The following table lists the hardware requirements, supported browsers, specific supported

application server editions, and supported databases for the various ColdFusion MX for IBM

WebSphere Application Server editions:

Category J2EE server Requirement

Minimum hardware requirements

Browsers supported for ColdFusion MX Administrator

Supported Databases All JDBC drivers are included for the

All Processor

Windows and Linux: Pentium Solaris: SPARC AIX: POWER/3 Minimum RAM Developer Edition, Windows: 128 MB All others: 256 MB

Recommended RAM Developer Mode, Windows: 256 MB All others: 512 MB

Free hard disk space To deploy: 400 MB To run: 250 MB

CD-ROM drive

All Internet Explorer 5.x, 6

Netscape 4, 6, 7 Mozilla 1.0

following databases:

Oracle 8.1.6 - 8.1.7, 9i (R1 - R2) Sybase 11.5 -11.9, 12, 12.5 DB2 for Windows, UNIX, and Linux v7.1,

v7.2, v8.1 DB2 for OS/390 v6.1, v7 Informix 9.2.x, 9.3.x, and 9.4 Microsoft SQL Server 7.0, 2000 MySQL

10 Chapter 1: Essential Information

On Windows, drivers are included for :

Access 97, 98, 2000, 2003 ODBC socket, supports ODBC compliant

databases

Connectivity is provided for all databases for which JDBC drivers compliant with the JDBC 3.0 specification are available.

Category J2EE server Requirement

Supported Application servers

IBM WebSphere 4 IBM WebSphere Advanced Edition,

Single Server 4.0.3, 4.0.4, or 4.0.5 Advanced Edition 4.0.3, 4.0.4, or 4.0.5

Note: FixPAK 3 or later is required

IBM WebSphere 5 IBM WebSphere Application Server 5.0

or 5.0.1 IBM WebSphere Application Server for

Developer 5.0 or 5.0.1 IBM WebSphere Application Server for

Network Deployment 5.0 or 5.0.1

To use data sources that you configure in WebSphere and third-party JDBC drivers, see “Using a

third-party JDBC database driver” on page 46.

Directory structure

The ColdFusion root directory, referred to as cf_root, contains all ColdFusion software except for Remote Development Services (RDS) support, which enables Macromedia Dreamweaver MX and Macromedia HomeSite+ to access ColdFusion directly. RDS support is not recommended on production servers.

If you install RDS support, it is located in a rds.war directory in the same parent directory as the ColdFusion root directory.

The following table describes the contents of the root directory of ColdFusion MX for IBM WebSphere Application Server. This table uses the backslash character (\) for directory paths; the information is the same for UNIX, except that the directories are separated by forward slashes (/).

Directory Contents

cfdocs Documentation for ColdFusion MX.

CFIDE Files for the ColdFusion MX Administrator.

META-INF Information about the application (might not contain substantial

information).

WEB-INF\cfclasses Compiled ColdFusion templates in your ColdFusion applications.

WEB-INF\cfc-skeletons Support for ColdFusion components that are exported as web

services.

WEB-INF\cftags Templates for ColdFusion MX.

WEB-INF\cfusion\bin Executable files used by ColdFusion MX.

WEB-INF\cfusion\cache Cached files.

WEB-INF\cfusion\cfx CFX tag include file and examples

WEB-INF\cfusion\charting Files for the ColdFusion MX graphing and charting engine.

WEB-INF\cfusion\Custom Tags Repository for your custom tags.

Directory structure 11

Directory Contents

WEB-INF\cfusion\db Sample databases: in Windows, the files for sample Microsoft

Access databases and ODBC services. On UNIX, the files for the sample Pointbase databases. Also includes software for installing ODBC support and other database system specific files.

WEB-INF\cfusion\jintegra JIntegra programs, libraries, and other supporting files (for

example, to integrate Java and COM code; manage access to ActiveX controls (OCXs) that are hosted in a graphical user interface (GUI) container; and register the JVM and type libraries).

WEB-INF\cfusion\lib and WEBINF\lib

WEB-INF\cfusion\logs ColdFusion MX log files.

WEB-INF\cfusion\Mail Files, including spool files, used by ColdFusion for mail.

WEB-INF\cfusion\registry Used only in UNIX, by the

WEB-INF\cfusion\stubs Contains compiled code for web services.

WEB-INF\cfusion\verity Verity collections.

WEB-INF\classes Java classes for the ColdFusion MX application.

WEB-INF\debug Files for debugging in ColdFusion MX.

WEB-INF\exception Files for exception handling in ColdFusion MX.

JAR, XML, property, and other files that are the foundation of ColdFusion MX, including functionality such as queries, charting, mail, security, Verity searches, and system probes.

cfregistry tag.

Differences between ColdFusion MX and ColdFusion MX on WebSphere

The following sections describe differences between the two configurations supported by ColdFusion MX: the J2EE configuration and the server configuration. ColdFusion MX for IBM WebSphere supports the J2EE configuration. Editions of ColdFusion MX available directly from Macromedia also support the server configuration. These differences include:

General ColdFusion MX feature differences

Differences in directory locations

Differences in the ColdFusion MX Administrator

General ColdFusion MX feature differences

The following differences exist between the features that are available in the ColdFusion MX server configuration and those that are available in ColdFusion MX for IBM WebSphere Application Server:

For All operating systems

• The CFML GetMetricData() function is not supported.

• Your application must use relative paths to ensure that it works on any application server.

12 Chapter 1: Essential Information

• ColdFusion MX for IBM WebSphere Application Server requires a redirector web application

for RDS access if you do not deploy the ColdFusion MX web application at the / context root. For more information, see “Using RDS” on page 50.

• ClusterCATS is not available; load-balancing is provided by your application server.

• On WebSphere 4, sandbox security cannot secure Java access to files and network resources.

For AIX

The following features are not supported on AIX:

• Ver it y search en gi ne

• CFX tags written in C++

• CreateUUID uses Java random characters in place of the MAC address

• Crystal Report integration (cfreport tag)

• COM support

• ODBC support

For RedHat

The Verity search engine is not supported on RedHat Linux 8.0.

Differences in directory locations

This section compares directory locations for ColdFusion MX and ColdFusion MX for IBM WebSphere Application Server.

Note: If you are developing a ColdFusion application on the ColdFusion MX server and you are deploying it to IBM WebSphere Application Server, also see Chapter 4, “Migrating a ColdFusion

application to IBM WebSphere Application Server,” on page 49.

Location of ColdFusion MX root directory

In the ColdFusion MX server, the default location of the ColdFusion MX root directory, (referred to as cf_root) is C:\CFusionMX in Windows and /opt/coldfusionmx on UNIX. For a description of the contents of the cf_root directory for ColdFusion MX, see Installing and Using ColdFusion MX on the ColdFusion MX Documentation page at www-3.ibm.com/software/webservers/ coldfusionmx/library.html.

In ColdFusion MX for IBM WebSphere Application Server, the location of the ColdFusion MX root directory, where the ColdFusion web application is installed, differs depending on the application server.

Note: For a description of the contents of the cf_root directory for IBM WebSphere Application Server, see Chapter 1, “Directory structure,” on page 11.

Differences between ColdFusion MX and ColdFusion MX on WebSphere 13

The following table lists the location of the root directory for the application servers:

Application server Windows location UNIX location

WebSphere 5 websphere_root\AppServer\

installedApps\node_name\ Macromedia ColdFusion MX.ear\cfusion.war

WebSphere 4 websphere_root\AppServer\

installedApps\cfusion.ear\ cfusion.war

AIX websphere_root\AppServer\

installedApps\app_name\ cfusion.war

websphere_root/AppServer/ installedApps/node_name/ Macromedia ColdFusion MX.ear/ cfusion.war

websphere_root/AppServer/ installedApps/cfusion.ear/ cfusion.war

websphere_root/AppServer/ installedApps/app_name/ cfusion.war

Location of your ColdFusion application files

In ColdFusion MX, the ColdFusion application files are located under the web root directory; for example, C:\InetPub\wwwroot. In ColdFusion MX for IBM WebSphere Application Server, your ColdFusion application files belong under the cf_root directory. Your application server and its configured web server will correctly handle your individual application files if they are located under this directory.

Differences in the ColdFusion MX Administrator

The following table summarizes the differences in the ColdFusion MX Administrator between ColdFusion MX and ColdFusion MX for IBM WebSphere Application Server:

Administrator component Status Notes

For all servers and operating systems

Server Settings > Java and JVM

Server Settings > Archives and Deployment

Data & Services > Data Sources

Debugging & Logging > Debugging Settings

For WebSphere 4 and 5 on AIX

Data & Services > Verity Collections

Data & Services > Verity K2 Server

Removed Your application server handles these settings, not

ColdFusion MX.

Not changed

Changed The Enable Performance Monitor and Enable CFSTAT

Inoperative Verity is not available, but the administrator pages

Inoperative

This functionality might differ from what you would expect from a J2EE application. For more information about this feature, see the ColdFusion MX Administrator online Help.

This page might display the data sources that are managed by your application server and by ColdFusion MX. You cannot modify the data sources that are managed by your application server on this page.

options are not available. Performance monitoring is not supported in ColdFusion MX for J2EE.

display. An attempt to set a value on these pages causes an error message.

14 Chapter 1: Essential Information

Installing ColdFusion MX for IBM WebSphere Application Server

This section describes installation considerations and the overall installation procedure that apply to all ColdFusion MX for IBM WebSphere Application Server editions.

Considerations for all platforms

The following are installation considerations for all platforms:

• In an optimal production environment, each ColdFusion MX application is hosted on a

dedicated server; database, mail, and other servers are not on the same computer.

• To interact with ColdFusion pages, components, and server-side ActionScript from a

Macromedia Flash movie, use the Macromedia Flash Remoting MX service in ColdFusion MX. Although no special installations are required to develop ColdFusion applications for the Flash Remoting MX service, you must install the Flash Remoting Components in the Macromedia Flash MX authoring environment. The Flash MX authoring environment is required to build applications that connect to and interact with the Flash Remoting MX service in ColdFusion.

For more information on Flash Remoting MX, see Developing ColdFusion MX Applications, available from the ColdFusion MX Documentation page at www-3.ibm.com/software/ webservers/coldfusionmx/library.html.

Considerations for Windows

The following are installation considerations for Windows:

• If you previously added a cf_root\bin or cf_root\verity\_nti40\bin directory to your system path

for ColdFusion 5, you must remove it before installing ColdFusion MX for J2EE. (For instructions, see the Microsoft Windows online Help.) Otherwise, ColdFusion MX cannot locate the correct Verity DLL files.

• Do not configure the server running ColdFusion MX as a primary domain controller (PDC)

or backup domain controller (BDC). Macromedia follows the Microsoft network model, in which the first level is the PDC/BDC. These systems only manage the network or domain and are not designed to run application servers. ColdFusion MX must reside on the second level of Windows NT and Windows 2000 stand-alone systems. Stand-alone servers can participate in a network or domain.

• Windows NT 4.0 Workstation and Windows 2000 Professional handle only 10 TCP/IP

connections concurrently. Therefore, Macromedia does not recommend using these operating systems in a production environment; use Window NT 4.0 Server or Windows 2000 Server instead.

Installation procedure

The ColdFusion MX for IBM WebSphere Application Server installation procedure depends on your application server and the target operating system. The application server-specific installation chapters detail these procedures.

Installing ColdFusion MX for IBM WebSphere Application Server 15

Creating and migrating applications on ColdFusion MX

This section describes resources that can help you get started creating ColdFusion MX applications or migrating existing ColdFusion applications to ColdFusion MX on WebSphere Application Server.

Learning about ColdFusion MX

If you are familiar with J2EE applications but you are a new ColdFusion MX user, there are several sources of information that can help you to quickly begin using ColdFusion MX:

• Getting Started Building ColdFusion MX Applications

• Resources, including tutorials and example applications, that you can access from the Home

page of the ColdFusion MX Administrator

• The Get Started with ColdFusion MX page on the Macromedia website at

www.macromedia.com/go/cfresources.

Migrating existing ColdFusion applications

For information on migrating existing ColdFusion MX applications, including ColdFusion applications to ColdFusion MX 6.1on IBM WebSphere, see Migrating ColdFusion Applications, which is available at www.macromedia.com/go/cfmxmigration.

16 Chapter 1: Essential Information

CHAPTER 2

Installing on

Before you can use ColdFusion MX on IBM WebSphere Application Server V5, you must do the following steps:

1 Install the ColdFusion files. 2 Deploy the ColdFusion J2EE application. 3 Configure ColdFusion in the Configuration and Migration Wizard. 4 Enable specific functionality required by ColdFusion applications, such as the Verity search

engine.

This chapter describes these steps in detail. It also describes how to undeploy ColdFusion MX.

Note: Check the Macromedia website at www.macromedia.com/go/cfmxj2ee-cert for any updates to these installation instructions, or other late-breaking information.

This chapter uses the following conventions:

WebSphere V5

• websphere_root refers to the directory in which IBM WebSphere Application Server is installed;

for example, C:\Program Files\WebSphere in Windows, and /opt/WebSphere on UNIX.

• cf_root refers to the directory to which ColdFusion is deployed; for example, C:\Program

Files\WebSphere\AppServer\installedApps\MyHost\Macromedia ColdFusion MX.ear\cfusion.war in Windows, and /opt/WebSphere/AppServer/installedApps/MyHost/ cfusion.ear/cfusion.war on UNIX.

Contents

Installing and deploying Macromedia ColdFusion MX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18

Enabling and configuring specific ColdFusion MX functionality. . . . . . . . . . . . . . . . . . . . . . . 23

Undeploying ColdFusion MX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28

Installing and deploying Macromedia ColdFusion MX

Before you can run ColdFusion applications, you must complete the following procedures to install and deploy ColdFusion MX to your application server:

1 Installing the ColdFusion MX files 2 Deploying ColdFusion MX on WebSphere 3 Running the Configuration and Settings Migration Wizard

Note: This chapter describes how to install ColdFusion MX directly from the cfusion.ear file. You can also install ColdFusion MX as a WAR file, but the process is more complex. To install using a WAR file, you must expand the cfusion.ear file into its constituent WAR files and deploy the cfusion.war file, specifying a context root in the WebSphere Administrative Console. If you do not deploy ColdFusion at the / context root, you must also deploy the rds.war file and specify /CFIDE as its context root.

Installing the ColdFusion MX files

The specific file you use to install ColdFusion MX for IBM WebSphere Application Server depends on your operating system. The following table lists the supported operating systems and the files on the product CD that you use to install ColdFusion MX:

Operating system Installation file

Full Product

Windows coldfusion-61-ibm-win.exe

Linux coldfusion-61-ibm-linux.bin

Solaris coldfusion-61-ibm-solaris.bin

AIX coldfusion-61-ibm-other.jar

Evaluation only

Windows coldfusion-61-ibm-eval-win.exe

Linux coldfusion-61-ibm-eval-linux.bin

Solaris coldfusion-61-ibm-eval-solaris.bin

AIX coldfusion-61-ibm-eval-other.jar

Note: The installation files on the IBM website use the product part number as the filename. Also, the AIX, Linux, and Solaris installation files on the website are in tar.gz zip archives; you must unzip these archives to get the installable .bin files. If you use a downloaded file, replace the CD image filename in the following instructions with the file you downloaded or downloaded and unzipped.

Use the following procedure to install the ColdFusion MX EAR file and installation documentation.

To install ColdFusion MX files:

1 Ensure that your system environment meets the system requirements described in Chapter 1,

“Essential Information,” on page 7.

2 Review the section “Installing ColdFusion MX for IBM WebSphere Application Server”

on page 15.

3 Read the Release Notes for any late-breaking information or updates.

18 Chapter 2: Installing on WebSphere V5

4 Close any applications that are currently running on the computer to which you are deploying

ColdFusion MX.

5 If you have the ColdFusion MX for IBM WebSphere Application Server evaluation or product

CD-ROM, insert the CD. Otherwise, download the installer file for your platform from the IBM website or a designated network.

6 Start the installation program. Do one of the following, depending on your operating system:

System Procedure

AIX Set the working directory to the directory that contains the JAR file

listed in the preceding table. Enter one of the following commands, replacing java_home with the path to the bin directory for your JRE installation:

In GUI mode (you must have XWindows Display configured): java_home/java -jar coldfusion-61-ibm-other.jar -i gui

or, for the evaluation version: java_home/java -jar coldfusion-61-ibm-eval-other.jar -i gui

In console mode: java_home/java -jar coldfusion-61-ibm-other.jar -i console

or, for the evaluation version, java_home/java -jar coldfusion-61-ibm-eval-other.jar -i console

Windows Double-click the installer file.

Solaris or Linux Set the working directory to the directory that contains the installer file

listed in the preceding table. In GUI mode (you must have XWindows Display configured), enter the

installer file for your operating system, followed by the -i gui switch; for example:

./coldfusion-61-ibm-linux.bin -i gui In console mode, enter the installer file for your operating system, followed by the -i console switch; for example:

./coldfusion-61-ibm-linux.bin -i console

7 Follow the instructions in the installation program. Use the following information to complete

certain sections of the installation program:

■ Before installing, determine the location of a working directory into which the ColdFusion

MX for J2EE EAR file should be installed.

■ The initial installer screen lets you select the language for the installer. This selection also

determines the language for the online Help and installed documentation.

■ On the License Agreement page, you must select I accept the terms of the License

Agreement before you can click Next.

■ On the Install Type page, select whether you are updating a ColdFusion MX installation to

ColdFusion MX 6.1, or installing a new version of ColdFusion MX. If you select the Update option, the installer backs up your application files, including configuration files. This is required because you must undeploy your ColdFusion application as part of the update procedure. You then use the backup files to restore the application.

■ ColdFusion asks you for the directory in which to install the files. These files are required to

deploy ColdFusion on WebSphere, but are not required afterward. Therefore, you can specify a staging area or temporary file location.

Installing and deploying Macromedia ColdFusion MX 19

■ If you specify an update installation, the installer asks you to select the directory in which to

back up your ColdFusion application files, and the location where you deployed the ColdFusion MX web application you want to back up, such as C:\Program Files\WebSphere\AppServer\installedApps\MyNode\Macromedia ColdFusion MX.ear\cfusion.war. If you have multiple ColdFusion MX web applications, you must run the installer once for each web application, to ensure that all files get backed up properly, and specify a different backup directory each time.

Note: Do not specify a backup directory that is inside your current application directory. For example, do not specify a directory such as C:\Program Files\WebSphere\AppServer\ installedApps\MyNode\Macromedia ColdFusion MX.ear. When you deploy the updated version of ColdFusion MX, you first undeploy your old version of ColdFusion, which deletes files in the application directory.

■ On the Context Root page, specify a name for the ColdFusion MX application context

root. The context root is the first part of the URL for all requests sent to the application. The application server uses the context root to determine which web application must service an incoming request The default value is cfmx. For information, see “Using the / context root”

on page 48.

■ In the ColdFusion MX Administrator password page, enter the password to require for the

ColdFusion MX Administrator.

■ Review the options in the Pre-Installation Summary section and accept them to complete

the installation.

When the installation is complete, the EAR file and any backup files are put in the specified locations. The installation wizard exits and a product registration page appears. Continue with the next section of the instructions, “Deploying ColdFusion MX on WebSphere”.

Note: The installer creates the following log file: install_root/ Macromedia_ColdFusion_MX_J2EE_InstallLog.log, where install_root is the directory that you specify when you install the ColdFusion MX files. If you contact Technical Support for installation support, you must send them this log file.

Deploying ColdFusion MX on WebSphere

This section describes how to deploy ColdFusion MX on WebSphere 5.

To deploy ColdFusion MX on WebSphere 5:

1 Start the IBM WebSphere Application Server, if it is not running. 2 Open the Run the IBM WebSphere Administrative Console, if it is not running. 3 If you are updating an existing ColdFusion MX application, you must uninstall the existing

copy of ColdFusion. Do the following:

a In Windows, if the ODBC services are installed, open the Services panel and make sure that

the ColdFusion MX ODBC server and the ColdFusion MX ODBC agent are stopped.

b On the WebSphere Administrative Console Applications > Enterprise Applications page,

select the ColdFusion application (the default name is Macromedia ColdFusion MX). If the application is running, click stop; when it has stopped, select it again. Click Uninstall.

20 Chapter 2: Installing on WebSphere V5

c WebSphere might display the warning “The operation did not complete in the expected

amount of time. It may have completed successfully. Check the logs for details.” This message indicates that uninstalling the application is taking some time; it does not necessarily indicate a problem. You can check the J2EE server logs (for example, C:\Program Files\WebSphere\AppServer\logs\server1\SystemOut.log) for any errors before proceeding.

d In the Messages box at the top of the Administrative Console page, click the Save link to

apply changes to the master configuration. Then click the Save button on the Save page to save your workspace. This might take some time. When it is complete, the main Administrative Console page appears.

e Stop the WebSphere Application Server. f Delete the cf_root directory (for example, C:\Program Files\WebSphere\AppServer\

installedApps\MyNode\Macromedia ColdFusion MX.ear).

g Restart the WebSphere Application Server.

4 Open the Applications > Install New Application page. 5 The Preparing Application Install page appears. Enter the path to the EAR file that you installed

in the Installing the ColdFusion MX files procedure; for example C:\CFMXJ2ee\cfusion.ear. Leave the Context Root box empty and click Next.

Note: If you are running the Administrative console from a browser that is not on the same system where WebSphere is running (i.e., not from localhost), use the Server Path option, which enables directory browsing on the server file system.

6 Accept the default values on the Preparing Application Install page, if appropriate for your

WebSphere configuration. Click Next.

7 Accept the default values in the Step 1: Provide Options to Perform the Installation panel of the

Install New Application procedure, if appropriate for your WebSphere configuration. Click Next.

Note: You might want to change the application name in this step. The default name, Macromedia ColdFusion MX, is long and results in an application deployment directory name (Macromedia ColdFusion MX.ear) that is long and has spaces. These instructions use the default name, however.

8 In Step 2: Map Virtual Hosts for Web Modules, select the virtual host or hosts in which to

install the ColdFusion MX application and Remote Development Services (RDS) support. RDS must be on the same virtual host and port as ColdFusion. Click Next.

9 In Step 3: Map modules to Application Servers, if you have multiple application servers, select

the application server in which to install the ColdFusion application and RDS support. Click Next.

10 In Step 4: Summary, review the installation configuration and click Finish. 11 When the “Application Macromedia ColdFusion MX installed successfully” message appears

on the Installing page, click the Save to Master Configuration link, and click the Save button on the Save page to save your workspace.

12 On AIX systems, if you are using the standard WebSphere JVM, Version 1.3.1, or any version

other than 1.4.2, make sure the ColdFusion application is stopped and replace cf_root/WEB- INF/cfusion/lib/tools.jar with the tools.jar from your JVM (normally websphere_root\AppServer\java\lib\tools.jar).

Installing and deploying Macromedia ColdFusion MX 21

13 Do the following to ensure that ColdFusion sandbox security secures Java access to files and

network resources:

a On the WebSphere Administrative Console Security > Global Security panel, make sure the

Enabled option and Enforce Java 2 Security option are both selected.

b If you made any changes in step a, save your configuration. c Continue with step 14.

14 If the Enabled option and Enforce Java 2 Security option are selected on the Security > Global

Security panel (that is, you use the Java security policy manager), do the following:

a Add the following lines to the JVM’s security policy file, java.policy (for example,

C:\Program Files\WebSphere\AppServer\java\jre\lib\security\java.policy):

grant codeBase "<file:cf_root/WEB-INF/cfusion/lib/*>" { permission java.security.AllPermission; }; grant codeBase "<file:cf_root/WEB-INF/lib/*>" { permission java.security.AllPermission; };

Replace cf_root with your cf_root directory, for example, "C:\Program Files\ WebSphere\AppServer\installedApps\MyNode\Macromedia ColdFusion MX.ear\ cfusion.war".

b Restart the application server.

15 If you are updating an existing ColdFusion MX application, when the workspace is saved, do

the following:

a Open the Enterprise Applications panel and make sure that the ColdFusion application is

stopped.

b Copy the files in the backup directory that you specified in the Installing the ColdFusion

MX files procedure back to your cf_root directory (for example, C:\Program

Files\WebSphere\AppServer\installedApps\ Macromedia ColdFusion MX.ear\cfusion.war). Ensure that the files from the backup directory tree overwrite any files with the same names in the cf_root directory tree.

16 Start the ColdFusion Application in the Enterprise Applications panel. Select the box next to

Macromedia ColdFusion MX, and click Start. You might have to stop and restart the application server on which the ColdFusion application runs before you can start ColdFusion MX.

17 Continue with the next section of the instructions, “Running the Configuration and Settings

Migration Wizard”.

Running the Configuration and Settings Migration Wizard

After you deploy ColdFusion MX, you run the ColdFusion MX 6.1 Configuration and Settings Migration Wizard. To run the wizard in your browser, enter the URL for the ColdFusion MX Administrator. The URL has the following form:

http://host:[port]/cf_context_root/CFIDE/administrator

for example:

http://localhost:9080/cfmx/CFIDE/administrator

For more information on specifying the Administrator URL, see “Accessing the ColdFusion MX

Administrator” on page 49.

22 Chapter 2: Installing on WebSphere V5

When you first access the Administrator, ColdFusion runs the Configuration and Settings Migration Wizard. Provide the wizard with the following information:

Note: When you upgrade a ColdFusion MX installation, the wizard might skip some of the following steps.

• Enter the Administrator password you specified when you installed ColdFusion MX files.

• Specify whether to configure RDS support, and if you configure RDS support, the RDS

password. To maximize security, do not install RDS on production servers. For more information on RDS, see “Using RDS” on page 50.

• (Windows only) Specify whether to install the ODBC socket JDBC driver, which lets

ColdFusion MX access ODBC data sources.

• Specify whether to install example applications and supporting files (including data sources)

for the ColdFusion MX Getting Started tutorial. For security reasons, Macromedia recommends that you do not install example applications on production servers.

• The System Configuration page might tell you that you must do additional configuration steps

to enable full ColdFusion MX functionality. You do not need to make these changes when you run the wizard; click Next. See “Enabling and configuring specific ColdFusion MX

functionality” on page 23 for information on the additional configuration steps you must take

to enable all available ColdFusion MX features.

When the wizard displays the Finish page, click OK to open the ColdFusion MX Administrator. When the Administrator opens, you can configure ColdFusion features. Running the Administrator confirms that the installation procedure was successful. However, you must perform the tasks described in the “Enabling and configuring specific ColdFusion MX

functionality” section before complete ColdFusion MX functionality is available.

Enabling and configuring specific ColdFusion MX functionality

For some ColdFusion MX functionality to work properly, you must manually configure your application server.

This section provides instructions for procedures that are specific to WebSphere 5. It describes what to do for the following functionality:

• Enabling features with operating system-specific binaries

• Enabling access to COM objects (Windows only)

• Enabling charting and graphing (UNIX)

• Disabling RDS

The following procedures are identical for WebSphere 4 and WebSphere 5, and are documented in Chapter 4, “Enabling and Using ColdFusion MX Features,” on page 43:

• Installing Verity Search Packs for ColdFusion MX

• Enabling CORBA support

• Using a third-party JDBC database driver

Enabling and configuring specific ColdFusion MX functionality 23

Enabling features with operating system-specific binaries

This step is required to support the following features that use binaries that are specific to your operating system:

• Verity search engine and the cfcollection, cfindex, and cfsearch tags

• CFX tags written in C++

• The cfreport tag

• Microsoft Access driver with Unicode support (Windows only)

These features work on Windows, Linux, and Solaris only.

Note: To do searches in languages other than English, including both European and Asian languages, you must also install language-specific Verity Search Packs. For more information, see

“Installing Verity Search Packs for ColdFusion MX” on page 44.

Use the procedure for your operating system to configure the search paths to find the required binary files. This files are located in the cf_root\WEB-INF\cfusion\lib directory in Windows, and the cf_root/WEB-INF/cfusion/lib directory on UNIX.

To configure operating system-specific binary support in Windows:

1 Make a backup copy of the setupCmdLine.bat file, located in the websphere_root\AppServer\bin

directory.

2 Open the original file for editing and add the following on a single, long line before the line that

starts with SET WAS_CLASSPATH:

SET CFMX_APPS_PATH=cf_root\WEB-INF\cfusion\lib;cf_root\WEB-INF\cfusion\ lib\_nti40\bin

Replace cf_root with the path to your cf_root directory; for example, enter the following:

SET CFMX_APPS_PATH=%WAS_HOME%\installedApps\%WAS_NODE%\ Macromedia ColdFusion MX.ear\cfusion.war\WEB-INF\cfusion\lib; %WAS_HOME%\installedApps\%WAS_NODE%\Macromedia ColdFusion MX.ear\ cfusion.war\WEB-INF\cfusion\lib\_nti40\bin

3 Add the CFMX_APPS_PATH variable to the WAS_CLASSPATH by appending the following

text to the path statement:

;%CFMX_APPS_PATH%

The WAS_CLASSPATH line should look similar to the following:

SET WAS_CLASSPATH=%WAS_HOME%/properties;%WAS_HOME%/lib/bootstrap.jar;

%WAS_HOME%/lib/j2ee.jar;%WAS_HOME%/lib/lmproxy.jar;%CFMX_APPS_PATH%

4 Save the file 5 Add the full path to the cf_root\WEB-INF\cfusion\lib directory to the WAS_PATH variable in

the setupCmdLine.bat file. The WAS_PATH line should look similar to the following:

SET WAS_PATH=WAS_HOME%\bin;%JAVA_HOME%\bin;%JAVA_HOME%\jre\bin;%PATH%;

C:\Program Files\IBM\WebSphere MQ\bin;C:\Program Files\IBM\ WebSphere MQ\java\bin;C:/Program Files/IBM/WebSphere MQ/WEMPS\bin; %WAS_HOME%\installedApps\%WAS_NODE%\Macromedia ColdFusion MX.ear\ cfusion.war\WEB-INF\cfusion\lib

6 Save the file and restart your WebSphere Application Server.

You can now use Verity in ColdFusion MX.

24 Chapter 2: Installing on WebSphere V5

To configure operating system-specific binary support on Solaris and Linux:

1 Make a backup copy of the startServer.sh file, located in the websphere_root/AppServer/bin

directory.

2 Open the original file for editing, and in the PLATFORM case block, just above the

LD_LIBRARY_PATH line, add the following entry on a single, long line:

Note: The path specifications in these instructions assume you deployed ColdFusion using the standard application name (Macromedia ColdFusion MX) and did not rename the application.

On Solaris:

CFMX_APPS_PATH=cf_root/WEB-INF/cfusion/lib:cf_root/WEB-INF/cfusion/ lib/_solaris/bin

Replace cf_root with the path to your cf_root directory; for example, enter the following:

CFMX_APPS_PATH="$WAS_HOME"/installedApps/"$WAS_NODE"/

Macromedia ColdFusion MX.ear/cfusion.war/WEB-INF/cfusion/lib: "$WAS_HOME"/installedApps/"$WAS_NODE"/Macromedia ColdFusion MX.ear/ cfusion.war/WEB-INF/cfusion/lib/_solaris/bin

On Linux:

CFMX_APPS_PATH=cf_root/WEB-INF/cfusion/lib:cf_root/WEB-INF/cfusion/ lib/_ilnx21/bin

Replace cf_root with the path to your cf_root directory; for example, enter the following:

CFMX_APPS_PATH="$WAS_HOME"/installedApps/"$WAS_NODE"/

Macromedia ColdFusion MX.ear/cfusion.war/WEB-INF/cfusion/lib: "$WAS_HOME"/installedApps/"$WAS_NODE"/Macromedia ColdFusion MX.ear/ cfusion.war/WEB-INF/cfusion/lib/_ilnx21/bin

3 Append the CFMX_APPS_PATH environment variable to the LD_LIBRARY_PATH entry.

The resulting line should be similar to the following:

LD_LIBRARY_PATH="$WAS_LIBPATH":$LD_LIBRARY_PATH:$CFMX_APPS_PATH

4 Save the file and restart your WebSphere Application Server.

You can now use Verity in ColdFusion MX.

Enabling access to COM objects (Windows only)

This section describes how to enable Component Object Model (COM) support in Windows after installing ColdFusion MX.

To enable COM support:

1 In the WebSphere Administrative Console, open the Node Name > Application Servers panel,

select the application server for your ColdFusion MX application, and select the Process Definition link in the Additional Properties box of the Configuration tab. Select the Java Virtual Machine link in the Process Definition Additional Properties panel and add the following line to the Generic JVM Arguments entry:

-DJINTEGRA_NATIVE_MODE -DJINTEGRA_PREFETCH_ENUMS

2 Save your configuration file. 3 Make a backup copy of the setupCmdLine.bat file, located in the websphere_root\AppServer\bin

directory.

4 Open the original file for editing and add the following on a single, long line:

SET PATH=%PATH%;cf_root\WEB-INF\cfusion\jintegra\bin;cf_root\WEB-INF\ cfusion\jintegra\bin\international

Enabling and configuring specific ColdFusion MX functionality 25

Replace cf_root with the path to your cf_root directory; for example, enter the following:

SET PATH=%PATH%;%WAS_HOME%\installedApps\%WAS_NODE%\Macromedia ColdFusion MX.ear\cfusion.war\WEB-INF\cfusion\jintegra\bin;%WAS_HOME%\installedApps\ %WAS_NODE%\Macromedia ColdFusion MX.ear\cfusion.war\WEB-INF\cfusion\ jintegra\bin\international

5 Save the file and restart your computer.

In some cases, you might also have to do the following to register the Microsoft Type viewer:

1 Open a console window and go to cf_root\WEB-INF\cfusion\lib. 2 Register TypeViewer.dll by issuing the following command:

regsvr32 TypeViewer.dll

Enabling charting and graphing (UNIX)

This section describes how to configure your application server to use ColdFusion MX charting and graphing (

cfchart, cfchartdata, and cfchartseries tags) on AIX, Linux, and Solaris

systems. This step is not required to enable charting and graphing in Windows.

To enable charting and graphing:

1 Open the WebSphere Administrative Console. 2 In the left navigation bar, select Node_name > Servers > Application Servers. 3 Select your J2EE application server; for example, Server1. 4 On the Configuration tab of the Application server page, click the Process Definition link in

the Additional Properties box.

5 On the Process Definition page, click the Java Virtual Machine link in the Additional Properties

box.

6 In the Additional Properties box at the bottom of the page, click the Custom Properties link. 7 On the Custom Properties page, click New and add a system property, completing the fields as

follows:

■ Name java.awt.graphicsenv

■ Value com.gp.java2d.ExGraphicsEnvironment

8 Click OK to return to the Java Virtual Machine page. 9 In the General Properties box of the Java Virtual Machine page, type the following in the Boot

Classpath field: cf_root/WEB-INF/cfusion/lib/webchartsJava2D.jar

10 Click OK.

Disabling RDS

For security reasons, Macromedia recommends that you disable RDS on a production server. If you install and enable RDS support, you can disable it later.

Note: If you disable RDS, the Browse Server button does not work in the ColdFusion MX Administrator (for example, on the ColdFusion Mappings page).

26 Chapter 2: Installing on WebSphere V5

To disable RDS, you must do the following:

• Disable the ColdFusion MX web module RDS Servlet. Doing so ensures that ColdFusion MX

cannot respond to any RDS requests.

• If your ColdFusion MX application context root is not /, disable or undeploy the RDS

redirector web module. (For a description of the module, see “Using RDS” on page 50.)

Disabling the RDS Servlet

To disable the RDS Servlet:

1 Back up the ColdFusion web module web.xml file.

By default, this file is in the cf_root\WEB-INF directory in Windows, and the cf_root/WEB- INF directory on UNIX.

2 Open the original web.xml file for editing. 3 Comment out the RDS Servlet definition, as follows:

<!-<servlet id="macromedia_servlet_8789">

<servlet-name>RDSServlet</servlet-name> <display-name>Apache-Axis Servlet</display-name> <servlet-class>coldfusion.bootstrap.BootstrapServlet</servlet-class> <init-param id="InitParam_103401311065856789">

<param-name>servlet.class</param-name> <param-value>coldfusion.rds.RdsFrontEndServlet</param-value>

</init-param>

</servlet>

-->

Note: Some of the text in the servlet definition might vary.

4 Comment out the RDS Servlet mapping, as the following example shows:

<!-<servlet-mapping id="macromedia_mapping_5">> <servlet-name>RDSServlet</servlet-name> <url-pattern>/CFIDE/main/ide.cfm</url-pattern> </servlet-mapping>

-->

Note: The servlet-mapping id value might vary.

5 Save the file.

RDS is disabled on the ColdFusion MX server.

Disabling the RDS redirector

Use the following procedure to disable the RDS redirector web module.

To disable the RDS web module:

1 In the WebSphere Administrative Console, select Node_name > Applications > Enterprise

Applications.

2 Stop the Macromedia ColdFusion MX application if it is running. 3 Click the Macromedia ColdFusion MX Application link to display the Configuration page,

then select the Local Topologies tab.

Enabling and configuring specific ColdFusion MX functionality 27

4 Expand the Macromedia_ColdFusion_MX entry in the Applications tree, then expand the Web

Module folder and click the rds.war link to display the rds.war configuration page.

5 Click the Target Mappings link in the Additional Properties box, and click the link to your

application server, for example, Server1.

6 On the Configuration page General Properties box, clear the Enabled check box and click OK. 7 Click the Save to Master Configuration link at the top of the Target Mappings page and click

the Save button on the Save page to save your workspace.

8 When the configuration has been saved and the main Administrative Console page appears,

stop and restart the application server.

9 Start the ColdFusion Application, if necessary.

The RDS web module is disabled. You can reenable the RDS web module by repeating this procedure and selecting the Enabled check box.

Undeploying ColdFusion MX

This section describes how to undeploy ColdFusion MX from IBM WebSphere Application Server.

To undeploy ColdFusion MX:

1 (Windows only) If the ODBC services are installed, open the Services panel and ensure that the

ColdFusion MX ODBC server and the ColdFusion MX ODBC agent are stopped.

2 Open the WebSphere Administrative Console. 3 Open the Node_name > Applications > Enterprise Applications page. If the ColdFusion

application status is Started, select the check box next to the Macromedia ColdFusion MX entry and click Stop.

4 When the ColdFusion application server has stopped, select the check box next to the

Macromedia ColdFusion MX entry again and click Uninstall.

5 WebSphere uninstalls the ColdFusion application. Save the new configuration by clicking the

save link in the messages box. The Save panel appears. Click Save.

6 Stop the WebSphere Application Server. 7 If WebSphere did not delete the cf_root directory, delete it. You might have to restart your

computer before you can delete the files.

28 Chapter 2: Installing on WebSphere V5

CHAPTER 3

Installing on

Before you can use ColdFusion MX on IBM WebSphere Application Server V4, you must do the following steps:

engine.

This chapter describes these steps in detail. It also describes how to undeploy ColdFusion MX.

Note: Check the Macromedia website at www.macromedia.com/go/cfmxj2ee-cert for any updates to these installation instructions, or other late-breaking information.

This chapter uses the following conventions:

WebSphere V4

• websphere_root refers to the directory in which IBM WebSphere Application Server is installed;

for example, C:\WebSphere in Windows, and /opt/WebSphere on UNIX.

• cf_root refers to the directory to which ColdFusion is deployed; for example,

C:\WebSphere\AppServer\installedApps\cfusion.ear\cfusion.war in Windows, and /opt/ WebSphere/AppServer/installedApps/cfusion.ear/cfusion.war on UNIX.

Contents

Installing and deploying Macromedia ColdFusion MX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30

Enabling and configuring specific ColdFusion MX functionality. . . . . . . . . . . . . . . . . . . . . . . 36

Undeploying ColdFusion MX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41

Installing and deploying Macromedia ColdFusion MX

Before you can run ColdFusion applications, you must complete the following procedures to install and deploy ColdFusion MX to your application server:

1 Installing the ColdFusion MX files 2 Deploying ColdFusion MX on WebSphere 3 Running the Configuration and Settings Migration Wizard

Installing the ColdFusion MX files

Operating system Installation file

Full Product

Windows coldfusion-61-ibm-win.exe

Linux coldfusion-61-ibm-linux.bin

Solaris coldfusion-61-ibm-solaris.bin

AIX coldfusion-61-ibm-other.jar

Evaluation only

Windows coldfusion-61-ibm-eval-win.exe

Linux coldfusion-61-ibm-eval-linux.bin

Solaris coldfusion-61-ibm-eval-solaris.bin

AIX coldfusion-61-ibm-eval-other.jar

Use the following procedure to install the ColdFusion MX EAR file and installation documentation.

To install ColdFusion MX files:

1 Ensure that your system environment meets the system requirements described in Chapter 1,

“Essential Information,” on page 7.

2 Review the section “Installing ColdFusion MX for IBM WebSphere Application Server”

on page 15.

3 Read the Release Notes for any late-breaking information or updates.

30 Chapter 3: Installing on WebSphere V4

4 Close any applications that are currently running on the computer to which you are deploying

ColdFusion MX.

5 If you have the ColdFusion MX for IBM WebSphere Application Server evaluation or product

CD-ROM, insert the CD. Otherwise, download the installer file for your platform from the IBM website or a designated network.

6 Start the installation program. Do one of the following, depending on your operating system:

System Procedure

AIX Set the working directory to the directory that contains the JAR file

listed in the preceding table. Enter one of the following commands, replacing java_home with the path to the bin directory for your JRE installation:

In GUI mode (you must have XWindows Display configured): java_home/java -jar coldfusion-61-ibm-other.jar -i gui

or, for the evaluation version: java_home/java -jar coldfusion-61-ibm-eval-other.jar -i gui

In console mode: java_home/java -jar coldfusion-61-ibm-other.jar -i console

or, for the evaluation version: java_home/java -jar coldfusion-61-ibm-eval-other.jar -i console

Windows Double-click the installer file.

Solaris or Linux Set the working directory to the directory that contains the installer file

listed in the preceding table. In GUI mode (you must have XWindows Display configured), enter the

installer file for your operating system, followed by the -i gui switch; for example:

./coldfusion-61-ibm-linux.bin -i gui

In console mode, enter the installer file for your operating system, followed by the -i console switch; for example:

./coldfusion-61-ibm-linux.bin -i console

7 Follow the instructions in the installation program. Use the following information to complete

certain sections of the installation program:

■ Before installing, determine the location of a working directory into which the ColdFusion

MX for J2EE EAR file should be installed.

■ The initial installer screen lets you select the language for the installer. This selection also

determines the language for the online Help and installed documentation.

■ On the License Agreement page, you must select I accept the terms of the License

Agreement before you can click Next.

■ On the Install Type page, select whether you are updating a ColdFusion MX installation to

Installing and deploying Macromedia ColdFusion MX 31

■ ColdFusion asks you for the directory in which to install the files. These files are required to

deploy ColdFusion on WebSphere, but are not required afterwards. Therefore, you can specify a staging area or temporary file location.

■ If you specify an update installation, the installer asks you to select the directory in which to

■ On the Context Root page, specify a name for the ColdFusion MX application context

on page 48.

■ In the ColdFusion MX Administrator password page, enter the password to require for the

ColdFusion MX Administrator.

■ Review the options in the Pre-Installation Summary section and accept them to complete

the installation.

When the installation is complete, the EAR file and any backup files are put in the specified locations. The installation wizard exits, and a product registration page appears. Continue with the next section of the instructions, “Deploying ColdFusion MX on WebSphere”.

Deploying ColdFusion MX on WebSphere

This section describes how to deploy ColdFusion MX on WebSphere 4.

Installing ColdFusion MX on Single Server Edition

Use the following procedure to deploy ColdFusion MX on WebSphere 4 Advanced Edition Single Server.

To deploy on WebSphere 4 Advanced Edition Single Server:

1 Start the IBM WebSphere Application Server, if it is not running. 2 Open the Run the IBM WebSphere Administrative console, if it is not running. 3 If you are updating an existing ColdFusion MX application, you must uninstall the existing

copy of ColdFusion. Do the following:

a In Windows, if the ODBC services are installed, open the Services panel and make sure that

the ColdFusion MX ODBC server and the ColdFusion MX ODBC agent are stopped.

32 Chapter 3: Installing on WebSphere V4

b On the WebSphere Administrative Console Nodes > node_name > Enterprise Applications

page, select the ColdFusion application (the default name is Macromedia ColdFusion MX). If the application is running, click stop; when it has stopped, select it again. Click Uninstall.

c WebSphere might display the warning “The operation did not complete in the expected

amount of time. It may have completed successfully. Check the logs for details”. This message indicates that uninstalling the application is taking some time; it does not necessarily indicate a problem. You can check the J2EE server logs (for example, C:\Program Files\WebSphere\AppServer\logs\server1\SystemOut.log) for any errors before proceeding.

d In the Messages box at the top of the Administrative Console page, click the Save link to

apply changes to the master configuration. Then click the Save button on the Save page to save your workspace. This might take some time.

e Stop the WebSphere Application Server. f Delete the cf_root directory. g Restart the WebSphere Application Server.

4 Open the Nodes > node_name > Enterprise Applications page and click Install. 5 The Application Installation Wizard page appears. In the first Path box, enter the path to the

EAR file that you installed in the Installing the ColdFusion MX files procedure; for example, C:\CFMXJ2ee\cfusion.ear. Leave the Application Name and Context Root fields empty. Click Next.

6 Select the virtual host or hosts in which to install the ColdFusion application and Remote

Development Services (RDS) support. Click Next.

7 Review the installation summary; if it is correct, click Finish. 8 Save the configuration and regenerate the Plug-in configuration. 9 On AIX systems, if you are using the standard WebSphere JVM, Version 1.3.1, or any version

other than 1.4.2, make sure the ColdFusion application is not running, and replace cf_root/ WEB-INF/cfusion/lib/tools.jar with the tools.jar from your JVM (normally websphere_root\AppServer\java\lib\tools.jar).

10 Open the Enterprise Applications panel and make sure that the ColdFusion application is

stopped. Add the following lines to the JVM's security policy file, java.policy (for example, C:\WebSphere\AppServer\java\jre\lib\security\java.policy):

grant codeBase "<file:cf_root/WEB-INF/cfusion/lib/*>" { permission java.security.AllPermission; }; grant codeBase "<file:cf_root/WEB-INF/lib/*>" { permission java.security.AllPermission; };

Replace cf_root with your cf_root directory; for example, C:\WebSphere\AppServer\ installedApps\MyHost\cfusion.ear\cfusion.war.

11 If you are updating an existing ColdFusion MX application, when the workspace is saved, do

the following:

a Open the Enterprise Applications panel and make sure that the ColdFusion application is

stopped.

b Copy the files in the backup directory that you specified in step 5b back to your cf_root

directory (for example, C:\WebSphere\AppServer\installedApps\MyHost\cfusion.ear\ cfusion.war). Ensure that the files from the backup directory tree overwrite any files with the same names in the cf_root directory tree.

Installing and deploying Macromedia ColdFusion MX 33

12 Start the ColdFusion Application in the Enterprise Applications panel. Select the box next to

Macromedia ColdFusion MX, and click Start.

13 Continue with the next section of the instructions, “Running the Configuration and Settings

Migration Wizard”.

Installing ColdFusion MX on Advanced Edition

Use the following procedure to deploy ColdFusion MX on WebSphere 4 Advanced Edition.

To deploy on WebSphere 4 Advanced Edition:

copy of ColdFusion. Do the following:

a In Windows, if the ODBC services are installed, open the Services panel and make sure that

the ColdFusion MX ODBC server and the ColdFusion MX ODBC agent are stopped.

b On the WebSphere Administrative Console Applications > Enterprise Applications page

select the ColdFusion application (the default name is Macromedia ColdFusion MX). If the application is running, click stop; when it has stopped, select it again. Click Uninstall.

c WebSphere might display the warning “The operation did not complete in the expected

d In the Messages box at the top of the Administrative Console page, click the Save link to

apply changes to the master configuration. Then click the Save button on the Save page to save your workspace. This might take some time.

e In many cases, WebSphere cannot delete all files. Make sure that the cf_root directory has

been deleted. If any files remain, stop the application server, delete the cf_root, and restart the server.

4 Select Enterprise Applications > Install Enterprise Application. 5 In the first page of the Install Enterprise Application Wizard, specify the node, path to the

ColdFusion MX EAR file that you installed in the Installing the ColdFusion MX files procedure, and the application name (for example, cfusion). Click Next.

6 Click Next to skip the next seven screens of the wizard. 7 On the Selecting Virtual Hosts for Web Modules page, select the virtual host or hosts for

ColdFusion MX and RDS. Click Next.

8 On the Selecting Application Servers page, select the application servers for ColdFusion MX

and RDS. Click Next.

9 On the Completing the Application Installation Wizard page, click Finish. 10 Do the following:

a Open the Enterprise Applications panel and make sure that the ColdFusion application is

stopped.

34 Chapter 3: Installing on WebSphere V4

b Add the following lines to the JVM’s security policy file, java.policy (for example,

C:\Program Files\WebSphere\AppServer\java\jre\lib\security\java.policy):

grant codeBase "<file:cf_root/WEB-INF/cfusion/lib/*>" { permission java.security.AllPermission; }; grant codeBase "<file:cf_root/WEB-INF/lib/*>" { permission java.security.AllPermission; };

Replace cf_root with your cf_root directory; for example, C:\WebSphere\AppServer\ installedApps\MyHost\cfusion.ear\cfusion.war.

11 On AIX systems, if you are using the standard WebSphere JVM, Version 1.3.1, or any version

12 If you are updating an existing ColdFusion MX application, when the workspace is saved, do

the following:

a Expand the Enterprise Applications tree and make sure that the ColdFusion application is

stopped.

b Copy the files in the backup directory that you specified in the Installing the ColdFusion

MX files procedure back to your cf_root directory (for example,

C:\WebSphere\AppServer\installedApps\MyHost\cfusion.ear\cfusion.war). Ensure that the files from the backup directory tree overwrite any files with the same names in the cf_root directory tree.

13 Select the application name you specified from the Enterprise Applications list and click the

Start button on the toolbar to Start the ColdFusion MX application.

14 Continue with the next section of the instructions, “Running the Configuration and Settings

Migration Wizard”.

Running the Configuration and Settings Migration Wizard

http://host:[port]/cf_context_root/CFIDE/administrator

for example:

http://localhost:9080/cfmx/CFIDE/administrator

For more information on specifying the Administrator URL, see “Accessing the ColdFusion MX

Administrator” on page 49.

When you first access the Administrator, ColdFusion runs the Configuration and Settings Migration Wizard.

Note: When you upgrade a ColdFusion MX installation, the wizard might skip some of the following steps.

Installing and deploying Macromedia ColdFusion MX 35

The wizard includes the following steps:

• Enter the ColdFusion MX Administrator password you specified when you installed

ColdFusion MX files.

• Specify whether to configure RDS support, and if you configure RDS support, the RDS

password. To maximize security, do not install RDS on production servers. For more information on RDS, see “Using RDS” on page 50.

• (Windows only) Specify whether to install the ODBC services, which let ColdFusion MX

access ODBC data sources.

• Specify whether to install example applications and supporting files (including data sources)

for the ColdFusion MX Getting Started tutorial. For security reasons, Macromedia recommends that you do not install example applications on production servers.

• The System Configuration page might tell you that you must do additional configuration steps

to enable full ColdFusion MX functionality. You do not need to make these changes when you run the wizard; click Next. See “Enabling and configuring specific ColdFusion MX

functionality” on page 36 for information on the additional configuration steps you must take

to enable all available ColdFusion MX features.

functionality” section before complete ColdFusion MX functionality is available.

Enabling and configuring specific ColdFusion MX functionality

For some ColdFusion MX functionality to work properly, you must manually configure your application server.

This section provides instructions for procedures that are specific to WebSphere 4. It describes what to do for the following functionality:

• Enabling features with operating system-specific binaries

• Enabling sandbox security (AIX)

• Enabling access to COM objects (Windows)

• Enabling charting and graphing (Unix)

• Supporting messages from a POP mail server (pre-FixPak 4)

• Disabling RDS after installation

The following procedures are identical for WebSphere 4 and WebSphere 5, and are documented in Chapter 4, “Enabling and Using ColdFusion MX Features,” on page 43:

• Installing Verity Search Packs for ColdFusion MX

• Enabling CORBA support

• Using a third-party JDBC database driver

36 Chapter 3: Installing on WebSphere V4

Enabling features with operating system-specific binaries

This step is required to support the following features that use binaries that are specific to your operating system:

• Verity search engine and the cfcollection, cfindex, and cfsearch tags

• CFX tags written in C++

• The cfreport tag

• Microsoft Access driver with Unicode support (Windows only)

These features work on Windows, Linux, and Solaris only.

Note: To do searches in languages other than English, including both European and Asian languages, you must also install language-specific Verity Search Packs. For more information, see

“Installing Verity Search Packs for ColdFusion MX” on page 44.

To configure operating system-specific binary support in Windows:

1 Make a backup copy of the setupCmdLine.bat file, located in the websphere_root\AppServer\bin

directory.

2 Open the original file for editing and add the following on a single, long line before the line that

starts with SET WAS_CLASSPATH:

SET CFMX_APPS_PATH=cf_root\WEB-INF\cfusion\lib;cf_root\WEB-INF\cfusion\ lib\_nti40\bin

Replace cf_root with the path to your cf_root directory; for example, enter the following:

SET CFMX_APPS_PATH=%WAS_HOME%\installedApps\cfusion.ear\cfusion.war\

WEB-INF\cfusion\lib;%WAS_HOME%\installedApps\cfusion.ear\cfusion.war\ WEB-INF\cfusion\lib\_nti40\bin

3 Add the CFMX_APPS_PATH variable to the WAS_CLASSPATH by appending the following

text to the path statement:

;%CFMX_APPS_PATH%

The WAS_CLASSPATH line should look similar to the following:

SET WAS_CLASSPATH=%WAS_HOME%/properties;%WAS_HOME%/lib/bootstrap.jar;

%WAS_HOME%/lib/j2ee.jar;%WAS_HOME%/lib/lmproxy.jar;%CFMX_APPS_PATH%

4 Save the file and restart your computer.

You can now use Verity in ColdFusion MX.

To configure operating system-specific binary support on Solaris and Linux:

1 Make a backup copy of the setupCmdLine.sh file, located in the websphere_root/AppServer/bin

directory.

2 Open the original file for editing, and add the following entry on a single, long line:

On Linux:

CFMX_APPS_PATH=cf_root/WEB-INF/cfusion/lib:cf_root/WEB-INF/cfusion/ lib/_ilnx21/bin

Enabling and configuring specific ColdFusion MX functionality 37

Replace cf_root with the path to your cf_root directory; for example, enter the following:

CFMX_APPS_PATH=/opt/WebSphere/AppServer/installedApps/cfusion.ear/

cfusion.war/WEB-INF/cfusion/lib:/opt/WebSphere/AppServer/installedApps/ cfusion.ear/cfusion.war/WEB-INF/cfusion/lib/_ilnx21/bin

On Solaris:

CFMX_APPS_PATH=cf_root/WEB-INF/cfusion/lib:cf_root/WEB-INF/cfusion/ lib/_solaris/bin

Replace cf_root with the path to your cf_root directory; for example, enter the following:

CFMX_APPS_PATH=/opt/WebSphere/AppServer/installedApps/cfusion.ear/

cfusion.war/WEB-INF/cfusion/lib:/opt/WebSphere/AppServer/installedApps/ cfusion.ear/cfusion.war/WEB-INF/cfusion/lib/_solaris/bin

3 Append the CFMX_APPS_PATH environment variable to the LD_LIBRARY_PATH entry.

The resulting line should be similar to the following:

LD_LIBRARY_PATH=$LD_LIBRARY_PATH:$CFMX_APPS_PATH

4 Make sure that LD_LIBRARY_PATH is exported (export LD_LIBRARY_PATH). 5 Save the file and restart WebSphere.

You can now use Verity in ColdFusion MX.

Enabling sandbox security (AIX)

To enable sandbox security in AIX, you must grant everyone full security permissions for accessing class files. To grant full permissions, ensure that you have a websphere_root/AppServer/ properties/java.policy file with the following contents:

// PERMISSIONS GRANTED TO EVERYONE grant {

permission java.security.AllPermission; };

Note: Sandbox security cannot restrict Java access to files and network resources on WebSphere 4.

Enabling access to COM objects (Windows)

This section explains how to enable Component Object Model (COM) support in Windows after installing ColdFusion MX.

To enable COM support:

1 In the WebSphere Administrative Console, add the following line to your JVM arguments. In

Advanced Edition Single Server, add the text to the Generic Command Line Arguments entry of the Nodes > Node Name > Application Servers > Default Server > Process Definition > JVM Settings panel. In Advanced Edition, add it to the Command Line Arguments entry of the Advanced JVM dialog, accessed from the JVM Settings tab of the Nodes > Node Name > Application Servers > Application Server Name panel.

-DJINTEGRA_NATIVE_MODE -DJINTEGRA_PREFETCH_ENUMS

2 Make a backup copy of the setupCmdLine.bat file, located in the websphere_root\AppServer\bin

directory.

3 Open the original file for editing and add the following on a single, long line:

SET PATH=%PATH%;cf_root\WEB-INF\cfusion\jintegra\bin;cf_root\WEB-

INF\cfusion\ jintegra\bin\international

38 Chapter 3: Installing on WebSphere V4

Replace cf_root with the path to your cf_root directory; for example, enter the following:

SET PATH=%PATH%;%WAS_HOME%\installedApps\cfusion.ear\cfusion.war\WEB-INF\ cfusion\jintegra\bin;%WAS_HOME%\installedApps\cfusion.ear\cfusion.war\ WEB-INF\cfusion\jintegra\bin\international

4 Save the file and restart your computer.

Enabling charting and graphing (Unix)

This section describes how to configure your application server to use ColdFusion MX charting and graphing (

cfchart, cfchartdata, and cfchartseries tags) on Unix. You do not have to

perform these steps to enable charting and graphing in Windows.

Note: Do not perform these steps if you are using JDK 1.4.1 on UNIX. You cannot use cfchart on UNIX with JDK 1.4.1.

Advanced Edition Single Server

This section explains how to enable charting and graphing in ColdFusion MX for IBM WebSphere Application Server Advanced Edition Single Server.

To enable charting and graphing:

1 Open the WebSphere Administrative Console. 2 In the left navigation bar, select Nodes > computer_name > Application Servers > Default

Server > Process Definition > JVM Settings.

3 On the JVM Settings page, type the following in the Boot Classpath field:

On Windows, Linux, and Solaris: cf_root/WEB-INF/lib/webchartsJava2D.jar

On AIX: cf_root/WEB-INF/cfusion/lib/webchartsJava2D.jar

4 Under Advanced Settings at the bottom of the page, click System Properties. 5 On the System Properties page, click New and add a system property, completing the fields as

follows:

6 Name java.awt.graphicsenv 7 Value com.gp.java2d.ExGraphicsEnvironment 8 Click OK. 9 Click OK on the System Properties page and then on the JVM Settings page.

Advanced Edition

This section explains how to enable charting and graphing in ColdFusion MX for IBM WebSphere Application Server Advanced Edition.

To enable charting and graphing:

1 Open the WebSphere Administrative Console. 2 In the left navigation bar, select Nodes > computer_name > server_name for the server to which

ColdFusion MX was deployed.

Enabling and configuring specific ColdFusion MX functionality 39

3 On the JVM Settings tab, add the following system properties:

Name java.awt.graphicsenv Value com.gp.java2d.ExGraphicsEnvironment

4 Click Advanced JVM Settings. 5 In the Boot Classpath (Append) field, type the following:

cf_root/WEB-INF/lib/webchartsJava2D.jar

6 Click OK on the Advanced JVM Settings page. 7 Click OK.

You can now use ColdFusion MX charting and graphing without any errors.

Supporting messages from a POP mail server (pre-FixPak 4)

WebSphere 4 prior to Fixpack 4 uses JavaMail 1.1, and the

cfpop tag does not work with this

version. To remedy this, install IBM WebSphere 4 Fixpack 4.

Disabling RDS after installation

For security reasons, Macromedia recommends that you disable RDS on a production server. If you install and enable RDS support, you can disable it later.

Note: If you disable RDS, the Browse Server button does not work in the ColdFusion MX Administrator (for example, on the ColdFusion Mappings page).

To disable RDS, you must do the following:

• Disable the ColdFusion MX web module RDS Servlet. Doing so ensures that ColdFusion MX

cannot respond to any RDS requests.

• If your ColdFusion MX application context root is not /, disable or undeploy the RDS

redirector web module. (For a description of the module, see “Using RDS” on page 50.)

Disabling the RDS Servlet

To disable the RDS Servlet:

1 Back up the ColdFusion web module web.xml file.

By default, this file is in the cf_root\WEB-INF directory in Windows, and the cf_root/WEB- INF directory on UNIX.

2 Open the original web.xml file for editing. 3 Comment out the RDS Servlet definition, as follows:

<!-<servlet id="macromedia_servlet_8789">

<param-name>servlet.class</param-name> <param-value>coldfusion.rds.RdsFrontEndServlet</param-value>

</init-param>

</servlet>

-->

Note: Some of the text in the servlet definition might vary.

40 Chapter 3: Installing on WebSphere V4

4 Comment out the RDS Servlet mapping, as the following example shows:

<!-<servlet-mapping id="macromedia_mapping_5">> <servlet-name>RDSServlet</servlet-name> <url-pattern>/CFIDE/main/ide.cfm</url-pattern> </servlet-mapping>

-->

Note: The servlet-mapping id value might vary.

5 Save the file.

RDS is disabled on the ColdFusion MX server.

Disabling the RDS Redirector

To disable the RDS redirector web module, undeploy or disable the CFMX RDS Application web module.

Undeploying ColdFusion MX

This section describes how to undeploy ColdFusion MX from IBM WebSphere Application Server.

To undeploy ColdFusion MX on Advanced Edition Single Server:

1 (Windows only) If the ODBC services are installed, open the Services panel and make sure that

the ColdFusion MX ODBC server and the ColdFusion MX ODBC agent are stopped.

2 Open the WebSphere Administrative Console. 3 Open the Node_name > Applications > Enterprise Applications page. If the ColdFusion

application status is Started, select the check box next to the Macromedia ColdFusion MX entry and click Stop.

4 When the ColdFusion application server has stopped, select the check box next to the

Macromedia ColdFusion MX entry again and click Uninstall. WebSphere uninstalls the ColdFusion application.

5 Save the new configuration by clicking the save link in the messages box. The Save panel

appears. Click Save.

6 Stop the WebSphere Application Server. 7 If WebSphere did not delete the cf_root directory, delete it. You might have to restart your

computer before you can delete the files.

To undeploy ColdFusion MX on Advanced Edition:

1 (Windows only) If the ODBC services are installed, open the Services panel and make sure that

the ColdFusion MX ODBC server and the ColdFusion MX ODBC agent are stopped.

2 Open the WebSphere Administrative Console. 3 Expand the Enterprise Applications tree. 4 Right-click on the ColdFusion MX entry and select Stop. 5 When the ColdFusion application server has stopped, right-click on the ColdFusion MX entry

and select Remove.

6 If WebSphere did not delete the cf_root directory, delete it. You might have to restart your

computer before you can delete the files.

Undeploying ColdFusion MX 41

42 Chapter 3: Installing on WebSphere V4

CHAPTER 4

Enabling and Using ColdFusion MX Features

This chapter describes how to build ColdFusion applications that run on your J2EE server.

This chapter uses the following conventions:

• websphere_root refers to the directory in which IBM WebSphere Application Server is installed;

for example, C:\Program Files\WebSphere in Windows, and /opt/WebSphere on UNIX.

• cf_root refers to the directory to which ColdFusion is deployed; for example,

C:\WebSphere\AppServer\installedApps\My_system\Macromedia ColdFusion MX.ear\cfusion.war for WebSphere in Windows, and /opt/WebSphere/AppServer/ installedApps/My_system/Macromedia ColdFusion MX.ear/cfusion.war on UNIX.

Contents

Enabling ColdFusion MX functionality. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44

Managing ColdFusion MX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47

Using the / context root. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48

Accessing the ColdFusion MX Administrator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49

Migrating a ColdFusion application to IBM WebSphere Application Server . . . . . . . . . . . . . . 49

Using RDS. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50

Enabling ColdFusion MX functionality

The following sections describe procedures that enable the following ColdFusion features. These procedures work with WebSphere 4 and 5.

• Installing Verity Search Packs for ColdFusion MX

• Enabling CORBA support

• Enabling web services access for Flash Remoting

• Using a third-party JDBC database driver

Installing Verity Search Packs for ColdFusion MX

ColdFusion MX lets you do Verity searches for languages other than English. For European languages, ColdFusion uses LinguistX technology from Inxight, and for Asian languages, ColdFusion uses IBM Classes for Unicode (ICU) technology.

This section describes how to install a Verity Search Pack from the Macromedia website, and how to switch to a different Verity Search Pack.

Note: Verity is not supported on AIX.

To install a Verity Search Pack:

1 If you have not yet registered ColdFusion MX for J2EE, in your browser, go to the following

location on the Macromedia website: www.macromedia.com/go/verity Enter your serial number on the Verity Search Packs page and click Submit.

2 Download the appropriate Verity Search Pack (ZIP file for Windows, TAR file for UNIX), for

your operating system, and save it to the cf_root\WEB-INF\cfusion directory in Windows, and the cf_root/WEB-INF/cfusion directory on UNIX.

3 Stop IBM WebSphere Application Server. 4 Extract the ZIP or TAR file.

The files are automatically placed in the appropriate directories.

5 Restart IBM WebSphere Application Server. 6 To use a different Verity Search Pack (for example, for German), repeat this procedure for the

new Verity Search Pack.

Enabling CORBA support

ColdFusion MX supports third-party Object Request Brokers (ORBs) through its integration with Borland VisiBroker. However, you must acquire the Common Object Request Broker Architecture (CORBA) software separately from Borland.

This section describes the system requirements for enabling CORBA support, and explains how to deploy and configure VisiBroker to work with ColdFusion MX.

44 Chapter 4: Enabling and Using ColdFusion MX Features

System requirements

You must have all of the following components installed on your computer before you can make CORBA invocations from ColdFusion MX:

• Borland VisiBroker 4.5.1 for Java

• Java Runtime Environment (JRE) 1.2 or higher for the VisiBroker Interface Repository

Installing and configuring VisiBroker for CORBA connections

This section describes how to use VisiBroker for CORBA connections.

To install and configure VisiBroker for CORBA connections:

1 Install VisiBroker on the CORBA server side, if you have not already done so.

For more information, see the Borland VisiBroker documentation.

2 Copy the vbjorb.jar file to your JRE’s jre/lib/ext directory. 3 Configure a VisiBroker connector in ColdFusion MX, as follows:

a In the ColdFusion MX Administrator, select Extensions > CORBA Connectors. b On the CORBA Connectors page, click Register CORBA Connector. c On the CORBA Connector page, enter information for the connector.

The following are values for an example connector:

Field Value

ORB Name visibroker

ORB Class Name coldfusion.runtime.corba.VisibrokerConnector

Classpath (none)

ORB Property File cf_root\WEB-INF\cfusion\lib\vbjorb.properties

The ORB Property File points to a Java properties file that contains the correct ORB settings for VisiBroker.

The contents of the vbjorb.properties file look like the following:

org.omg.CORBA.ORBClass=com.inprise.vbroker.orb.ORB org.omg.CORBA.ORBSingletonClass=com.inprise.vbroker.orb.ORB SVCnameroot=namingroot

d When you finish editing the page, click Submit.

The CORBA Connectors page appears.

e Select the radio button to the left of your new CORBA connector, and click Select ORB

Connector. This sets the new connector as the default.

4 Prepare your CORBA server side, as follows:

a Start your VisiBroker osagent service or process, if it is not already running, by entering the

following command:

osagent

Enabling ColdFusion MX functionality 45

If you must connect to an osagent in another subnetwork, include the following lines in the vbjorb.properties file:

vbroker.agent.addr=<IP address of computer running OSAGENT> vbroker.agent.port=<port>

b Start the Interface Repository and load it with the IDL file that you plan to use, by entering

irep command, as in the following example:

irep myir MyIDLFile.idl

c If you plan to use the Naming Service, start it by entering a command as in the following

example:

nameserv namingroot

The name of the Naming Service (namingroot in the previous example) must match the value for

d Start VisiBroker on your CORBA server.

SVCnameroot in the vbjorb.properties file.

For more information, see the Borland VisiBroker documentation.

5 Restart ColdFusion MX for your changes to take effect.

For more information, see “Managing ColdFusion MX” on page 47.

You can make CORBA invocations from ColdFusion MX.

For more information about integrating CORBA objects into ColdFusion MX, see Developing ColdFusion MX Applications.

Enabling web services access for Flash Remoting

By default, Flash Remoting cannot access web services through ColdFusion MX 6.1.

To enable Flash Remoting to access web services through ColdFusion MX 6.1:

1 Open the cf_root/WEB-INF/web.xml file in a text editor. 2 Locate the servlet definition for FlashGateway and change the DISABLE_CFWS_ADAPTERS

init-param from true to false.

<servlet-name>FlashGateway</servlet-name>

...

<init-param>

<param-name>DISABLE_CFWS_ADAPTERS</param-name> <param-value>false</param-value> <description>When set to true, this setting disables the

ColdFusion WebServices Adapters in the gateway.</description>

</init-param>

</servlet>

3 Save the file.

Using a third-party JDBC database driver

ColdFusion MX includes JDBC Type 4 database drivers from Merant and MySQL, and JDBC Type 3 database drivers from Merant and SQL Link. (JDBC is an Application Programming Interface (API) for Java programs to access data.)

46 Chapter 4: Enabling and Using ColdFusion MX Features

Data sources that you configure in the WebSphere default JNDI location are also available in ColdFusion MX. The data sources appear in the ColdFusion MX Administrator Data Source page, and you can use them in your CFML code. You cannot use the ColdFusion MX Administrator to add or modify WebSphere data sources.

In the ColdFusion MX Administrator, you can also configure and use JDBC drivers that are not included with ColdFusion MX (such as SQLAnywhere or PostgreSQL). If you do this, you can add and manage data sources that use the driver directly in ColdFusion. Use the following procedure to configure a third-party driver and add a data source that uses it:

To use a third-party JDBC database driver:

1 Copy the JAR file for the database driver to a directory that is on your Java CLASSPATH. For

example, you might put the file in the cf_root\WEB-INF\lib directory in Windows, or the cf_root/WEB-INF/lib directory on UNIX.

2 In the ColdFusion MX Administrator, on the Data Sources page, add the JDBC data source by

selecting Other from the Driver drop-down list box. For more information, see the ColdFusion MX Administrator online Help.

You can now use the third-party JDBC database driver.

Managing ColdFusion MX

This section explains how to manage ColdFusion MX and the Windows services that are created when you deploy ColdFusion MX.

Managing the ColdFusion MX application

IBM WebSphere Application Server manages the ColdFusion MX web application. Therefore, to start, stop, or restart ColdFusion MX, start, stop, or restart the ColdFusion application in the WebSphere Administrator. For more information, see your WebSphere documentation. To manage most ColdFusion MX characteristics and resources, such as data sources and debugging settings, use the ColdFusion MX Administrator.

Note: If you enable or disable security in the ColdFusion MX Administrator, you must stop and restart the server for ColdFusion MX for your changes to take effect.

Managing ColdFusion MX Windows services

This section describes the Windows ODBC services that the ColdFusion MX Configuration and Migration Wizard installations.

Overview of services

The ColdFusion MX Startup Wizard creates the following services in Windows:

Service Purpose

ColdFusion MX ODBC agent The service used to configure data sources for the ColdFusion MX

ODBC server.

ColdFusion MX ODBC server The middle-tier service for ODBC connections that use the

ColdFusion MX DataDirect drivers for Microsoft Access and ODBC Socket.

Managing ColdFusion MX 47

Starting and stopping services

This section explains how to start or stop ColdFusion MX services.

To start or stop a ColdFusion MX service:

1 Open the Services dialog box:

■ In Windows NT 4.0, select Start > Settings > Control Panel > Services.

■ In Windows 2000, select Start > Settings > Control Panel > Administrative Tools >

Services.

If a service is running, its status appears as Started in the Status column. If it is not running, no status appears for the service.

2 Do one of the following:

■ Right-click a service and select Stop.

In Windows NT, click Yes to confirm that you want to stop the service.

■ Right-click a service and select Start.

■ Right-click a service and select Restart.

The Services window refreshes.

To set a ColdFusion MX service to start automatically or manually:

1 Open the Services dialog box:

■ In Windows NT 4.0, select Start > Settings > Control Panel > Services.

■ In Windows 2000, select Start > Settings > Control Panel > Administrative Tools >

Services.

2 Do one of the following:

■ In Windows NT, double-click the service to configure.

The dialog box for the service opens.

■ In Windows 2000, right-click the service that you want to configure and select Properties.

In the Properties dialog box, click the General tab.

3 Select one of the following options in the Startup Type frame or drop-down list box:

■ Automatic Starts the service automatically when you start the computer.

■ Manual Requires a user or dependent service to manually start the service.

4 Click OK.

Using the / context root

You can install ColdFusion MX for IBM WebSphere Application Server at the / context root or at another context root, such as /cfmx. If you do not use the / context root, users normally specify the context root as part of your application’s URLs; for example, http://www.myco.com/cfmx/ welcome.htm. If you install at the / context root, users do not have to include a context root in URLs.

48 Chapter 4: Enabling and Using ColdFusion MX Features

However, you cannot have multiple J2EE web applications at the / context root. Therefore, if there is already a web application at the / context root, you cannot also have ColdFusion MX there. For example, when you install WebSphere 4 Single Server, the Sample Application default_app.war web module is put at the / context root. You must remove this web module or change it to a specific context root, such as /default, before you install ColdFusion MX at the / context root.

Note: If you install ColdFusion MX at the / context root, you do not need the RDS redirector web module. For more information on the RDS redirector web module, see “Using RDS” on page 50.

Accessing the ColdFusion MX Administrator

This section explains how to access the ColdFusion MX Administrator in ColdFusion MX for IBM WebSphere Application Server.

To access the ColdFusion MX Administrator:

1 Start the server on which ColdFusion MX is running. 2 Open the ColdFusion MX Administrator in a web browser with the following URL:

http://host:[port]/cf_context_root/CFIDE/administrator

Variable Value

host The host name or IP address on which the web server is running. If your web

server is on the local machine, you can also specify localhost for this value.

port The port on which your web server runs. Varies depending on your web server

and WebSphere configuration, and might not be required. For example, the default WebSphere Application Server installation uses a web server at port

9080.

cf_context_root The context root specified when you installed the ColdFusion EAR files. The

default value is cfmx. This value is stored in the application.xml file in the \cfusion.ear\META-INF directory in Windows, and in the /cfusion.ear/METAINF directory on UNIX.

The following sample URL accesses the ColdFusion MX Administrator:

■ http://localhost:9080/cfmx/CFIDE/administrator/index.cfm

Note: The ColdFusion MX Administrator documentation describes features that are not available, or behave differently in ColdFusion MX for IBM WebSphere Application Server. For information on these differences, see “Differences in the ColdFusion MX Administrator” on page 14.

Migrating a ColdFusion application to IBM WebSphere Application Server

This section describes how to migrate an application that you developed for ColdFusion MX to run on IBM WebSphere Application Server.

To migrate a ColdFusion application to IBM WebSphere Application Server

1 If you are migrating an application that was developed for ColdFusion 5 or earlier, ensure that

it is compatible with ColdFusion MX. For more information, see Migrating ColdFusion Applications and the Migrating from

ColdFusion section of the Release Notes.

Migrating a ColdFusion application to IBM WebSphere Application Server 49

2 Ensure that the application is compatible with ColdFusion MX for IBM WebSphere

Application Server. For a description of differences between this edition and ColdFusion MX, see “Differences between ColdFusion MX and ColdFusion MX on WebSphere” on page 12.

3 Install ColdFusion MX for IBM WebSphere Application Server on a test server that has IBM

WebSphere Application Server installed.

4 Move the directory with the application under the cf_root directory on the test server. 5 Test the ColdFusion MX application on the test server. Using a source control system, make

any necessary changes to the application. Ensure that you test all application features under load, not just with a few users.

Tip: A number of testing applications are available for download from the web. For more information, see the Support section of the Macromedia website (http://www.macromedia.com/ support).

6 If you encounter problems that do not seem to be related to the code, ensure that you are using

comparable Administrator settings. For example, Java Virtual Machine (JVM) settings are handled by your application server, not ColdFusion MX. For more information, see

“Differences in the ColdFusion MX Administrator” on page 14.

Using RDS

If you use Macromedia Dreamweaver MX or HomeSite+ to develop your applications, Remote Development Services (RDS) lets you access a remote ColdFusion MX server using HTTP. Using RDS, IDE users can securely access remote files and data sources, build SQL queries from these data sources, and debug CFML code. However, to maximize security, do not install RDS on production servers.

Note: ColdFusion MX does not support using RDS if you install multiple instances of ColdFusion MX on a single web server.

About RDS configuration

In ColdFusion MX for IBM WebSphere Application Server, RDS support typically requires two web modules:

• The ColdFusion MX web module

• The RDS redirector web module, also called the RDS application.

The ColdFusion MX web module handles RDS requests in addition to all requests for ColdFusion pages.

If the ColdFusion MX context root is anything other than /, the redirector web module redirects RDS requests (which always go to the /CFIDE context root) to the ColdFusion MX module. The RDS redirector web module must have the context root /CFIDE and is normally installed in the same directory as cf_root.

Note: If you install ColdFusion MX at the / context root, you do not need the RDS redirector web module.

The instructions in the installation chapters describe how to install and disable RDS support. This section describes how to reconfigure RDS support if you change the ColdFusion MX application context root.

50 Chapter 4: Enabling and Using ColdFusion MX Features

Configuring RDS for a new ColdFusion MX context root

If you change the ColdFusion MX context root after you deploy ColdFusion, you must manually reconfigure the RDS redirector web module to specify the correct context root.

To configure the RDS redirector with the correct context root, you must change the rds.properties file, which is located in the root directory of the RDS web module. The RDS web module root directory is typically located in the same directory as the ColdFusion MX context root, cf_root. For example, in Windows, the RDS root directory might be C:\WebSphere\AppServer\installedApps\My_system\Macromedia ColdFusion MX.ear\rds.war.

The rds.properties file has one line, with the following format:

contextRoot=ColdFusion_context_root

for example,

contextRoot=cfmx

When you change the ColdFusion MX application context root, you must change this line to specify the new ColdFusion MX context root. For example, if you change the ColdFusion MX context root from cfmx to ColdFusionMX, change the line to:

contextRoot=ColdFusionMX

Using RDS 51

52 Chapter 4: Enabling and Using ColdFusion MX Features

MACROMEDIA ColdFusion MX User Manual

Specifications and Main Features

Frequently Asked Questions

User Manual