Macromedia Advanced ColdFusion Administration User Manual

Advanced

ColdFusion Administration

ColdFusion® 5

Macromedia® Incorporated

be used or copied only in accordance with the terms of such license. The content of this manual is furnished for info rmatio nal us e only , is su bject to cha nge with out noti ce, an d should not be construed as a commitment by Macromedia, Inc. Macromedia Inc. assumes no responsibility or liability for any errors or inaccuracies that may appear in this book.

Except as permitted by such license, no part of this publication may be reproduced, stored in a retrieval system, or transmitted in any form or by any means, electronic, mechanical, record ing, or otherwise , without the prior written permission of Macromedia Inc.

ColdFusion and HomeSite are U.S. registered trademarks of Macromedia Inc.macromedia inc.M ac rom edi a, the Mac r om ed ia log o, Macr om ed ia Spec tra , ColdFusion logo , a nd J Run are tr adema rks o f Ma crome dia, I nc . Java is a t radema rk of Sun Microsystems, Inc. Microsoft, Windows, Windows NT, Windows 95, Microsoft Access, and FoxPro are registered trademarks of Microsoft Corporation. PostScript is a trademark of Adobe Systems Inc. Solaris is a trademark of Sun Microsystems Inc. UNIX is a trademark of The Op en Grou p.All oth er comp any nam es, bra nd name s, and product names are trademarks of their respective holder(s).

Part number: ZCF50MADM

About This Book . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiii

Intended Audience . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiv

New Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .xiv

Developer Resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xv

About ColdFusion Documentation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xvi

Getting Answers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xvii

Contacting Macromedia . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xviii

Part I Data Sources and Tools. . . . . . . . . . . . . . . 1

Chapter 1 Advanced Data Source Management . . . . . . 3

Printed and online documentation set . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xvi

Viewing online documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xvii

About ColdFusion database drivers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4

About OLE DB . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4

About native drivers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

Using ColdFusion to Create a Data Source (UNIX only). . . . . . . . . . . . . . . . . . . . . 10

Using Connection String Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

About the connection string . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

Changes to the ColdFusion Administrator . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

Changes to CFML tags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

Connecting to DB2 Databases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

Configuring DB2 options (Windows) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

Configuring DB2 options (UNIX) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

Configuring system and services files (UNIX) . . . . . . . . . . . . . . . . . . . . . . . . 16

Installing and Configuring DB2 Client Enabler (UNIX) . . . . . . . . . . . . . . . . 16

Data source and start script settings for DB2 (UNIX) . . . . . . . . . . . . . . . . . . 18

DB2 binding and privileges for ODBC (UNIX) . . . . . . . . . . . . . . . . . . . . . . . . 19

Executing a DB2 stored procedure (Windows, UNIX) . . . . . . . . . . . . . . . . . 19

iv Contents

Connecting to dBASE/FoxPro Databases. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

Configuring dBASE/FoxPro options (Windows) . . . . . . . . . . . . . . . . . . . . . . 21

Configuring dBASE/FoxPro Driver options (UNIX) . . . . . . . . . . . . . . . . . . . 23

Connecting to Excel Databases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24

ODBC: Microsoft Excel Driver options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24

ODBC: MERANT Excel Workbook Driver options . . . . . . . . . . . . . . . . . . . . . 25

Connecting to Informix Databases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26

Configuring Informix using ODBC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26

Configuring Informix using the native driver . . . . . . . . . . . . . . . . . . . . . . . . . 27

Connecting to Informix data sources (UNIX) . . . . . . . . . . . . . . . . . . . . . . . . . 27

Connecting to Informix through ODBC/CLI (Windows, UNIX) . . . . . . . . . 29

Connecting to Sybase Databases. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32

ODBC: MERANT Sybase ASE Driver options . . . . . . . . . . . . . . . . . . . . . . . . . 32

Native: Sybase 11 Driver options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33

Tips for connecting to Sybase System 11 (UNIX) . . . . . . . . . . . . . . . . . . . . . 33

Connecting to Text Databases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35

ODBC: Microsoft Text Driver options (Windows) . . . . . . . . . . . . . . . . . . . . . 35

ODBC: MERANT Text Driver options (UNIX) . . . . . . . . . . . . . . . . . . . . . . . . 35

Connecting to Visual FoxPro Databases. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37

Chapter 2 Administrator Tools . . . . . . . . . . . . . . . . . . . 39

Accessing the Administrator Tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40

Features on the Tools Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41

Logs and Statistics tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41

System Monitoring tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45

Archive and Deploy tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49

Part II ColdFusion Security . . . . . . . . . . . . . . . . 57

Chapter 3 ColdFusion Security . . . . . . . . . . . . . . . . . . 59

Why Is ColdFusion Security Important?. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60

Types of ColdFusion Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61

Choosing a Level of ColdFusion Security. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62

Developing applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63

Deploying applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64

Securing the ColdFusion Administrator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66

To Learn More About Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67

Contents v

Chapter 4 Configuring Basic Security . . . . . . . . . . . . . 71

About Basic Security. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72

Installation defaults . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72

Configuring Remote Development Security (RDS) . . . . . . . . . . . . . . . . . . . . . . . . . 73

Securing data sources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73

ColdFusion Remote Development Services (RDS) . . . . . . . . . . . . . . . . . . . . . . . . . 74

Basic security limitations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74

Securing ColdFusion file resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74

Securing ColdFusion data sources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75

Using a Password to Restrict Access to RDS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76

ColdFusion Studio Password . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76

Removing password-based access control: Windows . . . . . . . . . . . . . . . . . 76

Configuring Basic Runtime Security. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77

Chapter 5 Configuring Advanced Security . . . . . . . . . 79

What is Advanced Security? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80

Advanced Security Basics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81

User directories . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81

Resource types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82

Policies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82

Security contexts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83

Advanced Security Implementations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84

Securing applications with User security . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84

Securing resources with RDS security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85

Securing applications with a security sandbox . . . . . . . . . . . . . . . . . . . . . . . 85

Securing the ColdFusion Administrator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86

Creating an Advanced Security Framework . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88

Implementation summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88

Setting Up a Security Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89

Caching Advanced Security Information. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91

Defining User Directories . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92

Defining a Security Context . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95

Specifying Resources to Protect. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96

Implementing ColdFusion RDS Security. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98

Implementing User Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99

Implementing Server Sandbox Security. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100

Securing the ColdFusion Administrator. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102

Viewing a Map of your Security Framework . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103

vi Contents

An Example of ColdFusion Studio Security. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104

Enabling Advanced Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104

Specifying a User Directory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104

Defining a security context . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105

Specifying resources to protect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105

Adding policies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106

Granting access privileges . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106

Assigning users/groups to policies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107

Enable ColdFusion Studio Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108

Advanced Security Single Sign-On . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109

Undocumented Tags and Functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110

Administrative Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110

Administrative Tags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111

Part III Advanced Verity Tools. . . . . . . . . . . . . 113

Chapter 6 Configuring Verity K2 Server . . . . . . . . . . 115

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116

Verity operates in two modes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116

Quick start to K2 Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116

About K2 Server. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118

Installation details . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118

Two Verity modes now supported . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118

How ColdFusion determines which mode to use . . . . . . . . . . . . . . . . . . . . 119

Collections created with ColdFusion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119

Starting K2 Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120

Windows batch file example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121

Linux and UNIX scripts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121

Stopping K2 Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122

Stopping K2 when run as a service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122

Stopping K2 when run as an application . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122

Stopping K2 Server on Linux/UNIX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122

Editing the k2server.ini File. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124

Edit the vdkHome parameter of k2server.ini . . . . . . . . . . . . . . . . . . . . . . . . 124

Edit the Coll-n section of k2server.ini . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124

k2server.ini file listing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125

k2server.ini Parameter Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127

Server section . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127

Search thread keywords . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128

Collection sections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129

Using the rck2 Utility to Search K2 Documents . . . . . . . . . . . . . . . . . . . . . . . . . . . 131

rck2 syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131

rck2 command options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131

Contents vii

Error Messages. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132

Generic error codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132

Usage error codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132

Runtime error codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132

Data error codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133

Query error codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133

Security error codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133

Remote Connection error codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134

File Handling error codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134

Dispatch error codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134

Warnings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134

TCP/IP error codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135

Chapter 7 Indexing XML Documents . . . . . . . . . . . . . 137

Indexing Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138

Implementation summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138

Style Files. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139

Configuring style files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139

Configuring the style.xml file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139

style.xml command syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141

style.ufl file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142

style.dft file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142

Indexing XML Documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143

Indexing using mkvdk . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143

Searching using rcvdk . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143

Chapter 8 Verity Spider . . . . . . . . . . . . . . . . . . . . . . . . 145

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146

Supports Web standards . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146

Restart capability . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146

State maintenance through a persistent store . . . . . . . . . . . . . . . . . . . . . . . 146

Performance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146

Verity Spider Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148

The Verity Spider command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148

Using a command file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149

Command-line option reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149

Core Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151

Processing Options. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153

Networking Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159

Paths and URLs Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163

Content Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168

Locale Options. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176

viii Contents

Logging Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178

Maintenance Options. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 180

Setting MIME Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181

Syntax restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181

MIME types and Web crawling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181

MIME types and file system indexing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182

Indexing unknown MIME types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182

Known MIME types for file system indexing . . . . . . . . . . . . . . . . . . . . . . . . 183

Chapter 9 Managing Verity Collections with the

mkvdk Utility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185

Overview of the Verity mkvdk Utility. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186

mkvdk syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186

Getting Started with the Verity mkvdk Utility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187

Steps for building a collection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187

Collection setup options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 188

General processing options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189

Date format options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 191

Messaging options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192

Message types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192

Document processing options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193

Bulk Submit Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194

Using bulk insert and delete . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194

Collection Maintenance Options. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195

Examples: Maintaining collections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195

Deleting a Collection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196

Optimization Keywords . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196

About squeezing deleted documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197

About optimized Verity databases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198

Performance tuning options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198

Chapter 10 Verity Troubleshooting Utilities . . . . . . . 199

Overview of Verity Utilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 200

Note on collection types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 200

Using the Verity rcvdk Utility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201

Starting rcvdk . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201

Attaching to a Collection Using rcvdk. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202

Basic searching . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202

Viewing Results of the rcvdk Utility. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203

Displaying more fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204

Contents ix

Using the Verity didump Utility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 206

Viewing the word list with didump . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 206

Viewing the zone list with didump . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 207

Viewing the zone attribute list with didump . . . . . . . . . . . . . . . . . . . . . . . . 208

Using the Verity browse Utility. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 209

Using menu options with the browse utility . . . . . . . . . . . . . . . . . . . . . . . . 209

Displaying fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 210

Using the Verity merge Utility. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 211

Merging collections using the merge utility . . . . . . . . . . . . . . . . . . . . . . . . . 211

Splitting collections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 211

Verity VDK Error Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213

Generic error codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213

Usage error codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213

Runtime error codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213

Data error codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 214

Query error codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 214

Licensing error codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215

Security error codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 216

Remote connection error codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 216

Filtering error codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 216

Dispatch error codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 216

Warnings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 217

Part IV ColdFusion High-Availabilty . . . . . . . . 219

Chapter 11 Scalability and Availability Overview . . . 221

What is Scalability? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222

Performance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222

Load management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 224

Issues Affecting Successful Scalability Implementations. . . . . . . . . . . . . . . . . . . 225

Designing and coding scalable applications . . . . . . . . . . . . . . . . . . . . . . . . 225

Avoiding common bottlenecks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 227

DNS effects on Web site performance and availability . . . . . . . . . . . . . . . 228

Load testing your Web applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 231

What is Web Site Availability? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 234

Availability and reliability . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 234

Common failures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235

A Web site availability scenario . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 236

Failover considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 237

Techniques for Creating Scalable and Highly Available Sites . . . . . . . . . . . . . . . 239

What is clustering? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 239

Hardware-based clustering solutions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 240

Software-based clustering solutions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 242

Combining hardware and software clustering solutions . . . . . . . . . . . . . . 244

x Contents

Chapter 12 Configuring ColdFusion Clusters . . . . . . 245

Introduction to ClusterCATS Administration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 246

ClusterCATS Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 246

ClusterCATS Explorer (Windows only) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 246

ClusterCATS Web Explorer (UNIX only) . . . . . . . . . . . . . . . . . . . . . . . . . . . . 248

ClusterCATS Server Administrator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 251

btadmin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 252

Creating Clusters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 252

Creating clusters in Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 252

Creating clusters in UNIX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 261

Removing Clusters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 263

Adding Cluster Members. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 264

Adding cluster members in Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 264

Adding cluster members in UNIX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 265

Removing Cluster Members . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 266

Removing cluster members in Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . 266

Removing cluster members in UNIX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 267

Server Load Thresholds . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 268

Configuring load thresholds in Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . 268

Configuring load thresholds on UNIX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 272

Session-Aware Load Balancing. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 276

Enabling session-aware load balancing on Windows . . . . . . . . . . . . . . . . 277

Enabling session-aware load balancing on UNIX . . . . . . . . . . . . . . . . . . . . 278

Configuring ColdFusion probes in Windows . . . . . . . . . . . . . . . . . . . . . . . . 280

Configuring ColdFusion probes in UNIX . . . . . . . . . . . . . . . . . . . . . . . . . . . 285

Load-Balancing Devices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 290

Using Cisco LocalDirector . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 290

Using third-party load-balancing devices . . . . . . . . . . . . . . . . . . . . . . . . . . . 294

Administrator Alarm Notifications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 296

Configuring administrator alarm notifications on Windows . . . . . . . . . . 297

Configuring administrator alarm notifications on UNIX . . . . . . . . . . . . . . 297

Administrator E-mail Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 299

Configuring administration e-mail options on Windows . . . . . . . . . . . . . 300

Configuring administration e-mail options on UNIX . . . . . . . . . . . . . . . . . 300

Administrating Security. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 302

Configuring authentication on Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . 302

Configuring authentication on UNIX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 306

Contents xi

Chapter 13 Maintaining Cluster Members . . . . . . . . . 307

Understanding ClusterCATS Server Modes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 308

Changing Active/Passive Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 309

Changing active/passive settings in Windows . . . . . . . . . . . . . . . . . . . . . . . 309

Changing active/passive settings in UNIX . . . . . . . . . . . . . . . . . . . . . . . . . . 310

Changing Restricted/Unrestricted Settings. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 311

Restricting/unrestricting servers in Windows . . . . . . . . . . . . . . . . . . . . . . . 311

Restricting/unrestricting servers in UNIX . . . . . . . . . . . . . . . . . . . . . . . . . . . 312

Using Maintenance Mode (Windows only). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 313

Updating an Existing Cluster Member (Windows only). . . . . . . . . . . . . . . . . . . . 317

Resetting Cluster Members. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 319

Resetting cluster members on Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . 319

Resetting cluster members on UNIX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 320

Chapter 14 ClusterCATS Utilities . . . . . . . . . . . . . . . . 321

Using btadmin. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 322

Using btadmin on UNIX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 322

Using btadmin on Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 324

Using bt-start-server and bt-stop-server (UNIX only) . . . . . . . . . . . . . . . . . . . . . 325

Using btcfgchk. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 325

Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 325

Sample output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 325

btcfgchk DNS errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 326

Using hostinfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 328

Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 328

Sample output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 328

Using sniff. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 329

Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 329

Sample output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 329

Chapter 15 Optimizing ClusterCATS . . . . . . . . . . . . . 333

ClusterCATS Dynamic IP Addressing (Windows only) . . . . . . . . . . . . . . . . . . . . . 334

Understanding static and dynamic IP address configurations . . . . . . . . 334

Benefits of ClusterCATS dynamic IP addressing . . . . . . . . . . . . . . . . . . . . . 335

Setting up maintenance IP addresses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 335

Enabling ClusterCATS dynamic IP addressing . . . . . . . . . . . . . . . . . . . . . . 337

Using Server Failover . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 340

Static versus ClusterCATS dynamic IP addressing . . . . . . . . . . . . . . . . . . . 340

Windows domain controllers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 340

xii Contents

Configuring Load-Balancing Metrics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 341

Overview of metrics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 341

Load types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 342

Output variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 342

Troubleshooting the load-balancing metrics . . . . . . . . . . . . . . . . . . . . . . . . 343

Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 345

About This Book

Advanced ColdFusion Administration is intended for anyone who needs to configure databases for the ColdFusion server.

Contents

• Intended Audience...................................................................................................xiv

• New Features............................................................................................................ xiv

• Developer Resources.................................................................................................xv

• About ColdFusion Documentation............................................. ....... ...... ....... ...... .xvi

• Getting Answers ......................................................................................................xvii

• Contacting Macromedia........................................................................................xviii

xiv About This Book

Intended Audience

Advanced ColdFusion Administration is intended for anyone who needs to perform ColdFusion server management tasks, such as configuring advanced security or managing clustered servers.

New Features

The following table lists the new features in ColdFusion 5:

Benefit Feature Description

Breakthrough productivity

Powerful business intelligence capabilities

Enhanced performance

User-defined functions Create reusable functions to

accelerate development.

Query of queries

Easily integrate data from heterogeneous sour ce s by merging and querying data in memory using standard SQL.

Server analysis and troublshooting

Quickly detect and diagnose server errors with built-in server reporting and the new Log File Analyzer.

Charting engine

Create professional-quality charts and graphs from queried data without leaving the ColdFusion environment.

Enhanced V erity K2 fu ll-text search

Index and search up to 250,000 documents and enjoy greater performance.

Reporting interface for Crystal Reports 8.0

Create professional-quality tabular reports from queried data and applications.

Core engine tuning

Take advantage of dramatically improved server performance and reduced memory usage to deliver faster, more scalable applications.

Incremental page delivery

Improve response time by delivering page output to users as it is built.

Wire protocol database drivers

Deliver high-performance ODBC connectivity using new drivers.

Developer Resources xv

Benefit Feature Description

Easy managment

Application deployment services

Effortlessly and reliably deploy, archive, or restore entire applications using ColdFusion archive files.

Enhanced application monitoring

Keep track of server performance and availability with customizable alerts and recovery.

SNMP support

Monitor ColdFusion applicatio ns from enterprise management systems.

Expanded integration

Expanded Linux support

Deploy on additional Linux distributions, including SuSE and Cobalt.

Enhanced hardware load balancer integration

Apply optimized, agent-based support for hardware load balancers, including new support for the Cisco CSS 11000.

Enhanced COM support

Experience easier integration with COM components.

Developer Resources

Macromedia Corpo r a tion is comm itte d to set tin g the stan da r d fo r custom e r suppo rt in developer education, tech nical supp o rt, and pro fes sio nal services . T he Web site is designed to give you quick access to the entire range of online resources, as the following table describes.

Resource Description URL

Macromedia Web site General information about Macromedia

products and services

Information on ColdFusion

Technical Support Professional support progra ms that

ColdFusion Support Forum

Detailed p roduct information on

ColdFusion and related topics

Macromedia offers

Access to experienced ColdFusion

developers through participation in the

Online Forums, where you can post

messages and read replies on many

subjects relating to ColdFusion

www.macromedia.com/

www.coldfusion.com/products/ coldfusion/

www.coldfusion.com/support/

http://forums.allaire.com/coldfusion/

xvi About This Book

Resource Description URL

Installation Support Support for installation-related issues

for all Macromedia products

Professional Education Information about classes, on-site

training, and online courses offered by

Macromedia

Developer Community All the resources that you need to stay

on the cutting edge of ColdFusion

development, including online

discussion groups, Knowledge Base,

technical papers, and more

ColdFusion Dev Center Development tips, articles,

documentation, and white papers

Macromedia Alliance Connection with the growing network of

solution providers, applica tion

developers, resellers, and hosting

services creating solutions with

ColdFusion

www.coldfusion.com/support/ installation/

www.coldfusion.com/developer/ training.cfm

www.coldfusion.com/developer/

www.coldfusion.com/developer/ referencedesk/

www.coldfusion.com/partners/

About ColdFusion Documentation

ColdFusion documentation is designed to provide support for ColdFusion developers and ColdFusion Server administrators. The print and online versions are organized to allow you to quickly lo cate the information that you need. The ColdFusion online documentation is provided in HTML and Adobe Acrobat formats.

Printed and online documentation set

The ColdFusion documentation set consists of the following titles.

Book Description

Installing and Configuring ColdFusion Server

Advanced ColdFusion Administration

Developing ColdFusion Applications

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

Describes how to connect your data sources to the ColdFusion Server, configure security for your applications, and how to use ClusterCATS to manage scalability, clustering, and load-bal ancing for your site

Describes on how to ColdFusio n Server to develop yo ur dynamic Web applications, including retrieving and updating your data, using structures, and forms

Getting Answers xvii

Book Description

CFML Reference The online-only ColdFusion Reference provides descriptions,

syntax, usage, and code examples for all ColdFusion tags, functions, and variables

CFML Quick Reference

A brief guide that shows the syntax of ColdFusion tags, functions, and variables

Viewing online documentation

All ColdFusion documentation is available online in HTML and Adobe Acrobat PDF formats. To view the HTML documentation, open the following URL on the We b server running ColdFusion: http://localhost/cfdocs/dochome.htm.

ColdFusion documentation in Acrobat format is available on the ColdFusion product CD-ROM and for download from the ColdFusion web site: http://

www .coldfusion.com.

ColdFusion Studio documentation

ColdFusion Studio contains a wide range of online assistance, including a complete collection of ColdFusion documentation. T o vie w ColdFu sion online documentation from within ColdFusion Studio, click the Help resource tab. You will see an expandable list of documents about ColdFusion Server and ColdFusion Studio, as well as other information that relates to Web programming:

ColdFusion Studio online documentation is searchable and you can bookmark individual pages. For more information about using the Cold Fu sion S tud io interface , see the ColdFusion Studio documentation set.

Getting Answers

One of the best ways to solve particular programming problems is to tap into the vast expertise of the ColdFusion developer communities on the ColdFusion Forums. Other devel opers on th e forum can help y ou f igur e out ho w to do jus t abo ut a nythin g with ColdFusion. The search facility can also help you search messages from the previous 12 months, allowing you to learn how others have solved a problem that you might be facing. The Fo rums is a gr e at r es our ce for learning C oldF u sion, bu t it is also a great place to see the ColdFusion developer community in action.

xviii About This Book

Contacting Macromedia

Corporate headquarters

Technical support

Sales

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

Tel: 415.252.2000 Fax: 415.626.0554

Web: www.macromedia.com Macromedia offers a range of telephone and Web-based

support options. Go to http://www.coldfusion.com/

support/ for a complete description of technical support

services. You can make postings to the ColdFusion Support Forum

(http://forums.coldfusion.com/DevConf/index.cfm) at any time.

Toll Free: 888.939.2545 Tel: 617.219.2100

Fax: 617.219.2101 E-mail: sales@macromedia.com Web: http://commerce.coldfusion.com/purchase/

index.cfm

Part I

Data Sources and Tools

This part describes data source management and introduces the ColdFusion Administrator tools. The fol lowing chapters are included:

Advanced Data Source Management ..................................................3

Administrator Too ls................. ............. ... ............. .. ............. .. ..............39

Chapter 1

Advanced Data Source Management

This chapter describes how to create and configure ColdFusion data sources for several databases using ODBC, OLE DB, and native drivers. It also describes how to use ColdFusion to create a database file in a cfquery and how to use connection string options.

For basic information on data sources and fo r information on ho w to connect to SQL Server, Access, and Oracle databases, see Installing and Configuring ColdFusion Server.

Contents

• About ColdFusion database drivers................................ ....... ...... ....... ...... ....... ...... ....4

• Using ColdFusion to Create a Data Source (UNIX only)........................................10

• Using Connection String Options............................................................................12

• Connecting to DB2 Databases.................................................................................15

• Connecting to dBASE/FoxPro Databases................................................................21

• Connecting to Excel Databases................................................................................24

• Connecting to Informix Databases..................................................... ...... ....... ...... ..26

• Connecting to Sybase Databases.............................................................................32

• Connecting to Text Databases..................................................................................35

• Connecting to Visual FoxPro Databases..................................................................37

4 Chapter 1 Advanced Data Source Management

About ColdFusion database drivers

ColdFusion uses ODBC, OLE DB, and native database drivers. For detailed information about ODBC drivers, see Installing and Configuring ColdFusion Server.

About OLE DB

OLE DB is a Microsoft specification for a set of interfaces designed to access data. Although ODBC is primarily used to access SQL data in a platform-independent manner, OLE DB is designed to access SQL and non-SQL data in an OLE Component Object Model (COM) environment.

Note

OLE DB is available only on Windows NT/2000.

ColdFusion developers can access a range of data stores through Microsoft OLE DB, including:

• MAPI-based data stores such as Microsoft Exchange and Lotus Mail

• Nonrelational data stores, such as Lotus Notes

• LDAP 2.0 data

• Data from OLE applications like word processors and spreadsheets

• Mainf rame data

• HTML and text files, flat-file data

For more information, including a list of provider vendors, visit the Microsoft OLE DB site at http://www.microsoft.com/data/oledb/.

About OLE DB providers

Before ColdFusion can use OLE DB to access data stores, you must install an OLE DB provider, available from third-party vendors. The provider software handles data processing in response to requests from the OLE DB consumer, which in this case is ColdFusion.

ColdFusion uses an OLE DB provider to access an OLE DB data source. An OLE DB provider is a COM component that accepts calls to the OLE DB Application Programming Interface (API) and processes that request against the data source.

You can often achieve sultry performance levels by running an OLE DB provider, instead of an ODBC driver, to process SQL. This depends on how the provider implements the data call. Some providers route OLE DB calls through the ODBC Driver Manager, while others go directly to the data bas e. Provi ders tha t g o d ir e ctly to the database are akin to native drivers in providing an alternative to ODBC. Providers are available for all the major relational DBMS products as well as the data stores previously mentione d.

About ColdFusion database drivers 5

Installing the OLE DB provider

Before you configure an OLE DB data source, you must have installed a recent version of the Microsoft Data Access Components (MDAC). MDAC includes two OLE

DB providers—SQLOLEDB and MSDASQL. For Access d atabases, Microsoft makes available a Jet provider. For SQL Server, Microsoft offers MSDASQL and SQLOLEDB providers.

During its installation process, ColdFusion attempts to detect the MDAC version on your computer. If MDAC is absent or the identified version is 2.0 or earlier, ColdFusion installs MDAC version 2.5 and restarts the installation process. If you install MDAC on a Windows NT system, you get the MSDASQL and SQLOLEDB providers.

For updated versions of MDAC, visit the Microsoft Universal Data Access Download Page at http://www.microsoft.com/data/download.htm/.

Note

Before you install MDAC, stop all unnecessary services, such as Web servers, virus scanning programs, or mail servers.

You should be aware of the following characteristics in how ColdFusion handles OLE DB:

• The initial driver drop-down list box does not display all of the installed OLE DB providers. If you are creating a data source using a provider other than SQLOLEDB or Jet, such as MSDASQL or a MERANT OLE DB driver, you must select other from the drop-down list box.

• No matter which provider you select from the drop-down list box, you must still retype its name in the Provider field.

• When using MSDASQL, you must have an ODBC data source already defined for the database. Enter this ODBC DSN in the ProviderDSN text box.

6 Chapter 1 Advanced Data Source Management

The following procedure describes how to configure an OLE DB data source to a Microsoft SQL Server database on Windows NT, using SQLOLEDB as the provider.

To configure an OLE DB data source:

1Open the ColdFusion Administrator. 2 Under Data Sources, click OLE DB.

The OLE DB Data Sources page displays any existing OLE DB Data Source Names that are available to ColdFusion:

3 Enter a name for the new data source and select an OLE DB Provider from the

drop-down list.

Note

Do not name a ColdFusion data source Registry or Cookie, as these words are reserved for use by ColdFusion.

4Click Add.

The Create OLE DB Interface Data Source page displays:

5 (Optional) Enter a description.

About ColdFusion database drivers 7

6 Enter the following connection information:

• If SQLOLEDB is the provid er Enter SQLOLEDB a s the Provider, specify the

Server that hosts the database, and specify the name of the Default Database.

Note

For the Server field, if the database is a local SQL Server database, enclose the word local in parentheses: (local).

• If Microsoft Jet is the provider Enter Microsoft.Jet.versionnumber as the

Provider (such as Microsoft.Jet.OLEDB.4.0), and specify the path to the Database File.

• If you are using another provider Enter its name as the Provider. Be aware

that MSDASQL requires a predefined ODBC data source for the database to which you will connect. Enter the name of the ODBC data source in the Provider DSN field.

8 Chapter 1 Advanced Data Source Management

7 Click CF Settings and specify any ColdFusion-specific settings. For example,

enter a username and password if required for the data source.

Note

The omission of required username and password information is a common reason why a data source fails to verify.

8 Click Create to create the new data source.

ColdFusion automatically verifies that it can connect to the data source.

If ColdFusion cann ot verify the data sou rce, the S tatu s d isp lays a s Failed. You c an

cfquery against the failed data source to get more detailed information

run a about the problem. You also can try embedding a username and password into

cfquery tag to see if the query works.

the

About ColdFusion database drivers 9

If you are creating a UNIX data source, you might need to set environment variables for your database client library by editing the ColdFusion start script in <installdir>/coldfusion/bin. F or detailed information about editing the ColdFusion start script for your particular database, see the section about your database.

About native drivers

The Enterprise Edition of ColdFusion Server includes support for DB2, Informix, Sybase System 11 through Sybase Adaptive Server 12.0, and Oracle 7.3.4, 8.0, and 8i

databases through native database drivers on both Windows NT and UNIX platforms.

You might consider using native database drivers for the following reasons:

• Native drivers tend to offer better performance than their ODBC counterparts.

• Some stored procedure functionality is only available through native drivers. For

example, you must use an Oracle native driver to use packages.

Software requirements for native drivers

Before you can use the ColdFus ion native database drivers, you must install additional client software. Also, you must install the database client software and ColdFusion Server software on the same server.

The following table describes requirements for each database and each supported platform:

Database Client Software For more information

Oracle Oracle 7.3.4, Oracle 8.0.x

or Oracle 8.1.6 or higher

Sybase Sybase Open/Client

1 1.1 .1, 11.9.2 or 12.0

Informix Informix 2.50 SDK or

higher

IBM DB2 IBM DB2 Client

Application Enabler version 5 or 6

Installing and Configuring ColdFusion Server

“Connecting to Sybase Databases,” on page 32

“Connecting to Informix Databases,” on pag e 26

“Connecting to DB2 Databases,” on page 15

10 Chapter 1 Advanced Data Source Management

Using ColdFusion to Create a Data Source (UNIX only)

The MERANT ODBC drivers that ship with all UNIX versions of ColdFusion include a FoxPro 2.5/dBASE driver. You can use the FoxPro 2.5/dBASE driver to create a database file in a Oracle, Informix, Sybase, or DB2 database.

Note

See the MERANT DataDirect ODBC Reference for details about SQL statements used for flat-file drivers. The default location of this reference on UNIX machines is: <installdir>/coldfusion/odbc/doc/odbcref.pdf. On Win32 machines, the default location is: <installdir>/cfusion/bin/odbcref.pdf.

You need to create tables in a data source called newtable.

T o create a table in the data source:

1 Create the newtable data source in the ColdFusion Administrator, specifying the

MERANT dBASE/FoxPro ODBC driver. If you do not create the data source, you receive an error when you try to execute

this page.

2 Use the following code to generate these fields in the newtable data source:

cfquery with standard SQL syntax even if you do not have an

Field Data type

Bean_ID numeric Name char Price char Date date Descript char

<TITLE>dBASE Table Setup</TITLE> </HEAD> <BODY>

<!--Before running this code, you need to create the

newtable data source in the ColdFusion Administrator, specifying the MERANT dBASE/FoxPro ODBC driver.

--->

CREATE TABLE Beans1 (

Bean_ID numeric(6), Name char(50), Price char(50),

Using ColdFusion to Create a Data Source (UNIX only) 11

Date date,</P> Descript char(254))

</cfquery>

INSERT INTO Beans1 VALUES (

1,</P> ’Kenya’, ’33’, {ts ’1999-08-01 00:00:00.000000’}, ’Round, rich roast’)

</cfquery>

INSERT INTO Beans1 VALUES (

2, ’Sumatra’, ’21’, {ts ’1999-08-01 00:00:00.000000’}, ’Complex flavor, medium-bodied’)

</cfquery>

INSERT INTO Beans1 VALUES (

3, ’Colombia’, ’89’, {ts ’1999-08-01 00:00:00.000000’}, ’Deep rich, high-altitude flavor’)

</cfquery>

INSERT INTO Beans1 VALUES (

4,</P> ’Guatamala’, ’15’, {ts ’1999-08-01 00:00:00.000000’}, ’Organically grown’)

</cfquery>

CREATE UNIQUE INDEX Bean_ID on Beans1 (Bean_ID) </cfquery>

SELECT * FROM Beans </cfquery>

#Bean_ID# #Name#<br> </cfoutput>

</BODY> </HTML>

12 Chapter 1 Advanced Data Source Management

Using Connection String Options

ColdFusion 5 allows you to specify a connection string for ODBC data sources. You can do this programmatically or in the ColdFusion Administrator.

About the connection string

You can use the connection string to do the following tasks:

• Specify connection attributes that cannot be defined in the odbc.ini settings.

• Override odbc.ini settings.

• Make ODBC connections dynamically when there is no data source defined in

the odbc.ini settings.

Some ODBC data sources let you pass driver-specific options. A database administrator (DBA) can use t hese options to see whic h applications are connected to the database server, and to identify who is running those applications. For example, many applications that connect to Microsoft SQL Server pass the attribue-value pairs APP="appname" and WSID="work station id" when connecting.

Consider the following the APP and WSID attributes

<cfquery

name="getInfo" datasource="2Northwind" dbtype="ODBC"

connectstring="DRIVER={SQL SERVER}; SERVER=(local); UID=sa; PWD=; DATABASE=Northwind;

APP=ColdFusion5;WSID=Workstation_Moe"

SELECT *

FROM shippers </cfquery>

cfquery, which specifies values in the connection string for

The APP and WSID values are readily available when you run the above query. A SQL Server DBA can use Profiler to view this information in a trace:

+ 342 hidden pages