Chili!Soft ASP 3.6
Product Documentation
Chili!Soft ASP 3.6 Product Documentation
Legal Notice
Copyright 2001 Chili!Soft, Sun Microsystems, Inc., 901 San Antonio Road, Palo Alto, California
94303, U.S.A. All rights reserved. Sun Microsystems, Inc. has intellectual property rights relating
to technology embodied in the product that is described in this document. In particular, and
without limitation, these intellectual property rights may include one or more additional patents or
pending patent applications in the U.S. or other countries. This product documentation and the
technology it describes are distributed under licenses restricting their use, copying, distribution,
and decompilation. No part of this product documentation may be reproduced in any form by any
means without prior written authorization of Sun and its licensors, if any. Third-party software,
including font technology, is copyrighted and licensed from Sun suppliers. Parts of the product
may be derived from Berkeley BSD systems, licensed from the University of California. UNIX is
a registered trademark in the U.S. and other countries, exclusively licensed through X/Open
Company, Ltd. Sun, Sun Microsystems, the Sun Logo, Java, Solaris, and Chili!Soft ASP are
trademarks or registered trademarks of Chili!Soft, Inc. or Sun Microsystems, Inc. in the U.S. and
other countries. All SPARC trademarks are used under license and are trademarks of SPARC
International, Inc. in the U.S. and other countries. Federal Acquisitions: Commercial Software –
Government Users Subject to Standard License Terms and Conditions.
DOCUMENTATION IS PROVIDED "AS IS" AND ALL EXPRESS OR IMPLIED
CONDITIONS, REPRESENTATIONS AND WARRANTIES, INCLUDING ANY IMPLIED
WARRANTY OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE OR
NON-INFRINGEMENT, ARE
DISCLAIMED, EXCEPT TO THE EXTENT THAT SUCH DISCLAIMERS ARE HELD TO
BE LEGALLY INVALID.
Chili!Soft ASP 3.6 Product Documentation
Contents
Introduction: About This Documentation
What's in This Documentation
1
1
Accessing Documentation, Samples, and Diagnostics
Product Documentation
3
Sample ASP Applications
4
10-Step Tour
4
Diagnostic Applications
5
Chapter 1: About Chili!Soft ASP
What's in This Release
6
6
Supported Platforms and Web Servers
What Is ASP?
3
7
8
ASP for the HTML Author 9
ASP for the Experienced Web Scripter
10
ASP for the Web Developer and Programmer
What Is Chili!Soft ASP?
10
10
Chili!Soft ASP Features
10
Chapter 2: Installing and Configuring Chili!Soft ASP
12
Installing and Uninstalling Chili!Soft ASP 12
Installing Chili!Soft ASP 3.6.0-P1 for IBM AIX
12
Installing Chili!Soft ASP 3.6 for Sun Solaris 27
Installing Chili!Soft ASP 3.6 for Linux
42
Installing and Upgrading Chili!Soft ASP 3.6 for Cobalt
Installing Chili!Soft ASP 3.6 for HP-UX
62
Configuring the Web Server After Installation
Uninstalling Chili!Soft ASP 80
Enabling Publishing
82
Defining ASP Applications on the Server 82
Enabling Database Connections on the Server
83
75
61
Chili!Soft ASP 3.6 Product Documentation
Chapter 3: Managing Chili!Soft ASP
86
Using the Administration Console 86
Accessing the Administration Console
87
Starting and Stopping the Administration Web Server
Configuring Usernames and Passwords
90
Accessing the Product Documentation
91
Viewing the Product README File 93
Contacting Customer Support
95
Installing a New Serial Number
96
Managing the ASP Server 98
Changing ASP Server Settings
101
Stopping and Restarting the ASP Server
105
Configuring International Support 106
Enabling Session State
108
Enabling Java Support
111
Securing the Server 112
Configuring ASP Applications
117
Viewing Information About the ASP Server 123
Managing the Web Server 130
Starting and Stopping the Web Server
Enabling ASP for a Virtual Host
Changing the Web Server
133
Enabling FrontPage Publishing
136
131
131
Installing FrontPage 2000 Server Extensions
Enabling FrontPage Authoring
137
Setting up FrontPage Users 138
Configuring a Database
139
Configuring Data Source Names (DSNs)
140
Viewing the List of ODBC Drivers 149
Configuring SequeLink
Configuring DB2
151
153
Editing the Microsoft SQL Server Template 156
136
89
Chili!Soft ASP 3.6 Product Documentation
Configuring the Database Environment
156
Configuring Database Parameters 163
Configuring ActiveX Data Objects (ADO) Connections
Setting the ADO Connection Pool Size
176
Enabling and Disabling ADO Logging
177
175
Running Chili!Soft ASP in a Shared Web Hosting Environment 180
Creating Database Connections in a Shared Environment
Defining Applications in a Shared Environment
181
181
Using the User Configuration File 182
Using the FrontPage 2000 Services File in a Shared Environment
Setting up Multi-machine Chili!Soft ASP
Optimizing Server Performance
183
186
Enabling Scripts Buffering 187
Changing the Session Timeout Value
189
Changing the Script Timeout Value 191
Enabling Script Caching
192
Choosing a Threading Mode
194
Running in Multi-process Mode
195
Running in Multi-threaded Mode
197
Pre-compiling ASP Pages
199
Pooling Database Connections
Load Balancing
199
200
Advanced Administration Options 200
Editing the Windows NT Registry
201
Editing the Chili!Soft ASP Configuration File
Using the caspctrl Script
203
208
Defining Applications on UNIX
209
Starting and Stopping Multiple Instances of the ASP Server 212
Relocating the System Files for a Shared Installation213
Chapter 4: Building a Chili!Soft ASP Application
Creating the Basic ASP Application
Choosing an Authoring Tool
217
218
217
183
Chili!Soft ASP 3.6 Product Documentation
Creating an ASP Page
Adding Scripts
219
220
Changing the Scripting Language
221
Using @ Directives 222
Using Server-side Includes 223
Defining the ASP Application
Using the global.asa File
224
Specifying Application Events
Managing User Sessions
224
225
226
Saving Changes to the global.asa File
Using Chili!Soft ASP Built-in Objects
228
228
Using Chili!Soft ASP Installed Components
231
Using Java Objects and Classes 232
Connecting to a Database 233
Creating Connection Strings
233
Opening the Database Connection 242
Using FrontPage Database Features
243
Migrating a Microsoft Access Database to dBase
Developing International Applications
246
Understanding Code Pages 247
Publishing a Chili!Soft ASP Application
Chapter 5: Developer's Reference
ADO Component Reference
ADO Overview
250
ADO Objects
251
ADO Connection Object
250
267
ADO Error Object 295
ADO Field Object 300
ADO Parameter Object
314
ADO Property Object
322
ADO Recordset Object
328
ADO Collections
409
247
249
245
Chili!Soft ASP 3.6 Product Documentation
ASP Built-in Objects Reference
ASP Application Object
421
421
ASP Request Object 424
ASP Response Object
435
ASP Server Object 448
ASP Session Object 452
ASP Component Reference
459
Installed ASP Components 459
ASP Ad Rotator Component 459
ASP Ad Rotator Component Rotator Schedule File 460
ASP Ad Rotator Component Redirection File
ASP Ad Rotator Component Properties
463
ASP Ad Rotator Component Methods
464
ASP Browser Capabilities Component
465
ASP Content Linking Component
469
ASP Content Rotator Component
474
462
ASP Counters Component 479
ASP MyInfo Component
482
ASP Tools Component
483
Chilli!Beans Component Reference
487
Using Null Objects with Chili!Beans487
Iterating a Collection with Chili!Beans
487
Accessing Methods and Fields with Chili!Beans
Chili!Beans Environment Settings
488
Limitations of Chili!Beans Objects 489
Constructing Java Objects with Chili!Beans 489
Component Programmer's Reference
Scope and Threading
492
493
C++ Interfaces Reference 493
COM on UNIX
494
Editing the Registry (chregedit)
494
487
Chili!Soft ASP 3.6 Product Documentation
Registering Components (chregsvr) 495
IApplicationObject Interface
IReadCookie Interface
495
498
IRequest Interface 500
IRequestDictionary Interface
503
IResponse Interface 505
IScriptingContext Interface 516
IServer Interface
518
ISessionObject Interface
521
IStringList Interface525
IVariantDictionary Interface
IWriteCookie Interface
529
JScript Language Reference
533
JScript Features (ECMA)
527
533
JScript Features (non-ECMA)
538
JScript Data Type Conversion
540
JScript Conditional Compilation Variables 541
JScript Operators 542
JScript Functions
567
JScript Statements 570
JScript Objects
583
JScript Collections 730
SpicePack Component Reference
736
Installing and Uninstalling SpicePack
Chili!Mail (SMTP) Component
738
Chili!Upload (File Upload) Component
Chili!POP3 (POP3) Component
VBScript Language Reference
752
VBScript Constants 752
VBScript Operators 759
VBScript Statements
VBScript Functions 795
771
736
744
742
Chili!Soft ASP 3.6 Product Documentation
VBScript Objects and Collections 863
VBScript Dictionary Object 863
VBScript Drive Object
870
VBScript Err Object879
VBScript File Object
883
VBScript FileSystemObject Object 895
VBScript Folder Object
913
VBScript TextStream Object 925
VBScript Collections
931
Appendix A: Online Resources 936
Appendix B: Chili!Soft ASP White Papers
937
Chili!Soft ASP and Distributed Object Technologies
Abstract
939
Introduction
939
Chili!Soft ASP and COM/DCOM
939
Chili!Soft ASP and Enterprise JavaBeans (EJB)
Chili!Soft ASP and CORBA 942
Conclusion 943
Company and Product Overview
943
Chili!Soft ASP Development Guidelines 945
Abstract
945
Software Engineering Practices
945
Programming Tips and Suggestions 947
Company and Product Overview
Chili!Soft ASP Development Tools
Abstract
939
948
949
949
Introduction
949
Page Development Tools
951
Component Development Tools
955
Company and Product Overview
956
940
Chili!Soft ASP 3.6 Product Documentation
Chili!Soft ASP Scalability and Performance
Abstract
957
957
Executive Summary 957
Chili!Soft ASP Architecture 958
Horizontal Scalability Options
963
Vertical Scalability Options 965
The Future of Chili!Soft ASP Scalability
967
Conclusion 968
Company and Product Overview
968
Hosting Database-driven Web Sites Using Chili!Soft ASP
Abstract
970
970
Chili!Soft ASP Database Connectivity Primer
DSN Decisions
970
971
Database Connectivity
973
What About Microsoft Access?
974
Conclusion 977
Company and Product Overview
977
Appendix A: Using Microsoft Access as a Data Mining Tool 978
How ISPs Can Expand Their Hosting Business with Chili!Soft ASP
Abstract
980
The Market Challenge for ISPs
980
Active Server Pages and Chili!Soft 981
Chili!Soft ASP Hosting Scenarios
983
Chili!Soft ASP Value Proposition
985
Product and Company Overview
986
Platform-independent ASP Development Strategies
Abstract
987
Introduction
987
Operating System Considerations
Web Server Considerations 990
Database Considerations
991
988
987
980
Chili!Soft ASP 3.6 Product Documentation
Distributed Object Technology Considerations
992
Conclusion 997
Company and Product Overview
997
Why Active Server Pages 998
Abstract
998
ASP Overview
998
The World Before ASP
999
The ASP Value Proposition 1000
Chili!Soft ASP
1001
Company and Product Overview
1002
Why Chili!Soft ASP Makes Sense for IT Management
Abstract
1003
1003
Why ASP for Corporations and IT Management
1004
Why ASP for Corporations and IT Management
1005
Conclusion 1006
Company and Product Overview
1006
Appendix C: Chili!Soft ASP Error Messages 1007
Chili!Soft ASP Errors
VBScript Errors
1013
JScript Errors
1016
ADO Errors
1018
1007
Appendix D: Troubleshooting 1020
ASP Pages Not Served
Appendix E: Glossary
1022
1020
Chili!Soft ASP 3.6 Product Documentation
1
Introduction: About This Documentation
Welcome to the Chili!Soft ASP product documentation. There are two versions of this
documentation: one in HTML format that includes dynamic index and search functionality, and
one in Adobe PDF format that you can print. To view and print the Adobe PDF version, you must
have Adobe Acrobat Reader installed. To obtain a free copy of Acrobat Reader, go to:
http://www.adobe.com/products/acrobat/readstep2.html
In addition to the product documentation, the following resources will help you learn more about
Chili!Soft ASP:
•
Diagnostic applications verify that the features of your ASP environment are functioning
correctly
•
The 10-Step Tour provides a basic introduction to Chili!Soft ASP technology
•
Sample ASP applications demonstrate the basics of building Chili!Soft ASP applications
This introduction describes these resources and how to access them.
In this introduction:
•
What's in This Documentation
•
Accessing Documentation, Samples, and Diagnostics
We would appreciate having your comments about this documentation—both regarding what
you found helpful and what could be improved. Please send your comments to
chili.eval@sun.com.
What's in This Documentation
For administrators, this documentation includes information about installing, configuring, and
running Chili!Soft ASP. It also discusses configuring Chili!Soft ASP for a shared Web hosting
environment, such as an Internet Service Provider (ISP) or Internet Presence Provider (IPP).
For Web authors and developers, this documentation introduces the basics of building Chili!Soft
ASP applications. It also provides reference information about using scripting languages,
connecting to databases, and developing and using components.
The Chili!Soft ASP product documentation is structured so you can easily find the information
you need. The following table describes the contents of each chapter and the Chili!Soft ASP users
who will get the most from reading them:
2
Chili!Soft ASP 3.6 Product Documentation
Chapter Name
Who Should Read It
Description
Introduction: About This
Documentation
Everyone
The introduction provides an overview of
the Chili!Soft ASP product documentation
and other Chili!Soft ASP resources.
Chapter 1: About Chili!Soft
ASP
Everyone should read the
first topic. Users new to
ASP technology and/or
Chili!Soft ASP should
read the entire chapter.
This chapter describes what is included
with this release of Chili!Soft ASP. It also
provides an introduction to ASP
technology and describes the Chili!Soft
implementation of ASP.
Chapter 2: Installing and
Configuring Chili!Soft ASP
Administrators
This chapter tells you how to install
Chili!Soft ASP on your server and
describes the changes the setup program
makes to your Web server configuration
files. It also gives instructions for
performing basic server configuration tasks
and enabling users to publish ASP
applications to the Web server.
Chapter 3: Managing
Chili!Soft ASP
Administrators
This chapter provides detailed information
about administering Chili!Soft ASP,
including changing ASP Server
configuration settings, configuring
security, optimizing server performance,
and troubleshooting server problems.
Chapter 4: Building a
Chili!Soft ASP Application
Web developers new to
ASP technology and
Chili!Soft ASP and
administrators who would
like a basic introduction
to ASP should read the
introductory topics and
the sections about
connecting to a database.
Experienced ASP
developers might want to
read the topics about
using objects and
components. Everyone
should read the section
about publishing an ASP
application.
This chapter introduces the basics of
developing ASP applications: creating an
ASP page, adding scripts and server-side
includes, and defining the application on
the server. It also discusses extending ASP
applications by using objects and
components and connecting to databases.
This chapter concludes with important
information about publishing a Chili!Soft
ASP application.
Chapter 5: Developer's
Reference
Web developers
This chapter provides reference
information about using built-in ASP
components, additional "off-the-shelf" ASP
3
Chili!Soft ASP 3.6 Product Documentation
Chapter Name
Who Should Read It
Description
components, and custom components. It
also provides a scripting reference for
VBScript and JScript, as well as reference
information about using Active Data
Objects (ADO), Chili!Beans, and
SpicePack.
Appendix A: Online Resources
Administrators, Web
authors, and developers
This appendix provides links to online
information about Chili!Soft ASP and
developing ASP applications.
Appendix B: White Papers
Administrators, Web
authors, and developers
This appendix includes white papers
providing information about a number of
topics of interest to ASP developers and
administrators.
Appendix C: Chili!Soft ASP
Error Messages
Administrators, Web
authors, and developers
This appendix explains error messages you
might encounter when using Chili!Soft
ASP.
Appendix D: Troubleshooting
Administrators, Web
authors, and developers
This appendix provides troubleshooting
tips for problems that you might encounter
when running Chili!Soft ASP.
Appendix E: Glossary
Administrators, Web
authors, and developers
This appendix contains a glossary of terms
you might encounter when administering
Chili!Soft ASP and developing ASP
applications.
Accessing Documentation, Samples, and Diagnostics
On the Chili!Soft ASP Start Page, you can find links to the Chili!Soft ASP product
documentation, ASP sample applications, diagnostic applications, and the 10-Step Tour. You can
access the Start Page from:
http://[HOSTNAME]/caspsamp
where [HOSTNAME] is the hostname of your Web server.
The remainder of this topic provides more information about these resources and describes
additional ways to access them.
Product Documentation
You can always access the product documentation from the Chili!Soft ASP Administration
Console. In addition, the Chili!Soft ASP setup program gives you the option to enable the product
documentation on your Web server. If you choose this option, when your Web server is running,
you can also access the HTML version of the documentation at:
http://[HOSTNAME]/caspdoc/
Chili!Soft ASP 3.6 Product Documentation
4
where [HOSTNAME] is the hostname of your Web server.
From the first page of the HTML documentation, you can click a link to open the version in
Adobe PDF format. To access the Adobe PDF version directly, use the following URL:
http://[HOSTNAME]/caspsamp/pdf/
where [HOSTNAME] is the hostname of your Web server.
You can also access both versions of the product documentation from the Chili!Soft Web site at:
http://www.chilisoft.com/caspdoc/
Sample ASP Applications
The Chili!Soft ASP setup program gives you the option to enable the sample ASP applications on
the computer running Chili!Soft ASP. When your Web server is running, you can access the
samples from the Chili!Soft ASP Start Page at:
http://[HOSTNAME]/caspsamp/
where [HOSTNAME] is the hostname of your Web server.
- or You can access the samples from the Chili!Soft Web site at:
http://www.chilisoft.com/caspsamp/
You can view a list of installed sample ASP applications on the ASP Applications page of the
Chili!Soft Administration Console, as described in "Adding an ASP Application" in "Chapter 3:
Managing Chili!Soft ASP." The sample applications are located in your file system at:
/caspsamp="[C-ASP_INSTALL_DIR]/caspsamp"
where /caspsamp is the directory alias (virtual directory) for the caspsamp sample application
and [C-ASP_INSTALL DIR] is the path name of the Chili!Soft ASP installation directory.
In the caspsamp directory, the following subdirectories contain samples:
/casp401k="[C-ASP]/caspsamp/401k/content"
where /casp401k is the directory alias (virtual directory) for the casp401k sample application.
/caspagent="[C-ASP]/caspsamp/friendship/agent/content"
where /caspagent is the directory alias (virtual directory) for the caspagentsample application.
/caspclient="[C-ASP]/caspsamp/friendship/client/content"
where /caspclient is the directory alias (virtual directory) for the caspclient sample
application.
10-Step Tour
If you are new to ASP technology, we recommend that you take our 10-Step Tour to gain a better
understanding of what Chili!Soft ASP can do for you. When Chili!Soft ASP is installed and your
Web server is running, you can access the tour from the Chili!Soft ASP Start Page, at:
Chili!Soft ASP 3.6 Product Documentation
5
http://[HOSTNAME]/caspsamp/
where [HOSTNAME] is the hostname of your Web server.
Diagnostic Applications
The following diagnostic applications are installed with Chili!Soft ASP, which enable you to
verify that various features of your ASP environment are functioning correctly:
•
HELLO. This application tests the functionality of ASP and VBScript by using a simple
"Hello World" script.
•
SERVER. This application tests the ASP Server-to-Web server connection by retrieving
the standard Web server variables.
•
JSCRIPT. This application tests the functionality of JScript.
•
ADO. This application accesses ActiveX Data Objects (ADO): from VBScript. It
connects to a sample database by using ODBC (Open Database Connectivity) in order to
test the functionality of ADO and the dBase ODBC driver.
•
JSADO. This application performs the same test as ADO, except it accesses ADO from
JScript rather than VBScript.
•
SQLEXECUTE. This application uses ADO to execute an SQL statement and display the
results. To use this application, you must first create a system DSN for your database on
the ASP Server, as described in "Adding a DSN" in "Chapter 3: Managing Chili!Soft
ASP."
When your Web server is running, you can access the diagnostic applications from the Chili!Soft
ASP Start Page, at:
http://[HOSTNAME]]/caspsamp/
where [HOSTNAME] is the hostname of your Web server.
Tip
While running a diagnostic application, you can view the ASP code that generated the
HTML output by clicking View ASP Source at the bottom of the page.
Chili!Soft ASP 3.6 Product Documentation
6
Chapter 1: About Chili!Soft ASP
Chili!Soft ASP 3.6 enables you to run ASP applications on a variety of Web servers running on
IBM AIX, Sun Solaris, Linux, Cobalt, or HP-UX operating systems.
This chapter describes what is included in Chili!Soft ASP 3.6. It also gives an overview of Active
Server Pages (ASP) technology and describes the Chili!Soft implementation of ASP.
Who should read this chapter: Everyone should read the first topic, "What's in This Release."
Users new to ASP and/or Chili!Soft should read the entire chapter.
In this chapter:
•
What's in This Release
•
Supported Platforms and Web Servers
•
What Is ASP?
•
What Is Chili!Soft ASP?
What's in This Release
When you install Chili!Soft ASP 3.6, you can select either a bundle installation or a custom
installation. The option you choose determines which items are installed on your server.
Note
On Cobalt systems, there is no installation option provided; the setup program
automatically installs and configures the components that are listed below for a custom
installation.
With a bundle installation, the setup program automatically installs and configures the following
items on the target server:
•
Chili!Soft ASP Server
•
Chili!Soft ASP Administration Console
•
Chili!Beans (optional on Sun Solaris and IBM AIX; not available on Cobalt systems)
•
Java Runtime Environment (JRE) 1.2.2.06 (Linux only) or JRE 1.2.2.07 (HP-UX only)
•
Apache Web Server 1.3.12
•
Microsoft FrontPage 2000 Server Extensions
•
IBM DB2 runtime client 6.2 and 7.0.1 (IBM AIX and Linux only)
•
dBASE 5 database and samples
•
Merant DataDirect ODBC drivers
•
Merant SequeLink 4.51
7
Chili!Soft ASP 3.6 Product Documentation
With a custom installation, the setup program installs the following items on the target server and
gives you the option to specify their configuration settings:
•
Chili!Soft ASP Server
•
Chili!Soft ASP Administration Console
•
Chili!Beans (optional; not available on Cobalt systems)
•
Java Runtime Environment (JRE) 1.2.2.06 (Linux only) or JRE 1.2.2.07 (HP-UX only)
•
IBM DB2 runtime client 6.2 and 7.0.1 (IBM AIX and Linux only)
•
dBASE 5 database and samples
•
Merant DataDirect ODBC drivers
•
Merant SequeLink 4.51
During a custom installation, rather than installing and configuring a Web server automatically,
setup enables you to specify an installed Web server to run with Chili!Soft ASP.
For more information about what is included in Chili!Soft ASP, see "Installing and Uninstalling
Chili!Soft ASP" in "Chapter 2: Installing and Configuring Chili!Soft ASP." See also the
README file that was installed with your software. You can access it from the Administration
Console by clicking customer support in the left navigation pane (not available on Cobalt RaQ4
and RaQ XTR systems).
Starting with version 3.0, Chili!Soft ASP includes Java support, enabling Java class files to be
used as components by ASP scripts. The setup program also installs sample Java classes and
applications. For more information, see "Accessing Documentation, Samples, and Diagnostics" in
this chapter. For more information about Java support, see "Using Java Objects and Classes" in
"Chapter 4: Building a Chili!Soft ASP Application." Note that a Java Runtime Environment
(JRE) is included only in Chili!Soft ASP for Linux and HP-UX.
In addition to US English, Chili!Soft ASP also includes support for several other languages. For
more information, see "Configuring International Support" in "Chapter 3: Managing Chili!Soft
ASP."
Supported Platforms and Web Servers
Chili!Soft ASP 3.6 supports the following operating systems and Web servers:
Version
Operating Systems
Web Servers
ChiliSoft ASP 3.6A for IBM
AIX
IBM AIX 4.3
Apache 1.3.9, 1.3.12
iPlanet/Netscape 4.0
Zeus Web Server 3.3.7
ChiliSoft ASP 3.6 for Sun
Solaris
Sun Solaris 2.6, 2.7, 2.8
Apache Web Server 1.3.12 DSO, NDSO
Apache Web Server 1.3.14 DSO
8
Chili!Soft ASP 3.6 Product Documentation
Version
Operating Systems
Web Servers
iPlanet/Netscape 4.0, 4.1
Zeus Web Server 3.3.7
ChiliSoft ASP 3.6 for Linux
Red Hat Linux 6.2, 7.0
Apache Web Server 1.3.12 DSO, NDSO
Debian Linux 2.1, 2.2
Apache Web Server 1.3.14 DSO
SuSE Linux 6.4, 7.
Red Hat Secure Server 3.2
Slackware Linux 7.0, 7.1 iPlanet/Netscape Enterprise 4.1
Linux-Mandrake 7.0, 7.1 Zeus Web Server 3.3.7
TurboLinux Server 6.0
ChiliSoft ASP 3.6 for
Cobalt RaQ3
Cobalt OS 5.0
Apache Web Server 1.3.12 DSO, NDSO
Apache Web Server 1.3.14 DSO
Red Hat Secure Server 3.2
iPlanet/Netscape Enterprise 4.1
Zeus Web Server 3.3.7
ChiliSoft ASP 3.6 for
Cobalt RaQ4
Cobalt OS 6.0
Apache Web Server
ChiliSoft ASP 3.6 for
Cobalt RaQ XTR
Cobalt OS 6.5
Apache Web Server
ChiliSoft ASP 3.6 for
HP-UX
HP-UX 11
Apache Web Server 1.3.12 DSO, NDSO
Apache Web Server 1.3.14 DSO
iPlanet/Netscape 4.0, 4.1
Zeus Web Server 3.3.7
What Is ASP?
ASP is a server-side scripting technology developed by Microsoft. It is an open, compile-free
application environment in which you can combine HTML, scripts, and reusable components to
build dynamic and powerful Web applications.
An ASP application consists of ASP pages published on a Web site. ASP pages can contain
HTML code, client-side scripts, and server-side scripts. When a user goes to an ASP page, the
Web server calls the ASP Server, which processes the requested file from top to bottom,
executing any server-side scripts. It then formats a standard Web page and sends the results to the
user’s browser.
Because scripts can run on the server rather than on the client, the Web server can do much of the
work involved in generating the HTML pages sent to browsers. Server-side scripts cannot be
readily copied because only the result of the script is returned to the browser. Users cannot view
the script commands that created the page they are viewing.
Chili!Soft ASP 3.6 Product Documentation
9
ASP was designed as a faster and easier alternative to CGI scripting using Perl or C scripts. ASP
provides an easy-to-learn scripting interface (including native support for both VBScript and
JScript), along with a number of predefined objects that simplify many development tasks, such
as maintaining user state and defining global variables within an application. You can also use
Active-X Data Objects (ADO): components to perform additional functions, among them
accessing ODBC-compliant databases and outputting data to text files.
You can extend ASP scripts by using component object model (COM) components, Java
components, and extensible markup language (XML).
ASP runs as a service of the Web server, and is optimized for multiple processes or multiple
threads and multiple users. This means that ASP is fast and easy to implement. ASP enables you
to separate the design of your Web page from the details of programming access to databases and
applications, so programmers and Web designers can focus exclusively on what they do best.
The following are a few examples of ASP applications:
•
Put your employee handbook online, rather than printing copies that are soon obsolete.
You can even build a self-service application that allows employees to update their own
information online.
•
Connect customer orders from an online storefront to an existing inventory database and
order-processing system.
•
Give visitors a personalized view of information on your Web site, and automatically flag
items that have been added or changed since their last visit.
For more information on ASP in general and Chili!Soft ASP in particular, see the "Why Active
Server Pages?" white paper in "Appendix B: White Papers."
See also:
•
ASP for the HTML Author in this chapter
•
ASP for the Experienced Web Scripter in this chapter
•
ASP for the Web Developer and Programmer in this chapter
•
Chapter 4: Building a Chili!Soft ASP Application
ASP for the HTML Author
For the HTML author, ASP is an easy way to begin creating Web applications. With Common
Gateway Interface (CGI)applications, in order to process user input on the Web server you must
learn a programming language such as Perl or C. With ASP, however, you can collect HTML
form information and pass it to a database by using simple server-side scripts written in VBScript
or Jscript that are embedded directly in your HTML documents. You can use server-side ASP
scripts to store HTML form information in a database, personalize Web sites according to visitor
preferences, or use different HTML features based on the browser.
See also:
•
What Is ASP? in this chapter
•
Chapter 4: Building a Chili!Soft ASP Application
Chili!Soft ASP 3.6 Product Documentation
10
ASP for the Experienced Web Scripter
ASP is language-neutral, so if you are skilled at a scripting language such as VBScript or JScript,
you already know how to use ASP. (Chili!Soft ASP comes with VBScript and JScript scripting
engines.) You can use server-side ASP scripts to store HTML form information in a database,
personalize Web sites according to visitor preferences, or use different HTML features based on
the browser.
See also:
•
What Is ASP? in this chapter
•
Chapter 4: Building a Chili!Soft ASP Application
ASP for the Web Developer and Programmer
If you develop Web applications by using a programming language such as Visual Basic, C++, or
Java, you will appreciate the flexibility of ASP. Besides using scripts to create an engaging
HTML interface for your application, you can also use Component Object Model (COM) or Java
components to encapsulate your application's business logic into reusable modules that you can
call from a script, from another component, or from another program.
See also:
•
What Is ASP? in this chapter
•
Chapter 4: Building a Chili!Soft ASP Application
What Is Chili!Soft ASP?
Chili!Soft ASP is a platform-independent implementation of Microsoft ASP technology. It is the
functional and syntactic equivalent of the ASP technology included with Microsoft Internet
Information Server (IIS). However, unlike the Microsoft implementation, Chili!Soft ASP enables
you to build ASP applications that run on many different platforms, in addition to Windows NT
and IIS. You can build powerful ASP applications that run on all of the popular Web servers
under Sun Solaris, IBM AIX, Cobalt, Hewlett Packard HP-UX, Linux, and Windows NT, with
more platforms coming soon. Chili!Soft Chili!Beans support even enables you to use your Java
objects with ASP applications.
See also:
•
What Is ASP? in this chapter
•
Chili!Soft ASP Features in this chapter
•
Chapter 4: Building a Chili!Soft ASP Application
Chili!Soft ASP Features
Chili!Soft ASP is a platform-independent implementation of ASP. This topic describes three of
its key features: cross-platform support, development ease, and extensibility.
Chili!Soft ASP 3.6 Product Documentation
11
Cross-platform Support: Chili!Soft ASP runs on a wide variety of operating systems and Web
servers. Different versions of Chili!Soft ASP run on Windows, UNIX, and Linux platforms, and
no code changes are necessary to move a Chili!Soft ASP application from one platform to
another. This enables you to:
•
Develop ASP applications on inexpensive Windows NT workstations and deploy them on
the operating system that meets your needs
•
Consolidate multiple Windows NT-based servers onto fewer, more manageable UNIXbased servers
•
Easily develop ASP applications and deploy them on the operating system and Web server
of your choice
Development Ease: Developing applications with Chili!Soft ASP is easy, thanks to its support
for:
•
VBScript and JavaScript scripting languages
•
Built-in state and session management
•
Easy database access
Extensibility: Chili!Soft ASP applications are extensible via technology such as:
•
COM (Chili!Soft Chili!Beans support enables you to use your Java objects with ASP
applications)
•
Enterprise Java Beans (EJB)
•
Common Object Request Broker Architecture (CORBA)
This enables you to encapsulate business logic using powerful programming languages, connect
to transaction and application services provided by third-party application servers, connect to
legacy systems, and re-use existing code.
See also:
•
What Is ASP? in this chapter
•
What Is Chili!Soft ASP? in this chapter
•
Chapter 4: Building a Chili!Soft ASP Application
Chili!Soft ASP 3.6 Product Documentation
12
Chapter 2: Installing and Configuring
Chili!Soft ASP
This chapter describes the basic steps involved in installing Chili!Soft ASP on your server and
enabling users to publish ASP applications. This chapter also tells you how to configure the
server for hosting ASP applications and connecting ASP applications to databases. "Chapter 3:
Managing Chili!Soft ASP" provides detailed information about such topics as changing server
configuration settings, configuring different types of databases, and optimizing server
performance.
Who should read this chapter: System administrators who are responsible for installing,
configuring, and running Chili!Soft ASP.
In this chapter:
•
Installing and Uninstalling Chili!Soft ASP
•
Enabling Publishing
•
Defining ASP Applications on the Server
•
Enabling Database Connections on the Server
Installing and Uninstalling Chili!Soft ASP
This section includes the following topics about installing and uninstalling Chili!Soft ASP:
•
Installing Chili!Soft ASP 3.6.0-P1 for IBM AIX
•
Installing Chili!Soft ASP 3.6 for Sun Solaris
•
Installing Chili!Soft ASP 3.6 for Linux
•
Installing Chili!Soft ASP 3.6 for Cobalt
•
Installing Chili!Soft ASP 3.6 for HP-UX
•
Configuring the Web Server After Installation
•
Uninstalling Chili!Soft ASP
Subsequent sections in this chapter discuss how to enable publishing and perform basic server
configuration so you can get started using Chili!Soft ASP.
Installing Chili!Soft ASP 3.6.0-P1 for IBM AIX
This section describes the basic requirements and procedures for installing Chili!Soft ASP 3.6.0P1 for IBM AIX. Subsequent sections in this chapter discuss how to enable publishing and
perform basic server configuration so that you can get started using Chili!Soft ASP.
For up-to-date information about this product, please consult the README file. Before
installation, you can find it at:
Chili!Soft ASP 3.6 Product Documentation
13
http://www.chilisoft.com/readme/
After installation, you can access the README file from the Chili!Soft ASP Administration
Console, as described in "Viewing the Product README File" in "Chapter 3: Managing
Chili!Soft ASP."
Important Upgrade Information
If you are upgrading from a previous version, the setup program will not preserve your
existing settings. Before beginning the installation, see the README file for instructions.
In this section:
•
Installation Requirements—Chili!Soft ASP for IBM AIX
•
Choosing an Installation Option for IBM AIX
•
Installing the Chili!Soft ASP Bundle for IBM AIX
•
Important Notes About Bundle Installations for IBM AIX
•
Installing a Custom Configuration of Chili!Soft ASP for IBM AIX
•
Important Notes About Custom Installations for IBM AIX
Installation Requirements: Chili!Soft ASP for IBM AIX
This topic lists the hardware and software requirements for running Chili!Soft ASP 3.6.0-P1 for
IBM AIX. It also lists the additional software, such as databases and tools, that Chili!Soft ASP
supports.
Hardware and Software Requirements
This section lists the hardware and software requirements for installing and running Chili!Soft
ASP 3.6.0-P1 for IBM AIX.
Hardware
The minimum hardware configuration required to run Chili!Soft ASP 3.6.0-P1 for IBM AIX is as
follows:
•
128 MB RAM (256-512 recommended)
•
PowerPC processor
•
165 MB free hard disk space
Operating System
You can install Chili!Soft ASP 3.6.0-P1 for IBM AIX on a computer running the following
operating system:
•
IBM AIX 4.3
Software
Chili!Soft ASP 3.6 Product Documentation
14
Perl 5.005_03 or later must be running on the computer to which you are installing Chili!Soft
ASP 3.6.
Web Server
For a custom installation of Chili!Soft ASP 3.6 for IBM AIX, you must be running one of the
following Web servers (the bundle installation automatically installs and configures Apache
1.3.12):
•
Apache 1.3.12, 1.3.14
•
Netscape/iPlanet 4.0
•
Zeus 3.3.8
•
IBM HTTP Server
Supported Software
This section lists additional software that is installed and/or supported by Chili!Soft ASP 3.6 for
IBM AIX.
Database
Chili!Soft ASP 3.6 for IBM AIX includes ODBC drivers for the following databases:
•
DB2*
•
dBase 5
•
Informix 7, 9
•
Microsoft Access** (via SequeLink)
•
Microsoft SQL Server 6.5** (via SequeLink)
•
Microsoft SQL Server 7.0
•
Oracle 8
•
Sybase 11
ODBC drivers are installed automatically by the Chili!Soft ASP setup program. Following
installation, you must configure the ASP Server for the database being used. For more
information, see "Configuring a Database" in "Chapter 3: Managing Chili!Soft ASP."
*Note about DB2 support
In order to configure the ASP Server to connect to a DB2 database, the following
software must be installed on the computer running the ASP Server:
- IBM DB2 Client Application Enabler (CAE) for IBM AIX, version 2.1 or higher
- IBM DB2 Software Development Kit (DB2 SDK) for IBM AIX, version 2.1 or higher
For more information, see "Configuring DB2" in "Chapter 3: Managing Chili!Soft ASP."
Chili!Soft ASP 3.6 Product Documentation
15
** Note about Microsoft Access and Microsoft SQL Server 6.5 support
To provide remote database connectivity with Microsoft Access and Microsoft SQL
Server 6.5 databases, Chili!Soft ASP 3.6 includes the client portion of the Merant
SequeLink 4.51a software. You also must download and install the server portion of this
software from Chili!Soft. For more information, see "Configuring SequeLink" in
"Chapter 3: Managing Chili!Soft ASP."
MainSoft MainWin Win32 Libraries
Chili!Soft ASP 3.6 for IBM AIX includes MainSoft MainWin Win32 Libraries v3.3 (build 68).
Java Runtime Environment
In order to use Chili!Beans, you must have the Java Runtime Environment (JRE) 1.1.8 installed
on the computer running the ASP Server. Chili!Soft ASP 3.6 for IBM AIX does not include this
JRE. You must also enable Java support, as described in "Enabling Java Support" in "Chapter 3:
Managing Chili!Soft ASP." ChiliBeans enables you to use Java class files as components called
from VBScript or JScript. For more information about Chili!Beans, see "Chili!Beans Component
Reference" in "Chapter 5: Developer's Reference."
Microsoft FrontPage 2000 Server Extensions
Microsoft FrontPage 2000 Server Extensions are included in the bundle installation of Chili!Soft
ASP 3.6. They provide services to the Web server that work in conjunction with Chili!Soft ASP
to provide FrontPage functionality to computers that are not running Windows NT or Windows
2000 and Internet Information Services (IIS). For more information, see "Enabling FrontPage
Publishing" in "Chapter 3: Managing Chili!Soft ASP."
See also:
Installing Chili!Soft ASP 3.6.0-P1 for IBM AIX in this chapter
Uninstalling Chili!Soft ASP in this chapter
Choosing an Installation Option for IBM AIX
The setup program for Chili!Soft ASP 3.6.0-P1 for IBM AIX takes you through all of the steps
required to install the software. It provides two installation options, which are described in this
topic: a bundle installation and a custom installation.
•
Bundle installation. This is the easiest way to install Chili!Soft ASP. With a bundle
installation, the setup program automatically installs and configures the following
components on the target server:
Chili!Soft ASP Server
Chili!Soft ASP Administration Console
Chili!Beans (optional)
Apache Web Server 1.3.12
Microsoft FrontPage 2000 Server Extensions
Chili!Soft ASP 3.6 Product Documentation
16
dBase 5 database and samples
IBM DB2 Client Application Enabler (CAE) 7.0.1*
*Note
The DB2 Client Application Enabler (CAE) 7.0.1 is automatically installed, and it is
installed only if you do not have a DB2 CAE of any version already installed.
For more information about performing a bundle installation, see "Installing the Chili!Soft ASP
Bundle for IBM AIX" in this chapter.
Note
Chili!Soft provides technical support for configuring supported Web servers—such as
Apache and iPlanet)—so that they run with Chili!Soft ASP. In addition, Chili!Soft
provides technical support for the Apache Web Server that is installed with the Chili!Soft
ASP bundle. However, in order to receive technical support for the bundled Apache Web
Server, you must use the Chili!Soft ASP Administration Console to manage it, rather
than editing the Web server configuration files directly.
•
Custom installation. With this option, the setup program installs the following
components on the target server:
Chili!Soft ASP Server
Chili!Soft ASP Administration Console
Chili!Beans (optional)
The setup program gives you the option to either specify the configuration settings or accept the
default configuration settings. The configuration settings you specify during a custom installation
can have serious consequences for your server environment. For instructions on performing this
installation, see "Installing a Custom Configuration of Chili!Soft ASP for IBM AIX" in this
chapter.
For up-to-date information about Chili!Soft ASP 3.6 and its components, see the README file
that was installed with your software.
See also:
Installing Chili!Soft ASP 3.6 for IBM AIX in this chapter
Uninstalling Chili!Soft ASP in this chapter
Installing the Chili!Soft ASP Bundle for IBM AIX
This topic describes the steps to install the Chili!Soft ASP 3.6.0-P1 bundle for IBM AIX. For
more information about a bundle installation, see "Choosing an Installation Option for IBM AIX"
in this chapter.
Before you begin, make sure you meet the following requirements:
•
You must be logged in as root.
Chili!Soft ASP 3.6 Product Documentation
17
•
If you are downloading Chili!Soft ASP 3.6.0-P1 from the Web, in order to extract the
installation files, you must have 45 MB of hard disk space available to install the version
that does not include the DB2 Client Application Enabler (CAE) or 225 MB of hard disk
space available to install the version that includes the DB2 CAE.
•
Your hardware and software must meet the requirements listed in "Installation
Requirements—Chili!Soft ASP for IBM AIX" in this chapter.
•
You need to know your product serial number. Chili!Soft ASP requires a valid serial
number in order to run. If you downloaded the product from the Web, you should have
received an e-mail message that included your serial number. If you are installing this
product from a CD-ROM, the serial number is printed on the CD-ROM case. If you are
installing a trial version from a CD-ROM, you must obtain a serial number at:
http://www.chilisoft.com/register
•
The setup program for Chili!Soft ASP 3.6.0-P1 for IBM AIX does not upgrade previous
versions. If you have a previous installation of Chili!Soft ASP, see the README file or
go to the Chili!Soft Web site for more information about preserving your settings, at:
http://www.chilisoft.com/support/
•
You will need to specify a username and password for accessing the Chili!Soft ASP
Administration Console. Be sure to specify a password that you can remember, or else
plan to store it in a secure location. If you forget your password, you can run the admtool
utility and set a new password, as described in "Configuring Usernames and Passwords"
in "Chapter 3: Managing Chili!Soft ASP."
•
To enable Chili!Beans, you must have a Java Runtime Environment (JRE) version
between 1.1.7 and 1.2.1_03a installed on the target Web server. Chili!Beans enables you
to access Java objects and classes from an ASP script. For more information about
Chili!Beans, see "Chili!Beans Component Reference" in "Chapter 5: Developer's
Reference."
•
If FrontPage Server Extensions are already installed on your computer, the Chili!Soft ASP
setup program cannot properly install and configure the FrontPage 2000 Server
Extensions that are included in the bundle installation. If you already have FrontPage
Server Extensions installed on your server, you must take the following steps before
installing the Chili!Soft ASP bundle:
When FrontPage Server Extensions are already installed on your computer
1. Move the directory /usr/local/frontpage to a different location.
2. Create a symbolic link at /usr/local/frontpage that points to /usr/local/chilisoft/frontpage by
running the following command:
#> /usr/bin/ln -sf /usr/local/chilisoft/frontpage
/usr/local/frontpage
3.
Set file permissions by running the following command:
#> usr/local/chilisoft/frontpage/version4.0/set_default_perms.sh
Chili!Soft ASP 3.6 Product Documentation
18
To install the Chili!Soft ASP bundle for IBM AIX, use the following procedure:
To install the Chili!Soft ASP bundle for IBM AIX
1. If you are installing Chili!Soft ASP from a CD-ROM, skip this step and go to step 2. If you
are downloading Chili!Soft ASP from the Web, download the casp-3.6.0-p1-aix.tar file to a
temporary directory, and then extract the installation files by using the following command:
#> tar -xvf casp-3.6.0-p1-aix.tar
This step creates the following files in the temporary directory, which you can delete after
completing the installation:
A README file containing important product information
The install.sh installation script
A package/EULA file containing the end-user license agreement
A package/directory containing the files required to install Chili!Soft ASP
2. Run the install.sh script by using the following command. For downloaded versions, this
script is located in the temporary directory you created in the previous step. For CD-ROM
versions, this script is located on your installation CD-ROM.
#> ./install.sh
3. Review the End-User License Agreement (EULA) that displays. Enter yes if you agree to its
conditions. You must type the entire word, "yes."
– or –
Enter no if you do not agree. If you enter no, the Chili!Soft ASP setup program aborts the
installation.
4. On the next screen, enter 1 to select the Bundle Installation option.
5. On the next screen, press Enter if you want to install the Apache Web Server to port 80.
– or –
Enter a different port number for the Apache Web Server to use.
6. On the next screen, press Enter to accept the default administration username ("admin").
– or –
Enter a different administration username.
7. When prompted, enter an administration password and, when prompted, re-enter it to confirm
the password.
8. On the next screen, enter y (yes) if you know the product serial number. If you do not know
the serial number, enter n. Chili!Soft ASP will not run without a serial number, so if you
enter n, the setup program cancels the installation.
9. When prompted, enter the product serial number.
10. On the next screen, press Enter to accept the default language ("English – US").
– or –
Chili!Soft ASP 3.6 Product Documentation
19
Enter the number of a language shown in the list.
11. On the next screen, enter y to enable Chili!Beans support.
– or –
Enter n if you do not want to enable Chili!Beans support.
12. On the next screen, enter the absolute path name of your Java Runtime Environment (JRE).
The setup program automatically installs the Chili!Soft ASP bundle to the following directory
and performs basic configuration of the software:
/usr/local/chilisoft/
If you did not already have an IBM DB2 Client Application Enabler (CAE) installed on your
computer when you ran setup, the DB2 CAE 7.0.1 is installed at the following location (this only
applies for installations from a CD-ROM or from a version that includes the DB2 client if you
downloaded Chili!Soft ASP 3.6.0-P1 from the Chili!Soft Web site):
/usr/lpp/db2_07_01
Before running a bundle installation of Chili!Soft ASP, see "Important Notes About Bundle
Installations for IBM AIX" in this chapter.
For more information about running and configuring Chili!Soft ASP, see "Chapter 3: Managing
Chili!Soft ASP."
See also:
Installing Chili!Soft ASP 3.6 for IBM AIX in this chapter
Uninstalling Chili!Soft ASP in this chapter
Important Notes about Bundle Installations for IBM AIX
Before running a bundle installation of Chili!Soft ASP 3.6.0-P1 for IBM AIX, please review the
following information:
1. You use the Chili!Soft ASP Administration Console to start and stop the Chili!Soft ASP
Server and to change configuration settings. You can access the Administration Console from
the following URL:
http://[HOSTNAME]:[PORT]
where [HOSTNAME] is the hostname of the Web server configured to run with Chili!Soft
ASP, and [PORT] is the port on which the Administration Console is configured to run (5100
by default).
For more information about the configuring and running Chili!Soft ASP, see "Chapter 3:
Managing Chili!Soft ASP."
2. When finished installing Chili!Soft ASP 3.6, it is a good idea to use the diagnostic
applications to verify that your installation is functioning correctly. You can access the
diagnostics from the following URL:
http://[HOSTNAME]/caspsamp/diagnostics.htm
Chili!Soft ASP 3.6 Product Documentation
20
where [HOSTNAME] is the hostname of the Web server configured to run with Chili!Soft
ASP.
3. To use Chili!Beans, you must enable Java support, as described in "Enabling Java Support"
in "Chapter 3: Managing Chili!Soft ASP." Chili!Beans enables you to access Java objects and
classes from an ASP script. For more information about Chili!Beans, see "Chili!Beans
Component Reference" in "Chapter 5: Developer's Reference."
4. Important summary information about the installation is located in the following file:
/usr/local/chilisoft/casp/logs/install_summary
It is a good idea to print this information for future reference.
5. If you did not already have an IBM DB2 Client Application Enabler (CAE) installed on your
computer when you ran setup, the DB2 CAE 7.0.1 is installed at the following location (this
only applies for installations from a CD-ROM or from a version that includes the DB2 client
if you downloaded Chili!Soft ASP 3.6.0-P1 from the Chili!Soft Web site):
/usr/lpp/db2_07_01
Before you can connect to the DB2 database, you must first configure a DSN, as described in
"Configuring Data Source Names (DSNs)" in "Chapter 3: Managing Chili!Soft ASP." Note that
you must use the cataloged name of the database for the DSN name. Chili!Soft ASP
automatically sets the correct database parameters and associates them with the cataloged name
of the database. In addition to configuring a DSN for DB2, you must load the DB2 profile as
described in "Loading DB2 Profiles" in "Chapter 3: Managing Chili!Soft ASP."
See also:
Installing Chili!Soft ASP 3.6 for IBM AIX in this chapter
Uninstalling Chili!Soft ASP in this chapter
Installing a Custom Configuration of Chili!Soft ASP for IBM AIX
This topic describes the steps to install a custom configuration of Chili!Soft ASP 3.6.0-P1 for
IBM AIX. For more information about a custom installation, see "Choosing an Installation
Option for IBM AIX" in this chapter.
The configuration options you specify when installing a custom configuration of Chili!Soft ASP
can have serious consequences for your server environment. Before you begin, make sure you
meet the following requirements:
•
You must be logged in as root.
•
If you are downloading Chili!Soft ASP 3.6.0-P1 from the Web, in order to extract the
installation files, you must have 45 MB of hard disk space available to install the version
that does not include the DB2 Client Application Enabler (CAE) or 225 MB of hard disk
space available to install the version that includes the DB2 CAE.
•
Your hardware and software must meet the requirements listed in "Installation
Requirements—Chili!Soft ASP for IBM AIX" in this chapter.
Chili!Soft ASP 3.6 Product Documentation
•
21
You need to know your product serial number. Chili!Soft ASP requires a valid serial
number in order to run. If you downloaded the product from the Web, you should have
received an e-mail message that included your serial number. If you are installing this
product from a CD-ROM, the serial number is printed on the CD-ROM case. If you are
installing a trial version from a CD-ROM, you must obtain a serial number at:
http://www.chilisoft.com/register
•
To enable Chili!Beans, you must have a Java Runtime Environment (JRE) version
between 1.1.7 and 1.2.1_03a installed on the target Web server. Chili!Beans enables you
to access Java objects and classes from an ASP script. For more information about
Chili!Beans, see "Chili!Beans Component Reference" in "Chapter 5: Developer's
Reference."
•
To configure Chili!Soft ASP to work with a Web server that is already installed on the
target computer, you must shut down the Web server, and prepare to provide the following
information:
Absolute path name of the Web server main configuration file (for example,
/usr/HTTPServer/conf/httpd.conf)
Absolute path name of the Web server binary (for example, /usr/HTTPServer/bin/httpd)
Web server version (for example, 1.3.12)
Web server type (for example, Apache)
Web server port number (for example, 80)
Web server root directory (for example, /usr/HTTPServer)
•
If you install Chili!Soft ASP to run with an Apache Web Server that does not support
Dynamic Shared Objects (DSO), you must take additional steps. Following installation,
you must manually link the Web server to Chili!Soft ASP and then recompile it, as
described in "Configuring a Non-DSO Apache Web Server" in this chapter. If your
Apache Web Server supports DSO, there are no additional steps to take: Chili!Soft ASP
includes pre-built DSO modules that automatically link to your Web server.
•
You need to know whether you want to run Chili!Soft ASP in multi-threaded or multiprocess mode. For more information, see "Running in Multi-process Mode" and "Running
in Multi-threaded Mode" in "Chapter 3: Managing Chili!Soft ASP."
•
If you choose to customize settings for the Chili!Soft ASP Administration Console, you
will need to specify a username and password for accessing it. Be sure to specify a
password that you can remember, or else plan to store it in a secure location. If you forget
your password, you can run the admtool utility and set a new password, as described in
"Configuring Usernames and Passwords" in "Chapter 3: Managing Chili!Soft ASP." If
you do not choose the customize settings option, the username is set as "admin" and the
password as "root." To protect the security of your server, you should run the admtool and
change these as soon as possible following installation.
•
When configuring the Zeus Web Server to run with Chili!Soft ASP 3.6, do not specify the
Web server hostname as the fully qualified domain name (or "server address"). If you do,
Chili!Soft ASP 3.6 Product Documentation
22
the Test DSN feature of the Administration Console will not work. Instead, use the
hostname only.
For example, do not use this: hostname.domain.com
Instead, use this: hostname
•
The setup program for Chili!Soft ASP 3.6 for IBM AIX does not upgrade previous
versions. For more information about preserving your settings from a previous installation
of Chili!Soft ASP, see the product README file or go to:
http://www.chilisoft.com/support/
To install a custom configuration of Chili!Soft ASP for IBM AIX
1. If you are downloading Chili!Soft ASP from the Web, make sure you have 45 MB of hard
disk space available to install the version that does not include the DB2 Client Application
Enabler (CAE) or 225 MB of hard disk space available to install the version that includes the
DB2 CAE. (The DB2 CAE is installed only with a bundle installation.)
2. If you are installing Chili!Soft ASP from a CD-ROM, skip this step. If you are downloading
Chili!Soft ASP from the Web, download the casp-3.6.0-p1-aix.tar file to a temporary
directory, and then extract the installation files by using the following command:
#> tar -xvf casp-3.6.0-p1-aix.tar
This step creates the following files, which you can delete after completing the installation:
A README file containing important product information
The install.sh installation script
A package/EULA file containing the end-user license agreement
A package/directory containing files required to install Chili!Soft ASP
3. Run the install.sh script by using the following command. For downloaded versions, this
script is located in the temporary directory you created in the previous step. For CD-ROM
versions, this script is located on your installation CD-ROM.
#> ./install.sh
4. Review the End-User License Agreement (EULA) that displays. Enter yes if you agree with
its conditions. You must type the entire word "yes."
– or –
Enter no if you do not agree. If you enter no, the Chili!Soft ASP setup program cancels the
installation.
5. On the next screen, enter 2 to select a Custom Installation.
6. On the next screen, press Enter to accept the default Chili!Soft ASP installation directory
(/opt/casp).
– or –
Chili!Soft ASP 3.6 Product Documentation
23
Enter the absolute path name of the installation directory you want. The installation directory
you specify cannot already exist. It is a good idea to make a note of the installation directory
path name so that you can easily find the Chili!Soft ASP files at a later time.
7. In the previous step, if you specified a directory that already exists on your server, the setup
program cancels the installation. You must restart setup and specify an installation directory
that does not exist in order to complete the installation.
8. On the next screen, enter y (yes) if you know the product serial number.
– or –
If you do not know the serial number, enter n. Chili!Soft ASP will not run without a serial
number, so if you enter n, the setup program cancels the installation.
9. When prompted, enter the product serial number.
10. On the next screen, press Enter to accept the default language (English – US).
– or –
Enter the number of a language shown in the list.
11. On the next screen, enter y to enable Chili!Beans support.
– or –
Enter n if you do not want to enable Chili!Beans support.
12. On the next screen, enter the absolute path name of your Java Runtime Environment (JRE or
JDK 1.1.8).
13. The next screen provides options for choosing the Web server to configure with Chili!Soft
ASP. If you want the setup program to search your system and generate a list of installed
Web servers from which to select, enter the number of the search option you want (1, 2, or 3).
If you select one of these search options, skip to step 17.
– or –
If you want to skip this search and provide information about the Web server, enter 4 (Don't
search). If you choose option 4 (Don’t search), follow the instructions in step 15.
14. If you want to provide information about the Web server to configure, on the next screen,
enter 1 (Specify the Webserver), and then follow the instructions in step 15.
– or –
If you want the setup program to search for installed Web servers from which to select, enter
2 (Refresh the Webserver list), and then follow the instructions in step 13.
– or –
If you do not want to configure a Web server during installation, enter 3 (Do not configure a
Webserver), and then go to step 19. If you choose this option, the first time you open the
Chili!Soft ASP Administration Console, you will be prompted to configure the ASP Server
and a Web server.
Chili!Soft ASP 3.6 Product Documentation
24
15. On the next screen, enter the number of the type of Web server to configure: 1 for Apache, 2
for Netscape, 3 for Zeus, or 4 for IBM HTTP Server and go to the next step.
– or –
To cancel the user-specified Web server configuration, enter 5. If you choose this option, the
setup program returns you to the previous screen. From this screen you can choose another
option, as described in step 14.
16. At the prompts, enter the requested information about the Web server, and go to the next step.
17. On the next screen, enter the number of the Web server you want the setup program to
configure to run with Chili!Soft ASP, and go to the next step.
– or –
To provide information about the Web server to configure, enter the number for the option,
Specify the Webserver. If you choose this option, follow the instructions in step 15.
– or –
To perform another search for installed Web servers, enter the number for the option,
Refresh the webserver list. If you choose this option, follow the instructions in step 13.
– or –
If you do not want to configure a Web server during installation, enter the number for the
option, Do not configure a Webserver, and then go to step 19. If you choose this option, the
first time you open the Chili!Soft ASP Administration Console, you will be prompted to
configure the ASP Server and a Web server.
18. On the next screen, verify the information that the setup program displays about your Web
server. If the information is incorrect, the Chili!Soft ASP installation could fail. In this event,
you can run the installation script again. If you do this, it is recommended that you first run
the uninstall script, as described in "Uninstalling Chili!Soft ASP" in this chapter. If the
information on the screen is correct, enter y (yes), and go to the next step.
– or –
If the information is incorrect, enter n (no). The setup program returns you to the previous
screen. For this screen, follow the instructions in step 17.
19. On the next screen, choose a configuration option for the ASP Server. Enter 1 to choose a
default configuration, and go to the next step.
– or –
Enter 2 to choose a custom configuration, and enter the following information at the prompts:
Would you like me to restart this Web Server for you? Enter y (yes) if you want the
setup program to automatically restart the Web server after completing Chili!Soft ASP
installation, or enter n (no) if you do not want this.
Choose a mode. Enter the number of the mode in which you want to run the ASP
Server, or enter 3 for more information about this option.
1. Multi-threaded
Chili!Soft ASP 3.6 Product Documentation
25
2. Multi-process
3. More information
Enable samples on this Web server? Enter y (yes) if you want the setup program to
install and configure the Chili!Soft ASP samples on your Web server, or n (no) if you do
not want this.
Enable documentation on this Web server? Enter y (yes) if you want the setup
program to install and configure the Chili!Soft ASP documentation on your Web server,
or n (no) if you do not want this. If you enter n, the documentation will be available
from the Administration Console, but not from the Chili!Soft ASP Start Page.
Start the Chili!Soft ASP on system boot? Enter y (yes) if you want the setup program
to start Chili!Soft ASP automatically each time you start the computer, or type n (no) if
you do not want this.
Would you like to start this Chili!Soft ASP Server? Enter y (yes) if you want the
setup program to start Chili!Soft ASP automatically immediately after you finish
installing it, or n (no) if you do not want this.
– or –
Enter 3 to choose another Web server to configure for Chili!Soft ASP, and follow the
instructions in step 13.
20. On the next screen, select a configuration option for the Administration Console. When you
choose Auto-Select/Default, the setup program configures the console using default settings.
With this option, it specifies the username as "admin" and the password as "root." To protect
the security of your server, it is highly recommended that you change these settings as soon
as possible. For information about doing this, see "Configuring Usernames and Passwords" in
"Chapter 3: Managing Chili!Soft ASP."
If you choose Customize Settings, enter the following information at the prompts:
Administration Console port number: Enter the number of the port on which the Web
server should listen for requests for the Administration Console or press Enter to accept
the default.
Automatically start the Administration Console on system startup: Enter y (yes) if
you want the Chili!Soft ASP Administration Console to start automatically each time
you start the computer, or n (no) if you do not want this.
Type the username: Enter the administrator username.
New password: Enter the administrator password, which is required for accessing the
Administration Console. It is a good idea to make note of this password, because you
cannot access the Administration Console without providing it.
Confirm password: Re-enter the password.
21. The next screen provides summary information about your Administration Console
configuration, including the URL for accessing it. It is a good idea to make a note of this
Chili!Soft ASP 3.6 Product Documentation
26
information or else print this screen for future reference. When finished, press Enter to
complete the installation.
The setup program then completes the installation and writes a summary file to:
[C-ASP_INSTALL_DIR]/logs/install_summary
where [C-ASP_INSTALL_DIR] is the directory in which you installed Chili!Soft ASP
(/usr/local/casp by default).
Before running a custom installation of Chili!Soft ASP, see "Important Notes About Custom
Installations for IBM AIX" in this chapter.
For information about the changes the setup program makes to your Web server configuration
files, see "Changes to Netscape Web Server Configuration Files" or "Changes to Apache Web
Server Configuration Files" in this chapter, as appropriate.
See also:
Installing Chili!Soft ASP 3.6 for IBM AIX in this chapter
Uninstalling Chili!Soft ASP in this chapter
Important Notes About Custom Installations for IBM AIX
Before running a custom installation of Chili!Soft ASP 3.6.0-P1 for IBM AIX, please review the
following information:
1. You use the Chili!Soft ASP Administration Console to start and stop the Chili!Soft ASP
Server and to change configuration settings. You can access the Administration Console by
typing the following URL in your Web browser address bar:
http://[HOSTNAME]:[PORT]
where [HOSTNAME] is the valid DNS name or IP address of the Apache Web Server
running the Chili!Soft ASP Administration Console and [PORT] is the port on which the
Administration Console is configured to run (5100 by default).
2. If you chose the default configuration for the Administration Console, the setup program
configured the username as "admin" and the password as "root." To protect the security of
your server, it is highly recommended that you change the username and password as soon as
possible. For more information, see "Configuring Usernames and Passwords" in "Chapter 3:
Managing Chili!Soft ASP."
3. The Chili!Soft ASP setup program makes certain changes to the configuration files for the
associated Web server. For more information, see "Changes to Netscape Web Server
Configuration Files" or "Changes to Apache Web Server Configuration Files" in this chapter,
as appropriate.
4. If you installed Chili!Soft ASP to run with an Apache Web Server that does not support
Dynamic Shared Objects (DSO), you must manually link the Web server to Chili!Soft ASP
and then recompile it, as described in "Configuring a Non-DSO Apache Web Server" in this
chapter. If your Apache Web Server supports DSO, there are no additional steps to take:
Chili!Soft ASP includes pre-built DSO modules that automatically link to your Web server.
Chili!Soft ASP 3.6 Product Documentation
27
5. To use Chili!Beans, you must enable Java support, as described in "Enabling Java Support"
in "Chapter 3: Managing Chili!Soft ASP." Chili!Beans enables you to access Java objects and
classes from an ASP script. For more information about Chili!Beans, see "Chili!Beans
Component Reference" in "Chapter 5: Developer's Reference."
6. Important summary information about the installation is located in the following file:
[C-ASP_INSTALL_DIR]/logs/install_summary
where [C-ASP_INSTALL_DIR] is the directory in which you installed Chili!Soft ASP
(/usr/local/casp by default).
It is a good idea to print this information for future reference.
7. When finished installing Chili!Soft ASP 3.6.0-P1, it is a good idea to use the diagnostic
applications to verify that your installation is functioning correctly. You can access the
diagnostics from the following URL:
http://[HOSTNAME]/caspsamp/diagnostics.htm
where [HOSTNAME] is the hostname of the Web server configured to run with Chili!Soft
ASP.
See also:
Installing Chili!Soft ASP 3.6 for IBM AIX in this chapter
Uninstalling Chili!Soft ASP in this chapter
Installing Chili!Soft ASP 3.6 for Sun Solaris
The topics in this section describe the requirements and procedures for installing Chili!Soft ASP
3.6 for Sun Solaris. For up-to-date information about this product, see the README file included
with your software. You can access the README file from the Chili!Soft ASP Administration
Console, as described in "Viewing the Product README File" in "Chapter 3: Managing
Chili!Soft ASP."
Important Upgrade Information
Chili!Soft ASP 3.6.0-P1 for Sun Solaris automatically upgrades many of your settings
from an existing installation of Chili!Soft ASP 3.4.1. You can obtain this version from
the Chili!Soft Web site at:
http://www.chilisoft.com/upgrades/solaris/
If you have already purchased Chili!Soft ASP 3.6 for Sun Solaris, you can obtain this
version free of charge.
Be aware that following installation, you will need to take additional steps to finish the
configuration before running Chili!Soft ASP 3.6. For more information about performing
this upgrade see "Upgrading Chili!Soft ASP for Sun Solaris" in this chapter.
If you are upgrading from a version other than Chili!Soft ASP 3.4.1, the setup program
will not preserve your existing settings. Before beginning the installation, go to the
Chili!Soft Web site for information about performing an upgrade, at:
Chili!Soft ASP 3.6 Product Documentation
28
http://www.chilisoft.com/support/
In this section:
•
Installation Requirements: Chili!Soft ASP for Sun Solaris
•
Choosing an Installation Option for Sun Solaris
•
Installing the Chili!Soft ASP Bundle for Sun Solaris
•
Installing a Custom Configuration of Chili!Soft ASP for Sun Solaris
•
Upgrading Chili!Soft ASP for Sun Solaris
Installation Requirements: Chili!Soft ASP for Sun Solaris
This topic lists the hardware and software requirements for running Chili!Soft ASP 3.6 for Sun
Solaris. It also lists the additional software, such as databases and tools, that Chili!Soft ASP
supports.
Hardware and Software Requirements
This section lists the hardware and software required to install and run Chili!Soft ASP 3.6 for Sun
Solaris on your server.
Hardware
Your hardware configuration must meet the following minimum requirements:
•
128 MB RAM (256 MB recommended)
•
SPARC processor
•
200 MB free hard disk space (bundle Installation)
•
130 MB free hard disk space (custom Installation)
Operating System
You can install Chili!Soft ASP 3.6 for Sun Solaris on a computer running one of the following
operating systems:
•
Sun Solaris 2.6, 2.7, or 2.8
Web Server
For a custom Installationof Chili!Soft ASP 3.6 for Sun Solaris, you must be running one of the
following Web servers (the bundle Installationincludes Apache Web Server 1.3.12 DSO):
•
Apache Web Server 1.3.12 DSO, NDSO
•
Apache Web Server 1.3.14 DSO
•
iPlanet/Netscape 4.0, 4.1 SP5
•
Zeus 3.3.7, 3.3.8
Chili!Soft ASP 3.6 Product Documentation
29
Software
Perl 5.005_03 or later must be running on the computer to which you are installing Chili!Soft
ASP 3.6.
Important Note
Perl 5.6 does not work with the Chili!Soft ASP setup program. It causes setup to fail.
Supported Software
This section lists additional software that is supported and/or installed by Chili!Soft ASP 3.6 for
Sun Solaris.
Database
Chili!Soft ASP 3.6 for Sun Solaris includes ODBC drivers for the following databases:
•
dBase 5
•
Informix 7, 9 (Solaris 2.6, 2.7 only)
•
Microsoft Access (via SequeLink--see note below*)
•
Microsoft SQL Server 6.5 (via SequeLink--see note below*)
•
Microsoft SQL Server 7.0
•
Oracle 8
•
Sybase 11
ODBC drivers are installed automatically by the Chili!Soft ASP setup program. Following
installation, you must configure the drivers for the data source being used. For more information,
see "Configuring a Database" in "Chapter 3: Managing Chili!Soft ASP."
* Note
To provide remote database connectivity with Microsoft Access and Microsoft SQL
Server 6.5 databases, Chili!Soft ASP 3.6 ships with the client portion of the Merant
SequeLink 4.51a software. You also must download and install the server portion of this
software from Chili!Soft. For more information, see "Configuring SequeLink" in
"Chapter 3: Managing Chili!Soft ASP."
MainSoft MainWin Win32 Libraries
Chili!Soft ASP 3.6 for Sun Solaris includes MainSoft MainWin Win32 Libraries v3.4 (build 68)
on Solaris 2.6, 2.7, and 2.8.
Java Runtime Environment
Chili!Soft ASP 3.6 supports, but does not include, the Java Runtime Environment (JRE) that is
required for Chili!Beans. Chili!Beans enables you to use Java class files as components called
from VBScript or JScript. To enable Chili!Beans, you must have a version of JRE between 1.1.7
Chili!Soft ASP 3.6 Product Documentation
30
and 1.2.1_03a installed on the computer running the ASP Server. You must also enable Java
support, as described in "Enabling Java Support" in "Chapter 3: Managing Chili!Soft ASP." For
more information about Chili!Beans, see "Chili!Beans Component Reference" in "Chapter 5:
Developer's Reference."
Microsoft FrontPage 2000 Server Extensions
Microsoft FrontPage 2000 Server Extensions are included in the bundle installation of Chili!Soft
ASP 3.6. They provide services to the Web server that work in conjunction with Chili!Soft ASP
to provide FrontPage functionality to computers that are not running Microsoft Windows NT or
Windows 2000 and Internet Information Services (IIS). For more information, see "Enabling
FrontPage Publishing" in "Chapter 3: Managing Chili!Soft ASP."
See also:
Installing Chili!Soft ASP 3.6 for Sun Solaris in this chapter
Choosing an Installation Option for Sun Solaris in this chapter
Installing a Custom Configuration of Chili!Soft ASP for Sun Solaris in this chapter
Installing the Chili!Soft ASP Bundle for Sun Solaris in this chapter
Choosing an Installation Option for Sun Solaris
The Chili!Soft ASP setup program takes you through all of the steps required to install the
Chili!Soft ASP 3.6 software on Sun Solaris. It provides the following two installation options:
•
Bundle installation. This is the easiest way to install Chili!Soft ASP. However, if you are
performing an upgrade, you should choose a custom installation. With a bundle
installation, the setup program automatically installs and configures the following
components on the target server:
Chili!Soft ASP Server
Chili!Soft ASP Administration Console
Chili!Beans support
Apache Web Server 1.3.12
Microsoft FrontPage 2000 Server Extensions
dBase 5 database and samples
For more information about performing a bundle installation, see "Installing the Chili!Soft ASP
Bundle for Sun Solaris" in this chapter.
•
Custom installation. With this option, the setup program installs the following
components on the target server:
Chili!Soft ASP Server
Chili!Soft ASP Administration Console
Chili!Beans
Chili!Soft ASP 3.6 Product Documentation
31
Apache Web Server 1.3.12
The setup program gives you the option to either specify the configuration options or accept the
default configuration settings. The configuration settings you specify during a custom installation
can have serious consequences for your server environment. For more information about
performing this installation, see "Installing a Custom Configuration of Chili!Soft ASP for
SunSolaris" in this chapter.
For up-to-date information about Chili!Soft ASP 3.6 and its components, see the README file
that was installed with your software. You can access it from the Administration Console by
clicking customer support in the left navigation pane.
See also:
Installing Chili!Soft ASP 3.6 for Sun Solaris in this chapter
Installation Requirements—Chili!Soft ASP for Sun Solaris in this chapter
Uninstalling Chili!Soft ASP in this chapter
Installing the Chili!Soft ASP Bundle for Sun Solaris
This topic describes the steps to install the Chili!Soft ASP 3.6 bundle for Sun Solaris. For more
information about a bundle installation, see "Choosing an Installation Option for Sun Solaris" in
this chapter.
Before you begin, make sure you meet the following requirements:
•
You are logged in as root.
•
If you are downloading Chili!Soft ASP from the Web, you must have 45 MB of hard disk
space available in order to extract the installation files.
•
Your hardware and software meet the requirements listed in "Installation Requirements—
Chili!Soft ASP for Sun Solaris" in this chapter.
•
You know your product serial number. Chili!Soft ASP requires a valid serial number in
order to run. If you downloaded the product from the Web, you should have received an email message that included your serial number. If you are installing this product from a
CD-ROM, the serial number is printed on the CD-ROM case. If you are installing a trial
version from a CD-ROM, you must obtain a serial number at:
http://www.chilisoft.com/register
•
You know what language you want Chili!Soft ASP to support. The options are US
English, British English, Dutch, French, German, Japanese Shift-JIS, Spanish, and
Swedish. If you want, you can change the language after installation by using the
Chili!Soft ASP Administration Console, as described in "Configuring International
Support" in "Chapter 3: Managing Chili!Soft ASP."
•
You will need to specify a username and password for the Chili!Soft ASP Administration
Console. Be sure to specify a password that you can remember, or else plan to store it in a
secure location. If you forget your password, you can run the admtool utility and set a new
Chili!Soft ASP 3.6 Product Documentation
32
password, as described in "Configuring Usernames and Passwords" in "Chapter 3:
Managing Chili!Soft ASP."
•
If FrontPage Server Extensions are already installed on your computer, the Chili!Soft ASP
setup program cannot properly install and configure the FrontPage 2000 Server
Extensions that are included in the bundle installation. If you already have FrontPage
Server Extensions installed, you must uninstall them before installing the Chili!Soft ASP
3.6 bundle.
•
To enable Chili!Beans, you must have a Java Runtime Environment (JRE) version
between 1.1.7 and 1.2.1_03a installed on the target Web server. Chili!Beans enables you
to access Java objects and classes from an ASP script. For more information about
Chili!Beans, see "Chili!Beans Component Reference" in "Chapter 5: Developer's
Reference."
•
For bundle installations, if you have a previous installation of Chili!Soft ASP, the setup
program will not upgrade your existing settings. Before beginning the installation, go to
the Chili!Soft Web site for more information about upgrading your settings, at:
http://www.chilisoft.com/support/
To install the Chili!Soft ASP 3.6 bundle for Sun Solaris, use the following procedure.
To install the Chili!Soft ASP bundle for Sun Solaris
1. If you are installing Chili!Soft ASP from a CD-ROM, skip this step and go to step 2. If you
are downloading Chili!Soft ASP from the Web, download the casp-3.6.0-solaris.tar file to a
temporary directory, and then extract the installation files by using the following command:
#> tar -xvf casp-3.6.0-solaris.tar
This step creates the following files in the temporary directory, which you can delete after
completing the installation:
A README file containing important product information
The install.sh installation script
A package/EULA file containing the end-user license agreement
A package/directory containing the files required to install Chili!Soft ASP
2. Run the install.sh script by using the following command. For downloaded versions, this
script is located in the temporary directory you created in the previous step. For CD-ROM
versions, this script is located on your installation CD-ROM.
#> ./install.sh
3. Review the End-User License Agreement (EULA) that displays. Enter yes if you agree to its
conditions. You must type the entire word, "yes."
– or –
Enter no if you do not agree. If you enter no, the Chili!Soft ASP setup program aborts the
installation.
4. On the next screen, enter 1 to select the Bundle Installation option.
Chili!Soft ASP 3.6 Product Documentation
33
5. On the next screen, press Enter if you want to install the Apache Web Server to port 80.
– or –
Enter a different port number for the Apache Web Server to use.
6. On the next screen, press Enter to accept the default administration username ("admin").
– or –
Enter a different administration username.
7. When prompted, enter an administration password and, when prompted, re-enter it to confirm
the password.
8. On the next screen, enter y (yes) if you know the product serial number. If you do not know
the serial number, enter n. Chili!Soft ASP will not run without a serial number, so if you
enter n, the setup program aborts the installation.
9. When prompted, enter the product serial number.
10. On the next screen, press Enter to accept the default language ("English – US").
– or –
Enter the number of a language shown in the list.
11. On the next screen, enter y to enable Chili!Beans support.
– or –
Enter n if you do not want to enable Chili!Beans support.
12. On the next screen, enter the absolute path name of your Java Runtime Environment.
The setup program automatically installs the Chili!Soft ASP bundle to the following directory
and performs basic configuration of the software:
/usr/local/chilisoft/casp ...\
Before running a bundle installation of Chili!Soft ASP, see "Important Notes About Bundle
Installations for Sun Solaris" in this chapter.
For more information about running and configuring Chili!Soft ASP, see "Chapter 3: Managing
Chili!Soft ASP."
See also:
Installing Chili!Soft ASP 3.6 for Sun Solaris in this chapter
Uninstalling Chili!Soft ASP in this chapter
Important Notes About Bundle Installations for Sun Solaris
Before running a bundle installation of Chili!Soft ASP for Sun Solaris, please review the
following information:
Chili!Soft ASP 3.6 Product Documentation
34
1. You use the Chili!Soft ASP Administration Console to start and stop the Chili!Soft ASP
Server and to change configuration settings. You can access the Administration Console from
the following URL:
http://[HOSTNAME]:[PORT]
where [HOSTNAME] is the Web server running the Chili!Soft ASP Administration Console,
and [PORT] is the port on which the Administration Console is configured to run (5100 by
default).
For more information about the configuring and running Chili!Soft ASP, see "Chapter 3:
Managing Chili!Soft ASP."
2. When finished installing Chili!Soft ASP 3.6, it is a good idea to use the diagnostic
applications to verify that your installation is functioning correctly. You can access the
diagnostics from the following URL:
http://[HOSTNAME]/caspsamp/diagnostics.htm
where [HOSTNAME] is the hostname of the Web server configured to run with Chili!Soft
ASP.
3. To use Chili!Beans, you must enable Java support, as described in "Enabling Java Support"
in "Chapter 3: Managing Chili!Soft ASP." Chili!Beans enables you to access Java objects and
classes from an ASP script. For more information about Chili!Beans, see "Chili!Beans
Component Reference" in "Chapter 5: Developer's Reference."
4. Important summary information about the installation is located in the following file:
/usr/local/chilisoft/casp/logs/install_summary
It is a good idea to print this information for future reference.
See also:
Installing Chili!Soft ASP 3.6 for Sun Solaris in this chapter
Installing the Chili!Soft ASP Bundle for Sun Solaris in this chapter
Uninstalling Chili!Soft ASP in this chapter
Installing a Custom Configuration of Chili!Soft ASP for Sun Solaris
This topic describes the steps to install a custom configuration of Chili!Soft ASP 3.6 for Sun
Solaris. For more information about a custom installation, see "Choosing an Installation Option
for Sun Solaris" in this chapter.
Important Upgrade Information
If you are upgrading from a previous version, the setup program might not be able to
preserve your existing settings. Before beginning the installation, go to the Chili!Soft
Web site for information about performing an upgrade, at:
http://www.chilisoft.com/support/
Chili!Soft ASP 3.6 Product Documentation
35
If you downloaded Chili!Soft ASP 3.6 for Sun Solaris from the Chili!Soft Web site, your
version includes a setup program that can upgrade many of your settings from Chili!Soft
ASP 3.4.1. Be aware that following installation, you will need to take additional steps to
finish the configuration before running Chili!Soft ASP 3.6. For more information about
performing this upgrade see "Upgrading Chili!Soft ASP for Sun Solaris" in this chapter.
The configuration options you specify when installing a custom configuration of Chili!Soft ASP
can have serious consequences for your server environment. Before you begin, make sure you
meet the following requirements:
•
You must be logged in as root.
•
If you are downloading Chili!Soft ASP from the Web, you must have 45 MB of hard disk
space available in order to extract the installation files.
•
Your hardware and software must meet the requirements listed in "Installation
Requirements—Chili!Soft ASP for Sun Solaris" in this chapter.
•
You need to know your product serial number. Chili!Soft ASP requires a valid serial
number in order to run. If you downloaded the product from the Web, you should have
received an e-mail message that included your serial number. If you are installing this
product from a CD-ROM, the serial number is printed on the CD-ROM case. If you are
installing a trial version from a CD-ROM, you can obtain a serial number at:
http://www.chilisoft.com/register
•
To enable Chili!Beans, you must have a Java Runtime Environment (JRE) version
between 1.1.7 and 1.2.1_03a installed on the target Web server. Chili!Beans enables you
to access Java objects and classes from an ASP script. For more information about
Chili!Beans, see "Chili!Beans Component Reference" in "Chapter 5: Developer's
Reference."
•
If you are upgrading from a previous version of Chili!Soft ASP, you must shut down the
ASP Server, and you must install Chili!Soft ASP 3.6 into the same directory as your
previous installation. In addition, be sure to review the important information in
"Upgrading Chili!Soft ASP for Sun Solaris" in this chapter.
•
To configure Chili!Soft ASP to run with a Web server that is already installed on the
target computer, you must shut down the Web server. Also, be prepared to provide the
following information about your Web server:
Absolute path name of the Web server main configuration file (for example,
/usr/HTTPServer/conf/httpd.conf)
Absolute path name of the Web server binary (for example, /usr/HTTPServer/bin/httpd)
Web server version (for example, 1.3.12)
Web server type (for example, Apache)
Web server port number (for example, 80)
Web server root directory (for example, /usr/HTTPServer)
Chili!Soft ASP 3.6 Product Documentation
•
36
When configuring the Zeus Web Server to run with Chili!Soft ASP 3.6, do not specify the
Web server hostname as the fully qualified domain name (or "server address"). If you do,
the Test DSN feature of the Administration Console will not work. Instead, use the
hostname only.
For example, do not use this: hostname.domain.com
Instead, use this: hostname
•
If you choose to customize settings for the Chili!Soft ASP Administration Console, you
will need to specify a username and password for accessing it. Be sure to specify a
password that you can remember, or else plan to store it in a secure location. If you forget
your password, you can run the admtool utility and set a new password, as described in
"Configuring Usernames and Passwords" in "Chapter 3: Managing Chili!Soft ASP." If
you do not choose the customize settings option, the username is set as "admin" and the
password as "root." To protect the security of your server, you should run the admtool and
change these as soon as possible following installation.
•
You need to know what language you want Chili!Soft ASP to support. The options are US
English, British English, Dutch, French, German, Japanese Shift-JIS, Spanish, and
Swedish. If you want, you can change the language after installation, as described in
"Configuring International Support" in "Chapter 3: Managing Chili!Soft ASP."
•
If you configure Chili!Soft ASP to run with an Apache Web Server that does not support
Dynamic Shared Objects (DSO), following installation you must manually link the Web
server to Chili!Soft ASP and then recompile it, as described in "Configuring a Non-DSO
Apache Web Server" in this chapter. If your Apache Web Server supports DSO, there are
no additional steps to take: Chili!Soft ASP includes pre-built DSO modules that
automatically link to your Web server.
To install a custom configuration of Chili!Soft ASP 3.6 for Sun Solaris, use the following
procedure.
To install a custom configuration of Chili!Soft ASP for Sun Solaris
1. If you are installing Chili!Soft ASP from a CD-ROM, skip this step and go to step 2. If you
are downloading Chili!Soft ASP from the Web, download the casp-3.6.0-solaris.tar file to a
temporary directory, and then extract the installation files by using the following command:
#> tar -xvf casp-3.6.0-solaris.tar
This step creates the following files in the temporary directory, which you can delete after
completing the installation:
A README file containing important product information
The install.sh installation script
A package/EULA file containing the end-user license agreement
A package/directory containing files required to install Chili!Soft ASP
2. Run the install.sh script by using the following command. For downloaded versions, this
script is located in the temporary directory you created in the previous step. For CD-ROM
versions, this script is located on your installation CD-ROM.
Chili!Soft ASP 3.6 Product Documentation
37
#> ./install.sh
3. Review the End-User License Agreement (EULA) that displays. Enter yes if you agree with
its conditions. You must type the entire word "yes."
– or –
Enter no if you do not agree. If you enter no, the Chili!Soft ASP setup program aborts the
installation.
4. On the next screen, enter 2 to select a Custom Installation.
5. On the next screen, press Enter to accept the default Chili!Soft ASP installation directory
(/opt/casp).
– or –
Enter the absolute path name of the installation directory you want. It is a good idea to make
a note of this location so that you can easily find the Chili!Soft ASP files at a later time.
Note
In order to upgrade from Chili!Soft ASP 3.4.1, you must specify the installation directory
of your existing installation.
6. If the setup program detects a previous installation of Chili!Soft ASP in the specified
directory, it asks whether or not you want to uninstall the previous version and continue. If
the setup program successfully exported your existing settings from the previous installation,
it also provides a message indicating this. You will be prompted to import the settings later
during setup.
If you do not see the second message, your settings will not be preserved, and you will need
to reconfigure all of them following installation.
Enter y (yes) to uninstall the previous installation and continue.
– or –
Enter n (no) to change the installation directory or cancel the installation.
7. On the next screen, enter y (yes) if you know the product serial number.
– or –
If you do not know the serial number, enter n. Chili!Soft ASP will not run without a serial
number, so if you enter n, the setup program cancels the installation.
8. When prompted, enter the product serial number.
9. On the next screen, press Enter to accept the default language (English – US).
– or –
Enter the number of a language shown in the list.
10. On the next screen, enter y to enable Chili!Beans support.
– or –
Chili!Soft ASP 3.6 Product Documentation
38
Enter n if you do not want to enable Chili!Beans support.
11. On the next screen, enter the absolute path name of your Java Runtime Environment.
12. The next screen provides options for choosing the Web server to configure with Chili!Soft
ASP. If you want the setup program to search your system and generate a list of installed
Web servers from which to select, enter the number of the search option you want (1, 2, or 3).
If you select one of these search options, skip to step 16.
– or –
If you want to skip this search and provide information about the Web server, enter 4 (Don't
search). If you choose option 4 (Don’t search), follow the instructions in step 13.
13. If you want to provide information about the Web server to configure, on the next screen,
enter 1 (Specify the Webserver), and then follow the instructions in step 13.
– or –
If you want the setup program to search for installed Web servers from which to select, enter
2 (Refresh the Webserver list), and then follow the instructions in step 12.
– or –
If you do not want to configure a Web server during installation, enter 3 (Do not configure a
Webserver), and then go to step 18. If you choose this option, the first time you open the
Chili!Soft ASP Administration Console, you will be prompted to configure the ASP Server
and a Web server.
14. On the next screen, enter the number of the type of Web server to configure: 1 for Apache, 2
for Netscape, or 3 for Zeus, and go to the next step.
– or –
To cancel the user-specified Web server configuration, enter 4. If you choose this option, the
setup program returns you to the previous screen. From this screen you can choose another
option, as described in step 13.
15. At the prompts, enter the requested information about the Web server, and go to the next step.
16. On the next screen, enter the number of the Web server you want the setup program to
configure to run with Chili!Soft ASP, and go to the next step.
– or –
To provide information about the Web server to configure, enter the number for the option,
Specify the Webserver. If you choose this option, follow the instructions in step 14.
– or –
To perform another search for installed Web servers, enter the number for the option,
Refresh the webserver list. If you choose this option, follow the instructions in step 12.
– or –
If you do not want to configure a Web server during installation, enter the number for the
option, Do not configure a Webserver, and then go to step 18. If you choose this option, the
Chili!Soft ASP 3.6 Product Documentation
39
first time you open the Chili!Soft ASP Administration Console, you will be prompted to
configure the ASP Server and a Web server.
17. On the next screen, verify the information that the setup program displays about your Web
server. If the information is incorrect, the Chili!Soft ASP installation could fail. In this event,
you can run the installation script again. If you do this, it is recommended that you first run
the uninstall script, as described in "Uninstalling Chili!Soft ASP" in this chapter. If the
information on the screen is correct, enter y (yes), and go to the next step.
– or –
If the information is incorrect, enter n (no). The setup program returns you to the previous
screen. For this screen, follow the instructions in step 16.
18. On the next screen, choose a configuration option for the ASP Server. Enter 1 to choose a
default configuration, and go to the next step.
– or –
Enter 2 to choose a custom configuration, and enter the following information at the prompts:
Would you like me to restart this Web Server for you? Enter y (yes) if you want the
setup program to automatically restart the Web server after completing Chili!Soft ASP
installation, or enter n (no) if you do not want this.
Choose a mode. Enter the number of the mode in which you want to run the ASP
Server, or enter 3 for more information about this option.
1. Multi-threaded
2. Multi-process
3. More information
Enable samples on this Web server? Enter y (yes) if you want the setup program to
install and configure the Chili!Soft ASP samples on your Web server, or n (no) if you do
not want this.
Enable documentation on this Web server? Enter y (yes) if you want the setup
program to enable the Chili!Soft ASP documentation on your Web server, or n (no) if
you do not want this. If you enter n, the documentation will be available from the
Administration Console, but not from the Chili!Soft ASP Start Page.
Start the Chili!Soft ASP on system boot? Enter y (yes) if you want the setup program
to start Chili!Soft ASP automatically each time you start the computer, or type n (no) if
you do not want this.
Would you like to start this Chili!Soft ASP Server? Enter y (yes) if you want the
setup program to start Chili!Soft ASP automatically immediately after you finish
installing it, or n (no) if you do not want this.
– or –
Enter 3 to choose another Web server to configure for Chili!Soft ASP, and follow the
instructions in step 12.
Chili!Soft ASP 3.6 Product Documentation
40
19. On the next screen, select a configuration option for the Administration Console. When you
choose Auto-Select/Default the setup program configures the console using default settings.
With this option, it specifies the username as "admin" and the password as "root." To protect
the security of your server, it is highly recommend that you change these settings as soon as
possible. For information about doing this, see "Configuring Usernames and Passwords" in
"Chapter 3: Managing Chili!Soft ASP."
If you choose Customize Settings, enter the following information at the prompts:
Administration Console port number: Enter the number of the port on which the Web
server should listen for requests for the Administration Console or press Enter to accept
the default.
Automatically start the Administration Console on system startup: Enter y (yes) if
you want the Chili!Soft ASP Administration Console to start automatically each time
you start the computer, or n (no) if you do not want this.
Type the username: Enter the administrator username.
New password: Enter the administrator password, which is required for accessing the
Administration Console. It is a good idea to make note of this password because you
cannot access the Administration Console without providing it.
Confirm password: Re-enter the password.
20. The next screen provides summary information about your Administration Console
configuration, including the URL for accessing it. It is a good idea to make a note of this
information or else print this screen for future reference. When finished, press Enter to
complete the installation.
21. If you are upgrading from Chili!Soft ASP 3.4.1 for Sun Solaris, and the setup program was
able to export the settings from your previous installation, it prompts you to import these
settings into your new installation. Enter y (yes) to import your settings.
– or –
Enter n (no) if you do not want to import your settings.
The setup program then completes the installation and writes a summary file to:
[C-ASP_INSTALL_DIR]/logs/install_summary
where [C-ASP_INSTALL_DIR] is the directory in which you installed Chili!Soft ASP (/opt/casp
by default). It is a good idea to print the information contained in the install_summary file for
future reference.
Before running a custom installation of Chili!Soft ASP, see "Important Notes About Custom
Installation for Sun Solaris" in this chapter. If you are upgrading from Sun Solaris 3.4.1, you must
also take the additional steps described in "Upgrading Chili!Soft ASP for Sun Solaris" in this
chapter.
For information about the changes the setup program makes to your Web server configuration
files, see "Changes to Netscape Web Server Configuration Files" or "Changes to Apache Web
Server Configuration Files" in this chapter, as appropriate.
Chili!Soft ASP 3.6 Product Documentation
41
See also:
Installing Chili!Soft ASP 3.6 for Sun Solaris in this chapter
Uninstalling Chili!Soft ASP in this chapter
Important Notes About Custom Installations for Sun Solaris
Before running a custom installation of Chili!Soft ASP 3.6 for Sun Solaris, review the following
information:
1. If you chose the default configuration for the Administration Console, the setup program
configured the username as "admin" and the password as "root." To protect the security of
your server, it is highly recommended that you change the username and password as soon as
possible. For more information, see "Configuring Usernames and Passwords" in "Chapter 3:
Managing Chili!Soft ASP."
2. You use the Administration Console to start and stop the Chili!Soft ASP Server and to
change configuration settings. You can access the Administration Console by typing the
following URL in your Web browser address bar:
http://[HOSTNAME]:[PORT]
where [HOSTNAME] is the valid DNS name or IP address of the Apache Web Server
running the Chili!Soft ASP Administration Console and [PORT] is the port on which the
Administration Console is configured to run (5100 by default). The URL for accessing the
Administration Console is provided in the following file:
[C-ASP_INSTALL_DIR]/logs/install_summary
where [C-ASP_INSTALL_DIR] is the directory in which you installed Chili!Soft ASP
(/opt/casp by default).
3. If you chose the option not to configure a Web server to run with Chili!Soft ASP during
installation, the first time you open the Administration Console, you must select a Web
server.
4. The Chili!Soft ASP setup program makes certain changes to the configuration files for the
associated Web server. For more information, see "Changes to Netscape Web Server
Configuration Files" or "Changes to Apache Web Server Configuration Files" in this chapter,
as appropriate.
5. If you installed Chili!Soft ASP to run with an Apache Web server that does not support
Dynamic Shared Object (DSO), you must manually link the Web server to Chili!Soft ASP
and then recompile it, as described in "Configuring a Non-DSO Apache Web Server" in this
chapter. If your Apache Web server supports DSO, there are no additional steps to take:
Chili!Soft ASP includes pre-built DSO modules that automatically link to your Web server.
6. To use Chili!Beans, you must enable Java support, as described in "Enabling Java Support"
in "Chapter 3: Managing Chili!Soft ASP." Chili!Beans enables you to access Java objects and
classes from an ASP script. For more information about Chili!Beans, see "Chili!Beans
Component Reference" in "Chapter 5: Developer's Reference."
Chili!Soft ASP 3.6 Product Documentation
42
7. When finished installing Chili!Soft ASP 3.6, it is a good idea to use the diagnostic
applications to verify that your installation is functioning correctly. You can access the
diagnostics from the following URL:
http://[HOSTNAME]/caspsamp/diagnostics.htm
where [HOSTNAME] is the hostname of the Web server configured to run with Chili!Soft
ASP.
8. Important summary information about the installation is located in the following file:
[C-ASP_INSTALL_DIR]/logs/install_summary
where [C-ASP_INSTALL_DIR]is the directory in which you installed Chili!Soft ASP
(/opt/casp by default).
It is a good idea to print this information for future reference.
See also:
Installing a Custom Configuration of Chili!Soft ASP 3.6 for Sun Solaris in this chapter
Uninstalling Chili!Soft ASP in this chapter
Installing Chili!Soft ASP 3.6 for Linux
The topics in this section describe the requirements and procedures for installing Chili!Soft ASP
3.6 for Linux. For up-to-date product information, see the README file included with your
Chili!Soft ASP software. You can access the README file from the Chili!Soft ASP
Administration Console as described in "Viewing the Product README File" in "Chapter 3:
Managing Chili!Soft ASP."
Important Upgrade Information
If you are upgrading from a previous version, the setup program might not be able to
preserve your existing settings. Before beginning the installation, go to the Chili!Soft
Web site for information about performing an upgrade, at:
http://www.chilisoft.com/support/
In this section:
•
Installation Requirements: Chili!Soft ASP for Linux
•
Choosing an Installation Option for Linux
•
Installing the Chili!Soft ASP Bundle for Linux
•
Installing a Custom Configuration of Chili!Soft ASP for Linux
Installation Requirements: Chili!Soft ASP for Linux
This topic lists the hardware and software requirements for running Chili!Soft ASP 3.6 for Linux.
It also lists the additional software, such as databases and tools, that Chili!Soft ASP supports.
Chili!Soft ASP 3.6 Product Documentation
43
Hardware and Software Requirements
This section lists the hardware and software required to install and run Chili!Soft ASP 3.6 for
Linux on your server.
Hardware
The minimum hardware configuration required for Chili!Soft ASP 3.6 for Linux is as follows:
•
128 MB RAM (256 or higher recommended)
•
Pentium class processor (x86)
•
200 MB free hard disk space for the bundle installation of Chili!Soft ASP 3.6 with Apache
Web Server and Microsoft Front Page 2000 Server Extensions
•
130 MB free hard disk space for the custom installation of Chili!Soft ASP 3.6
Linux Kernel and GLIBC
•
Linux Kernel 2.2
•
GLIBC 2.1.2 to 2.1.94
Operating System
You can install and run Chili!Soft ASP 3.6 for Linux on a computer running one of the following
operating systems:
•
Red Hat Linux 6.2, 7.0
•
Debian Linux 2.2
•
SuSE Linux 6.4, 7.0
•
Slackware Linux 7.0, 7.1
•
Linux-Mandrake 7.0, 7.1
•
TurboLinux Server 6.0
Web Server
For a custom installation of Chili!Soft ASP 3.6 for Linux, you must be running one of the
following Web servers (the bundle installation automatically installs and configures Apache Web
Server 1.3.12 DSO):
•
Apache Web Server 1.3.12 DSO, NDSO
•
Apache Web Server 1.3.14 DSO
•
Red Hat Secure Server (on Red Hat 6.2 and 7.0 only)
•
iPlanet/Netscape Enterprise 4.0, 4.1
•
Zeus Web Server 3.3.7
Chili!Soft ASP 3.6 Product Documentation
44
Software
Perl 5.005_03 or later must be running on the computer to which you are installing Chili!Soft
ASP 3.6.
Important Note
Perl 5.6 does not work with the Chili!Soft ASP setup program. It causes setup to fail.
Supported Software
This section lists the software that is supported and/or installed by Chili!Soft ASP 3.6 for Linux.
Database
Chili!Soft ASP 3.6 for Linux includes ODBC drivers for the following databases:
•
DB2*
•
dBase 5
•
Informix 7, 9
•
InterBase 6.0
•
Microsoft Access (via SequeLink—see note below**)
•
Microsoft SQL Server 6.5 (via SequeLink—see note below**)
•
Microsoft SQL Server 7.0
•
MySQL 3.22, 3.23
•
Oracle 8, 8i
•
PostgreSQL 6.5, 7.0
•
Sybase 11
ODBC drivers are installed automatically by the Chili!Soft ASP setup program. Following
installation, you must configure the drivers for the data source being used. For more information,
see "Configuring a Database" in "Chapter 3: Managing Chili!Soft ASP."
*Note about DB2 support
In order to configure DB2 database connections, the following software must be installed
on the computer running the ASP Server:
- IBM DB2 Client Application Enabler (CAE) for Linux, version 2.1 or higher
- IBM DB2 Software Development Kit (DB2 SDK) for Linux, version 2.1 or higher
For more information, see "Configuring DB2" in "Chapter 3: Managing Chili!Soft ASP."
Chili!Soft ASP 3.6 Product Documentation
45
** Note about Microsoft Access and Microsoft SQL Server 6.5 support
To provide remote database connectivity with Microsoft Access and Microsoft SQL
Server 6.5 databases, Chili!Soft ASP 3.6 ships with the client portion of the Merant
SequeLink 4.51a software. You also must download and install the server portion of this
software from Chili!Soft. For more information, see "Configuring SequeLink" in
"Chapter 3: Managing Chili!Soft ASP."
Java Runtime Environment
ChiliSoft ASP 3.6 for Linux includes the Java Runtime Environment (JRE) 1.2.2_06, required for
Chili!Beans. ChiliBeans enables you to use Java class files as components called from VBScript
or JScript. You must also enable Java support, as described in "Enabling Java Support" in
"Chapter 3: Managing Chili!Soft ASP." For more information about Chili!Beans, see
"Chili!Beans Component Reference" in "Chapter 5: Developer's Reference."
Microsoft FrontPage 2000 Server Extensions
Microsoft FrontPage 2000 Server Extensions are included in the bundle installation of Chili!Soft
ASP 3.6. They provide services to the Web server that work in conjunction with Chili!Soft ASP
to provide FrontPage functionality to computers that are not running Microsoft Windows NT or
Windows 2000 and Internet Information Services (IIS). For more information, see "Enabling
FrontPage Publishing" in "Chapter 3: Managing Chili!Soft ASP."
See also:
Installing Chili!Soft ASP 3.6 for Linux in this chapter
Choosing an Installation Option for Linux in this chapter
Installing a Custom Configuration of Chili!Soft ASP for Linux in this chapter
Installing the Chili!Soft ASP Bundle for Linux in this chapter
Choosing an Installation Option for Linux
The Chili!Soft ASP 3.6 setup program takes you through all of the steps required to install the
Chili!Soft ASP software on Linux. It provides the following two installation options:
•
Bundle installation. This is the easiest way to install Chili!Soft ASP. However, if you are
performing an upgrade, you should choose a custom installation. With a bundle
installation, the setup program automatically installs and configures the following
components on the target server:
Chili!Soft ASP Server
Chili!Soft ASP Administration Console
Chili!Beans
Java Runtime Environment (JRE) 1.2.2_06 (required for Chili!Beans)
Apache Web Server 1.3.12
Microsoft FrontPage 2000 Server Extensions
Chili!Soft ASP 3.6 Product Documentation
46
dBase 5 database and samples
IBM DB2 Client Application Enabler (CAE) 7.0.1
For instructions about performing a bundle installation, see "Installing the Chili!Soft ASP Bundle
for Linux" in this chapter.
•
Custom installation. With this option, the setup program installs the following
components on the target server:
Chili!Soft ASP Server
Chili!Soft ASP Administration Console
Chili!Beans
Java Runtime Environment (JRE) 1.2.2_06 (required for Chili!Beans)
Apache Web Server 1.3.12
The setup program gives you the option to either specify the configuration options or accept the
default configuration settings. The configuration settings you specify during a custom installation
can have serious consequences for your server environment. For instructions about performing
this installation, see "Installing a Custom Configuration of Chili!Soft ASP for Linux" in this
chapter.
For up-to-date information about Chili!Soft ASP 3.6 and its components, see the README file
that was installed with your software. You can access it from the Administration Console by
clicking customer support in the left navigation pane.
See also:
Installing Chili!Soft ASP 3.6 for Linux in this chapter
Uninstalling Chili!Soft ASP in this chapter
Installing the Chili!Soft ASP Bundle for Linux
This topic describes the steps to install the Chili!Soft ASP 3.6 bundle for Linux. For more
information about a bundle installation, see "Choosing an Installation Option for Linux" in this
chapter.
Before you begin, make sure you meet the following requirements:
•
You are logged in as root.
•
If you are downloading Chili!Soft ASP from the Web, you must have 45 MB of hard disk
space available in order to extract the installation files.
•
Your hardware and software meet the requirements listed in "Installation Requirements—
Chili!Soft ASP for Linux" in this chapter.
•
You know your product serial number. Chili!Soft ASP requires a valid serial number in
order to run. If you downloaded the product from the Web, you should have received an email message that included your serial number. If you are installing this product from a
CD-ROM, the serial number is printed on the CD-ROM case. If you are installing a trial
version from a CD-ROM, you must obtain a serial number at:
Chili!Soft ASP 3.6 Product Documentation
47
http://www.chilisoft.com/register
•
You know what language you want Chili!Soft ASP to support. The options are US
English, British English, Dutch, French, German, Japanese Shift-JIS, Spanish, and
Swedish. If you want, you can change the language after installation, as described in
"Configuring International Support" in "Chapter 3: Managing Chili!Soft ASP."
•
If you have already installed the IBM Bonus Pack on your server, you must stop the IBM
HTTP Server before installing Chili!Soft ASP.
•
If you have a previous installation of Chili!Soft ASP on your server, contact Chili!Soft
ASP Customer Support for information about preserving your server settings.
•
For the Chili!Soft ASP Administration Console, you need to specify a username and
password. Be sure to specify a password that you can remember, or else plan to store it in
a secure location. If you forget your password, you can run the admtool utility and set a
new password, as described in "Configuring Usernames and Passwords" in "Chapter 3:
Managing Chili!Soft ASP."
•
If FrontPage Server Extensions are already installed on your computer, the Chili!Soft ASP
setup program cannot properly install and configure the FrontPage 2000 Server
Extensions that are included in the bundle installation. If you already have FrontPage
Server Extensions installed, you must uninstall them before installing the Chili!Soft ASP
bundle:
To install the Chili!Soft ASP 3.6 bundle for Linux, use the following procedure.
To install the Chili!Soft ASP bundle for Linux
1. If you are installing Chili!Soft ASP from a CD-ROM, skip this step and go to step 2. If you
are downloading Chili!Soft ASP from the Web, download the casp-3.6.0-linux.tar file to a
temporary directory, and then extract the installation files by using the following command:
#> tar -xvf casp-3.6.0-linux.tar
This step creates the following files in the temporary directory, which you can delete after
completing the installation:
A README file containing important product information
The install.sh installation script
A package/EULA file containing the end-user license agreement
A package/directory containing the files required to install Chili!Soft ASP
2. Run the install.sh script by using the following command. For downloaded versions, this
script is located in the temporary directory you created in the previous step. For CD-ROM
versions, this script is located on your installation CD-ROM.
#> ./install.sh
3. Review the End-User License Agreement (EULA) that displays. Enter yes if you agree to its
conditions. You must type the entire word "yes."
– or –
Chili!Soft ASP 3.6 Product Documentation
48
Enter no if you do not agree. If you enter no, the Chili!Soft ASP setup program aborts the
installation.
4. On the next screen, enter 1 to select the Bundle Installation option. The setup program
extracts the Chili!Soft files to /usr/local/chilisoft.
5. On the next screen, press Enter if you want to install the Apache Web Server to port 80.
– or –
Enter a different port number for the Apache Web Server to use.
6. On the next screen, press Enter to accept the default administration username ("admin").
– or –
Enter a different administration username.
7. When prompted, enter an administration password, and re-enter the password when prompted
to confirm it.
8. On the next screen, enter y (yes) if you know the product serial number. If you do not know
the serial number, enter n. Chili!Soft ASP will not run without a serial number, so if you
enter n, the setup program aborts the installation.
9. When prompted, enter the product serial number.
10. On the next screen, press Enter to accept the default language ("English – US").
– or –
Enter the number of a language shown in the list.
The setup program automatically installs the Chili!Soft ASP bundle to the following directory
and performs basic configuration of the software:
/usr/local/chilisoft/casp ...\
Before running a bundle installation of Chili!Soft ASP, see "Important Notes About Bundle
Installations for Linux" in this chapter.
For more information about running and configuring Chili!Soft ASP, see "Chapter 3: Managing
Chili!Soft ASP."
See also:
Installing Chili!Soft ASP 3.6 for Linux in this chapter
Uninstalling Chili!Soft ASP in this chapter
Important Notes About Bundle Installations for Linux
Before running a bundle installation of Chili!Soft ASP for Linux, please review the following
information:
1. You use the Chili!Soft ASP Administration Console to start and stop the Chili!Soft ASP
Server and to change configuration settings. You can access the Administration Console by
typing the following URL in your Web browser address bar:
Chili!Soft ASP 3.6 Product Documentation
49
http://[HOSTNAME]:[PORT]
where [HOSTNAME] is the valid DNS name or IP address of the Apache Web Server
running the Chili!Soft ASP Administration Console and [PORT] is the port on which the
Administration Console is configured to run (5100 by default).
For more information about the configuring and running Chili!Soft ASP, see "Chapter 3:
Managing Chili!Soft ASP."
2. Important summary information about the installation is located in the following file:
/usr/local/chilisoft/casp/logs/component_log
It is a good idea to print this information for future reference.
3. To use Chili!Beans, you must enable Java support, as described in "Enabling Java Support"
in "Chapter 3: Managing Chili!Soft ASP." Chili!Beans enables you to access Java objects and
classes from an ASP script. For more information about Chili!Beans, see "Chili!Beans
Component Reference" in "Chapter 5: Developer's Reference."
4. When finished installing Chili!Soft ASP 3.6, it is a good idea to use the diagnostic
applications to verify that your installation is functioning correctly. You can access the
diagnostics from the following URL:
http://[HOSTNAME]/caspsamp/diagnostics.htm
where [HOSTNAME] is the hostname of the Web server configured to run with Chili!Soft
ASP.
5. The IBM DB2 7.01 Client Application Enabler (CAE) is installed on your computer at the
following location:
/usr/lpp/db2_07_01
Before you can connect to the DB2 database, you must first configure a DSN, as described in
"Configuring Data Source Names (DSNs)" in "Chapter 3: Managing Chili!Soft ASP." Note
that you must use the cataloged name of the database for the DSN name. Chili!Soft ASP
automatically sets the correct database parameters and associates them with the cataloged
name of the database. In addition to configuring a DSN for DB2, you must load the DB2
profile as described in "Loading DB2 Profiles" in "Chapter 3: Managing Chili!Soft ASP."
See also:
Installing Chili!Soft ASP 3.6 for Linux in this chapter
Installing the Chili!Soft ASP Bundle for Linux in this chapter
Uninstalling Chili!Soft ASP in this chapter
Installing a Custom Configuration of Chili!Soft ASP for Linux
This topic describes the steps to install a custom configuration of Chili!Soft ASP for Linux
systems. For more information about a custom installation, see "Choosing an Installation Option
for Linux" in this chapter.
Chili!Soft ASP 3.6 Product Documentation
50
Important Upgrade Information
If you are upgrading from a version other than Chili!Soft ASP 3.5.2, the setup program
will not preserve your existing settings. Before beginning the installation, go to the
Chili!Soft Web site for information about performing an upgrade, at:
http://www.chilisoft.com/support/
The configuration options you specify when installing a custom configuration of Chili!Soft ASP
can have serious consequences for your server environment. Before you begin, make sure you
meet the following requirements:
•
You must be logged in as root.
•
If you are downloading Chili!Soft ASP from the Web, you must have 45 MB of hard disk
space available in order to extract the installation files.
•
Your hardware and software must meet the requirements listed in "Installation
Requirements—Chili!Soft ASP for Linux" in this chapter.
•
You need to know your product serial number. Chili!Soft ASP requires a valid serial
number in order to run. If you downloaded the product from the Web, you should have
received an e-mail message that included your serial number. If you are installing this
product from a CD-ROM, the serial number is printed on the CD-ROM case. If you are
installing a trial version from a CD-ROM, you must obtain a serial number at:
http://www.chilisoft.com/register
•
To configure Chili!Soft ASP to run with a Web server that is already installed on the
target computer, the Web server must be shut down, and you should be prepared to
provide the following information:
Absolute path name of the Web server main configuration file (for example,
/usr/HTTPServer/conf/httpd.conf)
Absolute path name of the Web server binary (for example, /usr/HTTPServer/bin/httpd)
Web server version (for example, 1.3.12)
Web server type (for example, Apache)
Web server port number (for example, 80)
Web server root directory (for example, /usr/HTTPServer)
•
If you configure Chili!Soft ASP to run with an Apache Web Server that does not support
Dynamic Shared Objects (DSO), you must manually link the Web server to Chili!Soft
ASP and then recompile it, as described in "Configuring a Non-DSO Apache Web Server"
in this chapter. If your Apache Web Server supports DSO, there are no additional steps to
take: Chili!Soft ASP includes pre-built DSO modules that automatically link to your Web
server.
•
When configuring the Zeus Web Server to run with Chili!Soft ASP 3.6, do not specify the
Web server hostname as the fully qualified domain name (or "server address"). If you do,
Chili!Soft ASP 3.6 Product Documentation
51
the Test DSN feature of the Administration Console will not work. Instead, use the
hostname only.
For example, do not use this: hostname.domain.com
Instead, use this: hostname
•
If you choose to customize settings for the Chili!Soft ASP Administration Console, you
will need to specify a username and password for accessing it. Be sure to specify a
password that you can remember, or else plan to store it in a secure location. If you forget
your password, you can run the admtool utility and set a new password, as described in
"Configuring Usernames and Passwords" in "Chapter 3: Managing Chili!Soft ASP." If
you do not choose the customize settings option, the username is set as "admin" and the
password as "root." To protect the security of your server, you should run the admtool and
change these as soon as possible.
•
You need to know what language you want Chili!Soft ASP to support. The options are US
English, British English, Dutch, French, German, Japanese Shift-JIS, Spanish, and
Swedish. If you want, you can change the language after installation, as described in
"Configuring International Support" in "Chapter 3: Managing Chili!Soft ASP."
•
If you have already installed the IBM Bonus Pack on your server, you must stop the IBM
HTTP Server before installing Chili!Soft ASP.
•
If you are upgrading from a previous installation of Chili!Soft ASP, you must shut down
the ASP Server.
•
If you have an existing installation of Chili!Soft ASP 3.5.2 or 3.6 in the directory to
which you are installing Chili!Soft ASP 3.6, the setup program automatically preserves
your existing server settings. However, you must take the additional steps described in
"Upgrading Chili!Soft ASP for Linux" in this chapter before you can run the ASP Server.
To install a custom configuration of Chili!Soft ASP 3.6 for Linux, use the following procedure.
To install a custom configuration of Chili!Soft ASP for Linux
1. If you are installing Chili!Soft ASP from a CD-ROM, skip this step and go to step 2. If you
are downloading Chili!Soft ASP from the Web, download the casp-3.6.0-linux.tar file to a
temporary directory, and then extract the installation files by using the following command:
#> tar -xvf casp-3.6.0-linux.tar
This step creates the following files in the temporary directory, which you can delete after
completing the installation:
A README file containing important product information
The install.sh installation script
A package/EULA file containing the end-user license agreement
A package/directory containing files required to install Chili!Soft ASP
2. Run the install.sh script by using the following command. For downloaded versions, this
script is located in the temporary directory you created in the previous step. For CD-ROM
versions, this script is located on your installation CD-ROM.
Chili!Soft ASP 3.6 Product Documentation
52
#> ./install.sh
3. Review the End-User License Agreement (EULA) that displays. Enter yes if you agree with
its conditions. You must type the entire word "yes."
– or –
Enter no if you do not agree. If you enter no, the Chili!Soft ASP setup program aborts the
installation
4. On the next screen, enter 2 to select a Custom Installation.
5. On the next screen, press Enter to accept the default Chili!Soft ASP installation directory
(/opt/casp).
– or –
Enter the absolute path name of the installation directory you want. It is a good idea to make
a note of this location so that you can easily find the Chili!Soft ASP files at a later time.
Note
In order to upgrade from Chili!Soft ASP 3.5.2, you must specify the installation directory
of your existing installation.
6. If the setup program detects a previous installation of Chili!Soft ASP in the specified
directory, it asks whether or not you want to uninstall the previous version and continue. If
the setup program successfully exported your existing settings from the previous installation,
it also provides a message indicating this. You will be prompted to import the settings later
during setup.
If you do not see the second message, your settings will not be preserved, and you will need
to reconfigure all of them following installation.
Enter y (yes) to uninstall the previous installation and continue, and then enter y (yes) again
to confirm that you want to continue.
– or –
Enter n (no) to cancel the installation.
7. On the next screen, enter y (yes) if you know the product serial number.
– or –
If you do not know the serial number, enter n. Chili!Soft ASP will not run without a serial
number, so if you enter n, the setup program aborts the installation.
8. When prompted, enter the product serial number.
9. On the next screen, press Enter to accept the default language (English – US).
– or –
Enter the number of a language shown in the list.
Chili!Soft ASP 3.6 Product Documentation
53
10. The next screen provides options for choosing the Web server to run with Chili!Soft ASP. If
you want the setup program to search your system and generate a list of installed Web servers
from which to select, enter the number of the search option you want (1, 2, or 3). If you select
one of these search options, skip to step 14.
– or –
If you want to skip this search and provide information about the Web server, or if you do not
want to configure a Web server during installation, enter number 4 (Don't search). If you
choose option 4 (Don’t search), follow the instructions in step 11.
11. On the next screen, if you want to provide information about the Web server to configure,
enter 1 (Specify the Webserver), and then follow the instructions in step 12.
– or –
If you want the setup program to search for installed Web servers from which to select, enter
2 (Refresh the Webserver list), and then follow the instructions in step 10.
– or –
If you do not want to configure a Web server during installation, enter 3 (Do not configure a
Webserver), and then go to step 16. If you choose this option, the first time you open the
Chili!Soft ASP Administration Console, you will be prompted to configure the ASP Server
and a Web server.
12. On the next screen, enter the number of the type of Web server to configure: 1 for Apache, 2
for Netscape, or 3 for Zeus, and go to the next step.
– or –
To cancel the user-specified Web server configuration, enter 4. If you choose this option, the
setup program returns you to the previous screen. From this screen you can choose another
option, as described in step 11.
13. At the prompts, enter the requested information about the Web server.
14. On the next screen, enter the number of the Web server you want the setup program to
configure to run with Chili!Soft ASP, and go to the next step.
– or –
To provide information about the Web server to configure, enter the number for the option,
Specify the Webserver. If you choose this option, follow the instructions in step 12.
– or –
To perform another search for installed Web servers, enter the number for the option,
Refresh the webserver list. If you choose this option, on the next screen, follow the
instructions in step 10.
– or –
If you do not want to configure a Web server during installation, enter the number for the
option, Do not configure a Webserver, and then go to step 16. If you choose this option, the
Chili!Soft ASP 3.6 Product Documentation
54
first time you open the Chili!Soft ASP Administration Console, you will be prompted to
configure the ASP Server and a Web server.
15. On the next screen, verify the information that the setup program displays about your Web
server. If the information is incorrect, the Chili!Soft ASP installation could fail. In this event,
you can run the installation script again. If you do this, it is recommended that you first run
the uninstall script, as described in "Uninstalling Chili!Soft ASP" in this chapter. If the
information on the screen is correct, enter y (yes), and go to the next step.
– or –
If the information is incorrect, enter n (no). The setup program returns you to the previous
screen. For this screen, follow the instructions in step 14.
16. On the next screen, choose a configuration option for the ASP Server. Enter 1 to choose a
default configuration, and go to the next step.
– or –
Enter 2 to choose a custom configuration, and provide the following information at the
prompts:
Would you like me to restart the Web Server for you? Type y (yes) if you want the
setup program to automatically restart Apache Web Server after completing Chili!Soft
ASP installation, or type n (no) if you do not want this, and then press Enter.
Enable samples on this Web server? Enter y (yes) if you want the setup program to
install and configure the Chili!Soft ASP samples on your Web server, or n (no) if you do
not want this.
Enable documentation on this Web server? Enter y (yes) if you want the setup
program to install and configure the Chili!Soft ASP documentation on your Web server,
or n (no) if you do not want this. If you enter n, the documentation will be available
from the Administration Console, but not from the Chili!Soft ASP Start Page.
Start the Chili!Soft ASP on system boot? Enter y (yes) if you want the setup program
to start Chili!Soft ASP automatically each time you start the computer, or type n (no) if
you do not want this.
Would you like to start this Chili!Soft ASP Server? Enter y (yes) if you want the
setup program to start Chili!Soft ASP automatically immediately after you finish
installing it, or n (no) if you do not want this.
17. On the next screen, select a configuration option for the Administration Console. When you
choose Auto-Select/Default, the setup program automatically configures the console. For
this option, the setup program specifies the username as "admin" and the password as "root."
To protect the security of your server, it is highly recommend that you change these settings
as soon as possible. For information about doing this, see "Configuring Usernames and
Passwords" in "Chapter 3: Managing Chili!Soft ASP."
When you choose Customize Settings, you must provide the following information:
Chili!Soft ASP 3.6 Product Documentation
55
Administration Console port number: Enter the number of the port on which the Web
server should listen for requests for the Administration Console or press Enter to accept
the default.
Automatically start the Administration Console on system startup: Enter y (yes) if
you want the Chili!Soft ASP Administration Console to start automatically each time
you start the computer, or n (no) if you do not want this.
Type the username for the administrator: Enter the administrator username.
New password: Enter the administrator password, which is required for accessing the
Administration Console. It is a good idea to make note of this password because you
cannot access the Administration Console without providing it.
Confirm password: Re-enter the password to confirm it.
18. If you are upgrading from Chili!Soft ASP 3.5.2, and the setup program was able to export the
settings from your previous installation, it prompts you to import these settings into your new
installation. Enter y (yes) to import your settings.
– or –
Enter n (no) if you do not want to import your settings.
19. The next screen provides summary information about your Administration Console
configuration, including the URL for accessing it. It is a good idea to make a note of this
information or else print this screen for future reference. When finished, press Enter to
complete the installation.
The setup program then completes the installation and writes a summary file to:
[C-ASP_INSTALL_DIR]/logs/install_summary
where [C-ASP_INSTALL_DIR] is the directory in which you installed Chili!Soft ASP (/opt/casp
by default). It is a good idea to print the information contained in the install_summary file for
future reference.
Note
On Chili!Soft ASP 3.6 for Linux, you need to access your Web server by using the
"server address" specified in the Zeus Administration Console, rather than the address
specified in install_summary.
Before running a custom installation of Chili!Soft ASP, see "Important Notes About Custom
Installations for Linux" in this chapter.
For information about the changes the setup program makes to your Web server configuration
files, see "Changes to Netscape Web Server Configuration Files" or "Changes to Apache Web
Server Configuration Files" in this chapter, as appropriate.
See also:
Installing Chili!Soft ASP 3.6 for Linux in this chapter
Uninstalling Chili!Soft ASP in this chapter
Chili!Soft ASP 3.6 Product Documentation
56
Important Notes about Custom Installations for Linux
Before running a custom installation of Chili!Soft ASP for Linux, review the following
information:
1. You use the Administration Console to start and stop the Chili!Soft ASP Server and to
change configuration settings. You can access the Administration Console by typing the
following URL in your Web browser address bar:
http://[HOSTNAME]:[PORT]
where [HOSTNAME] is the valid DNS name or IP address of the Apache Web Server
running the Chili!Soft ASP Administration Console and [PORT] is the port on which the
Administration Console is configured to run (5100 by default).
If you did not configure a Web server during installation, you will be prompted to configure
one when you first access the Administration Console.
2. If you chose the default configuration for the Chili!Soft ASP Administration Console, the
setup program configured the username as "admin" and the password as "root." To protect the
security of your server, it is highly recommended that you change the username and password
as soon as possible. For more information, see "Configuring Usernames and Passwords" in
"Chapter 3: Managing Chili!Soft ASP."
3. The Chili!Soft ASP setup program makes certain changes to the configuration files for the
associated Web server. For more information, see "Changes to Netscape Web Server
Configuration Files" or "Changes to Apache Web Server Configuration Files" in this chapter,
as appropriate.
4. If you installed Chili!Soft ASP to an Apache Web server that does not support Dynamic
Shared Object (DSO), you must manually link the Web server to Chili!Soft ASP and then
recompile it, as described in "Configuring a Non-DSO Apache Web Server" in this chapter. If
your Apache Web server supports DSO, there are no additional steps to take: Chili!Soft ASP
includes pre-built DSO modules that automatically link to your Web server.
5. To use Chili!Beans, you must enable Java support, as described in "Enabling Java Support"
in "Chapter 3: Managing Chili!Soft ASP." Chili!Beans enables you to access Java objects and
classes from an ASP script. For more information about Chili!Beans, see "Chili!Beans
Component Reference" in "Chapter 5: Developer's Reference."
6. When finished installing Chili!Soft ASP 3.6, it is a good idea to use the diagnostic
applications to verify that your installation is functioning correctly. (These diagnostic
applications will not function unless you have configured a Web server.) You can access the
diagnostics from the following URL:
http://[HOSTNAME]/caspsamp/diagnostics.htm
where [HOSTNAME] is the hostname of the Web server configured to run with Chili!Soft
ASP.
7. Important summary information about the installation is located in the following file:
[C-ASP_INSTALL_DIR]/logs/component_log
Chili!Soft ASP 3.6 Product Documentation
57
where [C-ASP_INSTALL_DIR] is the directory in which you installed Chili!Soft ASP
(/opt/casp by default).
It is a good idea to print this information for future reference.
Note
On Chili!Soft ASP 3.6 for Linux, you need to access your Web server by using the
"server address" specified in the Zeus Administration Console, rather than the address
specified in install_summary.
8. If you chose this option, the setup program installed the IBM DB2 7.01 Client Application
Enabler (CAE) on your computer in the following location:
/usr/lpp/db2_07_01
Before you can connect to the DB2 database, you must first configure a DSN, as described in
"Configuring Data Source Names (DSNs)" in "Chapter 3: Managing Chili!Soft ASP." Note that
you must use the cataloged name of the database for the DSN name. Chili!Soft ASP
automatically sets the correct database parameters and associates them with the cataloged name
of the database. In addition to configuring a DSN for DB2, you must load the DB2 profile as
described in "Loading DB2 Profiles" in "Chapter 3: Managing Chili!Soft ASP."
See also:
Installing a Custom Configuration of Chili!Soft ASP 3.6 for Linux in this chapter
Uninstalling Chili!Soft ASP in this chapter
Upgrading Chili!Soft ASP for Sun Solaris
Chili!Soft ASP 3.6.0-P1 for Sun Solaris automatically upgrades many of your settings from an
existing installation of Chili!Soft ASP 3.4.1. However, Chili!Soft ASP 3.6.0 does not upgrade
any settings. You can determine which version you have by viewing the README file found on
your Chili!Soft ASP 3.6 CD-ROM.
You can obtain Chili!Soft ASP 3.6.0-P1 for Sun Solaris from the Chili!Soft Web site at:
http://www.chilisoft.com/upgrades/solaris/
If you have already purchased Chili!Soft ASP 3.6 for Sun Solaris, you can obtain this version free
of charge.
If you are upgrading from a version other than Chili!Soft ASP 3.4.1, the setup program will not
preserve your existing settings. Before beginning the installation, go to the Chili!Soft Web site for
information about performing an upgrade, at:
http://www.chilisoft.com/support/
To perform an upgrade from Chili!Soft ASP 3.4.1 to Chili!Soft ASP 3.6.0-P1 for Sun Solaris,
you should follow the instructions provided in "Installing a Custom Configuration of Chili!Soft
ASP for Sun Solaris" in this chapter. In addition, you must take the steps described in this topic.
Before you begin the upgrade, take the following steps:
Chili!Soft ASP 3.6 Product Documentation
58
•
The Chili!Soft ASP 3.6.0-P1 setup program preserves the settings from your Chili!Soft
ASP 3.4.1 installation and then imports them into your new Chili!Soft ASP 3.6.0-P1
installation. However, you must take additional steps to configure the ASP Server after
setup is complete. These steps are described later in this topic. Be sure to review this
information prior to performing the upgrade.
•
If necessary, upgrade your Web server in order to meet the requirements listed in
"Installation Requirements: Chili!Soft ASP for Sun Solaris" in this chapter.
•
It is a good idea to back up your existing installation prior to beginning the upgrade.
•
It is not a good idea to upgrade a mission-critical production server. Performing the
upgrade and taking the additional configuration steps that are required might keep your
server offline for an unacceptably long period of time. If possible, you should mirror the
production server to a non-production server, perform the upgrade, and then test and
debug the upgraded server before deploying it in your production environment.
•
The new installation will completely overwrite your existing installation. Copy to another
location any items you want to preserve, such as COM components, that are contained
under your current Chili!Soft ASP installation directory. Otherwise, they will be lost. If
you are running SpicePack, you can obtain a free updated version of SpicePack from the
Chili!Soft Web site, as described next.
•
Chili!Soft ASP 3.6 does not support multiple ASP Servers. If you are running multiple
ASP Servers, e-mail Chili!Soft Customer Support at eval@chilisoft.com for instructions.
When the setup program has completed the installation, take the following steps:
•
If you were running SpicePack with your previous installation of Chili!Soft ASP 3.4.1,
you need to obtain the updated version, SpicePack 1.1, from the Chili!Soft Web site and
then install it. When you provide your SpicePack serial number, you can obtain a free
updated version at:
http://www.chilisoft.com/upgrades/spicepack/
The README_SPICEPACK file included with SpicePack provides installation
instructions.
•
Verify that any system DSNs defined for your previous installation are functioning
correctly. For more information, see "Testing a DSN" in "Chapter 3: Managing Chili!Soft
ASP." If they are not functioning, you can create or edit the system DSNs as needed, as
described in "Configuring Data Source Names (DSNs)" in "Chapter 3: Managing
Chili!Soft ASP." You can find the configuration information for the system DSNs that
were defined for your previous installation in the following file:
[C-ASP_INSTALL_DIR]/casp/INSTALL/settings.import
where [C-ASP_INSTALL_DIR] is the path name of the Chili!Soft ASP 3.6 installation
directory.
•
If you were running an Oracle, Sybase, or Informix database with your previous
installation, you must reconfigure your database environment, as described in
"Configuring the Database Environment" in "Chapter 3: Managing Chili!Soft ASP." You
Chili!Soft ASP 3.6 Product Documentation
59
can find the environment settings for your previous installation under the ODBC.INI
heading in the following file:
[C-ASP_INSTALL_DIR]/INSTALL/settings.import
where [C-ASP_INSTALL_DIR] is the path name of the Chili!Soft ASP 3.6 installation
directory.
•
The Chili!Soft ASP 3.6 setup program sets inherit_user to "yes" by default. This setting
can have important security implications for your server. Be sure to read "Setting the
Security Mode" in Chapter 3: Managing Chili!Soft ASP" for more information about
configuring this setting appropriately for your environment.
•
The Chili!Soft ASP 3.6 setup program sets EnableParentPaths to "no" by default. This
setting can have important security implications for your server. Be sure to read
"Configuring File System Access" in Chapter 3: Managing Chili!Soft ASP" for more
information about configuring this setting appropriately for your environment.
•
When you choose the option to run the ASP Server in multi-process mode, the Chili!Soft
ASP 3.6 setup program sets the Application Variables (AppVars) flag to Read-Only by
default. When set to Read-Only, application-level variables cannot be set or modified once
the global.asa file has been read. For information about changing this setting, see
"Changing ASP Server Settings" in "Chapter 3: Managing Chili!Soft ASP."
Upgrading Chili!Soft ASP for Linux
Chili!Soft ASP 3.6 for Linux automatically upgrades many of your settings from an existing
installation of Chili!Soft ASP 3.5.2. If you are upgrading from a version other than Chili!Soft
ASP 3.5.2, the setup program will not preserve your existing settings. Before beginning the
installation, go to the Chili!Soft Web site for information about performing an upgrade, at:
http://www.chilisoft.com/support/
To perform an upgrade from Chili!Soft ASP 3.5.2 for Linux to Chili!Soft ASP 3.6, you can
follow the instructions provided in "Installing a Custom Configuration of Chili!Soft ASP for
Linux" in this chapter. In addition, you must take the steps described in this topic.
Before you begin the upgrade, take the following steps:
•
The Chili!Soft ASP 3.6 setup program preserves the settings from your Chili!Soft ASP
3.5.2 installation and then imports them into your new Chili!Soft ASP 3.6 installation.
However, you must take additional steps to configure the ASP Server after setup is
complete. These steps are described later in this topic. Be sure to review this information
prior to performing the upgrade.
•
If necessary, upgrade your operating system and Web server in order to meet the
requirements listed in "Installation Requirements: Chili!Soft ASP for Linux" in this
chapter.
•
It is a good idea to back up your existing installation prior to beginning the upgrade.
•
It is not a good idea to upgrade a mission-critical production server. Performing the
upgrade and taking the additional configuration steps that are required might keep your
Chili!Soft ASP 3.6 Product Documentation
60
server offline for an unacceptably long period of time. If possible, you should mirror the
production server to a non-production server, perform the upgrade, and then test and
debug the upgraded server before deploying it in your production environment.
•
The new installation will completely overwrite your existing installation. Copy to another
location any items you want to preserve, such as COM components, that are contained
under your current Chili!Soft ASP installation directory. Otherwise, they will be lost. If
you are running SpicePack, you can obtain a free updated version of SpicePack from the
Chili!Soft Web site, as described next.
•
Note that your existing administrator username and password will be overwritten by the
new installation. The one you specify during setup will take effect.
•
Chili!Soft ASP 3.6 does not support multiple ASP Servers. If you are running multiple
ASP Servers, contact Chili!Soft Customer Support.
When the setup program has completed the installation, take the following steps:
•
If you were running SpicePack with your previous installation of Chili!Soft ASP 3.5.2,
you need to obtain the updated version, SpicePack 1.1, from the Chili!Soft Web site and
then install it. When you provide your SpicePack serial number, you can obtain a free
updated version at:
http://www.chilisoft.com/upgrades/spicepack/
The README_SPICEPACK file included with SpicePack provides installation
instructions.
•
Verify that any system DSNs defined for your previous installation are functioning
correctly. For more information, see "Testing a DSN" in "Chapter 3: Managing Chili!Soft
ASP." If they are not functioning, you can create or edit the system DSNs as needed, as
described in "Configuring Data Source Names (DSNs)" in "Chapter 3: Managing
Chili!Soft ASP." You can find the configuration information for the system DSNs that
were defined for your previous installation in the following file:
[C-ASP_INSTALL_DIR]/INSTALL/settings.import
where [C-ASP_INSTALL_DIR] is the path name of the Chili!Soft ASP 3.6 installation
directory.
•
The Chili!Soft ASP 3.6 setup program sets inherit_user to "yes" by default. This setting
can have important security implications for your server. Be sure to read "Setting the
Security Mode" in "Chapter 3: Managing Chili!Soft ASP" for more information about
configuring this setting appropriately for your environment.
•
The Chili!Soft ASP 3.6 setup program sets EnableParentPaths to "no" by default. This
setting can have important security implications for your server. Be sure to read
"Configuring File System Access" in "Chapter 3: Managing Chili!Soft ASP" for more
information about configuring this setting appropriately for your environment.
Chili!Soft ASP 3.6 Product Documentation
61
Installing and Upgrading Chili!Soft ASP 3.6 for Cobalt
To install Chili!Soft ASP 3.6 for Cobalt systems, you simply run the .pkg file, according to the
instructions provided with your software.
Chili!Soft ASP 3.6 is installed to the following directory:
/home/chiliasp
During installation, the setup program automatically configures your Apache Web Server to run
with Chili!Soft ASP. You do not need to take any additional steps to configure your Web server.
Important
The setup program sets the username and password required to access the Chili!Soft ASP
Administration Console to "admin" and "root." You should change these settings as soon
as possible, as described in "Configuring Usernames and Passwords" in "Chapter 3:
Managing Chili!Soft ASP."
Following installation, if you have a locale other than US English defined for your server, you
should change the locale setting for Chili!Soft ASP to match it. For instructions, see "Configuring
International Support" in "Chapter 3: Managing Chili!Soft ASP."
If you are upgrading to Chili!Soft ASP 3.6 from 3.5.2, you must take the following steps to
complete the upgrade:
•
If you were running SpicePack with your previous installation of Chili!Soft ASP 3.5.2,
you need to obtain the updated version, SpicePack 1.1, from the Chili!Soft Web site and
then install it. When you provide your SpicePack serial number, you can obtain a free
updated version at:
http://www.chilisoft.com/upgrades/spicepack/
•
Files contained under the Chili!Soft ASP installation directory (/home/chiliasp) will be
overwritten. Be sure to move any files you do not want to lose before performing the
upgrade.
•
Verify that any system DSNs defined for your previous installation are functioning
correctly. For more information, see "Testing a DSN" in "Chapter 3: Managing Chili!Soft
ASP." If they are not functioning, you can create or edit the system DSNs as needed, as
described in "Configuring Data Source Names (DSNs)" in "Chapter 3: Managing
Chili!Soft ASP." You can find the configuration information for the system DSNs that
were defined for your previous installation in the following file:
/home/chiliasp/INSTALL/settings.import
•
The Chili!Soft ASP 3.6 setup program sets inherit_user to "yes" by default. This setting
can have important security implications for your server. Be sure to read "Setting the
Security Mode" in "Chapter 3: Managing Chili!Soft ASP" for more information about
configuring this setting appropriately for your environment.
•
The Chili!Soft ASP 3.6 setup program sets EnableParentPaths to "no" by default. This
setting can have important security implications for your server. Be sure to read
Chili!Soft ASP 3.6 Product Documentation
62
"Configuring File System Access" in "Chapter 3: Managing Chili!Soft ASP" for more
information about configuring this setting appropriately for your environment.
Installing Chili!Soft ASP 3.6 for HP-UX
The topics in this section describe the requirements and procedures for installing Chili!Soft ASP
3.6 for HP-UX. For up-to-date information about this product, you can access the README file
as follows:
Before installation, you can find it at:
http://www.chilisoft.com/readme/
After installation, you can access the README file from the Chili!Soft ASP Administration
Console, as described in "Viewing the Product README File" in "Chapter 3: Managing
Chili!Soft ASP."
Important Upgrade Information
If you are upgrading from a previous version, the setup program will not preserve your
existing settings. Before beginning the installation, see the README file for instructions.
In this section:
•
Installation Requirements: Chili!Soft ASP for HP-UX
•
Choosing an Installation Option for HP-UX
•
Installing the Chili!Soft ASP Bundle for HP-UX
•
Installing a Custom Configuration of Chili!Soft ASP for HP-UX
Installation Requirements: Chili!Soft ASP for HP-UX
This topic lists the hardware and software requirements for running Chili!Soft ASP 3.6 for HPUX. It also lists the additional software, such as databases and tools, that Chili!Soft ASP
supports.
Hardware and Software Requirements
This section describes the hardware and software requirements for installing and running
Chili!Soft ASP 3.6 for HP-UX on your server.
Hardware
The minimum hardware configuration for your system is as follows:
•
128 MB RAM (256 or higher recommended)
•
Pentium class processor (x86)
•
230 MB free hard disk space (bundle Installation)
•
200 MB free hard disk space (custom Installation)
Chili!Soft ASP 3.6 Product Documentation
63
Operating System
You can install and run Chili!Soft ASP 3.6 for HP-UX on a computer running the following
operating system:
•
HP-UX 11.00
Chili!Soft ASP 3.6 requires that certain runtime library patches for the HP-UX operating system
are installed. For the best performance, it is strongly recommended that you install the latest
general release patch bundle. General release bundles are tested sets of HP-UX core patches that
keep your operating system up to date.
You can obtain the general release patch bundle from HP at:
http://www.software.hp.com/SUPPORT_PLUS/
Alternatively, you can obtain the following individual patches from HP at:
http://us-support.external.hp.com/common/bin/doc.pl/
The required patches are as follows:
•
PHSS_21959 (X/Motif 32 bit Runtime AUG2000 Periodic Patch)
•
PHSS_21961 (X/Motif 64 bit Runtime AUG2000 Periodic Patch)
•
PHSS_21906 (HP aC++ runtime libraries (aCC A.03.26))
•
PHSS_22478 (ld(1) and linker tools cumulative patch)
•
PHCO_22314 (libc cumulative patch)
•
PHSS_16931 (milli.a cumulative patch)
•
PHSS_21950 (LIBCL patch)
•
PHKL_18543 - (PM/VM/UFS/async/scsi/io/DMAPI/JFS/perf patch)
•
PHCO_19666 - (libpthreads cumulative patch)
•
PHKL_23002 - (Fix pthread error return, nfs/tcp panic)
Web Server
For a custom installation of Chili!Soft ASP 3.6 for HP-UX, you must be running one of the
following Web servers (the bundle installation includes Apache Web Server 1.3.12 DSO):
•
Apache Web Server 1.3.12 DSO, NDSO
•
Apache Web Server 1.3.14 DSO
•
iPlanet/Netscape Enterprise 4.0, 4.1
•
Zeus Web Server 3.3.7
Software
Perl 5.005_03 or later must be running on the computer to which you are installing Chili!Soft
ASP 3.6.
Chili!Soft ASP 3.6 Product Documentation
64
Supported Software
This topic lists additional software supported and/or installed by Chili!Soft ASP 3.6 for HP-UX.
Database
Chili!Soft ASP 3.6 for HP-UX includes ODBC drivers for the following databases:
•
dBase 5
•
Informix 7, 9
•
Microsoft Access*
•
Microsoft SQL Server 6.5*
•
Microsoft SQL Server 7.0
•
Oracle 8
•
Sybase 11
ODBC drivers are installed automatically by the Chili!Soft ASP setup program. Following
installation, you must configure the drivers for the data source being used. For more information,
see "Configuring a Database" in "Chapter 3: Managing Chili!Soft ASP."
*Note
To provide remote database connectivity with Microsoft Access and Microsoft SQL
Server 6.5 databases, Chili!Soft ASP 3.6 ships with the client portion of the Merant
SequeLink 4.51a software. You also must download install the server portion of this
software from Chili!Soft. For more information, see "Configuring SequeLink" in
"Chapter 3: Managing Chili!Soft ASP."
Java Runtime Environment and Patches
To enable Chili!Beans, Chili!Soft ASP 3.6 for HP-UX installs the Java Runtime Environment
(JRE) 1.2.2.07 on the computer running the ASP Server. ChiliBeans enables you to use Java class
files as components called from VBScript or JScript. For more information, see "Chili!Beans
Component Reference" in "Chapter 5: Developer's Reference."
Before installing Chili!Soft ASP 3.6, you must have the Java Runtime Environment (JRE)
patches for HP-UX 11.00 installed, which you can obtain at:
http://www.unix.hp.com/java/infolibrary/patches.html
Microsoft FrontPage 2000 Server Extensions
Microsoft FrontPage 2000 Server Extensions are included in the bundle installation of Chili!Soft
ASP 3.6. They provide services to the Web server that work in conjunction with Chili!Soft ASP
to provide FrontPage functionality to computers that are not running Microsoft Windows
NT/2000 and Internet Information Services (IIS). For more information, see "Installing FrontPage
2000 Server Extensions" in "Chapter 3: Managing Chili!Soft ASP."
See also:
Chili!Soft ASP 3.6 Product Documentation
65
Installing Chili!Soft ASP 3.6 for HP-UX in this chapter
Choosing an Installation Option for HP-UX in this chapter
Installing a Custom Configuration of Chili!Soft ASP for HP-UX in this chapter
Installing the Chili!Soft ASP Bundle for HP-UX in this chapter
Uninstalling Chili!Soft ASP in this chapter
Choosing an Installation Option for HP-UX
The Chili!Soft ASP setup program takes you through all of the steps required to install the
Chili!Soft ASP 3.6 for HP-UX. It provides the following two installation options:
•
Bundle installation. This is the easiest way to install Chili!Soft ASP. With a bundle
installation, the setup program automatically installs and configures the following
components on the target server:
Chili!Soft ASP Server
Chili!Soft ASP Administration Console
Chili!Beans
Java Runtime Environment (JRE) 1.2.2.07 (required for Chili!Beans)
Apache Web Server 1.3.12
Microsoft FrontPage 2000 Server Extensions
dBase 5 database and samples
For instructions about performing a bundle installation, see "Installing the Chili!Soft ASP
Bundle for HP-UX" in this chapter.
•
Custom installation. With this option, the setup program installs the following
components on the target server:
Chili!Soft ASP Server
Chili!Soft ASP Administration Console
Chili!Beans
Java Runtime Environment (JRE) 1.2.2.07 (required for Chili!Beans)
Apache Web Server 1.3.12
The setup program gives you the option to either specify the configuration options or
accept the default configuration settings. The configuration settings you specify during a
custom installation can have serious consequences for your server environment. For
instructions about performing this installation, see "Installing a Custom Configuration of
Chili!Soft ASP for HP-UX" in this chapter.
For up-to-date information about Chili!Soft ASP 3.6 and its components, see the README file
that was installed with your software. You can access it from the Administration Console by
clicking customer support in the left navigation pane.
Chili!Soft ASP 3.6 Product Documentation
66
See also:
Installing Chili!Soft ASP 3.6 for HP-UX in this chapter
Installation Requirements—Chili!Soft ASP for HP-UX in this chapter
Uninstalling Chili!Soft ASP in this chapter
Installing the Chili!Soft ASP Bundle for HP-UX
This topic describes the steps to install the Chili!Soft ASP 3.6 bundle for HP-UX. For more
information about a bundle installation, see "Choosing an Installation Option for HP-UX" in this
chapter.
Before you begin, make sure you meet the following requirements:
•
You are logged in as root.
•
If you are downloading Chili!Soft ASP from the Web, you must have 45 MB of hard disk
space available in order to extract the installation files.
•
Your hardware and software meet the requirements listed in "Installation Requirements—
Chili!Soft ASP for HP-UX" in this chapter.
•
You know your product serial number. Chili!Soft ASP requires a valid serial number in
order to run. If you downloaded the product from the Web, you should have received an email message that included your serial number. If you are installing this product from a
CD-ROM, the serial number is printed on the CD-ROM case. If you are installing a trial
version from a CD-ROM, you must obtain a serial number at:
http://www.chilisoft.com/register
•
You know what language you want Chili!Soft ASP to support. The options are US
English, British English, Dutch, French, German, Japanese Shift-JIS, Spanish, and
Swedish. If you want, you can change the language after installation, as described in
"Configuring International Support" in "Chapter 3: Managing Chili!Soft ASP."
•
If FrontPage Server Extensions are already installed on your computer, the Chili!Soft ASP
setup program cannot properly install and configure the FrontPage 2000 Server
Extensions that are included in the bundle installation. If you already have FrontPage
Server Extensions installed, you must uninstall them before installing the Chili!Soft ASP
3.6 bundle.
•
For the Chili!Soft ASP Administration Console, you need to specify a username and
password. Be sure to specify a password that you can remember, or else plan to store it in
a secure location. If you forget your password, you can run the admtool utility and set a
new password, as described in "Configuring Usernames and Passwords" in "Chapter 3:
Managing Chili!Soft ASP."
•
If you have a previous installation of Chili!Soft ASP in the bundle installation directory
(/usr/local/chilisoft), you must uninstall it before installing this version. For information
about uninstalling Chili!Soft ASP, see the documentation that was included with the
version you must uninstall. For information about preserving your configuration settings,
contact Chili!Soft Customer Support at eval@chilisoft.com.
Chili!Soft ASP 3.6 Product Documentation
67
Important Upgrade Information
If you are upgrading from a previous version, the setup program will not preserve your
existing settings. Before beginning the installation, see the README file for instructions.
To install the Chili!Soft ASP 3.6 bundle for HP-UX, use the following procedure.
To install the Chili!Soft ASP bundle for HP-UX
1. If you are installing Chili!Soft ASP from a CD-ROM, skip this step and go to step 2. If you
are downloading Chili!Soft ASP from the Web, download the casp-3.6.0-hpux.tar file to a
temporary directory, and then extract the installation files by using the following command:
#> tar -xvf casp-3.6.0-hpux.tar
This step creates the following files in the temporary directory, which you can delete after
completing the installation:
A README file containing important product information
The install.sh installation script
A package directory containing the Chili!Soft ASP installation files and the EULA
license file
2. Run the install.sh script by using the following command. For downloaded versions, this
script is located in the temporary directory you created in the previous step. For CD-ROM
versions, this script is located on your installation CD-ROM.
#> ./install.sh
3. Review the End-User License Agreement (EULA) that displays. Enter yes if you agree to its
conditions. You must type the entire word, "yes."
– or –
Enter no if you do not agree. If you enter no, the Chili!Soft ASP setup program cancels the
installation.
4. On the next screen, enter 1 to select the Bundle option. The setup program extracts the
installation packages.
5. On the next screen, press Enter if you want to install the bundled Apache Web Server to port
80.
– or –
Enter a different port number for the Apache Web Server to use.
6. On the next screen, enter your administrator username.
– or –
Press Enter to accept the default administration username ("admin"). To protect the security
of your server, it is highly recommended that you do not accept the default username.
7. When prompted, enter the administrator password.
8. When prompted, re-enter the administrator password to confirm it.
Chili!Soft ASP 3.6 Product Documentation
68
9. On the next screen, enter y (yes) if you know the product serial number. If you do not know
the serial number, enter n. Chili!Soft ASP will not run without a serial number, so if you
enter n, the setup program aborts the installation.
10. When prompted, enter the product serial number.
11. On the next screen, press Enter to accept the default language ("English – US").
– or –
Enter the number of a language shown in the list.
The setup program automatically installs the Chili!Soft ASP bundle to the following directory
and performs basic configuration of the software:
/usr/local/chilisoft/
Before running a bundle installation of Chili!Soft ASP, see "Important Notes About Bundle
Installations for HP-UX," next.
For more information about running and configuring Chili!Soft ASP, see "Chapter 3: Managing
Chili!Soft ASP."
See also:
Installing Chili!Soft ASP 3.6 for HP-UX in this chapter
Uninstalling Chili!Soft ASP in this chapter
Important Notes about Bundle Installations for HP-UX
Before running a bundle installation of Chili!Soft ASP for HP-UX, please review the following
information:
1. You use the Chili!Soft ASP Administration Console to start and stop the Chili!Soft ASP
Server and to change configuration settings. You can access the Administration Console by
typing the following URL in your Web browser address bar:
http://[HOSTNAME]:[PORT]
where [HOSTNAME] is the valid DNS name or IP address of the Apache Web Server
running the Chili!Soft ASP Administration Console and [PORT] is the port on which the
Administration Console is configured to run (5100 by default).
For more information about the configuring and running Chili!Soft ASP, see "Chapter 3:
Managing Chili!Soft ASP."
2. In order to use Chili!Beans, you must enable Java support, as described in "Enabling Java
Support" in "Chapter 3: Managing Chili!Soft ASP." Chili!Beans enables you to access Java
objects and classes from an ASP script. For more information about Chili!Beans, see
"Chili!Beans Component Reference" in "Chapter 5: Developer's Reference."
3. When finished installing Chili!Soft ASP 3.6, it is a good idea to use the diagnostic
applications to verify that your installation is functioning correctly. You can access the
diagnostics from the following URL:
http://[HOSTNAME]/caspsamp/diagnostics.htm
Chili!Soft ASP 3.6 Product Documentation
69
where [HOSTNAME] is the hostname of the Web server configured to run with Chili!Soft
ASP.
4. Important summary information about the installation is located in the following file:
/usr/local/chilisoft/casp/logs/install_summary
It is a good idea to print this information for future reference.
See also:
Installing the Chili!Soft ASP Bundle for HP-UX in this chapter
Uninstalling Chili!Soft ASP in this chapter
Installing a Custom Configuration of Chili!Soft ASP for HP-UX
This topic describes the steps to install a custom configuration of Chili!Soft ASP 3.6 for HP-UX.
For more information about a custom installation, see "Choosing an Installation Option for HPUX" in this chapter.
The configuration options you specify when installing a custom configuration of Chili!Soft ASP
can have serious consequences for your server environment. Before you begin, make sure you
meet the following requirements:
•
You are logged in as root.
•
If you are downloading Chili!Soft ASP from the Web, you must have 45 MB of hard disk
space available in order to extract the installation files.
•
Your hardware and software must meet the requirements listed in "Installation
Requirements—Chili!Soft ASP for HP-UX" in this chapter.
•
You must know your product serial number. Chili!Soft ASP requires a valid serial number
in order to run. If you downloaded the product from the Web, you should have received an
e-mail message that included your serial number. If you are installing this product from a
CD-ROM, the serial number is printed on the CD-ROM case. If you are installing a trial
version from a CD-ROM, you must obtain a serial number at:
http://www.chilisoft.com/register
•
You must shut down the Web server that you want to configure to run with Chili!Soft
ASP, and be prepared to provide the following information:
Absolute path name of the Web server main configuration file (for example,
/usr/HTTPServer/conf/httpd.conf)
Absolute path name of the Web server binary (for example, /usr/HTTPServer/bin/httpd)
Web server version (for example, 1.3.12)
Web server type (for example, Apache)
Web server port number (for example, 80)
Web server root directory (for example, /usr/HTTPServer)
Chili!Soft ASP 3.6 Product Documentation
70
•
If you configure Chili!Soft ASP to run with an Apache Web Server that does not support
Dynamic Shared Objects (DSO), following installation you must manually link the Web
server to Chili!Soft ASP and then recompile it, as described in "Configuring a Non-DSO
Apache Web Server" in this chapter. If your Apache Web Server supports DSO, there are
no additional steps to take: Chili!Soft ASP includes pre-built DSO modules that
automatically link to your Web server.
•
When configuring the Zeus Web Server to run with Chili!Soft ASP 3.6, do not specify the
Web server hostname as the fully qualified domain name (or "server address"). If you do,
the Test DSN feature of the Administration Console will not work. Instead, use the
hostname only.
For example, do not use this: hostname.domain.com
Instead, use this: hostname
•
If you choose to customize settings for the Chili!Soft ASP Administration Console, you
will need to specify a username and password for accessing it. Be sure to specify a
password that you can remember, or else plan to store it in a secure location. If you forget
your password, you can run the admtool utility and set a new password, as described in
"Configuring Usernames and Passwords" in "Chapter 3: Managing Chili!Soft ASP." If
you do not choose the customize settings option, the username is set as "admin" and the
password as "root." To protect the security of your server, you should run the admtool and
change these as soon as possible.
•
You need to know what language you want Chili!Soft ASP to support. The options are US
English, British English, Dutch, French, German, Japanese Shift-JIS, Spanish, and
Swedish. If you want, you can change the language after installation, as described in
"Configuring International Support" in "Chapter 3: Managing Chili!Soft ASP."
Important Upgrade Information
If you are upgrading from a previous version, the setup program will not preserve your
existing settings. Before beginning the installation, see the README file for instructions.
To install a custom configuration of Chili!Soft ASP 3.6 for HP-UX, use the following procedure.
To install a custom configuration of Chili!Soft ASP for HP-UX
1. If you are installing Chili!Soft ASP from a CD-ROM, skip this step and go to step 2. If you
are downloading Chili!Soft ASP from the Web, download the casp-3.6.0-HPUX.tar file to a
temporary directory, and then extract the installation files by using the following command:
#> tar -xvf casp-3.6.0-HPUX.tar
This step creates the following files in the temporary directory, which you can delete after
completing the installation:
A README file containing important product information
The install.sh installation script
A package/EULA file containing the end-user license agreement
A package/directory containing files required to install Chili!Soft ASP
Chili!Soft ASP 3.6 Product Documentation
71
2. Run the install.sh script by using the following command. For downloaded versions, this
script is located in the temporary directory you created in the previous step. For CD-ROM
versions, this script is located on your installation CD-ROM.
#> ./install.sh
3. Review the End-User License Agreement (EULA) that displays. Enter yes if you agree to its
conditions. You must type the entire word, "yes."
– or –
Enter no if you do not agree. If you enter no, the Chili!Soft ASP setup program cancels the
installation.
4. On the next screen, enter 2 to select the Custom option.
5. On the next screen, press Enter to accept the default Chili!Soft ASP installation directory
(/opt/casp).
– or –
Enter the absolute path name of the installation directory you want. It is a good idea to make
a note of this location so that you can easily find the Chili!Soft ASP files at a later time.
6. If the setup program detects a previous installation of Chili!Soft ASP in the specified
directory, it asks whether or not you want to uninstall the previous version and continue.
Enter y (yes) to uninstall the previous installation and continue.
– or –
Enter n (no) to cancel the installation.
7. On the next screen, enter y (yes) if you know the product serial number.
– or –
If you do not know the serial number, enter n. Chili!Soft ASP will not run without a serial
number, so if you enter n, the setup program aborts the installation.
8. When prompted, enter the product serial number.
9. On the next screen, press Enter to accept the default language (English – US).
– or –
Enter the number of a language shown in the list.
10. The next screen provides options for choosing the Web server to configure with Chili!Soft
ASP. If you want the setup program to search your system and generate a list of installed
Web servers from which to select, enter the number of the search option you want (1, 2, or 3).
If you select one of these search options, skip to step 14.
– or –
If you want to skip this search and provide information about the Web server, enter 4 (Don't
search). If you choose option 4 (Don’t search), follow the instructions in step 11.
Chili!Soft ASP 3.6 Product Documentation
72
11. If you want to provide information about the Web server to configure, on the next screen,
enter 1 (Specify the Webserver), and then follow the instructions in step 12.
– or –
If you want the setup program to search for installed Web servers from which to select, enter
2 (Refresh the webserver list), and then follow the instructions in step 10.
– or –
If you do not want to configure a Web server during installation, enter 3 (Do not configure a
webserver), and then go to step 16. If you choose this option, the first time you open the
Chili!Soft ASP Administration Console, you will be prompted to configure the ASP Server
and a Web server.
12. On the next screen, enter the number of the type of Web server to configure: 1 for Apache, 2
for Netscape, or 3 for Zeus, and go to the next step.
– or –
To cancel the user-specified Web server configuration, enter 4. If you choose this option, the
setup program returns you to the previous screen. From this screen you can choose another
option, as described in step 11.
13. At the prompts, enter the requested information about the Web server, and go to step 15.
14. On the next screen, enter the number of the Web server you want the setup program to
configure to run with Chili!Soft ASP, and go to the next step.
– or –
To provide information about the Web server to configure, enter the number for the option,
Specify the Webserver. If you choose this option, follow the instructions in step 12.
– or –
To perform another search for installed Web servers, enter the number for the option,
Refresh the webserver list. If you choose this option, follow the instructions in step 10.
– or –
If you do not want to configure a Web server during installation, enter the number for the
option, Do not configure a Webserver, and then go to step 16. If you choose this option, the
first time you open the Chili!Soft ASP Administration Console, you will be prompted to
configure the ASP Server and a Web server.
15. On the next screen, verify the information that the setup program displays about your Web
server. If the information is incorrect, the Chili!Soft ASP installation could fail. In this event,
you can run the installation script again. If you do this, it is recommended that you first run
the uninstall script, as described in "Uninstalling Chili!Soft ASP" in this chapter. If the
information on the screen is correct, enter y (yes), and go to the next step.
– or –
If the information is incorrect, enter n (no). The setup program returns you to the previous
screen. For this screen, follow the instructions in step 14.
Chili!Soft ASP 3.6 Product Documentation
73
16. On the next screen, choose a configuration option for the ASP Server. Enter 1 to choose a
default configuration, and go to the next step.
– or –
Enter 2 to choose a custom configuration, and enter the following information at the prompts:
Would you like me to restart this Web server for you? Enter y (yes) if you want the
setup program to automatically restart the Web server after completing Chili!Soft ASP
installation, or enter n (no) if you do not want this.
Choose a mode. Enter the number of the mode in which you want to run the ASP
Server, or enter 3 for more information about this option.
1. Multi-threaded
2. Multi-process
3. More information
Enable samples on this Web server? Enter y (yes) if you want the setup program to
install and configure the Chili!Soft ASP samples on your Web server, or n (no) if you do
not want this.
Enable documentation on this Web server? Enter y (yes) if you want the setup
program to install and configure the Chili!Soft ASP documentation on your Web server,
or n (no) if you do not want this. If you enter n, the documentation will be available
from the Administration Console, but not from the Chili!Soft ASP Start Page.
Start the Chili!Soft ASP on system boot? Enter y (yes) if you want the setup program
to start Chili!Soft ASP automatically each time you start the computer, or type n (no) if
you do not want this.
Would you like to start this Chili!Soft ASP server? Enter y (yes) if you want the setup
program to start Chili!Soft ASP automatically immediately after you finish installing it,
or n (no) if you do not want this.
– or –
Enter 3 to choose another Web server to configure for Chili!Soft ASP, and follow the
instructions in step 10.
17. On the next screen, select a configuration option for the Administration Console. When you
choose Auto-Select/Default, the setup program configures the console using default settings.
With this option, it specifies the username as "admin" and the password as "root." To protect
the security of your server, it is highly recommend that you change these settings as soon as
possible. For information about doing this, see "Configuring Usernames and Passwords" in
"Chapter 3: Managing Chili!Soft ASP."
If you choose Customize Settings, enter the following information at the prompts:
Administration Console port number: Enter the number of the port on which the Web
server should listen for requests for the Administration Console, or press Enter to accept
the default.
Chili!Soft ASP 3.6 Product Documentation
74
Automatically start the Administration Console on system startup: Enter y (yes) if
you want the Administration Console to start automatically each time you start the
computer, or n (no) if you do not want this.
Type the username: Enter the administrator username.
New password: Enter the administrator password, which is required for accessing the
Administration Console. It is a good idea to make note of this password because you
cannot access the Administration Console without providing it.
Confirm password: Re-enter the password.
18. The next screen provides summary information about your Administration Console
configuration, including the URL for accessing it. It is a good idea to make a note of this
information or else print this screen for future reference. When finished, press Enter to
complete the installation.
The setup program then completes the installation and writes a summary file to:
[C-ASP_INSTALL_DIR]/logs/install_summary
where [C-ASP_INSTALL_DIR] is the directory in which you installed Chili!Soft ASP (/opt/casp
by default). It is a good idea to print the information contained in the install_summary file for
future reference.
Before running a custom installation of Chili!Soft ASP, see "Important Notes About Custom
Installations for HP-UX" in this chapter.
For information about the changes the setup program makes to your Web server configuration
files, see "Changes to Netscape Web Server Configuration Files" or "Changes to Apache Web
Server Configuration Files" in this chapter, as appropriate.
See also:
Installing Chili!Soft ASP 3.6 for HP-UX in this chapter
Uninstalling Chili!Soft ASP in this chapter
Important Notes about Custom Installations for HP-UX
Before running a custom installation of Chili!Soft ASP 3.6 for HP-UX, review the following
information:
1. If you chose the default configuration for the Administration Console, the setup program
configured the username as "admin" and the password as "root. " To protect the security of
your server, it is highly recommended that you change the username and password as soon as
possible. For more information, see "Configuring Usernames and Passwords" in "Chapter 3:
Managing Chili!Soft ASP. "
2. The Chili!Soft ASP setup program makes certain changes to the configuration files for the
associated Web server. For more information, see "Changes to Netscape Web Server
Configuration Files" or "Changes to Apache Web Server Configuration Files" in this chapter,
as appropriate.
Chili!Soft ASP 3.6 Product Documentation
75
3. If you installed Chili!Soft ASP to an Apache Web Server that does not support Dynamic
Shared Object (DSO), you must manually link the Web server to Chili!Soft ASP and then
recompile it, as described in "Configuring a Non-DSO Apache Web Server" in this chapter. If
your Apache Web server supports DSO, there are no additional steps to take: Chili!Soft ASP
includes pre-built DSO modules that automatically link to your Web server.
4. You use the Administration Console to start and stop the Chili!Soft ASP Server and to
change configuration settings. You can access the Administration Console by typing the
following URL in your Web browser address bar:
http://[HOSTNAME]:[PORT]
where [HOSTNAME] is the valid DNS name or IP address of the Apache Web Server
running the Chili!Soft ASP Administration Console and [PORT] is the port on which the
Administration Console is configured to run (5100 by default).
5. To use Chili!Beans, you must enable Java support, as described in "Enabling Java Support"
in "Chapter 3: Managing Chili!Soft ASP." Chili!Beans enables you to access Java objects and
classes from an ASP script. For more information about Chili!Beans, see "Chili!Beans
Component Reference" in "Chapter 5: Developer's Reference."
6. When finished installing Chili!Soft ASP 3.6, it is a good idea to use the diagnostic
applications to verify that your installation is functioning correctly. You can access the
diagnostics from the following URL:
http://[HOSTNAME]/caspsamp/diagnostics.htm
where [HOSTNAME] is the hostname of the Web server configured to run with Chili!Soft
ASP.
7. Important summary information about the installation is located in the following file:
[C-ASP_INSTALL_DIR]/logs/install_summary
where [C-ASP_INSTALL_DIR]is the directory in which you installed Chili!Soft ASP
(/opt/casp by default).
It is a good idea to print this information for future reference.
See also:
Installing a Custom Configuration of Chili!Soft ASP for HP-UX in this chapter
Uninstalling Chili!Soft ASP in this chapter
Configuring the Web Server After Installation
This topic describes how to configure a Web server to run with Chili!Soft ASP, if you did not do
so during installation.
Note
This information does not apply to Cobalt platforms. On Cobalt platforms, the Web
server is configured automatically during installation.
Chili!Soft ASP 3.6 Product Documentation
76
When you configure a Web server to run with Chili!Soft ASP, either during installation or
afterwards (as described in this topic), the setup program makes certain changes to your Netscape
and Apache Web Server configuration files, as described in the following topics:
•
Changes to Netscape Web Server Configuration Files
•
Changes to Apache Web Server Configuration Files
In addition, after configuring an Apache Web Server that does not support Dynamic Shared
Objects (DSO) to run with Chili!Soft ASP you must make changes to your Web server, as
described in the following topic:
•
Configuring a Non-DSO Apache Web Server
Use the following procedure to configure a Web server if you did not do so during a custom
installation of Chili!Soft ASP:
To configure a Web server after installation
1. Open the Administration Console by using the following URL:
http://[HOSTNAME]:[PORT]
where [HOSTNAME] is the hostname of your Web server and [PORT] is the port on which
the Administration Console is running (5100 by default).
The Administration Console Add ASP Server page displays a list of Web servers that it has
detected on this computer.
2. Select the radio button of the Web server you want to configure, and then go to step 4.
- or –
Click Search Webservers to refresh the list of detected Web servers, and then go to step 3.
- or –
Type the absolute path name of the configuration file for the Web server you want to
configure, and then go to step 4.
3. The Search Webservers page displays, along with a web servers search popup box. When
the search is finished, the popup box displays the message Done. When you see this message,
click Add a Server on the Search Webservers page, and then follow the instructions in step
2.
4. Select or deselect the Insert Chili!Soft samples checkbox to enable or disable the Chili!Soft
sample applications, as desired.
5. Click OK.
6. The Administration Console Server Management page appears. From this page, you can
configure the ASP Server and Web server, as described in "Managing the ASP Server" and
"Managing the Web Server" in "Chapter 3: Managing Chili!Soft ASP."
Chili!Soft ASP 3.6 Product Documentation
77
Changes to Netscape Web Server Configuration Files
When you perform a custom installation of Chili!Soft ASP on a computer running Netscape Web
Server, the Chili!Soft ASP setup program makes the following three changes to the Netscape
Web Server configuration files:
1. It adds lines to the beginning of the obj.conf file, as follows:
On Sun Solaris:
Init fn="load-modules" funcs="caspreq,caspinit,casptrans" shlib="[CASP_INSTALL_DIR]/module/sunos5_optimized/netscape/nes_casp2.so"
Init fn="caspinit" casplib="[C- ASP_INSTALL_DIR]/asp-[SERVER][PORT]"
On Linux:
Init fn="load-modules" funcs="caspreq,caspinit,casptrans" shlib="[CASP_INSTALL_DIR]/module/netscape/nes_casp2.so"
Init fn="caspinit" casplib="[C- ASP_INSTALL_DIR]/asp-[SERVER][PORT]"
On IBM AIX:
Init fn="load-modules" funcs="caspreq,caspinit,casptrans" shlib="[CASP_INSTALL_DIR] module/aix4_optimized/netscape/nes_casp2.so"
Init fn="caspinit" casplib="[C- ASP_INSTALL_DIR]/asp-[SERVER][PORT]"
On HP-UX:
Init fn="load-modules" funcs="caspreq,caspinit,casptrans" shlib="[CASP_INSTALL_DIR]/module/ux11_optimized/netscape/nes_casp2.so"
Init fn="caspinit" casplib="[C- ASP_INSTALL_DIR]/asp-[SERVER][PORT]"
2. It adds the following lines to the default object section of obj.conf:
<Object name=default>
Service method=(GET|POST) type="chilisoft-internal/active-serverpage" fn="caspreq" casplib="[C- ASP_INSTALL_DIR]/asp-[SERVER][PORT]"
</Object>
3. It adds the following lines to the mime.types file:
type=chilisoft-internal/active-server-page exts=asp,asa
[C- ASP_INSTALL_DIR] resembles: /opt/casp
[SERVER] resembles: apache
[PORT] resembles: 80
Chili!Soft ASP 3.6 Product Documentation
78
Note
Chili!Soft ASP only supports one instance of LoadObjects in the Netscape Web Server
magnus.conf file.
See also:
Installing a Custom Configuration of Chili!Soft ASP for IBM AIX in this chapter
Installing a Custom Configuration of Chili!Soft ASP for Sun Solaris in this chapter
Installing a Custom Configuration of Chili!Soft ASP for Linux in this chapter
Installing a Custom Configuration of Chili!Soft ASP for HP in this chapter
Changes to Apache Web Server Configuration Files
When you perform a custom installation of Chili!Soft ASP 3.6 on a computer running Apache
Web Server, the Chili!Soft ASP setup program makes the following changes to the Web server
configuration files:
1. For Apache Web Server 1.3.9, 1.3.11, 1.3.12, and 1.3.14 it adds these lines to httpd.conf:
AddHandler chiliasp .asp
AddHandler chiliasp .asa
CaspLib [C- ASP_INSTALL_DIR]/asp-[SERVER]-[PORT]
2. For Apache Web Server 1.3.9, 1.3.11, 1.3.12, and 1.3.14 with Dynamic Shared Object (DSO)
support, the Chili!Soft ASP setup program also adds lines to httpd.conf, as follows:
On Sun Solaris:
LoadModule casp2_module [CASP_INSTALL_DIR]/module/sunos5_optimized/apache_[VERSION]/[API]/mod_
casp2.so
AddModule mod_casp2.c
On Linux:
LoadModule casp2_module [CASP_INSTALL_DIR]/module/linux2_optimized/apache_[VERSION]/[API]/mod_
casp2.so
AddModule mod_casp2.c
On IBM AIX:
LoadModule casp2_module [CASP_INSTALL_DIR]/module/aix4_optimized/apache_[VERSION]/[API]/mod_ca
sp2.so
AddModule mod_casp2.c
On HP-UX:
Chili!Soft ASP 3.6 Product Documentation
79
LoadModule casp2_module [CASP_INSTALL_DIR]/module/ux11_optimized/apache_[VERSION]/[API]/mod_ca
sp2.so
AddModule mod_casp2.c
[C- ASP_INSTALL_DIR] resembles: /opt/casp
[VERSION] resembles: 1.3.9
[API] is: eapi or standard
Note
If you are installing Chili!Soft ASP to an Apache Web Server that does not have DSO
support, see "Configuring a Non-DSO Apache Web Server" in this chapter.
See also:
Installing a Custom Configuration of Chili!Soft ASP for IBM AIX in this chapter
Installing a Custom Configuration of Chili!Soft ASP for Sun Solaris in this chapter
Installing a Custom Configuration of Chili!Soft ASP for Linux in this chapter
Installing a Custom Configuration of Chili!Soft ASP for HP in this chapter
Configuring a Non-DSO Apache Web Server
Read this section if you have performed a custom installation of Chili!Soft ASP on a computer
running an Apache Web Server that does not have Dynamic Shared Object (DSO) support.
When you perform a custom installation of Chili!Soft ASP 3.6 on a computer running Apache
Web Server, the setup program automatically links Chili!Soft ASP to Apache Web Server
through Apache’s module facility. The setup program uses pre-built Chili!Soft ASP DSO
modules to set up everything for you. However, if you are running a non-DSO version of Apache
(e.g., one that does not have DSO support), then you must use the following procedure to link
Chili!Soft ASP to Apache Web Server.
Note
The Chili!Soft ASP setup program also makes certain changes to the configuration files
for the associated Web server. For more information about the changes to Apache Web
Server, see "Changes to Apache Web Server Configuration Files" in this chapter.
To manually link the Chili!Soft ASP module to an Apache Web Server that does not have DSO
support, use the following procedure after you have finished installing Chili!Soft ASP.
To link the Chili!Soft ASP module to Apache Web Server
1. Stop the Apache Web Server.
Chili!Soft ASP 3.6 Product Documentation
80
2. Copy the files "module/source/build/mod_casp2.c" and "module/source/build/dispint.h" from
the Chili!Soft ASP installation directory to the "src/modules/extra" subdirectory of your
Apache Web Server source tree directory.
3. From the Apache source tree directory, enter the following (Note that if you have changed the
Apache Web Server configuration, your settings might vary from this example):
#> ./configure --prefix=[ROOT_DIRECTORY] --activatemodule=src/modules/extra/mod_casp2.c
where [ROOT_DIRECTORY] is the root directory for the Apache Web Server.
4. (Important: On HP-UX, do not take this step. Go to step 5 instead.) When the script has
finished running, use a text editor to add "-ldl" to the EXTRA_LIBS section of src/Makefile.
Return to the Apache installation directory, and enter the following:
# make
Copy the new Web server files to the appropriate location by entering:
# make install
5. Installation is automatic. When installation is complete, restart the Apache Web Server, and
then start the Chili!Soft ASP Server, as described in "Stopping and Restarting the ASP
Server" in "Chapter 3: Managing Chili!Soft ASP."
See also:
Installing a Custom Configuration of Chili!Soft ASP for IBM AIX in this chapter
Installing a Custom Configuration of Chili!Soft ASP for Sun Solaris in this chapter
Installing a Custom Configuration of Chili!Soft ASP for Linux in this chapter
Installing a Custom Configuration of Chili!Soft ASP for HP in this chapter
Uninstalling Chili!Soft ASP
You can uninstall Chili!Soft ASP 3.6 by running the script named "uninstall" located in the
Chili!Soft ASP installation directory.
Note
There is not option to uninstall Chili!Soft ASP on Cobalt platforms.
When you uninstall the Chili!Soft ASP 3.6 bundle, you have the option to uninstall the FrontPage
2000 Server Extensions and the Apache Web Server that were included in the bundle. When you
uninstall a custom installation of Chili!Soft ASP 3.6, you have the following two options:
•
Uninstall the entire product. If you choose this option, the uninstaller automatically
removes the ASP engine and all of the files and directories contained under the Chili!Soft
ASP installation directory.
Chili!Soft ASP 3.6 Product Documentation
•
81
Perform a staged uninstall. If you choose this option, you are prompted about whether or
not to remove the ASP engine and the files and directories contained in the Chili!Soft ASP
installation directory.
When you run the uninstaller, you can delete all of the directories and files contained in the
Chili!Soft ASP installation directory. Before beginning the uninstall, be sure to make copies of
any files contained under this directory that you do not want to lose.
Note
The uninstaller provided with Chili!Soft ASP 3.6 does not work with previous versions of
this software. To uninstall a different version of Chili!Soft ASP, you must use the
uninstaller provided with that version.
To uninstall the Chili!Soft ASP 3.6 bundle, use the following procedure. You must be logged in
as root on the computer running Chili!Soft ASP.
To uninstall the Chili!Soft ASP bundle
1. Stop both the Chili!Soft ASP Server and the Web server with which you are running
Chili!Soft ASP, as described in "Starting and Stopping the Web Server" and "Stopping and
Restarting the ASP Server" in "Chapter 3: Managing Chili!Soft ASP."
2. From the Chili!Soft ASP installation directory, run the following command (for custom
installations, the installation directory is /opt/casp by default, and for bundle installations it is
/usr/local/chilisoft):
#> ./uninstall
3. To uninstall the FrontPage 2000 Server Extensions, enter y (yes) at the prompt.
4. To uninstall the Apache Web Server, enter y (yes) at the prompt.
5. You are prompted to confirm uninstalling the Web server. Doing this removes the Web server
directories and their content. To remove the Web server, enter y (yes).
6. The uninstall script finishes uninstalling Chili!Soft ASP 3.6.
To uninstall a custom installation of Chili!Soft ASP 3.6, use the following procedure. You must
be logged in as root to the computer running Chili!Soft ASP.
To uninstall a custom installation of Chili!Soft ASP
1. Stop both the Chili!Soft ASP Server and the Web server with which you are running
Chili!Soft ASP, as described in "Starting and Stopping the Web Server" and "Stopping and
Restarting the ASP Server" in "Chapter 3: Managing Chili!Soft ASP."
2. From the Chili!Soft ASP installation directory (/opt/casp by default), type the following
command:
#> ./uninstall
Chili!Soft ASP 3.6 Product Documentation
82
3. Choose the number of the uninstall method you want. Choose 1. Uninstall the entire
product to remove all Chili!Soft ASP 3.6 components and all files and directories under the
installation directory. If you choose this option, go to step 6.
– or –
Choose 2. Perform a stage based uninstall to select which components to uninstall. If you
choose this option, go to step 4.
– or –
Choose 3. Cancel the uninstall to stop the uninstall without removing any files.
4. If you chose option 2. Perform a stage based uninstall, you are prompted to select the
components to uninstall. At the prompts, enter the number of the component(s) to remove.
5. If you want to restart the Web server, enter y (yes) at the prompt.
6. The next step of the uninstall is deleting all of the directories and files in the Chili!Soft ASP
installation directory. Before they are deleted, you are prompted to stop the uninstall and
make backup copies of any files. To do this, enter y (yes). To continue the uninstall and
delete all of the directories and files, enter n (no).
7. If you were running an Apache Web Server with Chili!Soft ASP that has Dynamic Shared
Object (DSO) support, all you need to do is run the uninstall script, as described in the
previous step. However, if your Apache Web Server does not have DSO support, then you
must also recompile the Web server after running the Chili!Soft ASP uninstall script.
Enabling Publishing
With Chili!Soft ASP 3.6, Web developers and authors can publish their work to the Web server in
the usual manner; such as by using FTP. In addition, Chili!Soft ASP 3.6 supports Microsoft
FrontPage 2000 Server Extensions, so that users of Microsoft FrontPage can publish Web pages
and applications to the Web server by using the FrontPage client. For more information about
installing FrontPage Server Extensions and setting up FrontPage users, see "Enabling FrontPage
Publishing" in "Chapter 3: Managing Chili!Soft ASP."
Defining ASP Applications on the Server
Chili!Soft ASP includes the concept of an ASP application, which comprises a hierarchical set of
directories that contain all of the ASP pages and other files used by the application. The root
directory of an ASP application contains an optional global.asa file, which stores application state
information along with Application and Session information. Using the Application and Session
Objects with the global.asa file is explained in "Using the global.asa File" in "Chapter 4:
Building a Chili!Soft ASP Application."
In order for an ASP application to be processed, it must be defined on the ASP Server. There are
four ways to define an application on Chili!Soft ASP:
•
Adding the application from the Administration Console, as described in "Adding an ASP
Application" in "Chapter 3: Managing Chili!Soft ASP."
Chili!Soft ASP 3.6 Product Documentation
83
•
Enabling ASP processing for a Virtual Host, as described in "Enabling ASP for a Virtual
Host" and "Defining Applications in a Shared Environment" in "Chapter 3: Managing
Chili!Soft ASP."
•
Using the FrontPage Services file, as described in "Using the Frontpage 2000 Services
File in a Shared Environment" in "Chapter 3: Managing Chili!Soft ASP."
•
Adding an application from within the Chili!Soft configuration file, or adding an alias
from within the Apache Web Server configuration file. This is an advanced administration
option described in "Defining Applications on UNIX" in "Chapter 3: Managing Chili!Soft
ASP."
Examples of ASP applications are the Chili!Soft ASP Administration Console and the Chili!Soft
ASP samples. (You can access the sample applications from the Administration Console, as
described in "Accessing Documentation, Samples, and Diagnostics" in "Introduction: About This
Documentation.")
Note
Chili!Soft provides technical support for configuring supported Web servers—such as
Apache and Netscape—so that they run with Chili!Soft ASP. In addition, Chili!Soft
provides technical support for the Apache Web Server that is installed with the Chili!Soft
ASP bundle. However, in order to receive technical support for the bundled Apache Web
Server, you must use the Chili!Soft ASP Administration Console to manage it, rather
than editing the Web server configuration files directly. On Cobalt systems there is no
option to configure a different Web server to run with Chili!Soft ASP.
Enabling Database Connections on the Server
With Chili!Soft ASP you can easily display and manipulate information stored in a database from
an ASP page. In order to enable an ASP application to retrieve data from a database, the system
administrator must first configure the Chili!Soft ASP Server to connect to the database. Then the
Web developer can create and initialize a connection to the database from within the application.
This topic provides overview information about enabling a connection on the ASP Server. For
more detailed instructions, see "Configuring a Database" in "Chapter 3: Managing Chili!Soft
ASP."
Chili!Soft ASP 3.6 provides built-in ActiveX Data Object (ADO) control that developers can use
from within an ASP application for initializing a connection to a database and for retrieving and
manipulating data. ADO provides the interface through which ODBC drivers are called and
provides "containers" for storing information that is passed to and from the database. The most
common container is a Recordset object, which stores the results of a SELECT SQL query. The
ADO Connection object establishes connections to databases by using ODBC drivers. For more
information about ADO, see "ADO Component Reference" in "Chapter 5: Developer’s
Reference."
Chili!Soft ASP 3.6 Product Documentation
84
Note
For DB2 databases, rather than connecting directly with the database, the ODBC driver
actually communicates with the database client software. The client software in turn
connects to the database server. Even if the database server is running on a remote
computer, the client software must be installed and configured on the computer running
the Chili!Soft ASP Server before an ASP application can access the database. For more
information, see "Configuring DB2" in "Chapter 3: Managing Chili!Soft ASP."
The Chili!Soft ASP setup program automatically installs ODBC drivers for a number of different
databases. You can view the list of installed drivers from the Administration Console, as
described in "Viewing the List of ODBC Drivers" in "Chapter 3: Managing Chili!Soft ASP."
Chili!Soft ASP 3.6 includes Merant SequeLink, which enables connections to remote computers
running Microsoft Access or Microsoft SQL Server 6.5. For more information, see "Configuring
SequeLink" in "Chapter 3: Managing Chili!Soft ASP."
ADO as well as either the appropriate ODBC driver or SequeLink are required to create a
connection to a particular database. ADO uses connection information and the ODBC driver
manager to create an instance of the required ODBC driver, which in turn connects to the
database.
With Chili!Soft ASP 3.6, Web developers can specify the connection information for the database
by using system DSNs, file DSNs, or DSN-less connection strings. The appropriate method to use
depends on user preferences and the environment in which Chili!Soft ASP is running. For more
information, see "Connecting to a Database" in "Chapter 4: Building a Chili!Soft ASP
Application."
For enterprise applications, it is recommended that ASP developers use system DSNs. The
system administrator can use the Chili!Soft ASP Administration Console to create system DSNs,
which can be referenced from within an ASP application for initializing the database connection.
For more information about creating a system DSN, see "Configuring Data Source Names
(DSNs)" in "Chapter 3: Managing Chili!Soft ASP."
In a shared Web hosting environment, such as an ISP, using system DSNs poses two problems:
First, a DSN that includes a username and password for the database makes the data source
accessible from any ASP page on the server, representing a security risk. Second, creating DSNs
for each customer can be a significant administrative burden for the Web hosting provider.
Because Web developers can create them and the database username and password information
can be restricted to a specific ASP application, using file DSNs and DSN-less connection strings
are more appropriate in a Web hosting environment.
Note
It is highly recommended that you validate your database connection parameters prior to
creating a database connection with Chili!Soft ASP. If it is passed incorrect parameters,
an ODBC driver can bring down your ASP Server. It is also a good idea to test your
database connections on a non-production server.
The following example illustrates the relationship between Chili!Soft ASP, ADO, ODBC drivers,
and databases.
Chili!Soft ASP 3.6 Product Documentation
85
First, a connection string on the ASP page specifies all of the information required by both ADO
and the ODBC driver manager for connecting to the database. The following example uses a
DSN-less connection string:
connect_string = "Driver={ODBC_driver_name};
Database=[database_name]; UID=[username]; PWD=[password]"
The next line of code creates an instance of the ADO Connection object:
set dbConn = server.createObject ("ADODB.connection")
The following code calls the Open method of the ADO Connection object, which takes the
connection_string parameter. In this step, ADO requests that the ODBC driver manager create
an instance of the specified ODBC driver. ADO then passes the remainder of the connection
string to the ODBC driver, which uses this information to connect to the database.
open dbConn connect_string
See also:
Connecting to a Database in "Chapter 4: Building a Chili!Soft ASP Application."
Chili!Soft ASP 3.6 Product Documentation
86
Chapter 3: Managing Chili!Soft ASP
This chapter provides detailed information about managing Chili!Soft ASP, including changing
configuration settings, enhancing security, and optimizing server performance. It describes how
to use the Chili!Soft ASP Administration Console, which provides Web-browser-based access to
Chili!Soft ASP configuration settings. For advanced users, "Advanced Administration Options"
in this chapter describes how to manage Chili!Soft ASP by editing configuration files directly or
by using provided scripts. However, because you can create serious problems with your system in
this manner, it is highly recommended that you use the Administration Console for configuration
tasks whenever possible.
Who should read this chapter: System administrators who are responsible for configuring and
running Chili!Soft ASP.
In this chapter:
•
Using the Administration Console
•
Managing the ASP Server
•
Managing the Web Server
•
Enabling FrontPage Publishing
•
Configuring a Database
•
Running Chili!Soft ASP in a Web Hosting Environment
•
Optimizing Server Performance
•
Advanced Administration Options
Using the Administration Console
Most configuration settings for Chili!Soft ASP 3.6 are accessible from the Chili!Soft ASP
Administration Console. The Administration Console is a Web browser-based application for
managing Chili!Soft ASP.
The topics in this section explain how to access, configure, and use the Administration Console.
In this section:
•
Accessing the Administration Console
•
Starting and Stopping the Administration Web Server
•
Configuring Usernames and Passwords
•
Accessing the Product Documentation
•
Contacting Customer Support
•
Installing a New Serial Number
The following sections, later in this chapter, provide information about configuring and managing
Chili!Soft ASP by using the Administration Console:
Chili!Soft ASP 3.6 Product Documentation
•
Managing the ASP Server
•
Managing the Web Server
•
Enabling FrontPage Publishing
•
Configuring a Database
•
Configuring ActiveX Data Objects (ADO) Connections
•
Optimizing Server Performance
87
Accessing the Administration Console
The Chili!Soft ASP Administration Console enables you to configure and manage a Chili!Soft
ASP Server from a Web browser, either locally or remotely. The Administration Console also
enables you to start and stop the Web server that is configured to run with Chili!Soft ASP.
The Administration Console is hosted by the Administration Web site, which is installed on the
computer running the ASP Server. The Administration Web site consists of its own Apache Web
Server and its own ASP Server. By default, the Administration Web site is configured to start
when you start the computer running Chili!Soft ASP.
Note
If you did not configure a Web server to run with Chili!Soft ASP during installation, you
will be prompted to configure one the first time you open the Administration Console. A
Web server is configured automatically during installation on Cobalt platforms.
To access the Administration Console from any platform, use the following procedure.
Note
On Cobalt platforms, you can also access the Chili!Soft ASP Administration Console
from the Cobalt Administration Console.
To access the Administration Console
1. In your browser address bar, enter the following URL:
http://[HOSTNAME]:[PORT]
where [HOSTNAME] is the hostname of your Web server and [PORT] is the port on which
the Administration Console is running (5100 by default—for more information, see the note
below).
For example, if your [HOSTNAME] is www.mysite.com and the Administration Console is
installed to port 5100, you would access the Administration Console at:
http:// www.mysite.com:5100/
2. When prompted, enter the username and password that were specified during installation. On
Cobalt platforms the setup programs sets the username to "admin" and the password to
"root." You should change these from the defaults as soon as possible. You can change the
Chili!Soft ASP 3.6 Product Documentation
username and password by following the instructions in "Configuring Usernames and
Passwords" in this chapter.)
The Administration Console opens, displaying the Server Management page.
From this page, you can access the configuration settings for Chili!Soft ASP, view information
about your installation, and start and stop the associated Web server.
Note
In order to access the Chili!Soft ASP Administration Console by using a URL, you must
specify its port number in the URL. The default port number is 5100. However, it might
be a different number if 5100 was already in use when you installed Chili!Soft ASP, or if
you specified a different port number for the Administration Web site during installation.
If you are unsure of the correct port number, you can find this information in the
Chili!Soft ASP installation summary file. This file is named install_summary on AIX,
Solaris, and HP-UX and component_log on Linux and Cobalt RaQ3.
For custom installations of Chili!Soft ASP, you can find the installation summary file in
the following location:
/[C-ASP_INSTALL_DIR]/logs/
88
Chili!Soft ASP 3.6 Product Documentation
89
where [C-ASP_INSTALL_DIR] is the directory in which you installed Chili!Soft ASP.
For bundle installations of Chili!Soft ASP, you can find the installation summary file in
the following location:
/usr/local/chilisoft/casp/logs/
On Cobalt platforms, you can find the installation summary file in the following location:
/home/chiliasp/logs/
The entry reads as follows:
Administration console installed:
URL: http://[WEB_SERVER_HOSTNAME]:[PORT_NUMBER]
Port: [PORT_NUMBER]
See also:
Using the Administration Console in this chapter
Starting and Stopping the Administration Web Server
When you install Chili!Soft ASP, the setup program installs an administration Web server, which
hosts the Chili!Soft ASP Administration Console. By default, the administration Web server is
configured to start when you start the computer running Chili!Soft ASP. Although you can start
and stop the ASP Server by using the Administration Console (as described in "Stopping and
Restarting the ASP Server" in this chapter), to start or stop the administration Web server, you
must use the command-line utility, admtool, which is installed with Chili!Soft ASP.
To start or stop the administration Web server, use the following procedure.
To start or stop the administration Web server
1. Telnet or log into the computer running Chili!Soft ASP as root.
2. Change directories (cd) to the Chili!Soft root installation directory (the default is
/usr/local/chilisoft/casp for bundle installations and /opt/casp for custom installations).
3. Start the admtool utility by running the following command:
./admtool
When you start the admtool utility, the following list of options displays:
1. Start admin server. Starts the administration Web server.
2. Stop admin server. Stops the administration Web server.
3. Admin server status. Indicates whether the administration Web server is running or
stopped.
Chili!Soft ASP 3.6 Product Documentation
90
4. Add a user. Adds a new administrator username and password or changes the password
for an existing username.
5. Remove a user. Removes a username.
6. List users. Shows a list of all usernames currently configured for the Administration
Console.
7. Quit. Saves any changes and exits the admtool utility.
4. To start the administration Web server, enter the number 1 (Start admin server)
– or –
To stop the administration Web enter the number 2 (Stop admin server).
5. When prompted, press Enter to continue.
6. To save any changes and exit, enter 7 (Quit).
See also:
Accessing the Administration Console in this chapter
Stopping and Restarting the ASP Server in this chapter
Starting and Stopping the Web Server in this chapter
Configuring Usernames and Passwords
During installation, the Chili!Soft ASP setup program creates a username and password to restrict
access to the Chili!Soft ASP Administration Console. You can add, edit, and delete usernames
and passwords by using the admtool utility, which is installed with Chili!Soft ASP. You cannot
configure usernames and passwords for the Administration Console from within the
Administration Console.
Important Security Note
During installation, if you are running a Cobalt system or if you chose a default
configuration for the Administration Console, the setup program set the administrator
username to "admin" and the default password to "root." To protect the security of your
server, you should change the username and password from the defaults as soon as
possible.
Chili!Soft ASP enables you to configure usernames and passwords for one or more
Administration Console users. To configure usernames and passwords, use the following
procedure.
To configure usernames and passwords
1. Telnet or log into the computer running Chili!Soft ASP 3.6 as root.
3. Change directories (cd) to the Chili!Soft ASP root installation directory (the default is
/usr/local/chilisoft/casp for bundle installations and /opt/casp for custom installations).
4. Start the admtool utility by using the following command:
Chili!Soft ASP 3.6 Product Documentation
91
./admtool
5. When you start the admtool utility, the following list of options displays. Enter the number of
the option you want (4 to add or change a username and password, 5 to remove a username,
or 6 to see the current list of usernames), and then follow the prompts.
1. Start admin server. Starts the administration Web server.
2. Stop admin server. Stops the administration Web server.
3. Admin server status. Indicates whether the administration Web server is running or
stopped.
4. Add a user. Adds a new administrator username and password or changes the password
for an existing username. To add a username and password, enter the new username and
password when prompted. To change the password for an existing username, enter the
username and the new password when prompted.
5. Remove a user. Removes a username. At the prompt enter the username you want to
remove.
6. List users. Displays a list of all usernames currently configured for the Administration
Console.
7. Quit. Saves any changes and exits the admtool utility.
6. When prompted, press Enter to continue.
7. To continue configuring more usernames and passwords, enter the number of the option you
want.
8. When finished, enter 7 (Quit) to save your changes and exit the admtool utility.
See also:
Accessing the Administration Console in this chapter
Accessing the Product Documentation
The Chili!Soft ASP setup program installs an HTML version of the product documentation that
provides dynamic indexing and search features, as well as a version in Adobe PDF format that
you can print. This topic describes three ways to access the documentation.
If you chose the option to enable documentation during installation, you can access the HTML
version of the documentation by using the following URL:
http://[HOSTNAME]/caspdoc/
where [HOSTNAME] is the hostname of your Web server.
From the first page of the HTML documentation, you can click a link to open the version in
Adobe PDF format. To access the Adobe PDF version directly, use the following URL:
http://[HOSTNAME]/caspsamp/pdf
where [HOSTNAME] is the hostname of your Web server.
Chili!Soft ASP 3.6 Product Documentation
92
To view and print the Adobe PDF version, you must have Adobe Acrobat Reader installed. To
obtain a free copy, go to:
http://www.adobe.com/products/acrobat/readstep2.html
- or You can access both versions of the product documentation on the Chili!Soft Web site at:
http://www.chilisoft.com/caspdoc/
- or You can also access the documentation from the Chili!Soft ASP Administration Console by using
the following procedure.
To access the product documentation from the Administration Console
1. If necessary, open the Administration Console by using the following URL:
http://[HOSTNAME]:[PORT]
where [HOSTNAME] is the hostname of your Web server and [PORT] is the port on which
the Administration Console is running (5100 by default).
The Server Management page displays.
2. In the left navigation pane, click documentation.
This opens the HTML version of the documentation. From the page that opens, you can click a
link to open and print the documentation in Adobe PDF format.
Chili!Soft ASP 3.6 Product Documentation
93
Viewing the Product README File
When you install Chili!Soft ASP 3.6, the setup program installs a README file on your
computer that provides important product information. You can access the README file from
the Chili!Soft ASP Administration Console, as described later in this topic. You can also find it in
the following directory:
Bundle installations: /usr/local/chilisoft/casp/logs
Custom installations and on Cobalt RaQ3: /[C-ASP_INSTALL_DIR]/logs
where [C-ASP_INSTALL_DIR] is the path name of the Chili!Soft ASP installation directory
(/home/chiliasp on RaQ3, and /opt/casp by default for custom installations).
Note
A README file is not provided for Cobalt RaQ4 and Cobalt XTR.
In addition to the README file, Chili!Soft provides a number of other resources to answer your
questions about configuring and using Chili!Soft ASP. These resources are described in
"Introduction: About This Documentation."
To view the product README file, use the following procedure.
To view the product README file
1. If necessary, open the Administration Console by using the following URL:
http://[HOSTNAME]:[PORT]
Chili!Soft ASP 3.6 Product Documentation
94
where [HOSTNAME] is the hostname of your Web server and [PORT] is the port on which
the Administration Console is running (5100 by default).
The Server Management page displays.
2. In the left navigation pane, click customer support.
The README file displays.
Chili!Soft ASP 3.6 Product Documentation
95
Contacting Customer Support
If you encounter a problem while using Chili!Soft ASP, you can contact Chili!Soft Customer
Support from the Chili!Soft ASP Administration Console Customer Support page by using the
following procedure.
Note
The Customer Support page of the Chili!Soft ASP Administration Console is not
available for Cobalt RaQ4 and Cobalt XTR.
To contact customer support
1. If necessary, open the Administration Console by using the following URL:
http://[HOSTNAME]:[PORT]
where [HOSTNAME] is the hostname of your Web server and [PORT] is the port on which
the Administration Console is running (5100 by default).
The Server Management page displays.
9. In the left navigation pane, click customer support.
The Customer Support page displays.
10. Click the Submit a question tab.
The Submit a question page displays.
Chili!Soft ASP 3.6 Product Documentation
96
11. In the text boxes, type your name, e-mail address, and a description of the problem.
12. When finished, click Submit.
If your Web browser is behind a firewall and you are unable to submit your problem as described
in the previous steps, you can e-mail your question to the Chili!Soft customer support team at
chili.eval@sun.com. If you do this, be sure to include in your message the license number that is
displayed on the ASP Server Licensing page. To view this page, click server licensing in the
left navigation pane.
Installing a New Serial Number
When you upgrade your product license, for example from an evaluation version of Chili!Soft
ASP or SpicePack to a full version, you must install a new serial number that you receive from
Chili!Soft. The Chili!Soft ASP Administration Console ASP Server Licensing page displays
information about your current Chili!Soft ASP and SpicePack licenses and enables you to install
a new serial number.
To install a new serial number or view your product license information, use the following
procedure.
To install a new Chili!Soft ASP serial number
1. If necessary, open the Administration Console by using the following URL:
http://[HOSTNAME]:[PORT]
where [HOSTNAME] is the hostname of your Web server and [PORT] is the port on which
the Administration Console is running (5100 by default).
Chili!Soft ASP 3.6 Product Documentation
The Server Management page displays.
2. In the left navigation pane, click server licensing.
The ASP Server Licensing page appears and displays information about your currently
installed product licenses.
3. In the drop-down list, select the product for which you want to install a new serial number,
Chili!Soft ASP or SpicePack.
97
Chili!Soft ASP 3.6 Product Documentation
98
4. In the Serial Number box, type the new serial number.
5. Click Install.
6. To view information about the new license, click server licensing in the left navigation pane.
In the drop-down list, select the product for which you want to view the information,
Chili!Soft ASP or SpicePack.
Managing the ASP Server
Chili!Soft ASP includes an ASP Server that handles ASP page requests. You manage the ASP
Server from the Administration Console Server Management page. Depending on your
installation, this page has either two or three tabs. You click these tabs in order to access settings
for the ASP Server, Web server, and FrontPage 2000 Server Extensions.
The ASP Server tab of the Server Management page displays when you open the
Administration Console.
Chili!Soft ASP 3.6 Product Documentation
99
On the ASP Server tab are the following items:
•
Status indicates whether the ASP Server is running or stopped.
•
Uptime indicates the length of time since the ASP Server was started or restarted.
•
Location indicates the directory in which the ASP Server is installed.
•
Stop, Start, and Restart buttons enable you to stop, start, and restart the ASP Server. For
more information, see "Stopping and Restarting the ASP Server" in this chapter.
•
The Databases link takes you to database configuration settings. For more information,
see "Configuring a Database" in this chapter.
•
The ASP Applications link takes you to settings for adding, removing, and configuring
ASP applications. For more information, see "Configuring ASP Applications" in this
chapter.
•
The Settings link takes you to general ASP Server settings. For more information, see
"Changing ASP Server Settings" in this chapter.
•
The View Logs link takes you to pages where you can view the log files enabled for the
ASP Server. For more information, see "Viewing Log Files" in this chapter.
When you click the Web Server tab, the following page displays:
Chili!Soft ASP 3.6 Product Documentation
100
On this tab are the following items:
•
Status indicates whether the Web server is running or stopped.
•
Name is the Web server hostname.
•
Port is the port the Web server is using.
•
Stop, Start, and Restart buttons enable you to stop, start, and restart the Web server. For
more information, see "Starting and Stopping the Web Server" in this chapter.
•
The Virtual Hosts link takes you to an option for enabling and disabling ASP processing
for individual Virtual Hosts. For more information, see "Enabling ASP for a Virtual Host"
in this chapter.
Note
On Cobalt systems, you manage Web server from the Cobalt Administration Console,
rather than from the Chili!Soft ASP Administration Console.
If you are running a bundle installation of Chili!Soft ASP, which includes FrontPage 2000 Server
Extensions, a Front Page tab also appears on the Server Management page. When you click
this tab, the following page displays:
Chili!Soft ASP 3.6 Product Documentation
101
On this tab, you can enable and disable FrontPage authoring. For more information, see
"Enabling FrontPage Authoring" in this chapter.
Note
On Cobalt systems, you manage FrontPage Server Extensions from the Cobalt
Administration Console, rather than from the Chili!Soft ASP Administration Console.
Changing ASP Server Settings
The Chili!Soft ASP Administration Console Server Settings page provides access to the basic
configuration settings for the ASP Server. To change these settings, use the following procedure.
Note
In order for these changes to take effect, you must restart the ASP Server. Restarting the
ASP Server resets all Session and Application variables.
To change ASP Server settings
1. If necessary, open the Administration Console by using the following URL:
http://[HOSTNAME]:[PORT]
where [HOSTNAME] is the hostname of your Web server and [PORT] is the port on which
the Administration Console is running (5100 by default).
13. On the ASP Server tab of the Server Management page (the first page to appear when you
open the console), click Settings.
Chili!Soft ASP 3.6 Product Documentation
The Server Settings page displays.
14. Configure the settings you want, as described in the following table.
15. When finished, click Save to save your changes.
102
Chili!Soft ASP 3.6 Product Documentation
103
– or –
Click Cancel to revert to the last settings that were saved.
The Server Management page displays.
16. Restart the ASP Server by clicking Restart.
ASP Server Setting
Explanation
Scripts buffering on
Yes enables scripts buffering, so that the ASP Server processes an entire
ASP page before returning its HTML output to the browser. This yields
better server performance. No disables scripts buffering, so that the ASP
Server returns the HTML output for an ASP page to the browser
incrementally, as soon as the HTML is processed. This makes debugging
easier. This setting is yes by default. For more information, see "Enabling
Scripts Buffering" in this chapter.
Session timeout
This specifies the number of minutes that the ASP Server maintains a user’s
session information since the last page request. When a user does not
submit a page request for the specified length of time, the server cancels the
session and discards its information. If a value for SessionTimeout is
specified in the script, it overrides this setting. This setting is 20 minutes by
default. For more information, see "Changing the Session Timeout Value"
in this chapter.
Script timeout
This specifies the number of seconds the ASP Server waits for a page to
finish processing before it cancels the page request. A value for
ScriptTimeout specified in a script is used only if it is higher than this
value. This setting is 90 seconds by default. For more information, see
"Changing the Script Timeout Value" in this chapter.
Allow session state
This specifies whether or not the ASP Server maintains session state. This
setting must be enabled (yes) in order for Session objects in scripts to
function. This setting is yes by default. For more information, see "Enabling
Session State" in this chapter.
Cache Scripts
Yes enables ASP scripts to be cached in memory, so ASP page s are served
faster, and no disables caching, which reduces the system memory used by
the server. This setting is yes by default. For more information, see
"Enabling Script Caching" in this chapter.
ASP errors logging file
To enable logging for the ASP Server and specify the location of the log
file, type the absolute path name of the log file in this text box. Chili!Soft
ASP creates the log file in the directory you specify. You cannot give the
log file the same name as a file that already exists in that directory. If the
ASP errors logging file text box is empty (the default), no logging is
performed. For more information, see "Enabling ASP Error Logging" in
this chapter.
ASP engine mode
This specifies the mode in which the ASP Server runs: multi-process or
multi-threaded. This setting is Multi-threaded by default. For more
Chili!Soft ASP 3.6 Product Documentation
104
information, see "Running in Multi-process Mode" and "Running in Multithreaded Mode" in this chapter. Linux does not support multi-process mode.
This feature is not available for the Linux or Cobalt versions of Chili!Soft
ASP.
Number of threads
-orNumber of processes
Depending on the engine mode in which the ASP Server is running, this
specifies the number of simultaneous threads or processes the ASP Server
handles. The number of threads is 5 by default. If you have many ASP
pages that include blocking operations (e.g., database access) it is best to
increase this number. However, keep in mind that doing this also increases
system overhead. For more information, see "Running in Multi-process
Mode" and "Running in Multi-threaded Mode" in this chapter.
Application variables
This setting is ignored in multi-threaded mode. In multi-process mode, this
setting is Read-Only by default. When set to Read-Only, application-level
variables cannot be set or modified once the global.asa file has been read.
When set to Read/Write, application-level variables can be set or modified;
however, the ASP Server can become unstable under heavy stress. For
more information, see "Running in Multi-process Mode" in this chapter.
Linux does not support multi-process mode. This feature is not available for
the Linux or Cobalt versions of Chili!Soft ASP 3.6.
Inherit user security
When Inherit user security is set to yes, the ASP Server runs with the
permissions of the Apache Web Server or the Virtual Host defined in the
Apache Web Server httpd.conf file. This is the default security mode for
Chili!Soft ASP. However, if you are running a Netscape or Zeus Web
server, be sure to read the security note that follows.
When Inherit user security is set to no, the ASP Server runs with the
permissions of the user who started the ASP Server, unless a different user
or group is specified in the Chili!Soft ASP configuration file, casp.cnfg.
This can create a security risk for your server. If you change Inherit user
security to no, be sure to specify a user or group in casp.cnfg, as described
in "Editing the Chili!Soft Configuration File" in Chapter 3: Managing
Chili!Soft ASP."
Important Security Note about Netscape and Zeus Web Servers
Netscape and Zeus Web servers do not support Inherit user
security mode, even when it is configured in the Administration
Console. To protect the security of your server, when running
Chili!Soft ASP with these Web servers, you should take the
following steps:
- Set Inherit user security to no in the Administration Console.
- Specify a user or group in the casp.cnfg file, as described in
"Editing the Chili!Soft Configuration File" in Chapter 3:
Managing Chili!Soft ASP." The ASP Server then runs with the
Chili!Soft ASP 3.6 Product Documentation
105
permissions of that user or group.
For more information, see "Securing the Server" in this chapter.
Enable Java support
Yes enables Java support for this ASP Server, which is required for
Chili!Beans. To reduce system overhead, do not enable Java support unless
you are using Chili!Beans. This setting is no by default. For more
information, see "Enabling Java Support" in this chapter. Chili!Beans are
not available for Cobalt systems.
Locale
This specifies the locale setting. The ASP Server uses the appropriate code
page for the language associated with the locale specified here. It also
correctly formats dates, numbers, and currency according to the locale. For
more information, see "Configuring International Support" in this chapter.
(Supported locales are US English, British English, Dutch, French, German,
Japanese Shift-JIS, Spanish, and Swedish.)
Stopping and Restarting the ASP Server
Most configuration changes you make to the Chili!Soft ASP Server require that you restart the
ASP Server before they take effect. In addition, you might need to stop the ASP Server, for
example to perform a product upgrade. To stop or restart the ASP Server, use the following
procedure.
Note
Restarting the ASP Server resets all Session and Application variables.
To stop, start, or restart the ASP Server
1. If necessary, open the Administration Console by using the following URL:
http://[HOSTNAME]:[PORT]
where [HOSTNAME] is the hostname of your Web server and [PORT] is the port on which
the Administration Console is running (5100 by default).
17. On the Server Management page (the first page to appear when you open the
Administration Console), click Stop, Start, or Restart as desired.
Chili!Soft ASP 3.6 Product Documentation
106
Stopping, starting, or restarting can take from several seconds to about one minute.
Configuring International Support
You might want to use the Chili!Soft ASP Server to serve Web pages in languages other than
United States (US) English or in countries other than the US. If so, you can change the locale
setting. When you do this, the ASP Server uses the appropriate code pages for the language
associated with the locale you specify. It also correctly formats dates, numbers, and currency
according to the locale. Depending on your version of Chili!Soft ASP 3.6, you can specify locales
for the following languages:
•
English - US
•
English - British
•
Dutch
•
French
•
German
•
Japanese Shift-JIS
•
Spanish
•
Swedish
To change the Chili!Soft ASP locale setting, use the following procedure.
To change the Chili!Soft ASP locale setting
1. If necessary, open the Chili!Soft ASP Administration Console by using the following URL:
http://[HOSTNAME]:[PORT]
Chili!Soft ASP 3.6 Product Documentation
107
where [HOSTNAME] is the hostname of your Web server and [PORT] is the port on which
the Administration Console is running (5100 by default).
2. On the ASP Server tab of the Server Management page (the first page to display when you
open the Administration Console), click Settings.
The Server Settings page displays.
3. In the Locale drop-down list, select the locale you want.
Chili!Soft ASP 3.6 Product Documentation
108
4. Click Save to save your changes.
– or –
Click Cancel to revert to the last settings that were saved.
The Server Management page displays.
5. To put your changes into effect, restart the ASP Server by clicking Restart.
Note
Restarting the ASP Server resets all Session and Application variables.
See also:
Developing International Applications in "Chapter 4: Building a Chili!Soft ASP Application"
Enabling Session State
With Chili!Soft ASP, you can specify whether or not the ASP Server maintains session state.
Session state is enabled by default. To conserve system resources, you might want to disable this
feature; however, in order for the Session object used in scripts to function, session state must be
enabled.
Chili!Soft ASP 3.6 Product Documentation
109
To enable or disable session state on the ASP Server, use the following procedure.
To enable or disable session state
1. If necessary, open the Chili!Soft ASP Administration Console by using the following URL:
http://[HOSTNAME]:[PORT]
where [HOSTNAME] is the hostname of your Web server and [PORT] is the port on which
the Administration Console is running (5100 by default).
2. On the ASP Server tab of the Server Management page (the first page to display when you
open the Administration Console), click Settings.
The Server Settings page displays.
Chili!Soft ASP 3.6 Product Documentation
3. In the Allow session state drop-down list, select yes or no as desired.
4. Click Save to save your changes.
– or –
Click Cancel to revert to the last settings that were saved.
The Server Management page displays.
5. To put your changes into effect, restart the ASP Server by clicking Restart.
Note
Restarting the ASP Server resets all Session and Application variables.
See also:
ASP Session Object Overview in "Chapter 4: Building a Chili!Soft ASP Application"
ASP Session Object in "Chapter 5: Developer’s Reference"
110
Chili!Soft ASP 3.6 Product Documentation
111
Enabling Java Support
By default Java support is disabled on the ASP Server. If your ASP applications make use of
Chili!Beans, you must enable Java support. To reduce system overhead, do not enable Java
support unless you are using Chili!Beans. For more information, see "Chili!Beans Component
Reference" in "Chapter 5: Developer's Reference."
Note
Chili!Beans is not available for Cobalt systems.
To enable or disable Java support, use the following procedure.
To enable or disable Java support
1. If necessary, open the Administration Console by using the following URL:
http://[HOSTNAME]:[PORT]
where [HOSTNAME] is the hostname of your Web server and [PORT] is the port on which
the Administration Console is running (5100 by default).
2. On the ASP Server tab of the Server Management page (the first page to display when you
open the Administration Console), click Settings.
The Server Settings page displays.
Chili!Soft ASP 3.6 Product Documentation
3. In the Enable Java support drop-down list, select yes or no as desired.
4. Click Save to save your changes.
– or –
Click Cancel to revert to the last settings that were saved.
The Server Management page displays.
5. To put your changes into effect, restart the ASP Server by clicking Restart.
Note
Restarting the ASP Server resets all Session and Application variables.
Securing the Server
The following topics discuss issues involved in securing the Chili!Soft ASP Server:
•
Configuring File System Access
•
Setting the Security Mode
•
Disabling Performance Monitoring
112
Chili!Soft ASP 3.6 Product Documentation
113
Configuring File System Access
You might want to enable access by an ASP application to a directory in the file system that is
not contained in the ASP application root directory or its subdirectories. In order to configure this
type of access, you must edit the EnableParentPaths setting in the Chili!Soft ASP configuration
file, casp.cnfg, as described in "Editing the Chili!Soft Configuration File" in this chapter.
However, be aware that doing this can affect the security of your server, as explained later in this
topic.
By default, EnableParentPaths is set to No. When EnableParentPaths is set to No, a
FileSystemObject instantiated by an ASP application is limited to that application’s defined
directory. In this case, #include statements cannot use the "../" syntax to access files outside the
ASP application root directory. This is the most secure setting, and is appropriate for most shared
Web hosting environments.
When EnableParentPaths is set to Yes, the FileSystemObject can access files outside the ASP
application directory. In this scenario, ASP developers can use the "../" syntax in #include
statements to access any file outside of the Web directory that the ASP Server has file system
permission to read.
Warning! Important Security Information
Changing EnableParentPaths to Yes can affect the security of your server. Before you
change this setting, make sure that your ASP Server has permission to access only the
files you want to be publicly accessible, and that it does not have access to sensitive files
containing configuration or password information. You can restrict the permissions of the
ASP Server by defining the user it runs under, and making sure that user has
appropriately restricted file-system permissions. For more information, see the next topic,
"Setting the Security Mode."
See also:
Defining ASP Applications on the Server in this chapter
Using Server-side Includes in "Chapter 4: Building a Chili!Soft ASP Application"
Setting the Security Mode
On Chili!Soft ASP 3.6 for Linux, Cobalt, and UNIX-based systems, you can configure the
Chili!Soft ASP Server to run under either Defined User Security mode or Inherit User Security
mode. The appropriate mode depends on your Web-hosting environment and has important
security implications for your server. Be sure to read "Important Security Information" later in
this topic, particularly if you are running a Zeus or Netscape Web server.
•
Inherit User Security mode is available only for Chili!Soft ASP running with Apache
Web Server. This mode is useful in shared Web hosting environments because the ASP
Server runs with the permissions of the user defined for the Apache Web Server. In a Web
hosting environment using virtual hosts, the ASP Server runs as the user configured for
the virtual host. For example, if the Web server is configured to run as user "john," when
someone accesses the virtual server www.johns-site.com, the ASP Server runs under the
account "john" when processing ASP page requests for www.johns-site.com. You can
Chili!Soft ASP 3.6 Product Documentation
114
enable this mode from the Chili!Soft ASP Administration Console, as described later in
this topic.
•
Defined User Security mode is appropriate for most corporate or dedicated Web-hosting
environments. In this mode, the ASP Server runs with the permissions of the user and
group defined in the Chili!Soft ASP configuration file, casp.cnfg. The user and group
account the ASP Server is configured to run under should have access rights to all *.asp
and *.asa pages and should also have rights to Chili!Soft ASP configuration files, such as
casp.cnfg and ODBC.INI. You enable this mode by setting Inherit User Security to no
in the Administration Console and then specifying a user and group in the casp.cnfg file,
as described later in this topic.
Note
Even if a user or group is specified in casp.cnfg, as long as Inherit User Security is
selected in the Administration Console, the ASP Server runs under Inherit User Security
mode.
Important Security Information
- If you set Inherit User Security to no and do not specify a user and group in the
casp.cnfg file, the ASP Server runs as root. This can compromise the security of your
server.
- Netscape and Zeus Web Servers do not support Inherit User Security mode. When
running Chili!Soft ASP with one of these Web servers, to protect the security of your
server, you should set Inherit User Security to no and then define a user or group in the
casp.cnfg file. For more information about adding users and groups to casp.cnfg, see
"Editing the Chili!Soft ASP Configuration File" in this chapter.
To set the ASP Server security mode, use the following procedure.
To set the ASP Server security mode
1. If necessary, open the Chili!Soft ASP Administration Console by using the following URL:
http://[HOSTNAME]:[PORT]
where [HOSTNAME] is the hostname of your Web server and [PORT] is the port on which
the Administration Console is running (5100 by default).
2. On the ASP Server tab of the Server Management page (the first page to appear when you
open the Administration Console), click Settings.
Chili!Soft ASP 3.6 Product Documentation
115
The Server Settings page displays.
3. In the Inherit user security drop-down list, select yes to run under Inherited User Security
mode, or no to run under Defined User Security mode. If you select no, you should edit the
Chili!Soft ASP 3.6 Product Documentation
116
casp.cnfg file to add a user or group for the ASP Server to run under, as described in "
Editing the Chili!Soft ASP Configuration File" in this chapter. If you do not, the ASP Server
runs as root, which can compromise the security of your server. You should always run Web
servers other than Apache Web Server under Defined User Security Mode.
4. Click Save to save your changes.
– or –
Click Cancel to revert to the last settings that were saved.
The Server Management page displays.
5. To put your changes into effect, restart the ASP Server by clicking Restart.
Note
Restarting the ASP Server resets all Session and Application variables.
See also:
Configuring File System Access in this chapter.
Disabling Performance Monitoring
If you are running Chili!Soft ASP in a shared Web hosting environment, it is strongly
recommended that you disable server performance monitoring to protect the security of your
server, as described in this topic.
By default, Chili!Soft ASP monitors server performance and displays this information on the
Chili!Soft ASP Administration Console Server Monitoring page, as described in "Monitoring
the ASP Server" in this chapter.
Chili!Soft ASP stores the server performance information in the following files:
/tmp/.casp[PORT]/chili-psm
/tmp/.casp[PORT]/.pm-chili-psm
/tmp/.pm-chili-psm
/tmp/chili-psm
These files are created with "world-readable" permissions that might not be appropriate in a
shared Web hosting environment. You can disable performance monitoring and the creation of
these log files by editing the enablemonitoring setting in the [default machine] section of
the Chili!Soft ASP configuration file, casp.cnfg. When you do this, server performance
information is no longer displayed on the Server Monitoring page of the Administration
Console.
For more information about editing casp.cnfg, see "Editing the Chili!Soft ASP Configuration
File" in this chapter.
Chili!Soft ASP 3.6 Product Documentation
117
Configuring ASP Applications
As discussed in "Defining ASP Applications on the Server" in "Chapter 2: Installing and
Configuring Chili!Soft ASP," you must define an ASP application on the ASP Server in order for
the application to be recognized and processed when a user requests an ASP page. The easiest
way to define and configure an application is by using the Chili!Soft ASP Administration
Console, as discussed in this section. However, if you need to configure an application in a hosted
environment, see the instructions provided in "Running Applications in a Shared Web Hosting
Environment" in this chapter. For more information about defining Microsoft FrontPage
applications, see "Using the FrontPage 2000 Services File in a Shared Environment" in this
chapter.
You can define and configure an ASP application from the Administration Console Applications
page.
•
Add a new application enables you to create a new application and associate it with the
physical directory containing the global.asa file. For instructions, see "Adding an ASP
Application" in this chapter.
•
Remove enables you to remove an ASP application from the ASP Server. For
instructions, see "Removing an ASP Application" in this chapter.
•
Configure enables you to associate an ASP application with a physical directory
containing the global.asa file. For instructions, see "Editing ASP Application Settings" in
this chapter.
Adding an ASP Application
In order for the ASP Server to process an ASP application when a user requests an ASP page, the
application must be defined on the ASP Server. The easiest way to do this is by using the
Chili!Soft ASP 3.6 Product Documentation
118
Chili!Soft ASP Administration Console. From the console, you "add" an application by giving
the application a name and specifying the physical directory containing the application files and
the global.asa file. When you do this, a virtual directory for the application is created on the Web
server and associated with the physical directory containing the application files.
To define an application for a virtual host, instead of using the following procedure, use the
instructions in "Enabling ASP for a Virtual Host" in this chapter. If the Web developers you
support are users of Microsoft FrontPage, see the discussion about defining FrontPage
applications in "Using the FrontPage 2000 Services File in a Shared Environment" in this chapter.
To define an ASP application that will not be served by a virtual host, use the following
procedure.
To add an ASP application to the ASP Server
1. If necessary, open the Administration Console by using the following URL:
http://[HOSTNAME]:[PORT]
where [HOSTNAME] is the hostname of your Web server and [PORT] is the port on which
the Administration Console is running (5100 by default).
2. On the ASP Server tab of the Server Management page (the first page to display when you
open the Administration Console), click ASP Applications.
The Applications page displays, showing a list of currently configured ASP applications.
3. Click Add a new application.
The Add application page displays.
Chili!Soft ASP 3.6 Product Documentation
119
4. In the Application name box, type the name of the virtual directory to create and enable as
an ASP application.
5. In the Directory box, type the absolute path name of the application directory. The
application directory is the top-level physical directory that contains the application ASP
files, the global.asa file (if one is being used for this application), and any application
subdirectories.
6. Click Save.
– or –
Click Cancel to cancel any entries.
The Applications page displays.
7. In the left navigation pane, click server management.
The Server Management page displays.
8. To put your changes into effect, restart the ASP Server by clicking Restart.
Note
Restarting the ASP Server resets all Session and Application variables.
See also:
Defining ASP Applications on the Server in "Chapter 2: Installing and Configuring Chili!Soft
ASP"
Configuring ASP Applications in this chapter
Editing ASP Application Settings in this chapter
Removing an ASP Application in this chapter
Chili!Soft ASP 3.6 Product Documentation
120
Removing an ASP Application
If you want the ASP Server to stop processing an ASP application, you must remove the
application from the ASP Server, as described in the following procedure. This deletes the virtual
directory for the application from the Web server. It does not delete the physical directory
containing the application files. For more information about ASP applications, see "Configuring
ASP Applications" in this chapter.
To remove an ASP application from the ASP Server
1. If necessary, open the Chili!Soft ASP Administration Console by using the following URL:
http://[HOSTNAME]:[PORT]
where [HOSTNAME] is the hostname of your Web server and [PORT] is the port on which
the Administration Console is running (5100 by default).
2. On the ASP Server tab of the Server Management page (the first page to display when you
open the Administration Console), click ASP Applications.
The Applications page displays, showing a list of currently configured ASP applications.
3. In line with the name of the application that you want to remove, click remove.
4. When prompted to confirm removing the application, click Yes.
The Applications page displays.
5. In the left navigation pane, click server management.
6. Restart the ASP Server by clicking Restart.
Note
Restarting the ASP Server resets all Session and Application variables.
Chili!Soft ASP 3.6 Product Documentation
121
See also:
Defining ASP Applications on the Server in "Chapter 2: Installing and Configuring Chili!Soft
ASP"
Configuring ASP Applications in this chapter
Editing ASP Application Settings in this chapter
Adding an ASP Application in this chapter
Editing ASP Application Settings
In order for the ASP Server to process an ASP application when a user requests an ASP page, you
first add it to the ASP Server, as described in "Adding an ASP Application" in this chapter.
Later, if you want to change the application name (e.g., the virtual directory name) or the physical
directory associated with the application, you can use the following procedure. For more
information about ASP applications, see "Configuring ASP Applications" in this chapter.
To edit ASP application settings
1. If necessary, open the Chili!Soft ASP Administration Console by using the following URL:
http://[HOSTNAME]:[PORT]
where [HOSTNAME] is the hostname of your Web server and [PORT] is the port on which
the Administration Console is running (5100 by default).
2. On the ASP Server tab of the Server Management page (the first page to display when you
open the Administration Console), click ASP Applications.
The Applications page displays, showing a list of currently configured ASP applications.
3. In line with the name of the application whose settings you want to edit, click configure.
Chili!Soft ASP 3.6 Product Documentation
122
The Configure application page displays.
4. If you want to change the application name, in the Application name box, type the new
name.
5. If you want to change the physical directory associated with the application, in the Directory
box, type the absolute path name of the new directory. The application directory is the toplevel directory that contains the application files, optional global.asa file, and any application
subdirectories.
6. Click Save.
– or –
Chili!Soft ASP 3.6 Product Documentation
123
Click Cancel to cancel any changes.
The Applications page displays.
7. In the left navigation pane, click server management.
8. To put your changes into effect, restart the ASP Server by clicking Restart.
Note
Restarting the ASP Server resets all Session and Application variables.
See also:
Defining ASP Applications on the Server in "Chapter 2: Installing and Configuring Chili!Soft
ASP"
Configuring ASP Applications in this chapter
Adding an ASP Application in this chapter
Removing an ASP Application in this chapter
Viewing Information About the ASP Server
Chili!Soft ASP provides several options for viewing information about the ASP Server. It enables
you to monitor real-time performance data, view diagnostic information, and log ASP errors.
In this section:
•
Monitoring ASP Server Performance
•
Enabling ASP Error Logging
•
Viewing the ASP Errors Log
•
Viewing Server Diagnostics
See also:
Optimizing Server Performance in this chapter
Monitoring ASP Server Performance
On Linux and Sun Solaris systems, the Server Monitoring page of the Chili!Soft ASP
Administration Console displays real-time information about ASP Server performance.
Notes
This feature is not available on HP-UX and IBM AIX systems.
On Sun Solaris, this feature is only available when the ASP Server is running in multithread mode.
Chili!Soft ASP 3.6 Product Documentation
124
If you have disabled performance monitoring, as described in "Disabling Performance
Monitoring" in this chapter, you cannot view this server performance information.
Disabling server performance monitoring is a recommended security precaution if you
are running Chili!Soft ASP in a shared Web hosting environment.
To view ASP Server performance information, use the following procedure.
To view real-time information about the ASP Server
1. If necessary, open the Administration Console by using the following URL:
http://[HOSTNAME]:[PORT]
where [HOSTNAME] is the hostname of your Web server and [PORT] is the port on which
the Administration Console is running (5100 by default).
The Server Management page displays.
6. In the left navigation pane, click monitor a server.
The Server Monitoring page displays.
Chili!Soft ASP 3.6 Product Documentation
125
7. If you want to continuously monitor the server, click live monitoring. This opens a separate
window that displays constantly updated information.
The Server Monitoring page displays the following information:
Item
Explanation
Total requests
Total number of requests since the ASP Server was started.
Requests per second
Number of requests per second being processed by the ASP Server
Total errors received
Number of ASP Server errors logged since the server was started
Current number of
sessions
Number of sessions currently active on the ASP Server
Cached scripts
Number of ASP scripts currently cached by the ASP Server
Active virtual hosts
Number of Virtual Hosts that currently have one or more active sessions
Total memory in use
System memory (RAM) currently being used by the ASP Server
Uptime
Length of time the ASP Server has been running since the last restart
See also:
Changing ASP Server Settings in this chapter
Viewing Server Diagnostics in this chapter
Enabling ASP Errors Logging in this chapter
Viewing the ASP Errors Log in this chapter
Optimizing Server Performance in this chapter
Chili!Soft ASP 3.6 Product Documentation
126
Enabling ASP Errors Logging
In order for Chili!Soft ASP to log ASP errors, you must first enable logging. For more
information about viewing the log file, see "Viewing the ASP Errors Log" in this chapter.
To enable ASP errors logging, use the following procedure.
To enable ASP errors logging
1. If necessary, open the Chili!Soft ASP Administration Console by using the following URL:
http://[HOSTNAME]:[PORT]
where [HOSTNAME] is the hostname of your Web server and [PORT] is the port on which
the Administration Console is running (5100 by default).
2. On the ASP Server tab of the Server Management page (the first page to appear when you
open the Administration Console), click Settings.
The Server Settings page displays.
Chili!Soft ASP 3.6 Product Documentation
127
3. In the ASP errors logging file box, type the name of the log file to which you want ASP
errors logged. You cannot give the log file the same name as a file that already exists in the
directory. If the ASP errors logging file box is empty (the default), no logging is performed.
4. Click Save to save your changes.
– or –
Click Cancel to revert to the last settings that were saved.
The Server Management page displays.
5. To put your changes into effect, restart the ASP Server by clicking Restart.
Note
Restarting the ASP Server resets all Session and Application variables.
A log file with the name you specified is created in the following directory:
Bundle installations: /usr/local/chilisoft/casp/logs
Custom installations: /[C-ASP_INSTALL_DIR]/logs
where [C-ASP_INSTALL_DIR] is the path name of the Chili!Soft ASP installation directory
(/opt/casp by default).
Chili!Soft ASP 3.6 Product Documentation
128
See also:
Monitoring ASP Server Performance in this chapter
Optimizing Server Performance in this chapter
Viewing Information About the ASP Server in this chapter
Viewing the ASP Errors Log
From the ASP Server tab of the Server Management page of the Chili!Soft ASP Administration
Console you can view the ASP errors log. In order to log ASP errors and view the logging
information, you must first enable logging as described in "Enabling ASP Errors Logging" in this
chapter.
To view the ASP errors log, use the following procedure.
To view the ASP errors log
1. If necessary, open the Administration Console by using the following URL:
http://[HOSTNAME]:[PORT]
where [HOSTNAME] is the hostname of your Web server and [PORT] is the port on which
the Administration Console is running (5100 by default).
2. On the ASP Server tab of the Server Management page (the first page to appear when you
open the Administration Console), click View Logs.
The Server Logs Files page displays, showing the ASP errors that have been logged.
See also:
Enabling ASP Errors Logging in this chapter
Monitoring ASP Server Performance in this chapter
Chili!Soft ASP 3.6 Product Documentation
129
Optimizing Server Performance in this chapter
Viewing Information About the ASP Server in this chapter
Viewing Server Diagnostics
From the Server Logs Files page of the Chili!Soft ASP Administration Console, you can view
diagnostic information about the ASP Server, such as when ASP engines were started and
stopped and configuration changes that have been made since Chili!Soft ASP was installed.
To view this information, use the following procedure.
To view server diagnostics
1. If necessary, open the Administration Console by using the following URL:
http://[HOSTNAME]:[PORT]
where [HOSTNAME] is the hostname of your Web server and [PORT] is the port on which
the Administration Console is running (5100 by default).
2. On the ASP Server tab of the Server Management page (the first page to appear when you
open the Administration Console), click View Logs.
The Server Logs Files page displays.
3. Click the Server Diagnostics tab.
Server diagnostic information displays.
See also:
Enabling ASP Errors Logging in this chapter
Monitoring ASP Server Performance in this chapter
Optimizing Server Performance in this chapter
Chili!Soft ASP 3.6 Product Documentation
130
Viewing Information About the ASP Server in this chapter
Managing the Web Server
Chili!Soft ASP is configured to run with a Web server, which receives page requests and hands
them to the ASP Server for processing. Most Web server management is handled through the
Web server's own management interface. However, from the Chili!Soft ASP Administration
Console Web Server page, you can view information about the Web server, start and stop the
Web server, and enable ASP processing for individual virtual hosts.
Note
On Cobalt RaQ4 and RaQ XTR systems, you manage the Web server and configure
virtual hosts from the Cobalt Administration Console, rather than from the Chili!Soft
ASP Administration Console.
This section explains how to use the Chili!Soft ASP Administration Console to manage the Web
server. It also explains how to change the Web server with which Chili!Soft ASP is configured to
run.
In this section:
•
Starting and Stopping the Web Server
•
Enabling ASP for a Virtual Host
•
Changing the Web Server
Chili!Soft ASP 3.6 Product Documentation
131
Starting and Stopping the Web Server
By using the Chili!Soft ASP Administration Console, you can start, stop, and restart the Web
server with which the Chili!Soft ASP Server is configured to run, as well as view the status of the
Web server (stopped or running).
Note
This feature is not available on Cobalt RaQ4 and RaQ XTR systems.
To start, stop, and restart the Web Server
1. If necessary, open the Administration Console by using the following URL:
http://[HOSTNAME]:[PORT]
where [HOSTNAME] is the hostname of your Web server and [PORT] is the port on which
the Administration Console is running (5100 by default).
2. On the Server Management page (the first page to appear when you open the
Administration Console), click the Web Server tab.
The Web Server tab displays.
3. Click Start, Stop, or Restart as desired.
See also:
Managing the Web Server in this chapter
Enabling ASP for a Virtual Host
In order for the ASP Server to recognize and process an ASP application when a user requests an
ASP page, you must first define the application. In a Web-hosting environment that makes use of
virtual hosts, such as an Internet Service Provider (ISP), you define ASP applications in a
Chili!Soft ASP 3.6 Product Documentation
132
different manner than is described in "Adding an ASP Application" in this chapter. This is
because the ASP Server automatically recognizes ASP applications for each virtual host defined
for the Web server. This topic describes how to use the Chili!Soft ASP Administration Console to
selectively enable or disable ASP processing for each virtual host.
In this scenario, the application files must be located within the document root directory of the
Web server or virtual host. In addition, the directory containing the global.asa file cannot be
below the top-level directory of the Web server or virtual host document root. For more
information about ASP applications and the global.asa file, see "Configuring ASP Applications"
in this chapter.
Note
On Cobalt RaQ4 and RaQ XTR systems, you manage the Web server and configure
virtual hosts from the Cobalt Administration Console, rather than from the Chili!Soft
ASP Administration Console. For more information, see the Cobalt documentation.
Use the following procedure to selectively enable or disable ASP processing for a virtual host.
To enable or disable ASP processing for a virtual host
1. If necessary, open the Administration Console by using the following URL:
http://[HOSTNAME]:[PORT]
where [HOSTNAME] is the hostname of your Web server and [PORT] is the port on which
the Administration Console is running (5100 by default).
2. On the Server Management page (the first page to appear when you open the
Administration Console), click the Web Server tab.
The Web Server tab displays.
3. Click Virtual Hosts.
Chili!Soft ASP 3.6 Product Documentation
133
4. Select the checkbox of each vrtual host for which you want to enable ASP processing, and
deselect the checkbox of each virtual host for which you want to disable ASP processing.
5. Click server management in the left navigation pane.
6. Restart the ASP Server by clicking Restart.
Note
Restarting the ASP Server resets all Session and Application variables.
See also:
Managing the Web Server in this chapter
Starting and Stopping the Web Serverin this chapter
Changing the Web Server
In certain cases, you might want to change the Web server with which Chili!Soft ASP is
configured to run. To change the Web server, you must first remove the ASP Server by running
the delete_server script. Then you can specify a different Web server to run with the ASP Server
by running the add_server script.
Note
This feature is not available on Cobalt systems.
Important
When you run the delete_server script, all of your Chili!Soft ASP configuration settings
are overwritten, and any data contained under the installation directory for the ASP
Server is deleted. Before you begin, be sure to make a note of your configuration settings
so that you can reset them in the Administration Console, and back up any data you do
not want to lose.
Note
Running the delete_server script stops the Web server that is currently associated with the
Chili!Soft ASP Server.
To change the Web server with which Chili!Soft ASP is configured to run, use the following
procedure.
To change the Web server
1. From the Chili!Soft ASP installation directory, enter the following command (for custom
installations, the installation directory is /opt/casp by default; for bundle installations it is
/usr/local/chilisoft):
#./delete_server
8. At the prompt, enter the number of the ASP Server ("engine") that you want to remove.
Chili!Soft ASP 3.6 Product Documentation
134
9. At the prompt, enter y (yes) if you want to continue uninstalling the ASP Server.
10. At the prompt, enter y (yes) if you want the associated Web server to restart after the ASP
Server is uninstalled.
11. After receiving the message, "The uninstall was successful," run the following command to
configure a different Web server:
#./add_server
12. The screen displays a list of installed Web servers, along with other options for specifying a
Web server. From the list, enter the number of the Web server to configure to run with
Chili!Soft ASP, and then follow the instructions in step 9.
– or –
If you want to provide information about the Web server to configure, enter the number for
Specify the Web Server, then follow the instructions in step 7.
– or –
If you want the add_server script to search for installed Web servers from which to select,
enter the number for Refresh the webserver list. Enter the number of the Web server you
want to configure to run with Chili!Soft ASP, and then follow the instructions in step 9.
– or –
If you do not want to configure a Web server during installation, enter the number for Do not
configure a web server. If you choose this option, the first time you open the Administration
Console, you are prompted to configure the ASP Server and a Web server.
13. On the next screen, enter the number of the type of Web server to configure: 1 for Apache, 2
for Netscape, or 3 for Zeus, and then go to the next step.
– or –
To cancel the user-specified Web server configuration, enter 4. If you choose this option, you
are returned to the previous screen. From this screen you can choose another option, as
described in step 6.
14. At the prompts, enter the requested information about the Web server, and go to the next step.
15. On the next screen, if the information displayed about your Web server is correct, enter y
(yes).
– or –
If the information is incorrect, enter n (no). This returns you to the previous screen. For this
screen, follow the instructions in step 6.
16. On the next screen, choose a configuration option for the ASP Server. Enter 1 to choose a
default configuration, and go to the next step.
– or –
Enter 2 to choose a custom configuration, and enter the following information at the prompts:
Chili!Soft ASP 3.6 Product Documentation
135
Would you like me to restart this Web server for you? Enter y (yes) if you want the
setup program to automatically restart the Web server after completing Chili!Soft ASP
installation, or enter n (no) if you do not want this.
Choose a mode. (Solaris, HP-UX, and IBM AIX only) Enter the number of the mode in
which you want to run the ASP Server, or enter 3 for more information about this option.
1. Multi-threaded
2. Multi-process
3. More information
Enable samples on this Web server? Enter y (yes) if you want the setup program to
install and configure the Chili!Soft ASP samples on your Web server, or n (no) if you
do not want this.
Enable documentation on this Web server? Enter y (yes) if you want the setup
program to install and configure the Chili!Soft ASP documentation on your Web server,
or n (no) if you do not want this.
Start the Chili!Soft ASP on system boot? Enter y (yes) if you want the setup program
to start Chili!Soft ASP automatically each time you start the computer, or type n (no) if
you do not want this.
Would you like to start this Chili!Soft ASP Server? Enter y (yes) if you want the
setup program to start Chili!Soft ASP automatically immediately after you finish
installing it, or n (no) if you do not want this.
– or –
Enter 3 to choose another Web server to configure for Chili!Soft ASP, and follow the
instructions in step 6.
The script installs the ASP Server in the following subdirectory of the Chili!Soft ASP installation
directory:
/asp-[SERVER_TYPE]-[PORT]
where[SERVER_TYPE]is the type of Web server with which you want to configure Chili!Soft
ASP to run, and [PORT] is the port on which the Web server is configured to listen. The screen
displays summary information about the installation. It is a good idea to print this screen for
future reference.
Be sure to reset all of your configuration settings after completing this procedure, and restore any
data from the original installation directory that you had backed up.
Note
On Chili!Soft ASP for Linux, if you had a locale specified for your ASP Server other
than English - US, you will need to reset it after changing the Web server, as described in
"Configuring International Support" in this chapter.
Chili!Soft ASP 3.6 Product Documentation
136
Enabling FrontPage Publishing
Chili!Soft ASP 3.6 supports Microsoft FrontPage 2000 Server Extensions. With FrontPage 2000
Server Extensions, Web authors and developers working on Windows-based computers can use
the FrontPage client to publish Web pages and applications to UNIX-based or Linux-based Web
servers, or to Windows NT/2000-based computers running a Web server other than Internet
Information Server (IIS).
When you perform a bundle installation of Chili!Soft ASP 3.6, the setup program automatically
installs and configures FrontPage 2000 Server Extensions on your server. When you perform a
custom installation of Chili!Soft ASP, you must go to the Microsoft Web site in order to obtain
the extensions, as described in "Installing FrontPage 2000 Server Extensions" in this chapter.
FrontPage Server Extensions are preinstalled on Cobalt platforms.
Once the extensions are installed, you must take additional steps to enable users to publish their
pages to the server, as described in "Enabling FrontPage Authoring" and "Setting up FrontPage
Users" in this chapter.
You can find more information about FrontPage 2000 Server Extensions at:
http://msdn.microsoft.com/workshop/c-frame.htm#/workshop/languages/fp/default.asp
Note
When publishing ASP pages created in FrontPage, be aware that EnableParentPaths is
set to No by default in the Chili!Soft ASP configuration file. With this configuration,
CreateObject ("Scripting.FileSystemObject") calls generated in global.asa file by
FrontPage will not work. This means that you must either change EnableParentPaths to
Yes, or else ASP developers must change the code that FrontPage generated in the
global.asa file to Server.CreateObject ("Scripting.FileSystemObject"). However, be
aware that changing this setting from the default can create a security risk for your server.
For more information, see "Configuring File System Access" and "Editing the Chili!Soft
Configuration File" in this chapter.
See also:
Managing the Web Server in this chapter
Installing FrontPage 2000 Server Extensions
FrontPage Server Extensions are preinstalled on Cobalt systems, and you do not need to install
them. When you perform a bundle installation of Chili!Soft ASP 3.6, the setup program
automatically installs and configures Microsoft FrontPage 2000 Server Extensions on your server
in the following location:
/usr/local/chilisoft/frontpage
The setup program also creates symbolic link at:
/usr/local/frontpage
If you perform a custom installation of Chili!Soft ASP and want to install FrontPage 2000 Server
Extensions on your server, you can obtain them from the following location:
Chili!Soft ASP 3.6 Product Documentation
137
http://msdn.microsoft.com/workshop/languages/fp/2000/unixfpse.asp
Note
Chili!Soft does not support configurations of FrontPage 2000 Server Extensions other
than those included in the bundle installation of Chili!Soft ASP 3.6.
You can find the FrontPage 2000 Server Extensions Resource Kit at:
http://officeupdate.microsoft.com/frontpage/wpp/serk/
You can download the FrontPage 2000 Server Extensions Resource Kit from this location:
http://officeupdate.microsoft.com/2000/downloadDetails/Fp2kserk.htm
After you install FrontPage 2000 Server Extensions, you can connect to the Web server from the
FrontPage 2000 client in order to change your administrator password ("root" by default) and set
up usernames, passwords, and directories, as described in "Setting up FrontPage Users" in this
chapter.
See also:
Enabling FrontPage Authoringin this chapter
Using the FrontPage 2000 Services File in a Shared Environment in this chapter
Enabling FrontPage Authoring
With Chili!Soft ASP 3.6, Web authors can publish their work to the Web server by using the
FrontPage client. To enable this capability, you must have FrontPage 2000 Server Extensions
installed and FrontPage authoring must also be enabled on the Web server.
FrontPage Server Extensions are installed and configured on Cobalt systems, as well as with the
bundle installation of Chili!Soft ASP 3.6. For custom installations you can obtain and install them
as described in "Installing FrontPage 2000 Server Extensions" in this chapter.
Once you have enabled FrontPage authoring, you can then access the FrontPage root Web on
your Web server in order to set it up for FrontPage users, as described in "Setting up FrontPage
Users" in this chapter.
Note
On Cobalt systems, you manage FrontPage Server Extensions from the Cobalt
Administration Console, rather than from the Chili!Soft ASP Administration Console.
If you have a bundle installation of Chili!Soft ASP, you can enable or disable FrontPage
authoring on the Web server by using the following procedure.
To enable or disable FrontPage authoring
1. If necessary, open the Chili!Soft ASP Administration Console by using the following URL:
http://[HOSTNAME]:[PORT]
Chili!Soft ASP 3.6 Product Documentation
138
where [HOSTNAME] is the hostname of your Web server and [PORT] is the port on which
the Administration Console is running (5100 by default).
2. On the Server Management page (the first page to appear when you open the
Administration Console), click the Web Server tab.
The Web Server tab displays.
3. Click Enable or Disable as appropriate.
See also:
Enabling FrontPage Publishing in this chapter
Installing FrontPage 2000 Server Extensions in this chapter
Setting up FrontPage Users in this chapter
Using the FrontPage 2000 Services File in a Shared Environmentin this chapter
Setting up FrontPage Users
Before you can set up directories and Webs for FrontPage users, you must first install and
configure FrontPage 2000 Server Extensions as described in "Installing FrontPage 2000 Server
Extensions" in this chapter. Then you must enable FrontPage authoring, as described in "Enabling
FrontPage Authoring" in this chapter.
Having done this, you can use the FrontPage 2000 client to connect to the FrontPage root Web in
order to set it up for users, as described in this topic. You can change your FrontPage
administrator password ("root" by default) and set up usernames, passwords, and directories,
called Webs in FrontPage. For more information about changing the administrator password and
adding users and user Webs, see the FrontPage 2000 Server Extensions online product
documentation.
To the FrontPage 2000 root Web in order to set it up for users, use the following procedure.
Chili!Soft ASP 3.6 Product Documentation
139
To connect to the FrontPage 2000 root Web
1. Make sure FrontPage 2000 Server Extensions are installed and FrontPage authoring is
enabled on the Web server.
2. From the FrontPage 2000 client File menu, click Open Web.
3. In the Folder Name box, type the following URL:
http://[HOSTNAME]
where [HOSTNAME] is the hostname of your Web server.
4. Click Open.
5. When prompted, type "admin" for the username and "root" for the password.
6. Make the configuration changes you want, as described in the FrontPage documentation.
See also:
Enabling FrontPage Publishing in this chapter
Using the FrontPage 2000 Services File in a Shared Environmentin this chapter
Configuring a Database
Chili!Soft ASP enables ASP developers to connect with several types of databases from within an
ASP application. It provides the built-in ADO Connection object that developers can use to
initiate a database connection, along with a set of ODBC drivers that enable that the ASP Server
and ODBC Manager to establish and maintain the connection. (For more information about
creating and initializing ADO database connections from within an ASP application, see
"Connecting to a Database" in "Chapter 4: Building a Chili!Soft ASP Application." )
Chili!Soft ASP automatically installs the needed ODBC drivers for the supported databases.
However, for some types of databases, the system administrator must take additional steps to
configure the ASP Server. For example, the system administrator must configure SequeLink in
order to enable connections from an ASP Server running on a UNIX or Linux system to a
Microsoft Access and Microsoft SQL Server 6.5 database running on a Windows system. In
addition, the system administrator might want to create system DSNs to make it easier for
developers to connect with databases. This section describes how to create and edit DSNs and
how to configure the ASP Server to connect with supported databases.
Note
Chili!Soft ASP 3.6 installs the ODBC drivers for a number of databases, but it does not
provide them for all databases on all platforms. You can view the list of installed drivers
for your platform from the Administration Console, as described in "Viewing the List of
ODBC Drivers" in this chapter. Chili!Soft provides technical support only for the ODBC
drivers installed with Chili!Soft ASP.
In this section:
•
Configuring Data Source Names (DSNs)
Chili!Soft ASP 3.6 Product Documentation
•
Viewing the List of ODBC Drivers
•
Configuring SequeLink
•
Configuring DB2
•
Editing the Microsoft SQL Server Template
•
Configuring the Database Environment
•
Configuring Database Parameters
140
See also:
Creating Database Connections on the Server in "Chapter 2: Installing and Configuring Chili!Soft
ASP"
Configuring Data Source Names (DSNs)
To make it easier for developers to connect an ASP application to a database, the system
administrator can add a system data source name (DSN) to the ASP Server. DSNs store
information about a database that the ASP Server and ODBC Manager use for connecting to it.
Developers can use the system DSN in connection strings on ASP pages to incorporate database
information by reference, rather than needing to specify the complete set of information in each
string.
You can access DSN configuration settings on the Data Source Names tab of the Chili!Soft ASP
Administration Console Databases page. This tab displays the list of system DSNs that are
currently configured for the ASP Server. It also provides access to settings for adding a new DSN
to the ASP Server, as well as removing, editing, and testing an existing DSN.
Chili!Soft ASP 3.6 Product Documentation
141
Note
To protect the security of your database, in a shared Web hosting environment, you might
prefer developers use DSN-less connection strings or file DSNs in place of system DSNs.
For a discussion of these security issues, see "Enabling Database Connections on the
Server" in "Chapter 2: Installing and Configuring Chili!Soft ASP."
The topics in this section describe how to add, remove, edit, and test system DSNs. In addition to
the steps described in this section, you might need to take additional steps to configure the ASP
Server to support a particular database. For more information, see "Configuring a Database" in
this chapter.
In this section:
•
Adding a DSN
•
Removing a DSN
•
Editing a DSN
•
Testing a DSN
Adding a DSN
To add a system DSN to the ASP Server, use the following procedure. When you add a DSN,
Chili!Soft ASP automatically sets the correct parameters for the databases. If necessary, you can
edit these parameters, as described in "Editing a DSN" in this chapter.
Notes about specific databases
- DB2. DB2 appears in the list of databases from which to select for Sun Solaris; however
DB2 is not supported on this platform.
- DB2. Before you configure a DSN for DB2, you must first have the required software
installed on your computer and load the DB2 profile, as described in "Configuring DB2"
in this chapter.
- Microsoft Access and Microsoft SQL Server 6.5. Chili!Soft ASP 3.6 includes an ODBC
driver for Microsoft SQL Server 7.0, but you must use SequeLink 4.51a for connecting to
Microsoft Access and Microsoft SQL Server 6.5 databases. You can create a DSN for
SequeLink using the procedure in this topic. However, before you do this, you must first
take the steps described in "Configuring SequeLink" in this chapter.
- Oracle, Sybase, and Informix. For these databases, after adding a DSN you must also
define database environment variables, as described in "Configuring the Database
Environment" in this chapter. Unless the environment variables have been set previously,
after you finish adding a new DSN, the Administration Console opens the appropriate
page on which to configure these settings.
To add a system DSN to the ASP Server, use the following procedure.
To add a system DSN
1. If necessary, open the Chili!Soft ASP Administration Console by using the following URL:
Chili!Soft ASP 3.6 Product Documentation
142
http://[HOSTNAME]:[PORT]
where [HOSTNAME] is the hostname of your Web server and [PORT] is the port on which
the Administration Console is running (5100 by default).
17. On the ASP Server tab of the Server Management page (the first page to appear when you
open the Administration Console), click Databases.
The Databases page displays.
18. Click Add new DSN.
The New Data Source Name page displays.
Chili!Soft ASP 3.6 Product Documentation
143
19. In the DSN box, type a name for the DSN.
20. If you want, in the Description box, type a description of the DSN to help distinguish it from
other DSNs.
21. In the Database type drop-down list, select the type of database for which you want to
configure a DSN--except for Microsoft Access and Microsoft SQL Server 6.5 databases,
select SequeLink 4.51a.
22. In the remaining text boxes, provide the requested information. For more information, see the
topic for your database in "Configuring Database Parameters" in this chapter.
23. To save your changes, click Save, and then click Done.
– or –
Click Cancel to revert to the last settings that were saved.
The new DSN appears in the Data Source Names list. After adding a DSN, it is a good idea to
test it, as described in "Testing a DSN" in this chapter.
See also:
Configuring Data Source Names (DSNs) in this chapter
Removing a DSN in this chapter
Editing a DSN in this chapter
Enabling Database Connections on the Server in "Chapter 2: Installing and Configuring
Chili!Soft ASP"
Chili!Soft ASP 3.6 Product Documentation
144
Removing a DSN
You remove a system DSN from the ASP Server, by using the Chili!Soft ASP Administration
Console. When you do this, it no longer can be used in an ASP application to reference database
connection information.
To remove a system DSN from the ASP Server, use the following procedure.
To remove a system DSN
1. If necessary, open the Administration Console by using the following URL:
http://[HOSTNAME]:[PORT]
where [HOSTNAME] is the hostname of your Web server and [PORT] is the port on which
the Administration Console is running (5100 by default).
2. On the ASP Server tab of the Server Management page (the first page to appear when you
open the Administration Console), click Databases.
The Databases page displays.
3. In the same line as the name of the DSN you want to remove, click remove.
Chili!Soft ASP 3.6 Product Documentation
145
4. When prompted to confirm the removal, click Yes, and then click Done.
See also:
Configuring Data Source Names (DSNs) in this chapter
Adding a DSN in this chapter
Editing a DSN in this chapter
Testing a DSN in this chapter
Enabling Database Connections on the Server in "Chapter 2: Installing and Configuring
Chili!Soft ASP"
Editing a DSN
After adding a system DSN to the ASP Server, you can change its information, such as name,
description, IP address, username, password, and so forth. You can also add values for parameters
that were not configured when you added the DSN.
When you add a new DSN to the ASP Server, Chili!Soft ASP automatically sets the correct
parameters for the database. Changing these parameters can affect database performance, so it is
not recommended that you do so. The default settings are sufficient for most applications. Before
editing database parameters, see the topics describing the required parameters for each ODBC
driver, which are provided in "Configuring Database Parameters" in this chapter.
To edit the information for a system DSN, use the following procedure.
To edit system DSN information
1. If necessary, open the Chili!Soft ASP Administration Console by using the following URL:
http://[HOSTNAME]:[PORT]
Chili!Soft ASP 3.6 Product Documentation
146
where [HOSTNAME] is the hostname of your Web server and [PORT] is the port on which
the Administration Console is running (5100 by default).
2. On the ASP Server tab of the Server Management page, click Databases.
The Data Source Names page displays.
3. In the same line as the name of the DSN you want to change, click edit.
The Edit Data Source Name page displays.
Chili!Soft ASP 3.6 Product Documentation
147
4. Change the database parameters as desired.
5. To save your changes, click Save and then click Done.
– or –
Click Cancel to revert to the last settings that were saved.
See also:
Configuring Data Source Names (DSNs) in this chapter
Adding a DSN in this chapter
Removing a DSN in this chapter
Testing a DSN in this chapter
Testing a DSN
When you have finished adding a new system DSN or editing its information, you can use the
following procedure to verify that it is functioning correctly.
To test a system DSN
1. If necessary, open the Chili!Soft ASP Administration Console by using the following URL:
Chili!Soft ASP 3.6 Product Documentation
148
http://[HOSTNAME]:[PORT]
where [HOSTNAME] is the hostname of your Web server and [PORT] is the port on which
the Administration Console is running (5100 by default).
24. On the ASP Server tab of the Server Management page (the first page to appear when you
open the Administration Console), click Databases.
The Data Source Names page displays.
25. In the same line as the name of the DSN you want to change, click test.
A dialog box displays providing information about the connection. If it reveals an error,
correct the problem, and then retest the connection.
Chili!Soft ASP 3.6 Product Documentation
149
Note
If you are running Chili!Soft ASP 3.6 with a Zeus Web server, and the test fails, it could
be because the Web server hostname is not configured correctly. When you configure a
Zeus Web server to run with Chili!Soft ASP 3.6, you should NOT use the fully qualified
domain name ("server address") for the Web server hostname. Instead, use the hostname
alone. For example, do not use this: hostname.domain.com. Instead, use this: hostname.
If your Zeus Web server is configured with the server address rather than the hostname
alone, you can test a DSN by using the SQLEXECUTE diagnostic included with
Chili!Soft ASP. For more information, see "Accessing Documentation, Samples, and
Diagnostics" in "Introduction: About This Documentation."
See also:
Configuring Data Source Names (DSNs) in this chapter
Adding a DSN in this chapter
Editing a DSN in this chapter
Removing a DSN in this chapter
Viewing the List of ODBC Drivers
Chili!Soft ASP enables you to connect to a variety of ODBC-compliant databases by using the
appropriate ODBC driver. To verify whether or not Chili!Soft ASP supports a specific version of
a database, you can view the list of ODBC drivers included with Chili!Soft ASP on the Drivers
tab of the Chili!Soft ASP Administration Console Databases page.
To view the list of ODBC drivers supported by Chili!Soft ASP, use the following procedure.
To view the list of ODBC Drivers
1. If necessary, open the Administration Console by using the following URL:
http://[HOSTNAME]:[PORT]
where [HOSTNAME] is the hostname of your Web server and [PORT] is the port on which
the Administration Console is running (5100 by default).
Chili!Soft ASP 3.6 Product Documentation
150
2. On the ASP Server tab of the Server Management page (the first page to appear when you
open the Administration Console), click Databases.
The Databases page displays.
3. Click the Drivers tab.
The ODBC Drivers page appears, displaying the list of installed ODBC drivers and their
locations in the file system.
Chili!Soft ASP 3.6 Product Documentation
151
Configuring SequeLink
Chili!Soft ASP 3.6 includes the client portion of Merant SequeLink 4.5.1, which enables you to
connect to a remote Microsoft Access or Microsoft SQL Server 6.5 database running on
Windows 95, Windows 98, Windows NT 3.51 or 4.0, or Windows 2000. The SequeLink client
resides on the same computer as the ASP Server and behaves like an ODBC driver. It
communicates with a SequeLink server running on the remote database server.
Before you can use SequeLink to connect to a remote database, you must take the following
steps:
1. Configure the SequeLink client software for Microsoft Access or Microsoft SQL Server 6.5,
as described later in this topic.
2. Install and configure the SequeLink server software on the database server. You can
download the software from the Chili!Soft Web site at:
ftp://ftp.chilisoft.com/chiliasp/sequelink/slkntsrv.zip
3. Add a SequeLink DSN by using the Administration Console, as described in "Adding a
DSN" in this chapter. When you do this, be sure to use the DSN name that you create in the
following procedure.
To configure the SequeLink client for Microsoft Access, use the following procedure.
Chili!Soft ASP 3.6 Product Documentation
152
To configure the SequeLink client for Microsoft Access
1. From the Chili!Soft ASP instance subdirectory of the Chili!Soft ASP installation directory
type the following command:
./setsqlnk
2. Select [2] New to create a new SequeLink DSN. Enter the following information when
prompted:
Name: The name of the SequeLink DSN that you want to create (you must use the same
DSN name when you configure the SequeLink DSN in the Administration Console).
Description: Optional
Transliteration: Do not configure this option. Leave it as-is.
Select a network: Select TCP.
Host: Enter the IP address of the Windows server on which your database is running.
ServerType: Select Windows NT Server.
User: Enter the username for accessing the Windows server.
Password: Enter the password for accessing the Windows server.
Select a Database service: Select ODBC MS Access.
Name: Enter the name of the Windows service that you created when installing the
SequeLink Server software.
Database: Enter the name of the database to which you want this DSN to connect, for
example, E:\data\publish.mdb (note the Windows syntax for providing the path
information).
3. Select [6] Test. The setup utility should return Test Passed. If you receive an error, select
[4] to edit your DSN information.
4. After completing SequeLink setup, select [0] to exit.
5. Configure the SequeLink DSN, as described in "Adding a DSN" in this chapter.
To configure the SequeLink client for Microsoft SQL Server 6.5, use the following procedure.
To configure the SequeLink client for Microsoft SQL Server 6.5
1. From the Chili!Soft ASP instance subdirectory of the Chili!Soft ASP installation directory
type:
./setsqlnk
2. Select [2] New to create a new SequeLink DSN. Enter the following information when
prompted:
Name: The name of the SequeLink DSN that you want to create (you must use the same
DSN name when you configure the SequeLink DSN in the Administration Console).
Description: Optional
Chili!Soft ASP 3.6 Product Documentation
153
Transliteration: Do not configure this setting. Leave it as-is.
Select a network: Select TCP.
Host: Enter the IP address of the Windows server on which your database is running.
ServerType: Select Windows NT Server.
User: Enter the username for accessing the Windows server.
Password: Enter the password for accessing the Windows server.
Select a Database service: Select MS SQL Server.
Name: Enter the name of the Windows service that you created when installing the
SequeLink Server software.
Database: Enter the name of the database to which you want this DSN to connect.
User: Enter the SQL Server username for accessing the database.
Password: Enter the password for accessing the SQL Server database (required).
3. Select [6] Test. The setup utility should return Test Passed. If you receive an error, select [4]
to edit your DSN information.
4. After completing SequeLink setup, select [0] to exit.
5. Configure the SequeLink DSN, as described in "Adding a DSN" in this chapter.
See also:
Configuring a Database in this chapter
SequeLink Parameters in this chapter
Configuring DB2
Chili!Soft ASP 3.6 for IBM AIX and Chili!Soft ASP 3.6 for Linux include an ODBC driver that
enables an ASP application to connect with a DB2 database. In addition, DB2 ODBC drivers for
Sun Solaris and HP-UX are supported by Chili!Soft ASP 3.6, although they are not included with
this product. When you install a DB2 ODBC driver for Sun Solaris or HP-UX, the Administration
Console automatically detects it and enables you to configure a DSN in the same manner as you
can with IBM AIX and Linux. For all platforms, you must use the catalogued name of the
database for the DSN name when configuring a DSN for a DB2 database.
In order to configure DB2 database connections, the following software must be installed on the
computer running the Chili!Soft ASP Server:
•
IBM DB2 Client Application Enabler (CAE) for your operating system, version 2.1 or
higher
•
IBM DB2 Software Development Kit (DB2 SDK) for your operating system, version 2.1
or higher
In addition, you must load the database profile, as described next, in "Loading DB2 Profiles."
See also:
Chili!Soft ASP 3.6 Product Documentation
154
Configuring a Database in this chapter
Loading DB2 Profiles
Chili!Soft ASP 3.6 for IBM AIX and Linux includes a DB2 database. In order for the DB2
database to connect to the Chili!Soft ASP Server, you must first load the database profile as
described in this topic. You must also have the software installed that is described in the previous
topic, "Configuring DB2."
To load the DB2 profile, use the following procedure.
To load a DB2 profile
1. If necessary, open the Chili!Soft ASP Administration Console by using the following URL:
http://[HOSTNAME]:[PORT]
where [HOSTNAME] is the hostname of your Web server and [PORT] is the port on which
the Administration Console is running (5100 by default).
2. On the ASP Server tab of the Server Management page (the first page to appear when you
open the Administration Console), click Databases.
The Databases page displays.
3. Click the DB2 Profiles tab.
The DB2 Profiles page displays.
Chili!Soft ASP 3.6 Product Documentation
155
Each currently loaded DB2 profile displays in a separate text box, along with an empty text
box in which you type the absolute path name of the profile that you want to load. If no
profiles are currently loaded, a single empty text box appears on the page.
4. In the empty text box, type the absolute path name for DB2-profile file you want to load. If
you make a mistake, click Reset to restore the information about currently loaded profiles.
5. When finished, click Save.
You must restart the ASP Server in order to finish loading the DB2 profile. If the Restart
ASP Server checkbox is selected, the ASP Server automatically restarts when you click
Save.
6. To add another profile, type its absolute path name in the empty text box that appears under
the last profile you loaded.
7. To remove a DB2 profile, delete the path name of the profile, and then click Save.
Note
Restarting the ASP Server resets all Session and Application variables.
See also:
Configuring DB2 in this chapter
DB2 Parameters in this chapter
Configuring a Database in this chapter
Chili!Soft ASP 3.6 Product Documentation
156
Editing the Microsoft SQL Server Template
In order for developers to use DSN-less connection strings or file DSNs to connect an ASP
application to a Microsoft SQL Server 7.0 database, you must specify the values for two
parameters in the Microsoft SQL Server template section of the odbc.ini file. For the
ServerIpAddress parameter, you must specify the IP address for the database server. For the
ServerPortNumber parameter, you must specify the port number on which the database server is
running.
In order to perform this procedure, you must be logged in as root on the computer running the
Chili!Soft ASP Server.
To edit the Microsoft SQL Server template, use the following procedure.
To edit the Microsoft SQL Server template
1. Stop Chili!Soft ASP Server, as described in "Stopping and Restarting the ASP Server" in this
chapter.
2. In the /casp directory, open the odbc.ini file in a text editor. This file is located in the
following directory:
/[C-ASP_INSTALL_DIR]/asp-[WEB_SERVER]-[PORT]
where [C-ASP_INSTALL_DIR] is the path name of the Chili!Soft ASP installation directory,
[WEB_SERVER] resembles apache, netscape, or zeus, and [PORT] is the ASP Server port
number (resembles 3000).
3. In the [MSSQLServer_template] section of the odbc.ini file, specify the
ServerIpAddress and ServerPortNumber values for the SQL Server 7.0 database you want
to configure.
4. Save your changes, and then restart the ASP Server, as described in "Stopping and Restarting
the ASP Server" in this chapter.
See also:
Using File DSNs in "Chapter 4: Building a Chili!Soft ASP Application"
Using DSN-less Connection Strings in "Chapter 4: Building a Chili!Soft ASP Application"
Configuring the Database Environment
When you configure data source names (DSNs) for Oracle, Sybase, and Informix databases for
Chili!Soft ASP, you must also specify additional environment information, as described in this
section. For more information about the settings to use, consult your database administrator. For
more information about configuring DSNs, see "Configuring Data Source Names (DSNs)" in this
chapter.
In this section:
•
Setting Oracle Environment Variables
•
Setting Sybase Environment Variables
Chili!Soft ASP 3.6 Product Documentation
•
157
Setting Informix Environment Variables
Setting Oracle Environment Variables
When you configure a DSN for an Oracle database, you must also specify values for the
Oracle_Home and Library path environment variables by using the following procedure. For
information about what values to set for these variables, consult your database administrator.
To set Oracle environment variables
1. If necessary, open the Chili!Soft ASP Administration Console by using the following URL:
http://[HOSTNAME]:[PORT]
where [HOSTNAME] is the hostname of your Web server and [PORT] is the port on which
the Administration Console is running (5100 by default).
2. On the ASP Server tab of the Server Management page (the first page to appear when you
open the Administration Console), click Databases.
The Databases page displays.
3. Click the Environment tab.
The Environment Database Specific Variables page displays.
Chili!Soft ASP 3.6 Product Documentation
4. Under the Oracle heading, in the Oracle_Home and Library path boxes, type the values
you want.
5. Select the Restart the ASP Server after saving checkbox.
6. Click Save.
Note
Restarting the ASP Server resets all Session and Application variables.
See also:
Configuring a Database in this chapter
158
Chili!Soft ASP 3.6 Product Documentation
159
Setting Sybase Environment Variables
When you configure a DSN for a Sybase database, you must also specify values for the Sybase
and Library path environment variables by using the following procedure. For information
about what values to set for these variables, consult your database administrator.
To set Sybase environment variables
1. If necessary, open the Chili!Soft ASP Administration Console by using the following URL:
http://[HOSTNAME]:[PORT]
where [HOSTNAME] is the hostname of your Web server and [PORT] is the port on which
the Administration Console is running (5100 by default).
2. On the ASP Server tab of the Server Management page (the first page to appear when you
open the Administration Console), click Databases.
The Databases page displays.
3. Click the Environment tab.
The Environment Database Specific Variables page displays.
Chili!Soft ASP 3.6 Product Documentation
160
4. Under the Sybase heading, in the Sybase and Library path boxes, type the values you want.
5. Select the Restart the ASP Server after saving checkbox.
6. Click Save.
Note
Restarting the ASP Server resets all Session and Application variables.
See also:
Configuring a Database in this chapter
Setting Informix Environment Variables
When you configure a DSN for an Informix 7 or 9 database, you must also specify values for the
INFORMIXDIR, INFORMIXSERVER, Temp path, Library path, and eSQL path
Chili!Soft ASP 3.6 Product Documentation
161
environment variables by using the following procedure. For information about what values to set
for these variables, consult your database administrator.
To set Informix environment variables
1. If necessary, open the Chili!Soft ASP Administration Console by using the following URL:
http://[HOSTNAME]:[PORT]
where [HOSTNAME] is the hostname of your Web server and [PORT] is the port on which
the Administration Console is running (5100 by default).
2. On the ASP Server tab of the Server Management page (the first page to appear when you
open the Administration Console), click Databases.
The Databases page displays.
3. Click the Environment tab.
The Environment Database Specific Variables page displays.
Chili!Soft ASP 3.6 Product Documentation
162
4. Under the Informix heading, in the INFORMIXDIR, INFORMIXSERVER, Temp path,
Library path, and eSQL path boxes, type the values you want.
5. Select the Restart the ASP Server after saving checkbox.
6. Click Save.
Note
Restarting the ASP Server resets all Session and Application variables.
See also:
Configuring a Database in this chapter
Chili!Soft ASP 3.6 Product Documentation
163
Configuring Database Parameters
In order to make it easier for Web developers to connect to a database from an ASP page, you can
"add" a system DSN for the database to the ASP Server, as described in "Adding a DSN" in this
chapter. When you do this, Chili!Soft ASP automatically configures the appropriate parameters
for the ODBC driver installed for that database. The ASP Server and ODBC Manager then use
this information to establish the connection.
In most cases, it is not a good idea to change the parameters that Chili!Soft ASP configures.
However, there might be times when you must edit them. This topic provides reference
information about the parameters that are configured for the ODBC drivers installed by Chili!Soft
ASP 3.6.
Note
Chili!Soft ASP 3.6 installs the ODBC drivers for a number of databases, but it does not
provide them for all databases on all platforms. You can view the list of installed drivers
for your platform from the Administration Console, as described in "Viewing the List of
ODBC Drivers" in this chapter. Chili!Soft provides technical support only for the ODBC
drivers installed with Chili!Soft ASP.
In this section:
•
DB2
•
dBase 5
•
Informix 7, 9
•
Interbase 6 (Linux and Cobalt only)
•
Microsoft SQL Server 7.0
•
MySQL 3.22.32 (Linux, Cobalt, and Solaris only)
•
Oracle 7, 8, 8i (versions 8 and 8i on Linux and Cobalt only)
•
PostgreSQL 6.5.2 (Linux and Cobalt only)
•
SequeLink (for connecting to Microsoft Access and Microsoft SQL Server 6.5 databases)
•
Sybase 11.9.2
See also:
Configuring a Database in this chapter
Editing a DSN in this chapter
DB2 Parameters
The following table describes the DB2 database parameters available for configuring system
DSNs, as they appear on the Chili!Soft ASP Administration Console New Data Source Name
and Edit Data Source Name pages. For more information, see "Configuring Data Source Names
(DSNs)" in this chapter.
Chili!Soft ASP 3.6 Product Documentation
164
Parameter
Explanation
Data Source Name*
This is the name of the data source name (DSN) you are
configuring. It must match the catalogued name of the DB2
database.
Database type*
This indicates for which type of database you are configuring
this DSN (DB2).
Description
This field provides a description of the DSN to distinguish it
from others.
Driver*
On the New Data Source Name page, this is the name of the
ODBC driver installed for the type of database selected in the
Database type box (DB2). It is a non-configurable field.
On the Edit Data Source Name page, this is the absolute path
name of the ODBC driver specified for this DSN. It is a
configurable field.
Database*
This entry must match the catalogued name of this DB2
database. The data source name (DSN) specified above must
match this entry.
LogonID
This is the username required for accessing the database. If the
username is not provided when configuring a system DSN,
every connection string using this DSN must include the
username.
Important Security Note:
In shared Web hosting environments, to prevent access to a
database by unauthorized users, it is recommended that the
username and password be provided in each connection string,
rather than in the system DSN.
Password
This is the password required for accessing the database. If the
password is not provided when configuring a system DSN,
every connection string using the DSN must include the
password.
Important Security Note:
In shared Web hosting environments, to prevent access to a
database by unauthorized users, it is recommended that the
username and password be provided in each connection string,
rather than in the system DSN.
* Required parameters.
See also:
Configuring a Database in this chapter
Configuring Database Parameters in this chapter
Chili!Soft ASP 3.6 Product Documentation
165
dBase 5 Parameters
The following table describes the dBase 5 database parameters available for configuring system
DSNs, as they appear on the Chili!Soft ASP Administration Console New Data Source Name
and Edit Data Source Name pages. For more information, see "Configuring Data Source Names
(DSNs)" in this chapter.
Parameter
Explanation
Data Source Name*
This is the name of the data source name (DSN) you are configuring.
Database type*
This indicates for which type of database you are configuring this DSN
(dBase 5).
Description
This field provides a description of the DSN to help distinguish it from
others.
Driver*
On the New Data Source Name page, this is the name of the ODBC
driver installed for the type of database selected in the Database type
box (dBase 5). It is a non-configurable field.
On the Edit Data Source Name page, this is the absolute path name of
the ODBC driver specified for this DSN. It is a configurable field.
Database*
This is the path name of the directory in which the DBF files reside.
* Required parameters.
See also:
Configuring a Database in this chapter
Configuring Database Parameters in this chapter
Informix 7, 9 Parameters
The following table describes the Informix 7 or 9 database parameters available for configuring
system DSNs, as they appear on the Chili!Soft ASP Administration Console New Data Source
Name and Edit Data Source Name pages. For more information, see "Configuring Data Source
Names (DSNs)" in this chapter.
Parameter
Explanation
Data Source Name*
This is the name of the data source name (DSN) you are configuring.
Database type*
This indicates for which type of database you are configuring this DSN
(Informix 7 or 9).
Description
This field provides a description of the DSN to help distinguish it from
others.
Driver*
On the New Data Source Name page, this is the name of the ODBC
driver installed for the type of database selected in the Database type
box (Informix 7 or 9). It is a non-configurable field.
On the Edit Data Source Name page, this is the absolute path name of
Chili!Soft ASP 3.6 Product Documentation
166
the ODBC driver specified for this DSN. It is a configurable field.
ServerName*
This is the IP address of the database server. If this field is blank, the
database is assumed to be running on the local computer.
Database*
Because there can be multiple installations of a database running on one
computer, each database is given its own name. This parameter
indicates the name of the database for which you are configuring this
DSN.
LogonID
This is the username required for accessing the database. If the
username is not provided when configuring a system DSN, every
connection string using this DSN must include the username.
Important Security Note:
In shared Web hosting environments, to prevent access to a database by
unauthorized users, it is recommended that the username and password
be provided in each connection string, rather than in the system DSN.
Password
This is the password required for accessing the database. If the
password is not provided when configuring a system DSN, every
connection string using this DSN must include the password.
Important Security Note:
In shared Web hosting environments, to prevent access to a database by
unauthorized users, it is recommended that the username and password
be provided in each connection string, rather than in the system DSN.
* Required parameters.
See also:
Configuring a Database in this chapter
Configuring Database Parameters in this chapter
Interbase 6 Parameters (Linux and Cobalt only)
The following table describes the Interbase 6 database parameters available for configuring
system DSNs, as they appear on the Chili!Soft ASP Administration Console New Data Source
Name and Edit Data Source Name pages. For more information, see "Configuring Data Source
Names (DSNs)" in this chapter.
Parameter
Explanation
Data Source Name*
This is the name of the data source name (DSN) you are configuring.
Database type*
This indicates for which type of database you are configuring this DSN
(Interbase 6).
Description
This field provides a description of the DSN to help distinguish it from
others.
Driver*
On the New Data Source Name page, this is the name of the ODBC
Chili!Soft ASP 3.6 Product Documentation
167
driver installed for the type of database selected in the Database type
box (Interbase 6). It is a non-configurable field.
On the Edit Data Source Name page, this is the absolute path name of
the ODBC driver specified for this DSN. It is a configurable field.
DbName*
Because there can be multiple installations of a database running on one
computer, each database is given its own name. This parameter
indicates the name of the database you are configuring for this DSN.
User
This is the username required for accessing the database. If the
username is not provided when configuring a system DSN, every
connection string using the DSN must include the username.
Important Security Note:
In shared Web hosting environments, to prevent access to a database by
unauthorized users, it is recommended that the username and password
be provided in each connection string, rather than in the system DSN.
Password
This is the password required for accessing the database. If the
password is not provided when configuring a system DSN, every
connection string using the DSN must include the password.
Important Security Note:
In shared Web hosting environments, to prevent access to a database by
unauthorized users, it is recommended that the username and password
be provided in each connection string, rather than in the system DSN.
UseCursorLib
When this option is enabled (the checkbox is selected), ODBC Manager
cursor support overrides ODBC driver cursor support. Use to enable
scrollable cursors when not supported by the ODBC driver. Enabled by
default.
JdbcDriver
Absolute path name of the JDBC driver file.
* Required parameters.
See also:
Configuring a Database in this chapter
Configuring Database Parameters in this chapter
Microsoft SQL Server 7.0 Parameters
The following table describes the Microsoft SQL Server 7.0 database parameters available for
configuring system DSNs, as they appear on the Chili!Soft ASP Administration Console New
Data Source Name and Edit Data Source Name pages. For more information, see "Configuring
Data Source Names (DSNs)" in this chapter.
Parameter
Explanation
Data Source Name*
This is the name of the data source name (DSN) you are configuring.
Chili!Soft ASP 3.6 Product Documentation
168
Database type*
This indicates for which type of database you are configuring this DSN
(Microsoft SQL Server 7.0).
Description
This field provides a description of the DSN to help distinguish it from
others.
Driver*
On the New Data Source Name page, this is the name of the ODBC
driver installed for the type of database selected in the Database type
box (Microsoft SQL Server 7.0). It is a non-configurable field.
On the Edit Data Source Name page, this is the absolute path name of
the ODBC driver specified for this DSN. It is a configurable field.
DATABASE*
Because there can be multiple installations of a database running on one
computer, each database is given its own name. This parameter
indicates the name of the database for which you are configuring this
DSN.
ServerIPAddress*
This is the IP address of the SQL Server 7.0 database server.
ServerPortNumber*
The port on which the SQL Server 7.0 database server is configured to
listen. The default is 1433.
LogonID
This is the username required for accessing the database. If the
username is not provided when configuring a system DSN, every
connection string using this DSN must include the username.
Important Security Note:
In shared Web hosting environments, to prevent access to a database by
unauthorized users, it is recommended that the username and password
be provided in each connection string, rather than in the system DSN.
Password
This is the password required for accessing the database. If the
password is not provided when configuring a system DSN, every
connection string using the DSN must include the password.
Important Security Note:
In shared Web hosting environments, to prevent access to a database by
unauthorized users, it is recommended that the username and password
be provided in each connection string, rather than in the system DSN.
* Required parameters.
See also:
Configuring a Database in this chapter
Configuring Database Parameters in this chapter
MySQL 3.22.32 Parameters (Linux, Cobalt, and Solaris only)
The following table describes the MySQL 3.22.32 database parameters available for configuring
system DSNs, as they appear on the Chili!Soft ASP Administration Console New Data Source
Chili!Soft ASP 3.6 Product Documentation
169
Name and Edit Data Source Name pages. For more information, see "Configuring Data Source
Names (DSNs)" in this chapter.
Parameter
Explanation
Data Source Name*
This is the name of the data source name (DSN) you are configuring.
Database type*
This indicates for which type of database you are configuring this DSN
(MySQL 3.22.32).
Description
This field provides a description of the DSN to help distinguish it from
others.
Driver*
On the New Data Source Name page, this is the name of the ODBC
driver installed for the type of database selected in the Database type
box (MySQL 3.22.32). It is a non-configurable field.
On the Edit Data Source Name page, this is the absolute path name of
the ODBC driver specified for this DSN. It is a configurable field.
Server*
This is the IP address of the MySQL database server. If this field is
blank, the server is assumed to be running on the local computer.
Port*
The port on which the MySQL database server is configured to listen.
The default is 3306.
Database*
Because there can be multiple installations of a database running on one
computer, each database is given its own name. This parameter
indicates the name of the database for which you are configuring this
DSN.
User
This is the username required for accessing the database. If the
username is not provided when configuring a system DSN, every
connection string using this DSN must include the username.
Important Security Note:
In shared Web hosting environments, to prevent access to a database by
unauthorized users, it is recommended that the username and password
be provided in each connection string, rather than in the system DSN.
Password
This is the password required for accessing the database. If the
password is not provided when configuring a system DSN, every
connection string using the DSN must include the password.
Important Security Note:
In shared Web hosting environments, to prevent access to a database by
unauthorized users, it is recommended that the username and password
be provided in each connection string, rather than in the system DSN.
UseCursorLib
When this option is enabled (the checkbox is selected), ODBC Manager
cursor support overrides ODBC driver cursor support. This enables
RecordSet.Update, which is not supported in the default MyODBC
driver. Enabled by default.
Chili!Soft ASP 3.6 Product Documentation
170
* Required parameters.
See also:
Configuring a Database in this chapter
Configuring Database Parameters in this chapter
Oracle 7, 8, 8i Parameters (8, 8i on Linux and Cobalt only)
The following table describes the Oracle 7,8,8i database parameters available for configuring
system DSNs, as they appear on the Chili!Soft ASP Administration Console New Data Source
Name and Edit Data Source Name pages. For more information, see "Configuring Data Source
Names (DSNs)" in this chapter.
Parameter
Explanation
Data Source Name*
This is the name of the data source name (DSN) you are configuring.
Database type
This indicates for which type of database you are configuring this
DSN (Oracle 7, 8, or 8i).
Description*
This field provides a description of the DSN to help distinguish it
from others.
Driver*
On the New Data Source Name page, this is the name of the ODBC
driver installed for the type of database selected in the Database
type box (Oracle 7, 8, or 8i). It is a non-configurable field.
On the Edit Data Source Name page, this is the absolute path name
of the ODBC driver specified for this DSN. It is a configurable field.
ServerName*
This is the TNS name as defined in the tnsnames.ora file by the
Oracle database client utility.
LogonID
This is the username required for accessing the database. If the
username is not provided when configuring a system DSN, every
connection string using this DSN must include the username.
Important Security Note:
In shared Web hosting environments, to prevent access to a database
by unauthorized users, it is recommended that the username and
password be provided in each connection string, rather than in the
system DSN.
Password
This is the password required for accessing the database. If the
password is not provided when configuring a system DSN, every
connection string using the DSN must include the password.
Important Security Note:
In shared Web hosting environments, to prevent access to a database
by unauthorized users, it is recommended that the username and
password be provided in each connection string, rather than in the
Chili!Soft ASP 3.6 Product Documentation
171
system DSN.
EnableDescribeParam
When this option is enabled (the checkbox is selected), all
StoredProcedure arguments are returned as string types. Enabled
by default.
ProcedureRetResults
When this option is enabled (the checkbox is selected), Oracle
returns record sets from a StoredProcedure call. Enabled by
default.
* Required parameters.
See also:
Configuring a Database in this chapter
Configuring Database Parameters in this chapter
PostgreSQL 6.5.2 Parameters (Linux and Cobalt only)
The following table describes the PostgreSQL 6.5.2 database parameters available for
configuring system DSNs, as they appear on the Chili!Soft ASP Administration Console New
Data Source Name and Edit Data Source Name pages. For more information, see "Configuring
Data Source Names (DSNs)" in this chapter.
Parameter
Explanation
Data Source Name*
This is the name of the data source name (DSN) you are configuring.
Database type*
This indicates for which type of database you are configuring this
DSN (PostgreSQL 6.5.2).
Description
This field provides a description of the DSN to help distinguish it
from others.
Driver*
On the New Data Source Name page, this is the name of the ODBC
driver installed for the type of database selected in the Database
type box (PostgreSQL 6.5.2). It is a non-configurable field.
On the Edit Data Source Name page, this is the absolute path name
of the ODBC driver specified for this DSN. It is a configurable field.
ServerName*
This is the IP address of the PostgreSQL database server. If this field
is blank, the server is assumed to be running on the local computer.
Port*
The port on which the PostgreSQL database server is configured to
listen. The default is 5432.
Database*
Because there can be multiple installations of a database running on
one computer, each database is given its own name. This parameter
indicates the name of the database for which you are configuring this
DSN.
User
This is the username required for accessing the database. If the
username is not provided when configuring a system DSN, every
Chili!Soft ASP 3.6 Product Documentation
172
connection string using this DSN must include the username.
Important Security Note:
In shared Web hosting environments, to prevent access to a database
by unauthorized users, it is recommended that the username and
password be provided in each connection string, rather than in the
system DSN.
Password
This is the password required for accessing the database. If the
password is not provided when configuring a system DSN, every
connection string using the DSN must include the password.
Important Security Note:
In shared Web hosting environments, to prevent access to a database
by unauthorized users, it is recommended that the username and
password be provided in each connection string, rather than in the
system DSN.
ReadOnly*
When this option is enabled (the checkbox is selected), the database
returns all record sets as read-only. Disabled by default.
UseCursorLib
When this option is enabled (the checkbox is selected), ODBC
Manager cursor support overrides ODBC driver cursor support. Use
this to enable scrollable cursors not supported by the driver. Enabled
by default.
* Required parameters.
See also:
Configuring a Database in this chapter
Configuring Database Parameters in this chapter
SequeLink Parameters
You use SequeLink for connecting to Microsoft Access and Microsoft SQL Server 6.5 databases
running on Windows-based computers. The following table describes the SequeLink database
parameters available for configuring system DSNs, as they appear on the Chili!Soft ASP
Administration Console New Data Source Name and Edit Data Source Name pages.
Parameter
Explanation
Data Source Name*
This is the name of the data source name (DSN) you are
configuring. It must match the entry for SQLnkDSN (below),
which is the DSN created with the ./setsqllnk utility. For more
information, see "Configuring SequeLink" in this chapter.
Database type
On the New Data Source Name page, select SequeLink 4.51a
from the list in order to configure a DSN for a Microsoft Access
or Microsoft SQL Server 6.5 database.
On the Edit Data Source Name page, SequeLink 4.51a appears
Chili!Soft ASP 3.6 Product Documentation
173
in this field.
Description*
This field provides a description of the DSN to help distinguish it
from others.
Driver*
On the New Data Source Name page, this is the name of the
database driver configured for this DSN (SequeLink). It is a nonconfigurable field.
On the Edit Data Source Name page, this is the absolute path
name of the database driver specified for this DSN. It is a
configurable field.
SQLnkDSN*
This is the name of the DSN configured by running the ./setsqllnk
utility. For more information, see "Configuring SequeLink" in
this chapter.
Database*
For Microsoft Access databases, this is the absolute path name of
the Access MDB file on the Windows-based server.
For Microsoft SQL Server 6.5 databases, this is the database
name of the SQL Server database.
LogonID
This is the username required for accessing the database. If the
username is not provided when configuring a system DSN, every
connection string using this DSN must include the username.
Important Security Note:
In shared Web hosting environments, to prevent access to a
database by unauthorized users, it is recommended that the
username and password be provided in each connection string,
rather than in the system DSN.
PreFetchRows
This is an advanced feature. Do not change this setting without
first contacting Chili!Soft Customer Support. The default is 30.
Password
This is the password required for accessing the database. If the
password is not provided when configuring a system DSN, every
connection string using the DSN must include the password.
Important Security Note:
In shared Web hosting environments, to prevent access to a
database by unauthorized users, it is recommended that the
username and password be provided in each connection string,
rather than in the system DSN.
EnableWarnings
This is an advanced feature. Do not change this setting without
first contacting Chili!Soft Customer Support. Enabled by default
(the checkbox is selected).
UidPwdMapping
Microsoft SQL Server requires two sets of usernames and
passwords, one for accessing the host server, and one for
Chili!Soft ASP 3.6 Product Documentation
174
accessing the database. Only one pair can be passed via the
connection string (or the LoginID/password configured here).
The other must be configured into the SqlnkDSN, as described in
"Configuring SequeLink" in this chapter.
When UidPwdMapping is enabled (the checkbox is selected), the
LoginID represents the host. When UidPwdMapping is disabled
(the checkbox is not selected) the LoginID represents the
database. Disabled by default.
AllowBatchStatements
This is an advanced feature. Do not change this setting without
first contacting Chili!Soft Customer Support. Disabled by default
(the checkbox is not selected).
EnableScrollableCursors
This option enables the use of cursor types other than
"ForwardOnly." Enabled by default (the checkbox is selected).
DataDictionary
This is an advanced feature. Do not change this setting without
first contacting Chili!Soft Customer Support.
* Required parameter.
See also:
Configuring SequeLink in this chapter
Configuring a Database in this chapter
Configuring Database Parameters in this chapter
Sybase 11.9.2 Parameters
The following table describes the Sybase 11.9.2 database parameters available for configuring
system DSNs, as they appear on the Chili!Soft ASP Administration Console New Data Source
Name and Edit Data Source Name pages. For more information, see "Configuring Data Source
Names (DSNs)" in this chapter.
Parameter
Explanation
Data Source Name*
This is the name of the data source name (DSN) you are configuring.
Database type*
This indicates for which type of database you are configuring this
DSN (Sybase 11.9.2).
Description
This field provides a description of the DSN to help distinguish it
from others.
Driver*
On the New Data Source Name page, this is the name of the ODBC
driver installed for the type of database selected in the Database type
box (Sybase 11.9.2). It is a non-configurable field.
On the Edit Data Source Name page, this is the absolute path name
of the ODBC driver specified for this DSN. It is a configurable field.
ServerName*
This is the IP address of the Sybase database server. If this field is
Chili!Soft ASP 3.6 Product Documentation
175
blank, the server is assumed to be running on the local computer.
DB*
Because there can be multiple installations of a database running on
one computer, each database is given its own name. This parameter
indicates the name of the database for which you are configuring this
DSN.
LogonID
This is the username required for accessing the database. If the
username is not provided when configuring a system DSN, every
connection string using this DSN must include the username.
Important Security Note:
In shared Web hosting environments, to prevent access to a database
by unauthorized users, it is recommended that the username and
password be provided in each connection string, rather than in the
system DSN.
Password
This is the password required for accessing the database. If the
password is not provided when configuring a system DSN, every
connection string using the DSN must include the password.
Important Security Note:
In shared Web hosting environments, to prevent access to a database
by unauthorized users, it is recommended that the username and
password be provided in each connection string, rather than in the
system DSN.
* Required parameters.
See also:
Configuring a Database in this chapter
Configuring Database Parameters in this chapter
Configuring ActiveX Data Objects (ADO) Connections
ActiveX Data Objects (ADO) is the Microsoft standard for database access. Chili!Soft ASP
provides an ADO control, which you can configure by using the Chili!Soft ASP Administration
Console. For more information about ADO, see "Enabling Database Connections on the Server"
in "Chapter 2: Installing and Configuring Chili!Soft ASP" and "ADO Component Reference" in
"Chapter 5: Developer's Reference."
This section describes the following configuration options for the ADO control:
•
Setting the ADO Connection Pool Size
•
Enabling and Disabling ADO Logging
Chili!Soft ASP 3.6 Product Documentation
176
Setting the ADO Connection Pool Size
Chili!Soft ASP 3.6 supports database connection pooling, which dramatically improves the
performance of applications that rely heavily on database operations. With connection pooling,
rather than opening and closing a database connection for each individual request, Chili!Soft ASP
uses a connection that is already open.
Chili!Soft ASP uses an ADO control to provide database connectivity. You set the ADO
connection pool size parameter by using the Chili!Soft ASP Administration Console. The default
ADO connection pool size is 25, which you can either increase or decrease according to your
requirements. Setting this parameter to 0 (zero) disables connection pooling.
To set the ADO connection pool size, use the following procedure.
To set the ADO connection pool size
1. If necessary, open the Administration Console by using the following URL:
http://[HOSTNAME]:[PORT]
where [HOSTNAME] is the hostname of your Web server and [PORT] is the port on which
the Administration Console is running (5100 by default).
2. On the ASP Server tab of the Server Management page (the first page to appear when you
open the Administration Console), click Databases.
3. Click the ADO Settings tab.
The ActiveX Data Object Connection Setting tab displays.
Chili!Soft ASP 3.6 Product Documentation
177
4. In the Connection pool size box, type the number of connections you want to pool.
5. Click Save, and then click server management in the left navigation pane.
6. Restart the ASP Server by clicking Restart.
Note
Restarting the ASP Server resets all Session and Application variables.
See also:
Pooling Database Connections in this chapter
Enabling and Disabling ADO Logging
Chili!Soft ASP uses an ADO control to provide database connectivity. You enable logging for
ADO from the Chili!Soft ASP Administration Console by providing an absolute path name for
the log file. When you do this, Chili!Soft ASP creates the log file in the directory you specify and
begins logging to it. To disable logging, you simply delete the path name of the log file.
Important Note
You should use ADO logging only for diagnostic purposes. It is not recommend that you
leave logging enabled when running Chili!Soft ASP on a production server.
To enable ADO logging, use the following procedure.
To enable ADO logging
1. If necessary, open the Administration Console by using the following URL:
http://[HOSTNAME]:[PORT]
Chili!Soft ASP 3.6 Product Documentation
178
where [HOSTNAME] is the hostname of your Web server and [PORT] is the port on which
the Administration Console is running (5100 by default).
2. On the ASP Server tab of the Server Management page (the first page to appear when you
open the Administration Console), click Databases.
3. Click the ADO Settings tab.
The ActiveX Data Object Connection Setting tab displays.
4. In the Logging file box, type the absolute path name of the log file. This includes the path to
the directory containing the file and the name of the log file. You cannot use the name of a
file that already exists in the directory.
Chili!Soft ASP 3.6 Product Documentation
179
5. Click Save, and then click server management.
6. Restart the ASP Server by clicking Restart.
Note
Restarting the ASP Server resets all Session and Application variables.
To disable ADO logging, use the following procedure.
To disable ADO logging
1. If necessary, open the Administration Console by using the following URL:
http://[HOSTNAME]:[PORT]
where [HOSTNAME] is the hostname of your Web server and [PORT] is the port on which
the Administration Console is running (5100 by default).
2. On the ASP Server tab of the Server Management page (the first page to appear when you
open the Administration Console), click Databases.
The Databases page displays.
3. Click the ADO Settings tab.
The ActiveX Data Object Connection Setting tab displays.
Chili!Soft ASP 3.6 Product Documentation
180
4. Delete the text in the Logging file box.
5. Click Save, and then click server management.
6. Restart the ASP Server by clicking Restart.
Note
Restarting the ASP Server resets all Session and Application variables.
See also:
Configuring ActiveX Data Objects (ADO) Connections in this chapter
Running Chili!Soft ASP in a Shared Web Hosting
Environment
Chili!Soft ASP supports the scenario in which users share physical hardware and a Web server,
for example with an Internet Service Provider (ISP) or Internet Presence Provider (IPP). In a
shared Web hosting environment, a single Web server installation answers requests for multiple
domain names by using Virtual Hosts. This section provides useful information about running
Chili!Soft ASP in a shared Web hosting environment:
In this section:
•
Creating Database Connections in a Shared Environment
•
Defining Applications in a Shared Environment
•
Using the User Configuration File
•
Using the FrontPage 2000 Services File in a Shared Environment
•
Setting up Multi-machine Chili!Soft ASP
Chili!Soft ASP 3.6 Product Documentation
181
The following topic (in another section of this chapter) discusses important security information
that you should be aware of when configuring a shared Web hosting environment:
•
Securing the Server
The following section discusses advanced options for administering Chili!Soft ASP that can give
you more flexibility when configuring a shared hosting environment:
•
Advanced Administration Options
Creating Database Connections in a Shared Environment
With Chili!Soft ASP 3.6, ASP developers can specify the connection information for a database
by using either system DSNs, file DSNs, or DSN-less connection strings. The appropriate method
to use depends on user preferences and the environment in which Chili!Soft ASP is running.
In enterprises and other dedicated hosting environments, it is recommended that ASP developers
use system DSNs. The system administrator uses the Chili!Soft ASP Administration Console to
create system DSNs, which then can be referenced from within an ASP application for initializing
a database connection. For more information, see "Configuring Data Source Names (DSNs)" in
this chapter.
However, in a shared Web hosting environment, such as an ISP, system DSNs pose two
problems: First, system DSNs can be a security risk. System DSNs can include the username and
password required for accessing the database, making the data source accessible from any ASP
page on the server. Second, creating DSNs for each customer can create a significant
administrative burden for the Web hosting provider. Because Web developers can create them,
and database access is restricted to the specific ASP application using the connection, file DSNs
and DSN-less connection strings are often more appropriate in a Web hosting environment.
See also:
Configuring a Database in this chapter
Enabling Database Connections on the Server in "Chapter 2: Installing and Configuring
Chili!Soft ASP"
Using DSN-less Connection Strings" in "Chapter 4: Building a Chili!Soft ASP Application"
Defining Applications in a Shared Environment
In order for the ASP Server to process an ASP application, the set of directories and files
comprising the application must be defined as an ASP application. In dedicated Web hosting
environments, you define an ASP application by "adding" it to the ASP Server, as described in
"Configuring ASP Applications" in this chapter.
However, in a shared Web hosting environment in which you are using Virtual Hosts, such as an
ISP or IPP, you do not "add" applications in this manner. Instead, the top-level, or root, directory
of each Virtual Host defined on your Web server is automatically defined as an ASP application.
You need take no further steps to enable ASP processing for the application.
Chili!Soft ASP 3.6 Product Documentation
182
There might be some situations, however, in which you want to enable or disable ASP processing
for a particular Virtual Host. You can do this by using the Chili!Soft ASP Administration
Console, as described in "Enabling ASP for a Virtual Host" in this chapter.
Users of FrontPage can also define an application as described in "Using the FrontPage 2000
Services File in a Shared Environment" in this chapter.
Using the User Configuration File
In a shared Web-hosting environment, rather than requiring the system administrator to define
each ASP application (as described in "Adding an ASP Application" in this chapter), you can
enable ASP developers to define their own ASP applications in a User Configuration file. To do
this, the system administrator must first edit the Chili!Soft ASP configuration file, casp.cnfg, so
that the ASP Server recognizes applications that are defined in the User Configuration file. Then
ASP developers can create the file and define their ASP applications within it.
To enable developers to define their own ASP applications, take the following steps. First, in the
[applications] section of the Chili!Soft ASP configuration file, casp.cnfg, specify the path
name of the User Configuration file (.aspconf) that defines the ASP applications.
[applications]
config_name=.aspconf
When you do this, the ASP Server looks for this file in the document root of the Web server and
each virtual host. For more information about editing casp.cnfg, see "Editing the Chili!Soft
Configuration File" in this chapter.
Next, create a User Configuration file. It should be a plain text file named .aspconf. Within this
file, specify the ASP application name to define as follows:
[applications]
/[appname]
where [appname] is the ASP application name. The ASP application name must be the same as
the name of the ASP application root directory, which is contained in the document root of the
virtual host.
Any applications defined in the User Configuration file are dynamically recognized, without
requiring the ASP Server to be restarted.
There are two limitations on applications defined in the User Configuration file. First, the
application directory containing the global.asa file must be directly below the top-level directory
of the Web server or virtual host document root. Second, if the User Configuration file appears in
the document root of a virtual host, then the ASP applications are applied only to that virtual host,
and not to others.
See also:
Configuring ASP Applications in this chapter
Chili!Soft ASP 3.6 Product Documentation
183
Using the FrontPage 2000 Services File in a Shared Environment
In a shared Web hosting environment, you can enable users to define new ASP applications by
using FrontPage 2000. You can use FrontPage 2000 to create new global.asa files and ASP
applications. FrontPage stores the definitions of these new applications in the FrontPage
services.cnf file in the /_vti_pvt subdirectory.
Chili!Soft ASP automatically looks for the services.cnf file in the /_vti_pvt subdirectory, and
treats the entries it finds in this file as ASP applications. Any applications defined in the
services.cnf file are dynamically recognized by Chili!Soft ASP, and do not require the ASP
Server to be restarted. Chili!Soft ASP looks for this filename in the document root directory of
the Web server (and each Virtual Host).
Entries in the services.cnf file use the following format:
/[appname] = "/path/to/app/home/directory"
If the services.cnf file and the /_vti_pvt subdirectory appear in the document root directory of a
Virtual Host, then the ASP applications are only be applied to that Virtual Host, and not to others.
There are two limitations on applications defined in the services.cnf file. First, the files in the
application must be located within the document root directory of the Web server (or Virtual
Host). Second, the directory containing the global.asa file cannot be below the top-level directory
of the Web server (or virtual host) document root. For more information about ASP applications
and the global.asa file, see "Configuring ASP Applications" in this chapter.
See also:
Adding an ASP Application in this chapter
Defining Application in a Shared Evironment in this chapter
Setting up Multi-machine Chili!Soft ASP
In some cases, you might want to run Chili!Soft ASP on more than one computer or locate your
Web server and the Chili!Soft ASP Server on separate computers. You might even want to run
your Web servers on one set of computers, and your ASP Servers on a different set of computers.
Configurations such as this are called "multi-machine Chili!Soft ASP."
Important Note
If you make any changes described in this section--such as to the Chili!Soft configuration
files--without prior authorization from Chili!Soft Customer support, you might void your
eligibility for technical support.
This section discusses the options you have for setting up multi-machine Chili!Soft ASP:
installing Chili!Soft ASP separately on each computer in the configuration and installing
Chili!Soft ASP on one computer and sharing that installation among all of the computers in the
configuration.
Notes
- You cannot configure multi-machine Chili!Soft ASP on Linux or Cobalt platforms.
Chili!Soft ASP 3.6 Product Documentation
184
- Multi-threading mode is not available for multi-machine Chili!Soft ASP. You must run
Chili!Soft ASP in multi-process mode in this configuration.
In this section:
•
Setting up Separate Installations of Chili!Soft ASP
•
Setting up a Shared Installation of Chili!Soft ASP
Setting up a Shared Installation of Chili!Soft ASP
Each computer participating in a multi-machine Chili!Soft ASP configuration (Web servers and
ASP Servers) must have identical casp.cnfg and odbc.ini files. As an alternative to installing
Chili!Soft ASP on each computer and then manually synchronizing these files, if you are using a
shared file system, you can install Chili!Soft ASP once to a location that is shared to all
computers in the configuration. Modifications you make to casp.cnfg are then picked up by all of
the computers in the installation. To complete this type of configuration, you must also relocate
several key system files to the local file system on each computer.
Important Note
If you make any of the changes described in this section--such as to the Chili!Soft
configuration files--without prior authorization from Chili!Soft Customer support, you
might void your eligibility for technical support.
Notes
- You cannot configure multi-machine Chili!Soft ASP on Linux or Cobalt platforms.
- Multi-threading mode is not available for multi-machine Chili!Soft ASP. You must run
Chili!Soft ASP in multi-process mode in this configuration.
To set up multi-machine Chili!Soft ASP using a shared installation, use the following procedure.
To set up a shared installation of multi-machine Chili!Soft ASP
1. Install Chili!Soft ASP on the computer running the Web server to configure for Chili!Soft
ASP (even if you do not plan to run the ASP Server on this computer). Do this by following
the custom installation instructions for your operating system, as provided in "Installing and
Uninstalling Chili!Soft ASP" in "Chapter 2: Installing and Configuring Chili!Soft ASP."
When prompted for an installation directory, specify a location on the file system that can be
shared among all of the computers in the configuration (for example /pub/opt/casp).
2. In a text editor, open the Chili!Soft ASP configuration file, casp.cnfg. You can find this file
in the following location:
/[C-ASP_INSTALLATION_DIRECTORY]/admin/bin
where [C-ASP_INSTALLATION_DIRECTORY] is the directory in which you installed
Chili!Soft ASP.
Chili!Soft ASP 3.6 Product Documentation
185
3. In the [machines] section of the casp.cnfg file, change the count attribute to match the
number of computers running Chili!Soft ASP, and add the IP address of each computer
running the Chili!Soft ASP Server. The following is a sample [machines] section:
[machines]
machine1=200.150.100.1
machine2=200.150.100.2
machine3=200.150.100.3
machine4=200.150.100.4
4. Certain Chili!Soft ASP system files cannot be shared by multiple running Chili!Soft ASP
engines, and must be relocated to non-shared files on each computer's local file system. For
instructions, see "Relocating the System Files for a Shared Installation" in this chapter.
5. You are now ready to start the ASP Server. To start the ASP Server in multi-machine mode,
see "Starting and Stopping Multiple Instances of the ASP Server" in this chapter.
See also:
Setting up Separate Installations of Chili!Soft ASP in this chapter
Setting up Separate Installations of Chili!Soft ASP
The easiest way to set up Chili!Soft ASP on more than one computer ("multi-machine Chili!Soft
ASP") is to install Chili!Soft ASP separately on each computer in the configuration, and then
modify the configuration files.
Important Note
If you make any of the changes described in this section--such as to the Chili!Soft
configuration files--without prior authorization from Chili!Soft Customer support, you
might void your eligibility for technical support.
Notes
- You cannot configure multi-machine Chili!Soft ASP on Linux or Cobalt platforms.
- Multi-threading mode is not available for multi-machine Chili!Soft ASP. You must run
Chili!Soft ASP in multi-process mode in this configuration.
To do set up separate installations of multi-machine ChiliSoft ASP, use the following procedure.
To set up separate installations of multi-machine Chili!Soft ASP
1. Install Chili!Soft ASP on the computer running the Web server to configure for Chili!Soft
ASP (even if you do not plan to run the ASP Server on this computer). Do this by following
the custom installation instructions for your operating system, as provided in "Installing and
Uninstalling Chili!Soft ASP" "Chapter 2: Installing and Configuring Chili!Soft ASP." Be
sure to make a note of the port number and a directory you specify for the Chili!Soft ASP
installation files.
Chili!Soft ASP 3.6 Product Documentation
186
2. Repeat step 1 for each computer running a Web server to configure for Chili!Soft ASP. Use
the same port number and installation directory that you specified in step 1.
3. In the same manner, install Chili!Soft ASP on the computer(s) that are to run the Chili!Soft
ASP Server, except when prompted to choose a Web server, select the option to not configure
a Web server. Use the same port number and directory options that you specified in step 1.
4. On any of the computers on which you installed Chili!Soft ASP, open the Chili!Soft ASP
configuration file, casp.cnfg in a text editor. You can find this file in the following location:
/[C-ASP_INSTALLATION_DIRECTORY]/admin/bin
where [C-ASP_INSTALLATION_DIRECTORY] is the directory in which you installed
Chili!Soft ASP.
5. In the [machines] section of the casp.cnfg file, change the count attribute to match the number
of computers running Chili!Soft ASP, and add the IP address of each computer running the
Chili!Soft ASP Server. For more information, see "Editing the Chili!Soft Configuration File"
in this chapter. The following is a sample [machines] section:
[machines]
machine1=200.150.100.1
machine2=200.150.100.2
machine3=200.150.100.3
machine4=200.150.100.4
portnumber=3000
logfile=/opt/casp/asp-apache-3000
mtengine=0
disablerestart=0
6. Databases that must be accessible from all of the ASP Servers must have identical DSNs
configured on each ASP Server. For each computer in the configuration, add the required
DSNs by following the instructions provided in "Adding a DSN" in this chapter. Make sure
that you use identical information on each computer.
7. You are now ready to start the ASP Server(s). To start the ASP Server in multi-machine
mode, see "Starting and Stopping Multiple Instances of the ASP Server" in this chapter.
See also:
Setting up a Shared Installation of Chili!Soft ASP in this chapter
Optimizing Server Performance
This section discusses the following features of Chili!Soft ASP that enhance its scalability and
performance:
•
Enabling Scripts Buffering
Chili!Soft ASP 3.6 Product Documentation
•
Changing the Session Timeout Value
•
Changing the Script Timeout Value
•
Enabling Script Caching
•
Running in Multi-process Mode
•
Running in Multi-threaded Mode
•
Pre-compiling ASP Pages
•
Pooling Database Connections
•
Load Balancing
187
See also:
Enabling ASP Error Logging in this chapter
Monitoring the ASP Server in this chapter
Viewing Information About the ASP Server in this chapter
Viewing Log Files in this chapter
Enabling Scripts Buffering
Chili!Soft ASP enables you to buffer ASP scripts in order to improve server performance. When
scripts buffering is enabled, the ASP Server waits until the entire ASP page is processed before
returning the results to the browser. When scripts buffering is disabled, the ASP Server returns
the HTML output for an ASP page to the browser incrementally, as soon as it is processed. For a
production server, it is best to enable scripts buffering. During development, however, you might
want to disable scripts buffering so you can more easily debug problems with your ASP pages.
To enable scripts buffering, use the following procedure.
To enable or disable scripts buffering
1. If necessary, open the Chili!Soft ASP Administration Console by using the following URL:
http://[HOSTNAME]:[PORT]
where [HOSTNAME] is the hostname of your Web server and [PORT] is the port on which
the Administration Console is running (5100 by default).
2. On the ASP tab of the Server Management page (the first page that displays when you open
the Administration Console), click Settings.
Chili!Soft ASP 3.6 Product Documentation
The Server Settings page displays.
3. In the Scripts buffering on list box, select Yes to enable scripts buffering or select No to
disable it.
188
Chili!Soft ASP 3.6 Product Documentation
189
4. Click Save, and then restart the ASP Server by clicking Restart.
Note
Restarting the ASP Server resets all Session and Application variables.
See also:
Optimizing Server Performance in this chapter
Changing the Session Timeout Value
With Chili!Soft ASP, you can specify the number of minutes that the ASP Server maintains a
user's session information since the last page request. When the user does not submit a request for
the specified length of time, the server cancels the session and discards its stored information.
Enabling the ASP Server to discard user information frees up its resources for another session.
By default, the session timeout value is 20 minutes. To change this value, use the following
procedure.
Note
A value specified for SessionTimeout in a script overrides this setting.
To change the session timeout value
1. If necessary, open the Chili!Soft ASP Administration Console by using the following URL:
http://[HOSTNAME]:[PORT]
where [HOSTNAME] is the hostname of your Web server and [PORT] is the port on which
the Administration Console is running (5100 by default).
2. On the ASP tab of the Server Management page (the first page that displays when you open
the Administration Console), click Settings.
Chili!Soft ASP 3.6 Product Documentation
The Server Settings page displays.
3. In the Session timeout box, type the number of minutes of inactivity before which a user
session times out.
190
Chili!Soft ASP 3.6 Product Documentation
191
4. Click Save, and then restart the ASP Server by clicking Restart.
Note
Restarting the ASP Server resets all Session and Application variables.
See also:
Optimizing Server Performance in this chapter
Changing the Script Timeout Value
With Chili!Soft ASP, you can specify the number of seconds that the ASP Server waits for an
ASP page to finish processing before canceling the page request. Setting a script timeout prevents
a malfunctioning ASP page from engaging server resources indefinitely. Enabling the ASP Server
to cancel a page request frees up its resources for another session.
By default, the session timeout value is 90 seconds. To change this value, use the following
procedure.
To change the script timeout value
1. If necessary, open the Chili!Soft ASP Administration Console by using the following URL:
http://[HOSTNAME]:[PORT]
where [HOSTNAME] is the hostname of your Web server and [PORT] is the port on which
the Administration Console is running (5100 by default).
2. On the ASP tab of the Server Management page (the first page that displays when you open
the Administration Console), click Settings.
The Server Settings page displays.
Chili!Soft ASP 3.6 Product Documentation
192
3. In the Script timeout box, type the number of seconds before which a script should time out.
4. Click Save, and then restart the ASP Server by clicking Restart.
Note
Restarting the ASP Server resets all Session and Application variables.
See also:
Optimizing Server Performance in this chapter
Enabling Script Caching
With Chili!Soft ASP, you can enable the ASP Server to cache ASP scripts in memory so that it
can serve ASP pagse more quickly. By default, script caching is enabled. To change this value,
use the following procedure.
To enable or disable script caching
1. If necessary, open the Chili!Soft ASP Administration Console by using the following URL:
http://[HOSTNAME]:[PORT]/
Chili!Soft ASP 3.6 Product Documentation
193
where [HOSTNAME] is the hostname of your Web server and [PORT] is the port on which
the Administration Console is running (5100 by default).
2. On the ASP tab of the Server Management page (the first page that displays when you open
the Administration Console), click Settings.
The Server Settings page displays.
Chili!Soft ASP 3.6 Product Documentation
194
3. In the Cache Scripts drop-down list box, select yes or no as desired.
4. Click Save, and then restart the ASP Server by clicking Restart.
Note
Restarting the ASP Server resets all Session and Application variables.
See also:
Optimizing Server Performance in this chapter
Choosing a Threading Mode
The Chili!Soft ASP Servercan run in one of two threading modes: multi-threaded or multiprocess. In multi-threaded mode, the ASP Server runs one process that starts multiple threads to
handle ASP page requests. In multi-process mode, the ASP Server runs one master process that
starts additional processes as needed to handle ASP requests.
You can change the mode by using the Administration Console, as described in "Running in
Multi-process Mode" and "Running in Multi-threaded Mode" in this chapter. The mode you
should choose depends on your server environment and the ASP application you are running.
This topic discusses some of the issues involved in choosing a mode.
Chili!Soft ASP 3.6 Product Documentation
195
Note
Multi-process mode is not available on Linux or Cobalt platforms.
Stability
Running Chili!Soft ASP in multi-process mode generally provides more stability than running it
in multi-threaded mode. In multi-threaded mode, a problem with one ASP page can cause
problems for all of the users accessing your site. In multi-process mode, a problem with a page or
operation affects only one Chili!Soft ASP process; the other processes continue to handle
requests normally.
Speed
ASP applications that make heavy use of the Application object perform better when running
multi-threaded mode. This is because in multi-threaded mode, the Application object is stored in
memory available to all threads of the single Chili!Soft ASP process. In multi-process mode,
accessing the Application object requires inter-process communications, which imposes a slight
performance hit.
Security
A multi-process Chili!Soft ASP Server runs under the user account inherited from the Web server
process that calls the ASP Server. Because of this, you can use file system permissions to limit
access by the ASP Server (and an ASP page) to user files, but Chili!Soft ASP configuration files
(such as odbc.ini) must be readable by all Web server users.
A multi-threaded Chili!Soft ASP server runs under the user account specified in the casp.cnfg
file. This user must have read access to all Chili!Soft ASP configuration files, as well as to all
individual ASP pages. You can limit access to Chili!Soft ASP configuration files to the specified
account under which the ASP Server runs.
Running in Multi-process Mode
As discussed in "Choosing a Threading Mode," you can select one of two basic modes in which
to run ASP Server: multi-threaded or multi-process. The mode you choose can affect the
performance of the server. Like Apache Web Server, the ASP Server provides excellent
performance in multi-process mode, and at the same time can take advantage of the stability
benefits of a multi-process architecture. Multi-process mode increases server stability because if
one process goes down, another processes can pick up the load while the failed process is
restarted.
For more information about multi-threaded mode, see "Running in Multi-threaded Mode" in this
chapter.
Note
Chili!Soft ASP 3.6 for Linux or Cobalt platforms does not support multi-process mode.
Chili!Soft ASP 3.6 Product Documentation
196
The number of simultaneous processes is 5 by default. If there are very many ASP pages that
include blocking operations (e.g., database access) it is a good idea to increase this number. Keep
in mind, however, that doing this creates more system overhead. In internal Chili!Soft testing, a
setting of 7 yielded the best performance under most circumstances.
Caution
The following procedure includes information about changing the Application variables
setting. In multi-process mode, this setting is Read-Only by default, which prevents you
from modifying, setting, or changing application-level variables once the global.asa file
has been read. If you change Application variables to Read/Write you can modify, set,
and change application-level variables; however, if you do this, the ASP Server can
become unstable under stress.
To configure Chili!Soft ASP to run in multi-process mode, use the following procedure.
Note
The last step of this procedure is to restart both the ASP Server and the Web server. Be
aware that restarting the ASP Server resets all Session and Application variables.
To configure Chili!Soft ASP to run in multi-process mode
1. If necessary, open the Chili!Soft ASP Administration Console by using the following URL:
http://[HOSTNAME]:[PORT]
where [HOSTNAME] is the hostname of your Web server and [PORT] is the port on which
the Administration Console is running (5100 by default).
2. On the ASP tab of the Server Management page (the first page that displays when you open
the Administration Console), click Settings.
The Server Settings page displays.
Chili!Soft ASP 3.6 Product Documentation
197
3. In the ASP engine mode list box, select Multi-Process.
4. In the Number of processes box, type the maximum number of processes you want to have
running at once. This number is 5 by default.
5. If necessary, in the Application variables list box select Read-Only (the default) or
Read/Write. Before changing the default value, read Caution earlier in this topic.
6. Click Save, and then click Yes to restart the Web server and ASP Server.
Note
Restarting the ASP Server resets all Session and Application variables.
Running in Multi-threaded Mode
As discussed in "Choosing a Threading Mode," you can choose one of two basic engine modes in
which to run the Chili!Soft ASP Server: multi-threaded or multi-process. The mode you choose
can affect the performance of the server. When running in multi-threaded mode, as load
increases, Chili!Soft ASP spawns new threads for servicing page requests, up to a configurable
maximum number. Multi-threaded mode can provide the best performance for certain types of
ASP applications, such as those making heavy use of the Application Object.
Chili!Soft ASP 3.6 Product Documentation
198
The number of simultaneous threads is 5 by default. If there are very many pages with blocking
operations (e.g., database access) it is a good idea to increase this number. Keep in mind,
however, that doing this creates more system overhead. A maximum number of 20 threads is
recommended.
To configure Chili!Soft ASP to run in multi-threaded mode and specify the number of threads,
use the following procedure.
Note
The last step of this procedure is to restart both the ASP Server and the Web server. Be
aware that restarting the ASP Server resets all Session and Application variables.
To configure Chili!Soft ASP to run in multi-threaded mode
1. If necessary, open the Chili!Soft ASP Administration Console by using the following URL:
http://[HOSTNAME]:[PORT]
where [HOSTNAME] is the hostname of your Web server and [PORT] is the port on which
the Administration Console is running (5100 by default).
2. On the ASP tab of the Server Management page (the first page that displays when you open
the Administration Console), click Settings.
The Server Settings page displays.
Chili!Soft ASP 3.6 Product Documentation
199
3. In the ASP engine mode list box, select Multi-Thread.
4. In the Number of threads box, type the maximum number of threads you want to have
running at once. This number is 5 by default.
5. Click Save, and then click Yes to restart the Web server and ASP Server.
For more information about multi-process mode, see "Running in Multi-process Mode" in this
chapter.
Pre-compiling ASP Pages
The Chili!Soft ASP Server automatically pre-compiles ASP pages in order to improve server
performance. When the ASP Server receives a page request, it compiles the page into bytecode
that can be more quickly processed in response to subsequent requests and saves the bytecode.
Pooling Database Connections
In terms of server resources, accessing a database is one of the most expensive operations of a
Web application. Typically, for each request, the Web application must open a connection to the
database, retrieve the data, and then close the connection. Repeatedly opening and closing the
database in this manner negatively impacts server performance.
Chili!Soft ASP 3.6 Product Documentation
200
To reduce this impact on server performance, you can configure the Chili!Soft ASP Server to
share open database connections among multiple users who are accessing the Web application.
This is called database connection pooling. With connection pooling, rather than opening and
closing a database connection for each individual request, the ASP Serveruses a connection that is
already open. Database connection pooling dramatically improves the performance of
applications that rely heavily on database operations.
To configure database connection pooling, use the procedure in "Setting the ADO Connection
Pool Size" in this chapter.
Load Balancing
Chili!Soft ASP supports various models for horizontal scalability and load balancing, including
both software- and hardware-based solutions. For example, Chili!Soft ASP can support softwarebased solutions such as round-robin DNS or load balancing software from Bright Tiger or
Microsoft. Chili!Soft ASP also can be used with hardware-based scalability and load balancing
products such as Cisco Local Director, F5 BigIP, and ArrowPoint Content Smart Switch. Each of
these products support the concept of "sticky sessions," necessary for session-based applications
to function properly. For more information, see "Chili!Soft ASP Scalability and Performance" in
"Appendix B: Chili!Soft ASP White Papers."
Advanced Administration Options
This section describes some options that advanced users can use to configure the Chili!Soft ASP
Server from the command line or by directly editing configuration files.
Important Note
If you make any of the changes described in this section--such as to the registry or
Chili!Soft configuration files--without prior authorization from Chili!Soft Customer
support, you might void your eligibility for technical support.
Most of the configuration settings described in this section are easily accessed from the
Chili!Soft ASP Administration Console. You can create serious problems with your
system by configuring your computer in the manner described in this section. It is highly
recommended that you use the Administration Console wherever possible. For more
information, see "Using the Administration Console" in this chapter.
In this section:
•
Editing the Windows NT Registry
•
Editing the Chili!Soft ASP Configuration File
•
Using the caspctrl Script
•
Defining Applications on UNIX
•
Starting and Stopping Multiple Instances of the ASP Server
•
Relocating the System Files for a Shared Installation
201
Chili!Soft ASP 3.6 Product Documentation
Editing the Windows NT Registry
Chili!Soft ASP for Windows NT stores some configuration information in the system registry.
This topic describes the registry settings Chili!Soft ASP uses. You can use regedit32 to edit these
settings, which is installed with the operating system.
Important Note
If you make any changes described in this topic, you might void your eligibility for
technical support. Most of the configuration settings described in this topic are easily
accessed from the Chili!Soft ASP Administration Console. Because you can create
serious problems with your system by configuring your computer in the manner
described in this topic, it is highly recommended that you use the Administration Console
whenever possible to manage the ASP Server, as described in "Using the Administration
Console" in this chapter.
Key
Default Value Description
AllowOutOfProcCmpnts
0 (False)
Controls whether or not Chili!Soft ASP allows Active
Server Components that do not run in the Chili!Soft ASP
process space. Out-of-process components run more
slowly than in-process components, but they are safer
because an individual component cannot bring down the
ASP Server.
AllowSessionState
1 (True)
Controls whether or not the ASP Server maintains session
state. If AllowSessionState is False, the Session object
cannot be used.
BufferingOn
0 (False)
Controls whether or not the ASP Server returns the
HTML generated from an ASP page as the page is
processed (BufferingOn = False), or processes the entire
page before returning HTML (BufferingOn = True).
BufferingOn provides slightly better performance when
set to True.
DefaultError
See Description This value controls the message returned when the ASP
Server encounters a run-time error and cannot process a
page. It appears if ShowDefaultError = True. The
default error message is: "An error occurred on the server
when processing the URL. Please contact the system
administrator."
DefaultLanguage
VBScript
This setting determines the language that the ASP Server
assumes is used in ASP pages. The other option is
JScript. Can be overridden in individual pages with an
@Language directive or <SCRIPT> block.
DefaultScriptLanguage
VBScript
This registry key is not active. See DefaultLanguage.
Enabled
1 (True)
Controls whether the ASP Server processes ASP pages. If
False, when a user requests an ASP page, the ASP Server
Chili!Soft ASP 3.6 Product Documentation
202
returns the message "Chili!Soft ASP has been disabled
and cannot process your request."
LogDirectory
See description Default value = "c:\WINNT\System32\chiliasp"
This value controls the directory where the ASP Server
writes the log file if LogToFile is True.
LogErrors
0 (False)
Determines if the ASP Server errors should be written to
the Chili!Soft ASP log file.
LogToFile
0 (False)
This registry entry is set internally by the Chili!Soft ASP
engine to control logging of debug information. Do not
modify this setting.
LogRequestErrors
0 (False)
Creates a file named errors in the directory specified by
LogDirectory.
MaxThreads
10
This value controls the maximum number of threads per
CPU that the Chili!Soft ASP engine uses to process
requests.
NumInitialThreads
2
The number of threads to start when the ASP Server
starts. This feature is not currently implemented. Use
MaxThreads instead.
Reset
00000000
Chili!Soft ASP internal setting. Do not modify this
setting.
Running
00000001
This registry entry is set internally by the Chili!Soft ASP
engine to indicate whether or not Chili!Soft ASP is
running. Do not modify this setting.
ScriptEngineCacheMax
ffffffff
This value controls the maximum number of script
engines that Chili!Soft ASP caches for servicing ASP
page requests. This feature is not completely
implemented. The default setting turns caching on, any
other setting turns caching off.
ScriptTimeout
90 Seconds
This is the amount of time the ASP Server waits for an
individual ASP page to finish processing before canceling
the request. The ScriptTimeout value can be increased in
a script, but this value sets the minimum.
SessionTimeout
20 minutes
This value controls how long the ASP Server maintains
Session values for a user without receiving a page
request. If the user is not heard from in this amount of
time, the session is canceled and its values are discarded.
SessionTimeout value can be increased in a script, but
this value is the minimum.
ShowDefaultError
0 (False)
This value controls ASP Server response to run-time
errors. If True, the ASP Server returns a message in
203
Chili!Soft ASP 3.6 Product Documentation
DefaultError when a run-time error occurs.
StartConnectionPool
1 (True)
If True, enables connection pooling when connecting to a
database.
Editing the Chili!Soft ASP Configuration File
UNIX and Linux versions of Chili!Soft ASP include a configuration file, casp.cnfg, in which you
can change Chili!Soft ASP settings. This topic describes the settings and their parameters.
Important Note
If you make any changes described in this section without prior authorization from
Chili!Soft Customer support, you might void your eligibility for technical support.
Most of the configuration settings described in this section are easily accessed from the
Chili!Soft ASP Administration Console. You can create serious problems with your
system by configuring your computer in the manner described in this section. It is highly
recommended that you use the Administration Console whenever possible, as described
in "Using the Administration Console" in this chapter.
You can find the casp.cnfg file in the following location:
/[C-ASP_INSTALL_DIR]/asp-[WEB_SERVER]-[PORT]
where [C-ASP_INSTALL_DIR] is the path name of the Chili!Soft ASP installation directory,
[WEB_SERVER] resembles apache, netscape, or zeus, and [PORT] is the ASP Server port
number (resembles 3000).
You can open casp.cnfg in any text editor, and make the changes you want. In order for the
changes to take effect, you must restart the ASP Server, as described in "Stopping and Restarting
the ASP Server" in this chapter.
The casp.cnfg file is divided into sections by keywords. The following sections describe the
keywords and parameters for each section.
[machines]
The [machines] keyword defines the computers that are running Chili!Soft ASP Servers. The
parameters specified in this section affect all Chili!Soft ASP Servers.
Parameters
count
The number of computers running the ASP Server.
machine1 … machineN
The IP address of each computer running the ASP Server. The number of entries should be the
same as the number of computers running an ASP Server.
portnumber
Chili!Soft ASP 3.6 Product Documentation
204
The base IP port to which the ASP Server control process listens. In multi-process mode, the ASP
Server uses ports portnumber through portnumber + maxprocesses (defined under
the [default computer] keyword). If you are running five server processes, you need six IP ports.
In multi-threading mode, the ASP Server uses only two ports.
logfile
Defines the name and location of the ASP Server status log file.
mtengine (1/0)
Controls multi-threading in the ASP server. If mtengine is set to 0, the ASP Server uses
multiple processes to serve ASP requests. If mtengine is set to 1, the ASP Server runs one
process with multiple threads to serve requests. Multi-process servers tend to be more stable
because an error only affects a single ASP Server process, but it might take longer to access
variables stored in the Application object. Multi-threaded servers tend to be less robust, but can
improve access time for variables stored in the Application object because all Application object
variables are stored in process space available to all threads.
disablerestart
This setting is useful for Chili!Soft ASP diagnostics. If set to 1, the Chili!Soft ASP parent process
does not automatically re-spawn Chili!Soft ASP child processes that fail.
hashobj_pid
(Optional) This setting enables you to specify the name and location of the process ID (PID) file
for the Chili!Soft ASP hash object.
[default machine]
The [default machine] keyword defines a section containing parameters that control the
operation of the ASP Server on each computer.
Parameters
license
The absolute path name of the directory containing the Chili!Soft ASP license file.
caspd_pid
(Optional) The name and location of the process ID (PID) file for the Chili!Soft ASP daemon.
maxprocesses (1 to 20)
The maximum number of ASP Server threads or processes (depending on the mtengine setting)
that are used to process pending ASP requests. The number specified can be between 1 and 20.
I/O-heavy scripts run better with more processes.
inherit_user (1/0)
This setting enables you to specify the security mode under which the ASP Server runs and can
have a serious impact on the security of your server. In particular, if you are running a Netscape
or Zeus Web server, be sure to read "Important Security Information."
Chili!Soft ASP 3.6 Product Documentation
205
The ASP Server can run with the permissions of the user defined for the Apache Web Server or
virtual host, with the permissions of a user or group defined in the casp.cnfg file, or with root
permissions. You can specify the mode as follows:
•
Inherit User Security mode. This mode, the default, is available only on Chili!Soft ASP
running with Apache Web Server. When inherit_user=1, the ASP Server runs with
("inherits") the permissions of the user defined for the Apache Web Server or virtual host
as defined in the Apache configuration file. This is the case even if a different user or
group is specified in the casp.cnfg file [default machine] section (as discussed
next).
•
Defined User Security mode. This mode is available on Chili!Soft ASP running with any
supported Web server. In this mode, the ASP Server runs with the permissions of the user
or group you specify. To run in this mode, set inherit_user=0 and then specify the
user or group in the [default machine] section of casp.cnfg, as described later.
Important Security Information
- When inherit_user=0 and no user or group is specified in the [default
machine] section of casp.cnfg, the ASP Server runs as root. This can create a security
risk for your server, so it is not recommended that you set inherit_user=0 unless
you also define a user or group for the ASP Server to run under.
- Netscape and Zeus Web servers do not support Inherit User Security mode. To protect
the security of your server, you should set inherit_user=0, and then specify a user
or group in casp.cnfg for the ASP Server to run under.
Note
On UNIX-based systems, you must run the ASP Server in multi-process mode for this
feature to work. (The ASP Server always runs in multi-process mode on Linux.)
For more information, see "Securing the Server" in this chapter.
javasupport (yes/no)
"Yes" enables Java support, required for Chili!Beans. "No," the default, disables Java support.
Because Java support can affect server performance, it is a good idea to enable it only when using
Chili!Beans.
Enablemonitoring (yes/no)
"Yes," the default, enables creation of performance counter log files, as follows:
/tmp/.casp[PORT]/chili-psm
/tmp/.casp[PORT]/.pm-chili-psm
/tmp/.pm-chili-psm
/tmp/chili-psm
These files are created with permissions that might not be appropriate in a shared Web hosting
environment. "No" disables performance monitoring and the creation of these files.
Chili!Soft ASP 3.6 Product Documentation
206
user
(Optional) The username for the account under which the ASP Server runs. Make sure that this
user has permission to open Chili!Soft ASP configuration files such as casp.cnfg and odbc.ini.
The user starting the ASP Server by using caspctrl must have root permissions. If this attribute is
not present and inherit_user=0, the ASP Server runs under the account of the user that
started the ASP Server.
Note
You must run the ASP Server in multi-threaded mode for this feature to work.
group
(Optional) The group name for the account under which the ASP Server runs. Make sure that this
group has permission to open Chili!Soft ASP configuration files such as casp.cnfg and odbc.ini.
The user starting the ASP Server using caspctrl must have greater permissions than this group. If
this attribute is not present and inherit_user=0, the ASP Server runs under the account of
the user that started the ASP Server.
Note
You must run the ASP Server in multi-threaded mode for this feature to work.
[default application]
bufferingon (yes/no)
"Yes" enables script buffering.
sessiontimeout
Amount of time in seconds that the ASP Server waits for a new page request before canceling the
session.
scripttimeout
Amount of time in seconds the ASP Server waits for an ASP page to finish processing before
canceling the request.
allowsessionstate (yes/no)
Yes enables the use of the Session object in ASP scripts.
enableparentpaths (yes/no)
No, the default, limits file system access by the FileSystemObject to the application directory
and subdirectories and disables the use of "../" syntax. Yes enables access to the file system by
the FileSystemObject outside the ASP application directory and the use of "../" syntax in
#include and Server.mapPath statements.
defaultlanguage
Specifies the default script interpreter. This value can be either vbscript or jscript.
Chili!Soft ASP 3.6 Product Documentation
207
[ado]
connectionpoolsize
The number of ADO connections to pool (reuse) to improve server performance. The default is
25. "0" disables connection pooling.
logpath
Absolute path name of the ADO errors log file. Specifying the path name enables logging. You
cannot use the name of a file that already exists in the directory.
maxLongFieldLength
Maximum long field length in bytes. By default this value is 64000. If the data you pass to a
database exceeds this limit, the ODBC driver might crash. You can increase this value as
needed.
[applications]
The [applications] keyword defines a section in which to specify information on how the ASP
Server handles ASP applications. There are several ways to define an ASP application on the
ASP Server. For more information, see "Configuring ASP Applications" in this chapter.
Parameters
use_aliases
If use_aliases=yes, then any virtual directory or alias defined in the Web server
configuration file is treated as an ASP application. If use_aliases=no, then the virtual
directories or aliases defined in the Web server configuration file are not treated as ASP
applications by the ASP Server.
/caspdoc
Absolute path name of the directory containing the Chili!Soft ASP product documentation.
/caspadmin
Absolute path name of the directory containing the admin files.
/caspsamp
Absolute path name of the directory containing the Chili!Soft ASP samples.
config_name
(Optional) This parameter enables you to specify the name of the ASP User Configuration file.
Any applications defined in this file are dynamically recognized by the ASP Server without
requiring the ASP Server to be restarted. If config_name=.aspconf, for example, the ASP
Server looks for this filename in the document root directory of the Web server. Entries in the
config_name file should use the following format:
/[appname]
There are two limitations on applications defined in the ASP User Configuration file. First, the
files in the application must be located within the document root of the Web server. Second, the
Chili!Soft ASP 3.6 Product Documentation
208
directory containing the global.asa file must not be below the top-level directory of the Web
server document root directory.
/appname
(Optional) To define an ASP application on the ASP Server, use the following format:
/[appname] = "/[path_name]" #The path name must be enclosed in
double quotes.
where [appname] is the name specified for the application and [path_name] is the absolute path
name of the directory containing the application files. If no applications are defined in the
[applications] section, then the ASP Server treats the root directory of the Web server as the
location of the "default" ASP application.
[virtual hosts]
(Optional) The [virtual hosts] keyword defines a section in which to configure the ASP
Server to work with the Virtual Hosts feature of Apache Web Server. For more information, see
"Defining Applications on UNIX" "Enabling ASP for a Virtual Host," and "Defining
Applications in a Shared Environment" in this chapter.
Parameters
allow_all
(Optional) If allow_all=no, then ASP functionality is only enabled for the Virtual Host
defined later in the [virtual hosts] section. If this attribute is omitted (or if allow_all=yes),
ASP is enabled for all of the Virtual Hosts defined in the Web server configuration file.
timeout
(Optional) If a Virtual Host has had no ASP activity for the number of minutes specified in the
timeout attribute, the ASP Server releases all of the cached ASP pages for that Virtual Host. The
ASP Server does not timeout a Virtual Host unless all of the sessions for that Virtual Host have
timed-out. If this setting is not configured, the default timeout is 60 minutes.
hostID(s)
(Optional) This setting applies only to Apache Web Server. It is a line-delimited list of hostnames
that identify which virtual hosts are allowed to handle requests for ASP pages. The hostname(s)
listed in this section should match the Virtual Hosts ServerName directive in the httpd.conf file
of the Apache Web Server. This attribute becomes active if allow_all=no. If
allow_all=no and no hostIDs are provided, ASP functionality is disabled for all Virtual
Hosts.
Using the caspctrl Script
In addition to using the Administration Console, you can manage Chili!Soft ASP by using the
caspctrl script. This topic describes how to use the script and lists the options it provides.
Chili!Soft ASP 3.6 Product Documentation
209
Important Note
If you make any changes described in this section--such as to the registry or Chili!Soft
configuration files--without prior authorization from Chili!Soft Customer support, you
might void your eligibility for technical support.
Most of the configuration settings described in this section are easily accessed from the
Chili!Soft ASP Administration Console. Because you can create serious problems with
your system by configuring your computer in the manner described in this section, it is
highly recommended that you use the Administration Console whenever possible, as
described in "Using the Administration Console" in this chapter.
To use the caspctrl script
•
From the Chili!Soft ASP installation directory, type caspctrl at the command prompt,
followed by the options you want to use. The correct format is as follows:
caspctrl (-v|version) (-vc|verbose) [](startdaemon|stopdaemon|starteng|stopeng|startall|stopall|viewlog|c
learlog|status)
The options are as follows:
•
version—reports the version of Chili!Soft ASP
•
verbose—enables the Chili!Soft ASP engines to output status messages to stdout
•
startdaemon—starts the Chili!Soft ASP Server daemon
•
stopdaemon—stops the Chili!Soft ASP Server daemon (plus any running ASP engines)
•
starteng—starts Chili!Soft ASP engine(s) on all Chili!Soft ASP computers in the
configuration with running daemons
•
stopeng—stops the Chili!Soft ASP engine(s) on all computers running Chili!Soft ASP in
the configuration with running daemons
•
startall—starts the Chili!Soft ASP daemon and engine(s) on single-computer installations
of Chili!Soft ASP
•
stopall —stops the Chili!Soft ASP daemon and engine(s) on single-computer installations
of Chili!Soft ASP
•
viewlog—enables you to view the Chili!Soft ASP Server log
•
clearlog—clears the Chili!Soft ASP Server log
•
status—reports the status of each Chili!Soft ASP Server in the configuration
Defining Applications on UNIX
This topic describes the options that are available for defining Chili!Soft ASP applications on
UNIX-based systems. Some options might not be available on Cobalt platforms.
Chili!Soft ASP 3.6 Product Documentation
210
Important Note
If you make any changes described in this section--such as to the registry or Chili!Soft
configuration files--without prior authorization from Chili!Soft Customer support, you
might void your eligibility for technical support.
Most of the configuration settings described in this section are easily accessed from the
Chili!Soft ASP Administration Console. Because you can create serious problems with
your system by configuring your computer in the manner described in this section, it is
highly recommended that you use the Administration Console whenever possible, as
described in "Using the Administration Console" in this chapter.
With Chili!Soft ASP running on a UNIX system with any supported Web server, you can define
an ASP application by using the following methods:
•
Adding an entry to the [applications] section of the Chili!Soft ASP configuration
file, casp.cnfg. For more information, see "Editing the Chili!Soft Configuration File" in
this chapter.
•
Adding an alias to the Web server configuration file (only if use_aliases=yes in the
[applications] section of casp.cnfg).
•
Adding an entry to the services.cnf file generated by FrontPage 2000, located in the
/_vti_pvt subdirectory of the Web server document root directory.
The ASP Server dynamically recognizes ASP applications that are defined in the Chili!Soft ASP
User Configuration file or the FrontPage 2000 services.cnf file. These applications must be
defined by using the application name (for example, "/appname"). An application named
/customers must correspond to a real top-level directory named customers in the Web server
document root directory. The files that make up this application must all exist within the Web
server document root directory, and the global.asa file, if present, must be located in the top-level
directory.
The ASP Server does not dynamically recognize ASP applications that are defined in the
Chili!Soft ASP configuration file, casp.cnfg or that are defined by using an alias in the Web
server configuration files. The ASP Server must be restarted in order to recognize them. ASP
applications defined in the casp.cnfg file or by creating an alias in the Web server configuration
files can include files outside of the Web server document root directory. The global.asa file, if
present, must be located in the top-level directory referenced by the ASP application.
In the event of naming conflicts between ASP applications that are defined in different
directories, the ASP Server honors application definitions in the following order:
1. Web server aliases
2. casp.cnfg file entries
3. FrontPage 2000 services.cnf file entries
4. ASP User Configuration file entries
Chili!Soft ASP 3.6 Product Documentation
211
Note
Chili!Soft ASP 3.6 for Linux and UNIX-based systems dynamically recognizes ASP
applications created by FrontPage 2000, but only if the application is not in a nested subWeb. If the application (and its associated global.asa file) is located in a directory that is
not a top-level directory of the Web server document root directory, you must define this
application using either the [applications] section of Chili!Soft ASP casp.cnfg file, or by
adding an alias to your Web server configuration. For more information, see "Editing the
Chili!Soft Configuration File" in this chapter.
Defining an Application on Netscape Web Server
For the purpose of defining Application and Session scope, the ASP Server considers all .asp files
located in a virtual directory to be part of one application. You can use the NameTrans
parameter in the obj.conf file to define an application. The following example defines an
application called "/dosperros":
NameTrans fn="pfx2dir" from="/dosperros" dir="/opt/caspnet30/caspsamp/dosperros"
If you are using the Netscape Server Administration tool, you can define an ASP application by
adding an "additional document directory."
Defining an ASP Application on Apache Web Server
For the purpose of defining Application and Session scope, the ASP Server considers all *.asp
files located in a virtual directory to be part of one ASP application. You can use the Alias
parameter in the srm.conf file (in httpd.conf for Apache 1.3.4, 1.3.6, or 1.3.9) to define an ASP
application. The following example defines an application called "/caspsamp":
Alias /caspsamp "/[C_ASP_INSTALL_DIR]/samples"
where [C-ASP_INSTALL_DIR] is the directory in which Chili!Soft ASP is installed.
If you have configured support for virtual hosts, you can define ASP applications on Apache Web
Server as follows:
•
By adding an entry to the [applications] section of casp.cnfg. This applies to the
"real host" only.
•
By adding an alias to the Web server configuration file (only if use_aliases=yes in
the [applications] section of casp.cnfg.) If the alias appears outside a
<virtualhost> ... </virtualhost> block, it applies to the "real host" only. If
the alias appears inside a <virtualhost> ... </virtualhost> block, it applies
to the virtual host.
•
By adding an entry to the ASP User Configuration file. The name of this file is defined in
the [applications] section of the casp.cnfg file. Chili!Soft ASP looks for this file in
the document root directory of each host, "real" or virtual. "Real host" entries apply to the
"real host" only.
Chili!Soft ASP 3.6 Product Documentation
•
212
By adding an entry to the services.cnf file generated by Front Page 2000. This file is
located in the /_vti_pvt subdirectory of the root directory of each host, "real" or virtual.
"Real host" entries apply to the "real host" only.
Starting and Stopping Multiple Instances of the ASP Server
With Chili!Soft ASP for Linux and UNIX-based systems, you have two distinct configuration options. In
the first type of configuration, the ASP Server and the Web server run on the same computer. In the second
type of configuration, multi-machine Chili!Soft ASP, the ASP Server and the Web server run on separate
computers, and there can be more than one ASP Server running in the configuration. This topic describes
how to start and stop the ASP Server when there is more than one instance in the configuration.
Starting and Stopping the ASP Server on a Single Computer
When Chili!Soft ASP and the Web server are running on the same computer, you can use the
Administration Console to start and stop the ASP Server, as described in "Stopping and
Restarting the ASP Server" in this chapter. You can also use the following methods to start and
stop each instance of the ASP Server individually by using the caspctrl script, which can be found
in the Chili!Soft ASP instance subdirectory:
[C-ASP_INSTALL_DIR]/asp-[server]-[port]/
where [C-ASP_INSTALL_DIR] is the directory in which Chili!Soft ASP is installed.
To start the ASP Server, use the following command:
#./caspctrl -startall
To stop the ASP Server, use the following command:
#./caspctrl -stopall
For more information about using the caspctrl script, see "Using the caspctrl Script" in this
chapter.
Note:
The startcaspd and stopcaspd commands from earlier versions of Chili!Soft ASP
are supported for backwards compatibility with any utility scripts you have created. You
should, however, replace startcaspd and stopcaspd if possible.
Starting and Stopping the ASP Server in a Multi-machine Configuration
For multi-machine Chili!Soft ASP (described in "Setting up Multi-machine Chili!Soft ASP" in
this chapter) you must use the caspctrl script to start and stop the ASP Server, which can be found
in the Chili!Soft ASP instance subdirectory (note you can start your Web server either before or
after you start the ASP Server):
[C-ASP_INSTALL_DIR]/asp-[server]-[port]/
For each computer hosting a Chili!Soft ASP engine, start the Chili!Soft ASP daemon in the
background by using the following command.:
#./caspctrl -startdaemon
Chili!Soft ASP 3.6 Product Documentation
213
You might want to add this command to the start-up script for each computer hosting a Chili!Soft
ASP engine. Next, from any machine that is participating in the configuration (whether a Web
server or ASP Server), start the Chili!Soft ASP engines by using the following command:
#./caspctrl -starteng
This starts all of the Chili!Soft ASP engines on each machine hosting Chili!Soft ASP. You do not
need to execute this command on each individual computer.
To stop all of the Chili!Soft ASP Servers in the configuration, use the following command:
#./caspctrl -stopeng
Finally, to stop the Chili!Soft ASP daemon(s) (the caspd process), use the following command
on each computer hosting the Chili!Soft ASP engine:
#./caspctrl -stopdaemon
Remember that caspctrl -startdaemon must be run on each machine before the
caspctrl -starteng script is run.
For more information about using the caspctrl script, see "Using the caspctrl Script" in this
chapter.
Important Note
If you make any changes described in this section--such as to the registry or Chili!Soft
configuration files--without prior authorization from Chili!Soft Customer support, you
might void your eligibility for technical support.
Most of the configuration settings described in this section are easily accessed from the
Chili!Soft ASP Administration Console. Because you can create serious problems with
your system by configuring your computer in the manner described in this section, it is
highly recommended that you use the Administration Console whenever possible, as
described in "Using the Administration Console" in this chapter.
Relocating the System Files for a Shared Installation
For users installing Chili!Soft ASP to shared file systems such as NFS or AFS (Andrew File
System), or who are setting up a shared, multi-machine installation of Chili!Soft ASP, use the
following instructions to relocate the system files. If you are not doing any of the above, it is
recommended that you not alter the locations of the Chili!Soft ASP system files. For more
information about multi-machine Chili!Soft ASP, see "Setting up Multi-machine Chili!Soft ASP"
in this chapter.
Important Note
If you make any changes described in this section--such as to the registry or Chili!Soft
configuration files--without prior authorization from Chili!Soft Customer support, you
might void your eligibility for technical support.
Chili!Soft ASP 3.6 Product Documentation
214
Most of the configuration settings described in this section are easily accessed from the
Chili!Soft ASP Administration Console. Because you can create serious problems with
your system by configuring your computer in the manner described in this section, it is
highly recommended that you use the Administration Console whenever possible, as
described in "Using the Administration Console" in this chapter.
Relocating the Registry File
One of the key Chili!Soft ASP system files, the registry file (registry.bin), must be located on a
local file system that supports file locking to ensure proper operation. During Chili!Soft ASP
installation, the installer creates a script named chsetup.sh in the Chili!Soft ASP installation
directory (the default is /opt/casp). Contained within this file is a line of code that resembles the
following:
MWREGISTRY=[path name]/registry.bin
where [path name] is the current location of the registry file.
To relocate the registry file, use the following procedure.
To relocate the registry file
5. Write down the current value of [path name].
6. Create the new directory where you wish to relocate the registry file. This directory must
reside on the local machine where the file system supports file locking. For the following
steps, this new directory will be referred to as <new path name>.
7. Edit chsetup.sh with a text editor such as vi and change the following line:
MWREGISTRY=[path name]/registry.bin
to
MWREGISTRY=[new path name]/registry.bin
8. Copy the registry file from its old location ([path name]/registry.bin) to its new
location (i.e., [new path name]/registry.bin).
Note
If you are setting up multi-machine Chili!Soft ASP, you need to have a separate copy of
registry.bin on each machine running Chili!Soft ASP. Also, each local file system must
have the identical local path to the location of the registry.bin file (i.e.,
/path/to/registry/file must exist on each machine.)
Relocating Chili!Soft ASP PID Files
For users who want to install Chili!Soft ASP to a shared file system, but move write-able
Chili!Soft ASP files to a local file system, Chili!Soft ASP provides a mechanism to allow for this.
For single machine Chili!Soft ASP installations, this is not required, but has the added benefit
that it may decrease network congestion. For multi-machine Chili!Soft ASP installations, the
process ID (PID) files cannot be shared by Chili!Soft ASP engines and must be relocated. For
Chili!Soft ASP 3.6 Product Documentation
215
more information about multi-machine Chili!Soft ASP, see "Setting up Multi-machine Chili!Soft
ASP" in this chapter.
There are three attributes of importance in the casp.cnfg file (which is contained under each
asp-<server>-<port> directory). These are the hashobj_pid and logfile attributes
(located in the [machines] section), and the caspd_pid attribute (located in the [default
machine] section). These attributes allow you to specify the locations of the two PID files. If
you need to relocate these files, remember these two important facts:
•
If you have several Chili!Soft ASP installations on a single physical server (with separate
asp-<server>-<port> directories), then the casp.cnfg file in each directory may
point to common directories for the PID and log files, but must point to different file
names for the PID and log files.
•
If you have a multi-machine installation of Chili!Soft ASP, then each machine that is
hosting the Chili!Soft ASP engine must have its own copy of the PID files. Because the
casp.cnfg file must be identical for each machine in a multi-machine installation, the
directories and filenames for the PID and log files specified in casp.cnfg must exist on
each machine’s local file system.
For example, suppose the [machines] and [default machine] sections of your current casp.cnfg
file resemble the following.
[machines]
count=1
machine1=127.0.0.1
portnumber=3000
logfile=/opt/casp/logs/server-3000
mtengine=0
disablerestart=0
hashobj_pid=/opt/casp/logs/asp-apache-3000/hashobj.pid
[default machine]
caspd_pid=/opt/casp/logs/asp-apache-3000/caspd.pid
maxprocesses=1
inherit_user=1
#user=nobody
#group=nobody
In this situation, to relocate all of your files off of the shared /opt directory to a /usr/local/casp
directory, use the following procedure.
To relocate all files
1. Create the destination directory(ies), for example:
Chili!Soft ASP 3.6 Product Documentation
mkdir -p /usr/local/casp/pids
mkdir -p /usr/local/casp/logs
2. Edit the casp.cnfg file to resemble the following example:
[machines]
count=1
machine1=127.0.0.1
portnumber=3000
logfile=/usr/local/casp/logs/server-3000
mtengine=0
disablerestart=0
hashobj_pid=/usr/local/casp/pids/hashobj-3000.pid
[default machine]
caspd_pid=/usr/local/casp/pids/caspd-3000.pid
maxprocesses=1
inherit_user=1
#user=nobody
#group=nobody
3. Copy the server log file and the PID files to the directories you created.
Note
If you are creating a multi-machine installation of Chili!Soft ASP, remember to copy the
log file and PID files to each machine running Chili!Soft ASP. Also, each local file
system must have the identical local path to the location of the log and PID files (i.e.
according to the above example, /usr/local/casp/logs and /usr/local/casp/pids must exist
on each machine).
216
Chili!Soft ASP 3.6 Product Documentation
217
Chapter 4: Building a Chili!Soft ASP Application
Active Server Pages (ASP) enables the Web author and developer to easily create dynamic Web
applications by using scripts that run on the Web server. An ASP page can contain a combination
of HTML text, server-side scripts, and client-side scripts, creating an engaging experience for the
Web user.
Chili!Soft ASP enables the scripting logic to interface with five built-in ASP objects, which
automatically handle many menial tasks, making application development easier. In addition to
using these basic elements, you can extend ASP by using the Component Object Model (COM).
This enables you to add sophisticated functionality by using components written in programming
languages such as C++ and Java. You can incorporate this functionality into your Web
applications by using scripts as the "glue" to link the COM objects. For example, Chili!Soft ASP
includes an ActiveX Data Object (ADO) component that provides a high-performance interface
between Web pages and databases that adhere to the Open Database Connectivity (ODBC)
standard. In addition, Chili!Beans support included with Chili!Soft ASP 3.6 enables you to use
Java objects with your ASP applications.
The first section in this chapter discusses the basics of building a Chili!Soft ASP application:
creating an ASP page, adding server-side scripts and server-side includes, and defining the
application. Next, the chapter discusses extending applications by using objects and components,
connecting to databases, and developing applications to publish in locales other than the United
States. Finally, it gives instructions for publishing a Chili!Soft ASP application.
Who should read this chapter: Web authors and developers who are new to ASP and
administrators who want a basic introduction to Chili!Soft ASP technology should read the first
section. Web authors and developers who have mastered the basics of building ASP applications
might be interested in reading the more advanced topics covered in subsequent sections.
Everyone should read the last section about publishing a Chili!Soft ASP application.
In this chapter:
•
Creating the Basic ASP Application
•
Using Chili!Soft ASP Built-in Objects
•
Using Chili!Soft ASP Installed Components
•
Connecting to a Database
•
Developing International Applications
•
Publishing a Chili!Soft ASP Application
Creating the Basic ASP Application
Chili!Soft ASP combines ASP technology with server-side object-oriented components to
provide an integrated Web development environment. A Chili!Soft ASP application consists of
the following elements:
Chili!Soft ASP 3.6 Product Documentation
•
ASP files, or pages, which are plain text files having an .asp extension. ASP pages
comprise a combination of standard HTML and scripting—written in either JScript or
Visual Basic Scripting Edition (VBScript)
•
Optional components written in any language
•
An optional global.asa file that contains global application information and session
information for individual users
218
Web servers normally send HTML files directly to the client's Web browser in response to HTTP
requests. When a browser requests an ASP page, the Web server calls the Chili!Soft ASP Server
to read through the file. The ASP Server executes the server-side scripts scripts and commands in
the page, executes any components called by the scripts, and then sends the resulting HTML page
to the browser.
This section discusses the following steps that you can take in order to create a basic ASP
application:
•
Choosing an Authoring Tool
•
Creating an ASP Page
•
Adding Scripts
•
Changing the Scripting Language
•
Using Server-side Includes
•
Defining the ASP Application
•
Using the global.asa File
When you are ready to publish your application, be sure to read "Publishing a Chili!Soft ASP
Application" in this chapter.
Once you have mastered the basics in this section you might also want to read the following
advanced topics:
•
Using Chili!Soft ASP Built-in Objects
•
Using Chili!Soft ASP Installed Components
•
Using Java Objects and Classes
•
Connecting to a Database
•
Developing International Applications
Choosing an Authoring Tool
ASP is one of the few technologies that can be used effectively for creating both sophisticated
and entry-level Web applications. Because of the flexibility of ASP, there is a wide variety of
ASP development tools available for Web developers and authors having very different skill
levels.
You can use any text editor to create *.asp files. As you progress, you may find it more
productive to use an editor that has enhanced support for ASP, such as one of the following:
219
Chili!Soft ASP 3.6 Product Documentation
Vendor/Tool
Skill Level
User Interface
Description
Microsoft
Entry- to mid-level
WYSIWYG
Microsoft’s entry-level product for
Web page creation, includes solid
ASP features.
Entry- to mid-level
WYSIWYG
Includes advanced page-creation
capabilities, mid-level ASP
capabilities.
Entry- to mid-level
WYSIWYG
Advanced page-creation capabilities,
simple ASP features.
Mid-level
WYSIWYG
Offers advanced page creation and
team-based capabilities, previews
ASP results well.
Mid-level to
advanced
Code
Editor for creating server- and clientside script. Good code validation
capabilities.
Advanced
Code
PowerSite is a sophisticated IDE for
developing data-driven Web
applications.
Advanced
Code/
Microsoft’s flagship product for
developing ASP applications.
FrontPage 2000
Macromedia
Drumbeat
NetObjects
Fusion
Macromedia
Dreamweaver
NetObjects
ScriptBuilder
Sybase
PowerSite
Microsoft
Visual InterDev
Allaire
WYSIWYG
Advanced
HomeSite
Code
Code-based editor requires advanced
HTML and ASP skills.
For more information about each of these tools, see the "Chili!Soft ASP Development Tools"
white paper in "Appendix B: Chili!Soft ASP White Papers."
The depth and breadth of ASP development tools separates ASP from the rest of the pack as a
Web application platform that meets the needs of a variety of users. Chili!Soft ASP, combined
with one or more of these development tools, gives you a common Web application platform for
applications large and small, simple or complex, for a host of popular Web servers and operating
systems, and for developers and page creators with widely varying skill levels.
Creating an ASP Page
The first step in building an ASP application is creating an ASP page. ASP pages are simply plain
text files that have an .asp filename extension. An ASP page contains optional text (usually
HTML and/or client-side scripts) interspersed with one or more ASP script blocks for
interpretation by the server.
Any valid HTML page can be a valid ASP page, enabling the Web developer to easily transform
a static Web site into a dynamic Web site by adding ASP scripts to existing HTML pages. With
Chili!Soft ASP, you can write scripts in VBScript or JScript. Saving the page with an *.asp
filename extension tells the Web server how to process the script commands.
Chili!Soft ASP 3.6 Product Documentation
220
For more information on ASP in general and Chili!Soft ASP in particular, see "Chapter 1: About
Chili!Soft ASP" and "Why Active Server Pages?" in "Appendix B: Chili!Soft ASP White
Papers."
See also:
Creating the Basic ASP Application in this chapter
Adding Scripts in this chapter
Using Server-side Includes in this chapter
Using @ Directives in this chapter
Adding Scripts
Once you have created an ASP page, as described in the previous topic, you can use a text editor
or other authoring tool to insert script commands into it. ASP pages can include both client-side
scripts, which are processed by the browser, and server-side scripts (or ASP scripts), which are
processed by the ASP Server.
ASP scripts enable you to dynamically create HTML responses based on the user's identity;
parameters in the HTTP request, and interactions with other objects, such as ASP built-in objects,
components, and databases. ASP enables you to assign values to variables, request information
from the server, or combine any set of commands into procedures.
For example, a common use of Web applications is to process a form submitted by a browser.
With ASP, you can embed scripts directly into an HTML file to process the form. The ASP
Server processes the HTML and script commands and returns the results to the browser.
Within the ASP page, you set off script blocks from other text by using delimiters. You must use
different script delimiters to distinguish between client-side and server-side scripts. You enclose
client-side scripts between the <script> and </script> tags. You enclose server-side
scripts between the delimiters <% and /%>.
You can write ASP scripts in either VBScript or JScript. The default scripting language for
Chili!Soft ASP is VBScript, but you can specify the scripting language for each ASP page. Your
system administrator can also change the default language for the ASP Server. For more
information, see "Changing the Scripting Language" in this chapter.
As the ASP Server processes each ASP script block, it creates HTML text that is returned to the
browser for rendering. Unlike client-side scripts, with server-side ASP scripts, you do not need to
be concerned about the capabilities of the browser; all processing is done at the server and only
standard HTML is returned.
Users cannot copy server-side scripts because only the output is returned to the browser.
Consequently, in order to view the results of a script you have added to an ASP page, you must
first publish the page to an ASP Server and then request the page by using a Web browser.
The following example shows how you can combine standard HTML tags with a simple script
that provides the current time of day:
<%@ LANGUAGE="VBSCRIPT" %>
Chili!Soft ASP 3.6 Product Documentation
221
<HTML>
<HEAD>
<META NAME="GENERATOR" Content="Microsoft Visual InterDev 1.0">
<META HTTP-EQUIV="Content-Type" content="text/html; charset=iso8859-1">
<TITLE>An ASP Page</TITLE>
</HEAD>
<BODY>
<The time is now <%Response.Write Now%>
</BODY>
</HTML>
Both VBScript and JScript support the If-Then-Else construct, enabling you to embed some real
logic into your HTML. The following example shows how you can set the greeting shown based
upon the time of day:
<%If Time >= #12:00:00 AM# And Time < #12:00:00 PM# Then%>
Good Morning!
<%Else%>
Hello!
<%End If%>
See also:
Creating the Basic ASP Application in this chapter
Creating an ASP Page in this chapter
Using Server-side Includes in this chapter
Using @ Directives in this chapter
Changing the Scripting Language
Chili!Soft ASP provides both VBScript and JScript script interpreters to process the commands in
an ASP script. The default scripting language is VBScript, but you can change this to JScript for
an ASP page by using the <%@ LANGUAGE> directive at the beginning of your ASP file, as
described in "Using @ Directives" in this chapter.
You can change the scripting language for a single block of script by enclosing the block in
<SCRIPT> ... </SCRIPT> tags. Normally, a block of code enclosed in <SCRIPT> tags
runs on the client side, but you can force the block to run on the server by including the
runat=server attribute, as shown in the following example:
<SCRIPT language=JScript runat=server>
Chili!Soft ASP 3.6 Product Documentation
222
Alternatively, your system administrator can change the default scripting language to either
VBScript or JScript on the ASP Server. For Windows systems, doing this is described in "Editing
the Windows NT Registry" in "Chapter 3: Managing Chili!Soft ASP." For Linux and UNIX
systems, doing this is described in "Editing the Chili!Soft Configuration File" in "Chapter 3:
Managing Chili!Soft ASP."
Using @ Directives
Chili!Soft ASP provides @ directives in addition to the available scripting commands. The
following standard ASP @ directives are available:
ENABLESESSIONSTATE. This directive turns on and off session tracking for an ASP page. If
your page does not rely on session information, turning off session tracking can decrease the time
it takes for Chili!Soft ASP to process the script. By default, sessions are enabled. For more
information, see "Managing User Sessions" in this chapter. The syntax for this directive is as
follows:
Syntax: ENABLESESSIONSTATE @ Directive
<%@ ENABLESESSIONSSTATE=True|False %>
LANGUAGE. By default, the primary scripting language for Chili!Soft ASP is VBScript, but
this can be changed to JScript for each ASP page by using the <%@ LANGUAGE> directive at the
beginning of your ASP file. The syntax and parameters are as follows:
Syntax: LANGUAGE @ Directive
<%@ LANGUAGE=scriptengine %>
Note
There must be a space between the @ and the keyword. More than one keyword can be
specified in a directive; each keyword/value pair must be separated by a space. Do not
put spaces around the equal sign (=).
Parameters: LANGUAGE @ Directive
scriptengine
The script engine that should process the script.
Note
The following standard ASP directives are not implemented by Chili!Soft ASP:
- CODEPAGE
- LCID
- TRANSACTION
Chili!Soft ASP 3.6 Product Documentation
223
For more information about configuring Chili!Soft ASP language support, see "Developing
International Applications" in this chapter.
See also:
Creating the Basic ASP Application in this chapter
Creating an ASP Page in this chapter
Using Server-side Includes in this chapter
Using Server-side Includes
You use a server-side include directive to import a file into an ASP page during processing. Any
text file can be imported, or "included." The contents of the included file are placed on the page at
the location of the server-side include directive.
You can include files that themselves contain included files. In the event of a "loop," in which the
first file contains an included file that in turn includes the first file, ASP reports an error. Included
files can also be ASP files; the results of an included ASP file are placed at the position of the
#INCLUDE statement. You cannot build a server-side include statement programmatically
because ASP processes #INCLUDE directives before processing any script.
The syntax for a server-side include is as follows:
<!--#INCLUDE VIRTUAL|FILE="filename"-->
To specify the path, use the Virtual keyword to indicate a path name beginning with a virtual
directory. Use the File keyword to indicate a relative path name that begins with the directory
containing the include file. For example, if a file were in the directory Dir1, and the file
Header1.inc is in Dir1/Headers, the following code would insert Header1.inc in your file:
<!--#INCLUDE FILE="Headers/header1.inc"-->
If the EnableParentPaths configuration setting is set to Yes, you can also use the File parameter
with ../ syntax to include a file from a parent, or higher-level, directory. By default
EnableParentPaths is set to No. In this case, the CreateObject
("Scripting.FileSystemObject") calls generated in global.asa by FrontPage do not work. Your
system administrator must either change EnableParentPaths to Yes, or else you must change the
code generated by FrontPage in the global.asa file to Server.CreateObject
("Scripting.FileSystemObject"). For more information, see "Configuring File System Access" in
"Chapter 3: Managing Chili!Soft ASP."
There is no real performance penalty for using server-side includes. ASP saves files in memory in
a compiled form after processing them. Processing only occurs the first time that a file is
accessed.
Often after you edit an "included" file, the change does not show up in your ASP page. The ASP
Server only picks up changes in an included file if it re-compiles the page that contains the
#INCLUDE directive. You can force a re-compile of this page by "touching" the file or by
making a trivial change that updates the timestamp on the file.
Within an included ASP file, script commands and procedures must be entirely contained within
the script delimiters <% and %>, the HTML tags <SCRIPT> and </SCRIPT>, or the HTML
Chili!Soft ASP 3.6 Product Documentation
224
tags <OBJECT> and </OBJECT>. That is, you cannot open a script delimiter in an included
ASP file, and then close the delimiter in the referencing file. The script or script command must
be a complete unit.
See also:
Creating the Basic ASP Application in this chapter
Creating an ASP Page in this chapter
Using @ Directives in this chapter
Defining the ASP Application
An ASP application is synonymous with a directory structure. It represents a collection of files
and virtual directories that are intended to work together to create a Web-based application. An
application is defined by flagging a directory as the application start point. The application scope
then includes all items within the directory and the sub-directories, except those that are included
in another application. Applications can include a global.asa file that contains global application
information and user session information.
In order for the Chili!Soft ASP Server to recognize and process an ASP application, your
administrator must first define the application on the server, as described in "Configuring ASP
Applications" in "Chapter 3: Managing Chili!Soft ASP."
See also:
Using the global.asa File in this chapter
Creating the Basic ASP Application in this chapter
Creating an ASP Page in this chapter
Using the global.asa File
Global.asa is an optional file that stores script procedures and objects used globally by an
application. There can only be one global.asa file per ASP application. The file must be named
global.asa and must be stored in the root directory of the application. The root directory of an
application is the top-level directory containing all of the application files and sub-directories.
The only script procedures you can declare in a global.asa are the following:
•
Application_OnStart event, as described in "Specifying Application Events" in this
chapter.
•
Application_OnEnd event, as described in "Specifying Application Events" in this
chapter.
•
Session_OnStart event, as described in "Managing User Sessions" in this chapter.
•
Session_OnEnd event, as described in "Managing User Sessions" in this chapter.
Scripts that do not have session or application scope cause the server to return an error.
Global.asa files that do not specify Application or Session events are ignored.
Script procedures declared in global.asa cannot be called from ASP pages in an application.
Chili!Soft ASP 3.6 Product Documentation
225
See also:
Saving Changes to the global.asa File in this chapter.
Specifying Application Events
An ASP application starts the first time the Web server receives a request for one of the ASP
pages contained in the application directory. The application ends when the Web server is shut
down. You can create global data for an application using the built-in ASP Application object.
You can assign variables and object instances to application variables so they are available to all
pages of an application.
When an application starts, the Application_OnStart event occurs. The Application_OnEnd
event occurs when the application shuts down. When the application starts or stops, the server
looks in the global.asa file file to find the event scripts.
ASP Application_OnStart Event
The Application_OnStart event occurs before the first session is created, before the
Session_OnStart event occurs. Only the Server and Application built-in objects are available.
Referencing the Session, Request, or Response object in the Application_OnStart event
generates an error.
Syntax: ASP Application_OnStart Event
<SCRIPT LANGUAGE=ScriptLanguage RUNAT=Server>
Sub Application_OnStart
. . .
End Sub
</SCRIPT>
Parameters: ASP Application_OnStart Event
ScriptLanguage
Specifies the scripting language used to write the event script; either VBScript or JScript. If more
than one event uses the same scripting language, the events can be enclosed within a single set of
<SCRIPT> tags.
Runat
Must be "Server."
ASP Application_OnEnd Event
The Application_OnEnd event occurs when the application ends, after the Session_OnEnd
event (see below). Only the Server and Application objects are available.
Syntax: ASP Application_OnEnd Event
<SCRIPT LANGUAGE=ScriptLanguage RUNAT=Server>
Chili!Soft ASP 3.6 Product Documentation
226
Sub Application_OnEnd
. . .
End Sub
</SCRIPT>
Parameters: ASP Application_OnEnd Event
ScriptLanguage
Specifies the scripting language used to write the event script, either VBScript or JScript. If more
than one event uses the same scripting language, the events can be enclosed within a single set of
<SCRIPT> tags.
Runat
Must be "Server."
See also:
Managing User Sessions in this chapter
Using the global.asa File in this chapter
Saving Changes to the global.asa File in this chapter
Managing User Sessions
Communication between a browser and a Web server uses the HTTP protocol. This protocol is
stateless, meaning that there is no information retained when a user goes from one page to
another. In a real-world application, it is usually necessary to retain information between pages
visited by the same user. The use of an application by a single user is called a session.
Chili!Soft ASP includes the built-in Session object for retaining session information. When a new
session starts, an instance of the Session object is created automatically. You can assign variables
and object instances to session variables so that they are available to all pages of the application
visited by the same user.
The global.asa file file can contain the following handlers for two session-level events:
Session_OnStart and Session_OnEnd, which are described later in this topic. These subroutines
are automatically executed the first time a user accesses an ASP page within the application.
Sessions exist until one of the following occurs:
•
The user closes the browser
•
The session times out (configurable by the ASP developer)
•
The session is explicitly abandoned (Session.Abandon)
Turning Session Tracking On and Off
The ENABLESESSIONSTATE @ directive turns off session tracking for a page. If your page
does not rely on session information, turning off session tracking can decrease the time it takes
for Chili!Soft ASP to process the script. By default, sessions are enabled.
Chili!Soft ASP 3.6 Product Documentation
227
Syntax
<%@ ENABLESESSIONSSTATE=True|False %>
ASP Session_OnStart Event
The Session_OnStart event occurs when the server creates a new session. The server processes
this script prior to executing the requested page. The Session_OnStart event is where when you
set any session-wide variables, they will be set before any pages are accessed. All the built-in
objects are available and can be referenced in the Session_OnStart event script.
Syntax: Session_OnStart Event
<SCRIPT LANGUAGE=ScriptLanguage RUNAT=Server>
Sub Session_OnStart
. . .
End Sub
</SCRIPT>
Parameters: Session_OnStart Event
ScriptLanguage
Specifies the scripting language used to write the event script, either VBScript or JScript. If more
than one event uses the same scripting language, the events can be enclosed within a single set of
<SCRIPT> tags.
Runat
Must be "Server."
ASP Session_OnEnd Event
The Session_OnEnd event occurs when a session is abandoned or times out. Only the
Application, Server and Session built-in objects are available.
Syntax: ASP Session_OnEnd Event
<SCRIPT LANGUAGE=ScriptLanguage RUNAT=Server>
Sub Session_OnEnd
. . .
End Sub
</SCRIPT>
Parameters: ASP Session_OnEnd Event
ScriptLanguage
Chili!Soft ASP 3.6 Product Documentation
228
Specifies the scripting language used to write the event script, either VBScript or JScript. If more
than one event uses the same scripting language, the events can be enclosed within a single set of
<SCRIPT> tags.
Runat
Must be "Server."
See also:
Specifying Application Events in this chapter
Using the global.asa File in this chapter
Saving Changes to the global.asa File in this chapter
Saving Changes to the global.asa File
When you make changes to the global.asa file file and then save them, the Chili!Soft ASP Server
reloads and compiles the file. Saving changes to a file included by the global.asa file does not
force the server to reload it, so you must force a reload by re-saving the global.asa file.
Note that the ASP Server processes all current application requests before it recompiles. During
that time, the server refuses additional requests, returning the message, "The request cannot be
processed while the application is being restarted."
See also:
Using the global.asa File in this chapter
Specifying Application Events in this chapter
Managing User Sessions in this chapter
Using Chili!Soft ASP Built-in Objects
Chili!Soft ASP includes five built-in objects—Application, Request, Response, Server, and
Session—that handle many common programming tasks. These objects enable you to avoid much
of the overhead associated with complex Web programming, so you can focus on creating
interesting, interactive Web content rather than on low-level programming.
Chili!Soft ASP objects use methods to perform some type of procedure and properties to store
object attributes (such as color, font, or size). The Request and Response objects also contain
collections (bits of information that are accessed in the same way).
For Web applications requiring more powerful programming, you can use Component Object
Model (COM) objects to process data and deliver output, with scripts acting as the "glue" to link
COM objects. Chili!Soft ASP also supports JavaBeans, Enterprise JavaBeans (EJB), and
Common Object Request Broker Architecture (CORBA) objects. For more information, see
"Component Programmer's Reference" in "Chapter 5: Developer's Reference."
This section provides a basic overview of the following built-in ASP objects included with
Chili!Soft ASP. For more information, see "ASP Built-in Objects Reference" in "Chapter 5:
Developer's Reference."
Chili!Soft ASP 3.6 Product Documentation
229
In this section:
•
ASP Application Object Overview — shares application-level information and control
settings for the lifetime of the application
•
ASP Request Object Overview — gets information from the user
•
ASP Response Object Overview — sends information to the user
•
ASP Server Object Overview — controls the Web server
•
ASP Session Object Overview — stores information about and changes settings for the
user's current session
ASP Request Object Overview
The Request object is one of the five Chili!Soft ASP built-in objects. The Request object is used
to get information from the user that is passed along in an HTTP request. Both the Request and
Response objects support the following collections:
•
QueryString—gets text,
•
Form—gets data from an HTML form
•
Cookies—gets the value of application-defined cookie
•
ServerVariables—gets HTTP information, such as the server name
See also:
Using Chili!Soft ASP Built-in Objects in this chapter
ASP Request Object in "Chapter 5: ASP Built-in Objects Reference"
ASP Response Object Overview
The Response object is one of the five Chili!Soft ASP built-in objects. The Response object is
used to send information to the user. The Response object supports only Cookies as a collection
(to set cookie values). Both the Request and Response objects support the following collections:
•
QueryString—gets text, such as a name
•
Form—gets data from an HTML form
•
Cookies—gets the value of application-defined cookie
•
ServerVariables—gets HTTP information, such as the server name
The Response object also supports a number of properties and methods. Supported properties are:
•
Buffer—buffers page output at the server. When this is set to TRUE, the server will not
send a response until all of the server scripts on the current page have been processed, or
until the Flush or End method has been called.
•
ContentType—sets the type of content (i.e., text/HTML, Excel, and so forth)
•
Expires—sets the expiration (when the data in the user's cache for this Web page is
considered invalid) based on minutes (i.e., expires in 10 minutes).
Chili!Soft ASP 3.6 Product Documentation
•
ExpiresAbsolute—enables you to set the expiration date to an absolute date and time.
•
Status—returns the status line (defined in the HTTP specification for the server).
230
Supported methods are:
•
AddHeader—adds an HTML header with a specified value
•
AppendToLog—appends a string to the end of the Web server log file
•
BinaryWrite—writes binary data (i.e., Excel spreadsheet data)
•
Clear—clears any buffered HTML output
•
End—stops processing of the script
•
Flush—sends all of the information in the buffer
•
Redirect—redirects the user to a different URL
•
Write—writes into the HTML stream. You can do this by using the construct
Response.Write("hello") or the shortcut command <%="hello"%>.
For information about using the ASP built-in objects, see "ASP Built-in Objects Reference" in
"Chapter 5: Developer's Reference."
See also:
Using Chili!Soft ASP Built-in Objects in this chapter
ASP Response Object in "Chapter 5: ASP Built-in Objects Reference"
ASP Server Object Overview
The Server object is one of the five Chili!Soft ASP built-in objects. The Server object provides
high-level access to the ASP Server. Along with the Application object, the Server object
provides ASP applications with global data—information that applies to all users of the
application. The Server object gives you programmatic control of the Web server, providing
access to HTTP services that you would otherwise need to code for each application. By using
Server object properties and methods, you can create objects, execute scripts on other ASP
pages, translate virtual path names to physical path names, and perform server-side redirects.
The Server object supports one property, ScriptTimeout, which allows you to set the value for
when the script processing will time out, and the following methods:
•
CreateObject—creates an instance of a server component. This component can be any
component that you have installed on your server (such as an ActiveX)
•
HTMLEncode—encodes the specified string in HTML
•
MapPath—maps the current virtual path to a physical directory structure. You can then
pass that path to a component that creates the specified directory or file on the server
•
URLEncode—applies URL encoding to a specified string
For information about using the ASP built-in objects, see "ASP Built-in Objects Reference" in
"Chapter 5: Developer's Reference."
Chili!Soft ASP 3.6 Product Documentation
231
See also:
Using Chili!Soft ASP Built-in Objects in this chapter
ASP Server Object in "Chapter 5: ASP Built-in Objects Reference"
ASP Session Object Overview
The Session object is one of the five Chili!Soft ASP built-in objects. The Session object is used
to store information about the current user's session. Variables stored with this object exist as
long as the user's session is active, even if more than one application is used.
This object supports one method, Abandon, which abandons the current Web-server session,
destroying any objects, and supports two properties, SessionID, containing the identifier for the
current session, and Timeout, specifying a time-out value for the session. One thing to bear in
mind is that the session identifier persists as long as the current Web-server session is running. If
you shut down the Web-server service, the identifiers restart. Therefore, it is not a good idea to
use it for creating logon IDs, because you could end up with duplicates.
For information about using the ASP built-in objects, see "ASP Built-in Objects Reference" in
"Chapter 5: Developer's Reference."
See also:
Using Chili!Soft ASP Built-in Objects in this chapter
ASP Session Object in "Chapter 5: ASP Built-in Objects Reference"
ASP Application Object Overview
The Application object is one of the five Chili!Soft ASP built-in objects. The Application object
stores information that persists for the entire lifetime of an ASP application, generally the entire
time that the Web server is running.
The Application object is a good place to store information that has to exist for more than one
user (such as a page counter). However, because a new instance of this object is not created for
each user, errors that might not show up when the code is called once might show up when it is
called many times in a row. In addition, because all users share the Application object, it can be
difficult to implement threading.
For more information about using the ASP built-in objects, see "ASP Built-in Objects Reference"
in "Chapter 5: Developer's Reference."
See also:
Using Chili!Soft ASP Built-in Objects in this chapter
ASP Application Object in "Chapter 5: ASP Built-in Objects Reference"
Using Chili!Soft ASP Installed Components
In addition to the five built-in objects described in "Using Chili!Soft ASP Built-in Objects,"
Chili!Soft ASP automatically installs a number of components that you can use to build dynamic
Chili!Soft ASP 3.6 Product Documentation
232
Web pages. The following table lists these installed components. For more information about
using them, see "ASP Component Reference" in "Chapter 5: Developer’s Reference."
Component
Description
Ad Rotator
Creates an AdRotator object that automates the rotation of
advertisement images on a Web page.
Browser Capabilities
Creates a BrowserType object that determines the type, version,
and capabilities of every browser that visits your site.
Content Linking
Creates a NextLink object that manages a list of URLs so that
you can treat the pages in your Web site like the pages in a
book.
Content Rotator
Creates a ContentRotator object that automatically rotates
HTML content strings on a Web page.
Counters
Creates a Counters object that can create, store, increment, and
retrieve any number of individual counters.
Database Access
Provides access to databases using ActiveX Data Objects
(ADO).
FileSystemObject Object
(VBScript)
Provides access to file input and output.
FileSystemObject Object
(JScript)
MyInfo
Creates a MyInfo object that keeps track of personal
information, such as the site administrator's name, address, and
display choices.
Tools
Creates a Tools object that provides utilities that enable you to
easily add sophisticated functionality to your Web pages.
Using Java Objects and Classes
Through Chili!Beans, Chili!Soft ASP provides support for Java objects and classes. Chili!Beans
is an ActiveX control that acts as a wrapper to enable Java objects to be used by Component
Object Model (COM) controllers such as ActiveX scripting engines or VBScript. Chili!Beans is
designed to work with any Java Virtual Machine (JVM) that implements the Java Native Interface
(JNI) specification, such as JDK 1.1.6 or JDK 1.2.
For more information, see "Chili!Beans Component Reference" in "Chapter 5: Developer’s
Reference."
See also:
Using Chili!Soft ASP Installed Components in this chapter
ASP Component Reference in "Chapter 5: Developer’s Reference"
Chili!Soft ASP 3.6 Product Documentation
233
Connecting to a Database
The topics in this section take you through the two basic steps required for connecting to a
database from an ASP page: first, creating a connection string and second, opening a database
connection. This section also explains how to use FrontPage database features with Chili!Soft
ASP 3.6. It also explains how to migrate a Microsoft Access database running on a Windowsbased computer to a dBase database running on a UNIX or Linux system to make it easier to use
with Chili!Soft ASP for UNIX or Linux.
A connection string provides information required by the Chili!Soft ASP Server to establish the
connection. Within a connection string, you can use one of three ways to specify information
about a database, as described later in this section: a system DSN, a DSN-less connection string,
and a file DSN.
You open a database connection by using the ADO Connection object included with Chili!Soft
ASP. You can then use other ADO objects to display and manipulate data on the ASP page. For
more information about using ADO objects, see "ADO Component Reference" in "Chapter 5:
Developer's Reference."
Note
If you are going to pass data exceeding 64,000 bytes to a database, your system
administrator should increase the maxLongFieldLength parameter for ADO, as
described in "Editing the Chili!Soft Configuration File" in "Chapter 3: Managing
Chili!Soft ASP."
In this section:
•
Creating Connection Strings
•
Opening the Database Connection
•
Using FrontPage Database Features
•
Migrating a Microsoft Access Database to dBase
Creating Connection Strings
When you want to connect to a database from an ASP page, your first step to is to create the
connection string. This provides information—in the form of parameters and their values—
required for the server to establish the connection.
Each type of database has a specific set of parameters for which you must specify values; these
are the required parameters. Some databases also provide optional parameters that you can
specify to implement special features.
Exactly what you must include in a connection string depends on the type of database and the
approach you use to specify its parameters. Chili!Soft ASP 3.6 supports the following three
approaches to specifying parameters in a connection string:
•
System DSNs. With a system DSN, all you need to provide in the connection string is the
name of the DSN that your system administrator has configured for the database on the
ASP Server. For more information, see "Using System DSNs" in this section.
Chili!Soft ASP 3.6 Product Documentation
234
•
File DSNs. A file DSN is similar to a system DSN, except the database information is
contained in a file (*.dsn) that can be stored in the root directory for a virtual host, rather
than being stored centrally by the ASP Server. File DSNs are useful in shared Web
hosting environments because a system administrator does not need to configure each file
DSN; users can configure their own. For more information, see "Using File DSNs" in this
section.
•
DSN-less connection strings. With a DSN-less connection string, you specify all of the
required database information in the connection string. For more information, see "Using
DSN-less Connection Strings" in this section.
Note about using Windows connection strings with Chili!Soft ASP for Linux or
UNIX
Connection strings must be constructed according to the requirements of the ODBC
driver being used. Chili!Soft ASP for Windows NT uses standard Windows ODBC
drivers, so connection strings you developed for Windows will work. However, the
ODBC drivers for Linux and UNIX platforms are different than for Windows, so before
you can use Windows connection strings with Chili!Soft ASP for Linux or UNIX, you
must edit them to use the syntax described in this section.
When creating file system references in ASP applications, bear in mind that Linux and
UNIX are case-sensitive operating systems. Be sure to use the correct capitalization in all
references to files and directories.
Ask your server administrator which one of these approaches to use in your particular Web server
environment.
Once you have created the connection string in your ASP page, you can add the code needed to
open a database connection, as described next, in "Opening the Database Connection."
Note
Chili!Soft ASP 3.6 installs the ODBC drivers to support a number of databases, but it
does not support all databases on all platforms. You can view the list of installed drivers
in the Installation Requirements topic for your platform in "Installing and Uninstalling
Chili!Soft ASP" in "Chapter 2: Installing and Configuring Chili!Soft ASP."
Using System DSNs
As discussed in "Creating Connection Strings" in this section, using a system DSN is one way to
specify database information in a connection string.
Before you can use a system DSN in a connection string, your administrator must first add it to
the ASP Server, as described in "Adding a DSN" in "Chapter 3: Managing Chili!Soft ASP." This
saves information on the ASP Server about all of the parameters required for connecting to the
database.
Chili!Soft ASP 3.6 Product Documentation
235
Note
Chili!Soft ASP 3.6 installs the ODBC drivers for a number of databases, but it does not
support all databases on all platforms. You can view the list of installed drivers in the
Installation Requirements topic for your platform in the "Installing and Uninstalling
Chili!Soft ASP" section of "Chapter 2: Installing and Configuring Chili!Soft ASP."
Once a system DSN is configured, rather than needing to specify all of the database information
in the connection string as you do with DSN-less connection strings, you can simply reference the
system DSN name. When you do this, the ASP Server uses the information stored in the system
DSN to establish the connection.
Often, all you need to provide in the connection string is the name of the DSN that your system
administrator has configured for the database. In this case, use the following syntax:
connect_string = "dsn=[dsn_name]"
where [dsn_name] is the name your system administrator defined for the DSN.
However, if the username and password required for connecting to the database are not specified
in the system DSN, you must include them in the connection string. Ask your database
administrator for this information. Be sure to use the correct syntax for your type of database, as
follows:
connect_string = "dsn=[dsn_name]; UID=[username]; PWD=[password]"
Note
dBase does not require a username and password.
If your system administrator asks you to use file DSNs or DSN-less connection strings rather than
system DSNs, see "Using File DSNs" and "Using DSN-less Connection Strings" in this chapter.
However, you must use system DSNs for connecting to DB2, Interbase, Microsoft Access, and
Microsoft SQL Server 6.5 databases. You cannot use DSN-less connection strings or file DSNs
for connecting to these databases.
See also:
Connecting to a Database in this chapter
Using FrontPage Database Features in this chapter
Using DSN-less Connection Strings
As discussed in "Creating Connection Strings" in this section, using a DSN-less connection string
is one way to specify the information—in the form of parameters and their values—needed for
establishing a database connection. Unlike system DSN and file DSNs, which incorporate this
information by reference, DSN-less connection strings include all of the required database
parameters.
You use the following syntax for a connection string:
connect_string = "[parameter_1=value_1; parameter_2=value_2;
parameter_3=value_3]"
Chili!Soft ASP 3.6 Product Documentation
236
where [parameter_1=value1; parameter_2=value_2;
parameter_3=value_3] specifies the required parameters for the given database.
The following example shows a DSN-less connection string for a MySQL database:
connect_string = "Driver={Mysql}; Server=[server_name];
Database=[database_name]; UID=[username]; PWD=[password]"
where [server_name] is the name of the database server, [database_name] is the name
of the database, and [username] and [password] are the username and password required
for accessing the database.
Different types of databases can require that you specify different parameters. The parameters to
configure for each database in a DSN-less connection string are provided in "Syntax for DSN-less
Connection Strings" in this section.
Note about using Windows connection strings with Chili!Soft ASP for Linux or
UNIX
Connection strings must be constructed according to the requirements of the ODBC
driver being used. Chili!Soft ASP for Windows NT uses standard Windows ODBC
drivers, so connection strings you developed for Windows will work. However, the
ODBC drivers for Linux and UNIX platforms are different than for Windows, so before
you can use Windows connection strings with Chili!Soft ASP for Linux or UNIX, you
must edit them to use the syntax described in this section.
Note about supported databases
- With Chili!Soft ASP for Linux or UNIX, you cannot use DSN-less connection strings
or file DSNs for connecting to DB2, Interbase, Microsoft Access, or Microsoft SQL
Server 6.5 databases; you must use system DSNs for connecting to these databases.
- With Chili!Soft ASP for Linux or UNIX, before you can reference a Microsoft SQL
Server 7.0 database in a DSN-less connection string or a file DSN, your system
administrator must take the steps described in "Editing the Microsoft SQL Server
Template" in "Chapter 3: Managing Chili!Soft ASP."
- Chili!Soft ASP 3.6 installs the ODBC drivers for a number of databases, but it does not
support all databases on all platforms. You can view the list of installed drivers in the
Installation Requirements topic for your platform in the "Installing and Uninstalling
Chili!Soft ASP" section of "Chapter 2: Installing and Configuring Chili!Soft ASP."
See also:
Connecting to a Database in this chapter
Creating Connection Stringsin this chapter
Syntax for DSN-less Connection Strings
The following table lists the parameters to define and the syntax to use for each type of database
in DSN-less connection strings.
Chili!Soft ASP 3.6 Product Documentation
237
Database Type
Syntax for DSN-less Connection Strings
DB2
DSN-less connection strings are not supported for DB2 databases. You
must use system DSNs.
dBase 5
connect_string = "Driver={Dbase}; DBQ=[pathname];
defaultDir=[default_directory]"
where [pathname] is the absolute path name of the directory containing
the database file and [default_directory] is the default directory
for the database.
Informix 7, 9
connect_string = "Driver={Informix};
Server=[server_name]; Database=[database_name];
UID=[username]; PWD=[password]"
where [server_name] is the name of the database server,
[database_name] is the name of the database, and [username]
and [password] are the username and password required for accessing
the database.
Microsoft Access
DSN-less connection strings and file DSNs are not supported for Microsoft
Access databases. You must use system DSNs.
Microsoft SQL Server
6.5
DSN-less connection strings and file DSNs are not supported for Microsoft
SQL Server 6.5 databases. You must use system DSNs.
Microsoft SQL Server
7.0
connect_string = "Driver={SQL Server};
Database=[database_name]; UID=[username];
PWD=[password]"
where [database_name] is the name of the database, and where
[username] and [password] are the username and password
required for accessing the database. Note that before you can reference a
Microsoft SQL Server 7.0 database in a DSN-less connection string or a
file DSN, your system administrator must take the steps described in
"Editing the Microsoft SQL Server Template" in "Chapter 3: Managing
Chili!Soft ASP."
MySQL
connect_string = "Driver={Mysql};
Server=[server_name]; Database=[database_name];
UID=[username]; PWD=[password]"
where [server_name] is the name of the database server,
[database_name] is the name of the database, and [username] and
[password] are the username and password required for accessing the
database.
Oracle 7
connect_string = " Driver={Oracle7};
Server=[TNS_name]; UID=[username]; PWD=[password]"
where [TNS_name] is the TNS name as defined in the tnsnames.ora file,
and [username] and [password] are the username and password
Chili!Soft ASP 3.6 Product Documentation
238
required for accessing the database.
Oracle 8, 8i
connect_string = " Driver={Oracle8};
Server=[TNS_name]; UID=[username]; PWD=[password]"
where [TNS_name] is the TNS name as defined in the tnsnames.ora file,
and [username] and [password] are the username and password
required for accessing the database.
PostgreSQL
connect_string = " Driver={Postgres};
Server=[server_name] UID=[username]; PWD=[password]"
where [server_name] is the name of the database server,
[username] and [password] are the username and password
required for accessing the database.
Sybase 11
connect_string = " Driver={Sybase};
Server=[server_name]; Database=[database_name];
UID=[username]; PWD=[password]"
where [server_name] is the name of the database server,
[database_name] is the name of the database, and [username] and
[password] are the username and password required for accessing the
database.
See also:
Using DSN-less Connection Strings in this chapter
Using File DSNs
As discussed in "Creating Connection Strings" in this section, using file DSNs is one way to
specify the information needed for establishing a connection to a database from an ASP
application. This topic explains how to create a file DSN and reference it from within a
connection string.
When you have a number of connection strings referencing the same database, file DSNs can be
quicker to implement than DSN-less connection strings. File DSNs can also make ASP
applications easier to port from the development environment to the production server because
you can edit the database information in a single file, rather than needing to edit multiple
connection strings.
To use file DSNs, the first step is to create a file containing the required parameters and values
for the database with which you want to connect. Then you simply reference the file from within
the connection string, rather than duplicating the database information each time.
To create a file DSN, open a plain text file and specify the parameters for the database to which
you want to connect by using the following general syntax:
[ODBC]
a=b
c=d
Chili!Soft ASP 3.6 Product Documentation
239
e=f
where a=b, c=d, and e=f are the key-value pairs that define the database parameters and their
values. One of the key-value pairs must specify the name of the ODBC driver for the database.
The parameters you must configure for each database are provided in "Parameters for File DSNs"
in this section.
Note about using Windows file DSNs with Chili!Soft ASP for Linux or UNIX
File DSNs and connection strings must be constructed according to the requirements of
the ODBC driver being used. On Windows NT, Chili!Soft ASP uses the same ODBC
drivers as Microsoft ASP, so you do not need to change any file DSNs or connection
strings in order to use them. However, the ODBC drivers available for Linux and UNIX
are different than for Windows. In order to connect to a database from an ASP
application that you developed for Windows on Chili!Soft ASP for Linux or UNIX, you
must edit your file DSNs and connection strings to use the syntax described in this topic.
Also, when porting file DSNs to Linux or UNIX systems, be sure to remove the "controlM" characters that Windows inserts at the end of each line.
The following example shows a file DSN for a Sybase 11 database:
[ODBC]
Driver={Sybase}
Server=Sun
DB=MyDatabase
UID=John
PWD=Some.Password
When finished defining parameters, give the file a DSN filename extension (*.dsn) and save it in
the document root of your Web server or virtual host.
Once you have created the file DSN, you can refer to it from within a connection string. The
syntax to use is as follows:
connect_string = "FileDSN=[MyFileDSN.dsn]"
- or connect_string = "File_Name=[MyFileDSN.dsn]"
where [MyFileDSN.dsn] is the absolute path name of the file DSN (*.dsn) containing the
database parameters and values.
In a shared Web hosting environment, such as an ISP, you might not know the directory structure
above the document root for your virtual host. In this situation, you cannot specify the absolute
path name of the file DSN, so you must use the Server.mapPath directive instead. The following
example uses a file DSN that is stored in the document root of the virtual host:
dim myConnFile,connection_string
myConnFile = Server.mapPath("/") & "/" & "MyFileDSN.dsn"
Chili!Soft ASP 3.6 Product Documentation
240
connect_string = "FileDSN=" & myConnFile
Note about supported databases
Chili!Soft ASP 3.6 installs the ODBC drivers for a number of databases, but it does not
support all databases on all platforms. You can view the list of installed drivers in the
Installation Requirements topic for your platform in the "Installing and Uninstalling
Chili!Soft ASP" section of "Chapter 2: Installing and Configuring Chili!Soft ASP."
Note about DB2, Microsoft Access, and Microsoft SQL Server databases
- You cannot use DSN-less connection strings or file DSNs for connecting to DB2,
Interbase, Microsoft Access, or Microsoft SQL Server 6.5 databases from Chili!Soft ASP
for Linux or UNIX; you must use system DSNs.
- With Chili!Soft ASP for Linux or UNIX, before you can reference a Microsoft SQL
Server 7.0 database in a DSN-less connection string or a file DSN, your system
administrator must take the steps described in "Editing the Microsoft SQL Server
Template" in "Chapter 3: Managing Chili!Soft ASP."
See also:
Connecting to a Database in this chapter
Creating Connection Strings in this chapter
Using System DSNs in this chapter
Using FrontPage Database Features in this chapter
Parameters for File DSNs
The following table lists the parameters you must define in a file DSN for each type of database.
In each case, use the driver name for your database that is provided in the table.
Database Type
Parameters
DB2
File DSNs are not supported for DB2 databases. You must use system
DSNs.
dBase 5
Driver={Dbase}
DBQ=[pathname]
defaultDir=[default_directory]
where [pathname] is the absolute path name of the directory containing
the database file and [default_directory] is the default directory
for the database.
Informix 7, 9
Driver={Informix}
Server=[server_name]
Database=[database_name]
Chili!Soft ASP 3.6 Product Documentation
241
UID=[username]
PWD=[password]
where [server_name] is the name of the database server,
[database_name] is the name of the database, and [username]
and [password] are the username and password required for accessing
the database.
Microsoft Access
DSN-less connection strings and file DSNs are not supported for Microsoft
Access databases. You must use system DSNs.
Microsoft SQL Server
6.5
DSN-less connection strings and file DSNs are not supported for Microsoft
SQL Server 6.5 databases. You must use system DSNs.
Microsoft SQL Server
7.0
Driver={SQL Server}
Database=[database_name]
UID=[username]
PWD=[password]
where [database_name] is the name of the database, and where
[username] and [password] are the username and password
required for accessing the database. Note that before you can reference a
Microsoft SQL Server 7.0 database in a DSN-less connection string or a
file DSN, your system administrator must take the steps described in
"Editing the Microsoft SQL Server Template" in "Chapter 3: Managing
Chili!Soft ASP."
MySQL
Driver={Mysql}
Server=[server_name]
Database=[database_name]
UID=[username]
PWD=[password]
where [server_name] is the name of the database server,
[database_name] is the name of the database, and [username] and
[password] are the username and password required for accessing the
database.
Oracle 7
Driver={Oracle7}
Server=[TNS_name]
UID=[username]
PWD=[password]
where [TNS_name] is the TNS name as defined in the tnsnames.ora file,
and [username] and [password] are the username and password
required for accessing the database.
Chili!Soft ASP 3.6 Product Documentation
Oracle 8, 8i
242
Driver={Oracle8}
Server=[TNS_name]
UID=[username]
PWD=[password]
where [TNS_name] is the TNS name as defined in the tnsnames.ora file,
and [username] and [password] are the username and password
required for accessing the database.
PostgreSQL
Driver={Postgres}
Server=[server_name]
UID=[username]
PWD=[password]
where [server_name] is the name of the database server, and
[username] and [password] are the username and password
required for accessing the database.
Sybase 11
Driver={Sybase}
Server=[server_name]
Database=[database_name]
UID=[username]
PWD=[password]
where [server_name] is the name of the database server,
[database_name] is the name of the database, and [username] and
[password] are the username and password required for accessing the
database.
See also:
Using File DSNs in this chapter
Opening the Database Connection
Chili!Soft ASP 3.6 includes an ActiveX Data Object (ADO) control that developers can use for
initializing connections to databases and for retrieving and manipulating data on a Web page. The
ADO Connection object opens and closes database connections by using ODBC drivers. Other
ADO objects act as containers for storing information that is passed to and from the database. The
most common container is a Recordset object, which stores the results of a SELECT SQL query.
The topic, "Creating Connection Strings," explains the first step to take to connect an ASP page
to a database. After creating the connection string, your next step is to use the ADO control
included with Chili!Soft ASP 3.6 to open a database connection, as described in this topic.
Chili!Soft ASP 3.6 Product Documentation
243
Note
Chili!Soft ASP 3.6 installs the ODBC drivers for a number of databases, but it does not
support all databases on all platforms. You can view the list of installed drivers in the
Installation Requirements topic for your platform in the "Installing and Uninstalling
Chili!Soft ASP" section of "Chapter 2: Installing and Configuring Chili!Soft ASP." It is
also a good idea to ask your system administrator to verify that the ODBC driver for your
database is functioning correctly.
To open a database connection, you first add code for creating an instance of the ADO
Connection object, as shown in the following example:
set dbConn = server.createObject("ADODB.connection")
Next, you add code to call the Connection object Open method, which takes the connect_string
parameter, as shown in the next example:
dbConn.open connect_string
This sends a request to the ODBC Manager to create an instance of the ODBC driver specified by
the connection string that you previously created. ADO then passes the remainder of the
connection string to the ODBC driver, which uses this information for connecting to the database.
Once you have established the connection, you can use the other ADO objects to retrieve, display,
and manipulate data on your Web page, as described in "ADO Component Reference" in
"Chapter 5: Developer's Reference."
If you want, you can also use FrontPage 2000 for creating connection strings and displaying data
on a Web page, as described in "Using FrontPage Database Features" in this chapter.
Note
Chili!Soft ASP 3.6 includes the ODBC drivers required to connect to a number of
different databases. Before you create a database connection, it is recommended that you
ask your system administrator to verify that the appropriate ODBC driver for your
database is configured and functioning properly. It is a good idea to test the driver on a
non-production server because a malfunctioning ODBC driver can bring down your ASP
Server.
See also:
Connecting to a Database in this chapter.
Using FrontPage Database Features
This section describes Chili!Soft ASP support for the database connectivity features of FrontPage
2000.
In this section:
•
Using FrontPage Database Connections
•
Displaying Data on a Web Page With FrontPage
Chili!Soft ASP 3.6 Product Documentation
244
Using FrontPage Database Connections
In order to create a database connection in FrontPage, you enter information about the database,
such as its name, ODBC driver, username, and password. FrontPage then writes this information
to the global.asa file as a connection string. Chili!Soft ASP for Windows NT directly supports
FrontPage Database Connections.
However, connection strings must be constructed according to the ODBC driver being used, and
the ODBC drivers are different on UNIX and Linux than on Windows. For this reason, before
you can use Windows connections with Chili!Soft ASP for Linux or UNIX, you must first edit
them so they use the syntax described in " Creating Connection Strings" in this chapter.
In addition, when you use DB2, Microsoft SQL Server 6.5 and Microsoft Access databases with
Chili!Soft ASP for UNIX or Linux, you must use system DSNs in connection strings; you cannot
use DSN-less connection strings or file DSNs. For you to use a system DSN for connecting to a
particular database, your administrator must create a DSN for the database on the ASP Server. In
addition, for SQL Server 6.5 and Access, your system administrator must configure SequeLink,
as described in "Configuring SequeLink" in "Chapter 3: Managing Chili!Soft ASP."
When you are using Chili!Soft ASP for Linux or UNIX, you might want to consider migrating
your Microsoft Access databases to dBase as described in "Migrating an Access Database to
dBase" in this chapter. dBase is relatively easy to learn and use and eliminates some of the
platform-compatibility problems you might otherwise experience.
For Microsoft SQL Server 7.0 databases, in addition to system DSNs, you can also use DSN-less
connection strings and file DSNs. To enable DSN-less connection strings and file DSNs, your
system administrator must edit the Microsoft SQL Server template, as described in "Editing the
Microsoft SQL Server Template" in "Chapter 3: Managing Chili!Soft ASP." You should verify
that your connection strings follow the syntax described in "Creating Connection Strings" in this
chapter.
For all other databases supported by Chili!Soft ASP, you can use system DSNs, file DSNs, and
DSN-less connection strings.
See also:
Using FrontPage Database Features in this chapter
Connecting to a Database in this chapter
Displaying Data on a Web Page With FrontPage
With Chili!Soft ASP, FrontPage developers can continue using the FrontPage features for
connecting to a database and displaying its information on an ASP page. Chili!Soft ASP 3.6
supports all of the methods for displaying database data that are generated by the FrontPage
Database Results Wizard, including:
•
Table format
•
List format
•
Drop-down menu format
Chili!Soft ASP 3.6 Product Documentation
245
By using the Database Results Wizard, developers can easily present the most recent data each
time a user views and refreshes a page. Chili!Soft ASP 3.6 also supports the FrontPage "Send To
Database" HTML form handler feature, as well as the Recordset navigation toolbar generated by
the Database Results Wizard for moving quickly through the pages of records returned by a
query.
Important
When using the FrontPage 2000 Database Results Wizard, you must first create the ASP
pages locally on your workstation, and then publish them on the server running the ASP
Server and FrontPage 2000 Server Extensions. After moving the ASP pages, you can
later use FrontPage 2000 to edit them on the server. Note that you must change the
connection strings created by FrontPage in order for them to work with Chili!Soft ASP
3.6 for Linux or UNIX. For more information, see "Using FrontPage Database
Connections" in this section.
See also:
Using FrontPage Database Connectionsin this chapter
Connecting to a Database in this chapter
Migrating a Microsoft Access Database to dBase
Microsoft Access databases are compatible with Chili!Soft ASP running on Windows NT, but
these databases do not run on Linux or UNIX systems. You have two options for connecting to a
Microsoft Access database with Chili!Soft ASP for Linux or UNIX.
First, you can use SequeLink. The necessary steps for creating the connection string are described
in "Creating Connection Strings" in this chapter. The steps the system administrator must take are
described in "Configuring SequeLink" in "Chapter 3: Managing Chili!Soft ASP."
Alternatively, if you use FrontPage, you can easily migrate your Microsoft Access database to
dBase by using the Microsoft Access Export Table feature. You can then import the resulting
folder of files to your FrontPage Web and use the Database Results Wizard. The dBase database
management system is relatively easy to learn and use.
If you have moved a dBase-based Web application to UNIX and then find that Chili!Soft ASP
cannot open the database, make sure that file extension of your dBase files are in all capital letters
(i.e., *.DBF).
Note
dBase databases do not support multi-table joins on UNIX.
See also:
Connecting to a Database in this chapter
Using FrontPage Database Featuresin this chapter
Chili!Soft ASP 3.6 Product Documentation
246
Developing International Applications
By default, the Chili!Soft ASP Server displays content in United States (US) English and uses US
date, time, and currency formats. If you want to deliver ASP applications in locales and languages
other than US English, your administrator can change the locale specified for the ASP Server, as
described in "Configuring International Support" in "Chapter 3: Managing Chili!Soft ASP." This
ensures that the characters in the specified language display properly and that date, time, and
currency formats are correct. Ask your administrator which locales are available.
Regardless of the locale for which your server is configured, you can dynamically change how
certain content—such as date, time, and currency—is formatted so that it is appropriate for a
given locale. You can do this from within an ASP page by changing the value of the
Session.LCID property.
The following example shows how to display the current date first in German and then in English
by using the Session.LCID property:
<%
Session.LCID = &H0407 ' specify Germany/German
Response.Write FormatDateTime( Date, vbLongDate ) & "<BR>" &
vbNewLine
Session.LCID = &H0409 ' specify USA/English
Response.Write FormatDateTime( Date, vbLongDate ) & "<BR>" &
vbNewLine
%>
Although you can dynamically change locales via Session.LCID, you can not effectively change
code pages in this release of Chili!Soft ASP by using Session.CodePage. This means that any
characters that are not supported by the CODEPAGE specified for the ASP Server locale are not
reproduced correctly. The major exception to this is characters falling within the normal ASCII
range (0x00 to 0x7E), in which the graphical representations are the same in all languages for
almost all characters. (The rare exceptions include the 0x5C character, which displays as a
backslash in English but as a Yen symbol in Japanese.)
Notes about Japanese character support
- Chili!Soft ASP 3.6 supports only the Shift-JIS encoding of Japanese characters and does
not support "extended" or "user-defined" characters. Please note that this applies to all
Japanese usage in ASP pages, including literal strings in the source files, text stored to
files via the Scripting.FileSystemObject, text stored to databases via the various
ADODB objects and methods, and so forth. Similarly, all output from ASP to browsers is
in Shift-JIS only.
- If a field is created as VarChar(nn) or Char(nn) then nn actually represents the
number of bytes of data that can be stored in that field. Since the majority of Shift-JIS
characters occupy two bytes of memory, fields should be specified with a size that is
twice the maximum number of Shift-JIS characters that they need to hold.
Chili!Soft ASP 3.6 Product Documentation
247
Note about DB2 and locale
You must connect to a DB2 database that was created in the same locale in which the
Web server and the Chili!Soft ASP Server are running. If you do not, upon attempting to
make the database connection from an ASP page, you might receive the following error
message:
"There is no available conversion for the source code page "932" to the target code page
"1252". Reason Code "1". SQLSTATE=57017"
To address this problem, create and connect to a database that is in the appropriate locale.
See also:
Understanding Code Pages in this chapter.
Understanding Code Pages
When you are building an ASP application that must support non-US-English users, it must
support character set conversions. Internally, ASP and the language engine it calls—VBScript or
JScript—speak in Unicode strings. However, Web page content can be in ANSI, DBCS, or
another character-encoding scheme. Therefore, when an HTTP request from a browser includes
either form or query string values, they must be converted from the character set used by the
browser into Unicode for processing by an ASP script. These conversions map characters from
one code page—which is a set of characters organized in some scheme, such as ANSI—to
another. For example, the value that refers to the letter "a" in ANSI is converted to the different
value that refers to that same letter "a" in Unicode. Similarly, when output is sent back to the
browser, any strings returned by scripts must be converted from Unicode back to the code page
used by the client.
These internal conversions are done using the default code page of the Web server. This works
great if the users and the server are all speaking the same language (more precisely, if they use
the same code page). However, if for example, you have a Japanese client hitting an English
server, the code page translations do not work because ASP treats Japanese characters as English
ones.
See also:
Developing International Applications in this chapter.
Publishing a Chili!Soft ASP Application
To publish an ASP application, simply save the application files in the directory defined for that
application on your Web server (be sure that the directory has either Script or Execute
permission enabled). Your administrator can set up the ASP application directory on the server by
using the procedure in "Adding an ASP Application" in "Chapter 3: Managing Chili!Soft ASP."
For more information about how ASP applications are structured, see "Creating the Basic ASP
Application" in this chapter.
To verify that an ASP page is displaying properly, you can request the page with your browser by
typing its URL. (Remember, ASP pages must be served, so you cannot request an *.asp file by
Chili!Soft ASP 3.6 Product Documentation
248
typing in its physical path.) After the page loads in your browser, you will notice that the server
has returned an HTML page. This may seem strange at first, but remember that the ASP Server
parses and executes all server-side scripts prior to sending the file. The user always receives
standard HTML.
Note
When publishing ASP pages created in FrontPage, be aware that if the
EnableParentPaths configuration setting is No, the default, CreateObject
("Scripting.FileSystemObject") calls generated in the global.asa file file by FrontPage
will not work. Your system administrator must either change EnableParentPaths to Yes,
or else you must change the code that FrontPage generated in the global.asa file to
Server.CreateObject ("Scripting.FileSystemObject"). For more information, see
"Configuring File System Access" in "Chapter 3: Managing Chili!Soft ASP."
Chili!Soft ASP 3.6 Product Documentation
Chapter 5: Developer's Reference
This chapter contains the following reference information for ASP developers:
•
ADO Component Reference
•
ASP Built-in Objects Reference
•
ASP Component Reference
•
Chili!Beans Component Reference
•
Component Programmer's Reference
•
JScript Language Reference
•
SpicePack Component Reference
•
VBScript Language Reference
249
Chili!Soft ASP 3.6 Product Documentation
250
ADO Component Reference
Chili!Soft ASP includes ActiveX Data Objects (ADO) for connecting ASP applications to
databases. ADO is a set of objects that provide a mechanism to access information from ODBCcompliant data sources.
This section provides the following ADO reference information:
•
ADO Overview
•
ADO Objects
•
ADO Command Object
•
ADO Connection Object
•
ADO Error Object
•
ADO Field Object
•
ADO Parameter Object
•
ADO Property Object
•
ADO Recordset Object
•
ADO Collections
ADO Overview
The implementation of ADO used with Chili!Soft ASP is called ADODB. ADO enables client
applications to access and manipulate data in a database server from a variety of different vendors
in the same manner. With ADO, data is updated and retrieved using a variety of existing methods
(including SQL). In the context of ASP, using ADO typically involves writing script procedures
that interact with a database and use HTML to display information from data sources.
In ADO, the Recordset object is the main interface to data. An example of the minimal VBScript
code to generate a recordset from an ODBC data source is as follows:
set rstMain = CreateObject("ADODB.Recordset")
rstMain.Open "SELECT * FROM authors", _
"DATABASE=pubs;UID=sa;PWD=;DSN=Publishers"
This generates a forward-only, read-only Recordset object useful for scanning data. A slightly
more functional recordset can be generated as follows:
set rstMain = CreateObject("ADODB.Recordset")
rstMain.Open "SELECT * FROM authors", _
"DATABASE=pubs;UID=sa;PWD=;DSN=Publishers",
adOpenKeyset, adLockOptimistic
This creates a fully scrollable and updateable recordset.
Chili!Soft ASP 3.6 Product Documentation
251
Note
Adovbs.inc & Adojavas.inc. For applications that use VBScript (for example, Active
Server Pages), you must include the Adovbs.inc file in your code in order to call ADO
constants by name (use Adojavas.inc for JScript). Always refer to constants by name
rather than by value since the values may change from one version to the next.
Note
Updatable Cursor support. Microsoft and Chili!Soft use the Positioned Update and
Positioned SQL features of ODBC to implement the AddNew, Update and Delete
methods of the ADO Recordset Object . For some of the supplied ODBC drivers these
features are not implemented at all (MySQL, PostgreSQL). For others the support is
incomplete (Merant SequeLink driver). For these drivers, Chili!Soft uses the
implementation of updatable cursors in the ODBC Driver Manager to supply the missing
functionality. This works well for recordsets whose fields contain string or numeric data
as well as a primary key, auto-increment or timestamp fields. However, in recordsets
containing binary fields or recordsets with duplicate rows, updates, inserts and deletes
should be done using the Execute method of the Connection object.
Connection.Execute will execute any SQL statement recognized by the database
regardless of the capabilities of the ODBC driver.
In ADO, the object hierarchy is de-emphasized. Unlike Data Access Objects (DAO) or Remote
Data Objects (RDO), you do not have to navigate through a hierarchy to create objects, because
most ADO objects can be independently created. This allows you to create and track only the
objects you need. This model also results in fewer ADO objects, and thus a smaller working set.
ADO supports the following key features for building client/server and Web-based applications:
•
Independently created objects.
•
Support for stored procedures with in/out parameters and return values.
•
Different cursor types, including the potential for support of back-end-specific cursors.
•
Advanced recordsetcache management.
•
Support for limits on number of returned rows and other query goals.
ADO Objects
ADO provides two objects for managing connections with data sources (Connection and
Command), two objects for managing the data returned from a data source (Field and
Recordset) and three secondary objects (Parameters, Properties, and Errors) for managing
information about ADO.
Object
Description
ADO Command Object
Defines a specific command to execute against a data source.
ADO Connection Object
Represents an open connection to a data source.
ADO Error Object
Provides specific details about each ADO error.
ADO Field Object
Represents a column of data with a common data type.
Chili!Soft ASP 3.6 Product Documentation
ADO Parameter Object
Represents a parameter or argument associated with a
Command object based on a parameterized query or stored
procedure.
ADO Property Object
Represents a dynamic characteristic of an ADO object that is
defined by the provider. This object is not currently supported
on UNIX.
ADO Recordset Object
Represents the entire set of records from a database table or the
results of an executed command.
252
ADO Command Object
The Command object defines a specific command to execute against a data source.
ADO Command Object Collections
ADO Parameters Collection
Contains all the Parameter objects of a Command
object.
ADO Properties Collection
Contains all the Property objects for a specific instance
of a Command object. This collection is not currently
supported on UNIX.
ADO Command Object Methods
ADO Command Object
CreateParameter Method
Creates a new Parameter object with the specified
properties.
ADO Command Object Execute
Method
Executes the query, SQL statement, or stored procedure
specified in the CommandText property.
ADO Command Object Properties
ADO Command Object
ActiveConnection Property
The Connection object to which the specified
Command object currently belongs.
ADO Command Object
CommandText Property
The text of a command that you want to issue against a
provider.
ADO Command Object
CommandTimeout Property
How long to wait while executing a command before
terminating the command and issuing an error.
ADO Command Object
CommandType Property
The type of Command object.
ADO Command Object Name
Property
The name of a specific Command object. This property
is not currently supported on UNIX
ADO Command Object Prepared
Property
Whether or not to save a compiled version of a
command before execution. This property is not
currently supported on UNIX.
ADO Command Object State
The current state of the Command object. This property
Chili!Soft ASP 3.6 Product Documentation
Property
253
is not currently supported on UNIX
ADO Command Object Remarks
A Command object is used to query a database, return records in a ADO Recordset Object,
execute bulk operations, or manipulate the structure of a database. It is a definition of a specific
command that you intend to execute against a data source.
The collections, methods, and properties of a Command object are used to:
•
Define the executable text of the command (for example, an SQL statement) with the
ADO Command Object CommandText Property.
•
Define parameterized queries or stored procedure arguments with ADO Parameter Object
objects and the ADO Parameters Collection.
•
Execute a command and return a ADO Recordset Object if appropriate with the ADO
Command Object Execute Method.
•
Specify the type of command with the ADO Command Object CommandType Property
prior to execution to optimize performance.
•
Set the number of seconds a provider will wait for a command to execute with the
CommandTimeout property.
•
Associate an open connection with a Command object by setting its property.
•
Set the ADO Command Object Name Property to identify the Command object as a
method on the associated ADO Connection Object.
•
Pass a Command object to the ADO Recordset Object Source Property of an ADO
Recordset Object in order to obtain data.
To execute a query without using a Command object, pass a query string to the ADO Connection
Object Execute Method of an ADO Connection Object or to the ADO Recordset Object Open
Method of an ADO Recordset Object. However, a Command object is required when you want
to retain the command text and re-execute it, or use query parameters.
To create a Command object independently of a previously defined Connection object, set its
ActiveConnection property to a valid connection string. ADO still creates a Connection object,
but it doesn't assign that object to an object variable. However, if you are associating multiple
Command objects with the same connection, you should explicitly create and open a
Connection object; this assigns the Connection object to an object variable. If you do not set the
Command object’s ActiveConnection property to this object variable, ADO creates a new
Connection object for each Command object, even if you use the same connection string.
To execute a Command, simply call it by its ADO Command Object Name Property on the
associated Connection object. The Command must have its ActiveConnection property set to
the Connection object. If the Command has parameters, pass values for them as arguments to
the method.
Depending on the functionality of the provider, some Command collections, methods, or
properties may generate an error when referenced.
Chili!Soft ASP 3.6 Product Documentation
254
ADO Command Object Methods
ADO Command Object CreateParameter Method
Creates a new Parameter object with the specified properties.
CreateParameter Method Syntax (ADO Command Object)
Set parameter = command.CreateParameter (
Name, Type, Direction, Size, Value)
CreateParameter Method Parameters (ADO Command Object)
parameter
The new ADO Parameter Object.
Name
An optional String representing the name of the Parameter object.
Type
An optional Long value specifying the data type of the Parameter object. See the ADO
Parameter Object Type Property for valid settings.
Direction
An optional Long value specifying the type of Parameter object. See the ADO Parameter Object
Direction Property for valid settings.
Size
An optional Long value specifying the maximum length for the parameter value in characters or
bytes.
Value
An optional varValue specifying the value for the Parameter object.
CreateParameter Method Return Value (ADO Command Object)
Returns a Parameter object.
CreateParameter Method Remarks (ADO Command Object)
Use the CreateParameter method to create a new ADO Parameter Object with the specified
name, type, direction, size, and value. Any values you pass in the arguments are written to the
corresponding Parameter properties.
This method does not automatically append the Parameter object to the ADO Parameters
Collection of a Command object. This lets you set additional properties whose values ADO will
validate when you append the Parameter object to the collection.
Chili!Soft ASP 3.6 Product Documentation
255
If you specify a variable-length data type in the Type argument, you must either pass a Size
argument or set the ADO Parameter Object Size Property of the Parameter object before
appending it to the Parameters collection; otherwise, an error occurs.
CreateParameter Method Examples (ADO Command Object)
See the ADO Collections Append Method example.
ADO Command Object Execute Method
Executes the query, SQL statement, or stored procedure specified in the CommandText
property.
Object Execute Method Syntax (ADO Command Object)
For a row-returning Command:
Set recordset = command.Execute(
RecordsAffected, Parameters, Options )
For a non-row-returning Command:
command.Execute RecordsAffected, Parameters, Options
Object Execute Method Parameters (ADO Command Object)
RecordsAffected
An optional Long variable to which the provider returns the number of records that the operation
affected.
Parameters
An optional Variant array of parameter values passed with an SQL statement. (Output
parameters will not return correct values when passed in this argument.)
Options
An optional Long value that indicates how the provider should evaluate the CommandText
property of the Command object:
Constant
Description
adCmdText
The provider should evaluate CommandText as a textual definition
of a command, such as a SQL statement.
adCmdTable
The provider should evaluate CommandText as a table name.
adCmdStoredProc
The provider should evaluate CommandText as a stored procedure.
adCmdUnknown
The type of command in CommandText is not known.
See the ADO Command Object CommandType Property for a more detailed explanation of the
four constants in this list.
Object Execute Method Remarks (ADO Command Object)
Chili!Soft ASP 3.6 Product Documentation
256
Using the Execute method on a Command object executes the query specified in the
CommandText property of the object. If the CommandText property specifies a row-returning
query, any results the execution generates are stored in a new ADO Recordset Object. If the
command is not a row-returning query, the provider returns a closed Recordset object. Some
application languages allow you to ignore this return value if no recordset is desired.
If the query has parameters, the current values for the Command object's parameters are used
unless you override these with parameter values passed with the Execute call. You can override a
subset of the parameters by omitting new values for some of the parameters when calling the
Execute method. The order in which you specify the parameters is the same order in which the
method passes them. For example, if there were four (or more) parameters and you wanted to
pass new values for only the first and fourth parameters, you would pass Array(var1,,,var4) as the
Parameters argument.
Note
Output parameters will not return correct values when passed in the Parameters
argument.
Object Execute Method Return Values (ADO Command Object)
Returns a Recordset object reference.
Object Execute Method Examples (ADO Command Object)
This VBScript example demonstrates the Execute method when run from both a Command
object and an ADO Connection Object. It also uses the ADO Recordset Object Requery Method
to retrieve current data in a recordset, and the ADO Collections Clear Method to clear the
contents of the ADO Errors Collection. The ExecuteCommand and PrintOutput procedures are
required for this procedure to run.
<!-- #Include file="ADOVBS.INC" -->
<HTML><HEAD>
<TITLE>ADO 1.5 Execute Method</TITLE></HEAD>
<BODY>
<FONT FACE="MS SANS SERIF" SIZE=2>
<Center><H3>ADO Execute Method</H3><H4>Recordset Retrieved Using
Connection Object</H4>
<TABLE WIDTH=600 BORDER=0>
<TD VALIGN=TOP ALIGN=LEFT COLSPAN=3><FONT SIZE=2>
<!--- Recordsets retrieved using Execute method of Connection and
Command Objects-->
<%
Set OBJdbConnection = Server.CreateObject("ADODB.Connection")
Chili!Soft ASP 3.6 Product Documentation
OBJdbConnection.Open "AdvWorks"
SQLQuery = "SELECT * FROM Customers"
'First Recordset RSCustomerList
Set RSCustomerList = OBJdbConnection.Execute(SQLQuery)
Set OBJdbCommand = Server.CreateObject("ADODB.Command")
OBJdbCommand.ActiveConnection = OBJdbConnection
SQLQuery2 = "SELECT * From Products"
OBJdbCommand.CommandText = SQLQuery2
Set RsProductList = OBJdbCommand.Execute
%>
<TABLE COLSPAN=8 CELLPADDING=5 BORDER=0>
<!-- BEGIN column header row for Customer Table-->
<TR><TD ALIGN=CENTER BGCOLOR="#008080">
<FONT STYLE="ARIAL NARROW" COLOR="#ffffff" SIZE=1>Company
Name</FONT>
</TD>
<TD ALIGN=CENTER BGCOLOR="#008080">
<FONT STYLE="ARIAL NARROW" COLOR="#ffffff" SIZE=1>Contact
Name</FONT>
</TD>
<TD ALIGN=CENTER WIDTH=150 BGCOLOR="#008080">
<FONT STYLE="ARIAL NARROW" COLOR="#ffffff" SIZE=1>E-mail
address</FONT>
</TD>
<TD ALIGN=CENTER BGCOLOR="#008080">
<FONT STYLE="ARIAL NARROW" COLOR="#ffffff" SIZE=1>City</FONT>
</TD>
<TD ALIGN=CENTER BGCOLOR="#008080">
<FONT STYLE="ARIAL NARROW" COLOR="#ffffff"
SIZE=1>State/Province</FONT>
</TD></TR>
<!--Display ADO Data from Customer Table-->
<% Do While Not RScustomerList.EOF %>
257
Chili!Soft ASP 3.6 Product Documentation
<TR>
<TD BGCOLOR="f7efde" ALIGN=CENTER>
<FONT STYLE="ARIAL NARROW" SIZE=1>
<%= RSCustomerList("CompanyName")%>
</FONT></TD>
<TD BGCOLOR="f7efde" ALIGN=CENTER>
<FONT STYLE="ARIAL NARROW" SIZE=1>
<%= RScustomerList("ContactLastName") & ", " %>
<%= RScustomerList("ContactFirstName") %>
</FONT></TD>
<TD BGCOLOR="f7efde" ALIGN=CENTER>
<FONT STYLE="ARIAL NARROW" SIZE=1>
<%= RScustomerList("ContactLastName")%>
</FONT></TD>
<TD BGCOLOR="f7efde" ALIGN=CENTER>
<FONT STYLE="ARIAL NARROW" SIZE=1>
<%= RScustomerList("City")%>
</FONT></TD>
<TD BGCOLOR="f7efde" ALIGN=CENTER>
<FONT STYLE="ARIAL NARROW" SIZE=1>
<%= RScustomerList("StateOrProvince")%>
</FONT></TD>
</TR>
<!-Next Row = Record Loop and add to html table-->
<%
RScustomerList.MoveNext
Loop
RScustomerList.Close
%>
</TABLE><HR>
<H4>Recordset Retrieved Using Command Object</H4>
<TABLE COLSPAN=8 CELLPADDING=5 BORDER=0>
258
Chili!Soft ASP 3.6 Product Documentation
259
<!-- BEGIN column header row for Product List Table-->
<TR><TD ALIGN=CENTER BGCOLOR="#800000">
<FONT STYLE="ARIAL NARROW" COLOR="#ffffff" SIZE=1>Product
Type</FONT>
</TD>
<TD ALIGN=CENTER BGCOLOR="#800000">
<FONT STYLE="ARIAL NARROW" COLOR="#ffffff" SIZE=1>Product
Name</FONT>
</TD>
<TD ALIGN=CENTER WIDTH=350 BGCOLOR="#800000">
<FONT STYLE="ARIAL NARROW" COLOR="#ffffff" SIZE=1>Product
Description</FONT>
</TD>
<TD ALIGN=CENTER BGCOLOR="#800000">
<FONT STYLE="ARIAL NARROW" COLOR="#ffffff" SIZE=1>Unit Price</FONT>
</TD></TR>
<!-- Display ADO Data Product List-->
<% Do While Not RsProductList.EOF %>
<TR>
<TD BGCOLOR="f7efde" ALIGN=CENTER>
<FONT STYLE="ARIAL NARROW" SIZE=1>
<%= RsProductList("ProductType")%>
</FONT></TD>
<TD BGCOLOR="f7efde" ALIGN=CENTER>
<FONT STYLE="ARIAL NARROW" SIZE=1>
<%= RsProductList("ProductName")%>
</FONT></TD>
<TD BGCOLOR="f7efde" ALIGN=CENTER>
<FONT STYLE="ARIAL NARROW" SIZE=1>
<%= RsProductList("ProductDescription")%>
</FONT></TD>
<TD BGCOLOR="f7efde" ALIGN=CENTER>
<FONT STYLE="ARIAL NARROW" SIZE=1>
Chili!Soft ASP 3.6 Product Documentation
260
<%= RsProductList("UnitPrice")%>
</FONT></TD>
<!-- Next Row = Record -->
<%
RsProductList.MoveNext
Loop
'Remove objects from memory to free resources
RsProductList.Close
OBJdbConnection.Close
Set ObJdbCommand = Nothing
Set RsProductList = Nothing
Set OBJdbConnection = Nothing
%>
</TABLE></FONT></Center></BODY></HTML>
ADO Command Object Properties
ADO Command Object ActiveConnection Property
Specifies to which Connection object the specified Command object currently belongs.
ActiveConnection Property Return Values (ADO Command Object)
Sets or returns a String containing the definition for a connection or a Connection object.
Default is a Null object reference.
ActiveConnection Property Remarks (ADO Command Object)
Use the ActiveConnection property to determine the Connection object over which the specified
Command object will execute.
For Command objects, the ActiveConnection property is read/write. If you attempt to call the
ADO Command Object Execute Method on a Command object before setting this property to an
open ADO Connection Object or valid connection string, an error occurs. Setting the
ActiveConnection property to Nothing disassociates the Command object from the current
Connection and causes the provider to release any associated resources on the data source. You
can then associate the Command object with the same or another Connection object. Some
providers allow you to change the property setting from one Connection to another, without
having to first set the property to Nothing.
If the ADO Parameters Collection of the Command object contains parameters supplied by the
provider, the collection is cleared if you set the ActiveConnection property to Nothing or to
another Connection object. If you manually create ADO Parameter Object objects and use them
Chili!Soft ASP 3.6 Product Documentation
261
to fill the Parameters collection of the Command object, setting the ActiveConnection property
to Nothing or to another Connection object leaves the Parameters collection intact.
Closing the Connection object with which a Command object is associated sets the
ActiveConnection property to Nothing. Setting this property to a closed Connection object
generates an error.
ActiveConnection Property Example (ADO Command Object)
This Visual Basic example uses the ActiveConnection, ADO Command Object
CommandText Property, CommandTimeout, ADO Command Object CommandType
Property, ADO Field Object ActualSize Property, and ADO Parameter Object Direction Property
properties to execute a stored procedure:
Public Sub ActiveConnectionX()
Dim cnn1 As ADODB.Connection
Dim cmdByRoyalty As ADODB.Command
Dim prmByRoyalty As ADODB.Parameter
Dim rstByRoyalty As ADODB.Recordset
Dim rstAuthors As ADODB.Recordset
Dim intRoyalty As Integer
Dim strAuthorID As String
Dim strCnn As String
` Define a command object for a stored procedure.
Set cnn1 = New ADODB.Connection
strCnn = "driver={SQL Server};server=srv;" & _
"uid=sa;pwd=;database=pubs"
cnn1.Open strCnn
Set cmdByRoyalty = New ADODB.Command
Set cmdByRoyalty.ActiveConnection = cnn1
cmdByRoyalty.CommandText = "byroyalty"
cmdByRoyalty.CommandType = adCmdStoredProc
cmdByRoyalty.CommandTimeout = 15
` Define the stored procedure's input parameter.
intRoyalty = Trim(InputBox( _
"Enter royalty:"))
Set prmByRoyalty = New ADODB.Parameter
prmByRoyalty.Type = adInteger
Chili!Soft ASP 3.6 Product Documentation
262
prmByRoyalty.Size = 3
prmByRoyalty.Direction = adParamInput
prmByRoyalty.Value = intRoyalty
cmdByRoyalty.Parameters.Append prmByRoyalty
` Create a recordset by executing the command.
Set rstByRoyalty = cmdByRoyalty.Execute()
` Open the Authors table to get author names for display.
Set rstAuthors = New ADODB.Recordset
rstAuthors.Open "authors", strCnn, , , adCmdTable
` Print current data in the recordset, adding
` author names from Authors table.
Debug.Print "Authors with " & intRoyalty & _
" percent royalty"
Do While Not rstByRoyalty.EOF
strAuthorID = rstByRoyalty!au_id
Debug.Print , rstByRoyalty!au_id & ", ";
rstAuthors.Filter = "au_id = '" & strAuthorID & "'"
Debug.Print rstAuthors!au_fname & " " & _
rstAuthors!au_lname
rstByRoyalty.MoveNext
Loop
rstByRoyalty.Close
rstAuthors.Close
cnn1.Close
End Sub
ADO Command Object CommandText Property
Contains the text of a command that you want to issue against a provider.
CommandText Property Return Values
Sets or returns a String value containing a provider command, such as an SQL statement, a table
name, or a stored procedure call. Default is "" (zero-length string).
CommandText Property Remarks
Chili!Soft ASP 3.6 Product Documentation
263
Use the CommandText property to set or return the text of a Command object. Usually, this will
be an SQL statement, but can also be any other type of command statement recognized by the
provider, such as a stored procedure call. An SQL statement must be of the particular dialect or
version supported by the provider's query processor.
If the ADO Command Object Prepared Property of the Command object is set to True and the
Command object is bound to an open connection when you set the CommandText property,
ADO prepares the query (that is, a compiled form of the query is stored by the provider) when
you call the ADO Command Object Execute Method or ADO Connection Object Open Method
methods. The Prepared property is not currently supported on UNIX.
Depending on the ADO Command Object CommandType Property setting, ADO may alter the
CommandText property. You can read the CommandText property at any time to see the actual
command text that ADO will use during execution.
CommandText Property Example
See the ActiveConnection property.
ADO Command Object CommandTimeout Property
How long to wait while executing a command before terminating the attempt and generating an
error.
CommandTimeout Property Return Values (ADO Command Object)
Sets or returns a Long value that specifies, in seconds, how long to wait for a command to
execute. Default is 30.
CommandTimeout Property Remarks (ADO Command Object)
Use the CommandTimeout property on a Command object to allow the cancellation of an ADO
Command Object Execute Method call due to delays from network traffic or heavy server use. If
the interval set in the CommandTimeout property elapses before the command completes
execution, an error occurs and ADO cancels the command. If you set the property to zero, ADO
will wait indefinitely until the execution is complete. Make sure the provider and data source to
which you are writing code supports the CommandTimeout functionality.
The CommandTimeout setting on a Connection object has no effect on the CommandTimeout
setting on a Command object on the same Connection; that is, the Command object's
CommandTimeout property does not inherit the value of the Connection object's
CommandTimeout value.
CommandTimeout Property Examples (ADO Command Object)
See the ActiveConnection property.
ADO Command Object CommandType Property
The type of a Command object.
Chili!Soft ASP 3.6 Product Documentation
264
CommandType Property Return Values (ADO Command Object)
Sets or returns one of the following CommandTypeEnum values:
Constant
Description
adCmdText
Evaluates CommandText as a textual definition of a command.
adCmdTable
Evaluates CommandText as a table name.
adCmdStoredProc
Evaluates CommandText as a stored procedure.
adCmdUnknown
(Default) The type of command in the CommandText property
is not known.
CommandType Property Remarks (ADO Command Object)
Use the CommandType property to optimize evaluation of the ADO Command Object
CommandText Property.
If the CommandType property value equals adCmdUnknown (the default value), you may
experience diminished performance because ADO must make calls to the provider to determine if
the CommandText property is an SQL statement, a stored procedure, or a table name. If you
know what type of command you're using, setting the CommandType property instructs ADO to
go directly to the relevant code. If the CommandType property does not match the type of
command in the CommandText property, an error occurs when you call the ADO Command
Object Execute Method.
CommandType Property Example (ADO Command Object)
See the ActiveConnection property.
ADO Command Object Name Property
The name of an object. This property is not currently supported on UNIX
Name Property Return Values (ADO Command Object)
Sets or returns a String value. The value is read/write.
Name Property Remarks (ADO Command Object)
Use the Name property to assign a name to or retrieve the name of a Command object.
ADO Command Object Prepared Property
Determines whether or not the provider saves a compiled version of a command before execution.
This property is not currently supported on UNIX.
Prepared Property Return Values
Sets or returns a Boolean value.
Prepared Property Remarks
Chili!Soft ASP 3.6 Product Documentation
265
Use the Prepared property to have the provider save a prepared (or compiled) version of the
query specified in the ADO Command Object CommandText Property before a Command
object's first execution. This may slow a command's first execution, but once the provider
compiles a command, the provider will use the compiled version of the command for any
subsequent executions, which will result in improved performance.
If the property is False, the provider will execute the Command object directly without creating
a compiled version.
If the provider does not support command preparation, it may return an error as soon as this
property is set to True. If it does not return an error, it simply ignores the request to prepare the
command and sets the Prepared property to False.
Prepared Property Example
This Visual Basic example demonstrates the Prepared property by opening two Command
objects: one prepared and one not prepared.
Public Sub PreparedX()
Dim cnn1 As ADODB.Connection
Dim cmd1 As ADODB.Command
Dim cmd2 As ADODB.Command
Dim strCnn As String
Dim strCmd As String
Dim sngStart As Single
Dim sngEnd As Single
Dim sngNotPrepared As Single
Dim sngPrepared As Single
Dim intLoop As Integer
` Open a connection.
strCnn = "driver={SQL Server};server=srv;" & _
"uid=sa;pwd=;database=pubs"
Set cnn1 = New ADODB.Connection
cnn1.Open strCnn
` Create two command objects for the same
` command -- one prepared and one not prepared.
strCmd = "SELECT title, type FROM titles ORDER BY type"
Set cmd1 = New ADODB.Command
Set cmd1.ActiveConnection = cnn1
Chili!Soft ASP 3.6 Product Documentation
cmd1.CommandText = strCmd
Set cmd2 = New ADODB.Command
Set cmd2.ActiveConnection = cnn1
cmd2.CommandText = strCmd
cmd2.Prepared = True
` Set timer, then execute unprepared command 20 times.
sngStart = Timer
For intLoop = 1 To 20
cmd1.Execute
Next intLoop
sngEnd = Timer
sngNotPrepared = sngEnd - sngStart
` Reset the timer, then execute the prepared
` command 20 times.
sngStart = Timer
For intLoop = 1 To 20
cmd2.Execute
Next intLoop
sngEnd = Timer
sngPrepared = sngEnd - sngStart
` Display performance results.
MsgBox "Performance Results:" & vbCr & _
" Not Prepared: " & Format(sngNotPrepared, _
"##0.000") & " seconds" & vbCr & _
" Prepared: " & Format(sngPrepared, _
"##0.000") & " seconds"
cnn1.Close
End Sub
ADO Command Object State Property
Describes the current state of an object. This property is not currently supported on UNIX
State Property Return Values (ADO Command Object)
Sets or returns a Long value that can be one of the following constants:
266
Chili!Soft ASP 3.6 Product Documentation
Constant
Description
adStateClosed
The object is closed. Default.
adStateOpen
The object is open.
267
State Property Remarks (ADO Command Object)
You can use the State property to determine the current state of a given object at any time.
ADO Connection Object
A Connection object represents an open connection to a data source.
ADO Connection Object Collections
ADO Errors Collection
Contains all stored Error objects that pertain to an ADO
operation.
ADO Properties Collection
All Property objects for a specific instance of a Connection
object. This collection is not currently supported on UNIX.
ADO Connection Object Methods
ADO Connection Object
BeginTrans, CommitTrans,
and RollbackTrans Methods
Begins a new database transaction within a Connection object.
ADO Connection Object
Close Method
Closes an open Connection object and any dependent objects.
ADO Connection Object
BeginTrans, CommitTrans,
and RollbackTrans Methods
Saves any pending changes and ends the current transaction. It
may also start a new transaction.
ADO Connection Object
Execute Method
Executes the specified query, SQL statement, stored procedure,
or provider-specified text.
ADO Connection Object
Open Method
Opens a connection to a data source.
ADO Connection Object
OpenSchema Method
Obtains database schema information from the provider. This
method is not currently supported on UNIX.
ADO Connection Object
BeginTrans, CommitTrans,
and RollbackTrans Methods
Cancels any changes made during the current transaction and
ends the transaction. It may also start a new transaction.
ADO Connection Object Properties
ADO Connection Object
Attributes Property
One or more characteristics of an object.
ADO Connection Object
How long to wait while executing a command before
Chili!Soft ASP 3.6 Product Documentation
CommandTimeout Property
terminating the command and issuing and error.
ADO Connection Object
ConnectionString Property
Contains the information used to establish a connection to a
data source.
268
ADO Connection Object
How long to wait while establishing a connection before
ConnectionTimeout Property terminating the attempt and issuing and error.
ADO Connection Object
CursorLocation Property
The location of the cursor engine in a recordset.
ADO Connection Object
DefaultDatabase Property
The default database for the Connection object.
ADO Connection Object
IsolationLevel Property
The level of isolation for the Connection object.
ADO Connection Object
Mode Property
The available permissions for modifying data in a Connection
object.
ADO Connection Object
Provider Property
The name of a provider for a Connection object. This property
is not available on UNIX.
ADO Connection Object
State Property
Describes the current state of the Connection object.
ADO Connection Object
Version Property
The ADO version number.
ADO Connection Object Remarks
A Connection object represents a session with a data source. In the case of a client/server
database system, it may represent an actual network connection to the server. Depending on the
functionality of the provider, some collections, properties, and methods of the Connection object
may not be available.
Use the collections, methods, and properties of a Connection object for:
•
configuring the connection before opening it with the ConnectionString,
CommandTimeout, and ADO Connection Object Mode Property properties.
•
setting the CursorLocation property to invoke the Client Cursor Provider, which supports
batch updates. Batch updates are not currently supported on UNIX.
•
setting the default database for the connection with the DefaultDatabase property.
•
setting the level of isolation for the transactions opened on the connection with the
IsolationLevel property. Transactions are not currently supported on UNIX.
•
specifying an OLE DB provider with the ADO Connection Object Provider Property.
•
establishing and breaking the physical connection to the data source with the ADO
Connection Object Open Method and ADO Connection Object Close Method methods.
•
executing a command on the connection with the ADO Connection Object Execute
Method and configuring the execution with the CommandTimeout property.
Chili!Soft ASP 3.6 Product Documentation
269
•
managing transactions on the open connection, including nested transactions if the
provider supports them, with the BeginTrans, CommitTrans, and RollbackTrans
methods and the ADO Connection Object Attributes Property. The transaction methods
are not currently supported on UNIX.
•
examining errors returned from the data source with the ADO Errors Collection.
•
reading the version from the ADO implementation in use with the ADO Connection
Object Version Property.
•
obtaining schema information about your database with the ADO Connection Object
OpenSchema Method.
Note
To execute a query without using a Command object, pass a query string to the Execute
method of a Connection object. However, a Command object is required when you
want to retain the command text and re-execute it, or use query parameters.
ADO Connection Object Methods
ADO Connection Object Close Method
Closes an open object and any dependent objects.
Close Method Syntax (ADO Connection Object)
object.Close
Close Method Remarks (ADO Connection Object)
Use the Close method to close a Connection object to free any associated system resources.
Closing an object does not remove it from memory; you may change its property settings and
open it again later. To completely eliminate an object from memory, set the object variable to
Nothing.
Using the Close method to close a Connection object also closes any active Recordset objects
associated with the connection. An ADO Command Object associated with the Connection
object you are closing will persist, but it will no longer be associated with a Connection object;
that is, its ActiveConnection property will be set to Nothing. Also, the Command object's ADO
Parameters Collection will be cleared of any provider-defined parameters.
You can later call the ADO Connection Object Open Method to reestablish the connection to the
same or another data source. While the Connection object is closed, calling any methods that
require an open connection to the data source generates an error.
Closing a Connection object while there are open ADO Recordset Object objects on the
connection rolls back any pending changes in all of the Recordset objects. Explicitly closing a
Connection object (calling the Close method) while a transaction is in progress generates an
error. If a Connection object falls out of scope while a transaction is in progress, ADO
automatically rolls back the transaction.
Chili!Soft ASP 3.6 Product Documentation
270
Close Method Examples (ADO Connection Object)
This VBScript example uses the Open and Close methods on both Recordset and Connection
objects that have been opened.
<!-- #Include file="ADOVBS.INC" -->
<HTML><HEAD>
<TITLE>ADO 1.5 Open Method</TITLE>
</HEAD><BODY>
<FONT FACE="MS SANS SERIF" SIZE=2>
<Center><H3>ADO Open Method</H3>
<TABLE WIDTH=600 BORDER=0>
<TD VALIGN=TOP ALIGN=LEFT COLSPAN=3><FONT SIZE=2>
<!--- ADO Connection used to create 2 recordsets-->
<%
Set OBJdbConnection = Server.CreateObject("ADODB.Connection")
OBJdbConnection.Open "AdvWorks"
SQLQuery = "SELECT * FROM Customers"
'First Recordset RSCustomerList
Set RSCustomerList = OBJdbConnection.Execute(SQLQuery)
'Second Recordset RsProductist
Set RsProductList = Server.CreateObject("ADODB.Recordset")
RsProductList.CursorType = adOpenDynamic
RsProductList.LockType = adLockOptimistic
RsProductList.Open "Products", OBJdbConnection
%>
<TABLE COLSPAN=8 CELLPADDING=5 BORDER=0>
<!-- BEGIN column header row for Customer Table-->
<TR><TD ALIGN=CENTER BGCOLOR="#008080">
<FONT STYLE="ARIAL NARROW" COLOR="#ffffff" SIZE=1>Company
Name</FONT></TD>
<TD ALIGN=CENTER BGCOLOR="#008080">
<FONT STYLE="ARIAL NARROW" COLOR="#ffffff" SIZE=1>Contact
Name</FONT></TD>
<TD ALIGN=CENTER WIDTH=150 BGCOLOR="#008080">
Chili!Soft ASP 3.6 Product Documentation
<FONT STYLE="ARIAL NARROW" COLOR="#ffffff" SIZE=1>E-mail
address</FONT></TD>
<TD ALIGN=CENTER BGCOLOR="#008080">
<FONT STYLE="ARIAL NARROW" COLOR="#ffffff" SIZE=1>City</FONT></TD>
<TD ALIGN=CENTER BGCOLOR="#008080">
<FONT STYLE="ARIAL NARROW" COLOR="#ffffff"
SIZE=1>State/Province</FONT></TD></TR>
<!--Display ADO Data from Customer Table-->
<% Do While Not RScustomerList.EOF %>
<TR><TD BGCOLOR="f7efde" ALIGN=CENTER>
<FONT STYLE="ARIAL NARROW" SIZE=1>
<%= RSCustomerList("CompanyName")%>
</FONT></TD>
<TD BGCOLOR="f7efde" ALIGN=CENTER>
<FONT STYLE="ARIAL NARROW" SIZE=1>
<%= RScustomerList("ContactLastName") & ", " %>
<%= RScustomerList("ContactFirstName") %>
</FONT></TD>
<TD BGCOLOR="f7efde" ALIGN=CENTER>
<FONT STYLE="ARIAL NARROW" SIZE=1>
<%= RScustomerList("ContactLastName")%>
</FONT></TD>
<TD BGCOLOR="f7efde" ALIGN=CENTER>
<FONT STYLE="ARIAL NARROW" SIZE=1>
<%= RScustomerList("City")%>
</FONT></TD>
<TD BGCOLOR="f7efde" ALIGN=CENTER>
<FONT STYLE="ARIAL NARROW" SIZE=1>
<%= RScustomerList("StateOrProvince")%>
</FONT></TD></TR>
<!-Next Row = Record Loop and add to html table-->
<%
RScustomerList.MoveNext
271
Chili!Soft ASP 3.6 Product Documentation
Loop
RScustomerList.Close
OBJdbConnection.Close
%>
</TABLE>
<HR>
<TABLE COLSPAN=8 CELLPADDING=5 BORDER=0>
<!-- BEGIN column header row for Product List Table-->
<TR><TD ALIGN=CENTER BGCOLOR="#800000">
<FONT STYLE="ARIAL NARROW" COLOR="#ffffff" SIZE=1>Product
Type</FONT></TD>
<TD ALIGN=CENTER BGCOLOR="#800000">
<FONT STYLE="ARIAL NARROW" COLOR="#ffffff" SIZE=1>Product
Name</FONT></TD>
<TD ALIGN=CENTER WIDTH=350 BGCOLOR="#800000">
<FONT STYLE="ARIAL NARROW" COLOR="#ffffff" SIZE=1>Product
Description</FONT></TD>
<TD ALIGN=CENTER BGCOLOR="#800000">
<FONT STYLE="ARIAL NARROW" COLOR="#ffffff" SIZE=1>Unit
Price</FONT></TD></TR>
<!-- Display ADO Data Product List-->
<% Do While Not RsProductList.EOF %>
<TR> <TD BGCOLOR="f7efde" ALIGN=CENTER>
<FONT STYLE="ARIAL NARROW" SIZE=1>
<%= RsProductList("ProductType")%>
</FONT></TD>
<TD BGCOLOR="f7efde" ALIGN=CENTER>
<FONT STYLE="ARIAL NARROW" SIZE=1>
<%= RsProductList("ProductName")%>
</FONT></TD>
<TD BGCOLOR="f7efde" ALIGN=CENTER>
<FONT STYLE="ARIAL NARROW" SIZE=1>
<%= RsProductList("ProductDescription")%>
272
Chili!Soft ASP 3.6 Product Documentation
273
</FONT></TD>
<TD BGCOLOR="f7efde" ALIGN=CENTER>
<FONT STYLE="ARIAL NARROW" SIZE=1>
<%= RsProductList("UnitPrice")%>
</FONT></TD>
<!-- Next Row = Record -->
<%
RsProductList.MoveNext
Loop
'Remove Objects from Memory Freeing
Set RsProductList = Nothing
Set OBJdbConnection = Nothing
%>
</TABLE></FONT></Center></BODY></HTML>
ADO Connection Object Execute Method
Executes the specified query, SQL statement, stored procedure, or provider-specific text.
Execute Method Syntax (ADO Connection Object)
For a non-row-returning command string:
connection.Execute CommandText, RecordsAffected, Options
For a row-returning command string:
Set recordset = connection.Execute (
CommandText, RecordsAffected, Options)
Execute Method Parameters (ADO Connection Object)
CommandText
A String containing the SQL statement, table name, stored procedure, or provider-specific text to
execute.
RecordsAffected
An optional Long variable to which the provider returns the number of records that the operation
affected.
Options
An optional Long value that indicates how the provider should evaluate the CommandText
argument:
Chili!Soft ASP 3.6 Product Documentation
Constant
Description
adCmdText
The provider should evaluate CommandText as a textual definition of a
command.
adCmdTable
The provider should evaluate CommandText as a table name.
274
adCmdStoredProc The provider should evaluate CommandText as a stored procedure.
adCmdUnknown The type of command in the CommandText argument is not known.
See the ADO Command Object CommandType Property for a more detailed explanation of the
four constants in this list.
Execute Method Return Values (ADO Connection Object)
Returns an ADO Recordset Object reference.
Execute Method Remarks (ADO Connection Object)
Using the Execute method on a Connection object executes whatever query you pass to the
method in the CommandText argument on the specified connection. If the CommandText
argument specifies a row-returning query, any results the execution generates are stored in a new
Recordset object. If the command is not a row-returning query, the provider returns a closed
Recordset object.
The returned Recordset object is always a read-only, forward-only cursor. If you need a
Recordset object with more functionality, first create a Recordset object with the desired
property settings, then use the Recordset object's ADO Recordset Object Open Method to
execute the query and return the desired cursor type.
The contents of the CommandText argument are specific to the provider and can be standard SQL
syntax or any special command format that the provider supports.
Execute Method Examples (ADO Connection Object)
See the Command ADO Command Object Execute Method.
ADO Connection Object OpenSchema Method
Obtains database schema information from the provider.
OpenSchema Method Syntax
Set recordset = connection.OpenSchema (QueryType,
Criteria, SchemaID)
OpenSchema Method Parameters
QueryType
The type of schema query to run. Can be any of the constants listed below.
Criteria
Chili!Soft ASP 3.6 Product Documentation
Optional array of query constraints for each QueryType option, as listed below:
QueryType values
Criteria values
adSchemaAsserts
CONSTRAINT_CATALOG
CONSTRAINT_SCHEMA
CONSTRAINT_NAME
adSchemaCatalogs
CATALOG_NAME
asSchemaCharacterSets
CHARACTER_SET_CATALO
G
CHARACTER_SET_SCHEMA
CHARACTER_SET_NAME
adSchemaCheckConstraints
CONSTRAINT_CATALOG
CONSTRAINT_SCHEMA
CONSTRAINT_NAME
adSchemaCollations
COLLATION_CATALOG
COLLATION_SCHEMA
COLLATION_NAME
adSchemaColumnDomainUsag DOMAIN_CATALOG
e
DOMAIN_SCHEMA
DOMAIN_NAME
COLUMN_NAME
adSchemaColumnPrivileges
TABLE_CATALOG
TABLE_SCHEMA
TABLE_NAME
COLUMN_NAME
GRANTOR
GRANTEE
adSchemaColumns
TABLE_CATALOG
TABLE_SCHEMA
TABLE_NAME
adSchemaConstraintTableUsag TABLE_CATALOG
e
TABLE_SCHEMA
TABLE_NAME
COLUMN_NAME
adSchemaForeignKeys
PK_TABLE_CATALOG
PK_TABLE_SCHEMA
PK_TABLE_NAME
FK_TABLE_CATALOG
FK_TABLE_SCHEMA
FK_TABLE_NAME
adSchemaIndexes
TABLE_CATALOG
TABLE_SCHEMA
275
Chili!Soft ASP 3.6 Product Documentation
INDEX_NAME
TYPE
TABLE_NAME
adSchemaKeyColumnUsage
CONSTRAINT_CATALOG
CONSTRAINT_SCHEMA
CONSTRAINT_NAME
TABLE_CATALOG
TABLE_SCHEMA
TABLE_NAME
COLUMN_NAME
adSchemaPrimaryKeys
PK_TABLE_CATALOG
PK_TABLE_SCHEMA
PK_TABLE_NAME
adSchemaProcedureColumns PROCEDURE_CATALOG
PROCEDURE_SCHEMA
PROCEDURE_NAME
COLUMN_NAME
adSchemaProcedures
PROCEDURE_CATALOG
PROCEDURE_SCHEMA
PROCEDURE_NAME
PARAMETER_TYPE
adSchemaProviderSpecific
see Remarks
adSchemaProviderTypes
DATA_TYPE
BEST_MATCH
adSchemaReferentialConstrain CONSTRAINT_CATALOG
ts
CONSTRAINT_SCHEMA
CONSTRAINT_NAME
adSchemaSchemata
CATALOG_NAME
SCHEMA_NAME
SCHEMA_OWNER
adSchemaSQLLanguages
<none>
adSchemaStatistics
TABLE_CATALOG
TABLE_SCHEMA
TABLE_NAME
adSchemaTableConstraints
CONSTRAINT_CATALOG
CONSTRAINT_SCHEMA
CONSTRAINT_NAME
TABLE_CATALOG
TABLE_SCHEMA
TABLE_NAME
CONSTRAINT_TYPE
276
Chili!Soft ASP 3.6 Product Documentation
adSchemaTablePrivileges
TABLE_CATALOG
TABLE_SCHEMA
TABLE_NAME
adSchemaTables
TABLE_CATALOG
TABLE_SCHEMA
TABLE_NAME
TABLE_TYPE
adSchemaTranslations
TRANSLATION_CATALOG
TRANSLATION_SCHEMA
TRANSLATION_NAME
adSchemaUsagePrivileges
OBJECT_CATALOG
OBJECT_SCHEMA
OBJECT_NAME
OBJECT_TYPE
GRANTOR
GRANTEE
277
adSchemaViewColumnUsage VIEW_CATALOG
VIEW_SCHEMA
VIEW_NAME
adSchemaViewTableUsage
VIEW_CATALOG
VIEW_SCHEMA
VIEW_NAME
adSchemaViews
TABLE_CATALOG
TABLE_SCHEMA
TABLE_NAME
SchemaID
The GUID for a provider-schema schema query is not defined by the OLE DB 1.1 specification.
This parameter is required if QueryType is set to adSchemaProviderSpecific; otherwise, it is not
used.
OpenSchema Method Return Values
Returns an ADO Recordset Object that contains schema information.
OpenSchema Method Remarks
The OpenSchema method returns information about the data source, such as information about
the tables on the server and the columns in the tables.
The Criteria argument is an array of values that can be used to limit the results of a schema
query. Each schema query has a different set of parameters that it supports. The actual schemas
are defined by the OLE DB specification under the "IDBSchemaRowset" interface. The ones
supported in ADO 1.5 are listed above.
Chili!Soft ASP 3.6 Product Documentation
278
The constant adSchemaProviderSpecific is used for the QueryType argument if the provider
defines its own non-standard schema queries outside those listed above. When this constant is
used, the SchemaID argument is required to pass the GUID of the schema query to execute. If
QueryType is set to adSchemaProviderSpecific but SchemaID is not provided, an error will
result.
Providers are not required to support all of the OLE DB standard schema queries. Specifically,
only adSchemaTables, adSchemaColumns and adSchemaProviderTypes are required by the
OLE DB specification. However, the provider is not required to support the Criteria constraints
listed above for those schema queries.
OpenSchema Method Example
This Visual Basic example uses the OpenSchema method to display the name and type of each
table in the Pubs database.
Public Sub OpenSchemaX()
Dim cnn1 As ADODB.Connection
Dim rstSchema As ADODB.Recordset
Dim strCnn As String
Set cnn1 = New ADODB.Connection
strCnn = "driver={SQL Server};server=srv;" & _
"uid=sa;pwd=;database=pubs"
cnn1.Open strCnn
Set rstSchema = cnn1.OpenSchema(adSchemaTables)
Do Until rstSchema.EOF
Debug.Print "Table name: " & _
rstSchema!TABLE_NAME & vbCr & _
"Table type: " & rstSchema!TABLE_TYPE & vbCr
rstSchema.MoveNext
Loop
rstSchema.Close
cnn1.Close
End Sub
ADO Connection Object Open Method
Opens a connection to a data source.
Open Method Syntax (ADO Connection Object)
connection.Open ConnectionString, UserID, Password
Chili!Soft ASP 3.6 Product Documentation
279
Open Method Parameters (ADO Connection Object)
ConnectionString
An optional String containing connection information. See the ConnectionString property for
details on valid settings.
UserID
An optional String containing a user name to use when establishing the connection.
Password
An optional String containing a password to use when establishing the connection.
Open Method Remarks (ADO Connection Object)
Using the Open method on a Connection object establishes the physical connection to a data
source. After this method successfully completes, the connection is live and you can issue
commands against it and process results.
Use the optional ConnectionString argument to specify a connection string containing a series of
argument = value statements separated by semicolons. The ConnectionString property
automatically inherits the value used for the ConnectionString argument. Therefore, you can
either set the ConnectionString property of the Connection object before opening it, or use the
ConnectionString argument to set or override the current connection parameters during the Open
method call.
If you pass user and password information both in the ConnectionString argument and in the
optional UserID and Password arguments, the results may be unpredictable; you should only pass
such information in either the ConnectionString argument or the UserID and Password
arguments.
When you have concluded your operations over an open Connection, use the ADO Connection
Object Close Method to free any associated system resources. Closing an object does not remove
it from memory; you may change its property settings and use the Open method to open it again
later. To completely eliminate an object from memory, set the object variable to Nothing.
Open Method Examples (ADO Connection Object)
See the ADO Connection Object Close Method.
ADO Connection Object BeginTrans, CommitTrans, and RollbackTrans Methods
The transaction methods manage transaction processing within a Connection object.
These transaction methods are summarized as follows:
Method
Description
BeginTrans
Begins a new transaction
CommitTrans Saves any changes and ends the current transaction. It may also start a new
transaction.
RollbackTrans Cancels any changes made during the current transaction and ends the
Chili!Soft ASP 3.6 Product Documentation
280
transaction. It may also start a new transaction.
BeginTrans, CommitTrans, and RollbackTrans Methods Syntax
level = connection.BeginTrans()
connection.BeginTrans
connection.CommitTrans
connection.RollbackTrans
BeginTrans, CommitTrans, and RollbackTrans Methods Remarks
Use these methods with a Connection object when you want to save or cancel a series of changes
made to the source data as a single unit. For example, to transfer money between accounts, you
subtract an amount from one and add the same amount to the other. If either update fails, the
accounts no longer balance. Making these changes within an open transaction ensures either all or
none of the changes goes through.
Not all providers support transactions. Check that the provider-defined property "Transaction
DDL" appears in the Connection object's ADO Properties Collection, indicating that the provider
supports transactions. If the provider does not support transactions, calling one of these methods
will return an error.
Once you call the BeginTrans method, the provider will no longer instantaneously commit any
changes you make until you call CommitTrans or RollbackTrans to end the transaction.
For providers that support nested transactions, calling the BeginTrans method within an open
transaction starts a new, nested transaction. The return value indicates the level of nesting: a
return value of "1" indicates you have opened a top-level transaction (that is, the transaction is not
nested within another transaction), "2" indicates that you have opened a second-level transaction
(a transaction nested within a top-level transaction), and so forth. Calling CommitTrans or
RollbackTrans affects only the most recently opened transaction; you must close or rollback the
current transaction before you can resolve any higher-level transactions.
Calling the CommitTrans method saves changes made within an open transaction on the
connection and ends the transaction. Calling the RollbackTrans method reverses any changes
made within an open transaction and ends the transaction. Calling either method when there is no
open transaction generates an error.
Depending on the Connection object's ADO Connection Object Attributes Property, calling
either the CommitTrans or RollbackTrans methods may automatically start a new transaction.
If the Attributes property is set to adXactCommitRetaining, the provider automatically starts a
new transaction after a CommitTrans call. If the Attributes property is set to
adXactAbortRetaining, the provider automatically starts a new transaction after a
RollbackTrans call.
BeginTrans, CommitTrans, and RollbackTrans Methods Return Value
BeginTrans can be called as a function that returns a Long variable indicating the nesting level
of the transaction.
Chili!Soft ASP 3.6 Product Documentation
281
BeginTrans, CommitTrans, and RollbackTrans Methods Examples
This Visual Basic example changes the book type of all psychology books in the Titles table of
the database. After the BeginTrans method starts a transaction that isolates all the changes made
to the Titles table, the CommitTrans method saves the changes. Notice that you can use the
RollbackTrans method to undo changes that you saved using the ADO Recordset Object Update
Method.
Public Sub BeginTransX()
Dim cnn1 As ADODB.Connection
Dim rstTitles As ADODB.Recordset
Dim strCnn As String
Dim strTitle As String
Dim strMessage As String
` Open connection.
strCnn = "driver={SQL Server};server=srv;" & _
"uid=sa;pwd=;database=pubs"
Set cnn1 = New ADODB.Connection
cnn1.Open strCnn
` Open titles table.
Set rstTitles = New ADODB.Recordset
rstTitles.CursorType = adOpenDynamic
rstTitles.LockType = adLockPessimistic
rstTitles.Open "titles", cnn1, , , adCmdTable
rstTitles.MoveFirst
cnn1.BeginTrans
` Loop through recordset and ask user if she wants
` to change the type for a specified title.
Do Until rstTitles.EOF
If Trim(rstTitles!Type) = "psychology" Then
strTitle = rstTitles!Title
strMessage = "Title: " & strTitle & vbCr & _
"Change type to self help?"
` Change the title for the specified employee.
If MsgBox(strMessage, vbYesNo) = vbYes Then
rstTitles!Type = "self_help"
Chili!Soft ASP 3.6 Product Documentation
rstTitles.Update
End If
End If
rstTitles.MoveNext
Loop
` Ask if the user wants to commit to all the
` changes made above.
If MsgBox("Save all changes?", vbYesNo) = vbYes Then
cnn1.CommitTrans
Else
cnn1.RollbackTrans
End If
` Print current data in recordset.
rstTitles.Requery
rstTitles.MoveFirst
Do While Not rstTitles.EOF
Debug.Print rstTitles!Title & " - " & rstTitles!Type
rstTitles.MoveNext
Loop
' Restore original data
rstTitles.MoveFirst
Do Until rstTitles.EOF
If Trim(rstTitles!Type) = "self_help" Then
rstTitles!Type = "psychology"
rstTitles.Update
End If
rstTitles.MoveNext
Loop
rstTitles.Close
cnn1.Close
End Sub
282
Chili!Soft ASP 3.6 Product Documentation
283
ADO Connection Object Properties
ADO Connection Object Attributes Property
One or more characteristics of an object. This property is read-only on UNIX.
Attributes Property Return Values (ADO Connection Object)
Sets or returns a Long value.
For a Connection object, the Attributes property is read/write, and its value can be the sum of
any one or more of these XactAttributeEnum values (default is zero):
Value
Description
adXactCommitRetaini Performs retaining commits, that is, calling the CommitTrans
ng
method automatically starts a new transaction. Not all providers
support this, and it is always zero under UNIX.
adXactAbortRetaining Performs retaining aborts, that is, calling the BeginTrans,
CommitTrans, and RollbackTrans methods automatically starts
a new transaction. Not all providers support this, and it is always
zero under UNIX.
Attributes Property Remarks (ADO Connection Object)
Use the Attributes property to set or return characteristics of Connection objects.
When you set multiple attributes, you can sum the appropriate constants. If you set the property
value to a sum including incompatible constants, an error occurs.
Attributes Property Examples (ADO Connection Object)
This Visual Basic example displays the value of the Attributes property for Connection objects.
It uses the ADO Field Object Name Property to display the name of each Field and Property
object.
Public Sub AttributesX
Dim cnn1 As ADODB.Connection
Dim strCnn As String
' Open connection
strCnn = "driver={SQL Server};server=srv;" & _
"uid=sa;pwd=;database=pubs"
Set cnn1 = New ADODB.Connection
cnn1.Open strCnn
' Display the attributes of the connection.
Debug.Print "Connection attributes = " & _
cnn1.Attributes
Chili!Soft ASP 3.6 Product Documentation
284
cnn1.Close
End Sub
ADO Connection Object CommandTimeout Property
How long to wait while executing a command before terminating the attempt and generating an
error.
CommandTimeout Property Return Values (ADO Connection Object)
Sets or returns a Long value that specifies, in seconds, how long to wait for a command to
execute. Default is 30.
CommandTimeout Property Remarks (ADO Connection Object)
Use the CommandTimeout property on a Connection object to allow the cancellation of an
ADO Connection Object Execute Method call, due to delays from network traffic or heavy server
use. If the interval set in the CommandTimeout property elapses before the command completes
execution, an error occurs and ADO cancels the command. If you set the property to zero, ADO
will wait indefinitely until the execution is complete. Make sure the provider and data source to
which you are writing code supports the CommandTimeout functionality.
The CommandTimeout setting on a Connection object has no effect on the CommandTimeout
setting on a Command object on the same Connection; that is, the Command object's
CommandTimeout property does not inherit the value of the Connection object's
CommandTimeout value.
On a Connection object, the CommandTimeout property remains read/write after the
Connection is opened.
CommandTimeout Property Examples (ADO Connection Object)
See the ActiveConnection property.
ADO Connection Object ConnectionString Property
Contains the information used to establish a connection to a data source.
ConnectionString Property Return Values (ADO Connection Object)
Sets or returns a String value.
ConnectionString Property Remarks (ADO Connection Object)
Use the ConnectionString property to specify a data source by passing a detailed connection
string containing a series of argument = value statements separated by semicolons.
ADO supports seven arguments for the ConnectionString property; any other arguments pass
directly to the provider without any processing by ADO. The arguments ADO supports are as
follows:
Chili!Soft ASP 3.6 Product Documentation
Argument
Description
Provider
Specifies the name of the provider to use for the connection.
DataSource
Specifies the name of a data source for the connection, for example,
an Oracle database registered as an ODBC data source.
UserID
Specifies the user name to use when opening the connection.
Password
Specifies the password to use when opening the connection.
FileName
Specifies the name of a provider-specific file (for example, a
persisted data source object) containing preset connection
information.
RemoteProvide
r
Specifies the name of a provider to use when opening a client-side
connection (Remote Data Service only).
RemoteServer
Specifies the path name of the server to use when opening a clientside connection (Remote Data Service only).
285
After you set the ConnectionString property and open the Connection object, the provider may
alter the contents of the property, for example, by mapping the ADO-defined argument names to
their provider equivalents.
The ConnectionString property automatically inherits the value used for the ConnectionString
argument of the ADO Connection Object Open Method, so you can override the current
ConnectionString property during the Open method call.
Because the File Name argument causes ADO to load the associated provider, you cannot pass
both the Provider and File Name arguments.
The ConnectionString property is read/write when the connection is closed and read-only when
it is open.
Remote Data Service Usage: When used on a client-side Connection object, the
ConnectionString property can only include the Remote Provider and Remote Server parameters.
ConnectionString Property Example (ADO Connection Object)
This Visual Basic example demonstrates different ways of using the ConnectionString property
to open a Connection object. It also uses the ConnectionTimeout property to set a connection
timeout period, and the ADO Connection Object State Property to check the state of the
connections. The GetState function is required for this procedure to run.
Public Sub ConnectionStringX()
Dim cnn1 As ADODB.Connection
Dim cnn2 As ADODB.Connection
Dim cnn3 As ADODB.Connection
Dim cnn4 As ADODB.Connection
' Open a connection without using a Data Source Name (DSN).
Chili!Soft ASP 3.6 Product Documentation
286
Set cnn1 = New ADODB.Connection
cnn1.ConnectionString = "driver={SQL Server};" & _
"server=bigsmile;uid=sa;pwd=pwd;database=pubs"
cnn1.ConnectionTimeout = 30
cnn1.Open
' Open a connection using a DSN and ODBC tags.
Set cnn2 = New ADODB.Connection
cnn2.ConnectionString = "DSN=Pubs;UID=sa;PWD=pwd;"
cnn2.Open
' Open a connection using a DSN and OLE DB tags.
Set cnn3 = New ADODB.Connection
cnn3.ConnectionString = "Data Source=Pubs;User ID=sa;Password=pwd;"
cnn3.Open
' Open a connection using a DSN and individual
' arguments instead of a connection string.
Set cnn4 = New ADODB.Connection
cnn4.Open "Pubs", "sa", "pwd"
' Display the state of the connections.
MsgBox "cnn1 state: " & GetState(cnn1.State) & vbCr & _
"cnn2 state: " & GetState(cnn1.State) & vbCr & _
"cnn3 state: " & GetState(cnn1.State) & vbCr & _
"cnn4 state: " & GetState(cnn1.State)
cnn4.Close
cnn3.Close
cnn2.Close
cnn1.Close
End Sub
Public Function GetState(intState As Integer) As String
Select Case intState
Case adStateClosed
GetState = "adStateClosed"
Case adStateOpen
Chili!Soft ASP 3.6 Product Documentation
287
GetState = "adStateOpen"
End Select
End Function
ADO Connection Object ConnectionTimeout Property
Sets how long to wait while establishing a connection before terminating the attempt and
generating an error.
ConnectionTimeout Property Return Values (ADO Connection Object)
Sets or returns a Long value that specifies, in seconds, how long to wait for the connection to
open. Default is 15.
ConnectionTimeout Property Remarks (ADO Connection Object)
Use the ConnectionTimeout property on a Connection object if delays from network traffic or
heavy server use make it necessary to abandon a connection attempt. If the time from the
ConnectionTimeout property setting elapses prior to the opening of the connection, an error
occurs and ADO cancels the attempt. If you set the property to zero, ADO will wait indefinitely
until the connection is opened. Make sure the provider to which you are writing code supports the
ConnectionTimeout functionality.
The ConnectionTimeout property is read/write when the connection is closed and read-only
when it is open.
ConnectionTimeout Property Example (ADO Connection Object)
See the ConnectionString property.
ADO Connection Object CursorLocation Property
Sets or returns the location of the cursor engine. This property is read-only on UNIX.
CursorLocation Property Return Values (ADO Connection Object)
Sets or returns a Long value that can be set to one of the following constants:
Constant
Description
adUseClient
Uses client-side cursors supplied by a local cursor library. Local cursor
engines will often allow many features that driver-supplied cursors
may not, so using this setting may provide an advantage with respect
to features that will be enabled. For backward-compatibility, the
synonym adUseClientBatch is also supported.
adUseServer
Default. Uses data provider or driver-supplied cursors. These cursors
are sometimes very flexible and allow for some additional sensitivity
to reflecting changes that others make to the actual data source.
However, some features of the Microsoft Client Cursor Provider (such
as disassociated recordsets) cannot be simulated.
Chili!Soft ASP 3.6 Product Documentation
288
CursorLocation Property Remarks (ADO Connection Object)
This property allows you to choose between various cursor libraries accessible to the provider.
Usually, you can choose between using a client-side cursor library or one that is located on the
server.
This property setting only affects connections established after the property has been set.
Changing the CursorLocation property has no effect on existing connections.
This property is read/write on a Connection.
CursorLocation Property Example (ADO Connection Object)
See the AbsolutePosition property example.
ADO Connection Object DefaultDatabase Property
The default database for a Connection object.
DefaultDatabase Property Return Values
Sets or returns a String that evaluates to the name of a database available from the provider.
DefaultDatabase Property Remarks
Use the DefaultDatabase property to set or return the name of the default database on a specific
Connection object.
If there is a default database, SQL strings may use an unqualified syntax to access objects in that
database. To access objects in a database other than the one specified in the DefaultDatabase
property, you must qualify object names with the desired database name. Upon connection, the
provider will write default database information to the DefaultDatabase property. Some
providers allow only one database per connection, in which case you cannot change the
DefaultDatabase property.
Some data sources and providers may not support this feature, and may return an error or an
empty string.
Remote Data Service Usage: This property is not available on a client-side Connection object.
DefaultDatabase Property Example
See ADO Connection Object Provider Property
ADO Connection Object IsolationLevel Property
The level of transaction isolation for a Connection object. Transactions are not currently
supported on UNIX.
IsolationLevel Property Return Values
Sets or returns one of the following IsolationLevelEnum values:
Chili!Soft ASP 3.6 Product Documentation
Constant
Description
adXactUnspecified
The provider is using a different IsolationLevel than
specified, but the level cannot be determined.
adXactChaos
You cannot overwrite pending changes from more highly
isolated transactions.
adXactBrowse
You can view uncommitted changes from one transaction in
other transactions.
adXactReadUncommitt
ed
Same as adXactBrowse.
adXactCursorStability
Default. You can view changes in other transactions only
after they have been committed.
adXactReadCommitted
Same as adXactCursorStability.
adXactRepeatableRead
You cannot see changes in other transactions, but requerying
can bring new Recordset objects.
adXactIsolated
Transactions are conducted in isolation of other transactions.
adXactSerializable
Same as adXactIsolated.
289
IsolationLevel Property Remarks
Use the IsolationLevel property to set the isolation level of a Connection object. The
IsolationLevel property is read/write. The setting does not take effect until the next time you call
the BeginTrans method. If the level of isolation you request is unavailable, the provider may
return the next greater level of isolation.
IsolationLevel Property Example
This example uses the ADO Connection Object Mode Property to open an exclusive connection,
and the IsolationLevel property to open a transaction that is conducted in isolation of other
transactions.
Public Sub IsolationLevelX()
Dim cnn1 As ADODB.Connection
Dim rstTitles As ADODB.Recordset
Dim strCnn As String
` Assign connection string to variable.
strCnn = "driver={SQL Server};server=srv;" & _
"uid=sa;pwd=;database=pubs"
` Open connection and titles table.
Set cnn1 = New ADODB.Connection
cnn1.Mode = adModeShareExclusive
Chili!Soft ASP 3.6 Product Documentation
cnn1.IsolationLevel = adXactIsolated
cnn1.Open strCnn
Set rstTitles = New ADODB.Recordset
rstTitles.CursorType = adOpenDynamic
rstTitles.LockType = adLockPessimistic
rstTitles.Open "titles", cnn1, , , adCmdTable
cnn1.BeginTrans
` Display connection mode.
If cnn1.Mode = adModeShareExclusive Then
MsgBox "Connection mode is exclusive."
Else
MsgBox "Connection mode is not exclusive."
End If
` Display isolation level.
If cnn1.IsolationLevel = adXactIsolated Then
MsgBox "Transaction is isolated."
Else
MsgBox "Transaction is not isolated."
End If
` Change the type of psychology titles.
Do Until rstTitles.EOF
If Trim(rstTitles!Type) = "psychology" Then
rstTitles!Type = "self_help"
rstTitles.Update
End If
rstTitles.MoveNext
Loop
` Print current data in recordset.
rstTitles.Requery
Do While Not rstTitles.EOF
Debug.Print rstTitles!Title & " - " & rstTitles!Type
rstTitles.MoveNext
290
Chili!Soft ASP 3.6 Product Documentation
291
Loop
` Restore original data.
cnn1.RollbackTrans
rstTitles.Close
cnn1.Close
End Sub
ADO Connection Object Mode Property
The available permissions for modifying data in a Connection.
Mode Property Return Values (ADO Connection Object)
Sets or returns one of the following ConnectModeEnum values:
Constant
Description
adModeUnknown
Default. The permissions have not been set or cannot be
determined.
adModeRead
Read-only permission.
adModeWrite
Write-only permission.
adModeReadWrite
Read/write permission.
adModeShareDenyRea
d
Prevents others from opening a connection with read
permission.
adModeShareDenyWrit
e
Prevents others from opening a connection with write
permission.
adModeShareExclusive
Prevents others from opening a connection.
adModeShareDenyNon
e
Allows others to open a connection with any permissions.
Neither read nor write access can be denied to others.
Mode Property Remarks (ADO Connection Object)
Use the Mode property to set or return the access permissions in use by the provider on the
current connection. You can set the Mode property only when the Connection object is closed.
Mode Property Example (ADO Connection Object)
See the IsolationLevel property example.
ADO Connection Object Provider Property
The name of the provider for a Connection object. This property is not available on UNIX.
Provider Property Return Values
Sets or returns a String value.
Chili!Soft ASP 3.6 Product Documentation
292
Provider Property Remarks
Use the Provider property to set or return the name of the provider for a connection. This
property can also be set by the contents of the ConnectionString property or the
ConnectionString argument of the ADO Connection Object Open Method; however, specifying a
provider in more than one place while calling the Open method can have unpredictable results. If
no provider is specified, the property will default to MSDASQL (Microsoft OLE DB Provider for
ODBC).
The Provider property is read/write when the connection is closed and read-only when it is open.
The setting does not take effect until you either open the Connection object or access the ADO
Properties Collection of the Connection object. If the setting is invalid, an error occurs.
Provider Property Example
This Visual Basic example demonstrates the Provider property by opening two Connection
objects using different providers. It also uses the DefaultDatabase property to set the default
database for the Microsoft ODBC Provider.
Public Sub ProviderX()
Dim cnn1 As ADODB.Connection
Dim cnn2 As ADODB.Connection
` Open a connection using the Microsoft ODBC provider.
Set cnn1 = New ADODB.Connection
cnn1.ConnectionString = "driver={SQL Server};" & _
"server=bigsmile;uid=sa;pwd=pwd"
cnn1.Open strCnn
cnn1.DefaultDatabase = "pubs"
` Display the provider.
MsgBox "Cnn1 provider: " & cnn1.Provider
` Open a connection using the Microsoft Jet provider.
Set cnn2 = New ADODB.Connection
cnn2.Provider = "Microsoft.Jet.OLEDB.3.51"
cnn2.Open "C:\Samples\northwind.mdb", "admin", ""
` Display the provider.
MsgBox "Cnn2 provider: " & cnn2.Provider
cnn1.Close
cnn2.Close
End Sub
Chili!Soft ASP 3.6 Product Documentation
293
ADO Connection Object State Property
Describes the current state of an object.
State Property Return Values (ADO Connection Object)
Sets or returns a Long value that can be one of the following constants:
Constant
Description
adStateClosed
Default. The object is closed.
adStateOpen
The object is open.
State Property Remarks (ADO Connection Object)
You can use the State property to determine the current state of a given object at any time.
State Property Examples (ADO Connection Object)
This Visual Basic example demonstrates different ways of using the ConnectionString property
to open a Connection object. It also uses the ConnectionTimeout property to set a connection
timeout period, and the State property to check the state of the connections. The GetState
function is required for this procedure to run.
Public Sub ConnectionStringX()
Dim cnn1 As ADODB.Connection
Dim cnn2 As ADODB.Connection
Dim cnn3 As ADODB.Connection
Dim cnn4 As ADODB.Connection
` Open a connection without using a DSN.
Set cnn1 = New ADODB.Connection
cnn1.ConnectionString = "driver={SQL Server};" & _
"server=bigsmile;uid=sa;pwd=pwd;database=pubs"
cnn1.ConnectionTimeout = 30
cnn1.Open
` Open a connection using a DSN and ODBC tags.
Set cnn2 = New ADODB.Connection
cnn2.ConnectionString = "DSN=Pubs;UID=sa;PWD=pwd;"
cnn2.Open
` Open a connection using a DSN and OLE DB tags.
Set cnn3 = New ADODB.Connection
cnn3.ConnectionString = "Data Source=Pubs;User ID=sa;Password=pwd;"
Chili!Soft ASP 3.6 Product Documentation
294
cnn3.Open
` Open a connection using a DSN and individual
` arguments instead of a connection string.
Set cnn4 = New ADODB.Connection
cnn4.Open "Pubs", "sa", "pwd"
` Display the state of the connections.
MsgBox "cnn1 state: " & GetState(cnn1.State) & vbCr &_
"cnn2 state: " & GetState(cnn1.State) & vbCr & _
"cnn3 state: " & GetState(cnn1.State) & vbCr & _
"cnn4 state: " & GetState(cnn1.State)
cnn4.Close
cnn3.Close
cnn2.Close
cnn1.Close
End Sub
Public Function GetState(intState As Integer) As String
Select Case intState
Case adStateClosed
GetState = "adStateClosed"
Case adStateOpen
GetState = "adStateOpen"
End Select
End Function
ADO Connection Object Version Property
The ADO version number.
Version Property Return Values
Returns a String value.
Version Property Remarks
Use the Version property to return the version number of the ADO implementation. The version
of the provider will be available on Windows NT servers as a dynamic property in the ADO
Properties Collection. The Properties collection is not currently supported on UNIX.
295
Chili!Soft ASP 3.6 Product Documentation
Version Property Example
This Visual Basic example uses the Version property of a Connection object to display the
current ADO version. It also uses several dynamic properties to show the current DBMS name
and version, OLE DB version, provider name and version, driver name and version, and driver
ODBC version.
Public Sub VersionX()
Dim cnn1 As ADODB.Connection
' Open connection.
Set cnn1 = New ADODB.Connection
strCnn = "driver={SQL Server};server=srv;" & _
"uid=sa;pwd=;database=pubs"
cnn1.Open strCnn
strVersionInfo = "ADO Version: " & cnn1.Version & vbCr & _
"DBMS Name: " & cnn1.Properties("DBMS Name") & vbCr & _
"DBMS Version: " & cnn1.Properties("DBMS Version") & vbCr & _
"OLE DB Version: " & cnn1.Properties("OLE DB Version") & vbCr & _
"Provider Name: " & cnn1.Properties("Provider Name") & vbCr & _
"Provider Version: " & cnn1.Properties("Provider Version") & vbCr &
_
"Driver Name: " & cnn1.Properties("Driver Name") & vbCr & _
"Driver Version: " & cnn1.Properties("Driver Version") & vbCr & _
"Driver ODBC Version: " & cnn1.Properties("Driver ODBC Version")
MsgBox strVersionInfo
cnn1.Close
End Sub
ADO Error Object
The ADO Error object provides specific details about each ADO error.
ADO Error Object Properties
ADO Error Object Description Property
A descriptive string associated with an
error.
ADO Error Object HelpContext, HelpFile
Property
The help file topic associated with an
error.
ADO Error Object HelpContext, HelpFile
The help file associated with an error.
296
Chili!Soft ASP 3.6 Product Documentation
Property
ADO Error Object NativeError Property
The provider-specific error code for an
error.
ADO Error Object Number Property
The number that uniquely identifies an
error.
ADO Error Object Source Property
The name of the object or application that
originally generated the error.
ADO Error Object SQLState Property
The SQL state for a given error.
ADO Error Object Remarks
Any operation involving ADO objects can generate one or more provider errors. As each error
occurs, one or more Error objects are placed in the ADO Errors Collection of the ADO
Connection Object. When another ADO operation generates an error, the Errors collection is
cleared, and the new set of Error objects are placed in the Errors collection.
Note
Each Error object represents a specific provider error, not an ADO error. ADO errors are
exposed to the run-time exception handling mechanism. For example, in Microsoft
Visual Basic, the occurrence of an ADO-specific error will trigger an On Error event
and appear in the Err object. For a complete list of ADO errors, see Appendix B.
Read the Error object's properties to obtain specific details about each error:
•
The ADO Error Object Description Property contains the text of the error.
•
The ADO Error Object Number Property contains the Long integer value of the error
constant.
•
The ADO Error Object Source Property identifies the object that raised the error. This is
particularly useful when you have several Error objects in the Errors collection
following a request to a data source.
•
The ADO Error Object HelpContext, and HelpFile Properties indicate the appropriate
Microsoft Windows Help file and Help topic, respectively (if any exist), for the error.
•
The ADO Error Object SQLState Property and ADO Error Object NativeError Property
properties provide information from SQL data sources.
ADO supports the return of multiple errors by a single ADO operation to allow for error
information specific to the provider. To obtain this error information in an error handler, use the
appropriate error-trapping features of the language or environment you are working with, then use
nested loops to enumerate the properties of each Error object in the Errors collection.
ADO clears the OLE Error Info object before making a call that could potentially generate a
new provider error. However, the Errors collection on the Connection object is cleared and
populated only when the provider generates a new error, or when the ADO Collections Clear
Method is called.
Chili!Soft ASP 3.6 Product Documentation
297
Some properties and methods return warnings that appear as Error objects in the Errors
collection but do not halt a program's execution. Before you call the ADO Recordset Object
Resync Method, ADO Recordset Object UpdateBatch Method, or ADO Recordset Object
CancelBatch Method methods on an ADO Recordset Object, or before you set the ADO
Recordset Object Filter Property on a Recordset object, call the ADO Collections Clear Method
on the Errors collection so that you can read the Count property of the Errors collection to test
for returned warnings.
If there is no valid Connection object when using Microsoft Visual Basic and VBScript, retrieve
error information from the Err object.
To refer to an Error object in a collection by its ordinal number, use either of the following
syntax forms:
connection.Errors.Item(0)
connection.Errors(0)
ADO Error Object Properties
ADO Error Object Description Property
A descriptive string associated with an Error object.
Description Property Return Values (ADO Error Object)
Returns a String value.
Description Property Remarks (ADO Error Object)
Use the Description property to obtain a short description of the error. Display this property to
alert the user to an error that you cannot or do not want to handle. The string will come from
either ADO or a provider.
Providers are responsible for passing specific error text to ADO. ADO adds an Error object to
the ADO Errors Collection for each provider error or warning it receives. Enumerate the Errors
collection to trace the errors that the provider passes.
Description Property Example (ADO Error Object)
This Visual Basic example triggers an error, traps it, and displays the ADO Error Object
Description Property, ADO Error Object HelpContext, and HelpFile Properties, ADO Error
Object NativeError Property, ADO Error Object Number Property, ADO Error Object Source
Property, and ADO Error Object SQLState Property properties of the resulting Error object:
Public Sub DescriptionX()
Dim cnn1 As ADODB.Connection
Dim errLoop As ADODB.Error
Dim strError As String
On Error GoTo ErrorHandler
Chili!Soft ASP 3.6 Product Documentation
` Intentionally trigger an error.
Set cnn1 = New ADODB.Connection
cnn1.Open "nothing"
Exit Sub
ErrorHandler:
` Enumerate Errors collection and display
` properties of each Error object.
For Each errLoop In cnn1.Errors
strError = "Error #" & errLoop.Number & vbCr & _
" " & errLoop.Description & vbCr & _
" (Source: " & errLoop.Source & ")" & vbCr & _
" (SQL State: " & errLoop.SQLState & ")" & vbCr & _
" (NativeError: " & errLoop.NativeError & ")" & vbCr
If errLoop.HelpFile = "" Then
strError = strError & _
" No Help file available" & _
vbCr & vbCr
Else
strError = strError & _
" (HelpFile: " & errLoop.HelpFile & ")" & vbCr & _
" (HelpContext: " & errLoop.HelpContext & ")" & _
vbCr & vbCr
End If
Debug.Print strError
Next
Resume Next
End Sub
ADO Error Object HelpContext, HelpFile Property
The help file and topic associated with an Error object.
HelpContext, HelpFile Property Return Values
HelpContextID
Returns a context ID, as a Long value, for a topic in a Microsoft Windows Help file.
298
Chili!Soft ASP 3.6 Product Documentation
299
HelpFile
Returns a String that evaluates to a fully resolved path to a Help file.
HelpContext, HelpFile Property Remarks
If a Windows Help (.hlp) file is specified in the HelpFile property, the HelpContext property is
used to automatically display the Help topic it identifies. If there is no relevant help topic
available, the HelpContext property returns zero and the HelpFile property returns a zero-length
string ("").
HelpContext, HelpFile Property Examples
See the ADO Error Object Description Property example.
ADO Error Object NativeError Property
The provider-specific error code for a given Error object.
NativeError Property Return Values
Returns a Long value.
NativeError Property Remarks
Use the NativeError property to retrieve the database-specific error information for a particular
Error object. For example, when using the Microsoft ODBC Provider for OLE DB with a SQL
Server database, native error codes that originate from SQL Server pass through ODBC and the
ODBC Provider to the ADO NativeError property.
NativeError Property Example
See the ADO Error Object Description Property.
ADO Error Object Number Property
The number that uniquely identifies an Error object.
Number Property Return Values
Returns a Long value.
Number Property Remarks
Use the Number property to determine which error occurred. The value of the property is a
unique number that corresponds to the error condition.
Number Property Example
See the ADO Error Object Description Property.
ADO Error Object Source Property
Chili!Soft ASP 3.6 Product Documentation
300
The name of the object or application that originally generated an error.
Source Property Return Values
Returns a String value.
Source Property Remarks
Use the Source property on an Error object to determine the name of the object or application
that originally generated an error. This could be the object's class name or programmatic ID. For
errors in ADODB, the property value will be ADODB.ObjectName.
Source Property Parameters (ADO Error Object)
ObjectName
The name of the object that triggered the error. The Source property is read-only for Error
objects.
Based on the error documentation from the Source, ADO Error Object Number Property, and
ADO Error Object Description Property properties of Error objects, you can write code that will
handle the error appropriately.
Source Property Example
See the ADO Error Object Description Property example.
ADO Error Object SQLState Property
The SQL state for a given Error object.
SQLState Property Return Values
Returns a five-character String that follows the ANSI SQL standard.
SQLState Property Remarks
Use the SQLState property to read the five-character error code that the provider returns when an
error occurs during the processing of a SQL statement. For example, when using the Microsoft
OLE DB Provider for ODBC with a SQL Server database, SQL state error codes originate from
ODBC based either on errors specific to ODBC or on errors that originate from Microsoft SQL
Server, and are then mapped to ODBC errors. These error codes are documented in the ANSI
SQL standard, but may be implemented differently by different data sources.
SQLState Property Example
See the ADO Error Object Description Property example.
ADO Field Object
The ADO Field Object represents a column of data with a common data type.
Chili!Soft ASP 3.6 Product Documentation
301
ADO Field Object Collections
ADO Properties Collection
All Property objects for a specific instance of a Field
object. This collection is not currently supported on
UNIX.
ADO Field Object Methods
ADO Field Object AppendChunk
Method
Appends data to a large text or binary data field.
ADO Field Object GetChunk
Method
Returns all or a portion of the contents of a large text or
binary data field.
ADO Field Object Properties
ADO Field Object ActualSize
Property
The actual length of a field value.
ADO Field Object Attributes
Property
One or more characteristics of a field. This property is
read-only on UNIX.
ADO Field Object DefinedSize
Property
The defined size of a field.
ADO Field Object Name Property
The name of a field.
ADO Field Object NumericScale
Property
The scale of numeric values in a field.
ADO Field Object OriginalValue
Property
The value of a field that existed in the record before any
changes were made.
ADO Field Object Precision
Property
The degree of precision for numeric values in a field.
ADO Field Object Type Property
The data type of the field.
ADO Field Object
UnderlyingValue Property
The current value of the field in the database.
ADO Field Object Value Property
The value assigned to the field.
ADO Field Object Remarks
A ADO Recordset Object has an ADO Fields Collection made up of Field objects. Each Field
object corresponds to a column in the recordset. You use the ADO Field Object Value Property of
Field objects to set or return data for the current record. Depending on the functionality the
provider exposes, some collections, methods, or properties of a Field object may not be available.
The collections, methods, and properties of a Field object are used to:
•
return the name of a field with the ADO Field Object Name Property.
•
view or change the data in the field with the ADO Field Object Value Property.
Chili!Soft ASP 3.6 Product Documentation
302
•
return the basic characteristics of a field with the ADO Field Object Type Property, ADO
Field Object Precision Property, and ADO Field Object NumericScale Property properties.
•
return the declared size of a field with the ADO Field Object DefinedSize Property.
•
return the actual size of the data in a given field with the ADO Field Object ActualSize
Property.
•
determine what types of functionality are supported for a given field with the ADO Field
Object Attributes Property and ADO Properties Collection.
•
manipulate the values of fields containing long binary or long character data with the
ADO Field Object AppendChunk Method and ADO Field Object GetChunk Method
methods.
•
resolve discrepancies in field values during batch updating with the ADO Field Object
OriginalValue Property and UnderlyingValue properties (if the provider supports batch
updates).
Note
All metadata properties (Name, Type, DefinedSize, Precision, and NumericScale) are
available before opening the Field object's recordset. Setting them at that time is useful
for dynamically constructing forms.
ADO Field Object Methods
ADO Field Object AppendChunk Method
Appends data to a large text or binary data Field object.
AppendChunk Method Syntax (ADO Field Object)
object.AppendChunk Data
AppendChunk Method Parameters (ADO Field Object)
object
A Field object.
Data
A Variant containing the data you want to append to the object.
AppendChunk Method Remarks (ADO Field Object)
Use the AppendChunk method on a Field object to fill it with long binary or character data. In
situations where system memory is limited, you can use the AppendChunk method to
manipulate long values in portions rather than in their entirety.
If the adFldLong bit in the ADO Field Object Attributes Property of a Field object is set to
True, you can use the AppendChunk method for that field.
Chili!Soft ASP 3.6 Product Documentation
303
The first AppendChunk call on a Field object writes data to the field, overwriting any existing
data. Subsequent AppendChunk calls add to existing data. If you are appending data to one field
and then you set or read the value of another field in the current record, ADO assumes that you
are done appending data to the first field. If you call the AppendChunk method on the first field
again, ADO interprets the call as a new AppendChunk operation and overwrites the existing
data. Accessing fields in other ADO Recordset Object objects (that are not clones of the first
Recordset object) will not disrupt AppendChunk operations.
If there is no current record when you call AppendChunk on a Field object, an error occurs.
AppendChunk Method Examples (ADO Field Object)
See the ADO Field Object GetChunk Method example.
ADO Field Object GetChunk Method
Returns all or a portion of the contents of a large text or binary data Field object.
GetChunk Method Syntax (ADO Field Object)
variable = field.GetChunk( Size )
GetChunk Method Parameters (ADO Field Object)
variable
Variant to hold data returned.
Size
A Long expression equal to the number of bytes or characters you want to retrieve.
GetChunk Method Remarks (ADO Field Object)
Use the GetChunk method on a Field object to retrieve part or all of its long binary or character
data. In situations where system memory is limited, you can use the GetChunk method to
manipulate long values in portions rather than in their entirety.
The data a GetChunk call returns is assigned to variable. If Size is greater than the remaining
data, the GetChunk method returns only the remaining data without padding variable with empty
spaces. If the field is empty, the GetChunk method returns Null.
Each subsequent GetChunk call retrieves data starting from where the previous GetChunk call
left off. However, if you are retrieving data from one field and then you set or read the value of
another field in the current record, ADO assumes you are done retrieving data from the first field.
If you call the GetChunk method on the first field again, ADO interprets the call as a new
GetChunk operation and starts reading from the beginning of the data. Accessing fields in other
ADO Recordset Object objects (that are not clones of the first Recordset object) will not disrupt
GetChunk operations.
If the adFldLong bit in the ADO Field Object Attributes Property of a Field object is set to
True, you can use the GetChunk method for that field.
Chili!Soft ASP 3.6 Product Documentation
304
If there is no current record when you use the GetChunk method on a Field object, error 3021
(no current record) occurs.
GetChunk Method Return Values (ADO Field Object)
Returns a Variant.
GetChunk Method Example (ADO Field Object)
See the ADO Field Object AppendChunk Method.
ADO Field Object Properties
ADO Field Object ActualSize Property
The actual length of a field's value.
ActualSize Property Return Values (ADO Field Object)
Returns a Long value. Some providers may allow this property to be set to reserve space for
BLOB data, in which case the default value is 0.
ActualSize Property Remarks (ADO Field Object)
Use the ActualSize property to return the actual length of a Field object's value. For all fields, the
ActualSize property is read-only. If ADO cannot determine the length of the Field object's value,
the ActualSize property returns adUnknown.
The ActualSize and ADO Field Object DefinedSize Property properties are different as shown in
the following example: a Field object with a declared type of adVarChar and a maximum length
of 50 characters returns a DefinedSize property value of 50, but the ActualSize property value it
returns is the length of the data stored in the field for the current record.
ActualSize Property Example (ADO Field Object)
This Visual Basic example uses the ActualSize and DefinedSize properties to display the defined
size and actual size of a field.
Public Sub ActualSizeX()
Dim rstStores As ADODB.Recordset
Dim strCnn As String
' Open a recordset for the Stores table.
strCnn = "driver={SQL Server};server=srv;" & _
"uid=sa;pwd=;database=pubs"
Set rstStores = New ADODB.Recordset
rstStores.Open "stores", strCnn, , , adCmdTable
' Loop through the recordset displaying the contents
Chili!Soft ASP 3.6 Product Documentation
305
' of the stor_name field, the field's defined size,
' and its actual size.
rstStores.MoveFirst
Do Until rstStores.EOF
MsgBox "Store name: " & rstStores!stor_name & _
vbCr & "Defined size: " & _
rstStores!stor_name.DefinedSize & _
vbCr & "Actual size: " & _
rstStores!stor_name.ActualSize & vbCr
rstStores.MoveNext
Loop
rstStores.Close
End Sub
ADO Field Object Attributes Property
One or more characteristics of an object. This property is read-only on UNIX.
Attributes Property Return Values (ADO Field Object)
Sets or returns a Long value.
Attributes Property Field (ADO Field Object)
For a Field object, the Attributes property is read-only, and its value can be the sum of any one
or more of these FieldAttributeEnum values:
Value
Description
adFldMayDefer
The field is deferred; that is, the field values are not retrieved
from the data source with the whole record, but only when you
explicitly access them.
adFldUpdatable
The field can be written.
adFldUnknownUpdatabl The provider cannot determine if the field can be written.
e
adFldFixed
The field contains fixed-length data.
adFldIsNullable
The field accepts Null values.
adFldMayBeNull
You can read Null values from the field.
adFldLong
The field is a long binary field. Also indicates that you can use
the ADO Field Object AppendChunk Method and ADO Field
Object GetChunk Method methods.
Chili!Soft ASP 3.6 Product Documentation
adFldRowID
The field contains some kind of record ID (record number,
unique identifier, and so forth).
adFldRowVersion
The field contains some kind of time or date stamp used to track
updates.
adFldCacheDeferred
The provider caches field values and subsequent reads are done
from the cache.
306
Attributes Property Remarks (ADO Field Object)
Use the Attributes property to set or return characteristics of Field objects.
When you set multiple attributes, you can sum the appropriate constants. If you set the property
value to a sum including incompatible constants, an error occurs.
ADO Field Object DefinedSize Property
The defined size of a Field object.
DefinedSize Property Return Values (ADO Field Object)
Returns a Long value that reflects the defined size of a field as a number of bytes.
DefinedSize Property Remarks (ADO Field Object)
Use the DefinedSize property to determine the data capacity of a Field object.
The DefinedSize and ADO Field Object ActualSize Property properties are different. For
example, consider a Field object with a declared type of adVarChar and a DefinedSize property
value of 50, containing a single character. The ActualSize property value it returns is the length
in bytes of the single character.
DefinedSize Property Examples (ADO Field Object)
See the ADO Field Object ActualSize Property example.
ADO Field Object Name Property
The name of an object.
Name Property Return Values (ADO Field Object)
Sets or returns a String value. The value is read-only on a Field object.
Name Property Remarks (ADO Field Object)
Use the Name property to retrieve the name of a Field object.
The Name property is read-only. Names do not have to be unique within a collection.
Name Property Examples (ADO Field Object)
See the ADO Field Object Attributes Property example.
Chili!Soft ASP 3.6 Product Documentation
307
ADO Field Object NumericScale Property
The scale of Numeric values in a Field object.
NumericScale Property Return Values (ADO Field Object)
Sets or returns a Byte value, indicating the number of decimal places to which numeric values
will be resolved
NumericScale Property Remarks (ADO Field Object)
Use the NumericScale property to determine how many digits to the right of the decimal point
will be used to represent values for a numeric Field object.
The NumericScale property is read-only.
ADO Field Object OriginalValue Property
The value of a Field object that existed in the record before any changes were made.
OriginalValue Property Return Values (ADO Field Object)
Returns a Variant value.
OriginalValue Property Remarks (ADO Field Object)
Use the OriginalValue property to return the original field value for a field from the current
record.
In immediate update mode (the provider writes changes to the underlying data source once you
call the ADO Recordset Object Update Method), the OriginalValue property returns the field
value that existed prior to any changes (that is, since the last Update method call). This is the
same value that the ADO Recordset Object CancelUpdate Method uses to replace the ADO Field
Object Value Property.
In batch update mode (the provider caches multiple changes and writes them to the underlying
data source only when you call the ADO Recordset Object UpdateBatch Method), the
OriginalValue property returns the field value that existed prior to any changes (that is, since the
last UpdateBatch method call). This is the same value that the ADO Recordset Object
CancelBatch Method uses to replace the Value property. When you use this property with the
UnderlyingValue property, you can resolve conflicts that arise from batch updates. Batch
updates are currently not supported on UNIX.
OriginalValue Property Example (ADO Field Object)
This Visual Basic example demonstrates the OriginalValue and UnderlyingValue properties by
displaying a message if a record's underlying data has changed during a ADO Recordset Object
batch update.
Public Sub OriginalValueX()
Dim cnn1 As ADODB.Connection
Chili!Soft ASP 3.6 Product Documentation
Dim rstTitles As ADODB.Recordset
Dim fldType As ADODB.Field
Dim strCnn As String
' Open connection.
Set cnn1 = New ADODB.Connection
strCnn = "driver={SQL Server};server=srv;" & _
"uid=sa;pwd=;database=pubs"
cnn1.Open strCnn
' Open recordset for batch update.
Set rstTitles = New ADODB.Recordset
Set rstTitles.ActiveConnection = cnn1
rstTitles.CursorType = adOpenKeyset
rstTitles.LockType = adLockBatchOptimistic
rstTitles.Open "titles"
' Set field object variable for Type field.
Set fldType = rstTitles!Type
' Change the type of psychology titles.
Do Until rstTitles.EOF
If Trim(fldType) = "psychology" Then
fldType = "self_help"
End If
rstTitles.MoveNext
Loop
' Similate a change by another user by updating
' data using a command string.
cnn1.Execute "UPDATE titles SET type = 'sociology' " & _
"WHERE type = 'psychology'"
'Check for changes.
rstTitles.MoveFirst
Do Until rstTitles.EOF
If fldType.OriginalValue <> _
fldType.UnderlyingValue Then
308
Chili!Soft ASP 3.6 Product Documentation
309
MsgBox "Data has changed!" & vbCr & vbCr & _
" Title ID: " & rstTitles!title_id & vbCr & _
" Current value: " & fldType & vbCr & _
" Original value: " & _
fldType.OriginalValue & vbCr & _
" Underlying value: " & _
fldType.UnderlyingValue & vbCr
End If
rstTitles.MoveNext
Loop
' Cancel the update because this is a demonstration.
rstTitles.CancelBatch
rstTitles.Close
' Restore original values.
cnn1.Execute "UPDATE titles SET type = 'psychology' " & _
"WHERE type = 'sociology'"
cnn1.Close
End Sub
ADO Field Object Precision Property
The degree of precision for numeric Field objects.
Precision Property Return Values (ADO Field Object)
Sets or returns a Byte value, indicating the maximum total number of digits used to represent
values. The value is read-only on a Field object.
Precision Property Remarks (ADO Field Object)
Use the Precision property to determine the maximum number of digits used to represent values
for a numeric Field object.
Precision Property Example (ADO Field Object)
See the ADO Field Object NumericScale Property.
ADO Field Object Type Property
The operational type or data type of a Field object.
Chili!Soft ASP 3.6 Product Documentation
310
Type Property Return Values (ADO Field Object)
Sets or returns one of the following DataTypeEnum values. The corresponding OLE DB type
indicators are as follows:
Constant
Description
adArray
Or'd together with another type to indicate that the data is a safe-array
of that type (DBTYPE_ARRAY).
adBigInt
An 8-byte signed integer (DBTYPE_I8).
adBinary
A binary value (DBTYPE_BYTES).
adBoolean
A Boolean value (DBTYPE_BOOL).
adByRef
Or'd together with another type to indicate that the data is a pointer to
data of the other type (DBTYPE_BYREF).
adBSTR
A null-terminated character string (Unicode) (DBTYPE_BSTR).
adChar
A String value (DBTYPE_STR).
adCurrency
A currency value (DBTYPE_CY). Currency is a fixed-point number
with 4 digits to the right of the decimal point. It is stored in an 8-byte
signed integer scaled by 10,000.
adDate
A date value (DBTYPE_DATE). A date is stored as a Double, the
whole part of which is the number of days since December 30, 1899,
and the fractional part of which is the fraction of a day.
adDBDate
A date value (yyyymmdd) (DBTYPE_DBDATE).
adDBTime
A time value (hhmmss) (DBTYPE_DBTIME).
adDBTimeStamp A date-time stamp (yyyymmddhhmmss plus a fraction in billionths)
(DBTYPE_DBTIMESTAMP).
adDecimal
An exact numeric value with a fixed precision and scale
(DBTYPE_DECIMAL).
adDouble
A double-precision floating point value (DBTYPE_R8).
adEmpty
No value was specified (DBTYPE_EMPTY).
adError
A 32-bit error code (DBTYPE_ERROR).
adGUID
A globally unique identifier (GUID) (DBTYPE_GUID).
adIDispatch
A pointer to an IDispatch interface on an OLE object
(DBTYPE_IDISPATCH).
adInteger
A 4-byte signed integer (DBTYPE_I4).
adIUnknown
A pointer to an IUnknown interface on an OLE object
(DBTYPE_IUNKNOWN).
adNumeric
An exact numeric value with a fixed precision and scale
(DBTYPE_NUMERIC).
Chili!Soft ASP 3.6 Product Documentation
adSingle
A single-precision floating point value (DBTYPE_R4).
adSmallInt
A 2-byte signed integer (DBTYPE_I2).
adTinyInt
A 1-byte signed integer (DBTYPE_I1).
311
adUnsignedBigIn An 8-byte unsigned integer (DBTYPE_UI8).
t
adUnsignedInt
A 4-byte unsigned integer (DBTYPE_UI4).
adUnsignedSmall A 2-byte unsigned integer (DBTYPE_UI2).
Int
adUnsignedTinyI A 1-byte unsigned integer (DBTYPE_UI1).
nt
adUserDefined
A user-defined variable (DBTYPE_UDT).
adVariant
An Automation Variant (DBTYPE_VARIANT).
adVector
OR'd together with another type to indicate that the data is a
DBVECTOR structure, as defined by OLE DB, that contains a count
of elements and a pointer to data of the other type
(DBTYPE_VECTOR).
adWChar
A null-terminated Unicode character string (DBTYPE_WSTR).
Type Property Remarks (ADO Field Object)
For Field objects, the Type property is read-only.
Type Property Example (ADO Field Object)
This example demonstrates the Type property by displaying the name of the constant
corresponding to the value of the Type property of all the Field objects in the Employees table.
The FieldType function is required for this procedure to run.
Public Sub TypeX()
Dim rstEmployees As ADODB.Recordset
Dim fldLoop As ADODB.Field
Dim strCnn As String
` Open recordset with data from Employee table.
strCnn = "driver={SQL Server};server=srv;" & _
"uid=sa;pwd=;database=pubs"
Set rstEmployees = New ADODB.Recordset
rstEmployees.Open "employee", strCnn, , , adCmdTable
Debug.Print "Fields in Employee Table:" & vbCr
` Enumerate Fields collection of Employees table.
Chili!Soft ASP 3.6 Product Documentation
312
For Each fldLoop In rstEmployees.Fields
Debug.Print " Name: " & fldLoop.Name & vbCr & _
" Type: " & FieldType(fldLoop.Type) & vbCr
Next fldLoop
End Sub
Public Function FieldType(intType As Integer) As String
Select Case intType
Case adChar
FieldType = "adChar"
Case adVarChar
FieldType = "adVarChar"
Case adSmallInt
FieldType = "adSmallInt"
Case adUnsignedTinyInt
FieldType = "adUnsignedTinyInt"
Case adDBTimeStamp
FieldType = "adDBTimeStamp"
End Select
End Function
ADO Field Object UnderlyingValue Property
A Field object's current value in the database.
UnderlyingValue Property Return Values (ADO Field Object)
Returns a Variant value.
UnderlyingValue Property Remarks (ADO Field Object)
Use the UnderlyingValue property to return the current field value from the database. The field
value in the UnderlyingValue property is the value that is visible to your transaction and may be
the result of a recent update by another transaction. This may differ from the ADO Field Object
OriginalValue Property, which reflects the value that was originally returned to the ADO
Recordset Object.
This is similar to using the ADO Recordset Object Resync Method, but the UnderlyingValue
property returns only the value for a specific field from the current record. This is the same value
that the Resync method uses to replace the ADO Field Object Value Property.
Chili!Soft ASP 3.6 Product Documentation
313
When you use this property with the OriginalValue property, you can resolve conflicts that arise
from batch updates.
UnderlyingValue Property Example (ADO Field Object)
See the ADO Field Object OriginalValue Property example.
ADO Field Object Value Property
Indicates the value assigned to a Field object.
Value Property Return Values (ADO Field Object)
Sets or returns a Variant value. Default value depends on the ADO Field Object Type Property.
Value Property Remarks (ADO Field Object)
Use the Value property to set or return data from Field objects. ADO allows setting and returning
long binary data with the Value property.
Value Property Example (ADO Field Object)
This Visual Basic example demonstrates the Value property with Field and Property objects by
displaying field and property values for the Employees table.
Public Sub ValueX()
Dim rstEmployees As ADODB.Recordset
Dim fldLoop As ADODB.Field
Dim prpLoop As ADODB.Property
Dim strCnn As String
' Open recordset with data from Employee table.
strCnn = "driver={SQL Server};server=srv;" & _
"uid=sa;pwd=;database=pubs"
Set rstEmployees = New ADODB.Recordset
rstEmployees.Open "employee", strCnn, , , adCmdTable
Debug.Print "Field values in rstEmployees"
' Enumerate the Fields collection of the Employees
' table.
For Each fldLoop In rstEmployees.Fields
` Because Value is the default property of a
` Field object, the use of the actual keyword
` here is optional.
314
Chili!Soft ASP 3.6 Product Documentation
Debug.Print " " & fldLoop.Name & " = " &
fldLoop.Value
Next fldLoop
Debug.Print "Property values in rstEmployees"
' Enumerate the Properties collection of the
' Recordset object.
For Each prpLoop In rstEmployees.Properties
' Because Value is the default property of a
' Property object, the use of the actual keyword
' here is optional.
Debug.Print " " & prpLoop.Name & " = " &
prpLoop.Value
Next prpLoop
rstEmployees.Close
End Sub
ADO Parameter Object
The ADO Parameter Object represents a parameter or argument associated with a Command
object based on a parameterized query or stored procedure.
ADO Parameter Object Collections
ADO Properties Collection
All the Property objects for a specific instance of a
Parameter object. This collection is not currently
supported on UNIX.
ADO Parameter Object Methods
ADO Parameter Object AppendChunk
Method
Appends data to a large text or binary data parameter.
ADO Parameter Object Properties
ADO Parameter Object Attributes
Property
One or more characteristics of a parameter. This
property is currently read-only on UNIX.
ADO Parameter Object Direction
Property
Indicates if the parameter is an input parameter, an
output parameter, or both; or if the parameter is the
output of a stored procedure.
ADO Parameter Object Name Property
The name of the parameter.
315
Chili!Soft ASP 3.6 Product Documentation
ADO Parameter Object NumericScale
Property
The scale of numeric values in the parameter.
ADO Parameter Object Precision
Property
The degree of precision for numeric values in the
parameter.
ADO Parameter Object Size Property
The maximum size, in bytes or characters, of a
parameter.
ADO Parameter Object Type Property
The data type of the parameter.
ADO Parameter Object Value Property
The value assigned to the parameter.
ADO Parameter Object Remarks
The Properties collection is not currently supported on UNIX.
Many providers support parameterized commands. These are commands where the desired action
is defined once, but variables (or parameters) are used to alter some details of the command. For
example, an SQL SELECT statement could use a parameter to define the matching criteria of a
WHERE clause, and another to define the column name for a SORT BY clause.
The Parameter objects represent parameters associated with parameterized queries, or the in/out
arguments and the return values of stored procedures. Depending on the functionality of the
provider, some collections, methods, or properties of a Parameter object may not be available.
The collections, methods, and properties of a Parameter object are used to:
•
set or return the name of a parameter with the ADO Parameter Object Name Property.
•
set or return the value of a parameter with the ADO Parameter Object Value Property.
•
set or return parameter characteristics with the ADO Parameter Object Attributes
Property, ADO Parameter Object Direction Property, ADO Parameter Object Precision
Property, ADO Parameter Object NumericScale Property, ADO Parameter Object Size
Property, and ADO Parameter Object Type Property properties.
•
pass long binary or character data to a parameter with the ADO Parameter Object
AppendChunk Method.
If you know the names and properties of the parameters associated with the stored procedure or
parameterized query you wish to call, you can use the CreateParameter method to create
Parameter objects with the appropriate property settings and use the ADO Collections Append
Method to add them to the ADO Parameters Collection. This lets you set and return parameter
values without having to call the ADO Collections Refresh Method on the Parameters collection
to retrieve the parameter information from the provider, a potentially resource-intensive
operation.
ADO Parameter Object Methods
ADO Parameter Object AppendChunk Method
Appends data to a large text or binary data Parameter object.
Chili!Soft ASP 3.6 Product Documentation
316
AppendChunk Method Syntax (ADO Parameter Object)
object.AppendChunk Data
AppendChunk Method Parameters (ADO Parameter Object)
object
A Parameter object.
Data
A Variant containing the data you want to append to the object.
AppendChunk Method Remarks (ADO Parameter Object)
Use the AppendChunk method on a Parameter object to fill it with long binary or character
data. In situations where system memory is limited, you can use the AppendChunk method to
manipulate long values in portions rather than in their entirety.
If the adFldLong bit in the ADO Parameter Object Attributes Property of a Parameter object is
set to True, you can use the AppendChunk method for that parameter.
The first AppendChunk call on a Parameter object writes data to the parameter, overwriting
any existing data. Subsequent AppendChunk calls on a Parameter object adds to existing
parameter data. An AppendChunk call that passes a Null value generates an error; you must
manually set the ADO Parameter Object Value Property of the Parameter object to a zero-length
string ("") in order to clear its value.
ADO Parameter Object Properties
ADO Parameter Object Attributes Property
One or more characteristics of an object. This property is read-only on UNIX.
Attributes Property Return Values (ADO Parameter Object)
Sets or returns a Long value.
Attributes Property Parameters (ADO Parameter Object)
For an ADO Parameter Object, the Attributes property is read/write, and its value can be the sum
of any one or more of these ParameterAttributesEnum values:
Value
Description
adParamSigned
Default. The parameter accepts signed values.
adParamNullable
The parameter accepts Null values.
adParamLong
The parameter accepts long binary data.
Attributes Property Remarks (ADO Parameter Object)
Use the Attributes property to set or return characteristics of Parameter objects.
Chili!Soft ASP 3.6 Product Documentation
317
When you set multiple attributes, you can sum the appropriate constants. If you set the property
value to a sum including incompatible constants, an error occurs.
Attributes Property Examples (ADO Parameter Object)
This Visual Basic example displays the value of the Attributes property for Connection, Field,
and Property objects. It uses the ADO Parameter Object Name Property to display the name of
each Field and Property object.
Public Sub AttributesX
Dim cnn1 As ADODB.Connection
Dim rstEmployees As ADODB.Recordset
Dim fldLoop As ADODB.Field
Dim proLoop As ADODB.Property
Dim strCnn As String
' Open connection and recordset.
strCnn = "driver={SQL Server};server=srv;" & _
"uid=sa;pwd=;database=pubs"
Set cnn1 = New ADODB.Connection
cnn1.Open strCnn
Set rstEmployees = New ADODB.Recordset
rstEmployees.Open "employee", cnn1, , ,
adCmdTable
' Display the attributes of the connection.
Debug.Print "Connection attributes = " & _
cnn1.Attributes
' Display attributes of the Employee table fields
Debug.Print "Field attributes:"
For Each fldLoop In rstEmployees.Fields
Debug.Print " " & fldLoop.Name & " = " & _
fldLoop.Attributes
Next fldLoop
' Display attributes of the Employee table properties.
Debug.Print "Property attributes:"
For Each proLoop In rstEmployees.Properties
Debug.Print " " & proLoop.Name & " = " & _
Chili!Soft ASP 3.6 Product Documentation
318
proLoop.Attributes
Next proLoop
rstEmployees.Close
cnn1.Close
End Sub
ADO Parameter Object Direction Property
Indicates whether the Parameter object represents an input parameter, an output parameter, or
both, or if the parameter is the return value from a stored procedure.
Direction Property Return Values
Sets or returns one of the following ParameterDirectionEnum values
Constant
Description
AdParamInput
Default. Indicates an input parameter.
AdParamOutput
Indicates an output parameter.
AdParamInputOutput
Indicates a two-way parameter.
AdParamReturnValue
Indicates a return value.
Direction Property Remarks
Use the Direction property to specify how a parameter is passed to or from a procedure. The
Direction property is read/write; this allows you to work with providers that do not return this
information, or to set this information when you do not want ADO to make an extra call to the
provider to retrieve parameter information.
Not all providers can determine the direction of parameters in their stored procedures. In these
cases, you must set the Direction property prior to executing the query.
ADO Parameter Object Name Property
The name of an object.
Name Property Return Values (ADO Parameter Object)
Sets or returns a String value. The value is read/write on a Parameter object.
Name Property Remarks (ADO Parameter Object)
Use the Name property to assign a name to or retrieve the name of a Parameter object.
For Parameter objects not yet appended to the ADO Parameters Collection, the Name property
is read/write. For appended Parameter objects and all other objects, the Name property is readonly. Names do not have to be unique within a collection.
ADO Parameter Object NumericScale Property
Chili!Soft ASP 3.6 Product Documentation
319
The scale of Numeric values in a Parameter object.
NumericScale Property Return Values
Sets or returns a Byte value, indicating the number of decimal places to which numeric values
will be resolved.
NumericScale Property Remarks
Use the NumericScale property to determine how many digits to the right of the decimal point
will be used to represent values for a numeric Parameter object.
For Parameter objects, the NumericScale property is read/write.
ADO Parameter Object Precision Property
The degree of precision for Numeric values in a Parameter object.
Precision Property Return Values (ADO Parameter Object)
Sets or returns a Byte value, indicating the maximum total number of digits used to represent
values. The value is read/write on a Parameter object.
Precision Property Remarks (ADO Parameter Object)
Use the Precision property to determine the maximum number of digits used to represent values
for a numeric Parameter object.
ADO Parameter Object Size Property
The maximum size, in bytes or characters, of a Parameter object.
Size Property Return Values (ADO Parameter Object)
Sets or returns a Long value that indicates the maximum size in bytes or characters of a value in a
Parameter object.
Size Property Remarks (ADO Parameter Object)
Use the Size property to determine the maximum size for values written to or read from the ADO
Parameter Object Value Property of a Parameter object. The Size property is read/write. If you
specify a variable-length data type for a Parameter object, you must set the object's Size
property before appending it to the ADO Parameters Collection; otherwise an error occurs. If you
have already appended the Parameter object to the Parameters collection of an ADO Command
Object and you change its type to a variable-length data type, you must set the Parameter
object's Size property before executing the Command object; otherwise an error occurs.
If you use the ADO Collections Refresh Method to obtain parameter information from the
provider and it returns one or more variable-length data type Parameter objects, ADO may
allocate memory for the parameters based on their maximum potential size, which could cause an
error during execution. To prevent an error, you should explicitly set the Size property for these
parameters before executing the command.
Chili!Soft ASP 3.6 Product Documentation
320
Size Property Example (ADO Parameter Object)
See ActiveConnection property example.
ADO Parameter Object Type Property
The operational type or data type of a Parameter object.
Type Property Return Values (ADO Parameter Object)
Sets or returns one of the following DataTypeEnum values. The corresponding OLE DB type
indicators are as follows:
Constant
Description
adArray
Or'd together with another type to indicate that the data is a safearray of that type (DBTYPE_ARRAY).
adBigInt
An 8-byte signed integer (DBTYPE_I8).
adBinary
A binary value (DBTYPE_BYTES).
adBoolean
A Boolean value (DBTYPE_BOOL).
adByRef
Or'd together with another type to indicate that the data is a pointer
to data of the other type (DBTYPE_BYREF).
adBSTR
A null-terminated character string (Unicode) (DBTYPE_BSTR).
adChar
A String value (DBTYPE_STR).
adCurrency
A currency value (DBTYPE_CY). Currency is a fixed-point number
with 4 digits to the right of the decimal point. It is stored in an 8-byte
signed integer scaled by 10,000.
adDate
A date value (DBTYPE_DATE). A date is stored as a Double, the
whole part of which is the number of days since December 30, 1899,
and the fractional part of which is the fraction of a day.
adDBDate
A date value (yyyymmdd) (DBTYPE_DBDATE).
adDBTime
A time value (hhmmss) (DBTYPE_DBTIME).
adDBTimeStamp
A date-time stamp (yyyymmddhhmmss plus a fraction in billionths)
(DBTYPE_DBTIMESTAMP).
adDecimal
An exact numeric value with a fixed precision and scale
(DBTYPE_DECIMAL).
adDouble
A double-precision floating point value (DBTYPE_R8).
adEmpty
No value was specified (DBTYPE_EMPTY).
adError
A 32-bit error code (DBTYPE_ERROR).
adGUID
A globally unique identifier (GUID) (DBTYPE_GUID).
adIDispatch
A pointer to an IDispatch interface on an OLE object
Chili!Soft ASP 3.6 Product Documentation
(DBTYPE_IDISPATCH).
adInteger
A 4-byte signed integer (DBTYPE_I4).
adIUnknown
A pointer to an IUnknown interface on an OLE object
(DBTYPE_IUNKNOWN).
adLongVarBinary A long binary value.
adLongVarChar
A long String value.
adLongVarWChar A long null-terminated string value.
adNumeric
An exact numeric value with a fixed precision and scale
(DBTYPE_NUMERIC).
adSingle
A single-precision floating point value (DBTYPE_R4).
adSmallInt
A 2-byte signed integer (DBTYPE_I2).
adTinyInt
A 1-byte signed integer (DBTYPE_I1).
adUnsignedBigInt An 8-byte unsigned integer (DBTYPE_UI8).
adUnsignedInt
A 4-byte unsigned integer (DBTYPE_UI4).
adUnsignedSmallIn A 2-byte unsigned integer (DBTYPE_UI2).
t
adUnsignedTinyInt A 1-byte unsigned integer (DBTYPE_UI1).
adUserDefined
A user-defined variable (DBTYPE_UDT).
adVarBinary
A binary value.
adVarChar
A String value.
adVariant
An Automation Variant (DBTYPE_VARIANT).
adVector
OR'd together with another type to indicate that the data is a
DBVECTOR structure, as defined by OLE DB, that contains a count
of elements and a pointer to data of the other type
(DBTYPE_VECTOR).
adVarWChar
A null-terminated Unicode character string.
adWChar
A null-terminated Unicode character string (DBTYPE_WSTR).
Type Property Remarks (ADO Parameter Object)
For Parameter objects, the Type property is read/write.
ADO Parameter Object Value Property
Indicates the value assigned to a Parameter object.
Value Property Return Values (ADO Parameter Object)
321
Chili!Soft ASP 3.6 Product Documentation
322
Sets or returns a Variant value. Default value depends on the ADO Parameter Object Type
Property.
Value Property Remarks (ADO Parameter Object)
Use the Value property to set or return parameter values with Parameter objects.
ADO allows setting and returning long binary data with the Value property.
ADO Property Object
The ADO Property object represents a dynamic characteristic of an ADO object that is defined
by the provider. This object is not currently supported on UNIX.[0]
ADO Property Object Properties
ADO Property Object Attributes
Property
One or more characteristics of a
property.
ADO Property Object Name
Property
The name of the property.
ADO Property Object Type Property
The operational or data type of the
property.
ADO Property Object Value
Property
The value assigned to the property.
ADO Property Object Remarks
ADO objects have two types of properties: built-in and dynamic. Built-in properties are those
properties implemented in ADO and immediately available to any new object, using the familiar
MyObject.Property syntax.
Built-in properties do not appear as Property objects in an object's ADO Properties Collection,
so while you can change their values, you cannot modify their characteristics or delete them.
Dynamic properties are defined by the underlying data provider, and appear in the Properties
collection for the appropriate ADO object. For example, a property specific to the provider may
indicate if an ADO Recordset Object supports transactions or updating. These additional
properties will appear as Property objects in that Recordset object's Properties collection.
Dynamic properties can be referenced only through the collection, using the
MyObject.Properties(0) or MyObject.Properties("Name") syntax.
A dynamic Property object has four built-in properties:
•
The ADO Property Object Name Property is a string that identifies the property.
•
The ADO Property Object Type Property is an integer that specifies the property data
type.
•
The ADO Property Object Value Property is a variant that contains the property setting.
Chili!Soft ASP 3.6 Product Documentation
•
323
The ADO Property Object Attributes Property is a long value that indicates characteristics
of the property specific to the provider.
ADO Property Object Properties
ADO Property Object Attributes Property
One or more characteristics of an object.
Attributes Property Return Values (ADO Property Object)
Sets or returns a Long value.
Attributes Property Property (ADO Property Object)
For a Property object, the Attributes property is read-only, and its value can be the sum of any
one or more of these PropertyAttributesEnum values:
Value
Description
adPropNotSupported The property is not supported by the provider.
adPropRequired
The user must specify a value for this property before the data
source is initialized.
adPropOptional
The user does not need to specify a value for this property before
the data source is initialized.
adPropRead
The user can read the property.
adPropWrite
The user can set the property.
Attributes Property Remarks (ADO Property Object)
Use the Attributes property to set or return characteristics of Property objects.
When you set multiple attributes, you can sum the appropriate constants. If you set the property
value to a sum including incompatible constants, an error occurs.
Attributes Property Examples (ADO Property Object)
This Visual Basic example displays the value of the Attributes property for Property objects. It
uses the ADO Property Object Name Property to display the name of each Property object.
Public Sub AttributesX
Dim cnn1 As ADODB.Connection
Dim rstEmployees As ADODB.Recordset
Dim fldLoop As ADODB.Field
Dim proLoop As ADODB.Property
Dim strCnn As String
' Open connection and recordset.
Chili!Soft ASP 3.6 Product Documentation
324
strCnn = "driver={SQL Server};server=srv;" & _
"uid=sa;pwd=;database=pubs"
Set cnn1 = New ADODB.Connection
cnn1.Open strCnn
Set rstEmployees = New ADODB.Recordset
rstEmployees.Open "employee", cnn1, , ,
adCmdTable
' Display attributes of the Employee table properties.
Debug.Print "Property attributes:"
For Each proLoop In rstEmployees.Properties
Debug.Print " " & proLoop.Name & " = " & _
proLoop.Attributes
Next proLoop
rstEmployees.Close
cnn1.Close
End Sub
ADO Property Object Name Property
The name of an object.
Name Property Return Values (ADO Property Object)
Sets or returns a String value. The value is read-only on a Property object.
Name Property Remarks (ADO Property Object)
Use the Name property to assign a name to or retrieve the name of a Property object.
You can retrieve the Name property of an object by an ordinal reference, after which the object
can be referred to directly by name. For example, if rstMain.Properties(20).Name
yields Updatability, you can subsequently refer to this property as
rstMain.Properties("Updatability").
Name Property Examples (ADO Property Object)
See the ADO Property Object Attributes Property example.
ADO Property Object Type Property
The operational type or data type of a Property object.
Type Property Return Values (ADO Property Object)
Chili!Soft ASP 3.6 Product Documentation
325
Sets or returns one of the following DataTypeEnum values. The corresponding OLE DB type
indicators are as follows:
Constant
Description
adArray
Or'd together with another type to indicate that the data is a safe-array
of that type (DBTYPE_ARRAY).
adBigInt
An 8-byte signed integer (DBTYPE_I8).
adBinary
A binary value (DBTYPE_BYTES).
adBoolean
A Boolean value (DBTYPE_BOOL).
adByRef
Or'd together with another type to indicate that the data is a pointer to
data of the other type (DBTYPE_BYREF).
adBSTR
A null-terminated character string (Unicode) (DBTYPE_BSTR).
adChar
A String value (DBTYPE_STR).
adCurrency
A currency value (DBTYPE_CY). Currency is a fixed-point number
with 4 digits to the right of the decimal point. It is stored in an 8-byte
signed integer scaled by 10,000.
adDate
A date value (DBTYPE_DATE). A date is stored as a Double, the
whole part of which is the number of days since December 30, 1899,
and the fractional part of which is the fraction of a day.
adDBDate
A date value (yyyymmdd) (DBTYPE_DBDATE).
adDBTime
A time value (hhmmss) (DBTYPE_DBTIME).
adDBTimeStamp A date-time stamp (yyyymmddhhmmss plus a fraction in billionths)
(DBTYPE_DBTIMESTAMP).
adDecimal
An exact numeric value with a fixed precision and scale
(DBTYPE_DECIMAL).
adDouble
A double-precision floating point value (DBTYPE_R8).
adEmpty
No value was specified (DBTYPE_EMPTY).
adError
A 32-bit error code (DBTYPE_ERROR).
adGUID
A globally unique identifier (GUID) (DBTYPE_GUID).
adIDispatch
A pointer to an IDispatch interface on an OLE object
(DBTYPE_IDISPATCH).
adInteger
A 4-byte signed integer (DBTYPE_I4).
adIUnknown
A pointer to an IUnknown interface on an OLE object
(DBTYPE_IUNKNOWN).
adLongVarBinaryA long binary value.
adLongVarChar A long String value.
Chili!Soft ASP 3.6 Product Documentation
adLongVarWCha A long null-terminated string value.
r
adNumeric
An exact numeric value with a fixed precision and scale
(DBTYPE_NUMERIC).
adSingle
A single-precision floating point value (DBTYPE_R4).
adSmallInt
A 2-byte signed integer (DBTYPE_I2).
adTinyInt
A 1-byte signed integer (DBTYPE_I1).
adUnsignedBigIn An 8-byte unsigned integer (DBTYPE_UI8).
t
adUnsignedInt
A 4-byte unsigned integer (DBTYPE_UI4).
adUnsignedSmall A 2-byte unsigned integer (DBTYPE_UI2).
Int
adUnsignedTinyI A 1-byte unsigned integer (DBTYPE_UI1).
nt
adUserDefined
A user-defined variable (DBTYPE_UDT).
adVarBinary
A binary value.
adVarChar
A String value.
adVariant
An Automation Variant (DBTYPE_VARIANT).
adVector
OR'd together with another type to indicate that the data is a
DBVECTOR structure, as defined by OLE DB, that contains a count
of elements and a pointer to data of the other type
(DBTYPE_VECTOR).
adVarWChar
A null-terminated Unicode character string.
adWChar
A null-terminated Unicode character string (DBTYPE_WSTR).
Type Property Remarks (ADO Property Object)
The Type property is read-only.
ADO Property Object Value Property
Indicates the value assigned to a Property object.
Value Property Return Values (ADO Property Object)
Sets or returns a Variant value. Default value depends on the ADO Property Object Type
Property.
Value Property Remarks (ADO Property Object)
Use the Value property to set or return property settings with Property objects.
326
Chili!Soft ASP 3.6 Product Documentation
327
Value Property Example (ADO Property Object)
This Visual Basic example demonstrates the Value property with Field and Property objects by
displaying field and property values for the Employees table.
Public Sub ValueX()
Dim rstEmployees As ADODB.Recordset
Dim fldLoop As ADODB.Field
Dim prpLoop As ADODB.Property
Dim strCnn As String
' Open recordset with data from Employee table.
strCnn = "driver={SQL Server};server=srv;" & _
"uid=sa;pwd=;database=pubs"
Set rstEmployees = New ADODB.Recordset
rstEmployees.Open "employee", strCnn, , , adCmdTable
Debug.Print "Field values in rstEmployees"
' Enumerate the Fields collection of the Employees
' table.
For Each fldLoop In rstEmployees.Fields
` Because Value is the default property of a
` Field object, the use of the actual keyword
` here is optional.
Debug.Print " " & fldLoop.Name & " = " &
fldLoop.Value
Next fldLoop
Debug.Print "Property values in rstEmployees"
' Enumerate the Properties collection of the
' Recordset object.
For Each prpLoop In rstEmployees.Properties
' Because Value is the default property of a
' Property object, the use of the actual keyword
' here is optional.
Debug.Print " " & prpLoop.Name & " = " &
prpLoop.Value
Next prpLoop
328
Chili!Soft ASP 3.6 Product Documentation
rstEmployees.Close
End Sub
ADO Recordset Object
The Recordset object represents the entire set of records from a database table or the results of an
executed command.
ADO Recordset Object Collections
ADO Fields Collection
All the stored Field objects of a Recordset object.
ADO Properties Collection
All the Property objects for a specific instance of a
Recordset object. This collection is not currently
supported on UNIX.
ADO Recordset Object Methods
ADO Recordset Object AddNew
Method
Creates a new record for an updatable Recordset
object.
ADO Recordset Object CancelBatch
Method
Cancels a pending batch update. This method is not
currently supported on UNIX.
ADO Recordset Object CancelUpdate
Method
Cancels any changes made to the current record prior
to calling the Update method.
ADO Recordset Object Clone Method
Creates a new Recordset object from an existing
Recordset object. This method is not currently
supported on UNIX.
ADO Recordset Object Close Method
Closes an open Recordset object and any dependent
objects.
ADO Recordset Object Delete
Method
Deletes the current record or group of records from a
Recordset object.
ADO Recordset Object GetRows
Method
Retrieves multiple rows from a Recordset object into
an array.
ADO Recordset Object Move Method
Moves the position of the current record in a
Recordset object.
ADO Recordset Object MoveFirst
Method
Moves to the first record in a Recordset object and
makes that record the current record.
ADO Recordset Object MoveLast
Method
Moves to the last record in a Recordset object and
makes that record the current record.
ADO Recordset Object MoveNext
Method
Moves to the next record in a Recordset object and
makes that record the current record.
ADO Recordset Object
Moves to the previous record in a Recordset object
329
Chili!Soft ASP 3.6 Product Documentation
MovePrevious Method
and makes that record the current record.
ADO Recordset Object
NextRecordset Method
Clears the current Recordset object and returns the
next recordset by advancing through a series of
commands. This method is not currently supported on
UNIX.
ADO Recordset Object Open Method
Opens a cursor.
ADO Recordset Object Requery
Method
Updates the data in a recordset by re-executing the
query on which the object is based.
ADO Recordset Object Resync
Method
Refreshes the data in the Recordset object from the
underlying database.
ADO Recordset Object Supports
Method
Determines whether a specified Recordset object
supports a particular type of functionality.
ADO Recordset Object Update
Method
Saves any changes you make to the current record of a
Recordset object.
ADO Recordset Object UpdateBatch
Method
Writes all pending batch updates. This method is not
currently supported on UNIX.
ADO Recordset Object Properties
ADO Recordset Object AbsolutePage
Property
The page in which the current record resides.
ADO Recordset Object
AbsolutePosition Property
The ordinal position of a Recordset object’s current
position.
ADO Recordset Object
ActiveConnection Property
The Connection object to which the Recordset object
currently belongs.
ADO Recordset Object BOF, EOF
Properties
If True, the current record position is before the first
record in a Recordset object.
ADO Recordset Object Bookmark
Property
A value that uniquely identifies the current record in a
Recordset object. Setting the Bookmark property to a
valid bookmark changes the current record.
ADO Recordset Object CacheSize
Property
The number of records from a Recordset object that
are cached locally in memory. This property is not
currently supported on UNIX.
ADO Recordset Object
CursorLocation Property
The location of the cursor engine.
ADO Recordset Object CursorType
Property
The type of cursor used in a Recordset object.
ADO Recordset Object EditMode
Property
The editing status of the current record.
330
Chili!Soft ASP 3.6 Product Documentation
ADO Recordset Object BOF, EOF
Properties
True if the record position is after the last record in a
Recordset object.
ADO Recordset Object Filter
Property
A filter for data in a Recordset object.
ADO Recordset Object LockType
Property
The type of locks placed on records during editing.
ADO Recordset Object
MarshalOptions Property
Which records are to be marshaled back to the server.
ADO Recordset Object MaxRecords
Property
The maximum number of records to return to a
Recordset object from a query.
ADO Recordset Object PageCount
Property
The number of pages of data the Recordset object
contains.
ADO Recordset Object PageSize
Property
The number of records that make up one page in the
Recordset object.
ADO Recordset Object RecordCount
Property
The current number of records in a Recordset object.
ADO Recordset Object Source
Property
The source for the data in a Recordset object.
ADO Recordset Object State Property
Describes the current state of the Recordset object.
ADO Recordset Object Status
Property
The status of the current record with respect to batch
updates or other bulk operations.
ADO Recordset Object Remarks
Use Recordset objects to manipulate data from a provider. In ADO, data is almost entirely
manipulated using Recordset objects. All Recordset objects are constructed using records (rows)
and fields (columns). Depending on the functionality supported by the provider, some Recordset
methods or properties may not be available.
Recordset objects can also be run remotely. For example, in a Web-based application, you can
open a Recordset on the client, using the progID "ADOR." The Remote Data Service provides a
mechanism for local data caching and local cursor movement in remote recordset data. A clientside recordset can be used in the same way as a server-side recordset, and supports almost all of
the Recordset object's normal methods and properties. Recordset methods and properties that are
not supported on a client-side recordset, or that behave differently, are noted in the topics for
those properties and methods.
There are four different cursor types defined in ADO:
Cursor
Description
Dynamic
Allows you to view additions, changes and deletions by other users, and
allows all types of movement through the recordset that don’t rely on
bookmarks; allows bookmarks if the provider supports them.
Chili!Soft ASP 3.6 Product Documentation
Keyset
Behaves like a dynamic cursor, except that it prevents you from seeing
records that other users add, and prevents access to records that other users
delete. Data change by other users will still be visible. It always supports
bookmarks and therefore allows all types of movement through the
recordset.
Static
Provides a static copy of a set of records for you to use to find data or
generate reports. Always allows bookmarks and therefore allows all types
of movement through the recordset. Additions, changes, or deletions by
other users will not be visible. This is the only type of cursor allowed when
you open a client-side (ADOR) Recordset object.
331
Forward-only Behaves identically to a dynamic cursor except that it allows you to scroll
only forward through records. This improves performance in situations
where you need to make only a single pass through a recordset.
Set the ADO Recordset Object CursorType Property prior to opening the recordset to choose the
cursor type, or pass a CursorType argument with the ADO Recordset Object Open Method. Some
providers don't support all cursor types. Check the documentation for the provider. If you don't
specify a cursor type, ADO opens a forward-only cursor by default.
When used with some providers (such as the Microsoft ODBC Provider for OLE DB in
conjunction with Microsoft SQL Server), you can create Recordset objects independently of a
previously defined ADO Connection Object by passing a connection string with the Open
method. ADO still creates a Connection object, but it doesn't assign that object to an object
variable. However, if you are opening multiple Recordset objects over the same connection, you
should explicitly create and open a Connection object; this assigns the Connection object to an
object variable. If you do not use this object variable when opening your Recordset objects,
ADO creates a new Connection object for each new recordset, even if you pass the same
connection string.
You can create as many Recordset objects as needed.
When you open a recordset, the current record is positioned to the first record (if any) and the
ADO Recordset Object BOF, EOF Properties are set to False. If there are no records, the BOF
and EOF property settings are True.
Use the ADO Recordset Object MoveFirst, MoveLast, MoveNext, MovePrevious Methods, as
well as the ADO Recordset Object Move Method, and the AbsolutePosition, AbsolutePage, and
ADO Recordset Object Filter Property properties to reposition the current record, assuming the
provider supports the relevant functionality. Forward-only Recordset objects support only the
MoveNext method. When you use the Move methods to visit each record (or enumerate the
recordset), you can use the BOF and EOF properties to see if you've moved beyond the
beginning or end of the recordset.
Recordset objects may support two types of updating: immediate and batched. In immediate
updating, all changes to data are written immediately to the underlying data source once you call
the ADO Recordset Object Update Method. You can also pass arrays of values as parameters
with the ADO Recordset Object AddNew Method and Update methods and simultaneously
update several fields in a record.
Chili!Soft ASP 3.6 Product Documentation
332
If a provider supports batch updating, you can have the provider cache changes to more than one
record and then transmit them in a single call to the database with the ADO Recordset Object
UpdateBatch Method. This applies to changes made with the AddNew, Update, and ADO
Recordset Object Delete Method methods. After you call the UpdateBatch method, you can use
the ADO Recordset Object Status Property to check for any data conflicts in order to resolve
them. Batch updating is not currently supported on UNIX.
Note
To execute a query without using an ADO Command Object, pass a query string to the
ADO Recordset Object Open Method of a Recordset object. However, a Command
object is required when you want to retain the command text and re-execute it, or use
query parameters.
ADO Recordset Object Methods
ADO Recordset Object AddNew Method
Creates a new record for an updateable Recordset object.
AddNew Method Syntax
recordset.AddNew Fields, Values
AddNew Method Parameters
Fields
An optional single name or an array of names or ordinal positions of the fields in the new record.
Values
An optional single value or an array of values for the fields in the new record. If Fields is an
array, Values must also be an array with the same number of members; otherwise, an error
occurs. The order of field names must match the order of field values in each array.
AddNew Method Remarks
Use the AddNew method to create and initialize a new record. Use the ADO Recordset Object
Supports Method with adAddNew to verify whether you can add records to the current
Recordset object.
After you call the AddNew method, the new record becomes the current record and remains
current after you call the ADO Recordset Object Update Method. If the Recordset object does
not support bookmarks, you may not be able to access the new record once you move to another
record. Depending on your cursor type, you may need to call the ADO Recordset Object Requery
Method to make the new record accessible.
If you call AddNew while editing the current record or while adding a new record, ADO calls the
Update method to save any changes and then creates the new record.
Chili!Soft ASP 3.6 Product Documentation
333
The behavior of the AddNew method depends on the updating mode of the Recordset object and
whether or not you pass the Fields and Values arguments.
In immediate update mode (the provider writes changes to the underlying data source once you
call the Update method), calling the AddNew method without arguments sets the ADO
Recordset Object EditMode Property to adEditAdd. The provider caches any field value changes
locally. Calling the Update method posts the new record to the database and resets the EditMode
property to adEditNone. If you pass the Fields and Values arguments, ADO immediately posts
the new record to the database (no Update call is necessary); the EditMode property value does
not change (adEditNone).
In batch update mode (the provider caches multiple changes and writes them to the underlying
data source only when you call the UpdateBatch method), calling the AddNew method without
arguments sets the EditMode property to adEditAdd. The provider caches any field value
changes locally. Calling the Update method adds the new record to the current recordset and
resets the EditMode property to adEditNone, but the provider does not post the changes to the
underlying database until you call the ADO Recordset Object UpdateBatch Method. If you pass
the Fields and Values arguments, ADO sends the new record to the provider for storage in a
cache; you need to call the UpdateBatch method to post the new record to the underlying
database. Batch updating is not currently supported on UNIX.
ADO Recordset Object CancelBatch Method
Cancels a pending batch update. This method is not currently supported on UNIX.
CancelBatch Method Syntax
recordset.CancelBatch AffectRecords
CancelBatch Method Parameters
AffectRecords
An optional AffectEnum value that determines how many records the CancelBatch method will
affect. It can be one of the following constants:
Constant
Description
adAffectCurrent
Cancels pending updates only for the current record.
adAffectGroup
Cancels pending updates for records that satisfy the current ADO
Recordset Object Filter Property setting. You must set the Filter
property to one of the valid predefined constants in order to use this
option.
adAffectAll
Default. Cancels pending updates for all the records in the Recordset
object, including any hidden by the current Filter property setting.
CancelBatch Method Remarks
Chili!Soft ASP 3.6 Product Documentation
334
Use the CancelBatch method to cancel any pending updates in a recordset in batch update mode.
If the recordset is in immediate update mode, calling CancelBatch without adAffectCurrent
generates an error.
If you are editing the current record or are adding a new record when you call CancelBatch,
ADO first calls the ADO Recordset Object CancelUpdate Method to cancel any cached changes;
after that, all pending changes in the recordset are canceled.
It's possible that the current record will be indeterminable after a CancelBatch call, especially if
you were in the process of adding a new record. For this reason, it is prudent to set the current
record position to a known location in the recordset after the CancelBatch call. For example, call
the ADO Recordset Object MoveFirst, MoveLast, MoveNext, and MovePrevious Methods.
If the attempt to cancel the pending updates fails because of a conflict with the underlying data
(for example, a record has been deleted by another user), the provider returns warnings to the
ADO Errors Collection but does not halt program execution. A run-time error occurs only if there
are conflicts on all the requested records. Use the Filter property (adFilterAffectedRecords) and
the ADO Recordset Object Status Property to locate records with conflicts.
CancelBatch Method Examples
This Visual Basic example demonstrates the ADO Recordset Object UpdateBatch Method in
conjunction with the CancelBatch method.
Public Sub UpdateBatchX()
Dim rstTitles As ADODB.Recordset
Dim strCnn As String
Dim strTitle As String
Dim strMessage As String
` Assign connection string to variable.
strCnn = "driver={SQL Server};server=srv;" & _
"uid=sa;pwd=;database=pubs"
Set rstTitles = New ADODB.Recordset
rstTitles.CursorType = adOpenKeyset
rstTitles.LockType = adLockBatchOptimistic
rstTitles.Open "titles", strCnn, , , adCmdTable
rstTitles.MoveFirst
` Loop through recordset and ask user if she wants
` to change the type for a specified title.
Do Until rstTitles.EOF
If Trim(rstTitles!Type) = "psychology" Then
Chili!Soft ASP 3.6 Product Documentation
strTitle = rstTitles!Title
strMessage = "Title: " & strTitle & vbCr & _
"Change type to self help?"
If MsgBox(strMessage, vbYesNo) = vbYes Then
rstTitles!Type = "self_help"
End If
End If
rstTitles.MoveNext
Loop
` Ask if the user wants to commit to all the
` changes made above.
If MsgBox("Save all changes?", vbYesNo) = vbYes Then
rstTitles.UpdateBatch
Else
rstTitles.CancelBatch
End If
` Print current data in recordset.
rstTitles.Requery
rstTitles.MoveFirst
Do While Not rstTitles.EOF
Debug.Print rstTitles!Title & " - " & rstTitles!Type
rstTitles.MoveNext
Loop
` Restore original values because this is a demonstration.
rstTitles.MoveFirst
Do Until rstTitles.EOF
If Trim(rstTitles!Type) = "self_help" Then
rstTitles!Type = "psychology"
End If
rstTitles.MoveNext
Loop
rstTitles.UpdateBatch
335
Chili!Soft ASP 3.6 Product Documentation
336
rstTitles.Close
End Sub
ADO Recordset Object CancelUpdate Method
Cancels any changes made to the current record or to a new record prior to calling the Update
method.
CancelUpdate Method Syntax
recordset.CancelUpdate
CancelUpdate Method Remarks
Use the CancelUpdate method to cancel any changes made to the current record or to discard a
newly added record.
Note
You cannot undo changes to the current record or to a new record after you call the ADO
Recordset Object Update Method unless the changes are either part of a transaction that
you can roll back with the RollbackTrans method or part of a batch update that you can
cancel with the ADO Recordset Object CancelBatch Method.
If you are adding a new record when you call the CancelUpdate method, the record that
was current prior to the ADO Recordset Object AddNew Method call becomes the
current record again. If you have not changed the current record or added a new record,
calling the CancelUpdate method generates an error.
CancelUpdate Method Examples
These Visual Basic examples demonstrate the ADO Recordset Object Update Method in
conjunction with the CancelUpdate method.
Public Sub UpdateX()
Dim rstEmployees As ADODB.Recordset
Dim strOldFirst As String
Dim strOldLast As String
Dim strMessage As String
` Open recordset with names from Employee table.
strCnn = "driver={SQL Server};server=srv;" & _
"uid=sa;pwd=;database=pubs"
Set rstEmployees = New ADODB.Recordset
rstEmployees.CursorType = adOpenKeyset
rstEmployees.LockType = adLockOptimistic
Chili!Soft ASP 3.6 Product Documentation
rstEmployees.Open "SELECT fname, lname " & _
"FROM Employee ORDER BY lname", strCnn, , , adCmdText
` Store original data.
strOldFirst = rstEmployees!fname
strOldLast = rstEmployees!lname
` Change data in edit buffer.
rstEmployees!fname = "Linda"
rstEmployees!lname = "Kobara"
` Show contents of buffer and get user input.
strMessage = "Edit in progress:" & vbCr & _
" Original data = " & strOldFirst & " " & _
strOldLast & vbCr & " Data in buffer = " & _
rstEmployees!fname & " " & rstEmployees!lname & vbCr & vbCr & _
"Use Update to replace the original data with " & _
"the buffered data in the Recordset?"
If MsgBox(strMessage, vbYesNo) = vbYes Then
rstEmployees.Update
Else
rstEmployees.CancelUpdate
End If
` Show the resulting data.
MsgBox "Data in recordset = " & rstEmployees!fname & " " & _
rstEmployees!lname
` Restore original data because this is a demonstration.
If Not (strOldFirst = rstEmployees!fname And _
strOldLast = rstEmployees!lname) Then
rstEmployees!fname = strOldFirst
rstEmployees!lname = strOldLast
rstEmployees.Update
End If
rstEmployees.Close
End Sub
337
Chili!Soft ASP 3.6 Product Documentation
This example demonstrates the Update method in conjunction with the AddNew method.
Public Sub UpdateX2()
Dim cnn1 As ADODB.Connection
Dim rstEmployees As ADODB.Recordset
Dim strEmpID As String
Dim strOldFirst As String
Dim strOldLast As String
Dim strMessage As String
` Open a connection.
Set cnn1 = New ADODB.Connection
strCnn = "driver={SQL Server};server=srv;" & _
"uid=sa;pwd=;database=pubs"
cnn1.Open strCnn
` Open recordset with data from Employee table.
Set rstEmployees = New ADODB.Recordset
rstEmployees.CursorType = adOpenKeyset
rstEmployees.LockType = adLockOptimistic
rstEmployees.Open "employee", cnn1, , , adCmdTable
rstEmployees.AddNew
strEmpID = "B-S55555M"
rstEmployees!emp_id = strEmpID
rstEmployees!fname = "Bill"
rstEmployees!lname = "Sornsin"
` Show contents of buffer and get user input.
strMessage = "AddNew in progress:" & vbCr & _
"Data in buffer = " & rstEmployees!emp_id & ", " & _
rstEmployees!fname & " " & rstEmployees!lname & vbCr & vbCr & _
"Use Update to save buffer to recordset?"
If MsgBox(strMessage, vbYesNoCancel) = vbYes Then
rstEmployees.Update
` Go to the new record and show the resulting data.
MsgBox "Data in recordset = " & rstEmployees!emp_id & ", " & _
338
Chili!Soft ASP 3.6 Product Documentation
339
rstEmployees!fname & " " & rstEmployees!lname
Else
rstEmployees.CancelUpdate
MsgBox "No new record added."
End If
` Delete new data because this is a demonstration.
cnn1.Execute "DELETE FROM employee WHERE emp_id = '" & strEmpID &
"'"
rstEmployees.Close
End Sub
ADO Recordset Object Clone Method
Creates a duplicate Recordset object from an existing Recordset object. This method is not
currently supported on UNIX.
Clone Method Syntax
Set rstDuplicate = rstOriginal.Clone ()
Clone Method Parameters
rstDuplicate
An object variable identifying the duplicate Recordset object you're creating.
rstOriginal
An object variable identifying the Recordset object you want to duplicate.
Clone Method Remarks
Use the Clone method to create multiple, duplicate Recordset objects, particularly if you want to
be able to maintain more than one current record in a given set of records. Using the Clone
method is more efficient than creating and opening a new Recordset object with the same
definition as the original.
The current record of a newly created clone is set to the first record.
Changes you make to one Recordset object are visible in all of its clones regardless of cursor
type. However, once you execute the ADO Recordset Object Requery Method on the original
Recordset, the clones will no longer be synchronized to the original.
Closing the original recordset does not close its copies; closing a copy does not close the original
or any of the other copies.
You can only clone a Recordset object that supports bookmarks. Bookmark values are
interchangeable; that is, a bookmark reference from one Recordset object refers to the same
record in any of its clones.
Chili!Soft ASP 3.6 Product Documentation
340
Clone Method Return Values
Returns a Recordset object reference.
ADO Recordset Object Close Method
Closes an open object and any dependent objects.
Close Method Syntax
object.Close
Close Method Remarks
Use the Close method to close a Recordset object to free any associated system resources.
Closing an object does not remove it from memory; you may change its property settings and
open it again later. To completely eliminate an object from memory, set the object variable to
Nothing.
Using the Close method to close a Recordset object releases the associated data and any
exclusive access you may have had to the data through this particular Recordset object. You can
later call the ADO Recordset Object Open Method to reopen the Recordset with the same or
modified attributes. While the Recordset object is closed, calling any methods that require a live
cursor generates an error.
If an edit is in progress while in immediate update mode, calling the Close method generates an
error; call the ADO Recordset Object Update Method or ADO Recordset Object CancelUpdate
Method first. If you close the Recordset object during batch updating, all changes since the last
ADO Recordset Object UpdateBatch Method call are lost.
If you use the Clone method to create copies of an open Recordset object, closing the original or
a clone does not affect any of the other copies.
Close Method Examples
This VBScript example uses the Open and Close methods on both Recordset and Connection
objects that have been opened.
<!-- #Include file="ADOVBS.INC" -->
<HTML><HEAD>
<TITLE>ADO 1.5 Open Method</TITLE>
</HEAD><BODY>
<FONT FACE="MS SANS SERIF" SIZE=2>
<Center><H3>ADO Open Method</H3>
<TABLE WIDTH=600 BORDER=0>
<TD VALIGN=TOP ALIGN=LEFT COLSPAN=3><FONT SIZE=2>
<!--- ADO Connection used to create 2 recordsets-->
Chili!Soft ASP 3.6 Product Documentation
<%
Set OBJdbConnection = Server.CreateObject("ADODB.Connection")
OBJdbConnection.Open "AdvWorks"
SQLQuery = "SELECT * FROM Customers"
'First Recordset RSCustomerList
Set RSCustomerList = OBJdbConnection.Execute(SQLQuery)
'Second Recordset RsProductist
Set RsProductList = Server.CreateObject("ADODB.Recordset")
RsProductList.CursorType = adOpenDynamic
RsProductList.LockType = adLockOptimistic
RsProductList.Open "Products", OBJdbConnection
%>
<TABLE COLSPAN=8 CELLPADDING=5 BORDER=0>
<!-- BEGIN column header row for Customer Table-->
<TR><TD ALIGN=CENTER BGCOLOR="#008080">
<FONT STYLE="ARIAL NARROW" COLOR="#ffffff" SIZE=1>Company
Name</FONT></TD>
<TD ALIGN=CENTER BGCOLOR="#008080">
<FONT STYLE="ARIAL NARROW" COLOR="#ffffff" SIZE=1>Contact
Name</FONT></TD>
<TD ALIGN=CENTER WIDTH=150 BGCOLOR="#008080">
<FONT STYLE="ARIAL NARROW" COLOR="#ffffff" SIZE=1>E-mail
address</FONT></TD>
<TD ALIGN=CENTER BGCOLOR="#008080">
<FONT STYLE="ARIAL NARROW" COLOR="#ffffff" SIZE=1>City</FONT></TD>
<TD ALIGN=CENTER BGCOLOR="#008080">
<FONT STYLE="ARIAL NARROW" COLOR="#ffffff"
SIZE=1>State/Province</FONT></TD></TR>
<!--Display ADO Data from Customer Table-->
<% Do While Not RScustomerList.EOF %>
<TR><TD BGCOLOR="f7efde" ALIGN=CENTER>
<FONT STYLE="ARIAL NARROW" SIZE=1>
<%= RSCustomerList("CompanyName")%>
341
Chili!Soft ASP 3.6 Product Documentation
</FONT></TD>
<TD BGCOLOR="f7efde" ALIGN=CENTER>
<FONT STYLE="ARIAL NARROW" SIZE=1>
<%= RScustomerList("ContactLastName") & ", " %>
<%= RScustomerList("ContactFirstName") %>
</FONT></TD>
<TD BGCOLOR="f7efde" ALIGN=CENTER>
<FONT STYLE="ARIAL NARROW" SIZE=1>
<%= RScustomerList("ContactLastName")%>
</FONT></TD>
<TD BGCOLOR="f7efde" ALIGN=CENTER>
<FONT STYLE="ARIAL NARROW" SIZE=1>
<%= RScustomerList("City")%>
</FONT></TD>
<TD BGCOLOR="f7efde" ALIGN=CENTER>
<FONT STYLE="ARIAL NARROW" SIZE=1>
<%= RScustomerList("StateOrProvince")%>
</FONT></TD></TR>
<!-Next Row = Record Loop and add to html table-->
<%
RScustomerList.MoveNext
Loop
RScustomerList.Close
OBJdbConnection.Close
%>
</TABLE>
<HR>
<TABLE COLSPAN=8 CELLPADDING=5 BORDER=0>
<!-- BEGIN column header row for Product List Table-->
<TR><TD ALIGN=CENTER BGCOLOR="#800000">
<FONT STYLE="ARIAL NARROW" COLOR="#ffffff" SIZE=1>Product
Type</FONT></TD>
<TD ALIGN=CENTER BGCOLOR="#800000">
342
Chili!Soft ASP 3.6 Product Documentation
<FONT STYLE="ARIAL NARROW" COLOR="#ffffff" SIZE=1>Product
Name</FONT></TD>
<TD ALIGN=CENTER WIDTH=350 BGCOLOR="#800000">
<FONT STYLE="ARIAL NARROW" COLOR="#ffffff" SIZE=1>Product
Description</FONT></TD>
<TD ALIGN=CENTER BGCOLOR="#800000">
<FONT STYLE="ARIAL NARROW" COLOR="#ffffff" SIZE=1>Unit
Price</FONT></TD></TR>
<!-- Display ADO Data Product List-->
<% Do While Not RsProductList.EOF %>
<TR> <TD BGCOLOR="f7efde" ALIGN=CENTER>
<FONT STYLE="ARIAL NARROW" SIZE=1>
<%= RsProductList("ProductType")%>
</FONT></TD>
<TD BGCOLOR="f7efde" ALIGN=CENTER>
<FONT STYLE="ARIAL NARROW" SIZE=1>
<%= RsProductList("ProductName")%>
</FONT></TD>
<TD BGCOLOR="f7efde" ALIGN=CENTER>
<FONT STYLE="ARIAL NARROW" SIZE=1>
<%= RsProductList("ProductDescription")%>
</FONT></TD>
<TD BGCOLOR="f7efde" ALIGN=CENTER>
<FONT STYLE="ARIAL NARROW" SIZE=1>
<%= RsProductList("UnitPrice")%>
</FONT></TD>
<!-- Next Row = Record -->
<%
RsProductList.MoveNext
Loop
'Remove Objects from Memory Freeing
Set RsProductList = Nothing
Set OBJdbConnection = Nothing
343
Chili!Soft ASP 3.6 Product Documentation
344
%>
</TABLE></FONT></Center></BODY></HTML>
ADO Recordset Object Delete Method
Deletes the current record or a group of records.
Delete Method Syntax
recordset.Delete AffectRecords
Delete Method Parameters
AffectRecords
An optional AffectEnum value that determines how many records the Delete method will affect.
Can be one of the following constants:
Constant
Description
adAffectCurrent
Default. Delete only the current record.
adAffectGroup
Delete the records that satisfy the current ADO Recordset Object Filter
Property setting. You must set the Filter property to one of the valid
predefined constants in order to use this option. The Filter property is
not currently supported on UNIX.
Delete Method Remarks
Using the Delete method marks the current record or a group of records in a Recordset object for
deletion. If the Recordset object doesn't allow record deletion, an error occurs. If you are in
immediate update mode, deletions occur in the database immediately. Otherwise, the records are
marked for deletion from the cache and the actual deletion happens when you call the ADO
Recordset Object UpdateBatch Method. (Use the Filter property to view the deleted records.)
Retrieving field values from the deleted record generates an error. After deleting the current
record, the deleted record remains current until you move to a different record. Once you move
away from the deleted record, it is no longer accessible.
If you nest deletions in a transaction, you can recover deleted records with the RollbackTrans
method. If you are in batch update mode, you can cancel a pending deletion or group of pending
deletions with the ADO Recordset Object CancelBatch Method.
If the attempt to delete records fails because of a conflict with the underlying data (for example, a
record has already been deleted by another user), the provider returns warnings to the ADO
Errors Collection, but does not halt program execution. A run-time error occurs only if there are
conflicts on all the requested records.
Delete Method Examples
This VBScript example uses the Delete method to remove a specified record from a recordset.
<!-- #Include file="ADOVBS.INC" -->
Chili!Soft ASP 3.6 Product Documentation
<% Language = VBScript %>
<HTML>
<HEAD><TITLE>ADO 1.5 Delete Method</TITLE>
</HEAD><BODY>
<FONT FACE="MS SANS SERIF" SIZE=2>
<Center><H3>ADO Delete Method</H3>
<!--- ADO Connection Object used to create recordset-->
<%
'Create and Open Connection Object
Set OBJdbConnection = Server.CreateObject("ADODB.Connection")
OBJdbConnection.Open "AdvWorks"
'Create and Open Recordset Object
Set RsCustomerList = Server.CreateObject("ADODB.Recordset")
RsCustomerList.ActiveConnection = OBJdbConnection
RsCustomerList.CursorType = adOpenKeyset
RsCustomerList.LockType = adLockOptimistic
RsCustomerList.Source = "Customers"
RsCustomerList.Open
%>
<!-- Move to designated Record and Delete It -->
<%
If Not IsEmpty(Request.Form("WhichRecord")) Then
`Get value to move from Form Post method
Moves = Request.Form("WhichRecord")
RsCustomerList.Move CInt(Moves)
If Not RsCustomerList.EOF or RsCustomerList.BOF Then
RsCustomerList.Delete 1
RsCustomerList.MoveFirst
Else
Response.Write "Not a Valid Record Number"
RsCustomerList.MoveFirst
End If
345
Chili!Soft ASP 3.6 Product Documentation
End If
%>
<!-- BEGIN column header row for Customer Table-->
<TABLE COLSPAN=8 CELLPADDING=5 BORDER=0><TR>
<TD ALIGN=CENTER BGCOLOR="#008080">
<FONT STYLE="ARIAL NARROW" COLOR="#ffffff" SIZE=1>Company
Name</FONT>
</TD>
<TD ALIGN=CENTER BGCOLOR="#008080">
<FONT STYLE="ARIAL NARROW" COLOR="#ffffff" SIZE=1>Contact
Name</FONT>
</TD>
<TD ALIGN=CENTER WIDTH=150 BGCOLOR="#008080">
<FONT STYLE="ARIAL NARROW" COLOR="#ffffff" SIZE=1>Phone
Number</FONT>
</TD>
<TD ALIGN=CENTER BGCOLOR="#008080">
<FONT STYLE="ARIAL NARROW" COLOR="#ffffff" SIZE=1>City</FONT>
</TD>
<TD ALIGN=CENTER BGCOLOR="#008080">
<FONT STYLE="ARIAL NARROW" COLOR="#ffffff"
SIZE=1>State/Province</FONT>
</TD></TR>
<!--Display ADO Data from Customer Table Loop through Recordset
adding one Row to HTML Table each pass-->
<% Do While Not RsCustomerList.EOF %>
<TR><TD BGCOLOR="f7efde" ALIGN=CENTER>
<FONT STYLE="ARIAL NARROW" SIZE=1>
<%= RSCustomerList("CompanyName")%>
</FONT></TD>
<TD BGCOLOR="f7efde" ALIGN=CENTER>
<FONT STYLE="ARIAL NARROW" SIZE=1>
<%= RScustomerList("ContactLastName") & ", " %>
346
Chili!Soft ASP 3.6 Product Documentation
<%= RScustomerList("ContactFirstName") %>
</FONT></TD>
<TD BGCOLOR="f7efde" ALIGN=CENTER>
<FONT STYLE="ARIAL NARROW" SIZE=1>
<%= RScustomerList("PhoneNumber")%>
</FONT></TD>
<TD BGCOLOR="f7efde" ALIGN=CENTER>
<FONT STYLE="ARIAL NARROW" SIZE=1>
<%= RScustomerList("City")%>
</FONT></TD>
<TD BGCOLOR="f7efde" ALIGN=CENTER>
<FONT STYLE="ARIAL NARROW" SIZE=1>
<%= RScustomerList("StateOrProvince")%>
</FONT></TD>
</TR>
<!-Next Row = Record Loop and add to html table-->
<%
RScustomerList.MoveNext
Loop
%>
</Table></Center></FONT>
<!-- Do Client side Input Data Validation Move to named
record and Delete it -->
<Center>
<H4>Clicking Button Will Remove Designated Record</H4>
<H5>There are <%=RsCustomerList.RecordCount - 1%> Records in this
Set</H5>
<Form Method = Post Action = "Delete.asp" Name = Form>
<Input Type = Text Name = "WhichRecord" Size = 3></Form>
<Input Type = Button Name = cmdDelete Value = "Delete
Record"></Center>
</BODY>
<Script Language = "VBScript">
347
Chili!Soft ASP 3.6 Product Documentation
Sub cmdDelete_OnClick
If IsNumeric(Document.Form.WhichRecord.Value) Then
Document.Form.WhichRecord.Value =
CInt(Document.Form.WhichRecord.Value)
Dim Response
Response = MsgBox("Are You Sure About Deleting This Record?",
vbYesNo, "ADO-ASP Example")
If Response = vbYes Then
Document.Form.Submit
End If
Else
MsgBox "You Must Enter a Valid Record Number",,"ADO-ASP Example"
End If
End Sub
</Script>
</HTML>
ADO Recordset Object GetRows Method
Retrieves multiple records of a recordset into an array.
GetRows Method Syntax
array = recordset.GetRows( Rows, Start, Fields )
GetRows Method Parameters
array
Two-dimensional Array containing records.
Rows
An optional Long expression indicating the number of records to retrieve. Default is
adGetRowsRest (-1).
Start
An optional String or Variant that evaluates to the bookmark for the record from which the
GetRows operation should begin. You can also use one of the following BookmarkEnum
values:
Constant
Description
AdBookmarkCurrent Start at the current record.
348
Chili!Soft ASP 3.6 Product Documentation
AdBookmarkFirst
Start at the first record.
AdBookmarkLast
Start at the last record.
349
Fields
An optional Variant representing a single field name or ordinal position or an array of field
names or ordinal position numbers. ADO returns only the data in these fields.
GetRows Method Return Values
Returns a two-dimensional array.
GetRows Method Remarks
Use the GetRows method to copy records from a recordset into a two-dimensional array. The
first subscript identifies the field and the second identifies the record number. The array variable
is automatically dimensioned to the correct size when the GetRows method returns the data.
If you do not specify a value for the Rows argument, the GetRows method automatically retrieves
all the records in the Recordset object. If you request more records than are available, GetRows
returns only the number of available records.
If the Recordset object supports bookmarks, you can specify at which record the GetRows
method should begin retrieving data by passing the value of that record's ADO Recordset Object
Bookmark Property.
If you want to restrict the fields the GetRows call returns, you can pass either a single field
name/number or an array of field names/numbers in the Fields argument.
After you call GetRows, the next unread record becomes the current record, or the ADO
Recordset Object BOF, EOF Properties property is set to True if there are no more records.
GetRows Method Examples
This Visual Basic example uses the GetRows method to retrieve a specified number of rows from
a recordset and to fill an array with the resulting data. The GetRows method will return fewer
than the desired number of rows in two cases: either if EOF has been reached, or if GetRows
tried to retrieve a record that was deleted by another user. The function returns False only if the
second case occurs. The GetRowsOK function is required for this procedure to run.
Public Sub GetRowsX()
Dim rstEmployees As ADODB.Recordset
Dim strCnn As String
Dim strMessage As String
Dim intRows As Integer
Dim avarRecords As Variant
Dim intRecord As Integer
' Open recordset with names and hire dates from employee table.
Chili!Soft ASP 3.6 Product Documentation
strCnn = "driver={SQL Server};server=srv;" & _
"uid=sa;pwd=;database=pubs"
Set rstEmployees = New ADODB.Recordset
rstEmployees.Open "SELECT fName, lName, hire_date " & _
"FROM Employee ORDER BY lName", strCnn, , , adCmdText
Do While True
` Get user input for number of rows.
strMessage = "Enter number of rows to retrieve."
intRows = Val(InputBox(strMessage))
If intRows <= 0 Then Exit Do
` If GetRowsOK is successful, print the results,
` noting if the end of the file was reached.
If GetRowsOK(rstEmployees, intRows, _
avarRecords) Then
If intRows > UBound(avarRecords, 2) + 1 Then
Debug.Print "(Not enough records in " & _
"Recordset to retrieve " & intRows & _
" rows.)"
End If
Debug.Print UBound(avarRecords, 2) + 1 & _
" records found."
` Print the retrieved data.
For intRecord = 0 To UBound(avarRecords, 2)
Debug.Print " " & _
avarRecords(0, intRecord) & " " & _
avarRecords(1, intRecord) & ", " & _
avarRecords(2, intRecord)
Next intRecord
Else
` Assuming the GetRows error was due to data
` changes by another user, use Requery to
` refresh the Recordset and start over.
350
Chili!Soft ASP 3.6 Product Documentation
If MsgBox("GetRows failed--retry?", _
vbYesNo) = vbYes Then
rstEmployees.Requery
Else
Debug.Print "GetRows failed!"
Exit Do
End If
End If
` Because using GetRows leaves the current
` record pointer at the last record accessed,
` move the pointer back to the beginning of the
` Recordset before looping back for another search.
rstEmployees.MoveFirst
Loop
rstEmployees.Close
End Sub
Public Function GetRowsOK(rstTemp As ADODB.Recordset, _
intNumber As Integer, avarData As Variant) As Boolean
` Store results of GetRows method in array.
avarData = rstTemp.GetRows(intNumber)
` Return False only if fewer than the desired
` number of rows were returned, but not because the
` end of the Recordset was reached.
If intNumber > UBound(avarData, 2) + 1 And _
Not rstTemp.EOF Then
GetRowsOK = False
Else
GetRowsOK = True
End If
End Function
ADO Recordset Object Move Method
Moves the position of the current record in a Recordset object.
351
Chili!Soft ASP 3.6 Product Documentation
352
Move Method Syntax
recordset.Move NumRecords, Start
Move Method Parameters
NumRecords
A signed Long expression specifying the number of records the current record position moves.
Start
An optional String or Variant that evaluates to a bookmark. You can also use one of the
following BookmarkEnum values:
Constant
Description
AdBookmarkCurrent
Default. Start at the current record.
AdBookmarkFirst
Start at the first record.
AdBookmarkLast
Start at the last record.
Move Method Remarks
The Move method is supported on all Recordset objects.
If the NumRecords argument is greater than zero, the current record position moves forward
(toward the end of the recordset). If NumRecords is less than zero, the current record position
moves backward (toward the beginning of the recordset).
If the Move call would move the current record position to a point before the first record, ADO
sets the current record to the position before the first record in the recordset (BOF is True). An
attempt to move backward when the ADO Recordset Object BOF, EOF Properties property is
already True generates an error.
If the Move call would move the current record position to a point after the last record, ADO sets
the current record to the position after the last record in the recordset (EOF is True). An attempt
to move forward when the ADO Recordset Object BOF, EOF Properties property is already True
generates an error.
Calling the Move method from an empty Recordset object generates an error.
If you pass the Start argument, the move is relative to the record with this bookmark, assuming
the Recordset object supports bookmarks. If not specified, the move is relative to the current
record.
If you are using the ADO Recordset Object CacheSize Property to locally cache records from the
provider, passing a NumRecords that moves the current record position outside of the current
group of cached records forces ADO to retrieve a new group of records starting from the
destination record. The CacheSize property determines the size of the newly retrieved group, and
the destination record is the first record retrieved.
If the Recordset object is forward-only, a user can still pass a NumRecords less than zero as long
as the destination is within the current set of cached records. If the Move call would move the
current record position to a record before the first cached record, an error will occur. Thus, you
Chili!Soft ASP 3.6 Product Documentation
353
can use a record cache that supports full scrolling over a provider that only supports forward
scrolling. Because cached records are loaded into memory, you should avoid caching more
records than is necessary. Even if a forward-only Recordset object supports backward moves in
this way, calling the ADO Recordset Object MoveFirst, MoveLast, MoveNext, MovePrevious
Methods method on any forward-only Recordset object still generates an error.
Move Method Example
This VBScript example uses the Move method to position the record pointer based on user input.
Try entering a letter or non-integer to see the error-handling work.
<!-- #Include file="ADOVBS.INC" -->
<% Language = VBScript %>
<HTML><HEAD>
<TITLE>ADO 1.5 Move Methods</TITLE></HEAD>
<BODY>
<FONT FACE="MS SANS SERIF" SIZE=2>
<Center>
<H3>ADO Move Methods</H3>
<%
'Create and Open Connection Object
Set OBJdbConnection = Server.CreateObject("ADODB.Connection")
OBJdbConnection.Open "AdvWorks"
'Create and Open Recordset Object
Set RsCustomerList = Server.CreateObject("ADODB.Recordset")
RsCustomerList.ActiveConnection = OBJdbConnection
RsCustomerList.CursorType = adOpenKeyset
RsCustomerList.LockType = adLockOptimistic
RsCustomerList.Source = "Customers"
RsCustomerList.Open
'Check number of user moves this session
'Increment by amount in Form
Session("Clicks") = Session("Clicks") + Request.Form("MoveAmount")
Clicks = Session("Clicks")
'Move to last known recordset position plus amount passed by Form
Post method
RsCustomerList.Move CInt(Clicks)
Chili!Soft ASP 3.6 Product Documentation
'Error Handling
If RsCustomerList.EOF Then
Session("Clicks") = RsCustomerList.RecordCount
Response.Write "This is the Last Record"
RsCustomerList.MoveLast
Else If RsCustomerList.BOF Then
Session("Clicks") = 1
RsCustomerList.MoveFirst
Response.Write "This is the First Record"
End If
End If
%>
<H3>Current Record Number is <BR>
<% If Session("Clicks") = 0 Then
Session("Clicks") = 1
End If
Response.Write(Session("Clicks") )%> of
<%=RsCustomerList.RecordCount%></H3>
<HR>
<Center><TABLE COLSPAN=8 CELLPADDING=5 BORDER=0>
<!-- BEGIN column header row for Customer Table-->
<TR>
<TD ALIGN=CENTER BGCOLOR="#008080">
<FONT STYLE="ARIAL NARROW" COLOR="#ffffff" SIZE=1>Company
Name</FONT>
</TD>
<TD ALIGN=CENTER BGCOLOR="#008080">
<FONT STYLE="ARIAL NARROW" COLOR="#ffffff" SIZE=1>Contact
Name</FONT>
</TD>
<TD ALIGN=CENTER WIDTH=150 BGCOLOR="#008080">
<FONT STYLE="ARIAL NARROW" COLOR="#ffffff" SIZE=1>Phone
Number</FONT>
354
Chili!Soft ASP 3.6 Product Documentation
</TD>
<TD ALIGN=CENTER BGCOLOR="#008080">
<FONT STYLE="ARIAL NARROW" COLOR="#ffffff" SIZE=1>City</FONT>
</TD>
<TD ALIGN=CENTER BGCOLOR="#008080">
<FONT STYLE="ARIAL NARROW" COLOR="#ffffff"
SIZE=1>State/Province</FONT>
</TD>
</TR>
<!--Display ADO Data from Customer Table-->
<TR>
<TD BGCOLOR="f7efde" ALIGN=CENTER>
<FONT STYLE="ARIAL NARROW" SIZE=1>
<%= RSCustomerList("CompanyName")%>
</FONT></TD>
<TD BGCOLOR="f7efde" ALIGN=CENTER>
<FONT STYLE="ARIAL NARROW" SIZE=1>
<%= RScustomerList("ContactLastName") & ", " %>
<%= RScustomerList("ContactFirstName") %>
</FONT></TD>
<TD BGCOLOR="f7efde" ALIGN=CENTER>
<FONT STYLE="ARIAL NARROW" SIZE=1>
<%= RScustomerList("PhoneNumber")%>
</FONT></TD>
<TD BGCOLOR="f7efde" ALIGN=CENTER>
<FONT STYLE="ARIAL NARROW" SIZE=1>
<%= RScustomerList("City")%>
</FONT></TD>
<TD BGCOLOR="f7efde" ALIGN=CENTER>
<FONT STYLE="ARIAL NARROW" SIZE=1>
<%= RScustomerList("StateOrProvince")%>
</FONT></TD>
</TR> </Table></FONT>
355
Chili!Soft ASP 3.6 Product Documentation
<HR>
<Input Type = Button Name = cmdDown Value = "< ">
<Input Type = Button Name = cmdUp Value = " >">
<H5>Click Direction Arrows for Previous or Next Record
<BR> Click Move Amount to use Move Method
Enter Number of Records to Move + or - </H5>
<Table>
<Form Method = Post Action="Move.asp" Name=Form>
<TR><TD><Input Type="Button" Name = Move Value="Move Amount
"></TD><TD></TD><TD>
<Input Type="Text" Size="4" Name="MoveAmount" Value = 0></TD><TR>
</Form></Table></Center>
</BODY>
<Script Language = "VBScript">
Sub Move_OnClick
' Make sure move value entered is an integer
If IsNumeric(Document.Form.MoveAmount.Value)Then
Document.Form.MoveAmount.Value =
CInt(Document.Form.MoveAmount.Value)
Document.Form.Submit
Else
MsgBox "You Must Enter a Number", ,"ADO-ASP Example"
Document.Form.MoveAmount.Value = 0
End If
End Sub
Sub cmdDown_OnClick
Document.Form.MoveAmount.Value = -1
Document.Form.Submit
End Sub
Sub cmdUp_OnClick
Document.Form.MoveAmount.Value = 1
Document.Form.Submit
End Sub
356
Chili!Soft ASP 3.6 Product Documentation
357
</Script>
</HTML>
ADO Recordset Object MoveFirst, MoveLast, MoveNext, MovePrevious Methods
These methods move to the first, last, next, or previous record in a specified Recordset object
and make that record the current record.
MoveFirst, MoveLast, MoveNext, MovePrevious Methods Syntax
recordset.{MoveFirst | MoveLast | MoveNext | MovePrevious}
MoveFirst, MoveLast, MoveNext, MovePrevious Methods Remarks
Use the MoveFirst method to move the current record position to the first record in the recordset.
Use the MoveLast method to move the current record position to the last record in the recordset.
The Recordset object must support bookmarks or backward cursor movement; otherwise, the
method call will generate an error.
Use the MoveNext method to move the current record position one record forward (toward the
bottom of the recordset). If the last record is the current record and you call the MoveNext
method, ADO sets the current record to the position after the last record in the recordset (EOF is
True). An attempt to move forward when the ADO Recordset Object BOF, EOF Properties
property is already True generates an error.
Use the MovePrevious method to move the current record position one record backward (toward
the top of the recordset). The Recordset object must support bookmarks or backward cursor
movement; otherwise, the method call will generate an error. If the first record is the current
record and you call the MovePrevious method, ADO sets the current record to the position
before the first record in the recordset (BOF is True). An attempt to move backward when the
ADO Recordset Object BOF, EOF Properties property is already True generates an error. If the
Recordset object does not support either bookmarks or backward cursor movement, the
MovePrevious method will generate an error.
If the recordset is forward-only and you want to support both forward and backward scrolling,
you can use the ADO Recordset Object CacheSize Property to create a record cache that will
support backward cursor movement through the ADO Recordset Object Move Method. Because
cached records are loaded into memory, you should avoid caching more records than is necessary.
You can call the MoveFirst method in a forward-only Recordset object; doing so may cause the
provider to re-execute the command that generated the Recordset object.
MoveFirst, MoveLast, MoveNext, MovePrevious Methods Example
This VBScript example uses the MoveFirst, MoveLast, MoveNext, and MovePrevious methods
to move the record pointer of a recordset based on the supplied command. The MoveAny
function is required for this procedure to run. Try moving beyond the upper or lower limits of the
recordset to see error-handling work.
<!-- #Include file="ADOVBS.INC" -->
Chili!Soft ASP 3.6 Product Documentation
<% Language = VBScript %>
<HTML><HEAD>
<TITLE>ADO 1.5 MoveNext MovePrevious MoveLast MoveFirst
Methods</TITLE></HEAD>
<BODY>
<FONT FACE="MS SANS SERIF" SIZE=2>
<Center>
<H3>ADO Methods<BR>MoveNext MovePrevious MoveLast MoveFirst</H3>
<!-- Create Connection and Recordset Objects on Server -->
<%
'Create and Open Connection Object
Set OBJdbConnection = Server.CreateObject("ADODB.Connection")
OBJdbConnection.Open "AdvWorks"
'Create and Open Recordset Object
Set RsCustomerList = Server.CreateObject("ADODB.Recordset")
RsCustomerList.ActiveConnection = OBJdbConnection
RsCustomerList.CursorType = adOpenKeyset
RsCustomerList.LockType = adLockOptimistic
RsCustomerList.Source = "Customers"
RsCustomerList.Open
' Check Request.Form collection to see if any moves are recorded
If Not IsEmpty(Request.Form("MoveAmount")) Then
'Keep track of the number and direction of moves this session
Session("Moves") = Session("Moves") + Request.Form("MoveAmount")
Clicks = Session("Moves")
'Move to last known position
RsCustomerList.Move CInt(Clicks)
'Check if move is + or - and do error checking
If CInt(Request.Form("MoveAmount")) = 1 Then
If RsCustomerList.EOF Then
Session("Moves") = RsCustomerList.RecordCount
RsCustomerList.MoveLast
End If
358
Chili!Soft ASP 3.6 Product Documentation
RsCustomerList.MoveNext
End If
If Request.Form("MoveAmount") < 1 Then
RsCustomerList.MovePrevious
End If
'Check if First Record or Last Record Command Buttons Clicked
If Request.Form("MoveLast") = 3 Then
RsCustomerList.MoveLast
Session("Moves") = RsCustomerList.RecordCount
End If
If Request.Form("MoveFirst") = 2 Then
RsCustomerList.MoveFirst
Session("Moves") = 1
End If
End If
' Do Error checking for combination of Move Button clicks
If RsCustomerList.EOF Then
Session("Moves") = RsCustomerList.RecordCount
RsCustomerList.MoveLast
Response.Write "This is the Last Record"
End If
If RsCustomerList.BOF Then
Session("Moves") = 1
RsCustomerList.MoveFirst
Response.Write "This is the First Record"
End If
%>
<H3>Current Record Number is <BR>
<!-- Display Current Record Number and Recordset Size -->
<% If IsEmpty(Session("Moves")) Then
Session("Moves") = 1
End If
359
Chili!Soft ASP 3.6 Product Documentation
%>
<%Response.Write(Session("Moves") )%> of
<%=RsCustomerList.RecordCount%></H3>
<HR>
<Center><TABLE COLSPAN=8 CELLPADDING=5 BORDER=0>
<!-- BEGIN column header row for Customer Table-->
<TR><TD ALIGN=CENTER BGCOLOR="#008080">
<FONT STYLE="ARIAL NARROW" COLOR="#ffffff" SIZE=1>Company
Name</FONT>
</TD>
<TD ALIGN=CENTER BGCOLOR="#008080">
<FONT STYLE="ARIAL NARROW" COLOR="#ffffff" SIZE=1>Contact
Name</FONT>
</TD>
<TD ALIGN=CENTER WIDTH=150 BGCOLOR="#008080">
<FONT STYLE="ARIAL NARROW" COLOR="#ffffff" SIZE=1>Phone
Number</FONT>
</TD>
<TD ALIGN=CENTER BGCOLOR="#008080">
<FONT STYLE="ARIAL NARROW" COLOR="#ffffff" SIZE=1>City</FONT>
</TD>
<TD ALIGN=CENTER BGCOLOR="#008080">
<FONT STYLE="ARIAL NARROW" COLOR="#ffffff"
SIZE=1>State/Province</FONT>
</TD></TR>
<!--Display ADO Data from Customer Table-->
<TR>
<TD BGCOLOR="f7efde" ALIGN=CENTER>
<FONT STYLE="ARIAL NARROW" SIZE=1>
<%= RSCustomerList("CompanyName")%>
</FONT></TD>
<TD BGCOLOR="f7efde" ALIGN=CENTER>
<FONT STYLE="ARIAL NARROW" SIZE=1>
<%= RScustomerList("ContactLastName") & ", " %>
360
Chili!Soft ASP 3.6 Product Documentation
<%= RScustomerList("ContactFirstName") %>
</FONT></TD>
<TD BGCOLOR="f7efde" ALIGN=CENTER>
<FONT STYLE="ARIAL NARROW" SIZE=1>
<%= RScustomerList("PhoneNumber")%>
</FONT></TD>
<TD BGCOLOR="f7efde" ALIGN=CENTER>
<FONT STYLE="ARIAL NARROW" SIZE=1>
<%= RScustomerList("City")%>
</FONT></TD>
<TD BGCOLOR="f7efde" ALIGN=CENTER>
<FONT STYLE="ARIAL NARROW" SIZE=1>
<%= RScustomerList("StateOrProvince")%>
</FONT></TD>
</TR> </Table></FONT>
<HR>
<Input Type = Button Name = cmdDown Value = "< ">
<Input Type = Button Name = cmdUp Value = " >">
<BR>
<Input Type = Button Name = cmdFirst Value = "First Record">
<Input Type = Button Name = cmdLast Value = "Last Record">
<H5>Click Direction Arrows to Use MovePrevious or MoveNext
<BR> </H5>
<!-- Use Hidden Form Fields to send values to Server -->
<Form Method = Post Action="MoveOne.asp" Name=Form>
<Input Type="Hidden" Size="4" Name="MoveAmount" Value = 0>
<Input Type="Hidden" Size="4" Name="MoveLast" Value = 0>
<Input Type="Hidden" Size="4" Name="MoveFirst" Value = 0>
</Form></BODY>
<Script Language = "VBScript">
Sub cmdDown_OnClick
'Set Values in Form Input Boxes and Submit Form
361
Chili!Soft ASP 3.6 Product Documentation
362
Document.Form.MoveAmount.Value = -1
Document.Form.Submit
End Sub
Sub cmdUp_OnClick
Document.Form.MoveAmount.Value = 1
Document.Form.Submit
End Sub
Sub cmdFirst_OnClick
Document.Form.MoveFirst.Value = 2
Document.Form.Submit
End Sub
Sub cmdLast_OnClick
Document.Form.MoveLast.Value = 3
Document.Form.Submit
End Sub
</Script></HTML>
ADO Recordset Object NextRecordset Method
Clears the current Recordset object and returns the next recordset by advancing through a series
of commands. This method is not currently supported on UNIX.
NextRecordset Method Syntax
Set recordset2 = recordset1.NextRecordset( RecordsAffected )
NextRecordset Method Parameters
recordset2
Recordset containing results of command.
RecordsAffected
An optional Long variable to which the provider returns the number of records that the current
operation affected.
NextRecordset Method Return Values
Returns a Recordset object. In the syntax model, recordset1 and recordset2 can be the same
Recordset object, or you can use separate objects.
NextRecordset Method Remarks
Chili!Soft ASP 3.6 Product Documentation
363
Use the NextRecordset method to return the results of the next command in a compound
command statement or of a stored procedure that returns multiple results. If you open a
Recordset object based on a compound command statement (for example, "SELECT * FROM
table1;SELECT * FROM table2") using the ADO Command Object Execute Method on
an ADO Command Object or the ADO Recordset Object Open Method on a recordset, ADO
executes only the first command and returns the results to recordset. To access the results of
subsequent commands in the statement, call the NextRecordset method.
As long as there are additional results, the NextRecordset method will continue to return
Recordset objects. If a row-returning command returns no records, the returned Recordset object
will be empty; test for this case by verifying that the ADO Recordset Object BOF, EOF
Properties are both True. If a non row-returning command executes successfully, the returned
Recordset object will be closed, which you can verify by testing the ADO Recordset Object State
Property on the recordset. When there are no more results, recordset will be set to Nothing.
If an edit is in progress while in immediate update mode, calling the NextRecordset method
generates an error; call the ADO Recordset Object Update Method or the ADO Recordset Object
CancelUpdate Method first.
If you need to pass parameters for more than one command in the compound statement by filling
the ADO Parameters Collection or by passing an array with the original Open or Execute call,
the parameters must be in the same order in the collection or array as their respective commands
in the command series. You must finish reading all the results before reading output parameter
values.
When you call the NextRecordset method, ADO executes only the next command in the
statement. If you explicitly close the Recordset object before stepping through the entire
command statement, ADO never executes the remaining commands.
The NextRecordset method is not available on a client-side (ADOR) Recordset object.
NextRecordset Method Example
This Visual Basic example uses the NextRecordset method to view the data in a recordset that
uses a compound command statement made up of three separate SELECT statements.
Public Sub NextRecordsetX()
Dim rstCompound As ADODB.Recordset
Dim strCnn As String
Dim intCount As Integer
` Open compound recordset.
strCnn = "driver={SQL Server};server=srv;" & _
"uid=sa;pwd=;database=pubs"
Set rstCompound = New ADODB.Recordset
rstCompound.Open "SELECT * FROM authors; " & _
"SELECT * FROM stores; " & _
Chili!Soft ASP 3.6 Product Documentation
364
"SELECT * FROM jobs", strCnn, , , adCmdText
` Display results from each SELECT statement.
intCount = 1
Do Until rstCompound Is Nothing
Debug.Print "Contents of recordset #" & intCount
Do While Not rstCompound.EOF
Debug.Print , rstCompound.Fields(0), _
rstCompound.Fields(1)
rstCompound.MoveNext
Loop
Set rstCompound = rstCompound.NextRecordset
intCount = intCount + 1
Loop
End Sub
ADO Recordset Object Open Method
Opens a cursor.
Open Method Syntax
recordset.Open Source, ActiveConnection, CursorType, LockType,
Options
Open Method Parameters
Source
An optional Variant that evaluates to a valid Command object variable name, an SQL statement,
a table name, or a stored procedure call.
ActiveConnection
An optional Variant that evaluates to a valid Connection object variable name, or a String
containing ConnectionString parameters.
CursorType
An optional CursorTypeEnum value that determines the type of cursor that the provider should
use when opening the recordset. Can be one of the following constants (See the ADO Recordset
Object CursorType Property for definitions of these settings.):
Constant
Description
adOpenForwardOnly Default. Opens a forward-only cursor.
Chili!Soft ASP 3.6 Product Documentation
adOpenKeyset
Opens a keyset cursor.
adOpenDynamic
Opens a dynamic cursor.
adOpenStatic
Opens a static cursor.
365
LockType
An optional LockTypeEnum value that determines what type of locking (concurrency) the
provider should use when opening the recordset. Can be one of the following constants (See the
LockType property for more information.):
Constant
Description
adLockReadOnly
Default. Read-only; you cannot alter the data.
adLocPessimistic
Pessimistic locking, record by record. The provider does what is
necessary to ensure successful editing of the records, usually by
locking records at the data source immediately upon editing.
adLockOptimistic
Optimistic locking, record by record. The provider uses optimistic
locking, locking records only when you call the Update method.
adLockBatchOptimisti Optimistic batch updates. Required for batch update mode as
c
opposed to immediate update mode.
Options
An optional Long value that indicates how the provider should evaluate the Source argument if it
represents something other than a Command object. Can be one of the following constants (See
the CommandType property for a more detailed explanation of these constants.):
Constant
Description
adCmdText
The provider should evaluate Source as a textual definition of a
command.
adCmdTable
The provider should evaluate Source as a table name.
adCmdStoredProc
The provider should evaluate Source as a stored procedure.
adCmdUnknown
The type of command in the Source argument is not known.
See the ADO Command Object CommandType Property for a more detailed explanation of the
four constants in this list.
Open Method Remarks
Using the Open method on a Recordset object opens a cursor that represents records from a base
table or the results of a query.
Use the optional Source argument to specify a data source using one of the following: an ADO
Command Object variable, an SQL statement, a stored procedure, or a table name.
The ActiveConnection argument corresponds to the ActiveConnection property and specifies in
which connection to open the Recordset object. If you pass a connection definition for this
argument, ADO opens a new connection using the specified parameters. You can change the
Chili!Soft ASP 3.6 Product Documentation
366
value of this property after opening the recordset to send updates to another provider. Or, you can
set this property to Nothing (in Microsoft Visual Basic) to disconnect the recordset from any
provider.
For the other arguments that correspond directly to properties of a Recordset object (Source,
CursorType, and LockType), the relationship of the arguments to the properties is as follows:
•
The property is read/write before the Recordset object is opened.
•
The property settings are used unless you pass the corresponding arguments when
executing the Open method. If you pass an argument, it overrides the corresponding
property setting, and the property setting is updated with the argument value.
•
After you open the Recordset object, these properties become read-only.
Note
For Recordset objects whose ADO Recordset Object Source Property is set to a valid
Command object, the ActiveConnection property is read-only, even if the Recordset
object isn't open.
If you pass a Command object in the Source argument and also pass an ActiveConnection
argument, an error occurs. The ActiveConnection property of the Command object must already
be set to a valid ADO Connection Object or connection string.
If you pass something other than a Command object in the Source argument, you can use the
Options argument to optimize evaluation of the Source argument. If the Options argument is not
defined, you may experience diminished performance because ADO must make calls to the
provider to determine if the argument is an SQL statement, a stored procedure, or a table name. If
you know what Source type you're using, setting the Options argument instructs ADO to jump
directly to the relevant code. If the Options argument does not match the Source type, an error
occurs.
If the data source returns no records, the provider sets both the ADO Recordset Object BOF, EOF
Properties to True, and the current record position is undefined. You can still add new data to this
empty Recordset object if the cursor type allows it.
When you have concluded your operations over an open Recordset object, use the ADO
Recordset Object Close Method to free any associated system resources. Closing an object does
not remove it from memory; you may change its property settings and use the Open method to
open it again later. To completely eliminate an object from memory, set the object variable to
Nothing.
Open Method Examples
See the ADO Recordset Object Close Method.
ADO Recordset Object Requery Method
Updates the data in a Recordset object by re-executing the query on which the object is based.
Requery Method Syntax
Chili!Soft ASP 3.6 Product Documentation
367
recordset.Requery
Requery Method Remarks
Use the Requery method to refresh the entire contents of a Recordset object from the data source
by reissuing the original command and retrieving the data a second time. Calling this method is
equivalent to calling the ADO Recordset Object Close Method and ADO Recordset Object Open
Method methods in succession. If you are editing the current record or adding a new record, an
error occurs.
While the Recordset object is open, the properties that define the nature of the cursor (ADO
Recordset Object CursorType Property, ADO Recordset Object LockType Property, ADO
Recordset Object MaxRecords Property, and so forth) are read-only. Thus, the Requery method
can only refresh the current cursor. To change any of the cursor properties and view the results,
you must use the Close method so that the properties become read/write again. You can then
change the property settings and call the Open method to reopen the cursor.
Requery Method Example
See the command ADO Command Object Execute Method.
ADO Recordset Object Resync Method
Refreshes the data in the current Recordset object from the underlying database.
Resync Method Syntax
recordset.Resync AffectRecords
Resync Method Parameters
AffectRecords
An optional AffectEnum constant that determines how many records the Resync method will
affect. Can be one of the following constants:
Constant
Description
adAffectCurrent Refresh only the current record.
adAffectGroup
Refresh the records that satisfy the current Filter property setting. You
must set the Filter property to one of the valid predefined constants in
order to use this option. The Filter property is not currently supported
on UNIX.
adAffectAll
Default. Refresh all the records in the Recordset object, including any
hidden by the current Filter property setting.
Resync Method Remarks
Use the Resync method to re-synchronize records in the current recordset with the underlying
database. This is useful if you are using either a static or forward-only cursor but you want to see
Chili!Soft ASP 3.6 Product Documentation
368
any changes in the underlying database. Calling the Resync method cancels any pending batch
updates.
Unlike the ADO Recordset Object Requery Method, the Resync method does not re-execute the
Recordset object's underlying command; new records in the underlying database will not be
visible.
If the attempt to resynchronize fails because of a conflict with the underlying data (for example, a
record has been deleted by another user), the provider returns warnings to the ADO Errors
Collection, but does not halt program execution. A run-time error occurs only if there are
conflicts on all the requested records. Use the ADO Recordset Object Filter Property
(adFilterAffectedRecords) and the ADO Recordset Object Status Property to locate records with
conflicts.
Resync Method Examples
This Visual Basic example demonstrates using the Resync method to refresh data in a static
recordset.
Public Sub ResyncX()
Dim strCnn As String
Dim rstTitles As ADODB.Recordset
' Open connections.
strCnn = "driver={SQL Server};server=srv;" & _
"uid=sa;pwd=;database=pubs"
' Open recordset for titles table.
Set rstTitles = New ADODB.Recordset
rstTitles.CursorType = adOpenStatic
rstTitles.LockType = adLockBatchOptimistic
rstTitles.Open "titles", strCnn, , , adCmdTable
' Change the type of the first title in the recordset.
rstTitles!Type = "database"
' Display the results of the change.
MsgBox "Before resync: " & vbCr & vbCr & _
"Title - " & rstTitles!Title & vbCr & _
"Type - " & rstTitles!Type
' Resync with database and redisplay results.
rstTitles.Resync
MsgBox "After resync: " & vbCr & vbCr & _
Chili!Soft ASP 3.6 Product Documentation
369
"Title - " & rstTitles!Title & vbCr & _
"Type - " & rstTitles!Type
rstTitles.CancelBatch
rstTitles.Close
End Sub
ADO Recordset Object Supports Method
Determines whether a specified Recordset object supports a particular type of functionality.
Supports Method Syntax
boolean = recordset.Supports( CursorOptions )
Supports Method Parameters
CursorOptions
A Long expression that consists of one or more of the following CursorOptionEnum values:
Value
Description
adAddNew
The AddNew method adds new records.
adApproxPositionYou can read and set the AbsolutePosition and AbsolutePage properties.
adBookmark
The Bookmark property accesses specific records.
adDelete
The Delete method deletes records.
adHoldRecords
You can retrieve more records or change the next retrieve position without
committing all pending changes.
adMovePrevious The MoveFirst, MovePrevious, Move, and GetRows methods move the
current position backward without requiring bookmarks.
adResync
The Resync method modifies existing data.
adUpdate
The Update method modifies existing data.
adUpdateBatch
The UpdateBatch and CancelBatch methods transmit changes to the
provider in groups.
Supports Method Remarks
Use the Supports method to determine what types of functionality a Recordset object supports.
If the Recordset object supports the features whose corresponding constants are in
CursorOptions, the Supports method returns True. Otherwise, it returns False.
Chili!Soft ASP 3.6 Product Documentation
370
Note
Although the Supports method may return True for a given functionality, it does not
guarantee that the provider can make the feature available under all circumstances. The
Supports method simply returns whether or not the provider can support the specified
functionality assuming certain conditions are met. For example, the Supports method
may indicate that a Recordset object supports updates even though the cursor is based on
a multi-table join, some columns of which are not updatable.
Supports Method Examples
This Visual Basic example uses the Supports method to display the options supported by a
recordset opened with different cursor types. The DisplaySupport function is required for this
procedure to run.
Public Sub SupportsX()
Dim aintCursorType(4) As Integer
Dim rstTitles As ADODB.Recordset
Dim strCnn As String
Dim intIndex As Integer
` Open connections.
strCnn = "driver={SQL Server};server=srv;" & _
"uid=sa;pwd=;database=pubs"
` Fill array with CursorType constants.
aintCursorType(0) = adOpenForwardOnly
aintCursorType(1) = adOpenKeyset
aintCursorType(2) = adOpenDynamic
aintCursorType(3) = adOpenStatic
` Open recordset using each CursorType and
` optimitic locking. Then call the DisplaySupport
` procedure to display the supported options.
For intIndex = 0 To 3
Set rstTitles = New ADODB.Recordset
rstTitles.CursorType = aintCursorType(intIndex)
rstTitles.LockType = adLockOptimistic
rstTitles.Open "titles", strCnn, , , adCmdTable
Select Case aintCursorType(intIndex)
Case adOpenForwardOnly
Chili!Soft ASP 3.6 Product Documentation
Debug.Print "ForwardOnly cursor supports:"
Case adOpenKeyset
Debug.Print "Keyset cursor supports:"
Case adOpenDynamic
Debug.Print "Dynamic cursor supports:"
Case adOpenStatic
Debug.Print "Static cursor supports:"
End Select
DisplaySupport rstTitles
rstTitles.Close
Next intIndex
End Sub
Public Sub DisplaySupport(rstTemp As ADODB.Recordset)
Dim alngConstants(9) As Long
Dim booSupports As Boolean
Dim intIndex As Integer
' Fill array with cursor option constants.
alngConstants(0) = adAddNew
alngConstants(1) = adApproxPosition
alngConstants(2) = adBookmark
alngConstants(3) = adDelete
alngConstants(4) = adHoldRecords
alngConstants(5) = adMovePrevious
alngConstants(6) = adResync
alngConstants(7) = adUpdate
alngConstants(8) = adUpdateBatch
For intIndex = 0 To 8
booSupports = _
rstTemp.Supports(alngConstants(intIndex))
If booSupports Then
Select Case alngConstants(intIndex)
Case adAddNew
371
Chili!Soft ASP 3.6 Product Documentation
372
Debug.Print " AddNew"
Case adApproxPosition
Debug.Print " AbsolutePosition and AbsolutePage"
Case adBookmark
Debug.Print " Bookmark"
Case adDelete
Debug.Print " Delete"
Case adHoldRecords
Debug.Print " holding records"
Case adMovePrevious
Debug.Print " MovePrevious and Move"
Case adResync
Debug.Print " resyncing data"
Case adUpdate
Debug.Print " Update"
Case adUpdateBatch
Debug.Print " batch updating"
End Select
End If
Next intIndex
End Sub
ADO Recordset Object Update Method
Saves any changes you make to the current record of a Recordset object.
Note
This method is not available for some databases and ODBC drivers.
Update Method Syntax
recordset.Update Fields, Values
Update Method Parameters
Fields
An optional Variant representing a single name or a Variant array representing names or ordinal
positions of the field or fields you wish to modify.
Chili!Soft ASP 3.6 Product Documentation
373
Values
An optional Variant representing a single value or a Variant array representing values for the
field or fields in the new record.
Update Method Remarks
Use the Update method to save any changes you make to the current record of a Recordset
object since calling the ADO Recordset Object AddNew Method or since changing any field
values in an existing record. The Recordset object must support updates.
To set field values, do one of the following:
•
Assign values to a ADO Field Object object's ADO Field Object Value Property and call
the ADO Recordset Object Update Method.
•
Pass a field name and a value as arguments with the Update call.
•
Pass an array of field names and an array of values with the Update call.
When you use arrays of fields and values, there must be an equal number of elements in both
arrays. Also, the order of field names must match the order of field values. If the number and
order of fields and values do not match, an error occurs.
If the Recordset object supports batch updating, then you can cache multiple changes to one or
more records locally until you call the ADO Recordset Object UpdateBatch Method. If you are
editing the current record or adding a new record when you call the UpdateBatch method, ADO
will automatically call the Update method to save any pending changes to the current record
before transmitting the batched changes to the provider. Batch updating is not currently
supported on UNIX.
If you move from the record you are adding or editing before calling the Update method, ADO
will automatically call Update to save the changes. You must call the ADO Recordset Object
CancelUpdate Method if you want to cancel any changes made to the current record or to discard
a newly added record.
The current record remains current after you call the Update method.
Update Method Examples
The following Visual Basic examples show how to use the Update method.
The first example demonstrates using the Update method in conjunction with CancelUpdate
method.
Public Sub UpdateX()
Dim rstEmployees As ADODB.Recordset
Dim strOldFirst As String
Dim strOldLast As String
Dim strMessage As String
` Open recordset with names from Employee table.
Chili!Soft ASP 3.6 Product Documentation
strCnn = "driver={SQL Server};server=srv;" & _
"uid=sa;pwd=;database=pubs"
Set rstEmployees = New ADODB.Recordset
rstEmployees.CursorType = adOpenKeyset
rstEmployees.LockType = adLockOptimistic
rstEmployees.Open "SELECT fname, lname " & _
"FROM Employee ORDER BY lname", strCnn, , , adCmdText
` Store original data.
strOldFirst = rstEmployees!fname
strOldLast = rstEmployees!lname
` Change data in edit buffer.
rstEmployees!fname = "Linda"
rstEmployees!lname = "Kobara"
` Show contents of buffer and get user input.
strMessage = "Edit in progress:" & vbCr & _
" Original data = " & strOldFirst & " " & _
strOldLast & vbCr & " Data in buffer = " & _
rstEmployees!fname & " " & rstEmployees!lname & vbCr & vbCr & _
"Use Update to replace the original data with " & _
"the buffered data in the Recordset?"
If MsgBox(strMessage, vbYesNo) = vbYes Then
rstEmployees.Update
Else
rstEmployees.CancelUpdate
End If
` Show the resulting data.
MsgBox "Data in recordset = " & rstEmployees!fname & " " & _
rstEmployees!lname
` Restore original data because this is a demonstration.
If Not (strOldFirst = rstEmployees!fname And _
strOldLast = rstEmployees!lname) Then
rstEmployees!fname = strOldFirst
374
Chili!Soft ASP 3.6 Product Documentation
375
rstEmployees!lname = strOldLast
rstEmployees.Update
End If
rstEmployees.Close
End Sub
The following example demonstrates using the Update method in conjunction with the AddNew
method:
Public Sub UpdateX2()
Dim cnn1 As ADODB.Connection
Dim rstEmployees As ADODB.Recordset
Dim strEmpID As String
Dim strOldFirst As String
Dim strOldLast As String
Dim strMessage As String
' Open a connection.
Set cnn1 = New ADODB.Connection
strCnn = "driver={SQL Server};server=srv;" & _
"uid=sa;pwd=;database=pubs"
cnn1.Open strCnn
' Open recordset with data from Employee table.
Set rstEmployees = New ADODB.Recordset
rstEmployees.CursorType = adOpenKeyset
rstEmployees.LockType = adLockOptimistic
rstEmployees.Open "employee", cnn1, , , adCmdTable
rstEmployees.AddNew
strEmpID = "B-S55555M"
rstEmployees!emp_id = strEmpID
rstEmployees!fname = "Bill"
rstEmployees!lname = "Sornsin"
' Show contents of buffer and get user input.
strMessage = "AddNew in progress:" & vbCr & _
"Data in buffer = " & rstEmployees!emp_id & ", " & _
rstEmployees!fname & " " & rstEmployees!lname & vbCr & vbCr & _
Chili!Soft ASP 3.6 Product Documentation
376
"Use Update to save buffer to recordset?"
If MsgBox(strMessage, vbYesNoCancel) = vbYes Then
rstEmployees.Update
` Go to the new record and show the resulting data.
MsgBox "Data in recordset = " & rstEmployees!emp_id & ", " & _
rstEmployees!fname & " " & rstEmployees!lname
Else
rstEmployees.CancelUpdate
MsgBox "No new record added."
End If
' Delete new data because this is a demonstration.
cnn1.Execute "DELETE FROM employee WHERE emp_id = '" & strEmpID &
"'"
rstEmployees.Close
End Sub
ADO Recordset Object UpdateBatch Method
Writes all pending batch updates to disk. This method is not currently supported on UNIX.
UpdateBatch Method Syntax
recordset.UpdateBatch AffectRecords
UpdateBatch Method Parameters
AffectRecords
An optional AffectEnum value that determines how many records the UpdateBatch method will
affect. Can be one of the following constants:
Constant
Description
AdAffectCurre
nt
Write pending changes only for the current record.
AdAffectGroup
Write pending changes for the records that satisfy the current Filter
property setting. You must set the Filter property to one of the valid
predefined constants in order to use this option.
adAffectAll
Default. Write pending changes for all the records in the Recordset
object, including any hidden by the current Filter property setting.
UpdateBatch Method Remarks
Chili!Soft ASP 3.6 Product Documentation
377
Use the UpdateBatch method when modifying a Recordset object in batch update mode to
transmit all changes made in a Recordset object to the underlying database.
If the Recordset object supports batch updating, then you can cache multiple changes to one or
more records locally until you call the UpdateBatch method. If you are editing the current record
or adding a new record when you call the UpdateBatch method, ADO will automatically call the
ADO Recordset Object Update Method to save any pending changes to the current record before
transmitting the batched changes to the provider.
Note
You should use batch updating only with either a keyset or static cursor.
If the attempt to transmit changes fails because of a conflict with the underlying data (for
example, a record has already been deleted by another user), the provider returns warnings to the
ADO Errors Collection but does not halt program execution. A run-time error occurs only if there
are conflicts on all the requested records. Use the ADO Recordset Object Filter Property
(adFilterAffectedRecords) and the ADO Recordset Object Status Property to locate records with
conflicts.
To cancel all pending batch updates, use the ADO Recordset Object CancelBatch Method.
UpdateBatch Method Example
See the ADO Recordset Object CancelBatch Method example.
ADO Recordset Object Properties
ADO Recordset Object AbsolutePage Property
Specifies in which page the current record resides.
AbsolutePage Property Return Values
Sets or returns a Long value from 1 to the number of pages in the Recordset object
(PageCount), or returns one of the following constants:
Constant
Description
adPosUnknown
The recordset is empty, the current position is unknown, or the
provider does not support the AbsolutePage property
adPosBOF
The current record pointer is at BOF (that is, the BOF property is
True).
adPosEOF
The current record pointer is at EOF (that is, the EOF property is
True).
AbsolutePage Property Remarks
Use the AbsolutePage property to identify the page number on which the current record is
located. Use the ADO Recordset Object PageSize Property to logically divide the Recordset
Chili!Soft ASP 3.6 Product Documentation
378
object into a series of pages, each of which has the number of records equal to PageSize (except
for the last page, which may have fewer records). The provider must support the appropriate
functionality for this property to be available.
Like the AbsolutePosition property, AbsolutePage is 1-based and equals 1 when the current
record is the first record in the recordset. Set this property to move to the first record of a
particular page. Obtain the total number of pages from the ADO Recordset Object PageCount
Property.
AbsolutePage Property Example
This Visual Basic example uses the AbsolutePage, PageCount, and PageSize properties to
display names and hire dates from the Employees table five records at a time.
Public Sub AbsolutePageX()
Dim rstEmployees As ADODB.Recordset
Dim strCnn As String
Dim strMessage As String
Dim intPage As Integer
Dim intPageCount As Integer
Dim intRecord As Integer
` Open a recordset using a client cursor
` for the employee table.
strCnn = "driver={SQL Server};server=srv;" & _
"uid=sa;pwd=;database=pubs"
Set rstEmployees = New ADODB.Recordset
` Use client cursor to enable AbsolutePosition property.
rstEmployees.CursorLocation = adUseClient
rstEmployees.Open "employee", strCnn, , , adCmdTable
` Display names and hire dates, five records
` at a time.
rstEmployees.PageSize = 5
intPageCount = rstEmployees.PageCount
For intPage = 1 To intPageCount
rstEmployees.AbsolutePage = intPage
strMessage = ""
For intRecord = 1 To rstEmployees.PageSize
Chili!Soft ASP 3.6 Product Documentation
379
strMessage = strMessage & _
rstEmployees!fname & " " & _
rstEmployees!lname & " " & _
rstEmployees!hire_date & vbCr
rstEmployees.MoveNext
If rstEmployees.EOF Then Exit For
Next intRecord
MsgBox strMessage
Next intPage
rstEmployees.Close
End Sub
ADO Recordset Object AbsolutePosition Property
Specifies the ordinal position of a Recordset object's current record.
AbsolutePosition Property Return Values
Sets or returns a Long value from 1 to the number of records in the Recordset object
(RecordCount), or returns one of the following constants:
Constant
Description
adPosUnknown
The recordset is empty, the current position is unknown, or the
provider does not support the AbsolutePosition property.
adPosBOF
The current record pointer is at BOF (that is, the BOF property is
True).
adPosEOF
The current record pointer is at EOF (that is, the EOF property is
True).
AbsolutePosition Property Remarks
Use the AbsolutePosition property to move to a record based on its ordinal position in the
Recordset object, or to determine the ordinal position of the current record. The provider must
support the appropriate functionality for this property to be available.
Like the AbsolutePage property, AbsolutePosition is 1-based and equals 1 when the current
record is the first record in the recordset. You can obtain the total number of records in the
Recordset object from the RecordCount property.
When you set the AbsolutePosition property, even if it is to a record in the current cache, ADO
reloads the cache with a new group of records starting with the record you specified. The ADO
Recordset Object CacheSize Property determines the size of this group.
Chili!Soft ASP 3.6 Product Documentation
Note
You should not use the AbsolutePosition property as a surrogate record number. The
position of a given record changes when you delete a preceding record. There is also no
assurance that a given record will have the same AbsolutePosition if the Recordset
object is requeried or reopened. Bookmarks are still the recommended way of retaining
and returning to a given position, and are the only way of positioning across all types of
Recordset objects.
AbsolutePosition Property Example
This Visual Basic example demonstrates how the AbsolutePosition property can track the
progress of a loop that enumerates all the records of a recordset. It uses the CursorLocation
property to enable the AbsolutePosition property by setting the cursor to a client cursor.
Public Sub AbsolutePositionX()
Dim rstEmployees As ADODB.Recordset
Dim strCnn As String
Dim strMessage As String
' Open a recordset for the Employee table
' using a client cursor.
strCnn = "driver={SQL Server};server=srv;" & _
"uid=sa;pwd=;database=pubs"
Set rstEmployees = New ADODB.Recordset
' Use client cursor to enable AbsolutePosition property.
rstEmployees.CursorLocation = adUseClient
rstEmployees.Open "employee", strCnn, , , adCmdTable
' Enumerate Recordset.
Do While Not rstEmployees.EOF
' Display current record information.
strMessage = "Employee: " & rstEmployees!lName & vbCr & _
"(record " & rstEmployees.AbsolutePosition & _
" of " & rstEmployees.RecordCount & ")"
If MsgBox(strMessage, vbOKCancel) = vbCancel _
Then Exit Do
rstEmployees.MoveNext
Loop
rstEmployees.Close
380
Chili!Soft ASP 3.6 Product Documentation
381
End Sub
ADO Recordset Object ActiveConnection Property
Specifies to which Connection object the Recordset object currently belongs.
ActiveConnection Property Return Values (ADO Recordset Object)
Sets or returns a String containing the definition for a connection or an ADO Connection Object.
Default is a Null object reference.
ActiveConnection Property Remarks (ADO Recordset Object)
Use the ActiveConnection property to determine the Connection object over which the specified
Command object will execute or the specified recordset will be opened.
For open Recordset objects or for Recordset objects whose ADO Recordset Object Source
Property is set to a valid ADO Command Object, the ActiveConnection property is read-only.
Otherwise, it is read/write.
You can set this property to a valid Connection object or to a valid connection string. In this
case, the provider creates a new Connection object using this definition and opens the
connection. Additionally, the provider may set this property to the new Connection object to give
you a way to access the Connection object for extended error information or to execute other
commands.
If you use the ActiveConnection argument of the ADO Recordset Object Open Method to open a
Recordset object, the ActiveConnection property will inherit the value of the argument.
If you set the Source property of the Recordset object to a valid Command object variable, the
ActiveConnection property of the recordset inherits the setting of the Command object's
ActiveConnection property.
ActiveConnection Property Example (ADO Recordset Object)
This Visual Basic example uses the ActiveConnection, ADO Command Object CommandText
Property, CommandTimeout, ADO Command Object CommandType Property, ADO Parameter
Object Size Property, and ADO Parameter Object Direction Property properties to execute a
stored procedure:
Public Sub ActiveConnectionX()
Dim cnn1 As ADODB.Connection
Dim cmdByRoyalty As ADODB.Command
Dim prmByRoyalty As ADODB.Parameter
Dim rstByRoyalty As ADODB.Recordset
Dim rstAuthors As ADODB.Recordset
Dim intRoyalty As Integer
Dim strAuthorID As String
Chili!Soft ASP 3.6 Product Documentation
Dim strCnn As String
` Define a command object for a stored procedure.
Set cnn1 = New ADODB.Connection
strCnn = "driver={SQL Server};server=srv;" & _
"uid=sa;pwd=;database=pubs"
cnn1.Open strCnn
Set cmdByRoyalty = New ADODB.Command
Set cmdByRoyalty.ActiveConnection = cnn1
cmdByRoyalty.CommandText = "byroyalty"
cmdByRoyalty.CommandType = adCmdStoredProc
cmdByRoyalty.CommandTimeout = 15
` Define the stored procedure's input parameter.
intRoyalty = Trim(InputBox( _
"Enter royalty:"))
Set prmByRoyalty = New ADODB.Parameter
prmByRoyalty.Type = adInteger
prmByRoyalty.Size = 3
prmByRoyalty.Direction = adParamInput
prmByRoyalty.Value = intRoyalty
cmdByRoyalty.Parameters.Append prmByRoyalty
` Create a recordset by executing the command.
Set rstByRoyalty = cmdByRoyalty.Execute()
` Open the Authors table to get author names for display.
Set rstAuthors = New ADODB.Recordset
rstAuthors.Open "authors", strCnn, , , adCmdTable
` Print current data in the recordset, adding
` author names from Authors table.
Debug.Print "Authors with " & intRoyalty & _
" percent royalty"
Do While Not rstByRoyalty.EOF
strAuthorID = rstByRoyalty!au_id
Debug.Print , rstByRoyalty!au_id & ", ";
382
Chili!Soft ASP 3.6 Product Documentation
383
rstAuthors.Filter = "au_id = '" & strAuthorID & "'"
Debug.Print rstAuthors!au_fname & " " & _
rstAuthors!au_lname
rstByRoyalty.MoveNext
Loop
rstByRoyalty.Close
rstAuthors.Close
cnn1.Close
End Sub
ADO Recordset Object BOF, EOF Properties
BOF indicates that the current record position is before the first record in a Recordset object.
EOF indicates that the current record position is after the last record in a Recordset object.
BOF, EOF Properties Return Values
The BOF and EOF properties return Boolean values.
BOF, EOF Properties Remarks
Use the BOF and EOF properties to determine whether a Recordset object contains records or
whether you've gone beyond the limits of a Recordset object when you move from record to
record.
The BOF property returns True (-1) if the current record position is before the first record and
False (0) if the current record position is on or after the first record.
The EOF property returns True if the current record position is after the last record and False if
the current record position is on or before the last record.
If either the BOF or EOF property is True, there is no current record.
If you open a Recordset object containing no records, the BOF and EOF properties are set to
True, and the Recordset object's RecordCount property setting is zero. When you open a
Recordset object that contains at least one record, the first record is the current record and the
BOF and EOF properties are False.
If you delete the last remaining record in the Recordset object, the BOF and EOF properties may
remain False until you attempt to reposition the current record.
This table shows which ADO Recordset Object Move Method methods are allowed with different
combinations of the BOF and EOF properties:
384
Chili!Soft ASP 3.6 Product Documentation
MoveFirst
MoveLast
MovePreviou
s
Move < 0
Move 0
MoveNext
Move > 0
BOF =
True,
EOF =
False
Allowed
Error
Error
Allowed
BOF=False
EOF=True
Allowed
Allowed
Error
Error
Both True
Error
Error
Error
Error
Both False
Allowed
Allowed
Allowed
Allowed
Allowing a Move method doesn't guarantee that the method will successfully locate a record; it
only means that calling the specified Move method won't generate an error.
The following table shows what happens to the BOF and EOF property settings when you call
various Move methods but are unable to successfully locate a record.
BOF
EOF
MoveFirst, MoveLast
Set to True
Set to True
Move 0
No change
No change
MovePrevious, Move < 0
Set to True
No change
MoveNext, Move > 0
No change
Set to True
BOF, EOF Properties Example
This Visual Basic example uses the BOF and EOF properties to display a message if a user tries
to move past the first or last record of a recordset. It uses the ADO Recordset Object Bookmark
Property to let the user flag a record in a recordset and return to it later.
Public Sub BOFX()
Dim rstPublishers As ADODB.Recordset
Dim strCnn As String
Dim strMessage As String
Dim intCommand As Integer
Dim varBookmark As Variant
` Open recordset with data from Publishers table.
strCnn = "driver={SQL Server};server=srv;" & _
"uid=sa;pwd=;database=pubs"
Set rstPublishers = New ADODB.Recordset
rstPublishers.CursorType = adOpenStatic
Chili!Soft ASP 3.6 Product Documentation
` Use client cursor to enable AbsolutePosition property.
rstPublishers.CursorLocation = adUseClient
rstPublishers.Open "SELECT pub_id, pub_name FROM publishers " & _
"ORDER BY pub_name", strCnn, , , adCmdText
rstPublishers.MoveFirst
Do While True
` Display information about current record
` and get user input.
strMessage = "Publisher: " & rstPublishers!pub_name & _
vbCr & "(record " & rstPublishers.AbsolutePosition & _
" of " & rstPublishers.RecordCount & ")" & vbCr & vbCr & _
"Enter command:" & vbCr & _
"[1 - next / 2 - previous /" & vbCr & _
"3 - set bookmark / 4 - go to bookmark]"
intCommand = Val(InputBox(strMessage))
Select Case intCommand
` Move forward or backward, trapping for BOF
` or EOF.
Case 1
rstPublishers.MoveNext
If rstPublishers.EOF Then
MsgBox "Moving past the last record." & _
vbCr & "Try again."
rstPublishers.MoveLast
End If
Case 2
rstPublishers.MovePrevious
If rstPublishers.BOF Then
MsgBox "Moving past the first record." &
_vbCr & "Try again."
rstPublishers.MoveFirst
End If
385
Chili!Soft ASP 3.6 Product Documentation
386
` Store the bookmark of the current record.
Case 3
varBookmark = rstPublishers.Bookmark
` Go to the record indicated by the stored
` bookmark.
Case 4
If IsEmpty(varBookmark) Then
MsgBox "No Bookmark set!"
Else
rstPublishers.Bookmark = varBookmark
End If
Case Else
Exit Do
End Select
Loop
rstPublishers.Close
End Sub
ADO Recordset Object Bookmark Property
Returns a bookmark that uniquely identifies the current record in a Recordset object or sets the
current record in a Recordset object to the record identified by a valid bookmark.
Bookmark Property Return Values
Sets or returns a Variant expression that evaluates to a valid bookmark.
Bookmark Property Remarks
Use the Bookmark property to save the position of the current record and return to that record at
any time. Bookmarks are available only in Recordset objects that support bookmark
functionality.
When you open a Recordset object, each of its records has a unique bookmark. To save the
bookmark for the current record, assign the value of the Bookmark property to a variable. To
quickly return to that record at any time after moving to a different record, set the Recordset
object's Bookmark property to the value of that variable.
The user may not be able to view the value of the bookmark. Also, users should not expect
bookmarks to be directly comparable—two bookmarks that refer to the same record may have
different values.
Chili!Soft ASP 3.6 Product Documentation
387
If you use the ADO Recordset Object Clone Method to create a copy of a Recordset object, the
Bookmark property settings for the original and the duplicate Recordset objects are identical
and you can use them interchangeably. However, you can't use bookmarks from different
Recordset objects interchangeably, even if they were created from the same source or command.
Bookmark Property Examples
See the ADO Recordset Object BOF, EOF Properties.
ADO Recordset Object CacheSize Property
The number of records from a Recordset object that are cached locally in memory. This property
is not currently supported on UNIX.
CacheSize Property Return Values
Sets or returns a Long value that must be greater than 0. Default is 1.
CacheSize Property Remarks
Use the CacheSize property to control how many records the provider keeps in its buffer and how
many to retrieve at one time into local memory. For example, if the CacheSize is 10, after first
opening the Recordset object, the provider retrieves the first 10 records into local memory. As
you move through the Recordset object, the provider returns the data from the local memory
buffer. As soon as you move past the last record in the cache, the provider retrieves the next 10
records from the data source into the cache.
The value of this property can be adjusted during the life of the Recordset object, but changing
this value only affects the number of records in the cache after subsequent retrievals from the data
source. Changing the property value alone will not change the current contents of the cache.
If there are fewer records to retrieve than CacheSize specifies, the provider returns the remaining
records; no error occurs.
A CacheSize setting of zero is not allowed and returns an error.
Records retrieved from the cache don't reflect concurrent changes that other users made to the
source data. To force an update of all the cached data, use the ADO Recordset Object Resync
Method.
CacheSize Property Example
This Visual Basic example uses the CacheSize property to show the difference in performance
for an operation performed with and without a 30-record cache.
Public Sub CacheSizeX()
Dim rstRoySched As ADODB.Recordset
Dim strCnn As String
Dim sngStart As Single
Dim sngEnd As Single
Chili!Soft ASP 3.6 Product Documentation
Dim sngNoCache As Single
Dim sngCache As Single
Dim intLoop As Integer
Dim strTemp As String
` Open the RoySched table.
strCnn = "driver={SQL Server};server=srv;" & _
"uid=sa;pwd=;database=pubs"
Set rstRoySched = New ADODB.Recordset
rstRoySched.Open "roysched", strCnn, , , adCmdTable
` Enumerate the Recordset object twice and record
` the elapsed time.
sngStart = Timer
For intLoop = 1 To 2
rstRoySched.MoveFirst
Do While Not rstRoySched.EOF
' Execute a simple operation for the performance test.
strTemp = rstRoySched!title_id
rstRoySched.MoveNext
Loop
Next intLoop
sngEnd = Timer
sngNoCache = sngEnd - sngStart
' Cache records in groups of 30 records.
rstRoySched.MoveFirst
rstRoySched.CacheSize = 30
sngStart = Timer
` Enumerate the Recordset object twice and record
' the elapsed time.
For intLoop = 1 To 2
rstRoySched.MoveFirst
Do While Not rstRoySched.EOF
` Execute a simple operation for the
388
Chili!Soft ASP 3.6 Product Documentation
389
` performance test.
strTemp = rstRoySched!title_id
rstRoySched.MoveNext
Loop
Next intLoop
sngEnd = Timer
sngCache = sngEnd - sngStart
' Display performance results.
MsgBox "Caching Performance Results:" & vbCr & _
" No cache: " & Format(sngNoCache, _
"##0.000") & " seconds" & vbCr & _
" 30-record cache: " & Format(sngCache, _
"##0.000") & " seconds"
rstRoySched.Close
End Sub
ADO Recordset Object CursorLocation Property
Sets or returns the location of the cursor engine. This property is read-only on UNIX.
CursorLocation Property Return Values
Sets or returns a Long value that can be set to one of the following constants:
Constant
Description
adUseClient
Uses client-side cursors supplied by a local cursor library. Local
cursor engines will often allow many features that driver-supplied
cursors may not, so using this setting may provide an advantage with
respect to features that will be enabled. For backward-compatibility,
the synonym adUseClientBatch is also supported.
adUseServer
Default. Uses data-provider or driver-supplied cursors. These cursors
are sometimes very flexible and allow for some additional sensitivity
to reflecting changes that others make to the actual data source.
However, some features of the Microsoft Client Cursor Provider
(such as disassociated recordsets) cannot be simulated.
CursorLocation Property Remarks
This property allows you to choose between various cursor libraries accessible to the provider.
Usually, you can choose between using a client-side cursor library or one that is located on the
server.
Chili!Soft ASP 3.6 Product Documentation
390
This property setting only affects connections established after the property has been set.
Changing the CursorLocation property has no effect on existing connections.
This property is read/write on a closed recordset, and read-only on an open recordset.
CursorLocation Property Example
See the AbsolutePosition property example.
ADO Recordset Object CursorType Property
The type of cursor used in a Recordset object.
CursorType Property Return Values
Sets or returns one of the following CursorTypeEnum values:
Constant
Description
adOpenForwardOnly Forward-only cursor. Default. Identical to a static cursor except
that you can only scroll forward through records. This improves
performance in situations when you only need to make a single
pass through a recordset.
adOpenKeyset
Keyset cursor. Like a dynamic cursor, except that you can't see
records that other users add, although records that other users
delete are inaccessible from your recordset. Data changes by other
users are still visible.
adOpenDynamic
Dynamic cursor. Additions, changes, and deletions by other users
are visible, and all types of movement through the recordset are
allowed, except for bookmarks if the provider doesn't support
them.
adOpenStatic
Static cursor. A static copy of a set of records that you can use to
find data or generate reports. Additions, changes, or deletions by
other users are not visible.
CursorType Property Remarks
Use the CursorType property to specify the type of cursor that should be used when opening the
Recordset object. The CursorType property is read/write when the recordset is closed and readonly when it is open.
If a provider does not support the requested cursor type, the provider may return another cursor
type. The CursorType property will change to match the actual cursor type in use when the
recordset object is open. To verify specific functionality of the returned cursor, use the ADO
Recordset Object Supports Method. After you close the recordset, the CursorType property
reverts to its original setting.
The following chart shows the provider functionality (identified by Supports method constants)
required for each cursor type.
Chili!Soft ASP 3.6 Product Documentation
CursorType
391
The Supports method must return True for these
constants
adOpenForwardOnly none
adOpenKeyset
adBookmark, adHoldRecords, adMovePrevious, adResync
adOpenDynamic
adMovePrevious
adOpenStatic
adBookmark, adHoldRecords, adMovePrevious, adResync
Note
Although Supports(adUpdateBatch) may be true for dynamic and forward-only cursors,
for batch updates you should use either a keyset or static cursor. Set the ADO Recordset
Object LockType Property to adLockBatchOptimistic, and set the CursorLocation
property to adUseClient (or its synonym, adUseClientBatch) to enable the Microsoft
Client Cursor Engine, which is required for batch updates.
CursorType Property Example
This Visual Basic example demonstrates setting the CursorType and LockType properties
before opening a recordset. It also shows the value of the ADO Recordset Object EditMode
Property under various conditions. The EditModeOutput function is required for this procedure
to run.
Public Sub EditModeX()
Dim cnn1 As ADODB.Connection
Dim rstEmployees As ADODB.Recordset
Dim strCnn As String
` Open recordset with data from Employee table.
Set cnn1 = New ADODB.Connection
strCnn = "driver={SQL Server};server=srv;" & _
"uid=sa;pwd=;database=pubs"
cnn1.Open strCnn
Set rstEmployees = New ADODB.Recordset
Set rstEmployees.ActiveConnection = cnn1
rstEmployees.CursorType = adOpenKeyset
rstEmployees.LockType = adLockBatchOptimistic
rstEmployees.Open "employee", , , , adCmdTable
` Show the EditMode property under different editing
` states.
rstEmployees.AddNew
Chili!Soft ASP 3.6 Product Documentation
rstEmployees!emp_id = "T-T55555M"
rstEmployees!fname = "temp_fname"
rstEmployees!lname = "temp_lname"
EditModeOutput "After AddNew:", rstEmployees.EditMode
rstEmployees.UpdateBatch
EditModeOutput "After UpdateBatch:", rstEmployees.EditMode
rstEmployees!fname = "test"
EditModeOutput "After Edit:", rstEmployees.EditMode
rstEmployees.Close
` Delete new record because this is a demonstration.
cnn1.Execute "DELETE FROM employee WHERE emp_id = 'T-T55555M'"
End Sub
Public Function EditModeOutput(strTemp As String, _
intEditMode As Integer)
` Print report based on the value of the EditMode
` property.
Debug.Print strTemp
Debug.Print " EditMode = ";
Select Case intEditMode
Case adEditNone
Debug.Print "adEditNone"
Case adEditInProgress
Debug.Print "adEditInProgress"
Case adEditAdd
Debug.Print "adEditAdd"
End Select
End Function
ADO Recordset Object EditMode Property
The editing status of the current record.
EditMode Property Return Values
Returns one of the following EditModeEnum values:
392
Chili!Soft ASP 3.6 Product Documentation
Constant
Description
adEditNone
No editing operation is in progress.
adEditInProgres
s
The data in the current record has been modified but not yet saved.
adEditAdd
The AddNew method has been invoked and the current record in
the copy buffer is a new record that hasn’t been saved in the
database.
393
EditMode Property Remarks
ADO maintains an editing buffer associated with the current record. This property indicates
whether changes have been made to this buffer, or whether a new record has been created. Use
the EditMode property to determine the editing status of the current record. You can test for
pending changes if an editing process has been interrupted and determine whether you need to
use the ADO Recordset Object Update Method or ADO Recordset Object CancelUpdate Method.
See the ADO Recordset Object AddNew Method for a more detailed description of the
EditMode property under different editing conditions.
EditMode Property Example
See the ADO Recordset Object CursorType Property example.
ADO Recordset Object Filter Property
A filter for data in a recordset.
Filter Property Return Values
Sets or returns a Variant value, which can contain one of the following:
Criteria string
A string made up of one or more individual clauses concatenated with AND or OR operators.
Array of bookmarks
An array of unique bookmark values that point to records in the Recordset object. This return
value is not currently supported on UNIX.
One of the following FilterGroupEnum values:
Constant
Description
adFilterNone
Removes the current filter and restores all records to view.
adFilterPendingRecor
ds
Enables you to view only records that have changed but have
not yet been sent to the server. Only applicable for batch
update mode. Not currently supported on UNIX.
adFilterAffectedRecor
ds
Enables you to view only records affected by the last Delete,
Resync, UpdateBatch, or CancelBatch call. Not currently
Chili!Soft ASP 3.6 Product Documentation
394
supported on UNIX.
adFilterFetchedRecord
s
Enables you to view records in the current cache, that is, the
results of the last call to retrieve records from the database.
Not currently supported on UNIX.
Filter Property Remarks
Use the Filter property to selectively screen out records in a Recordset object. The filtered
recordset becomes the current cursor. This affects other properties such as AbsolutePosition,
AbsolutePage, RecordCount, and ADO Recordset Object PageCount Property that return values
based on the current cursor, since setting the Filter property to a specific value will move the
current record to the first record that satisfies the new value.
On UNIX systems the Filter property is implemented for Recordset objects whose source is a
SELECT query. Setting the Filter property will resubmit the query with the criteria string AND’d
with the WHERE clause.
The criteria string is made up of clauses in the form FieldName-Operator-Value (for example,
"LastName = 'Smith'"). You can create compound clauses by concatenating individual
clauses with AND (for example, "LastName = 'Smith' AND FirstName =
'John'") or OR (for example, "LastName = 'Smith' OR LastName = 'Jones'").
Use the following guidelines for criteria strings:
FieldName
Must be a valid field name from the recordset. If the field name contains spaces, you must
enclose the name in square brackets.
Operator
Must be one of the following: <, >, <=, >=, <>, =, LIKE.
Value
The value with which you will compare the field values (for example, 'Smith',
#8/24/95#, 12.345 or $50.00). Use single quotes with strings and pound signs (#) with
dates. For numbers, you can use decimal points, dollar signs, and scientific notation. If Operator
is LIKE, Value can use wildcards. Only the asterisk (*) and percent sign (%) wildcards are
allowed, and they must be the last character in the string. Value may not be Null.
There is no precedence between AND and OR. Clauses can be grouped within parentheses.
However, you cannot group clauses joined by an OR and then join the group to another clause
with an AND, like this:
(LastName = 'Smith' OR LastName = 'Jones') AND FirstName = 'John'
Instead, you would construct this filter as:
(LastName = 'Smith' AND FirstName = 'John') OR
(LastName = 'Jones' AND FirstName = 'John')
Chili!Soft ASP 3.6 Product Documentation
395
In a LIKE clause, you can use a wildcard at the beginning and end of the pattern (for example,
LastName Like '*mit*'), or only at the end of the pattern (for example, LastName
Like 'Smit*').
The filter constants make it easier to resolve individual record conflicts during batch update mode
by allowing you to view, for example, only those records that were affected during the last ADO
Recordset Object UpdateBatch Method call.
Setting the Filter property itself may fail because of a conflict with the underlying data (for
example, a record has already been deleted by another user); in such a case, the provider returns
warnings to the ADO Errors Collection but does not halt program execution. A run-time error
occurs only if there are conflicts on all the requested records. Use the ADO Recordset Object
Status Property to locate records with conflicts.
Setting the Filter property to a zero-length string ("") has the same effect as using the
adFilterNone constant.
Whenever the Filter property is set, the current record position moves to the first record in the
filtered subset of records in the recordset. Similarly, when the Filter property is cleared, the
current record position moves to the first record in the recordset.
See the ADO Recordset Object Bookmark Property for an explanation of bookmark values from
which you can build an array to use with the Filter property.
Filter Property Example
This Visual Basic example uses the Filter property to open a new recordset based on a specified
condition applied to an existing recordset. It uses the RecordCount property to show the number
of records in the two recordsets. The FilterField function is required for this procedure to run.
Public Sub FilterX()
Dim rstPublishers As ADODB.Recordset
Dim rstPublishersCountry As ADODB.Recordset
Dim strCnn As String
Dim intPublisherCount As Integer
Dim strCountry As String
Dim strMessage As String
` Open recordset with data from Publishers table.
strCnn = "driver={SQL Server};server=srv;" & _
"uid=sa;pwd=;database=pubs"
Set rstPublishers = New ADODB.Recordset
rstPublishers.CursorType = adOpenStatic
rstPublishers.Open "publishers", strCnn, , , adCmdTable
` Populate the Recordset.
Chili!Soft ASP 3.6 Product Documentation
intPublisherCount = rstPublishers.RecordCount
` Get user input.
strCountry = Trim(InputBox( _
"Enter a country to filter on:"))
If strCountry <> "" Then
` Open a filtered Recordset object.
Set rstPublishersCountry = _
FilterField(rstPublishers, "Country", strCountry)
If rstPublishersCountry.RecordCount = 0 Then
MsgBox "No publishers from that country."
Else
` Print number of records for the original
` Recordset object and the filtered Recordset
` object.
strMessage = "Orders in original recordset: " & _
vbCr & intPublisherCount & vbCr & _
"Orders in filtered recordset (Country = '" & _
strCountry & "'): " & vbCr & _
rstPublishersCountry.RecordCount
MsgBox strMessage
End If
rstPublishersCountry.Close
End If
End Sub
Public Function FilterField(rstTemp As ADODB.Recordset, _
strField As String, strFilter As String) As ADODB.Recordset
` Set a filter on the specified Recordset object and then
` open a new Recordset object.
rstTemp.Filter = strField & " = '" & strFilter & "'"
Set FilterField = rstTemp
End Function
396
Chili!Soft ASP 3.6 Product Documentation
Note
When you know the data you want to select, it's usually more efficient to open a recordset
with an SQL statement. This example shows how you can create just one recordset and
obtain records from a particular country.
Public Sub FilterX2()
Dim rstPublishers As ADODB.Recordset
Dim strCnn As String
` Open recordset with data from Publishers table.
strCnn = "driver={SQL Server};server=srv;" & _
"uid=sa;pwd=;database=pubs"
Set rstPublishers = New ADODB.Recordset
rstPublishers.CursorType = adOpenStatic
rstPublishers.Open "SELECT * FROM publishers " & _
"WHERE Country = 'USA'", strCnn, , , adCmdText
` Print current data in recordset.
rstPublishers.MoveFirst
Do While Not rstPublishers.EOF
Debug.Print rstPublishers!pub_name & ", " & _
rstPublishers!country
rstPublishers.MoveNext
Loop
rstPublishers.Close
End Sub
ADO Recordset Object LockType Property
The type of locks placed on records during editing.
LockType Property Return Values
Sets or returns one of the following LockTypeEnum values:
Constant
Description
adLockReadOnly
Default. Read-only; the data cannot be modified.
adLockPessimistic
Pessimistic locking, record by record. The provider does what
is necessary to ensure successful editing of the records, usually
by locking records at the data source immediately upon
397
Chili!Soft ASP 3.6 Product Documentation
398
editing.
adLockOptimistic
Optimistic locking, record by record. The provider uses
optimistic locking, locking records only when you call the
Update method.
adLockBatchOptimist Optimistic batch updates. Required for batch update mode as
ic
opposed to immediate update mode.
LockType Property Remarks
Set the LockType property before opening a recordset to specify what type of locking the
provider should use when opening it. Read the property to return the type of locking in use on an
open Recordset object. The LockType property is read/write when the recordset is closed and
read-only when it is open.
Providers may not support all lock types. If a provider cannot support the requested LockType
setting, it will substitute another type of locking. To determine the actual locking functionality
available in a Recordset object, use the ADO Recordset Object Supports Method with adUpdate
and adUpdateBatch.
LockType Property Example
See the ADO Recordset Object CursorType Property example.
ADO Recordset Object MarshalOptions Property
Indicates which records are to be marshaled back to the server. This is a client-side only property.
MarshalOptions Property Return Values
Sets or returns a Long value that can be one of the following constants:
Constant
Description
adMarshalAll
Default. All rows are returned to the server.
adMarshalModifiedOnl
y
Only modified rows are returned to the server.
MarshalOptions Property Remarks
When using a client-side (ADOR) recordset, records that have been modified on the client are
written back to the middle-tier or Web server through a technique called marshaling, the process
of packaging and sending interface method parameters across thread or process boundaries.
Setting the MarshalOptions property can improve performance when modified remote data is
marshaled for updating back to the middle-tier or Web server.
Remote Data Service Usage: This property is only used on a client-side (ADOR) recordset.
MarshalOptions Property Example
Chili!Soft ASP 3.6 Product Documentation
399
This Visual Basic example uses the MarshalOptions property to specify what rows are sent back
to the server—All Rows or only Modified Rows.
Public Sub MarshalOptionsX()
Dim rstEmployees As ADODB.Recordset
Dim strCnn As String
Dim strOldFirst As String
Dim strOldLast As String
Dim strMessage As String
Dim strMarshalAll As String
Dim strMarshalModified As String
` Open recordset with names from Employee table.
strCnn = "driver={SQL Server};server=srv;" & _
"uid=sa;pwd=;database=pubs"
Set rstEmployees = New ADODB.Recordset
rstEmployees.CursorType = adOpenKeyset
rstEmployees.LockType = adLockOptimistic
rstEmployees.CursorLocation = adUseClient
rstEmployees.Open "SELECT fname, lname " & _
"FROM Employee ORDER BY lname", strCnn, , , adCmdText
` Store original data.
strOldFirst = rstEmployees!fname
strOldLast = rstEmployees!lname
` Change data in edit buffer.
rstEmployees!fname = "Linda"
rstEmployees!lname = "Kobara"
` Show contents of buffer and get user input.
strMessage = "Edit in progress:" & vbCr & _
" Original data = " & strOldFirst & " " & _
strOldLast & vbCr & " Data in buffer = " & _
rstEmployees!fname & " " & rstEmployees!lname & vbCr & vbCr & _
"Use Update to replace the original data with " & _
"the buffered data in the Recordset?"
strMarshalAll = "Would you like to send all the rows " & _
Chili!Soft ASP 3.6 Product Documentation
400
"in the recordset back to the server?"
strMarshalModified = "Would you like to send only " & _
"modified rows back to the server?"
If MsgBox(strMessage, vbYesNo) = vbYes Then
If MsgBox(strMarshalAll, vbYesNo) = vbYes Then
rstEmployees.MarshalOptions = adMarshalAll
rstEmployees.Update
ElseIf MsgBox(strMarshalModified, vbYesNo) = vbYes Then
rstEmployees.MarshalOptions = adMarshalModifiedOnly
rstEmployees.Update
End If
End If
` Show the resulting data.
MsgBox "Data in recordset = " & rstEmployees!fname & " " & _
rstEmployees!lname
` Restore original data because this is a demonstration.
If Not (strOldFirst = rstEmployees!fname And _
strOldLast = rstEmployees!lname) Then
rstEmployees!fname = strOldFirst
rstEmployees!lname = strOldLast
rstEmployees.Update
End If
rstEmployees.Close
End Sub
ADO Recordset Object MaxRecords Property
The maximum number of records to return to a recordset from a query.
MaxRecords Property Return Values
Sets or returns a Long value. Default is zero (no limit).
MaxRecords Property Remarks
Use the MaxRecords property to limit the number of records the provider returns from the data
source. The default setting of this property is zero, which means the provider returns all requested
Chili!Soft ASP 3.6 Product Documentation
401
records. The MaxRecords property is read/write when the recordset is closed and read-only when
it is open.
MaxRecords Property Example
This Visual Basic example uses the MaxRecords property to open a recordset containing the 10
most expensive titles in the Titles table.
Public Sub MaxRecordsX()
Dim rstTemp As ADODB.Recordset
Dim strCnn As String
` Open recordset containing the 10 most expensive
` titles in the Titles table.
strCnn = "driver={SQL Server};server=srv;" & _
"uid=sa;pwd=;database=pubs"
Set rstTemp = New ADODB.Recordset
rstTemp.MaxRecords = 10
rstTemp.Open "SELECT Title, Price FROM Titles " & _
"ORDER BY Price DESC", strCnn, , , adCmdText
` Display the contents of the recordset.
Debug.Print "Top Ten Titles by Price:"
Do While Not rstTemp.EOF
Debug.Print " " & rstTemp!Title & " - " & rstTemp!Price
rstTemp.MoveNext
Loop
rstTemp.Close
End Sub
ADO Recordset Object PageCount Property
The number of pages of data the Recordset object contains.
PageCount Property Return Values
Returns a Long value.
PageCount Property Remarks
Use the PageCount property to determine how many pages of data are in the Recordset object.
Pages are groups of records whose size equals the ADO Recordset Object PageSize Property
setting. Even if the last page is incomplete, because there are fewer records than the PageSize
Chili!Soft ASP 3.6 Product Documentation
402
value, it counts as an additional page in the PageCount value. If the Recordset object does not
support this property, the value will be -1 to indicate that the PageCount is indeterminable.
See the PageSize and AbsolutePage properties for more on page functionality.
PageCount Property Example
See the AbsolutePage example.
ADO Recordset Object PageSize Property
The number of records that constitute one page in the recordset.
PageSize Property Return Values (ADO Recordset Object)[0]
Sets or returns a Long value, the number of records on a page. Default is 10.
PageSize Property Remarks (ADO Recordset Object)
Use the PageSize property to determine how many records make up a logical page of data.
Establishing a page size allows you to use the AbsolutePage property to move to the first record
of a particular page. This is useful in Web-server scenarios when you want to allow the user to
page through data, viewing a certain number of records at a time.
This property can be set at any time, and its value will be used for calculating where the first
record of a particular page is.
PageSize Property Example (ADO Recordset Object)
See the AbsolutePage property example.
ADO Recordset Object State Property
Describes the current state of an object.
State Property Return Values (ADO Recordset Object)
Sets or returns a Long value that can be one of the following constants:
Constant
Description
AdStateClosed
Default. The object is closed.
AdStateOpen
The object is open.
State Property Remarks (ADO Recordset Object)
You can use the State property to determine the current state of a given object at any time.
ADO Recordset Object Status Property
Indicates the status of the current record with respect to batch updates or other bulk operations.
Status Property Return Values (ADO Recordset Object)
Chili!Soft ASP 3.6 Product Documentation
403
Returns a sum of one or more of the following RecordStatusEnum values:
Constant
Description
adRecOK
The record was successfully updated.
adRecNew
The record is new.
adRecModified
The record was modified.
adRecDeleted
The record was deleted.
adRecUnmodified
The record was not modified.
adRecInvalid
The record was not saved because its bookmark is invalid.
adRecMultipleChanges
The record was not saved because it would have affected
multiple records.
adRecPendingChanges
The record was not saved because it refers to a pending
insert.
adRecCanceled
The record was not saved because the operation was
canceled.
adRecCantRelease
The new record was not saved because of existing record
locks.
adRecConcurrencyViolati
on
The record was not saved because optimistic concurrency
was in use.
adRecIntegrityViolation
The record was not saved because the user violated integrity
constraints.
adRecMaxChangesExceed
ed
The record was not saved because there were too many
pending changes.
adRecObjectOpen
The record was not saved because of a conflict with an open
storage object.
adRecOutOfMemory
The record was not saved because the computer has run out
of memory.
adRecPermissionDenied
The record was not saved because the user has insufficient
permissions.
adRecSchemaViolation
The record was not saved because it violates the structure of
the underlying database.
adRecDBDeleted
The record has already been deleted from the data source.
Status Property Remarks (ADO Recordset Object)
Use the Status property to see what changes are pending for records modified during batch
updating. You can also use the Status property to view the status of records that fail during bulk
operations such as when you call the ADO Recordset Object Resync Method, ADO Recordset
Object UpdateBatch Method, or ADO Recordset Object CancelBatch Method methods on a
Chili!Soft ASP 3.6 Product Documentation
404
Recordset object, or set the ADO Recordset Object Filter Property on a Recordset object to an
array of bookmarks. With this property, you can determine how a given record failed and resolve
it accordingly.
Status Property Example (ADO Recordset Object)
This example uses the Status property to display which records have been modified in a batch
operation before a batch update has occurred.
Public Sub StatusX()
Dim rstTitles As ADODB.Recordset
Dim strCnn As String
` Open recordset for batch update.
strCnn = "driver={SQL Server};server=srv;" & _
"uid=sa;pwd=;database=pubs"
Set rstTitles = New ADODB.Recordset
rstTitles.CursorType = adOpenKeyset
rstTitles.LockType = adLockBatchOptimistic
rstTitles.Open "titles", strCnn, , , adCmdTable
` Change the type of psychology titles.
Do Until rstTitles.EOF
If Trim(rstTitles!Type) = "psychology" Then
rstTitles!Type = "self_help"
End If
rstTitles.MoveNext
Loop
` Display Title ID and status.
rstTitles.MoveFirst
Do Until rstTitles.EOF
If rstTitles.Status = adRecModified Then
Debug.Print rstTitles!title_id & " - Modified"
Else
Debug.Print rstTitles!title_id
End If
rstTitles.MoveNext
Loop
Chili!Soft ASP 3.6 Product Documentation
405
` Cancel the update because this is a demonstration.
rstTitles.CancelBatch
rstTitles.Close
End Sub
ADO Recordset Object Source Property
The source for the data in a Recordset object (Command object, SQL statement, table name, or
stored procedure).
Source Property Return Values (ADO Recordset Object)
Sets a String value or Command object reference; returns only a String value.
Source Property Remarks (ADO Recordset Object)
Use the Source property to specify a data source for a Recordset object using one of the
following: an ADO Command Object variable, an SQL statement, a stored procedure, or a table
name. The Source property is read/write for closed Recordset objects and read-only for open
Recordset objects.
If you set the Source property to a Command object, the ActiveConnection property of the
Recordset object will inherit the value of the ActiveConnection property for the specified
Command object. However, reading the Source property does not return a Command object;
instead, it returns the CommandText property of the Command object to which you set the
Source property.
If the Source property is an SQL statement, a stored procedure, or a table name, you can optimize
performance by passing the appropriate Options argument with the ADO Recordset Object Open
Method call.
Source Property Example (ADO Recordset Object)
This Visual Basic example demonstrates the Source property by opening three Recordset objects
based on different data sources.
Public Sub SourceX()
Dim cnn1 As ADODB.Connection
Dim rstTitles As ADODB.Recordset
Dim rstPublishers As ADODB.Recordset
Dim rstTitlesPublishers As ADODB.Recordset
Dim cmdSQL As ADODB.Command
Dim strCnn As String
Dim strSQL As String
` Open a connection.
Chili!Soft ASP 3.6 Product Documentation
Set cnn1 = New ADODB.Connection
strCnn = "driver={SQL Server};server=srv;" & _
"uid=sa;pwd=;database=pubs"
cnn1.Open strCnn
` Open a recordset based on a command object.
Set cmdSQL = New ADODB.Command
Set cmdSQL.ActiveConnection = cnn1
cmdSQL.CommandText = "Select title, type, pubdate " & _
"FROM titles ORDER BY title"
Set rstTitles = cmdSQL.Execute()
` Open a recordset based on a table.
Set rstPublishers = New ADODB.Recordset
rstPublishers.Open "publishers", strCnn, , , adCmdTable
` Open a recordset based on an SQL string.
Set rstTitlesPublishers = New ADODB.Recordset
strSQL = "SELECT title_ID AS TitleID, title AS Title, " & _
"publishers.pub_id AS PubID, pub_name AS PubName " & _
"FROM publishers INNER JOIN titles " & _
"ON publishers.pub_id = titles.pub_id " & _
"ORDER BY Title"
rstTitlesPublishers.Open strSQL, strCnn, , , adCmdText
` Use the Source property to display the source of each recordset.
MsgBox "rstTitles source: " & vbCr & _
rstTitles.Source & vbCr & vbCr & _
"rstPublishers source: " & vbCr & _
rstPublishers.Source & vbCr & vbCr & _
"rstTitlesPublishers source: " & vbCr & _
rstTitlesPublishers.Source
rstTitles.Close
rstPublishers.Close
rstTitlesPublishers.Close
cnn1.Close
406
Chili!Soft ASP 3.6 Product Documentation
407
End Sub
ADO Recordset Object RecordCount Property
The current number of records in a Recordset object.
RecordCount Property Return Values
Returns a Long value.
RecordCount Property Remarks
Use the RecordCount property to find out how many records are in a Recordset object. The
property returns -1 when ADO cannot determine the number of records. Reading the
RecordCount property on a closed recordset causes an error.
If the Recordset object supports approximate positioning or bookmarks—that is, ADO Recordset
Object Supports Method (adApproxPosition) or Supports (adBookmark), respectively, returns
True—this value will be the exact number of records in the recordset regardless of whether it has
been fully populated. If the Recordset object does not support approximate positioning, this
property may be a significant drain on resources because all records will have to be retrieved and
counted to return an accurate RecordCount value.
RecordCount Property Example
This Visual Basic example uses the Filter property to open a new recordset based on a specified
condition applied to an existing recordset. It uses the RecordCount property to show the number
of records in the two recordsets. The FilterField function is required for this procedure to run.
Public Sub FilterX()
Dim rstPublishers As ADODB.Recordset
Dim rstPublishersCountry As ADODB.Recordset
Dim strCnn As String
Dim intPublisherCount As Integer
Dim strCountry As String
Dim strMessage As String
` Open recordset with data from Publishers table.
strCnn = "driver={SQL Server};server=srv;" & _
"uid=sa;pwd=;database=pubs"
Set rstPublishers = New ADODB.Recordset
rstPublishers.CursorType = adOpenStatic
rstPublishers.Open "publishers", strCnn, , , adCmdTable
` Populate the Recordset.
Chili!Soft ASP 3.6 Product Documentation
intPublisherCount = rstPublishers.RecordCount
` Get user input.
strCountry = Trim(InputBox( _
"Enter a country to filter on:"))
If strCountry <> "" Then
` Open a filtered Recordset object.
Set rstPublishersCountry = _
FilterField(rstPublishers, "Country", strCountry)
If rstPublishersCountry.RecordCount = 0 Then
MsgBox "No publishers from that country."
Else
` Print number of records for the original
` Recordset object and the filtered Recordset
` object.
strMessage = "Orders in original recordset: " & _
vbCr & intPublisherCount & vbCr & _
"Orders in filtered recordset (Country = '" & _
strCountry & "'): " & vbCr & _
rstPublishersCountry.RecordCount
MsgBox strMessage
End If
rstPublishersCountry.Close
End If
End Sub
Public Function FilterField(rstTemp As ADODB.Recordset, _
strField As String, strFilter As String) As ADODB.Recordset
` Set a filter on the specified Recordset object and then
` open a new Recordset object.
rstTemp.Filter = strField & " = '" & strFilter & "'"
Set FilterField = rstTemp
End Function
408
Chili!Soft ASP 3.6 Product Documentation
409
Note
When you know the data you want to select, it's usually more efficient to open a recordset
with an SQL statement. This example shows how you can create just one recordset and
obtain records from a particular country.
Public Sub FilterX2()
Dim rstPublishers As ADODB.Recordset
Dim strCnn As String
` Open recordset with data from Publishers table.
strCnn = "driver={SQL Server};server=srv;" & _
"uid=sa;pwd=;database=pubs"
Set rstPublishers = New ADODB.Recordset
rstPublishers.CursorType = adOpenStatic
rstPublishers.Open "SELECT * FROM publishers " & _
"WHERE Country = 'USA'", strCnn, , , adCmdText
` Print current data in recordset.
rstPublishers.MoveFirst
Do While Not rstPublishers.EOF
Debug.Print rstPublishers!pub_name & ", " & _
rstPublishers!country
rstPublishers.MoveNext
Loop
rstPublishers.Close
End Sub
ADO Collections
Collections
ADO Errors Collection
Contains all stored Error objects, all of which pertain to a
single operation involving ADO.
ADO Fields Collection
Contains all stored Field objects of a Recordset object.
ADO Parameters Collection
Contains all the Parameter objects of a Command object.
Chili!Soft ASP 3.6 Product Documentation
ADO Properties Collection
410
Contains all the Property objects for the specific instance of
an object. This collection is not currently supported on UNIX.
Methods
ADO Collections Append
Method
Appends a new object to the Parameters collection.
ADO Collections Clear
Method
Clears the contents of an Errors collection.
ADO Collections Delete
Method
Deletes an object from the Parameters collection.
ADO Collections Item Method
Returns a specific member of a collection by name or ordinal
number.
ADO Collections Refresh
Method
Updates the objects in a collection to reflect objects available
from and specific to the provider.
Properties
ADO Collections Count
Property
The number of objects in a collection.
ADO Errors Collection
The Errors collection contains all stored ADO Error Object objects created in response to a
single failure involving the provider.
ADO Errors Collection Remarks
Any operation involving ADO objects can generate one or more provider errors. As each error
occurs, one or more ADO Error Object objects may be placed in the Errors collection of the
ADO Connection Object. When another ADO operation generates an error, the Errors collection
is cleared, and the new set of Error objects may be placed in the Errors collection.
Each Error object represents a specific provider error, not an ADO error. ADO errors are
exposed to the run-time exception-handling mechanism. For example, in Microsoft Visual Basic,
the occurrence of an ADO-specific error will trigger an On Error event and appear in the Err
object.
ADO operations that don't generate an error have no effect on the Errors collection. Use the
ADO Collections Clear Method to manually clear the Errors collection.
The set of Error objects in the Errors collection describes all errors that occurred in response to
a single statement. Enumerating the specific errors in the Errors collection enables your errorhandling routines to more precisely determine the cause and origin of an error, and take
appropriate steps to recover.
Some properties and methods return warnings that appear as Error objects in the Errors
collection but do not halt a program's execution. Before you call the ADO Recordset Object
Resync Method, ADO Recordset Object UpdateBatch Method, or ADO Recordset Object
CancelBatch Method methods on an ADO Recordset Object, or before you set the ADO
Chili!Soft ASP 3.6 Product Documentation
411
Recordset Object Filter Property on a Recordset object, call the Clear method on the Errors
collection so that you can read the Count Property of the Errors collection to test for returned
warnings.
Note
See the ADO Error Object for a more detailed explanation of the way a single ADO
operation can generate multiple errors.
ADO Fields Collection
The Fields collection contains all the Field objects of a Recordset object.
ADO Fields Collection Remarks
An ADO Recordset Object has a Fields collection made up of ADO Field Object objects. Each
Field object corresponds to a column in the recordset. You can populate the Fields collection
before opening the recordset by calling the ADO Collections Refresh Method on the collection.
Note
See the ADO Field Object for a more detailed explanation of how to use Field objects.
ADO Parameters Collection
The Parameters collection contains all the Parameter objects of a Command object.
ADO Parameters Collection Remarks
An ADO Command Object has a Parameters collection made up of ADO Parameter Object
objects. Using the ADO Collections Refresh Method on a Command object's Parameters
collection retrieves provider parameter information for the stored procedure or parameterized
query specified in the Command object. Some providers do not support stored procedure calls or
parameterized queries; calling the Refresh method on the Parameters collection when using
such a provider will return an error.
If you have not defined your own Parameter objects and you access the Parameters collection
before calling the Refresh method, ADO will automatically call the method and populate the
collection for you.
You can minimize calls to the provider to improve performance if you know the properties of the
parameters associated with the stored procedure or parameterized query you wish to call. Use the
CreateParameter method to create Parameter objects with the appropriate property settings and
use the ADO Collections Append Method to add them to the Parameters collection. This lets
you set and return parameter values without having to call the provider for the parameter
information. If you are writing to a provider that does not supply parameter information, you
must manually populate the Parameters collection using this method to be able to use parameters
at all. Use the ADO Collections Delete Method to remove Parameter objects from the
Parameters collection if necessary.
Chili!Soft ASP 3.6 Product Documentation
412
ADO Properties Collection
The Properties collection contains all the Property objects for a specific instance of an object.
The Property collection is not currently supported on UNIX.
ADO Properties Collection Remarks
Some ADO objects have a Properties collection made up of ADO Property Object objects. Each
Property object corresponds to a characteristic of the ADO object specific to the provider.
Note
See the ADO Property Object topic for a more detailed explanation of how to use
Property objects.
ADO Collections Methods
ADO Collections Append Method
Appends an object to a collection.
Append Method Applies To
ADO Parameters Collection
Append Method Syntax
collection.Append object
Append Method Parameters
object
An object variable representing the object to be appended.
Append Method Remarks
Use the Append method on a collection to add an object to that collection. This method is
available only on the Parameters collection of a ADO Command Object. You must set the ADO
Parameter Object Type Property of an ADO Parameter Object before appending it to the
Parameters collection. If you select a variable-length data type, you must also set the ADO
Parameter Object Size Property to a value greater than zero.
By describing the parameter yourself, you can minimize calls to the provider and consequently
improve performance when using stored procedures or parameterized queries. However, you
must know the properties of the parameters associated with the stored procedure or parameterized
query you wish to call. Use the CreateParameter method to create Parameter objects with the
appropriate property settings and use the Append method to add them to the Parameters
collection. This lets you set and return parameter values without having to call the provider for
the parameter information. If you are writing to a provider that does not supply parameter
information, you must manually populate the Parameters collection using this method to be able
to use parameters at all.
Chili!Soft ASP 3.6 Product Documentation
413
Append Method Examples
This Visual Basic example uses the Append and CreateParameter methods to execute a stored
procedure with an input parameter.
Public Sub AppendX()
Dim cnn1 As ADODB.Connection
Dim cmdByRoyalty As ADODB.Command
Dim prmByRoyalty As ADODB.Parameter
Dim rstByRoyalty As ADODB.Recordset
Dim rstAuthors As ADODB.Recordset
Dim intRoyalty As Integer
Dim strAuthorID As String
Dim strCnn As String
` Open connection.
Set cnn1 = New ADODB.Connection
strCnn = "driver={SQL Server};server=srv;" & _
"uid=sa;pwd=;database=pubs"
cnn1.Open strCnn
cnn1.CursorLocation = adUseClient
` Open command object with one parameter.
Set cmdByRoyalty = New ADODB.Command
cmdByRoyalty.CommandText = "byroyalty"
cmdByRoyalty.CommandType = adCmdStoredProc
` Get parameter value and append parameter.
intRoyalty = Trim(InputBox("Enter royalty:"))
Set prmByRoyalty = cmdByRoyalty.CreateParameter("percentage", _
adInteger, adParamInput)
cmdByRoyalty.Parameters.Append prmByRoyalty
prmByRoyalty.Value = intRoyalty
` Create recordset by executing the command.
Set cmdByRoyalty.ActiveConnection = cnn1
Set rstByRoyalty = cmdByRoyalty.Execute
` Open the Authors table to display author names.
Set rstAuthors = New ADODB.Recordset
Chili!Soft ASP 3.6 Product Documentation
414
rstAuthors.Open "authors", cnn1, , , adCmdTable
` Print current data in the recordset, adding
` author names from Authors table.
Debug.Print "Authors with " & intRoyalty & " percent royalty"
Do While Not rstByRoyalty.EOF
strAuthorID = rstByRoyalty!au_id
Debug.Print " " & rstByRoyalty!au_id & ", ";
rstAuthors.Filter = "au_id = '" & strAuthorID & "'"
Debug.Print rstAuthors!au_fname & " " & rstAuthors!au_lname
rstByRoyalty.MoveNext
Loop
rstByRoyalty.Close
rstAuthors.Close
cnn1.Close
End Sub
ADO Collections Clear Method
Removes all of the objects in a collection.
Clear Method Applies To
ADO Errors Collection
Clear Method Syntax
Errors.Clear
Clear Method Remarks
Use the Clear method on the Errors collection to remove all existing ADO Error Object objects
from the collection. When an error occurs, ADO automatically clears the Errors collection and
fills it with Error objects based on the new error. However, some properties and methods return
warnings that appear as Error objects in the Errors collection but do not halt a program's
execution. Before you call the ADO Recordset Object Resync Method, ADO Recordset Object
UpdateBatch Method, or ADO Recordset Object CancelBatch Method methods on an ADO
Recordset Object or before you set the ADO Recordset Object Filter Property on a Recordset
object, call the Clear method on the Errors collection. Doing so enables you to read the ADO
Collections Count Property of the Errors collection to test for returned warnings as a result of
these specific calls.
Clear Method Examples
Chili!Soft ASP 3.6 Product Documentation
415
See the ADO Command Object Execute Method.
ADO Collections Delete Method
Deletes an object from the Parameters collection.
Delete Method Applies To
ADO Parameters Collection
Delete Method Syntax
object.Parameters.Delete ( Index )
Delete Method Parameters
object
A Command object.
Index
A Variant that evaluates either to the name or to the ordinal number of an object in a collection.
Delete Method Remarks
Using the Delete method on a Parameters collection lets you remove one of the objects in the
collection. This method is available only on the Parameters collection of an ADO Command
Object. You must the use ADO Parameter Object object’s ADO Parameter Object Name Property
or its collection index when calling the Delete method; an object variable is not a valid argument.
ADO Collections Item Method
Returns a specific member of a collection by name or ordinal number.
Item Method Applies To
ADO Errors Collection, ADO Fields Collection, ADO Parameters Collection, ADO Properties
Collection
Item Method Syntax
Set object = collection.Item ( Index )
Item Method Parameters
object
Object reference created.
Index
A Variant that evaluates either to the name or to the ordinal number of an object in a collection.
Chili!Soft ASP 3.6 Product Documentation
416
Item Method Return Values
Returns an object reference.
Item Method Remarks
Use the Item method to return a specific object in a collection. If the method cannot find an
object in the collection corresponding to the Index argument, an error occurs. Also, some
collections don't support named objects; for these collections, you must use ordinal number
references.
The Item method is the default method for all collections; therefore, the following syntax forms
are interchangeable:
collection.Item (Index)
collection (Index)
ADO Collections Refresh Method
Updates the objects in a collection to reflect objects available from and specific to the provider.
Refresh Method Applies To
ADO Fields Collection, ADO Parameters Collection, ADO Properties Collection
Refresh Method Syntax
collection.Refresh
Refresh Method Parameters Collection
Using the Refresh method on a ADO Command Object object's Parameters collection retrieves
provider-side parameter information for the stored procedure or parameterized query specified in
the Command object. The collection will be empty for providers that do not support stored
procedure calls or parameterized queries.
You should set the ActiveConnection property of the Command object to a valid ADO
Connection Object, the ADO Command Object CommandText Property to a valid command, and
the ADO Command Object CommandType Property to adCmdStoredProc before calling the
ADO Collections Refresh Method.
If you access the Parameters collection before calling the Refresh method, ADO will
automatically call the method and populate the collection for you.
Note
If you use the Refresh method to obtain parameter information from the provider and it
returns one or more variable-length data type ADO Parameter Object objects, ADO may
allocate memory for the parameters based on their maximum potential size, which will
cause an error during execution. You should explicitly set the ADO Parameter Object
Size Property for these parameters before calling the ADO Command Object Execute
Method to prevent errors.
Chili!Soft ASP 3.6 Product Documentation
417
Refresh Method Fields Collection
Using the Refresh method on the Fields collection has no visible effect. To retrieve changes from
the underlying database structure, you must use either the ADO Recordset Object Requery
Method or, if the Recordset object does not support bookmarks, the ADO Recordset Object
MoveFirst, MoveLast, MoveNext, MovePrevious Methods method.
Refresh Method Properties Collection
Using the Refresh method on a Properties collection of some objects populates the collection
with the dynamic properties the provider exposes. These properties provide information about
functionality specific to the provider beyond the built-in properties ADO supports.
The Refresh method accomplishes different tasks depending on the collection from which you
call it.
Refresh Method Example
This Visual Basic example demonstrates using the Refresh method to refresh the Parameters
collection for a stored procedure Command object.
Public Sub RefreshX()
Dim cnn1 As ADODB.Connection
Dim cmdByRoyalty As ADODB.Command
Dim rstByRoyalty As ADODB.Recordset
Dim rstAuthors As ADODB.Recordset
Dim intRoyalty As Integer
Dim strAuthorID As String
Dim strCnn As String
' Open connection.
Set cnn1 = New ADODB.Connection
strCnn = "driver={SQL Server};server=srv;" & _
"uid=sa;pwd=;database=pubs"
cnn1.Open strCnn
' Open a command object for a stored procedure
' with one parameter.
Set cmdByRoyalty = New ADODB.Command
Set cmdByRoyalty.ActiveConnection = cnn1
cmdByRoyalty.CommandText = "byroyalty"
cmdByRoyalty.CommandType = adCmdStoredProc
cmdByRoyalty.Parameters.Refresh
Chili!Soft ASP 3.6 Product Documentation
418
' Get paramater value and execute the command,
' storing the results in a recordset.
intRoyalty = Trim(InputBox("Enter royalty:"))
cmdByRoyalty.Parameters(1) = intRoyalty
Set rstByRoyalty = cmdByRoyalty.Execute()
` Open the Authors table to get author names for display.
Set rstAuthors = New ADODB.Recordset
rstAuthors.Open "authors", cnn1, , , adCmdTable
' Print current data in the recordset, adding
' author names from Authors table.
Debug.Print "Authors with " & intRoyalty & " percent royalty"
Do While Not rstByRoyalty.EOF
strAuthorID = rstByRoyalty!au_id
Debug.Print " " & rstByRoyalty!au_id & ", ";
rstAuthors.Filter = "au_id = '" & strAuthorID & "'"
Debug.Print rstAuthors!au_fname & " " & _
rstAuthors!au_lname
rstByRoyalty.MoveNext
Loop
rstByRoyalty.Close
rstAuthors.Close
cnn1.Close
End Sub
ADO Collections Properties
ADO Collections Count Property
The number of objects in a collection.
Count Property Applies To
ADO Errors Collection, ADO Fields Collection, ADO Parameters Collection, ADO Properties
Collection
Count Property Return Values
Returns a Long value.
Chili!Soft ASP 3.6 Product Documentation
419
Count Property Remarks
Use the Count property to determine how many objects are in a given collection.
Because numbering for members of a collection begins with zero, you should always code loops
starting with the zero member and ending with the value of the Count property minus one. If you
are using Visual Basic and want to loop through the members of a collection without checking the
Count property, use the For Each...Next command.
If the Count property is zero, there are no objects in the collection.
Count Property Example
This Visual Basic example demonstrates the Count property with two collections in the
Employee database. The property obtains the number of objects in each collection, and sets the
upper limit for loops that enumerate these collections. Another way to enumerate these
collections without using the Count property would be to use For Each...Next statements.
Public Sub CountX()
Dim rstEmployees As ADODB.Recordset
Dim strCnn As String
Dim intloop As Integer
' Open recordset with data from Employee table.
strCnn = "driver={SQL Server};server=srv;" & _
"uid=sa;pwd=;database=pubs"
Set rstEmployees = New ADODB.Recordset
rstEmployees.Open "employee", strCnn, , , adCmdTable
' Print information about Fields collection.
Debug.Print rstEmployees.Fields.Count & _
" Fields in Employee"
For intloop = 0 To rstEmployees.Fields.Count - 1
Debug.Print " " & rstEmployees.Fields(intloop).Name
Next intloop
' Print information about Properties collection.
Debug.Print rstEmployees.Properties.Count & _
" Properties in Employee"
For intloop = 0 To rstEmployees.Properties.Count - 1 Debug.Print " "
& rstEmployees.Properties(intloop).Name
Next intloop
rstEmployees.Close
Chili!Soft ASP 3.6 Product Documentation
End Sub
420
Chili!Soft ASP 3.6 Product Documentation
421
ASP Built-in Objects Reference
Chili!Soft ASP provides five built-in or intrinsic objects for the Active Server Pages (ASP)
framework: Request, Response, Application, Server, and Session. Built-in objects are objects
that are included on all ASP pages; they do not need to be created before they can be used. This
section discusses the following ASP built-in objects:
ASP Built-in Object
Description
ASP Application Object Stores information (variables and objects) needed for all users of
a particular application. Information stored in the Application
object persists for the lifetime of the application.
ASP Request Object
Provides access to values passed to the server by the client.
ASP Response Object
Controls the output from an ASP script to the requesting client.
ASP Server Object
Provides access to methods and properties on the server. These
methods and properties typically serve as utility functions.
ASP Session Object
Stores information (variables and objects) needed for a particular
user session. Information stored in the Session object is not
discarded when the user jumps between pages in the application;
instead information persists for the entire user session.
Built-in objects simplify development by solving Web-protocol programming issues. For
example, built-in objects can provide mechanisms to process data sent using the Hypertext
Transfer Protocol (HTTP). HTTP is a stateless technology, and the server cannot track the
location of users in an application or the use of an application. By using the built-in Session
object, an application (or object) can handle session management tasks.
Note
ASP scripts provided in the examples are assumed to be enclosed in script delimiters.
The <%, %>, <SCRIPT>, and </SCRIPT> delimiters are generally not shown.
See also:
Using Chili!Soft ASP Built-in Objects in "Chapter 4: Building a Chili!Soft ASP Application"
ASP Application Object
The ASP Application object shares information among all users of a given application. An ASPbased application is defined as all the .asp files in a virtual directory and associated subdirectories. Because the Application object can be shared by more than one user, Lock and
Unlock methods are provided to ensure that multiple users do not try to alter a property
simultaneously.
Syntax: ASP Application Object
Application.method
Chili!Soft ASP 3.6 Product Documentation
422
ASP Application Object Methods
ASP Application Object Lock Method Prevents script from modifying object properties.
ASP Application Object Unlock MethodEnables script to modify object properties after
execution of the Lock method.
ASP Application Object Events
Application_OnStart
Runs when an ASP page belonging to the application is accessed for
the first time.
Application_OnEnd
Runs when the Web server is shut down.
Values can be stored in the Application object. These values are available throughout the
application and have application scope.
Objects can be created within the Application_OnStart script and assigned to the Application
object. You cannot, however, store a built-in object in the Application object. Each of the
following lines will return an error:
Set Application("var1") = Session
Set Application("var2") = Request
Set Application("var3") = Response
Set Application("var4") = Server
Set Application("var5") = Application
Before you store an object in the Application object, you must know what threading model it
uses. Only objects marked as both free and apartment-threaded can be stored in the Application
object.
The Application object is implemented as a collection. If you store an array in an Application
object, you should not attempt to alter elements of the stored array directly. For example, the
following script does not work:
Application("StoredArray") (3) = "new value"
Instead of storing the value "new value" in StoredArray(3) the value is stored in the
Application collection, overwriting any information stored at Application(3).
Note
It is strongly recommended that if you store an array in the Application object that you
retrieve a copy of the array before retrieving or changing any of the elements of the array.
When you are done making changes to the array, store the array back into the
Application object to save changes. This is demonstrated in the following examples.
ASP Application Object Examples
You can store different types of variables:
Application("greeting") = "Welcome to My Web World"
Chili!Soft ASP 3.6 Product Documentation
423
Application("num") = 25
You must use the Set keyword when storing objects:
Set Application("Obj1") = Server.CreateObject("MyComponent")
You can use methods and properties on subsequent ASP pages by using the following:
Application("Obj1").MyObjMethod
As an alternative, you can extract a local copy of the object:
Set MyLocalObj1 = Application("Obj1")
MyLocalObj.MyObjMethod
The next example demonstrates using an application variable called NumVisits to store the
number of times a particular page has been accessed. The Lock method is called to ensure only
the current client can access or alter NumVisits. Calling the Unlock method then enables other
clients to access the application object.
Application.Lock
Application("NumVisits") = Application("NumVisits") + 1
Application.Unlock
This application page has been visited <%= Application("NumVisits")
%> times!
The next three examples demonstrate storing and manipulating an array in the Application
object. The Lock and Unlock methods are used to control access to the Application object.
Application.Lock
Application("StoredArray") = MyArray
Application.Unlock
To retrieve the array from the Application object and modify its elements:
LocalArray = Application("StoredArray")
LocalArray(0) = "Hello"
LocalArray(1) = "there"
Next you need to restore the array in the Application object. This overwrites the values in
StoredArray with new values.
Application.Lock
Application("StoredArray") = LocalArray
Application.Unlock
ASP Application Object Methods
ASP Application Object Lock Method
424
Chili!Soft ASP 3.6 Product Documentation
The Lock method blocks other clients from modifying variables stored in the Application object,
ensuring that only one client at a time can alter or access the application variables. If you do not
call the Unlock method explicitly, the server unlocks the locked Application object when the
script ends or times out.
Syntax: ASP Application Object Lock Method
Application.Lock
ASP Application Object Unlock Method
The Unlock method enables other clients (via an ASP page) to modify the variables stored in the
Application object after it has been locked using the Lock method. If you do not call the Unlock
method explicitly, the server unlocks the locked Application object when the script ends or times
out.
Syntax: ASP Application Object Unlock Method
Application.Unlock
ASP Request Object
The Request object retrieves the values that the browser passed to the server during an HTTP
request.
Syntax: ASP Request Object
Request.[collection | property | method] (variable)
ASP Request Object Collections
ASP Request Object Cookies Collection
The value of cookies sent in the HTTP request.
ASP Request Object Form Collection
The values of form elements sent in the HTTP
request body.
ASP Request Object QueryString Collection
The value of variables in the HTTP query string.
ASP Request Object ServerVariables Collection The value of predetermined environment variables.
Note
Due to widely differing Web-server support for client-side certificates, Chili!Soft ASP
does not implement the ClientCertificate collection.
ASP Request Object Properties
ASP Request Object TotalBytes
Property
The total number of bytes the client is sending in the body of
the request.
Chili!Soft ASP 3.6 Product Documentation
425
ASP Request Object Methods
ASP Request Object BinaryRead
Method
Retrieves data sent to the server from the client as part of a
POST request.
Variable parameters are strings that identify the item to be retrieved from a collection or a value
to be passed to a property or method. For more information about the variable parameter, see the
individual collection descriptions. If the specified variable is not in one of the collections, the
Request object returns EMPTY.
All variables can be accessed directly by calling Request("variable") without a collection
name. In this case, the Web server searches the collections in the following order:
•
QueryString
•
Form
•
Cookies
•
ServerVariables
If the same variable exists in more than one collection, the first one encountered will be used. It is
strongly recommended that you use the collection name. For example, instead of
Request.(AUTH_USER) use Request.ServerVariables(AUTH_USER).
ASP Request Object Collections
ASP Request Object Cookies Collection
The Cookies collection allows you to retrieve the values of the cookies sent in an HTTP request.
Syntax: ASP Request Object Cookies Collection
Request.Cookies(cookie)[(key)|.attribute]
Parameters: ASP Request Object Cookies Collection
cookie
Specifies the cookie whose value should be received.
key
An optional parameter used to retrieve subkey values from cookie dictionaries.
attribute
Specifies information about the cookie itself. The attribute value can be:
Name
Value
HasKeys
Read-only. Specifies whether the cookie contains keys.
Remarks: ASP Request Object Cookies Collection
Access the subkeys of a cookie dictionary by including a value for key. If a cookie dictionary is
accessed without specifying a key, all of the keys are returned as a single query string. For
Chili!Soft ASP 3.6 Product Documentation
426
example, if MyCookie has two keys, First and Second, and you do not specify either of these
keys in a call to Request.Cookies, the following string is returned.
First=firstkeyvalue&Second=secondkeyvalue
If two cookies with the same name are sent by the client browser, Request.Cookies returns the
one with the deeper path structure. For example, if two cookies had the same name but one had a
path attribute of /www/ and the other of /www/home/, the client browser would send both cookies
to the /www/home/ directory, but Request.Cookies would only return the second cookie.
To determine whether a cookie is a cookie dictionary (whether the cookie has keys), use the
following script.
<%= Request.Cookies("myCookie").HasKeys %>
If myCookie is a cookie dictionary, the preceding value evaluates to TRUE; otherwise, it
evaluates to FALSE.
You can use an iterator to cycle through all the cookies in the Cookie collection, or all the keys in
a cookie. However, iterating through keys on a cookie that does not have keys will not produce
any output. You can avoid this situation by first checking to see whether a cookie has keys by
using the HasKeys attribute.
Examples: ASP Request Object Cookies Collection
The first example shows how to print the entire cookie collection:
<%
'Print out the entire cookie collection.
For Each cookie in Request.Cookies
If Not cookie.HasKeys Then
'Print out the cookie string
%>
<%= cookie %> = <%= Request.Cookies(cookie) %>
<%
Else
'Print out the cookie collection
For Each key in Request.Cookies(cookie) %>
<%= cookie %> (<%= key %>) = <%= Request.Cookies(cookie)(key)
%>
<%
Next
End If
Next
Chili!Soft ASP 3.6 Product Documentation
427
%>
The next example prints the value of a cookie variable called "myCookie":
<%= Request.Cookies("myCookie") %>
ASP Request Object Form Collection
The Form collection retrieves the values of form elements posted to the HTTP request body by a
form using the POST method.
Syntax: ASP Request Object Form Collection
Request.Form(parameter)[(index)|.Count]
Parameters: ASP Request Object Form Collection
parameter
Specifies the name of the form element from which the collection is to retrieve values.
index
An optional parameter that enables you to access one of multiple values for a parameter. It can be
any integer in the range 1 to Count.
Remarks: ASP Request Object Form Collection
The Form collection is indexed by the names of the parameters in the request body. The value of
Request.Form(parameter) is an array of all of the values of parameter that occur in the request
body. You can determine the number of values of a parameter by calling
Request.Form(parameter).Count. If a parameter does not have multiple values associated with
it, the count is 1. If the parameter is not bound, the count is 0.
To reference a single value of a form element that has multiple values, you must specify a value
for the index. The index parameter may be any number between 1 and
Request.Form(parameter).Count. If you reference one of multiple form parameters without
specifying a value for index, the data is returned as a comma-delimited string.
When you use parameters with Request.Form, the Web server parses the HTTP request body
and returns the specified data. If your application requires unparsed data from the form, you can
access it by calling Request.Form without any parameters.
Examples: ASP Request Object Form Collection
In this example an iterator is used to loop through all the data values in a form request. Assume
that a user fills out a form by specifying two values (Chocolate and Butterscotch) for the
FavoriteFlavor parameter. The following script will retrieve these values:
For Each item In Request.Form("FavoriteFlavor")
Response.Write item & "<BR>"
Next
Chili!Soft ASP 3.6 Product Documentation
428
This displays the following:
Chocolate
Butterscotch
The same output can be generated with a For…Next loop, as shown in the following script:
For I = 1 To Request.Form("FavoriteFlavor").Count
Response.Write Request.Form("FavoriteFlavor")(I) & "<BR>"
Next
This iterator can display the parameter name, as shown in the following script.
<% For Each x In Request.Form %>
Request.Form( <%= x %> ) = <%= Request.Form(x) %> <BR>
<% Next %>
This displays the following:
FavoriteFlavor = Chocolate
FavoriteFlavor = Butterscotch
The next example uses the following form to solicit information from a user:
<FORM ACTION = "/scripts/submit.asp" METHOD = "post">
<P>Your first name: <INPUT NAME = "firstname" SIZE = 48>
<P>What is your favorite ice cream flavor: <SELECT NAME = "flavor">
<OPTION>Vanilla
<OPTION>Strawberry
<OPTION>Chocolate
<OPTION>Rocky Road</SELECT>
<p><INPUT TYPE = SUBMIT>
</FORM>
From that form, the following request body might be sent to the client:
firstname=James&flavor=Rocky+Road
The following script can then be used:
Welcome, <%= Request.Form("firstname") %>.
Your favorite flavor is <%= Request.Form("flavor") %>.
The unparsed form data is: <%= Request.Form %>
This displays the following:
"Welcome, James. Your favorite flavor is Rocky Road."
Chili!Soft ASP 3.6 Product Documentation
429
The unparsed form data is: firstname=James&flavor=Rocky+Road
ASP Request Object QueryString Collection
The QueryString collection retrieves the values of the variables in the HTTP query string; that is,
it retrieves the values encoded after the question mark (?) in an HTTP request. For example, it
parses the values sent by a form using the GET method.
Syntax: ASP Request Object QueryString Collection
Request.QueryString(variable)[(index)|.Count]
Parameters: ASP Request Object QueryString Collection
variable
Specifies the name of the variable in the HTTP query string to retrieve.
ASP Request Object QueryString Collection Index
An optional parameter that enables you to retrieve one of multiple values for variable. It can be
any integer value in the range 1 to Request.QueryString(variable).Count.
Remarks: ASP Request Object QueryString Collection
The QueryString collection is a parsed version of the QUERY_STRING variable in the
ServerVariables collection. It enables you to retrieve the QUERY_STRING variables by name.
The value of Request.QueryString(parameter) is an array of all of the values of parameter that
occur in QUERY_STRING. You can determine the number of values of a parameter by calling
Request.QueryString(parameter).Count. If a variable does not have multiple data sets
associated with it, the count is 1. If the variable is not found, the count is 0.
To reference a QueryString variable in one of multiple data sets, you specify a value for index.
The index parameter may be any value between 1 and Request.QueryString(variable).Count. If
you reference one of multiple QueryString variables without specifying a value for index, the
data is returned as a comma-delimited string.
When you use parameters with Request.QueryString, the server parses the parameters sent to
the request and returns the specified data. If your application requires unparsed QueryString
data, you can retrieve it by calling Request.QueryString without any parameters.
Examples: ASP Request Object QueryString Collection
You can use an iterator to loop through all the data values in a query string. For example, if the
following request is sent:
http://NAMES.ASP?Q=Fred&Q=Sally
and NAMES.ASP contained the following script:
For Each item In Request.QueryString("Q")
Response.Write item & "<BR>"
Chili!Soft ASP 3.6 Product Documentation
430
Next
NAMES.ASP would display the following:
Fred
Sally
Instead of using For Each, you can loop through data values in a query string using the Count
variable:
For I = 1 To Request.QueryString("Q").Count
Response.Write Request.QueryString("Q")(I) & "<BR>"
Next
The following client request:
/scripts/directory-lookup.asp?name=fred&age=22
results in the QUERY_STRING value:
name=fred&age=22.
The QueryString collection would then contain two members, name and age.
Welcome, <%= Request.QueryString("name") %>.
Your age is <%= Request.QueryString("age") %>.
This script displays:
"Welcome, Fred. Your age is 22."
ASP Request Object ServerVariables Collection
The ServerVariables collection retrieves the values of environment variables.
Syntax: Request Object ServerVariables Collection
Request.ServerVariables(variable)
Parameters: Request Object ServerVariables Collection
variable
This specifies the name of the server environment variable to retrieve. It can be one of the values
from the following table:
Value
Description
ALL_RAW
All headers in raw form as sent by the client.
APPL_MD_PATH*
Retrieves the metabase path for the application.
APPL_PHYSICAL_PATH
Retrieves the physical path corresponding to the metabase path.
ASP_VERSION
Version number of the Chili!Soft ASP server.
ASP_VERSION_MAJOR
The major version number of the Chili!Soft ASP server.
Chili!Soft ASP 3.6 Product Documentation
431
ASP_VERSION_MINOR
The minor version number of the Chili!Soft ASP server.
ASP_OS
The operating system the server is running on.
ASP_LICENSE
License information for the Chili!Soft ASP server.
AUTH_PASSWORD
The password corresponding to REMOTE_USER as supplied by
the client.
AUTH_TYPE
If the server supports user authentication and the script is
protected, this is the protocol-specific authentication method used
to validate the user.
AUTH_USER
Raw authenticated user name.
CERT_COOKIE*
Unique ID for the client certificate, returned as a string.
CERT_FLAGS*
bit0 is set to 1 if the client certificate is present. bit1 is set to 1 if the
Certifying Authority of the client certificate is invalid (not in the list of
recognized CA on the server).
CERT_ISSUER*
Issuer field of the client certificate.
CERT_KEYSIZE*
Number of bits in the Secure Sockets Layer connection key size, for
example, 128.
CERT_SECRETKEYSIZE*
Number of bits in the server certificate private key, for example
1024.
CERT_SERIALNUMBER*
Serial number field of the client certificate.
CERT_SERVER_ISSUER*
Issuer field of the server certificate.
CERT_SERVER_SUBJECT* Subject field of the server certificate.
CERT_SUBJECT*
Subject field of the client certificate.
CONTENT_LENGTH
The length of content as given by the client.
CONTENT_TYPE
The data type of the content in queries that have attached
information, such as HTTP GET, POST, and PUT.
GATEWAY_INTERFACE
The revision of the CGI specification used by the server. Format:
CGI/revision.
HTTP_<HeaderName>
The value stored in the header HeaderName. Any header other
than those listed in this table must be prefixed by "HTTP_" in order
for the ServerVariables collection to retrieve its value. The server
interprets any underscore (_) characters in HeaderName as dashes
in the actual header. For example, if you specify
HTTP_MY_HEADER, the server searches for MY-HEADER.
HTTPS
Returns "on" if the request came in through a secure channel or
"off" if the request is for a non-secure channel.
HTTPS_KEYSIZE
Number of bits in Secure Sockets Layer key size, for example, 128.
HTTPS_SECRET_KEYSIZE Number of bits in the server certificate private key, for example,
1024.
HTTPS_SERVER_ISSUER
Issuer field of the server certificate.
HTTPS_SERVER_SUBJECT Subject field of the server certificate.
INSTANCE_ID
The ID for the instance in textual format. If the instance ID is 1, it
appears as a string. Under IIS you can use this variable to retrieve
Chili!Soft ASP 3.6 Product Documentation
432
the ID of the Web-server instance (in the metabase) to which the
request belongs.
INSTANCE_META_PATH*
The metabase path for the instance of IIS that responds to the
request.
LOCAL_ADDR
Returns the Server Address on which the request came in. This is
important on multi-homed machines where there can be multiple IP
addresses bound to a machine and you want to find out which
address the request used.
LOGON_USER
The Windows NT account the client user is logged into.
Note
Not supported by Chili!Soft ASP for UNIX.
PATH_INFO
The extra path information, as given by the client. Scripts can be
accessed by using their virtual path and the PATH_INFO server
variable. If this information comes from a URL, it is decoded by the
server before it is passed to the script.
PATH_TRANSLATED
A translated version of PATH_INFO that takes the path and
performs any virtual to physical mapping.
QUERY_STRING
Query information in the string following the question mark (?) in the
HTTP request.
REMOTE_ADDR
The IP address of the remote host making the request.
REMOTE_HOST
The name of the host making the request. If the server does not
have this information, it will set REMOTE_ADDR and leave this
empty.
REMOTE_USER
If the server supports user authentication and the script is
protected, this is the username by which the user is authenticated.
REQUEST_METHOD
The method used to make the request. For HTTP, this would be
GET, HEAD, POST, etc.
SCRIPT_NAME
A virtual path to the script being executed. This is used for selfreferencing URLs.
SERVER_NAME
The server’s host name, DNS alias, or IP address as it would
appear in self-referencing URLs.
SERVER_PORT
The port number to which the request was sent.
SERVER_PORT_SECURE
A string that contains either 0 or 1. If the request is being handled
on the secure port, then this will be 1; otherwise it will be 0.
SERVER_PROTOCOL
The name and revision of the information protocol. Format:
protocol/revision.
SERVER_SOFTWARE
The name and version of the server software answering the request
and running the gateway. Format: name/version.
URL
Gives the base portion of the URL.
*These server variables are only valid when running Chili!Soft ASP with Microsoft Internet
Information Server. When using other Web servers they will always be empty.
Chili!Soft ASP 3.6 Product Documentation
433
Remarks: Request Object ServerVariables Collection
If a client sends a header other than those specified in the preceding table, you can retrieve the
value of the header by prefixing the header name with "HTTP_" in the call to
Request.ServerVariables. For example, if the client sent the following header:
SomeNewHeader:SomeNewValue
you could retrieve SomeNewValue by using the following:
<% Request.ServerVariables("HTTP_SomeNewHeader") %>
Examples: Request Object ServerVariables Collection
You can use an iterator to loop through each server variable name. For example, the following
script prints all of the server variables in a table:
<TABLE>
<TR><TH>Server Variable</TH><TH>Value</TH></TR>
<% for each name in Request.ServerVariables %>
<TR>
<TD><%= name %></TD>
<TD><%= Request.ServerVariables(name) %></TD>
</TR>
<% Next %>
</TABLE>
The following example demonstrates using Request.ServerVariables to insert the name of a
server into a hyperlink:
<A HREF="http://<%= Request.ServerVariables("SERVER_NAME")%>
/scripts/MyPage.asp">Link to MyPage.asp</A>
ASP Request Object Methods
ASP Request Object BinaryRead Method
The BinaryRead method reads information sent from the client to the server as part of a POST
request. The data is returned as a SafeArray that contains information about the dimensions of
the array.
Syntax: ASP Request Object BinaryRead Method
variant = Request.BinaryRead(count)
Parameters: ASP Request Object BinaryRead Method
variant
Chili!Soft ASP 3.6 Product Documentation
434
An array of unsigned bytes returned by this method.
count
Before the read, the number of bytes to read from the client. After execution, the actual number of
bytes successfully read from the client. The number of bytes that will be read is less than or equal
to Request.TotalBytes.
Remarks: ASP Request Object BinaryRead Method
The BinaryRead method is used to read the raw data sent by a POST request. This provides lowlevel access as opposed to the formatted data provided by the Request.Form collection. Once
you have used the BinaryRead method, any call to a variable in the Request.Form collection
will cause an error. Conversely, calling BinaryRead after accessing the Request.Form collection
will also cause an error. Remember, if you access a variable in the Request object without
specifying a collection, the Request.Form collection may be accessed, bringing this rule into
force.
Examples: ASP Request Object BinaryRead Method
The following example uses the BinaryRead method to place the contents of a Request object
into a safe array.
<%
dim bytecount
dim binread
bytecount = Request.TotalBytes
binread = Request.BinaryRead(bytecount)
%>
ASP Request Object Properties
ASP Request Object TotalBytes Property
The TotalBytes property contains the total number of bytes sent by the client in the body of the
request. The property is read-only.
Syntax: ASP Request Object TotalBytes Property
Counter = Request.TotalBytes
Parameters: ASP Request Object TotalBytes Property
counter
A variable to hold the total number of bytes the client sent in the request.
Examples: ASP Request Object TotalBytes Property
435
Chili!Soft ASP 3.6 Product Documentation
The following example sets a variable equal to the total number of bytes included in a request
object:
<%
dim bytecount
bytecount = Request.TotalBytes
%>
ASP Response Object
The Response object controls sending output to the browser.
Syntax: ASP Response Object
Response.collection | property | method
ASP Response Object Collections
ASP Response Object Cookies Collection
You can use this collection to set cookie
values to send to the client browser.
ASP Response Object Properties
ASP Response Object Buffer Property
Indicates whether to buffer page output.
ASP Response Object CacheControl Property
Determines if proxy servers are allowed to
cache the output generated by ASP.
ASP Response Object Charset Property
Appends the name of the character set to the
content-type header.
ASP Response Object ContentType Property
Specifies the HTTP content type for the
response.
ASP Response Object Expires Property
Specifies the length of time until the page
cached on a browser expires.
ASP Response Object ExpiresAbsolute Property
Specifies the date and time a page cached on
a browser expires.
ASP Response Object IsClientConnected Property
Indicates if the client is still connected to the
server.
ASP Response Object PICS Property
Adds the value of a PICS label to the picslabel field of the response header.
ASP Response Object Status Property
The value of the status line returned by the
server.
ASP Response Object Methods
ASP Response Object AddHeader Method
Set the HTML header name to value.
ASP Response Object AppendToLog Method
Adds a string to the end of the Web server log
entry for this request.
436
Chili!Soft ASP 3.6 Product Documentation
ASP Response Object BinaryWrite Method
Writes the given information to the current
HTTP output without any character set
conversion.
ASP Response Object Clear Method
Erases any buffered HTML output.
ASP Response Object End Method
Stops processing the .asp file and returns the
current results.
ASP Response Object Flush Method
Sends any buffered HTML output immediately.
ASP Response Object Redirect Method
Sends a redirect message to the browser,
causing it to attempt to connect to a different
URL.
ASP Response Object Write Method
Writes a variable to the current HTML output
as a string.
ASP Response Object Collections
ASP Response Object Cookies Collection
The Cookies collection sets the value of a cookie. If a specified cookie does not exist, it is
created. If it does exist, the cookie takes on the new value and the old value is discarded.
Syntax: ASP Response Object Cookies Collection
Response.Cookies(cookie) [(key) | .attribute] = value
Parameters: ASP Response Object Cookies Collection
cookie
The name of the cookie.
key
Optional. If key is specified, the cookie is a dictionary and key is set to value.
attribute
Specific information about the cookie itself. The attribute can be one of the following:
Attribute
Description
Expires
The date on which the cookie expires. This attribute must be set to a date
later than the current date in order to store the cookie on the client disk
after the current session ends. Write-only.
HasKeys
Indicates that the cookie has keys. Read-only.
Path
If set, the cookie is only sent to requests on this path. If the attribute is
not set, the application path is used. Write-only.
Secure
Indicates that the cookie is secure. Write-only.
value
Specifies the value to assign to key or attribute.
Chili!Soft ASP 3.6 Product Documentation
437
Remarks: ASP Response Object Cookies Collection
If a cookie with keys is created, as in the following script:
Response.Cookies("myCookie")("type1") = "sugar"
Response.Cookies("myCookie")("type2") = "ginger snap"
the following header is sent:
SET-COOKIE:MYCOOKIE=TYPE1=sugar&TYPE2=ginger+snap
Any subsequent assignment to myCookie that does not include a key would destroy type1 and
type2. The following example discards the values type1 and type2 and replaces them with
the value "chocolate chip":
Response.Cookies("myCookie") = "chocolate chip"
Conversely, calling a cookie with a key destroys any non-key values the cookie might contain.
The following code will discard the value "chocolate chip" and insert the key value instead:
Response.Cookies("myCookie") ("NewType") = "peanut butter"
To check to see if a cookie has key values, use the following:
Response.Cookies("myCookie").HasKeys
If myCookie is a dictionary and has keys, the previous script will evaluate to TRUE, otherwise
it will be FALSE.
You can use an iterator to set cookie attributes. The following example sets all the cookies in a
collection to expire on Dec. 31, 1999:
<%
For each cookie in Response.Cookies
Response.Cookies(cookie).ExpiresAbsolute = #Dec. 31, 1999#
Next
%>
An iterator can also be used to set the values of all the cookies in a collection, or all the keys in a
cookie. However, when using an iterator to retrieve cookie values, the cookies must have keys or
the iterator will not execute. Use the HasKeys property to check to see whether a cookie has any
keys. This is demonstrated in the following example.
<%
If Not cookie.HasKeys Then
'Set the value of the cookie
Response.Cookies(cookie) = ""
Else
'Set the value for each key in the cookie collection
For Each key in Response.Cookies(cookie)
Chili!Soft ASP 3.6 Product Documentation
438
Response.Cookies(cookie)(key) = ""
Next key
%>
Examples: ASP Response Object Cookies Collection
The following example shows how you can set cookie values and their attributes:
<%
Response.Cookies("Type") = "Chocolate Chip"
Response.Cookies("Type").Expires = "July 31, 1997"
Response.Cookies("Type").Domain = "msn.com"
Response.Cookies("Type").Path = "/www/home/"
Response.Cookies("Type").Secure = FALSE
%>
ASP Response Object Methods
ASP Response Object AddHeader Method
The AddHeader method adds an HTML header with a specified value. This method always adds
a new HTTP header to the response. It will not replace an existing header of the same name. Once
a header has been added, it cannot be removed.
This method is for advanced use only. If another Response method will provide the functionality
you require, it is recommended that you use that method instead.
Syntax: ASP Response Object AddHeader Method
Response.AddHeader name, value
Parameters: ASP Response Object AddHeader Method
name
The name of the header variable.
value
The value assigned to the header variable.
Remarks: ASP Response Object AddHeader Method
To avoid any name ambiguity, the name of the header should not contain any underscores (_).
The Request.ServerVariables collection interprets underscores as dashes in the header name.
The following script causes a search for a header named "My-Header":
<% Request.ServerVariables("HTTP_MY_HEADER") %>
Chili!Soft ASP 3.6 Product Documentation
439
Because HTTP protocol requires that all headers be sent before content, you must call the
AddHeader method in your script before any output (such as that generated by HTML code or
the ASP Response Object Write Method) is sent to the client. The exception to this rule is when
the ASP Response Object Buffer Property is set to True. If the output is buffered, you can call
the AddHeader method at any point in the script, as long as it precedes any calls to the ASP
Response Object Flush Method. Otherwise, the call to AddHeader will generate a run-time error.
The following two examples illustrate this. In the first example, the page is not buffered. The
script works, however, because the AddHeader method is called before the server sends the Web
page to the client. If the order were reversed, the call to the AddHeader method would generate a
run-time error.
<% Response.AddHeader "WARNING", "Error Message Text" %>
<HTML>
Some text on the Web page.
</HTML>
In the next example, the page is buffered, and as a result, the server will not send output to the
client until all the ASP scripts on the page have been processed or until the Flush method is
called. With buffered output, calls to the AddHeader method can appear anywhere the script, so
long as they precede any calls to the Flush method. If the call to the AddHeader method
appeared below the call to the Flush method in the preceding example, the script would generate
a run-time error.
<% Response.Buffer = TRUE %>
' Here is some text on your Web page.
<% Response.AddHeader "WARNING", "Error Message Text" %> Here's some
more interesting and illuminating text.
<% Response.Flush %>
<%= Response.Write("some string") %>
Examples: ASP Response Object AddHeader Method
The following example uses the AddHeader method to request that the client use BASIC
authentication.
<% Response.Addheader "WWW-Authenticate", "BASIC" %>
Note
The preceding script merely informs the client browser which authentication to use. If
you use this script in your Web applications, you should ensure that the Web server has
BASIC authentication enabled.
ASP Response Object AppendToLog Method
Chili!Soft ASP 3.6 Product Documentation
440
The AppendToLog method adds a string to the end of the Web log entry for this page request.
You can call it multiple times during the execution of a page; each time the string is appended to
the existing entry.
Syntax: ASP Response Object AppendToLog Method
Response.AppendToLog string
Parameters: ASP Response Object AppendToLog Method
string
The text to append to the log. Because fields in Web server logs are often comma-delimited, this
string cannot contain any commas. The maximum length of the string is 80 characters.
ASP Response Object BinaryWrite Method
The BinaryWrite method writes the specified information to the current HTTP output without
any character conversion. It is useful for sending non-string information, such as binary data
required by custom applications.
Syntax: ASP Response Object BinaryWrite Method
Response.BinaryWrite data
Parameters: ASP Response Object BinaryWrite Method
data
The binary information to be sent.
Examples: ASP Response Object BinaryWrite Method
If you have an object that creates an array of bytes, you can send the results using BinaryWrite:
<%
Set bg = Server.CreateObject(MY.BinaryGenerator)
Pict = bg.MakePicture
Response.BinaryWrite Pict
%>
ASP Response Object Clear Method
The Clear method erases any buffered HTML output. It only erases the response body, it does
not affect headers. You can use this method to handle error messages. Calling Clear will cause an
error if Response.Buffer is not TRUE.
Syntax: ASP Response Object Clear Method
Response.Clear
Chili!Soft ASP 3.6 Product Documentation
441
ASP Response Object End Method
The End method stops the Web server from processing any additional script and sends the
current result. The remaining contents of the file are not processed.
Syntax: ASP Response Object End Method
Response.End
Remarks: ASP Response Object End Method
If Response.Buffer is set to TRUE, End flushes the buffer. If you do not want the result sent to
the client, use the following:
Response.Clear
Response.End
ASP Response Object Flush Method
The Flush method sends buffered output immediately. Flush will cause a run-time error if called
when Response.Buffer is not TRUE.
Syntax: ASP Response Object Flush Method
Response.Flush
Remarks: ASP Response Object Flush Method
If Flush is called on an ASP page, the server does not honor Keep-Alive requests for that page.
ASP Response Object Redirect Method
The Redirect method causes the browser to attempt to connect to a different URL.
Syntax: ASP Response Object Redirect Method
Reponse.Redirect URL
Parameters: ASP Response Object Redirect Method
URL
The Uniform Resource Locator the client is redirected to.
Remarks: ASP Response Object Redirect Method
Any response body content set explicitly in the page is ignored. However, the method does send
to the client other HTTP headers set by this page. An automatic response body containing the
redirect URL as a link is generated.
The Redirect method sends the following explicit header:
HTTP/1.0 302 Object Moved
Chili!Soft ASP 3.6 Product Documentation
442
Location URL
ASP Response Object Write Method
The Write method writes a specified string to the current output.
Syntax: ASP Response Object Write Method
Response.Write variant
Parameters: ASP Response Object Write Method
variant
The data to write. This parameter can be any data type supported by the Visual Basic VARIANT
data type, including characters, strings, and integers. This value cannot contain the character
combination "%>"; instead you should use the escape sequence "%\>". The Web server will
translate the escape sequence when it processes the script.
Remarks: ASP Response Object Write Method
VBScript limits the size of string literals to 1022 bytes, therefore variant cannot be a string literal
of more than 1022 bytes. You can, however, specify variant as the name of a variable containing
more than 1022 bytes.
Examples: ASP Response Object Write Method
The following VBScript, in which a is repeated 1023 times in the string literal will fail:
<% Response.Write "aaaaaaaaaaaa...aaaaaaaaaaaaaaaaaa"
The following VBScript, in which `a' is repeated 4096 times in the string variable will succeed:
AVeryLongString = String(4096, "a")
Response.Write(AVeryLongString)
Using the Response.Write method to send output to the client:
I just want to say <% Response.Write "Hello World." %>
Your name is: <% Response.Write Request.Form("name") %>
The following script demonstrates adding an HTML tag to the Web page output. Because the
string returned by the Write method cannot contain the character combination, "%>", the escape,
"%\>", has been used instead:
<% Response.Write "<TABLE WIDTH = 100%\>" %>
The script outputs:
<TABLE WIDTH = 100%>
ASP Response Object Properties
ASP Response Object Buffer Property
Chili!Soft ASP 3.6 Product Documentation
443
The Buffer property determines whether to buffer page output. When page output is buffered,
HTML output is not sent to the client until the script on the page has been processed or until the
ASP Response Object Flush or ASP Response Object End methods are called.
The Buffer property cannot be set after the server has sent output to the client. For this reason,
you should set the Buffer property on the first line of the script.
Syntax: ASP Response Object Buffer Property
Response.Buffer = flag
Parameters: ASP Response Object Buffer Property
flag
Specifies whether to buffer page output. It can be one of the following values:
Value
Description
TRUE
Output is buffered. The server does not send output from the script on the page
until all the script has been processes or until the Flush or End method is
called.
FALSE
Output is not buffered. The server sends output from the script on the page as
the script is processed.
Remarks: ASP Response Object Buffer Property
If the current ASP script has buffering set to TRUE and does not call the ASP Response Object
Flush Method, the server will honor Keep-Alive requests made by the client. This saves time
because the server does not have to create a new connection for each client request.
However, buffering prevents any of the response from being displayed to the client until the
server has finished all script processing for the current page. For long scripts, this may cause a
perceptible delay.
ASP Response Object CacheControl Property
The CacheControl property overrides the default Private value. Setting this property to Public
allows proxy servers to cache the output generated by ASP.
Syntax: ASP Response Object CacheControl Property
Response.CacheControl = Cache Control Header
Parameters: ASP Response Object CacheControl Property
Cache Control Header
A cache control header that will be either Public or Private.
ASP Response Object Charset Property
The Charset property appends the name of the character set (for example, ISO-LATIN-7) to the
content-type header in the response object.
Chili!Soft ASP 3.6 Product Documentation
444
Syntax: ASP Response Object Charset Property
Response.Charset(CharsetName)
Parameters: ASP Response Object Charset Property
CharsetName
A string that specifies a character set for the page. The character set name will be appended to the
content-type header in the Response object.
Examples: ASP Response Object Charset Property
For an ASP page that did not include the Response.Charset property, the content-type header
would be:
content-type:text/html
If the same .asp file included:
<% Response.Charset("ISO-LATIN-7") %>
the content-type header would be:
content-type:text/html; charset=ISO-LATIN-7
Remarks: ASP Response Object Charset Property
This function inserts any string in the header, whether it represents a valid character set or not.
If a single page contains multiple tags containing Response.Charset, each Response.Charset
will replace the previous CharsetName. As a result, the character set will be set to the value
specified by the last instance of Response.Charset in the page.
ASP Response Object ContentType Property
The ContentType property specifies the HTTP content type for the response. If not specified, the
default is "text/HTML."
Syntax: ASP Response Object ContentType Property
Response.ContentType = ContentType
Parameters: ASP Response Object ContentType Property
ContentType
A string describing the content type. This string is usually formatted type/subtype, where type is
the general content category and subtype is the specific content type. For a full list of supported
content types, see your Web browser documentation or the current HTTP specification.
Examples: ASP Response Object ContentType Property
The following example sets the content type to non-HTML encoded text. This means the client
will not interpret any HTML tags in the text:
Chili!Soft ASP 3.6 Product Documentation
445
<% Response.ContentType="text/plain"
The following example shows some other common content types:
<% Response.ContentType = "text/html" %>
<% Response.ContentType = "image/GIF" %>
<% Response.ContentType = "image/JPEG" %>
ASP Response Object Expires Property
The Expires property sets the length of time a page will be cached on a client browser. If the user
returns to the page before it expires, the cached version will be displayed.
Syntax: ASP Response Object Expires Property
Response.Expires = number
Parameters: ASP Response Object Expires Property
number
The number of minutes until the page expires. Set this to 0 to have the cached page expire
immediately.
Remarks: ASP Response Object Expires Property
If the property is set more than once on a page, the shortest time is used.
ASP Response Object ExpiresAbsolute Property
The ExpiresAbsolute property specifies the date and time at which a page cached on a browser
expires. If the user returns to the same page before that date and time, the cached version is
displayed. If a time is not specified, the page expires at midnight of that day. If a date is not
specified, the page expires at the given time on the day that the script is run.
Syntax: ASP Response Object ExpiresAbsolute Property
Reponse.ExpiresAbsolute = [date] [time]
Parameters: ASP Response Object ExpiresAbsolute Property
date
Specifies the date on which the page will expire. The value sent in the Expires header conforms to
the RFC-1123 date format.
time
Specifies the time at which the page will expire. This value is converted to GMT before the
header is sent.
Remarks: ASP Response Object ExpiresAbsolute Property
Chili!Soft ASP 3.6 Product Documentation
446
If this property is set more than once on a page, the earliest time is used.
Examples: ASP Response Object ExpiresAbsolute Property
The following example sets the page to expire 15 seconds after 1:30 p.m. on May 31, 1996:
Response.ExpiresAbsolute = #May 31, 1996 13:30:15#
ASP Response Object IsClientConnected Property
The IsClientConnected property is a read-only property that indicates if the client has
disconnected since the last call to Response.Write.
Syntax: ASP Response Object IsClientConnected Property
Response.IsClientConnected
Remarks: ASP Response Object IsClientConnected Property
This property allows you greater control over circumstances where the client may have
disconnected from the server. For example, if a long period of time has elapsed between a client
request and the server response, it may be beneficial to make sure the client is still connected
before continuing to process the script.
Examples: ASP Response Object IsClientConnected Property
<%
'check to see if the client is connected
If Not Response.IsClientConnected Then
'get the sessionid to send to the shutdown function
Shutdownid = Session.SessionID
'perform shutdown processing
Shutdown(Shutdownid)
End If
%>
ASP Response Object PICS Property
The PICS property adds a value to the pics-label field of the response header.
Syntax: ASP Response Object PICS Property
Response.PICS(PICSLabel)
Parameters: ASP Response Object PICS Property
PICSLabel
Chili!Soft ASP 3.6 Product Documentation
447
A string that is a properly formatted PICS label. The value will be appended to the PICS-Label
field in the response header.
Remarks: ASP Response Object PICS Property
The Response.PICS property inserts any string into the response header, whether or not it is a
valid PICS label.
If a single page sets Response.PICS multiple times, each setting will replace the previous one.
As a result, the PICS label will be set to the last Response.PICS instance on the page.
Because PICS labels contain quotes, you must replace quotes with " & chr(34) & ".
Examples: ASP Response Object PICS Property
For an .asp file that includes:
<%
Response.PICS("(PICS-1.1 <http://www.rsac.org/ratingv01.html>
labels on " & chr(34) & "1997.01.05T08:15-0500" & chr(34) &
" until" & chr(34) & "1999.12.31T23:59-0000" & chr(34) &
" ratings (v 0 s 0 l 0 n 0))")
%>
the following header would be added:
PICS-label:(PICS-1.1 <http://www.rsac.org/ratingv01.html>
labels on "1997.01.05T08:15-0500"
until "1999.12.31T23:59-0000"
ratings (v 0 s 0 l 0 n 0))
ASP Response Object Status Property
The Status property sets the value of the status line returned by the server. Status values are
defined in the HTTP specification.
Syntax: ASP Response Object Status Property
Response.Status = StatusDescription
Parameters: ASP Response Object Status Property
StatusDescription
A string that contains a three-digit status code and a brief explanation of that status. For example,
"310 Move Permanently".
Remarks: ASP Response Object Status Property
448
Chili!Soft ASP 3.6 Product Documentation
Use this property to modify the status line returned by the server.
Examples: ASP Response Object Status Property
The following example sets the response status:
Response.Status = "401 Unauthorized"
ASP Server Object
The Server object provides access to methods and properties on the server. Most of its methods
and properties serve as utility functions.
Syntax: ASP Server Object
Server.method | property
ASP Server Object Properties
ASP Server Object ScriptTimeout Property The length of time a script runs before it is
terminated.
ASP Server Object Methods
ASP Server Object CreateObject Method
Creates an instance of a server component.
ASP Server Object HTMLEncode Method Applies HTML encoding to a specified string.
ASP Server Object MapPath Method
Maps the specified virtual path, either the absolute
path on the current server or the path relative to the
current page, into a physical path.
ASP Server Object URLEncode Method
Applies URL encoding rules, including escape
characters, to a string.
ASP Server Object Methods
ASP Server Object CreateObject Method
The CreateObject method creates an instance of a server component. If the component has
implemented the OnStartPage and OnEndPage methods, the OnStartPage method is called at
this time.
Syntax: ASP Server Object CreateObject Method
Obj = Server.CreateObject( progID )
Parameters: ASP Server Object CreateObject Method
Obj
Chili!Soft ASP 3.6 Product Documentation
449
A variable name for the object
progID
Specifies the type of object to create. The format for progID is [vendor.]component[.version].
Remarks: ASP Server Object CreateObject Method
By default, objects created by the Server.CreateObject method have page scope. This means
that they are automatically destroyed by the server when it finishes processing the current ASP
page.
To create an object with session or application scope, you can either use the <OBJECT> tag and
set the SCOPE parameter to SESSION or APPLICATION, or store the object in a session or
application variable.
Examples: ASP Server Object CreateObject Method
You can destroy an object by setting the variable to NOTHING or setting the variable to a new
value, as shown below. The first example releases the object ad. The second replaces ad with a
string:
<% Session("ad") = Nothing %>
<% Session("ad") = "some other value" %>
You cannot create an object with the same name as a built-in object. The following example will
cause an error:
<% Set Response = Server.CreateObject("Response") %>
The following example creates an instance of the MSWC.BrowserType component. This
component can be used to determine the capabilities of the browser requesting the page.
<% Set MyB = Server.CreateObject("MSWC.BrowserType") %>
ASP Server Object HTMLEncode Method
The HTMLEncode method applies HTML encoding to a specified string.
Syntax: ASP Server Object HTMLEncode Method
Server.HTMLEncode( string )
Parameters: ASP Server Object HTMLEncode Method
string
Specifies the string to encode.
Examples: ASP Server Object HTMLEncode Method
The following script:
<% Server.HTMLEncode("The paragraph tag <P>" %>
Chili!Soft ASP 3.6 Product Documentation
450
produces the following output:
The paragraph tag &lt;P&gt;
The preceding text will be displayed on a Web browser as:
The paragraph tag <P>
You can view the source to see the encoded HTML.
ASP Server Object MapPath Method
The MapPath method maps the specified relative or virtual path to the corresponding physical
directory on the server.
Syntax: ASP Server Object MapPath Method
Server.MapPath( path )
Parameters: ASP Server Object MapPath Method
path
Specifies the relative or virtual path to map to a physical directory. If path starts with either a
forward or backward slash, either (/) or (\), the MapPath method returns a path as if path is a full
virtual path. If path doesn't start with a slash, the MapPath method returns a path relative to the
directory of the .ASP file being processed.
Note
The path parameter can contain relative paths (../../Scripts/, for example).
Remarks: ASP Server Object MapPath Method
The MapPath method does not check whether the path it returns is valid or exists on the server.
Because the MapPath method maps a path regardless of whether the specified directories
currently exist, you can use the MapPath method to map a path to a physical directory structure,
and then pass that path to a component that creates the specified directory or file on the server.
Examples: ASP Server Object MapPath Method
For the examples below, the DATA.TXT and TEST.ASP files are located in the
C:\Inetpub\Wwwroot\Script directory. The TEST.ASP file contains scripts. The
C:\Inetpub\Wwwroot directory is set as the server's home directory.
The following example uses the server variable PATH_INFO to map the physical path to the
current file:
<%= server.mappath(Request.ServerVariables("PATH_INFO"))%>
<BR>
This script produces the following:
c:\inetpub\wwwroot\script\test.asp<BR>
Chili!Soft ASP 3.6 Product Documentation
451
Because the path parameters in the following examples do not start with a slash character, they
are mapped relative to the current directory, in this case C:\Inetpub\Wwwroot\Script.
<%= server.mappath("data.txt")%><BR>
<%= server.mappath("script/data.txt")%><BR>
This script outputs the following:
c:\inetpub\wwwroot\script\data.txt<BR>
c:\inetpub\wwwroot\script\script\data.txt<BR>
The next two scripts use the slash characters to specify that the paths returned should be looked
up as complete virtual paths on the server:
<%= server.mappath("/script/data.txt")%><BR>
<%= server.mappath("\script")%><BR>
This script outputs the following:
c:\inetpub\script\data.txt<BR>
c:\inetpub\script<BR>
The following examples demonstrate how you can use either a forward slash (/) or a backslash (\)
to return the physical path to the home directory. The following script:
<%= server.mappath("/")%><BR>
<%= server.mappath("\")%><BR>
produces the following output:
c:\inetpub\wwwroot<BR>
c:\inetpub\wwwroot<BR>
ASP Server Object URLEncode Method
The URLEncode method applies URL encoding rules, including escape characters, to a specified
string.
Syntax: ASP Server Object URLEncode Method
Server.URLEncode( string )
Parameters: ASP Server Object URLEncode Method
string
Specifies the string to encode.
Examples: ASP Server Object URLEncode Method
The following example encodes the paragraph tag:
<%= Server.URLEncode("The paragraph tag: <P>") %>
Chili!Soft ASP 3.6 Product Documentation
452
The script produces the following:
The+paragraph+tag%3A+%3CP%3E
ASP Server Object Properties
ASP Server Object ScriptTimeout Property
The ScriptTimeout property specifies the maximum amount of time a script can run before it is
terminated. The delay before scripts are ended is by default 90 seconds. This will not take effect
while a server component is processing.
Syntax: ASP Server Object ScriptTimeout Property
Server.ScriptTimeout = NumSeconds
Parameters: ASP Server Object ScriptTimeout Property
NumSeconds
Specifies the maximum number of seconds that a script can run before the server terminates it.
The default value is 90 seconds.
Note
The ScriptTimeout property cannot be set to a value less than that specified in the
registry settings or configuration file. For example, if NumSeconds is set to 10, and the
registry setting or configuration file contains the default value of 90 seconds, scripts will
time out after 90 seconds. However, if NumSeconds were set to 100, the scripts would
time out after 100 seconds.
Examples: ASP Server Object ScriptTimeout Property
The following example causes scripts to time out if the server takes longer than 30 seconds to
process them.
<% Server.ScriptTimeout = 30 %>
The following example retrieves the current value of the ScriptTimeout property and stores it in
the variable TimeOut.
<% TimeOut = Server.ScriptTimeout %>
ASP Session Object
The Session object stores information needed for a particular user-session.
Variables stored in the Session object are not discarded when the user jumps between pages in the
application; instead, they persist for the entire user-session. The Web server automatically creates
a Session object when a Web page (from a server application) is requested by a user who does not
already have a session. The server destroys the Session object when the session expires or is
abandoned.
Chili!Soft ASP 3.6 Product Documentation
453
The AllowSessionState registry or configuration file setting controls the creation of Session
objects. If AllowSessionState is set to False, the Session object cannot be used. The default is to
use Sessions.
Session object event scripts are declared in the Global.asa.
Note
Session state is only maintained for browsers that support cookies.
Syntax: ASP Session Object
Session.collection|property|method
ASP Session Object Collections
ASP Session Object Contents
Collection
Contains the items you have added to the session with script
commands.
ASP Session Object StaticObjects
Collection
Contains items created in Global.asa using the <OBJECT>
tag and given session scope.
ASP Session Object Properties
ASP Session Object SessionID
Property
Returns the session identifier for this client. Each session has
a unique identifier.
ASP Session Object Timeout Property The timeout period, in minutes, for session state for this
application.
ASP Session Object LCID Property
Sets or gets a Locale Identifier (LCID) that determines how
certain content—such as date, time, and currency—is
formatted.
The CodePage property is not currently implemented in Chili!Soft ASP.
ASP Session Object Methods
ASP Session Object Abandon Method Destroys a Session object and all objects stored in it, and
releases their resources.
ASP Session Object Events
Session_OnStart
Occurs when the server creates a new session. It runs before executing the
requested page.
Session_OnEnd
Occurs when the session is abandoned or times out.
Session object events are defined in the Global.asa file.
Chili!Soft ASP 3.6 Product Documentation
454
Remarks: ASP Session Object
You can store values in the Session object. Information stored in the Session object is available
for the entire session and has session scope. The following script demonstrates how two types of
variables are stored:
Session("username") = "Janine"
Session("age") = 42
If you are using VBScript as your scripting language, you must use the Set keyword to store an
object in the Session object, as shown in the following example:
<% Set Session("Obj1") = Server.CreateObject("MyComponent") %>
You can then call the methods and properties of Obj1 on subsequent Web pages by using the
following syntax:
<% Session("Obj1").MyObjMethod %>
As an alternative, you can extract a local copy of the object:
Set MyLocalObj = Session("Obj1")
MyLocalObj.MyObjMethod
You cannot store a built-in object in a Session object. Each of the following lines will return an
error:
Set Session("var1") = Session
Set Session("var2") = Request
Set Session("var3") = Response
Set Session("var4") = Server
Set Session("var5") = Application
Before you store an object in the Session object, you must know what threading model it uses.
Only objects marked as both free and apartment-threaded can be stored in the Session object.
The Session object is implemented as a collection. If you store an array in an Session object, you
should not attempt to alter elements of the stored array directly. For example, the following script
does not work:
Session("StoredArray") (3) = "new value"
Instead of storing the value "new value" in StoredArray(3), the value is stored in the
Session collection, overwriting any information stored at Session(3).
See the Application object for an example of storing an array.
ASP Session Object Collections
ASP Session Object Contents Collection
Chili!Soft ASP 3.6 Product Documentation
455
The Contents collection contains all of the items that have been created for a session without
using the <OBJECT> tag. The collection can be used to determine the value of a specific item, or
to iterate over all the items in the session.
Syntax: ASP Session Object Contents Collection
Session.Contents( key )
Parameters: ASP Session Object Contents Collection
key
The name of the item to retrieve.
Remarks: ASP Session Object Contents Collection
You can use an iterating control structure to loop through the keys of the Contents collection.
This is demonstrated in the following example.
<%
Dim sessitem
For Each sessitem in Session.Contents
Response.write(sessitem & " : " & Session.Contents(sessitem) &
"<BR>")
Next
%>
ASP Session Object StaticObjects Collection
The StaticObjects collection contains all the objects created in Global.asa with the <OBJECT>
tag and given session scope. The collection can be used to retrieve the value of a specific item, or
you can use an iterator to retrieve all the items in the collection.
Syntax: ASP Session Object StaticObjects Collection
Session.StaticObjects( key )
Parameters: ASP Session Object StaticObjects Collection
key
The item to retrieve.
Remarks: ASP Session Object StaticObjects Collection
You can use an iterating control structure to loop through the keys of the StaticObjects
collection. This is demonstrated in the following example.
<%
Chili!Soft ASP 3.6 Product Documentation
456
Dim objprop
For Each objprop in Session.StaticObjects
Response.write(objproperty & " : " &
Session.StaticObjects(objprop) & "<BR>")
Next
%>
ASP Session Object Methods
ASP Session Object Abandon Method
The Abandon method destroys all the objects stored in a Session object and releases their
resources. If you do not call the Abandon method explicitly, the server destroys these objects
when the session times out.
Syntax: ASP Session Object Abandon Method
Session.Abandon
Remarks: ASP Session Object Abandon Method
When the Abandon method is called, the current Session object is queued for deletion, but is not
actually deleted until all of the script commands on the current page have been processed. This
means that you can access variables stored in the Session object on the same page as the call to
Abandon, but not in any subsequent Web pages.
For example, in the following script, the third line prints the value Mary. This is because the
Session object is not destroyed until the server has finished processing the script.
Session.Abandon
Session("MyName") = "Mary"
Response.Write(Session("MyName"))
If you access the variable MyName on a subsequent Web page, it is empty. This is because
MyName was destroyed with the previous Session object when the page containing the above
example finished processing.
The server creates a new Session object when you open a subsequent Web page after abandoning
a session. You can store variables and objects in this new Session object.
ASP Session Object Properties
ASP Session Object SessionID Property
The SessionID property returns the session identification for this user. Each session has a unique
identifier that is generated by the server when the session is created. The session ID is returned as
data type LONG.
Chili!Soft ASP 3.6 Product Documentation
457
Syntax: ASP Session Object SessionID Property
Session.SessionID
Remarks: ASP Session Object SessionID Property
Do not use the SessionID property to generate primary key values for a database application. This
is because if the Web server is restarted, some SessionID values may be the same as those
generated before the server was stopped. Instead, you should use an auto-increment column data
type.
ASP Session Object Timeout Property
The Timeout property specifies the timeout period for the Session object for this application, in
minutes. If the user does not refresh or request a page within the timeout period, the session ends.
Syntax: ASP Session Object Timeout Property
Session.Timeout [= nMinutes]
Parameters: ASP Session Object Timeout Property
nMinutes
The number of minutes that a session can remain idle before the server terminates it
automatically. The default is 20 minutes.
Remarks: ASP Session Object Timeout Property
The SessionTimeout registry or configuration file setting controls the default value of the
Timeout property for an ASP application.
ASP Session Object LCID Property
The SessionID property enables you to set or get a Locale Identifier (LCID) that determines how
certain content—such as date, time, and currency—is formatted.
Syntax: ASP Session Object LCID Property
nCurrentLCID = Session.LCID
SessionLCID = nLCIDnumber
Parameters: ASP Session Object LCID Property
nLCIDnumber
A valid Local Identifier (LCID) number. For a list of valid values, see "Developing International
Applications" in "Chapter 4: Building a Chili!Soft ASP Application."
Remarks: ASP Session Object LCID Property
For usage and limitations, see "Developing International Applications" in "Chapter 4: Building a
Chili!Soft ASP Application."
Chili!Soft ASP 3.6 Product Documentation
458
Chili!Soft ASP 3.6 Product Documentation
459
ASP Component Reference
Chili!Soft ASP automatically installs a number of components that you can use to build dynamic
Web pages. This section provides reference information about these components.
In this section:
•
Installed ASP Components
•
ASP Ad Rotator Component
•
ASP Browser Capabilities Component
•
ASP Content Linking Component
•
ASP Content Rotator Component
•
ASP Counters Component
•
ASP MyInfo Component
•
ASP Tools Component
Installed ASP Components
The following is a list of ASP components that are installed with Chili!Soft ASP.
Component
Description
Ad Rotator
Creates an Ad Rotator object that automates the rotation of
advertisement images on a Web page.
Browser
Capabilities
Creates a BrowserType object that determines the type, version, and
capabilities of every browser that visits your site.
Content Linking
Creates a NextLink object that manages a list of URLs so that you can
treat the pages in your Web site like the pages in a book.
Content Rotator
Creates a ContentRotator object that automatically rotates HTML
content strings on a Web page.
Counters
Creates a Counters object that can create, store, increment, and retrieve
any number of individual counters.
MyInfo
Creates a MyInfo object that keeps track of personal information, such
as the site administrator's name, address, and display choices.
Tools
Creates a Tools object that provides utilities that enable you to easily
add sophisticated functionality to your Web pages.
ASP Ad Rotator Component
The Ad Rotator component creates an Ad Rotator object that automates the rotation of
advertisement images on a Web page. Each time a user opens or reloads the Web page, the Ad
Rotator object displays a new advertisement based on the information you specify in a Rotator
Schedule file.
Chili!Soft ASP 3.6 Product Documentation
460
You can record how many users click each advertisement by setting the URL parameter in the
Rotator Schedule file to direct users to the Redirection file. When you specify this parameter,
each jump to an advertiser’s URL is recorded in the Web server activity logs.
The Ad Rotator object relies on two additional files for parameters and functionality:
Redirection File. An optional file that implements redirection and enables you to record how
many users click on each advertisement and save this information to a file on the server.
Rotator Schedule File. A text file that contains the display schedule and file information for
advertisements. This file must be available on a Web server virtual path.
Registry Settings: ASP Ad Rotator Component
The Ad Rotator Component makes use of no registry settings.
Control Reference[0]: ASP Ad Rotator Component
The Ad Rotator Control is registered with the ProgId of "MSWC.AdRotator". The following
VBScript excerpt shows creating an instance of the control.
Set adRot = Server.CreateObject( "MSWC.AdRotator" )
Properties: ASP Ad Rotator Component
•
Border
•
Clickable
•
TargetFrame
ASP Ad Rotator Component Rotator Schedule File
The Rotator Schedule file contains information that the Ad Rotator component uses to manage
and display the various advertisement images. In it you can specify the details for the
advertisements, such as the size of the advertisement space, the image files to use, and the
percentage of time that each file should be displayed.
The Rotator Schedule file has two sections. The first section sets parameters that apply to all
advertisement images in the rotation schedule. The second section specifies file and location
information for each individual advertisement and the percentage of display time that each
advertisement should receive. The two sections are separated by a line containing only an asterisk
(*).
In the first section there are four global parameters, each consisting of a keyword and a value. All
are optional. If you do not specify values for the global parameters, the Ad Rotator uses default
values. In this case, the first line of the file must contain only an asterisk (*).
Syntax: ASP Ad Rotator Component Rotator Schedule File
[REDIRECT URL]
[WIDTH numWidth]
Chili!Soft ASP 3.6 Product Documentation
461
[HEIGHT numHeight]
[BORDER numBorder]
*
adURL
adHomePageURL
Text
impressions
Parameters: ASP Ad Rotator Component Rotator Schedule File
URL
Specifies the path to the dynamic-link library (.dll) or application (.asp) file that implements
redirection. This path can be specified either fully (http://MyServer/MyDir/redirect.asp) or
relative to the virtual directory (/MyDir/redirect.asp).
numWidth
Specifies the width of the advertisement on the page, in pixels. The default is 440 pixels.
numHeight
Specifies the height of the advertisement on the page, in pixels. The default is 60 pixels.
numBorder
Specifies the thickness of the hyperlink border around the advertisement, in pixels. The default is
a 1-pixel border. Set this parameter to 0 for no border.
adURL
The location of the advertisement image file.
adHomePageURL
The location of the advertiser’s home page. If the advertiser does not have a home page, put a
hyphen (-) on this line to indicate that there is no link for this ad.
Text
Alternate text that is displayed if the browser does not support graphics, or has its graphics
capabilities turned off.
impressions
A number between 0 and 10000 that indicates the relative weight of the advertisement.
For example, if a Rotator Schedule file contains three ads with impressions set to 2, 3, and 5, the
first advertisement is displayed 20 percent of the time, the second 30 percent of the time, and the
third 50 percent of the time.
Chili!Soft ASP 3.6 Product Documentation
462
Remarks: ASP Ad Rotator Component Rotator Schedule File
If the sum of the impressions parameters for all items exceeds 10000, an error will be generated
the first time the Rotator Schedule file is accessed by a call to the GetAdvertisement method.
Examples: ASP Ad Rotator Component Rotator Schedule File
The following script demonstrates how you can use a rotator schedule file to display a variety of
advertisements and how to include a redirection file.
---ADROT.TXT--REDIRECT /scripts/adredir.asp
WIDTH 440
HEIGHT 60
BORDER 1
*
http://kabaweb/ads/homepage/chlogolg.gif
http://www.bytecomp.com/
Check out the ByteComp Technology Center
20
http://kabaweb/ads/homepage/gamichlg.gif
Sponsored by Flyteworks
20
http://kabaweb/ads/homepage/ismodemlg.gif
http:// www.proelectron.com/
28.8 internal PC modem, only $99
80
http://kabaweb/ads/homepage/spranklg.gif
http://www.clocktower.com/
The #1 Sports site on the net
10
ASP Ad Rotator Component Redirection File
The Redirection file is a file that you create. It usually includes script to parse the query string
sent by the AdRotator object and to redirect the user to the URL associated with the
advertisement that the user clicked on.
Chili!Soft ASP 3.6 Product Documentation
463
You can also include script in the Redirection file to count the number of users that have clicked
on a particular advertisement, and save this information to a file on the server.
Examples: ASP Ad Rotator Component Redirection File
The following example redirects the user to the advertiser’s home page.
---ADREDIR.ASP--<% Response.Redirect(Request.QueryString("url")) %>
ASP Ad Rotator Component Properties
ASP Ad Rotator Component Border Property
The Border property enables you to specify whether to display the advertisements with a
surrounding border.
Syntax: ASP Ad Rotator Component Border Property
Border = size
Parameters: ASP Ad Rotator Component Border Property
size
Specifies the thickness of the border that surrounds the displayed advertisement. The default is
the value set in the header of Rotator Schedule file. 0 specifies no border.
ASP Ad Rotator Component Clickable Property
The Clickable property enables you to specify whether the advertisements are displayed as
hyperlinks.
Syntax: ASP Ad Rotator Component Clickable Property
Clickable = value
Parameters: ASP Ad Rotator Component Clickable Property
value
Specifies whether the advertisement should be a hyperlink. This parameter can set to either
TRUE or FALSE. If FALSE, only the image is displayed without a "click-through" hyperlink.
The default value is TRUE.
ASP Ad Rotator Component TargetFrame Property
The TargetFrame property specifies the target frame into which the link should be loaded. This
property fulfills the same function as the TARGET parameter in an HTML anchor statement.
Syntax: ASP Ad Rotator Component TargetFrame Property
TargetFrame = frame
Chili!Soft ASP 3.6 Product Documentation
464
Parameters: ASP Ad Rotator Component TargetFrame Property
frame
Specifies the name of the frame in which to display the advertisement. This parameter can also be
one of the HTML frame-keywords, such as _TOP, NEW, CHILD, _SELF, _PARENT, or
_BLANK. The default value is NO FRAME.
ASP Ad Rotator Component Methods
ASP Ad Rotator Component GetAdvertisement Method
The GetAdvertisement method retrieves the next advertisement from the Rotator Schedule file.
Each time the script is run, such as when a user opens or refreshes a page, the method retrieves
the next scheduled advertisement.
Arguments: ASP Ad Rotator Component GetAdvertisement Method
rotationSchedulePath
Specifies the location of the Rotator Schedule file relative to the
virtual directory. For example, if the physical path was
C:\Inetpub\Wwwroot\Ads\Adrot.txt (where Wwwroot is the "/" virtual
directory), you would specify the path \Ads\Adrot.txt.
Return Values: ASP Ad Rotator Component GetAdvertisement Method
Returns HTML that displays the advertisement in the current page.
Examples: ASP Ad Rotator Component GetAdvertisement Method
The following example gets an advertisement from the Adrot.txt file in the /Ads/ virtual directory.
<% Set NextAd = Server.CreateObject("MSWC.AdRotator") %>
<%= NextAd.GetAdvertisement("/ads/adrot.txt") %>
Examples: ASP Ad Rotator Component GetAdvertisement Method HTML Output
Assuming the following fragment of a redirection file is chosen by the control:
REDIRECT /foo/bar.asp
WIDTH 300
HEIGHT 40
BORDER 1
*
/ads/picture.gif
http://www.chilisoft.com/info/index.html
Hello from Chilisoft.
90
The HTML that is produced is:
Chili!Soft ASP 3.6 Product Documentation
465
<A HREF=
"/foo/bar.asp?url=http://www.chilisoft.com/info/index.html&image=/ad
s/picture.gif TARGET="_blank">
<IMG SRC="/ads/picture.gif" ALT="Hello from Chilisoft" WIDTH=300
HEIGHT=40 BORDER = 1>
</A>
The Redirect script "foo/bar.asp" is invoked and can record click-through information before
redirecting the client browser to the user’s desired location.
ASP Browser Capabilities Component
The Browser Capabilities component determines which features a browser supports. This
component uses two files: Browscap.ini and Browscap.dll (libchilicap.so and libchilicap.ini on
UNIX).
Syntax: ASP Browser Capabilities Component
Set BrowserType = Server.CreateObject("MSWC.BrowserType")
Parameters: ASP Browser Capabilities Component
BrowserType
Specifies the name of the object created by the call to Server.CreateObject.
When a client requests a page from the server, the HTTP header includes a user agent ASCII
string that specifies the browser software name and version. The Browser Capabilities component
searches for this string in the Browser Capabilities component Browsecap.ini file. When it finds a
match, the properties of the client browser are read and the server adopts the properties of the
browser.
The following table lists the minimum set of properties that ASP always checks:
Property
Description
ActiveXControls
Support for Active X Controls.
Backgroundsounds Support for background sounds.
Beta
Is browser beta software?
Browser
Browser name.
Cookies
Support for cookies.
Frames
Support for frames.
Javaapplets
Support for Java applets.
Javascript
Support for JavaScript.
Majorver
Major version number of the browser.
Chili!Soft ASP 3.6 Product Documentation
Minorver
Minor version number of the browser.
Parent
Parent browser (as defined in
browscap.ini).
Platform
User's operating system.
Tables
Support for HTML tables.
Vbscript
Support for VBScript.
Version
Full version number of the browser.
466
ASP Browser Capabilities Component Browsecap.ini File
The Browscap.ini (called libchilicap.ini on UNIX) file contains information about each known
browser. It is a standard text file that lists features a browser supports. The Browscap.ini file
maps browser capabilities to the HTTP User Agent header.
It is important to keep your Browscap.ini or libchilicap.ini file up to date. When new browsers are
released their capabilities are unknown to the current file, and pages that rely on browser
detection may fail. You can obtain updates to Browscap.ini at:
http://www.cyscape.com/browscap/
To use the Browscap.ini file on UNIX, you must convert the text file to UNIX format and rename
it "libchilicap.ini." You should rename your existing libchilicap.ini file "libchilicap.old" before
installing the updated version.
You can also maintain the Browscap.ini file by editing the Browscap.ini file. A default section of
the Browscap.ini file is used when the browser details don't match any of the ones specified. If
the browser in use doesn't match any in the Browscap.ini file, and no default browser settings are
specified, all properties are set "UNKNOWN."
Note
The Browscap.ini (or libchilicap.ini) file must be in the same directory as Browscap.dll or
libchilicap.so.
To use the Browser Capabilities Component, it is necessary to create an instance of it and
refer to its properties. To avoid having the Browscap.ini file accessed every time, read the
value once and assign it to a variable:
Set objBCap = Server.CreateObject("MSWC.BrowserType")
Synatax: Browsecap.ini File HTTPUserAgentHeader Section
The HTTPUserAgentHeader section of Browscap.ini (libchilicap.ini on UNIX) defines the
properties for a particular browser. The syntax is as follows:
[HTTPUserAgentHeader]
parent = browserDefinition
property1 = value 1
Chili!Soft ASP 3.6 Product Documentation
467
property2 = value 2
.
.
.
Parent
Another definition contains more information for that browser
value 1
A number used to map a capability for the first property listed.
value 2
A number used to map a capability for the second property listed.
Browsecap.ini File Default Section
The Default section of Browscap.ini (libchilicap.ini on UNIX) lists the properties and values
to be used if the current browser isn't listed in its own section (or, if listed, not all properties are
supplied). The following is the syntax for the default section of the Browscap.ini file:
[Default Browser Capability Settings]
defaultProperty1 = default value 1
defaultProperty2 = default value 2
.
.
.
default value 1
A number used to map a default capability for the first property listed.
default value 2
A number used to map a default capability for the second property listed.
Examples: Browsecap.ini File Default Section[0]
This example shows entries for Internet Explorer (IE) 3.0. Since it has no parent line, the only
properties its has (other than those defined in the default section) are those explicitly defined:
[IE 3.0]
browser=IE
Version =3.0
majorver=#3
minorver=#0
frames=TRUE
Chili!Soft ASP 3.6 Product Documentation
tables=TRUE
cookies=TRUE
vbscript=TRUE
javascript=TRUE
ActiveXControls=TRUE
In the following example IE 3.0 is specified as the parent for the browser. The properties
explicitly provided replace, or add to, those values in the parent's definition:
[Mozilla/2.0 (compatible; MSIE 3.01; Windows 95)]
parent=IE 3.0
version = 3.01
minorver=01
platform=Win95
[Default Browser Capability Settings]
browser=Default
frames=FALSE
tables=FALSE
cookies=FALSE
backgroundsounds=FALSE
vbscript= FALSE
javascript= FALSE
. . .
To determine if a browser supports JavaScript use the following code:
bc = Server.CreateObject("MSWC.BrowserType")
if bc.javascript = 0 then
Response.Write "This browser does not support JavaScript."
else
REM The browser supports JavaScript so simply continue.
end if
The following example determines if a browser supports tables:
bc = Server.CreateObject("MSWC.BrowserType")
if bc.tables = 0 then
Response.Write "This browser does not support tables."
. . .
468
Chili!Soft ASP 3.6 Product Documentation
469
The following example uses the Browser Capabilities component to display a table showing some
of the capabilities of the current browser:
<% Set bc = Server.CreateObject("MSWC.BrowserType") %>
<table border=1>
<tr><td>Browser</td><td> <%= bc.browser %>
<tr><td>Version</td><td> <%= bc.version %> </td></TR>
<tr><td>Frames</td><td>
<% if (bc.frames = TRUE) then %> TRUE
<% else %> FALSE
<% end if %> </td></TR>
<tr><td>Tables</td><td>
<% if (bc.tables = TRUE) then %> TRUE
<% else %> FALSE
<% end if %> </td></TR>
<tr><td>BackgroundSounds</td><td>
<% if (bc.BackgroundSounds = TRUE) then %> TRUE
<% else %> FALSE
<% end if %> </td></TR>
<tr><td>VBScript</td><td>
<% if (bc.vbscript = TRUE) then %> TRUE
<% else %> FALSE
<% end if %> </td></TR>
<tr><td>JScript</td><td>
<% if (bc.javascript = TRUE) then %> TRUE
<% else %> FALSE
<% end if %> </td></TR>
</table>
ASP Content Linking Component
The Content Linking component creates a NextLink object that manages a list of URLs so that
you can treat the pages in your Web site like the pages in a book. You can use the Content
Linking component to automatically generate and update tables of contents and navigational links
to previous and subsequent Web pages. This is ideal for applications such as online newspapers
and forum message listings.
Chili!Soft ASP 3.6 Product Documentation
470
The Content Linking component references a Content Linking List file that contains the list of the
linked Web pages. This list is stored on the Web server and must be available on a web server
virtual path.
Registry Settings: ASP Content Linking Component
The control makes use of no registry settings.
Control Reference: ASP Content Linking Component
The Content Linking component is registered with the ProgId of "MSWC.NextLink." The
following VBScript excerpt shows creating an instance of the control.
Set cLinker = Server.CreateObject( "MSWC.NextLink" )
Properties: ASP Content Linking Component
None.
Methods: ASP Content Linking Component
•
GetListCount
•
etListIndex
•
GetNextDescription
•
GetNextURL
•
GetNthDescription
•
GetNthURL
•
GetPreviousDescription
•
GetPreviousURL
Examples: ASP Content Linking Component
The following example builds a table of contents.
<OL>
<%
Set NextLink = Server.CreateObject ("MSWC.NextLink")
count = NextLink.GetListCount ("/data/nextlink.txt")
I = 1
%>
<UL>
<% Do While (I <= count) %>
<LI><A HREF=" <%= NextLink.GetNthURL ("/data/nextlink.txt", I) %> ">
Chili!Soft ASP 3.6 Product Documentation
471
<%= NextLink.GetNthDescription ("/data/nextlink.txt", I) %> </A>
<%
I = (I + 1)
Loop
%>
</UL>
</OL>
The following script adds the next-page and previous-page buttons to an HTML file.
<%
Set NextLink = Server.CreateObject ("MSWC.NextLink")
If (NextLink.GetListIndex ("/data/nextlink.txt") > 1)
Then
%>
<A HREF=" <%= NextLink.GetPreviousURL ("/data/nextlink.txt") %> ">
Previous Page</A>
<% End If %>
<A HREF=" <%= NextLink.GetNextURL ("/data/nextlink.txt") %> ">Next
Page</A>
ASP Content Linking Component Content Linking List File
The Content Linking List file contains one line of text for each URL in the list. Each line ends in
a carriage return and each item on a line is separated by a TAB character.
Syntax: ASP Content Linking Component Content Linking List File
Web-page-URL [text-description [comment]]
Values[0]: ASP Content Linking Component Content Linking List File
Web-page-URL
The virtual or relative URL of the Web page in the format filename or directory\filename.
Absolute URLs, those that start with "http:", "//", or "\\”, are not supported and will not be
processed by methods such as GetNextURL and GetListIndex. When building your content
path, you should ensure that no collisions or infinite loops can occur.
text-description
A value containing text that describes Web-page-URL.
comment
Explanatory text that is not processed by the component.
Chili!Soft ASP 3.6 Product Documentation
472
Examples: ASP Content Linking Component Content Linking List File
The following text file creates a list of URLs that can be used by the Content Linking component.
---NEXTLINK.TXT--story1.htm Highlights From the Hockey Playoffs
story2.htm Congress Passes New Welfare Initiative
story3.htm Cider Recipes to Warm Long Winter Nights
story4.htm Winter Storm to bring more snow to East
story5.htm Reducing Stress on the Job
main.htm Return to the table of contents
ASP Content Linking Component Methods
ASP Content Linking Component GetListCount Method
The GetListCount method retrieves the total number of Web pages listed in the Content Linking
List file.
Arguments: ASP Content Linking Component GetListCount Method
listURL
The location of the Content Linking List file.
Return Values: ASP Content Linking Component GetListCount Method
This method returns an integer.
ASP Content Linking Component GetListIndex Method
The GetListIndex method retrieves the index number of the current item in the Content Linking
List file.
Arguments: ASP Content Linking Component GetListIndex Method
listURL
The location of the Content Linking List file.
Return Values: ASP Content Linking Component GetListIndex Method
The GetListIndex method returns an integer index value specifying the current page’s position
on the file list. The index number of the first item is 1. The method returns 0 if the current page is
not in the Content Linking List file.
ASP Content Linking Component GetNextDescription Method
The GetNextDescription method retrieves the text description of the next item in the Content
Linking List file.
Arguments: ASP Content Linking Component GetNextDescription Method
Chili!Soft ASP 3.6 Product Documentation
listURL
473
The location of the Content Linking List file.
Return Values: ASP Content Linking Component GetNextDescription Method
The GetNextDescription method returns an ASCII string describing the next item in the Content
Linking List file. If the current page is not found in the list file, GetNextDescription returns the
string description of the last page on the list.
ASP Content Linking Component GetNextURL Method
The GetNextURL method retrieves the URL of the next item in the Content Linking List file.
Arguments: ASP Content Linking Component GetNextURL Method
listURL
The location of the Content Linking List file.
Return Values: ASP Content Linking Component GetNextURL Method
This method returns the URL of the next page specified in the Content Linking List file. If the
current page is not specified in the Content Linking List file, GetNextURL returns the URL of
the last page on the list.
Examples: ASP Content Linking Component GetNextURL Method
The following example uses the GetNextURL method to embed a link to the next page in the
Content Linking List file. The advantage of using GetNextURL is that when you change the
order or number of the content pages, you only have to update the list in the Content Linking List
file and do not need to update the navigational links on each page.
<% Set NextLink = Server.CreateObject ("MSWC.NextLink") %>
<A HREF="<%= NextLink.GetNextURL ("/data/nextlink.txt") %>">Next
Page </A>
ASP Content Linking Component GetNthDescription Method
The GetNthDescription method retrieves a text description of the nth item in the Content
Linking List file.
Arguments: ASP Content Linking Component GetNthDescription Method
listURL
The location of the Content Linking List file.
index
The index number of an item in the Content Linking List
fil.e
Return Values: ASP Content Linking Component GetNthDescription Method
This method returns a string.
ASP Content Linking Component GetNthURL Method
The GetNthURL method returns the URL of the Nth item in the Content Linking List file.
Chili!Soft ASP 3.6 Product Documentation
474
Arguments: ASP Content Linking Component GetNthURL Method
listURL
The location of the Content Linking List file.
index
The index number of an item in the Content Linking List
file.
Return Values: ASP Content Linking Component GetNthURL Method
This method returns a string.
ASP Content Linking Component GetPreviousDescription Method
The GetPreviousDescription method retrieves a text description of the previous item in the
Content Linking List file.
Arguments: ASP Content Linking Component GetPreviousDescription Method
listURL
The location of the Content Linking List file.
Return Values: ASP Content Linking Component GetPreviousDescription Method
This method returns a string describing either the previous item in the Content Linking List file
or, if the current page is not in the file, the first item on the list.
ASP Content Linking Component GetPreviousURL Method
The GetPreviousURL method returns the URL of the previous item in the Content Linking List
file.
Arguments: ASP Content Linking Component GetPreviousURL Method
listURL
The location of the Content Linking List file.
Return Values: ASP Content Linking Component GetPreviousURL Method
This method returns a string containing the URL of the previous item in the Content Linking List
file. If the current page is not specified in the Content Linking List file, GetPreviousURL returns
the URL of the first page in the file.
ASP Content Rotator Component
The Content Rotator component creates a ContentRotator object that automatically rotates
HTML content strings on a Web page. Each time a user requests the Web page, the object
displays a new HTML content string based upon information that you specify in a Content
Schedule file.
Because the content strings can contain HTML tags, you can display any type of content that
HTML can represent: text, images, or hyperlinks. For example, you can use this component to
rotate through a list of daily quotations or hyperlinks, or to change text and background colors
each time the Web page is opened.
Chili!Soft ASP 3.6 Product Documentation
475
Because the ContentRotator object uses a random generator to select which of the weighted
content strings is displayed, a string may be repeated. This is most likely to occur if there are few
entries in the Content Schedule file, or if one entry is weighted much higher than the others.
Registry Settings: ASP Content Rotator Component
The ASP Content Rotator component makes use of no registry settings.
Control Reference: ASP Content Rotator Component
The Content Rotator component is registered with the ProgId of "MSWC.ContentRotator." The
following VBScript excerpt shows creating an instance of the control.
Set oVar = Server.CreateObject( "MSWC.ContentRotator" )
Properties: ASP Content Rotator Component
None
Methods: ASP Content Rotator Component
ChooseContent
GetAllContent
ASP Content Rotator Component Content Schedule File
The Content Schedule file contains information that the ContentRotator object uses to manage
and display the specified content. In this file you include any number of HTML content string
entries. Each entry consists of two parts: a line that begins with double percentage signs (%%)
and contains both the relative weight and any comments, and a second part that contains the
HTML content string itself.
Syntax: ASP Content Rotator Component Content Schedule File
%% [#Weight] [//Comments]
ContentString
Parameters: ASP Content Rotator Component Content Schedule File
ASP Content Rotator Component Content Schedule File Weight Parameter[0]
This optional parameter specifies a number between 0 and 10000 that indicates the relative
weight of the HTML content string. The probability of a particular content string being displayed
by the ContentRotator object can be expressed as the Weight of that content string divided by
the sum of Weight values for all entries in the Content Schedule file.
For example, if a Content Schedule file contained three content strings with respective weights of
1, 3, and 4, the Content Rotator displays the first content string one-eighth of the time, the second
string three-eighths of the time, and the third string half of the time.
A Weight of 0 will cause a content entry to be ignored.
Chili!Soft ASP 3.6 Product Documentation
476
If Weight is not specified, the default value is 1.
If the sum of all weight values exceeds 10000, an error will be generated when the schedule file is
accessed by a call to either the GetAllContent or ChooseContent methods.
ASP Content Rotator Component Content Schedule File Comments Parameter
This optional parameter contains comments about the entry. These comments are for
development use only and are not displayed to the user. If you require more than one line of
comments, you must start each additional comment line with a line delimiter (%%) followed by a
comment delimiter (//).
ASP Content Rotator Component Content Schedule File ContentString Parameter
The HTML content that the ContentRotator object displays. For example, you can present a line
of text, an image, or a sound.
ContentString may include one or more lines. The ContentRotator object treats everything
between blocks of double percent signs (%%) as a single HTML content string.
Examples: ASP Content Rotator Component Content Schedule File Parameters[0]
The following is an example of a Content Schedule file.
Note
Because the content strings can contain HTML tags, you can display any type of content
that can be represented with HTML, including text, images, and hyperlinks.
-------------content.txt-------------------%% // Because no value is set for Weight, the default value is 1.
Don’t run with scissors.
%% #2 // Content can be more that one line long
%% // Additional line of comments
%% // Yet another line of comments
<FONT FACE="ARIAL,HELVETICA" SIZE="2">
Let a
<H1>smile</H1>
be your umbrella.
</FONT>
%% #3 // This is our favorite image, so show it most often
<IMG SRC="/images/happy.gif">
%%
Chili!Soft ASP 3.6 Product Documentation
477
Here’s the <A HREF="secret.asp">secret link.</A>
ASP Content Rotator Component Methods
ASP Content Rotator Component ChooseContent Method[0]
The ChooseContent method retrieves an HTML content string from the Content Schedule file.
The method retrieves a new content string each time the script is run, such as when a user opens
or reloads a page.
Arguments: ASP Content Rotator Component ChooseContent Method
content-schedule-path
Specifies the location of the Content Schedule file.
This parameter can be specified either as a relative or virtual path. For example, if the Content
Schedule file, Content.txt, and the .asp file that called ChooseContent both resided in the
directory /MyApp/Tips/, where MyApp is a virtual directory on the server, then either the full
virtual path (/MyApp/Tips/Content.txt) or the relative path (Content.txt) could be specified for
content-schedule-path.
The ContentRotator object calls the Server.MapPath method to map the specified path to a
physical directory. For more information, see the Server Object reference pages.
Return Value: ASP Content Rotator Component ChooseContent Method
Returns an HTML content string from the Content Schedule file.
Examples: ASP Content Rotator Component ChooseContent Method
The following example gets a new tip from the content.txt file in the /Tips/ virtual directory.
<%
Set NextTip = Server.CreateObject("MSWC.ContentRotator")
NextTip.ChooseContent("/Tips/Content.txt")
%>
ASP Content Rotator Component GetAllContent Method
The GetAllContent method retrieves all of the HTML content strings from the Content Schedule
file and writes them directly to the Web page as a list with an <HR> tag after each entry.
This method is typically used during authoring, to proofread the Content Schedule file.
Arguments: ASP Content Rotator Component GetAllContent Method
content-schedule-path
Specifies the location of the Content Schedule file.
Chili!Soft ASP 3.6 Product Documentation
478
This parameter can be specified either as a relative or virtual path. For example, if the Content
Schedule file, Content.txt, and the .asp file that called ChooseContent both resided in the
directory /MyApp/Tips/, where MyApp is a virtual directory on the server, then either the full
virtual path (/MyApp/Tips/Content.txt) or the relative path (Content.txt) could be specified for
content-schedule-path.
The ContentRotator object calls the Server.MapPath method to map the specified path to a
physical directory. For more information, see the Server Object reference pages.
Remarks: ASP Content Rotator Component GetAllContent Method
The Content Rotator component uses the Response.Write method to write output directly to the
.asp page that called the GetAllContent method. For more information, see the Response object
topics.
Examples: ASP Content Rotator Component GetAllContent Method
The following example uses the GetAllContent method to display all of the entries in the
Content Schedule file.
<H1>Tips Stored in the Content Schedule File:</H1>
<%
Set Tips = Server.CreateObject("MSWC.ContentRotator")
Tips.GetAllContent("/Tips/Content.txt")
%>
The preceding example produces HTML output such as the following:
<H1>Tips Stored in the Content Schedule File:</H1>
<HR>
Don’t run with scissors.
<HR>
<FONT FACE="ARIAL,HELVETICA" SIZE="2">
Let a
<H1>smile</H1>
be your umbrella.
</FONT>
<HR>
<IMG SRC="/images/happy.gif">
<HR>
Here’s the <A HREF="secret.asp">secret link.</A>
<HR>
Chili!Soft ASP 3.6 Product Documentation
479
ASP Counters Component
The Counter component creates a Counters object that can create, store, increment, and retrieve
any number of individual counters.
A counter is a persistent value that contains an integer. You can manipulate a counter with the
Get, Increment, Set, and Remove methods of the Counters object. Once you create the counter,
it persists until you remove it.
Counters do not automatically increment on an event like a page hit. You must manually set or
increment counters using the Set and Increment methods.
Counters are not limited in scope. Once you create a counter, any page on your site can retrieve or
manipulate its value. For example, if you increment and display a counter named hits in a page
called Page1.asp, and you increment hits in another page called Page2.asp, both pages will
increment the same counter. If you hit Page1.asp, and increment hits to 34, hitting Page2.asp will
increment hits to 35. The next time you hit Page1.asp, hits will increment to 36.
All counters are stored in a single text file, counters.txt.
Only create one Counters object in your site. This single Counters object can create any number
of individual counters.
Registry Settings: ASP Counters Component
The Counters Component makes use of no registry settings.
Control Reference: ASP Counters Component
The Counters control is registered with the ProgId of "MSWC.Counters." Create the Counters
object one time on your site by adding the following to the Global.asa file:
<OBJECT
RUNAT=Server
SCOPE=Application
ID=Counter
PROGID="MSWC.Counters">
</OBJECT>
Properties: ASP Counters Component
None.
Methods: ASP Counters Component
•
Get
•
Increment
•
Remove
Chili!Soft ASP 3.6 Product Documentation
•
480
Set
ASP Counters Component Methods
ASP Counters Component Get Method
The Get method takes the name of a counter and returns the current value of the counter. If the
counter doesn’t exist, the method creates it and sets it to 0.
Arguments: ASP Counters Component Get Method
CounterName
A string containing the name of the counter.
Examples: ASP Counters Component Get Method
Display the value a counter with <%= Counters.Get(CounterName) %>. Assign the
value of the counter to a variable with <% countervar =
Counters.Get(CounterName) %>.
The following script displays the vote tally from a poll about favorite colors.
<%
If colornumber = "1" Then
Counters.Increment("greencounter")
Else
If colornumber = "2" Then
Counters.Increment("bluecounter")
Else
If colornumber = "0" Then
Counters.Increment("redcounter")
End If
End If
End If
%>
<P>Current vote tally:
<P>red: <% =Counters.Get("redcounter") %>
<P>green: <% = Counters.Get("greencounter") %>
<P>blue: <% = Counters.Get("bluecounter") %>
ASP Counters Component Increment Method
Chili!Soft ASP 3.6 Product Documentation
481
The Increment method takes the name of a counter, adds 1 to the current value of the counter,
and returns the counter's new value. If the counter doesn't exist, the method creates it and sets its
value to 1.
Arguments: ASP Counters Component Increment Method
CounterName
A string containing the name of the counter.
Examples: ASP Counters Component Increment Method
Increment the value of a counter with <% Counters.Increment(CounterName) %>.
Increment and display the value of a counter with <%=
Counters.Increment(CounterName) %>.
To retrieve the value of a counter, use Counters.Get. To set a counter to a specific value, use
Counters.Set.
The following code implements a one-line page-hit counter.
<P>There have been <%= Counters.Increment("hits") %> visits to this
Web page. </P>
In this example, Counters.Increment increases the counter by one each time the client requests
the page from the server.
ASP Counters Component Remove Method
The Remove method takes the name of a counter, removes the counter from the Counters object,
and deletes the counter from the Counters.txt file.
Arguments: ASP Counters Component Remove Method
CounterName
A string containing the name of the counter.
Examples: ASP Counters Component Remove Method
The following code removes the counter hitscounter from the counters.txt file.
<% Counters.Remove(hitscounter) %>
ASP Counters Component Set Method
The Set method takes the name of a counter and an integer, sets the counter to the value of the
integer, and returns the new value. If the counter doesn’t exist, Counters.Set creates it and sets it
to the value of the integer.
Arguments: ASP Counters Component Set Method
CounterName
A string containing the name of the counter.
int
The new integer value for CounterName.
Examples: ASP Counters Component Set Method
Chili!Soft ASP 3.6 Product Documentation
482
The following code resets the hit counter pageHits to 0:
<% Counters.Set(pageHits, 0) %>
ASP MyInfo Component
The MyInfo component creates a MyInfo object that keeps track of personal information, such as
the site administrator's name, address, and display choices. Typically, the administrator types this
information directly into the Web server interface. However, you can set the values of the
properties directly by using a script in an ASP page.
Note
Chili!Soft ASP does not implement the default properties available under Windows NT
Personal Web Services.
Each property of a MyInfo object returns a string. If a MyInfo property has no value set, the
property returns an empty string.
Create new MyInfo properties for values that remain consistent throughout a site. You can create
new MyInfo properties by simply assigning a string value to them. The following example
creates the new properties DogName and DogBreed. These new properties are stored persistently
along with the other MyInfo properties.
<%
MyInfo.DogName = "Snoopy"
MyInfo.DogBreed = "Beagle"
%>
The values of MyInfo properties are stored in the text file, libmyinfo.ini. On Linux systems, this
file is located in [C-ASP_INSTALL_DIR]/lib-chilicom. On UNIX-based systems, this file is
located in [C-ASP_INSTALL_DIR]/lib-mainwin, where [C-ASP_INSTALL_DIR] is the
complete directory path of the Chili!Soft ASP installation directory.
The Chili!Soft ASP implementation of the MyInfo component is compatible with the
libmyinfo.ini files produced by the Microsoft implementation. However, Microsoft implements
libmyinfo.ini as an XML file, while Chili!Soft ASP does not.
Registry Settings: ASP MyInfo Component
The control makes use of no registry settings.
Control Reference: ASP MyInfo Component
The MyInfo component is registered with the ProgID of "MSWC.MyInfo."
The following code in the global.asa file creates one instance of the MyInfo object. In this
example, the object is given Session scope, but a MyInfo object could also be given Application
scope:
<OBJECT
Chili!Soft ASP 3.6 Product Documentation
483
RUNAT=Server
SCOPE=Session
ID=MyInfo
PROGID="MSWC.MyInfo">
</OBJECT>
Properties: ASP MyInfo Component
The Chili!Soft implementation does not implement the default properties available under
Windows NT Personal Web Services. You create your own properties as described in this topic.
Methods: ASP MyInfo Component
None.
ASP Tools Component
The Tools component creates a Tools object that provides utilities that enable you to easily add
sophisticated functionality to your Web pages.
Registry Settings: ASP Tools Component
The control makes use of no registry settings.
Control Reference: ASP Tools Component
The Tools component is registered with the ProgId of "MSWC.Tools." The following VBScript
excerpt shows creating an instance of the control.
Set Tools = Server.CreateObject( "MSWC.Tools" )
The Tools component exposes the following properties and methods.
Properties: ASP Tools Component
None.
Methods: ASP Tools Component
•
FileExists
•
Owner
•
ProcessForm
•
PluginExists
•
Random
Chili!Soft ASP 3.6 Product Documentation
484
ASP Tools Component Methods
ASP Tools Component FileExists Method
The FileExists method checks the existence of a file. It returns –TRUE if the specified URL
exists within a published directory. If the file does not exist, it returns FALSE.
Arguments: ASP Tools Component FileExists Method
URL
A string that specifies the relative URL of the file you are
checking.
Remarks: ASP Tools Component FileExists Method
FileExists only checks the existence of files published on your site. Therefore, it takes a relative
URL rather than an absolute URL.
Examples: ASP Tools Component FileExists Method
The following example demonstrates using the FileExists property to create a link if a particular
file is present.
<%If Tools.FileExists("ie_animated.gif") then %>
<p> <a HREF="/isapi/gomscom.asp?TARGET=/ie/"><img
src="ie_animated.gif"></a>
<% End If %>
ASP Tools Component Owner Method
The Chili!Soft ASP implementation of this method always returns 0.
ASP Tools Component PluginExists Method
The Chili!Soft ASP implementation of this method always returns 0.
ASP Tools Component ProcessForm Method
The ProcessForm method processes the contents of a form that has been submitted by a visitor to
the Web site.
Arguments: ASP Tools Component ProcessForm Method
OutputFileURL
A string containing the relative URL of the file to which the
processed data is written.
TemplateURL
A string containing the relative URL of the file that contains
the template, or instructions, for processing the data.
InsertionPoint
An optional parameter indicating where in the output file to
insert the process data. This parameter has not been
implemented. If you include a value for this parameter it will
be ignored.
Chili!Soft ASP 3.6 Product Documentation
485
Remarks: ASP Tools Component ProcessForm Method
The template files can contain ASP scripts. A script between <% and %> delimiters is treated just
like other text in the template and copied into the output file. If the output file is an ASP
document, the script will run when the output file is accessed. Scripts in template files can also be
put between special <%% and %%> delimiters which cause the script to execute while
Tools.ProcessForm is executing. Since these scripts are executed before the template data is
saved in the output file, the results get saved in the output file, usually as standard text.
The scripts can use any of the ASP intrinsics for the page containing the script executing the
ProcessForm method except for the Response objects. Instead, the miniscripts have their own
Response objects with implementations of Write and BinaryWrite that write to the output file
instead of the Web server output stream.
If the specified output file does not exist, the server creates it.
If the InsertionPoint parameter does not exist, Tools.ProcessForm replaces the entire output file.
If the InsertionPoint parameter exists, and does not begin with an asterisk (*),
Tools.ProcessForm finds the InsertionPoint string in the output file and inserts the data
immediately after it. If the InsertionPoint string begins with an asterisk (*), Tools.ProcessForm
finds the InsertionPoint string in the output file and inserts the data immediately before it. If the
InsertionPoint string exists, but is not found in the output file, the data is appended to the end of
the file.
Examples: ASP Tools Component ProcessForm Method
The following code demonstrates calling an .asp file to process a form.
<%
Tools.processform("/$Received
Messages/default.asp","MessageInsert.process","<SPAN>*")
%>
ASP Tools Component Random Method
The Random method returns an integer between –32768 to 32767.
Arguments: ASP Tools Component Random Method
None.
Remarks: ASP Tools Component Random Method
This method is similar to the Rnd function, but returns an integer.
To get a positive random integer, use the Abs function.
To get a random integer below a specific value, use the Mod function.
Examples: ASP Tools Component Random Method
Chili!Soft ASP 3.6 Product Documentation
486
<% = Tools.Random %> will display a random integer between –32768 to
32767. For example, -13067.
<% = ( Abs( Tools.Random ) ) %> will display a positive random
integer. For example, 23054.
<% = ( Abs( Tools.Random ) ) Mod 100 %> will display a random
integer between 0 and 99. For example, 63.
Chili!Soft ASP 3.6 Product Documentation
487
Chilli!Beans Component Reference
The Chili!Beans ActiveX control is a wrapper that enables Java objects to be used by Component
Object Model (COM) controllers such as ActiveX scripting engines or VBScript. The control is
designed to work with any Java Virtual Machine (JVM) that implements the Java Native Interface
(JNI) specification, such as JDK 1.1.6 or JDK 1.2.
Notes
When using Chili!Beans with Chili!Soft ASP 3.6 for Sun Solaris, you must use the JVM
Native Threads.
Chili!Beans is not available for Cobalt systems or on the Windows NT version of
Chili!Soft ASP.
This section provides the following Chili!Beans reference information:
•
Using Null Objects with Chili!Beans
•
Iterating a Collection with Chili!Beans
•
Accessing Methods and Fields with Chili!Beans
•
Chili!Beans Environment Settings
•
Limitations of Chili!Beans Objects
•
Constructing Java Objects with Chili!Beans
Using Null Objects with Chili!Beans
When a Chili!Beans wrapped Java method returns a Null object, the Null object is translated to
the special value Nothing when returned to the ASP script. If the special value Nothing is passed
from the ASP script to a Chili!Bean, it is converted to a Null object before being passed to the
Java method.
Iterating a Collection with Chili!Beans
If the Java object underlying a Chili!Beans control implements the java .util.Enumeration
interface it will function like a COM Collection class, and you can use the For…Each…Next
statement to iterate the Java object.
Accessing Methods and Fields with Chili!Beans
All public methods of a class are accessible from their Chili!Beans wrapper. If a class has
multiple methods with the same name, the control will resolve the correct method at runtime
based on the arguments passed. In some cases the mappings of Variant data types in client
scripts to Java data types can result in incorrect resolution between methods with similar
signatures. The Chili!Beans control does not distinguish between methods or fields whose names
differ only by case.
488
Chili!Soft ASP 3.6 Product Documentation
Uncaught exceptions thrown by Java method calls are caught by the control and reported to the
controller as COM exceptions whose Description field is the toString() value of the Java
Exception object thrown. If the CB_STACKTRACE environment variable is set to 1, a full stack
trace for the exception is included in the description field. With Chili!Soft ASP as the controller,
this string is reported as part of the runtime error text and will appear in the browser.
Chili!Beans Environment Settings
There are a number of environment settings that can aid in debugging applications that make use
of Chili!Beans and can improve overall Java performance. For Chili!Beans to use these values,
follow these instructions:
On UNIX systems, the environment settings must be set in the shell running caspd. The usual
place to set them is in javasetup.sh which is sourced by the startup script, startcaspd.
On Windows NT, the environment settings must be set as Windows NT system variables.
Environment Variable
Default Value
Function
CB_CHECKSOURCE
0 (False)
VM initialization checkSource argument
CB_VERIFYMODE
1 (True)
VM initialization verifyMode argument
CB_VERBOSE
0 (False)
VM initialization verbose argument
CB_ENABLECLASSGC
1 (True)
VM initialization enableClassGC argument
CB_ENABLEVERBOSEGC
0 (False)
VM initialization enableVerboseGC argument
CB_DISABLEASYNCGC
0 (False)
VM initialization disableAsyncGC argument
CB_NATIVESTACKSIZE
0x20000
VM initialization nativeStackSize argument
CB_JAVASTACKSIZE
0x64000
VM initialization javaStackSize argument
CB_MINHEAPSIZE
0x400000
VM initialization minHeapSize argument
CB_MAXHEAPSIZE
0x1000000
VM initialization maxHeapSize argument
CB_JVMPATH
UNIX:
libjava.so
Path to shared library containing JNI entry
points. Directory must be on UNIX library path
or NT system path.
NT: java .dll or
jvm .dll
CB_LOGPATH
""
Full path to (writable) logfile. Logging takes
place only if it is set. Do not set except for
debugging purposes.
CB_STACKTRACE
0 (False)
Determines whether full JVM stack trace is
displayed as the textual part of every COM error
message.
CB_BOOST
0 (False)
All methods on each argument are synchronized
unless set to 1.
Chili!Soft ASP 3.6 Product Documentation
489
Limitations of Chili!Beans Objects
The following limitations apply to Chili!Beans objects:
•
A Chili!Beans object is accessible to all threads in a Chili!Soft ASP application, and is
thread-safe if the underlying Java class is thread-safe. The Chili!Beans object is marked
in the registry with ThreadingModel=both; this means that Chili!Beans objects
stored as application or session variables will be accessed from multiple threads and will
certainly fail if their underlying Java code is not thread-safe.
•
There is no support for multiple-dimension arrays as either arguments or return values.
Constructing Java Objects with Chili!Beans
The Chili!Beans control is used in client scripts exactly like the Microsoft implementation of
COM wrappers for Java objects with the Microsoft JVM for Windows NT .
An instance of any Java class located on the path in the local CLASSPATH environment variable
can be constructed, any public methods of the resulting object can be called, and any of its public
fields can be accessed.
There are three ways to create a Java object by using Chili!Beans:
•
Accessing a Java Class via Chili!Beans
•
Registering a Java Class as a COM Component on Linux and UNIX
•
Returning a Java Class From a Method Call or Field Access
Accessing a Java Class via Chili!Beans
You can use the Chili!Beans object Construct method to create instances of Chili!Beans. The
first argument is the fully qualified name of the class to be instantiated and the remaining
arguments are the arguments to be passed to the desired constructor for that class. For example, if
the package Database contains Table .class, the following script will create a Table object:
Set factory = Server.CreateObject("Chili.Beans")
set table = factory.Construct "Database/Table", "Employees",
CLng(100)
This will create an object named "table," using the constructor whose signature is
constructor(String, Int)
Notes
If the class name cannot be found on the CLASSPATH or if there is no public constructor
whose signature matches the arguments passed to Construct, a runtime error occurs in the
client script.
In order to use a Java class with Chili!Soft ASP, the .class file must exist in a directory
that is listed in the Java CLASSPATH environment variable, and it must be registered
with Chili!Soft ASP as described in "Registering a Java Class as a COM Component on
Linux and UNIX" in this chapter.
Chili!Soft ASP 3.6 Product Documentation
490
Registering a Java Class as a COM Component on Linux and UNIX
The chregclass tool included with Chili!Soft ASP 3.6 enables you to register a Java class as a
COM component on Linux and UNIX. You register a Java class by using the chregclass tool to
create a registry entry that maps a given ProgID to the Java class. The chregclass tool is similar to
the javareg tool provided for the Microsoft JVM.
Notes
In order to register a Java class to use with Chili!Soft ASP, the .class file must exist in a
directory that is listed in the Java CLASSPATH environment variable.
Any class registered by using chregclass must have a public default constructor to
instantiate the class. This applies to all chregclass calls.
To register a Java class as a COM component
1. Log in as root and change directories to the Chili!Soft ASP 3.6 installation directory.
2. Stop the ASP Server, as described in "Stopping and Restarting the ASP Server" in "Chapter
3: Managing Chili!Soft ASP."
3. Map the ProgID to the Java class by running the following command:
chregclass [–f] [ProgID] [JAVA_CLASS]
where [ProgID] is the Prog ID you want to map and [JAVA_CLASS] is the name of the
Java class you want to register. [JAVA_CLASS] should not include the .class extension. If it
does, the mapping will not work.
4. Restart the ASP Server, as described in "Stopping and Restarting the ASP Server" in
"Chapter 3: Managing Chili!Soft ASP."
For example, to register the Table .class in the package Database on the CLASSPATH, use the
following command:
chregclass Db.Table Database/Table
After running this command, you can then construct a Table object in a client script as follows:
set table = Server.CreateObject("Db.Table")
Returning a Java Class from a Method Call or Field Access
A Java object returned from a Java method call or field access in a client script is automatically
wrapped in its own Chili!Beans wrapper. For example, the classes Table and Record are defined
as:
//Table.java
package Database ;
public class Table {
public Table(String name, in initialSize) {...};
Chili!Soft ASP 3.6 Product Documentation
491
public int numRecords() {...};
public Record getEmployee(int employeeNumber)
{...}
...
}
//Record.java
package Database ;
public class Record {
public Record() {...};
public String m_LastName ;
public String m_FirstName ;
...
}
The following ASP script will print out the names of the employees in table:
set t = Server.CreateObject("Chili.Beans")
t.ClassName = "Database/Table"
t.Construct "Employees", 100
for I = 0 to t.numRecords – 1
set record = t .getEmployee(I)
Response.Write(record.m_FirstName & " " _
& record .m_LastName & "<br>")
next
The Java objects returned by the getEmployee calls on the Table object are automatically given
Chili!Beans wrappers and their methods and fields are available even though they have not been
constructed with the CreateObject method.
Chili!Soft ASP 3.6 Product Documentation
492
Component Programmer's Reference
On Windows NT and UNIX systems, Chili!Soft ASP provides support for custom server
components, which can be useful when your Web applications require complex business logic.
The application developer may find it more efficient to encapsulate this business logic in a
custom server component written in an advanced language like C++ or Java, rather than trying to
implement it with script. Chili!Soft ASP uses COM (Component Object Model) as the standard
interface for creating custom components.
Note
At this time there is no compiler or API for third-party COM objects available for Linux.
On Windows NT, Chili!Soft ASP server components can be written in any language that supports
COM, including Visual Basic, C++, and Java. On UNIX, Chili!Soft ASP server components can
be written in either Java or C++. If you wish to develop your components in Java, Chili!Beans
shields you from many of the details of COM. For more information, see "Chili!Beans
Component Reference" in this chapter.
If you want to develop components using C++, this section is for you. On UNIX systems,
Chili!Soft ASP provides an implementation of COM from MainSoft. To develop C++ COM
components on UNIX, you need the MainSoft tools for developing COM components, available
from MainSoft. The following books provide reference information about developing COM
components:
•
Inside COM, by Dale Rogerson, published by Microsoft Press
•
Understanding ActiveX and OLE, by David Chappell, published by Microsoft Press
If you are developing for UNIX, the MainSoft tools also have extensive documentation for
creating COM components.
This section provides the following reference information about components:
•
Scope and Threading
•
C++ Interfaces Reference
•
IApplicationObject Interface
•
IReadCookie Interface
•
IRequest Interface
•
IRequestDictionary Interface
•
IResponse Interface
•
IScriptingContext Interface
•
IServer Interface
•
ISessionObject Interface
•
IStringList Interface
Chili!Soft ASP 3.6 Product Documentation
•
IVariantDictionary Interface
•
IWriteCookie Interface
•
COM on UNIX
493
Scope and Threading
COM objects used in ASP pages can have Page, Session, or Application scope depending on how
and when they are created. Objects created on ASP pages will have Page scope by default; they
are created when the page is processed, and are released when page processing is complete.
Objects with Page scope are only available on the page where they are created.
Objects given Session scope or Application scope in the global.asa file or on an ASP page are
then available to other ASP pages. Objects that are given Session or Application scope using the
Server.CreateObject method must be marked as both apartment and free-threaded. It is possible
to create single, apartment, and free-threaded objects in the global.asa file using the extended
<OBJECT> tag syntax, but doing so will constrain the Chili!Soft ASP server to a single thread,
significantly impacting performance. For more information, see "Choosing a Threading Mode" in
"Chapter 3: Managing Chili!Soft ASP."
For maximum flexibility, all COM objects used on ASP pages should be marked as "Both," and
use both the apartment and free-threaded models.
C++ Interfaces Reference
Chili!Soft ASP implements interfaces that allow your components to access the properties and
methods of built-in ASP objects. You component can use these object interfaces to access the
properties, methods, and collections of the built-in objects.
Chili!Soft ASP does not currently support the IObjectContext interface required to access
Microsoft Transaction Server methods. The IScriptingContext should be used to access the
built-in object interfaces.
The following table lists the built-in object interfaces:
Interface
Description
IApplicationObje
ct
Calls the methods and properties of the Application object.
IReadCookie
Retrieves the values stored in the read-only Cookies collection.
IRequest
Calls the methods and properties of the Request object.
IRequestDictiona
ry
Indexes the collections of the IRequest interface.
IResponse
Calls the methods and properties of the Response object.
IScriptingContext
Returns a pointer to the interface on one of the built-in objects:
IApplicationObject, IRequest, IResponse, IServer, or
ISessionObject.
Chili!Soft ASP 3.6 Product Documentation
IServer
Calls the methods and properties of the Server object.
ISessionObject
Calls the methods and properties of the Session object.
IStringList
Retrieves the values stored in a string list, used in the QueryString,
Form or ServerVariables collections.
IVariantDictionar
y
Retrieves the items stored in the Application and Session Contents
and StaticObjects collections.
IWriteCookie
Sets the values and attributes in the write-only Cookies collection.
494
To use IScriptingContext and object interfaces in a C++ component, you must include the
header file asptlb.h.
For more information, see "ASP Built-in Objects Reference" in this chapter.
COM on UNIX
Chili!Soft ASP uses an implementation of COM for UNIX called MainWin, from MainSoft
Corporation. A run-time version of MainWin is installed with Chili!Soft ASP. In order to develop
C++ COM components for use with Chili!Soft ASP, you need to obtain the MainSoft COM
development tools, available from MainSoft. If you are developing your components in Java, you
do not need the MainSoft tools and can use Chili!Beans instead.
If you plan on building or porting custom components that use the Microsoft Foundation Classes
(MFC), you will need to have the MFC elements of the MainWin COM environment installed.
These can be installed with the MainWin COM development tools.
Note
The use of MFC requires an X server to be configured and running. If you answered Yes
to the use of MFC during Chili!Soft ASP installation, a simple X server was installed for
you. If you need further assistance, contact Chili!Soft.
COM on UNIX provides an implementation of the Windows registry. There are two utilities
available for working with the Registry, one for editing the Registry and one for registering COM
components.
Editing the Registry (chregedit)
Chili!Soft provides a user-friendly version of the MainSoft tool for editing the registry. To run
this tool, connect to the machine running Chili!Soft ASP using an X server (such as
Hummingbird Exceed). To edit the registry, run the following command from the Chili!Soft ASP
installation directory:
# chregedit
This will launch an X application that simulates the Windows Registry Editor tool.
Chili!Soft ASP 3.6 Product Documentation
495
Note
You should only edit the Chili!Soft ASP Registry with the Chili!Soft ASP engine
stopped. If you make registry changes while Chili!Soft ASP is running, the changes will
not take effect and will not be applied to the registry.
Registering Components (chregsvr)
Chili!Soft provides a user-friendly version of the MainSoft tool for registering a COM
component. To register a component, run the following command from the Chili!Soft ASP
installation directory:
# chregsvr /path/to/component.so
After you run this command, a message indicates whether or not the component registration was
successful.
For information about registering Java classes as COM components, see "Registering a Java
Class as a COM Component on Linux and UNIX" in "Chili!Beans Component Reference" in this
chapter.
Note
You should only register new components with the Chili!Soft ASP engine stopped. If you
make registry changes while Chili!Soft ASP is running, the changes will not take effect
and will not be applied to the registry.
IApplicationObject Interface
The IApplicationObject interface exposes the methods of the Application object.
IApplicationObject::get_Conten
ts
Retrieves the Contents collection
IApplicationObject::get_Static
Objects
Retrieves the StaticObjects collection.
IApplicationObject::get_Value
Retrieves the value of a variable stored in the
Application object.
IApplicationObject::Lock
Prevents other clients from accessing the variables
stored in the Application object until
IApplication::Unlock is called.
IApplicationObject::putref_Val
ue
Stores a variable in the Application object by reference.
IApplicationObject::put_Value
Stores a variable in the Application object by value.
IApplicationObject::UnLock
Releases the lock that was created by the
IApplication::Lock method.
IApplication also supports all IUnknown and IDispatch interface methods.
Chili!Soft ASP 3.6 Product Documentation
496
IApplicationObject::get_Contents
The IApplicationObject::get_Contents method retrieves the Application.Contents collection.
HRESULT get_Contents(
IVariantDictionary **ppProperties
)
Parameters: IApplicationObject::get_Contents
ppProperties
Points to an IVariantDictionary interface pointer that receives the Contents collection.
Remarks: IApplicationObject::get_Contents
The Application.Contents collection contains all variables and objects that have been given
application scope with the Server.CreateObject command. You can iterate through the
Contents collection with the IVariantDictionary::get_NewEnum method. You can also retrieve
a specific item with the IVariantDictionary::get_Item method.
IApplicationObject::get_StaticObjects
The IApplicationObject::get_StaticObjects method retrieves the Appliction.StaticObjects
collection.
HRESULT get_StaticObjects(
IVariantDictionary **ppProperties
);
Parameters: IApplicationObject::get_StaticObjects
ppProperties
Points to an IVariantDictionary interface pointer that receives the StaticObjects collection.
Remarks: IApplicationObject::get_StaticObjects
You can iterate through the StaticObjects collection with the
IVariantDictionary::get_NewEnum method. You can also retrieve a specific item with the
IVariantDictionary::get_Item method.
IApplicationObject::get_Value
The IApplicationObject::get_Value method retrieves the value of a variable stored in the
Application object.
HRESULT get_Value
BSTR bstrValue,
VARIANT * pvar
Chili!Soft ASP 3.6 Product Documentation
497
)
Parameters: IApplicationObject::get_Value
bstrValue
A binary string that contains the name of the variable to retrieve.
pvar
Points to a variant that holds the value for the variable specified in bstrValue.
Remarks: IApplicationObject::get_Value
You can use this method to access variables that have been given application scope.
IApplicationObject::Lock
The IApplicationObject::Lock method prevents other clients from accessing the variables stored
in the Application object until the IApplicationObject::UnLock method has been called.
HRESULT Lock(VOID);
IApplicationObject::putref_Value
The IApplicationObject::putref_Value method stores an object in the Application object.
Equivalent to the IApplicationObject::put_Value method for non-objects.
HRESULT putref_Value(
BSTR bstrValue,
VARIANT var
);
Parameters: IApplicationObject::putref_Value
bstrValue
A binary string that contains the name of the object to store.
var
A variant that contains the reference to the object.
Remarks: IApplicationObject::putref_Value
You can use this method to create a reference to an object. Giving some object application scope
will have a negative impact on server performance. See Scope and Threading for more
information.
IApplicationObject::put_Value
The IApplicationObject::put_Value method stores a variant in the Application object.
HRESULT put_Value(
Chili!Soft ASP 3.6 Product Documentation
498
BSTR bstrValue,
VARIANT var
);
Parameters: IApplicationObject::put_Value
bstrValue
A binary name that contains the name of the variable.
var
A variant that contains the variable value.
Remarks: IApplicationObject::put_Value
If the variant being stored is an object, Chili!Soft ASP will attempt to store the default value of
that object into the application. If Chili!Soft ASP cannot get the default value, the call will fail.
IApplicationObject::UnLock
The IApplicationObject::UnLock method releases a variable that was locked by the
IApplicationObject::Lock method.
HRESULT UnLock(VOID)
IReadCookie Interface
You can use the IReadCookie interface to access the objet returned from the read-only Cookies
collection. Calling IRequestDictionary::get_Item on the read-only Cookies collection will
always return an object that implements the IReadCookie interface.
IReadCookie::get_HasKeys
Retrieves a Boolean indicating whether the cookie has
keys.
IReadCookie::get_Item
Retrieves the specified item from a cookie dictionary.
IReadCookie::get_NewEnu
m
Retrieves an enumerator for the Cookies collection.
IReadCookie and IWriteCookie are interfaces for the same object. If you have an IReadCookie
pointer, you can use the IUnknown::QueryInterface method on an IWriteCookie pointer.
IReadCookie::get_HasKeys
The IReadCookie::get_HasKeys method returns a Boolean value which indicates whether or not
the cookie has keys.
HRESULT get_HasKeys(
VARIANT_BOOL * pfHasKeys
);
Parameters: IReadCookie::get_HasKeys
Chili!Soft ASP 3.6 Product Documentation
499
pfHasKeys
Points to a Boolean that indicates whether or not the cookie has keys.
Remarks: IReadCookie::get_HasKeys
If the cookie has been implemented as a collection, this method will return TRUE. If the cookie
has keys, use the IReadCookie::get_NewEnum method to retrieve an enumerator for iterating
through the collection.
IReadCookie::get_Item
The IReadCookie::get_Item method retrieves the specified item from a Cookie object.
HRESULT get_Item(
VARIANT Var,
VARIANT * pVariantReturn
);
Parameters: IReadCookie::get_Item
Var
A variant that contains the name of the item in the collection.
pVariantReturn
Points to a variant that receives the item value.
Remarks: IReadCookie::get_Item
If Var is a string, the cookie is assumed to be a dictionary cookie and Var is treated as the key. If
Var is a variant with type VT_ERROR and error code DISP_E_PARAMNOTFOUND, then the
cookie is assumed to be a simple cookie and the primary value is returned. (If the cookie is a
dictionary, the sequence of key/value pairs are URL-encoded and returned.)
If a dictionary lookup is performed and the item is not found, then pVariantReturn returns
VT_EMPTY. Otherwise a VT_BSTR is always returned.
IReadCookie::get_NewEnum
The IReadCookie::get_NewEnum method returns an enumerator interface which can be used to
iterate through the items in a cookie.
HRESULT get_NewEnum(
IUnknown ** ppEnumReturn
);
Parameters: IReadCookie::get_NewEnum
ppEnumReturn
Points to an IUnknown interface pointer that receives the enumerator.
Chili!Soft ASP 3.6 Product Documentation
500
Remarks: IReadCookie::get_NewEnum
If a cookie has been implemented as a collection, you can use this method to iterate through all
the members of its collection.
IRequest Interface
The IRequest interface exposes methods that access the collections of the Request object.
IRequest::BinaryRead
Retrieves the current request and places it into a safe
array.
IRequest::get_Cookies
Retrieves the Cookies collection.
IRequest::get_Form
Retrieves the Form collection.
IRequest::get_Item
Retrieves an item from the Request collection by
looking for the first match in the QueryString,
Form, Cookies, ClientCertificate, and
ServerVariables collections.
IRequest::get_QueryString
Retrieves the QueryString collection.
IRequest::get_ServerVariables
Retrieves the ServerVariables collection.
IRequest::get_TotalBytes
Returns the size of the current request in bytes.
The IRequest interface also supports the IUnknown and IDispatch interface methods.
The Chili!Soft ASP IRequest interface does not currently support the IClientCertificate
collection.
IRequest::BinaryRead
The IRequest::BinaryRead method retrieves the current Request object in a safe array.
HRESULT BinaryRead(
VARIANT *pvarCountToRead,
VARIANT *pvarReturn
);
Parameters: IRequest::BinaryRead
pvarCountToRead
Points to a variant that contains an integer value of the bytes to read.
pvarReturn
Points to a safe array that contains the bytes that were read by an HTTP POST.
Remarks: IRequest::BinaryRead
A safe array is an array that contains information about the number of dimensions and the upper
and lower bounds of the dimensions.
Chili!Soft ASP 3.6 Product Documentation
501
IRequest::get_Cookies
The IRequest::get_Cookies method retrieves the Cookies collection of the Request object.
HRESULT get_Cookies(
IRequestDictionary ** ppDictReturn
);
Parameters: IRequest::get_Cookies
ppDictReturn
Points to an IRequestDictionary interface pointer that receives the Cookies collection.
Remarks: IRequest::get_Cookies
You can iterate through the Cookies collection with the IRequestDictionary::get_NewEnum
method or retrieve a specific cookie with the IRequestDictionary::get_Item method.
IRequest::get_Form
The IRequest::get_Form method retrieves the Form collection of the Request object.
HRESULT get_Form(
IRequestDictionary ** ppDictReturn
);
Parameters: IRequest::get_Form
ppDictReturn
Points to an IRequestDictionary interface that receives the Form collection.
Remarks: IRequest::get_Form
You can iterate through the Form collection with the IRequestDictionary::get_NewEnum
method or retrieve a specific cookie with the IRequestDictionary::get_Item method.
IRequest::get_Item
The IRequest::get_Item method retrieves a pointer to an interface pointer of the first item in the
Request object’s collections that contains the specified string.
HRESULT get_Item(
BSTR bstrVar,
IDispatch ** ppObjReturn
);
Parameters: IRequest::get_Item
bstrVar
A binary string that contains the name of the item to retrieve.
Chili!Soft ASP 3.6 Product Documentation
502
ppObjReturn
Points to an IDispatch pointer that receives the object that contains the value specified in
bstrVar.
Remarks: IRequest::get_Item
The Request object’s collections are searched in the following order: QueryString, Form,
Cookies, ClientCertificate, and ServerVariables.
If the object containing bstrVar is found in the QueryString, Form, or ServerVariables
collection, then ppObjReturn points to an object that supports the IStringList interface.
If the object is found in the Cookies collection, ppObjReturn points to an object that supports the
IReadCookie interface.
IRequest::get_QueryString
The IRequest::get_QueryString method retrieves the QueryString collection of the Request
object.
HRESULT get_QueryString(
IRequestDictionary ** ppDictReturn
);
Parameters: IRequest::get_QueryString
ppDictReturn
Points to an IRequestDictionary interface pointer that receives the QueryString collection.
Remarks: IRequest::get_QueryString
You can iterate through the QueryString collection with the
IRequestDictionary::get_NewEnum method or retrieve a specific cookie with the
IRequestDictionary::get_Item method.
IRequest::get_ServerVariables
The IRequest::get_ServerVariables method retrieves the QueryString collection of the
Request object.
HRESULT get_ServerVariables(
IRequestDictionary ** ppDictReturn
);
Parameters: IRequest::get_ServerVariables
ppDictReturn
Points to an IRequestDictionary interface pointer that receives the ServerVariables collection.
Remarks: IRequest::get_ServerVariables
Chili!Soft ASP 3.6 Product Documentation
You can iterate through the ServerVariables collection with the
IRequestDictionary::get_NewEnum method or retrieve a specific cookie with the
IRequestDictionary::get_Item method.
IRequest::get_TotalBytes
The IRequest::get_TotalBytes method retrieves the size of the current request in bytes.
get_TotalBytes(
LONG pcbTotal
);
Parameters: IRequest::get_TotalBytes
pcbTotal
Points to a long integer that contains the size of the current request in bytes.
IRequestDictionary Interface
The IRequestDictionary interface is a general interface wrapper that can wrap the following
collections:
•
Request.Cookies
•
Request.Form
•
Request.QueryString
•
Request.ServerVariables
•
Response.Cookies
The behavior of the IRequestDictionary interface depends on how the Request or Response
object implements the IRequestDictionary::get_Item method.
IRequestDictionary::get_Coun
t
Retrieves the number of items in a dictionary.
IRequestDictionary::get_Item
Retrieves the specified item from a dictionary.
IRequestDictionary::get_Key
Retrieves the identifier of the item to be retrieved from
the collection.
IRequestDictionary::get_New
Enum
Retrieves an enumerator for the collection.
The IRequestDictionary interface also supports the IUnknown and IDispatch interface
methods.
IRequestDictionary::get_Count
The IRequestDictionary::get_Count method determines the total number of items in a
collection.
503
Chili!Soft ASP 3.6 Product Documentation
504
HRESULT STDMETHODCALLTYPE get_Count(
int * cStrRet
);
Return Values: IRequestDictionary::get_Count
cStrRet
Points to an integer that contains the total number of items in a collection.
IRequestDictionary::get_Item
The IRequestDictionary::get_Item method retrieves the specified item from a Request object
dictionary
HRESULT get_Item(
VARIANT Var,
VARIANT * pVariantReturn
);
Parameters: IRequestDictionary::get_Item
Var
A variant that contains the name of the item in the collection.
pVariantReturn
Points to a variant that receives the item.
Remarks: IRequestDictionary::get_Item
Objects can specify that one or more variant parameters are optional. This is done by passing the
parameter with the type set to VT_ERROR and a value of DISP_E_PARAMNOTFOUND. For
example, if you want to do this with the Var parameter, the value it returns will depend on the
object’s implementation of the IRequestDictionary interface; the QueryString object will return
the entire query string, for example.
•
For Request.QueryString, pVariantReturn contains the unparsed query string data.
•
For Request.Form, pVariantReturn contains the unparsed form data.
•
For Request.Cookies, pVariantReturn contains a URL-encoded list of the cookies.
•
Request.ServerVariables and Response.Cookies do not accept an optional variant
parameter, and will raise a COM exception if Var is DISP_E_PARAMNOTFOUND.
If Var is not an optional parameter then it must be a VT_BSTR or a VT_DISPATCH pointer with
a default value that can be converted to a BSTR. In this case, the BSTR value of Var is looked up
in the appropriate dictionary, and the value of Var is returned. If Var is not in the dictionary, then
a variant equal to VT_EMPTY is returned if the IRequestDictionary is covering one of the
Request object’s collections. If the IRequestDictionary pointer is the Response.Cookies
collection, a new cookie with the name of Var is created, and that cookie is returned. If Var is not
Chili!Soft ASP 3.6 Product Documentation
505
a BSTR (and not DISP_E_PARAMNOTFOUND), then the get_Item method will raise an OLE
exception.
IRequestDictionary::get_Key
The IRequestDictionary::get_Key method returns the unique identifier for items in the Cookies,
Form and QueryString collections.
HRESULT STDMETHODCALLTYPE get_Item(
VARIANT VarKey,
VARIANT * pVar
);
Parameters: IRequestDictionary::get_Key
VarKey
Identifier that indicates which item to retrieve from the collection.
pVar
Points to a variant that receives the item.
IRequestDictionary::get_NewEnum
The IRequestDictionary::get_NewEnum method returns an enumerator interface that can be
used to iterate through the items in a collection.
HRESULT get_NewEnum(
IUnknown ** ppEnumReturn
);
Parameters: IRequestDictionary::get_NewEnum
ppEnumReturn
Points to an IUnknown interface pointer that receives the enumerator.
Remarks: IRequestDictionary::get_NewEnum
You can use this method to iterate through the items in any collection. Members of the Cookies
collection may be implemented as collections. IReadCookie and IWriteCookie both support this
method, which you can use to iterate through members of the sub-collections.
IResponse Interface
The IResponse interface exposes the methods of the Response object.
IResponse::AddHeader
Adds a header to the HTML output.
IResponse::AppendToLog
Adds a string to the end of the Web server log for the current
request.
Chili!Soft ASP 3.6 Product Documentation
506
IResponse::BinaryWrite
Writes data to the HTTP output without any character
conversion.
IResponse::Clear
Erases any buffered HTML output.
IResponse::End
Causes the server to stop executing script and return the current
response.
IResponse::Flush
Sends buffered HTML output immediately.
IResponse::get_Buffer
Retrieves the value of the Buffer property.
IResponse::get_CacheContr
ol
Retrieves the value of the CacheControl property.
IResponse::get_CharSet
Retrieves the name of the character set to append to the content
type header.
IResponse::get_ContentType
Retrieves the value of the ContentType property.
IResponse::get_Cookies
Retrieves the write-only Cookies collection.
IResponse::get_Expires
Retrieves the value of the Expires property.
IResponse::get_ExpiresAbso
lute
Retrieves the value of the ExpiresAbsolute property.
IResponse::get_Status
Retrieves the value of the Status property.
IResponse::IsClientConnecte Determines if the client has disconnected from the server.
d
IResponse::PICS
Adds a value to the PICS label field of the Response header.
IResponse::put_Buffer
Sets the value of the Buffer property.
IResponse::putCharSet
Retrieves a character set to append to the content header type.
IResponse::put_ContentTyp
e
Sets the value of the ContentType property.
IResponse::put_Expires
Sets the value of the Expires property.
IResponse::put_ExpiresAbso Sets the value of the ExpiresAbsolute property.
lute
IResponse::put_Status
Sets the value of the Status property.
IResponse::Redirect
Causes the browser to attempt to connect to a different URL.
IResponse::Write
Writes a variant to the HTTP output.
The IResponse interface also supports the IUnknown and IDispatch interface methods.
IResponse::AddHeader
The IResponse::AddHeader method adds an HTTP header to the HTTP response.
HRESULT AddHeader(
Chili!Soft ASP 3.6 Product Documentation
507
BSTR bstrHeaderName,
BSTR bstrHeaderValue
);
Parameters: IResponse::AddHeader
bstrHeaderName
A binary string that contains the name of the HTTP header.
bstrHeaderValue
A binary string that contains the header value.
Remarks: IResponse::AddHeader
This method always adds an HTTP header with the specified value. It will not replace a header
with the same name; once a header has been added it cannot be removed.
IResponse::AppendToLog
The IResponse::AppendToLog method adds a string to the end of the Web server log entry for
the current request.
HRESULT AppendToLog(
BSTR bstrLogEntry
);
Parameters: IResponse::AppendToLog
bstrLogEntry
A binary string to append to the log entry. The string may be a maximum of 80 characters and
may not contain commas (,).
Remarks: IResponse::AppendToLog
This method adds a string to the end of the Web server log entry for this request. It can be called
multiple times in one section of script; each time the method is called it appends the specified
string to the existing entry.
IResponse::BinaryWrite
The IResponse::BinaryWrite method writes data to the HTTP output without converting Unicode
characters to ANSI.
HRESULT BinaryWrite(
VARIANT varBuffer
);
Parameters: IResponse::BinaryWrite
Chili!Soft ASP 3.6 Product Documentation
508
varBuffer
A variant containing the data as a Safe Array.
Remarks: IResponse::BinaryWrite
This method writes the specified information to the current HTTP output without any character
conversion. This method is useful for writing binary data required by a custom application.
IResponse::Clear
The IResponse::Clear method erases any buffered HTML output.
HRESULT Clear(VOID)
Remarks: IResponse::Clear
This method only erases the response body; it does not erase response headers. You can use this
method to handle error cases. This method will cause a run-time error if Response.Buffer has not
been set to TRUE.
IResponse::End
The IResponse::End method causes the server to stop processing the script and to return the
current response.
HRESULT End(VOID)
Remarks: IResponse::End
Any remaining contents of the file are not processed.
IResponse::Flush
The IResponse::Flush method sends buffered output immediately.
HRESULT Flush(VOID)
Remarks: IResponse::Flush
If this method is called on an ASP page, the server does not honor Keep-Alive requests for that
page. This method will cause a run-time error if Response.Buffer has not been set to TRUE.
IResponse::get_Buffer
The IResponse::get_Buffer method retrieves the current value of the Buffer property of the
Response object.
HRESULT get_Buffer(
VARIANT_BOOL * fIsBuffering
);
Parameters: IResponse::get_Buffer
Chili!Soft ASP 3.6 Product Documentation
509
fIsBuffering
Points to a Boolean variant that receives the Buffer value.
Remarks: IResponse::get_Buffer
When page output is buffered, the server does not send a response to the client until all of the
server scripts on the current page have been processed, or until the Flush or End method has
been called.
The Buffer property cannot be set after the server has sent output to the client. For this reason,
the call to Response.Buffer should be the first line of the .asp file.
IResponse::get_CacheControl
The IResponse::get_CacheControl method retrieves a value for the CacheControl property.
HRESULT get_CacheControl(
BSTR * pbstrCacheControl
);
Parameters: IResponse::get_CacheControl
pbstrCacheControl
Points to a binary string that receives the CacheControl value.
Remarks: IResponse::get_CacheControl
You can use the CacheControl value to override the default value (FALSE). By setting the value
to TRUE, proxy servers will be able to cache output from ASP pages.
IResponse::get_CharSet
The IResponse::get_CharSet method retrieves a character set to append to the content type
header.
HRESULT get_CharSet(
BSTR * pbstrCharSetRet
);
Parameters: IResponse::get_CharSet
pbstrCharSetRet
Points to a binary string that receives the CharSet value.
Remarks: IResponse::get_CharSet
You can use the CharSet value to determine the character set to use when displaying the current
Response object.
Chili!Soft ASP 3.6 Product Documentation
510
Iresponse::get_ContentType
The IResponse::get_ContentType method retrieves the current value of the ContentType
property of the Response object.
HRESULT get_ContentType(
BSTR * pbstrContentTypeRet
);
Parameters: IResponse::get_ContentType
pbstrContentTypeRet
Points to a binary string that receives the ContentType value.
Remarks: IResponse::get_ContentType
You can use the pbstrContentTypeRet value to determine the content type of the current
Response object.
IResponse::get_Cookies
The IResponse::get_Cookies method retrieves the write-only Cookies collection of the
Response object.
HRESULT get_Cookies(
IRequestDictionary ** ppCookies
);
Parameters: IResponse::get_Cookies
ppCookies
Points to an IRequestDictionary interface pointer that receives the write-only Cookies
collection.
Remarks: IResponse::get_Cookies
You can iterate through the Cookies collection with the IRequestDictionary::get_NewEnum
method, or you can retrieve a specific cookie with the IRequestDictionary::get_Item method.
IResponse::get_Expires
The IResponse::get_Expires method retrieves the current value of the Expires property of the
Response object.
HRESULT get_Expires*
VARIANT * pvarExpiresMinutesRet
);
Parameters: IResponse::get_Expires
pvarExpiresMinutesRet
Chili!Soft ASP 3.6 Product Documentation
511
Points to a variant that receives the Expires value. This value specifies the number of minutes
until the page will expire.
Remarks: IResponse::get_Expires
If the user returns to the same page before it expires, the cached version is displayed. If this
property is set more than once on a page, the shortest time is used.
IResponse::get_ExpiresAbsolute
The IResponse::get_ExpiresAbsolute method retrieves the current value of the
ExpiresAbsolute property of the Response object.
HRESULT get_ExpiresAbsolute(
VARIANT * pvarExpiresRet
);
Parameters: IResponse::get_ExpiresAbsolute
pvarExpiresRet
Points to a variant that receives the ExpiresAbsolute value. The variant should specify the date
and time.
Remarks: IResponse::get_ExpiresAbsolute
If the user returns to the same page before the set date and time, the cached version is displayed.
If a time is not specified, the page expires at midnight of that day. If a date is not specified, the
page expires at the given time on the day that the script is run. If this property is set more than
once on a page, the earliest expiration date or time is used. The date value sent in the Expires
header conforms to the RFC-1123 date format. The time value is converted to Greenwich Mean
Time before an Expires header is sent.
IResponse::get_Status
The IResponse::get_Status method retrieves the current value of the Status property of the
Response object.
HRESULT get_Status(
BSTR * pbstrStatusRet
);
Parameters: IResponse::get_Status
pbstrStatusRet
Points to a binary string that receives the Status value.
Remarks: IResponse::get_Status
Use this property to modify the status line returned by the server. Status values are defined in the
HTTP specification.
Chili!Soft ASP 3.6 Product Documentation
512
IResponse::IsClientConnected
The IResponse::IsClientConnected method determines if the client has disconnected from the
server since the last Response.Write operation.
HRESULT IsClientConnected(
VARIANT_BOOL pfIsClientConnected
);
Parameters: IResponse::IsClientConnected
pfIsClientConnected
Points to a Boolean that indicates whether or not the client is connected.
IResponse::PICS
The IResponse::PICS methods adds a value to the PICS label field of the response header.
HRESULT Pics(
BSTR bstrHeaderValue
);
Parameters: IResponse::PICS
bstrHeaderValue
A binary string that contains the new PICS value.
Remarks: IResponse::PICS
The IResponse::PICS method inserts any string in the header, whether or not it represents a valid
PICS label.
If a single page contains multiple tags containing Response.PICS, each instance will replace the
PICS label set by the previous one. As a result, the PICS label will be set to the value specified by
the last instance of Response.PICS in the page.
Because PICS labels contain quotes, the author must replace each quote with the ASCII
equivalent for the quote symbol [& chr(34) &].
For more details on the PICS standard, see:
http://www.w3.org/PICS/
IResponse::put_Buffer
The IResponse::put_Buffer method sets the value of the Buffer property of the Response
object.
HRESULT put_Buffer(
VARIANT_BOOL fIsBuffering
);
Chili!Soft ASP 3.6 Product Documentation
513
Parameters: IResponse::put_Buffer
fIsBuffering
A Boolean variant that contains the new Buffer value.
Remarks: IResponse::put_Buffer
When page output is buffered, the server does not send a response to the client until all of the
server scripts on the current page have been processed, or until the Flush or End methods are
called.
Since the Buffer property cannot be set after the server has sent output to the client, the call to
Response.Buffer should be the first line of the .asp file.
IResponse::putCharSet
The IResponse::putCharSet method sets the value of the Charset property of the Response
object.
HRESULT put_CharSet(
BSTR bstrCharset
);
Parameters: IResponse::putCharSet
bstrCharSet
A binary string that contains the new CharSet value.
Remarks: IResponse::putCharSet
You can use the CharSet value to set the character set to use when displaying the Response
object.
IResponse::put_ContentType
The IResponse::put_ContentType method sets the value of the ContentType property of the
Response object.
HRESULT put_ContentType(
BSTR bstrContentType
);
Parameters: IResponse::put_ContentType
bstrContentType
A binary string that contains the new ContentType value.
Remarks: IResponse::put_ContentType
You can use the ContentType value to set the content type to use when displaying the current
Response object.
Chili!Soft ASP 3.6 Product Documentation
514
IResponse::put_Expires
The IResponse::put_Expires method sets the current value of the Expires property of the
Response object.
HRESULT put_Expires(
LONG lExpiresMinutes
//LONG that contains the new Expires value
);
Parameters: IResponse::put_Expires
lExpiresMinutes
A Long integer that contains the new Expires value.
Remarks: IResponse::put_Expires
If the user returns to the same page before it expires, the cached version is displayed. If this
method is set more than once on a page, the shortest time is used.
IResponse::put_ExpiresAbsolute
The IResponse::put_ExpiresAbsolute method sets the value of the ExpiresAbsolute property
of the Response object.
HRESULT put_ExpiresAbsolute(
DATE dtExpires
);
Parameters: IResponse::put_ExpiresAbsolute
dtExpires
A date that contains the new ExpiresAbsolute value
Remarks: IResponse::put_ExpiresAbsolute
If the user returns to the same page before the set date and time, the cached version is displayed.
If a time is not specified, the page expires at midnight of that day. If a date is not specified, the
page expires at the given time on the day that the script is run. If this property is set more than
once on a page, the earliest expiration date or time is used. The date value sent in the Expires
header conforms to the RFC-1123 date format. The time value is converted to Greenwich Mean
Time before an Expires header is sent.
IResponse::put_Status
The IResponse::put_Status method sets the value of the Status property of the Response object.
HRESULT put_Status(
BSTR bstrStatus
);
Chili!Soft ASP 3.6 Product Documentation
515
Parameters: IResponse::put_Status
bstrStatus
A binary string that contains the new Status value.
Remarks: IResponse::put_Status
You can use this property to modify the status line returned by the server. Status values are
defined in the HTTP specification.
IResponse::Redirect
The IResponse::Redirect method first stops the server from processing the current script and
then causes the browser to attempt to connect to a different URL. For more information, see the
Redirect method of the Response object.
HRESULT Redirect(
BSTR bstrURL
);
Parameters: IResponse::Redirect
bstrURL
A binary string that contains the URL.
Remarks: IResponse::Redirect
If you have set any response body content in the page, it will be ignored. However, this method
does send to the client other HTTP headers set by this page. An automatic response body
containing the redirect URL as a link is generated. The IResponse::Redirect method sends the
following explicit header,
HTTP/1.0 302 Object Moved
Location URL
where URL is the value passed to the method.
IResponse::Write
The IResponse::Write method writes the specified variant to the HTTP output. For more
information, see the Write method of the Response object.
HRESULT Write(
VARIANT varText
);
Parameters: IResponse::Write
varText
A variant to write to the HTTP output.
Chili!Soft ASP 3.6 Product Documentation
516
Remarks: IResponse::Write
If VBScript is your primary scripting language, variant cannot be a string literal that contains
more than 1022 characters. This is because VBScript limits static strings to 1022 bytes. You can,
however, specify variant as the name of a variable that contains greater than 1022 bytes.
IScriptingContext Interface
The IScriptingContext interface exposes methods that your component can use to retrieve the
ASP built-in objects.
IScriptingContext::get_Appli
cation
Retrieves the Application object. This object implements the
IApplicationObject interface.
IScriptingContext::get_Reque
st
Retrieves the Request object. This object implements the
IRequest interface.
IScriptingContext::get_Respo
nse
Retrieves the Response object. This object implements the
IResponse interface.
IScriptingContext::get_Server
Retrieves the Server object. This object implements the IServer
interface.
IScriptingContext::get_Sessio
n
Retrieves the Session object. This object implements the
ISessionObject interface.
The IScriptingContext also supports the IUnknown and IDispatch interface methods.
IScriptingContext::get_Application
The IScriptingContext::get_Application method retrieves a pointer to the IApplicationObject
interface of the Application object.
HRESULT get_Application(
IApplicationObject ** ppApplication
);
Parameters: IScriptingContext::get_Application
ppApplication
Points to an IApplicationObject interface.
Remarks: IScriptingContext::get_Application
You can use IApplicationObject interface to gain access to variables and objects that have been
given application scope. IApplicationObject also exposes methods to lock and unlock an
application to prevent concurrent access to application objects and variables.
IScriptingContext::get_Request
The IScriptingContext::get_Request method retrieves a pointer to the IRequest interface of the
Request object.
Chili!Soft ASP 3.6 Product Documentation
517
HRESULT get_Request(
IRequest ** ppRequest
);
Parameters: IScriptingContext::get_Request
ppRequest
Points to an IRequest interface pointer.
Remarks: IScriptingContext::get_Request
You can use the IRequest interface to access the methods, properties, and collections of the
Request object.
IScriptingContext::get_Response
The IScriptingContext::get_Response method retrieves a pointer to the IResponse interface of
the Response object.
HRESULT get_Response(
IResponse ** ppResponse
);
Parameters: IScriptingContext::get_Response
ppResponse
Points to an IResponse interface pointer.
Remarks: IScriptingContext::get_Response
You can use the IResponse interface to access the methods, properties, and collections of the
Response object.
IScriptingContext::get_Server
The IScriptingContext::get_Server method retrieves a pointer to the IServer interface of the
Server object.
HRESULT get_Server(
IServer ** ppServer
);
Parameters: IScriptingContext::get_Server
ppServer
Points to an IServer interface pointer.
Remarks: IScriptingContext::get_Server
You can use the IServer interface to access the methods exposed by the Server object.
Chili!Soft ASP 3.6 Product Documentation
518
IScriptingContext::get_Session
The IScriptingContext::get_Session method retrieves a pointer to the ISessionObject interface
of the Session object.
HRESULT get_Session(
ISessionObject ** ppSession
);
Parameters: IScriptingContext::get_Session
ppSession
Points to an ISessionObject interface pointer.
Remarks: IScriptingContext::get_Session
You can use the ISessionObject interface to access variables and objects that have been given
session scope.
IServer Interface
The IServer interface exposes the methods and properties of the Server object.
IServer::CreateObject
Creates an instance of an object.
IServer::get_ScriptTimeou
t
Retrieves the value of the ScriptTimeout property.
IServer::HTMLEncode
Applies HTML encoding to the specified string.
IServer::MapPath
Maps the specified relative or virtual path to the corresponding
physical directory on the server.
IServer::put_ScriptTimeou
t
Sets the value of the ScriptTimeout property.
IServer::URLEncode
Applies URL encoding rules, including escape characters, to the
specified string.
The IServer interface also supports the IUnknown and IDispatch interface methods.
IServer::CreateObject
The IServer::CreateObject method creates an instance of a server component. For more
information, see the CreateObject method of the Server object.
HRESULT CreateObject(
BSTR bstrProgID,
IDispatch ** ppDispObject
);
Parameters: IServer::CreateObject
Chili!Soft ASP 3.6 Product Documentation
519
bstrProgID
A binary string that contains the progID of the object.
ppDispObject
Points to an IDispatch interface pointer.
Remarks: IServer::CreateObject
By default, objects created by the Server.CreateObject method have page scope. This means
that they are automatically destroyed by the server when it finishes processing the current ASP
page.
To create an object with session or application scope, you can either use the <OBJECT> tag and
set the SCOPE attribute to SESSION or APPLICATION, or store the object in a session or
application variable.
IServer::get_ScriptTimeout
The IServer::get_ScriptTimeout method retrieves the value of the ScriptTimeout property of
the Server object.
HRESULT get_ScriptTimeout(
LONG * plTimeoutSeconds
);
Parameters: IServer::get_ScriptTimeout
plTimeoutSeconds
Points to a LONG that receives the ScriptTimeout value.
Remarks: IServer::get_ScriptTimeout
A default ScriptTimeout can be set for a Web Service or Web Server by using the
ScriptTimeout property in the registry or configuration file. The ScriptTimeout property cannot
be set to a value less than that specified in the registry or configuration file.
IServer::HTMLEncode
The IServer::HTMLEncode method applies HTML encoding to the specified string. For more
information, see the HTMLEncode method of the Server object.
HRESULT HTMLEncode(
BSTR bstrIn,
BSTR * pbstrEncoded
);
Parameters: IServer::HTMLEncode
bstrIn
Chili!Soft ASP 3.6 Product Documentation
520
A binary string that contains the text to be encoded.
pbstrEncoded
Points to a binary string that receives the encoded text.
Remarks: IServer::HTMLEncode
If your component returns the encoded text to a browser, the browser will display it in HTML
format, rather than in plain text. For example, if the bstrIn contained the following string, <
>, the pbstrEncoded parameter would contain the HTML code for those characters, &lt
&gt. If your component returned this to a browser, however, it would display it as < >.
IServer::MapPath
The IServer::MapPath method maps the specified relative or virtual path to the corresponding
physical directory on the server. For more information, see the MapPath method of the Server
object.
HRESULT MapPath(
BSTR bstrLogicalPath,
BSTR * pbstrPhysicalPath
);
Parameters: IServer::MapPath
bstrLogicalPath
A binary string that contains the relative or virtual path.
pbstrPhysicalPath
Points to a binary string that receives the physical path.
Remarks: IServer::MapPath
This method does not check whether the path it returns is valid or exists on the server.
Because the IServer::MapPath method maps a path regardless of whether the specified
directories currently exist, you can use it to map a path to a physical directory structure, and then
pass that path to a component that creates the specified directory or file on the server.
IServer::put_ScriptTimeout
The IServer::put_ScriptTimeout method sets the value of the ScriptTimeout property of the
Server object.
HRESULT put_ScriptTimeout(
LONG lTimeoutSeconds
);
Parameters: IServer::put_ScriptTimeout
Chili!Soft ASP 3.6 Product Documentation
521
lTimeoutSeconds
A LONG integer that contains the new ScriptTimeout value.
Remarks: IServer::put_ScriptTimeout
A default ScriptTimeout can be set for a Web Service or Web Server by using the
ScriptTimeout property in the registry or configuration file. The ScriptTimeout property cannot
be set to a value less than that specified in the registry or configuration file.
IServer::URLEncode
The IServer::URLEncode method applies URL encoding rules, including escape characters, to
the specified string. For more information, see the URLEncode method of the Server object.
HRESULT URLEncode(
BSTR bstrIn,
BSTR * pbstrEncoded
);
Parameters: IServer::URLEncode
bstrIn
A binary string that contains the text to be encoded.
pbstrEncoded
Points to a binary string that receives the encoded text.
ISessionObject Interface
The ISessionObject interface exposes the methods of the Session object.
ISessionObject::Abandon
Destroys all the objects stored in the Session object
and releases their resources.
ISessionObject::get_Contents
Retrieves the Contents collection.
ISessionObject::get_SessionID
Retrieves the value of the SessionID entry.
ISessionObject::get_StaticObj
ects
Retrieves the StaticObjects collection.
ISessionObject::get_Timeout
Retrieves the value of the Timeout property.
ISessionObject::get_Value
Retrieves the value of a variable stored in the Session
object.
ISessionObject::put_Timeout
Sets a value for the Timeout property.
ISessionObject::putref_Value
Stores a variable in the Session object by reference.
ISessionObject::put_Value
Stores a variable in the Session object by value.
The ISessionObject interface also supports the IUnknown and IDispatch interfaces.
Chili!Soft ASP 3.6 Product Documentation
522
ISessionObject::Abandon
The ISessionObject::Abandon method destroys all the objects stored in the current session and
releases their resources. For more information see the Abandon method of the Session object.
HRESULT Abandon(VOID);
Remarks: ISessionObject::Abandon
When this method is called, the current Session object is queued for deletion, but is not actually
deleted until all of the script commands on the current page have been processed. This means that
you can access variables stored in the Session object on the same page as the call to Abandon,
but not in any subsequent Web pages.
ISessionObject::get_Contents
The ISessionObject::get_Contents method retrieves the value of the Contents property.
HRESULT get_Contents(
IVariantDictionary **ppProperties
);
Parameters: ISessionObject::get_Contents
ppProperties
Points to an IVariantDictionary interface pointer that receives the Contents collection.
Remarks: ISessionObject::get_Contents
The Session Contents collection contains all variables and objects that have been given
application scope with the Server.CreateObject command. You can iterate through the
Contents collection with the IVariantDictionary::get_NewEnum method exposed by the
interface. You can also retrieve a specific member of the collection with the
IVariantDictionary::get_Item method.
ISessionObject::get_SessionID
The ISessionObject::get_SessionID method retrieves the value of the SessionID property.
HRESULT get_SessionID(
BSTR * pbstrRet
);
Parameters: ISessionObject::get_SessionID
pbstrRet
Points to a binary string that receives the SessionID value.
Remarks: ISessionObject::get_SessionID
Chili!Soft ASP 3.6 Product Documentation
523
You should not use the SessionID property to generate primary key values for a database
application. This is because if the Web server is restarted, some SessionID values may be the
same as those generated before the server was stopped. Instead, you should use an auto-increment
column data type.
ISessionObject::get_StaticObjects
The ISessionObject::get_StaticObjects method retrieves the StaticObjects collection of the
Session object.
HRESULT get_StaticObjects(
IVariantDictionary **ppProperties
);
Parameters: ISessionObject::get_StaticObjects
ppProperties
Points to an IVariantDictionary interface pointer that receives the StaticObjects collection.
Remarks: ISessionObject::get_StaticObjects
You can iterate through the StaticObjects collection with the
IVariantDictionary::get_NewEnum method exposed by the interface. You can also retrieve a
specific member of the collection with the IVariantDictionary::get_Item method.
ISessionObject::get_Timeout
The ISessionObject::get_Timeout method retrieves the value of the Timeout property of the
Session object.
HRESULT get_Timeout(
LONG * plvar
);
Parameters: ISessionObject::get_Timeout
plvar
Points to a LONG integer that receives the Timeout value.
ISessionObject::get_Value
The ISessionObject::get_Value method retrieves the value of a variable stored in the Session
object.
HRESULT get_Value(
BSTR bstrValue,
VARIANT * pvar
);
Chili!Soft ASP 3.6 Product Documentation
524
Parameters: ISessionObject::get_Value
bstrValue
A binary string that contains the variable name.
pvar
Points to a variant that receives the variable value.
Remarks: ISessionObject::get_Value
You can store values in the Session object. Information stored in the Session object is available
throughout the session and has session scope.
ISessionObject::put_Timeout
This ISessionObject::put_Timeout method sets the value of the Timeout property of the
Session object.
HRESULT put_Timeout(
LONG lvar
);
Parameters: ISessionObject::put_Timeout
lvar
A LONG integer that contains the new Timeout value.
ISessionObject::putref_Value
The ISessionObject::putref_Value method stores a COM object in the Session object. This
method is equivalent to ISessionObject::put_Value for non-COM objects.
HRESULT putref_Value(
BSTR bstrValue,
VARIANT var
);
Parameters: ISessionObject::putref_Value
bstrValue
A binary string that contains the new variable name.
var
A variant to store in the variable.
Remarks: ISessionObject::putref_Value
Before you store an object in the Session object, you should know what threading model it uses.
For more information, see the Scope and Threading topics.
Chili!Soft ASP 3.6 Product Documentation
525
ISessionObject::put_Value
The ISessionObject::put_Value method stores a variant in the Session object. If the variant is a
COM object, then Chili!Soft ASP will attempt to store the default value of that object into the
application. If Chili!Soft ASP cannot get the default value, then the call will fail.
HRESULT put_Value(
BSTR bstrValue,
VARIANT var
);
Parameters: ISessionObject::put_Value
bstrValue
A binary string that contains the variable name.
var
A variant that contains the variable value.
Remarks: ISessionObject::put_Value
If you store an array in a Session object, you should not attempt to alter the elements of the stored
array directly. For example, the following script will not work.
<% Session("StoredArray")(3) = "new value" %>
This is because the Session object is implemented as a collection. The array element
StoredArray(3) does not receive the new value. Instead, the value is indexed into the
collection, overwriting any information stored at that location.
It is strongly recommended that if you store an array in the Session object, you retrieve a copy of
the array before retrieving or changing any of the elements of the array. When you are done with
the array, you should store the array in the Session object again so that any changes you made are
saved.
IStringList Interface
The IStringList interface is used to retrieve individual items from the string lists contained in the
QueryString, Form, or ServerVariables collections.
IStringList::get_Count
Retrieves the number of items in the string list.
IStringList::get_Item
Retrieves the specified item from a string list.
IStringList::get_NewEnu
m
Retrieves an enumerator for the string list.
The IStringList interface also supports the IUnknown and IDispatch interface methods.
IStringList::get_Count
The IStringList::get_Count method retrieves the number of items in a string list.
Chili!Soft ASP 3.6 Product Documentation
526
HRESULT get_Count(
INT * cStrRet
);
Parameters: IStringList::get_Count
cStrRet
Points to an integer that receives the number of items.
Remarks: IStringList::get_Count
The Form, QueryString, and ServerVariables collections return parameter values as an array. If
the collection does not contain multiple values, the cStrRet will contain 1; if the parameter is
not found, it will contain 0.
You can use this method to determine the number of items in the array. For example, if a Form
included an Items ordered parameter, you could use the get_Count method to determine the
number of items that had been ordered in the Form.
IStringList::get_Item
The IStringList::get_Item method retrieves an individual item from a string list.
HRESULT get_Item(
VARIANT Var,
VARIANT * pVariantReturn
);
Parameters: IStringList::get_Item
Var
A variant that contains the name of the item in the collection.
pVariantReturn
Points to a variant that receives the item value.
Remarks: IStringList::get_Item
You can use this method to retrieve a particular item from an array that has been returned by a
Form, QueryString, or ServerVariables collection.
IStringList::get_NewEnum
The IStringList::get_NewEnum method retrieves an enumerator interface which can be used to
iterate through the items in the string list.
HRESULT get__NewEnum(
IUnknown ** ppEnumReturn
);
Chili!Soft ASP 3.6 Product Documentation
527
Parameters: IStringList::get_NewEnum
ppEnumReturn
Points to an IUnknown interface pointer that receives the enumerator.
Remarks: IStringList::get_NewEnum
The Form, QueryString, and ServerVariables collections return parameter values as an array.
You can use this method to retrieve an enumerator to iterate through one of the string list
collections.
IVariantDictionary Interface
The IVariantDictionary interface exposes methods that you use to access the members of the
Application Contents, Application StaticObjects, Session Contents and Session
StaticObjects collections.
IVariantDictionary::get_Count
Retrieves the number of items in the collection.
IVariantDictionary::get_Item
Retrieves an item from the specified collection.
IVariantDictionary::get_Key
Retrieves an identifier for an item.
IVariantDictionary::get_NewE
num
Retrieves an enumerator for the collection.
IVariantDictionary::put_Item
Adds an item to the specified collection.
IVariantDictionary::get_Count
The IVariantDictionary::get_Count method returns the number of items in either the Contents
or StaticObjects collection.
HRESULT STDMETHODCALLTYPE get_Count(
int * cStrRet
);
Parameters: IVariantDictionary::get_Count
cStrRet
Points to an integer that contains a total of the number of items in the collection.
IVariantDictionary::get_Item
The IVariantDictionary::get_Item method retrieves the specified item from either the Contents
or StaticObjects collection. Both the Application and Session objects provide these collections.
HRESULT STDMETHODCALLTYPE get_Item(
VARIANT VarKey,
VARIANT * pvar
);
Chili!Soft ASP 3.6 Product Documentation
528
Parameters: IVariantDictionary::get_Item
VarKey
Identifier that indicates which item to retrieve from the collection.
pVar
Points to the item that is returned.
IVariantDictionary::get_Key
The IVariantDictionary::get_Key method returns a unique identifier for an item in either the
Contents or StaticObjects collection.
HRESULT STDMETHODCALLTYPE get_Item(
VARIANT VarKey,
VARIANT * pvar
);
Parameters: IVariantDictionary::get_Key
VarKey
Identifier that indicates which item to retrieve from the collection.
pVar
Points to the item that is returned.
IVariantDictionary::get_NewEnum
The IVariantDictionary::get_NewEnum method retrieves an enumerator interface which can be
used to iterate through the items in the collection.
HRESULT STDMETHODCALLTYPE get__NewEnum(
IUnknown * ppEnumReturn
);
Parameters: IVariantDictionary::get_NewEnum
ppEnumReturn
Points to an IUnknown interface pointer that receives the enumerator.
IVariantDictionary::put_Item
The IVariantDictionary::put_Item method adds an item to either the Contents or
StaticObjects collection.
HRESULT put_Item(
VARIANT VarKey,
VARIANT var
Chili!Soft ASP 3.6 Product Documentation
529
);
Parameters: IVariantDictionary::put_Item
VarKey
Identifier that indicates which item to add to the collection.
Var
The item to add to the collection.
IWriteCookie Interface
The IWriteCookie interface exposes the methods that you can use to alter the values and
attributes of the cookies stored in the write-only Cookies collection.
IWriteCookie::get_NewE
num
Retrieves an enumerator for the Cookies collection.
IWriteCookie::get_HasK
eys
Retrieves a Boolean indicating whether the cookie has
keys.
IWriteCookie::put_Doma
in
Sets the Domain attribute of the cookie to the specified
value.
IWriteCookie::put_Expir
es
Sets the Expires attribute of the cookie to the specified
value.
IWriteCookie::put_Item
Adds an item to the Cookies collection.
IWriteCookie::put_Path
Sets the Path attribute of the cookie to the specified value.
IWriteCookie::put_Secur
e
Sets the Secure attribute of the cookie to the specified
value.
IWriteCookie and IReadCookie are interfaces for the same object. If you have an
IWriteCookie pointer, you can call the IUnknown::QueryInterface method on an
IReadCookie pointer.
The IWriteCookie interface also supports the IUnknown and IDispatch interface methods.
IWriteCookie::get_NewEnum
The IWriteCookie::get_NewEnum method retrieves an enumerator interface which can be used
to iterate through the items in a cookie.
HRESULT get__NewEnum(
IUnknown ** ppEnumReturn
);
Parameters: IWriteCookie::get_NewEnum
ppEnumReturn
Points to an IUnknown interface pointer that receives the enumerator.
Chili!Soft ASP 3.6 Product Documentation
530
Remarks: IWriteCookie::get_NewEnum
If a cookie has been implemented as a collection, you can use this method to iterate through all
the members of its collection.
IWriteCookie::get_HasKeys
The IWriteCookie::get_HasKeys method retrieves a Boolean value which indicates whether or
not the cookie has keys.
HRESULT get_HasKeys(
VARIANT_BOOL * pfHasKeys
);
Parameters: IWriteCookie::get_HasKeys
pfHasKeys
Points to a Boolean that indicates whether or not the cookie has keys.
Remarks: IWriteCookie::get_HasKeys
If the cookie has been implemented as a collection, this method will return TRUE. If the cookie
has keys, you can use the IWriteCookie::get_NewEnum method to retrieve an enumerator for
iterating through the collection.
IWriteCookie::put_Domain
The IWriteCookie::put_Domain method sets the Domain attribute of the write-only Cookies
collection to the specified value.
HRESULT put_Domain(
BSTR bstrDomain
);
Parameters: IWriteCookie::put_Domain
bstrDomain
A binary string that contains the new domain value.
Remarks: IWriteCookie::put_Domain
You can use this method to specify particular domains for a cookie. This method only applies to
the Response.Cookies collection.
IWriteCookie::put_Expires
The IWriteCookie::put_Expires method sets the Expires attribute of the write-only Cookies
collection to the specified value.
HRESULT put_Expires(
DATE dtExpires
Chili!Soft ASP 3.6 Product Documentation
531
);
Parameters: IWriteCookie::put_Expires
dtExpires
A date that contains the new expiration value.
Remarks: IWriteCookie::put_Expires
This date must be set in order for the cookie to be maintained after the session ends. If this
attribute is not set to a date beyond the current date, the cookie will expire when the session ends.
IWriteCookie::put_Item
The IWriteCookie::put_Item method adds a specified cookie to the write-only Cookie
collection.
HRESULT put_Item(
VARIANT key,
BSTR bstrValue
);
Parameters: IWriteCookie::put_Item
key
A variant that contains the name of the cookie.
bstrValue
A binary string that contains the cookie value.
Remarks: IWriteCookie::put_Item
Automation objects can specify that one or more variant parameters are optional. This is done by
passing the parameter with the type set to VT_ERROR and a value of
DISP_E_PARAMNOTFOUND. If you pass key as an optional parameter, the cookie is treated as a
simple cookie and its value is set to bstrValue. Otherwise, the cookie is treated as a dictionary
cookie and bstrValue is the value for the cookie's key.
IWriteCookie::put_Path
The IWriteCookie::put_Path method sets the Path attribute of the write-only Cookies
collection to the specified value.
HRESULT put_Path(
BSTR bstrPath
);
Parameters: IWriteCookie::put_Path
bstrPath
Chili!Soft ASP 3.6 Product Documentation
532
A binary string that contains the new path.
Remarks: IWriteCookie::put_Path
You can use this method to specify that the cookie should be sent only to requests on a particular
path. If this attribute is not set, the application path is used.
IWriteCookie::put_Secure
The IWriteCookie::put_Secure method sets the Secure attribute of the write-only Cookies
collection to the specified value.
HRESULT put_Secure(
VARIANT_BOOL fSecure
);
Parameters: IWriteCookie::put_Secure
fSecure
A Boolean that contains the new value for the Secure attribute.
Remarks: IWriteCookie::put_Secure
You can use this method to specify that a cookie is secure. If you set this value to TRUE, a
Secure flag will be added to the Set-Cookie header sent to the client. The Secure flag
instructs the client to use only secure means to access the server when sending back the cookie.
Chili!Soft ASP 3.6 Product Documentation
JScript Language Reference
Chili!Soft ASP supports version 3.1 of JScript.
The following JScript reference topics are provided in this section:
•
JScript Operators
•
JScript Statements
•
JScript Functions
•
JScript Objects
•
JScript Collections
JScript Features (ECMA)
Category
Feature/Keyword
Array Handling
JScript Array Object
JScript Array Object concat Method
JScript Array Object join Method
JScript Array Object length Property
JScript Array Object reverse Method
JScript Array Object slice Method
JScript Array Object sort Method
Assignments
JScript Assignment Operator (=) [JScript Assignment Operator
('equals sign')
JScript Compound Assignment Operators
Booleans
JScript Boolean Object
Comments
JScript Comment Statements
Constants/Literals
JScript Global Object NaN Property
null,
true,
false,
JScript Global Object Infinity Property,
Undefined
Control Flow
JScript break Statement
JScript continue Statement
JScript for Statement
533
Chili!Soft ASP 3.6 Product Documentation
JScript for. . . in Statement
JScript if. . . else Statement
JScript return Statement
JScript while Statement
Dates and Time
JScript Date Object
JScript Date Object getDate Method
JScript Date Object getDay Method
JScript Date Object getFullYear Method
JScript Date Object getHours Method
JScript Date Object getMilliseconds Method
JScript Date Object getMinutes Method
JScript Date Object getMonth Method
JScript Date Object getSeconds Method
JScript Date Object getTime Method
JScript Date Object getTimezoneOffset Method
JScript Date Object getYear Method
JScript Date Object getUTCDate Method
JScript Date Object getUTCDay Method
JScript Date Object getUTCFullYear Method
JScript Date Object getUTCHours Method
JScript Date Object getUTCMilliseconds Method
JScript Date Object getUTCMinutes Method
JScript Date Object getUTCMonth Method
JScript Date Object getUTCSeconds Method
JScript Date Object setDate Method
JScript Date Object setFullYear Method
JScript Date Object setHours Method
JScript Date Object setMilliseconds Method
JScript Date Object setMinutes Method
JScript Date Object setMonth Method
JScript Date Object setSeconds Method
JScript Date Object setTime Method
534
Chili!Soft ASP 3.6 Product Documentation
JScript Date Object setYear Method
JScript Date Object setUTCDate Method
JScript Date Object setUTCFullYear Method
JScript Date Object setUTCHours Method
JScript Date Object setUTCMilliseconds Method
JScript Date Object setMinutes Method
JScript Date Object setUTCMonth Method
JScript Date Object setUTCSeconds Method
JScript Date Object toGMTString Method
JScript Date Object toLocaleString Method
JScript Date Object toUTCString Method
JScript Date Object parse Method
JScript Date Object UTC Method
Declarations
JScript function Statement
JScript new Operator
JScript this Statement
JScript var Statement
JScript with Statement
Function Creation
JScript Function Object
JScript Function Object arguments Property
JScript Function Object length Property
Global Methods
JScript Global Object
JScript Global Object escape Method
JScript Global Object unescape Method
JScript Global Object eval Method
JScript Global Object isFinite Method
JScript Global Object isNaN Method
JScript Global Object parseInt Method
JScript Global Object parseFloat Method
Math
JScript Math Object
JScript Math Object abs Method
JScript Math Object acos Method
535
Chili!Soft ASP 3.6 Product Documentation
JScript Math Object asin Method
JScript Math Object atan Method
JScript Math Object atan2 Method
JScript Math Object ceil Method
JScript Math Object cos Method
JScript Math Object exp Method
JScript Math Object floor Method
JScript Math Object log Method
JScript Math Object max Method
JScript Math Object min Method
JScript Math Object pow Method
JScript Math Object random Method
JScript Math Object round Method
JScript Math Object sin Method
JScript Math Object sqrt Method
JScript Math Object tan Method
JScript Math Object E Property
JScript Math Object LN2 Property
JScript Math Object LN10 Property
JScript Math Object LOG2E Property
JScript Math Object LOG10E Property
JScript Math Object PI Property
JScript Math Object SQRT1_2 Property
JScript Math Object SQRT2 Property
Numbers
JScript Number Object
JScript Number Object MAX_VALUE Property
JScript Number Object MIN_VALUE Property
JScript Number Object NaN Property
JScript Number Object NEGATIVE_INFINITY Property
JScript Number Object POSITIVE_INFINITY Property
Object Creation
JScript Object
JScript new Operator
536
Chili!Soft ASP 3.6 Product Documentation
JScript Object constructor Property
JScript Object prototype Property
JScript Object toString Method
JScript Object valueOf Method
Operators
JScript Addition Operator (+)
JScript Subtraction and Unary Negation Operator (-)
JScript Modulus Operator (%)
JScript Multiplication Operator (*)
JScript Division Operator (/)
JScript Subtraction and Unary Negation Operator (-)
JScript Comparison Operators
JScript Logical AND Operator (&&)
JScript Logical OR Operator (||)
JScript Logical NOT Operator (!)
JScript Bitwise AND Operator (&)
JScript Bitwise OR Operator (|)
JScript Bitwise NOT Operator (~)
JScript Bitwise XOR Operator (^)
JScript Bitwise Left Shift Operator (<<)
JScript Bitwise Right Shift Operator (>>)
JScript Unsigned Right Shift Operator (>>>)
JScript Conditional (ternary) Operator (?:)
JScript Comma Operator (,)
JScript delete Operator
JScript typeof Operator
JScript void Operator
JScript Decrement (--) and Increment (++) Operators
Objects
JScript Array Object
JScript Boolean Object
JScript Date Object
JScript Dictionary Object
JScript Function Object
537
Chili!Soft ASP 3.6 Product Documentation
JScript Global Object
JScript Math Object
JScript Number Object
JScript Object
JScript String Object
Strings
JScript String Object
JScript String Object charAt Method
JScript String Object charCodeAt Method
JScript String Object fromCharCode Method
JScript String Object indexOf Method
JScript String Object lastIndexOf Method
JScript String Object split Method
JScript String Object toLowerCase Method
JScript String Object toUpperCase Method
JScript String Object length Property
JScript Features (non-ECMA)
Category
Feature/Keyword
Array Handling
JScript Array Object concat Method
JScript Array Object slice Method
JScript VBArray Object
JScript VBArray Object Dimensions Method
JScript VBArray Object getItem Method
JScript VBArray Object lbound Method
JScript VBArray Object toArray Method
JScript VBArray Object ubound Method
Conditional
Compilation
JScript @cc_on Statement
JScript @if Statement
JScript @set Statement
JScript Conditional Compilation Variables
Control Flow
JScript do. . . while Statement
JScript Labeled Statement
538
Chili!Soft ASP 3.6 Product Documentation
JScript switch Statement
Dates and Time
JScript Date Object getVarDate Method
Enumeration
JScript Enumerator Object
JScript Enumerator Object AtEnd Method
JScript Enumerator Object item Method
JScript Enumerator Object moveFirst Method
JScript Enumerator Object moveNext Method
Function Creation
JScript Function Object caller Property
Operators
JScript Comparison Operators
Objects
JScript Enumerator Object
JScript RegExp Object
JScript Regular Expression Object
JScript VBArray Object
Regular Expressions JScript RegExp Object
and Pattern
JScript RegExp Object index Property
Matching
JScript RegExp Object input Property
JScript RegExp Object lastIndex Property
JScript RegExp Object lastMatch Property
JScript RegExp Object lastParen Property
JScript RegExp Object leftContext Property
JScript RegExp Object multiline Property
JScript RegExp Object rightContext Property
JScript RegExp Object $1. . . $9 Property
JScript Regular Expression Object
JScript Regular Expression Object global Property
JScript Regular Expression Object ignoreCase Property
JScript Regular Expression Object lastIndex Property
JScript Regular Expression Object source Property
JScript Regular Expression Object compile Method
JScript Regular Expression Object exec Method
JScript Regular Expression Object test Method
Script Engine
JScript ScriptEngine Function
539
Chili!Soft ASP 3.6 Product Documentation
Identification
540
JScript ScriptEngineBuildVersion Function
JScript ScriptEngineBuildMajorVersion Function
JScript ScriptEngineBuildMinorVersion Function
Strings
JScript String Object concat Method
JScript String Object slice Method
JScript String Object match Method
JScript String Object replace Method
JScript String Object search Method
JScript String Object anchor Method
JScript String Object big Method
JScript String Object blink Method
JScript String Object bold Method
JScript String Object fixed Method
JScript String Object fontcolor Method
JScript String Object fontsize Method
JScript String Object italics Method
JScript String Object small Method
JScript String Object strike Method
JScript String Object sub Method
JScript String Object sup Method
JScript Data Type Conversion
JScript provides automatic type conversion as the context may require. This means that if the
context expects a value to be a string, for example, JScript tries to convert the value to a string.
The language has six types of data. All values have one of these types:
•
Undefined. The undefined type has one value only, undefined.
•
Null. The null type has one value only, null.
•
Boolean. The Boolean type represents the two logical values, true and false.
•
String. A string delineated by single or double quotation marks; can contain zero or more
unicode characters. An empty string ("") has zero characters and length.
•
Number. Can be an integer or floating point number according to the IEEE 754
specification. There also several special values:
•
NaN, or not a Number
•
Positive infinity
541
Chili!Soft ASP 3.6 Product Documentation
•
Negative infinity
•
Positive zero
•
Negative zero
•
Object. An object definition including its set of properties and methods.
The following table defines what happens when the context requires that JScript convert one data
type into another:
Outpu
t
Input
Undefined
Null
Boolean
Number
String
Object
Boolea
n
false
false
no
conversion
false if +0, -0 or
NaN, otherwise
true
false if empty
string (""),
otherwise true
true
Numbe
r
NaN
NaN
1 if true +0
if false
no conversion
If it cannot be
interpreted as a
number, it is
interpreted as
NaN
Number
object
String
undefined
"null
"
"true" or
"false"
The absolute
value of the
number plus its
sign, with the
following
exceptions:
NaN returns
"NaN" +0 or -0
returns "0" +
infinity returns
"Infinity" –
infinity returns
"-Infinity"
no conversion
String
object
Object
runtime
error
runti
me
error
New
Boolean
object
New Number
object
New String
object
no
conversio
n
JScript Conditional Compilation Variables
The following predefined variables are available for conditional compilation. If a variable is not
True, it is not defined and behaves as NaN when accessed.
Chili!Soft ASP 3.6 Product Documentation
Variable
Description
@_win32
True if running on a Win32 system.
@_win16
True if running on a Win16 system.
@_mac
True if running on an Apple Macintosh system.
@_alpha
True if running on a DEC Alpha processor.
@_x86
True if running on an Intel processor.
@_mc680x0
True if running on a Motorola 680x0 processor.
@_PowerPC
True if running on a Motorola PowerPC processor.
@_jscript
Always true.
@_jscript_build
Contains the build number of the JScript scripting
engine.
@_jscript_version
Contains the JScript version number in major.minor
format.
JScript Operators
Operator
Description
JScript Addition Operator (+)
Sum two numbers or perform string concatenation.
JScript Assignment Operator (=)
[JScript Assignment Operator
('equals sign')
Assign a value to a variable.
JScript Bitwise AND Operator
(&)
Perform bitwise AND on two expressions.
JScript Bitwise Left Shift
Operator (<<)
Shift the bits of an expression to the left.
JScript Bitwise NOT Operator
(~)
Perform a bitwise NOT (negation) of an
expression.
JScript Bitwise OR Operator (|)
Perform bitwise OR on two expressions.
JScript Bitwise Right Shift
Operator (>>)
Shift the bits of an expression right, maintaining
sign.
JScript Bitwise XOR Operator
(^)
Perform bitwise exclusive OR on two expressions.
JScript Comma Operator (,)
Causes expressions to be executed sequentially.
JScript Comparison Operators
Returns a Boolean value indicating the result of the
comparison.
JScript Compound Assignment
Operators
Combine computational operators with assignment
operators to simplify expressions.
542
Chili!Soft ASP 3.6 Product Documentation
JScript Conditional (ternary)
Operator (?:)
Executes one of two statements depending on a
condition.
JScript Delete Operator
Deletes a property from an object, or removes an
element from an array.
JScript Decrement (--) and
Increment (++) Operators
Decrements a variable by one.
JScript Division Operator (/)
Divide two numbers and return a numeric result.
JScript Comparison Operators
(==)
Compares two expressions for equality
JScript Comparison Operators
(>)
Compares the magnitude of two expressions.
JScript Comparison Operators
(>=)
Compares the magnitude or equality of two
expressions.
JScript Comparison Operators
(===)
Compares two expressions for equality and type.
JScript Decrement (--) and
Increment (++) Operators
Increments a variable by one.
JScript Logical AND Operator
(&&)
Perform a logical conjunction on two expressions.
JScript Logical NOT Operator
(!)
Perform logical negation on an expression.
JScript Logical OR Operator (||)
Perform a logical disjunction on two expressions.
JScript Modulus Operator (%)
Divide two numbers and return only the remainder.
JScript Multiplication Operator
(*)
Multiply two numbers.
JScript new Operator
Create a new object.
JScript Subtraction and Unary
Negation Operator (-)
Indicate the negative value of a numeric
expression.
Comparison (!===)
Compares two expressions for equality and type.
Subtraction (-)
Find the difference between two expressions
JScript typeof Operator
Determine the type of an expression.
JScript Unsigned Right Shift
Operator (>>>)
Shift bits of an expression to the right.
JScript void Operator
Discards its operator and returns undefined.
543
544
Chili!Soft ASP 3.6 Product Documentation
JScript Operator Behavior
The following table describes the behavior of most JScript operators. The columns and rows
represent the different types of expressions possible on either side of an operator in JScript, and
the entries in the table describe the behavior.
An E indicates a run-time error. An N indicates a numeric result, or a Boolean result in the case
of logical operators.
obj
As
Ns
num
bool
Undef
null
Obj
N
E
N
N
N
E
E
As
E
E
E
E
E
E
E
Ns
N
E
N
N
N
E
E
Num
N
E
N
N
N
E
E
Bool
N
E
N
N
N
E
E
Undef
E
E
E
E
E
E
E
Null
E
E
E
E
E
E
E
obj = object, as = alphanumeric string, ns = numeric string, num = number, bool = Boolean, undef
= undefined, null = null value.
JScript Operator Precedence
Operators in JScript are evaluated in a particular order. This order is known as the operator
precedence. The following table lists the operators in highest-to-lowest precedence order.
Operators with the same precedence are evaluated in left to right order in the expression.
Operator
Description
. [] ()
Field access, array indexing, and function calls
++ -- - ~ ! delete new typeof
void
Unary operators, return data type, object creation,
undefined values
*/%
Multiplication, division, modulo division
+-+
Addition, subtraction, string concatenation
<< >> >>>
Bit shifting
< <= > >=
Less than, less than or equal, greater than, greater than or
equal
== != === !==
Equality, inequality, identity, nonidentity
&
Bitwise AND
^
Bitwise XOR
|
Bitwise OR
&&
Logical AND
545
Chili!Soft ASP 3.6 Product Documentation
||
Logical OR
?:
Conditional
= OP=
Assignment, assignment with operation
,
Multiple evaluation
Parentheses are used to alter the order of evaluation. The expression within parentheses is fully
evaluated before its value is used in the remainder of the statement.
An operator with higher precedence is evaluated before one with lower precedence. For example:
z = 78 * (96 + 3 + 45)
There are five operators in this expression: =, *, (), +, and +. According to precedence,
they are evaluated in the following order: (), *, +, +, =.
Evaluation of the expression within the parentheses is first: There are two addition operators, and
they have the same precedence: 96 and 3 are added together and 45 is added to that total,
resulting in a value of 144.
Multiplication is next: 78 and 144 are multiplied, resulting in a value of 10998.
Assignment is last: 11232 is assigned into z.
JScript Addition Operator (+)
Used to sum two numbers or perform string concatenation.
Syntax: JScript Addition Operator (+)
result = expression1 + expression2
Arguments: JScript Addition Operator (+)
result
Any variable.
expression1
Any expression.
expression2
Any expression.
Remarks: JScript Addition Operator (+)
The underlying subtype of the expressions determines the behavior of the + operator.
If
Then
Both expressions are numeric or Boolean
Add
Both expressions are strings
Concatenate
One expression is numeric and the other is a string
Concatenate
546
Chili!Soft ASP 3.6 Product Documentation
JScript += Operator
Used to increment a variable by a specified amount
Syntax: JScript += Operator
result += expression
Arguments: JScript += Operator
result
Any variable.
expression
Any expression.
Remarks: JScript += Operator
Using this operator is exactly the same as specifying:
result = result + expression
The underlying subtype of the expression determines the behavior of the += operator:
If
Then
Both expressions are numeric or Boolean
Add
Both expressions are strings
Concatenate
One expression is numeric and the other is a
string
Concatenate
For information on when a run-time error is generated by the += operator, see the Operator
Behavior table.
JScript Assignment Operator (=)
Assigns a value to a variable.
Syntax: JScript Assignment Operator (=)
result = expression
Arguments: JScript Assignment Operator (=)
result
Any variable.
expression
Any numeric expression.
Remarks: JScript Assignment Operator (=)
Chili!Soft ASP 3.6 Product Documentation
547
As the = operator behaves like other operators, expressions using it have a value in addition to
assigning that value into variable. This means that you can chain assignment operators as
follows:
j = k = l = 0;
j, k, and l equal zero after the example statement is executed.
JScript Bitwise AND Operator (&)
Used to perform a bitwise AND on two expressions.
Syntax: JScript Bitwise AND Operator (&)
result = expression1 & expression2
Arguments: JScript Bitwise AND Operator (&)
result
Any variable.
expression1
Any expression.
expression2
Any expression.
Remarks: JScript Bitwise AND Operator (&)
The & operator looks at the binary representation of the values of two expressions and does a
bitwise AND operation on them. The result of this operation behaves as follows:
0101 (expression1)
1100 (expression2)
---0100 (result)
Any time both of the expressions have a 1 in a digit, the result has a 1 in that digit. Otherwise, the
result has a 0 in that digit.
JScript &= Operator
Used to perform a bitwise AND on an expression
Syntax: JScript &= Operator
result &= expression
Arguments: JScript &= Operator
result
Any variable.
Chili!Soft ASP 3.6 Product Documentation
548
expression
Any expression.
Remarks: JScript &= Operator
Using this operator is exactly the same as specifying:
result = result & expression
The &= operator looks at the binary representation of the values of result and expression and does
a bitwise AND operation on them. The output of this operation behaves like this:
0101
(result)
1100
(expression)
---0100
(output)
Any time both result and expression have a 1 in a digit, result will have a 1 in that digit,
otherwise result will have a 0 in that digit.
For information on when a run-time error is generated by the &= operator, see the Operator
Behavior table.
JScript Bitwise Left Shift Operator (<<)
Used to shift the bits of an expression to the left.
Syntax: JScript Bitwise Left Shift Operator (<<)
result = expression1 << expression2
Arguments: JScript Bitwise Left Shift Operator (<<)
result
Any variable.
expression1
Any expression.
expression2
Any expression.
Remarks: JScript Bitwise Left Shift Operator (<<)
The << operator shifts the bits of expression1 left by the number of bits specified in expression2.
For example:
var temp
temp = 14 << 2
The variable temp has a value of 56 as 14 (00001110 in binary) shifted left two bits equals 56
(00111000 in binary).
Chili!Soft ASP 3.6 Product Documentation
549
For information on when a run-time error is generated by the << operator, see the Operator
Behavior table.
JScript <<= Operator
Left shifts the value of a variable by the number of bits specified in the value of an expression
and assigns the result to a variable.
Syntax: JScript <<= Operator
result <<= expression
Arguments: JScript <<= Operator
result
Any variable.
expression
Any expression.
Remarks: JScript <<= Operator
Using this operator is exactly the same as specifying:
result = result << expression
The <<= operator shifts the bits of result left by the number of bits specified in expression. For
example:
var temp
temp = 14
temp <<= 2
The variable temp has a value of 56 as 14 (00001110 in binary) shifted left two bits equals 56
(00111000) in binary. Bits are filled in with zeroes when shifting.
For information on when a run-time error is generated by the <<= operator, see the Operator
Behavior table.
JScript Bitwise NOT Operator (~)
Used to perform a bitwise NOT (negation) on an expression.
Syntax: JScript Bitwise NOT Operator (~)
result = ~ expression
Arguments: JScript Bitwise NOT Operator (~)
result
Any variable.
expression
Chili!Soft ASP 3.6 Product Documentation
Any expression.
Remarks: JScript Bitwise NOT Operator (~)
All unary operators, such as the ~ operator, evaluate expressions as follows:
•
If applied to undefined or null expressions, a run-time error is raised.
•
Objects are converted to strings.
•
Strings are converted to numbers if possible. If not, a run-time error is raised.
•
Boolean values are treated as numbers (0 if false, 1 if true).
The operator is applied to the resulting number.
The ~ operator looks at the binary representation of the values of the expression and does a
bitwise negation operation on it. The result of this operation behaves as follows:
0101 (expression)
---1010 (result)
1011
Any digit that is a 1 in the expression becomes a 0 in the result. Any digit that is a 0 in the
expression becomes a 1 in the result.
JScript Bitwise OR Operator (|)
Used to perform a bitwise OR on two expressions.
Syntax: JScript Bitwise OR Operator (|)
result = expression1 | expression2
Arguments: JScript Bitwise OR Operator (|)
result
Any variable.
expression1
Any expression.
expression2
Any expression.
Remarks: JScript Bitwise OR Operator (|)
The | operator looks at the binary representation of the values of two expressions and does a
bitwise OR operation on them. The result of this operation behaves as follows:
0101 (expression1)
1100 (expression2)
550
Chili!Soft ASP 3.6 Product Documentation
551
---1101 (result)
Any time either of the expressions has a 1 in a digit, the result will have a 1 in that digit.
Otherwise, the result will have a 0 in that digit.
For information on when a run-time error is generated by the | operator, see the Operator
Behavior table.
JScript |= Operator
Used to perform a bitwise OR on an expression.
Syntax: JScript |= Operator
result |= expression
Arguments: JScript |= Operator
result
Any variable.
expression
Any expression.
Remarks: JScript |= Operator
Using this operator is exactly the same as specifying:
result = result | expression
The |= operator looks at the binary representation of the values of result and expression and does
a bitwise OR operation on them. The output of this operation behaves like this:
0101
(result)
1100
(expression)
---1101
(output)
Any time either result or expression has a 1 in a digit, result will have a 1 in that digit, otherwise
result will have a 0 in that digit.
For information on when a run-time error is generated by the |= operator, see the Operator
Behavior table.
JScript Bitwise Right Shift Operator (>>)
Used to shift the bits of an expression to the right, maintaining sign.
Syntax: JScript Bitwise Right Shift Operator (>>)
result = expression1 >> expression2
Chili!Soft ASP 3.6 Product Documentation
552
Arguments: JScript Bitwise Right Shift Operator (>>)
result
Any variable.
expression1
Any expression.
expression2
Any expression.
Remarks: JScript Bitwise Right Shift Operator (>>)
The >> operator shifts the bits of expression1 right by the number of bits specified in
expression2. The sign bit of expression1 is used to fill the digits from the left. Digits shifted off
the right are discarded. For example, after the following code is evaluated, temp has a value of 4: 14 (11110010 in binary) shifted right two bits equals -4 (11111100 in binary).
var temp
temp = -14 >> 2
For information on when a run-time error is generated by the >> operator, see the Operator
Behavior table.
JScript >>= Operator
Used to shift the bits of an expression to the right, preserving sign.
Syntax: JScript >>= Operator
result >>= expression
Arguments: JScript >>= Operator
result
Any variable.
expression
Any expression.
Remarks: JScript >>= Operator
Using this operator is exactly the same as specifying:
result = result >> expression
The >>= operator shifts the bits of result right by the number of bits specified in expression. The
sign bit of result is used to fill the digits from the left. Digits shifted off the right are discarded.
For example, after the following code is evaluated, temp has a value of –4: 14 (11110010 in
binary) shifted right two bits equals –4 (11111100 in binary).
var temp
Chili!Soft ASP 3.6 Product Documentation
temp = -14
temp <<= 2
For information on when a run-time error is generated by the >>= operator, see the Operator
Behavior table.
JScript Bitwise XOR Operator (^)
Used to perform a bitwise exclusive OR on two expressions.
Syntax: JScript Bitwise XOR Operator (^)
result = expression1 ^ expression2
Arguments: JScript Bitwise XOR Operator (^)
result
Any variable.
expression1
Any expression.
expression2
Any expression.
Remarks: JScript Bitwise XOR Operator (^)
The ^ operator looks at the binary representation of the values of two expressions and does a
bitwise exclusive OR operation on them. The result of this operation behaves as follows:
0101 (expression1)
1100 (expression2)
---1001 (result)
When one, and only one, of the expressions has a 1 in a digit, the result has a 1 in that digit.
Otherwise, the result has a 0 in that digit.
For information on when a run-time error is generated by the ^ operator, see the Operator
Behavior table.
JScript ^= Operator
Used to perform a bitwise exclusive OR on an expression.
Syntax: JScript ^= Operator
result ^= expression
Arguments: JScript ^= Operator
result
553
Chili!Soft ASP 3.6 Product Documentation
554
Any variable.
expression
Any expression.
Remarks: JScript ^= Operator
Using this operator is exactly the same as specifying:
result = result ^ expression
The ^= operator looks at the binary representation of the values of result and expression and does
a bitwise OR operation on them. The output of this operation behaves like this:
0101
(result)
1100
(expression)
---1001
(output)
When one, and only one, of result or expression have a 1 in a digit, result will have a 1 in that
digit, otherwise result will have a 0 in that digit.
For information on when a run-time error is generated by the ^= operator, see the Operator
Behavior table.
JScript Comma Operator (,)
Causes two expressions to be executed sequentially.
Syntax: JScript Comma Operator (,)
expression1, expression2
Arguments: JScript Comma Operator (,)
expression1
Any expression.
expression2
Any expression.
Remarks: JScript Comma Operator (,)
The , operator causes the expressions on either side of it to be executed in left-to-right order,
and obtains the value of the expression on the right. The most common use for the , operator is in
the increment expression of a for loop. For example:
for (i = 0; i < 10; i++, j++)
{
k = i + j;
}
Chili!Soft ASP 3.6 Product Documentation
555
The for statement only allows a single expression to be executed at the end of every pass through
a loop. The , operator is used to allow multiple expressions to be treated as a single expression,
thereby getting around the restriction.
JScript Comparison Operators
Returns a Boolean value indicating the result of the comparison.
Syntax: JScript Comparison Operators
expression1 comparisonoperator expression2
Arguments: JScript Comparison Operators
expression1
Any expression.
comparisonoperator
Any comparison operator.
expression2
Any expression.
Remarks: JScript Comparison Operators
When comparing strings, JScript uses the Unicode character value of the String expression. The
following is how the different groups of operators behave depending on the types and values of
expression1 and expression2:
Relational (<, >, <=, =)
Attempt to convert both expression1 and expression2 into numbers.
•
If both expressions are strings, do a lexicographical string comparison.
•
If either expression is NaN, return false.
•
Negative zero equals Positive zero.
•
Negative Infinity is less than everything including itself.
•
Positive Infinity is greater than everything including itself.
Equality (==, !=)
If the types of the two expressions are different, attempt to convert them to string, number, or
Boolean.
•
NaN is not equal to anything including itself.
•
Negative zero equals positive zero.
•
Null equals both null and undefined.
556
Chili!Soft ASP 3.6 Product Documentation
•
Values are considered equal if they are identical strings, numerically equivalent numbers,
the same object, identical Boolean values, or (if different types) they can be coerced into
one of these situations.
•
Every other comparison is considered unequal.
Ide