PowerDynamo - Unione Parmense Degli IndustrialiServer SNMP SubAgent, SQL Station, SQLJ, STEP, SupportNow, Sybase Central, Sybase Client/Server Interfaces, Sybase Financial Server,

PowerDynamo Users Guide

PowerDynamoVersion 3.5

n new

29-9

the

erver, catio

s, n prise ork n ase,

upport, it,

erAMC, ipt, erWare

or, S SQL , SQL L

inancial orkbench, ream,

e roup

s.

MC00341

Last revised: October 1999

Copyright © 1989-1999 by Sybase, Inc. All rights reserved.

This publication pertains to Sybase database management software and to any subsequent release until otherwise indicated i editions or technical notes. Information in this document is subject to change without notice. The software described herein is furnished under a license agreement, and it may be used or copied only in accordance with the terms of that agreement.

To order additional documents, U.S. and Canadian customers should call Customer Fulfillment at (800) 685-8225, fax (617) 2845.

Customers in other countries with a U.S. license agreement may contact Customer Fulfillment via the above fax number. All or international customers should contact their Sybase subsidiary or local distributor. Upgrades are provided only at regularly scheduled software release dates. No part of this publication may be reproduced, transmitted, or translated in any form or by any means, electronic, mechanical, manual, optical, or otherwise, without the prior written permission of Sybase, Inc.

Sybase, the Sybase logo, ADA Workbench, Adaptable Windowing Environment, Adaptive Component Architecture, Adaptive SAdaptive Server Anywhere, Adaptive Server Enterprise, Adaptive Server Enterprise Monitor, Adaptive Server Enterprise Replin, Adaptive Server Everywhere, Adaptive Server IQ, Adaptive Warehouse, AnswerBase, Anywhere Studio, Application Manager,AppModeler, APT Workbench, APT-Build, APT-Edit, APT-Execute, APT-FORMS, APT-Translator, APT-Library, Backup Server, ClearConnect, Client-Library, Client Services, Data Pipeline, Data Workbench, DataArchitect, Database Analyzer, DataExpresDataServer, DataWindow, DB-Library, dbQueue, Developers Workbench, Direct Connect Anywhere, DirectConnect, DistributioDirector, E-Anywhere, E-Whatever, Embedded SQL, EMS, Enterprise Application Server, Enterprise Application Studio, EnterClient/Server, Enterprise Connect, Enterprise Data Studio, Enterprise Manager, Enterprise SQL Server Manager, Enterprise WArchitecture, Enterprise Work Designer, Enterprise Work Modeler, EWA, Gateway Manager, ImpactNow, InfoMaker, InformatioAnywhere, Information Everywhere, InformationConnect, InternetBuilder, iScript, Jaguar CTS, jConnect for JDBC, KnowledgeBMainframeConnect, Maintenance Express, MAP, MDI Access Server, MDI Database Gateway, media.splash, MetaWorks, MySNet-Gateway, Net-Library, NetImpact, ObjectConnect, ObjectCycle, OmniConnect, OmniSQL Access Module, OmniSQL ToolkOpen Client, Open ClientConnect, Open Client/Server, Open Client/Server Interfaces, Open Gateway, Open Server, Open ServerConnect, Open Solutions, Optima++, PB-Gen, PC APT Execute, PC DB-Net, PC Net Library, Power++, power.stop, PowPowerBuilder, PowerBuilder Foundation Class Library, PowerDesigner, PowerDimensions, PowerDynamo, PowerJ, PowerScrPowerSite, PowerSocket, Powersoft, PowerStage, PowerStudio, PowerTips, Powersoft Portfolio, Powersoft Professional, PowDesktop, PowerWare Enterprise, ProcessAnalyst, Report Workbench, Report-Execute, Replication Agent, Replication Driver, Replication Server, Replication Server Manager, Replication Toolkit, Resource Manager, RW-DisplayLib, RW-Library, S Design-Designor, SDF, Secure SQL Server, Secure SQL Toolset, Security Guardian, SKILS, smart.partners, smart.parts, smart.script,Advantage, SQL Anywhere, SQL Anywhere Studio, SQL Code Checker, SQL Debug, SQL Edit, SQL Edit/TPU, SQL EverywhereModeler, SQL Remote, SQL Server, SQL Server Manager, SQL SMART, SQL Toolset, SQL Server/CFT, SQL Server/DBM, SQServer SNMP SubAgent, SQL Station, SQLJ, STEP, SupportNow, Sybase Central, Sybase Client/Server Interfaces, Sybase FServer, Sybase Gateways, Sybase MPP, Sybase SQL Desktop, Sybase SQL Lifecycle, Sybase SQL Workgroup, Sybase User WSybaseWare, Syber Financial, SyberAssist, SyBooks, System 10, System 11, System XI (logo), SystemTools, Tabular Data StTransact-SQL, Translation Toolkit, UNIBOM, Unilib, Uninull, Unisep, Unistring, URK Runtime Kit for UniCode, Viewer, Visual Components, VisualSpeller, VisualWriter, VQL, WarehouseArchitect, Warehouse Control Center, Warehouse Studio, WarehousWORKS, Watcom, Watcom SQL, Watcom SQL Server, Web Deployment Kit, Web.PB, Web.SQL, WebSights, WebViewer, WorkGSQL Server, XA-Library, XA-Server and XP Server are trademarks of Sybase, Inc. 9/99

Unicode and the Unicode Logo are registered trademarks of Unicode, Inc.

All other company and product names used herein may be trademarks or registered trademarks of their respective companie

Use, duplication, or disclosure by the government is subject to the restrictions set forth in subparagraph (c)(1)(ii) of DFARS 52.227-7013 for the DOD and as set forth in FAR 52.227-19(a)-(d) for civilian agencies.

Sybase, Inc., 6475 Christie Avenue, Emeryville, CA 94608.

Chapter

iii

iv

Contents

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

CHAPTER 1 Databases and the Internet ............................................................ 1Basic Web concepts......................................................................... 2

Storing, locating, and transmitting information on the Web....... 2Databases and the Web................................................................... 5

Gateways between Web servers and databases ...................... 5Static and dynamic Web pages................................................. 6Storing and accessing Web information in a database ............. 8

A glance at PowerDynamo............................................................... 9The interpreter ........................................................................... 9Web-site management ............................................................ 10HTML templates and scripts.................................................... 10The data store ......................................................................... 13The template repository........................................................... 13How the pieces fit together ...................................................... 13

CHAPTER 2 Getting Started with PowerDynamo ............................................ 15Overview ........................................................................................ 16

Before you begin ..................................................................... 16Installing the sample database................................................ 17Starting Dynamo programs ..................................................... 18Creating the sample Web site ................................................. 19

Looking at the sample Web site ..................................................... 20Connecting from Sybase Central to the sample Web site ....... 20Navigating the sample Web site.............................................. 21

Creating a template ........................................................................ 22How dynamic content is held in HTML templates ................... 23

Creating a script ............................................................................. 25Viewing template output in a browser ............................................ 27

Accessing the Web site locally ................................................ 27Accessing the Web site over a network .................................. 29

v

Contents

CHAPTER 3 Working with Dynamo Web Sites................................................. 31Working with Web sites.................................................................. 32

Web site architecture............................................................... 32Before you begin ..................................................................... 33Creating a Web site [Adaptive Server Anywhere] ................... 33Creating a Web site [Adaptive Server Enterprise]................... 35Creating a dynamic file-based Web site.................................. 36Creating a connection profile for your Web site ...................... 38Regenerating a Web site......................................................... 40Deleting a Web site ................................................................. 40

The Utilities folder .......................................................................... 41Starting the utilities .................................................................. 41

Working with folders and documents in your Web site .................. 42Creating folders ....................................................................... 42Moving or copying folders and documents.............................. 42Deleting folders and documents.............................................. 43Renaming folders and documents........................................... 43Linking folders to directories on disk ....................................... 43

Working with templates .................................................................. 46Creating a template ................................................................. 46Viewing and editing templates................................................. 48Embedding instructions in a template ..................................... 50Passing variables from one document to another ................... 52

Importing and exporting documents............................................... 55Importing documents into a Web site ...................................... 55Exporting documents from a Web site .................................... 56

Scheduling actions ......................................................................... 57Removing a scheduled action ................................................. 58

Working with connections .............................................................. 60The connection pool ................................................................ 60Connection definitions ............................................................. 62Creating, deleting, modifying and testing User connections ... 62Working with permanent and temporary connections ............. 64Managing the connection pool ................................................ 67

Copying a Web-site database [Adaptive Server Anywhere] .......... 69Using the Performance Monitor ..................................................... 70

CHAPTER 4 Configuring Web Servers and Web sites .................................... 71The Personal Web Server.............................................................. 72

Accessing a Web site using the Personal Web Server ........... 72Preparing to use the Personal Web Server............................. 73Starting the Personal Web Server........................................... 73Viewing a local Dynamo document ......................................... 74

Configuring a Dynamo Web site .................................................... 76

vi

Contents

Configuring Web servers during installation............................ 77Configuring Web Servers manually......................................... 77

Configuring an ISAPI server........................................................... 79Step 1: Edit the System Path in the System Properties window 79Step 2: Install the Application Server ..................................... 79Step 3: Create an ODBC System Data Source Name (DSN) 81Step 4: Create a connection profile ......................................... 83Step 5: Configure the Application Server ................................ 83

Configuring an ISAPI 4.0 server..................................................... 85Configuring the IIS 4.0 Server ................................................. 85

Configuring an NSAPI server ......................................................... 86Step 1: Edit the system path in the System Properties window 86Step 2: Install the Application Server ...................................... 87Step 3: Create an ODBC System Data Source Name (DSN) 91Step 4: Create a connection profile ......................................... 92Step 5: Configure the Application Server ................................ 93

Configuring a CGI or WIN-CGI server............................................ 94Step 1: Edit the System Path in the System Properties window 94Step 2: Install the Application Server ..................................... 94Step 3: Create an ODBC System Data Source Name (DSN) 97Step 4: Create a connection profile ......................................... 98Step 5: Configure the Application Server ................................ 99

Configuring Web sites .................................................................. 100Accessing the Dynamo Configuration folder ......................... 100Setting Dynamo mappings .................................................... 100

How mapping information is stored.............................................. 105Changing Dynamo configuration settings .................................... 106Setting Dynamo MIME types........................................................ 109

CHAPTER 5 Dynamo Tags Tutorial ................................................................ 111Overview of Dynamo Tags........................................................... 112Tags tutorial ................................................................................. 113

Using the SQL tag ................................................................. 113Using the FORMATTING tag ................................................ 115Using the error checking tags................................................ 118Using the INCLUDE tag ........................................................ 121Using the SQL_INSERT tag.................................................. 123The SCRIPT tag .................................................................... 125

CHAPTER 6 Writing DynaScripts.................................................................... 127Overview of scripts....................................................................... 128Script tutorials .............................................................................. 130

Embedding a Script in HTML ................................................ 130

vii

Contents

Using variables and expressions........................................... 132Using control statements....................................................... 133Using functions...................................................................... 134Using simple objects ............................................................. 135Using arrays .......................................................................... 137Passing variables from one document to another ................. 138Using object inheritance ........................................................ 140

CHAPTER 7 PowerDynamo and Java ............................................................. 145An introduction to Java................................................................. 146

Object-oriented and procedural languages ........................... 146A Java glossary ..................................................................... 151Java error handling................................................................ 152

Dynamo and Java ........................................................................ 155Configuring Dynamo to use Java ................................................. 156Using Java in a PowerDynamo script .......................................... 158

Arrays in Java........................................................................ 161Method overloading and type conversion.............................. 162Calling Jaguar components................................................... 163

CHAPTER 8 Working with XML Documents ................................................... 165Dynamo and XML ........................................................................ 166An introduction to XML................................................................. 167

Valid and well-formed XML documents................................. 167XML syntax............................................................................ 168

Creating XML documents............................................................. 170Creating XML documents from the query object ................... 170Creating custom XML documents from query result sets...... 172Creating XML documents from queries using the FORMATTING

tag................................................................................... 172Creating XML from DynaScript objects ................................. 174

Introduction to the Document Object Model................................. 177What you can do with DOM................................................... 177The DOM view of documents ................................................ 177Using nodes to work with XML documents ........................... 179The object interface to XML documents................................ 180Error checking XML-handling scripts..................................... 181

Document Object Model examples .............................................. 182Converting XML to HTML for sending to a browser .............. 182Inserting data from XML into a database .............................. 184

Creating the DOMDocument object ............................................. 187Working with elements ................................................................. 189

Using the DOMNode object to work with elements ............... 189

viii

Contents

Using the DOMElement object to work with elements .......... 190Working with attributes................................................................. 191

Using the DOMNode object to work with attributes............... 191Using the DOMAttribute object to work with attributes .......... 192

Working with text.......................................................................... 193Obtaining all the text inside an element ................................ 194Working with CDATA sections .............................................. 194Escaping text with xmlEscape............................................... 195

Working with entities .................................................................... 196Working with internal entities................................................. 197Working with external entities................................................ 197

Working with other XML objects................................................... 199Using the DOM interface to create and edit XML documents ...... 200

Creating a DOM document object ......................................... 200Adding objects to DOM documents....................................... 200Removing and replacing objects in DOM documents ........... 201

CHAPTER 9 PowerDynamo Mail Support ...................................................... 203About PowerDynamo’s mail support ............................................ 204

Requirements for using PowerDynamo mail objects............. 204Sending mail ................................................................................ 206

To send a mail piece ............................................................. 206Receiving mail .............................................................................. 208

To retrieve mail from PowerDynamo..................................... 208Deleting mail ................................................................................ 210Forwarding and replying to mail ................................................... 211

Forwarding mail ..................................................................... 211Replying to mail ..................................................................... 212

A simple mail application.............................................................. 213

CHAPTER 10 Achieving Optimum Performance with PowerDynamo........... 217Performance requirements........................................................... 218

Processing of scripts ............................................................. 218Minimizing the calls to the database ..................................... 219Working with Connections to increase performance ............. 220

Designing your Web site .............................................................. 221Increasing the performance of your Web site .............................. 222Optimizing your document cache................................................. 223

Setting a document cache size ............................................. 224Setting a cachedOutputTimeOut value ................................. 225The relationship between cache size and cachedOutputTimeOut

values ............................................................................. 226Scheduling your scripts ................................................................ 228

ix

Contents

Enhancing performance for non-cacheable documents........ 229Writing cacheable documents ...................................................... 230Expensive methods and properties.............................................. 234Load balancing............................................................................. 235

Load balancing across processors........................................ 235Load balancing across servers.............................................. 236

Converting an inefficient Web site to an efficient Web site .......... 237Working with documents ....................................................... 237Working with connections...................................................... 238

Summary...................................................................................... 240

CHAPTER 11 Setting Up a Mobile Intranet ....................................................... 241SQL Remote replication technology............................................. 242

Web site replication ............................................................... 242Requirements for a mobile intranet .............................................. 243Replicating a Web site ................................................................. 244

Setting up publications and subscriptions ............................. 244Setting up remote users ........................................................ 245

A Replication Tutorial ................................................................... 246The database ........................................................................ 246Setting up SQL Remote using Sybase Central ..................... 248Setting up the consolidated database ................................... 250Setting up the remote database ............................................ 254Replicating data..................................................................... 255

CHAPTER 12 Calling Jaguar Component Methods from PowerDynamo ...... 261How do Jaguar and PowerDynamo work together?..................... 262What does Jaguar bring to PowerDynamo applications? ............ 264

The benefits of using Jaguar CTS components with PowerDynamo 264

MASP method calls versus ActiveX or Java objects ............. 265Setting up PowerDynamo as a client ........................................... 266

Setting up PowerDynamo to use Jaguar components through ActiveX ........................................................................... 266

Setting up PowerDynamo to use Jaguar components through Java 267

Setting up PowerDynamo to use MASP................................ 267Using an ODBC data source to connect to Jaguar ............... 268Using an Open Client connection to connect to Jaguar ........ 269

Calling Jaguar components from a PowerDynamo script ............ 271The Dynamo SQL tag (MASP) .............................................. 271The Dynamo COMPONENT tag ........................................... 272The connection.CreateQuery method (MASP)...................... 274

x

Contents

The connection.CreateComponent method (MASP)............. 274The java.CreateComponent method ..................................... 275GetHomeInterface method .................................................... 277GetUserTransaction method ................................................. 278The PowerDynamo CreateObject method ............................ 281

Working with ADO record sets as PowerDynamo query objects . 284Working with Tabular Results ...................................................... 286

APPENDIX A Setting Up the Adaptive Server Anywhere Database Server as a Service 289

Why use the Adaptive Server Anywhere server?......................... 290Why run the Adaptive Server Anywhere database server as a

service? .......................................................................... 290Setting up the Adaptive Server Anywhere database server for

PowerDynamo ................................................................ 292 Start the Adaptive Server Anywhere server as a service ..... 292Set up the ODBC System DSN ............................................. 292Set up the Connection Profile................................................ 294Connect to PowerDynamo .................................................... 294

APPENDIX B Language Support ...................................................................... 297Language support ........................................................................ 298

Adaptive Server Anywhere language support ....................... 298Adaptive Server Enterprise language support....................... 299Dynamic file site language support ....................................... 300

Usage of multi-byte characters .................................................... 301

xi

xii

About This Book

Subject This manual describes PowerDynamo, a suite of tools for building and managing database-hosted Web sites and for enabling intranets for a mobile workforce.

Audience This manual is for users who want to build Web sites with dynamic content. For reference type information, see the PowerDynamo Reference.

Before you begin This manual assumes that you are moderately familiar with HTML, ECMAScript (the standardized version of JavaScript) and the operations of Web browsers and servers.

Introducing PowerDynamoYou can use PowerDynamo to store, manage, and access both static HTML and dynamic database data. You can then make that information available over the Internet for not only information delivery but also for use by Web-hosted client/server applications.

You can combine PowerDynamo with Sybase SQL Remote replication technology to replicate Web templates and dynamic content onto a laptop computer for offline use.

SQL Remote allows data and HTML templates to be replicated in both directions, so you can run client/server applications offline and SQL Remote can update your changes to the central server.

New FeaturesThis release of PowerDynamo has several major new features:

•Java You can access Java classes from within Dynamo scripts. For information see “PowerDynamo and Java” on page 145.

xiii

About this book

ar

•XML PowerDynamo now supports XML You can create queries that generate output in either HTML or XML. For more information see “Working with XML Documents” on page 165.

•Mail Several objects have been added to PowerDynamo that enable the sending, receiving, and manipulation of mail from within a PowerDynamo Web site. For more information see “PowerDynamo Mail Support” onpage 203.

•FTP Several objects have been added to PowerDynamo that provide FTP functionality to PowerDynamo Web sites. These objects are documented in “DynaScript Predefined Objects” in the PowerDynamo Reference.

•ECMAScript compatible PowerDynamo is now ECMAScript compatible. The ECMAScript objects are documented in “DynaScriptPredefined Objects” in the PowerDynamo Reference.

•Invoking Jaguar CTS components PowerDynamo clients can access Jaguar components through Java, ActiveX, SQL queries or PowerDynamo tags. For information on PowerDynamo and Jaguar see “Calling JaguComponent Methods from PowerDynamo” on page 261.

•UNIX Dynamo is now available on AIX with NSAPI, CGI, and the Personal Web Server. CGI and the Personal Web Server are now available on Solaris (NSAPI is supported from previous Dynamo releases).

New objects, properties and methodsThe following objects (along with their methods and properties) are new to PowerDynamo:

• Java object

• Incoming mail object

• Outgoing mail object

• Mail list object

• Attachment object

• Recipient object

• FTP object

• DOMAttribute object

• DOMCDATASection object

xiv

About this book

• DOMCharacterData object

• DOMComment object

• DOMDocument object

• DOMDocumentFragment object

• DOMDocumentType object

• DOMElement object

• DOMEntity object

• DOMEntityReference object

• DOMImplementation object

• DOMNamedNodeMap object

• DOMNode object

• DOMNodeList object

• DOMNotation object

• DOMProcessingInstruction object

• DOMText object

The following properties and methods are new to PowerDynamo

• java.CreateObject( )

• java.GetHomeInterface()

• java.GetUserTransaction()

• query.cursorType

• query.stripTrailingBlanks

• query.ResultsToXMLString( )

PowerDynamo built-in functionsThe following built-ins have been added to PowerDynamo:

• xmlEscape( )

• toXMLString( )

xv

About this book

PowerDynamo tagsThe following tags have been added to PowerDynamo:

• COMPONENT

• ENDIF

• ELSE

• ELSEIF

• FORMAT_AS (attribute on FORMATTING tag)

• IF

• MAILPIECE

• STRIP_TRAILING_BLANKS (attribute on FORMATTING tag)

• USE_CDATA (attribute on FORMATTING tag)

Other New Features• You can set event handlers for 404 (not found) messages.

• New ability to test if a connection is valid from within Sybase Central.

• From within Sybase Central you can:

• Test whether a connection is valid.

• Change the directory to which a linked folder refers.

You can use relative paths in Dynamo.

You can execute a script before a user session times out.

Printed and online documentationThe PowerDynamo Users Guide is available in both printed and online formats. The PowerDynamo Reference is provided in online format only unlessordered separately. The online documentation is available in two formats:

• As Windows Help.

• In HTML format which you can import into a PowerDynamo Web site.

xvi

About this book

Online documentation more complete and timelyOnline documentation is more up to date and may be more complete than printed documentation: in case of differences between the two, you should follow the online documentation.

Syntax conventionsThe following conventions are used for syntax diagrams in this manual:

PowerDynamo Web sites work with either Adaptive Server Enterprise or Adaptive Server Anywhere databases. In this book, sections that apply to only one of these databases are marked by [Adaptive Server Anywhere] or [Adaptive Server Enterprise] at the beginning of the appropriate section.

Type Symbol Syntax ConventionKeywords SCRIPT SQL keywords and HTML tags are shown in

uppercase.

Placeholders name Items that the user must replace with appropriate identifiers or expressions are shown in italics.

Options | Options are separated by vertical bars. Any one of the items is allowed.

Continuation ... Lines beginning with ... are a continuation of the statements from the previous line.

Lists ",..." Lists are shown with a list element followed by ",...". This means that one or more list elements are allowed and if more than one is specified, they must be separated by commas.

Optional portions

[ ] Optional portions of a statement are enclosed by square brackets. For example, FORMATTING [ MAXROWS = num ] indicates that the MAXROWS = num is optional. Alternative optional parts of a statement are sometimes listed within the brackets separated by vertical bars. For example, [ ASC | DESC ] indicates that ASC or DESC are optional. Do not type the square bracket.

Alternatives { } When one of the options must be chosen, the alternatives are enclosed in curly braces. For example [ QUOTES { ON | OFF } ] indicates that if the QUOTES option is chosen, one of ON or OFF must be provided. Do not include the braces.

xvii

About this book

This book uses “PowerDynamo” and “Dynamo” interchangeably when referring to PowerDynamo.

xviii

C H A P T E R 1 Databases and the Internet

About this chapter This chapter introduces basic Internet and World Wide Web concepts, and describes the increasingly important role of databases on the Internet. It also provides an overview of the pieces that make up PowerDynamo.

Contents Topic Page

Basic Web concepts 2

Databases and the Web 5

A glance at PowerDynamo 9

1

Basic Web concepts

Basic Web conceptsThis section describes the essential concepts for working with PowerDynamo.

Storing, locating, and transmitting information on the WebFigure 1-1: Accessing information on the Web

As Figure 1-1 illustrates, information is stored at Web sites. Access to the information is managed by a Web server for the site. Users access the information using Web clients, which are also called browsers.

Information on the Web is stored in documents, using a language called HTML (HyperText Markup Language). Web clients must interpret HTML to be able to display the documents to a user. The protocol that governs the exchange of information between the Web server and Web client is named HTTP (HyperText Transfer Protocol).

2

CHAPTER 1 Databases and the Internet

ic–

How information is located: the URL

To move from one page of a document to another page, or to another document on the same or another Web site, the user clicks a hyperlink (usually just called a link) in the document shown in their Web client. Documents and locations within documents are identified by an address, defined as a Uniform Resource Locator, or URL. The following URL illustrates the general form:

http://www.sybase.com/productsl

or

http://www.sybase.com/inc/corpinfo/mkcreate.html

URLs contain information about which server the document is on, and may also specify a particular document available to that server, and even a position within the document. In addition, a URL may carry other information from a Web client to a Web server, including the values entered into fields in an HTML form.

For more information about URLs and addresses on the Web, see the material on the World Wide Web Consortium pages, at the following address:

http://www.w3.org/pub/WWW/Addressing/

When a user clicks a link on a document on their Web client, the URL is sent to the server of the indicated Web site. The Web server locates the document, and sends the HTML to the Web client across the network.

External data in HTML documents

HTML documents can include graphics or other types of data by referencing an external file (for example, a GIF or JPEG file for a graphic). Not all these external formats are supported by all Web clients. When the document contains such data, the Web client can send a request to the Web server to provide the relevant graphic. If the Web client does not support the format, it does not request the information from the server.

Problems with file-based Web sites

In a file-based Web site, each resource is a separate file. For large Web sites, this leads to management problems. For example, maintaining current copies of hundreds or thousands of different resources in separate files is difficult enough; maintaining the links between these resources is even more challenging.

Another problem is that many Web sites contain information that is dynampricing information, for example, or employee information on an organization's Intranet. Maintaining such information in HTML files in addition to the database where it resides is a huge task.

3

Basic Web concepts

For these and other reasons, linking databases to the Web is increasingly the solution of choice for management of large Web sites and management of dynamic content. Database storage of Web information can either replace or complement file storage of Web resources.

4


Databases and the WebThis section describes how databases can connect to the Internet using a application server, or gateway. It also describes the information commonly stored in databases.

Gateways between Web servers and databasesFigure 1-2: Accessing data through an application server

For a Web server to retrieve information from a database, an intermediary application server or gateway is required between the Web server and the database management system (DBMS). Such an intermediary must have an interface to the Web server, and an interface to the DBMS. The most common Web server interface is named CGI. Each DBMS has a native interface; open interfaces such as ODBC and Open Client are also available.

5

Databases and the Web

d in

filled and s.

Web server interfaces CGI (Common Gateway Interface) is a standard Web server interface. When a Web server receives a URL corresponding to a CGI resource, it starts a CGI program (such as a perl script, or the PowerDynamo Application Server) which connects to the DBMS, queries the database, and returns the information to the Web server to be handed on to the Web client.

CGI is a standard for interfacing any external application with a Web server, not just a DBMS. CGI applications may also simply process files. The output of the CGI program or script is returned to the Web server. This output can be an HTML document, an image, a reference to another document, or any other form of information understood by the Web server.

CGI is an industry-standard Web server interface. Some Web server vendors also provide proprietary interfaces to their servers: NSAPI (Netscape Application Programming Interface) and Microsoft ISAPI (Internet Server Application Programming Interface) are two examples supported by PowerDynamo.

Static and dynamic Web pagesAn HTML document stored in a file is an example of a static Web page; its content does not change unless the file itself is edited.

With application servers, you can create dynamic Web pages, which are generated each time they are accessed. Dynamic pages have features not found in static Web pages:

• They can respond to input from the Web client, returning data requestesome way (such as by filling in a form on a Web page) by the client.

• They can be customized for each user. For example, once a user hasin preferences when visiting a site (areas of interest, level of expertise,so on), information sent to the user can be tuned to those preference

• They can be customized for the display capabilities of the Web client.

• The accuracy of time-sensitive information can be guaranteed.

Templates and data A dynamic Web page can any combination of:

• Static HTML text, displayed every time the page is displayed

• Embedded queries and programmatic instructions

• Data from the database that is filled in when the page is generated

6


Figure 1-3: Static and dynamic Web page components

The static components of the page are stored in an HTML document called a template. The template consists of the static HTML text (which is passed on to the Web client without change) together with the query or other instruction defining the dynamic component of the page, and the layout instructions governing the display of the data.

The query tags are interpreted by the application server and replaced by a result set when the document is generated. The application connecting the database to the Web server replaces the query with its data, formatted according to the instructions, and sends the resulting page to the Web server for relay to the Web client.

7

Databases and the Web

rately

on eb

nd

t, the TML erver.

tead ver

, fill also nt

Storing and accessing Web information in a databaseThis section describes some of the types of data that can be stored in a database for Internet access. This information falls into two broad categories:

• Data you already keep in a database, and don't want to duplicate sepain HTML files (pricing information and so on).

• Data that you create specifically for the Internet, and want to use a database to manage, such as HTML documents.

Accessing existing data

Existing data in a database can be accessed from the Internet using an application server. In this case the application server merges an HTML document (which may exist inside or outside the database) with informatistored in the database, and sends the resulting HTML document to the Wserver.

For example, a dynamically generated Web page might display pictures adescriptions of a product line, which are stored in HTML files, but fill in theprices, contact information, and other information from the database.

HTML documents HTML documents themselves may be stored in a database. At its simplestask of the application server is then to execute a query that retrieves the Hdocument from the database and passes it on without change to the Web s

Images and other external data

Images and other non-HTML information may be stored in a database insof being stored in a file. When the image is requested, the application serretrieves it from the database and hands it on to the Web server.

All of the above An application server can retrieve an HTML document from the databasein part of the document from data stored elsewhere in the database, and provide images and other external resources associated with the documefrom the database.

8


ther

, and

gged s the b

b site

A glance at PowerDynamoPowerDynamo includes Web-site management features and mobile Intranet capabilities.

Building Web applications and managing Web sites

With PowerDynamo, you can embed instructions into any Web page, and process these instructions when providing HTML to a Web client for viewing or interaction. PowerDynamo supports the following kinds of embedded instructions:

•Tags You can embed SQL statements and manipulate returned data within a document.

•SQL statements You can place up-to-date database query results into a Web page.

•Scripts You can include programmatic control (conditional execution, looping, and so on) in your Web pages.

•Text replacement and host variable macros You can respond to HTML forms and other variables supplied by a Web client.

The Web-site management utility, Sybase Central, manages all aspects of dynamic Web content:

• Authoring

• Site management

• Application servers for deployment on a Web site managed by some oWeb server.

• A Personal Web Server for offline access to data and Web documentsfor developing Web site content.

The interpreterAt the core of PowerDynamo is an interpreter which processes specially tainstructions embedded in the HTML pages or other documents, and serveresulting output together with static HTML to an application such as a Weserver.

The PowerDynamo interpreter is built into several components:

• The Web-site management tool, for managing a database-hosted We

• Application servers that link your database and your Web server

9

A glance at PowerDynamo

nt

in to both

ed

re

larly

ting

ase the

eb

sees

ets ide

• The Personal Web Server, for working offline with dynamic Web conte

Web-site managementPowerDynamo includes a Web site management tool for managing HTMLtemplates and connections. PowerDynamo focuses on combining HTML documents with database data, and the Web-site management utility plugsthe Sybase Central database management utility, bringing management oftechnologies under the single roof of Sybase Central, using a consistent interface.

PowerDynamo provides tools for the following management tasks:

• Wizard-based HTML template creation.

• Folder-based arrangement of HTML templates to map onto a file-basWeb site's directory structure.

• Syntax-highlighting editor. HTML tags, embedded SQL, and scripts aall highlighted.

• Browsing and syntax highlighting of output HTML.

• Scheduled processing of scripts and templates. This process is particuuseful for pages that would take a long time to generate.

Sybase Central requires either the Windows 95 or the Windows NT operasystem.

The Web-site management utility is a plug-in to the Sybase Central databmanagement tool, so that you manage your data and your Web site from same Sybase Central interface.

HTML templates and scriptsDynamo can work with static Web documents and two types of dynamic Wpages: HTML templates and scripts.

Templates can include not only static HTML, but instructions that are interpreted when a document is requested by a Web client. The client thenthe results of those instructions.

The PowerDynamo executes SQL statements against a database, interprscripts internally, and can use text replacement and host variables to provclient/server interactions.

10


any e up- the

to

clicks in the egory.

Scripts are ECMAScript that generate HTML. ECMAScript is a standardized version of Javascript. JavaScript is a compact, object-based scripting language for developing client and server Internet applications.

For more flexibility over template content, PowerDynamo provides the DynaScript language. DynaScript is a JavaScript compatible language. You can embed DynaScripts in templates, but they can also be stored as standalone scripts, with no container HTML document.

For information about JavaScript, see the Netscape JavaScript Authoring Guide at the following URL:

http://home.netscape.com/eng/mozilla/3.0/handbook/javascript/

Script language imposes no restrictions on Web clientJavaScript was developed by Netscape primarily for interpretation at the Web client, not at the Web server, and consequently JavaScript has been tied to the Netscape Navigator browser. In PowerDynamo, appropriately tagged DynaScript scripts are interpreted at the server, and only the output HTML is sent to the Web client. The PowerDynamo inclusion of a JavaScript-based language as its scripting language places no restrictions on the Web clients that can use the system.

Embedding dynamic content in a templateSQL queries in a template

With PowerDynamo, you can embed SQL queries in an HTML or XML template. This allows you to provide flexible and controlled intranet or Internet access to your organization’s data.

For example, you might develop a template that contains a query for compproducts, product descriptions, pricing and availability. Users can then seto-the-minute information that is generated in response to the request forpage.

With support for text substitution and host variables, you are not limited tostatic SQL statements. Instead, SQL statements can be built in responseinput from a Web client.

For example, you could provide a Web template with a list box containingcategories of products. When the user selects one of these categories anda button, the Web client sends a request containing the selected categoryURL. In response, the application server constructs a query limited to theselected category and sends back a table of company products in that cat

11


one

ere

ent

Text substitution and host variables

To enable real interaction between a Web client and the Web server, an action at the client (clicking on a button after filling out a form, for example) must send information to the Web server, and this information must be used by the application server in formulating its response. PowerDynamo supports this function using: text substitution macros and host variables. Both are sent to the Web server as part of the address when a link or button in the client is clicked.

You can include a macro in an HTML template. This macro is expanded by the interpreter when the template is processed, being replaced by its value.

The value of a macro is defined in the URL when the page is accessed. The following example shows how text substitution works.

1 A user at a Web client fills out an HTML form to subscribe to a service. The form includes fields for their first and last name.

2 When the form is sent to the Web server, the user’s entry is sent along with the request in the URL. The standard form for such an inclusion is:

http://www.organization.com/template-name?firstname=Jane&lastname=Smith

3 In the HTML template, the symbol $firstname is replaced by Jane and the symbol $lastname by Smith wherever they appear. For example, a returned acknowledgment may include the text:

Dear Jane Smith,Thank you for your registration. Your registration number is 123-456.

For more information about text substitution, see “Passing variables from document to another” on page 52.

For more information about text substitution with DynaScript, see “value property” in PowerDynamo Reference.

While text substitution macros are ideal for general-purpose substitution, thare some circumstances where a similar but alternative method has performance advantages. Host variables can be specified in a SQL statemand the statement could be executed repeatedly without being reparsed, providing significant performance improvements.

12


The data storeQueries embedded in a template are executed against a database. This can be any single data source, and the SQL statement must conform to the SQL supported by the database. The queries are executed against one and only one data source, and this may be the same or a different database than the one in which the templates themselves are stored.

The template repositoryThe PowerDynamo application server allows templates to be held in a data source that can process Transact-SQL queries or in the file system. The two supported databases for template storage are Sybase Adaptive Server Anywhere and Sybase Adaptive Server Enterprise. PowerDynamo can use an ODBC connection for each of these database management systems or an Open Client connection for the Adaptive Server Enterprise database management system. The database need not be the same one as the one holding the data referenced in SQL statements embedded in the templates.

Although it is held in a relational database, a database-based template repository is organized according to a folder-based motif, which mimics a file system organization. This structure allows easy import and export of Web sites between the database and a file system, so that you can continue to use tools geared to managing and working with file-based Web sites and information, and yet gain the benefits of a database-hosted Web site.

How the pieces fit togetherThe application server takes an HTML template from the template repository, processes script instructions embedded in this template, fetches data as required from the data store, and passes a finished HTML document to the Web server for relaying to the Web client.

13


14

C H A P T E R 2 Getting Started with PowerDynamo

About this chapter This chapter contains a set of tutorials that introduce you to the core features of PowerDynamo.

Contents Topic Page

Overview 16

Looking at the sample Web site 20

Creating a template 22

Creating a script 25

Viewing template output in a browser 27

15

Overview

ase

the

) on al

e on

ite eb

gh n on a

g as

st a on to

ng

k,

OverviewThe tutorials in this chapter guide you through:

• Inspecting the sample Web site included in PowerDynamo, using SybCentral.

• Creating a dynamic HTML page containing a SQL query and viewing results of the query.

• Creating a template containing a script.

• Accessing the templates you have created from a Web client (browseryour own machine. This tutorial introduces the PowerDynamo PersonWeb Server.

• Accessing the templates you have created from a Web client elsewhera network.

Topics covered in other chapters

This chapter does not include how to incorporate a PowerDynamo Web sinto an existing Web site managed by a Web server – see “Configuring WServers and Web sites” on page 71.

Also, this chapter does not cover development of a mobile intranet, althoumany of the concepts and tools you need are covered. For more informatiomobile intranets and SQL Remote replication technology, see “Setting UpMobile Intranet” on page 241.

Before you beginBefore you begin, note the following:

• Most of these tutorials can be carried out on a single computer, as lonthe sample database can be accessed from your machine.

If you are running PowerDynamo in a client/server environment againdatabase server on a different machine, you need a network connectithat machine.

• Before running the tutorials, install the sample database. See “Installithe sample database” on page 17.

• For the tutorials involving a browser, you need a TCP/IP protocol stacand for the final tutorial you need a connection to a network.

16

CHAPTER 2 Getting Started with PowerDynamo

ice

Installing the sample databaseInstalling the sample database is different whether you are using Adaptive Server Anywhere or Adaptive Server Enterprise.

Installing the sample database [Adaptive Server Enterprise]

The tutorials are based on a sample Web site, which is hosted in the Powersoft sample database. You must install the Powersoft sample database before you can run the tutorials.

The sample database is two SQL scripts with a controlling batch file, named psdemodb.bat. The psdemodb.bat file is installed into the PowerDynamo\psdemo directory.

The SQL scripts carry out the following tasks to create the sample database. Use command-line arguments to the batch file to control the settings.

1 Drops the psdemodb database from the server, if it exists.

2 Creates a 4MB device named tempdb_dev for the tempdb database on the server.

3 Adds a 4MB log to tempdb from the new tempdb_dev device.

4 Creates a 14MB device named psdemodb_dev.

5 Creates a database named psdemodb on the server, using the psdemodb_dev device, and fills it with data.

❖ To install the sample database:

1 Ensure that you can connect to Adaptive Server Enterprise and have a valid user ID and password with permissions to create a database.

2 From an operating system command prompt, run the psdemodb batch file, using these arguments:

• The tempdb device location and file name.

• The tempdb device number. You should use the first free device number.

• The psdemodb device location and file name.

• The psdemodb device number. You should use the second free devnumber.

• The server name.

• The system administrator user ID.

17

Overview

ault

erver rver

tion tup dify it ource.

rom

r you e.

lient 38.

base ple.

4.0 ows

• The system administrator password.

For new Adaptive Server Enterprise installations, you can use the defsystem administrator user ID, which is sa, and omit the password argument, as the default password is empty. The default name of the sis the name of the machine on which it is installed. For an Adaptive SeEnterprise newly installed on a machine named my_machine, a typical command line is (you should type this all on one line):

psdemodb c:\syb11\data\tempdb.dev 8 c:\syb11\data\psdemodb.dev 9 my_machine sa

Modify the installed ODBC data source

PowerDynamo is able to use an ODBC interface or an Open Client connecto access Adaptive Server Enterprise. The Adaptive Server Enterprise secreates an ODBC data source for the sample database, but you must moto reflect the name of the installed server before you can access the data s

❖ To modify the ODBC data source for the sample database:

1 Start the ODBC Administrator and select Sybase System 11 Sample fthe list of available data sources. Then click Setup.

2 Change the server name for the data source to the name of the servehave installed. By default the server name is the name of the machin

3 Click OK on the Driver Setup window to create the data source.

For information on how to connect to the sample database using an Open Cconnection see “Creating a connection profile for your Web site” on page

Installing the sample database [Adaptive Server Anywhere]

The Adaptive Server Anywhere Setup automatically installs a sample datanamed sademo.db, and creates an ODBC data source named ASA 6.0 SamNo further preparation is required.

Starting Dynamo programsThe Dynamo programs are installed into the Start Menu for Windows NT and Windows 95, and are installed into a Program Manager group for WindNT 3.51.

18


h the

For users of Windows 95 or Windows NT 4.0, the Dynamo programs are added to the Start Menu, under Programs | Sybase | PowerDynamo 3.5. For users of Windows NT 3.51, the programs are added to the PowerDynamo 3.5 program group.

PowerDynamo is accessible through Sybase Central. Sybase Central can be started either from within the Sybase program group (Start | Programs | Sybase | Sybase Central) or from within the PowerDynamo program group under the heading of Manage PowerDynamo (Start | Programs | Sybase | PowerDynamo 3.5 | Manage PowerDynamo).

Creating the sample Web siteIn Sybase Central, when you connect PowerDynamo to a database that does not have a Web site stored for the user ID and database, Dynamo asks you if you wish to create a Web site for the supplied user ID.

❖ To create the sample Web site:

1 Start Sybase Central, and select Tools | Connection Profiles.

2 Select the Dynamo Demo connection profile from the list.

3 Click Connect. Because no Web site exists on the sample database for the user ID you have specified, Dynamo prompts you to add a Web site. Click Yes to create a new Web site.

Check the boxes to load the documentation and samples and enter a name for the main document folder in the site. The documentation refers to this folder as “Site”. Click OK to create the site.

Once you have created the sample Web site, you are ready to continue witrest of the tutorials.

19

Looking at the sample Web site

Looking at the sample Web siteIn this tutorial you connect to the Dynamo sample Web site using Sybase Central, and survey the structure and content of that Web site. After completing this tutorial, you should understand the components that make up a PowerDynamo Web site.

Connecting from Sybase Central to the sample Web siteLocating Sybase Central on your desktop

If you are using Windows 95 or Windows NT 4.0, select Start | Programs | Sybase. You can also start Sybase Central from within the PowerDynamo program group by selecting Manage PowerDynamo.

If you are using Windows NT 3.51, Sybase Central is installed into a program group with the other software in this package. For example, if you are using PowerDynamo as part of Sybase Adaptive Server Anywhere Professional, you will find Sybase Central in the Sybase Adaptive Server Anywhere Professional program group.

❖ To connect to the sample Web site:

1 Start Sybase Central.

2 Select Tools | Connection Profiles.

3 Select Dynamo Demo from the list of connection profiles, then click Connect to connect to the Web site.

4 If you have previously connected to this Web site, the Web site is listed in the left pane of the Sybase Central window under the PowerDynamo icon.

If you have not previously connected to this Web site, you are prompted to create a new site. Click Yes. Enter Site for the name of the main contents folder, and check the boxes to import the samples and documentation. Click OK to create the Web site.

20


ral user

cases, that

der, ssed

Navigating the sample Web siteSybase Central has an Explorer-like interface. The left pane is a tree view of containers. The top-level containers are the various products that Sybase Central can manage (Adaptive Server Anywhere, Adaptive Server Enterprise, PowerDynamo, and so on). Within each of these product containers is a set of database servers or Web sites. The contents of each of these servers or sites is contained hierarchically within the container.

❖ To display the structure and contents of the sample Web site:

1 Open your Web site container in the left pane. You can do this by clicking the + icon next to the folder or double-clicking the folder itself.

Two folders are displayed: Connections and Site. The Site folder is also called the main contents folder.

2 Open the Site folder to explore the contents of the Web site.

The contents of the sample Web site

The Site folder contains the HTML templates and scripts for the Web site. Although this main content folder is named Site in the sample site, it may have a different name for each site.

If you open the main content folder (in this case Site), you will see folders named app, doc, images, and system.

• The app folder contains a sample application, which contains many examples of useful techniques for using PowerDynamo.

• The doc folder contains HTML documentation for PowerDynamo.

• The images folder contains the images for PowerDynamo.

• The system folder contains a set of PowerDynamo scripts that are automatically built into each new Web site to control the Sybase Centenvironment. Do not alter system scripts unless you are an advancedwanting to customize your Web site administration environment.

The contents of the Connections folder are used to provide access to thedatabase data that is queried or accessed from the Web clients. In some and in this set of tutorials, the database containing the site is the same ascontaining the data.

In summary, a Web site consists of documents, held in a main content foland data that may be in the same or different data sources, which is acceusing the connections in the Connections folder.

21

Creating a template

rice

r.

Creating a templateIn this tutorial you create an HTML template that includes a SQL query. A Web client accessing this template will receive the formatted results of the SQL query.

❖ To add a template to your Web site:

1 From Sybase Central, connect to the Dynamo Demo Web site.

2 In the left pane, click the Site folder. You may have to expand the Web site container to do this.

3 In the right pane, double-click Add Template.

4 Enter a name for the template; for example, Products. Do not use any spaces. Click Next.

5 Enter a description, for example, A test template. Click Next.

6 If you have more than one connection type you will be asked to pick a connection.

7 On the Add SQL Query page, click Select. The SQL Query Editor is displayed. The SQL Query Editor is a tab window that allows you to manipulate and enter clauses of the SELECT statement. The Test tab allows you to Test the query before continuing.

• On the Table tab, add product to the list of selected tables.

• On the Columns tab, add name, description, size, color, and unit_pto the list of selected columns.

• On the Sort tab, add name, size, and color to the Sort By list.

• Select the Test tab, check the SQL statement, and click Test. Theresults of the query display in the lower window. Verify that the results are correct, and click OK.

• Click Next to complete the query.

8 Select HTML as the document type.

9 Select Table with Headings from the list of supplied formats.

10 Click Finish to add the template to the Web site.

You can display the HTML in the Sybase Central syntax-highlighting editoThe editor color-codes HTML tags, SQL syntax, and script syntax, makingediting and viewing of templates easier.

22


eb

e

se.

base.

.

ent.

Templates are created with default extensions of .stm. We recommend that you keep this extension for all your templates.

The query and formatting instructions are included in the HTML as specially formatted HTML comments.

❖ To view the template output:

1 Right-click on the template.

2 Select View Output from the pop-up menu to display the results of the query in the Sybase Central syntax-highlighting editor.

The output displays the formatted results of the query instead of the query and the formatting instructions.

You can also send the output to your browser by selecting Browse Output from the pop-up menu. For more information see “Viewing template output in a Wbrowser” on page 49.

❖ To edit the template using the Sybase Central editor:

1 Double-click on the template to display it in the Sybase Central highlighting editor.

2 Add a paragraph in front of the table. For example, you could enter thfollowing text after the </H1> tag that marks the end of the heading:

Table of Products

3 Click the database icon on the toolbar to save the script to the databa

Save templates to a databaseMake sure that you do not save the template to a file, but save it to the data

How dynamic content is held in HTML templatesDynamic content is embedded in an HTML template as HTML commentsThis allows you to use Web page authoring tools to refine the static components of your Web pages without interfering with the dynamic cont

An HTML comment is marked by the following delimiters:



23

Creating a template

A SQL statement is identified by a special comment marker, as follows:



A SQL statement with formatting instructions is embedded as follows:

( table instructions here )

A script is embedded as follows:



For more information see the chapter “Dynamo Tags” in the PowerDynamo Reference.

24


ys

t.

ript

Creating a scriptIn this tutorial you create an HTML template that includes a script. Scripts provide programmatic control over the content of the HTML page. For example, they can be used to respond to forms filled out and submitted from a Web client.

❖ To add a script to your Web site:

1 From Sybase Central, connect to the PowerDynamo sample site.

2 In the left pane, click the Site folder. You may have to expand the Web site container to do this.

3 In the right pane, double-click Add Script.

4 Enter a name for the script, for example, Test. Do not include any spaces. Click Next.

5 Enter a description; for example, “A test script”.

Click Finish. A script icon named test.ssc is added to the right pane of Sybase Central.

6 Double-click test.ssc to edit the script. The Sybase Central editor displaan empty script template:



7 Add lines to the script, so it reads as follows:



These instructions write text into the document produced by the scrip

For information about the Dynamo script language, see “The DynaScLanguage” in PowerDynamo Reference.

8 Click the database icon to save the script.

❖ To view the script output:

1 From Sybase Central, right-click on test.ssc.

25

Creating a script

2 Select Execute from the pop-up menu. The output displays in the Sybase Central syntax-highlighting editor.

26


sing

amo

rver

eb n

ite rver Web

b ing

hey he n the

Viewing template output in a browserYou can access a PowerDynamo Web site in several ways:

• During development, you can access the site locally (on the same machine) or across a client/server connection (on the same machine) uSybase Central.

• You can access the site locally using a Web client and the PowerDynPersonal Web Server.

• You can access the site across the Internet or other network from anybrowser or Web client, using the Personal Web Server as the Web sefor the site.

• You can access the site across the Internet or other network from a Wclient, using a third party Web server and a PowerDynamo Applicatioserver to link the PowerDynamo Web site to the Web server.

In previous tutorials, we have been using Sybase Central to access the slocally. In this tutorial we first use a Web browser and the Personal Web Seto access the site locally, and then use a Web browser and the Personal Server to access the site across a local-area network.

Browser and TCP/IP requiredYou must have a Web browser or other Web client to run this tutorial.

Web browsers require a TCP/IP protocol stack to communicate with a Weserver, even if the server is on the same machine and there is no intervennetwork. You must have TCP/IP installed to use PowerDynamo.

Accessing the Web site locallyWeb clients generally access data across the Internet or other network. Texchange information with a Web server, which relays the information in taddressed document to the Web client. In this tutorial, the Web server is osame computer as the browser or other Web client.

❖ To access data in the PowerDynamo sample Web site from a browser or other Web client:

1 Start the Personal Web Server.

• Open the Utilities folder in the left pane of Sybase Central.

27

Viewing template output in a browser

ase

at ing.

s the

ssed

g

a

.1

ta in te” b

ser.

• Double-click the Personal Web Server icon in the right pane of SybCentral.

• The Personal Web Server will be displayed as a small “tray icon” the opposite end of the taskbar from the Start menu when it is runn

The software installation configures the Personal Web Server to accesPowerDynamo sample Web site, so that no further configuration is needed.

2 Start your browser or other Web client.

3 Type the following URL into the address field of your browser or Webclient:

http://localhost/Site/products.stm

The products template output, including the results of a query, is proceby the Web server and displayed in your browser.

Notes • The http:// part of the URL defines the protocol to use when exchangininformation.

• The localhost part of the URL directs the Web client to access data fromWeb server on the local machine. In our case, this Web server is the PowerDynamo Personal Web Server.

If you are not connected to a network, localhost may not be recognized. If this is the case, you can either:

• Substitute localhost with your machine's IP address, or

• Modify your hosts file to map the host name localhost to the 127.0.0address.

127.0.0.1 localhost

• The Site part of the URL directs the Personal Web Server to access daa PowerDynamo Web according to the information specified for the “Simapping. For more information about mappings, see “Configuring Wesites” on page 100.

• products.stm directs the Personal Web Server to access the products.stm template from the Web site, process it, and return the output to the brow

28


“tray onal

ng use

ssed layed

m tory

Accessing the Web site over a networkAlthough the Personal Web Server is designed primarily for testing and development work, and for same-machine (local) access to Web data, it can be used as a normal Web server and accessed from other machines on a local network or over the Internet.

With its small footprint, and its simplicity, the Personal Web Server is suited for use for an Intranet site server for workgroups. Workgroups can use Intranet sites as a place to share information. If the workgroup grows to the point that the 10 connection limit of the Personal Web Server is no longer sufficient, a third party web server should be used.

This tutorial shows how to access Web information on a Personal Web Server across a local-area TCP/IP network.

Required facilities: You require a local-area TCP/IP network and a Web browser to follow this tutorial.

❖ To access Web information on a Personal Web Server across a network:

1 Ensure your Personal Web Server is running (there should be a small icon” at the opposite end of the taskbar from the Start menu if the PersWeb Server is running).

2 Take note of the IP address or the name of the machine on which thePersonal Web Server is running. A typical IP address is of the followiform: 123.45.67.220. If you are using domain name services, you canthe machine name instead of the TCP/IP address.

3 Start a Web browser on another machine on the network.

4 Enter the following URL in the browser:

http://ip-number/Site/products.stm

or

http://machine name/Site/products.stm

The products template output, including the results of a query, is proceby the Personal Web Server and relayed across the network to be dispin your browser.

Notes • The ip-number part of the URL directs the Web client to access data froa Web server on the specified machine. If you are using network direcservices, you could use the machine name instead of the IP address.

29

Viewing template output in a browser

ta in e

n

he

• The Site part of the URL directs the Personal Web Server to access daa PowerDynamo Web site according to the information specified for th“Site” mapping.

For more information about mappings, see “Configuring Web sites” opage 100.

products.stm directs the Personal web Server to access the products.stm template from the Web site, process it, and return the output across tnetwork to the browser.

30

C H A P T E R 3 Working with Dynamo Web Sites

About this chapter This chapter describes some basic elements of managing PowerDynamo Web sites.

For information on Web server configuration issues, see “ConfiguringWeb Servers and Web sites” on page 71.

Contents Topic Page

Working with Web sites 32

The Utilities folder 41

Working with folders and documents in your Web site 42

Working with templates 46

Scheduling actions 57

Working with connections 60

Copying a Web-site database [Adaptive Server Anywhere] 69

Using the Performance Monitor 70

31

Working with Web sites

ith a

This

to

b ther,

Working with Web sitesYou create and work with Web sites using Sybase Central. Because PowerDynamo plugs into Sybase Central you can manage both your databases and your Web sites from within Sybase Central.

What is a Dynamo Web site?

A Dynamo Web site consists of:

• A set of documents stored in a database or in files on disk, together wconnection specification (including user ID) for a database.

• A set of data referenced by SQL statements included in the templates.data is stored in an ODBC or Open Client database.

• A set of connections used by the PowerDynamo Application Server toaccess the data.

Web site architectureHow documents are stored

Dynamo Web sites include:

•Documents These may be templates, scripts, or HTML documents.

•Database data The data that fills out queries in templates.

•Connections To access the data.

Web site documents are usually stored in an Adaptive Server Enterprise or Adaptive Server Anywhere relational database in a set of tables. However, the structure of these tables is hidden from the user by the PowerDynamo application server. Web sites may also be hosted in the file system.

The data may be contained in an Adaptive Server Enterprise or Adaptive Server Anywhere database, or in some other ODBC or Open Client data source.

Hierarchical views of documents

Sybase Central provides a hierarchical view of a Web site, just like a directory structure. A hierarchical architecture has advantages for a Web site:

• The URL, the address of documents on the World Wide Web, uses a hierarchical model. A hierarchical structure is required for URL accessthe documents.

• You can import whole directory trees of HTML files into a Dynamo Wesite database, and maintain hypertext links from one document to anoas long as these links are coded as relative addresses, not absolute.

32

CHAPTER 3 Working with Dynamo Web Sites

g a

to a age

ing ntral

l

ate a rk. s the

eate base

tral

BC

Storing documents on disk

Not all the documents in a site need be held in a database. Web sites can also contain documents stored in folders on disk.

For information about creating dynamic file-based Web sites see “Creatindynamic file-based Web site” on page 36

For more information about storing documents on disk and linking these indatabase-hosted Web site, see “Linking folders to directories on disk” on p43.

Before you beginYou should be familiar with the basics of using Sybase Central for managdatabases. For assistance with using Sybase Central, see the Sybase Ceonline help for Dynamo.

Creating a Web site [Adaptive Server Anywhere]You create Dynamo Web sites from Sybase Central, the management tooincluded in Dynamo, Adaptive Server Anywhere, and Adaptive Server Enterprise.

Web site created at the server

Sybase Central is a client application. You can use Sybase Central to credatabase-hosted Web site on a database residing anywhere on the netwoThere is no requirement for Sybase Central to run on the same machine adatabase server.

❖ To create a Web site from Sybase Central [Adaptive Server Anywhere]:

1 If you do not wish to use an existing database to hold the Web site, cra database to hold the Web site. You can do this using the Create Datautility, which is in the Sybase Adaptive Server Anywhere container in Sybase Central.

For more information about creating a database, see the Sybase Cenonline help and “Working with Database Objects” in the Adaptive Server Anywhere User’s Guide.

2 Start Sybase Central.

3 Create an ODBC data source definition for this database. Use the ODAdministrator from the Utilities folder in Sybase Central.

33


he al)

g

list

re

a

ou

se,

lder

o the

DBA r base.

For more information about creating an ODBC data source, see “Connecting to a Database” in the Adaptive Server Anywhere User’s Guide.

4 Create a connection profile for your Web site.

1 Select Tools | Connect Profiles.

2 Click New. In the Create New Profile window, enter the name of tprofile (this name is used to identify the Web site in Sybase Centrand select PowerDynamo as the type. Click OK.

3 Fill in the fields in the Connection Profile window. If you are creatinan ODBC connection profile, you would:

• Select the data source you have created from the drop-downof ODBC data sources,

• Enter a valid user ID. Adaptive Server Anywhere databases acreated with a single user, with DBA authority. The user ID isDBA and the password is SQL.

4 When you have filled in all fields, click OK.

For information on creating File connection profiles, see “Creatingconnection profile for your Web site” on page 38.

5 From the Connection Profile window, highlight the connection profile yjust created and click Connect.

6 If no Web site exists for the user ID you have specified on the databaDynamo prompts you to add a Web site.

• Enter a name for the site. This is the name of the main contents foon the site.

• Select the appropriate boxes if you want to load the PowerDynamdocumentation and samples into the Web site. Click OK to createsite.

7 To configure this Web site to be accessible from a Web server, see “Configuring Web sites” on page 100.

Notes • Only one Web site per user can be created in a database; for example,can create only one Web site in the sample database. A new user; foexample DBA2, can create another Web site in the same sample data

34


ll in ner d as in

l

ate a rk. s the

t to

ou

nd

as

.

ese

r ID

• The connection information (database, user ID, and so on) that you fiwhen you first connect to the Web site serves two functions. It is the owof the tables containing the template and script data, and it is providea connection called <default> which can be used for data referenced queries in templates.

Creating a Web site [Adaptive Server Enterprise]You create Dynamo Web sites from Sybase Central, the management tooincluded with Adaptive Server Enterprise.

Web site created at the server

Sybase Central is a client application. You can use Sybase Central to credatabase-hosted Web site on a database residing anywhere on the netwoThere is no requirement for Sybase Central to run on the same machine adatabase server.

❖ To create a Web site from Sybase Central [Adaptive Server Enterprise]:

1 From Sybase Central, connect to the Adaptive Server where you wancreate the Web site, or create a new database.

2 Now you need to connect to the database as a Web site. To do this, ymust connect using a Dynamo connection, not an Adaptive Server Enterprise connection, within Sybase Central.

3 Create a connection profile for your Web site.

1 Select Tools | Connect Profiles.

2 Click New.

3 In the Create New Profile window, enter the name of the profile aselect PowerDynamo as the type. Click OK.

4 Change the connection type to Open Client.

5 Fill in the fields in the Connection window:

• Enter a descriptive name in the Connection Name field, suchMy First Site. This name is used to identify the Web site in Sybase Central. You can use spaces in the name if you wish

• Enter the names of the server and database to connect to. Thnames are case sensitive.

• Enter a valid user ID and password for this database. The usemust have the permissions necessary to create tables.

35


se,

lder

the

DBA r base.

l in ner d as n

n any

base

-ill

When you have filled in all fields, click OK.

For information on creating ODBC and File connection profiles, see “Creating a connection profile for your Web site” on page 38.

4 Highlight the connection profile you just created and click Connect.

5 If no Web site exists for the user ID you have specified on the databaDynamo prompts you to add a Web site.

• Enter a name for the site. This is the name of the main contents foon the site.

• Select the appropriate boxes to load the PowerDynamo documentation and samples into the Web site. Click OK to createsite.


Notes • Only one Web site per user can be created in a database; for example,can create only one Web site in the sample database. A new user; foexample, DBA2, can create another Web site in the same sample data

• The connection information (database, user ID, and so on) that you filwhen you first connect to the Web site serves two functions. It is the owof the tables containing the template and script data, and it is providea connection called <default> which can be used for data referenced iqueries in templates.

Creating a dynamic file-based Web site You can use Sybase Central to create a file-based Web site that resides odrive that is accessible (locally or via a network) from the machine where Sybase Central is running. File-based sites dynamically connect to a dataand retrieve data.

CautionAll files in the target directory will be deleted when creating a dynamic filebased Web site. If there are read-only files in this directory the Web site wnot be created.

❖ To create a file-based Web site from Sybase Central:

1 Create a directory for store your Web site.

36


eb

and

them

older

f the

nts

query.

2 From Sybase Central, select Tools | Connect.

3 In the connection profile window:

• Select a connection type of Dynamic File.

• Enter the name of the connection that you are making.

• Enter the path to the file-based site.

Click OK.

4 If no Web site exists in the directory, Dynamo prompts you to add a Wsite.

5 Select the appropriate boxes to load the PowerDynamo documentationsamples into the Web site, and click OK to create the site.


Notes CautionFile-based Web sites store database passwords as plain text which makesaccessible through the file system.

Retrieving data from a database with a dynamic file-based Web site

After you have created a dynamic file-based Web site, you must create aconnection to the database and specify the connection name in the root fof the file-based Web site.

❖ To retrieve data from a database:

1 Use Sybase Central to connect to your file-based Web site.

2 Open the Connections folder of the Web site.

3 Create a connection to the database you want to retrieve data.

4 Right-click on the root folder of your file-based Web site and select Properties.

5 Select the connection that you just created from the pull down menu oConnection field.

6 Click OK.

Alternatively, you can create DynaScript connections in your Web documeto connect to a database and retrieve data. The following script uses the connection myConn (connects to the sample database) to execute a SQL

37


<HTML><TITLE>testthis.stm</TITLE><BODY><H1></H1><TABLE BORDER><TR><TH>last_name</TH><TH>first_name</TH><TH>title</TH></TR><TR><TD></TD><TD></TD><TD></TD></TR></TABLE></BODY></HTML>

Creating a connection profile for your Web siteYou should create a connection profile for your Web site from Sybase Central. When you create a connection profile, the connection information is stored in the registry in encrypted form. This information is used not only in Sybase Central, but also by the Dynamo application server as database provider profiles.

There are three types of connection profiles that you may create:

•ODBC connection profile Used for connecting to Adaptive Server Anywhere or Adaptive Server Enterprise Web sites.

38


t.

he

•Open Client connection profile Used for connecting to Adaptive Server Enterprise Web sites.

•Dynamic File connection profile Used for connecting to Web sites that are hosted on disk.

Consistency with connectionsA Web site should always be connected to with the same type of connection as was used for the original creation of the site. For example, if the sample Web site was created with an ODBC connection, it should not later be connected to with an Open Client connection

❖ To create a connection profile:

1 From Sybase Central, select Tools | Connection Profiles. The Connection Profiles window is displayed.

2 Click New. The Create New Profile window is displayed.

3 Enter a name for the connection profile, and select PowerDynamo from the list of available types. Click OK. The Connection window displays.

4 Select a connection type.

• For ODBC:

a Fill in the fields in the Connection window, and click OK to create the profile.

• For Open Client:

a Enter the name of the server to which you wish to connect.

b Enter the name of the database to which you wish to connec

c Fill in your user ID and password, and click OK to create the profile.

• For Dynamic File:

a Enter the path to the File-based site, and click OK to create tprofile.

39


The Select MethodWhen you are creating an ODBC data source for an Adaptive Server Enterprise database the Select Method must be set to 0 - Cursor for Dynamo to work. The Select method setting is located within the ODBC Administrator | ODBC Sybase | Driver Setup | Performance Tab.

Regenerating a Web siteWhen you regenerate a Web site, the existing content of the Web site is deleted, and a new Web site is created.

❖ To regenerate a Web site:

1 With the right mouse button, click the Web site icon in the left pane of Sybase Central, and select Regenerate from the menu.

2 Enter a name for the main contents folder in the Web site setup window, and select the appropriate options to include the Dynamo documentation and sample application in the site. Click OK to regenerate a clean Web site.

CautionRegenerating a Web site deletes the entire content of the Web site. This action cannot be undone.

Deleting a Web siteWhen you delete a Web site, the existing content of the Web site is deleted. If the database containing your Web site has other data, it is not affected by the deletion of the Web site. Also, the database itself is not deleted.

With the right mouse button, click the Web site icon in the left pane of Sybase Central, and select Delete from the menu.

CautionDeleting a Web site deletes the entire content of the Web site. This action cannot be undone.

40


00.

lity

The Utilities folderThe Dynamo Utilities folder contains several utilities used for creating, maintaining, and configuring Web sites. These utilities include:

•ODBC Administrator Used to create and administer ODBC connections.

•Personal Web Server Used for testing and developing applications. For more information see “The Personal Web Server” on page 72.

•Helper Application for CGI Used in conjunction with CGI or WIN-CGI Web servers.

•Configuration folder Includes folders that allow you to configure certain aspects of your Web sites, for example, cookie time-outs, and port numbers. For more information see “Configuring Web sites” on page 1

Starting the utilities

❖ To start one of the utilities from Sybase Central:

1 Click on the Utilities folder in the left pane of Sybase Central.

2 Double click on the icon in the right pane of Sybase Central for the utiyou want to start.

41

Working with folders and documents in your Web site

Working with folders and documents in your Web siteWhen you create a Web site, two folders are automatically placed into the Web site:

•Connections The connections folder holds user-defined connections. You can create new connections from this folder by double-clicking the Add Connection wizard, which is contained in this folder.

•Main contents folder You specify the name of the main contents folder when you create your Web site. You should place all the content you wish to create inside this folder. The main contents folder may contain the App, Doc, Images, and System folders, depending on the options you select when creating your Web site. The System folder contains scripts used for site management purposes. Do not alter or execute directly scripts contained in the system folder unless you are an experienced user of PowerDynamo.

Once you start adding content to your Web site, you may want to create additional folders.

Creating foldersTo add a folder to a Web site:

1 Use Sybase Central to connect to a Web site.

2 Open the folder within which you want to create a new folder.

3 Double-click Add Folder in the right pane.

4 Enter a name for your folder, and click Next. Do not use spaces, as not all Web servers and browsers handle spaces correctly.

5 If your Web site has more than one connection, select the connection for the documents in this folder to use as a default. For more information about connections, see “Working with connections” on page 60.

6 Enter an optional description of the folder, and click Finish.

Moving or copying folders and documentsTo move or copy a folder or document within a Web site:

42


1 From Sybase Central, open the Web site folders until you see the folder or document you want to move or copy.

2 To move the folder or document, drag the icon to the desired location. To copy it, press the Ctrl key while you drag the icon.

Deleting folders and documentsTo delete a folder or document from a Web site:

1 Use Sybase Central to open the Web site folders until the folder or document you want to delete is displayed.

2 Right-click the folder or document, and select Delete from the menu to delete the folder.

CautionDeleting a folder deletes all the contents of that folder and cannot be undone.

Renaming folders and documentsTo rename a folder or document:


2 Open the Web site folders until you see the folder or document you want to rename.

3 Right-click the folder or document and select Properties from the menu.

4 Replace the current name with a new name, and click OK to make the change.

Linking folders to directories on diskYou can store documents that are part of a Web site either in a database or as files in a directory tree. While holding information in a database has many advantages, you may wish to hold some of the material in your database-based Web site as files. PowerDynamo allows you to do this using linked folders. A linked folder is a folder in a database-based Web site that provides access to files stored in a directory on a disk.

43

Working with folders and documents in your Web site

de

ked

ng

e

Linking vs. importingLinking a folder to a directory leaves the Web documents stored physically in the file system; it does not physically import them into the database. Importing a directory or a set of files physically copies the documents into the database.

❖ To create a linked folder:

1 Use Sybase Central to open the Web site folders in the left pane until you see the folder where you want to create the linked folder.

2 Double-click Add Linked Folder in the right pane.

3 Follow the instructions in the wizard to create the linked folder.

Linked FoldersYou cannot create a linked folder inside a linked folder.

Linked folders are applicable only to database-based Web sites.

Working with linked folders

You should be aware of the following behavior when working with the contents of a linked folder:

• When you add a folder within a linked folder, a new subdirectory is maon your disk.

• When you delete a folder within a linked folder, the corresponding subdirectory is deleted from your disk.

• When you create or delete a document (template or script) inside a linfolder, a corresponding file is created or deleted on your disk.

• If you delete the linked folder itself from the Web site, the correspondidirectory is not deleted on your disk.

• If you move a document from a linked folder to an unlinked folder in thWeb site, the corresponding file is deleted from your disk.

• If you move a document or folder to a linked folder, a corresponding subdirectory or file is created on your disk.

44


SQL Remote cannot replicate linked foldersSQL Remote replication technology replicates database content only. It cannot replicate the files stored in a linked folder.

45

Working with templates

27.

ple cts

ple,

ction ing

the

nt

of

gs

Working with templatesTemplates in a PowerDynamo Web site are HTML documents that may include embedded instructions. This section describes how to create, edit, and delete Dynamo templates.

For information about scripts, which are the other kind of dynamic Web content managed by PowerDynamo, see “Writing DynaScripts” on page 1

Creating a templateThis section describes how to add a template to your Web site. The examdescribes a template displaying a table of information about current produsold by the company.

❖ To create a template:


2 In the left pane, select the folder where you want to create the new template. You may have to expand the Web site container to do this.


4 On the first page of the wizard enter a name for the template, for examProducts. Do not use spaces. Click Next.

5 Enter an optional description for the template and click Next.

6 If your Web site has more than one connection, select a default connefor this template. For more information about connections, see “Workwith connections” on page 60.

7 On the Add SQL Query page, click Select and enter the query using query tab window. You can enter a query manually if you wish.

8 Select HTML or XML as the type of document to create.

9 Specify the type of formatting you would like. These options are differedepending on the choice you made in the previous step.

If you chose HTML as the document output, you must provide the typeHTML format you wish to use for the output.

If you chose XML as the document output you are asked to provide tafor the output or to select existing tags.

10 Click Finish to add the template to the Web site.

46


m.

You can view the contents of the template in several ways, as described in “Viewing and editing templates” on page 48.

Selecting an HTML output format for your template

The Add Template wizard provides you with a list of formats to choose fro

•Tables Tables, with or without headings, are useful for queries returning several columns of results.

The default table has a border to separate the data fields. After you have completed the wizard, you can customize the attributes of the table using a Web authoring tool or Sybase Central.

•Definition List A definition list displays queries with two columns, as a list. Each list item has a term and a description. For example, you might use a definition list for a glossary:

<DL><DT>Otley<DD>A market town in Wharfedale<DT>Wharfedale<DD>A valley in Yorkshire, U.K.</DL>

If you use the definition list format for a query with more than two columns, any extra columns are concatenated into the description.

•Ordered and unordered lists These types of lists are useful primarily for queries that return a single column. Markings for an ordered and unordered list are dependent on the browser but in most cases an unordered list is marked by bullets and an ordered list is marked by numbers.

•Detail This is useful for queries with any number of columns. Each field is shown on a separate line.

•Link This is most useful for three-column queries. An unordered list of links is created such that column 1 is the link’s URL, column 2 is the text that gets displayed for the link (the part that is usually underlined in the browser), and column 3 (and onward) become the text that is displayed after the link.

•Paragraph This is useful primarily for single column queries: each row of the result set is placed in a separate paragraph.

47


ith

ew

it,

you

itor.

ing

site

m ent

Viewing and editing templatesYou can view and edit templates in several ways from within Sybase Central and from a Web client:

• You can inspect and alter the template source—the HTML together wthe embedded instructions—in the Sybase Central syntax-highlightingeditor.

• You can view the output of a document in the Sybase Central editor.

• You can use a Web client together with the personal Web server to vithe template as users will see it.

• You can export the template to a file and use an HTML editor to alter and then import the file back into the database.

Viewing template source in the Sybase Central editor

❖ To view or alter the source of a template:


2 In the left pane, open the appropriate folders until you see the templatewant to work with in the right pane of Sybase Central.

3 In the right pane, right-click on the template, and select Open. The template source displays in the Sybase Central syntax highlighting ed

4 Make any changes to the template, then save it.

Viewing template output in the Sybase Central editor

You can check that your query result contains the data you expect by viewthe output in the Sybase Central editor.

❖ To view the output HTML of a template:


2 In the left pane, click the Site folder. You may have to expand the Webcontainer to do this.

3 In the right pane, right-click on a Template, and select View Output frothe menu. The Sybase Central editor displays the HTML of the documas it would be received by a Web client.

48


The instructions embedded in the template are not present in the output HTML document. Instead, the results of those instructions are displayed along with the HTML tags.

Viewing template output in a Web browser

You can check that your query result contains the data you expect without leaving Sybase Central, and check the formatting of a template, by viewing the output in your Web browser.

❖ To view template output in a browser:


2 In the left panel, open the appropriate folders until you see the required template in the right pane.

3 In the right pane, right-click on a template, and select Browse Execution Output from the menu. The document output is displayed in the browser as it would be received by a Web client.

The instructions embedded in the template are not present in the output HTML document. Instead, the results of those instructions and HTML are displayed.

Limitations of browsing outputThe document output is sent to a file, which is then loaded into your Web browser. Consequently, any links to relative addresses will not work, and any graphics that are given relative addresses are not displayed. It is recommended to use relative addresses and tolerate the discrepancies in output appearance when accessed in this manner. To view output exactly as it would appear to a user, use the Personal Web Server with a browser.

Using a Web authoring tool with PowerDynamo

Web authoring tools (HTML editors) work with HTML files, while PowerDynamo templates are stored in a database. However, you can edit PowerDynamo templates using a Web authoring tool.

This tutorial shows you how to customize the formatting of the template that you generated in the previous tutorial. You must have a Web authoring tool other than the Sybase Central editor.

49


❖ To edit a template using a Web authoring tool or text editor:

1 Use Sybase Central to locate the template you want to edit.

2 Right-click the template and select Export from the menu.

3 Enter a file name for the exported template.

4 Open the file in your Web authoring tool or text editor.

5 Make any changes to the template. Save it, and close your Web authoring tool or text editor.

6 From Sybase Central, right-click the folder where your template resides and select Import from the menu to bring the file back into the database.

7 From Sybase Central, right-click the template and select View Output from the popup menu. This shows the HTML output of the template, including the changes you have made.

When you open the template in a Web authoring tool, the query is not shown. PowerDynamo stores queries in HTML templates as specially marked HTML comments. Storing queries in this manner allows editing by any HTML editor, without interfering with the query.

When you open the template in a Web authoring tool, only the headings and one empty row of the table is shown. PowerDynamo uses specially marked HTML comments to indicate formatting information, and these comments are ignored by Web authoring tools. The single row containing apparently empty cells actually contains the following HTML comment:



Storing formatting in this manner allows editing by any HTML editor, including formatting of the table containing the output.

Embedding instructions in a templateInstructions are embedded in a template as HTML comments rather than as HTML tags.

Embedding SQL in a template

A SQL statement is contained inside an HTML comment. HTML comments are of the following form:



50


All material inside the angle brackets is ignored by an HTML parser such as that included inside a Web client. Thus, a Web client can view a template, and it will ignore the material inside the comment tags. If you edit the template using an HTML authoring tool it will ignore the embedded instructions. Of course, the SQL statements are not seen by a Web client, as they are interpreted and executed by the PowerDynamo Application Server.

SQL statements are embedded in an HTML document as follows:



The SQL statement itself can continue over several lines. It should start on a separate line from the SQL comment tag.

Example The following HTML fragment contains a simple query.



Naming a SQL statement

You can provide an identifying name for an embedded query. This is useful, for example, if you have more than one SQL statement in a template.

To name a SQL statement, provide a name for a SQL statement as the NAME attribute for the SQL comment tag. The following SQL statement has a name of ProductQuery:



The SQL statement itself must start on a separate line from the NAME attribute.

Formatting query results

If the embedded SQL statement is a query, then the Application Server inserts the results of the query into the output document. PowerDynamo allows you to describe the formatting of a query using a formatting comment tag.

The HTML tags for formatting instructions are slightly different from the tags used for SQL statements. To allow an HTML editor to modify and refine the actual formatting, the formatting description is not inside a comment. Instead, comment tags are used for placeholders for the data, which are replaced on processing by the actual data.

51


be n ns.

de ent

eir

ain

Start and end formatting comment tags

All data placeholders must be between formatting start and end comment tags. The formatting start comment tag is of the form



The formatting end comment tag is of the form



Formatting using scriptsIn addition to using formatting comment tags, you can use embedded scripts to format output. The flexibility of scripts allows more varied formatting than the formatting comment tags.

For more information on formatting using scripts, see the chapter “WritingDynaScripts” on page 127.

As these are HTML comments, there is no restriction on the HTML that canincluded between the tags. The formatting comment tags have no effect oHTML that occurs between them; they affect just the embedded instructio

For more information on Dynamo Tags, see the chapter “Dynamo Tags” inPowerDynamo Reference.

Passing variables from one document to anotherYou can use text replacement macros, or text substitution macros, to incluvalues provided by a Web client in document output. For example, a documin your Web site may ask a user to enter their name in an HTML form. Thname can then be used in documents returned from the Web server.

Example This example includes the following:

• A sample form asking the user to enter their first and last names, andsubmitting them to the Web server.

• A reply document that uses the supplied names to address the user.

❖ To create the documents for the example:

1 In Sybase Central, connect to the sample Web site and move to the mcontents folder.

2 Create a new template named form.stm, without entering any query. Thenedit the document so that it has the following content:

<HTML>

52


<HEAD><TITLE>Test of text substitution</TITLE></HEAD><BODY><FORM ACTION="reply.stm" NAME="log" METHOD="GET"><p>Please enter your name.<ul><li>First name: <INPUT TYPE="text" NAME="firstname" SIZE="15"><li>Last name: <INPUT TYPE="text" NAME="lastname" SIZE="15"></ul><p><Center><INPUT TYPE="Submit" VALUE="Register"></Center></p></FORM></BODY></HTML>

This HTML document contains a form, but contains no Dynamo-specific instructions. The <FORM> tag tells the browser to retrieve reply.stm when the user clicks Register.

3 Create a new template named reply.stm, without entering any query. Then edit the document so that it has the following content:

<HTML><HEAD><TITLE>Test of text substitution</TITLE></HEAD><BODY><p>Dear $firstname $lastname,</p><p>Thank you for using our text substitution facility.<p>Yours<p>TextSub Corporation.</BODY></HTML>

The $firstname and $lastname entries are text substitution macros. They are replaced by the values entered in the form when reply.stm is processed.

53


ing

❖ To run the example:

1 Start the Personal Web Server from the Utilities folder in Sybase Central. You will see the Personal Web Server tray icon at the end of your start bar once it is running.

2 Start your browser, and open the URL for the HTML form. If you created the form in the main contents folder of the sample Web site, the address is as follows:

http://localhost/Site/form.stm

3 Enter your first and last names into the fields, and click Register. The entry is sent to the Web server in the URL in the following form:

http://localhost/Site/reply.stm?firstname=first-name&lastname=last-name

4 The reply.stm document is returned, with the proper values placed in for the name. If you entered a name of Simon James, the reply would be:

Dear Simon James,Thank you for using our text substitution facility. Yours TextSub Corporation.

Text replacement macros in scripts

Text replacement macros can be accessed inside scripts, but are accessed in a different manner. The argument is a property of the document object, which is a predefined object. The actual value of an argument named firstname can be accessed inside a script as:

document.value.firstname

For information about using text replacement macros in scripts, see “Passvariables from one document to another” on page 138.

54


the

we

les s

File

o

Importing and exporting documentsPowerDynamo manages Web documents using a hierarchical motif, just like a file system. You can make folders, add documents to a folder, and move or copy documents from one folder to another.

You can also export documents to a file, or import a file into the Web site database. This section describes how to import and export files.

There are several reasons why you may want to move documents between your Web site database and the file system:

• To import HTML documents generated using some other tool. For example, the documentation included with the sample Web site is imported into Dynamo from text files.

• To export documents for editing by Web authoring tools, and to import modified documents.

Importing documents into a Web siteYou can import one or more files or folders into a Web site. In this sectiondescribe how to import a set of files.

❖ To import a set of files into a Web site:

1 From Sybase Central, connect to your Web site.

2 Open the Web site so that a folder into which you wish to import the fiis displayed. For example, you may wish to import documentation fileinto a folder named doc.

3 Right-click on the folder, and select Import from the popup menu. TheImport Files window is displayed.

4 Use the browse options or enter a file name or a directory name in thetext box. Click Add to add this to the Import List.

5 Add other file names or directory names as required. Then click OK timport the files.

55

Importing and exporting documents

Dynamo storage efficiencyThe disk space taken up in a Dynamo database file may not be the same as the space the files take up on disk. Although storage efficiency depends on the particular files you are importing, storing data in Dynamo generally takes less space than storing the same information on disk.

Exporting documents from a Web siteYou can export a document from a Web site as a file or as a folder.

When you export a template or script, the instructions are not executed; the exported file has the same content as the document stored in the database.

❖ To export a document from a Web site:

1 Use Sybase Central to connect to your Web site.

2 Open the Web site so that a document you wish to export to disk is displayed.

3 Right-click on the document, and select Export from the menu. The Export Files window is displayed.

4 Enter the location to which you want to export the document and click OK.

56


Scheduling actionsWith PowerDynamo you can schedule a script or template to be executed periodically.

Scheduling script and template execution provides an alternative way of quickly providing to users the results of queries that take a long time to run. It allows the results to be kept up to date, while allowing quick and efficient access from Web clients.

The output of a scheduled script is stored in the Web site and available to users.

For scheduling to take effect:For scheduling to take effect, the Load at startup and Enable scheduling options must both be selected for the mapping representing this site. These options are visible after clicking the Browse button in the mapping property window.

If the Personal Web server or the Dynamo application server you are using is already running, it must be restarted in order for scheduling to take effect.

❖ To schedule a script:

1 Use Sybase Central to locate the script or template you want to schedule.

2 Right-click the script or template and select Schedule from the menu. This will start the schedule wizard.

3 Select the appropriate time interval from the pull down menu in the wizard.

4 The second screen of the wizard allows you to enter a time interval, at which the document is to be generated. If you do not enter the time interval exactly as specified in the following table default values will be used.

You must use a 24 hour clock to enter time intervals. Time interval values are not case sensitive.

Time Interval (Window 1)

Time Interval Format (Window 2) Example Default

Hourly MM 30 00

Daily HH:MM 21:30 00:00

Weekly Day HH:MM Saturday 21:30 Sunday 00:00

Monthly DD HH:MM 02 12:00 01 00:00

57

Scheduling actions

pre-

u.

ource ed.

File replaced with its output

The file containing the script or template is modified to instead contain the output of the document. In this manner, you can change a script or template from on-demand processing to scheduled processing without changing the URL.

Original file saved to a different location

The contents of the original script or template are saved in a file with the same name but a changed extension. The extension for script source is sss, while the extension for template source is sts. The source is saved in the same directory as the original script.

The contents of the ssc or stm file are altered to indicate that the contents are pre-generated from a scheduled script or template.

The schedule.ssc document in the system directory is altered to add a call to site.Schedule(). This call adds the scheduled document to the list of scheduled documents. The schedule.ssc document is imported by autoexec.ssc.

Scheduling with ISAPI or NSAPI serversScheduling begins when the first request for a script has been made to the Web server. ISAPI and NSAPI Web servers do not load the Dynamo plug-in until it is needed – such as when the first scheduled script is requested.

Removing a scheduled actionYou can unschedule previously scheduled documents. This replaces the generated document with the original script or template. The script is thenprocessed on demand, rather than according to a schedule.

❖ To remove a scheduled action:

1 Use Sybase Central to locate the script or template you want to unschedule.

2 Right-click the script or template and select Unschedule from the men

The script contents are restored to the original document name, and the sdocument that was produced when the document was scheduled is deletAlso, the site.Schedule() line is removed from the schedule.ssc document.

Yearly Month DD HH:MM

June 15 18:00 January 00 00:00

Time Interval (Window 1)

Time Interval Format (Window 2) Example Default

58


Scheduled actions and SQL RemoteAdaptive Server Anywhere users employing SQL Remote should ensure that the Personal Web Server at each remote database is configured so that scheduled actions are not executed. If scheduled actions take place at both consolidated and remote databases, replication errors may occur.

59

Working with connections

rary

costly

user

Working with connectionsPowerDynamo uses a connection pool to store connections, once they have been created, for later use. By storing connections in a connection pool instead of re-creating them each time a connection is required, the processing time required to execute a request is reduced. A small number of connections can service a large number of users.

PowerDynamo has two kinds of connections. User Connections are used to connect to the database to extract data, and Dynamo connections are used to connect to a database-hosted Web site to extract Web documents. Each PowerDynamo connection profile represents a Dynamo connection.

• There are two different types of User connections:

•Permanent types Permanent connections are held in the connection pool until they are requested or timed out. You can find a list of user connections in the Connections folder in Sybase Central. User connection objects may be created within a script with the use of the connection object.

•Temporary Temporary connections are closed and removed when they are no longer required. Create temporary connections using the

x = new connection (name, description, datasource [,userName, password, ODBC, connectParameters]);

constructor.

Permanent user connection definitions should be used when a connection will be requested repeatedly. Temporary connections are available for instances where user-specific credentials are required. Because temporary connections are not stored in the connection pool, they are not as performance friendly as permanent connections. The proper use of connections allows you to limit the size of the connection pool and control the load of the database server.

For an example of how to use temporary connections, see “Using a tempoconnection with the session object” on page 64.

The connection poolCreating database user connections can be one of the most performance processes required by a Web site. To minimize this performance cost, PowerDynamo stores user connections in a connection pool, which allowsconnections to be re-used for a specified period of time.

60


e ext

in the ol s.

er set

tions s, it is ll be tes ing

ction

ll not

ion. e s.

er:

Each time a browser requests a PowerDynamo script, a user connection is either created or retrieved from the connection pool to process the request. If a PowerDynamo script is requested simultaneously by many different browsers, each request requires its own user connection.

Instead of creating a new user connection each time, which would use up valuable processing time, connections are retrieved from the connection pool. User connections are held in the connection pool to wait for the next connection request. If no free connections are available from the connection pool at the time of a request, a new connection is created. Once the new connection is released it too is held in the connection pool – as long as thmaximum number of connections has not been reached – to wait for the nrequest. Once the maximum number of connections have been gathered connection pool, no more connections will be added to the connection pountil the number of connections residing in the connection pool decrease

User connections remain in the connection pool until they time out (in othwords, have resided in the connection pool without being requested for aperiod of time).

The number of connections in the connection pool decreases when connectime out. For example, if a connection has a time out value of five minuteonce that connection has been idle in the connection pool for five minutesclosed and removed from the connection pool. Each time a connection isretrieved and then returned to the connection pool the inactive counter wirestarted. This means that a connection with a time out value of five minumight remain in the connection pool for several hours if it is constantly beretrieved from and returned to the connection pool.

For information on setting connection defaults see “Changing Dynamo configuration settings” on page 106.

Populating the connection pool

When you first start PowerDynamo there are no connections in the connepool. The connection pool is populated through regular Web activity and connection creation. Once the minimum number of connections in the connection pool has been met or exceeded, the number of connections widrop below the set default minimum.

The minimum and maximum number of user connections is set per definitEach user-defined connection (myConnection1 and myConnection2 in thfollowing list), <default>, and <inherited> are all user connection definitionFor example, if you had the following connections in your connection fold

61


of ther less

iated

ted.

For

ion.

• <default>

• myConnection1

• myConnection2

and you set the minimum number of user connections to five, five of eachthe above connection definitions would be held in the connection pool. In owords, once the connection pool was fully populated, there would never bethan fifteen connections.

For information on setting connection defaults see “Changing Dynamo configuration settings” on page 106.

Connection definitionsEach folder, template, and script object has a connection definition assocwith it, and all SQL statements within that object are executed using that connection. The connection definition is assigned when the object is creaYou can override the default connection definition by getting another connection (site.GetConnection) or by using the attributes on a SQL tag. example, if your data is stored in a different database than your Web site content, you may wish to execute SQL statements using another connect

There are four user connection definitions:

•<default> The connection specified when you create a database-based Web site.

•<inherited> The first specified connection, other than <inherited>, as you go up the hierarchy of the Sybase Central tree.

•<no connection> The connection specified when you create a file-based Web site, or for scripts or templates without SQL statements.

•user-defined A user connection created by the user. Each instance of a user-defined connection represents another connection definition.

Creating, deleting, modifying and testing User connectionsYou can use Sybase Central to create, delete, modify, and test user connections.

❖ To create a user defined User connection in Sybase Central:

1 Connect to a Web site.

62


2 In the left pane, click the Connections folder. You may have to expand the Web site container to do this.

3 In the right pane, double-click Add Connection.

4 Follow the instructions in the wizard to create a new connection.

If you have more than one connection, you are prompted for a connection name whenever you create a new template, script, or folder.

❖ To change the connection definition associated with a document:


2 Open the Web site root folder.

3 From the right pane, right click on the document for which you want to change the connection information. Select Properties.

4 Select the appropriate connection from the drop-down menu.

5 Click OK.

❖ To delete a connection definition:



3 In the right pane, right click on the connection that you want to delete.

4 Select Delete then click Yes to permanently remove the connection.

❖ To test a connection definition:



3 In the right pane, right click on the connection to test.

4 Select Test. A message indicates whether or not the connection is still valid.

63


ost tral

e:

nds.

er ssion y ad ins You

Working with permanent and temporary connectionsCreate permanent and temporary connections by including the appropriate instructions directly into your Dynamo script. This section describes how to associate and use the correct connection definition with each Dynamo script.

❖ To create a permanent user connection definition from within a document:

• To create an ODBC connection within a document, use:

site.CreateConnection(connName, description, datasource [, userName, password, ODBC, connectParameters])

The connection is added to the Connection folder in Sybase Central. In mcases, permanent connection should be created through the Sybase Cenconnection wizard as described previously.

• To create an Open Client connection within a document, use:

site.CreateConnection(connName, description, server, userName, password, Open Client [, database])

❖ To create a temporary user connection from within a document:

• To create a temporary ODBC connection within a document, use:

x = new Connection(connName, description, datasource [, userName, password, ODBC, connectParameters]);

• To create a temporary Open Client connection within a document, us

x = new Connection(connName, description, server, userName, password, Open Client [, database]);

Note Remember, temporary connections are deleted when the session e

For more information, see “The connection object” in the PowerDynamo Reference.

Using a temporary connection with the session object

The most efficient way to work with temporary connections that require uscredentials is to create a temporary connection and associate it with the seobject. By associating a connection with the session object, the temporarconnection is not closed after a script has finished processing but is insteavailable for the next script that the user accesses. The connection remaavailable for as long as the user's session is active or until it is timed out.can also close a session object by setting it to null within the script.

64


The following example asks a user to log in to a site. Once the login information is provided a connection is created using the user’s ID and password. The connection is associated with a session object which is then used by Web site scripts. If the session times out, the user is directed back to the login page.

Contents of logon.ssc:

<HTML><H1>Logon to temporary connection sample</H1><FORM METHOD=POST ACTION="tempConnection.ssc"><INPUT TYPE="text" NAME="id" value="id" CHECKED>Enter your user ID<BR><INPUT TYPE="text" NAME="password" value="password">Enter your password<BR><P><INPUT TYPE="submit"></p><P><INPUT TYPE="RESET" VALUE="Clear Form"></P></FORM></HTML>

tempConnection.ssc

<HTML><BODY><A HREF="useConnection.ssc" >Click here to access a new script that used the existing temporary connection</A></BODY></HTML>

useConnection.ssc

<HTML><BODY><H1>Contacts for ACME Corp. </H1>

66


</BODY></HTML>

Managing the connection poolThis section describes how to manage the connection pool to ensure the optimum performance of the site.

Setting a connection timeout

The connection timeout value sets the number of minutes that a connection must be inactive before it is released from the connection pool.

You can use connection timeout values to control the number of connections in the pool as Web site activity fluctuates. This is more efficient than setting the minimum number of connections to the highest number of necessary connections or to creating new connections each time the minimum number of connections in the connection pool is exceeded.

By having the number of connections in the connection pool roughly match the number of connections being used by the Web site, performance will be increased for two reasons. The processing time required to create the connections is not being repeated for each individual request and there are no excess connections in the connection pool.

Use the Default General Settings folder in Sybase Central to set connection timeout values.

Setting maximum and minimum number of connections

You can set the values for the maximum and minimum number of connections being held in the connection pool for both user connections and Dynamo connections.

Limiting the number of User connections

The minimum number of user connections identifies the number of connections that are to be held in the connection pool of that definition. These connections are not affected by the connection timeout setting. If you were to set the default minimum number of connections to three, three connections for each definition would always remain in the connection pool ready for use, assuming that at some point the connections had been created.

67


rty

The maximum number of user connections identifies the maximum number of connections of that definition that are to be allowed to connect at any one time. Any connection requests beyond this number results in a null connection object being returned to the script.

Limiting the number of Dynamo connections

The minimum number of Dynamo connections identifies the minimum number of Dynamo connections in total that are to be held in the connection pool. These connections are not affected by the connection timeout setting. If you were to set the default minimum number of connections to three, three connections would always remain in the connection pool ready for use, assuming that at some point three connections had been created.

The maximum number of Dynamo connections stored in the connection pool should be set to the highest supportable number of connections required by your Web site during its highest time of throughput. The maximum number of connections value sets a limit on the number of Dynamo connections to the Web site, eliminating the chance of performance degradation due to too many connections being created at once.

Using <no connection>

You create a script or template with a Dynamo wizard, must specify the connection definition to be used for that document. Use <no connection> when a Web document does not require any connections to a database to complete execution. By specifying <no connection>, no connection object is created during the execution of that document. You can specify <no connection> for individual documents or for entire trees.

Once you have created a script or template, you can change the User connection associated with that document by using the document’s propesheet.

For specific information on how to set User connection defaults, see “Changing Dynamo configuration settings” on page 106.

68


ne 2, the

C

of n

Copying a Web-site database [Adaptive Server Anywhere]

When you copy a Web-site database to a new computer, the ODBC data source name is copied to the new machine as well. To connect to the Web site on the new machine, the connection’s ODBC data source name must be known on that machine. For example, if you create a Web site on machine 1 with an ODBC data source name of “mysite1” and copy the Web site database to machithe ODBC data source name on machine 2 is still “mysite1”. To connect toWeb site on machine 2, you can either:

• On machine 2, open the Connections folder, select the “default” connection, open the Properties window, and select an existing ODBdata source name from the drop-down list.

• On machine 2, create a new ODBC data source name on machine 2 “mysite1.” The “default” connection will recognize “mysite1” as a knowODBC data source name and connect to the Web site properly.

69

Using the Performance Monitor

Using the Performance MonitorThe Performance Monitor is a Windows NT tool that provides feedback on the performance of the following Dynamo-related items:

•Cache Hit Ratio Number of times a document is found in the cache versus the number of times the cache is searched.

•Cache Used Percentage of the document cache in use.

•Database Queries/Sec Number of queries per second being performed on the database.

•Documents in Cache Number of documents currently stored in the cache.

•Dynamo Connections Current number of Dynamo connections.

•Scripts Run Total number of scripts that have been run.

•Scripts/sec Number of scripts being run per second.

•Total Database Queries Total number of database queries performed.

•Total URL Requests Total number of URL requests processed by Dynamo.

•URL Requests/Sec Number of URL requests being processed per second.

•User Connections Current number of user connections.

❖ To run the Performance Monitor:

1 Connect to the Web site you want to monitor. You can monitor multiple Web sites at the same time if they are each connected.

2 From the NT Desktop, Select Start | Programs | Administrative Tools | Performance Monitor.

3 From the Performance Monitor select Edit | Add to Chart.

4 From the Add to Chart dialog window, select PowerDynamo as the Object. The Instance field displays the Web sites to which you are connected. You can display information in the instance field for a maximum of ten connected Web sites.

5 Select the first counter you want to monitor, and the appropriate Web site from the Instance field. Click Add.

Repeat this step for each counter you wish to display.

For more information, see the Performance Monitor online documentation.

70

er

C H A P T E R 4 Configuring Web Servers and Web sites

About this chapter You can access a PowerDynamo Web site from a browser or other Web client either by:

• Using the PowerDynamo Personal Web Server, or

• Using a third party Web server and a PowerDynamo Application Server. The Application Server communicates with the Web servusing one of the ISAPI, NSAPI, CGI or WIN-CGI interfaces.

Contents Topic Page

The Personal Web Server 72

Configuring a Dynamo Web site 76

Configuring an ISAPI server 79

Configuring an ISAPI 4.0 server 85

Configuring an NSAPI server 86

Configuring a CGI or WIN-CGI server 94

Configuring Web sites 100

How mapping information is stored 105

Changing Dynamo configuration settings 106

Setting Dynamo MIME types 109

71

The Personal Web Server

ve is

ase

oint hen ere

The Personal Web ServerThe Personal Web Server runs as an application on your computer. Once you start it, it runs in the background, automatically handling your Web browser’s requests for local Web pages (and supplying database content for any pages produced with Dynamo).

Accessing a Web site using the Personal Web ServerYour Web browser normally goes out onto the Internet (or your organization’s intranet) to get Web pages. When you run the Personal Web Server, your browser can get Web pages from your own computer as well.

These local pages can be either static documents or Dynamo documents, since the Personal Web Server automatically generates Web pages from Dynamo templates and scripts.

Testing Web sites When you are creating or changing a Web site that contains Dynamo content, you may find it easiest to create all or part of the site on your own computer. The site is stored in your own Dynamo database or in the file system.

Using the Personal Web Server, you can then point your Web browser to this local site and test your changes, without disrupting your organization’s production Web site.

For Dynamo sites that are stored in an Adaptive Server Anywhere database, moving a site to a server platform is a simple matter of copying the appropriate database and log file to the new location. For file-based Web sites, simply copy the files.

Using the Web offline To use the Web, normally you must be online—that is, you must have a liInternet connection for your Web browser. If you are offline, normally, thereno Web server to supply your browser with Web content. This is not the cwith PowerDynamo.

If you have some Web content already stored on your computer, you can pyour browser to this content by using the Personal Web Server. You can tnavigate these local pages as you would normally navigate the Web if you wonline.

72

CHAPTER 4 Configuring Web Servers and Web sites

g a ite

ection 38.

a

b ust

Your offline Web content can be a mixture of static and Dynamo documents stored on your computer. It can be stored as conventional files copied from the Internet, or stored as part of a Dynamo database replicated automatically from an Adaptive Server Enterprise or Adaptive Server Anywhere central database using SQL Remote. The Personal Web Server handles these details and presents the results to your Web browser.

Preparing to use the Personal Web Server

❖ To use the Personal Web Server:

1 For a database-hosted Web site, create an ODBC Data Source Name (this step is not necessary if you are using an Open Client connection to connect to the database).

For information on creating an ODBC Data Source Name see “CreatinWeb site [Adaptive Server Anywhere]” on page 33 or “Creating a Web s[Adaptive Server Enterprise]” on page 35.

2 For a database-hosted Web site, use Sybase Central to create a connprofile. See “Creating a connection profile for your Web site” on page

3 Configure the Application Server by defining mappings from a URL toDynamo site.

For information about configuring the Personal Web Server, see “Configuring Web sites” on page 100.

TCP/IP requiredWeb browsers require a TCP/IP protocol stack to communicate with a Weserver, even if it is on the same machine with no intervening network. You mhave TCP/IP installed to use the Personal Web Server.

Starting the Personal Web Server

❖ To start the Personal Web Server on your computer:

1 To start the Personal Web Server from Sybase Central, click on the Utilities folder in the left pane of Sybase Central.

2 Double-click on the Personal Web Server icon in the right pane.

73

The Personal Web Server

rt

that The

can

ne:

The Personal Web Server on the desktopUnder Windows 95 and Windows NT 4.0, the Personal Web Server appears only as a small “tray icon” at the opposite end of the taskbar from the Stamenu.

Figure 4-1: Personal Web server icon

Viewing a local Dynamo documentFrom a browser, you must identify, by means of the server part of a URL, a document is to be found using a Web server running on your machine. server part of a URL identifies a particular computer, and the Web server running on that computer can then receive and process the request. You identify your own machine in a URL in one of the following ways:

• Use the special name localhost for the server part of the URL. For example, the following URL accesses a document on the local machi

http://localhost/Site/sample.stm

This is the recommended method.

• Use the IP number of your machine. For example:

http://123.45.54.211/Site/sample.stm

• Use the name of your machine. For example:

http://test_machine/Site/sample.stm

Figure 4-2: URL format

74


Web content may be on other machinesThe Personal Web Server connects to a database-hosted Web site via an ODBC client/server connection. The documents you access using the Personal Web Server may be located on an Adaptive Server Enterprise or Adaptive Server Anywhere database on a different machine on the network.

75

Configuring a Dynamo Web site

Configuring a Dynamo Web siteIf you have a live Internet connection you do not need to use the Personal Web Server to access Dynamo Web content on a Web site. In this case, you use one of the application servers (or gateways) provided as part of PowerDynamo to serve Dynamo Web site content to the site Web server.

Figure 4-3: Web servers and application servers

76


Supported Web servers

PowerDynamo includes an Application Server for each of these interfaces:

•CGI For integration with CGI-compatible Web servers.

•WIN-CGI For integration with Windows CGI-compatible Web servers.

•ISAPI For integration with Microsoft Internet Information Server or other ISAPI Web server.

•NSAPI For integration with a Netscape Web server or other NSAPI Web server.

Configuring Web servers during installationIf you have a Web server installed on your machine, the installation program allows you to configure the server to work with PowerDynamo. The installation program will add the appropriate DLLs to your system path, and install the PowerDynamo Application Server software on the Web server machine. This eliminates the need for steps 1 and 2 listed below. You must still complete steps 3 through 5 for PowerDynamo to work properly.

If you install a Web server after installing PowerDynamo, you can use the setup -webserver command to reexecute the installation program.

Configuring Web Servers manuallyThe following procedure is an overview of the steps required to configure a Dynamo Web site. Detailed instructions specific to each of the supported server interfaces follow.

Note Ensure that PowerDynamo has been installed on the Web server machine before beginning configuration. For future administration use, it is recommended that all PowerDynamo components remain installed on the Web server machine. You must confirm that you are properly licensed to use PowerDynamo and Adaptive Server Anywhere or Adaptive Server Enterprise on your Web site before configuring your Web site.

❖ To configure a Dynamo Web site:

1 Edit your computer’s path to include the Application Server DLLs. If the Web server was detected and configured during the PowerDynamo installation, this step is not necessary.

77

Configuring a Dynamo Web site

2 Install the PowerDynamo Application Server software on the Web Server machine if it is not already.

3 For database-based Web sites, create an ODBC System Data Source Name (DSN). If you are using an Open Client connection, this step is not necessary.

4 For database-based Web sites, create a Sybase Central connection profile.

5 Configure the Application Server by defining mappings from a URL to a Dynamo site.

ImportantThe above steps rely on tools available from PowerDynamo.

78


steps

ur

vers

s

Configuring an ISAPI serverThis section provides a detailed explanation of how to set up an ISAPI server to run with PowerDynamo.

IIS 4.0If you have the Internet Information Server NT 4.0 option pack, see “Configuring an ISAPI 4.0 server” on page 85.

Steps 1 and 2 are part of the PowerDynamo installation procedure. Theseare not necessary if the Web server was detected and configured during installation. Steps 3 through 5 must still be completed.

For more information on configuring Web servers during installation see “Configuring Web servers during installation” on page 77.

Step 1: Edit the System Path in the System Properties windowIn Step two, you will copy DLLs to the InetPub\scripts directory of the ISAPI Web server. For the Microsoft server to find these DLLs, you must edit yocomputer's system path to include the directory containing the DLLs.

Windows 95If you are running Windows 95, edit the path to include the directory containing the new DLLs.

The DLL directory is added to the system path, not the user path. ISAPI serrun as Windows NT services on the NT operating system.

Step 2: Install the Application ServerYou must install the Application Server software into a directory defined aexecutable by the Web server. Microsoft presets the InetPub\scripts directory as being executable. For this reason, we recommend that you copy the appropriate DLLs to this directory.

79

Configuring an ISAPI server

rver ith

ed

Installing the required software

• If you haven't done so already, install PowerDynamo onto the Web semachine using the standard software installation. This provides you wtools such as Sybase Central and the Dynamo Configuration folder.

• Copy the required DLLs into the InetPub\scripts directory on the Web Server machine.

Required DLLs for ISAPI servers

The PowerDynamo Application Server for ISAPI Web servers includes thefollowing files:

• dyisa03.dll

• dyhtml03.dll

• dydom03.dll

• dyscr03.dll

• dydbg03.dll (optional)

• dyxdb03.dll

• dyxdfl03.dll

• dys03ent.dll

• dycom03.dll (optional)

• dycls03.dll

• dyzip03.dll

• dyperf03.dll (optional)

• mthr110.dll

• plbr110.dll

• clbr110.dll

The following required Power++ runtime libraries are automatically installinto your Windows SYSTEM directory or your Windows NT system32 directory.

80


ther

tem

te a

Using the ISAPI filter

The dyisa03.dll provides translation capabilities so that users can enter a standard URL call (http://localhost/Site/Contents.stm) instead of the longer ISAPI call (http://localhost/Scripts/dyisa03.dll/Site/Contents.stm).

To load dyisa03.dll properly, you must create an IIS virtual directory, and set the ISAPI filter for PowerDynamo.

❖ To create an IIS virtual directory

1 Start the Microsoft Internet Service Manger.

2 Right-click in the left pane of the Management Console, underneath the Default Web Site and select New →Virtual Directory.

3 Enter “Sybase” as the alias. Click Next.

4 Enter or browse to the path of your Dynamo win32 directory.

5 Select Allow Execute Access as the permission type and clear all the oboxes.

The virtual directory is now set.

❖ To set the ISAPI filter DLL:

1 From the Management Console, right-click on your machine (directlybeneath the Internet Information Server folder) and select Properties.Click Edit.

2 Select the ISAPI Filter tab, then click Add.

3 Enter “PowerDynamo” as the Filter Name, then enter the path to dyisa03.dll.

4 Restart the Microsoft IIS Server for these changes to take effect.

Step 3: Create an ODBC System Data Source Name (DSN)An ODBC System DSN is the same as an ODBC DSN except that the SysDSN is available to all users on a machine, including services.

NoteIf you are connecting to a file-based Web site, or using an Open Client connection, this step is not necessary. If you are using Windows 95, creadata source; you do not need a system DSN.

81


prise . The

e the ed.

he tory ether

ata

the

❖ To create an ODBC System Data Source Name:

1 Start the ODBC Administrator from the Utilities folder in Sybase Central.

2 Select the System DSN tab. Click Add.

3 From the Create New Data Source window, select the appropriate ODBC driver; for example, Adaptive Server Anywhere 6.0. Click Finish.

4 Enter the:

• Data Source Name

• User Id

• Password

• Database name

• Database file

Click OK.

Creating an ODBC data source to connect to an Adaptive Server Enterprise databaseWhen you are creating an ODBC data source for an Adaptive Server Enterdatabase the Select Method must be set to 0 - Cursor for Dynamo to workSelect method setting is located within the ODBC Administrator → ODBC Sybase Driver Setup → Performance Tab

❖ To ensure that the ODBC data source is available:

1 If you are using Adaptive Server Enterprise as the data server, ensurappropriate client library software and ODBC driver have been install

2 If you are using Adaptive Server Anywhere as the data server, copy tWeb site database file and transaction log file into an appropriate direcon the Web server machine and ensure that the database engine togwith the Adaptive Server Anywhere ODBC driver and its attendant libraries are accessible on the machine.

3 If you are using the Adaptive Server Anywhere network server as the dserver, install the Adaptive Server Anywhere client together with the Adaptive Server Anywhere ODBC driver and its attendant libraries on Web server machine.

82


38.

m

nter ions.

o the You the

your

Step 4: Create a connection profileYou should create a connection profile for your Web site to store connection information in the registry in encrypted form. This information is used by Sybase Central, the Personal Web Server, and the Dynamo Application Servers.

NoteIf you are connecting to a file-based Web site, or using an Open Client connection, see “Creating a connection profile for your Web site” on page

❖ To create an ODBC connection profile for your Web site:

1 From Sybase Central, select Tools →Connection Profiles.

2 Click New.

3 Enter a name for the connection profile, and select PowerDynamo frothe list of available types. Click OK.

4 Select an ODBC data source from the drop-down list. If appropriate, ea user ID and password, and any additional parameters and descriptClick OK to create the connection profile.

Step 5: Configure the Application ServerOnce the site Web server receives an URL from a Web client, it passes it tDynamo Application Server, which locates and processes the document. must add a mapping to the Application Server so it can locate the path todocument.

Dynamo configuration

❖ To add a new mapping using the Dynamo Configuration folder:

1 In the left pane of Sybase Central, open the Utilities folder.

2 In the right pane of Sybase Central, open the Configuration folder.

3 Double-click the Mappings folder.

4 Double-click Add Mapping.

5 Enter a URL prefix, the Dynamo site type, the resource to access on machine and the maximum size of the document cache.

6 Restart the server for these changes to take effect.

83


on
For a more detailed description of how to configure the Dynamo sites using Sybase Central and the Configuration folder, see “Configuring Web sites”page 100.
84


Configuring an ISAPI 4.0 serverIf IIS 4.0 is detected during installation, the procedures in this section occur automatically. To configure the IIS 4.0 manually follow the instructions in this section.

Installing IIS 4.0When installing the Internet Server NT 4.0, ensure that the Internet Service Manager is selected as one of the components under the Personal Web Server. This is not a default selection and the manager is necessary for starting and stopping the server.

Configuring the IIS 4.0 ServerIf you have installed IIS 4.0 on a machine that was already configured for PowerDynamo to work with an ISAPI server, you should already have a virtual directory and filter path set. If you are configuring ISAPI for the first time, follow the instructions for creating an IIS virtual directory and setting the ISAPI filter DLL starting on page 81.

Starting and stopping the IIS service

Whenever a change is made to a PowerDynamo mapping or within the Sybase Central configuration folder, the server must be stopped and restarted in order for the changes to take effect.

❖ To stop the IIS Admin Service:

1 From your Control Panel, open the Services utility.

2 Select IIS Admin Service and click Stop. This will stop both the IIS Admin Service and the World Wide Web Publishing Service.

❖ To start the IIS Admin Service:

1 From your Control Panel, open the Services utility.

2 Select World Wide Web Publishing Service and click Start. This will start both the World Wide Web Publishing Service and the IIS Admin Service.

85

Configuring an NSAPI server

n

e the

ath. tem.

Configuring an NSAPI serverThis section provides a detailed explanation for setting up an NSAPI server to run with PowerDynamo.

Steps 1 and 2 are part of the PowerDynamo installation procedure. These steps are not necessary if you configured the Web server during installation. You must still complete steps 3 through 5.

For more information, see “Configuring Web servers during installation” opage 77.

Step 1: Edit the system path in the System Properties windowIn Step two of Configuring an NSAPI Server, you will be copying DLLs to thNetscape\server\plugins\dynamo directory of the NSAPI Web server (you willhave to create the dynamo directory). For the server to find these DLLs, youmust edit your computer's system path to include the directory containingDLLs.

Note The DLL directory must be added to the system path, not the user pNSAPI servers are run as Windows NT services from an NT operating sys

Figure 4-4: System Properties window

86


Step 2: Install the Application ServerIf you haven’t done so already, install PowerDynamo onto the Web server machine using the standard software installation. This provides you with tools such as Sybase Central and the Dynamo Configuration folder that are necessary in later stages of the configuration.


The PowerDynamo Application Server for NSAPI Web servers includes the following files, which are loaded during installation:

• dy2ns03.dll (for Netscape version 2.0)

• dy3ns03.dll (for Netscape version 3.0 or higher with SSL)

• dyhtml03.dll

• dyscr03.dll

87


tion

nly.


• dydom03.dll

• dyxdb03.dll

• dyxdfl03.dll

• dys03ent.dll


• dycls03.dll

• dyzip03.dll


The following Powersoft Power++ runtime libraries are installed into your Windows SYSTEM directory or your Windows NT system32 directory:

• mthr110.dll

• plbr110.dll

• clbr110.dll


Netscape Web servers use the NSAPI interface to communicate with the Dynamo Application Server.

For full details on configuring Netscape servers, see your Web server documentation.

❖ To configure Netscape Web servers for use with Dynamo:

1 Make the appropriate changes to the Netscape Web server configurafile obj.conf. This is a plain text file located in the CONFIG directory of each server configuration.

Instruct the server to load the dy2ns03.dll or the dy3ns03.dll Application Server. The following is an example line in the obj.conf file. The first line must be typed on a single line, it is wrapped here for display reasons oThe last line Init fn=_dynamo_init should be written on a new line.

Init fn=load-modules shlib=path/dy2ns03.dll funcs="_dynamo_ntrans,_dynamo_fn,_dynamo_pathcheck,_dynamo_init"

Init fn=_dynamo_init

88


for n this

• _dynamo_pathcheck,_dynamo_init should be written without any spaces.

• In the above example, path is where the filter DLL can be found. Forexample,

Shlib=c:/netscape/server/plugins/dynamo

• Ensure that you have specified the correct DLL for your Netscapeserver. If you are using Netscape Server 2.0, specify dy2ns03.dll; if you are using Netscape Server 3.0 or higher, specify dy3ns03.dll.

2 At the top of the NameTrans list, enter:

NameTrans fn=_dynamo_ntrans

3 At the top of the PathCheck list, enter:

PathCheck fn=_dynamo_pathcheck

4 Add the following section to the end of the file:

<Object name=PowerDynamo>Service fn=_dynamo_fn</Object>

The following is a sample configuration file. Some long lines are wrappeddisplay reasons. Each separate line in the file is separated by a blank line ilisting.

# Use only forward slashes in pathnames

# backslashes can cause

# problems.

Init fn=flex-init access="c:/Netscape/Server/https-steverd/logs/access" format.access="%Ses->client.ip% - %Req->vars.auth-user% [%SYSDATE%] \"%Req->reqpb.clf-request%\" %Req->srvhdrs.clf-status% %Req->srvhdrs.content-length%"

Init fn=load-types mime-types=mime.types

Init fn=load-modules shlib=c:/Netscape/Server/Plugins/dynamo/dy2ns03.dll funcs="_dynamo_ntrans,_dynamo_fn,_dynamo_pathcheck,_dynamo_init"

Init fn=_dynamo_init

89


<Object name=default>

NameTrans fn=_dynamo_ntrans

NameTrans fn=pfx2dir from=/ns-icons dir="c:/Netscape/Server/ns-icons"

NameTrans fn=pfx2dir from=/mc-icons dir="c:/Netscape/Server/ns-icons"

NameTrans fn=document-root root="c:/Netscape/Server/docs"

PathCheck fn=_dynamo_pathcheck

PathCheck fn=nt-uri-clean

PathCheck fn=find-pathinfo

PathCheck fn=find-index index-names="index.html,home.html"

ObjectType fn=type-by-extension

ObjectType fn=force-type type=text/plain

Service method=(GET|HEAD) type=magnus-internal/imagemap fn=imagemap

Service method=(GET|HEAD) type=magnus-internal/directory fn=index-common

Service method=(GET|HEAD) type=*~magnus-internal/* fn=send-file

AddLog fn=flex-log name="access"

</Object>

<Object name=cgi>

ObjectType fn=force-type type=magnus-internal/cgi

Service fn=send-cgi

90


</Object>

<Object name=PowerDynamo>

Service fn=_dynamo_fn

</Object>

A document named test.stm in the Dynamo Web site folder would then have the following URL:

http://server-name/Site/test.stm

The URL contains the server name, followed by the URL prefix defined in the Application Server mapping: in this case /Site. This mode of addressing is exactly the same as for the Personal Web Server.

Step 3: Create an ODBC System Data Source Name (DSN)Creating a System DSN is the same as creating a DSN except a System DSN is available to all users on a machine as well as services.

NoteIf you are connecting to a file-based Web site, or using an Open Client connection, this step is not necessary. If you are using Windows 95, create a data source; you do not need a system DSN.





4 Enter the:


• User Id

• Password

• Database name

• Database file

91


38.

Click OK.

Creating an ODBC data source to connect to an Adaptive Server Enterprise databaseWhen you are creating an ODBC data source for an Adaptive Server Enterprise database the Select Method must be set to 0 - Cursor for Dynamo to work. The Select method setting is located within the ODBC Administrator → ODBC Sybase Driver Setup → Performance Tab


1 If you are using Adaptive Server Enterprise as the data server, ensure the appropriate client library software and ODBC driver have been installed.

2 If you are using Adaptive Server Anywhere as the data server, copy the Web site database file and transaction log file into an appropriate directory on the Web server machine and ensure that the database engine together with the Adaptive Server Anywhere ODBC driver and its attendant libraries are accessible on the machine.

3 If you are using the Adaptive Server Anywhere network server as the data server, install the Adaptive Server Anywhere client together with the Adaptive Server Anywhere ODBC driver and its attendant libraries on the Web server machine.





2 Click New.

92


on

3 Enter a name for the connection profile, and select PowerDynamo from the list of available types. Click OK.

4 Select an ODBC data source from the drop-down list. If appropriate, enter a user ID and password, and any additional parameters and descriptions. Click OK to create the connection profile.

Step 5: Configure the Application ServerOnce the site Web server receives an URL from a Web client, it passes it to the Dynamo Application Server, which locates and processes the document. You must add a mapping to the Application Server so it can locate the document. Use the Configuration folder found within the Utilities folder of Sybase Central to add a mapping to the Application Server.







5 Enter a URL prefix, the Dynamo site type, the resource to access on your machine and the maximum size of the document cache.



93

Configuring a CGI or WIN-CGI server

n

o

ath.

n

rver ith

Configuring a CGI or WIN-CGI serverThis section provides a detailed explanation for setting up a CGI or WIN-CGI server to run with PowerDynamo.

Steps 1 and 2 are part of the PowerDynamo installation procedure. These steps are not necessary if you configured the Web server during installation. You must still complete steps 3 through 5.

For more information, see “Configuring Web servers during installation” opage 77.

Step 1: Edit the System Path in the System Properties windowIn Step two of Configuring a CGI or WIN-CGI server, you will be copying DLLs to the directory of the CGI or WIN-CGI Web server. For the server tfind these DLLs, you must edit your computer's system path to include thedirectory containing the DLLs. Figure 4-4 on page 86 shows the System Properties window.

Note The DLL directory must be added to the system path, not the user p

Step 2: Install the Application ServerEach Web server has a method for defining directories where programs executable by the Web server are located. You must install the ApplicatioServer software into a directory defined as executable by the Web server.


• If you haven't done so already, install PowerDynamo onto the Web semachine using the standard software installation. This provides you wtools such as the Personal Web Server and Sybase Central that are necessary in later stages of the configuration.

• Copy the required DLLs into the directory of the Web server machine.

Required files for CGI servers

The PowerDynamo Application Server for CGI Web servers includes the following files:

94


the

• dycsrv03.exe

• dycgi03.exe

• dyhtml03.dll

• dyscr03.dll


• dydom03.dll

• dys03ent.dll

• dyu03ent.dll

• dyxdfl03.dll

• dyxdb03.dll


• dycls03.dll

• dyzip03.dll



• mthr110.dll

• plbr110.dll

• clbr110.dll

Required files for WIN-CGI servers

The PowerDynamo Application Server for WIN-CGI Web servers includes following files:

• dycsrv03.exe

• dycwin03.exe

• dyhtml03.dll

• dyscr03.dll


• dydom03.dll

• dys03ent.dll

• dyu03ent.dll

95


lt for

ch ry.

ust

• dyxdfl03.dll

• dyxdb03.dll


• dycls03.dll

• dyzip03.dll



• mthr110.dll

• plbr110.dll

• clbr110.dll


For more information on setting up your CGI or WIN-CGI directory, consuyour Web server documentation. It is important that the directory is set upthe correct type of server.

CGI Web servers allow you to describe a set of executable directories. Eadirectory has an alias, which is an URL prefix corresponding to that directoThe default alias for most CGI Web servers is /cgi-bin.

CGI Web servers support one of two types of CGI:

• CGI

• WIN-CGI

Determine which type of CGI your Web server uses.

CGI HelperIn order for a Web site to interface with PowerDynamo through CGI you mrun the Dynamo CGI Helper along with the Web site server itself.

You can start the CGI Helper from the Dynamo Utilities folder.

This is a sample URL call for a CGI server:

http://server/cgi-bin/dycgi03.exe/Site/Contents.stm

This is a sample URL call to a WIN-CGI server:

96


prise . The

http://server/cgi-win/dycwin03.exe/Site/Contents.stm

Step 3: Create an ODBC System Data Source Name (DSN)Creating a System DSN is the same as creating a DSN except a System DSN is available to all users on a machine as well as services.

NoteIf you are connecting to a file-based Web site, or using an Open Client connection, this step is not necessary. If you are using Windows 95, create a data source; you do not need a system DSN.





4 Enter the:


• User Id

• Password

• Database name

• Database file

Click OK.

Creating an ODBC data source to connect to an Adaptive Server Enterprise databaseWhen you are creating an ODBC data source for an Adaptive Server Enterdatabase the Select Method must be set to 0 - Cursor for Dynamo to workSelect method setting is located within the ODBC Administrator → ODBC Sybase Driver Setup → Performance Tab

97


38.

m

nter ons.


1 If you are using Adaptive Server Enterprise as the data server, ensure the appropriate client library software and ODBC driver have been installed.

2 If you are using Adaptive Server Anywhere as the data server, copy the Web site database file and transaction log file into an appropriate directory on the Web server machine and ensure that the database engine together with the Adaptive Server Anywhere ODBC driver and its attendant libraries are accessible on the machine.

3 If you are using the Adaptive Server Anywhere network server as the data server, install the Adaptive Server Anywhere client together with the Adaptive Server Anywhere ODBC driver and its attendant libraries on the Web server machine.





2 Click New.

3 Enter a name for the connection profile, and select PowerDynamo frothe list of available types. Click OK.

4 Select an ODBC data source from the drop-down list. If appropriate, ea user ID and password, and any additional parameters and descriptiClick OK to create the connection profile.

98


on

Step 5: Configure the Application ServerOnce the site Web server receives an URL from a Web client, it passes it to the Dynamo Application Server, which locates and processes the document. You must add a mapping to the Application Server so it can locate the document. Use the Configuration folder found within the Utilities folder of Sybase Central to add a mapping to the Application Server.







5 Enter a URL prefix, the Dynamo site type, the resource to access on your machine and the maximum size of the document cache.



99

Configuring Web sites

how

Configuring Web sitesRegardless of the server you are using to access your Web site there are some aspects of Web site behavior that you can configure.

Configuration is machine specificAny settings you make in the Dynamo Configuration folder apply to all Web sites accessed from the current machine, whether they are accessed by a Personal Web Server or by a Dynamo Application Server attached to a third party Web server. The configuration information is stored in the Windows 95 or Windows NT registry.

Accessing the Dynamo Configuration folderYou can access the Configuration folder from Sybase Central.



3 Select the folder you want to work with.

There are three types of information you can configure:

•Mappings Associate URL prefixes with Dynamo sites. See “Setting Dynamo mappings” on page 100.

•MIME Associate file extensions with applications. See “Defining mappings for database-hosted sites” on page 102.

•Default Settings Default settings for the Web site. See “Changing Dynamo configuration settings” on page 106.

Setting Dynamo mappingsThis section describes the elements that make up a Dynamo mapping, andto set the mappings using the Dynamo Configuration folder.





100



5 Enter an URL prefix, a Dynamo site type, the site you want to access and the maximum size of the document cache. Each of these elements of a mapping is described below.

6 Restart the server for your changes to take effect.

Figure 4-5: Site Properties window

The elements of a mapping

Dynamo mappings include these elements:

URL prefix In Dynamo, URL prefix means any part of an URL immediately following the server name. For example, in the following address, /this is a URL prefix.

http://www.sybase.com/this/that/other.stm

The remainder of the URL ( /that/other.stm ) refers to the position of the document that is mapped to the URL prefix /this.

If you are using ISAPI Web servers, you can use the above URL format or you can use the longer version displayed below, which directly calls dyisa03.dll.

http://server/alias/dyisa03.dll/this/that/other.stm

101


.

on

entral

able

ir ase se

o set

the

For more information, see “Using the ISAPI filter” on page 81.

Dynamo site type The type of document to which the URL prefix refers

There are three Dynamo site types:

•Database site Documents are held in a database-hosted Web site. You can process templates and scripts containing DynaScript.

•Dynamic file site Documents are held on disk. Templates and scripts containing DynaScript can be processed.

•Static file site Documents are held on disk. Sends back static HTML. You cannot process queries or templates containing DynaScript.

For more information, see “Defining mappings for database-hosted sites”page 102 and “Defining a mapping for file-based sites” on page 103.

Site location The location of the site corresponding to the URL prefix.

The site location for a database hosted Web site is the name of a Sybase Cconnection profile. Connection information is stored in the Registry.

The site location for a file-based Web site is a folder name on a drive availto the Web site machine.

Document cache size The maximum amount of memory to reserve foryour document cache.

Java cache size The maximum amount of memory to reserve for your Java cache.

Java classpath Class files that are stored in a database must have theclass path specified in Sybase Central for the class file to be found. Databclass paths may be set per mapping from the Configuration folder in SybaCentral.

The mapping and Dynamo site name must be the same.

Class files that are stored in a file-based Web site can also use this field tthe Java classpath.

Defining mappings for database-hosted sites

❖ To define a mapping for a database-hosted site:

1 Use Sybase Central to create a PowerDynamo connection profile for Web site.

For more information, see “Creating a connection profile for your Website” on page 38.

102


2 From the Utilities folder, open the Dynamo Configuration folder.

3 Open the Mappings folder and double-click Add Mapping.

4 In the URL prefix field, enter the name to use for URLs to access the site. For example, if you want the index.html document to be addressed as:

http://server-name/db_site/index.html

then enter /db_site as the URL prefix.

5 Select Database from the list of Dynamo site types.

6 To define the resource, click Browse, and select the profile from the list of available Sybase Central profiles.

7 Enter the desired cache size for your documents.

8 Enter the desired cache size for your Java classes.

9 If you have Web sites that access Java class files from within a database enter the classpath for the mapping. Dynamo cannot find the class files unless the location is specified here.

10 Restart the server.

Defining a mapping for file-based sites

❖ To define a mapping for a file-based site:

1 Open the Dynamo Configuration folder from the Sybase Central Utilities folder.

2 From the Mappings folder, double-click Add Mapping.

3 In the URL prefix field, enter the name for URLs to access the site. For example, if you want the index.html document to be addressed as:

http://server-name/file_site/index.html

then enter /file_site as the URL prefix.

4 Select Dynamo site types. Chose Dynamic if you want Dynamo to produce dynamic content from templates and scripts. Chose Static to return static HTML documents.

5 To define the resource, click Browse, and select the folder containing the documents from the expandable list. Click OK twice to save the mapping.

6 Enter the desired cache size for your documents.

7 Enter the desired cache size for your Java classes.

103


8 If you have Web sites that access Java class files from within a database enter the classpath for the mapping. Dynamo cannot find the class files unless the location is specified here.

9 Restart the server.

To edit a mapping, double-click on the mapping and make the necessary changes. Click OK to save the changes.

To delete a mapping, right-click the mapping and select Delete.

104


e of , as

C

not SER stem in

ource

How mapping information is storedThe mapping information is stored in the Windows or Windows NT Registry.

• The Dynamo mappings are stored in:

HKEY_LOCAL_MACHINE\SOFTWARE\Sybase\PowerDynamo\Mappings

• Encrypted Sybase Central connection profile information is stored in:

HKEY_LOCAL_MACHINE\SOFTWARE\Sybase\Sybase Central\Profiles

This registry folder contains a set of folders. Each folder has the nama profile, and contains the name of the associated ODBC data sourcewell as the user ID and password used to access the data source.

• The ODBC data source, which you may have created using the ODBAdministrator, is held in:

HKEY_CURRENT_USER\SOFTWARE\ODBC\ODBC.INI

• If you are running your Web server as a Windows NT service, it does use a login ID, and consequently has no access to the CURRENT_Uregistry. In this case, you must create your ODBC data source as a SyDataSource Name (System DSN). System DSN descriptions are heldthe LOCAL_MACHINE registry.

• The ODBC driver used to access the data source is part of the data sdefinition. The available ODBC drivers are listed in:

HKEY_LOCAL_MACHINE\SOFTWARE\ODBC\ODBCINST.INI

105

Changing Dynamo configuration settings

Changing Dynamo configuration settingsThe Dynamo configuration settings govern some aspects of Dynamo server behavior.

❖ To change the settings for your Dynamo server:



3 Open one of these folders:

•Default CGI Settings

•Maximum number of CGI clients Sets the maximum number of CGI clients that are allowed to connect at one time.

•Default General Settings

•Application to launch when debugging The application you would like to use when debugging.

•Cookie timeout When information is exchanged between a browser and a Web server, such as when a sequence of forms is filled out at a browser, Dynamo uses a cookie to maintain information about the session. After the specified timeout period, this information is discarded. The default setting is five minutes.

•Java VM This default sets the Java VM for the Web site. Dynamo supports the Microsoft Java VM, the Sun Java VM and the Sun Debug Java VM. If using Jaguar, this must be set to the SUN VM.

•Connection timeout This default value causes connections in the connection pool to expire or be disconnected, once the specified amount of time of inactivity has elapsed. A value of 0 indicates that connections within the pool should not be expired.

For more information, see “The connection pool” on page 60.

•Maximum number of Dynamo connections per mapping This sets the maximum number of Dynamo connections to be stored in the database connection pool.

•Maximum number of user connections per connection type

Specifies the maximum number of user connections per connection type to be stored in the connection pool.

106


•Minimum number of Dynamo connections per mapping Sets the minimum number of Dynamo connections to be stored in the connection pool.

•Minimum number of user connections per connection type Sets the minimum number of User connections per connect type to be stored in the connection pool. This number of connections will never expire.

•SMTP host Specifies the SMTP host to be used for outgoing mail. The smtpHost property of the outgoing MailPiece object takes precedence over this setting. A SMTP host must be set from this field or the smtpHost property in order for the mail to be sent.

•Trace The trace option, when set to yes, creates a dynamo.log file in the Dynamo installation directory that captures logging and error information that may be useful for debugging.

•URL arguments case sensitive Indicates whether case sensitivity is used for your URLs.

•Default ISAPI Settings The default settings for ISAPI Web servers.

•ISAPI filter directory alias Location of the ISAPI filter.

•Maximum number of pending requests Maximum number of URL requests that can be maintained in the queue for future processing.

•Maximum number of worker threads Maximum number of worker threads in the pool. Each worker thread can process one task URL request at a time. Once a task has been completed by a worker thread it is released. If there are other tasks waiting to be processed by a worker thread the next is selected for processing.

•Default Jaguar Settings The default settings for working with the Jaguar Component Transaction Server. Settings that you specify here apply to Jaguar Managers that have not been specifically set up in the Manager Settings folder.

•Orb Class The ORB class that represents the Java object.

•Proxy Host Specifies the machine name or the IP address of an SSL proxy

•Proxy Port Specifies the port number of the SSL proxy.

•Retry Count The number of times that connecting to the server should be attempted.

107

Changing Dynamo configuration settings

•Retry Delay The number of milliseconds to wait between attempts to connect to the server.

•Manager Settings The configuration settings for specific Jaguar Managers. Each setting allows you to set the same properties as are found in the Default Jaguar settings. If for some reason you cannot make a connection with the settings from here, the defaults specified in the Default Jaguar Settings folder are used. For more information, see the Jaguar documentation.

•Default PWS Settings The default settings for the PowerDynamo Personal Web Server.

•Default document for static file sites When a URL without an explicit document name is supplied, the default document for the site is returned to the Web client. For the sample Web site, the default document is contents.html.

Must be a known MIME typeThe extension of the default document (contents.html) must be registered to Dynamo as a known MIME type, if not, the content type will be returned as “octet/stream” (binary) and be unreadable.

•Port number Each Internet service is assigned to a logical port number. The usual port number for HTTP servers such as the Dynamo Personal Web Server is 80. You need change this value only if some other service on your machine is already using port number 80. Port numbers are ignored on UNIX machines.

To modify any of these entries, double-click on the entry, make the appropriate changes and click OK to save.

Changes take effect the next time the server is startedYou must restart the server for changes made to the Configuration folder to take effect.

108


Setting Dynamo MIME typesInformation of many different types can be exchanged between a Web client and a Web server. HTML documents, text files, and images are only a few. The way each set of information is handled is described using MIME types. You can configure the MIME type definitions for your Dynamo server using the Dynamo configuration utility: the server then informs clients receiving the data of the proper type.

Each MIME type definition is an association between a file extension and a mime type.

❖ To set the MIME types for your Dynamo server:

1 Open the Dynamo Configuration folder.

2 Open the MIME folder.

3 Click Add MIME Type or double-click on the MIME type you want to edit.

4 Make changes.

5 Click OK to save the changes.

To remove an existing MIME type, right-click on it and select Delete.

Changes take effect the next time the server is startedYou must restart the server for changes made to the Configuration folder to take effect.

109

Setting Dynamo MIME types

110

C H A P T E R 5 Dynamo Tags Tutorial

About this chapter This chapter introduces Dynamo tags, which are HTML-like tags used for simple manipulation of PowerDynamo Web site documents.

The tutorials in this chapter introduce you to the most commonly used Dynamo tags. Several other tags are also explored that allow you to manipulate data within your Web site possible without using a scripting language such as DynaScript or JavaScript.

Contents Topic Page

Overview of Dynamo Tags 112

Tags tutorial 113

111

Overview of Dynamo Tags

data

Overview of Dynamo TagsDynamo tags are extensions to the regular HTML tags that are used for creating Web documents. The main difference between Dynamo tags and HTML tags is the location from which the tags are processed. Dynamo tags are processed at the Web server while HTML tags are processed at the browser. Dynamo tags also provide extended Web site capabilities that are not available through the regular set of HTML tags. Normally, a scripting language such as DynaScript or JavaScript is required to gain the functionality that is provided with the Dynamo tags.

Dynamo tags appear as HTML comments, which allow you to use your favorite HTML editor to enter them. Once all Dynamo tags have been processed by the server, the resulting page is returned to the browser.

PowerDynamo tags have the following characteristics:

• Each Dynamo tag begins with an HTML comment tag ().

• Dynamo tags are not case sensitive.

• Some Dynamo tags have attributes that enable specific document andmanipulation.

112

CHAPTER 5 Dynamo Tags Tutorial

lay

ests

(<!- the

Tags tutorialThese tutorials teach you how to use the most commonly used Dynamo tags.

• SQL

• FORMATTING

• The error checking tags

• INCLUDE

• SQL_INSERT

Using the SQL tagUse the SQL Tag to embed SQL queries within HTML. You can then dispthe output in a variety of formats by using additional Dynamo tags.

This example shows how to embed a SQL query in HTML. This query requthe ID, first name, last name, and phone number of the customers in the customer table. The SQL block of information between the start SQL tag -SQL) and the end SQL tag (-->) is processed by the Dynamo applicationserver. The document is then passed on to the browser to be processed; results display in HTML format.

<HTML><TITLE>SQL_tag.stm</TITLE><BODY><H1>Customer Information</H1>

There are two ways to create a document with an embedded SQL query:

• Use the Add Template wizard in Sybase Central. This automatically generates the SQL template for you.

• Use the Sybase Central code editor to enter the SQL query.

❖ Using the Add Template wizard:

1 Use Sybase Central to connect to the sample Web site.

113

Tags tutorial

itor

.

Add editor

2 Open the root folder of the Web site.

3 In the right pane of Sybase Central, double-click Add Template.

4 Enter a name for the document you are creating, and click Next.

5 You may enter a description of the document. The description you enter is displayed as an HTML H1 element. Click Next.

6 If you have more than one connection, select the connection to use for this document. Select <inherited> unless you want to connect to a database other than the one where your Web site is stored. Click Next.

7 Click Select. The SQL Query Editor opens.

8 From the Tables tab, double-click on the customer table. The customer table appears under the selected table panel.

9 Select the Columns tab. Double-click on the following columns in the order given.

• Id

• Fname

• Lname

• phone

10 Click OK once you have completed the SQL query. This closes the edand returns you to the wizard. Click Next.

11 Select HTML as the type of document you wish to create. Click Next.

12 Select “Table with headings” as the format to display your SQL queryClick Finish.

You can also create a document with an embedded SQL query by using thea Script wizard to create a script and then using the Sybase Central code to add the SQL tags and query by hand.

❖ Using the Sybase Central code editor

1 Use Sybase Central to connect to the sample Web site.

2 Double-click the document to edit.

3 The document opens in the code editor ready for editing.

The document you just created contains a simple embedded SQL query.

Next, we’ll add a FORMATTING tag to display the results of the query.

114


Using the FORMATTING tagUse the FORMATTING tag to display rows in the form of a table or a list. When you perform a query, you usually do not know how many rows will be returned.

To display the output as a simple table with no borders, headings or titles, enter:

<TR>



The template you created with the Add Template wizard automatically inserted FORMATTING tags. Your template should look something like this:


--><TABLE BORDER><TR><TH>id</TH><TH>lname</TH><TH>fname</TH><TH>phone</TH></TR><TR><TD></TD><TD></TD><TD></TD><TD></TD></TR></TABLE></BODY></HTML>

115

Tags tutorial

The  tag indicates that the tags following it provide information on the formatting of the query. The  tags represent data in a column. This example has four  tags; one for each column being returned.

To assign column headings of the database table to the output, enter:

<TR><TH>id</TH><TH>lname</TH><TH>fname</TH><TH>phone</TH></TR>

You can use the Sybase Central code editor to edit formatting tags.

❖ To alter a table heading with the Sybase Central code editor:

1 From Sybase Central, double-click on the template you created. The template opens in the code editor.

2 Change the line:

<TH>id</TH>

to

<TH>Customer ID</TH>

3 Change the line:

<TH>lname</TH>

to

<TH>Last Name</TH>

4 Change the line:

<TH>fname</TH>

to

<TH>First Name</TH>

5 Select File→ Save to Database or click the Save to Database icon to save the changes you have made to the file.

You have now altered the table headings of your query. To view the template with these changes, right-click on the template within Sybase Central, and select Browse Output.

116


The LABEL tag Yet another way to alter the formatting of your output is by using the LABEL tag. LABEL allows you to return the column name along with the column data. For example, you could set up a query to return output in this format:

id: 101lname: Devlinfname: Michaelphone: 2015558966

id: 102lname: Reiserfname: Bethphone: 2125558725

id: 103lname: Niedringhausfname: Erinphone: 2155556513

❖ To use the LABEL tag to format the output of a SQL query:

1 Use the code editor to open the template you created previously.

2 Delete the text between the  and  tags so that your template contains only the following lines:

<HTML><TITLE>SQL_tag1.stm</TITLE><BODY><H1>Customer Information</H1>





</BODY></HTML>

3 To assign a label to each unit of data that is returned by the query, enter this line four times between the formatting tags:

: <BR>

117

Tags tutorial

Using HTML tags with Dynamo tagsYou can use normal HTML tags with the Dynamo tag to format the output. In this example we are using the break (<BR>) tag to format the output in a single column.

4 Save the changes you just made. Your template should now look like this:


-->

: <BR>: <BR>: <BR>: <BR><BR>

</BODY></HTML>

5 To view these changes, right-click on the template within Sybase Central, and select Browse Output.

Using the error checking tagsQueries and manipulations against a database may sometimes generate errors. When errors occur, it is more useful to display a message to the user rather than an empty table of results. Dynamo includes several error-checking tags.

The next example first queries the product table from the Sample database, then adds error checking to ensure that no errors occur while the output is generated.

118


❖ To use error checking tags in your template:

1 Create a Dynamo template called error_check.stm that contains the following code:

<HTML><TITLE>error_check.stm</TITLE><BODY><H1>Error Checking Example</H1> <TABLE BORDER><TR><TH>Product Name</TH><TH>Quantity</TH><TH>Unit_price</TH><TH>Total</TH></TR><TR><TD></TD><TD></TD><TD></TD><TD></TD></TR></TABLE></BODY></HTML>

The output from this query list all inventory items, and the quantity, price, and total value of each item.

2 Use the SQL_ON_NO_ERROR tag to ensure that the output is error-free.

Add the SQL_ON_NO_ERROR tags at the beginning and end of the portion of the file you want error-checked. Your template should look like this:

<HTML><TITLE>error_check.stm</TITLE><BODY><H1>Error Checking example</H1>

119

Tags tutorial

<TABLE BORDER><TR><TH>Product Name</TH><TH>Quantity</TH><TH>Unit_price</TH><TH>Total</TH></TR><TR><TD></TD><TD></TD><TD></TD><TD></TD></TR></TABLE> </BODY></HTML>

3 You can use the SQL_ON_ERROR tag to add a comment that displays only if an error is encountered.

The default behavior of the SQL tag in the event of an error is to abort processing. For this reason, you must add the NO_SQL_ERROR to the SQL tag. This will allow the template to continue executing even if an error is encountered. For example:

<HTML><TITLE>error_check.stm</TITLE><BODY><H1>Error Checking example</H1> <TABLE BORDER><TR><TH>Product Name</TH><TH>Quantity</TH><TH>Unit_price</TH><TH>Total</TH></TR><TR><TD></TD><TD></TD><TD></TD><TD></TD>

120


into used uery uery.

of ndle tacts at

</TR></TABLE> <P>An error has occurred. Contact your system administrator.</P></BODY></HTML>

4 View the output of your template. You should see the output of your query in table format as expected.

5 Change the SQL query so that it has an error in it. Add a spelling mistake to the table that is being queried, for example:

select name, quantity, unit_price, (quantity * unit_price) as total from prodduct

Save your changes.

6 View the output of your template. Once the error in the query is encountered, the formatting instructions surrounded by the SQL_ON_NO_ERROR tags stop and the SQL_ON_ERROR tags take effect. The text indicating that an error has been encountered is displayed.

See the SQL_ERROR_CODE, SQL_ERROR_INFO, and SQL_STATE tags in “Dynamo Tags” in PowerDynamo Reference for information on how to display errors returned by the database.

Using the INCLUDE tagUse the INCLUDE tag to incorporate generated output from a document the current document. This can be useful when an identical SQL query is by several different documents. Instead of maintaining and updating the qin each document, you can create one template containing the common q

Let’s say that you have an internal Web site that requires a the same list customer contacts on several different Web pages. The easiest way to hathis is to create one template that queries the customer table for a list of conand then to include that template within all the Web pages that required thdata.

121

Tags tutorial

❖ To include the output of a document within another document:

1 Create a template that performs the required query. For example, the following template customer.stm queries the customer table for a list of all customer contacts and displays the results in table format:

<TABLE BORDER><TR><TH>company_name</TH><TH>lname</TH><TH>fname</TH><TH>phone</TH></TR><TR><TD></TD><TD></TD><TD></TD><TD></TD></TR></TABLE>

2 Create a second template that lists expectations for Sales reps. For example:

<HTML><H1>Customer List</H1><H2>Expectations</H2><P>Each sales rep is expected to contact the customers on their contact list a minimum of once every two weeks. For a list of the customers that you are responsible for please talk to you supervisor.</P></HTML>

3 This example would benefit from displaying a list of customer contacts as well as the expectations. To do this, you need only add one line to the example, which includes the generated output from the customer list. After the “Customer List” heading, add this line:



Your example should look like this:

122


les e.

<HTML><BODY><H1>Customer List</H1><H2>Expectations</H2><P>Each sales rep is expected to contact the customers on their contact list a minimum of once every two weeks. For a list of the customers that you are responsible for please talk to you supervisor.</P></BODY></HTML>

4 Save the template and view the output.

Using the SQL_INSERT tagUse SQL_INSERT to create a Web page that updates data in a database.

For example, let’s say you want to create an internal Web page for the sagroup that allows the sales staff to add new customers to the contact tabl

❖ To create a Web page that updates the database:

1 Create a template called NewCustomer.stm that looks like this:

<HTML><TITLE>newCustomer.stm</TITLE><BODY><H1>New Customer</H1><P>Enter the following information</P><FORM METHOD=POST ACTION="insertCust.ssc"><OL><LI><INPUT TYPE="text" NAME="id" >ID of the customer<BR><LI><INPUT TYPE="text" NAME="last_name" >Last name of the customer<BR><LI><INPUT TYPE="text" NAME="first_name" >First name of the customer<BR><LI><INPUT TYPE="text" NAME="title" >Customer title<BR><LI><INPUT TYPE="text" NAME="street" >Street<BR><LI><INPUT TYPE="text" NAME="city" >City<BR><LI><INPUT TYPE="text" NAME="state" >State<BR><LI><INPUT TYPE="text" NAME="zip" >Zip Code<BR><LI><INPUT TYPE="text" NAME="phone" >Phone

123

Tags tutorial

number<BR><LI><INPUT TYPE="text" NAME="fax" >Fax number<BR></OL><P><INPUT TYPE="submit"></p><P><INPUT TYPE="RESET" VALUE="Clear Form"></P></FORM></BODY></HTML>

In a browser, this template would look like Figure 5-1:

Figure 5-1: NewCustomer.stm template

2 The NAME tags must match the appropriate column in the table that the information is being inserted into. For example, the field that requests the customer’s first name has a NAME tag of first_name. This matches the first_name column in the contact table.

124


ript

3 Save the template.

4 Create a template called insertCust.ssc. To take the data that is entered in the NewCustomer.ssc template and add it to the database. It should look like this:

<HTML><TITLE>insertCust.ssc</TITLE><BODY><H1>New Customer</H1><P>Click here <a HREF=NewCustomer.ssc>here </a> if you would like to add another customer</P><P>Click here <a HREF=Customer.stm>here </a> if you would like a listing of all customers</P></BODY></HTML>

5 Save the template.

6 Display the NewCustomer.ssc page in your browser and add a new customer as requested (make sure you enter a unique customer ID).

7 You have now added data to the contact table of the database.

The SCRIPT tagUse the SCRIPT tag to embed Dynamo script language within documents. The format:



lets Web editing tools know that they should ignore all text between the start tag () while also letting the Dynamo application server know that there is DynaScript present that requires processing.

For more information on the SCRIPT tag and DynaScript, see “The DynaScLanguage” in PowerDynamo Reference.

125

Tags tutorial

126

C H A P T E R 6 Writing DynaScripts

About this chapter This chapter introduces DynaScript, which is the PowerDynamo server-side language that provides programmable control over the content returned to a Web client.

Contents Topic Page

Overview of scripts 128

Script tutorials 130

127

Overview of scripts

ripts

as

t or

Overview of scriptsYou can embed scripts in HTML templates to control the information that the template provides to the user. The PowerDynamo script language, DynaScript, uses a syntax much like JavaScript. DynaScripts are interpreted by the application server, and the results of that interpretation are passed on to the Web server.

Script language summary

DynaScript has the following characteristics:

• Scripts are usually embedded in an HTML template. You can also maintain a script as a separate file in the site, and include it in other scor templates, allowing for code reuse throughout the site.

• Because DynaScript is processed at the application server, before thecontent is passed back to the client, no client support for scripting is required.

• Script statements and variables are case-sensitive.

• You do not need to declare variables.

• Scripts can use the following datatypes:

• numeric

• logical (Boolean) true or false

• string

• null

• function

• object (methods and properties)

• Variables do not have a fixed datatype. Datatype assignment occurs needed when expressions are evaluated.

• Control statements such as if, while, do-while and for have a syntax similar to C and Java.

• You can create objects and define their properties and methods.

• DynaScript includes several built-in object types for working with databases, SQL, and HTML documents.

Using a server-side language

Scripting languages for the Internet are interpreted at either the Web clienthe Web server.

128

CHAPTER 6 Writing DynaScripts

to

n

lient.

t the

ding s

ingle

s Perl.

this

ith

to

hat

DynaScript is a server-side language that follows the ECMAScript standard (the standardized version of JavaScript). DynaScript has a syntax much like JavaScript. There are many uses for a server-side scripting language:

• Maintaining information through a series of client accesses.

• Detailed control over formatting of SQL queries.

• Error-checking for SQL statements. For example, you can use scriptscheck the success or failure of a delete statement, and to send an appropriate message to the Web client.

• Client-independent form validation. It is quicker to validate entries in aHTML form at the Web client, but validation at the server makes an HTML form client-independent.

• Server-side scripts can reduce the amount of data being sent to the c

There are some tasks that can be better performed (or only performed) aclient side. For example, you cannot direct HTML to different frames in a window from the server side.

Why a JavaScript-based language?

There are several languages commonly used for Web-related tasks, incluJava, JavaScript, and Perl. An ECMAScript compatible language provideseveral advantages in PowerDynamo:

• While the strict typing and mandatory variable declaration of Java aredesirable for large-scale application development, they can cause unnecessary overhead when developing small scripts attached to a sWeb page.

• The object-based structure of ECMAScript allows more readable andmaintainable code than languages with many special features, such a

Implementing scripts You can implement DynaScript in several ways:

• You can embed Scripts in HTML templates. This is the most straightforward way of using scripts, and how most of the examples in chapter are presented.

• You can write a script that generates an entire document (complete wHTML tags and queries). The Web client can request the script itself (rather than a separate HTML document), and the application server interprets the script to generate both the HTML and the query output return to the client.

• You can group common functions or class definitions into a separate script. You can then import this script into any other script or template trequires those functions or classes.

129

Script tutorials

Script tutorialsThis section presents some simple scripts that introduce you to DynaScript.

Embedding a Script in HTMLWriting HTML with scripts

The following example shows how to embed a script into an HTML template. This script simply writes Hello world to the HTML document that is generated for the Web client.

❖ To create this script:

1 In Sybase Central, connect to a Web site.

2 In the left pane, click the Site folder (inside the site database).

3 In the right panel, double-click Add Template.

4 On the first page of the wizard, enter the template name as

first_template

Click Next.

5 Enter a description if you wish. For example:

A test template containing a simple script

Click Next.

6 Do not enter anything on the Add SQL Query page; click Next to move to the next page.

7 Select <default> from the list of supplied formats.

8 Click Finish.

This adds first_template.stm to the Web site.

9 Double-click the template to open it in the code editor It should look like this:

<HTML><TITLE>first_template</TITLE><BODY><H1>A test template containing a simple script</H1></BODY></HTML>

130


p

e

is to

r can

IPT

10 After the <BODY> tag, enter:



11 Click File→ Save Script. This saves your updated template in the Dynamo site.

❖ To display the source code of this script:

• In the right pane, right-click first_template and click Open in the pop-umenu. As a shortcut, you can double-click the script icon instead.

❖ To execute the script against the application server:

• In the right pane, right-click first_template and click View Output in thpop-up menu.

You see:

<HTML><TITLE>first_template</TITLE><BODY>Hello world</BODY></HTML>

When this script is executed from the Web site, the Web server returns ththe Web client, which in turn interprets the HTML for the user:

Hello world

Scripts are embedded in HTML templates

The script is embedded as a comment in the body of a minimal HTML document. An HTML comment is marked by a tag like this:



DynaScript is comments use the SCRIPT tag, so that the application serverecognize it:



JavaScript vs. Dynamo Be careful not to confuse JavaScript SCRIPT tags with DynaScript SCR

tags; the syntax is very similar.

JavaScript uses this syntax:

131

Script tutorials

<SCRIPT LANGUAGE="JavaScript">

DynaScript uses this syntax:



The parts of the script The body of the script consists of a single instruction:

document.Write( "Hello world" );

Here, document is a predefined object that refers to the HTML document being executed.

The statement optionally ends with a semicolon.

Objects have methods associated with them. A method is a function that carries out actions on an object. Write is a method of the document object.

An object method can take arguments and carries out actions, like a function or subroutine in other programming languages. In this case, the argument to the method is the character string "Hello world". The Write method inserts this string into the HTML document that is sent to the client when the template is requested.

Using variables and expressionsThe following example script illustrates how scripts use variables and how expressions are evaluated and assigned to variables:



To try this script out, you can use the Sybase Central editor to replace the script in the template you created in the previous section.

The output from this script is:

Colorless green ideas sleep furiously

Declaration and assignment of variable values

You do not have to declare variables (although it is good practice to declare them anyway). Note how the first line of this script creates a variable called quote and assigns it the value of the string "Colorless green ideas".

132


The + operator concatenates the two strings, and the resulting expression is assigned to the variable quote. The last line sends the value of the variable as a string to the HTML output.

Variable types and operators

Unlike variables in many compiled programming languages, Dynascript variables do not have fixed datatypes. The datatype of a variable is set whenever the variable is assigned a value. You can change the datatype of a variable by assigning it an expression of a different type.

While this is convenient for small scripts, it does require that you take care when working with variables.

The same applies to operators. For example, the meaning of the + operator depends on the expressions it is operating on. In the previous example + was used to concatenate two strings, but if it is operating on integer expressions rather than string expressions, it adds rather than concatenates the expressions. Consider the following script:



The output from this script is the following HTML string:

579

The value of sum is set to the integer 123 in the first line. In the second line the + operator acts on the two integers, and so adds them to produce the value 579. In the final line, this integer is converted to a string for output.

Using control statementsYou can use the following control statements to allow looping or conditional execution of statements:

• if-else

• for

• while

• do-while

These statements use standard C syntax.

133

Script tutorials

te a t the

g

A script using the while statement

The following example illustrates the use of the while statement:



This script prints the following HTML:

This is paragraph 1<P>This is paragraph 2<P>This is paragraph 3<P>

Notes Notice the way that the + operator acts in this script:

• In the expression (i + 1) it adds two integers.

• The other two + operators recognize a string, and combine the other variable with the string by concatenation.

Using functionsYou can define and use functions in scripts, which allows you to encapsulaset of instructions once in a document, and use it several times throughoudocument.

The following example shows how to provide consistent custom formattinacross headings in an HTML document:

<HTML><TITLE>Function testing</TITLE>

<BODY></BODY></HTML>

Notes Note the following in this example:

• The h1 function is defined before it is invoked.

• The h1 function does not return a value to the calling script, so it is calusing a simple statement. You can also return a value from a function uthe return statement, in which case you typically call the function as pof an assignment statement.

• Simple variables such as strings and numbers are passed to functionby value, while objects (including arrays) are passed by reference.

Using simple objectsDynaScript is object-oriented. An object can have properties (data) associated with it, as well as methods (functions that act on the properties). You can usthe predefined objects included with Dynamo, or create your own customobjects.

For example, you could create a class of object called product. You can add properties to store all the information about a product (such as the producname, color, size, description, price, and quantity in stock). You can also methods that carry out typical actions on the product, such as ordering a cequantity.

Using an object There are two steps to using an object:

1 Declare the structure of the object using a function or class statement.

This defines the name of the class, and its properties and methods. Inthe class definition, the properties and methods identify themselves aclass members by using the prefix this.

2 Create an instance of the class using the new operator.

For example, the following class statement defines the product class:

class product(id, name, size, color,quantity, price) {

this.id = id ; this.name = name ; this.size = size ; this.color = color ;

135

Script tutorials

this.quantity = quantity ; this.price = price ;}

To create currentProduct, which is an actual object (or instance) of the product class, use new with the appropriate property values:

var currentProduct = new product(600, "Sweatshirt", "Large", "Green", 39, 24.00 ) ;

Using objects In practice, you could have an application that takes an ID from an HTML form filled out at a Web client, and use that ID together with a SQL query to fill out the properties of the currentProduct object. Combining scripts with SQL queries and responding to user input are discussed in later sections.

Defining methods for an object

So far, the product class has properties, but no methods to act on those properties. To add a method to an object, you must:

1 Define a function that carries out the actions you want.

You can define the function inside the class definition, or as a global definition (outside the class definition).

2 Assign the function to the class.

For example, you could define an order method for the product class, which carries out the proper actions when a product is ordered:

function order ( orderQuantity ) {// order returns true if the order is successful,// false if stock is too lowif ( this.quantity >= orderQuantity ) {

this.quantity -= orderQuantity ;return ( true ) ;

} else {return ( false ) ;

}}

Since we’ve declared order as a global function in our script, its definition must precede the definition of the product class. We can then make the order function a method of product by adding a line to the class definition:

class product( id, name, size, color,quantity, price ) {

this.id = id ;

136


this.name = name ; this.size = size ; this.color = color ; this.quantity = quantity ; this.price = price ; this.order = order ;}

Since we haven’t added any new properties, creating a new instance of the product class is the same as it was before:

var currentProduct = new product(600, "Sweatshirt","Large", "Green", 39, 24.00 ) ;

You could then use the order method in a template as follows:



Using arraysArrays are useful for keeping track of a collection of objects. Typically, you index a variable using integers, as in this example of three prices:

price = new Array(3);price[0] = 19.95;price[1] = 42.99;price[2] = 0.02;

A common programming construct is a loop that performs some action on each element of an array. The loop variable iterates over the index of the array, as in the following example:

137

Script tutorials

for ( i = 0 ; i < price.length; i++ ) {document.WriteLn("Price of item #" +

i + " = " + price[ i ] );}

This produces the following output:

Price of item #0 = 19.95Price of item #1 = 42.99Price of item #2 = 0.02

Passing variables from one document to anotherSome functions must be able to receive and act on user input from the Web client. This information is sent by the Web client when a form is filled out as part of the Uniform Resource Locator (URL) that retrieves the form.

For example, suppose the Web client displays a form containing a list box, a text box, and an Order button. The user selects a particular product from the list, enters the desired quantity in the text box, then clicks the button to order the product.

The Order button points to an order-processing template that has a URL of http://www.sybase.com/products/order.html. When the Order button is clicked, the Web client sends the URL along with arguments that specify the order information. For example, if the user orders 25 of product #600, the complete URL would be:

http://www.sybase.com/products/order.html?id=600&quantity=25

The question mark separates the address of the document from the arguments supplied to the document. An ampersand separates each of the arguments in the list. In this example, the two arguments id and quantity are sent, with values 600 and 25 respectively.

Referring to arguments in the document

You can fill in the value of a supplied argument in the HTML part of a document by preceding the value with a dollar sign. For example:

<HTML><TITLE>Displaying variables</TITLE><BODY>The value of argument quantity is $quantity.</BODY></HTML>

If this template is called with this URL:

138


http://address?quantity=25

the following HTML is returned to the Web client:

<HTML><TITLE>Displaying variables</TITLE><BODY>The value of argument quantity is 25.</BODY></HTML>

Using arguments in scripts

You can also use arguments inside scripts. The argument is a property of the document, which is a predefined object. The actual value of an argument named quantity can be accessed inside a script as:

document.value.quantity

The following script responds to user input for an order:



For information on passing values of a multiple selection list see “value property” in PowerDynamo Reference.

139

Script tutorials

Using object inheritanceDynaScript extends JavaScript to include inheritance, which is the ability to create a new class of object that extends an existing class. The new class inherits all of the properties and methods of the parent class, and adds its own properties and methods.

This is tremendously useful when you are dealing with objects that share characteristics. Instead of defining each object separately, you can identify the information and behavior that is common to them, then define the objects themselves as extensions of the common material.

Without inheritance For example, suppose that Acme Widgets has some employees that are paid a salary, while others are paid by the hour. You could define two separate classes, salariedEmployee and hourlyEmployee, with their own sets of properties and methods. Here’s a simple version:

class salariedEmployee(name, title, managerName, salary)this.name = name;this.title = title;this.managerName = managerName;this.salary = salary;function PrintNameAndTitle() {

document.WriteLn("Name, title: " + this.name+ ", " + this.title); }

this.PrintNameAndTitle = PrintNameAndTitle;function PrintAllInfo() {

document.WriteLn("Name: " + this.name);document.WriteLn("Title: " + this.title);document.WriteLn("Reports to: " +

this.managerName);document.WriteLn("Salary: " + this.salary); }

this.PrintAllInfo = PrintAllInfo;}class hourlyEmployee(name, title, managerName, wage)this.name = name;this.title = title;this.managerName = managerName;this.wage = wage;function PrintNameAndTitle() {


this.PrintNameAndTitle = PrintNameAndTitle;function PrintAllInfo() {

document.WriteLn("Name: " + this.name);document.WriteLn("Title: " + this.title);

140


document.WriteLn("Reports to: " +this.managerName);

document.WriteLn("Hourly wage: " + this.wage); }this.PrintAllInfo = PrintAllInfo;}

With inheritance Because there is a lot of duplication between the two classes of employees, you’ll be maintaining two nearly identical sets of code. Suppose instead that we take the common items (name, title, managerName, and PrintNameAndTitle) and move them into a new generic class called employee:

class employee(name, title, managerName) {this.name = name;this.title = title;this.managerName = managerName;function PrintNameAndTitle() {


this.PrintNameAndTitle = PrintNameAndTitle;}

We can then change salariedEmployee and hourlyEmployee to use this new employee class as their common parent. To do this, we use the extends clause of the class statement:

class salariedEmployee(name, title, managerName, salary)extends employee(name, title, managerName) {

this.salary = salary;function PrintAllInfo() {


this.managerName);document.WriteLn("Salary: " + this.salary);

}this.PrintAllInfo = PrintAllInfo;

}class hourlyEmployee(name, title, managerName, wage)extends employee(name, title, managerName) {

this.wage = wage;function PrintAllInfo() {


this.managerName);

141

Script tutorials

document.WriteLn("Hourly wage: " +this.wage);

}this.PrintAllInfo = PrintAllInfo;

}

We can then try out the redefined classes by creating salaried and hourly employees, then printing their information:

var salaryEmp = new salariedEmployee("Ned Simpson", "Technical Writer", "Barney Burns", 80000);salaryEmp.PrintNameAndTitle();salaryEmp.PrintAllInfo();document.WriteLn("");var hourlyEmp = new hourlyEmployee("Marge Flanders", "Contractor", "Barney Burns", 25);hourlyEmp.PrintNameAndTitle();hourlyEmp.PrintAllInfo();

This produces the following output:

Name, title: Ned Simpson, Technical WriterName: Ned SimpsonTitle: Technical WriterReports to: Barney BurnsSalary: 80000Name, title: Marge Flanders, ContractorName: Marge FlandersTitle: ContractorReports to: Barney BurnsHourly wage: 25

There are several things to note here:

• The salariedEmployee and hourlyEmployee classes do not have their own PrintNameAndTitle methods, so they automatically use thePrintNameAndTitle method of the employee parent class.

If required, these classes could define their own PrintNameAndTitle methods, which would be used instead of the parent class's PrintNameAndTitle method. This is called overriding a parent method.

142


an

s

,

• The PrintAllInfo method is polymorphic; that is, you can call PrintAllInfo for instances of salariedEmployee and hourlyEmployee, and they each respond in their own way. This is especially handy when looping through arrays of objects, since you cuse the same method call on each object (instead having to use if statements to call methods like PrintAllSalariedInfo, PrintAllHourlyInfo, and so on).

• Once you have defined salariedEmployee and hourlyEmployee, we would not ordinarily create instances of the parent class employee – it is designed as an abstract class that simply collects the common propertieand behavior.

To handle a third kind of employee who was neither salaried or hourlysimply create a new class derived from employee and add the appropriateproperties and methods (including a PrintAllInfo method.

143

Script tutorials

144

C H A P T E R 7 PowerDynamo and Java

About this chapter This chapter provides an introduction to Java and an example of using Java within a PowerDynamo script.

Contents Topic Page

An introduction to Java 146

Dynamo and Java 155

Configuring Dynamo to use Java 156

Using Java in a PowerDynamo script 158

145

An introduction to Java

and e

cal late tal.

ed to

An introduction to JavaThis section introduces key Java concepts. After reading this section you should be able to examine Java code, such as a simple class definition or the invocation of a method, and understand what is taking place.

Object-oriented and procedural languagesThis section explains some of the key similarities and differences between procedural and object-oriented languages.

Java is based on classes

The main structural unit of code in Java is a class. A Java class is a collection of procedures and variables that have been grouped together because they all relate to a specific, identifiable category.

The manner in which classes get used is what sets object oriented languages apart from procedural languages. When an application written in a procedural language is executed, it is typically loaded into memory once and takes the user down a predefined course of execution.

In object-oriented languages such as Java, classes are used like templates, in other words, a definition of potential program execution. Multiple copies of a class can be created and loaded dynamically, as needed, with each instance of the class capable of containing its own data, values, and course of execution. Each loaded class can be acted on or executed independently of any other class loaded into memory.

A class that is loaded into memory for execution is said to have been instantiated. An instantiated class is called an object – it is an application derived from the class that is prepared to hold unique values or have its methods executed in a manner independent of other class instances.

For example, you could design an Invoice class to mimic a paper invoice include certain information, like line-item details, who is being invoiced, thdate of the invoice, the payment amount, and when payment is due. Thisinformation is contained in an instance of an Invoice class.

In addition to just holding data, a class is capable of calculations and logioperations. For example, you could also define the Invoice class to calcuthe tax on a list of line items, and add it to the subtotal to produce a final toYou could define every Invoice object to do this without user intervention.

Such a class could also ensure all essential pieces of information are addthe invoice and even indicate when payment is overdue or partially paid.

146

CHAPTER 7 PowerDynamo and Java

the a

e

and .

the ct

or

A class combines the ability to hold information and perform computational operations.

Example The code below declares a class called Invoice. This class declaration would be stored in a file named Invoice.java. It could then be compiled into a Java class, using a Java compiler.

A note about compiling Java classesCompiling a Java class declaration creates a new file with the same name but a different extension. Compiling Invoice.java creates a file called Invoice.class that could be used in a Java application and executed by a Java VM.

The Sun JDK tool for compiling class declarations is javac.exe.

public class Invoice { // So far, this class does nothing and knows nothing}

The class keyword is followed by the name of the class. There is an opening and closing brace: everything declared between the braces, such as fields and methods, becomes a part of the class.

No Java code exists outside class declarations. Even the Java procedure that a Java interpreter runs automatically to create and manage other objects —main method that is often the start of your application—is located within class declaration.

Java classes and objects

A class is the template for what can be done–it defines what an object is capable of doing just as an invoice form defines the information the invoicshould contain.

Information is not held in a class. An object is created based on the classthe object is used to hold data or perform calculations or other operations

An object is said to be of type JavaClass, where JavaClass is the name of the class upon which the object is based. An Invoice object is an instance of Invoice class. The class defines what the object is capable of but the objegives the class meaning and usefulness.

This is similar to the invoice example. The invoice form defines what all invoices based on that form can accomplish. There is one form and zero many invoices based on the form. The form contains the definition but theinvoice does the work.

147


Similarly it is the Invoice object that gets created, stores information, is stored, retrieved, edited, updated, and so on.

Just as one invoice template is used to create many separate and distinct invoices, many objects can be generated from one class.

Methods and fields A method is the part of the class that performs a calculation or interacts with other objects. Methods can accept arguments, and return a value to the calling function. If no return value is needed, a method can return void. Classes can have any number of methods.

A field is the part of a class that ends up holding information. When an object of type JavaClass is created, the fields in JavaClass are available to be passed values unique to that object.

Examples To declare a field in a class, state its type and name, followed by a semicolon. Such a variable is a field if it is declared in the body of the class and not within a method. Declaring a variable within a method makes it a part of the method, not the class.

public class Invoice {

// Fields are things an Invoice object knows public String lineItem1Description; public int lineItem1Cost;

public String lineItem2Description; public int lineItem2Cost;

}

Adding methods

You might want to include a method in the Invoice class. Declare a method by stating its return type, its name, and what parameters it takes (in this case, none). Like a class declaration, the method uses an opening and closing brace to identify the body of the method where the code goes.


// Fields public String lineItem1Description; public double lineItem1Cost;

public String lineItem2Description; public double lineItem2Cost;

148


// A method public double totalSum() { double runningsum; runningsum = lineItem1Cost + lineItem2Cost; runningsum = runningsum * 1.15; return runningsum; }}

Within the body of the totalSum method, a variable named runningsum is declared. This is used first to hold the subtotal of the first and second line item cost. This subtotal is then multiplied by the rate of taxation to determine the total sum.

The local variable (as it is known within the method body) is then returned to the calling function. When the totalSum method is invoked, it returns the sum of the two line item cost fields plus the cost of tax on those two items.

Instance methods and class methods

Most methods are used with an instance of a class. For example, a totalSum method in the Invoice class can calculate and add the tax, and return the sum of all costs, but is useful only if called in conjunction with an Invoice object that has values for its line item costs. The calculation can only be performed for an object, since the object, not the class, contains the line items of the invoice. The class only defines the capability of the object to have line items. Only the object has the data needed to perform such a calculation.

Java methods are divided into two categories:

•Instance methods The totalSum method is an example of an instance method that can only be used in a conjunction with an object and object data.

•Class methods Class methods are also called static methods. A class method can be invoked without an object. Only the name of the class and method is required to invoke a class method.

Similar to instance methods, class methods accept arguments and return values. Typically, class methods perform some sort of utility or information function related to the overall functionality of the class.

149


ral . A ld).

.

n value first. ation

out turn at

The parseInt method of the java.lang.Integer class, which is supplied with Adaptive Server Anywhere, is one example of a class method. When given a string argument, the parseInt method returns the integer version of the string.

For example given the string value “1,” the parseInt method returns 1, the integer value, without requiring an instance of the java.lang.Integer class to first be created as illustrated by this Java code fragment.

String num = "1";int i = java.lang.Integer.parseInt( num );

Fields can also be declared using the static Java keyword, which makes theminto class fields. A static class variable is like a global variable in procedulanguages, except that its value is predetermined and cannot be changedfield whose name is all in capital letters is often a static variable (class fie

Examples The following version of the Invoice class now includes both an instance method and a class method. The class method rateOfTaxation returns the rate of taxation used by the class to calculate the total sum of the invoice

The advantage of making rateOfTaxation a class method (as opposed to ainstance method or field) is that other classes and procedures can use thereturned by this method without having to create an instance of the class Only the name of the class and method is required to return the rate of taxused by this class.

It allows the application developer to change how the rate is calculated withadversely effecting any objects, applications, or procedures that use its revalue. rateOfTaxation can be changed without affecting other methods thuse its return value.


// Fields public String lineItem1Description; public double lineItem1Cost;

public String lineItem2Description; public double lineItem2Cost;

// An instance method public double totalSum() { double runningsum; double taxfactor = 1 + Invoice.rateOfTaxation(); runningsum = lineItem1Cost + lineItem2Cost;

150


.

ely, ects

d by ed by

gory. ds in

that

runningsum = runningsum * taxfactor; return runningsum; }

// A class method public static double rateOfTaxation() { double rate; rate = .15; return rate; }}

A Java glossaryThe following items outline some details regarding Java classes that may aid in the use of Java classes in PowerDynamo.

Public versus private The visibility of a field, method, or class to other Java objects and operations is determined by what is known as an access modifier — essentially the public, private, or protected keyword used in front of any declaration

Fields and methods can be declared private or public, meaning, respectivtheir values are available to code within the object, or to code/classes/objboth inside and outside the object.

Fields or methods declared as private cannot be manipulated or accessemethods outside the class. Public fields or methods can be directly accessother classes and methods.

Packages and the protected modifier

Protected fields or methods are accessible only:

• Within their class

• Within subclasses that inherit from their class

• Within the package of which the class is a part

A package is a grouping of classes that share a common purpose or cateMembers of a package have special privileges to access data and methoother members of the package, hence the protected access modifier.

A package is the Java equivalent of a library. It is a collection of classes, can be made available using the import statement. The following Java statement imports the utility library from the Java API:

151


ge

ss

ace y the

tatic ds The

.

ated.

import java.util.*

Packages are typically held in Java archive (Jar) files, which have the extension .jar or .zip.

Constructors A constructor is a special method of a Java class that creates an instance of the class and returns a reference to the newly-created Java object.

Classes can define their own constructors, including multiple, overriding constructors. Which constructor is used is determined by the arguments used to create the object. When the type, number, and order of arguments used to create an instance of the class match one of the class’s constructors, that constructor is used to create the object.

Destructors There is no such thing as a destructor method in Java (as there is in C++). Java classes can define a finalize method for clean-up operations when an object is discarded, but there is no guarantee that this method will get called.

An object that has no references to is automatically removed by a “garbacollection” process.

Other C++ differences Everything related to a class is contained within the boundaries of the cladeclaration, including all methods and fields.

Classes can inherit from only one class. Java uses interfaces instead of multiple-inheritance. A class can implement multiple interfaces. Each interfdefines a set of methods and method profiles that must be implemented bclass in order for the class to compile.

An interface is similar to an abstract class; it defines what methods and sfields the class must declare. The implementation of the methods and fieldeclared in an interface is located within the class that uses the interface.interface defines what the class must declare, and it is up to the class to determine how it is implemented.

Java error handlingJava error handling code is separate from the code for normal processing

When an error occurs, an exception object representing the error is generThis is called throwing an exception. A thrown exception will terminate a Javaprogram unless it is caught and handled properly at some level of the application.

152


Both Java API classes and custom-created classes can throw exceptions. In fact, users can create their own exceptions classes, which can be thrown by their own custom-created classes.

If there is no exception handler in the method where the exception occurred, the search for an exception handler continues up the call stack. If the top of the call stack is reached and no exception handler has been found, the default exception handler of the Java interpreter running the application is called and the program terminates.

Error types in Java All errors in Java are derived from two types of error classes: Exception and Error. Usually, exception errors are handled by error-handling code in your method body. Error type errors are reserved for internal and resource exhaustion errors inside the Java runtime system.

Exception class errors are thrown and caught. Exception handling code is characterized by try, catch, and finally code blocks.

A try block executes code that may generate an error. A catch block will execute if an error is generated (thrown) during the execution of a try block.

A finally block defines code executes regardless of whether an error was generated and caught and is typically used for clean-up operations. It is used for code that, under no circumstances, can be omitted.

Exception errors are divided into runtime exceptions and those that are not runtime exceptions.

Errors generated by the runtime system are known as implicit exceptions, because they do not have to be explicitly handled as part of every class or method declaration.

For example, an array out of bounds exception can occur whenever an array is used, but the error does not have to be part of the declaration of the class or method that uses the array.

All other exceptions are explicit. If the method being invoked can throw an error, it must be explicitly caught by the class using the exception throwing method, or this class must explicitly throw the error itself by identifying the exception it may generate in its class declaration.

A method must declare all the explicit errors it throws, or catch all the explicit errors that may be potentially thrown.

Non-runtime exceptions are checked at compile time. Runtime exceptions are usually caused by errors in programming. Java catches many such errors during compilation, before the code is run.

153


Every Java method is given an alternative path of execution so that all Java methods complete, even if they are unable to complete normally. If the type of error that is thrown is not caught, it’s passed to the next code block or method in the stack.

154


t

s that

Dynamo and JavaPowerDynamo supports Java classes in PowerDynamo scripts.

You can create Java classes using PowerJ or any other Java development tool. These classes are then deployed to one of two places for Dynamo scripts to have access to them:

• A PowerDynamo Web site (database-hosted or file-hosted)

• The file system of the PowerDynamo host machine

Before you can write Dynamo scripts that use Java objects, you must firsconfigure PowerDynamo to recognize these classes.

You should restart Dynamo whenever changes are made to the Java clasis being instantiated.

155

Configuring Dynamo to use Java

Configuring Dynamo to use JavaYou must configure your Web site to use Java class objects within your Web site. You should be aware of the following configuration options in the Configuration folder of Sybase Central if you wish to create and use instances of Java class objects within your Dynamo scripts.

❖ Java VM

Dynamo provides Java support only if you have selected a Java VM in the Sybase Central Configuration folder.

1 From the Configuration folder, open the Default General Settings folder.

2 In the right pane, double-click the Java VM setting.

3 Select the Java VM option from the drop-down list and click OK.

4 Restart PowerDynamo if you change the Java VM.

NoteIf using the Sun VM you must have JDK 1.1.6 or higher installed. For information, see http//java.sun.com/jdk/1.1. If using the Microsoft VM, you must have msjava.dll (version 5) installed. For information, see http//www.microsoft.com/java/download.htm.

❖ Java class cache

To improve performance, information about the methods and properties of Java classes is cached. To set the Java class cache:

1 From the Configuration folder, open the Mappings folder.

2 In the right pane, double-click the URL prefix to modify.

3 Enter the maximum size of the java cache and click OK. The default value is 2048KB.

4 If you change your cache size, you must restart PowerDynamo.

❖ Classpath for the mapping

Class files that are stored in a database-hosted Web site must have their class path specified in Sybase Central. If class files in the file system are being called, you do not need to set this classpath. To set the Classpath:

1 From the Configuration folder, open the Mappings folder.

2 In the right pane, double-click the URL prefix to modify.

156


ts

ses

3 Enter the classpath for this mapping in the field provided and click OK.

4 If you change your classpath, you must restart PowerDynamo.

Executing scripts from within Sybase CentralTo execute scripts that use the Java objects from within Sybase Central, the mapping and Dynamo site name must be identical. If you are running your scripts exclusively through a server such as the Personal Web Server, this is not necessary.

Check he following PATH and CLASSPATH environment variables:

• If using the MS VM, ensure that your PATH variable points to msjava.dll.

• If using the SUN VM, ensure that your PATH variable points to javai.dll or java.dll.

• If using the SUN DebugVM, ensure that your PATH variable pointo javai_g.dll or java_g.dll.

• Ensure that your CLASSPATH variable contains the path to the system classes for the VM that you are using (typically these clasare contained in a file called classes.zip).

157

Using Java in a PowerDynamo script

should

on

of

on

Using Java in a PowerDynamo scriptJava classes can be stored either in the PowerDynamo Web site, a dynamic Web site, or somewhere on the file system. Importing a Java class into a PowerDynamo Web site is the same as importing any other file. Once the Java class is in an accessible location, you are ready to use the class in a Dynamo script.

Java classes can be accessed from within a database or within the file system. Depending on which of these locations you will be accessing your Java class from, you will have to perform certain steps. Generally, you should store Java classes within a database when you want to replicate the classes along with the database. If you don’t need the Java classes stored in the database, you probably store them in the file system for performance reasons.

❖ To call Java classes stored in the file system:

1 Write and compile your Java code.

2 Set the required Java VM from within the Sybase Central Configuratifolder.

3 Modify the CLASSPATH environment variable to point to the location the Java class in the file system.

4 Restart PowerDynamo.

5 Write your PowerDynamo script.

6 Execute.

❖ To call Java classes stored in a Dynamo Web site:

1 Write and compile your Java code.

2 Import the Java class into the database.

3 Set the required Java VM from within the Sybase Central Configuratifolder.

4 Modify the Dynamo CLASSPATH in the Sybase Central Configurationfolder to point to the imported Java class.

5 Restart PowerDynamo.

6 Write your PowerDynamo script.

7 Execute.

158


File-hosted Web siteA Web site that is hosted in the file system can use either of these methods but storing Java classes in the file system probably produces more efficient results.

Here is a simple example of a Java class that performs basic string manipulation. Let’s assume that the following Java class has been imported into our database-hosted Web site.

public class testclass { public String str; public testclass( String str1 ) { str = str1; } public testclass() { str = "";} public String getstr() { return str; } public void setstr( String newstr ) { str = newstr; } public String Upper() { return Upper( str ); } public String Upper( String str1 ) { return str1.toUpperCase(); }}

Let’s also assume that we have chosen our Java VM and set the CLASSPATH variable using Sybase Central.

In our script we will use the Java.CreateObject method. The Java object manipulates Java classes within PowerDynamo scripts. The CreateObject method is just one of the Java objects methods and is used to instantiate a Java class so that it can be used as an object within your PowerDynamo script. The syntax for this method is:

java.CreateObject( class_name [, list of constructor parameters] )

The Java class we are going to use in our script is called testclass. It does not take any parameters. The proper syntax to instantiate testclass in our script is:

cls1 = java.CreateObject( "testclass" );

159


va

n

The Java class that we are instantiating has properties and methods associated with it. To use those properties within our Dynamo script, the Java class must contain both get and set functions for this property. For example, testclass has a property called str. When this property is used within a Dynamo script to display the value of the str property ( document.WriteLn( cls1.str ); ) in actuality, the getstr function from the Java class is called. The same holds true for setting a property; the setstr function would be called. If you look at the testclass code you will see that the str property has both get and set functions.

Working with methods of an instantiated Java class is the same as working with any DynaScript method.

Methods that take a Java class parameterIf you have a method that takes another Java class parameter, that class must be instantiated within the script before it can be used.

For further information about the Java object and its methods see “The jaobject” in PowerDynamo Reference.

The following is a Dynamo script that provided two strings for manipulatioby the testclass object:



The output for this script would look something like this:

1 2 This is my very long test string that I am using3 THIS IS MY VERY LONG TEST STRING THAT I AM USING4 THIS IS ALL UPPER

As you can see, once you have instantiated the Java class within your script, you work with the Java object in the same manner that you would work with any other object within a Dynamo script.

Arrays in JavaPowerDynamo does not support array indexing in Java. Use the Java class java.lang.reflect.Array if you require array manipulation. For example:



161


CallStaticMethodThis example uses the CallStaticMethod method of the Java object, which enables users to access static methods without creating (java.CreateObject) an instance of the object within the script.

Method overloading and type conversionMethod overloading in Java may occasionally cause problems in Dynamo.

In most cases, PowerDynamo can handle overloading. There are a few cases, however, where this is not the case. For example, take the following methods:

My_method( long, string, bool, int );My_method( int, string, bool, int );

Lets assume that the following method call is being made:

Obj.My_method( 4, "hello", true, 7 );

Although Dynamo strings and Java strings are not exactly the same, Dynamo is able to recognize the difference and make the conversion. The same is true for converting Java Booleans to Dynamo Booleans and Java ints to Dynamo ints.

The problem arises for the above example because Dynamo does not know which method to use. The variables hello, true, and 7 are all easily identified. The variable 4, however, could be either an integer or a long so either method could be the correct one to use. At this point an error message indicating an ambiguous method call displays.

If the My_method was instead overloaded in the following manner:

My_method( string, string, bool, int );My_method( int, string, bool, int );

There would be no problem with the method call, Dynamo can discern that 4 is an int and not a string.

162


e the

Calling Jaguar componentsYou can use PowerDynamo to call Java components through Jaguar CTS. This process is explained in “Calling Jaguar Component Methods from PowerDynamo” on page 261. For complete information on Jaguar CTS, seJaguar documentation.

163


164

C H A P T E R 8 Working with XML Documents

About this chapter XML is becoming a standard framework for exchanging data over the Web. This chapter describes how you can use Dynamo to manipulate XML documents and data.

Contents Topic Page

Dynamo and XML 166

An introduction to XML 167

Creating XML documents 170

Introduction to the Document Object Model 177

Document Object Model examples 182

Creating the DOMDocument object 187

Working with elements 189

Working with text 193

Working with entities 197

Working with other XML objects 199

Using the DOM interface to create and edit XML documents 200

165

Dynamo and XML

7.

Dynamo and XMLXML stands for eXtensible Markup Language. It is a framework for creating markup languages. Each XML markup language is a set of tags (or elements), and a set of rules about where each element can occur.

HTML is an example of a markup language. It contains elements such as headings, lists, tables, and so on. There are rules governing where these elements can occur.

XML provides a framework for data exchange. An XML document can hold many kinds of data, including file formats, relational database data, and information transmitted from Web browsers to Web servers.

For example, you can use XML to describe a sales transaction exchanged between two applications or to describe the contents of a Web page. For the remainder of this chapter, the word document is used to mean any XML document.

Dynamo and XML Dynamo provides several tools for working with XML.

• DynaScript functions and tags that let you take information from a database, and provide it to a Web browser in XML form.

For information, see “Creating XML documents” on page 170.

• A DynaScript function to parse XML documents (process them into a form understandable by the application).

For information, see “Creating the DOMDocument object” on page 18

• A set of DynaScript objects to access individual pieces of a parsed document.

For information, see “Introduction to the Document Object Model” on page 177.

• A set of DynaScript objects to create and modify XML documents.

For information, see “Using the DOM interface to create and edit XMLdocuments” on page 200.

• A utility function (xmlEscape) to aid in escaping data for XML.

For information, see “Escaping text with xmlEscape” on page 195.

166

CHAPTER 8 Working with XML Documents

An introduction to XMLXML is a framework for creating markup languages. It has been designed specifically for use on the Web.

Example Here is an example XML document:

<?xml version="1.0"?><Example> <Computer> <Name>Toshiba</Name> <Processor>Pentium</Processor> <Memory units="MB">96</Memory> </Computer></Example>

Any complete XML document starts with an XML declaration (the first line in the example above).

Other attributes can be added to this declaration, as described in any XML book.

Valid and well-formed XML documentsAn XML document must be valid, well-formed, or both. The following sections discuss each type of document.

Valid documents To define a set of tags for use in a particular application, XML uses a separate document named a document type definition (DTD). A DTD states what tags are allowed in an XML document and defines rules for how those tags can be used in relation to each other. It defines the elements that are allowed in the language, the attributes each element can have, and the type of information each element can hold. Documents can be verified against a DTD to ensure that they follow all the rules of the language. A document that satisfies a DTD is said to be valid.

The DTD for documents like the example given above might look something like this:

<!DOCTYPE Example [ <!ELEMENT Computer (Name, Processor, Memory)> <!ELEMENT Name (#PCDATA)> <!ELEMENT Processor (#PCDATA)> <!ELEMENT Memory (#PCDATA)> <!ATTLIST Memory units #REQUIRED>]>

167

An introduction to XML

If a document uses a DTD, the DTD must immediately follow the declaration.

Well-formed documents

The second way to specify XML syntax is to assume that a document is using its language properly. XML provides a set of generic syntax rules that must be satisfied, and as long as a document satisfies these rules, it is said to be well-formed. All valid documents must be well-formed.

Processing well-formed documents is faster than processing valid documents because the parser does not have to verify against the DTD. When valid documents are transmitted, the DTD must also be transmitted if the receiver does not already possess it. On the other hand, well-formed documents can be sent without other information.

XML documents should conform to a DTD if they are going to be used by more than one application. If they are not valid, there is no way to guarantee that various applications will be able to understand each other.

In this chapter, most examples use well-formed documents with no DTD, for simplicity.

XML syntaxThere are a few more restrictions on XML than HTML, which make parsing simpler. Unlike in HTML, you cannot omit tags. This guarantees that parsers know where elements end. The following example is acceptable HTML, but not XML:

<table><tr><td>Dog</td><td>Cat<td>Mouse</table>

To make this well-formed XML, you need to add all the missing end tags:

<table><tr><td>Dog</td><td>Cat</td><td>Mouse</td></tr></table>

168


Empty elements cannot be represented in XML the same way they are in HTML. An empty element is one that is not used to markup data, so in HTML there will not be an end tag. There are two ways to handle empty elements. The first is to place a dummy tag immediately after the start tag. For example:

<img href="picture.jpg"></img>

The second method is to use a slash character at the end of the initial tag:

<img href="picture.jpg"/>

This tells a parser that the element consists only of one tag.

XML is case sensitive, which allows XML to be used with non-Latin alphabets. You must ensure that letter case matches in start and end tags: <MyTag> and </Mytag> belong to two different elements.

White space within tags in XML is unchanged by parsers.

All elements must be nested

All XML elements must be properly nested. All child elements must be closed before their parent elements close.

169

Creating XML documents

m

Creating XML documentsIn PowerDynamo, an XML document is any string that contains a valid XML document. Once you have created an XML document, you can send it to a browser, or parse it and process it using the DynaScript DOM objects.

You can create XML documents in PowerDynamo from a variety of sources:

•DynaScript query object From a query object, using the ResultsToXMLString method.

•Dynamo SQL and FORMATTING tags From a query, using the FORMATTING tag with the FORMAT_AS attribute set to XML.

•DynaScript objects From any DynaScript object, using the toXMLString function.

•Sybase Central From the Add Template wizard, which provides XML output options.

•DynaScript By writing scripts to output XML documents in a custom fashion, adding tags as required.

•Import By importing an XML file into your Web site.

The built-in methods for producing XML documents are discussed in this section.

Creating XML documents from the query objectIf you use the DynaScript query object to execute a SQL query against your database, you can use the ResultsToXMLString method to wrap the results in XML tags.

For an alternative approach using tags, see “Creating XML documents froqueries using the FORMATTING tag” on page 172.

Example The following script illustrates how to use ResultsToXMLString:

myConn = site.GetConnection( "myConn" ); //1myQuery = myConn.CreateQuery( "SELECT id, name, unit_price FROM product" ); //2xmlString = myQuery.ResultsToXMLString( "Products", "Product", "ID Name Price" ); //3document.writeln( xmlString ); //4

170


•Line 1 Create a connection object from the current connection.

•Line 2 Create a query object from the connection object and executes the query. The query retrieves some columns from the product table in the demo database.

•Line 3 Format the query results into an XML string.

ResultsToXMLString takes between zero and four parameters. For details, see “ResultsToXMLString method” in PowerDynamo Reference.

•Line 4 Write out the XML string. The string contains tags around the individual results rather than providing a DTD. The output string has no white space. Here it is, with white space added for readability:

<Products> <Product> <ID>600</ID> <Name>Sweatshirt</Name> <Price>24.00</Price> </Product> <Product> <ID>601</ID> <Name>Sweatshirt</Name> <Price>24.00</Price> </Product></Products>

The entire result set constitutes a Products element. Each row is a Product element, and contains ID, Name, and Price elements.

Notes There are several points of interest in the above example.

•Error checking The example script does not include any error checking. In a real application, you should verify that each individual step succeeds. Check the method return values or use the GetErrorCode method of the object carrying out the step. Many methods return null when they fail.

•White space White space outside tags, including new line and carriage return characters, is significant in XML. It is added in the sample above for readability, but in fact changes the document. You must be careful about extraneous white space in your XML documents.

•XML header For the example script to be a complete XML document, you must add a proper XML header, such as the following:

<?xml version=’1.0’ encoding=’ISO-8859-1’?>

171


y

t by

as

e

•Default tags The default result set tag is SYBRESULTSET. The default row tag is SYBROW. If you do not supply any tags in the arguments to ResultsToXMLString, the name of the column is used as the tag for each tag. If you supply a single tag, it is used for all columns. If you supply more than one tag, but not as many as there are columns, then the remaining columns tags default to the column labels.

•Validation The XML output string is not validated. To validate the XML, you must do so independently of Dynamo.

•Applying attributes The ResultsToXMLString method provides a convenient way of supplying simple XML. To specify attributes for XML tags in your output, see “Creating custom XML documents from querresult sets” on page 172.

Creating custom XML documents from query result setsYou can customize the XML you obtain from the result set of a query objecbuilding an XML string explicitly, instead of using ResultsToXMLString.

For example:

xmlString = "<Products>";while ( myQuery.MoveNext() ){ xmlString += "<Product>"; xmlString += "<ID>" + myQuery.GetValue(1) + "</ID>" ; xmlString += "<Name>" + myQuery.GetValue(2) + "</Name>"; xmlString += ’<Price units="DOLLARS">’ + myQuery.GetValue(3) + "</Price>"; xmlString += "</Product>";}xmlString += "</Products>";

Creating XML documents from queries using the FORMATTING tagThe FORMATTING tag provides a way of writing out the results of queriesXML.

The following template illustrates how to use the FORMATTING tag with XML output. You must enter the FORMATTING tag, like any tag, all on online in a Dynamo template:



The output of this template is the following. Line wrapping occurs in the printed document but is not present in the actual output string:

<Products> <Product> <Description>Hooded Sweatshirt</Description> <Color>Green</Color> </Product> <Product> <Description>Zipped Sweatshirt</Description> <Color>Blue</Color> </Product></Products>

Notes •Attributes The attributes of the FORMATTING tag are as follows:

•FORMAT_AS attribute Can have values of HTML or XML. HTML is the default.

•RESULTSET_TAG attribute Provides the element name for the tag that surrounds the entire result set. In the example, Products.

•ROW_TAG attribute Provides the element name for the tag that surrounds each row. In the example, Product.

•COLUMN_TAG attribute If no COLUMN_TAG attribute is provided, the column’s label is used. Multiple column tags can be specified in a space-delimited string. If a single column tag is provided, this tag is used to mark all columns. If multiple column tags are provided, but not as many as there are columns, then the remaining columns tags will default to the column labels.

•Only applies to default formatting The attributes apply only if there is nothing between the FORMATTING tag and its end tag. If you add  tags, then the attributes do not apply.

•Validation The XML output string is not validated. To validate the XML, you must do so independently of Dynamo.

173


ult

is

r if a

e of

•Applying attributes The FORMATTING tag provides a convenient way of supplying simple XML. To specify attributes for any of the XML tags in your output, see “Creating custom XML documents from query ressets” on page 172.

Creating XML from DynaScript objectsYou can create XML from any DynaScript object using the toXMLString function.

This function accepts 1, 2, or 3 arguments:

• Argument 1 is the DynaScript object for which an XML representationrequested.

• Argument 2 (optional) specifies whether to build a CDATA section to escape special XML characters. The default value is false.

• Argument 3 (optional) specifies a set of tags to use when unnamed members of the object are encountered. The toXMLString function returns null if a non-object argument is passed as the first argument, othe object passed has no enumerable members. Otherwise it returnsstring.

Examples The following set of scripts illustrate how to use toXMLString:

• Create a simple object and write it out as an XML string. The propertynames are used as tags.



The output for the script is as follows:

<a>2</a><b>3</b>

• Create a nested object and write it out as an XML string. The structurthe document reflects the structure of the object.




<a>2</a><b><b1>3</b1><b2>4</b2></b>

• Use the ampersand character to escape text. The toXMLString functichanges the < and > characters to the XML entities < and >.




<a>2</a><b>&<encoding needed>&</b>

• Use CDATA escaping of text that contains special characters, by addisecond argument to toXMLString.




<a>2</a><b><![CDATA[&<encoding needed>&]]></b>

• Write an XML string from an object with indexed members, with no taspecified.




<0>2</0><1>3</1>

• Write an XML string from an object with indexed members. This time,supply tags for the output.




<ROW><COL>shirt</COL><COL>blue</COL></ROW><ROW><COL>hat</COL><COL>green</COL></ROW>

176


Introduction to the Document Object ModelDynamo provides a set of DynaScript objects for navigating and manipulating XML documents. These objects implement the Document Object Model (DOM) core Level 1 features. The DOM is a W3C recommendation (REC-DOM-Level-1-19981001).

What you can do with DOMWith the DOM interface, you can access and modify the content and structure of XML documents from DynaScript. Tasks that you can carry out using DOM including:

•Parsing XML documents The toDOMDocument function parses a string that contains XML data. It builds an internal representation of the XML document so that it can be manipulated and acted on.

•Converting XML to other formats For example, you can convert XML to HTML for sending to a browser.

•Selectively displaying pieces of a document The DOM interface allows you to navigate through a document and locate specific pieces. If an XML document contains a SUMMARY element, you can select just that piece and send it to the application.

•Change XML documents In addition to processing an existing document, the DOM interface allows you to develop applications that create and edit XML documents.

The DOM view of documentsThe DOM interface presents XML documents to your application as a tree. Consider the following simple XML document, shown with indented lines for readability:

<?xml version=’1.0’ ?><Customer> <FName>Jessie</FName> <LName>Gagliardo</LName> <Address> <Street>2800 Park Avenue</Street> <City>Hull</City> <Region Type=Province>PQ</Region>

177

Introduction to the Document Object Model

</Address></Customer>

The tree representation of this document is shown in Figure 8-1.

Figure 8-1: Tree representation of XML document

The node interface to DOM

In a DOM representation of this document, each element is a node. You can navigate the document using the relationships among these nodes:

•Each node has at most one parent The parent of City is Address. The parent of LName is Customer, and the parent of Customer is a special node named the document node. The document node does not have a parent node. No node can have more than one parent, and only certain classes of node (such as the document node) can have zero parents.

In the DOM representation, each node has a parentNode property that takes you to the parent of the current node.

•Nodes have zero, one, or more child nodes For example, the children of Customer are FName, LName, and Address.

In the DOM representation, each node has a childNodes property that provides you with a list of all children of the current node. It also provides a firstChild and lastChild node to take you to those specific child nodes. These nodes are ordered, and each has a previousSibling property and a nextSibling property that enable you to loop through the current node.

178


on

is

s. node:

•Not all nodes are elements Some nodes represent text, such as the text nodes shaded gray in the above diagram. Other nodes represent attributes, entity references, comments, and so on.

For example, the Region element has a single attribute. This attribute is a node, with a name of Type and a value of Province. Attribute nodes have some differences from element and text nodes.

For more information on attribute nodes, see “Working with attributes” page 191.

•Some nodes contain text and other nodes Character data, or text, in a node, is also considered to be a separate node. Thus the child of the FName node is a node that has a nodeType of Text and a nodeValue of Gagliardo.

In the following example:

<Sentence>The cat was <Em>very</Em> black</Sentence>

the Sentence node contains three children. The first is a text node (with a value of “The cat was” ), the second is an Em element, and the third another text node (with a value of “black”).

Using nodes to work with XML documentsThe DOMNode object is the primary object for the DOM model of documentIt has a set of properties that you can use to obtain information about the

•Characteristics The nodeName, nodeType, and nodeValue properties give information about the node. For example, nodeType tells you whether the node represents an element, attribute, text, or some other node type.

•Position You can use the parentNode, previousSibling, nextSibling, firstChild, and lastChild properties to take you to related nodes. You can use the hasChildNodes() method to determine if a node has children, and if it does, the childNodes property returns a whole list of children nodes.

•Modification You can use insertBefore, replaceChild, removeChild, appendChild, and cloneNode to add or remove related nodes.

•Element attributes If the node represents an element, the attributes property returns a list of the XML attributes of the element.

179

Introduction to the Document Object Model

Node types The properties of nodes depend on what piece of an XML document they represent. The node types and their corresponding values are:

The object interface to XML documentsWhile you can access all parts of a document as nodes, the DOM interface also provides explicit objects for elements (DOMElement), attributes (DomAttr), and other node types. These objects inherit properties from the DOMNode object and provide some additional functionality of their own. The properties and methods of each of these objects reflect the features of the XML object they represent.

The following sections describe both the DOMNode approach and the object interface. Although you can mix these approaches, most developers will want to use one method per task, for consistency.

nodeType value XML Comments

1 Element Many nodes are XML elements.

2 Attribute Attributes of an XML element.

3 Text Text can occur in elements, or in the values of attributes.

4 CDATASection Typically used for including blocks of text that contain characters that would otherwise be regarded as markup (such as <, >).

5 EntityReference A reference to an XML entity.

6 Entity An XML entity.

7 ProcessingInstruction An XML processing instruction.

8 Comment An XML comment: all the characters between .

9 Document The document with which the node is associated.

10 DocumentType The document type definition (DTD) of the document.

11 DocumentFragment A piece of a document, primarily used for editing purposes.

12 Notation An XML notation.

180


Performance tipIt is generally more efficient to use the explicit objects instead of the generic node interface to XML documents.

Error checking XML-handling scriptsTo assist in developing reliable scripts Dynamo provides:

•prettyPrint method The DOMNode object provides a prettyPrint() method that returns the XML tree starting at the current node. This method is an extension to the DOM recommendation, and takes no arguments. You can use it in a statement such as:

document.writeln( myNode.prettyPrint() );

•returned object is null Many methods return an object. For example, the DOMNode.appendChild() returns the child node. On failure, the return value is null . You can compare the return value to null to check for the success of a method.

•Check that the document parses correctly If the XML document is not well-formed, the call to toDOMDocument returns null . You can use site.GetErrorInfo() to provide information on where the document is incorrect. The following code fragment illustrates how to do this.

domDoc = toDOMDocument( xmlString );if( domDoc == null ) { document.writeln( site.GetErrorInfo() );}else {...}

181

Document Object Model examples

Document Object Model examplesThis section contains two examples illustrating XML applications of Dynamo. Subsequent sections describe the techniques employed in these examples.

Converting XML to HTML for sending to a browserThis section provides an overview of how applications can use the DOM interface. It uses the DOMNode object to process an XML document.

The document The document below is shown with white space for readability. To reproduce this example, delete the white space between the tags.

<?xml version=’1.0’ ?><Customer> <FName>Jessie</FName> <LName>Gagliardo</LName> <Address> <Street>2800 Park Avenue</Street> <City>Hull</City> <Region Type="Province">PQ</Region> </Address></Customer>

The script This script converts the customer information to HTML and sends it to a Web browser. The line numbers are added in comments, and are referenced in the description following the script:



The output is as follows:

<P>Name: Jessie Gagliardo<P>Address: 2800 Park AvenueHullPQ

How the script works The script works as follows:

•Line 2 An XML document is received by Dynamo, as a document value named xmlData. It is parsed to provide a DOM document object.

You can create document objects from several sources, including files on disk, documents stored in a Dynamo Web site, query results, or arguments passed in from a URL.

For more information, see “Creating the DOMDocument object” on pag187.

•Line 6 The node corresponding to the top element of the DOM document is accessed. Each XML document has a single top-level element that includes all other content: in this case, it is the Customer element.

•Lines 8 and 9 The firstChild of the Customer element is FName. The firstChild of FName is a text node. The nodeValue of the text node is the string Jessie.

For information on navigating the document tree, see “Using nodes towork with XML documents” on page 179.

•Lines 10 and 11 The nextSibling of FName is LName. Line 12 writes out the string in the text node of LName (Gagliardo).

183


•Lines 14 to 16 These lines loop over the members of the childNodes list of the Address element, writing out the text values of each.

It is actually more efficient to use firstChild followed by nextSibling methods to loop over the children of a node than to loop over the members of the childNodes list.

Inserting data from XML into a databaseXML applications can insert data from an XML document into a database. For example, you may design a Web page to contain a form that, when a button is clicked, constructs an XML document (perhaps using JavaScript) and posts it to PowerDynamo.

This section describes how to construct an INSERT statement from an XML document.

The following XML document (which has had white space added for readability) contains information for a new product, to be added to the database:

<?xml version=’1.0’?><Products> <Product> <Name>Cricket Cap</Name> <Description>Cotton Cap</Description> <Size>One size fits all</Size> <Color>Blue</Color> <Quantity>30</Quantity> <Unit_Price>10</Unit_Price> </Product></Products>

The following DynaScript code takes a DOMDocument that has been constructed from this, and creates an INSERT statement from it:

function SQLVar( prod, elemname ){ //1 return prod.getElementsByTagName( elemname ).item(0).firstChild.nodeValue;//2} //3function InsertProduct(){ //4 var i, prod, name, desc, size, color; //5

184


var quantity, unit_price, id, //6 var docElem, domDoc, xmlDoc; //7 domDoc = toDOMDocument(document.value.xmlData); //8 docElem = domDoc.documentElement ; //9 sql = connection.CreateQuery(); //10 id=1000; // Not a recommended way of generating ID numbers //11 // loop over individual product elements -- only one in this example //12 for( i = 0 ; i < docElem.childNodes.length ; i ++ ){ //13 id += 1; //14 prod = docElem.childNodes.item(i); //15 name = SQLVar( prod , "Name" ); //16 desc = SQLVar( prod , "Description" ); //17 size = SQLVar( prod , "Size" ); //18 color = SQLVar( prod , "Color" ); //19 quantity = SQLVar( prod , "Quantity" ); //20 unit_price = SQLVar( prod , "Unit_Price" ); //21 sql.SetSQL( "INSERT INTO DBA.Product " //22 + "VALUES ( " + id + ", ’" + name + "’, ’" + desc + "’, ’" + size + "’, ’" + color + "’, " + quantity + ", " + unit_price + " )" ); if( !sql.Execute() ){ //23 document.writeln( sql.GetErrorInfo() ); //24 } //25 } //26

185


the

} //27

Notes •Lines 1 to 3 The SQLVar function gets the value of the named element.

For information on the getElementsByTagName method, see “Using DOMElement object to work with elements” on page 190.

•Lines 8 to 9 These lines parse the document and locate the document element.

For information on the toDOMDocument function, see “Creating the DOMDocument object” on page 187.

•Lines 15 to 21 These lines call SQLVar to construct variables containing the quantities that need to be inserted in the database.

•Line 22 The INSERT statement is constructed and executed.

•Lines 23 to 25 These lines check that the INSERT was carried out successfully.

186


70.

it ce

not

he

sible.

Creating the DOMDocument objectWhen you process an XML document, the first step is to create a DOMDocument object. You do this using the toDOMDocument function, which takes a string as an argument and returns a DOMDocument object.

The following lines create a DOMDocument object from an XML document named mydoc.xml stored in a Web site:

xmlDoc = site.GetDocument( "mydoc.xml" );domDoc = toDOMDocument( xmlDoc.source );

The first line creates a document object, the second line creates a DOMDocument object, taking a string as an argument.

You can create DOMDocuments from several other sources. For information on generating XML documents, see “Creating XML documents” on page 1

You can also create an empty DOMDocument object and add elements tousing the DOM interface. For more information, see “Using the DOM interfato create and edit XML documents” on page 200.

Parser does not validate

The toDOMDocument function parses the XML document and builds a representation of the entire document tree in memory. The XML parser isa validating parser: that is, it does not confirm that the structure of the document conforms to any DTD referenced in the document.

On the other hand, if the document is not well formed, then it cannot be built into a proper tree structure, and the function call fails, returning null. You can call site.GetErrorInfo to display specific error information.

In this example, the error is handled by writing a message and stopping tapplication:

domDoc = toDOMDocument( xmlDoc.source );if( domDoc == null ){ document.writeln( site.GetErrorInfo() ); exit;}

Performance tip Parsing large documents with toDOMDocument can be an expensive task. Consider designing your site so that it is carried out as infrequently as pos

You can avoid unnecessary parsing of the document by attaching the DOMDocument object to the session object, using a script such as:

function getSessionDocument(){ if ( !exists(session.domDoc) ) { xmlDoc = site.GetDocument( "xmldoc.xml" );

187

Creating the DOMDocument object

session.domDoc = toDOMDocument( xmlDoc.source ); } return session.domDoc}

If you call this function whenever you need the DOM representation of the XML document, it is regenerated when necessary, but not if it already exists in the session object.

188


Working with elementsMany applications that process XML documents need to locate or manipulate various elements of the document by using the tree structure.

The DOM interface provides two ways of working with elements:

•DOMNode object You can use the DOMNode object and test to see if the node you are addressing is an element node.

•DOMElement object You can explicitly use the DOMElement object, which provides some additional properties and methods that reflect the features of XML elements.

Using the DOMNode object to work with elementsThe element nodes of a document have all the properties (parents, siblings, children) that you need to navigate a document. These nodes provide one way of accessing the properties of elements.

Example Here is a script that writes out the names of all elements in a document:

function displayElementName( domElement ){ //1 var i; //2 var domChild; //3 if( domElement.nodeType == 1){ //4 document.writeln( domElement.nodeName ); //5 } //6 for( i=0; i < domElement.childNodes.length ; i++ ){//7 domChild = domElement.childNodes.item(i); //8 displayElementName( domChild ); //9 } //10} //11displayElementName( domDoc.documentElement ); //12

Notes •Lines 2 and 3 When calling a function recursively, as in this example, you must declare variables inside the function to ensure a new copy is made each time.

•Lines 4 to 6 Only write out the names of nodes that are elements (nodeType = 1).

•Lines 7 to 10 Loop over all the child nodes of the current node, calling displayElementName on each.

•Line 12 Invoke displayElementName with the document element of a DOM document. The function must be defined before it is used.

189

Working with elements

n

.

ment

Obj

ing

Characteristics of nodes that represent elements

Nodes that correspond to elements have the following characteristics:

•nodeType The nodeType of a node that is an element is 1.

•nodeName This is the tag name of the element.

•nodeValue The nodeValue of a node that is an element is null .

•attributes The attributes of an element. These are made available as a DOMNamedNodeMap object.

For more information about attributes, see “Working with attributes” opage 191.

Using the DOMElement object to work with elementsThe DOMElement object corresponds to an element of an XML document. DOMElement inherits all the properties and methods from the DOMNode object. In addition, it supports some properties and methods specific to elements

Getting elements by tag name

You can retrieve and process all elements with a given name from a docuas follows:

elemlist = domObj.getElementsByTagName(tag_name);for(i=0; i < elemlist.length ; i++){ document.writeln( elemlist.item(i).tagName);}

where domObj is a DOMDocument object or a DOMElement object, and tag_name is the case-sensitive name of the tag you want to retrieve. If domis a DOMElement object, only those elements contained in domObj are retrieved (descendants of domObj).

This is usually more effective than traversing the entire document tree lookfor a particular element.

For a list of DOMElement properties and methods, see “The DOMElement object” in PowerDynamo Reference.

190


pt to

er

Working with attributesYou can access the attributes of an element in the following ways:

•DOMNode interface From the element node’s attributes property.

•Object interface From the getAttribute or getAttributeNode methods of the DOMElement object.

Using the DOMNode object to work with attributesThe following example writes out the names and values of the attributes of an element.

function displayAttributes( node ){ //1 var i; //2 var attnode; //3 if( node.nodeType == 1){ //4 for( j=0; j < node.attributes.length; j++){ //5 attnode = node.attributes.item(j) //6 document.writeln( attnode.nodeName ); //7 document.writeln( attnode.firstChild.nodeValue ); } }}

If the supplied element has a start tag of this form:

<Region Type="Province">

Then the output is:

TypeProvince

In this example, the attribute node has a child that is a text object. The nodeValue of this text object can also be used to retrieve the attribute value.

Attribute nodes • Attributes do not occupy a place in the document tree. A DOMNode object that represents an attribute has no parents and no siblings. Any attemaccess these properties returns null.

• You can access an attribute node of an XML element using the attributes property of the element node. This property returns a DOMNamedNodeMap object. You can access the individual attributes eithby index (as in the sample code above) or by name. The following statement sets attnode to the Type attribute of the element:

191

Working with attributes

to

attnode = node.attributes.getNamedItem( "Type" );

Using the DOMAttribute object to work with attributesThe DOMAttribute object corresponds to an attribute of an XML element. The DOMAttribute object inherits all the properties and methods from the DOMNode object. In addition, it supports some properties and methods specific to attributes.

You can access the attributes of an element in the following ways:

•Get the value of an attribute with a given name The following sample code takes a list of elements as input (elemList), and lists the value of all the Type attributes:

for( i = 0 ; i < elemList.length ; i ++ ){ elem = elemList.item(i); document.writeln( elem.getAttribute( "Type" ) );}

•Get the DOMAttribute object for an attribute The following sample code lists the value of each Type attribute for a list of elements:

for( i = 0 ; i < elemList.length ; i ++ ){ elem = elemList.item(i); att = elem.getAttributeNode( "Type" ); document.writeln( att.name + " = " + att.value );}

The DOMAttribute object also has methods and properties that you can use to alter XML documents. For more information, see “Using the DOM interfacecreate and edit XML documents” on page 200.

192


Working with textThis section includes a description of how to access and work with the text that is contained in XML documents.

Text occurs in the following places:

•Inside elements This is where most text in XML documents resides:

<Street>2800 Park Avenue</Street>

•As attribute values The following is an example:

<Region Type="Province">

Simple cases When an element or attribute has no child nodes apart from a single text node, you can access the text content of an element or attribute using the nodeValue of the element’s child.

If an element contains no other elements or other non-text pieces, the only child of the element is a text node. The nodeValue of this text node is a string. The following example writes out the text of an element:

document.writeln( elemnode.firstChild.nodeValue )

For an attribute node, the following example writes out the value of the node:

document.writeln( attnode.nodeValue )

More complicated cases

Some elements contain several text nodes among their children. Consider the following cases:

•Text mixed with entities The following Names element has three child nodes:

<Names>Sammy & Rosie</Names>

The first child is a text node with value "Sammy ". The second child is an entity node representing the ampersand character. The third child is a text node with value " Rosie ".

•Text mixed with elements The following Warning element has three child nodes:

<Warning>Do <emphasis>not</emphasis> walk on the grass</Warning>

The first child is a text node with value "Do ". The second is an element node. The third child is a text node with value " walk on the grass ".

For more information, see “Working with entities” on page 196.

193

Working with text

as

n as

Obtaining all the text inside an elementIf you want to obtain all the text inside an element, including its children, you can use the getElementsByTagName method of the root element, with the special value "*", which means all tags. The following function demonstrates this technique.

function listTextOfAllElements(rootelement){ var elemlist, elem, child, i, j ; elemlist = rootelement.getElementsByTagName( "*" ); for( i = 0 ; i < elemlist.length ; i ++ ){ elem = elemlist.item(i); for( j = 0 ; j < elem.childNodes.length ; j ++ ){ child = elem.childNodes.item(j); if( child.nodeType == 3) { // 3 is a text node document.writeln( child.nodeValue ); } } }}

Working with CDATA sectionsCDATA sections provide a way of including blocks of text in XML documents even if the text contains characters that would otherwise be recognized as markup. CDATA sections start with <![CDATA. All characters inside a CDATA section, including angle brackets and ampersands, are seen as text data until the marker for the end of the section, which is ]]>, is reached.

Here are some examples of CDATA sections:

• Text containing an ampersand can be included:

<![CDATA [Jane & John Doe]]>

In the above example, the ampersand is treated as a text rather thanstarting an entity reference.

• Text containing tags can be included:

<![CDATA [<title>Working with CDATA sections</title>]]>

In the above example, <title> and </title> are treated as text rather thatags.

194


false. '

The text content of a CDATA section is the nodeValue of the object. For example, the following fragment writes out the content of a node if it is a CDATA section node:

if (child.nodeType == 4 ){ //CData Section document.writeln( child.nodeValue ) ;}

Escaping text with xmlEscapeDynamo includes the xmlEscape function to assist with preparing text for use in XML documents. The prototype is as follows:

string xmlEscape( input_string [, use_CDATA ] )

This function encodes ‘&’, ‘<‘, and ‘>’ characters in a string and returns the encoded string. The input_string parameter is the string to be encoded. Theoptional use_CDATA parameter dictates whether a CDATA section will be used to encode the characters. If not provided, this parameter defaults to If use_CDATA is false, then characters are encoded using the 'ampersandmethod of encoding.

Examples The following script:

document.writeln( xmlEscape( "<MyTag>Hello!</MyTag>" ));

produces the following output

<MyTag>Hello!</MyTag>

The following script:

document.writeln( xmlEscape( "Calvin & Hobbs", true ) );

produces the following output:

<![CDATA[Calvin & Hobbs]]>

195

Working with entities

Working with entitiesIn an XML document, an entity is a holder for some information. To use entities, you must first declare them, and then reference them. You declare entities in the DTD. The entities section of the XML document may be held separately or placed at the beginning of the document. Here is a simple DTD that specifies the two entities PQ and Logo.

<?xml version=’1.0’ encoding=’ISO-8859-1’?><!DOCTYPE Customers [ <!ENTITY PQ "Province of Quebec"> <!ENTITY Logo SYSTEM "nautilus.gif" NDATA GIF>]><Customers><Customer><FName>Jess...

There are two kinds of entity declared here: PQ is a simple text replacement, and Logo is a reference to a graphic, held in a GIF file.

Entity types The following kinds of entity can occur in XML documents:

•Internal entities These entities hold replacement text that is defined in an entity declaration.

The following is an internal entity declaration:

<!ENTITY PQ "Province of Quebec">

You can reference this entity as follows in the content of an element:

<Region type="Province">&PQ;</Region>

XML supports a small set of predefined internal entities, which do not need to be defined. This set includes:

•amp The ampersand character (&)

•lt The left angle bracket character, or less-than sign (<)

•gt The right angle bracket character, or greater-than sign (>)

•apos The apostrophe character (’)

•quot The quotation mark character (")

•External entities that can be parsed These allow you to incorporate XML content from other files. You declare them as follows:

<!ENTITY chap1 SYSTEM "chapter1.xml"><!ENTITY chap2 SYSTEM "chapter2.xml">

The string chapter1.xml is called the system identifier of the entity. You can reference this entity from within the content of an element as follows:

196


<BOOK>&chap1;&chap2;</BOOK>

•External entities that cannot be parsed These allow you to incorporate material that is not XML content, such as images, into an XML document.

You declare them as follows:

<!ENTITY Logo SYSTEM "emblem.gif" NDATA gif>

NDATA states that the entity is not XML data and should not be parsed.

To include an external entity of this kind in a document, you must reference it in an attribute of an element:

<GRAPHIC entity="Logo">

Working with internal entitiesYou can include references to internal entities in the text. For example, the following element includes a predefined internal entity:

<Names>Sammy & Rosie</Names>

The Names element has three children, the first being a text node, the second being an entity reference node, and the third being another text node. The firstChild of the entity reference node is a text node, and the nodeValue of this text object is the replacement text.

The entity definitions of predefined entities are also available from the entities property of the DOMDocument object’s doctype property.

Working with external entitiesThe following is a complete XML document that defines and references an external entity:

<?xml version=’1.0’ encoding=’ISO-8859-1’?><!DOCTYPE DOC [ <!NOTATION gif SYSTEM "GIF"> <!ENTITY Logo SYSTEM "nautilus.gif" NDATA gif>]><DOC><GRAPHIC ENTITY="Logo"/></DOC>

197

Working with entities

tion ing

uld the

o

The following DynaScript function takes the DOMDocument object as its argument, and displays the nautilus.gif file that holds the Logo image:

function displayGraphic( domDoc){ dtd = domDoc.doctype; entlist = dtd.entities; elemlist = domDoc.getElementsByTagName( "GRAPHIC" ); elem = elemlist.item(0); gif = elem.getAttribute( "ENTITY" ); ent = entlist.item( gif ); sysid = ent.systemId; document.writeln( ’<img src="’ + sysid + ’>’);}

Notes • To access the entity declarations, you use the DOMDocumentType object, which is accessible as the doctype property of the DOMDocument object. The entities property of DOMDocumentType returns a list of entities.

• The application must know which attributes are entities, as the DOM interface does not makes this information available. Here, the ENTITYattribute of the GRAPHIC element is an entity name.

• The systemID property of the DOMEntity object returns the path to thefile.

• If you use an entity to refer to another document, you need to pay attento the path to that document. In particular, the path may differ dependon whether the reference is resolved on the client or by Dynamo.

To resolve entities on the server you must use the full path.

Although Dynamo recognizes the home directory (~) in a path, you shonot use ~ in an img tag to a browser, as the browser does not recognizehome directory.

Conversely, although browsers recognize standard URLs of the form http://address, you should not use these if you expect Dynamo itself tobtain information from the address, as Dynamo is not a Web client.

198


ct”

in

Working with other XML objectsIn addition to elements, attributes, entities, and text, there are several other items that can occur in an XML document. These include the following:

•Processing instructions These contain instructions for applications. The first line of any XML document is a processing instruction with a name of xml . For example:

<?xml version=’1.0’?>

For information on handling processing instructions, see “The DOMProcessingInstruction object” in PowerDynamo Reference.

•Comments A comment embedded in an XML document contains text that is not part of the document’s character data. For example:



For information on handling comments, see “The DOMComment objein PowerDynamo Reference.

•Notations A notation is a declaration for the supported types of external entities that are not parsed. For example:

<!NOTATION IMAGE SYSTEM "GIF">

For information on handling notations, see “The DOMNotation object” PowerDynamo Reference.

•Document type information The DTD is held in the DOMDocumentType object. This object has properties that hold the name of the DTD, as well as listings of the entities and notations declared within the DTD.

The Document Object Model, Level 1, does not specify access to any other information in the DTD.

For information on handling notations, see “The DOMDocumentTypeobject” in PowerDynamo Reference.

199

Using the DOM interface to create and edit XML documents

t you


This section describes how to use the DOM interface to create and edit XML documents.

You can output XML data from a database using standard string functions. The DOM interface lets you construct or modify the DOM representation of an XML document. To do anything with this document, you must process it using the DOM interfaces described in the other sections of this chapter.

Creating a DOM document objectThe DOMDocument object has a constructor that allows you to create an empty DOM document.

❖ To create a DOMDocument object:

• Use the following statement:

domDoc = new DOMDocument();

Standards The DOM Level 1 specification does not provide a standard method for creating a DOM document object. The DOMDocument() constructor is an extension to the standard.

Adding objects to DOM documentsTo add elements to a DOM document, create the elements or other objecwant to add, and then insert them in the proper place in the tree.

Creating objects You can create an element or other object using methods of the DOMDocument object. These methods are:

• createAttribute

• createCDATASection

• createComment

• createDocumentFragment

• createElement

• createEntityReference

200


ment

ode

d”

ent.

• createProcessingInstruction

• createTextNode

The following fragment creates an FName element (elem), and a text node (tnode) with content “Ann T. Dote” in a DOMDocument object named domDoc:

elem = domDoc.createElement( "FName" );tnode = domDoc.createTextNode( "Ann T. Dote" );

These nodes currently have no place in the document, and the FName elehas no content.

Adding objects to documents

You can add objects to a node using one of these methods of the DOMNobject:

• The appendChild method

• The insertBefore method

• The replaceChild method

This fragment expands on the previous one to add the elements into a document. The FName element is a child of a node named cust, and the text node is a child of the FName element:

elem = domDoc.createElement( "FName" );text = domDoc.createTextNode("Ann T. Dote" );el = cust.appendChild( elem );el.appendChild( text );

For more information, see “insertBefore method” and “replaceChild methoin PowerDynamo Reference.

Removing and replacing objects in DOM documentsThe DOM interface provides a set of methods for deleting and replacing objects in the document tree. There is not a method on a DOMNode object to delete the object itself. Instead, you delete a node by a method on its parThe removeChild method deletes a child node, and the replaceChild method replaces a child node with a new node.

For more information, see “removeChild method” in PowerDynamo Reference, and “replaceChild method” in PowerDynamo Reference.

201


em

Removing and replacing attributes

For attributes and other unordered objects (not elements) you can also use methods defined on the collection of attributes. This collection, which is unordered, is represented by a DOMNamedNodeList object, and you can use the removeNamedItem method and the setNamedItem method to carry out the operations.

For more information, see “removeNamedItem method” and “setNamedItmethod” in PowerDynamo Reference.

202

C H A P T E R 9 PowerDynamo Mail Support

About this chapter This chapter looks at how to send, receive, monitor and edit mail from a PowerDynamo Web site.

For reference information on the PowerDynamo mail objects see “DynaScript Predefined Objects” in PowerDynamo Reference.

Contents Topic Page

About PowerDynamo’s mail support 204

Sending mail 206

Receiving mail 208

Deleting mail 210

Forwarding and replying to mail 211

A simple mail application 213

203

About PowerDynamo’s mail support

as ight eate

to

et

ust mail.

d d

cript.

About PowerDynamo’s mail supportYou can use DynaScript to send, receive, and monitor e-mail from PowerDynamo. PowerDynamo includes the following predefined objects, which allow users to send mail through a SMTP mail server or receive mail through a POP3 mail server:

• the outgoing mail object

• the incoming mail object

• the recipient object

• the attachment object

There is also one Dynamo tag called MAILPIECE that can be used for sendingmail from a Dynamo document.

The PowerDynamo mail objects are extremely flexible and can be made simple or as complex as required by the application. For example, you mwant to simply send and receive basic mail pieces or, you might want to cran application that filters incoming tech support questions and routes themthe appropriate tech support staff.

Requirements for using PowerDynamo mail objectsThe PowerDynamo mail objects fully support the SMTP and POP3 Internmail transfer protocols.

To use the PowerDynamo mail objects within your Dynamo scripts you mhave access to an SMTP server to send mail and a POP3 server to receive

Mail sent from a PowerDynamo script does not necessarily have to be reathrough a POP3 mail server. Other mail programs such as Lotus Notes anExchange may be used to read mail that has been sent from a Dynamo s

Figure 9-1: SMTP and POP3 servers

204

CHAPTER 9 PowerDynamo Mail Support

205

Sending mail

nts the

to

erty ple,

tant's sor's

Sending mailTo send mail with PowerDynamo use the outgoing mail piece object. The outgoing mail piece object has many different methods and properties to help manipulate the way you want your outgoing mail piece to perform.

Some of the options that may be useful when sending mail through PowerDynamo are as follows:

• Attachments You can send attachments such as files and documealong with a mail piece. The attachment object allows the recipients ofmail piece to manipulate the attachment as required.

• Error checking Use the GetErrorCode and GetErrorInfo methods monitor the status of a mail piece that is being sent.

• Multiple addresses You can send a single mail piece to many people.

• Sender property You can specify a sender property. The sender property represents the person that sent the mail piece. The from proprepresents the person from whom the mail piece originated. For examif an assistant was sending a mail piece for their supervisor, the assisname would be represented by the sender property while the superviname would be represented by the from property.

To send a mail pieceTo send a mail piece from Dynamo you need:

• An SMTP host name

• The address of the person you are sending the mail to

• The address from which the mail piece is being sent

❖ To create and send a mail piece from within a Dynamo script:

1 Specify an SMTP host in the Default General Setting folder of SybaseCentral.

2 Create an empty Dynamo script within Sybase Central.

3 Open the script for editing.

4 Enter:



This code creates a mail piece called mp. Properties and methods are used to define the sender, recipient, subject, and actual content of the mail piece. The Send method actually sends the mail piece.

5 Replace [email protected] with your own address.

6 Replace [email protected] with the address of the recipient.

7 Save the script.

8 Execute the script.

9 To verify that the mail piece was sent, replace the line:

mp.Send();

with:

if( !mp.Send() ) { document.writeln( mp.GetErrorCode() ); document.writeln( mp.GetErrorInfo() );}

For additional information, see “The mail piece object (outgoing)” in PowerDynamo Reference.

207

Receiving mail

es to

he OP3

ail

at

Receiving mailYou can receive mail through Dynamo using a POP3 server, the DynaScript mail list, and incoming mail piece objects.

To retrieve mail from PowerDynamoTo retrieve mail from PowerDynamo you need:

• The name of the POP3 server

• A user ID and password to connect to the POP3 server

The most efficient way to retrieve mail is to generate a list of the mail piecthat are waiting at the POP3 server, then select the mail pieces you wantdownload. Generally this will be done all in one script.

❖ To generate and retrieve a mail list from a Dynamo script

1 Create an empty Dynamo script within Sybase Central.

2 Open the script for editing.

3 Enter this code, which creates a mail list object and a connection to tPOP3 mail server. Replace mail.sybase.com with the name of your Pserver:



4 You may request all your mail or you may select individual pieces of mbased on size or subject matter.

To retrieve all your mail from a Dynamo mail list, modify the code so thit looks like this:



This script checks each mail piece to see if the subject line is “Bug Report.” If it is, the contents of the mail piece and the sender display.

5 Save the script.

6 Execute the script.

209

Deleting mail

Deleting mailYou can use either the Delete method of the Retrieve method to delete mail objects.

The Delete method allows you to delete a specific mail piece from the server, while the Retrieve method marks a mail piece for deletion as soon as it has been retrieved from the server. In either case the deletion occurs when you disconnect from the POP3 server.

This example retrieves all mail pieces from the mail server and marks them for deletion.



210


Forwarding and replying to mailYou can forward, reply to, or redirect incoming mail in the same way as you would with most other mail applications.

Forwarding mailYou can either include your own message along with the forwarded mail piece or you may forward a mail piece as it is with no additional text.

Select the mail piece you want to forward. For example:

mlist = new MailList ("mail.sybase.com", "elmo", "dynamo", "[email protected]");mlistitem = mlist[0];mlistitem.Retrieve();

Specify that you want to forward the mail and the address to where you want to forward it. For example:

forwardmp= mlistitem.Forward("[email protected]")

The body of the original mail piece is now held in forwardmp.body. To add your own text to the mail piece you would do something like:

forwardmp.body = ( "Please review this mail piece " + forwardmp.body );

The full script looks similar to the following:



211

Forwarding and replying to mail

Replying to mailSelect the mail piece you want to reply to. For example:

mlist = new MailList ("mail.sybase.com", "elmo", "dynamo", "[email protected]");mlistitem = mlist[0];mlistitem.Retrieve();

Indicate that you want to use the Reply method and the address to which to respond. For example, to respond to all recipients including the sender and include the original mail piece in the body of the outgoing mail piece, enter:

replymp=mlistitem.Reply( "all", true );

To add your own text to the mail piece you enter something like:

forwardmp.body = ( "I have read the attached document and all the changes look correct. " + replymp.body );

The mail piece is then sent in the normal fashion. The full script would look similar to:



212


er

A simple mail applicationIn this section you will create a simple mail application which may be used to send and view mail for a number of users. To use this simple application, you must have access to a POP3 mail server and a SMTP host.

Create the following templates in your PowerDynamo Web site:

mailMain.stm

<HTML><TITLE>mailMain.stm</TITLE><BODY><H1>Dynamo 3.5 Mail</H1><a href=mailComp.stm>Compose a piece of mail</a><BR><a href=mailListMain.stm>List mail in the mail box</a></BODY></HTML>

Notes • This is the starting page for the application. To access it from a browsthe URL would look something like http://localhost/Site/mailmain.stm.

• Links to other parts of the mail application allow the user to decide whether to compose a new mail piece or view existing mail pieces.

mailComp.stm <HTML><TITLE>mailcomp.stm</TITLE><BODY><h1>Sending an email<form action=mailSend.stm> <table> <tr><th align=left>From:</th> <td><input type=input name=from size=30 maxlength=30 [email protected]></td></tr> <tr><th align=left>To:</th> <td><input type=input name=to size=30 maxlength=30 [email protected]></td></tr> <tr><th align=left>Host:</th> <td><input type=input name=host size=30 maxlength=40 value=boot.sample.com></td></tr> <tr><th align=left>Subject:</th> <td><input type=input name=subject size=50 maxlength=60 value=’testing stuff’></td></tr> <tr><th align=left>Body:</th> <td><textarea name=body rows=5 cols=50> Enter your message here... </textarea></td></tr> </table>

213

A simple mail application

<input type=submit value=Send> <input type=submit value=Cancel> </form></BODY></HTML>

Notes • This page enables a mail piece to be composed and sent.

• Ensure that a valid host has been specified either in the template youcreate, or via Sybase Central.

For more information on setting the host see the “smtpHost property” in PowerDynamo Reference.

For more information on the outgoing mail, see “The mail piece object (outgoing)” in PowerDynamo Reference.

mailSend.stm <HTML><TITLE>mailsend.stm</TITLE><BODY><H1>Dynamo 3.5 Mail</H1><a href="mailMain.stm">click here to return to the mail menu</a></BODY></HTML>

Notes • This file sends the mail piece and checks for errors.

For more information on error checking, see “The mail piece object (outgoing)” in PowerDynamo Reference.

214


ell as d.

y.

mailListMain.stm <HTML><TITLE>mailListMain.stm</TITLE><BODY><H1>Dynamo 3.5 display of mail in the mailbox</H1> <form action=’mailList.stm’ method=post> <table> <tr><th align=left>Mail Server:</th> <td><input type=text name=mailServer size=30 value=mailsrv.sybase.com></td></tr> <tr><th align=left>User Name:</th> <td><input type=text name=username size=30 value=george></td></tr> <tr><th align=left>Password:</th> <td><input type=password name=passwd size=30 value=dynamo></td></tr> </table> <input type=submit name=action value=Logon> </form>

</BODY></HTML>

Notes • This page requests the name of the mail server that is to be used as wthe user name and password for the mail pieces that are to be viewe

• Only the mail that has been sent to the user name provided will displa

mailList.stm <HTML><TITLE>mailList.stm</TITLE><BODY><H1>Dynamo 3.5 Mail</H1><BR><a href=mailMain.stm>Return to the main menu</a></BODY></HTML>

Notes • This page displays all the mail messages that have been sent to the u(specified in mailListMain.stm).

For information on the incoming mail piece and its methods see “The maipiece object (incoming)” in PowerDynamo Reference.

Once you have created these files, you can start your mail application by opening mainMail.stm in a browser.

216

C H A P T E R 1 0 Achieving Optimum Performance with PowerDynamo

About this chapter This chapter describes how to design a PowerDynamo Web site to ensure maximum productivity and performance.

Contents Topic Page

Performance requirements 218

Increasing the performance of your Web site 222

Optimizing your document cache 223

Scheduling your scripts 228

Writing cacheable documents 230

Expensive methods and properties 234

Load balancing 235

Converting an inefficient Web site to an efficient Web site 237

Summary 240

217

Performance requirements

in nd.

the be rom

est

lows

t. two . The If the

Performance requirementsPowerDynamo includes features that have been specially designed to make the creation and optimization of high volume Web sites practically effortless.

Dynamo Web sites that are designed without thought to performance or site specifications generally experience a slow down due to one or all of the following reasons:

• Slow or excessive processing of scripts

• Exorbitant calls to the database

• Expensive use of connections

Processing of scriptsWeb sites that are required to support large volumes of traffic must contadocuments that have been created with the criterion of the Web site in mi

As a general rule, a Web document should take no longer to execute thantime between requests to the Web site. For example, if a Web site has anaverage of one request every three seconds, each Web document shouldwritten so that no document takes longer than three seconds to execute fstart to finish.

The ideal script designThis section describes the ideal design where each script is the only requbeing processed at any time. In reality, multiple requests will arrive for processing by the Web site. PowerDynamo's multithreaded architecture alfor efficient processing of these scripts.

If only one Web document is being executed by PowerDynamo, 100% of Dynamo's CPU time may be available for the processing of that documenThis results in the shortest possible execution time of a document. When or more documents are being processed concurrently, CPU time is sharedsharing of CPU time increases the time required to complete the request. average volume of requests is once every two seconds and the average document takes three seconds to execute, a backlog is created as each subsequent request takes longer to execute.

Figure 10-1 illustrates how the length of time required to execute a script increases as the load on the Web server increases.

218

CHAPTER 10 Achieving Optimum Performance with PowerDynamo

” on

or

cute the ber

e the

te a the

Figure 10-1: Relationship between load and processing time

For more information on minimizing the processing time of your scripts, see “Writing cacheable documents” on page 230 and “Scheduling your scriptspage 228.

For more information about running PowerDynamo on a multiple processsystem, see “Load balancing” on page 235.

Minimizing the calls to the databaseYet another cause for performance degradation is the time required to exequeries against the database. PowerDynamo does not have control over time required to issue a query, but it does provide ways to control the numof times a database is accessed.

Setting an efficient document cache size as well as defining cachedOutputTimeOut values where appropriate can significantly minimizthe number of calls to a database. Further improvements can be made toefficiency of a Web site by scheduling certain documents to execute on aspecial time frame.

If you do not optimize scripts and minimize database calls when you creahigh-volume Web site, you may experience the time lag demonstrated in first time line in Figure 10-2.

219

Performance requirements

and sers akes tions,

e time eb

g

Figure 10-2: Optimizing scripts

For more information about minimizing calls to your database, see “Optimizing your document cache” on page 223.

Working with Connections to increase performanceThe third most common cause of performance degradation is the creationuse of connections within a Web site. Connections are the link between uand the information that they request from a Web site. Each time a user ma request to a dynamic Web site, connections are created. Creating connecwhile necessary, requires costly processing time.

With minimal effort from the Web author, PowerDynamo is able to optimizits connections and work with them in such a way that required processing for creating connections need not be an issue to the performance of the Wsite.

For more information about working with connections, please see “Workinwith connections” on page 60.

220


hour

ize igh

le to

Designing your Web siteWhen you create a dynamic Web application site, you should plan and design the site to provide optimum performance. A Web site can work only as fast as its design allows.

You should consider these factors when designing a dynamic Web site:

• What is the expected volume to be hitting the Web site?

• How often will the data being queried change?

• What can you afford to set your cache size to?

• How essential is the timing of the information being delivered? For example, does the data need to be updated every minute or is once ansufficient?

Once you have evaluated these factors you can decide how to best optimyour Web site. For example, if you are creating a dynamic Web site with hvolume throughput, you’d probably want to take these steps:

• Set the proper CachedOutputTimeout value.

• Set a maximum cache size.

• Schedule documents that can be.

• Create the proper type of connection for each query.

• Queries should be as specific as possible to support caching.

The following sections describe in more detail the features that are availaboptimize PowerDynamo to its greatest possible performance.

221

Increasing the performance of your Web site

osted a

Increasing the performance of your Web siteThere are many factors that determine the speed of a Web site. For high throughput Web sites that rely on dynamically driven data, it is essential that Web sites be appropriately streamlined to handle the required volume. PowerDynamo delivers to users the ability to fine-tune their own Web sites according to the level of performance they require and the individual characteristics of their Web site application.

There are four key areas that you can manipulate to increase the performance of a dynamic Web site:

•Document cache Memory used to hold recently accessed documents so that subsequent requests of the same document do not require re-retrieving the document from the database or file system.

•Scheduling The act of scheduling a document to execute at a certain time on a regular basis. The generated output is stored in a document and returned to all subsequent requests for the scheduled document. Data is updated each time a scheduled document is executed.

•Scripts and templates The documents that hold the HTML and database queries that are used to generate dynamic content.

•Connections PowerDynamo uses two kinds of connections – Dynamo connections, which are used to extract documents from a database-hWeb site, and User connections, which are used to extract data from database.

222


Optimizing your document cacheTo achieve optimum performance, it is crucial that you understand how the document cache works with your PowerDynamo Web site.

The document cache stores document source and output, for a duration of time, to minimize unnecessary processing of that document.

Figure 10-3 demonstrates a dynamic PowerDynamo Web document from a database-hosted Web site.

Figure 10-3: Dynamic PowerDynamo Web document

223

Optimizing your document cache

urce uent

and

t can in to

at can

le

nd

Once a request for a document has been made, three basic paths are possible. They are listed here in order of the most to the least efficient:

•Doc source and output held in cache The output is retrieved from the cache and returned.

•Doc source held in cache The document is executed and the appropriate information is stored in the cache and the output is returned.

•Doc source not held in cache A connection must be made to the Web site to retrieve the document source. The document in executed and the appropriate information is stored in the cache and the output is returned.

The most efficient path is requests for documents that have been written in such a way as to support cached output.

For more information about writing documents with cacheable output, see “Writing cacheable documents” on page 230.

Setting a document cache sizeAll documents that are executed in a PowerDynamo Web site have their so(and optionally their output) stored in the cache. This ensures that subseqrequests for the same data can be readily processed without the original expenditure of processing time to create connections, retrieve the sourceexecute the script. You set the storage size in Sybase Central.

The specified cache size determines the number (size) of documents thabe stored in the cache before the least recently requested documents begbe released to make room for more recently requested documents.

The result of caching documents greatly reduces the processing time for repeated requests for a document. For this reason, the more documents threside in the cache at any one time the better.

Setting the cache sizeDo not set your document cache size higher than your machine's availabmemory.

❖ To set the document cache size:

1 In Sybase Central, select Utilities | Configuration | Mappings folder.

2 Right-click on the mapping for which you want to set the cache size aselect Properties.

224


3 Enter the desired document cache size.

4 Click OK.

5 Restart the Web server for these changes to take effect.

Setting a cachedOutputTimeOut valueCachedOutputTimeOut is a property of the DynaScript document object that sets the duration of time for which the generated output of a document will be cached.

Setting a cachedOutputTimeOut value in a document allows the Web author to store the generated output of the document, after execution, for a predetermined amount of time. If a second request is then made to the same script within the allocated amount of time, the output in the cache is returned without execution of the document being required. This is much more efficient than the document executing again and possibly repeating the same database calls that were just made.

The following example sets a cachedOutputTimeOut of three minutes for the document:



or you can use the Dynamo tag method:



When you set a cachedOutputTimeOut value, ensure that you are not compromising the validity of your Web site to increase performance. For example, while storing output for an extended period of time increases the performance of your Web site, it may also diminish accuracy if you store the generated output for too long. You should ensure output is regenerated with a frequency that is appropriate for the Web site data.

225

Optimizing your document cache

l be ve

Out

ain e cache ently g the

The relationship between cache size and cachedOutputTimeOut values

There are two pieces of information that can be stored in the document cache for each Web document.

• The document source, which is automatically stored in the documentcache

• The document output, which is stored in the document cache if a cachedOutputTimeOut value is set in the Web document.

What is the difference?

The output of documents without a cachedOutputTimeOut value must stilgenerated but the source is available without a call to the database or filesystem. Documents that have a cachedOutputTimeOut value specified hatheir output stored in the cache as well as the source.

When it is possible, you should create documents with cachedOutputTimevalues.

The size of the cache The size of the document cache may affect how documents with specifiedcachedOutputTimeOut values are cached.

If a document has a cachedOutputTimeOut value of 10 minutes, it will remin the cache for the full 10 minutes only if there is room for it along with thsubsequent documents that are called during those 10 minutes. When the is full and a new document is requested, the document that was least recused is flushed to make room for the new document regardless of how loncachedOutputTimeOut value is set to.

Type of cachingStored in the cache Conditions

Database-hosted, dynamic Web site document with a cachedOutputTimeOut value specified.

Generated output and source

• Data need not be refreshed every time a request is made.

Database-hosted, dynamic Web site document with no cachedOutputTimeOut value specified.

Source • Data must be refreshed each time a request is made

Database-hosted, dynamic Web site document with an insufficient document cache size.

Source (will be flushed from the cache before being of any use performance wise)

• source and data must be refreshed each time a request is made

226


Cache is flushedThe entire document cache is flushed if you modify or create documents outside a Web server environment; for example, in Sybase Central.

227

Scheduling your scripts

’s

,

ified

ins .

duling

-up

t is

ns”

Scheduling your scriptsPowerDynamo allows you to schedule documents to be executed hourly, daily, weekly, monthly or yearly. Once a scheduled document executes, subsequent requests of that document can receive the output without requiring processing time or User connections. Scheduling documents can significantly cut processing time and the number of database calls.

If a document called sample.stm were scheduled to run once every hour, herewhat would happen:

1 sample.stm is moved to a new file called sample.sts.

2 If you selected to pregenerate the output, sample.stm holds the generated output resulting from executing sample.sts. If you did not select to pregenerate the data, sample.stm remains empty until the first scheduledexecution. In either case, the output is available as a static source filewhich makes a cachedOutputTimeOut value in scheduled documentsunnecessary.

3 An entry is added to the schedule.ssc file in the system directory to let Dynamo know that a document had been scheduled to run at the spectime.

4 Subsequent requests for sample.stm returns the data being held in sample.stm. No execution of the document is required as the data remaavailable for subsequent retrievals until the next scheduled executionWhen the next execution occurs, sample.stm is updated with new output.

For data that does not need to be updated more than once an hour, schedocuments for slow times or at regular intervals can greatly increase the performance of a Web site.

❖ To schedule a document:

1 In Sybase Central, locate the script or template to schedule.

2 Right-click on the script or template and select Schedule from the popmenu to start the Schedule wizard.

3 Select the time interval from the drop-down list in the wizard.

4 Enter a time, within the specified time interval, at which the documento be generated.

For more information about scheduling documents, see “Scheduling actioon page 57.

228


nput main

ser rate ent f

ect A

Documents that take parametersDo not schedule or assign a cacheOutputTimeOut value to documents that require users to enter parameters. This kind of document depends on the parameters provided by the users; therefore, you cannot cache output.

For information on writing cacheable documents, see “Writing cacheable documents” on page 230.

Enhancing performance for non-cacheable documentsFor documents that would benefit from being scheduled but require user iyou might want to separate the script into multiple documents. Create one document with as many side documents as required to meet the main document's requirements. For example, if a main document allowed the uthe option of choosing between A, B, C, or D, you might create four sepadocuments for each one. If the user chose option A, the applicable documwould be called (docA.stm) from the main document. Because the content odocA.stm does not require user input, you can schedule it or assign a cachedOutputTimeOut value so data is already available for users that selfrom the main document.

For more information, see “Writing cacheable documents” on page 230.

229

Writing cacheable documents

ed.

o

Writing cacheable documentsOne of the most expensive tasks of a Web site is generating the output of a dynamic document. Caching a document’s output with the cachedOutputTimeOut property can significantly reduce the time required by a Web site to respond to a request.

You should write Web documents so as many as possible use cacheable output and have a cachedOutputTimeOut value assigned.

The following Web documents do not produce cacheable output:

• Documents that require information from the user

• Documents without a cachedOutputTimeOut value

Output that use variables given by the user are a good example of non-cacheable output. The first script, multiIntro.stm, displays a list of radio buttonsfor users to select the price range of products that they would like display

Notes • The documents choice1.stm, choice2.stm and choice3.stm all have cacheable output since each performs a specific query and requires nparameters.

• If choice1.stm, choice2.stm and choice3.stm and the output generated byeach remain in the cache a request for mulchoice.stm does not require any queries against the product table.

<HTML><TITLE>multiIntro.stm</TITLE><BODY><H1>Product List</H1><P>The following items are available from the sample database</P><TABLE BORDER><TR><TH>name</TH></TR><TR><TD></TD></TR></TABLE><P>Enter the price range you would like displayed</P><FORM METHOD=POST ACTION="mulchoice.stm" MULTIPLE

230


SIZE="5"><OL><INPUT TYPE="radio" NAME="choice" value="less10">Less than $10<BR><INPUT TYPE="radio" NAME="choice" value="less20">Less than $20, more than $10<BR><INPUT TYPE="radio" NAME="choice" value="less30">Less than $30, more than $20<BR></OL><P><INPUT TYPE="submit" VALUE="Submit List"></P><P><INPUT TYPE="RESET" VALUE="Clear Form"></P></FORM></BODY></HTML>

multiIntro.stm calls the following script, which in turn calls one of three scripts depending on the parameter being passed:

mulchoice.stm <HTML><TITLE>Selected Products</TITLE><BODY></BODY></HTML>

choice1.stm <H1>The following items are under $10.00 in price</H1><TABLE BORDER><TR><TH>name</TH>

231

Writing cacheable documents

<TH>color</TH><TH>unit_price</TH></TR><TR><TD></TD><TD></TD><TD></TD></TR></TABLE><!—DOCUMENT CACHED_OUTPUT_TIMEOUT = 10 -->

choice2.stm <H1>The following items are $10.00 to $20.00 in price</H1><TABLE BORDER><TR><TH>name</TH><TH>color</TH><TH>unit_price</TH></TR><TR><TD></TD><TD></TD><TD></TD></TR></TABLE><!—DOCUMENT CACHED_OUTPUT_TIMEOUT = 10 -->

choice3.stm <H1>The following items are $20.00 to $30.00 in price</H1><TABLE BORDER><TR><TH>name</TH><TH>color</TH>

232


<TH>unit_price</TH></TR><TR><TD></TD><TD></TD><TD></TD></TR></TABLE><!—DOCUMENT CACHED_OUTPUT_TIMEOUT = 10 -->

233

Expensive methods and properties

ts.

e)

f

Expensive methods and propertiesDynaScript consists of several objects made up of methods and properties. In general, methods or properties that cause a connection to a database to be created or a document to be loaded are expensive to execute. When possible, you should avoid excessive use of the more expensive methods and properties in Web sites that hold performance at a premium.

For example, suppose you wanted to display the URL of the parent of your current document. Using the parent property is an expensive way of doing this.



document.parent may require that the parent document be loaded from the database or file system. This may in turn, bump a document out of the document cache if the cache is full. A more resourceful way of obtaining the same information is to use document.location with the substring method to extract the parent’s URL from the current URL. This is less expensive since the current document is already loaded.



The more expensive DynaScript methods and properties include:

• connection.simulateCursors with databases (such as Adaptive Server Enterprise) that do not support backward movement through result se

• query.GetRowCount with databases (such as Adaptive Server Enterpristhat do not support row counts.

• new Connection constructor this kind of connection does not make use othe connection pool.

234


e for

f a

read read

Load balancingLoad balancing – that is, running PowerDynamo on systems with multipleprocessors or across multiple server machines – can be extremely effectivimproving PowerDynamo performance.

Load balancing across processorsThe multithreaded design of PowerDynamo makes the use of a multiple processor system an excellent candidate for improving the performance oPowerDynamo Web site.

Each request to a PowerDynamo application is received on an individual th(worker threads). Because of this, PowerDynamo requests are evenly spamong the available processors.

Figure 10-4: Distributing PowerDynamo requests to worker threads

235

Load balancing

Load balancing across serversAnother setup for improving the performance of a Web site by load balancing is the using PowerDynamo with multiple Web servers. The use of PowerDynamo with a load balancing mechanism such as the Cisco LocalDirector enables TCP/IP traffic to be distributed across multiple low-cost servers.

Figure 10-5: Load balancing Web servers

Further information on the Cisco LocalDirector can be found at the following URL: http://www.cisco.com/warp/public/751/lodir/index.html.

236


lf is

our e

wn le so e. If

sible. r

e of

ing ent

Converting an inefficient Web site to an efficient Web site

Let's say that the high-volume Web site “Hockey” has an average of one request every two seconds, 24 hours a day. Half the data being accessedchanges at most once a day (statistics, player info etc.) while the other haconstantly changing (game scores, penalties etc.).

For a Web site such as this, each area of the site must be looked at and inefficient or unnecessary processing eliminated.

We’ll look at four key areas to ensure that the Web site is operating as efficiently as possible.

• The Web documents

• The document cache

• The use of scheduling

• The connections

If you use Windows NT, you can use the Performance Monitor to monitor yWeb site's performance. For more information see “Using the PerformancMonitor” on page 70.

Working with documentsAny document that takes longer than two seconds to execute can slow dothe system. Wherever possible, documents must be as specific as possibqueries can execute as quickly and take no longer than the time betweenrequests to complete. Ideally, each request should receive 100% CPU timthis goal is attained, requests are processed at maximum efficiency.

Another practice that leads to performance degradation is putting multiplequeries in one script. Again, each document should be as specific as posIt is far more efficient to have many specific documents than to have fewegeneral documents. More specific documents allow you to take advantagoutput caching.

Categorize your documents

By categorizing your documents and setting them up accordingly, much processing time can be eliminated. Categorizing automatically uses cachand scheduling to enhance performance. You can categorize each documinto one of the following three categories:

237

Converting an inefficient Web site to an efficient Web site

ng . This

e

and alues sure uests

ll be old size o be re-

ork

ffic t 15,

s tly ays

• Data that changes less than once an hour or documents that take a lotime to execute – Schedule these documents to run on a regular basismakes the output readily available for subsequent requests.

• Data that changes once an hour or more often – Assign appropriate cachedOutputTimeOut values to these documents.

Refer to “Setting a cachedOutputTimeOut value” on page 225 for morinformation.

• Data that is constantly changing and must be accurate to the minute documents that take parameters – do not set cachedOutputTimeOut vfor these documents or schedule them with the scheduling wizard. Enthat the cache size is set high enough to hold their source so those reqcan be processed as quickly as possible.

A cache size should be set that is appropriate for the Web site that wiutilizing it. It is important that the size of the cache is large enough to hall the active documents for at least a brief duration of time. If a cache is too small, the stored document output and source may be flushed tmake room for more recent documents before they have a chance to used before being unloaded.

Working with connectionsThere are several ways for a Web author to control the way connections wwithin a Web site:

• Setting a connection timeout

• Setting maximum and minimum number of connections

• Creating permanent or temporary connections.

Connection timeout value

The first value you should set to increase performance is the connection timeout value. The default connection timeout value of 0 indicates that allconnections remain in the connection pool. Because of the fluctuating trathat our Web site receives, this is not what we are looking for. For the besperformance for this Web site, we will set the connection timeout value to which holds a connection in the pool for 15 minutes after the last time it was active. The number of connections stored in the connection pool fluctuatewith the Web site volume. This produces better performance than constancreating new connections or keeping enough connections in the pool to alwcover the peak times of volume.

238


ting

t

d be ed to

ge

Next, we will look at the maximum and minimum number of User connections for our Hockey Web site.

User connections At peak times our Web site uses a maximum of 20 User connections. Since this is manageable without slowing down the overall performance of the Web site, we can set the maximum number of User connections to 20.

Number of User connectionsCaching document output and scheduling documents may greatly reduce the required number of User connections for your Web site.

During the slow times, there is a minimum of four User connections per definition being used at any one time. By setting the minimum number of User connections to four, we ensure that four connections will always remain in each connection pool ready for use.

Dynamo connections The minimum and maximum connections for User connections applies per definition. The minimum and maximum number of connections for Dynamo connections is a total since each Web site has only one Dynamo connection. For example, suppose there are two User connections defined in the connections folder of Sybase Central; “sales_db” and “marketing_db”, seta minimum number of user connections to four would mean that eight connections would be held in the connection pool, once created.

Our Hockey Web site requires a slightly smaller number of Dynamo connections than User connections. The maximum number of Dynamo connections will be set to fifteen and the minimum number of Dynamo connections will be set to five.

Use of permanent and temporary connections

Finally, let's look at whether our Web site is using temporary or permanenconnections within its scripts. We need to ensure that temporary User connections are used only in the appropriate instances. Scripts that use temporary User connections that are reused in day to day Web use shoulchanged to permanent User connections to minimize the processing requircreate a new connection each time.

For more information on connections see “Working with connections” on pa60.

239

Summary

Summary

Ways to increase performance:

Set an appropriate cache size

Set a cachedOutputTimeOut value in the appropriate documents

Create the most efficient type of connections in your documents

Set connection minimum and maximum defaults that are correct for your Web site

Set an appropriate connection time out value

Schedule all possible documents for minimal processing time

Ensure that your scripts are specific and efficient

Limit the time of processing per document to use the CPU time the most efficiently

240

C H A P T E R 1 1 Setting Up a Mobile Intranet

About this chapter This chapter describes how to set up a mobile intranet using PowerDynamo and SQL Remote replication technology.

PowerDynamo allows you to browse both static and dynamic Web pages, and enter data using HTML forms. SQL Remote provides message-based replication technology. Together, these two applications enable you to set up a mobile intranet that can be used on laptop computers without requiring constant network connections.

Contents Topic Page

SQL Remote replication technology 242

Requirements for a mobile intranet 243

Replicating a Web site 244

A Replication Tutorial 246

241

SQL Remote replication technology

dreds

, and

the

n a

r dds

aptive sing

the rver.

base

SQL Remote replication technologySQL Remote is an established message-based database replication technology. When combined with a database-hosted Web site it, enables your intranet applications and documents to be deployed on laptop computers.

SQL Remote is a transaction-based replication technology that provides:

• Replication between a central consolidated database server and hunor even thousands of occasionally-connected remote databases.

• A loose concurrency among all components of the dispersed databasetransactional integrity of your database.

• Updates to occur via e-mail or file sharing.

• A publish-and-subscribe model that allows your users to receive only data they need.

• The ability to place a full transaction-processing relational database onotebook computer.

• Replication of updates that occur at either consolidated or remote databases.

• Centralized task via Sybase Central.

For complete information about SQL Remote, see the Data Replication with SQL Remote manual.

Web site replicationThe components of a PowerDynamo Web site are HTML templates, otheembedded objects (images, sound, video, and so on), and the data that acontent to the HTML templates.

Because these objects are all stored in a relational database, such as AdServer Enterprise or Adaptive Server Anywhere, they can be replicated uSQL Remote. The databases against which the queries run can also be replicated, so that all the relevant portions of the Web site, including its dynamic content, can be replicated to mobile users.

As SQL Remote allows bidirectional replication, changes can be made todata from a Web client and can be replicated back to the consolidated se

You can manage replication of both the Web site and of the data using SyCentral.

242

CHAPTER 11 Setting Up a Mobile Intranet

tive

e.

er

hold

f

ts.

Requirements for a mobile intranetAt the central location for your mobile intranet, you must have:

• PowerDynamo, for developing your Web site.

• A central server for your intranet data. This can be either Sybase AdapServer Anywhere or Sybase Adaptive Server Enterprise.

• A central server for your Web site documents. This can also be eitherAdaptive Server Anywhere or Adaptive Server Enterprise.

Note You can use the same server for both data and Web site storag

• Sybase SQL Remote, to manage replication.

Each remote machine requires:

• TCP/IP networking software. This is required for browser to Web servcommunication, even if the machine is never connected to a TCP/IP network.

• A browser or other Web client software.

• The PowerDynamo Personal Web Server.

• A Sybase Adaptive Server Anywhere standalone database engine, tothe local copies of the data and the Web site templates.

• The Sybase SQL Remote Replication Agent, to carry out replication odata and Web site documents to and from the central site.

Confirm licensing before deployment Before you deploy this software, you must confirm that you are abiding by your software license agreemen

243

Replicating a Web site

.

the

ive a

the

Replicating a Web siteTo replicate a Web site you need to make the database tables containing the Web site information available as a SQL Remote publication, they ensure that users have subscriptions to both the publication and the relevant data referred to in the templates.

You can use Sybase Central to replicate Dynamo Web sites.

To replicate a Web site:

• Define the publications and subscriptions for the data to be replicated

• Configure each remote user's machine for Web site access and SQL Remote replication.

Setting up publications and subscriptionsPublications and subscriptions define the data that is to be replicated, andlocations to where replication occurs.

❖ To subscribe users to your Web site:

1 Use Sybase Central to connect to the database where the Web site templates and scripts are stored. The connection should be an AdaptServer Anywhere or Adaptive Server Enterprise connection, rather thanPowerDynamo connection.

2 Open the SQL Remote folder.

3 Create a publication containing all the Web tables:

• WebConnection

• WebData

• WebDocumentType

• WebSynchronize

• WebTemplate

• WebVersion

4 Create subscriptions for users to this publication.

For a full description of how to create publications and subscriptions, seeSQL Remote User’s Guide.

244


Setting up remote usersOnce you have defined subscriptions in the central database, you can set up remote machines to handle SQL Remote replication.

❖ To set up remote machines for mobile Intranet use:

1 Install the necessary software onto the remote user’s machine.

2 Ensure the user is subscribed to the database containing the Web site and the database containing the data accessed by the templates, if it is different.

3 For the remote user, extract an initial copy of the database or both databases, if they are different.

4 If necessary, set up the required ODBC data source for the database (or databases) on the remote machine.

5 Configure the Personal Web Server mappings to point to the correct connection profiles.

6 Ensure that the Web client can access the Intranet site on the local machine when the Personal Web Server is running.

245

A Replication Tutorial

base

.

our

er

site les

A Replication Tutorial This section includes a tutorial in which you set up a simple SQL Remote replication system between an Adaptive Server Enterprise consolidated database and a remote Adaptive Server Anywhere database to replicate a Dynamo Web site along with accompanying data.

In the tutorial you act as the system administrator of a consolidated Enterprise database, and set up a simple replication system. The replication system consists of a sales database with two tables, and a Web site.

The consolidated database holds all of the database and Web site, while the remote database has the entire Web site, all of one table, and some of the rows in the other table.

The goals of the replication design are to provide each sales representative with:

• The complete SalesRep table

• Those customers assigned to them

• A Web site for querying and updating their data

The tutorial describes how to meet this goal using SQL Remote and the SyCentral management utility.

The tutorial takes you through:

• Creating a consolidated database on your Adaptive Server Enterprise

• Connecting to the consolidated database through Dynamo to create yWeb site.

• Creating a file-sharing replication system with a single Adaptive ServAnywhere remote database.

• Replicating the Web site between the two databases.

The databaseThe tutorial uses a database that contains two tables and a Dynamo Webthat performs queries on the tables. One table holds information about sarepresentatives, and the other about customers.

Database schema The database schema for the tutorial is illustrated in Figure 11-1.

246


Figure 11-1: Database schema

Each sales representative is represented by one row in the SalesRep table, and each customer is represented by one row in the customer table.

Each customer is assigned to a single Sales representative, and this assignment is built in to the database as a foreign key from the Customer table to the SalesRep table. The relationship between the Customer table and the SalesRep table is many-to-one.

The tables in the database

The tables are described in more detail as follows:

Table Description

SalesRep The SalesRep table has the following columns:

• rep_key An identifier for each sales representative. This is the primary key.

• name The name of each sales representative.

The SQL statement creating this table is as follows:CREATE TABLE SalesRep (rep_key CHAR(5) NOT NULL,name CHAR(40) NOT NULL,PRIMARY KEY (rep_key)

)

Customer One row for each customer that does business with the company. The Customer table includes the following columns:

• cust_key An identifier for each customer. This is the primary key.

• name The name of each customer.

• rep_key An identifier for the sales representative in a sales relationship. This is a foreign key to the SalesRep table.

The SQL statement creating this table is as follows:CREATE TABLE Customer (cust_key CHAR(12) NOT NULL,name CHAR(40) NOT NULL,rep_key CHAR(5) NOT NULL,FOREIGN KEY ( rep_key )

REFERENCES SalesRep ( rep_key ),PRIMARY KEY (cust_key)

)

247


be

tion ase.

Setting up SQL Remote using Sybase CentralThe first part of the tutorial describes how to set up a simple SQL Remote replication system using Sybase Central. You do not need to enter SQL statements if you are using Sybase Central to administer SQL Remote.

Create a login name and password

You must have system administrator privileges on an Adaptive server. The tutorial assumes that your login name is sa and that the password is sysadmin.

Create a database Create a 20MB database named hq on your Adaptive Server Enterprise.

1 Connect to the Adaptive Server Enterprise from Sybase Central.

2 Open the Databases folder, and double-click Add database in the right pane.

3 Enter hq on the first page of the wizard.

4 Follow the instructions in the wizard.

For information on how to create databases and assign space to them, see your Adaptive Server Enterprise documentation. Install SQL Remote into the hq database.

Create the Web site Create a Dynamo Web site in the Adaptive Server Enterprise database:

1 Connect to the hq Adaptive Server Enterprise database from Dynamo. When asked if you would like to create a Web site, select Yes.

2 Enter a name for the Web site and select the check boxes if you would like to include the Dynamo samples and documentation.

3 The following Dynamo tables are created in your hq database:

• WebConnection

• WebDocumentType

• WebSynchronize

• WebTemplate

• WebData

• WebVersion

4 Later, you will connect to this Web site through a remote database. Toable to do this, you must modify the connection settings in your consolidated database so they do not hold specific database informasuch as data source names and passwords of the consolidated datab

248


From the Web site’s system folder, open the connect.ssc file. Modify the <default> connection so there is no information specific to the consolidated database. Your <default> connection should look like this:

site.LoadConnection( "<default>", "", "", "", "", "", "" );

Save the file.

Install SQL Remote Install SQL Remote into the HQ database:

1 Open the hq database container in the left pane of Sybase Central.

2 Open the SQL Remote folder, double-click Setup SQL Remote, and follow the instructions. For the tutorial, install the stable queue in the hq database.

If your TEMPDB database is too small, you may have to add space to it.

For a full description of how to install SQL Remote, see the Data Replication with SQL Remote manual.

Create directories for messages

Make a directory for the files created in this tutorial. For example:

mkdir c:\tutorial

Under this directory, create a directory for each of the two users of the replication system:

mkdir c:\tutorial\hqmkdir c:\tutorial\field

Add tables The next step is to add two user-defined tables to the consolidated database:

1 Connect to the hq database from Sybase Central.

2 Click the User Tables folder of the hq database.

3 Double-click Add Table, and use the Table Editor to create a table named SalesRep with the following columns:

You do not need to use the Advanced Properties window. By default, the columns do not allow NULL.

4 Double-click Add Table again, and use the Table Editor to create a table named Customer with the following columns:

Key Column Data Type Size/Prec

Primary key rep_key char 5

name char 40

249


ing

t you dress

Again, you do not need to use the Advanced Properties window. By default, the columns do not allow NULL.

5 Open the Foreign Keys folder of the Customer table container, and double-click Add Foreign Key. Using the wizard, add a foreign key to the rep_key column of the SalesRep table. Use the default settings for this foreign key.

Setting up the consolidated databaseThis section of the tutorial describes how to prepare the consolidated database of a simple replication system, including:

1 Creating a message type to use for replication.

2 Granting PUBLISH permissions to a user ID to identify the source of outgoing messages.

3 Granting REMOTE permissions to all user IDs that will receive messages.

4 Creating a publication describing the data to be replicated.

5 Creating subscriptions describing who is to receive the publication.

You should have system administrator authority to carry out these tasks.

Add a SQL Remote message type

All messages sent as part of replication use a message type. A message type description has two parts:

• A message link supported by SQL Remote.

• An address for this message link, which identifies the source of outgomessages.

Adaptive Server Anywhere databases have predefined message types, buneed to supply an address for the message type you will use. To add an adto a message type:

1 From Sybase Central, open the hq database container.

Key Column Data Type Size/Prec

Primary key cust_key char 10

name char 40

rep_key char 5

250


ssary

er is

r ID r ser ID

2 Click the SQL Remote folder on the left panel.

3 Double-click the Message Types folder on the right pane.

4 Double-click the file message type.

5 Enter hq as the publisher address. This provides a return address for remote users; the directory you created to hold messages for the consolidated database.

The address (hq) for a file link is a directory relative to the SQLRemote environment variable or registry entry. Because you have not set this value, the address is relative to the directory from which the Message Agent is run. You should run the Message Agent from your tutorial directory for the addresses to be interpreted properly.

6 Click OK to save the message type.

Create the necessary users and permissions

In this tutorial, the following are required for the SQL Remote installation:

• A publisher user name

• A remote user or subscriber

This section describes how to create each user and assign them the necepermissions.

To create the publisher:

1 From Sybase Central, open the container for the hq database.

2 Open the Users folder, and double-click Add User.

3 Create a user named hq_user. Map the login name to an available loginname on your server. The tutorial uses hq_pwd as the password.

4 Make this user the publisher of the hq database. Open the SQL Remotefolder, and double-click Set Publisher. Select hq_user from the list of users to set it as the publisher.

A database can have only one publisher. You can find out who the publishat any time by opening the SQL Remote folder.

Add a remote user Each remote database is identified in the consolidated database by a usewith REMOTE permissions. Whether the remote database is a single-usedatabase engine or a database server with many users, it needs a single uto represent it to the consolidated database.

251


In a mobile workgroup setting, remote users may already be users of the consolidated database. If this is the case, you may not have to add any new users, but you do need to set existing users as remote users.

When a remote user is added to a database, the message system they use and their address for that message system are stored along with their database user ID.

To add a remote user:

1 Double-click the SQL Remote folder in the left pane, then click the Remote Users folder.

2 If you do not have a login name to use for the remote user, open the Logins folder directly under the server container, and add a login. The name is unimportant.

Double-click Add Remote User in the right pane. The New Remote User wizard is displayed.

3 Create a remote user named field_user. Select FILE as the message type, then select the corresponding address you are using for this user (such as field).

As with the publisher address, the address of the remote user (field) is a directory relative to the SQLRemote environment variable or registry entry and may not be set appropriately for the tutorial. Run the Message Agent from your tutorial directory for the addresses to be interpreted properly.

For information about setting the SQLRemote enviroment variable, see the Data Replication with SQL Remote manual.

4 Next, ensure that the Send Then Close option is checked.

5 When you have finished all the entries, click Finish to create the remote user.

Create the publication and subscription

This section describes how to add a publication to a database, and how to add a subscription to that publication for a user. The publication replicates the full Dynamo Web site as well as all rows in the table SalesRep and some of the rows of the Customer table.

The first step is to mark the Web site tables as well as the SalesRep and Customer tables for SQL Remote replication. Marking a table for SQL Remote replication enables it to be included in publications.

252


ct ote

ame

1 Open the SQL Remote folder in the hq database.

2 Open the Remote Tables folder, and double-click Add Remote Table.

3 Select WebConnection from the list of tables. Leave the Conflict Resolution fields are they are and click Apply to mark the table for SQL Remote replication. Repeat this step for all the other Web site tables:

• WebDocumentType

• WebSynchronize

• WebTemplate

• WebData

• WebVersion

4 Select SalesRep from the list of tables. You can leave the Conflict Resolution fields as they are. Click Apply to mark the table for SQL Remote replication.

5 Select Customer from the list of tables. Again, you can leave the ConfliResolution fields as they are. Click OK to mark the table for SQL Remreplication.

To add a publication:

1 Click the Publications folder in the SQL Remote folder.

2 Double-click Add Publication.

3 On the first page of the wizard, name the publication SalesRepData.

4 On the next page, click Add Table and select SalesRep from the list. Leave All Columns selected, and press OK to add the table. Do the sfor all the Dynamo Web tables:

• WebConnection

• WebDocumentType

• WebSynchronize

• WebTemplate

• WebData

• WebVersion

253


that a

abase

Click Add Table again, and select Customer from the list. Again, leave All Columns selected. Click the Subscribe Restriction tab, and choose to Subscribe by the column rep_key. Click OK to add the table to the publication.

5 Complete the wizard to create the publication.

Add a subscription Each user ID that is to receive updates to a publication must have a subscription to that publication. You need to add a subscription to the SalesRepData publication for the remote database user field_user:

1 Double-click the Publications folder, which is in the SQL Remote folder, so that the SalesRepData publication is displayed in the left pane.

2 Click the Remote Users folder so that remote users are displayed in the right pane.

3 Drag field_user from the right pane onto the SalesRepData publication in the left pane. In the Create Subscription window, enter rep1 in the With Value box. This value represents the rep_key value for field_user in the SalesRep table.

You have now set up the consolidated database.

No data will be exchanged until you start the database extraction utility.

Setting up the remote database This section of the tutorial describes how to create and configure the remote database to send and receive messages and participate in a SQL Remote setup.

Here’s what happens when you extract (create) the remote database:

• Creates a publisher (in this case, the field_user user ID) to identify the source of outgoing messages.

• Creates the hq_user as a user with consolidated permissions.

• Creates the SalesRepData publication and a subscription for the hq_user user ID.

• Synchronizes the remote database with the consolidated database socurrent copy of the data is available.

The database extraction utility performs these steps to create a remote datcomplete with subscriptions and required user IDs.

254


d

You need to extract a database from the consolidated database for remote user field_user:

1 Click the Remote Users folder, which is in the SQL Remote folder.

2 Right-click field_user, and select Extract Database from the pop-up menu.

3 In the Extraction wizard, enter the user ID and password that you used to create the tables and users in the database.

4 On the next page, select Start Subscriptions Automatically. Also, check Create New Remote Database. Adaptive Server Anywhere must be installed for Create New Remote Database to be available.

5 Create the database as file c:\tutorial\field.db and specify a transaction log in the same directory.

6 Extract all parts of the schema (the default). Leave the other options at their default settings, and create the remote database.

You should connect to the field database as DBA and confirm that all the database objects are created:

1 From Sybase Central, choose Tools | Connect | Sybase Adaptive Server Anywhere.

2 Enter DBA as the user and SQL as the password. Use upper case, as the database was created as case sensitive. Select field.db, and Connect.

3 Open the database container, and confirm that the tables and user names are present.

In a real-life SQL Remote setup, you would load the remote database field onto the computer using it, together with an Adaptive Server Anywhere engine and any required client applications. For the tutorial, we leave the database where it is and use isql to input and replicate data.

The system is now ready for replication.

Replicating dataIn this section of the tutorial, we’ll replicate data from the consolidated database to the remote database, and from the remote to the consolidatedatabase.

255


Enter data at the consolidated database

To enter data at the Adaptive Server Enterprise database:

1 Use isql to connect to the Enterprise server:

isql -S server-name -U sa -P sysadmin

2 Verify that you are using the hq database, and enter a series of rows:

use hqgoinsert into SalesRep (rep_key, name)values (’rep1’, ’Field User’)goinsert into SalesRep (rep_key, name)values (’rep2’, ’Another User’)goinsert into Customer (cust_key, name, rep_key)values (’cust1’, ’Ocean Sports’, ’rep1’)goinsert into Customer (cust_key, name, rep_key)values (’cust2’, ’Sports Plus’, ’rep2’)gocommitgo

These commands assign the customer Ocean Sports to the sales rep Field User, and Sports Plus to Another User. You must commit the changes, as SQL Remote replicates only committed changes.

Next, you send the relevant rows to the remote Adaptive Server Anywhere database.

Send data from the consolidated database

The Message Agent, which, for the tutorial, is called SSremote, populates the remote database with the rows you added in the previous section. To send the rows to the remote database, you must run the Message Agent at the consolidated database.

❖ To replicate the data from Adaptive Server Enterprise:

1 Enter the following statement (on a single line) at the command line to run the Message Agent against the consolidated database:

ssremote -c "eng=server-name;dbn=hq;uid=sa;pwd=sysadmin"

256


2 Click Shutdown on the Message Agent window to stop the Message Agent when the messages have been sent.

Receive data at the remote database

The Message Agent first receives a message from hq, and then sends a message. This return message contains confirmation of successful receipt of the replication update; such confirmations are part of the SQL Remote message tracking system that ensures message delivery even in the event of message system errors.

To receive the insert statement at the remote database, you must run the Message Agent, dbremote, at the remote database:

1 With the database engine running, enter:

dbremote -c "eng=field;dbn=field;uid=DBA;pwd=SQL"

2 Click Shutdown on the Message Agent window to stop the Message Agent when the messages have been processed.

The Message Agent window displays status information while running. In a production setup, you will probably send this information to a log file for record keeping.

To verify that the data has arrived at the remote database, connect to the remote field database and inspect the SalesRep and Customer tables, to see which rows have been received:

1 Connect to the field database using isql.

2 Inspect the SalesRep table by typing:

SELECT * FROM SalesRep

You see that the SalesRep table contains both rows entered at the consolidated database. This is because the SalesRepData publication included all the data from the SalesRep table.

3 Inspect the Customer table by typing:

SELECT * FROM Customer

You see that the Customer table contains only one row (Ocean Sports) entered at the consolidated database. This is because the SalesRepData publication included only those customers assigned to the subscribed sales rep.

257


Create a template in your remote Web site that queries the data

In this section, we create a template that performs a query from the Adaptive Server Anywhere remote database. This template queries data that has been replicated from the consolidated database to the Adaptive Server Anywhere remote database.

1 From Sybase Central, create a ODBC Data Source name to connect to field.db.

2 Create a connection profile for field.db.

3 Connect to field.db.

4 In the left pane of Sybase Central, open the Site folder.


6 On the first page of the wizard, enter a name for the template, for example, RepProducts. Do not use spaces. Click Next.

7 Enter an optional description for the template and click Next again.

8 Use the default connection.

9 On the Add SQL Query page, click Select and enter a query to display the cust_key, name, and rep_key columns.

10 Select one of the supplied formats from the list.

11 Click Finish.

You can view the output by right-clicking on the template and selecting Browse Output.

Creating a Template Wizard - tab editorIf the user-defined tables were created from the consolidated database with a user name of DBO, the tab editor needs to be set to display system tables. Adaptive Server Anywhere considers all tables created under DBO as system tables. They will not be visible to the tab editor if table type is set to table.

Replicate from the remote database to the consolidated database

You should now try entering data at the remote database and sending it to the consolidated database:

1 Use isql to connect to the field database.

2 Insert a row at the remote database. For example:

258


INSERT INTO Customer (cust_key, name, rep_key) VALUES (’cust3’, ’North Land Trading’, ’rep1’)

3 Commit the row:

COMMIT;

4 With the field.db database running, run dbremote to send this message to the consolidated database.

dbremote -c "eng=field;dbn=field;uid=DBA;pwd=SQL"

5 Run ssremote to receive the message at the consolidated database:

ssremote -c "eng=server-name;dbn=hq;uid=sa;pwd=sysadmin"

6 From Sybase Central, connect to the Web site in the consolidated database and browse the RepProducts template, which has three rows:

In this example, there is no protection against duplicate entries of primary key values, however SQL Remote does provide for such protection. For information, see the Data Replication with SQL Remote manual.

cust_key name rep_key

cust1 Ocean Sports rep1

cust2 Sports Plus rep2

cust3 North Land Trading rep1

259


260

C H A P T E R 1 2 Calling Jaguar Component Methods from PowerDynamo

About this chapter Jaguar CTS makes it possible for multiple clients, whether Java, PowerBuilder, Visual Basic or PowerDynamo, to execute methods from a Jaguar component. Jaguar eliminates the need to write application logic toward specific platforms or a specific client. Jaguar allows methods to be created once, installed on a Jaguar server, and accessed from multiple clients from a variety of platforms.

This chapter looks at how you can use PowerDynamo and Jaguar together to serve up applications that require dynamic Web pages as well and access components (Java/JavaBeans, CORBA C++, ActiveX, and C) that run in Jaguar.

Contents Topic Page

How do Jaguar and PowerDynamo work together? 262

What does Jaguar bring to PowerDynamo applications? 264

Setting up PowerDynamo as a client 266

Calling Jaguar components from a PowerDynamo script 271

Working with ADO record sets as PowerDynamo query objects 284

Working with Tabular Results 286

261

How do Jaguar and PowerDynamo work together?

How do Jaguar and PowerDynamo work together?Dynamo is an application server that dynamically generates HTML pages which are in turn delivered to Web browsers through an HTTP protocol.

Jaguar, on the other hand, is a component transaction server that can serve up components to any client that makes MASP, Java, CORBA C++, ActiveX or C method calls. Jaguar components contain business logic that is completely independent of the client or clients accessing the component. In addition, you can configure Jaguar to host your Dynamo Web pages, making them accessible from a Web browser. See the Jaguar CTS System Administration Guide for information about hosting Dynamo Web pages.

The combination of PowerDynamo and Jaguar CTS allows you to create pure HTML applications that dynamically make use of business logic from Jaguar CTS components.

Figure 12-1 demonstrates a scenario in which a Dynamo client connects to Jaguar to process a Dynamo script that contains a Method as a Stored Procedure (MASP) call to a Jaguar component.

Figure 12-1: Dynamo client calling Jaguar component

262

CHAPTER 12 Calling Jaguar Component Methods from PowerDynamo

gh the

e)

hine

cript ll to

h l be

These steps correspond to the numbers in the diagram:

1 A browser requests a Web page, which is a PowerDynamo script that contains HTML, SQL queries, and a MASP call to a Jaguar component.

2 The Web server passes the request to Dynamo.

3 The script is retrieved from the Web site (not shown in graphic). The HTML in the Dynamo script and the SQL query begin to be processed.

4 An ODBC or Open Client connection is made to a database to retrieve the necessary information for the SQL query.

5 The data is returned to PowerDynamo. Processing continues until the Jaguar component call is encountered.

6 Because a MASP call is being made, an ODBC or Open Client connection is made to Jaguar CTS to access the Jaguar component and called method.

7 The component method is executed. If the method requires database access, a connection is made to a database to retrieve the appropriate data.

8 The data is returned to Jaguar CTS through an ODBC, Open Client, or JDBC connection.

9 The results from the Jaguar function are returned to PowerDynamo through an ODBC or Open Client connection.

10 PowerDynamo passes the results, in HTML format, back to the Web server.

11 The results are passed back to the client through an HTTP connection.

Notes • Jaguar and Dynamo can access several different databases even thoudiagram displays only one database.

• Jaguar components can access data from many different (non-Sybastypes of databases.

• The client, PowerDynamo, and Jaguar can either all reside on one macor on separate machines.

A Web author may embed calls to Jaguar components within a Dynamo sor template. The Dynamo script executes in the regular manner until the cathe Jaguar component is encountered. At this point, a connection (througPowerDynamo) is made to the Jaguar server, the appropriate method wilexecuted and the results are returned to PowerDynamo. PowerDynamo processes the information and returns pure HTML.

263

What does Jaguar bring to PowerDynamo applications?

:

any

ve s on

What does Jaguar bring to PowerDynamo applications?

Jaguar is a platform-independent component transaction server that allows you to develop component-based applications that can be accessed by thousands of clients simultaneously. Jaguar brings flexibility to PowerDynamo scripts by allowing you to create a component, deploy it to the Jaguar server, and share it among remote sites using PowerDynamo scripts that call the Jaguar component.

PowerDynamo also brings flexibility to Jaguar by providing a means for accessing Jaguar components and their business logic through an ultra-thin intranet or Internet client.

The benefits of using Jaguar CTS components with PowerDynamoJaguar components can be:

• Java/Enterprise JavaBeans

• CORBA C++

• ActiveX (nonvisual)

• C

• PowerBuilder NVO

You can call these components from within a Dynamo script as stored procedures or as ActiveX or Java objects. The type of component being accessed is irrelevant to the client.

The main benefits to using Jaguar components in Dynamo scripts include

• Business logic stored in one Jaguar component becomes available to mpresentation-independent clients.

• Jaguar makes powerful native code components such as C and C++ available for execution by Dynamo scripts that would otherwise not haaccess to methods written in those languages. There are few limitationthe languages Dynamo scripts can use.

264


s to a tting ing a

eous

re

next

r

P

ile

eX nent s it , is

• Components can be updated in one location. Without Jaguar, changecomponent or a stored procedure would be required at each client. Seup Dynamo to access Jaguar components can be as simple as creatconnection to the Jaguar CTS server or installing the ActiveX proxy server.

The way that Jaguar components are accessible by Dynamo is advantagbecause there are no restrictions on how Dynamo can manipulate the component results. The component results, in the form of HTML pages, awholly controlled by Dynamo.

A brief summary on setting up clients to access Jaguar CTS is given in thesection. For detailed information on setting up clients that require Jaguar access, see the Jaguar CTS Programmer’s Guide.

MASP method calls versus ActiveX or Java objectsThere are a few benefits to using ActiveX or Java objects against a Jaguacomponent instead of MASP method calls:

• ActiveX or Java objects exist until they go out of scope, whereas MAScalls create an instance of the component, execute it, and destroy it immediately.

• ActiveX or Java objects can give any type of return. MASP calls, fromPowerDynamo, can return only a result set.

• ActiveX or Java objects are treated like normal DynaScript objects, whMASP calls (except the connection.CreateComponent method) require that you enter a full string each time you make a call.

If a script requires repeated use of a Jaguar component, creating an Activobject or Java stub is the preferred method of working with a Jaguar compoand its methods. ActiveX, however, is a Microsoft technology, which meanis only available on Microsoft operating systems. Java, on the other handplatform-independent, which means that Java objects can run anywhere.

265

Setting up PowerDynamo as a client

ugh

Java.

w to

t

n

xy s on

Setting up PowerDynamo as a clientFor PowerDynamo to access Jaguar as a client, the machine on which PowerDynamo is installed must be set up properly. This setup depends on the type of calls that the Dynamo client will be making to Jaguar:

• If the Dynamo client will be performing ActiveX calls to Jaguar, followthe steps in “Setting up PowerDynamo to use Jaguar components throActiveX” on page 266.

• If the Dynamo client will be performing Java calls to Jaguar, follow thesteps in Setting up PowerDynamo to use Jaguar components through

• If the Dynamo client will be performing only MASP calls to Jaguar, follothe steps for setting up the Dynamo client in “Setting up PowerDynamouse MASP” on page 267.

Jaguar client softwareTo call Jaguar components from PowerDynamo, you must install the cliensoftware (select Runtime), when installing Jaguar.

Setting up PowerDynamo to use Jaguar components through ActiveX

To access a Jaguar component with ActiveX objects:

1 Install Jaguar Manager on the Dynamo machine.

2 Install the ActiveX Proxy Automation Server using the Client InstallatioProgram (JagClient.exe) on the Dynamo machine.

3 From Jaguar Manager, connect to the Jaguar server that contains therequired components.

4 Generate TLB/REG files for the package. This generates ActiveX proobjects that you can then use to create instances and invoke methodremote Jaguar components.

5 Register the package.

You are now ready to run the Dynamo application.

For detailed information on setting up an ActiveX client, see the Jaguar Programmer’s Guide.

266


e

guar .

only

r from

Setting up PowerDynamo to use Jaguar components through JavaTo create Java objects to access a Jaguar component:

1 Install Jaguar Manager on the Dynamo machine.

2 From Jaguar Manager, generate stubs for the desired package using these options:

• generate stubs

• Java stubs

• JDK 1.1

3 Ensure that the Java Code Base path is in your class path.

4 Compile the generated Java files as instructed in the Jaguar Programmer’s Guide.

5 Configure Dynamo for Java support. See “Configuring Dynamo to usJava” on page 156.

6 Set your default Jaguar settings. For information about the default Jasettings, see “Changing Dynamo configuration settings” on page 106

Setting up PowerDynamo to use MASPTo set up Dynamo as a client machine to use MASP method calls you needto create a connection to the Jaguar server.

For detailed information on accessing Jaguar MASP methods, see the Jaguar Programmer’s Guide.

There are two types of connections that may be created to access JaguaPowerDynamo.

• Sybase System 11 ODBC data source connection

• Open Client connection

267


a

d of

uar this

ActiveX and Java object callsIf you are creating instances of either ActiveX or Java objects within a script and no MASP method calls are involved, a connection to the Jaguar server as described here is not required. For ActiveX objects, a connection is made through the ActiveX proxy server that you install on your machine as explained in “Setting up PowerDynamo as a client” on page 266. For Java objects, connection is made through the Object Request Broker (ORB). See the Jaguar Programmer’s Guide for more information on ORBs.

Using an ODBC data source to connect to JaguarTo create an ODBC data source connection:

1 Register Jaguar in the Dynamo machine's sql.ini file.

2 Create an ODBC data source.

3 Create a permanent user connection to Jaguar. If you do not require connection pooling you can create a temporary user connection insteaa permanent user connection.

❖ To register Jaguar in the Sybase\sql.ini file:

1 On the machine running Jaguar, open <Jaguar CTS>\ini\sql.ini.

2 From the Jaguar machine, copy <Jaguar CTS>\ini\sql.ini file to the Dynamo machine; for example, Sybase\ini\sql.ini.

The file should look something like this. If you have configured the JagTDS listener to something other than localhost, replace localhost with value.

[Jaguar]master=NLWNSCK,localhost,7878query=NLWNSCK,localhost,7878http=NLWNSCK,localhost,8080iiop=NLWNSCK,localhost,9000

❖ To create an ODBC data source for Jaguar:

1 Start the ODBC Administrator.

2 Click Add.

3 Select the Sybase System 11 driver and click Finish.

268


4 On the General tab, enter an ODBC data source name (for example, Jaguar_dsn), and a Server name (for example, Jaguar).

5 Click OK to create the data source.

❖ To create a permanent user connection to Jaguar:

1 Start the Jaguar server.

2 Use Sybase Central to connect to the Dynamo Web site that contains the scripts requiring a connection to Jaguar.

3 Open the Connection folder.

4 Click Add Connection.

5 Give the connection a name. Click Next.

6 Enter a description for the connection. Click Next.

7 Select ODBC as the connection type. Click Next.

8 Select the data source for the connection, which is the name of the ODBC data source that you created in the previous procedure. Click Next.

9 Enter a user ID for this connection. The Jaguar samples use jagadmin as the user ID. Click Next.

10 Enter a password for this connection. The Jaguar samples use a blank password. Click Next.

11 Click Finish.

Your permanent user connection should now be visible from the connection folder in Sybase Central. To use this connection for scripts that require a Jaguar connection, right-click on the script, select Properties, and choose the new connection. You can also do this at the folder level. If you set the connection to at the folder level any scripts within that folder with a connection type set to <inherited> will use the Jaguar connection as their default connection.

You can also access the Jaguar connection using the DynaScript method site.GetConnection or the Dynamo SQL tag and attributes.

Using an Open Client connection to connect to JaguarIf an Open Client connection is required, you must:

1 Register Jaguar in the sql.ini file.

2 Create a permanent user connection to Jaguar.

269


❖ To register Jaguar in the Sybase\sql.ini file:

1 Open the sql.ini file that resides in <Jaguar CTS>\ini\.

2 Copy the contents of the sql.ini file to the sql.ini file on the Dynamo machine. For example, Sybase\ini\sql.ini.

The content being copied should look something like the following. If the Jaguar TDS listener has been configured to something other than localhost, for example the machine name, replace localhost with this value.

[Jaguar]query=NLWNSCK,localhost,7878

❖ To create a permanent user connection to Jaguar:

1 Start the Jaguar server.

2 Use Sybase Central to connect to the Dynamo Web site containing the scripts that require a connection to Jaguar.

3 Open the Connection folder.

4 Click Add Connection.

5 Give the connection a name. Click Next.

6 Enter a description for the connection. Click Next.

7 Select Open Client as the type of connection you want to create. Click Next.

8 Enter the Jaguar Server name. Click Next.

9 Leave the database name blank. Click Next.

10 Enter a user ID for the connection. The Jaguar sample uses jagadmin as a user ID. Click Next.

11 Enter a password for this connection. The Jaguar samples use a blank password. Click Finish.

Your permanent user connection should now be visible from the connection folder. To use this connection for scripts that require a Jaguar connection, right-click on the script, select Properties and choose the new connection. You can also do this at the folder level. Any scripts in the folder you select that have a connection type of <inherited> will use the Jaguar connection as their default connection.

You can also access the Jaguar connection using the DynaScript method site.GetConnection or the Dynamo SQL tag and attributes.

270


face

no

e

). e

you r.

en QL

Calling Jaguar components from a PowerDynamo script

You can call Jaguar components from within a PowerDynamo script by using:

• The Dynamo SQL tag (must return a result set)

• The Dynamo COMPONENT tag (may return a result set)

• The connection.CreateQuery method (must return a result set)

• The connection.CreateComponent method (must return a result set)

• The java.CreateComponent method (no restriction on the return)

• The java.GetUserTransaction method (allows access to the UserTransaction object of Jaguar components participating in a transaction)

• The java.GetHomeInterface method (allows access to EJB home interof Jaguar components)

• An ActiveX object through the PowerDynamo CreateObject method (restriction on the return)

The SQL tag, COMPONENT tag, connection.CreateQuery method and thconnection.CreateComponent methods allow Dynamo to call Jaguar components as though they were Methods As Stored Procedures (MASPEach MASP invocation creates an instance of the component, invokes thmethod and then destroys the component instance.

Jaguar client softwareIf you will be calling Jaguar components from PowerDynamo, ensure that have installed the client software (select Runtime), when installing Jagua

For more information on MASP, see the Jaguar Programmer’s Guide.

The Dynamo SQL tag (MASP)Description You can use the PowerDynamo SQL tag to make Methods As Stored

Procedures (MASP) calls. You can use the normal SQL tag attributes whcalling a MASP with the SQL tag. For a list of these attributes, see “The Stag” in PowerDynamo Reference.

Syntax 

Example The following example makes a MASP method call to the SVUEnrollment component, which resides in the SVU package. The method being called is getMajors. No parameters are being passed in.



The SVUEnrollment component contains several methods, one of which is getMajors. These methods can all be called as MASP methods by the SQL tag. The only restriction on calling a MASP with the SQL tag is that the return must be a result set. If the component method contains inout or output parameters, the output of these parameters will not be available.

The MASP being called in the following example requires that parameters be passed in order for the method to execute. In this case, a first and last name are required as well as a phone number.



These examples assume that the connection for the script has been set to the Jaguar server.

For more information on the SQL tag, see “The SQL tag” in PowerDynamo Reference.

The Dynamo COMPONENT tagDescription Using the Dynamo COMPONENT tag is similar to the way in which the SQ

tag is used to call Jaguar components except that the package, componenmethod are clearly labeled. The attributes normally associated with the Stag can also be used with the COMPONENT tag. For a list of these attribusee “The COMPONENT tag” in PowerDynamo Reference.

Although you can use the COMPONENT tag for ActiveX and Java accessinstance of that component exists only until the end of the COMPONENT

272


g”

COMPONENT name for the returned valueThe default name of the returned value when using the COMPONENT tag is COMPONENT, in the same way that the default name of the query object is SQL when using the SQL tag.

Syntax For SQL access (MASP):



For ActiveX access (no restriction on the return):



For Java access (no restriction on the return):



Example Here is an example of a MASP being called from within a Dynamo script using the Dynamo COMPONENT tag. You can use the FORMATTING tags to move through the result set:



For more information on the COMPONENT tag, see “The COMPONENT tain PowerDynamo Reference.

273


s that

The connection.CreateQuery method (MASP)Description The connection.CreateQuery method executes a MASP and returns a

query object that you can use to move through the result set. This is a method of the DynaScript scripting language.

Syntax 

Example The following example uses the connection.CreateQuery method to call a Jaguar MASP:



This example uses connection.CreateQuery to call a MASP that adds new users to a phone list:



For more information, see “CreateQuery method” in PowerDynamo Reference.

The connection.CreateComponent method (MASP)Description The connection.CreateComponent method executes a MASP and return

a component object. You can then call methods of the component object will return a query object.

Syntax 

274


an call its

Example This example uses the connection.CreateComponent method to create an instance of the SVUEnrollment Jaguar component and to then call the getMajors method of that component:



The following example uses connection.CreateComponent to call a MASP that adds a new user to the phone list:



For more information, see “CreateComponent method” in PowerDynamo Reference.

The java.CreateComponent methodDescription You can use the PowerDynamo java.CreateComponent method to create

instance of a Java object. Once you have created a Java object, you can methods in the same manner as a normal DynaScript object.

Syntax 

Example The following example creates an instance of the SVU/SVUEnrollment component called comp. Once the object is created, its method getMajors is called and the Record Set is displayed:

</HTML>

For more information, see “CreateComponent method” in PowerDynamo Reference.

This example creates an instance of the SVU/SVUEnrollment componentcalled comp from a machine called testMachine. Once the object is createdmethod getMajors is called and the Record Set is displayed:



For information on tabular results see, “Working with Tabular Results” on pa286.

276


ing

as

ger.

e w

d

rves

ou

en d

a

GetHomeInterface methodDescription Allows access to the EJBHome interface for a Jaguar component.

Syntax java.GetHomeInterface(component_name [, provider_url, user_id, password] )

The parameters are:

•component_name The name of the component to instantiate. Component names are composed as follows:[<server-context>]<package>/<comp>

• server-context – The root naming context for the server where the component is installed. server-context is optional and necessary onlyif a root naming context has been set for the server. The root namcontext can also be given as the initial context in the provider_url.

• package – The Jaguar package to which the component belongs, displayed in Jaguar Manager.

• component – The component name, as displayed in Jaguar Mana

You can view and edit this setting using the Naming Service tab of thServer Properties window from Jaguar Manager. The default for a neserver is “/”. If you specified an initial name context in GetHomeInterface()'s provider_url parameter, then the server context isassumed to be relative to this initial name context. For example, if theprovider_url parameter is set to iiop://localhost:9000/USA/Sybase, anyour server's root context is USA/Sybase/Engineering, then you can resolve component names as Engineering/package/component.

•provider_url The provider_url is optional and defaults to “iiop://localhost:9000”. If used, it identifies the URL of the JNDI nameserver. This parameter should be of the form iiop://<hostname>[:<iiop-port>][/<initial-context>] where:

• hostname Is the host machine name for the Jaguar server that seas the name server for your application.

• iiop-port Is the IIOP port number for the server.

• initial-context Is the optional initial naming context, which can be used to set a default prefix for name resolution. For example, if yspecify USA/Sybase/, then the component_name parameter is assumed to be relative to this location in the name hierarchy. Whspecifying the initial context, the trailing slash is optional; it is addeautomatically if you do not specify an initial context that ends withslash.

277


•user_id The user name for the Jaguar session. If authorization is enabled for your Jaguar server, this parameter is used to authorize access to Jaguar components.

The user_id parameter is optional and defaults to “guest”.

•password The password for the Jaguar session. If authorization is enabled for your Jaguar server, the password is used to authorize access to Jaguar components.

The password parameter is optional and default is no password.

Note The Dynamo methods GetHomeInterface and GetUserTransaction enable access to EJB interfaces of Jaguar components.

To access EJB interfaces of Jaguar components, Dynamo requires a Jaguar client zip file, jagclient.zip, from a Jaguar CTS installation version 3.5 or above. Refer to PowerDynamo installation instructions for your platform and ensure that this file is included in your JAGUARCLASSES (Solaris) or CLASSPATH (NT) variable.

Example Use java.GetHomeInterface to create an instance of the EJBHome interface for the component Test/Cart. Then use the Home interface to create an actual instance of Test/Cart.

carthomeObj = java.GetHomeInterface("CartPackage/Cart")

cartObj = carthomeObj.create("John", "7506");

cartObj.addItem(66)

cartObj.addItem(22)

cartObj.purchase()

carthomeObj.remove(...)

See also The PowerDynamo Reference Manual.

GetUserTransaction methodDescription Allows access to the EJB UserTransaction object.

Syntax java.GetUserTransaction( [ <provider_url>, <user_id>, <password>] )

The parameters are:

278


rves

ou are en d

a

is

•provider_url The provider_url is optional and defaults to “iiop://localhost:9000”. It identifies the URL of the JNDI name server. This parameter should be of the form iiop://<hostname>[:<iiop-port>][/<initial-context>] where:

• hostname Is the host machine name for the Jaguar server that seas the name server for your application.

• iiop-port Is the IIOP port number for the server.

• initial-context Is the optional initial naming context, which can be used to set a default prefix for name resolution. For example, if yspecify USA/Sybase/, all names that you resolve with the contextassumed to be relative to this location in the name hierarchy. Whspecifying the initial context, the trailing slash is optional; it is addeautomatically if you do not specify an initial context that ends withslash.

•user_id The user name for the Jaguar session. If authorization is enabled for your Jaguar server this optional parameter, which defaults to “guest”,used to authorize access to Jaguar components.

•password The password for the Jaguar session. If authorization is enabled for your Jaguar server, this optional parameter, which defaults to no password, is used to authorize access to Jaguar components.

Note The Dynamo methods GetHomeInterface and GetUserTransaction enable access to EJB interfaces of Jaguar components.

To access EJB interfaces of Jaguar components, Dynamo requires a Jaguar client zip file, jagclient.zip, from a Jaguar CTS installation version 3.5 or above. Refer to PowerDynamo installation instructions for your platform and ensure that this file is included in your JAGUARCLASSES (Solaris) or CLASSPATH (NT) variable.

Comments The components that participate in the transaction managed with the UserTransaction object must be in the same server as the UserTransaction object, which cannot be assumed if a Jaguar cluster is used to ensure that this requirement is met:

1 Use the same name server to create the UserTransaction object that was used when creating the component instances. That is, supply the same provider_url to GetUserTransaction() and GetHomeInterface(), CreateComponent(). The initial-context values of the URLs can differ.

279


2 Get the UserTransaction object and begin the transaction before creating any component instances.

3 In addition, follow the same restrictions as other Java clients when using the UserTransaction object. Refer to the Jaguar CTS Programmer’s Guide and Jaguar CTS Reference Manual for details.

The UserTransaction interface defines exceptions that are thrown when errors occur. For example, TransactionRolledbackException is thrown when commit() is called after setRollbackOnly() has already been called for a transaction.

As many of the methods in the UserTransaction interface for example, return void, begin(), commit(), rollback(), these exceptions are the only way to detect errors.

In DynaScript, exceptions are passed to the user through the site.GetErrorInfo() method. That is, the exception is converted to an error string. For example:

ut.begin()...ut.commit()errMsg = site.GetErrorInfo();if ((errMsg != null) && (errMsg != "")){

/* the transaction was not committed */}

The UserTransaction.getStatus() method returns an integer value indicating the status of the current transaction. Dynamo users can include the script ~/system/utils/usertran.ssc to get the definitions of variables that map to the integer values returned by getStatus().

import "~/system/utils/usertran.ssc"...

ut = java.GetUserTransaction(...);ut.begin()status = ut.getStatus();if (status != UserTran.STATUS_ACTIVE){

/* the transaction was not started */

}

...

280


Example Use java.GetUserTransaction to get the UserTransaction object, instantiate the components that will participate in the transaction, begin the transaction, perform the operations required in the transaction, and commit the transaction.

ut = java.GetUserTransaction("iiop://my-host:9000")acctHome = java.GetHomeInterface("Bank/Account", "iiop://my-host:9000")acct1 = acctHome.create("John", "Doe", "111-11-1111")acct2 = acctHome.create("Jane", "Doe", "222-22-2222")acct3 = = java.CreateComponent("Bank/Account", "iiop://my-host:9000")ut.begin();errMsg = site.GetErrorInfo();if ((errMsg != null) && (errMsg != "")){

/* handle error, the transaction did not begin return}acct1.withdraw(100);acct2.deposit(50);acct3.deposit(50);ut.commit();errMsg = site.GetErrorInfo();if ((errMsg != null) && (errMsg != "")){

/* handle error, the transaction did not commit return}

See also The PowerDynamo Reference Manual.

The PowerDynamo CreateObject methodDescription You can use the PowerDynamo CreateObject method to create an instance of

an ActiveX object. Once an ActiveX object has been created, its methods may be called in the same manner as a normal DynaScript object. An ActiveX object exists until it goes out of scope or until the ActiveX variable is assigned a new value.

Syntax 

The Host, UserName, and Password are all optional properties, depending on the scenario in which you are creating your instance of an ActiveX object.

•Host By default, host is set to localhost:9000. If the Jaguar server is running on a different machine or the port number is a value other than 9000, you must set this property accordingly.

•UserName and Password The user name and password are optional properties unless you are working with components that have had component level security specified using Roles.

•Name The name property is optional if the package name is the same as the module name and the component name is the same as the interface name.

For more information on working with ActiveX and Jaguar, see the Jaguar Programmer’s Guide.

Example This example creates an instance of an ActiveX object called comp. Once the object is created, its method getMajors is called and the Record Set is displayed:



This example creates an instance of an ActiveX object called comp that resides on a machine called testMachine. Once the Object is created, its method getMajors is called and the Record Set is displayed:

282


ns”

s



For more information about the CreateObject method, see “Built-in functioin PowerDynamo Reference.

For information on ADO record sets see “Working with ADO record sets aPowerDynamo query objects” on page 284.

283

Working with ADO record sets as PowerDynamo query objects

Working with ADO record sets as PowerDynamo query objects

When a Dynamo script calls a Jaguar component through ActiveX and that component returns a result set, an ADO record set is returned. ADO record sets have different properties and methods than the Dynamo query object. Dynamo includes a script called adoqry.ssc that is installed in the system/utils folder of the Dynamo Web site. This script implements a class called ADOQuery which takes as a parameter an ADO record set object sent by Jaguar, and returns a class that has methods mimicking those of a Dynamo query object.

Scripts that call a Jaguar component through ActiveX and do not make use of the ADOQuery class look something like this:

comp = CreateObject( "SVU.SVUEnrollment" );comp.Initialize();// returns ADO RecordSet-like objectquery = comp.getMajors();query.MoveFirst();columns = query.Fields.Count;document.writeln( "There are " + columns + " columns" );while( !query.EOF ) { fields = query.Fields; for( j = 0; j < columns; j++ ) { field = fields.Item(j); value = field.Value; document.writeln( value ); } query.MoveNext();}

With the ADOQuery class, you could instead do this:

import ~/system/utils/adoqry.ssc;

comp = CreateObject( "SVU.SVUEnrollment" );comp.Initialize();// returns ADO RecordSet-like objectquery = comp.getMajors();// wrap up the ADO RecordSet to mimic a Dynamo query // objectdynQuery = new ADOQuery( query );columns = dynQuery.GetColumnCount();document.writeln( "There are " + columns + " columns" );while( dynQuery.MoveNext() ) { for( j = 1; j <= columns; j++ ) { value = dynQuery.GetValue(j);

284


document.writeln( value ); }}

285

Working with Tabular Results

Working with Tabular ResultsWhen a Dynamo script calls a Jaguar component through Java, results are returned as Tabular ResultSets. Tabular ResultSets have different properties and methods than the Dynamo query object. Dynamo includes a script called javaqry.ssc that is installed in the system/utils folder of the Dynamo web site. This script implements a class called JavaQuery which takes as a parameter a TabularResults Set object sent by Jaguar and returns a class that has methods mimicking those of a Dynamo query object.

Scripts that call a Jaguar component through Java and do not make use of the JavaQuery class look something like this:

comp = java.CreateComponent( "SVU/SVUEnrollment" );prequery = comp.getMajors();query = java.CallStaticMethod( "com.sybase.CORBA.jdbc11.SQL","getResultSet",prequery );received = query.next();metadata = query.getMetaData();columns = metadata.getColumnCount();document.writeln( "There are " + columns + " columns" );while( received ) { fields = query.Fields; for( j = 0; j < columns; j++ ) { value = query.getString( j ) document.writeln( value ); } received = query.next();}

Using the JavaQuery class, you could use:

import ~/system/utils/javaqry.ssc;

comp = java.CreateComponent( "SVU/SVUEnrollment" );// returns Tabular ResultSet objectquery = comp.getMajors();// wrap up the Tabular ResultSet to mimic a Dynamo query //objectdynQuery = new JavaQuery( query );columns = dynQuery.GetColumnCount();document.writeln( "There are " + columns + " columns" );while( dynQuery.MoveNext() ) { for( j = 0; j <= columns; j++ ) { value = dynQuery.GetValue(j); document.writeln( value );

286


}}

287

Working with Tabular Results

288

A P P E N D I X A Setting Up the Adaptive Server Anywhere Database Server as a Service

About this appendix This appendix explains how to set up PowerDynamo to run with the Adaptive Server Anywhere database server.

Adaptive Server Anywhere requiredThis chapter applies only to those users that are running PowerDynamo with an Adaptive Server Anywhere database.

Contents Topic Page

Why use the Adaptive Server Anywhere server? 290

Setting up the Adaptive Server Anywhere database server for PowerDynamo

292

289

Why use the Adaptive Server Anywhere server?

a three ase.

tive

d

wn

o log

rver

run

Why use the Adaptive Server Anywhere server?The Adaptive Server Anywhere personal server has a limit of ten connections. While this limit is appropriate for developing a Web site, it is not sufficient for a “live” site that will get any number of calls at one time. Every request frombrowser counts as one connection. For example, a Web page containing graphics and one OLE control, can generate five connections to the datab

Comparison of the personal server and the network server

For more information on running Adaptive Server Anywhere, see the AdapServer Anywhere documentation.

Check your license agreement You must confirm that you are properly licensed to use PowerDynamo anAdaptive Server Anywhere before using your Web site.

Why run the Adaptive Server Anywhere database server as a service?

There are several advantages to running the Adaptive Server Anywhere database server as a service for PowerDynamo:

• Users can log out of NT without connections being lost or losing their oconnection to the server.

• The server console is secure as users must use normal NT security tin.

• A new user logging in will already be set up with both the database seand the Web server as they both run as a service.

• Users can log in and out of NT while the database server continues toand accept connections.

Personal Database Server Network server

No network connection Network connections

Ten-connection limit Connection limit based on license

Can run as an NT service Can run as an NT service

Can be automatically started through ODBC

Cannot automatically start a remote server ODBC

Can be automatically started if set up as a service

Can be automatically started if set up as a service

Can be automatically stopped Cannot be automatically stopped

290

APPENDIX A Setting Up the Adaptive Server Anywhere Database Server as a Service

ter
• A service can be configured to start automatically when the NT compuis started, before a user logs on.
291



The following section explains the required steps for setting up an Adaptive Server Anywhere database server to run as an NT service. They are:

1 Start the Adaptive Server Anywhere server as a service

2 Set up the ODBC System DSN

3 Set up the Connection Profile

4 Connect to PowerDynamo

Start the Adaptive Server Anywhere server as a serviceConfigure the Adaptive Server Anywhere server as an NT service by opening the Services folder in the Sybase Central, then clicking Add Service in the right pane.

Follow the instructions in the wizard to define the new service.

The path you specify in the wizard should point to dbsrv50.exe for 5.5.04 or earlier versions of SQL Anywhere. For versions 6.0 or later, the path should point to dbsrv6.exe.

You must also specify the server name and the database to which PowerDynamo will be connecting.

For more information on services, see the Sybase Adaptive Server Anywhere User’s Guide.

Set up the ODBC System DSNYou must next create an ODBC System DSN, which stores information about how to connect to a data provider. By defining a System DSN rather than a User DSN, the information is accessible to any user on the local machine.


1 Start the ODBC Administrator.

2 Select the System DSN tab. The System Data Source window will open. Click Add.

292


3 In the Create New Data Source window, select the appropriate ODBC driver and click OK.

4 In the SQL Anywhere ODBC configuration window, enter the data source name, the server name, and the database name. Click OK.

Start-up options for SQL Anywhere 5.5.04 or earlier

If you are using SQL Anywhere 5.5.04 or earlier, you should set some start-up commands in the ODBC configuration window.

If you are using Adaptive Server Anywhere 6.0 or later, you do not need to set these start-up commands.

Click Options from the SQL Anywhere ODBC configuration window.

Figure A-1 illustrates how your start-up options should be set if you are using SQL Anywhere 5.5.04 or lower.

Figure A-1: Startup Options window

If you are connecting to a remote database server, specify this start command:

c:\sqlany50\win32\dbclient.exe

If you are connecting to a database server on the same machine as the Web server and DBCLIENT has been specified, the Agent should be Not Specified. This does not start the DBCLIENT application, but allows access to the database server.

Selecting Client as the Agent would cause the DBCLIENT application to start unnecessarily, causing the local connection to be made through the network which would cause a decline in performance. Select Client as the Agent only if the database server is running on a different machine than the Web server.

293


Set up the Connection ProfileTo connect to the appropriate database, create a PowerDynamo connection profile that calls the appropriate ODBC data source name.

1 In Sybase Central, select Tools -> Connection Profiles.

2 Click New.

3 Enter a connection name and select PowerDynamo as the profile type from the drop-down list. Click OK.

4 Select the appropriate ODBC data source from the drop-down list.

5 Enter your user ID and password. Click OK.

Figure A-2: Connection Profile window

Connect to PowerDynamoOnce you have completed your connection profile, you can connect to PowerDynamo.

1 In Sybase Central, select Tools -> Connection Profiles.

294


2 Select the connection profile you want to connect with and click Connect.

295


296

A P P E N D I X B Language Support

About this appendix This appendix explains the language support that Dynamo provides for double-byte and multi-byte character sets.

Contents Topic Page

Language support 298

Usage of multi-byte characters 301

297

Language support

Language supportIn many languages, each letter and number can be represented by a single-byte character set. Each character is represented by an 8 bit byte. At most, 256 characters can be represented.

For many languages such as Japanese or Taiwanese 256 characters is not sufficient. In cases such as these, a double-byte character set is necessary to represent the large number of characters that make up the language. In a few languages even double-byte character sets are not sufficient, in which case a multi-byte character set is used.

Multi-byte characters and PowerDynamo PowerDynamo supports multi-byte character sets up to 4 bytes in length.

Collation Sequence Each character set has its own collation sequence (sorting order) for characters in a character set. The collation sequence is important when doing queries and compares such as:



The collation sequence enables the database to determine if J is greater than or less than S in this example.

One language is supported per Dynamo Web ServerThe first site you connect to through a Web server sets the collation sequence for all PowerDynamo Web sites on that server. All subsequent databases being connected to must use the same collation sequence.

Adaptive Server Anywhere language supportThe collation sequence used by an Adaptive Server Anywhere database is selected when the database is created. If no collation sequence is specified, a default collation sequence is used.

The collation sequence used by the PowerDynamo scripting engine is specified in the host database. If no collation sequence was specified for the database at the time of creation, the collation sequence from the PowerDynamo language DLL is used.

298

APPENDIX B Language Support

The Japanese language DLL (dys03jpt.dll) sets the collation sequence to sjis (Japanese Shift-JIS Encoding).

The English language DLL (dys03ent.dll) sets the collation sequence to cp437, ASCII, United States.

To change the collation sequence used by PowerDynamo, create a new database and specify the appropriate collation sequence for the required language. Store the PowerDynamo Web site in the newly created database. The Web site will have the same collation sequence as that specified for the new database.

Individual collation sequence PowerDynamo and Adaptive Server Anywhere have individual collation sequences. They are not necessarily the same.

For more information about collation sequences, see the Sybase Adaptive Server Anywhere User’s Guide.

Adaptive Server Enterprise language supportThe character set used by an Adaptive Server Enterprise server is set when it is created. If no collation sequence is specified, the default collation sequence is used.

The character set used by the PowerDynamo scripting engine is determined by the character set specified in the host server. PowerDynamo reads the character set from the Enterprise server and then maps it to the appropriate PowerDynamo character set by means of the table shown here.

Adaptive Server Enterprise Dynamo

“cp437” “437”

“cp850” “850”

“cp852” “852”

“cp855” “855CYR”

“cp857” “857TRK”

“cp860” “860”

“cp866” “866RUS”

“cp869” “869ELL”

“eucb5” “EUC_TAIWAN”

“eucgb” “EUC_CHINA”

299

Language support

Dynamic file site language supportFor a dynamic file site to use a collation sequence other than the default, you must specify a character set in the registry:

1 From your system’s Registry Editor, open the following file:

HKEY_LOCAL_MACHINE\SOFTWARE\Sybase\PowerDynamo

2 Create a new string value called Character Set with a string value of the desired character set, for example “cp437”.

The following string values are valid:

“cp437”“cp850”“cp852”“cp855”“cp855”“cp860”“cp866”“cp869”“eucb5”“eyecup”“eucjis”“eucksc”“iso_1”“sjis”“utf8”

3 Restart the Web server.

“eucjis” “EUC_CHINA”

“eucksc” “EUC_KOREA”

“iso_1” “ISO_1”

“sjis” “SJIS_2”

“utf8” “UTF8”

Adaptive Server Enterprise Dynamo

300

APPENDIX B Language Support

Usage of multi-byte charactersYou can use multi-byte characters in PowerDynamo templates and scripts in these areas:

• DynaScript queries and comparisons

• DynaScript variables

• SQL queries and comparisons

• SQL variables

• HTML (depending on support from the browser being used)

301

Usage of multi-byte characters

302

Index

Aabstract classes 143access modifiers

Java 151accessing existing data 8ActiveX

in Jaguar 265using in Jaguar 266

ActiveX proxy automation server 266Adaptive Server Anywhere database server 289ADO record sets 284ADOQuery class 284agents

and mappings 101database 102file 103

answering mail 211App folder 21Application Servers

about 80, 94application servers

about 77, 79, 83, 87, 93, 94, 99, 128, 129configuring 83, 93, 99

application to launch when debugging 106arguments

scripts 139URLs 138

arraysJava 161tutorial 137

attributesusing 191XML 191

authoring toolsusing with PowerDynamo 49

Bbrowsers

viewing Dynamo documents 27, 29viewing local Dynamo documents 27

Ccache

document 223setting the size of 224size 102, 226

cache size 102cacheable documents

writing 230cachedOutputTimeOut

setting a value 225caching the generated output of a document 225CallStaticMethod method (java object) 277, 278case sensitive 106

Dynamo tags 112XML 169

catch blockJava 153

CDATA sectionsabout 194

CGIabout 6, 96configuration 94, 96helper 96helper application 41maximum number of connections 106support for 77System DSN 97system path 94

character dataXML 193

class methodsabout 149

1

Index

class path 102Java 102setting for Java 156

class statementsabout 135, 140

classesabout 143compiling 147instances 146Java 146

clbr110.dll 80, 94clients

about 128code editor

editing a template 23collation sequence 298, 299comments

HTML 131XML 199

comparisonDBENG50 and DBSRV50 290

COMPONENT (Dynamo tag)Jaguar 271, 272

components 264Jaguar 266

configurationapplication server 83, 93, 99CGI servers 94, 96connection timeout 106cookies 106default settings 106ISAPI 4.0 servers 85ISAPI servers 79Java 156mappings 100Netscape servers 88NSAPI servers 86Web servers 96

configuration settings 106Configuration Utility

starting 41configuring

about Web sites 71Jaguar 106

connecting to a Web sitesample 20

2

using the same connection type 38connection pool

about 60, 67permanent connections 60populating 61

connection profilescreating 38, 83, 92, 98, 294creating a File-based connection profile 39creating an ODBC connection profile 38creating an Open Client connection profile 39

connection timeout 106setting a value for 67

connectionsabout 60CGI 106changing 60creating 60creating for Jaguar 268creating permanent 64creating temporary 64creating through Sybase Central 62default 60definitions 60deleting through Sybase Central 62dynamic file sites 37Dynamo connections 60expensive use of 218folder 21increasing performance 60, 220inherited 60Jaguar 267limits 290local 292modifying through Sybase Central 62multi 13network 292performance 222permanent 60pool 60services 290setting defaults 106temporary 60testing 62User 60

Connections folderabout 42

Index

working with 60consolidated databases

setting up 250constructors

DOMDocument object 187Java 152

control statementstutorial 133

conventionssyntax xvii

cookiesconfiguring 106timeout 106

copying a database 69CreateComponent method

Jaguar 274, 275CreateComponent method (connection object)

Jaguar 271CreateComponent method (java object)

Jaguar 271CreateObject method

Jaguar 281CreateQuery method

Jaguar 274CreateQuery method (connection object)

Jaguar 271creating

an ODBC connection profile 38an Open Client connection profile 39DOMDocument objects 187file connection profile 39file-based Web site 36multiple Web sites 34, 36publications 252subscriptions 254templates 22user connections 62Web sites 19, 33XML documents 170, 200

Ddata sources

installing 82, 92, 97registry 105

databasesconnecting to the internet 5copying 69minimizing calls to 219remote 254software 82, 92, 97storing data 8XML and 184XML from 170, 172

datatypes for variables 133DBCLIENT 293DBENG50 290dbremote 256, 257

message agent 255DBSRV50 290debugging 106

default application to launch 106DOM 181

declarationvariables 132XML 167

declaring entities 196default

configuring 106connections 60general settings 106ISAPI settings 106PWS settings 108

deletingconnections 62

deploymentabout 76, 77application server 83, 93, 99installation 79, 80, 87, 94overview 77steps 77

designing your Web site 221desktop

locating Dynamo programs 18destructors

Java 152disk

storing documents on 32disk space

storage efficiency 56Doc folder 21

3

Index

document cachehow does it work? 223optimizing 223performance 222setting the size of 224size 102, 226

Document Object Modelabout 177

document type definitionsXML 167

documentationin HTML form 21online xvi

documentsaccessing 57, 58arguments 138copying 42creating XML 170default 108deleting 43exporting 55, 56hierarchical storage 32importing 55moving 42renaming 43storing 32storing on disk 32XML 166

DOMabout 177creating documents 200creating DOMDocument objects 187debugging 181document trees 177examples 182features 177interfaces 180node types 180nodes 179

DOMAttribute objectXML elements 191, 192

DOMDocument objectadding to 200constructor 200creating 187removing objects 201

4

replacing objects 201DOMElement object

XML elements 189, 190DOMNode object

XML 179double-byte characters set 298, 299

usage 301do-while statements

about 133DTD

XML 167, 199dycgi03.exe 94dycsrv03.exe 94dydbg03.dll 80, 94dyhtml03.dll 80, 94DYISA03.DLL 81dyisa03.dll 80dynamic content

HTML tags 23local viewing 27SQL queries 22templates 22viewing 27, 29

dynamic file sitesconnections 37creating 36language support 300

dynamic Web pages 6requirements 6

Dynamodeployment 76script language 128

Dynamo and Jaguarbenefits of 264how they work together 262

Dynamo Configuration foldermappings 100

Dynamo connections 60limiting 67

Dynamo interpreterabout 9

Dynamo tagsabout 112tutorial 113

DynaScriptabout 128

Index

implementing 129server-side 128tutorial 130

dys03ent.dll 80, 94dyscr03.dll 80, 94dyxdb03.dll 80, 94

EECMAScript

about 128editing

XML documents 200, 201editing script source 131elements

DOM 189DOMAttribute object 191, 192DOMElement object 189, 190DOMNode object and 189, 191getElementsByTagName function 190nodeType value 190XML 189

embedding instructionsabout 9supported types 9

entitiesdeclaring 196external 196, 197internal 196, 197referencing 196types of 196XML 196

error checkingJava 152using dynamo tags 118XML 181

escaping textXML 195

evaluating performance 70examples

DOM 182exceptions

Java 152executing scripts 131expensive methods and properties 234

expressionstutorial 132

extensible markup language 166external entities 196

using 197

Ffields

Java 148private 151protected 151public 151

file-based Web sites 36connections 37

filesand folders 43creating a connection profile 39exporting 55, 56importing 55storing Web pages as 43

filterISAPI 81

finally blockJava 153

flushing the cache 226folders

about 42adding 42App 21Configuration 41Connections 21, 42connections 60copying 42creating 42deleting 43Doc 21Helper Application for CGI 41linked 43, 44linking with directories 43main contents 42moving 42ODBC administrator 41Personal Web Server 41renaming 43

5

Index

Site 21, 42Utilities 41working with 41, 42

for statementsabout 133

FORMATTING (Dynamo tag) using 115formatting HTML comment tags 51FORMATTING tag

XML 172forms

processing 52forwarding mail 211function statements

about 135functions

tutorial 134

Ggateways 5getElementsByTagName method 190GetHomeInterface method 277, 278

Hhigh volume Web sites 218host variables 12HTML

comments 131content 3dynamic content 23embedded scripts 131formatting tags 51generating from scripts 129queries in 23query tags 50, 51scripts in 23Template wizard 46tutorial 130XML converted to 182

HTML documentsretrieving 8storing in a database 8

HTML editors

6

using with PowerDynamo 49HTML forms

processing 52HTML headers for functions 135HTML template

viewing output 23hyperlink 3

Iif-else statements

about 133images

storing in a database 8import statement

Java 151import statements 129INCLUDE (Dynamo tag)

using 121inheritance

tutorial 140inherited

connections 60inserting data

SQL_INSERT tag 123installation

Application Server 80, 94installing

application server 79, 87, 94sample database 17Web servers 77

instance methodsabout 149

instancescreating 136Java classes 146

instantiateddefinition 146

interfacesJava 152

internal entities 196using 197

Internationalization 298, 299interpreter

about 9

Index

components of 9ISAPI

configuration 79DLL files 80, 94filter 81ODBC System DSN 81registry entries 81support for 77system path 79

ISAPI 4.0configuration 85

ISAPI filter directorydefault 106

JJaguar

about 262accessing components 266COMPONENT tag 272components 264connecting from Dynamo 267CreateComponent method (connection object)

274CreateComponent method (java object) 275CreateObject method 281CreateQuery method 274creating ActiveX objects 265creating Java objects 265defaults 106MASP method calls 265ODBC connections 268Open Client connections 269PowerDynamo as a client 266record sets 284, 286setting a VM 106SQL tag 271

Jaguar and Dynamohow they work together 262

Jaguar componentscalling from PowerDynamo 271

Japanese support 298, 299JAR files

Java 151Java

about 129an example 158arrays 161cache size 102catch block 153classes 146classpath 102compiling classes 147configuring PowerDynamo 156constructors 152default VM 106destructors 152Dynamo 155error handling 152fields 148finally block 153in Jaguar 265interfaces 152introduction 146method overloading 162methods 148objects 147try block 153using in Jaguar 267using Jaguar 163

Java class cachesetting 156

Java VMdefault 106setting 156

JavaQuery class 286JavaScript

about 11compatible syntax 128tags 131

LLABEL (Dynamo tag)

using 117language

summary 128tutorials 130

language support 298, 299dynamic file sites 300

7

Index

laptop computersintranet access 242

limiting user connections 67link 3linked folders

about 43, 44and replication 44creating 43

load balancingacross processors 235across servers 236performance 235

local pathand mappings 101database 102file 103

localhostserver name 74URL 74

Mmacros

text replacement 52tutorial 138

maila simple application 213about 204forwarding 211getting started 204objects 204receiving 208replying 211retrieving 208sending 206SMTP host 106

mail listgenerating 208

main contents folderabout 42

mappingsdatabase 102defining 102, 103elements of 101file 103

8

registry information 105storage of 105URL 100, 101

MASPusing in Jaguar 267

MASP method callsJaguar 265

maximum number of connectionsperformance 67

maximum number of Dynamo connectionssetting default 106

maximum number of pending requestssetting default 106

maximum number of worker threadssetting default 106

Message Agent 255, 256, 257using 256

messagesreceiving 257sending 256

method overloadingJava 162

methodsabout 132, 135class 149defining 136expensive use of 234instance 149Java 148overriding 142private 151protected 151public 151static 149writing 148

MIME typesconfiguring 109

minimizing calls to the database 219minimizing processing time 218minimum number of connections

performance 67minimum number of Dynamo connections

setting default 106mobile intranet

about 241, 242capabilities 9

Index

requirements 243software 243

mthr110.dll 80, 94multi-byte character set 298, 299

usage 301multiple processors 235multiple servers 235multi-threaded

PowerDynamo 235

NNAME

HTML comment tag 51Netscape

server configuration 88Netscape JavaScript Authoring Guide 11new features xiii

documentation xvinew operators

about 135NO_SQL_ERROR (Dynamo tag)

using 119nodes

DOM 179elements 190types of 180

notationsXML 199

NSAPIconfiguration 86, 88support for 77, 88System DSN 91system path 86

Oobject-oriented programming

Java 146objects

abstract classes 143arrays 137creating 136Java 147

methods 132, 136polymorphism 143tutorial 135, 140types 147

ODBCabout 5creating a connection profile 38data source 294data sources 105

ODBC Administratorstarting from Sybase Central 41

ODBC configurationoptions 293

ODBC data sourceexecuting against 13

ODBC System DSNcreating 292

Open Clientabout 5creating a connection profile 39

Open Client data sourceexecuting against 13

optimizingdocument cache 223

outputstoring 225

overloadingmethods 162

Ppackages

Java 151parser

XML 177parsing

XML 187passing variables 135passing vriables

tutorial 138pending requests

setting default 106performance

causes of poor performance 218connection pool 60

9

Index

connection timeout 67connections 60DOM 180example 237expensive methods and properties 234factors 222load balancing 235scheduling 228

Performance Monitorabout 70statistics 70

Perlabout 129

permanent connections 60Personal Web Server

about 27, 29, 71, 72configuration 71mappings 100prefixes 100preparing to use 73providers 100requirements 73starting 41, 73URL 74uses of 72using 71, 72

plbr110.dll 80, 94polymorphism

about 143port number

configuring 108setting default 108

PowerDynamogetting started 16summary 13

PowerDynamo and Jaguarbenefits of 264

prefixesabout 100

pregenerating output 228prettyPrint method

debugging 181private

Java access 151processing instructions

XML 199

10

processing of a Web site 223processing of scripts 218profiles

and mappings 102programs

on the desktop 18properties

about 132, 135expensive use of 234

protectedJava access 151Java keyword 151

providersabout 100

publicJava access 151

publicationscreating 252Web sites 244, 245

Qqueries

about 50formatting 47, 51in HTML 50, 51naming 51pre-generation of results 57, 58selecting a data source 13XML from 170, 172

query objectXML 170, 172

query tags 7

Rreceiving messages 257record sets

Jaguar 284, 286referencing entities 196regenerating

Web sites 40registry

data sources in 105

Index

Dynamo mappings 105mappings 105

remote databasessetting up 254

replacingvariables 138

replicationIntranet 244intranet 241, 244, 245tutorial 246Web site 244, 245

ResultsToXMLString methodquery object 170, 172

return statementsabout 135

Ssample database

creating a Web site 19installing 17

schedulesabout 57, 58removing 58scheduling actions 57

schedulingperformance 222, 228

scopeJava 151

script languagearrays 137control statements 133functions 134inheritance 140objects 135passing variables 138server-side 128summary 128tags 131variables and expressions 132

scriptsabout 10, 50, 128arguments 139cacheable 230connections 60

creating 25, 130designing 218editing source 131embedded in HTML 11, 130, 131excessive processing of 218executing 131implementing 129importing 129maintaining 128scheduling 57, 58tags 131tutorials 130viewing output 25

scripts and templatesperformance 222

sending messages 256Server

database 292Services 290

advantages 290connections 290NT 105, 289starting 292

sessionscookies 106

setting upa remote database 254the consolidated database 250Web server 77

single-byte character set 298, 299Site folder

about 42SJIS 298, 299SMTP host

default 106source code for scripts 131spaces

XML 169SQL (Dynamo tag)

Jaguar 271using 113

SQL as HTML comment tags 50SQL formatting as HTML comment tags 51SQL naming statements 51SQL queries

in a template 11

11

Index

SQL Remoteand the mobile intranet 241, 242creating publications 252dbremote 255, 256, 257Message Agent 255, 256, 257setting up 248setting up a consolidated database 250setting up a remote database 254ssremote 256tutorial 246

SQL_INSERT (Dynamo tag)using 123

SQL_ON_ERROR (Dynamo tag)using 119

SQL_ON_NO_ERROR (Dynamo tag)using 119

ssremote 256starting

PowerDynamo 18Sybase Central 18

start-up options 293statements

flow control 133objects 135

static methodsabout 149

statisticsPerformance Monitor 70

storageefficiency 56of documents 32

storing output 225scheduling 228

subscriptionscreating 254to Web sites 244, 245

summaryPowerDynamo 13

Sybase Centralconnecting to a Web site 20connection profiles 38, 83, 92, 98creating a file-based Web site 36creating an Adaptive Server Anywhere Web site 33creating an Adaptive Server Enterprise Web site 35navigating a Web site 21Services 292

12

starting 18Sybase Central editor 23syntax conventions xviisyntax of script language 128System DSN

CGI 97NSAPI 91

system folderabout 42

system pathCGI 94ISAPI 79NSAPI 86

Ttabular result sets 286tags

HTML comments 50JavaScript vs DynaScript 131scripts 131

TCP/IPand the mobile intranet 243required for PowerDynamo 73

templatesabout 7, 10, 22, 46, 50adding 46adding to a Web site 22browsing 23, 49cacheable 230connections 60creating 11, 22, 46, 130editing 23, 48, 49embedding instructions 50excessive processing of 218exporting 55, 56formatting 47importing 55previewing 48repository 13scheduling 57, 58SQL queries 22viewing 48viewing output 23, 48viewing output in a browser 49

Index

viewing source 48wizard 11working with 46

templates and scriptsperformance 222

temporary connections 60testing

connections 62text

replacement 12substitution 12XML 193XML elements 194

text replacementabout 52

timeoutconnection 106cookies 106

toDOMDocument functionusing 187

toXMLString functionusing 174

tracesetting default 107

treeDOM documents 177

try blockJava 153

tutorialsarrays 137control statements 133Dynamo tags 113functions 134getting started with PowerDynamo 16object inheritance 140passing variables 138replication 246scripts 130simple objects 135variables and expressions 132writing HTML 130

typeobjects 147

typing of variables 133

UUNIX

port number 108URL

about 3, 74, 138accessing the sample Web site 28and the Personal Web Server 74case sensitive 106mapping 100prefixes 100

URL prefixand database mappings 102and file mappings 103and mappings 101

User connections 60creating 62limiting 67ltno connectiongt 68

Utilities folder 41application to launch when debugging 106connection timeout 106cookie timeout 106Dynamo defaults 106port number 108

Vvalid documents

XML 167variables

data types 133declaration 132passing 52passing by value and reference 135replacing 138tutorial 132

voidJava methods 148

WW3C standards

Document Object Model 177wcmdpa24.dll 80, 94

13

Index

Web authoring toolsusing with PowerDynamo 49

Web clientsabout 128

Web pagesdynamic 6static 6

Web server interfacesabout 5

Web serversabout 77, 128CGI 96configuring 77, 96Netscape 88supported interfaces 77

Web sitesabout 32accessing 71adding a template 22and SQL Remote 244, 245configuring 71connecting to 20, 32connection profiles 38, 83, 92, 98contents 32creating file-based 36creating for Adaptive Server Anywhere 33creating for Adaptive Server Enterprise 35deleting 40deploying 71, 76designing 221file-based 3folders 42management tools 10navigating 21one per user per database 34, 36regenerating 40replication of 244, 245sample 20, 21structure 32Sybase Central 33, 35, 36templates 22, 46viewing 27working with 32

well-formed documentsXML 167, 168

while statements

14

about 133white space

XML 169WIN CGI, support for 77wizards

scheduling 228worker threads 235

setting maximum 106writing cacheable documents 230

XXML

about 165attributes 191case sensitivity 169CDATA sections 194character data 193comments 199converting to HTML 182creating documents 170, 200databases and 170, 172definition 166document declaration 167Document Object Model (DOM) 177document type definitions 167DTD 167Dynamo features overview 166DynaScript objects and 174editing documents 200, 201elements 189, 191entities 196entity types 196error-checking 181escaping 195example 168examples 182inserting into a database 184interfaces to 180introduction 167nesting of elements 169notations 199parser 177, 187parsing 187processing instructions 199

Index

queries and 170, 172Template wizard 46text 193valid documents 167well-formed documents 167, 168white space 169

xmlEscape functionusing 195

Zzip files

Java 151

15

16