HAHTsite IDE Programming Guide - Product Documentation

HAHTsite IDE
Programming Guide

IDE
Programming
Guide
release 4.0

Notice
© Copyright 1999 HAHT Software, Inc.
All Rights Reserved
May 1999
MN07-C-00-400-00
No part of this publication may be copied, photocopied, reproduced, transmitted, transcribed, or reduced to
any electronic medium or machine-readable form without the prior written consent of HAHT Software, Inc.
Information in this document is subject to change without notice. Names and information used in examples
are fictitious.
U.S. GOVERNMENT RESTRICTED RIGHTS. It is acknowledged that the Software and the Documentation were
developed at private expense, that no part is in the public domain, and that the Software and Documentation
are Commercial Computer Software provided with RESTRICTED RIGHTS under Federal Acquisition
Regulations and agency supplements to them. Use, duplication, or disclosure by the U.S. Government is
subject to restrictions as set forth in subparagraph (c)(1)(ii) of The Rights in Technical Data and Computer
Software clause at DFAR 252.227-7013 et. seq. or subparagraph (c)(1) and (2) of the Commercial Computer
Software—96 Restricted Rights at FAR 52.227-19, as applicable. Contractor is HAHT Software, Inc., 4200 Six
Forks Road, Raleigh, NC 27609. Rights are reserved under copyright laws of the United States with respect to
unpublished portions of the Software.
Trademarks
HAHT, HAHT Software, HAHTsite, e-Scenario, and “e-nable your enterprise” are trademarks or U.S. registered
trademarks of HAHT Software, Inc.
Portions Copyright© 1992-1996 Summit Software Company.
This product includes software developed by the Apache Group for use in the Apache HTTP server project
(http://www.apache.org/).
Any other corporate names, product names, tradenames, trademarks, service marks, or service names owned
or registered by any other company and mentioned herein are the property of their respective companies.
Specifications subject to change without notice.
HAHT Software, Inc.
4200 Six Forks Road
Raleigh, NC 27609 USA
(919) 786-5100
(888) 438-4248 (in the USA)
(919) 786-5200 (Technical Support)

Contents
About This Book
Who is this book for? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xvii
Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xvii
Other HAHTsite documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xviii
Other HAHTsite products . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xix
HAHT Software’s commitment to you . . . . . . . . . . . . . . . . . . . . . . . . . . xix
1 Introduction
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
HAHTsite Server Object Model. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
The project package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3
The datamanager package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4
The form package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4
The access package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5
The corba package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5
Data-management API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
ActiveX Data Objects classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6
Relationship between ADO and SOM classes . . . . . . . . . . . . . . . . . . .6
Data management in HAHTtalk Basic projects . . . . . . . . . . . . . . . . . .7
Client-side scripting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
CORBA capabilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
Access to COM/DCOM objects. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
Remote debugging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
2 Working with Java Projects
What’s in this chapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
Adding server-side code to a Java project. . . . . . . . . . . . . . . . . . . . . . . . 12
iii

Contents
iv
HAHTsite Server Object Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . .13
External logic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .13
In-line code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .13
Invoking an expression or a method from a dialog box . . . . . . . . .15
Adding code in Server-side Code view . . . . . . . . . . . . . . . . . . . . . . .17
What’s in a Java page? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .18
Editing HahtApplication.java and HahtSession.java . . . . . . . . . . . .25
Adding Java files to a project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .26
Naming conventions for Java projects . . . . . . . . . . . . . . . . . . . . . . . . . . 30
Naming conventions for dynamic pages . . . . . . . . . . . . . . . . . . . . .30
Calling a dynamic page from Java . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
Event handling in a Java project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
Editing and compiling Java code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
Using the code editor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .37
Compiling a Java application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .38
Finding compile-time errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .39
Debugging a Java application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .39
Working with application directories . . . . . . . . . . . . . . . . . . . . . . . .39
Java options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
Changing the Java file type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .41
Overriding Java compiler options . . . . . . . . . . . . . . . . . . . . . . . . . . .42
Overriding options for JAR, CAB, and ZIP files . . . . . . . . . . . . . . . . .43
3 Working with HAHTtalk Basic Projects
What’s in this chapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
Adding server-side code to a HAHTtalk Basic project . . . . . . . . . . . . . . 46
HAHTsite Server Object Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . .47
External logic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .47
In-line code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .48
Invoking an expression or a subroutine from a dialog box . . . . . . .50
Adding code in Server-side Code view . . . . . . . . . . . . . . . . . . . . . . .52
What’s in a HAHTtalk Basic page? . . . . . . . . . . . . . . . . . . . . . . . . . .53
Adding HAHTtalk Basic files to a project . . . . . . . . . . . . . . . . . . . . .60
Naming conventions for HAHTtalk Basic projects . . . . . . . . . . . . . . . . 62
Include files and Globals.hbs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63

Contents
Project and external includes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .63
Declaring public variables with Globals.hbs . . . . . . . . . . . . . . . . . . .64
Precompiler directives . . . . . . . . . . . . . . . . .64
Calling dynamic pages from HAHTtalk Basic . . . . . . . . . . . . . . . . . . . . 65
Event handling in a HAHTtalk Basic project . . . . . . . . . . . . . . . . . . . . . 66
Editing and compiling HAHTtalk Basic code . . . . . . . . . . . . . . . . . . . . . 67
Using the code editor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .67
Compiling a HAHTtalk Basic application . . . . . . . . . . . . . . . . . . . . .69
Finding compile-time errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .69
Debugging a HAHTtalk Basic application . . . . . . . . . . . . . . . . . . . . .70
Working with application directories . . . . . . . . . . . . . . . . . . . . . . . .70
Comparing HAHTtalk Basic and Visual Basic . . . . . . . . . . . . . . . . . . . . 72
HAHTtalk Basic data types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .72
Subroutines and functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .73
File I/O . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .73
Error handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .73
Code page properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73
4 Calling Server-side Java from HAHTtalk Basic
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76
Using Java objects with HAHTtalk Basic . . . . . . . . . . . . . . . . . . . . . . . . 76
CreateJavaObject . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .77
GetJavaClass . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .78
CreateTypedJavaNull . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .78
Differences between HAHTtalk Basic and Java . . . . . . . . . . . . . . . . . . . 79
Java is strongly typed . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .79
Parameter passing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .80
Java is case sensitive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .80
Locating objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .80
Mapping HAHTtalk Basic types to Java parameter types . . . . . . . . . . . . 81
Mapping Java types to HAHTtalk Basic types . . . . . . . . . . . . . . . . . . . . 83
Troubleshooting: Java runtime errors . . . . . . . . . . . . . . . . . . . . . . . . . . 84
v

Contents
5 HAHTsite Server Object Model
vi
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89
Built-in objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .90
Getting references to the built-in objects. . . . . . . . . . . . . . . . . . . . . . . . 91
From a Java project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .91
From a HAHTtalk Basic project . . . . . . . . . . . . . . . . . . . . . . . . . . . . .96
The Application object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
Application object methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .97
Application object variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .98
Multiple processes and application-level variables . . . . . . . . . . . . . .99
Retrieving Application object properties . . . . . . . . . . . . . . . . . . . .100
Summary of Application object methods . . . . . . . . . . . . . . . . . . . .102
The Session object. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107
Session state . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .107
Session timeout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .108
Event handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .108
Creating a dynamic URL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .109
Creating a static URL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .113
Identification methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .113
Summary of Session object methods . . . . . . . . . . . . . . . . . . . . . . .114
The Request object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117
Retrieving field values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .117
Retrieving cookie values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .121
Retrieving attachments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .122
Retrieving environment variables . . . . . . . . . . . . . . . . . . . . . . . . . .122
Summary of Request object methods . . . . . . . . . . . . . . . . . . . . . . .123
The Response object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126
Writing headers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .126
Setting cookies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .127
Writing the HTML output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .129
Summary of Response object methods . . . . . . . . . . . . . . . . . . . . . .130
6 Forms-Related Programming
What’s in this chapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134
Calling a subroutine from a form. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134

Contents
Writing the subroutine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .138
Associating the subroutine with a form . . . . . . . . . . . . . . . . . . . . .139
Attaching a file to a form . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140
Adding a File Upload control to a page . . . . . . . . . . . . . . . . . . . . .141
Working with a file attachment . . . . . . . . . . . . . . . . . . . . . . . . . . .142
Custom Form Handler widgets. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145
Writing the form-handler function . . . . . . . . . . . . . . . . . . . . . . . .145
Creating the custom form-handler widget . . . . . . . . . . . . . . . . . . .152
7 Form Fields Programming
What’s in this chapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156
Setting form-field properties. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156
Examples of setting form-field properties . . . . . . . . . . . . . . . . . . . .156
Setting and getting form-field properties . . . . . . . . . . . . . . . . . . . .161
FormField properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .163
Button properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .165
Checkbox properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .167
Combo properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .168
FileUpload properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .168
ListElement and Listbox classes . . . . . . . . . . . . . . . . . . . . . . . . . . .169
Radiobutton properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .175
StaticText properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .176
TextArea properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .178
Textbox properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .178
Calculating form-field values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 180
Calling user code from a button. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183
Code associated with a button versus code associated with a form
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .183
Configuring a button to call user code . . . . . . . . . . . . . . . . . . . . . .184
8 Data-Agent Programming
Data agents and command handlers . . . . . . . . . . . . . . . . . . . . . . . . . . 188
Calling data-agent methods at runtime . . . . . . . . . . . . . . . . . . . . . . . . 190
Setting a data agent’s command . . . . . . . . . . . . . . . . . . . . . . . . . . .190
Performing a data-agent action . . . . . . . . . . . . . . . . . . . . . . . . . . . .192
Getting and setting the values of a data agent’s fields . . . . . . . . . .196
vii

Contents
viii
Getting a reference to a data agent’s connection . . . . . . . . . . . . . .198
Dealing with recordsets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .198
Getting parameters to stored procedures . . . . . . . . . . . . . . . . . . . .202
Refreshing a data agent’s data . . . . . . . . . . . . . . . . . . . . . . . . . . . . .203
Sorting records . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .204
Filtering records . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .205
Handling errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .210
Enabling tracing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .210
The structure of a command handler. . . . . . . . . . . . . . . . . . . . . . . . . . 212
Modifying a command handler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 216
Where to add code to a command handler . . . . . . . . . . . . . . . . . .216
Examples of adding code to a command handler . . . . . . . . . . . . .217
Changing the flow of control in a command handler . . . . . . . . . .225
Example of changing the flow of control . . . . . . . . . . . . . . . . . . . .227
9 Programming with the Connection Manager
The DMConnectionManager class . . . . . . . . . . . . . . . . . . . . . . . . . . . . 230
Opening a connection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 230
Opening a shared connection . . . . . . . . . . . . . . . . . . . . . . . . . . . . .231
Opening a private connection . . . . . . . . . . . . . . . . . . . . . . . . . . . .232
Closing a connection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232
Connections in HAHTtalk Basic projects . . . . . . . . . . . . . . . . . . . . . . . 233
10 Working with Client-side Scripts
Introduction to client-side scripts . . . . . . . . . . . . . . . . . . . . . . . . . . . . 236
Types of client-side scripts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 238
Choosing a scripting language . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 238
Client-side scripts and the HTML editor . . . . . . . . . . . . . . . . . . . . . . . 240
Browsing the object model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .241
Configuring the Client Scripts view . . . . . . . . . . . . . . . . . . . . . . . .242
Writing in-line scripts. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 243
Writing script functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 244
HTML tags for client-side scripts . . . . . . . . . . . . . . . . . . . . . . . . . . .246

Contents
About event handlers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 247
Scripting event handlers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .247
Browser compatibility issues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 249
The browser object model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .250
Strategies for handling browser incompatibilities . . . . . . . . . . . . .250
About Dynamic HTML . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 252
Moving objects using DTHML . . . . . . . . . . . . . . . . . . . . . . . . . . . .252
Why use Netscape Layers for positioning? . . . . . . . . . . . . . . . . . . .253
JavaScript example for browser-independent DHTML . . . . . . . . . .255
Scripts with server-side expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . 257
11 Using HtmlOut Routines or the HtmlOut Class
Creating HTML at runtime. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 260
The HAHTtalk Basic HtmlOut library. . . . . . . . . . . . . . . . . . . . . . . . . . 260
Using the HAHTtalk Basic HtmlOut library . . . . . . . . . . . . . . . . . .261
HAHTtalk Basic example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .262
The HtmlOut Java class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 264
Java example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .265
12 Access Control
What is access control?. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 270
Granting privileges: the basics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 271
Controlling access to a page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .271
Controlling access to part of a page . . . . . . . . . . . . . . . . . . . . . . . .274
Displaying a custom error page . . . . . . . . . . . . . . . . . . . . . . . . . . . .275
Granting privileges to logged-in users . . . . . . . . . . . . . . . . . . . . . . . . . 276
Authenticating users with the Login widget . . . . . . . . . . . . . . . . . .277
Authenticating users with the Authentication interface . . . . . . . .286
Letting the Web server authenticate users . . . . . . . . . . . . . . . . . . .288
Granting privileges on a user-name basis . . . . . . . . . . . . . . . . . . . . . . 289
Using a Login widget and a database privilege repository . . . . . . .290
Using a Login widget and a nondatabase privilege repository . . . .291
Using the Server Object Model . . . . . . . . . . . . . . . . . . . . . . . . . . . .293
ix

Contents
x
Server Object Model methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 296
Session class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .297
Privileges class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .298
Application class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .298
Authentication interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .299
UserProfile interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .299
13 Connecting to COM Objects
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 302
Calling DLLs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 302
Declaring a DLL in HAHTtalk Basic . . . . . . . . . . . . . . . . . . . . . . . .302
Example DLL declarations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .303
Mapping HAHTtalk Basic types to DLL data types . . . . . . . . . . . . .304
Using COM objects with HAHTtalk Basic . . . . . . . . . . . . . . . . . . . . . . 305
The CreateObject function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .305
A COM Server example. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 306
Background . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .307
HAHTMem methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .307
14 HAHTsite CORBA Capabilities
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 310
What is CORBA? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .310
What does HAHTsite/CORBA interoperation mean? . . . . . . . . . . .310
Using CORBA with the HAHTsite IDE . . . . . . . . . . . . . . . . . . . . . . . . . 311
Handling CORBA projects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .311
Setting options for CORBA . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .312
HAHTsite as a CORBA client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 315
Example: Building a HAHTsite CORBA client . . . . . . . . . . . . . . . . .316
HAHTsite as a traditional CORBA server . . . . . . . . . . . . . . . . . . . . . . . 318
Example: Using CORBA to hold HAHTsite global state . . . . . . . . .319
CORBA and the HAHTsite Server Object Model . . . . . . . . . . . . . . . . . 321
Using the HAHTsite Server Object Model in a HAHTsite CORBA server
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .321

Contents
Accessing the HAHTsite Server Object Model from a CORBA client
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .322
Client/server communication . . . . . . . . . . . . . . . . . . . . . . . . . . . . .325
Example: Using CORBA in a session initiated via HTTP . . . . . . . .325
Example: Initiating a HAHTsite application session with CORBA .327
Other Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 328
Interoperability with other ORBS . . . . . . . . . . . . . . . . . . . . . . . . . .328
Using CORBA with HAHTtalk Basic . . . . . . . . . . . . . . . . . . . . . . . .329
VisiBroker installation and configuration . . . . . . . . . . . . . . . . . . . .329
VisiBroker SmartAgent and the CORBA Naming Service . . . . . . . .329
VisiBroker GateKeeper . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .329
References . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 330
15 Debugging Server-side Code
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 332
Requirements for debugging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 332
A special case: debugging HAHTtalk Basic stand-alone programs .333
Starting a debugging session . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 333
Debugging a code page. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 336
Executing code in the debugger . . . . . . . . . . . . . . . . . . . . . . . . . . .336
Single-stepping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .337
Procedure-stepping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .338
Using breakpoints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .338
The debug windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 340
Debug output panel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .341
Variable window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .341
Watch window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .343
Call Stack window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .344
Threads window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .345
A HAHTsite 3.x WebApp Methods and Properties
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 348
WebApp properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 348
WebApp methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 350
xi

Contents
xii
Pseudo-methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .352
B HAHTsite 3.x Data Management
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 356
DataSets and data agents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 356
Accessing and changing DataSet properties at runtime . . . . . . . . .356
DataSet control functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .357
Writing user-defined DataSet functions . . . . . . . . . . . . . . . . . . . . .358
Accessing and changing form-control properties at runtime . . . . . . . 358
Connection-manager functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 359
C Code Examples
Calling a subroutine as a form action . . . . . . . . . . . . . . . . . . . . . . . . . 362
Modifying a command handler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 370
Writing a custom authentication class. . . . . . . . . . . . . . . . . . . . . . . . . 373
D ADO Primer
What’s in this appendix . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 376
Connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 376
Opening a connection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .376
Executing a command against a connection . . . . . . . . . . . . . . . . .378
Closing a connection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .379
Recordsets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 380
Creating a recordset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .380
Iterating through the records in a recordset . . . . . . . . . . . . . . . . . .381
Finding a specific record in a recordset . . . . . . . . . . . . . . . . . . . . . .382
Reading a record . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .382
Updating a record . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .383
Inserting a record . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .383
Deleting a record . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .384
Closing a recordset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .385
E ADO Extensions
What’s in this appendix . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 388

Contents
Extensions to the Java interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 388
ADO tracing in Java projects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .388
Additional appendChunk methods . . . . . . . . . . . . . . . . . . . . . . . .390
The Variant data type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .390
Extensions to the HAHTtalk Basic interface. . . . . . . . . . . . . . . . . . . . . 391
ADO tracing in HAHTtalk Basic projects . . . . . . . . . . . . . . . . . . . .391
Functions for managing connections . . . . . . . . . . . . . . . . . . . . . . .391
xiii

Contents
xiv

About This Book
The HAHTsite IDE Programming Guide explains how to extend your HAHTsite ®
applications programmatically. Chapter 1, “Introduction,” gives you an
overview of the programming capabilities available within HAHTsite. If you’re
developing a Java application, continue with Chapter 2, “Working with Java
Projects.” If you’re developing a HAHTtalk Basic application, look at the
corresponding chapter, Chapter 3, “Working with HAHTtalk Basic Projects.”
Then read Chapter 5, “HAHTsite Server Object Model,” which describes the
programming model that underlies a HAHTsite application, including the
Application, Session, Page, Request, and Response objects. This chapter, and
all the chapters that follow, contain both HAHTtalk Basic and Java examples.
However, the functionality is the same, regardless of which language you use.
The table below lists each chapter in the HAHTsite IDE Programming Guide,
along with its contents.
Chapter/Appendix Contents
Chapter 1, “Introduction” A high-level introduction to the IDE’s Server
Object Model, data management model, and
COM, CORBA, and client-scripting capabilities.
Chapter 2, “Working with Java
Projects”
Chapter 3, “Working with
HAHTtalk Basic Projects”
Chapter 4, “Calling Server-side
Java from HAHTtalk Basic”
Chapter 5, “HAHTsite Server
Object Model”
Chapter 6, “Forms-Related
Programming”
Chapter 7, “Form Fields
Programming”
Information for developers who are adding
server-side code to a Java project.
Information for developers who are adding
server-side code to a HAHTtalk Basic project.
How to call Java from a HAHTtalk Basic project.
Explanation of the built-in objects in HAHTsite’s
Server Object Model.
Customizing your application’s form-handling
capabilities. For HAHTtalk Basic projects, adding
a custom form handler.
Writing code that affects form fields and using a
button to call user-written code.
xv

About This Book
Chapter/Appendix Contents
Chapter 8, “Data-Agent
Programming”
Chapter 9, “Programming with
the Connection Manager”
Chapter 10, “Working with
Client-side Scripts”
Chapter 11, “Using HtmlOut
Routines or the HtmlOut
Class”
xvi
Calling data-agent methods at runtime;
customizing HAHTsite’s command handlers.
Opening and closing shared and private
connections using the DMConnectionManager
class.
Adding JavaScript or VBScript to your
application.
Using HAHTsite functions/methods to create
HTML at runtime.
Chapter 12, “Access Control” Controlling access to HAHTsite project items by
assigning a set of required privileges to the
items.
Chapter 13, “Connecting to
COM Objects”
Chapter 14, “HAHTsite CORBA
Capabilities”
Chapter 15, “Debugging
Server-side Code”
Appendix A, “HAHTsite 3.x
WebApp Methods and
Properties”
Appendix B, “HAHTsite 3.x
Data Management”
Accessing DLLs and COM/DCOM objects from
HAHTsite applications.
Building HAHTsite applications that are CORBA
clients or servers.
Using HAHTsite’s remote debugger to inspect
code running on the Application Server.
How WebApp properties and methods (from
HAHTsite 3.x) relate to objects in the Server
Object Model.
How programming database applications differs
between HAHTsite 3.x and HAHTsite 4.0.
Appendix C, “Code Examples” A set of sample functions/methods that
supplement those in the text.
Appendix D, “ADO Primer” How to perform basic operations using ADO
connections and recordsets.
Appendix E, “ADO Extensions” The few ways in which HAHTsite’s ADO
implementation differs from the standard.

Who is this book for?
About This Book
This book is written for use by HAHTsite programmers. It assumes that you:
know how to use the HAHTsite IDE to create Web applications.
have an understanding of how the HAHTsite IDE creates Web
applications, how HAHTsite applications are structured, and how
applications interact with the HAHTsite Application Server.
know how to use either the Visual Basic or Java programming language.
are familiar with HTML.
Prerequisites
In order to build a Java project that contains dynamic pages, or a HAHTtalk
Basic project that calls server-side Java, you must have a Java compiler
installed (not included with the HAHTsite software). See the ReadMe file for
information on downloading a Java compiler.
Conventions
This book uses several conventions, which are described here.
HAHTsite installation directory
The directory into which you install the HAHTsite IDE is called the HAHTsite
installation directory. This book uses the variable HAHTsiteInstallDir as a
placeholder for the HAHTsite installation directory — for example,
C:\HAHTsite. When you see this variable, you should replace it with the name
of the HAHTsite installation directory on your system.
Continuation characters in sample code
Some lines of sample code are too long to fit on one line. For HAHTtalk Basic
code, this book uses the line-continuation character (“_”) at the end of a line.
For example:
Function Create (instanceHandle As Long, createTime As Integer, _
scopeCount As Long) As Integer
xvii

About This Book
Screen images
The HAHTsite IDE/IP runs on Windows 95, Windows 98, and Windows NT.
Depending on which operating system you are using, the “look” of the screens
might be slightly different from what you see in this book. However, the
screens’ contents are the same.
Other HAHTsite documentation
The HAHTsite IDE includes this additional documentation:
xviii
HAHTsite IDE and IP User’s Guide
HAHTsite IDE and IP Installation Guide
HAHTsite Widget Programming Guide
“Getting Started”
The HAHTsite IDE/IP also includes an introduction to HAHTsite, lessons in
using HAHTsite, and sample (HAHT_Intro) projects in Java and HAHTtalk
Basic. Choose Getting Started from the Help menu.
Online documentation
In addition to the printed books, you can use the IDE/IP’s online help system.
As well as context-sensitive help for each of the dialogs, the online help system
includes:
Overview information about the IDE/IP.
Step-by-step instructions on how to use the IDE/IP’s features.
Reference pages for the HAHTtalk Basic language, HAHTsite’s Server
Object Model, and the SQL Assistant.
Information about using HAHTtalk Basic’s Dialog Editor (used in
building widgets).
To open the help system, choose Contents and Index from the Help menu.

HAHTsite OLE Interface Guide
About This Book
The HAHTsite IDE provides an OLE interface that you can access from your
custom widgets. The OLE objects and methods are described in the HAHTsite
OLE Interface Guide, which you can access from the IDE’s Help menu. The
HAHTsite OLE Interface Guide is an HTML document.
The HAHTsite OLE Interface Guide is also installed as a HAHTsite project (in
HAHTsiteInstallDir\sdk\oleapi). This enables you to add comments to the
guide or to copy the guide’s examples into the HAHTsite IDE and test them.
Other HAHTsite products
In addition to the IDE and the IP, the HAHTsite family of products includes the
HAHTsite Application Server, which works with any Web server to execute
HAHTsite applications. The Application Server runs on the Windows NT,
HP/UX, Solaris, and AIX operating systems. It executes application logic,
enables complete access to multiple data sources, maintains session
information, and dynamically generates HTML pages.
HAHT Software’s commitment to you
We want you to be completely satisfied with your HAHT Software products.
If you have questions about HAHTsite, the HAHTsite IDE, the HAHTsite IP, or
the HAHTsite Application Server, you can contact HAHT Software in the
following ways:
Telephone
(919) 786-5200 Technical Support (Voice)
(919) 786-5252 Technical Support (FAX)
(888) 438-4248 Sales (Voice—in the USA)
(919) 786-5100 Office (Voice)
(919) 786-5250 Office (FAX)
xix

About This Book
Email
xx
info@haht.com General Information
sales@haht.com Sales
support@haht.com Support
World Wide Web
• www.haht.com

Introduction
1
Overview ...........................................................................................................2
HAHTsite Server Object Model.........................................................................3
The project package.....................................................................................3
The datamanager package ...........................................................................4
The form package ........................................................................................4
The access package ......................................................................................5
The corba package .......................................................................................5
Data-management API......................................................................................5
ActiveX Data Objects classes .......................................................................6
Relationship between ADO and SOM classes .............................................6
Data management in HAHTtalk Basic projects ..........................................7
Client-side scripting..........................................................................................8
CORBA capabilities ...........................................................................................9
Access to COM/DCOM objects ........................................................................9
Remote debugging ..........................................................................................10
1

Chapter 1: Introduction
Overview
Using HAHTsite’s Integrated Development Environment (IDE), you can create
many Web applications without writing any code. You describe your
application’s requirements using the IDE’s graphical user interface, and
HAHTsite’s code generator creates the code for your application.
Of course, code generators can’t account for every contingency. Therefore,
HAHTsite makes it easy for you to add your own code to this generated code
as needed. In HAHTsite, you can add such code using either Java or HAHTtalk
Basic (which is syntax compatible with Visual Basic). A Java virtual machine
(either Microsoft or Sun) and a Basic virtual machine are embedded in the
Application Server for the execution of code written in these languages.
Being able to add Java or HAHTtalk Basic code to HAHTsite pages is useful in
itself, but the real power of this language support lies in the fact that you can
use these languages to call a tremendous amount of existing code. For
instance, from either Java or HAHTtalk Basic, your Web application can call
other code in DLLs, UNIX shared libraries, Java classes, or practically anything
else that has a callable API. Of particular importance are the Java packages and
Basic libraries supplied with HAHTsite.
First, HAHTsite includes a set of Java packages that make up what is called its
Server Object Model. The classes in these packages can be called from both
Java and HAHTtalk Basic projects and enable you to:
2
obtain information about the Application Server, about your application
and individual user sessions, and about the data being passed back and
forth between the Application Server and the Web server
establish connections with relational and nonrelational data sources and
to manage the ActiveX Data Objects (ADO) recordsets obtained via those
connections
control the form fields in your application’s forms
provide access control for the pages in your application
make your application a CORBA server
HAHTsite also includes a Java package and a Basic library that enable you to
use the ActiveX Data Objects API for data management.

HAHTsite Server Object Model
Chapter 1: Introduction
The classes in the HAHTsite Server Object Model (SOM) are implemented in
Java. At runtime, Java projects access SOM objects as real Java objects, and can
subclass SOM classes and override SOM methods. You can also access the SOM
from HAHTtalk Basic projects using HAHTtalk Basic syntax. However, some
limitations apply; for example, SOM objects cannot be subclassed in a
HAHTtalk Basic project. The classes in the SOM give you many capabilities,
including the ability to examine requests sent from a Web browser, to manage
data sources, and to protect information from unauthorized access.
The principal packages in the SOM are:
com.haht.project
com.haht.project.datamanager
com.haht.project.form
com.haht.access
com.haht.corba
The project package
The project package contains a number of built-in objects, which are
available in every HAHTsite application. These objects are similar to the
built-in objects in Microsoft’s Active Server Pages. They let you control the
data passed to and from a Web browser client and to get information about the
application, the Web server, and the Application Server.
When you run a HAHTsite application, each instance of a dynamic page is a
Page object. You can also create dynamic pages programmatically, by
implementing the HAHTPage interface in a Java project, or by implementing a
Basic subroutine that generates HTML in a HAHTtalk Basic project. In addition
to Page objects, each HAHTsite application contains these built-in objects:
The Server object contains methods for storing variables that may be
shared among multiple applications (as long as they are running in the
same process on the Application Server).
The Application object has information about the current application, as
well as event handlers that are triggered when an application or session
starts or ends.
The Session object has information about the current session, which is
defined as a browser client using the application. There is a separate
Session object for each client. It also has two event handlers, called
when a session is created and just before it’s destroyed.
3

Chapter 1: Introduction
4
The Request object’s methods retrieve data the client browser sends to
the Web server — for example, form data or cookies.
The Response object’s methods generate HTML that the Web server sends
to the browser.
For further information about the project package, see Chapter 5, “HAHTsite
Server Object Model.”
The datamanager package
The most important classes in the datamanager package are:
DataAgent
DMConnectionManager
The DataAgent class represents an ADO recordset and enables you perform a
variety of actions against that recordset. For example, you can use this class’s
methods to set the command that returns the recordset, to perform an action
such as updating a record, or to get or set the value of a field in the recordset’s
current record.
The DMConnectionManager class includes methods for opening ADO
connections to relational or nonrelational data sources. These connections
can be shared by two or more data agents within a session to lessen the
amount of time your application spends establishing connections. Or they can
be private so that you can perform transactions on the connection.
The DataAgent and DMConnectionManager classes are discussed in detail in
Chapter 8, “Data-Agent Programming” and Chapter 9, “Programming with
the Connection Manager,” respectively.
The form package
The form package contains classes that represent the different types of form
fields that you can place in a form, such as text boxes, combo boxes, and
submit buttons. The methods of these classes enable you to perform tasks such
as:
setting a form field’s value
setting a text box’s width
setting the selected status of a list-box element
Basically, all the form-field attributes that you can set in the IDE, you can also
set at runtime.

Chapter 1: Introduction
For further information about the form package, see Chapter 7, “Form Fields
Programming.”
The access package
The access package includes classes that enable you to control access to
HAHTsite pages. A Privileges class provides a container for a set of
user-defined privileges, and each session contains a Privileges object. In
addition, HAHTsite pages have associated with them a set of privileges. At
runtime, the Application Server determines whether a session has access to a
particular page in an application by comparing the privileges in the session’s
Privileges object with the page’s privileges. The session can access a page
only if all of that page’s required privileges are contained in its Privileges
object.
This package also contains classes that enable you to:
authenticate a user login
retrieve a set of privileges from a repository by user name
Chapter 12, “Access Control,” provides a complete explanation of how to use
the classes in this package.
The corba package
The corba package enables you to create a HAHTsite application that plays the
role of a CORBA server. Using the CORBA interface, clients can create sessions
and invoke Java object methods. This CORBA interface enables applets
running in a browser to communicate directly with the Application Server,
bypassing the Web server. It also enables other CORBA applications in the
corporate IT infrastructure to invoke services from the HAHTsite Application
Server.
A HAHTsite application can also function as a CORBA client. For further
information about creating CORBA clients and servers, see Chapter 14,
“HAHTsite CORBA Capabilities.”
Data-management API
In addition to the Server Object Model, HAHTsite includes both a Java package
and a Basic library that provide a data-management API based on Microsoft’s
ActiveX Data Objects (ADO) 2.0. Java projects use the Java classes, and
5

Chapter 1: Introduction
HAHTtalk Basic projects use the Basic classes. You can find documentation for
both interfaces on Microsoft’s Web site (http://msdn.microsoft.com/isapi/
msdnlib.idc?theURL=/library/sdkdoc/dasdk/mdwe7i0f.htm).
The ADO interface has the benefit of being well known and widely used by
developers and, thus, is preferable to yet another proprietary data-access
model. In addition, ADO is not tied to SQL, but allows access to both relational
and nonrelational data sources.
ActiveX Data Objects classes
As mentioned earlier, HAHTsite’s ADO interfaces are based on those of
Microsoft ADO 2.0. If you’re familiar with ADO programming, you know that
the principal classes in the ADO object model are:
6
Connection
Command
Recordset
The Connection class represents a connection to a data source. An object of
this type enables you to open and close a connection to a data source, to
execute a command that returns a recordset from the data source, and to
manage transactions on the connection.
A Command object represents a command that queries a data source and returns
a recordset. This command may be a SQL statement or some other textual
command, the name of a database table, or the name of a stored procedure.
A Recordset object contains the records returned over a connection following
the execution of a query. Using a Recordset’s methods, you can navigate the
records in the recordset, add a new row to the recordset or delete an existing
record, update a record, and so on.
For information on how these ADO classes relate to the Server Object Model’s
DataAgent and DMConnectionManager classes, see “Relationship between ADO
and SOM classes” on page 6.
Relationship between ADO and SOM classes
As you’ve probably noticed, there’s some overlap between the ADO object
model and the Server Object Model’s DMConnectionManager and DataAgent
classes. You can use either — or a combination of both — for your
data-management programming.
Basically, the classes in the Server Object Model (SOM) provide a layer on top
of the ADO classes that makes programming easier. The DMConnectionManager

Chapter 1: Introduction
class enables you to create an ADO connection, and the DataAgent class not
only represents an ADO recordset, but knows about the connection and the
command used to retrieve that recordset. If you use the IDE to create
connections to data sources and to create data agents, HAHTsite calls methods
of the DMConnectionManager class and the DataAgent class in its generated
code. So some of your data-management programming can be as simple as
describing your requirements in the IDE.
For situations where you need to perform tasks that aren’t supported by the
IDE, you can supplement the IDE’s generated code with your own code that
uses the DMConnectionManager and DataAgent classes, or you can use the ADO
interface directly.
Data management in HAHTtalk Basic projects
In HAHTtalk Basic projects, you have two options when it comes to ADO
programming. You can create Basic objects by making calls like this:
Dim myConn As New ADODB.Connection
myConn.open "..."
Or you can create Java objects by using the classes defined in the package
com.haht.ado, like this:
Dim myConn As Object
myConn = CreateJavaObject("com.haht.ado.Connection" ...)
myConn.open "..."
Although both approaches are perfectly acceptable, the assumption is that
Basic programmers will prefer to use Basic objects (the first approach).
If you do use the Basic library for your ADO programming, make sure you
understand that a Basic object and its Java counterpart are not type
compatible. That is, a Basic recordset and a Java recordset do not have the
same data type. Therefore, the following code will result in a type-mismatch
error:
Dim myRS As ADODB.Recordset
.
.
.
Set myRS = dataAgent.getRecordset()
The DataAgent class is a Java class, and the getRecordset method returns a
Java object. A reference to this object cannot be assigned to myRS.
One other note. The Java classes DMConnectionManager and DataAgent —
which are not part of the ADO object model, but define methods that return
ADO objects — do not have Basic counterparts. HAHTsite does include Basic
7

Chapter 1: Introduction
functions that give you much of the functionality of the
DMConnectionManager class. (These functions are discussed in Appendix E,
“ADO Extensions.”) However, to work with data agents, you must work with
Java objects.
Client-side scripting
Most code in a HAHTsite application is executed by the Application Server;
however, HAHTsite also provides support for writing client-side scripts to be
executed in the user’s browser. You can write these scripts in either JavaScript
or VBScript.
To help you develop scripts more easily, the HAHTsite IDE provides a Client
Scripts view of each HTML page. In this view, you see a tree representation of
the Document Object Model for the page. By navigating this tree, you can
select specific objects that you want to associate event handlers with. For
instance, you can navigate to a text box in a form and select the text box’s
onChange event. You can then use a script editor window to write a script that
will be executed when this event occurs.
The Document Object Model window also displays properties of the currently
selected object and methods that may be applied to that object. If you drag
one of these properties from the Document Object Model window to the
editing window, HAHTsite constructs the appropriate reference, including
correct capitalization and syntax. This drag-and-drop feature makes it easier to
write client scripts.
One other point. The task of writing client scripts and Dynamic HTML is
complicated by variations in the Document Object Models in different
browsers and different browser revisions. In general, the Document Object
Model has become much more sophisticated and robust in later browser
revisions, but pages that use the new browser features do not work in older
browsers. The HAHTsite client-script editor enables you to view a particular
Document Object Model. Thus, if you select the Internet Explorer 3.0
Document Object Model, HAHTsite will not display the new events and
scriptable objects introduced in later versions of Internet Explorer and
Netscape Navigator. This feature makes it easy to write scripts that work when
the browser revision of your end users varies.
For additional information about using JavaScript and VBScript in your
applications, see Chapter 10, “Working with Client-side Scripts.”
8

CORBA capabilities
Chapter 1: Introduction
The software bundled with HAHTsite includes Inprise (formerly Visigenic)
VisiBroker for Java, a suite of tools for building distributed-object applications.
HAHTsite applications written using the HAHTsite Server Object Model can
incorporate calls to the VisiBroker interfaces and thereby act as standard
CORBA objects. Using CORBA’s built-in capabilities, they can communicate
with and become part of an enterprise built of distributed CORBA objects.
Information from remote CORBA systems, such as mainframes, can be
obtained by these CORBA-enhanced HAHTsite applications. This data can
then be used in any manner within the HAHTsite application, providing a
flexible, complete method to present enterprise information on the Web.
In addition, there are several extensions to the HAHTsite Server Object Model
that provide CORBA interfaces, allowing CORBA systems to operate directly
on some HAHTsite server objects. This level of integration allows an external,
non-HAHTsite application to connect as a CORBA client to a CORBA-enabled
HAHTsite application acting as a CORBA server. Such a client can initiate and
control a HAHTsite session, making use of session capabilities such as
automatic timeout.
CORBA can also provide a Java applet running in a browser the ability to
communicate with a HAHTsite application without the overhead of the HTTP
protocol. For applets requiring substantial or very dynamic data from the
server, this can be very beneficial.
Access to COM/DCOM objects
In a Microsoft environment, HAHTsite also provides full access to
COM/DCOM objects. This access is native and does not depend on bridges
from CORBA or other distributed object systems. From HAHTtalk Basic code,
COM/DCOM servers are instantiated using the standard CreateObject call.
Both in-process and out-of-process servers are supported. From Java code,
COM/DCOM objects can be accessed via Java wrapper classes created using
tools provided with the Microsoft SDK for Java. HAHTsite’s ability to naturally
and directly access COM/DCOM objects makes it easy to interface your
HAHTsite application to other software products or custom code written for
the Microsoft environment.
For additional information, see Chapter 13, “Connecting to COM Objects.”
9

Chapter 1: Introduction
Remote debugging
HAHTsite supports remote debugging of both Java and HAHTtalk Basic code
running in the Application Server (but not both in the same debug session).
The Java and HAHTtalk Basic debuggers share the same IDE interface and have
equivalent function except that Java code must be published with the debug
option so that debug symbols are included. (HAHTtalk Basic code can be
debugged without the debug option.)
Debugging HAHTsite applications is discussed in detail in Chapter 15,
“Debugging Server-side Code.”
10

Working with Java
Projects
2
What’s in this chapter ....................................................................................12
Adding server-side code to a Java project......................................................12
In-line code ................................................................................................13
Invoking an expression or a method from a dialog box .........................15
Adding code in Server-side Code view .....................................................17
What’s in a Java page?...............................................................................18
Editing HahtApplication.java and HahtSession.java ................................25
Adding Java files to a project ....................................................................26
Naming conventions for Java projects ..........................................................30
Calling a dynamic page from Java.................................................................30
Event handling in a Java project ...................................................................31
Editing and compiling Java code ...................................................................37
Using the code editor ................................................................................37
Compiling a Java application....................................................................38
Finding compile-time errors......................................................................39
Debugging a Java application....................................................................39
Working with application directories .......................................................39
Java options ....................................................................................................41
Changing the Java file type.......................................................................41
Overriding Java compiler options.............................................................42
Overriding options for JAR, CAB, and ZIP files........................................43
11

Chapter 2: Working with Java Projects
What’s in this chapter
The first half of this chapter explains how to add server-side code — that is,
code that runs on the Application Server — to a Java project. The second half
of the chapter explains the mechanics of working with the code editor and
compiling the code.
Later chapters in this book give detailed explanations, with examples, of ways
you can extend your HAHTsite application programmatically. For complete
information about specific Java classes and methods, refer to the online help
for the Server Object Model.
In addition, if you are interested in further customizing your application with
client-side scripts and applets, then be sure to look at Chapter 10, “Working
with Client-side Scripts,” and the HAHTsite IDE and IP User’s Guide, Chapter 20,
“Applets and Multimedia Objects.”
12
Note - The examples throughout this book assume the
appropriate import statements and invoke Java methods
without qualifying them with the full package name — for
example, they call Haht.getRequest() instead of
com.haht.Haht.getRequest(). HAHTsite’s generated code
uses the full qualification, to eliminate the possibility that a
HAHTsite class might have the same name as another (non-
HAHTsite) package you have imported. You may wish to do the
same.
Adding server-side code to a Java project
With Java, you can easily extend the functionality of your HAHTsite Web
applications beyond what you can do with HTML or CGI programs. In a
HAHTsite Java project, you can use Java in these ways:
1 You can add in-line code to a page, intermixed with other HAHTsite
elements such as text, pictures, and forms. The code can be a simple
expression, a single line, or a complete block of code. See “In-line code”
on page 13.
2 You can insert expressions and method calls in many of the dialogs in the
IDE — for example, a text box can be initialized with the value of an
expression, and a form’s action can be a call to a Java method. See
“Invoking an expression or a method from a dialog box” on page 15.

Chapter 2: Working with Java Projects
3 You can insert code in predefined places within the Java source for a page,
using the HTML editor’s Server-side Code view. See “Adding code in
Server-side Code view” on page 17.
4 You can modify or add to the source code for the HahtApplication and
HahtSession classes. See “Editing HahtApplication.java and
HahtSession.java” on page 25.
5 You can create or import separate Java source files, with classes and
methods that can be shared by all of the pages in an project and that can
be reused in other projects. In addition, you can import Java class files as
well as JAR, CAB, and ZIP files. See “Adding Java files to a project” on page
26.
HAHTsite Server Object Model
Much of this book describes classes and methods in HAHTsite’s Server Object
Model, which controls the structure of a HAHTsite Web application. With the
Server Object Model, you can perform tasks such as reading data passed on the
URL, writing HTML data, and controlling session timeout, as well as managing
data source connections, setting form field values, and controlling access to
dynamic pages.
The Server Object Model is implemented in Java. However, it is equally
accessible from HAHTtalk Basic projects, and the online help for the Server
Object Model shows both the Java and HAHTtalk Basic syntax to call each
method.
External logic
From your Java code, you also have access to Java classes outside the project
and to capabilities such as CORBA, COM objects, and native methods. For
more information, see Chapter 13, “Connecting to COM Objects” and
Chapter 14, “HAHTsite CORBA Capabilities.”
In-line code
The ability to intermix Java code with other elements (such as text, pictures,
widgets, and form elements) gives you a powerful tool for dynamically
changing the content of Web pages. You can use this technique for many
purposes — for example:
to control the flow of logic on the page
13

Chapter 2: Working with Java Projects
14
to create “internationalized” pages that contain text in different
languages from which a user can select
to retrieve values passed on the URL from a calling page
to override the value of a form field at runtime
In-line code is typically used for short expressions and statements. To
maintain the WYSIWYG look of your pages, you’ll probably want to minimize
the amount of code that you place directly onto a page. You can do this by
creating classes and methods in a project’s source pages and calling them from
your Web pages. With this approach, you can also share classes and methods
among the project’s Web pages.
In this example, a data agent (represented by the icon at the top of the page)
populates a form with fields from a database. However, between the data agent
and the form, note the code that disables the Next button if we’ve reached end
of file.
Besides adding entire lines of code, you can also add expressions. An expression
can include variables, constants, operators, and methods, as long as it resolves
to a single value. Here are two examples:
a * b / c
aRequest.getURLField("txtCity")
In the Java source, the IDE includes the expression in an out.print statement.

To add a Java expression to an HTML page
Chapter 2: Working with Java Projects
1 On the page, click where you want the expression to appear.
2 Click the Server-side Expression button .
3 Type the expression.
4 By default, expressions are displayed in red in the editor, although you can
change this setting using Tools > Options.
To add a statement to an HTML page
1 On the page, click where you want the statement to appear.
2 Click the Server-side Statement button .
3 Type one or more statements.
4 By default, statements are displayed in blue in the HTML editor.
To convert existing text to an expression or statement
1 Select the text you want to convert.
2 Click either the Server-side Expression button or the Server-side
Statement button . Or choose Edit > Character, click the Script tab, and
then select the type of expression or statement you want to create.
To format the output of an expression or statement
You can format the output of a Java expression or statement, just as you can
format text that you type directly on the page.
1 Select the paragraph or characters you want to affect.
2 To modify the paragraph properties, choose Edit > Paragraph... or make a
selection from the Paragraph Styles toolbar.
3 To modify the character properties, choose Edit > Character.... or make a
selection from the Character Styles toolbar. (If you modify the font color,
the new color will be displayed in the browser, but not in the IDE.)
Invoking an expression or a method from a dialog box
The second way you can customize your project is through dialog boxes. From
the HAHTsite IDE and IP User’s Guide, you’re probably aware of the many places
that allow you to set project item properties using an expression rather than a
field name or a constant, or that allow you to call a method instead of a
dynamic page as a link or form action.
15

Chapter 2: Working with Java Projects
Dialog box expressions
To substitute an expression for a field name or constant, prefix the expression
with “==”. For example, in the properties for a link, you could define the query
string to contain the entry point name of the current page:
callingPage=/*==getName()*/
On the destination page, you could retrieve the information this way:
aRequest.getURLField("callingPage")
which would return packagename.class.method, like this:
JavaExample.HsLinkStart.run
Notice in the example the use of "/*" and "*/" bracketing the expression. You
must use this construction when you want to use an expression in a
name/value attribute pair, or when it appears in the middle of a script.
However, if you simply want to set an attribute to the value of an expression,
you can use ==expression.
The expression must evaluate to a character string.
16

Dialog box method calls
Chapter 2: Working with Java Projects
In addition to using expressions, you can call user-defined methods from
several property sheets in the IDE, such as the Form Properties dialog and the
Link Properties dialog. For example:
A Java method can generate the binary data to display a picture, an
image map, or a multimedia object.
It can be the destination for a dynamic link (the value of an HREF
attribute tag).
It can be the default action that takes place when the user submits a
form, or the action tied to one of the form’s buttons.
Obviously, the content of your Java method will be determined primarily by
what you want it to do, and the HAHTsite IDE and IP User’s Guide explains any
restrictions on calling a method or subroutine in the documentation for each
set of properties. However, if the effect is to display a page, the class should
implement the HAHTPage interface, including the run method:
void run (Request aRequest, Response aResponse)
The run method and its arguments are described later in this chapter; see
“What’s in a Java page?” on page 18.
Adding code in Server-side Code view
The third way to customize your project is to add code directly to the serverside
code for a page. When you include a dynamic page in a build or publish
operation, the IDE generates a new Java source file for that page, extending the
com.haht.project.Page class. When you add in-line code to the page, it’s
inserted in the Java source, in the run method for that page. However, you may
want to make other additions to the code for a page — for example, you might
want to add an import statement, add some initialization code to the run
method, or call your own exception handler. The HTML editor’s Server-side
Code view lets you view the source code for a page, and lets you make
additions, in predefined places, that will be preserved when the page is
regenerated. (Note - you cannot change the generated source code; you can
only add to it.)
To view and add to the server-side code for a page
1 Open the page in the HTML editor.
2 Select View > Server-side Code, or click the Server-side Code view button
.
17

Chapter 2: Working with Java Projects
3 Here are some points to note:
18
The white areas mark places where you can insert code.
The grayed-out areas mark generated source code, which is read-only.
If you make changes in Server-side Code view, and then return to
Normal view or HTML tags view, you will see your changes reflected.
If the Server-side Code view button is disabled, be sure that you have
saved the page.
For more information on this process, see the note that follows.
Behind the scenes: How does Server-side Code view work?
To keep from overwriting your additions, the IDE must keep your code
separate from the code it generates. When you add code in Server-side Code
view, your code is translated into HTML tags and kept in the project’s HTML
file for this page. If you look at the page in HTML tags view, you will see
sections like this:
When you build or publish the project, the code for the dynamic page is
generated from the HTML file.
What’s in a Java page?
For each dynamic page, the IDE generates a file (Hspagename.java) that
defines a class Hspagename as a subclass of Page. The source code for each
dynamic page has these contents:
A package statement
Import statements
Class declaration and constructor
A run method
An exception handler
A form handler
Places to add classes and methods
The following sections explain each of these topics, using as an example the
Java source for a page that simply displays the current date.

A package statement
The package name is the name of the project.
package ExamplProj;
Chapter 2: Working with Java Projects
For more information about package names, see “Naming conventions for
Java projects” on page 30.
Import statements
Each page source file imports several packages, including the HAHTsite
packages for the Server Object Model and for data management. You can add
your own import statements using the HTML editor’s Server-side Code view.
////////////////////////////////////////////////////////////////
// IMPORTS
////////////////////////////////////////////////////////////////
import com.haht.*;
import com.haht.project.*;
import com.haht.io.*;
import com.haht.project.form.*;
import com.haht.project.datamanager.*;
import com.haht.ado.Abstract.*;
import java.io.*;
import java.util.*;
// custom imports
import com.haht.access.*;
import java.text.*;
Class declaration and constructor
Each page has a constructor, called once per page per session to create the page
object. If the page contains form fields, they are initialized here. You can also
add custom code to the constructor.
Notice the class declaration: the page name, which is simply ShowDate.html
in the IDE, has become the class HsShowDate in the Java source for the page.
For more information on dynamic page names, see “Naming conventions for
Java projects” on page 30. You can add “implements” clauses if the class
implements any additional interfaces.
19

Chapter 2: Working with Java Projects
The constructor also gets references to both the Application object and the
Session object — references you can use anywhere in a dynamic page. These
references are very useful in accessing application-level and session-level
variables.
A run method
Each page has a run method, with two arguments: the Request object and the
Response object. The run method emits any header lines — for example,
20
public class HsShowDate extends com.haht.project.Page
// Specify implements declarations here.
{
/**
* Default constructor for HsShowDate
*
**/
public HsShowDate ()
{
hahtApplication = (HahtApplication) Haht.getApplication();
hahtSession = (HahtSession) Haht.getSession();
}
...
// Custom constructor code.
Content-type: text/html
Note that you can override the content-type header by another call to the
Response object’s setContentType method. See “Adding content information
to a header line” on page 127.
After emitting header lines, the run method then sets up the basic structure of
the page, which would look like this in HTML:
...
...

Chapter 2: Working with Java Projects
When you add in-line code to a page, it’s normally added here, between the
and tags. (Some code — such as setting a cookie — must be
output with the HTTP headers. HAHTsite automatically handles this code
correctly. See “Writing headers” on page 126.)
Notice the marked sections where you can add local variables, initialization
code, and custom HTTP response headers (two places). You can also edit any
in-line code. In this example, the page contains two lines of in-line code, to
set the date.
/**
* Runs the page, producing HTML.
*
* @param aRequest - HTTP request for this page
* @param aResponse - HTTP response for this page
*
**/
public void run(com.haht.project.Request aRequest,
com.haht.project.Response aResponse)
{
HtmlWriter out;
// user-defined run() local variables
try
{
// Initialize variables.
out = aResponse.getWriter();
// Custom initialization code executes before HTML
// tags are generated.
// Output HTTP response headers.
// Custom HTTP Response Headers.
aResponse.setContentType("text/html");
out.print("\r\n");
// More Custom HTTP Response Headers.
21

Chapter 2: Working with Java Projects
References to the Request and Response objects
The run method, seen in the example above, has two arguments:
22
// Generate HTML.
out.print("\r\n");
out.print("\r\n");
out.print(" \r\n");
out.print(" ShowDate\r\n");
out.print("\r\n");
out.print("\r\n");
out.print(" ");
Date d = new Date();
out.print(d);
out.print("\r\n");
out.print("  \r\n");
out.print("\r\n");
out.print("");
// All HTML has been generated. Put cleanup code here.
} // try
catch (java.lang.Throwable t)
{
handleException(t, "HsShowDate", aRequest, aResponse);
} // catch
} // End of run method
the Request object (aRequest), whose methods get information from the
Web browser — for example, methods to read data passed in a form field
or on the URL.
the Response object (aResponse), whose methods send information to
the Web server — for example, HTML output and cookies.
The Request and Response objects are built in to your HAHTsite application,
along with the Application and Session objects. Both these object references
(aRequest and aResponse) will be useful in your in-line code. For example, to
read a value passed in a form or on the URL, you would call
aRequest.getURLField.

Chapter 2: Working with Java Projects
Note - For information about using the variables and methods
of the Application and Session objects, see “Calling a
dynamic page from Java” on page 30. For general information
on the HAHTsite Server Object Model’s built-in objects, see
“Built-in objects” on page 90.
A reference for writing HTML output
The run method also gets a reference to the default HtmlWriter. To write HTML
output programmatically, you can use statements like this:
out.print(d);
Of course, you can also intermix text and in-line code on a page. In the Java
source, the text turns into out.print statements.
An exception handler
The run method of every dynamic page calls a general-purpose exception
handler, handleException, to catch runtime errors and print an error message
similar to this.
You can override this method or add other exception handlers to your code.
A form handler
The Java source for each dynamic page contains a form handler that adapts to
the contents of the page. At runtime, when a user submits a form, the form
handler determines which button was clicked and calls the appropriate
command handler.
Because this page doesn’t contain a form, it has no command handlers. If it
did, you would see additional places in which you can customize the
command handlers by writing your own event-handling code. For more
information, see Chapter 8, “Data-Agent Programming.”
23

Chapter 2: Working with Java Projects
Places to add classes and methods
In Server-side Code view, you will see a number of marked sections where you
can add classes, methods, and variables:
24
/**
* Entry point that is called via URL when a form is
* submitted from this page.
*
* @param aRequest - HTTP request for this page
* @param aResponse - HTTP response for this page
*
**/
public void mapFormToCmd
(com.haht.project.Request aRequest,
com.haht.project.Response aResponse)
{
boolean bCmdHandlerCalled = false;
if (! bCmdHandlerCalled)
{
getErrors().add("Received form command did not
invoke a command-handler", "form-handler");
run (aRequest, aResponse);
}
}
public, protected, and private methods
static initializer code
nested classes
public, protected, and private member variables
// user-defined public methods
// protected methods
// user-defined protected methods

private methods
// user-defined private methods
// static initializer code
Chapter 2: Working with Java Projects
static
{
// Initialization code for user-defined static variables.
}
// nested classes
// user-defined nested classes
// public member variables
// user-defined public variables
// protected member variables
protected HahtApplication hahtApplication;
protected HahtSession hahtSession;
// user-defined protected variables
// private member variables
// user-defined private variables
Editing HahtApplication.java and HahtSession.java
In addition to one or more Page subclasses, your HAHTsite application
includes a HahtApplication class and a HahtSession class, which you can see
in your project window.
25

Chapter 2: Working with Java Projects
You can open these files in the code editor and add variables and methods to
these classes. You can use HahtApplication to cache variables that may be
shared by multiple sessions. Use HahtSession to store variables that apply
across page boundaries.
A session recordset is a particularly powerful use of the HahtSession object.
You can update a recordset on one page and use it to populate a form on
another, without reaccessing the database.
Both HahtApplication and HahtSession contain event handlers that you can
edit; see “Event handling in a Java project” on page 31.
For more information about these files, see “Built-in objects” on page 90.
26
Note - Do not call Server Object Model methods from the
constructors in HahtApplication and HahtSession. The Server
Object Model must be initialized first. Instead, edit the
onStart and onEnd methods.
Adding Java files to a project
The final way to add server-side Java to your project is by creating a Java source
file or by importing a Java source file, class file, or JAR, CAB, or ZIP file, to be
used by any of a project’s dynamic pages.
In a Java project, all Java files should be stored in the Packages folder. You can
use the same package name as the page files (that is, the project name), or you
can create additional packages and store the Java files in subfolders under
Packages.

Chapter 2: Working with Java Projects
Note - If you (1) omit the package statement in a Java source
page and (2) reference one of its classes from an HTML page,
some compilers will generate a “class not found” compiler
error. To avoid this problem, put all your source code in
packages and use the appropriate package import statements.
To add a new Java source page
1 Choose File > New > Java Source... The New Java Source dialog appears.
2 Select the type of Java code you want to create:
Type Description
Applet Source for a Java applet
Common Java source that may be used in both server-side code
and applets
Server-side Java Source for Java code that will run on the server
Servlet Source for a Java servlet — a Web server plug-in that
allows dynamic content to be created using Java on
the server side
3 Click OK to open the Java source file.
27

Chapter 2: Working with Java Projects
To import a Java source, class, JAR, CAB, or ZIP file
In addition to creating new source files in your project, you can import
existing Java files, including:
1 In the project window, select the folder in which you want to store the
imported file. For server-side Java, files must be stored in the Packages
folder. (Applets, on the other hand, are stored in the Web folder.)
2 Choose File > Import File.... The Import Files dialog appears.
28
Type Description Extension
Java source Java source code .java
Class file Compiled Java code .class
JAR file Java archive file, which can contain multiple
files (class files, images, etc.)
Java CAB file Collection of Java class files in Microsoft’s Java
Cabinet format
Java ZIP file Collection of Java class files in ZIP format,
typically uncompressed
.jar
.cab
.zip

3 Type or browse for one or more filenames.
Chapter 2: Working with Java Projects
4 Choose Copy Files or Create Shortcuts. If you want to maintain one
central version of a file but use it in several projects, you may want to
create a shortcut.
5 In the combo box marked Import Java files as, select the type of Java code
you are importing — server-side, applet, servlet, or common.
6 Click OK to complete the import.
For more information about imported files, including information about
source control, consult the HAHTsite IDE and IP User’s Guide, Chapter 3,
“Managing Projects.”
To save a source code page
1 Select File > Save. The Save Code Page As dialog appears.
2 Type in a page name, or accept the default name. The suffix must be
“.java”.
3 To save the code page inside the project, browse within the Project Items
window for the folder name you want.
4 If the project is in source control, you will see an additional checkbox: Add
to source control. Check this box to add this file to the source control
system.
5 Click OK to save your changes.
To save a source code page outside the project
To be called from within the project, a source code page must be saved inside
the project. However, you can also save it to a file outside the project.
1 Select File > Save. The Save Code Page As dialog appears.
2 Click the Save to File... button. The Save As dialog appears.
3 Browse for a folder location and enter a filename.
4 Click OK to save your changes.
29

Chapter 2: Working with Java Projects
Naming conventions for Java projects
HAHTsite uses certain naming conventions for Java projects. In a HAHTsite
Java project, project names become package names.
30
Project names must be unique within a site.
Any valid filename can be used as a project name, with one exception:
Java keywords cannot be used as project names (you’ll get an error when
you create the project).
When the IDE generates the package name, it turns any nonalphanumeric
characters (including spaces) to underscores (_).
Naming conventions for dynamic pages
When the IDE generates the Java code for a dynamic page, the page becomes
a Java class.
All the dynamic pages in a project are placed in the same package,
regardless of the directory structure you may have set up within the
project. This means that page names must be unique to the entire
project, since class names must be unique within a package. (Note: you
can have source pages in different packages; this rule applies only to
dynamic pages.)
The IDE prepends “Hs" to the page name, so that a page named Welcome
would become the class HsWelcome.
Any valid filename can be used as a page name. When it generates the
class name, the IDE converts non-alphanumeric characters (anything
other than A-Z, a-z, and 0-9) to underscores. For example, Page 1.html,
Page_1.html, and Page$1.html would all resolve to the class HsPage_1.
Calling a dynamic page from Java
When a user browses a dynamic page for the first time, HAHTsite instantiates
the page object and invokes its run method. If the user returns to the same
page, rather than instantiating the page again, HAHTsite uses a reference to
that page.
You can do the same thing in your application, when you call a dynamic page
programmatically. In a Java application, you instantiate a dynamic page by
calling the Session object’s returnHAHTPageObject method and passing it the

Chapter 2: Working with Java Projects
fully-qualified page name (that is, packagename.classname). If the page hasn’t
already been instantiated, returnHAHTPageObject instantiates the page object
and returns a reference to it; otherwise, it simply returns the object reference.
(If for some reason, you want a new instance of the page, then you can use new
rather than returnHAHTPageObject.) You call a dynamic page by invoking its
run method.
This code instantiates a dynamic page called MyNewPage, in a project called
ExampleProj:
HAHTPage MyNewPage = hahtSession.returnHAHTPageObject
("ExampleProj.HsMyNewPage");
To call its run method, you would use this code:
MyNewPage.run(aRequest, aResponse);
Event handling in a Java project
If you look at the code for HahtApplication.java and HahtSession.java,
you’ll see several methods that are triggered when an application or a session
starts or ends. In a Java project, you can add your own code to these six
methods:
Application
method
Description
onStart Called right after a new application is created, but before any
pages are run.
onEnd Called just before an application is destroyed.
onSessionStart Called when a new session is created, but before any pages
are run. (Called for each session. This method is called before
the Session object’s onStart method.)
onSessionEnd Called just before a session is destroyed. (Called for each
session. This method is called after the Session object’s
onEnd method.)
31

Chapter 2: Working with Java Projects
When are these methods useful? In the Session object’s onStart method, you
could populate a session recordset for use by subsequent pages in the session
— for example, you might want to read in the values of a database table (a
catalog, say) that’s used by several different pages. In the onEnd method, you
might want to save the session state, so that you can restore it later if the user
returns to the application.
If onStart fails, the Application Server calls onEnd and terminates the
application or session without running any pages. There are two ways for
onStart to fail:
32
Session method Description
onStart Called when a new session is created, but before any pages
are run. (Called once, for the current session.)
onEnd Called just before a session is destroyed. (Called once, for the
current session.) Note: onEnd is called even if onStart fails.
You can throw a runtime exception, such as this:
throw new RuntimeException("Failed in onStart");
In this case, the Application Server calls onEnd, generates a runtime error
message, and terminates the session.
You can edit the onStart method to produce a custom diagnostic page.
Generally, after producing a diagnostic page, you want to prevent any
further running of the session and any further error output from the
Application Server, so you should also call the Session object’s abandon
method, which calls onEnd and terminates the session.
Java
Response aResponse = Haht.getResponse();
aResponse.setContentType("text/html");
aResponse.endHeaders();
aResponse.write("Exiting the session ");
aResponse.write("Failed in onStart ");
// Abandon the session
Haht.getSession().abandon();
The onEnd methods are passed an ApplicationEvent or SessionEvent object.
By calling this object’s getReason method, you can determine the reason for
the event. For a session ending, the available reasons are:

Chapter 2: Working with Java Projects
SessionEvent.SESSION_TIMEOUT -— session timed out normally
SessionEvent.SESSION_STOP_END — session was stopped by a call to the
abandon method
SessionEvent.SESSION_TERMINATED — session was terminated by an
administrator
SessionEvent.SESSION_START_ERROR — the onStart method threw an
exception
The example that follows uses the Application object’s onSessionStart and
onSessionEnd methods to update a variable that tracks active sessions.
Example: onSessionStart, onSessionEnd
Suppose you want to keep track of the number of currently-active sessions in
an application. At any point in the application, you want to be able to print
out this information.
You might begin by creating a static variable, called nActiveSessions, in the
HahtApplication class. Notice two particular methods in this class —
onSessionStart, which is called each time a session is started, and
onSessionEnd, which is called when a session times out. You can add code to
those methods to increment and decrement nActiveSessions appropriately.
You’ll also want to add a method to return the value of nActiveSessions. Here
is the code in the HahtApplication class (ellipses mark “boilerplate” code that
has been omitted).
33

Chapter 2: Working with Java Projects
34
Java
/**
* ExamplProj.HahtApplication.java
**/
////////////////////////////////////////////////////////////////
// PACKAGE
////////////////////////////////////////////////////////////////
package ExamplProj;
///////////////////////////////////////////////////////////
// IMPORTS
///////////////////////////////////////////////////////////
import com.haht.*;
import com.haht.project.*;
/**
* HahtApplication class
*
* Represents a HAHTsite web application.
* Put customizations for an application in this class.
*
* This class is derived from GeneratedApplication.
* GeneratedApplication is built by the HAHTsite IDE
* according to your project configuration.
*
* @version
* @author
*
* @see ExamplProj.GeneratedApplication
* @see com.haht.project.Application
*
**/
public class HahtApplication extends
ExamplProj.GeneratedApplication
{
/**
* Default constructor for HahtApplication
**/
public HahtApplication()
{
}

Java
Chapter 2: Working with Java Projects
/**
* Called when a new session is being created.
*
* @param anEvent Describes details about the event.
*
**/
public void onSessionStart
(com.haht.project.SessionEvent anEvent)
{
// As each session starts, increment total count
nActiveSessions++;
}
/**
* Called right before a session is destroyed.
*
* @param anEvent Describes details about the event.
*
**/
public void onSessionEnd
(com.haht.project.SessionEvent anEvent)
{
// As each session ends, decrement total count
nActiveSessions--;
}
/**
* Called when a new application is being created.
*
* @param anEvent Describes details about the event.
*
**/
public void onStart(com.haht.project.ApplicationEvent
anEvent)
{
}
35

Chapter 2: Working with Java Projects
Java
}
Now you’re ready to add some in-line code to a dynamic page. The line shown
below contains text and an expression calling the method you added to return
the number of active sessions. It also prints the current date and time.
36
/**
* Called right before a application is destroyed.
*
* @param anEvent Describes details about the event.
*
**/
public void onEnd(com.haht.project.ApplicationEvent
anEvent)
{
}
/*
* Keep track of number of currently-active sessions
*/
private static int nActiveSessions=0;
public int getActiveSessionCount()
{
return nActiveSessions;
}
At [insert DateTime widget] there are
hahtApplication.getActiveSessionCount() active sessions.
The generated code for a dynamic page automatically defines
hahtApplication and hahtSession to refer to the Application and Session
objects, respectively, and casts them appropriately. You can use both these
references anywhere in a dynamic page. For more information, see
“Application and Session references in a dynamic page” on page 92.
(By the way, if you try this example, at runtime you may notice a lag between
the time a user leaves the application and the time the onSessionEnd method
is called. This is due to the session timeout; see “Session timeout” on page
108.)

Editing and compiling Java code
Chapter 2: Working with Java Projects
This section explains the mechanics of writing Java code in the IDE:
Using the code editor
Compiling a Java application
Working with application directories
Using the code editor
When you open a source file into the IDE’s Code window, the Select
Object/Select Event combo boxes contain the names of the file’s objects and
methods.
To jump to an object or method in the source code
Select its name from the combo box.
To move to the next or previous method on the page
Click the up or down arrow.
To jump to a specific line of code
1 Click inside the source file (open in the code editor) and choose Edit > Go
to.... The Go to line dialog appears.
37

Chapter 2: Working with Java Projects
2 In the Line number field, enter the line number from the compiler’s error
message.
3 Click OK. The cursor’s line number is displayed in the lower right-hand
corner of the IDE’s window.
To hide (or make visible) the code on a page
38
Select View > Code as Icon. All the code on the page is toggled between
viewing as icon or viewing as text.
To view more than one file in a split window
Select Window > Tile.
The files that are open in the workspace are tiled (to a maximum of four files),
so that you can view one file while you’re editing another.
Compiling a Java application
When you publish a Java project, the IDE converts each dynamic page to a
Java code (.java) file. Then it compiles all Java code, including source pages,
generating class files that it publishes to the project’s application root
directory (server-side code) or static root directory (applets).
You can also compile a single file — for example, to check for syntax errors:
With the file open in the code editor, select Java > Build. (This option is not
available for dynamic pages.)
Note - If a file is not compiled as you expected, be sure that you
have identified it correctly to the project as server-side, applet,
servlet, or common. To check (and optionally change) this
identification, see “Changing the Java file type” on page 41.
A Java application is compiled using the options set in the IDE, using the Tools
> Options > Java Options dialog. For each type of Java source file — server-side,
applet, servlet, or common — the IDE has a profile, specifying the path to the
default compiler as well as the classpath and output directory. When you
install the IDE, these profiles are created with default values, but you can

Chapter 2: Working with Java Projects
modify the profiles, and you can override the defaults for a particular project
and/or for any Java source file in the project. For more information, see
“Overriding Java compiler options” on page 42.
Again by default, server-side and common JAR files are automatically added to
the compile-time and runtime classpath, but applet and servlet JARs are not.
You can override this default behavior for any JAR file in your project. (This
information applies to CAB and ZIP files as well.) For more information, see
“Overriding options for JAR, CAB, and ZIP files” on page 43.
Finding compile-time errors
If the Java compiler finds a syntax error in your Java code, it sends an error
message to the project’s Build/Publish window. In many cases, you can see
what the problem is by looking at the error message. (Recall that the Java
compiler options set the amount of parsing for error messages. Choose Tools
> Options > Java, and edit your server-side Java compiler profile.)
To navigate the compiler’s error messages
You can scroll through the messages in the Build/Publish window,
double-clicking on any message with a “+” to expand it. If you doubleclick
the error message, the IDE opens the file if necessary and displays
the relevant line.
Or you can choose Edit > Find Error > [First, Next] to go to that particular
error in the Build/Publish window. The IDE opens the file if necessary
and displays the relevant line.
Debugging a Java application
HAHTsite includes a source-level debugger that lets you debug HAHTsite Java
applications, even remotely. You must compile the Java application with the
debug option set: from the Build Type combo box in the IDE’s toolbar, choose
Debug. (This is the default.)
For more information about running the debugger, see Chapter 15,
“Debugging Server-side Code.”
Working with application directories
HAHTsite Java applications use three special directories: the static root
directory, userroot, and approot. You set these directory locations when you
install the IDE and Application Server or when you modify their
configurations. These root directories are shared by all applications within a
39

Chapter 2: Working with Java Projects
particular server group, but you can differentiate between them by using the
subdirectory macros %project% and/or %username%. (Otherwise, files from one
project could overwrite files with the same name from another project.)
Static root directory
The static root directory is the directory where the Web server gets the
application’s static pages (.htm and .html files), graphics files, and any other
files not run by the HAHTsite Application Server.
40
Note - “Secure static” pages are stored in the project’s approot
directory.
To retrieve the directory pathname (in either NT or UNIX format, depending
on the operating system), you could use code like this:
String myStaticRoot = hahtApplication.getStaticRoot();
To retrieve the URL for the static-page directory, you could use code like this:
String myStaticURL = hahtSession.getStaticURL();
Userroot and approot
The userroot and approot directories are used by the HAHTsite Application
Server.
userroot is the application’s initial working directory. At runtime, a
HAHTsite application has a current, or “initial working” directory on the
server. In your Java code, if you read or write a file by specifying just the
file’s name, the application looks for the file in the application’s initial
working directory. To retrieve this pathname, you could use code like
this:
String myUserRoot = hahtApplication.getUserRoot();
approot, the application root directory, is the directory in which a
HAHTsite Application Server finds an application’s executable files
(.class, .jar, .zip, and .cab files), as well as its “secure static” pages. To
check where the project’s executable files were published, relative to the
approot directory, you could use code like this:
String myAppDir = hahtApplication.getDirName();
If the method returns “\” or “/”, the files were published directly to the
application root directory. Otherwise, the method returns the path to the
subdirectory. (Note that this method does not return the full path to the
application root directory.)
You may also notice a javaroot directory, which holds Java class files for a
HAHTtalk project, but which is not used by Java projects.

Java options
Chapter 2: Working with Java Projects
In the IDE, the Tools > Options > Java Options dialog defines the default
compiler and compile-time options, such as classpath and output directory,
that apply to your Java files. However, for any project, and for any Java source
file within a project, you can override both the default compiler and the
compile-time options. And for any JAR, CAB, and ZIP file, you can specify
whether it should be included in the compile-time and/or runtime classpath.
You can also view and change the Java file type.
Changing the Java file type
The General properties of a Java source file list its name and Java file type:
server-side, applet, servlet, or common. If you create or import a file but
specify the wrong type, you can change the type on this property sheet.
1 In the project window, select the filename and choose Edit > Properties.
2 From the drop-down list in the Type field, select a new type. For more
information on the Java file types, see “Adding Java files to a project” on
page 26.
41

Chapter 2: Working with Java Projects
Overriding Java compiler options
If you override Java options at the project level, the new options will apply
throughout your project. However, you can also specify overrides at the file
level.
1 To override Java options at the project level:
42
In the project window, select the project name and choose Edit >
Properties.....
Click the Java Compiler tab.
You will see a list of Java file types, and the default compiler for each.
To modify the default for a particular file type, select it and click
Modify....
2 To override source-file options:
In the project window, select the filename and choose Edit >
Properties.
Click the Java Compiler tab.
3 The Java Compiler dialog appears.

Chapter 2: Working with Java Projects
4 To override the default compiler, uncheck the Use Default Compiler box,
and select a compiler from the drop-down list. The compiler must have
been previously defined in the Tools > Options > Java Options dialog.
5 To override the compiler settings, check the Override Compiler Settings
box. The boxes below will no longer be grayed out, and you can define a
different classpath, output directory, or other compiler option. For details
on setting these options, see the “Java Options” section of the HAHTsite
IDE and IP User’s Guide, Chapter 2, “Using the IDE/IP’s Windows and
Toolbars.”
Overriding options for JAR, CAB, and ZIP files
JAR, CAB, and ZIP files are treated differently in a HAHTsite project, depending
on whether you identify them as server-side, applet, servlet, or common files.
(For brevity’s sake, this section refers only to JARs, but the information applies
equally to JAR, CAB, and ZIP files.)
Server-side and common JARs are automatically added to the project via the
%(ProjectJars) macro in the compile-time classpath. When you publish your
project, the Application Server also automatically adds the JAR file to the
runtime classpath for the application.
43

Chapter 2: Working with Java Projects
By default, applet and servlet JARs are not automatically added to either the
compile-time classpath or the application’s runtime classpath.
You can change the compile-time or runtime defaults for a specific JAR file,
using the Jar Properties dialog in the project window.
1 In the project window, click on a JAR file to select it. The Jar Properties
dialog appears.
2 Respond to the prompts:
44
Item Description
Type To change the type of JAR file (server-side, applet,
servlet, or common), make another selection from
the drop-down box.
Add to compiler class
path
Add to project’s
runtime class path in
application server
Check if you want this JAR added to the compiletime
class path.
Check if you want this JAR added to the runtime
classpath.

Working with
HAHTtalk Basic
Projects
3
What’s in this chapter ....................................................................................46
Adding server-side code to a HAHTtalk Basic project ...................................46
In-line code ................................................................................................48
Invoking an expression or a subroutine from a dialog box ....................50
Adding code in Server-side Code view .....................................................52
What’s in a HAHTtalk Basic page?............................................................53
Adding HAHTtalk Basic files to a project .................................................60
Naming conventions for HAHTtalk Basic projects........................................62
Include files and Globals.hbs .........................................................................63
Project and external includes....................................................................63
Declaring public variables with Globals.hbs ............................................64
Precompiler directives ...............................................................................64
Calling dynamic pages from HAHTtalk Basic................................................65
Event handling in a HAHTtalk Basic project.................................................66
Editing and compiling HAHTtalk Basic code ................................................67
Using the code editor ................................................................................67
Compiling a HAHTtalk Basic application.................................................69
Finding compile-time errors......................................................................69
Debugging a HAHTtalk Basic application.................................................70
Working with application directories .......................................................70
Comparing HAHTtalk Basic and Visual Basic................................................72
45

Chapter 3: Working with HAHTtalk Basic Projects
What’s in this chapter
The first half of this chapter explains how to add server-side code — that is,
code that runs on the Application Server — to a HAHTtalk Basic project. The
second half of the chapter explains the mechanics of working with the code
editor and compiling the code.
Later chapters in this book give detailed explanations, with examples, of ways
you can extend your HAHTsite application programmatically. For complete
information about specific classes and methods, refer to the HAHTsite Server
Object Model and the HAHTtalk Reference in the online help.
In addition, if you are interested in further customizing your application with
client-side scripts and applets, then be sure to look at these chapters:
46
In this book: Chapter 10, “Working with Client-side Scripts”
In the HAHTsite IDE and IP User’s Guide: Chapter 20, “Applets and
Multimedia Objects”
Adding server-side code to a HAHTtalk
Basic project
With HAHTtalk Basic, you can easily extend the functionality of your
HAHTsite Web applications beyond what you can do with HTML or CGI
programs. In a HAHTsite HAHTtalk Basic project, you can use HAHTtalk Basic
in these ways:
1 You can add in-line code to a page, intermixed with other HAHTsite
elements such as text, pictures, and forms. The code can be a simple
expression, a single line, or a complete block of code. See “In-line code”
on page 48.
2 You can insert expressions and method calls in many of the dialogs in the
IDE — for example, a text box can be initialized with the value of an
expression, and a form’s action can be a call to a HAHTtalk Basic
subroutine. See “Invoking an expression or a subroutine from a dialog
box” on page 50.
3 You can insert code in predefined places within the source code for a page,
using the HTML editor’s Server-side Code view. See “Adding code in
Server-side Code view” on page 52.

Chapter 3: Working with HAHTtalk Basic Projects
4 You can create separate source files, with functions and subroutines that
can be shared by all of the pages in an project and that can be reused in
other projects. In addition to creating or importing HAHTtalk Basic source
files, you can import compiled HAHTtalk Basic files as well. See “Adding
HAHTtalk Basic files to a project” on page 60.
HAHTsite Server Object Model
Much of this book describes classes and methods in HAHTsite’s Server Object
Model, which controls the structure of a HAHTsite Web application. With the
Server Object Model, you can perform tasks such as reading data passed on the
URL, writing HTML data, and controlling session timeout, as well as managing
data source connections, setting form field values, and controlling access to
dynamic pages.
The Server Object Model is implemented in Java. However, it is equally
accessible from HAHTtalk Basic projects, and the online help for the Server
Object Model shows both the Java and HAHTtalk Basic syntax to call each
method. A few methods are not meaningful in a HAHTtalk Basic project, and
for those methods the syntax is shown as “n.a.”
For more information about Java, you may wish to look at Chapter 4, “Calling
Server-side Java from HAHTtalk Basic.” You may already be familiar with
calling CreateObject or CreateJavaObject, to access COM objects or Java
objects from Basic. However, HAHTsite’s Server Object Model has a set of builtin
objects. You do not need to instantiate them in order to call their methods.
External logic
From your HAHTtalk Basic code you also have access to capabilities such as
CORBA, COM/DCOM, and native methods. For more information, see the
table below.
External logic Where described
Server-side Java Chapter 4, “Calling Server-side Java from
HAHTtalk Basic”
CORBA Chapter 14, “HAHTsite CORBA Capabilities”
COM/DCOM Chapter 13, “Connecting to COM Objects”
ActiveX object calls Online help
Database Stored Procedure Calls Chapter 8, “Data-Agent Programming”
47

Chapter 3: Working with HAHTtalk Basic Projects
External logic Where described
In-line code
The ability to intermix HAHTtalk Basic code with other elements (such as text,
pictures, Widgets, and form elements) gives you a powerful tool for
dynamically changing the content of Web pages. You can use this technique
for many purposes — for example:
48
Windows DDE calls Online help
Sending SMTP email messages Online help
FTP operations to a remote server Online help
Using the shell command to
create an external process
Online help
Socket operations Online help
UNIX API system calls
Windows API systems calls Online help
to control the flow of logic on the page
to create “internationalized” pages that contain text in different
languages from which a user can select
to modify values read in from a database or from the URL
To maintain the WYSIWYG look of your pages, you’ll probably want to
minimize the amount of code that you place directly onto a page. You can do
this by creating functions and subroutines in a project’s source pages and
calling them from your Web pages. With this approach, you can also share
functions and subroutines among the project’s Web pages.
This example shows a form whose first-name and last-name text box values are
being overridden by global variables from in-line code at the top of the page.

Chapter 3: Working with HAHTtalk Basic Projects
Besides adding entire lines of code, you can also add expressions. An expression
can include variables, constants, operators, and functions, as long as it resolves
to a single value. Here are two examples:
Date$
Haht.getRequest().getURLField("txtCity")
In the HAHTtalk Basic source, the IDE includes the expression in a Print
statement.
To add a HAHTtalk Basic expression to an HTML page
1 On the page, click where you want the expression to appear.
2 Click the Server-side Expression button .
3 Type the expression.
4 By default, expressions are displayed in red in the HTML editor. However,
you can override this setting in Tools > Options > Editor.
To add a statement to an HTML page
1 On the page, click where you want the statement to appear.
2 Click the Server-side Statement button .
3 Type one or more statements.
4 By default, statements are displayed in blue in the HTML editor.
49

Chapter 3: Working with HAHTtalk Basic Projects
To convert existing text to an expression or statement
1 Select the text you want to convert.
2 Click either the Server-side Expression button or the Server-side
Statement button .
To format the output of an expression or statement
You can format the output of a HAHTtalk Basic expression or statement, just
as you can format text that you type directly on the page.
1 Select the paragraph or characters you want to affect.
2 To modify the paragraph properties, choose Edit > Paragraph... or make a
selection from the Paragraph Styles toolbar.
3 To modify the character properties, choose Edit > Character.... or make a
selection from the Character Styles toolbar. (If you modify the font color,
the new color will be displayed in the browser, but not in the IDE.)
Invoking an expression or a subroutine from a dialog
box
The second way you can customize your project is by invoking expressions or
subroutines inside a dialog box — for example, to set link properties or form
properties. From the HAHTsite IDE and IP User’s Guide, you’re probably aware
of the many places in property-sheet dialog boxes that allow you to use an
expression rather than a field name or a constant, or that allow you to call a
subroutine instead of a dynamic page as a link or form action.
Dialog box expressions
To substitute an expression for a field name or constant, prefix the expression
with "==". For example, in the link properties, you could set the query string
to contain the value of the (String) variable "CityCode":
Code=/*==CityCode*/
50

Chapter 3: Working with HAHTtalk Basic Projects
On the destination page, you could retrieve the information this way:
Print aRequest.getURLField("Code")
Notice in the example the use of "/*" and "*/" bracketing the expression. You
must use this construction when you want to use an expression in a
name/value attribute pair, or when it appears in the middle of a script.
However, if you simply want to set an attribute to the value of an expression,
you can use ==expression.
The expression must evaluate to a character string.
Dialog box subroutine calls
In addition to using expressions, you can call user-defined subroutines (not
functions) from several dialogs in the IDE, such as the Form Properties dialog
and the Link Properties dialog. For example:
A subroutine can generate the binary data to display a picture, an image
map, or a multimedia object.
It can be the destination for a dynamic link (the value of an HREF
attribute tag).
51

Chapter 3: Working with HAHTtalk Basic Projects
52
It can be the default action that takes place when the user submits a
form, or the action tied to one of the form’s buttons.
Obviously, the content of your subroutine will be determined primarily by
what you want it to do. However, if its effect is to display a page, it should emit
the ... and and HTML tags.
For an annotated view of a typical page, see “What’s in a HAHTtalk Basic
page?” on page 53.
Adding code in Server-side Code view
The third way to customize your project is to add directly to the server-side
code for a page. When you build or publish your project, the IDE generates a
pagename.hbs file for every dynamic page. (These generated files are stored in
your project’s sites directory and don’t appear in the project window.) If you
add in-line code to the page, it’s inserted in the HAHTtalk Basic source.
However, you may want to make other additions to the code for a page — for
example, you might want to add an include statement, add some initialization
code, or add variables to the page. The HTML editor’s Server-side Code view
lets you view the source code for a page, and lets you make additions, in
predefined places, that will be preserved when the page is regenerated. (Note
- you cannot change the generated source code; you can only add to it.)
To view and add to the server-side code for a page
1 Open the page in the HTML editor.
2 Select View > Server-side Code, or click the Server-side Code view button
. Here are some points to note:
The white areas mark places where you can insert code.
The grayed-out areas mark generated source code, which is read-only.
If you make changes in Server-side Code view, and then return to
Normal view or HTML Tags view, you will see your changes reflected.
If the Server-side Code view button is disabled, be sure that you have
saved the page (and that it is dynamic).
For more information on this process, see the note that follows.
Behind the scenes: How does Server-side Code view work?
To keep from overwriting your additions, the IDE must keep your code
separate from the code it generates. When you add code in Server-side Code
view, your code is translated into HTML tags and kept in the project’s HTML

Chapter 3: Working with HAHTtalk Basic Projects
file for this page. If you look at the page in HTML tags view, you will see
sections like this:
When you build or publish the project, the code for the dynamic page is
generated from the HTML file.
What’s in a HAHTtalk Basic page?
When you publish a project, for each dynamic page, the IDE generates a file
(pagename.hbs) that includes a constructor and an entry point for
HS_pagename. The source code for each dynamic page has these contents.
Note - Much of what you see in Server-side Code view for a
HAHTtalk Basic page is generated for use by the IDE/IP’s dialog
boxes and can be ignored. In the example that follows, ellipses
mark code that has been omitted.
A place for include files
Type definitions
A page "constructor"
A form handler
An entry point for the page
An exit handler
An error handler
The following sections explain each of these topics, using as an example the
HAHTtalk Basic source for a page that simply displays the current date.
A place for include files
You can use the HAHTtalk Basic #include directive to include in a page one or
more files that contain HAHTtalk Basic declarations. HAHTsite also supports a
per-project Globals.hbs code page, which you can use to declare session
“global” variables that can be accessed by all of the HAHTtalk Basic code in a
project. (If this file is present in your project, its contents are automatically
prepended to each .hbs file.) For more information, see “Include files and
Globals.hbs” on page 63.
53

Chapter 3: Working with HAHTtalk Basic Projects
' Generated by HAHTsite
' Includes. Includes can only be at the top of the file,
' and should not have code in them.
Type definitions
The page defines two constants that can be useful in Print statements:
Const HSQUOT = Chr$(34)
Const HSCRLF = Chr$(13) & Chr$(10)
HSQUOT produces quotation marks; use this constant when you want to embed
quotation marks in a printed string. HSCRLF (carriage return/line feed) forces a
line break in the HTML source file. (Remember that line breaks in HTML
source files are ignored; if you want a line break in the displayed HTML, you
will still need to add tags such as "" or "...".)
You can add your own public or private variables, functions, or subroutines in
the marked places of this section. For example, you might want to add a
subroutine to be called as the “success” or “failure” page from a database
action of a form button on this page.
54
' Imports and includes.
' Type definitions.
' Privates
' Publish-code-generation helper variables - do not remove!
Private Haht_TempJavaObj As Object
' Used for static-finals from Java Classes, temp java objects
Private Haht_Page as Object
Private HS_ShowDate_Construct_Called As Boolean
' User-defined private variables.
' More user-defined private variables.
' Private Functions and Subs
' User-defined private functions and subs.

Chapter 3: Working with HAHTtalk Basic Projects
' More user-defined private functions and subroutines.
' Public variables
Const HSCRLF = Chr$(13) & Chr$(10)
Const HSQUOT = Chr$(34)
' User-defined public variables.
' Public Functions and Subs
' User-defined public functions and subs.
' User-defined functions and subroutines.
A page "constructor"
This code is called the first time this page is browsed in a session. You can add
custom code to the constructor.
' Constructor for page. Called once per page per state.
Private Function HS_ShowDate_Construct() As Boolean
On Error Goto HAHTErrorHandler_cons
Dim aResponse As Object
Set Haht_Page = Haht.getPage()
HS_ShowDate_Construct = TRUE
If (HS_ShowDate_Construct_Called) Then
Exit Function
Else
HS_ShowDate_Construct_Called = TRUE
End If
...
' Custom constructor code. This code executes
' the first time a page is called.
' Custom initialization code
' for user-defined static variables.
55

Chapter 3: Working with HAHTtalk Basic Projects
A form handler
If your page contains one or more forms with buttons, then the Type
Definitions section of your code will contain this line:
#CONST HAHT_FORM_HANDLER_DEFINED=1
and the form handler code (enclosed by an #If statement) will execute.
The generated code for a page’s form handler adapts to the contents of the
page. At runtime, when a user submits a form, the form handler determines
which button was clicked and calls the appropriate command handler. In a
HAHTtalk Basic project, you can create a custom form handler. You can also
add your own code to process a Submit button, via the “User Code” choice in
the button’s Action field. For more information, see Chapter 8, “Data-Agent
Programming.”
56

Chapter 3: Working with HAHTtalk Basic Projects
#If (HAHT_FORM_HANDLER_DEFINED=1) Then
' Form handler
Public Sub HS_ShowDate_fH
Dim bCmdHandlerCalled As Boolean
Dim thePage As Object, theErrors As Object
Dim aResponse As Object
Set aResponse = Haht.getResponse()
On Error Goto HAHTErrorHandler_fH
bCmdHandlerCalled = False
If (Not bCmdHandlerCalled) Then
Set thePage = Haht.getPage()
Set theErrors = thePage.getErrors()
theErrors.add "Received form command did not _
invoke a command-handler", "form-handler"
Set thePage = Nothing
Set theErrors = Nothing
HS_ShowDate
End If
HAHTExitHandler_fH:
Exit Sub
HAHTErrorHandler_fH:
aResponse.addHeaderLine "Content-type: text/html"
Print ""
Print ""
Print "The following error has occurred on page _
HS_ShowDate on line " & Str$(erl);
If (Err.Source "") Then
Print " of script " & Err.Source;
End If
Print ": " & Str$(Err) & " - " & Error & "";
Print ""
Resume HAHTExitHandler_fH
End Sub
#End If
An entry point for the page
Each dynamic page has an entry point, named HS_pagename. This is the
subroutine name you would use to call the page. The subroutine emits any
header lines — for example,
Content-type: text/html
57

Chapter 3: Working with HAHTtalk Basic Projects
Note that you can override the content-type header by another call to the
Response object’s setContentType method. See “Adding content information
to a header line” on page 127.
After emitting header lines, the subroutine then sets up the basic structure of
the page, which would look like this in HTML:
...
...
When you add in-line code to a page, it’s added here, between the and
tags. (However, for information about output that must go in the
HTTP headers, see “Writing headers” on page 126.)
' Entry point for page
Sub HS_ShowDate()
' Local variables
Dim aResponse As Object
Dim aRequest As Object
Dim out As Object
On Error Goto HAHTErrorHandler
58
' Custom local variables. These are instantiated
' each time the page is run.
' Initialize local variables.
Set aResponse = Haht.getResponse()
Set aRequest = Haht.getRequest()
Set out = aResponse.getWriter()
If (Not HS_ShowDate_Construct()) Then
' Constructor failed - exit page
Exit Sub
End If
' Custom initialization code. Executes before
' HTML tags are generated.
' Output HTTP response headers.
' Custom HTTP response headers. Add HTTP headers here.

Chapter 3: Working with HAHTtalk Basic Projects
aResponse.addHeaderLine "Content-type: text/html"
Print HSCRLF
' More custom HTTP response headers.
' Add HTTP headers here.
' Generate HTML for browser.
print "" & HSCRLF _
& "" & HSCRLF _
& " " & HSCRLF _
& " ShowDate" & HSCRLF _
& "" & HSCRLF _
& "" & HSCRLF _
& " " ;
Print date$
Object references you can use
The code shown above gets references to the Request and Response objects, as
well as the default HtmlWriter. You can use aRequest and aResponse to read
values sent by the Web server or to write HTML. For example, to read a value
passed in a form or on the URL, you would call aRequest.getURLField.
This code also gets a reference to the default HtmlWriter. To write HTML
output programmatically, you simply call the Print statement. You can also
intermix text and in-line code on a page. In the HAHTtalk Basic source, the
text turns into Print statements.
For more information about these objects, see Chapter 5, “HAHTsite Server
Object Model.”
An exit handler
print "" & HSCRLF _
& "" & HSCRLF _
& "" ;
' All HTML has been generated. Put cleanup code here.
In addition to a default error handler, each page has an exit handler label
called HAHTExitHandler, which simply exits the subroutine. If you want to exit
a page, you can write a GoTo HAHTExitHandler statement.
59

Chapter 3: Working with HAHTtalk Basic Projects
HAHTExitHandler:
Exit Sub
An error handler
Each dynamic page includes a default error handler and an On Error Goto
statement that traps page-level errors. You can add code to the default error
handler, and you can also include your own HAHTtalk Basic On Error
construct in your subroutines. Your “On Error” construct will be nested inside
the default error handler and will trap subroutine-level errors.
HAHTErrorHandler:
' Handle errors that occur on the page.
Adding HAHTtalk Basic files to a project
Another way to add server-side code to your project is to create a source file or
import a source file or object file to be used by any of a project’s dynamic
pages.
Code pages are source code files containing subroutines or functions written
in HAHTtalk Basic. These subroutines and functions must have unique
(project-wide) names, and they can be called by any of a project’s dynamic
pages. For example, the in-line code on an HTML page can call a subroutine to
process some data. Or you can set a form’s action to call a subroutine which
either creates or calls a dynamic page. A subroutine can generate the binary
60
If (aResponse.getContentType() = "") Then
aResponse.addHeaderLine "Content-type: text/html"
Print ""
End If
' Close any table tags that may be open.
Print ""
Print "The following error has occurred on page _
HS_ShowDate on line " & Str$(erl);
If (Err.Source "") Then
Print " of script " & Err.Source;
End If
Print ": " & Str$(Err) & " - " & Error & "";
' Handle errors that occur on the page.
Resume HAHTExitHandler

Chapter 3: Working with HAHTtalk Basic Projects
data to display a picture or create a dynamic link and then print the link in an
HTML anchor tag on the page.
In a HAHTtalk Basic project, code pages are stored in the Web folder, usually in
a subfolder.
To add a new code page
1 Choose File > New > Code.
2 A blank code page opens in the workspace.
3 Enter HAHTtalk Basic subroutines or functions. For information about
using the IDE’s code editor, see “Editing and compiling HAHTtalk Basic
code” on page 67.
To import a code page
In addition to creating new code pages in your project, you can import
existing source code files.
1 In the project window, click on the folder in which you want to store the
new file.
2 Choose File > Import File.... The Import Files dialog appears.
3 Type or browse for one or more filenames.
4 Choose Copy Files or Create Shortcuts. If you want to maintain one
central version of this file but use it in several projects, you may want to
create a shortcut.
5 Click OK to complete the import.
For more information about importing files into the IDE, consult the HAHTsite
IDE and IP User’s Guide, Chapter 3, “Managing Projects.”
To save a code page
1 Select File > Save. The Save Code Page As dialog appears.
2 Type in a page name, or accept the default name. The suffix must be
".hbs".
3 To save the code page within the project, browse within the Project Items
window for the folder name you want.
4 If the project is in source control, you will see an additional checkbox: Add
to source control. Check this box to add this file to the source control
system.
5 Click OK to save your changes.
61

Chapter 3: Working with HAHTtalk Basic Projects
To save a code page outside the project
To be called from within the project, a code page must be saved within the
project. However, you can also save a code page to a file outside the project.
1 Select File > Save. The Save Code Page As dialog appears.
2 Click the Save to File... button. The Save As dialog appears.
3 Browse for a folder location and enter a filename.
4 Click OK to save your changes.
Naming conventions for HAHTtalk Basic
projects
Code pages and dynamic pages represent entry points into the application’s
symbol table (.htx) file that HAHTsite creates when you publish a project.
During the publish operation, HAHTsite converts dynamic pages into
HAHTtalk Basic subroutines and prepends the characters “HS_” to the
resulting subroutine names. (Subroutine names in code pages are not
changed.) The name assigned to a dynamic page’s subroutine is determined as
follows:
62
The dynamic-page name is preceded with the characters HS_.
Any illegal character — that is, anything other than an alphabetic or
numeric character — is converted to the underscore (_) character.
As a result of this conversion process, dynamic pages with similar names could
be converted to subroutines with the same name. For example, the IDE
converts the names “2-Page” and “2 Page” to “HS_2_Page.” Creating multiple
pages that result in HAHTtalk Basic subroutines with the same name causes an
error at publish time.
To prevent this type of error, you can accept the default page names that
HAHTsite provides. Or you can establish a page naming convention such that
all dynamic page names consist of letters and numbers only.

Include files and Globals.hbs
Chapter 3: Working with HAHTtalk Basic Projects
The HAHTtalk Basic #include directive is similar to the #include directive
used in C and C++. Here is a summary of the rules for using the #include
directive and creating an include file.
Rules for using an include file
A file can have multiple #include directives. However, the directives
must be at the top of a page, before any executable HAHTtalk Basic code.
The #include directives must appear on a code page, not an HTML page.
You can add #includes to an HTML page in Server-side Code view. (You
can then access their contents from in-line expressions and statements
on the HTML page.)
Pathnames in the #include directives use HAHTsite project-style (UNIXstyle)
directory delimiters (“/”).
You can indent the #include directive with spaces or tab characters.
However, the HAHTsite compiler will not recognize the directive if it is
preceded by any characters other than spaces or tabs.
Rules for creating an include file
Include files use the “.hbh” extension.
Include files must contain only declarations — they cannot contain
executable HAHTtalk Basic code.
Include files can themselves contain #include directives (that is, nested
includes are allowed).
Project and external includes
There are two versions of the HAHTtalk Basic #include directive: the project
include and the external include.
The project include
The project include looks first for the included file in a project folder, then in
an external (to the project) path. Its basic form is:
#include "filename.hbh"
which can include subfolder names. The compiler looks for the named file in
these locations:
1 First, in the project folder containing the code page.
63

Chapter 3: Working with HAHTtalk Basic Projects
2 In the search path that you specified in the IDE’s Tools > Options >
General dialog. The path is a semi-colon separated directory list, which
enables you to search several directories (in the order that the directories
appear in the list). The default directory is HAHTsiteInstallDir/include.
The HAHTsite compiler generates an error if it cannot find the include file in
the project or in the include-directory search path.
The external include
The external include looks for the included file in an external path. Its basic
form is:
#include
which can include subfolder names as well. The compiler looks for the named
file only using the include-file search path you specified the IDE’s Tools >
Options > General dialog.
You can also use fully-qualified external directives. For example:
#include
Declaring public variables with Globals.hbs
You can declare a project’s public (global) variables in a code page named
Globals.hbs. A project can contain only one Globals.hbs, which can reside
in any project folder. Its contents are automatically prepended to every
dynamic page in the project. This file can contain project-wide constants and
declarations in addition to global variables. Globals.hbs can contain only
constants and variable declarations, not subroutines or functions. Because its
contents become part of every dynamic page, be careful not to make the
Globals.hbs file too large. You can always use #include directives to include
files on a page-by-page basis.
It’s important to understand that each session gets its own copy of these global
variables. They are not shared across sessions.
Precompiler directives
HAHTtalk code (whether on a code page or in the generated code for a
dynamic page) can contain these standard precompiler directives:
#Const
#If...Then...#Else
In addition, HAHTsite provides these predefined constants that can be used in
an #If...Then...#Else directive:
64

Constant Description
Chapter 3: Working with HAHTtalk Basic Projects
PUBLISH_OS The operating system to which this site is being
published. Available only if this information has been
entered in the Application Server administrator. If so,
it appears in the site’s .hsg file, like this:
OSType=Windows:NT
PUBLISH_WEBSERVER The name of the Web server for this site, as defined
during Application Server installation or by the Web
Server Utility. This name appears in the site’s .hca file,
like this:
WebServerName=Netscape FastTrack 3.01
PUBLISH_SITENAME The name of the site to which you are currently
publishing (i.e., the current site). This name includes
the hostname. Here is an example:
FastTrack@caleb.haht.com
PUBLISH_SERVERGROUP The name of the current server group, which appears
in the Name field of the .hsg file, like this:
Name=webapps
Calling dynamic pages from HAHTtalk
Basic
When you build a HAHTsite project, the names of the project’s dynamic Web
pages are included as subroutines in the project’s symbol table (.htx) file. The
IDE automatically prepends “HS_” to each page name, so that Page1.html
would be stored in the symbol table as HS_Page1. From HAHTtalk Basic code,
you can call a dynamic page as you would any subroutine, as in this example:
Call HS_Page1
As with any subroutine, each dynamic page in a project must have a unique
(project-wide) name.
65

Chapter 3: Working with HAHTtalk Basic Projects
Event handling in a HAHTtalk Basic project
In a HAHTtalk Basic project, initialization or termination methods are
triggered when a session starts and when it ends. By default, these methods do
nothing, but you can override them using the pseudo-methods
HahtSessionOnStart and HahtSessionOnEnd. Here are the pseudo-methods:
HahtSessionOnStart
In HahtSessionOnStart, you could populate a session recordset for use by
subsequent pages in the session — for example, you might want to read in the
values of a database table (such as a catalog) that’s used by several different
pages.
If HahtSessionOnStart fails, the Application Server terminates the session
without running any pages. Note that HahtSessionOnEnd is not called if
HahtSessionOnStart fails.
There are two ways for HahtSessionOnStart to fail:
66
Method Description
HahtSessionOnStart Called when a new session is created, but before any
pages are run. Should be declared as a function
returning a boolean value.
HahtSessionOnEnd Called just before a session is destroyed. The system also
calls this method after the application executes a
HAHTtalk Basic STOP or END statement. Should be
declared as a subroutine.
It can return False, in which case the Application Server writes a runtime
error message and terminates the session.
You can edit HahtSessionOnStart to generate a page of diagnostic
information if desired. Generally, after producing a diagnostic page, you
want to prevent any further running of the session and any further error
output from the Application Server, so you should also call End or Stop,
which terminates the session. Here is an example:

HAHTtalk Basic
HahtSessionOnEnd
Chapter 3: Working with HAHTtalk Basic Projects
Function HahtSessionOnStart As Boolean
Dim aResponse As Object
Set aResponse = Haht.getResponse()
aResponse.setContentType "text/html"
aResponse.endHeaders
aResponse.write "Exiting the session "
aResponse.write "Failed in HahtSessionOnStart "
'Terminate the session
End
End Function
Before terminating a session, the Application Server calls HahtSessionOnEnd
(except in the case where HahtSessionOnStart has failed, as noted above). At
this point, you might want to save the session state (for example), so that you
can restore it later if the user returns to the application.
Editing and compiling HAHTtalk Basic code
This section explains the mechanics of writing HAHTtalk Basic code in the
IDE:
Using the code editor
Compiling a HAHTtalk Basic application
Working with application directories
Using the code editor
When you open a source file in the IDE’s Code window, the Select object/Select
event combo boxes contain the names of the file’s objects and events.
67

Chapter 3: Working with HAHTtalk Basic Projects
To jump to an object or event in the source code
68
Select its name from the appropriate combo box.
To move to the next or previous event on the page
Click the up or down arrow.
To jump to a specific line of code
1 Click inside the source file (open in the code editor) and choose Edit > Go
to.... The Go to line dialog appears.
2 In the Line number field, enter the line number from the compiler’s error
message.
3 Click OK. The cursor’s line number is displayed in the lower right-hand
corner of the IDE’s window.

To hide (or make visible) the code on a page
Chapter 3: Working with HAHTtalk Basic Projects
Select View > Code as Icon. All the code on the page is toggled between
being shown as an icon and as text.
To view more than one file in a split window
Select Window > Tile.
The files that are open in the workspace are tiled (to a maximum of four files),
so that you can view one file while you’re editing another.
To display help for a HAHTtalk Basic keyword
On the code page, highlight a HAHTtalk Basic keyword and press F1.
Anywhere on a code page, you can press F1 to invoke the online help, which
includes information about HAHTtalk Basic and the HAHTsite Server Object
Model.
To check the syntax of HAHTtalk Basic code
You can check the syntax of a code file without running the compiler:
With a page open in the code editor, choose Script > Check Syntax.
(This option does not apply to pages open in Server-side Code view.)
Compiling a HAHTtalk Basic application
When you publish a HAHTtalk project, the IDE converts each dynamic page
to an intermediate HAHTtalk Basic code (.hbs) file. Then it compiles all
HAHTtalk Basic code, including code pages, generating binary (.hbb) files that
it publishes to the project’s application root directory.
Note - If your project includes Java source files (for server-side
Java that is called from HAHTtalk Basic), they are compiled at
the same time.
Finding compile-time errors
If the HAHTtalk Basic compiler finds a syntax error in your code, it sends an
error message to the project’s Build/Publish window. In many cases, you can
see what the problem is by looking at the error message.
To navigate the compiler’s error messages
You can scroll through the messages in the Build/Publish window,
double-clicking on any message with a “+” to expand it.
69

Chapter 3: Working with HAHTtalk Basic Projects
70
Or you can choose Edit > Find Error > [First, Next, Previous, or Last] to go
to that particular error in the Build/Publish window.
To locate an error in your source code
There are two ways to locate a particular compiler error:
Double-click on the error message in the Build/Publish window. The IDE
opens the file, if it’s not open, and displays the relevant line.
Click inside the source file (open in the code editor) and choose Edit >
Go to.... The Go to line dialog appears. In the Line number field, enter
the line number from the compiler’s error message. Then click OK.
If the error is in your in-line code, rather than a HAHTtalk Basic code file, the
IDE displays the source code for that page in Server-side Code view.
Debugging a HAHTtalk Basic application
HAHTsite includes a source-level debugger that lets you debug HAHTsite
HAHTtalk Basic applications, even remotely. No special flag needs to be set to
compile for debugging. For more information, see Chapter 15, “Debugging
Server-side Code.”
Note - If your application calls server-side Java from HAHTtalk
Basic, the Java code will be skipped over during a debugging
session.
Working with application directories
HAHTsite applications use four special directories: the staticroot directory,
userroot, approot, and javaroot. You set these directory locations when you
install the Application Server or when you modify its configuration. These
root directories are shared by all applications within a particular server group,
but you can differentiate between them by using the subdirectory macros
%project% and/or %username%. (Otherwise, files from one project could
overwrite files with the same name from another project.)
Static root directory
The static root directory is the directory where the Web server gets the
application’s static pages (.htm and .html files), graphics files, and any other
files not run by the HAHTsite Application Server.
Note - “Secure static” pages are stored in the approot directory.
See “Userroot, approot, and javaroot” on page 71.

Chapter 3: Working with HAHTtalk Basic Projects
To retrieve the directory pathnames (in either NT or UNIX format, depending
on the operating system), you would use code like this:
Dim MyStaticRoot As String
MyStaticRoot = HahtApplication.getStaticRoot()
To retrieve the URL for the static-page directory, you would use code like this:
Dim MyStaticURL As String
MyStaticURL = HahtSession.getStaticURL()
For more information about these methods and their uses, see “Retrieving
Application object properties” on page 100.
Userroot, approot, and javaroot
The userroot, approot, and javaroot directories are used by the HAHTsite
Application Server.
userroot is the application’s initial working directory. At runtime, a
HAHTsite application has a current, or “initial working,” directory on the
server. In your HAHTtalk Basic code, if you read or write a file by
specifying just the file’s name, the application looks for the file in the
application’s initial working directory. To retrieve this pathname, you can
use code like this:
Dim MyUserRoot As String
MyUserRoot = HahtApplication.getUserRoot()
approot, the application root directory, is the directory in which a
HAHTsite Application Server finds an application’s executable files (.htx,
.hbb, and .hbx files). To check where the project’s executable files were
published, relative to the approot directory, you can use code like this:
Dim MyAppDir As String
MyAppDir = HahtApplication.getDirName()
If the method returns “\” or “/”, the files were published directly to the
application root directory. Otherwise, the method returns the path to the
subdirectory. (Note that this method does not return the full path to the
application root directory.)
javaroot, the Java class directory, specifies the location of any
application-specific Java classes that you have developed. For more
information about using server-side Java with your project, see Chapter 4,
“Calling Server-side Java from HAHTtalk Basic.”
71

Chapter 3: Working with HAHTtalk Basic Projects
Comparing HAHTtalk Basic and Visual Basic
HAHTtalk Basic is fully syntax-compatible with Visual Basic. It is based on
Visual Basic 3 and incorporates some features of Visual Basic 4.
HAHTtalk Basic data types
Scalars
HAHTtalk Basic supports the following scalar data types
.
Arrays
Multidimensional arrays (of up to 60 dimensions) are supported. You can use
REDIM to redimension arrays.
Records
Records in HAHTtalk Basic are declared using the TYPE statement.
Names
Variable names in HAHTtalk Basic:
72
Must begin with a lowercase or an uppercase letter. Names cannot start
with numbers, spaces, or hyphens.
Must contain only letters, numbers, and the underscore character.
Must not be longer than 80 characters. In contrast, Visual Basic names
must not be longer than 40 characters.
Scope
boolean (2 bytes) currency (8 bytes)
integer (2 bytes) string (variable and fixed length)
long (4 bytes) date (8-byte IEEE double)
single (4 bytes) variant
double (8 bytes) object
HAHTtalk Basic variables follow the same scoping rules as Visual Basic
variables and can be Public (global) or Private. Static variables are not
supported.

Subroutines and functions
Chapter 3: Working with HAHTtalk Basic Projects
Subroutines and functions can be declared in the code blocks of any code
pages. The scope of HAHTtalk Basic subroutines and functions is global by
default. You can restrict the scope of a subroutine or function by using the
Private keyword.
A project’s HAHTtalk Basic Executable file (.htx file) contains a dictionary that
maps entry-point names to the appropriate HAHTtalk Basic object file.
File I/O
The HAHTsite Application Server supports the I/O mechanisms built into
HAHTtalk Basic. These mechanisms include:
various forms of sequential and random access to flat files
SQL statements for accessing databases through ODBC and native access
support for file and directory information, such as FileAttr, FileDate,
FileLen, ChDir, ChDrive, CurDir, MkDir, RmDir, GetAttr, and SetAttr
The HAHTsite Server Object Model provides methods for getting the
pathnames of an application’s static-page directory, dynamic-page directory,
and initial working directory (see the section “Working with application
directories” on page 70).
Error handling
HAHTtalk Basic supports the Visual Basic statements for error handling.
Unhandled runtime errors will cause the HAHTsite Application Server to
return an error page to the user. See the section “An error handler” on page 60
for more about using the HAHTtalk Basic “On Error” construct.
Code page properties
In the project window, you can set the properties of a code page.
The General tab shows the page name and path (read-only).
The Privileges tab lets you set the privileges required to access this code
page.
73

Chapter 3: Working with HAHTtalk Basic Projects
74
The Publish tab lets you specify whether or not the page should be
published, whether it should inherit its publish properties from the
parent folder, and whether it is exportable.
The File tab displays the filename and characteristics as well as the
project ID for this code page.

Calling Server-side
Java from HAHTtalk
Basic
4
Introduction....................................................................................................76
Using Java objects with HAHTtalk Basic .......................................................76
CreateJavaObject........................................................................................77
GetJavaClass...............................................................................................78
CreateTypedJavaNull .................................................................................78
Differences between HAHTtalk Basic and Java..............................................79
Java is strongly typed ................................................................................79
Parameter passing ......................................................................................80
Java is case sensitive ..................................................................................80
Locating objects.........................................................................................80
Mapping HAHTtalk Basic types to Java parameter types..............................81
Mapping Java types to HAHTtalk Basic types................................................83
Troubleshooting: Java runtime errors ............................................................84
75

Chapter 4: Calling Server-side Java from HAHTtalk Basic
Introduction
In addition to support for client-side JavaScript, Java applets, Java servlets,
VBScript, and ActiveX, HAHTsite supports calling server-side Java from
HAHTtalk Basic code with the HAHTsite Application Server’s Java Virtual
Machine. Server-side Java can be used on all the supported HAHTtalk Basic
platforms.
In addition to providing the inherent object-oriented benefits of
encapsulation, inheritance, and polymorphism, Java integration lets you take
advantage of JDBC, Java Beans, CORBA and the ever-growing supply of thirdparty
class libraries.
From your HAHTtalk Basic code, you can access Java classes as native objects
— simply declare Java objects as a HAHTtalk Basic data type, using either the
CreateJavaObject or GetJavaClass calls. You can then access a Java class’s
methods and properties directly from your HAHTtalk Basic code.
Java source files and class files are completely integrated into a HAHTsite
project’s hierarchy for easy editing, compiling, publishing, and integration
with source control and configuration management systems. You can write
the Java code for your Java source files (.java files) in the HAHTsite code editor,
which provides syntax coloring for the Java language.
For information about configuring Java compilers for your project, see the
description of Tools > Options > Java Options in the HAHTsite IDE and IP User’s
Guide, Chapter 2, “Using the IDE/IP’s Windows and Toolbars.” For
information about creating and compiling Java files, see “Editing and
compiling Java code” on page 37.
Using Java objects with HAHTtalk Basic
Creating and using Java objects with HAHTtalk Basic works much like creating
and using COM/ActiveX objects. To create a Java object, you use the
CreateJavaObject function instead of CreateObject. If you want to access a
static variable or method of a Java class, use the GetJavaClass function. You
can also obtain a null reference to a particular type of object using the function
CreateTypedJavaNull. Occasionally, you may need such a reference for use as
a parameter.
Once you have a Java object in a HAHTtalk Basic variable of type Object, you
access the Java object’s properties and methods using the "." syntax.
76

Chapter 4: Calling Server-side Java from HAHTtalk Basic
Here are descriptions of the two HAHTtalk Basic calls you use with Java.
CreateJavaObject
Syntax
Function CreateJavaObject(className[, param1, param2, _
...paramN]) As Object
Description
Creates an instance of the Java class specified in the className parameter by
calling the Java class’s constructor and passing the additional parameters.
Parameters
Parameter Type Description
className String The case-sensitive name of the Java
class.
param1...paramn Variant Parameters to pass to the constructor of
the Java class specified in the
className parameter.
Example
The following subroutine creates a Java object called MyCal from the class
HTMLCalendar, which takes a month and a year as parameters. Then the
calendar's GetMonthHTML method is called. This method returns an HTML
string showing the days of the specified month.
Sub printMonth(MyMonth As Long, MyYear as Long)
Dim MyCal As Object
Set MyCal = CreateJavaObject("HTMLCalendar", MyMonth, MyYear)
print MyCal.GetMonthHTML()
Set MyCal = Nothing
End Sub
77

Chapter 4: Calling Server-side Java from HAHTtalk Basic
GetJavaClass
Syntax
78
Function GetJavaClass(className) As Object
Description
Returns a reference to a Java class without creating an instance of the class. Use
this function to access the static properties and methods of a Java class.
Parameters
Parameter Type Description
className String The case-sensitive name of the Java
class.
Example
Static methods and properties in Java are methods and properties that can be
called without actually creating an object. For example, in Java the Math class
has a static property that holds the value of PI. In Java code, you do not need
to create a new Math object to access PI. You simply use Math.PI.
In HAHTtalk Basic, you first need to get the class. Then you can access all the
static members of the class. Here is an example.
Sub printPi()
Dim J As Object
Set J = GetJavaClass("java.lang.Math")
print J.PI ’PI is a static property of the Math class
End Sub
CreateTypedJavaNull
Syntax
Function CreateTypedJavaNull(className) As Object
Description
Returns a reference to an object of the type you specify in the className
argument. The reference will have been set to null. This reference is useful
when you want to pass a value of null as a parameter to a method. The null
must have a data type associated with it so that the Java Virtual Machine will
recognize the method’s signature.

Parameters
Parameter Type Description
Example
Chapter 4: Calling Server-side Java from HAHTtalk Basic
className String The case sensitive name of the Java
class to which you want a null
reference.
The following statements create a null reference to an object of type
HTMLCalendar:
Dim MyCal As Object
Set MyCal = CreateTypedJavaNull("HTMLCalendar")
These statements are the equivalent of the following statement in Java:
HAHTCalendar MyCal = null;
Differences between HAHTtalk Basic and
Java
The most important thing you should know when working with HAHTtalk
Basic and Java is that there are important differences between the two
languages’ data types, which are described later in this section. However, if you
are an experienced HAHTtalk Basic programmer and are just starting to use
Java, here are some other general things that are different in the two
languages.
Java is strongly typed
In HAHTtalk Basic, many data types are automatically converted to the
necessary type. For example:
sub MyTest(Fred As String)
print Fred
End Sub
sub YourTest
MyTest 5
End Sub
79

Chapter 4: Calling Server-side Java from HAHTtalk Basic
This HAHTtalk Basic code compiles and runs correctly because HAHTtalk Basic
automatically converts the number 5 to the string “5” before passing it to the
subroutine MyTest.
Java is a strongly typed language — it requires that data types match exactly.
If a data type does not match, you will get compiler errors or runtime errors.
Parameter passing
In HAHTtalk Basic parameters are passed either by reference (ByRef) or by
value (ByVal). Java has no equivalent specifier. Instead, Java determines how
parameters are passed by examining their types: all primitive types (such as
int and short) are passed by value; objects are passed by reference.
Since Java is strongly typed, it is important that parameter and return-value
types match.
Java is case sensitive
HAHTtalk Basic is case insensitive; the following subroutine calls are
equivalent:
Call YourTest
Call yourtest
Java is case sensitive. Method and property names must match case exactly.
For example, if a Java class has a method called GetMyStuff, and you have a
variable called J, J.getmystuff is not the same as J.GetMyStuff.
Locating objects
Java uses a class path to help find binaries (.class files) for a specific object.
The class path is a semicolon (for Windows platforms) or colon (for Unix)
separated list of directory names or zip file names. Java looks from left to right
along the class path for a given class file name. For example, if the function
CreateJavaObject("MyObject") is specified, then the Java VM does a casesensitive
search for a file called MyObject.class along the path.
All class names do not have to be immediately along the class path — they can
also be in subdirectories. For example, suppose the Java class path was set to
C:\Fred and you want to create an instance of class found in
C:\Fred\sub\myclass.class. To create an instance of the class, you would use
the syntax CreateJavaObject("sub.myclass").
80

Chapter 4: Calling Server-side Java from HAHTtalk Basic
For information on setting the class path, see the “Java Options” section of the
HAHTsite IDE and IP User’s Guide, Chapter 2, “Using the IDE/IP’s Windows and
Toolbars.”
Mapping HAHTtalk Basic types to Java
parameter types
The following table shows how HAHTtalk Basic types map to Java types when
passed as parameters.
HAHTtalk
Basic Type
Size
(Bytes)
Description Java Type
Integer 2 Integer variables are used to hold
numbers within the following range:
–32768

Chapter 4: Calling Server-side Java from HAHTtalk Basic
HAHTtalk
Basic Type
82
Double 8 (64-bit)
IEEE
values
A data type used to declare variables
capable of holding real numbers with
15–16 digits of precision. Double
variables are used to hold numbers
within the following ranges:
Negative:
-1.797693134862315E308

HAHTtalk
Basic Type
Size
(Bytes)
Chapter 4: Calling Server-side Java from HAHTtalk Basic
Description Java Type
Array Varies An array of one of the above types. Not currently
supported in
HAHTsite
Mapping Java types to HAHTtalk Basic
types
You can pass Java variables into your HAHTtalk Basic code. The following table
shows how Java method and field (or property) types map into HAHTtalk Basic
types.
Java type Description HAHTtalk Basic type
boolean unsigned 8 bits Boolean
byte signed 8 bits Integer
char unsigned 16 bits String of 1 character
short signed 16 bits Integer
int signed 32 bits Long
long signed 64 bits No equivalent
float 32 bits Single
double 64 bits Double
String String object String
object Java object Object
array of type T An array of some type Not currently supported in
HAHTsite.
83

Chapter 4: Calling Server-side Java from HAHTtalk Basic
Troubleshooting: Java runtime errors
The table below lists Java runtime errors that are issued by the HAHTsite
Application Server. The most common errors are 844 and 845. Error 844 (class
not found) is typically caused by publishing to the wrong directory. Error 845
(method not found) is typically caused by a parameter mismatch.
Error
number
84
Error text Typical reason(s)
844 Java class className not
found.
845 Method methodName not
found or not public in
Java class className.
846 Field fieldName not
found or not public in
Java class className.
Class file is not on the class path.
Wrong path to class given.
Misspelling of class name (check
case).
Misspelled method name.
Method is not declared public, so you
do not have access to it.
Parameter types you passed in do not
match those of the method you
specified.
You need to refresh classes by
restarting the Application Server.
Misspelled field name.
Specified field is not declared public,
so you do not have access to it.
You need to refresh classes by
restarting the Application Server.
847 Cannot load the Java VM. Misconfiguration due to missing
javai.dll (or javai.so),
HSInspector.class, or
classes.zip.
848 Required HAHTtalk Basic
Java class requiredClass
not found.
849 The Java VM failed to
load.
Class path on Application Server
could also be set up improperly.
Missing HSInspector.class file or class
path does not specify the directory
where HSInspector.class lives.
Same reasons as 848.

Error
number
850 Cannot convert parameter
parameterNumber from a
HAHTtalk Basic
HAHTtalkBasicType to a
Java JavaType.
Chapter 4: Calling Server-side Java from HAHTtalk Basic
Error text Typical reason(s)
851 Cannot convert a
HAHTtalk Basic
HAHTtalkBasicType to a
Java JavaType.
852 Cannot convert a Java
JavaType to a HAHTtalk
Basic
HAHTtalkBasicType.
853 Cannot convert return
value from a Java
JavaType to a HAHTtalk
Basic
HAHTtalkBasicType.
854 Cannot convert a
HAHTtalk Basic array to a
Java array.
855 No Java class path
specified. Please specify
one using the HAHTtalk
Basic administrator.
856 Cannot create Java object.
Maximum number
(10,000) of Java objects
reached.
857 The following Java
exception was thrown:
exceptionName&Descr
There is no supported Java type for
the specified HAHTtalk Basic type for
the specified parameter.
There is no supported Java type for
the specified HAHTtalk Basic type.
There is no equivalent HAHTtalk
Basic type for the specified Java type.
There is no equivalent HAHTtalk
Basic type for the specified Java type.
Cannot pass HAHTtalk Basic arrays to
Java methods.
There is no class path configured for
the Application Server.
Each user can have a maximum of
10,000 Java objects in use at one
time.
A Java object threw the specified
exception that was not handled in
the Java code.
85

Chapter 4: Calling Server-side Java from HAHTtalk Basic
86

HAHTsite Server
Object Model
5
Introduction....................................................................................................89
Built-in objects...........................................................................................90
Getting references to the built-in objects ......................................................91
From a Java project....................................................................................91
From a HAHTtalk Basic project.................................................................96
The Application object ...................................................................................97
Application object methods ......................................................................97
Application object variables ......................................................................98
Multiple processes and application-level variables...................................99
Retrieving Application object properties ................................................100
Summary of Application object methods...............................................102
The Session object ........................................................................................107
Session state .............................................................................................107
Session timeout........................................................................................108
Event handling ........................................................................................108
Creating a dynamic URL .........................................................................109
Creating a static URL...............................................................................113
Identification methods ............................................................................113
Summary of Session object methods ......................................................114
The Request object........................................................................................117
Retrieving field values .............................................................................117
87

Chapter 5: HAHTsite Server Object Model
Retrieving cookie values ..........................................................................121
Retrieving attachments............................................................................122
Retrieving environment variables ...........................................................122
Summary of Request object methods .....................................................123
The Response object .....................................................................................126
Writing headers........................................................................................126
Setting cookies .........................................................................................127
Writing the HTML output .......................................................................129
Summary of Response object methods...................................................130
88

Introduction
Chapter 5: HAHTsite Server Object Model
HAHTsite’s Server Object Model serves as a framework for a HAHTsite Web
application. Using its built-in objects and methods, you can control the data
passed to and from a Web browser client and get information about the
application, the Web server, and the Application Server.
If you look at HAHT_Intro’s ShoppingCart.html page (part of which is shown
above), you can see two common uses of the built-in objects: retrieving data
passed in the URL field, and calling a subroutine to store data in variables, to
be shared across pages in a session. With the Server Object Model you can also
perform operations such as:
sharing variables across sessions, as well as across pages.
setting and retrieving the values of one or more cookies.
enforcing page sequence in a session. If your application requires that a
user visit pages in a particular order — for example, users must fill out a
form on one page before they can view another page — you can check
for and enforce this requirement.
managing the lifetime of a session, by controlling session timeouts.
This chapter describes the Server Object Model’s built-in objects, which
provide most of the functionality described above, and more. For information
about controlling access to secure-static and dynamic pages, by setting and
89

Chapter 5: HAHTsite Server Object Model
checking page and session privileges, see Chapter 12, “Access Control.” For
information about creating CORBA clients and servers, see Chapter 14,
“HAHTsite CORBA Capabilities.”
Built-in objects
From “What’s in a Java page?” on page 18, and “What’s in a HAHTtalk Basic
page?” on page 53, you should already be familiar with the Page object. In a
Java project, every dynamic page created in the IDE is a subclass of Page, called
Hspagename. In a HAHTtalk Basic project, each page is a subroutine, called
HS_pagename. You can also create dynamic pages programmatically, by
implementing the HAHTPage interface (in Java) or by creating a HAHTtalk Basic
subroutine to display a page.
In addition to Page objects, each HAHTsite application contains several builtin
objects. You don’t need to (and should not!) create the Server,
Application, and Session objects; all you need is references to them. Each
application also has built-in Request and Response objects; however, for
special purposes you may want to create your own Request and/or Response
object.
The com.haht.Haht class contains methods that will return a reference to your
application’s built-in objects; see “Getting references to the built-in objects”
on page 91.
The built-in objects are derived from the com.haht.HahtObject class, as shown
in the tree below:
HahtObject
(implements ApplicationListener)
Application
90
GeneratedApplication
HahtApplication
HahtEvent
(implements HAHTPage)
Page
Request
Response
Server
(implements SessionListener)
Session
GeneratedSession
HahtSession
The Server object contains get and put methods for storing variables
shared among applications, as well as event handling methods. There is a
single Server object for each hsserver process in the Application Server.
The Application object has information about the current application.
There is only one Application object, which may be shared by many
clients simultaneously.

Chapter 5: HAHTsite Server Object Model
The Application object contains methods that return information about
the current application, as well as event handlers that are triggered when
the application has just started or is about to end, or when a session is
about to start or has just ended. Like the Server object, it has get and put
methods for storing application-level variables.
The Session object contains information about the current session,
which is defined as a browser client using the application. There is a
separate Session object for each client. It contains methods to retrieve
information about the current session, such as session privileges;
methods to create URLs; and methods to control the session timeout. It
also has two event handlers, onStart and onEnd, that are called when a
session is created and just before it’s destroyed. Like the Server and
Application objects, it has get and put methods for storing
application-level variables.
You use the Request object’s methods to retrieve data the client browser
sends to the Web server. For example, when a user completes a form and
presses the submit button, the form data is sent to the Web server, either
on the URL or in a separate packet. The Request object has getURLField
methods to retrieve these values.
You use the Response object’s methods to generate HTML that the Web
server sends to the browser, including methods to write HTML output
and set cookies.
Note - The HahtEvent class is the parent class for application-
and session-level event handlers. For more information, see
“Event handling in a Java project” on page 31 and “Event
handling in a HAHTtalk Basic project” on page 66.
Getting references to the built-in objects
Depending on whether you are developing a Java project or a HAHTtalk Basic
project, you will use different methods to get references to the Server Object
Model’s built-in objects.
From a Java project
When you create a new Java project, the IDE creates a HahtApplication class
and a HahtSession class, as subclasses of GeneratedApplication and
91

Chapter 5: HAHTsite Server Object Model
GeneratedSession, respectively. You can add variables and methods to these
classes and reference them from each dynamic page.
Application and Session references in a dynamic page
In a Java project, the generated code for a dynamic page defines two variables,
hahtApplication and hahtSession, to refer to the Application and Session
objects:
Both hahtApplication and hahtSession are set in the constructor for the
page, so their values are accessible anywhere in the code for that page. For
example, if you have declared a variable lastName in HahtSession.java, this
is how you would refer to it on a dynamic page:
hahtSession.lastName
Application and Session references in other Java source files
In a Java source file other than a dynamic page, there are two ways to get a
reference to the Application or Session object. If you simply need to use a
method defined for the Application or Session class, you can use this
procedure:
1 Get a reference to the current application or session, using
Haht.getApplication() or Haht.getSession().
2 Use that reference to access the variable or method. For example, you can
get a URL string, given a project ID:
However, you may also need to access variables and methods that you have
added to HahtApplication.java or HahtSession.java. In that case, you
must use the second procedure, which is actually a superset of the first. (This
92
Java
protected HahtApplication hahtApplication;
protected HahtSession hahtSession;
...
hahtApplication = (HahtApplication) Haht.getApplication();
hahtSession = (HahtSession) Haht.getSession();
Java
String myURL = Haht.getSession().getURL
("89392C87BB91D2119141A02550C10000");

Chapter 5: HAHTsite Server Object Model
is the procedure used to define hahtSession and hahtApplication on
dynamic pages.)
1 Get a reference to the current application or session, using
Haht.getApplication() or Haht.getSession().
2 Cast the return value to type HahtApplication or HahtSession.
3 Use that reference to access the variable or method. For example, suppose
that in the code for a dynamic page, you want to print the value of a
variable you’ve stored in the Application object. Your code would look
something like this:
Java
HahtApplication myApp =
(HahtApplication)Haht.getApplication();
out.print(myApp.myVar);
Session references in master projects and referred projects
Both master projects and referred projects contain GeneratedSession.java
and HahtSession.java files; however, in a master project, the class
GeneratedSession extends com.haht.project.Session, while in a referred
project, the GeneratedSession class extends the class
com.haht.project.UtilitySession (see the figure below). The important
point to note here is that the UtilitySession class does not represent a user
session, as Session does; UtilitySession is a very general class from which
GeneratedSession inherits only a small amount of functionality.
93

Chapter 5: HAHTsite Server Object Model
In a master project:
94
com.haht.project.Session
GeneratedSession
HahtSession
A Session object represents an entire session.
com.haht.project.
UtilitySession
GeneratedSession
HahtSession
Master Project Referred Project
A GeneratedSession object contains master-project extensions to the
Session class such as references to objects that have been dragged and
dropped onto the project’s Session folder. For example, the
GeneratedSession object might contain a reference to a data agent
representing a session recordset created by dragging and dropping a table
onto the Session folder.
A HahtSession object contains user-defined variables and methods.
A referred project’s GeneratedSession and HahtSession objects are analogous
to those in a master project. However, a referred project has no Session object
associated with it. There is only one Session object per user session.
How do you get references to these objects? HAHTsite generates the code that
obtains references to these objects and assigns those references to variables.
The matrix below shows the names you use to access objects in either a master
project or a referred project from either a master project or a referred project.

Name Use
Chapter 5: HAHTsite Server Object Model
hahtSession In a master project, you should use this
name to refer to the session’s Session
object. You can also use it in a master
project to refer to the master project’s
GeneratedSession and HahtSession
objects, but you shouldn’t do this if your
project is, or might later become, a referred
project. HAHTsite provides another name to
use in this situation.
In a referred project, you can only use the
name to refer to the session’s Session
object.
projectName_hahtSessionExt In a master project, you can use a name of
this form to refer to the master project’s
extended objects (its GeneratedSession
and HahtSession objects) and to a referred
project’s extended objects. (The
projectName portion of the name will
vary depending on the project.)
In a referred project, you use a name of this
form to refer to the referred project’s
extended objects.
Briefly, here’s how you might use these names. Suppose that from your master
project, you want to refer to a session recordset (a data agent) defined in the
referred project ReferredProject. For the purposes of this example, assume that
the session recordset was created by dragging a shared query named
SharedQuery to the project’s Session folder. You could refer to this data agent
using the following code:
protected com.haht.project.datamanager.DataAgent da1 =
ReferredProject_hahtSessionExt.getSharedQuery();
Request and Response objects
The run method for each page takes two arguments: aRequest and aResponse,
which refer to the Request and Response objects, respectively. You can use
these references if you add code to a dynamic page — either by adding in-line
code to the HTML page, or by adding to the generated code in Server-side Code
view.
You can also call the Haht object’s getRequest and getResponse methods:
95

Chapter 5: HAHTsite Server Object Model
Page object
The Session object’s returnHAHTPageObject method instantiates a page
object and returns a reference to it; if the page has already been instantiated,
it simply returns the object reference. For details, see “Calling a dynamic page
from Java” on page 30.
From a HAHTtalk Basic project
In a HAHTtalk Basic project, the Server Object Model contains three
predefined constants:
96
Java
Request myRequest = Haht.getRequest();
Response myResponse = Haht.getResponse();
haht — a reference to the com.haht.Haht object
hahtApplication — a reference to the current Application object
hahtSession — a reference to the current Session object
(As with other HAHTtalk Basic identifiers, the names for these constants are
case insensitive.)
You can use these references anywhere in the code for a dynamic page. For
example, to retrieve the state ID for the current session, you would use code
like this:
HAHTtalk Basic
Dim sStateId as String
Set sStateId = hahtSession.getStateId()
On code pages, you can use the Haht object’s getApplication and getSession
methods to get references to the Application and Session objects, like this:
HAHTtalk Basic
Dim MyApp As Object
Set MyApp = Haht.getApplication()
Dim MySession As Object
Set MySession = Haht.getSession()

Request and Response objects
Chapter 5: HAHTsite Server Object Model
The generated code for a page gets references to the Request and Response
objects in this way:
HAHTtalk Basic
Dim aRequest As Object
Dim aResponse As Object
Set aRequest = Haht.getRequest()
Set aResponse = Haht.getResponse()
You can use these references if you add in-line code to a page, or if you add
code in Server-side Code view. On a separate code page, you can call the
getRequest and getResponse methods.
The Page object
In a HAHTtalk Basic project, you refer to a page, or call a page, simply by its
name (recall that dynamic pages in the IDE have the prefix “HS_”).
The Application object
The Application object contains information about the current application.
There is only one Application object, which may be shared by many clients
simultaneously. On the other hand, there is a separate Session object for each
client using the same application.
Note - If you have configured the Application Server to run
multiple processes, there will actually be one Application
object per process. See the technical note “Multiple processes
and application-level variables” on page 99.
Application object methods
The most commonly-used Application object methods can be divided into
these types:
Type Refer to
Methods dealing with application
variables
“Application object variables” on page
98
97

Chapter 5: HAHTsite Server Object Model
Type Refer to
Methods to get the properties of the
Application object
In addition, to read about access control methods, see Chapter 12, “Access
Control.” For information about CORBA, see Chapter 14, “HAHTsite CORBA
Capabilities.”
Application object variables
In a Java project, you can store application-level variables directly in the
HahtApplication class. The Application class also has get and put methods
that you can use to create variables on the fly.
In a HAHTtalk Basic project, you can use the get and put methods for
application-level variables; this can be particularly useful in HAHTtalk Basic
applications that call server-side Java, as a way to share variables.
Get, put, and remove
The put method associates a name with an object and stores the name/value
pair in the Application object. The get method retrieves the stored value.
There is also a remove method, that removes the object reference. In a Java
project, the value you put must be an object; when you call get, you must cast
the return type appropriately. In a HAHTtalk Basic project, the value you put
can be an object or a string; the type conversion is done automatically on a
get.
Calling get for a variable that doesn’t exist returns a null object.
Examples:
98
Java
String s = "Hello world";
hahtApplication.put("myvar", s);
// Get the value we just put
String s2 = hahtApplication.get("myvar");
“Retrieving Application object
properties” on page 100

HAHTtalk Basic
Dim O as Object
hahtApplication.put "myvar", "Hello world"
’Get the value we just put
Set O = hahtApplication.get("myvar")
If O is not Nothing Then
Print O
Else
Print "Variable not set" & ""
End If
Variable locking
Chapter 5: HAHTsite Server Object Model
If you are updating a variable that belongs to the Application object, it’s a
good idea to lock the application’s variables until the operation has
completed. Suppose you are updating several related variables, such as
database access information. Because they are related, you don’t want any
other sessions to access them until they have all been updated. In your
program, you would lock the Application object’s variables each time you
access them. If another session has the variables locked, your session waits
until the other session calls the unlock method. Note that these methods work
only if every access to those variables calls lock and unlock. In pseudocode:
Call lock (if the Application object’s variables are locked by another session,
waits until they are unlocked)
Update variables
Call unlock
If your program doesn’t explicitly call the unlock method, the Application
Server will unlock the Application object’s variables when the page ends or
times out.
Multiple processes and application-level variables
What is the scope of an Application object’s variables? You can use the
Application object to share variables across multiple sessions. However, it’s
important to understand that, depending on your Application Server
configuration, an application may be running in several processes, each with
its own Application object and set of Session objects. See the drawing below,
showing four processes running on two Application Servers. Each session can
access the variables stored in the Application object, but only for that
particular process. There is no communication between processes.
99

Chapter 5: HAHTsite Server Object Model
You can use the Application object to cache variables for use by multiple
sessions — as you could see in the Java example that printed the current
number of sessions (“Example: onSessionStart, onSessionEnd” on page 33). In
that example, an application-level variable, nActiveSessions, kept count of
the number of active sessions. But since variables cannot be shared across
processes, each process would have its own copy of the nActiveSessions
variable.
Retrieving Application object properties
The Application object provides a number of methods for retrieving
properties such as its name, directory name, or initial working directory. One
commonly-used method is getAppData, which returns the value of an
application property. For example, to get the dynamic URL, you would use this
code:
Java
String myURL = hahtApplication.getAppData(0, "DynamicURL");
100

HAHTtalk Basic
Chapter 5: HAHTsite Server Object Model
Dim MyURL As String
MyURL = hahtApplication.getAppData(0, "DynamicURL")
This URL is determined by a project’s site properties, where it appears as the
Dynamic-hsrun URL (seen below). You can use it as the prefix for URLs to
applications.
The first argument to getAppData is a subsite index. Site definitions, which
exist at the project level, can contain definitions of subsites which will apply
to certain project items. For example, you might want to publish part of a
project to a secure Web server (one that supports the HTTPS protocol). Or you
might want to include Perl scripts in a HAHTsite project and publish them
directly to the Web server’s cgibin directory. For more information about
subsites, see the HAHTsite IDE and IP User’s Guide, Chapter 4, “Working with
Sites.”
In a project without subsites, the site definition becomes the default subsite
definition. In this case, use zero as the subsite index.
The second argument is the property whose value you want returned. It can
be one of the following:
101

Chapter 5: HAHTsite Server Object Model
Field Description
"AppendString" String (if any) this subsite’s Web server appends to
the URL of a dynamic page.
Example: ?
"DynamicURL" URL for the directory defined by the Web server’s
CGI alias.
Example: http://www.haht.com/cgi-bin
"HSrunAppendString" String (if any) this subsite’s Web server appends to
the HSrun command.
"HSrunExtension" String (if any) this subsite’s Web server expects the
HSrun executable to have.
Example: .hse
"HSrunParamDelimiter" Character used as a delimiter between parameters
passed on the URL.
Example: &
"StaticROOT" Path to subsite’s document root directory.
Example: \\moe\D\Netscape\SuiteSpot\docs
"StaticURL" URL to default subsite’s document root directory.
Same as getStaticURL.
Example: http://www.haht.com
"ProjectSubDir" 1
1. For compatibility with past releases, “SubDirURL” can be substituted for “ProjectSubDir.”
Summary of Application object methods
The following table lists the methods available with the Application object
(with the exception of methods related to access control and CORBA, which
are covered in later chapters). For a fuller description of each method, consult
the on-line help for the Server Object Model.
102
Project subdirectory under application root
directory.
Example: %project%
"SubSiteName" Subsite name associated with index (zero-based).
Same as getSubSite.
Example: default

Chapter 5: HAHTsite Server Object Model
Note - When a file system pathname is returned (rather than a
WWW URL), its format is operating system-dependent. For
example, for an NT system, getDirname would return
\subdirectory\, while for a UNIX system, it would return
/subdirectory/.
Method Description
addApplicationListener (Java only). Adds an event listener to the
Application Event Listener.
get Retrieves the value of a name/value pair stored
in the Application object (see put). The
value is returned as an Object and, in Java,
must be cast to the appropriate class.
getAppData Depending on the fieldName argument,
returns information about the application for
the given subsite.
getDirName Directory part of HAHTsite executable file
pathname, relative to the application root
directory.
NT example: \JSimple\
UNIX example: /Jsimple/
This value is useful for accessing user data files
that are organized in the same manner as the
application; the data files will be in a parallel
subdirectory with the same name under the
Userroot directory. Note, however, that this
directory is relative to the configured
Application Root directory. Thus, what is
returned as ‘/’ here may indeed be
‘usr/local/WebApp/AppRoot’.
getName Application name without extension or path.
Example: Test
getPathName Full pathname of HAHTsite executable file.
NT example: \JSimple\Test.htx
UNIX example: /JSimple/Test.htx
103

Chapter 5: HAHTsite Server Object Model
Method Description
getStaticRoot Path to Web server’s document root directory
for the default subsite. The document root
directory is where the Web server stores its
static pages.
NT example: \\moe\d\hahtsite\doctree
UNIX example:
/usr/local/hahtsite/doctree
getStaticURL URL to default subsite’s document root
directory.
Example: http://www.haht.com
getString Retrieves the value of a name/value pair that
is a string stored in the Application object.
See putString.
getSubSite Subsite name associated with index (zerobased).
Example: default
getSubSiteCount Number of subsites defined for the
application, including the default subsite.
104

Method Description
Chapter 5: HAHTsite Server Object Model
getUserRoot Path to application’s initial working directory
(operating system dependent). If your code
reads or writes a file without specifying an
absolute path, the application looks for the
file in the application’s userroot directory.
Files that a user attaches to a form (using File
Upload) are also placed in userroot.
When you install the Application Server or
modify its properties, you set the userroot
Transfer URL (shown in a site definition
below), which defaults to
HAHTsiteInstallDir\userroot. If you
publish your project to a subdirectory, the
subdirectory’s name is appended to the
userroot path (for example,
\\moe\WebDocs\userroot\MyProject).
Dynamic - server group:
Server Group Host: moe.haht.com
Server Group: webapps
File: d:\hahtsite\sites\cache\moe.haht.com
\webapps.hsg
Subdirectory: %project%
State IDs in: Cookies
Location: approot
Transfer URL:
\\moe\WebDocs\approot
Location: userroot
Transfer URL:
\\moe\WebDocs\userroot
Location: javaroot
Transfer URL:
\\moe\WebDocs\javaroot
isBasicApp Returns true if this is a HAHTtalk Basic
application.
isJavaApp Returns true if this is a Java application.
isRecordingPageVisits Returns true if sessions of this application are
recording a history of pages visited.
isUsingCookies Returns true if the application was published
to use cookies (based on the site definition).
For more information about setting the “use
Cookies/use URL” property, see the HAHTsite
IDE and IP User’s Guide, Chapter 4, “Working
with Sites.”
105

Chapter 5: HAHTsite Server Object Model
Method Description
lock Acquires a lock for the Application object’s
variables.
onSessionStart,
onSessionEnd
106
Event handler called when a new session is
created, or right before a session is destroyed.
In a Java project, can be customized in
HahtApplication.java. (Not accessible in
HAHTtalk Basic projects.)
onStart, onEnd Event handler called when the application has
just been created or just before it is
terminated. In a Java project, can be
customized in HahtApplication.java. (Not
accessible in HAHTtalk Basic projects.)
put Associates an object with a name and stores
the name/value pair in the Application
object. See get.
putString Associates a string value with a name and
stores the name/value pair in the
Application object. See getString.
remove Removes the association of the named
variable with a value. Applies to name/value
pairs created with put or putString.
removeApplicationListener (Java projects only). Removes an event listener
from the list of Application listeners.
startRecordingPageVisits,
stopRecordingPageVisits
Tells the Application Server to begin/stop
recording a history of pages visited.
To retrieve this history, use the Session
object’s getPagesVisited method.
unlock Releases the lock for the Application
object’s variables.
writeLog Writes a string to the Application Server’s log
file.

The Session object
Chapter 5: HAHTsite Server Object Model
Unlike the Application object, a Session object applies to a single user. When
a browser initially requests a Web page, the Application Server creates a
Session object unless one has already been created for that user. A Session
object continues to exist until it’s terminated by the Application Server (see
“Session timeout” on page 108).
Like the Application class, the Session class has get and put methods that
you can use to create variables on the fly, and it has lock and unlock methods
that let you serialize access to session-level variables (see “Variable locking” on
page 99).
In a Java project, you can also edit HahtSession.java directly, to declare and
set variables as well as to add event handlers.
In a HAHTtalk Basic project, you can use include files or store variables in the
globals.hbs file. (Note that variables are not shared across sessions in a
HAHTtalk Basic project.) For more information, see “Include files and
Globals.hbs” on page 63.
Session-related topics covered in this chapter include:
Topic Reference
Session state “Session state” on page 107
Session timeout “Session timeout” on page 108
Event handling at the session level “Event handling” on page 108
Creating a URL for a project item or for
a location outside the project
Determining whether this is the first
page of a session; identifying the
current method/subroutine or the
calling method/subroutine
You may also be interested in the explanation of session privileges and access
control in Chapter 12, “Access Control.”
Session state
“Creating a dynamic URL” on page 109
“Identification methods” on page 113
There are two important concepts to understand at the session level: state and
timeout.
107

Chapter 5: HAHTsite Server Object Model
State is the collection of information available to an application. Typical Web
applications are inherently stateless, meaning that they don’t retain
information between pages. In HAHTsite, Session objects maintain state even
if the user moves to other Web pages, until the session times out. This means
that you can store session-level variables in the Session object and access
them from multiple pages.
One use for session-level variables is to store information about user
preferences. Another is to store a recordset returned by a database command.
You can then access the recordset across page boundaries — a great efficiency.
(For details, see the HAHTsite IDE and IP User’s Guide, Chapter 15, “Connecting
to a Data Source.”)
Session timeout
When a user leaves a Web application, how does the application know? There
is no quit or exit button, and in fact the user might return after browsing other
pages. On the other hand, you wouldn’t want to keep a session alive
indefinitely — it would eat up your resources. The answer lies in the
Application Server, which controls the session timeout — that is, how many
seconds must elapse, with the application idle, before the Application Server
terminates the session. The default timeout value is 300 seconds, set in the
Application Server configuration. However, you can override this default for
the current session. Here are the applicable methods:
108
The setTimeout method sets the timeout value for the current session.
The getTimeout method returns the number of seconds before timeout
occurs.
(There is also a keepAlive method, which resets the timeout value; this
method is useful only when you are accessing CORBA objects.)
In addition to these methods, in a HAHTtalk Basic project, you can call Stop
or End to immediately stop execution of the application. In a Java project, you
can call the Session object’s abandon method.
Event handling
When a session ends, HAHTsite automatically performs cleanup tasks such as
closing any open data source connections, destroying OLE and Java objects,
and freeing memory. However, you may want to save the session state, so that
you can restore it if the user logs back in. Or you may want to perform certain
initialization procedures when a session begins. The Session object includes
onStart and onEnd event handlers that you can customize (in Java) or override

Chapter 5: HAHTsite Server Object Model
(in HAHTtalk Basic). Refer to “Event handling in a Java project” on page 31, or
“Event handling in a HAHTtalk Basic project” on page 66.
Creating a dynamic URL
The Session object provides several methods for building a URL that you can
use to link from a dynamic page to another page, to an image, or to an image
map. These methods require either a project ID or a string representing the
page, image, or image map.
Building a URL from a project ID
The getURL method locates a project item — a page, an image, or an image
map — by means of its project ID and returns a string containing a URL for that
item.
The getURL method has a number of variations, with different parameters,
including:
project ID — a universally unique identifier that HAHTsite assigns to a
project item. Within the IDE, you can view a project item’s ID by clicking
on the item, choosing Edit > Properties and clicking the File tab.
default string — a string that is to be returned if the method fails to
locate the item. This can occur if a project item was deleted but is still
referenced somewhere in the source code. If you don’t specify a default
string and the method fails, it returns an empty string.
append string — a bookmark or query string to be appended to the
generated URL. A bookmark consists of the pound sign (#), followed by
the string for a bookmark anchor. A query string should contain one or
more name/value pairs, separated by ampersands — for example,
“Name=Johnson&City=London”.
method (Java only) — the method to be run on the destination page. The
method defaults to run. This argument is disregarded in HAHTtalk Basic
projects.
wantFullURL — a boolean value; if true, the method returns a complete
URL, rather than a relative URL. You might set this value to true to
produce a string to redirect users to another dynamic page. Some
browsers require full URLs in this case. A full URL would look something
like this:
http://www.haht.com/cgi-bin/hsrun/webapps40/PJ2/StateId/
TbOIpYMPgKipKLh90G357_Ws_T/HAHTpage/PJ2.HsPageTwo.run
109

Chapter 5: HAHTsite Server Object Model
110
while a relative URL might look like this for the first dynamic page:
StateId/TbOMAYMPp5MpKLxZ0G3xK_WCL1/HAHTpage/PJ2.HsPageTwo.run
and like this for subsequent dynamic pages:
../HAHTpage/PJ2.HsPageTwo.run
Note that if state IDs are being passed in cookies, rather than on the URL,
you will not see a state ID in the URL string returned.
The default for this argument is false — that is, relative URLs.
wantStartURL — a boolean value; if true, the method returns a URL for
calling the page from a static page, including the .htx or .hjx file and the
“start=” string. It does not include a state ID, and it does start another
session instance. If you set wantStartURL to true, you will always get a
full URL, regardless of the setting for wantFullURL. Here’s an example of
the string returned:
http://www.haht.com/cgi-bin/hsrun/webapps40/PJ2/
PJ2.hjx;start=PJ2.HsPageTwo.run
The default for this argument is false.
Example: Building a URL
This example programmatically builds an anchor tag and target URL for a
dynamic page, using relative URLs (the default). The example calls getURL,
passing it the project ID for the destination page. Then it inserts the return
value in an anchor tag.
Java
String myURL = hahtSession.getURL
("74FC8E62E969D2119141748209C10000");
out.print(" Page2 ");
HAHTtalk Basic
Dim MyURL As String
MyURL = hahtSession.getURL("74FC8E62E969D2119141748209C10000")
Print " Page2 "
At runtime, getURL adds the correct CGI delimiter (such as “?”), depending on
the target Web server. If the call is being made from the first dynamic page of
the application, then getURL returns a URL containing the state ID (if state IDs
are being passed in URLs rather than cookies); the HTML for the anchor tag
looks similar to this:

Chapter 5: HAHTsite Server Object Model
PageTwo
If this isn’t the first dynamic page in the sequence, then getURL returns a
relative URL, and the HTML looks like this.
PageTwo
(This is the output from a Java project; in a HAHTtalk Basic project, it would
look the same, except that “HsPageTwo.run” would be replaced by
“HS_PageTwo.”)
If the Web server has been defined as storing state information in cookies, then
the state ID is passed in a cookie instead of on the URL. For more information
about cookies and Web browsers, see the HAHTsite IDE and IP User’s Guide,
Chapter 4, “Working with Sites.”
Creating a dynamic URL for an image map, page, or file
In addition to the getURL method, there are three methods that return a
dynamic URL for an image map, a dynamic page, or a file (for example, a
secure static page), without requiring the project ID as an argument. Instead,
you supply a string containing the name of the page, image map, or file.
(There is a second, optional argument: the name of a subsite.)
These URLs can refer to elements outside the project, or even to elements that
don’t yet exist (for example, files you will later copy to the approot directory).
HAHTsite doesn’t check on the validity of the URL it creates; it simply accepts
the input you supply and creates a URL by adding the state ID and the CGI
delimiter for the Web server you’re publishing to.
createPageURL creates a URL for a dynamic page. In a Java project, its
argument is the page’s fully-qualified run method — that is,
packagename.classname.run. In a HAHTtalk Basic project, its argument is
the name of the page subroutine (HS_pagename).
This code returns a dynamic page URL.
Java
String myPageURL =
hahtSession.createPageURL("MyProject.HsPageTwo.run");
HAHTtalk Basic
Dim MyPageURL As String
MyPageURL = hahtSession.createPageURL("HS_PageTwo")
111

Chapter 5: HAHTsite Server Object Model
112
createMapURL creates a URL for an image map. Its argument is the
filename for a dynamic server-side image map (.hmp).
This example displays a dynamic image map (“MyMap.hmp,” based on an
image “Globe.gif”). It calls two Session methods: one to create a dynamic
map URL, and one to create a static URL (for more information on that
method, see “Creating a static URL” on page 113).
Java
out.print("");
HAHTtalk Basic
Print "" & HSCRLF
createFileURL creates a URL for a file stored in the approot directory,
such as a secure static page.
This code returns a URL for a secure static page.
Java
String myFileURL =
hahtSession.createFileURL("MySecurePage.html");
HAHTtalk Basic
Dim MyFileURL As String
MyFileURL = hahtSession.createFileURL("MySecurePage.html")

Creating a static URL
Chapter 5: HAHTsite Server Object Model
One additional method creates a URL for a static page; its arguments are the
name of the page and, optionally, a subsite name. Given a null page name, it
returns the URL for the staticroot directory.
Suppose your site is called www.mysite.com, and you want to create an HTML
anchor with the destination of
http://www.mysite.com/MyProject/Static.html
You would use code like this:
Java
String myStaticURL =
hahtSession.createStaticURL("StaticPage.htm");
out.print(" Static page ");
HAHTtalk Basic
Dim MyStaticURL As String
MyStaticURL = hahtSession.createStaticURL("MyStaticPage.htm")
Print " StaticPage
"
Identification methods
The Session object has additional methods for purposes such as finding out if
this is the first dynamic page of the session, and finding the name of the
calling routine.
isNewApp
The isNewApp method returns true if this is the first dynamic page of a session.
One simple use for this method is to conditionally display a welcome message
when a user first invokes an application. It can also be used to control how a
page generates URLs in a case where the user can return to the start page via a
text anchor.
113

Chapter 5: HAHTsite Server Object Model
whoAmI and whoCalledMe
The whoAmI method returns the name of the current method or subroutine. If
you were placing a clip on a number of different pages, you could call whoAmI
within the clip to customize some part of the output, depending on the
current page.
The whoCalledMe method returns the name of the calling method or
subroutine. You might invoke whoCalledMe in a general-purpose method or
subroutine that might be called by several different pages.
Summary of Session object methods
This table summarizes the methods of the Session object. It does not include
methods for access control or for CORBA, which are described in later
chapters.
For particulars, consult the online help for the Server Object Model.
Method Description
abandon Terminates the session after the page completes.
addSessionListener (Java projects only). Adds an event listener to the
Session Event Listener.
auditMessage Writes a message to an audit file keyed to a hit
number.
auditPage Turns on session auditing for the current page. The
audit files contain information about requests and
responses and user-generated auditing messages.
callByProjID Calls a dynamic page, given its project ID.
createFileURL Returns the URL for a file, including a secure static
page.
createMapURL Returns the URL for a dynamic image map.
createPageURL Returns the URL for a dynamic page.
createStaticURL Returns the URL for a static page.
endAuditing Stops session auditing.
get Retrieves the value of a name/value pair stored in
the Session object. See put.
114

Method Description
Chapter 5: HAHTsite Server Object Model
getAdoConnStrByID Returns the connection string associated with the
ADO connection that has a particular project ID.
getConnectionManager Returns a reference to the session’s
DMConnectionManager object.
getErrors Returns a reference to the session’s Errors object.
getHostName Returns a string containing the hostname of the
current machine. This method is useful, for
example, to determine which background server is
generating an error.
getPagesVisited Returns a PagesVisited object with the dynamic
and secure-static pages visited by this session.
getServerGroupName Returns a string containing the name of the server
group to which the project was published (as set in
the project’s site description; see the example
below). This value can be used to generate a URL,
but it’s not usually required because most URLs are
relative to the application’s root directory.
Dynamic - server group
Server Group Host:moe.haht.com
Server Group:webapps
File: d:\hahtsite\masters\moe.haht.com\
webapps40.hsg
getStateCookieString Returns a string that is the cookie for the current
session. This string is meaningful if the site is set up
to use cookies; see the Application object’s
isUsingCookies method. The string includes the
state ID and CGI path and looks something like
this:
Set-Cookie: HS_StateId=TbI-v6MO-
GepKs3M0GYjh-RCNw; path=/cgibin/hsrun/webapps40/ExamplProj/
getStateId Returns the current state ID. Each session has a
unique state ID, which is useful for naming
temporary files or CORBA objects.
getString Retrieves the value of a variable stored in the
Session object using putString. Also see get.
115

Chapter 5: HAHTsite Server Object Model
Method Description
getTimeout Returns the timeout value for the current session —
that is, how many seconds must elapse, with the
user not accessing the application, before the
Application Server will terminate the session. See
setTimeout, keepAlive.
getURL Returns the URL for a project item, given a project
ID.
getUserName Returns the user name (if any) associated with the
current session. See setUserName.
isNewApp Returns true if this is the first dynamic page
executed in a new instance of an application. This
method returns false for every other dynamic
page executed in the application.
keepAlive Resets the timeout value, to keep a session from
timing out. See getTimeout, setTimeOut.
lock Blocks other client threads from modifying data
stored in the Session object.
onStart, onEnd Event handlers called when a session is about to
start or end. In a Java project, you can customize
these methods in HahtSession.java. In a
HAHTtalk Basic project, you can override them
with the HahtSessionOnStart and
HahtSessionOnEnd pseudo-methods.
put Associates a value with a name and stores the
name/value pair in the Session object. See get.
putString Associates a string value with a name and stores the
name/value pair in the Session object. See
getString.
remove Removes the association of the named variable
with a value. Applies to name/value pairs created
with put or putString.
removeSessionListener (Java projects only). Removes an event listener
from the list of session listeners.
returnHAHTPageObject (Java projects only). If the requested page has
already been instantiated, returns a reference to
that object. Otherwise, the method instantiates the
page and returns a reference to it.
116

Method Description
The Request object
Chapter 5: HAHTsite Server Object Model
setTimeout Sets the timeout value for the current session, in
seconds. See getTimeout, keepAlive.
setUserName Associates a user name with a session.
startAuditing Starts session auditing, beginning with the current
page.
unlock Disables a lock that has been preventing other
client threads from modifying data stored in the
Session object.
whoAmI Returns a string containing the name of the
currently executing function.
whoCalledMe Returns a string containing the name of the calling
function.
The Request object lets you access data a browser sends to the Web server with
an HTTP request, including:
Topic Refer to
Getting the value of a field “Retrieving field values” on page 117
Getting the value of a cookie “Retrieving cookie values” on page 121
Getting information about the Web
server and the remote host making the
request
Retrieving field values
“Retrieving environment variables” on
page 122
During a session, the Web browser passes data to the Web server in the form
of name/value pairs. One source of such data is a form. On a Web page, forms
have many uses — for example, collecting data that may be entered into a
database, or displaying read-only information. When a user enters
information into a form, that information can be sent back to the Web server
in one of two ways:
117

Chapter 5: HAHTsite Server Object Model
118
If the form’s method is GET, the data is sent as part of the URL string,
which looks something like this:
Name=Scott&Location=SouthPole&Button1=Submit
If the form’s method is POST, the data is sent to the Web server in a
separate message packet.
Field variables can come from other sources besides a form. For example, you
might design a Web page that passes parameters on a link (using the link’s
Query field). Or you might place in-line code on a Web page that calculates a
value and passes it to the destination page. Each variable is passed as a
name/value pair on the URL.
The catalog_main.html page from Haht_Intro demonstrates two methods of
passing fields to a destination page.
First of all, each category (OUTDOOR, HOUSEHOLD, and so on) is actually an
image which functions as a link to the destination page. The query string for
the link contains the category of item being searched for — for example,
“CatGrp=4” for Outdoor items. In addition, you can enter a product name and
click on SEARCH BY NAME, which adds the name/value pair
“SearchName=youritem” to the query string.

Retrieving field values
Chapter 5: HAHTsite Server Object Model
Whether the data comes from a form or by some other means, a request
typically includes a number of field variables. The Request object’s
getURLField method lets you access these values without the need to
determine whether the data was sent using GET or POST. Given a field name,
getURLField returns the field’s value.
Returning to the Haht_Intro example, the destination page,
CatalogDisp.html, first tests to see if the query string has a value for
“CatGrp”; if that value is missing, it tests for a value for “SearchName.” It uses
one of those values to define a shared query over the database.
HAHTtalk Basic
If aRequest.getURLField("CatGrp") "" Then
...
ElseIf aRequest.getURLField("SearchName") "" Then
...
sParam = "'%" & aRequest.getURLField("SearchName") & "%'"
...
End If
Testing for a field’s existence
The Haht_Intro example tests for an empty string, which can mean one of two
things: either the field cannot be found, or the field actually contains an
empty string (""). If you simply want to check whether a field exists, use the
getURLFieldExists or getURLFieldCount method.
Retrieving a field’s value by its index
If you call getURLField with an index into the collection of field variables, it
returns the name/value string corresponding to that index. To retrieve the
values of all fields in a form, you could use code like this:
Java
for (int fieldNum=1; fieldNum

Chapter 5: HAHTsite Server Object Model
HAHTtalk Basic
Dim FieldNum As Integer
For FieldNum = 1 to aRequest.getURLFieldCount()
Print aRequest.getURLField(FieldNum) & ""
Next FieldNum
(Note that indexing into the field array is one-based, not zero-based.) In this
case, each field would be returned as a name/value string, like this:
txtLastName=Simpson
txtFirstName=Bart
txtCity=Springfield
Button1=Submit
If you index past the number of available fields, the method returns an empty
string.
Fields with multiple values
Sometimes a form will have more than one value for the same field. For
example, a list box like the one shown below contains multiple values, and the
user can select more than one item in the list:
In this case, the browser sends a name/value pair, using the same fieldname,
for each item selected — for example, "txtCity=Berlin&txtCity=Amsterdam".
To retrieve these values, you use the same methods as above, but with an
additional argument:
120
getURLField (fieldname, n) returns the value of the nth occurrence of
fieldname.
getURLFieldCount (fieldname) returns the number of values the
browser sent for a particular field. A count of zero means that the field
isn’t present in the form data; perhaps the user made no selection.
getURLFieldExists (fieldname, n) returns true if occurrence n of field
fieldname exists, and false otherwise.

Adding fields and overriding field values
Chapter 5: HAHTsite Server Object Model
On the destination page, you can call setURLField to override the value of a
field, and you can call addURLField to set the value of an additional field,
which will then behave as if it had been passed from the calling page.
Retrieving cookie values
A cookie is a string passed in the HTTP headers between a Web server and a
browser. If the browser is configured to accept cookies, it will store the cookies
on the user’s system and later, on request, will make the cookie available to the
Web server. Information stored in cookies can include items such as user
names, user preferences, or pages last visited. In HAHTsite, if the site is
configured to use cookies, the state ID is also passed in a cookie.
The Response object contains methods to set cookies; the Request object,
methods to retrieve cookie values. You retrieve cookie values just as you
retrieve field values.
getCookieCount returns the number of cookies sent from the browser.
getCookie(cookie) returns the value of the named cookie.
getCookie(index) treats the cookies like an array and returns the cookie
corresponding to the index argument; the first cookie has an index of
one.
Retrieving cookie collections
A single cookie may store several pieces of data — for example,
“dimensions=height=10&width=5”. These multiple-value cookies are also
called cookie collections. To retrieve these values, you must use the getCookie
method and then parse the results. For example,
Java
String myCookie = aRequest.getCookie("dimensions");
HAHTtalk Basic
Dim MyCookie As String
MyCookie = aRequest.getCookie("dimensions")
would return “height=10&width=5”. For information on setting these cookie
values, see “Multiple values within a single cookie” on page 128.
121

Chapter 5: HAHTsite Server Object Model
Retrieving multiple cookies with the same name
A cookie collection (above) refers to a single cookie with multiple values.
However, you can also have several cookies with the same name but different
paths. In this case, they are all sent with the request string, beginning with the
deepest path. For example, the cookie with a path of “www/home/products”
would appear on the string before “www/home.” If you simply call
aRequest.getCookie(cookie), you will retrieve the first cookie value on the
string. However, you can also index into the set of cookies:
122
getCookieCount(cookie) returns the number of values returned for this
cookie.
getCookie(cookie, index) returns the cookie value corresponding to
index.
For more information on cookies, including the path field, see “Setting
cookies” on page 127.
Retrieving attachments
An HTTP request often includes one or more attachments, which are placed in
temporary files in the Application Server’s userroot directory.
getURLAttachmentExists returns true if the named attachment exists,
and false otherwise.
getURLAttachmentCount returns the number of attachments transferred.
getURLAttachment returns the name of the temporary file associated with
the file upload form field.
getURLAttachmentType returns the content-type for the attachment
associated with the file upload form field. If the browser didn’t send a
content-type, then the return value is an empty string.
For more information about attachments, including an example, see
“Working with a file attachment” on page 142.
Retrieving environment variables
An HTTP request can include information such as the request method (“GET,”
“POST,” and so on) or the content-type or length of the data being transferred.
The Web server passes this information to the CGI program in the form of
environment variables.
Just as the getURLField method retrieves the value of a form field, the
getServerVariable method retrieves the value of an environment variable.

Chapter 5: HAHTsite Server Object Model
getServerVariableCount returns the total number of environment
variables passed to the Web server.
getServerVariable(variablename) returns the value of an environment
variable. (The name is not case sensitive.)
getServerVariable(index) returns the value of the environment variable
corresponding to the given index, in the form name=value.
If the name can’t be found, or if the index into the collection of environment
variables is out of range, the method returns an empty string.
Tip - If you are debugging an application, you can view the
Web server’s environment variables in HAHTsite’s Output
window.
This code prints out all the environment variables returned by the Web server:
Java
int numVars = aRequest.getServerVariableCount();
for (int i = 0; i < numVars; i++) {
out.print(aRequest.getServerVariable(i) + "");
}
HAHTtalk Basic
Dim NumVars As Integer, FieldNum As Integer
NumVars = aRequest.getServerVariableCount()
For FieldNum = 1 to NumVars
Print aRequest.getServerVariable(FieldNum) + ""
Next FieldNum
The environment variables returned depend on the Web server you’re using
and the operating system under which you are running. For more
information, consult the documentation for your Web server.
Summary of Request object methods
This table summarizes the methods of the Request object. For particulars,
consult the online help for the Server Object Model.
123

Chapter 5: HAHTsite Server Object Model
Method Description
addURLField Adds a name/value pair to the set of fields
passed from the calling page. You can then
retrieve its value with getURLField.
getCookie Given the name of a cookie, returns its value.
Given an index, treats the cookies like an array
and returns the cookie corresponding to the
index argument; the first cookie has an index
of one.
Given a cookie name and an index n, returns
the value of the nth occurrence of the cookie.
getCookieCount Returns the number of cookies sent from the
browser.
Given a cookie name, returns the number of
cookies with this name.
getInputStream Returns the java.io.ByteArrayInputStream
object for the client input stream.
getServerVariable Given the name of an environment variable,
returns its value. (The name is not case
sensitive.)
Given an index, returns the value of the
corresponding environment variable, in the
form name=value.
If the name cannot be found, or if the index
into the collection of environment variables is
out of range, the method returns an empty
string.
getServerVariableCount Returns the total number of environment
variables given by the Web server to the
Application Server.
getURLAttachment Returns the name of the temporary file
associated with the file upload form field.
getURLAttachmentCount Returns the number of attachments transferred.
getURLAttachmentExists Returns true if the named attachment exists,
and false otherwise.
getURLAttachmentType Returns the content type of the attachment
associated with the file upload form field.
124

Method Description
Chapter 5: HAHTsite Server Object Model
getURLField Given a field name, returns the value of a field
variable. (The name is case insensitive.)
Given an index (one-based) into a set of fields,
returns the corresponding name/value pair.
If a field cannot be found, the method returns
an empty string. Since there are times when an
empty string may be a valid field value, this
method is not useful for checking for the
existence of a particular field. To check for a
field’s existence, use the getURLFieldExists
or getURLFieldCount method.
getURLFieldCount Returns the number of name/value pairs in the
form or on the URL.This value refers to the
fields the browser sends with the request, not to
the total number of fields in a form as it was
created.
Given a field name, returns the number of
values sent for that field.
Note that:
If a field has multiple values, each value the
browser sends counts as a separate field.
Only the fields the browser sends are counted.
If a list box has 12 possible choices, and the
user selects 3, then the count is incremented
by 3, not 12.
getURLFieldExists Given a field name, returns true if the
specified field exists, and false otherwise.
Given a name and index n (one-based), returns
true if the nth occurrence of the field exists,
and false otherwise.
getUserProp Returns the value of a user-defined property.
isPost Returns true if this URL is a POST operation,
and false if it is a GET.
setURLField Overrides the value of a URL field that was
passed to this page. If the field doesn’t exist,
this method has no effect.
setUserProp Sets a user-defined property to a given value.
125

Chapter 5: HAHTsite Server Object Model
The Response object
The Response object lets the Web server send data back to the browser. It
includes methods for these purposes:
Topic Refer to
Writing header data “Writing headers” on page 126
Setting the values of one or more
cookies
Writing headers
Headers are part of the HTTP protocol and include information describing the
data being sent, such as the Web server name and version, the content type
and length, the date the document was last modified, language and character
set information, and redirector information. Each header line ends with a
header mark, consisting of the “” characters. A blank line signifies
the end of the header section.
Some actions — for example, setting a cookie — must take place while the Web
server is still emitting the HTTP headers, before it starts to send HTML code.
How, then, do you add header lines to an existing page? If you’re adding inline
code to an HTML page, the IDE distinguishes between code that generates
HTTP headers and code that generates HTML. If you call a method such as
addHeaderLine or setCookie, that output is stored in a separate buffer and is
sent as part of the HTTP headers. This feature lets you add in-line code to a
page without worrying about the mechanics of writing headers versus writing
HTML.
Terminating headers
If you’re writing a separate code page instead of in-line code, then you’re
responsible for writing the headers and calling endHeaders appropriately.
If you call one dynamic page from another — as a direct call, not a link — then
you must first call endHeaders, so that the HTTP headers will not be displayed
on the page.
To terminate headers, add this line to your in-line code:
126
“Setting cookies” on page 127
Writing out the HTML “Writing the HTML output” on page
129

Java
aResponse.endHeaders();
HAHTtalk Basic
aResponse.endHeaders
Chapter 5: HAHTsite Server Object Model
Anything below that line is automatically emitted as part of the HTML output
stream. If you don’t explicitly call endHeaders, it is assumed to have been
called at the end of the page.
Writing custom headers
Normally, the HAHTsite IDE writes a standard Response header. However, you
can send a custom header by calling the addHeaderLine method. If you are not
currently “in headers,” the write operation is suppressed.
Adding content information to a header line
Once a header line has been written, it can’t be changed. The one exception is
the content-type header line, containing the MIME type of the data being
sent, such as "text/html" or "image/gif." Within the IDE, the default
content-type is “text/html.” To change it, call the setContentType method.
For more information about HTTP headers, consult a reference such as W3C
(http://www.w3.org).
Setting cookies
Setting a cookie sends it to the client browser, to be stored (with the user’s
permission) on the user’s system for later retrieval. (See “Retrieving cookie
values” on page 121.) Cookies must be set in the HTTP headers (see “Writing
headers” on page 126).
To set a cookie, you specify its name and value. You may also want to set
additional attributes, such as the cookie’s expiration date or a valid domain
and path for returning the cookie. Or you may want to stipulate that the
cookie should be sent only over a secure connection.
setCookie(cookie, value) sets the cookie using default attributes (see
the table, below, for defaults).
setCookie(cookie, domain, expires, path, secure, value) sets the
additional attributes described in the table.
127

Chapter 5: HAHTsite Server Object Model
Parameter Description
cookie The name of the cookie, which should be unique for the given
path. (Within different directories or subdirectories, there may be
cookies with the same name.)
domain Specifies an Internet domain name, such as haht.com. The
cookie is sent only in response to requests to the named domain.
Note that domain will match any hosts within that domain; for
example, haht.com would also match a hostname of
products.haht.com. If domain is null, it defaults to the
hostname of the Web server that set the cookie in the first place.
expires Specifies the date on which the cookie expires, in standard GMT
format (for example, “Mon, 29-Jun-98 18:03:00 GMT”). If
expires is null, or if the date isn’t later than the current date,
the cookie automatically expires when the session ends.
path Specifies a path within a specified domain. The cookie is sent
only in response to requests to this path or any directories
contained within it. A path of /docs would also match
/docs/techsupport and /docs/marketing. If path is null,
then it defaults to the application path.
secure This argument is a boolean; if true, the cookie is secure,
meaning that the browser should send the cookie only if it has a
secure (HTTPS) connection to the Web server. (The default is
false.)
value A string containing the cookie’s value.
Multiple values within a single cookie
It’s possible to set a cookie that contains multiple pieces of data. This is
sometimes called a cookie collection. To set these values, call setCookie, passing
it the cookie name and a single string that contains all the cookie data,
separated by a delimiter that’s not used elsewhere in the cookie. Here’s an
example that uses the ampersand as a delimiter:
Java
aResponse.setCookie("dimensions", "height=10&width=5");
HAHTtalk Basic
aResponse.setCookie "dimensions", "height=10&width=5"
128

Chapter 5: HAHTsite Server Object Model
To retrieve these values, see “Retrieving cookie collections” on page 121. For
more information about setting cookies, consult the documentation for your
Web server.
Writing the HTML output
Typically, you write HTML output using print or println methods (in Java)
or the Print statement (in HAHTtalk Basic). You must add the necessary HTML
paragraph formatting tags such as “” or “...”.
Java
In a Java project, each Page automatically gets the default HTMLWriter,
using this code:
HtmlWriter out;
out = aResponse.getWriter();
If you add in-line code to your page, you can use print or println
statements like this:
out.print(aRequest.getURLfield("Name") + "");
HAHTtalk Basic
In a HAHTtalk Basic project, you can simply call the print statement, like
this:
Print aRequest.getURLField("txtLastName") & ""
The output from write operations is always buffered. At the end of the page,
the buffer is flushed. If you’re generating a long page, you can call the
Response object’s flush method to flush the output and begin buffering the
data again.
Additional write methods
There are two additional write methods you may want to use:
writeBinary writes binary data, such as GIF data. You must set the page’s
content-type to image/gif (or jpeg or png).
setWriter lets you use a subclassed HtmlWriter — for example, one that
always writes its output to a file.
129

Chapter 5: HAHTsite Server Object Model
Summary of Response object methods
Method Description
addHeaderLine Outputs a full header line. The Application Server
automatically adds the header mark, signifying
end-of-line.
clear Empties the Response object’s output stream.
end Flushes the output stream and closes the Response
writer.
endHeaders Terminates the header section of the response with a
CR/LF sequence.
flush Flushes the output stream and begins buffering data
again.
getContentType Returns a string containing the content-type header
line.
getOutputStream Returns the current output stream.
getWriter Returns the current HTML writer.
HTMLEncode Processes a string according to the HTML 3.2
specification for special characters, so that they will
display correctly on an HTML page.
inHeaders Returns true if headers are still being output, and
false if endHeaders has been called.
reset Empties the output stream.
setContentType Sets the content-type header line to the specified type.
You can call setContentType multiple times if
necessary. When endHeaders is called, the
Application Server emits the content-type header line
using the last value you set. This functionality can be
useful if you need to change the content type on the
fly.
setCookie Sets a cookie.
setOutputStream Sets the current output stream.
130

Method Description
Chapter 5: HAHTsite Server Object Model
setWriter Sets the HtmlWriter for the Response object. This
method lets you use a subclassed HtmlWriter —
for example, one that always writes its output to
a file.
URLEncode Processes a string according to the RFC 2068 and RFC
1808 specifications for special characters, so that the
string can be sent in HTTP headers.
write Writes a string to the output stream of this Response
object.
writeBinary Writes binary data, such as GIF data.
131

Chapter 5: HAHTsite Server Object Model
132

Forms-Related
Programming
6
What’s in this chapter ..................................................................................134
Calling a subroutine from a form ................................................................134
Writing the subroutine ............................................................................138
Associating the subroutine with a form .................................................139
Attaching a file to a form.............................................................................140
Adding a File Upload control to a page..................................................141
Working with a file attachment..............................................................142
Custom Form Handler widgets ....................................................................145
Writing the form-handler function.........................................................145
Creating the custom form-handler widget .............................................152
133

Chapter 6: Forms-Related Programming
What’s in this chapter
In most cases, you handle the submission of a form using a data agent or a
page that includes code that parses a URL to get the values submitted in the
form. However, HAHTsite provides additional form-handling capabilities. For
instance, you can have your application call a HAHTtalk Basic subroutine or a
Java method when a form is submitted. One of the examples in this chapter
illustrates how you might use such a subroutine to write a Binary Large Object
named in a form to a database.
Using the File Upload form field, a user can submit a file along with a form.
When the form is submitted, the file is moved to the Application Server. The
chapter discusses both how to add a File Upload field to a page and how to
manage uploaded files.
Finally, the chapter explains how to create a custom Form Handler widget in
a HAHTtalk Basic project. You may use a custom Form Handler widget if your
application requires a form handler that does something other than save form
data to a file or a Web page or include that data in an email message.
Calling a subroutine from a form
When you define the properties of a form, you can specify an action that
should occur when the form is submitted. Often, this action is to loop back to
the form page or to load a dynamic page. However, you can also request that
your application call a Java method or a HAHTtalk Basic subroutine when the
form is submitted.
Why would you want to call a method or subroutine? Usually, you use this
feature to perform some task that can’t be accomplished with a standard
command handler, like the command handler for a Move Next or Insert
button. For instance, the example discussed in this section illustrates how you
could use a form action of Subroutine to write a Binary Large Object (BLOB) to
a database. In this example, the user must enter in a form a name to associate
with a picture and the path to an image.
134

The subroutine will then take the following steps:
Chapter 6: Forms-Related Programming
1 Open a connection to the database, instantiate a Recordset, and set the
active connection for the recordset.
2 Get the filename of the image, and open the file for reading.
3 Add a new record to the recordset, and get a handle to the picture field.
4 Read chunks of data from the image file and write them to the database
field.
5 Update the recordset.
6 Close the file input stream and the recordset.
The listing below shows an abbreviated version of the subroutine as it might
appear in a Java project. For a complete listing for the subroutine — in both
Java and HAHTtalk Basic — see “Calling a subroutine as a form action” on page
362.
135

Chapter 6: Forms-Related Programming
Java
package FileUploadJava;
import com.haht.*;
import com.haht.project.*;
import com.haht.ado.Abstract.*;
import java.io.*;
class WritePictureToAccess extends Object
implements HAHTPage
{
static final int BUFSIZE = 1024;
136
public void run (Request aRequest, Response aResponse)
{
Connection myConn;
try
{
myConn = Haht.getSession().getConnectionManager().
getSharedConnectionByName("NameAndPict");
}
catch (com.haht.HahtException e)
{
return;
}
Recordset myRS = new com.haht.ado.Recordset();
myRS.setActiveConnection (myConn);
myRS.setCursorType
(com.haht.ado.CursorTypeEnum.adOpenKeyset);
myRS.setLockType
(com.haht.ado.LockTypeEnum.adLockOptimistic);
try
{
myRS.open("NameAndPict");
}
catch (java.lang.Exception e)
{
}

Java
Chapter 6: Forms-Related Programming
java.io.File pictureFile = new java.io.File
(Haht.getApplication().getUserRoot() +
'/' + aRequest.getURLAttachment("uplPicture"));
FileInputStream pictureStream;
Field pictureFld;
try
{
pictureStream = new FileInputStream
(pictureFile);
}
catch (java.io.FileNotFoundException e)
{
return;
}
myRS.addNew ();
myRS.getField("Name").setString
(aRequest.getURLField("txtName"));
pictureFld = myRS.getField("Picture");
byte [] pictureBuf = new byte[BUFSIZE];
int nBytesRead = 0;
do
{
try
{
nBytesRead = pictureStream.read(pictureBuf);
if (nBytesRead > 0)
{
pictureFld.appendChunk
(pictureBuf, nBytesRead);
}
}
catch (java.io.IOException e)
{
}
}
while (nBytesRead > 0);
137

Chapter 6: Forms-Related Programming
Java
}
Writing the subroutine
Obviously, the content of your subroutine will be determined primarily by
what you want the subroutine to do. However, there are a few guidelines that
you should follow.
In a Java project, your class must implement the HAHTPage interface. This
interface requires that you implement one method, run, whose signature is
shown below.
void run (Request aRequest, Response aResponse)
If you implement this method, when HAHTsite calls your class’s run method,
it will pass to the subroutine a Request object that contains the URL used to
execute the subroutine. You can parse this URL to obtain information such as
the picture name entered on the form that was submitted:
aRequest.getURLField("txtName");
HAHTsite also passes to the run method a Response object, which you can use
to send HTML to the user’s browser. In addition, you have the option of
passing both the Request and Resposne objects to a dynamic page when your
method has completed its part of the job.
In a HAHTtalk Basic project, there are no similar requirements for a Basic
subroutine. However, you may need to get references to your session’s Request
and Response objects — for the same reasons you need them in a Java method.
You can get these references using the following code:
138
}
myRS.update();
try
{
pictureStream.close();
}
catch (java.io.IOException e)
{
}
myRS.close();
com.haht.io.HtmlWriter out = aResponse.getWriter();
out.print("Image written to database");

HAHTtalk Basic
Dim aResponse As Object
Dim aRequest As Object
Set aResponse = Haht.getResponse()
Set aRequest = Haht.getRequest()
Associating the subroutine with a form
Chapter 6: Forms-Related Programming
Once you’ve written your subroutine, you can associate it with a form so that
when the form is submitted, the subroutine will be executed. To create this
association, perform the following steps.
To specify that a subroutine should be called when a form is submitted
1 Right-click the form to bring up a pop-up menu that displays the
operations you can perform in this context.
2 Select Form... from the pop-up menu.
The Form Properties dialog appears.
3 From the Type list box, select Subroutine.
4 In the Path text box, enter the name of the method or subroutine.
In a Java project, you may have to fully qualify this method name:
If the method is implemented outside the page that contains the form
— that is, defined in a Java source file — this name must have the
form packageName.className.methodName. For example,
FileUploadJava.WritePictureToAccess.run would be a valid name,
139

Chapter 6: Forms-Related Programming
140
assuming that the WritePictureToAccess class is part of the project
FileUploadJava. (Remember that for Java projects, the project name is
the default package name.)
If the method is implemented on the page that contains the form —
in the Server-side Code view — you need only supply the method
name.
In a HAHTtalk Basic project, you simply enter the name of the subroutine.
5 Click OK.
Your form will now cause a subroutine to be called when the form is
submitted.
Attaching a file to a form
HAHTsite’s File Upload form field enables a user to attach a file to a form and
to send the file to the Application Server’s initial working directory when the
user submits the form. The File Upload form field places a text box and a
Browse button onto a form. In his or her browser, the user can either type the
name or pathname of a file into the text box or use the Browse button to find
the file on his or her local machine or LAN.
Note - Not all browsers support this file-upload feature.
Netscape Navigator 2.0 and later does support the feature;
Internet Explorer 3.0 and earlier does not.
When the user submits a form that contains a File Upload field, the
name/value pairs for the form’s fields are sent to the Web server. The Web
server then passes this information to the Application Server, which moves a
copy of the file to its initial working directory. By default, the initial working
directory is HAHTsiteInstallDir\userroot\projectName — for example,
C:\HAHTsite4.0\userroot\FileUploadJava.
When the file is moved to the initial working directory, it is given a unique
name created by prepending the user’s state ID (a unique string) to the file’s
name. You can obtain the unique filename by using a Request object’s
getURLAttachment method. This and other methods related to handling file
attachments are discussed in “Working with a file attachment” on page 142.

Adding a File Upload control to a page
Chapter 6: Forms-Related Programming
You add a file-upload form field to a form using the IDE. The procedure for
adding this field is explained below.
To add a File Upload field to a form
1 Position your cursor on the page at the point at which you want to place
the File Upload form field.
If your cursor is inside a form, the File Upload field will be added to that
form; otherwise, the IDE will automatically create a form into which to
place the new field.
2 From the Insert menu, select Form Field > File Upload, or click the File
Upload button .
The File Upload form field is written to your form.
3 Right-click the new field to display a pop-up menu of actions you can take
in this context.
4 Select Form Field... from the pop-up menu.
The Form Field Properties dialog appears.
5 Edit the properties shown on the General tab (optional).
The table below explains what information you can enter on this tab.
Field Explanation
Name The name of the File Upload field. This is the name you
use to refer to the Java object that represents the field.
141

Chapter 6: Forms-Related Programming
6 Click OK.
This is all you have to do to enable the user to submit a file with a form and
have that file copied to the Application Server’s initial working directory. If
you want to process the file, you must use the Server Object Model methods
discussed in “Working with a file attachment” below.
Working with a file attachment
When a file is submitted with a form and you want to handle the file
programatically, you can place the code that will process the file in one of two
places:
142
Field Explanation
Value The value of the file-upload field when the form is
submitted. Normally, this will be a pathname that the
user types in or selects using the Browse button.
However, you can provide the field a default value by
setting this form-field property.
Label A label that you want to appear to the left or right of the
File Upload field when the page is browsed.
Label Alignment If you specified a label for the field, choosing the Left
radio button causes the label to appear to the left of the
field when the page is browsed, and the Right radio
button causes the label to be displayed on the right.
In a subroutine to be called when the form containing the file-upload
field is submitted. For information on calling a subroutine from a form,
see “Calling a subroutine from a form” on page 134.
In “user code” that is called when a particular form button is clicked,
causing the form to be submitted. For information on calling “user code”
from a form button, see “Calling user code from a button” on page 183.
The example used in “Calling a subroutine from a form” on page 134 is a good
illustration of manipulating a file using a subroutine called when a form is
submitted. This section refers to that example in explaining how to work with
a file submitted with a form.
If you recall, the subroutine discussed in that section takes an image file
submitted with a form and writes it to a database. In the course of moving the
contents of the file to the database, the subroutine performs two actions that
you’ll always want to perform when working with a file submitted with a
form:

Chapter 6: Forms-Related Programming
1 Check the URL used to call the subroutine to see if the URL contains a
field that holds the name of a file attachment. If this field does not exist,
the user didn’t supply a filename or some error occurred, and you should
call an error-message page.
You can determine whether the URL contains such a field using the
Request object’s getURLAttachmentExists method as shown below.
Java
// Check to see if the user has submitted a picture name and a
// filename.
if (aRequest.getURLFieldExists("txtName")
&& aRequest.getURLAttachmentExists("uplPicture"))
{
// Bulk of the subroutine goes here.
...
}
else
{
// Instantiate an error page and call its run routine.
...
}
HAHTtalk Basic
' Check to see if the user has submitted a picture name and a
' filename.
'
If (aRequest.getURLFieldExists("txtName") And _
aRequest.getURLAttachmentExists("uplPicture")) Then
' Bulk of the subroutine goes here.
...
Else
' Instantiate an error page and call its run routine.
...
End If
2 Get the name of the file that was transferred to the Application Server. The
file won’t have the same name it had when the user entered its name in
your form. HAHTsite prepends the user’s state ID to the original filename
143

Chapter 6: Forms-Related Programming
144
so that it turns out looking something like this:
T7UqieNDj0YplcN40CEVbC0_Kohahtsite.jpg.
You obtain this filename using the Request object’s getURLAttachment
method as shown below. In this example, uplPicture is the name of the
form’s File Upload form field.
Java
java.io.File pictureFile = new java.io.File
(Haht.getApplication().getUserRoot() +
'/' + aRequest.getURLAttachment("uplPicture"));
HAHTtalk Basic
Dim sPictureFileName as String
sPictureFileName = HahtApplication.getUserRoot() & "/" _
& aRequest.getURLAttachment("uplPicture")
The Request object also provides methods that enable you to determine the
content type of an attachment and to determine how many file-attachment
fields are in a URL (if there is more than one). The table below summarizes the
Request methods related to handling file attachments.
Method Explanation
getURLAttachmentCount indicates how many files were submitted with
the form
getURLAttachmentExists indicates whether the URL contains a
file-attachment field for a particular file-upload
field
getURLAttachment gets the name of the file that was attached to
the form using a particular file-upload field
getURLAttachmentType gets the content type of an attached file. This
content type might be something like
image/jpeg or audio/basic.

Custom Form Handler widgets
Chapter 6: Forms-Related Programming
HAHTtalk Basic projects include a Form Handler widget that enables you to
add to a form a button whose action is to write the values of a form’s fields to:
a file
an HTML page
an email message
HAHTtalk Basic projects also give you the ability to create custom
form-handler widgets by writing the Basic function that will be executed when
the form button representing the widget is clicked. Because this function is
passed information about the Web application, information about the
environment in which the application is running, and the contents of the
form’s fields, custom form handlers usually make use of this information. “An
example form-handler function” on page 149 illustrates how to write a
function that uses this information in a simple way.
Note - The custom form-handler widget is a useful feature, but
it has been retained primarily for compatibility with HAHTsite
3.x. This feature has not been ported to Java projects because
you can create the equivalent of a custom form-handler widget
in Java projects by writing a method that is called when a form
is submitted or when a particular form button is clicked. This
method can obtain information about the values of form fields
and the values of Web-server environment variables using the
getServerVariable method of the Request class. HAHTsite
Basic programmers can also use this technique.
The remainder of this chapter is for programmers who want to create new
custom form-handler widgets. It explains how to:
write a form-handler function in HAHTtalk Basic
how to create a form-handler widget based on the Basic function you
created earlier
Writing the form-handler function
The HAHTtalk Basic code around which you build a custom form-handler
widget must be a function, not a subroutine. In addition, the name of your
function must be the same as the name of the code file that contains it.
Included in the HAHTsiteInstallDir\scripts directory is a sample
form-handler function FormHand, which is contained in the file FormHand.hbs.
You can use this function as a template for your own form handler.
145

Chapter 6: Forms-Related Programming
Notice that the sample form-handler function requires two parameters, one of
type Environment and one of type FormArray. The Environment data structure
contains the values of a number of Web-server environment variables and
Web-application properties. The FormArray data structure contains the names
and values of your form’s form fields. For definitions of these structures, see
“Parameters of the form-handler function” on page 146.
Parameters of the form-handler function
The first parameter required by a form-handler function is a parameter of type
Environment. The definition of this data type is shown below.
146

HAHTtalk Basic
Type Environment
ComputerName as string
ComSpec as string
GATEWAY_INTERFACE as string
HTTP_ACCEPT as string
HTTP_CONNECTION as string
HTTP_HOST as string
HTTP_REFERER as string
HTTP_USER_AGENT as string
OS as string
Os2LibPath as string
Path as string
PATH_INFO as string
PROCESSOR_ARCHITECTURE as string
PROCESSOR_IDENTIFIER as string
PROCESSOR_LEVEL as string
PROCESSOR_REVISION as string
QUERY_STRING as string
REMOTE_ADDR as string
REMOTE_HOST as string
REQUEST_METHOD as string
SCRIPT_NAME as string
SERVER_NAME as string
SERVER_PORT as string
SERVER_PROTOCOL as string
SERVER_SOFTWARE as string
SERVER_URL as string
SystemRoot as string
SystemDrive as string
windir as string
NewApp as boolean
DirName as string
HTXName as string
PathName as string
PageName as string
ServerName as string
StateId as string
Timeout as long
End Type
Chapter 6: Forms-Related Programming
147

Chapter 6: Forms-Related Programming
The table below shows how the members of this structure map to WebApp
properties and environment variables retrievable via the WebApp method
Environ$. (For documentation of the WebApp object, see the HAHTsite 3.x
programmer’s guide. For information about how WebApp properties and
methods map to elements in the Server Object Model, see Appendix A,
“HAHTsite 3.x WebApp Methods and Properties.”)
Structure Member Definition
ComputerName Webapp.Environ$("COMPUTERNAME")
ComSpec Webapp.Environ$("ComSpec")
GATEWAY_INTERFACE Webapp.Environ$("GATEWAY_INTERFACE")
HTTP_ACCEPT Webapp.Environ$("HTTP_ACCEPT")
HTTP_CONNECTION Webapp.Environ$("HTTP_CONNECTION")
HTTP_HOST Webapp.Environ$("HTTP_HOST")
HTTP_REFERER Webapp.Environ$("HTTP_REFERER")
HTTP_USER_AGENT Webapp.Environ$("HTTP_USER_AGENT")
OS Webapp.Environ$("OS")
Os2LibPath Webapp.Environ$("Os2LibPath")
Path Webapp.Environ$("Path")
PATH_INFO Webapp.Environ$("PATH_INFO")
PROCESSOR_ARCHITECTURE Webapp.Environ$("PROCESSOR_ARCHITECTURE")
PROCESSOR_IDENTIFIER Webapp.Environ$("PROCESSOR_IDENTIFIER")
PROCESSOR_LEVEL Webapp.Environ$("PROCESSOR_LEVEL")
PROCESSOR_REVISION Webapp.Environ$("PROCESSOR_REVISION")
QUERY_STRING Webapp.Environ$("QUERY_STRING")
REMOTE_ADDR Webapp.Environ$("REMOTE_ADDR")
REMOTE_HOST Webapp.Environ$("REMOTE_HOST")
REQUEST_METHOD Webapp.Environ$("REQUEST_METHOD")
SCRIPT_NAME Webapp.Environ$("SCRIPT_NAME")
SERVER_NAME Webapp.Environ$("SERVER_NAME")
148

Structure Member Definition
The definition of the FormArray structure is shown below:
Type FormArray
FieldName as string
Value as string
End Type
Chapter 6: Forms-Related Programming
SERVER_PORT Webapp.Environ$("SERVER_PORT")
SERVER_PORT Webapp.Environ$("SERVER_PORT")
SERVER_SOFTWARE Webapp.Environ$("SERVER_SOFTWARE")
SERVER_URL Webapp.Environ$("SERVER_URL")
SystemRoot Webapp.Environ$("SystemRoot")
SystemDrive Webapp.Environ$("SystemDrive")
windir Webapp.Environ$("windir")
NewApp Webapp.NewApp
DirName Webapp.DirName
HTXName Webapp.HTXName
PathName Webapp.PathName
ServerName Webapp.ServerName
StateId Webapp.StateId
Timeout Webapp.Timeout
You must place the definitions of both the Environment type and the
FormArray type above your function definition in your code file. For an
example function definition, see “An example form-handler function.”
An example form-handler function
Assume that your application contains a form that requires a user to submit an
email address, a user name, and a password.
149

Chapter 6: Forms-Related Programming
When the user submits this form, the custom form handler:
150
Writes a file, Users.txt, to the Application Server’s userroot directory.
This file contains the data submitted with the form in a comma-separated
format.
Sends an email message to the user who submits the form. (Note that the
code that writes this email message uses a member of the Environment
structure.)
After the custom form handler performs these actions, the application displays
a response page that thanks the user for registering and shows the time of
registration.
The HAHTtalk Basic function for the custom form handler is shown below:

HAHTtalk Basic
Chapter 6: Forms-Related Programming
' Definitions of Environment and FormArray Types go here.
Public Function Sample(myEnv As Environment, myFields() As _
FormArray) As Integer
On Error Goto Sample_Error
Dim i As Integer
Dim m As New Message
Dim user As String
Dim email As String
Dim password As String
For i = LBound(myFields) To UBound(myFields)
If myFields(i).FieldName = "Username" Then
user = myFields(i).Value
ElseIf myFields(i).FieldName = "Password" Then
password = myFields(i).Value
ElseIf myFields(i).FieldName = "Address" Then
email = myFields(i).Value
End If
Next i
' Write information to user's file in UserRoot
Open "Users.txt" For Append As #1
Print #1, user & "," & password & "," & email
Close #1
' Mail Confirmation
m.To.New email
m.From = "info@haht.com"
m.Subject = "Registration Confirmation"
m.SmtpServer = "mailhost"
m.Body.Writeln "Registration Confirmation for " & email & _
"received from remote host: " & myEnv.REMOTE_HOST
m.Body.Writeln "Your username is: " & user
m.Body.Writeln "Your password is: " & password
m.Submit
151

Chapter 6: Forms-Related Programming
HAHTtalk Basic
Sample_Error:
Sample = 0
' Go To Response Page
Call HS_Response()
End Function
Creating the custom form-handler widget
Once you’ve written the HAHTtalk Basic function that performs the actions
you want your custom form-handler widget to perform, you can create the
widget by following the directions below.
To create a custom widget
1 Place your cursor in your form at the position where you want the widget
(represented as a form button) to appear.
2 Drag a Form Handler widget from the Widgets folder in your Project
window to your page.
152
The Form Handler Properties dialog appears.
3 Click the Custom button in the Form Handler Properties dialog box.
The Custom dialog appears.

4 Fill out the Custom dialog box.
The table below discusses each form field in the dialog.
Form Field Explanation
Chapter 6: Forms-Related Programming
Description Enter a short name for your custom
form-handler widget. HAHTsite adds this name
to the list of form handlers you can add to a
page (within this project) using the Form
Handler widget.
Code Page Name Specify the name of the .hbs file that includes
your HAHTtalk Basic function.
Redisplay Page If you leave this box checked, the page that
contains your custom form handler will be
redisplayed after the form-handler function is
executed. If your function calls a dynamic page
— as the example function does — you should
remove the check from this box.
Default Button Label Supply a label for the form-handler button.
153

Chapter 6: Forms-Related Programming
154

Form Fields
Programming
7
What’s in this chapter ..................................................................................156
Setting form-field properties ........................................................................156
Examples of setting form-field properties...............................................156
Setting and getting form-field properties ...............................................161
FormField properties................................................................................163
Button properties.....................................................................................165
Checkbox properties................................................................................167
Combo properties ....................................................................................168
FileUpload properties...............................................................................168
ListElement and Listbox classes ..............................................................169
Radiobutton properties............................................................................175
StaticText properties ................................................................................176
TextArea properties ..................................................................................178
Textbox properties ...................................................................................178
Calculating form-field values .......................................................................180
Calling user code from a button..................................................................183
Code associated with a button versus code associated with a form .....183
Configuring a button to call user code ..................................................184
155

Chapter 7: Form Fields Programming
What’s in this chapter
This chapter discusses both how to write code that affects form fields and how
to use a form field (a button) to call user-written code.
As you’ll read below, all HAHTsite form fields (text boxes etc.) are Java objects,
and these objects have methods that enable you to set their properties at
runtime. While you usually set form-field properties when you design your
form using the IDE, you may want to set some properties conditionally. For
instance, you may want to make a Move First button invisible if your
application is already displaying the first record in a recordset.
Another type of form-field programming involves manipulating values
retrieved from a data source before they are displayed in form fields. You can
change these values by adding code to a page between the data agent that
retrieves the values and the form that is populated by the data agent.
Finally, the chapter discusses how you can call “user code” when a particular
button (form field) is used to submit the form.
Setting form-field properties
Each form field in a form — whether it be a text box or a radio button — is a
Java object and has a set of properties (member variables) that you can set. This
section begins with a couple of examples that illustrate problems you can solve
by setting these form-field properties programatically. The section then
presents reference information about what properties you can set for each
object and how to set and read the values of these properties.
156
To see the introductory examples, look at “Examples of setting form-field
properties” on page 156.
For reference information about form-field properties and how to set
them, see “Setting and getting form-field properties” on page 161.
Examples of setting form-field properties
This section demonstrates how to solve two common problems by setting
form-field properties. The first example assumes that your application uses a
form to present the user with information from a database, and that the user
can navigate from record to record using Move First, Move Next, Move
Previous, and Move Last buttons. The example makes the Move Previous
button invisible if the user tries to access a record before the first record and

Chapter 7: Form Fields Programming
makes the Move Next button invisible if the user tries to access a record
beyond the last record.
The second example illustrates a simple method of internationalizing the
static text in a form.
Example 1: Turning off visibility for a button
Say that you have an application that enables users to work with the records
in an employee-information database. Users can view, insert, update, or delete
records. They can also navigate the database using Move First, Move Next,
Move Previous, and Move Last buttons.
Further, assume that you want the Move Previous button to be removed from
the form when the user’s record pointer is pointing at BOF and the Move Next
button to be removed when the user’s record pointer is pointing at EOF.
157

Chapter 7: Form Fields Programming
The code required to implement this feature is very simple. Just place the
following code somewhere between the data agent that is populating these
fields and the form.
Java
btnMoveNext.setVisible(true);
btnMovePrevious.setVisible(true);
if (daPopulater.getRecordset().getEOF()) {
btnMoveNext.setVisible(false);
}
if (daPopulater.getRecordset().getBOF()) {
btnMovePrevious.setVisible(false);
}
HAHTtalk Basic
btnMoveNext.setVisible True
btnMovePrevious.setVisible True
If (daPopulater.getRecordset().getEOF()) Then
btnMoveNext.setVisible False
End If
If (daPopulater.getRecordset().getBOF()) Then
btnMovePrevious.setVisible False
End If
158

Chapter 7: Form Fields Programming
The getBOF and getEOF methods check to see whether the current recordset of
the page’s data agent (daPopulater) is pointing before the first record or after
the last record. (For more information about HAHTsite’s interface to data
agents and their recordsets, see Chapter 8, “Data-Agent Programming.”) If one
of these conditions is true, the appropriate button’s setVisible method turns
the visibility of the object off.
Note - The first two statements in this block make both
buttons visible. Without these statements, once a button’s
visibility was turned off, it would never be turned on again.
Example 2: Internationalizing a form
Here’s another situation in which you might want to set the properties of form
fields. Say that you’re working with the interface shown in “Example 1:
Turning off visibility for a button” on page 157 and that you want to be able
to display the labels next to the text boxes in either English or Spanish. (You
can use the same technique to change the language of the text associated with
any form field.)
First, you might prompt the user for a language preference and store that
preference in a session-scope variable, for instance, language. You’ll also need
to make sure that the labels are Static Text objects, not just text. You can then
call the code shown below:
159

Chapter 7: Form Fields Programming
Java
This code assumes that you have defined the variable language in the
HahtSession class. This class is defined in the file HahtSession.java, which is
located in your project’s Session folder.
if (hahtSession.language == "Spanish") {
staLastName.setValue("Apellido:");
staFirstName.setValue("Nombre:");
staStreetAddr.setValue("Direccion:");
staCity.setValue("Ciudad:");
staState.setValue("Estado:");
staZipCode.setValue("Codigo Postal:");
}
HAHTtalk Basic
This code assumes that you’ve defined the global variable language in the file
globals.hbs.
If (language = "Spanish") Then
staLastName.setValue "Apellido:"
staFirstName.setValue "Nombre:"
staStreetAddr.setValue "Direccion:"
staCity.setValue "Ciudad:"
staState.setValue "Estado:"
staZipCode.setValue "Codigo Postal:"
End If
This code uses the setValue method of the Static Text object to change each
object’s Value member variable.
160
Note - To change a Static Text object’s label — as opposed to
the text itself — you can use the setLabel method. (In the
example above, the Static Text objects don’t have labels
because the objects are being used as labels.) You can also use
the setLabel method to change the label associated with other
form fields, for example, text boxes and radio buttons. For
most fields, the label you supply appears to the left or right of
the field when the page is browsed.

Setting and getting form-field properties
Chapter 7: Form Fields Programming
This section contains primarily reference material that details what properties
you can set for each form-field object and what methods you call to set these
properties. However, there are a couple of things you should understand about
HAHTsite form fields and their properties before you begin setting these
properties.
First, as was mentioned earlier, each form field is a Java object. Therefore, it’s
important to understand the relationships between the Java classes from
which these objects are created. These class relationships are shown in the
figure below.
FormField
Buttons Checkbox FileUpload Listbox
Radiobutton StaticText TextArea Textbox
ListElement
Combo
As you can see, most of the classes that represent objects you can place on a
page (like Button and Checkbox) are subclasses of FormField. This means that
all the properties and property-accessor methods defined in the FormField
class are inherited by the other classes shown. (For the purposes of this
documentation, this hierarchy means that the reference information for an
object of type Textbox is the union of the information presented for the
FormField class and that presented for the Textbox class.) Combo is a subclass
of Listbox as well, but this relationship doesn’t affect your use of these two
classes because they expose the same interface.
One other word of introduction. There are two methods of setting form-field
properties in HAHTsite: you can either use a set method or set a member
variable directly. The code below illustrates the use of a set method.
161

Chapter 7: Form Fields Programming
Java
staLastName.setValue("Apellido:");
HAHTtalk Basic
staLastName.setValue "Apellido:"
The following code illustrates how you can set a member variable of an object
directly:
Java
staLastName.Value = "Apellido:";
HAHTtalk Basic
staLastName.Value = "Apellido:"
HAHT recommends that you use the set methods to set form-field properties,
and, consequently, the upcoming sections document these methods as the
interface to use in setting and reading form-field properties. Again, though,
the member variables that represent these properties are public and can be set
directly. For a list of the member variables you can set for a particular object,
see the online help for the HAHTsite Server Object Model.
The table below directs you to information about setting the properties of the
object in which you’re interested.
Section Description
“FormField properties” on page
163
162
explains how to set and read the properties
that are common to all form fields.
FormField is a superclass of all the other
classes listed in this table; therefore, the
methods listed here can be used with any
form-field object.
“Button properties” on page 165 explains how to set and read the properties of
a button (a Submit button, a Reset button,
etc.)

Section Description
“Checkbox properties” on page
167
FormField properties
Chapter 7: Form Fields Programming
As was mentioned earlier, FormField is a superclass of the classes representing
the following form-field objects:
Button
Check box
Combo box
File-upload control
List box
Radio button
Static text
Text area
Text box
explains how to set and read the properties of
a check box
“Combo properties” on page 168 explains how to set and read the properties of
a combo box
“FileUpload properties” on page
168
“ListElement and Listbox classes”
on page 169
“Radiobutton properties” on
page 175
“StaticText properties” on page
176
“TextArea properties” on page
178
“Textbox properties” on page
178
explains how to set and read the properties of
a file-upload widget, which enables you to
copy a file to the Application Server when
you submit your form
explains how to change the contents of a list
box at runtime
explains how to set and read the properties of
a radio button
explains how to set and read the properties of
a static-text object
explains how to set and read the properties of
a text-area widget
explains how to set and read the properties of
a text box
163

Chapter 7: Form Fields Programming
Because these objects are created from subclasses of the FormField class, you
can use FormField methods to set properties that all of the objects have in
common. For example, you can set the visibility of any object like this:
Java
This code changes the Visible attribute of a Button object from on to off. It
assumes that the object btnMoveFirst has already been instantiated.
btnMoveFirst.setVisible(false);
HAHTtalk Basic
This code changes the Visible attribute of a Button object from on to off. It
assumes that the object btnMoveFirst has already been instantiated.
btnMoveFirst.setVisible False
The following table lists the most commonly used set and get methods for use
with all the subclasses of FormField.
Method Explanation
addExtAttr enables you to add an extended attribute to a form-field
object. This extended attribute is an HTML attribute not
represented by one of the object’s standard properties
(value, etc.). Note that case matters when you’re storing
and retrieving these extended attributes
setLabelAlignment determines whether a form field’s label is displayed on
the left or right of the field when the page is browsed.
See setLabel.
setLabel establishes the value of a label to be displayed to the left
or right of the form field when the page is browsed. All
form-field objects except those of type Button can
display labels.
setName changes the name of the form field. You use this name
to refer to the object that represents the form field.
164

Method Explanation
Button properties
HAHTsite enables you to put four types of buttons on a page:
Chapter 7: Form Fields Programming
setValue establishes the value of the form field. This is the value
that is submitted with the form. In some cases, the value
is also displayed in the browser. For example, the value
of a button is used as its label, and a text box’s value
appears in the text box.
setVisible determines whether a field is visible or not. That is, a
page’s run method or HS_ subroutine does not generate
HTML for an invisible form field.
getExtAttrValue retrieves an extended attribute of an object by name.
The name you use to retrieve the value of an attribute is
case sensitive.
getLabelAlignment indicates whether the object’s label is to be displayed on
the left or right of the corresponding form field
getLabel retrieves a form field’s current label
getName retrieves a form field’s current name
getValue retrieves a form field’s current value
isVisible indicates whether a form field is currently marked as
visible or not
toString returns an HTML representation of the form field as a
string
Submit button - submits the values on a form to a form handler or
performs some database-related action
Reset button - returns the form fields’ values to what they were when the
page was first displayed
Button button - executes a client-side script
Image button - similar to a Submit button except that its label is an
image instead of text
You can set a button’s properties programatically to accomplish such tasks as
the following. Suppose that you want to set a session-scope variable to change
the labels on all of your buttons from text labels to pictures. You could
accomplish this task using code similar to the following:
165

Chapter 7: Form Fields Programming
Java
if (hahtSession.picturesOnButtons == true) {
btnMoveFirst.setStyle
(com.haht.project.form.Button.STYLE_IMAGE);
btnMoveFirst.setPictureURL(Haht.getSession().createStaticURL
("HAHTsite.gif","default"));
}
HAHTtalk Basic
If (HahtSession.picturesOnButtons = True) Then
Set Haht_TempJavaObj = GetJavaClass _
("com.haht.project.form.Button")
btnMoveFirst.setStyle Haht_TempJavaObj.STYLE_IMAGE
btnMoveFirst.setPictureURL HahtSession.createStaticURL _
("HAHTsite.gif", "default")
Set Haht_TempJavaObj = Nothing
End If
You use the setStyle method to change a button from one type to another
(from a Submit button to an Image button, for example) and the
setPictureURL method to specify the location of the image to be displayed on
the button.
The table below lists the methods of the Button class that you can use to set
and retrieve the properties of a Button object.
Method Explanation
setLowSrcURL specifies the URL of the image to be used as an Image
button’s Low-Resolution Image
setPictureURL specifies the URL of the image to be used as an Image
button’s Source Picture
setStyle sets a button’s type to one of the following values:
Submit, Reset, Button, or Image
getLowSrcURL gets the URL of the image being used as an Image
button’s Low-Resolution Image
getPictureURL gets the URL of the image being used as an Image
button’s Source Picture
166

Method Explanation
getStyle gets the type of a button
Checkbox properties
Chapter 7: Form Fields Programming
When you add a check box to a form using the IDE, you can specify:
the value of the check box if the form it is on is submitted while the box
is checked
the value of the check box if the form it is on is submitted while the box
is unchecked
the initial state of the checkbox: checked or unchecked
You can also set or read these properties — and others — at runtime using
methods of the Checkbox class. For example, you might want to determine at
runtime whether a check box, chkExample, should be checked or unchecked
when it is first displayed. To do this, you would include code similar to the
following above the form that contains the check box.
Java
if (...) {
chkExample.setChecked(true);
}
HAHTtalk Basic
If (...) Then
chkExample.setChecked True
End If
The table below enumerates the methods used most often to work with check
box properties.
Method Explanation
setChecked enables you to change the checked status of a
check box — from unchecked to checked or
from checked to unchecked
167

Chapter 7: Form Fields Programming
Method Explanation
setCheckedIfValueIs sets the checked status of a check box to
checked if a string that you pass as an argument
matches the current checked value of the check
box
setUnCheckedValue sets the value the check box has when the
check box is unchecked
getUnCheckedValue retrieves the check box’s unchecked value
isChecked returns the value of the Checked member
variable, which indicates whether the check box
will be checked when the page it is on is
displayed
168
Note - You set the checked value of a check box using the
setValue method, which Checkbox inherits from FormField.
Combo properties
In the Server Object Model, Combo is a subclass of Listbox. However, while
Combo overrides a few methods defined in the Listbox class, this is entirely
transparent to you. The interface used to set and read combo box properties is
exactly the same as the interface used to work with list boxes. See “ListElement
and Listbox classes” on page 169 for a description of this interface.
FileUpload properties
The properties you can set for a file-upload field are all very general. You can
set the field’s:
Name
Value
Label
Label alignment
Visibility
The methods you use to work with these properties are all inherited from
FormField. Therefore, you can find reference information about these
methods in “FormField properties” on page 163.

ListElement and Listbox classes
Chapter 7: Form Fields Programming
The ListElement and Listbox classes enable you (and HAHTsite) to create list
boxes that contain particular sets of list entries, or elements. An object of the
Listbox class represents the list box itself, and each entry in the list is an
object of type ListElement.
Note - List elements can also be added to combo boxes since
Combo is a subclass of Listbox.
There are three possible types of list elements:
Design-time list elements. HAHTsite creates design-time list elements
when you use the IDE to create a list box and add list items to the list.
For each list item, HAHTsite instantiates a list element with a type
property whose value is STATIC_ELEMENT.
Populater list elements. If you design a page so that a data agent is used
to populate a list box or combo box, for each list item, HAHTsite
instantiates a list element of type POPULATER_ELEMENT.
Runtime list elements. These are elements — of type PAGE_RUN_ELEMENT
— that you add to a list box or combo box by making calls to
ListElement and Listbox methods.
Any list box can contain any combination of these three types of elements.
For information about creating list elements and working with list boxes, see
the following sections:
“Creating list elements” on page 169
“Getting and setting ListElement properties” on page 171
“Adding list elements to a list” on page 171
“Selecting an element in a list” on page 172
“Finding an item in a list” on page 173
“Getting and setting Listbox properties” on page 173
Creating list elements
List box
List element
A list element has four member variables:
A display value. This is the string that is displayed in the list.
169

Chapter 7: Form Fields Programming
170
An internal value. This is the value of the list box when the form
containing the list box is submitted with a particular display value
selected. Each display value has a corresponding internal value.
A selected status. If a list element's selected status is set to true, the list
element will be highlighted when the list box is displayed.
An element type (or creation type). This type indicates whether the
element was created at design time, by a populater, or by user-written
code. The following constants represent these three types:
STATIC_ELEMENT, POPULATER_ELEMENT, and PAGE_RUN_ELEMENT. HAHTsite
uses this type to determine when to remove elements from a list.
Design-time elements are never removed; populater elements are
removed each time the list box is populated; and page-run elements are
removed each time the page is run.
To create a list element, you call one of the ListElement class's constructors.
ListElement(String aDisplayVal)
ListElement(String aDisplayVal, String anInternalVal,
boolean aSelOnOff, int aCreateFlag)
If you use the first form of the constructor, HAHTsite sets the list element's
internal value to the empty string, its selection flag to false, and its type to
STATIC_ELEMENT.
The code fragments below illustrate how to instantiate a list element in both
Java and HAHTtalk Basic.
Java
ListElement element1 = new ListElement("JaneDoe", "12345",
false, PAGE_RUN_ELEMENT);
HAHTtalk Basic
Dim element1 As Object
Set element1 = CreateJavaObject("ListElement", "Jane Doe", _
"12345", False, PAGE_RUN_ELEMENT)
In this case, the list element’s display value is “Jane Doe,” its internal value is
Jane’s employee number 12345, and the element will not be highlighted by
default.

Chapter 7: Form Fields Programming
Note - It's also possible to create a list element and insert that
element into a list in a single step. For information on how to
do this, see “Adding list elements to a list” on page 171.
Getting and setting ListElement properties
Once you've created a ListElement, you can read or set the properties of this
object using the methods listed in the table below.
Method Description
setCreateFlag Indicates whether this list element was created at design
time, by a populater (a data agent), or by user code. In
your code, you’ll want to set this flag to
PAGE_RUN_ELEMENT to indicate that you’re adding this
item to the list at runtime.
setDisplayValue Sets a list element’s display value, the value that will be
shown in the list box.
setInternalValue Sets a list element’s internal value. This value will be the
list box’s value when the form is submitted.
setSelected Sets the list element’s selected flag, to determine
whether the list element will be highlighted when the
list box is displayed.
getCreateFlag Reads the list element’s element type: STATIC_ELEMENT,
PAGE_RUN_ELEMENT, or POPULATER_ELEMENT.
getDisplayValue Reads the list element’s display value.
getInternalValue Reads the list element’s internal value.
isSelected Gets the value of the list element’s selected flag.
Adding list elements to a list
This section covers how to insert list elements into a list box and how to
remove them.
You have three options when you insert a list element (or elements) into a list
box. You can:
Insert a list element that you created earlier.
Create a list element and insert it into a list box in a single step.
Insert a vector of list elements into a list box.
171

Chapter 7: Form Fields Programming
The prototypes for the methods that perform these tasks are shown below:
int insertElementAt(ListElement anElement, int index)
int insertElementAt(String aDisplayVal, String an InternalVal,
boolean aSelOnOff, int aCreateFlag, int index)
void insertElementAt(Vector aList, int index)
For each method, the index parameter indicates the point in the list at which
the new element(s) should be added. For example, if you specify an index of
3, the new element will become the third item in the list box's list.
172
Note - You can replace an existing list item using the method
setElementAt. (This method’s counterpart, getElementAt,
returns the ListElement object at a particular index.)
To remove an item from a list box, use one of the methods shown in the table
below.
Method Description
removeAllElements Removes all of a list box’s list items.
removeElementAt Removes the list item at a particular index into the list.
removeElements Removes all list items of a particular type:
STATIC_ELEMENT, PAGE_RUN_ELEMENT, or
POPULATER_ELEMENT.
Selecting an element in a list
Using methods of the Listbox class, you can specify:
Whether the user can select only one value from the list box before
submitting the form containing the list box, or whether the user can
select several values.
Which list element or elements (if any) should be highlighted (selected)
when the list box is first displayed.
A Listbox object contains a member variable that determines whether
multiple selections are allowed. You can read the value of this variable using
the method isMultiple, and you can set the value using the method
setMultiple. If the variable is set to true, multiple selections are allowed.
Note - One difference between list boxes and combo boxes is
that combo boxes do not allow multiple selections.
To indicate that a list item should be selected — or deselected — when the list
box is displayed, use one of the methods listed in the table below.

Method Description
Finding an item in a list
Chapter 7: Form Fields Programming
selectIfDisplayValueIs Clears the existing selection, and then selects all
of the items in the list whose display value
matches a value you supply.
selectIfInternalValueIs Clears the existing selection, and then selects all
of the items in the list whose internal value
matches a value you supply.
selectItem Selects the item at the position you indicate. If
this is a single-select list box, all other items are
deselected.
deSelectAll Deselects all of the elements in the list.
deSelectItem Deselects the element at the position indicated
by an index.
The Listbox class contains several methods that enable you to determine the
current location (index) of a list element within a list box. These methods are
shown in the table below.
Method Description
findDisplayValue Finds an element with a display value equal to a
value you supply. The comparison ignores case.
findInternalValue Finds an element with an internal value equal to a
value you supply. The comparison ignores case.
getSelected Finds the first selected item that follows an index
you provide.
Getting and setting Listbox properties
The Listbox class also contains accessor methods that enable you to get or set
a number of properties of the list box or of a list element contained in the list
box. See the table below.
173

Chapter 7: Form Fields Programming
Method Description
setInsertPopulaterElementsFirst Moves any list elements of type
POPULATER_ELEMENT to the beginning
of the list. By default, such entries are
placed at the end of the list.
setMultiple Sets or clears the HTML attribute
multiple for this list box. This
attribute controls whether or not
multiple selections are allowed in the
list box.
setSize Sets the HTML size attribute. The
size attribute controls the number of
elements that will be visible when the
list box is displayed in the browser.
getDisplayValue Returns the display value of the list
element at the index you supply.
getElementCount Returns the number of list elements in
the list.
getInsertPopulaterElementsFirst Indicates whether list elements of type
POPULATER_ELEMENT will be displayed
in the list box first or last.
getInternalValue Returns the internal value of the list
element at the index you supply.
isMultiple Returns true if the multiple attribute
is set for this list box; otherwise, it
returns false.
isSelected Returns true if the list element at the
index you specify is selected. Returns
false if the item is not selected or
doesn't exist.
getSize Returns the value of the list box’s size
(HTML) attribute. The size attribute
controls the number of elements that
will be visible when the list box is
displayed in the browser.
174

Radiobutton properties
Chapter 7: Form Fields Programming
By setting the properties of Radiobutton objects, you can control at runtime
such things as which radio button in a group is selected. For example, say that
one of your forms has a group of three radio buttons — radioSelf,
radioSpouse, and radioDependent — and that when you created the radio
buttons you chose to have radioSelf checked by default. However, at runtime
you would like to be able to change which radio button is selected by default.
Perhaps if the last time the form was submitted, the radioSelf radio button
was checked, you would like the radioSpouse radio button to be checked by
default. You can make this change by using the Radiobutton method
setChecked.
Java
if (...) {
radioSelf.setChecked(false);
radioSpouse.setChecked(true);
}
HAHTtalk Basic
if (...) Then
radioSelf.setChecked False
radioSpouse.setChecked True
End If
The table below lists all of the methods commonly used to set and read the
properties of radio buttons:
Method Explanation
setCheckedIfValueIs sets the radio button’s Checked variable to
true if the argument you pass to the method
matches the current value of the radio button.
If this variable is set to true, the radio button is
checked when its page is first displayed.
setChecked sets the radio button’s Checked variable to
true unconditionally. If this variable is set to
true, the radio button is checked when its page
is first displayed.
175

Chapter 7: Form Fields Programming
Method Explanation
setGroupName establishes the name of the button group to
which a radio button belongs
getGroupName retrieves the name of the button group to which
a radio button belongs
isChecked determines whether a radio button’s Checked
variable is set to true
StaticText properties
There are a couple of common reasons for setting a property of a static-text
field at runtime. For example, suppose that a static-text field on your page is a
hypertext link and that you want to be able to set the destination of the link
at runtime. You could use code similar to the following to accomplish this
task.
Java
if (...) {
staticLink.setHREF(hahtSession().createStaticURL
("Destination.html","default"));
}
HAHTtalk Basic
If (...) Then
staticLink.setHREF HahtSession.createStaticURL _
("Destination.html", "default")
End If
As another example, consider the case where you’ve read a currency value
from a database and assigned it to a static-text field. By default, this value will
be displayed without the proper formatting. To display the value as a dollar
amount, you would normally set the Format property of the static-text field
using the IDE. However, you could also format the value by calling the method
setDisplayText above the form containing the field:
176

Java
Chapter 7: Form Fields Programming
static1.setDisplayText(com.haht.Haht.format(static1.value,
"Currency"));
HAHTtalk Basic
static1.setDisplayText Format$(static1.value,"Currency")
Note - For a list of the predefined formats you can use in this
call, see Chapter 14, “Working with Form Fields,” in the
HAHTsite IDE and IP User’s Guide.
The table below lists the methods most commonly used to set and read the
properties of StaticText objects.
Method Explanation
setDisplayText controls the string to be displayed in a
static-text field without changing the
underlying value of the field. Usually, this string
is a reformatted version of the field’s value. You
can reformat this field’s value using the
Format$ function (HAHTtalk Basic) or the
format method (Java).
setEscapeHTMLChars determines whether characters such as ‘’ in a static text field’s value are interpreted as
being part of an HTML tag or not. If an object’s
mEscapeHTMLChars variable is set to true (the
default), these characters are interpreted as
HTML and are used in formatting the
non-HTML portion of the value. If the variable
is set to false, the characters are displayed as
part of the value.
setHREF used with static text that is (the default
case)also a link. Establishes the URL of the page
being linked to.
setLinkID used with static text that is also a link. Sets the
project ID of the page being linked to.
177

Chapter 7: Form Fields Programming
Method Explanation
setTarget used with static text that is also a link.
Establishes the frame in which to display the
page being linked to.
getHREF used with static text that is also a link. Returns
the URL of the destination page.
getLinkID used with static text that is also a link. Returns
the project ID of the destination page.
getTarget used with static text that is also a link. Returns
the name of the frame in which the destination
page will be displayed.
isEscapeHTMLChars returns true if HTML special characters are
being interpreted as such
TextArea properties
A text-area object’s properties enable you determine at runtime the size of the
text area and whether word wrap is turned on or off. The table below lists the
methods that you use to set and read these properties.
Method Explanation
setCols establishes the number of columns in the text
area
setRows establishes the number of rows in the text area
setWordWrap turns word wrap on or off. If word wrap is off,
your text remains on one line until you type
Enter.
getCols returns the number of columns in a text area
getRows returns the number of rows in a text area
isWordWrap determines whether word wrap is on or off
Textbox properties
Being able to set text-box properties at runtime is handy for many tasks,
including internationalization. For instance, the code below enables you to set
178

Chapter 7: Form Fields Programming
the size of a Phone field to 12 if the user is working in the United States and
to 16 if the user is working in France:
Java
if (language == "English") {
txtPhone.setSize(12);
}
else if (language == "French") {
txtPhone.setSize(16);
}
else {
...
}
HAHTtalk Basic
If (language = "English") Then
txtPhone.setSize 12
ElseIf (language = "French") Then
txtPhone.setSize 16
Else
...
End If
The table below lists the most useful of the methods you can use to set and
read the properties of Textbox objects.
Method Explanation
setHidden sets a Textbox object’s Hidden variable to true
or false. If this variable is set to true, the text
box becomes a “hidden” form field; otherwise,
it’s a regular text box.
Primarily used for compatibility with HAHTsite
3.x.
setMaxLength establishes the maximum number of characters
that can be entered in the field
setPassword used to indicate that a text box is a password
field. When you enter characters in a password
field, they are not echoed literally.
179

Chapter 7: Form Fields Programming
Method Explanation
setSize determines the width of the text box in
characters, that is, how many characters you
can view at once
getMaxLength returns the maximum number of characters
that can be entered in the field
getSize returns the width of the field in characters
isHidden returns the value of the object’s Hidden
variable, which determines whether the text
box is a “hidden” field
isPassword returns the value of the object’s Password
variable, which determines whether the field is
a password field or not
Calculating form-field values
Suppose that you’ve developed a form to display information stored in a
database concerning the quarterly sales totals for your sales people.
A data agent on your HTML page retrieves each sales person’s name, employee
number, and quarterly sales figures from a database and displays them in your
form.
180

Chapter 7: Form Fields Programming
This is fine. But suppose you also want the form to display each sales person’s
total sales for the fiscal year to date. This is not the type of value that you
would store in your database because it can easily be calculated from the
quarterly sales figures. The remainder of this section explains how to perform
this type of calculation and display the result using HAHTsite.
Suppose your HTML page contains a heading, followed by a data agent,
followed by a form. If you add code between the data agent and the form, that
code will be executed:
after the data agent has performed the most recently requested
command, such as Move Next
before the data retrieved by the data agent is actually displayed in the
form
You can use methods of the form-field classes used in the form to read and set
the values that will be displayed in the form.
Assume that you want to take the quarterly sales figures retrieved by the data
agent, calculate the yearly total, and display that total in a static-text field
labeled Year-to-Date Sales. You can do this using the code shown below.
181

Chapter 7: Form Fields Programming
Java
try
{
double salesQ1 = (new
Double(staticFirstQtrSales.getValue())).doubleValue();
double salesQ2 = (new
Double(staticSecondQtrSales.getValue())).doubleValue();
double salesQ3 = (new
Double(staticThirdQtrSales.getValue())).doubleValue();
double salesQ4 = (new
Double(staticFourthQtrSales.getValue())).doubleValue();
double salesCY = salesQ1 + salesQ2 + salesQ3 + salesQ4;
String salesCYStr = Double.toString(salesCY);
staticYearSales.setValue(salesCYStr);
}
catch ( NumberFormatException e )
{
out.println("Exception = " + e.getMessage());
}
HAHTtalk Basic
Dim Q1Sales As Double
Dim Q2Sales As Double
Dim Q3Sales As Double
Dim Q4Sales As Double
Dim FYSales As Double
Q1Sales = Val(staticFirstQtrSales.getValue())
Q2Sales = Val(staticSecondQtrSales.getValue())
Q3Sales = Val(staticThirdQtrSales.getValue())
Q4Sales = Val(staticFourthQtrSales.getValue())
FYSales = Q1Sales + Q2Sales + Q3Sales + Q4Sales
staticYearSales.setValue Str$(FYSales)
This code uses the getValue method of the quarterly sales static-text objects
to obtain the quarterly sales figures. The code then sums the quarterly figures
and calls the setValue method to set the value of a year-to-date-sales
static-text field. When the form is displayed, the sum will be displayed in the
appropriate field.
182

Chapter 7: Form Fields Programming
For more information about setting and reading form field attributes using the
setValue and getValue methods, see “Setting and getting form-field
properties” on page 161.
Calling user code from a button
Similar to the way in which your application can call a subroutine associated
with a form at the time you submit the form, you can have your application
execute “user code” associated with a button when a form is submitted as a
result of that button being clicked. These two features give you similar
capabilities; in fact, the example presented in “Calling a subroutine from a
form” on page 134 (writing a BLOB to a database) could just as well have been
handled by “user code” associated with a button. However, there are also
important differences between the two methods of calling user code. These
differences are discussed in “Code associated with a button versus code
associated with a form” below.
This section also covers the mechanics of configuring a button to have a
Submit Action of User Code.
Code associated with a button versus code associated
with a form
Many tasks can be handled in either a subroutine associated with a form or
user code associated with a particular button; in both cases, HAHTsite executes
code when a form is submitted. However, it’s important to understand the
183

Chapter 7: Form Fields Programming
differences between these two actions and how the actions relate to one
another.
The obvious differences are that:
184
a subroutine associated with a form is executed every time its form is
submitted, while user code associated with a button is executed only
when its form is submitted as a result of a particular button being pressed
only one subroutine can be associated with a form while you can
associate different subroutines with different form buttons
One thing, however, might not be so obvious. On a single page, you can’t use
both a form action of Subroutine and a button action of User Code. This fact
has to do with the way in which command handlers for buttons are generated.
If the form’s action is not Automatic/SELF, HAHTsite does not even generate a
command handler for a form button, so any subroutine you associated with
that button will never be called. You must loop back to the page on which you
began before the “user code” associated with a button can be executed.
Configuring a button to call user code
To configure a button so that user-supplied code is called when the button is
selected, follow these steps.
To configure the button:
1 Double-click the form button to bring up the Form Field Properties
window.

2 From the Action combo box, select the User Code option.
Chapter 7: Form Fields Programming
A group of fields labeled Subroutine appears in the window.
3 In the Definition field, enter the name of a Basic subroutine or a Java
method.
In a Basic project, you can enter the name of any subroutine in the
project, along with any required parameters. In a Java project, you must
adhere to the following rules:
You must enter the name of a method defined on the current page. This
means that you must have used the page’s Server-side Code view to
enter your code.
Enter an argument list. The argument list can be empty, but the
parentheses must be present.
Don’t terminate your call with a semicolon. The code generator adds a
semicolon for you.
4 Select the OK button.
185

Chapter 7: Form Fields Programming
186

Data-Agent
Programming
8
Data agents and command handlers ...........................................................188
Calling data-agent methods at runtime.......................................................190
Setting a data agent’s command .............................................................190
Performing a data-agent action...............................................................192
Getting and setting the values of a data agent’s fields ..........................196
Getting a reference to a data agent’s connection...................................198
Dealing with recordsets ...........................................................................198
Getting parameters to stored procedures................................................202
Refreshing a data agent’s data.................................................................203
Sorting records .........................................................................................204
Filtering records .......................................................................................205
Handling errors........................................................................................210
Enabling tracing.......................................................................................210
The structure of a command handler..........................................................212
Modifying a command handler ...................................................................216
Where to add code to a command handler ...........................................216
Examples of adding code to a command handler .................................217
Changing the flow of control in a command handler ..........................225
Example of changing the flow of control ..............................................227
187

Chapter 8: Data-Agent Programming
Data agents and command handlers
As you know if you’ve created a HAHTsite page that links a form to a database,
HAHTsite uses objects called data agents to:
188
get an ADO recordset from a data source
populate form fields in a form using a set of bindings defined in the data
agent
HAHTsite performs actions against the data agent’s recordset when a user
clicks a form button. For example, if the user clicks a Move Next button, code
generated by HAHTsite calls the data agent’s performAction method using an
argument that indicates that the data agent should change its current record.
Once the data agent’s record pointer has been updated, the page can exit. The
next time the page is run, the data agent will populate the form with data from
the new current record.

Chapter 8: Data-Agent Programming
The code generated to perform the action associated with a form button is
called a command handler. Each button has its own command handler, and this
method or subroutine performs the following tasks:
If the Submit Action associated with the clicked button was Insert or
Update, the command handler binds the data in the form to fields in the
data agent’s current record. If the action was Query or Find, the
command handler fills in the Query or Find criteria.
In all cases, the command handler performs the requested operation.
If the operation was successful, the command handler calls the button’s
success page.
If the operation was not successful, the command handler calls the
button’s failure page.
The remainder of this chapter discusses two important ways in which you can
customize pages that include data agents:
You can call data-agent methods directly by placing Java or HAHTtalk
Basic code on your page (Server-side Code view).
In this view, you’ll see two methods or subroutines named
dataAgent_OnPreRun and dataAgent_OnPostRun. When you execute your
page, dataAgent_onPreRun executes immediately before the
dataAgent.run routine executes. (dataAgent.run executes the data agent’s
initial command, if necessary, and opens the data agent’s recordset.) The
dataAgent_OnPostRun routine executes immediately after dataAgent.run
completes — before any data retrieved from the data source has been
bound to form fields.
The dataAgent_OnPreRun method or subroutine is a good place to do such
things as change the data agent’s command, and the
dataAgent_OnPostRun routine gives you an opportunity to examine the
values in the data agent’s current record before the values in that record
are bound to form fields.
For further information about the DataAgent methods you can call from
these routines, see “Calling data-agent methods at runtime” on page 190.
You can customize the command handlers that HAHTsite generates to
control what happens when a user clicks a form button. You can add
functionality to these command handlers or change the normal flow of
control in them. For additional information on this subject, see “The
structure of a command handler” on page 212 and “Modifying a
command handler” on page 216.
189

Chapter 8: Data-Agent Programming
Calling data-agent methods at runtime
The DataAgent class includes a number of methods that enable you to control
the behavior of a data agent at runtime. This section contains information
about the most frequently used of these methods. This subset of methods
allows you to:
190
set the command that a data agent will use to get its recordset
perform a data-agent action, such as inserting a record
get or set the value of a field in a data agent’s recordset
get a reference to a data agent’s connection
get a reference to a data agent’s recordset
get the values of a stored procedure’s output parameters
refresh a data agent’s data
sort a data agent’s records
filter the records going in to the data agent’s recordset
handle a data agent’s errors
enable tracing for a data agent
Setting a data agent’s command
The command associated with a data agent determines how the data agent
obtains its recordset. This command can be a database table name, the name
of a stored procedure, the name of a view, or (if the data agent is connected to
a relational database) a SQL statement. You set such a command when you
create a data agent using the IDE; however, you can override this original
command using the DataAgent class’s setCommand method.
For example, say that you have a project that displays records from an
employee-information database and that the data agent in your project uses a
table name (Employees) as its command. You could quickly modify this
project to display information only about employees from North Carolina by
adding code similar to the following to your page’s dataAgent_OnPreRun
routine (Server-side Code view).
Java
da1.setCommand("SELECT * FROM Employees WHERE State = 'NC'");
da1.setCommandType (com.haht.ado.CommandTypeEnum.adCmdText);

HAHTtalk Basic
Chapter 8: Data-Agent Programming
da1.setCommand "SELECT * FROM Employees WHERE State = 'NC'"
da1.setCommandType ADO_CommandTypeEnum_adCmdText
In this case, the data agent’s command is being changed from a table name to
a SQL statement. Note that you provide the new command using the
setCommand method and that you use the setCommandType method to specify
the type of the new command. (You don’t need to specify the type if the
command type isn’t changing.) The table below shows the Java class variables
(constants) that you can use with the setCommandType method in Java
projects.
Constant Meaning
CommandTypeEnum.adCmdStoredProc The command is the name of a stored
procedure.
CommandTypeEnum.adCmdTable The command is the name of a table
or a view.
CommandTypeEnum.adCmdText The command is a textual command,
such as a SQL statement. The
command might also be a command
requesting data from a nonrelational
data source.
CommandTypeEnum.adCmdUnknown The type of the command is
unknown.
In HAHTtalk Basic projects, you use similar constants, but the constants have
slightly different names:
ADO_CommandTypeEnum_adCmdStoredProc
ADO_CommandTypeEnum_adCmdTable
ADO_CommandTypeEnum_adCmdText
ADO_CommandTypeEnum_adCmdUnknown
The Basic constants are defined in the file ADOConstants.hbh, which HAHTsite
automatically includes in the generated code for every page that contains a
data agent.
191

Chapter 8: Data-Agent Programming
192
Note - These constants are defined so that Basic projects do not
have to incur the overhead of creating a Java class object in
order to set a data agent’s command type.
That’s all there is to changing a data agent’s command. However, there are a
couple of side effects of using the setCommand method that you should be
aware of:
If your command is the name of a stored procedure, any “pre-fetch”
filtering or sorting operations are changed to “post-fetch” filtering or sort
operations. This change is necessary because “pre-fetch” operations can
modify the command text by adding a WHERE or ORDER BY clause, which
is inappropriate for a stored-procedure call.
If you change the command from a non-SQL command to a SQL
command, the data agent’s mIsStandardSQL member variable remains set
to false until you explicitly change it. If you are performing pre-fetch
filtering or sorting, you should change the value of this variable by
calling setIsStandardSQL with a parameter of true. Pre-fetch operations
are usually more efficient if mIsStandardSQL is set to true.
If the data agent whose command you are setting is being used to
populate a form (which is typically the case), the data agent’s notion of
which Page Items (form fields) are bound to which Data Items (fields in
the data agent’s recordset) must be taken into consideration. That is, the
recordset retrieved by the new command must contain a field with the
appropriate name and data type for each of the data agent’s Data Items so
that the data agent can populate the corresponding form fields.
If the original data-agent command was to call a stored procedure and
the new command is to call a different stored procedure, the two stored
procedures must have the same parameters, or they need to be modified.
Performing a data-agent action
A data agent usually performs actions, such as changing the current record or
updating a record, when a user clicks a form button whose target is that data
agent. The data agent also performs an action the first time that the page on
which it appears is run. All this is typically handled with generated code.
However, it’s also possible to write code that causes the data agent to perform
an action:
when a form button is clicked
when the data agent’s page is first displayed
The following sections explain in more detail how to write this type of code.

Performing data-agent actions
Chapter 8: Data-Agent Programming
Typically, a data agent performs an action when the command handler
associated with a form button calls the data agent’s performAction method.
It’s also possible to call this method directly.
The two prototypes for this method are shown below:
boolean performAction(int anAction)
boolean performAction(int anAction, java.lang.Object
anActionArg)
The first form of the method takes as its argument a constant. In Java projects,
this constant is a final class variable of the class
com.haht.project.datamanager.DMConstants. The constants you can use
with the first form of this method are shown in the table below.
Constant Action
ACTION_ADD_NEW adds a new record to the data agent’s recordset
ACTION_CANCEL_UPDATE enables you to cancel an Insert operation after a
new record has been created, but before the
record has been updated
ACTION_CLEAR clears the form fields being populated by the
data agent
ACTION_DELETE deletes the data agent’s current record
ACTION_FIND performs an ADO Find operation. Finds the first
record in the data agent’s recordset that meets a
single criterion and moves the current-record
pointer to that record. You must have set up
your find criterion (by calling
setFindCriteria) before you perform this
action.
ACTION_INSERT inserts the values of the form fields being
populated by the data agent into a new record
in the data agent’s recordset
ACTION_MOVE_FIRST makes the first record in the data agent’s
recordset the current record
ACTION_MOVE_LAST makes the last record in the data agent’s
recordset the current record
ACTION_MOVE_NEXT makes the next record in the data agent’s
recordset the current record
193

Chapter 8: Data-Agent Programming
Constant Action
ACTION_MOVE_PREVIOUS makes the previous record in the data agent’s
recordset the current record
ACTION_NEXT_RECORDSET loads a new recordset into the data agent — the
next in a series of recordsets retrieved by the
data agent’s last command
ACTION_NONE no action
ACTION_QUERY returns a set of records (from the data agent’s
recordset) that meet a set of criteria you supply.
You must establish these criteria by making one
or more calls to setQueryCriteria before you
perform this action.
ACTION_REQUERY causes the data agent to get a new recordset by
calling the data agent’s current command
(established by the last call to setCommand)
ACTION_UPDATE updates the data agent’s current record
You use similarly named constants in a HAHTtalk Basic project. You just need
to prepend DMConstants_ to a name shown in the table above. For example,
to request a move-next action, you would use the constant
DMConstants_ACTION_MOVE_NEXT. These Basic constants are defined in the file
SOMConstants.hbh, which is included in the generated code for every page
with a data agent.
There are also two constants that require or may take an associated argument:
ACTION_EXEC_COMMAND and ACTION_FIND
(DMConstants_ACTION_EXEC_COMMAND and DMConstants_ACTION_FIND in Basic
projects). You use these constants with the second form of the performAction
method. (The constant is the first argument to the method.)
The constant ACTION_EXEC_COMMAND causes performAction to execute the
command that you supply as an argument (the second argument to
performAction). The argument associated with ACTION_EXEC_COMMAND can be
a string or null.
194
If the argument is a string, it must be the command that you want the
data agent to use to get a new recordset. This command can be the name
of a table, the name of a stored procedure, and so forth. (This argument
is analogous to the argument to the setCommand method.)
If the argument is null, performAction executes the last command set
using the setCommand method.

Chapter 8: Data-Agent Programming
The constant ACTION_FIND causes performAction to find the next record in
the recordset that meets the criterion specified in its associated argument, a
string. This string must have the form columnName operator value. For
example, the string "State = 'NC'" is a valid find-criteria string.
Note - Both a connection and a recordset must be open before
you call performAction with any constant other than
ACTION_NONE or ACTION_EXEC_COMMAND. In addition, a
connection must be open before you call performAction with
the constant ACTION_EXEC_COMMAND.
Here’s an example of how you might use the performAction method in your
project. Say that your application calls a stored procedure that returns two
recordsets and that the two recordsets have the same columns. You can only
work with the first recordset using the standard data agent commands. To load
the second recordset into the data agent, you would need to call
performAction with the ACTION_NEXT_RECORDSET argument. For example, you
could add code to the command handler for a Move Next button to have your
application load the second recordset when a user clicks a Move Next button
while looking at the last record in the first recordset.
Note - For detailed information about command handlers, see
“The structure of a command handler” on page 212 and
“Modifying a command handler” on page 216.
Setting a data agent’s initial command
It’s also possible to set a data agent’s initial command programatically. You do
this using the setInitialAction method, whose prototype is shown below:
void setInitialAction(int anAction)
This method takes as its argument a constant defined in the class
com.haht.project.datamanager.DMConstants (Java projects) or in the file
SOMConstants.hbh (HAHTtalk Basic projects). The constants most commonly
used with this method are shown in the table below.
Java HAHTtalk Basic
DMConstants.ACTION_CLEAR DMConstants_ACTION_CLEAR
DMConstants.ACTION_MOVE_FIRST DMConstants_ACTION_MOVE_FIRST
DMConstants.ACTION_MOVE_LAST DMConstants_ACTION_MOVE_LAST
DMConstants.ACTION_MOVE_NEXT DMConstants_ACTION_MOVE_NEXT
DMConstants.ACTION_MOVE_PREVIOUS DMConstants_ACTION_MOVE_PREVIOUS
195

Chapter 8: Data-Agent Programming
For a complete list of the constants you can use with the setInitialAction
method, see “Performing data-agent actions” on page 193.
Since a data agent’s initial action can be set using the IDE, you will generally
only use this method if you want to change the initial action based on some
user preference. For example, some users might want to browse a set of records
beginning with the first record, while others might want browse the records
starting with the last record.
Java
if (...) {
da1.setInitialAction
(com.haht.project.datamanager.DMConstants.ACTION_MOVE_FIRST);
}
else {
da1.setInitialAction
(com.haht.project.datamanager.DMConstants.ACTION_MOVE_LAST);
}
HAHTtalk Basic
If (...) Then
da1.setInitialAction DMConstants_ACTION_MOVE_FIRST
Else
da1.setInitialAction DMConstants_ACTION_MOVE_LAST
End If
Getting and setting the values of a data agent’s fields
The DataAgent class includes a number of methods that enable you to set and
retrieve the values of fields in a data agent’s recordset. These methods can be
useful in command handlers where you need to set or test the value of a field
before a data-agent action is performed. For instance, a code example
presented later in this chapter — see “Altering a form-field value before
binding” on page 218 — illustrates how you might set a field value in a
command handler to ensure that a field containing an empty string is given a
reasonable default value before its record is inserted in a database.
The table below lists the get and set routines that are available.
196

Method Explanation
Chapter 8: Data-Agent Programming
getFieldString retrieves the value of a field in the current
record as a String. The single argument to this
method can be a String containing a field
name or an integer representing the position of
the field within the record.
getFieldStringByNameOr
Ordinal
retrieves the value of a field in the current
record as a String. The single argument to this
method must be a String containing a field
name or a positional number.
getFieldVariant retrieves the value of a field in the current
record as a Variant. The single argument to
this method can be a String containing a field
name or an integer representing the position of
the field within the record.
getFieldVariantByNameOr
Ordinal
retrieves the value of a field in the current
record as a Variant. The single argument to
this method must be a String containing a
field name or a positional number.
isFieldNull determines whether the value of a field in the
current record is null. The single argument to
this method can be a String containing a field
name or an integer representing the position of
the field within the record. The method’s return
value is a boolean.
setFieldString sets the value of a field in the current record
using a String. The first argument to this
method can be a String containing a field
name or an integer representing the position of
the field within the record. The second is the
String to which the field should be set.
setFieldToNull sets the value of a field in the current record to
null. The single argument to this method can
be a String containing a field name or an
integer representing the position of the field
within the record.
197

Chapter 8: Data-Agent Programming
Method Explanation
setFieldVariant Sets the value of a field in the current record
using a Variant. The first argument to this
method can be a String containing a field
name or an integer representing the position of
the field within the record. The second is the
Variant to which the field should be set.
198
Note - It’s a good idea to call the data-agent method
isFieldDataAvailable before reading or writing a field —
especially in a HAHTtalk Basic project, where the try/catch
mechanism is not available. A get or set operation could fail if
you’re working with an empty recordset, have reached EOF,
etc.
Getting a reference to a data agent’s connection
Using the DataAgent class’s getConnection method, you can get a reference to
the Connection object being used by the data agent. Using this Connection
object, you can perform all of the actions associated with that object, such as
opening or closing the connection, executing a command, or managing a
transaction. You can also examine the properties of the connection to
determine such things as:
the timeout value for establishing the connection
the timeout value for executing a command
whether the connection is currently open or closed
The prototype for the getConnection method is shown below:
com.haht.ado.Abstract.Connection getConnection()
Dealing with recordsets
The interface to DataAgent objects enables you to perform several types of
actions related to recordsets. For example, you can:
limit the maximum number of records retrieved by a data agent’s
command
make a recordset read only
get a reference to the ADO Recordset object associated with the data
agent

load a session recordset at session start
Limiting the maximum number of records
Chapter 8: Data-Agent Programming
To limit the maximum number of records returned by a data-agent command,
you use the method setMaxRecords:
void setMaxRecords(int aMax)
For example, the code below limits the size of the data agent’s recordset to 100
records.
Java
if (!da1.getInitialActionHasCompleted()) {
da1.setMaxRecords(100);
}
HAHTtalk Basic
If (da1.getInitialActionHasCompleted() = False) Then
da1.setMaxRecords 100
End If
Note - The call to getInitialActionHasCompleted is necessary
to ensure that the limit on the number of records is set only
the first time the page is run (before the data agent’s initial
action has completed). If you attempt to set the limit each time
the page is run, you’ll get an error the second time the page is
run saying that this property can’t be set while a recordset is
open.
Making a recordset read only
You can make a recordset read only by calling a data agent’s setReadOnly
method. If you call this method, users will not be able to perform operations
that change the data in a recordset, such as Insert. In addition, making a
recordset read only makes certain ADO optimizations possible.
The prototype for the setReadOnly method is shown below:
void setReadOnly(boolean readOnly)
199

Chapter 8: Data-Agent Programming
Getting a reference to a data agent’s recordset
In addition to setting a maximum number of records and making a recordset
read only, you can also get a reference to a data agent’s recordset using the
method getRecordset:
com.haht.ado.Abstract.Recordset getRecordset()
Once you have this reference, you can use all of the recordset methods and
properties defined by ADO. For example, you’ll have access to methods that
enable you to:
200
cancel an update
move to any record in the recordset
refresh the data in the recordset without requirying the data source
check for EOF and BOF
Loading a session recordset at the start of a session
If your application
uses a session recordset and
you need to access data in that recordset before the user visits a page
containing a data agent whose Data Source is that session recordset,
you can load data into the session recordset at the time a user session begins.
To do this, you add code to an on-start method or function. This method must:
get a reference to the session recordset (a data agent)
set some data-agent properties, such as the data agent’s connection and
its command.
call the data agent’s run method
In a Java project, you must add the code that performs these tasks to the
HahtSession class’s onStart method. (This class is defined in the file
HahtSession.java, which is in your Session folder.) The code below provides
an example of how you might implement the onStart method.

Java
Chapter 8: Data-Agent Programming
public void onStart(com.haht.project.SessionEvent anEvent)
{
com.haht.project.datamanager.DataAgent sessionDA =
((HahtSession)Haht.getSession()).getEmployees();
sessionDA.setConnectionByName(“EmployeeConn”);
sessionDA.setCommand("SELECT * FROM Employees");
sessionDA.setCommandType
(com.haht.ado.CommandTypeEnum.adCmdText);
sessionDA.setIsStandardSQL(true);
sessionDA.setInitialAction
(com.haht.project.datamanager.DMConstants.
ACTION_MOVE_FIRST);
sessionDA.run();
}
In your own code, you’ll need to replace the call to getEmployees with a call
to getSessionRecordset where SessionRecordset is the name of your session
recordset.
In a HAHTtalk Basic project, you must add a code page to your project, and in
this file define a public function called HahtSessionOnStart. See the example
below.
201

Chapter 8: Data-Agent Programming
HAHTtalk Basic
#include "Session\GeneratedSession.hbh"
#include
#include
Public function HahtSessionOnStart As Boolean
Dim sessionDA As Object
Getting parameters to stored procedures
The DataAgent class contains several methods that are useful for getting the
value of an output parameter (or an input/output parameter) of a stored
procedure or the return value of a stored procedure. These methods are shown
in the table below.
202
Set sessionDA = Employees
sessionDA.setConnectionByName "EmployeeConn"
sessionDA.setCommand "SELECT * FROM EMPLOYEES"
sessionDA.setCommandType ADO_CommandTypeEnum_adCmdText
sessionDA.setIsStandardSQL True
sessionDA.setInitialAction DMConstants_ACTION_MOVE_FIRST
sessionDA.run
HahtSessionOnStart = True
End function
Method Explanation
getParameterString(int) retrieves the value of a parameter or the
return value of a stored procedure as a
String. The argument to this method is an
index into a set of parameters.
getParameterString(String) retrieves the value of a parameter or the
return value of a stored procedure as a
String. The argument to this method is a
String containing the name of a
parameter.
getParameterVariant(int) retrieves the value of a parameter or the
return value of a stored procedure as a
Variant. The argument to this method is
an index into a set of parameters.

Method Explanation
Chapter 8: Data-Agent Programming
getParameterVariant(String) retrieves the value of a parameter or the
return value of a stored procedure as a
Variant. The argument to this method is a
String containing the name of a
parameter.
One restriction you should be aware of here is that a stored procedure’s output
parameters may not be available to your application immediately after the
stored procedure is executed. For example, consider the following SQL Server
stored procedure:
CREATE PROCEDURE total_gallons @colorval varchar(20)='%', @sumgal
integer OUTPUT
AS
SELECT cust_id, paint_supplier.name AS brand, color, gallons
FROM paint_order, paint_supplier
WHERE color LIKE @colorval and
paint_supplier.supplier_id=paint_order.supplier_id
SELECT @sumgal=SUM(gallons)
FROM paint_order
WHERE color LIKE @colorval
The first SELECT statement in this stored procedure returns a recordset. Only
after your application has traversed this recordset (or at least until you’ve done
a Move Last), you cannot get the value of sumgal. Once you’ve accessed the
last record in the recordset, the output parameter becomes available.
Refreshing a data agent’s data
The Advanced tab in the IDE’s Data Agent Properties dialog enables you to
check a check box to specify that a data agent’ command should be reexecuted
each time its page is run. Reexecuting this command, of course, refreshes the
data in the data agent’s recordset.
You can also request that the data agent execute its command each time its
page is run using the data agent’s setRefreshOnPageRun method.
Java
da1.setRefreshOnPageRun(true);
203

Chapter 8: Data-Agent Programming
HAHTtalk Basic
da1.setRefreshOnPageRun True
You can place this call in the “Custom constructor code” section of the
Server-side Code view of your page.
204
Note - The DataAgent class also contains a
getRefreshOnPageRun method that retrieves the value of the
data agent’s refresh property.
Sorting records
If you have a page that includes an ADO report, and that report uses grouping,
the records to be displayed in the report must be sorted. This sorting can take
place on the database server, or it can be performed by the HAHTsite
Application Server. You can control where the sorting takes place by calling the
appropriate method of the DataAgent class, either setPreSort (database) or
setPostSort (Application Server).
By default, HAHTsite generates a call to setPostSort on a page that contains
a report with groups, for example:
daEmployees.setPostSort("lastName", "firstName");
This statement indicates that the sorting should be done on the Application
Server. This type of sorting is the default because of a restriction on sorting
records on the database server: If a SELECT statement refers to two or more
columns that are in different tables but have the same name, a “pre” sort will
not work correctly. In addition, you must always use a “post” sort if your data
source is not a relational database.
Having said that, if you are getting data from a relational database and won’t
run into the naming-conflict problem mentioned above, you should let your
database server do the sorting to increase the efficiency of your application. To
make this change, add code that calls the data agent’s setPreSort method in
your page’s constructor or dataAgent_OnPreRun method. See the code below
for an example:
Java
if (!da1.getInitialActionHasCompleted()) {
daEmployees.setPreSort(daEmployees.getPostSort());
daEmployees.setPostSort("");
}

HAHTtalk Basic
Chapter 8: Data-Agent Programming
If (da1.getInitialActionHasCompleted() = False) Then
da1.setPreSort da1.getPostSort()
da1.setPostSort ""
End If
If the report page has not been run previously, this code calls the data agent’s
setPreSort routine to indicate that the sorting should be done by the
database server. The argument passed to this method is the argument that
HAHTsite generated for its call to setPostSort — in this case, "lastName",
"firstName". Finally, the code calls setPostSort with an argument of the
empty string so that records will not be sorted by the Application Server.
Filtering records
The IDE provides a nice graphical user interface you can use to specify the
conditions a data agent should use to filter the records it retrieves as a result of
a command. For example, you might want a data agent to retrieve information
about sales orders placed after January 1, 1999. This type of filtering is easy —
and can be done on either the database server or the Applicatin Server — but
has one limitation: the same filters are used each time a particular data agent
obtains a recordset.
Suppose you have a project that enables users to view the orders placed by a
particular customer during a specific period of time. The first page of the
application presents a form that asks the user to specify a customer, a starting
date, and an ending date.
205

Chapter 8: Data-Agent Programming
Only after this form is submitted will you have the information you need to
construct the necessary filter. Therefore, you must set up the filter
programatically on the target page (the page that will contain your data agent
and present the results of your query). Sample code for both a Java project and
a HAHTtalk Basic project is shown below.
206

Java
Chapter 8: Data-Agent Programming
//
// Conditional pre-filtering - use start, end date of previous
// form IF the user filled either of them out.
//
if (aRequest.getURLFieldExists("txtStartDate") &&
!aRequest.getURLField("txtStartDate").equals(""))
{
daUserSQL.setPreFilter (DMConstants.USER_FILTER_URLFIELD,
"purchase_date", ">=", "txtStartDate",
com.haht.ado.DataTypeEnum.adDate);
}
if (aRequest.getURLFieldExists("txtEndDate") &&
!aRequest.getURLField("txtEndDate").equals(""))
{
daUserSQL.setPreFilter (DMConstants.USER_FILTER_URLFIELD,
"purchase_date", "=", "txtStartDate", _
ADO_DataTypeEnum_adDate
End If
If (aRequest.getURLFieldExists("txtEndDate") AND _
aRequest.getURLField("txtEndDate") "") Then
dapaint_order.setPreFilter DMConstants_USER_FILTER_URLFIELD, _
"purchase_date", "

Chapter 8: Data-Agent Programming
This code calls the method setPreFilter to indicate that the filtering should
take place on the database server. This method is overloaded and can have the
following signatures:
public void setPreFilter (int aType, String aField, String anOp,
String aCompVal)
public void setPreFilter (int aType, String aField, String anOp,
String aCompVal, Object aMaster)
public void setPreFilter (int aType, String aField, String anOp,
String aCompVal, int aDataType)
public void setPreFilter (int aType, String aField, String anOp,
String aCompVal, Object aMaster, int aDataType)
The table below describes the parameters that the method takes.
Parameter Description
aType A constant that indicates the type of the comparison value
to be used in the filter criterion, which has the form field
operator comparisonValue.
In Java projects, you select a constant defined in
com.haht.project.datamanager.DMConstants. The
constants you can choose from are:
208
USER_FILTER_CONSTANT - The comparison value is a
constant.
USER_FILTER_VARIABLE - The comparison value is the
current value of a variable.
USER_FILTER_URLFIELD - The comparison value is the
value of a URL field.
USER_FILTER_RS_FLD - The comparison value is the value
of a field in a master recordset.
In HAHTtalk Basic projects, the corresponding values are
defined in the include file SOMConstants.hbh. These
constants have the same names as their Java counterparts
except that you must prepend DMConstants_ to each name.
For instance, the HAHTtalk Basic equivalent of
USER_FILTER_CONSTANT is
DMConstants_USER_FILTER_CONSTANTS.
aField The name of a column in your data agent’s recordset.

Parameter Description
anOp An operator. The possible operators are:
=
<
>
=
LIKE
IS NULL
Chapter 8: Data-Agent Programming
IS NOT NULL
If you use one of the last two options for this parameter,
there is no need to supply the aCompVal parameter.
aCompVal The value with which you want to compare the value of a
field in your data agent’s recordset. This value can be a
constant, the value of variable, the value of a URL field, or
the value of a field in a master recordset. In the last case,
aCompValue should be the name of a field in a master
recordset.
aMaster The data agent containing the master recordset. You supply
this value only if your aType parameter is
USER_FILTER_RS_FLD.
aDataType An ADO constant that specifies the data type of the
comparison value. HAHTsite uses this argument to determine
how to escape the comparison value. If you don’t supply this
argument, HAHTsite treats all comparison values as database
strings; that is, it encloses them in single quotes. If the
comparison value is of a data type that should not be single
quoted, you must supply this argument.
The DataAgent class also contains methods for setting up filtering to be done
on the Application Server. These methods are named setPostFilter and have
the signatures shown below:
public void setPostFilter (int aType, String aField, String anOp,
String aCompVal)
public void setPostFilter (int aType, String aField, String anOp,
String aCompVal, Object aMaster)
209

Chapter 8: Data-Agent Programming
The parameters to these methods are the same as those used with the
setPreFilter methods.
Handling errors
When a data agent attempts to perform an action and an error occurs,
HAHTsite creates an ADO Error object. If several errors occur, several Error
objects are created in a collection.
The DataAgent class provides two methods that you can use to deal with such
errors: getErrorCount and getError:
int getErrorCount()
com.haht.ado.Abstract.Error getError(int index)
The method getErrorCount indicates the number of errors that occurred as a
result of the data agent’s last call to performAction or performInitialAction,
and the getError method returns a reference to one of the Error objects in
the collection. Once you have a reference to an Error object, you can use the
Error class’s getDescription method to get a description of the error.
Typically, you’ll call these error methods from a command handler’s prefailure
event handler and then display your error information on a failure page. For a
complete discussion of how to write this event handler and a complementary
failure page, see “Customizing a failure page” on page 223.
Enabling tracing
In the IDE — on the Advanced tab of the Data Agent Properties dialog — you
can turn on a data-agent feature called tracing. If you turn tracing on, HAHTsite
writes to a log file information about the activity of the data agent. Part of a
sample log file is shown below.
210

Chapter 8: Data-Agent Programming
----------------------------------------------------------------
Starting trace at Mon Jan 04 12:09:14 CST 1999
DataAgent(da1).setInitialAction( movefirst)
DataAgent(da1).setCommandType: new type=2
DataAgent(da1).setConnectionByName: id=EmployeeConn
DataAgent(da1).performInitialAction: action=movefirst
DataAgent(da1).openPendingConnections(ID): connection is non-null
DataAgent(da1).performInitialAction: opening recordset if nonnull
command.
DataAgent(da1).openRS, opening RS, command=Employees
DataAgent(da1).openRS: Allocating new recordset
DataAgent(da1).openRS: setting Max Records to 2
DataAgent(da1).openRS, after open, EOF=false, BOF=false
DataAgent(da1).run: FieldDataAvailable =true
DataAgent(da1).getFieldString(Last Name)
DataAgent(da1).getFieldString: value='Doe'
DataAgent(da1).getFieldString(First Name)
DataAgent(da1).getFieldString: value='John'
DataAgent(da1).getFieldString(Street Addr)
DataAgent(da1).getFieldString: value='4200 Six Forks Rd'
DataAgent(da1).getFieldString(City)
DataAgent(da1).getFieldString: value='Raleigh'
DataAgent(da1).getFieldString(State)
DataAgent(da1).getFieldString: value='NC'
DataAgent(da1).getFieldString(Zip)
DataAgent(da1).getFieldString: value='27609'
This is an all-or-nothing proposition. Once you turn tracing on, it remains on
for the duration of a session.
To limit the scope of the tracing, you can use the DataAgent class’s setTracing
method:
void setTracing(boolean tracingStatus)
For example, you might want to have tracing turned on only when a particular
command handler is running. To achieve this result, simply turn tracing on at
the beginning of the command handler and off at the end of the command
handler.
211

Chapter 8: Data-Agent Programming
The structure of a command handler
In database applications, it’s common for a page to include a data agent
followed by a form.
If such a form’s action is Automatic/SELF and the form contains buttons,
HAHTsite generates a form handler for the page. This form handler looks like
this:
212

Java
Chapter 8: Data-Agent Programming
public void mapFormToCmd (com.haht.project.Request aRequest,
com.haht.project.Response aResponse)
{
boolean bCmdHandlerCalled = false;
if (aRequest.getURLFieldExists("btnMoveFirst"))
{
Form1_btnMoveFirst_ch(aRequest, aResponse);
bCmdHandlerCalled = true;
}
else if (aRequest.getURLFieldExists("btnMoveNext"))
{
Form1_btnMoveNext_ch(aRequest, aResponse);
bCmdHandlerCalled = true;
}
...
if (! bCmdHandlerCalled)
{
getErrors().add
("Received form command did not invoke a command-handler",
"form-handler");
run (aRequest, aResponse);
}
}
213

Chapter 8: Data-Agent Programming
HAHTtalk Basic
Public Sub HS_EmployeeInfo_fH
Dim bCmdHandlerCalled As Boolean
Dim thePage As Object, theErrors As Object
Dim aResponse As Object
Set aResponse = Haht.getResponse()
On Error Goto HAHTErrorHandler_fH
bCmdHandlerCalled = False
If (Haht.getRequest().getURLFieldExists("btnMoveFirst")) Then
Form1_btnMoveFirst_ch
bCmdHandlerCalled = True
ElseIf (Haht.getRequest().getURLFieldExists("btnMoveNext")) _
Then
Form1_btnMoveNext_ch
bCmdHandlerCalled = True
...
End If
If (Not bCmdHandlerCalled) Then
Set thePage = Haht.getPage()
Set theErrors = thePage.getErrors()
theErrors.add _
"Received form command didn't invoke a command-handler", _
"form-handler"
Set thePage = Nothing
Set theErrors = Nothing
HS_EmployeeInfo
End If
End Sub
This form handler simply looks at the incoming URL datastream when the
user submits a form from a browser, determines which button was clicked, and
calls a generated command handler that matches that button. In both Java and
HAHTtalk Basic projects, a command handler has a name of the form
buttonName_ch. It’s important to understand the structure of a command
handler because, as you’ll see in the next section, these handlers are designed
to be customized, and you need to understand where you can add your own
code and how you can customize the flow of control.
The tasks that a command handler performs are as follows:
1 Bind the data submitted with the form to fields in the recordset
represented by the data agent that is the target of the command (button).
214

Chapter 8: Data-Agent Programming
This data binding applies only to Insert and Update commands. (For Find
and Query operations, the criteria to be used for the operation are
established at this point.)
2 Execute the command associated with the button used to submit the
form.
3 If the command succeeds, go to a success page.
4 If the command fails, go to a failure page.
Without going into too much detail, the figure below shows you more
specifically how HAHTsite would structure the command handler for a button
named btnUpdate on a form named Form1.
Note - The method names used in this figure are taken from a
Java project; however, a HAHTtalk Basic command handler is
structured the same way.
Entry point
btnUpdate_bindFields() {
// Bind fields from URL to data-agent fields.
}
btnUpdate_execAction() {
// Execute action.
if (action is successful) {
stepVar=PROCEED_DO_SUCCESS_PAGE
}
else {
stepVar=PROCEED_DO_FAILURE_PAGE
}
}
btnUpdate_ch() {
btnUpdate_bindFields()
btunUpdate_execAction()
if (stepVar= =PROCEED_DO_SUCCESS_PAGE) {
run success page
}
if (stepVar= =PROCEED_DO_FAILURE_PAGE) {
run failure page
}
}
215

Chapter 8: Data-Agent Programming
As you’ll see in the next section, there are four places where you can add code
to change the behavior of such a command handler. It’s also possible to skip
steps in the standard sequence of command-handler actions:
1 Bind data (Insert and Update only)
2 Execute action
3 Run success page
4 Run failure page
The upcoming section, “Modifying a command handler,” explains in detail
how to — and why you would want to — customize your command handlers.
Modifying a command handler
As was mentioned in “The structure of a command handler” on page 212, you
can add code to a command handler in several places. In addition, the code
you add can alter the flow of control in the command handler. This section
contains the following subsections:
216
“Where to add code to a command handler” on page 216
“Examples of adding code to a command handler” on page 217
“Changing the flow of control in a command handler” on page 225
“Example of changing the flow of control” on page 227
Where to add code to a command handler
In each command handler in your application, there are either three or four
places where you can add code. Command handlers for Insert and Update
buttons have four such places, and most other command handlers have three.
Here are the locations:
Just before the command handler binds data from a URL to data-agent
fields (Insert and Update command handlers only). To add code that will
be executed at this point, you add statements to the generated function
buttonName_onBind.
Just before the command handler executes the command associated with
the button used to submit the form. To add code that will be executed at
this point, you add statements to the generated function
buttonName_onExec.

Chapter 8: Data-Agent Programming
Just before the command handler runs its success page. To add code that
will be executed at this point, you add statements to the generated
function buttonName_onSuccess.
Just before the command handler runs its failure page. To add code that
will be executed at this point, you add statements to the generated
function buttonName_onFail.
When you look at the Server-side Code view of your page, you’ll see these
empty functions just above the related command handler.
You customize these functions by typing in the white areas just below the
method or subroutine names. Any code you type in the white areas of the
screen will be retained when the code for your page is regenerated.
This will all probably make more sense when you look at an example or two
of why you might add code to a command handler. You can find such
examples in the next section, “Examples of adding code to a command
handler.”
Examples of adding code to a command handler
This section presents several examples of how you can add functionality to a
generated command handler:
217

Chapter 8: Data-Agent Programming
218
The first example illustrates how to change a form-field value between
the time the value is submitted and the time the command handler binds
that value to a data agent.
The second example is a variation of an example used in Chapter 6,
“Forms-Related Programming”: it explains how to insert a Binary Large
Object (BLOB) in a database using a command handler’s prebind routine.
The third example explains how to use a prefailure routine to customize
a failure page.
Altering a form-field value before binding
When a user clicks an Insert or Update button on a form and a command
handler is called, the command handler normally binds the data submitted to
fields in the button’s target data agent. However, you have a chance to
intercept this data, and to change it in any way you like, before the data is
bound to data-agent fields. You do this by adding code to your command
handler’s prebind routine: buttonName_onBind.
For example, let’s say that you have a project that:
reads personal data submitted by potential subscribers from a temporary
database
allows you to insert subscriber records into a permanent database

Chapter 8: Data-Agent Programming
If the subscriber did not supply a country name, you want to bind the value
“United States” to the data agent’s Country field before the normal binding
occurs. (Normal binding will not affect the Country field because the Country
text box is empty.). To accomplish this, you can add code to the Insert
command handler’s prebind function. See the code samples below.
Java
protected void btnInsert_onBind
(com.haht.project.Request aRequest,
com.haht.project.Response aResponse,
com.haht.project.datamanager.DMHandlerInfo aHandlerInfo)
{
// Insert code to run before binding data to the command btnInsert.
if (aRequest.getURLField("txtCountry").equals(""))
{
da1.setFieldString("Country", "United States");
}
}
HAHTtalk Basic
Private Sub btnInsert_onBind(aHandlerInfo As Object)
' Insert code to run before binding data to the command btnInsert.
If (Haht.getRequest().getURLField("txtCountry") = "") Then
dsSubscriberInfo.setFieldString "Country", "United States"
End If
End Sub
This is a simple example, but it illustrates how to get a value submitted with a
form before the form’s values are bound to a data agent, and how to bind
values to a data agent. For a lengthier example of how to customize a
command handler’s prebind routine, see “Inserting a BLOB into a database”
below.
Inserting a BLOB into a database
This section presents another example of how you might customize a
command handler’s prebind method. Suppose you have a form that contains
a File Upload form field. When a user runs your application, he or she will
enter the path to an image file in the File Upload text field. When the user
clicks the Insert button, you want to take this pathname, open the image file,
and write the contents of the file to a BLOB field in your database. (The record
219

Chapter 8: Data-Agent Programming
containing the image will also contain a picture name that you can use to
identify the image.)
Since HAHTsite doesn’t generate code for inserting a large binary object into a
database, you must add code similar to the following to a command handler
to insert this object in your database.
220

Java
Chapter 8: Data-Agent Programming
protected void btnInsert_onBind(com.haht.project.Request
aRequest, com.haht.project.Response aResponse,
com.haht.project.datamanager.DMHandlerInfo aHandlerInfo)
{
//
// Get filename of uploaded image, open it, and prepare to
// appendChunk it into the recordset field
//
String sPictureFileName = Haht.getApplication().
getUserRoot() + '/' + aRequest.getURLAttachment
("mfuPicture");
java.io.File pictureFile = new java.io.File
(sPictureFileName);
FileInputStream pictureStream;
try
{
pictureStream = new FileInputStream (pictureFile);
}
catch (java.io.FileNotFoundException e)
{
aRequest.setUserProp("ErrorMessage",
"Uploaded file not found!");
aHandlerInfo.setProceedAction
(DMConstants.PROCEED_DO_FAILURE_PAGE);
return;
}
// Recordset has done addNew, so we have a Field to put
// picture in. Get picture field for appending data into
//
Field pictureFld = daNameAndPict.getRecordset().
getField("Picture");
Field nameFld = daNameAndPict.getRecordset().
getField("Name");
nameFld.setString(aRequest.getURLField("txtName"));
221

Chapter 8: Data-Agent Programming
Java
222
//
// Allocate a buffer and read until we're done
//
byte [] pictureBuf = new byte[BUFSIZE];
int nBytesRead;
int nBytesTotal = 0;
do
{
try
{
nBytesRead = pictureStream.read (pictureBuf);
nBytesTotal += nBytesRead;
if (nBytesRead > 0)
pictureFld.appendChunk (pictureBuf, nBytesRead);
}
catch (java.io.IOException e)
{
aRequest.setUserProp("ErrorMessage",
"Error occurred while reading/writing image");
daNameAndPict.getRecordset().cancelUpdate();
aHandlerInfo.setProceedAction
(DMConstants.PROCEED_DO_FAILURE_PAGE);
try
{
pictureStream.close();
}
catch (java.io.IOException e2)
{
}
return;
}
}
while (nBytesRead > 0);

Java
}
//
// Close file, continue
//
try
{
pictureStream.close();
}
catch (java.io.IOException e)
{
}
Chapter 8: Data-Agent Programming
Note - Appendix C, “Code Examples,” presents code you could
use in a HAHTtalk Basic project to perform this same task. See
the section “Modifying a command handler” on page 370.
If you’ve read Chapter 6, “Forms-Related Programming,”, you’ll recognize this
example as a variation of an earlier example that illustrated how to write a
BLOB to a database by calling a subroutine as the action of a form. Note that
several steps taken in the earlier example are not necessary in this one,
including:
opening a connection
opening a recordset
adding a new record to the recordset
Because this section’s example code is being called from an Insert button’s
command handler, these actions have already been performed at the time the
code is called.
Customizing a failure page
Suppose you implemented the example in “Inserting a BLOB into a database”
on page 219, which uses a custom Insert command handler to insert a BLOB
in a database, and the insertion failed. You could use the IDE to customize the
Insert button so that an error page would be run if the insertion failed, but
how would you write some custom content to that error page? This section
tells you how.
The simple answer is that you can add code to the Insert button’s prefailure
routine to make customizing the failure page possible. See the sample code
below.
223

Chapter 8: Data-Agent Programming
Java
protected void btnInsert_onFail
(com.haht.project.Request aRequest,
com.haht.project.Response aResponse,
com.haht.project.datamanager.DMHandlerInfo aHandlerInfo)
{
// Insert code to run after the btnInsert command fails.
aRequest.setUserProp("ErrorMessage","Insertion of picture "
+ aRequest.getURLField("txtName") + " failed.");
}
224
Note - In a HAHTtalk Basic project, you could use a global
variable to hold the error message.
This code uses the setUserProp method of the Request object passed to the
method to set a user property associated with the Request object. The two
arguments to this method are the name of a user property (which is user
defined) and the value of that property. Since this Request object is passed to
the failure page’s run method, that run method can use the Request object’s
getUserProp method to get this message in order to display it.
The Normal view of a sample failure page is shown below.
Java
// Check to see if the message was passed in
// Request.UserProp("Message") or ("ErrorMessage")
if (aRequest.getUserProp("ErrorMessage") != null)
setErrorMessage ((String) aRequest.getUserProp
("ErrorMessage"));
else if (aRequest.getUserProp("Message") != null)
setMessage ((String) aRequest.getUserProp("Message"));
// Display success or error message here, using property set by
// caller.
out.print ("");
if (mMsgIsError)
out.print("sMsg");
else
out.print("sMsg");
out.print("");
sMsg = "";
mMsgIsError = false;

Chapter 8: Data-Agent Programming
This page checks the Request object passed to it for an error message
(“ErrorMessage”) or a success message (“Message”). If the user property
“ErrorMessage” has been set, the page gets the value of that property and uses
the user-defined method setErrorMessage to set the value of the user-defined
variable sMsg. This method and member variable are defined in the Server-side
Code view of the failure page.
Java
// private methods
/**
* Set displayed message text, and mark for display as non-error
**/
public void setMessage(String aMsg)
{
sMsg = aMsg;
mMsgIsError = false;
}
/**
* Set displayed message text, and mark for display as error
**/
public void setErrorMessage (String aMsg)
{
sMsg = aMsg;
mMsgIsError = true;
}
...
// private member variables
private String sMsg = "";
private boolean mMsgIsError = false;
This example requires you to write a little code in three different places, but
should be a very useful example if you’re customizing your application’s
command handlers.
Changing the flow of control in a command handler
In addition to adding code to a command handler, you can change the flow
of control in the command handler. The normal flow of control is shown
below.
225

Chapter 8: Data-Agent Programming
You can easily change this flow, however, by setting a constant in a command
handler’s prebind, preexecute, presuccess, or prefailure routine. Here’s how the
mechanism works.
When a command handler calls one of the methods or subroutines shown
below, it passes to that subroutine or method an object of type DMHandlerInfo:
226
ButtonName_onBind
ButtonName_onExec
ButtonName_onSuccess
ButtonName_onFail
One of this object’s member variables, mProceed, stores a constant that
indicates what action the command handler should take after the user-defined
routine exits. This constant is preset to PROCEED_DO_NEXT_STEP when the
user-defined routine is called. The constants you can use in setting this action
are listed in the table below.
Constant Explanation
PROCEED_DO_NEXT_STEP Continue with the next step. For example, if the
handler-information object’s mProceed variable
is set to PROCEED_DO_NEXT_STEP in a prebind
routine, the next step to be performed will be
the binding step.

Constant Explanation
Chapter 8: Data-Agent Programming
PROCEED_SKIP_NEXT_STEP Skip the next step. For example, if the
handler-information object’s mProceed variable
is set to PROCEED_SKIP_NEXT_STEP in a
prebind routine, the next step to be performed
will be the execute-action step.
PROCEED_DO_SUCCESS_PAGE Go directly to the success routine.
PROCEED_DO_FAILURE_PAGE Go directly to the failure routine.
Note - In HAHTtalk Basic project, you should prepend
DMConstants_ to the names of these constants.
The upcoming section “Example of changing the flow of control,” illustrates
how to set the mProceed variable to one of these constants.
Example of changing the flow of control
Here’s a simple example of how to change the flow of control in a command
handler. Say that you have a prebind routine, like the one discussed in
“Customizing a failure page” on page 223, that records error information in a
user property of a Request object if an error occurs. For instance, the prebind
routine in that example can fail if the routine is unable to find the file it is
supposed to read. At this point, you should not only record your error
information, but tell the command handler to go directly to its failure routine.
The code below illustrates how to do this.
Java
try
{
pictureStream = new FileInputStream (pictureFile);
}
catch (java.io.FileNotFoundException e)
{
aRequest.setUserProp("ErrorMessage","File not found!");
aHandlerInfo.setProceedAction
(DMConstants.PROCEED_DO_FAILURE_PAGE);
return;
}
227

Chapter 8: Data-Agent Programming
Note that the variable mProceed is set using the DMHandlerInfo object’s
setProceedAction method.
228

Programming with
the Connection
Manager
9
The DMConnectionManager class ...............................................................230
Opening a connection..................................................................................230
Opening a shared connection.................................................................231
Opening a private connection ................................................................232
Closing a connection....................................................................................232
Connections in HAHTtalk Basic projects.....................................................233
229

Chapter 9: Programming with the Connection Manager
The DMConnectionManager class
The HAHTsite Server Object Model includes a connection-manager class
named DMConnectionManager. This class includes methods that enable you to
open or obtain a reference to a shared connection and to open a private
connection. Once you obtain a Connection, you can use it in your ADO
programming as you normally would. For example, you might instantiate a
Recordset and then set the recordset’s active connection using your
Connection object.
A shared connection can be opened by a session the first time the connection
is needed and then be used for the duration of the session by both your code
and any number of data agents. Sharing a connection improves an
application’s performance because you avoid the overhead of opening
multiple connections. Some applications may require or prefer to use private
connections, however. For example, an application that performs transactions
might choose to conduct those transactions over a private connection.
You might be thinking, “ADO allows me to create connections of different
scopes, so why would I use the connection manager?” There are two main
reasons:
230
The management of connection strings is simplified. If you need to
change a connection string, you can make the change in one place — the
definition of the connection — and all of the code pages that might open
the connection will know about the new connection string.
You can share a connection with one or more data agents. A data agent
uses the DMConnectionManager class to open a shared connection to a
data source, and you can use a method of this class to get a reference to
the same connection.
The remainder of this chapter discusses the procedures for opening and
closing shared and private connections using the DMConnectionManager class.
Opening a connection
The general procedure for opening a connection or getting a reference to a
shared connection is as follows:
1 Create an ADO connection using the HAHTsite IDE. The procedure for
creating this connection is covered in Chapter 15, “Connecting to a Data
Source,” in the HAHTsite IDE and IP User’s Guide.

Chapter 9: Programming with the Connection Manager
2 If the user will be getting a reference to a shared connection and the
connection’s data source requires that the user log in, set up a login page
that user must visit before getting the shared connection. The name of
this login page is an attribute of the connection.
3 Call the appropriate SOM method to open or get a reference to the
connection.
The subsections below explain in detail how to call the proper method to
establish a shared or private connection.
Opening a shared connection
Generally, you get a reference to a shared connection using the method
getSharedConnectionByName:
com.haht.ado.Abstract.Connection getSharedConnectionByName
(String connName)
The single argument to this method is the name of an ADO connection
created in the IDE.
Note - You can also get a reference to a shared connection
using the method getSharedConnectionByID. Using this
method, however, makes your code a little harder to read since
it requires the project ID of a connection as its argument. This
method is primarily for use by data agents.
Before you call the getSharedConnectionByName method, you should
determine whether the connection’s data source requires that users log in. If
users must log in, your application must include a data agent that establishes
the shared connection before your code attempts to get a reference to that
connection. Also, the definition of the connection itself must include the
name of a login page that will enable users to log in to the data source.
The call to getSharedConnectionByName will return null if:
the connection required a login and the user has not logged in yet
a connection of the name you supplied does not exist
Java programmers: The getSharedConnectionByName method can throw two
exceptions: SharedConnectionUnpreparedException and
UnknownConnectionException. This means that you should make this call
using the try/catch mechanism. The first exception indicates that the
connection’s data source requires a login and that the user has not logged in,
and the second exception indicates that the application does not know of a
connection with the name you specified.
231

Chapter 9: Programming with the Connection Manager
Opening a private connection
Generally, you open a private connection using the method
openPrivateConnectionByName:
232
com.haht.ado.Abstract.Connection openPrivateConnectionByName
(String connName, String userID, String password)
The three arguments to this method are:
the name of an ADO connection created in the IDE
a user ID to be used in logging in to the data source
a password to be used in logging in to the data source
Use empty strings for the second and third arguments if the connection’s data
source does not require that users log in.
Note - You can also open a private connection using the
method openPrivateConnectionByID. Using this method,
however, makes your code a little harder to read since it
requires the project ID of a connection as its argument. This
method is primarily for use by data agents.
The call to openPrivateConnectionByName will return null if:
the method is unable to log in to the connection’s data source
a connection of the name you supplied does not exist
Java programmers: The openPrivateConnectionByName method can throw
two exceptions: PrivateConnectionUnpreparedException and
UnknownConnectionException. This means that you should make this call
using the try/catch mechanism. The first exception indicates that the
connection’s data source requires a login and that the method was unable to
log the user in, and the second exception indicates that the application does
not know of a connection with the name you specified.
Closing a connection
Because you might want to open and close a private connection repeatedly
during a session — for example, you might want to open and close the
connection each time you access a data source — HAHTsite provides a method
that enables you to close a private connection explicitly:
void closePrivateConnection(com.haht.ado.Abstract.Connection)

Chapter 9: Programming with the Connection Manager
If you don’t call this method, HAHTsite closes all private connections when a
session ends.
Similarly, HAHTsite closes all shared connections automatically when a
session ends.
Connections in HAHTtalk Basic projects
Because most HAHTtalk Basic programmers would prefer to work with
connection objects of type ADODB.Connection rather than objects of type
com.haht.ado.Connection, HAHTsite includes four Basic functions that
return connections:
getSharedConnectionByID
getSharedConnectionByName
openPrivateConnectionByID
openPrivateConnectionByName
These functions serve the same general purpose as their Server Object Model
counterparts, but return connections of type ADODB.Connection.
In addition, the class ADODB.Connection defines a closePrivateConnection
method that you can use to close private connections.
233

Chapter 9: Programming with the Connection Manager
234

Working with
Client-side Scripts
10
Introduction to client-side scripts................................................................236
Types of client-side scripts............................................................................238
Choosing a scripting language.....................................................................238
Client-side scripts and the HTML editor .....................................................240
Writing in-line scripts...................................................................................243
Writing script functions ...............................................................................244
About event handlers ...................................................................................247
Browser compatibility issues ........................................................................249
About Dynamic HTML .................................................................................252
Scripts with server-side expressions .............................................................257
235

Chapter 10: Working with Client-side Scripts
Introduction to client-side scripts
Client-side scripts enable you to include executable content in Web pages,
providing dynamically created HTML content, interaction with the user, and
control of the Web browser. You can use client-side scripts in a variety of ways.
Some of the common uses are:
236
to validate form fields before submitting a form
to animate menus to indicate mouseovers
to display a special picture, depending on the user’s history
to enforce an ordered navigation of a set of Web pages
to interact with and control the execution of applets
As a simple example of what you can do with client-side scripts, try entering
the following text into a page using the Normal view of the HTML editor:
The Fibonacci sequence
document.write("1, 1");
first = 1; second = 1;
for(i=0; i

Chapter 10: Working with Client-side Scripts
The JavaScript code that you place on a Web page is interpreted by the browser,
which dynamically generates the HTML content that is displayed. Using
client-side scripts allows you to run programs on a viewer’s computer within
the Web browser.
The HAHTsite IDE/IP includes a rich script-aware HTML editor for writing,
testing, and debugging client-side scripts in a Web page. The HTML editor
supports both JavaScript and VBScript as scripting languages. In addition, the
Document Object Models (DOM) for the major Web browsers are incorporated
into the editor, allowing drag-and-drop insertion of objects, properties, and
methods from the DOM directly into the scripts. This is a very powerful
feature that simplifies the complex task of writing scripts using objects in the
browser’s DOM. Perhaps the most difficult task associated with writing
client-side scripts is dealing with incompatibilities in the different versions of
Netscape Navigator and Internet Explorer. The HTML editor filters the DOM
presented in the editor, supporting writing scripts for targeted browsers.
This chapter explains how to use the HTML editor to create Web pages with
scripts. The reader is assumed to understand JavaScript or VBScript and the
concepts involved in using the DOM for the target browser. Because of the
predominate use of JavaScript, the examples in this chapter use JavaScript.
However, the use of the HTML editor is the same, regardless of the scripting
language.
237

Chapter 10: Working with Client-side Scripts
Types of client-side scripts
When you’re using its Normal view, the IDE’s HTML editor acts as a WYSIWYG
Web page editor. When used in this mode, the editor has features that enable
you to add client-side scripts to a Web page. In addition, the editor has a Client
Scripts view that you can use to create event handlers and functions for your
scripts.
The HTML editor supports three basic types of scripts in a page:
238
in-line scripts. The HTML editor allows you to type script statements
directly into a Web page, at the place that the browser should execute the
script. These in-line scripts appear in the Normal view of the HTML
editor and are marked with a special font. Writing in-line scripts is
explained in “Writing in-line scripts” on page 243.
page-scope functions. You can write script functions to perform common
functions or to improve readability. Page-scope functions are created in
the Client Scripts view of the HTML editor and are available to in-line
scripts or event handlers anywhere on the page. These functions are not
visible in the Normal view. If you put the bulk of your scripting code into
functions, Web pages with in-line code maintain a more WYSIWYG look
because they have fewer in-line statements. Creating page-scope
functions is discussed in “Writing script functions” on page 244.
event handlers. The Client Scripts view of the HTML editor provides a
convenient way to write event handlers associated with an event for an
object on the page. The scripts for each event are created and edited in
the Client Scripts view, and are not shown on the page in the Normal
view. More information about writing event handlers is provided in
“Scripting event handlers” on page 247.
Choosing a scripting language
The HTML editor supports the use of both JavaScript and VBScript in
client-side scripts. Both languages provide basic control flow and support for
creating Web pages that are customized at display time. However, JavaScript is
recognized by more browsers and is more widely used than VBScript.
The most important difference between JavaScript and VBScript is browser
support. JavaScript is supported by Navigator and IE. VBScript is only
supported by IE. If you use VBScript, only clients that are using IE will be able
to correctly view your pages with scripts. Scripting-language and

Chapter 10: Working with Client-side Scripts
browser-compatibility issues are discussed further in “Browser compatibility
issues” on page 249.
You can choose to use either JavaScript or VBScript as the current scripting
language. If you intend to use only one language for all your scripts, you can
make this choice once using an HTML editor option, and all the scripts that
you write will be generated in that language. If you need to write in both
JavaScript and VBScript, you must change this setting each time you edit a
different type of script.
To select the current scripting language
1 From the main menu, select Tools > Options....
The Options dialog appears.
2 Select the Client Scripts tab.
3 From the Default Client Script LANGUAGE combo box, select either
JavaScript or VBScript. You can also type an entry into this field to specify
a different scripting language or a specific version of a language, such as
JavaScript1.2.
4 Click OK.
The script language you select will be used by the HTML editor for any new
scripts that are created.
239

Chapter 10: Working with Client-side Scripts
Client-side scripts and the HTML editor
When an HTML page is opened in a project, it is first displayed using the
Normal view of the HTML editor. The Normal view displays an editing
window with a WYSIWYG representation of the page. While you’re in this
view, client-side scripts appear as in-line code, or as icons, depending on the
setting of the View Code as Icon option.
When you switch to the Client Scripts view, the DOM Objects tab is selected
in the Project window. The DOM Objects panel contains a graph
representation of the client-side script tags and client-side objects. The objects
and tags are placed in a hierarchy represented by folders. The editing window
contains the currently selected script. The DOM Objects window only displays
the object model when the HTML editor is in the Client Scripts view.
240
Note - There are no real folders corresponding to this
representation. The folders are only used as a convenient
mechanism for presenting the tags and objects in an
easy-to-use way.
The Client-Side Script Tags folder lists both functions and in-line scripts
contained in the page. The first script in the list of Client-Side Script Tags is
used to create page-scope functions. Page-scope functions are discussed in
“Writing script functions” on page 244. Any other functions or in-line scripts
in a page will also appear as script elements in this list.
The script that is currently being edited is signified by a red highlight box
around the script’s icon. In the illustration above, the first script item, which
contains the page scope functions, is being edited. When you switch between
Normal and Client Scripts view, if possible, the HTML editor maintains the
focus on the item currently being edited. For instance, if you are editing (or
place the cursor in) an in-line function while in Normal view, then switch to
the Client Scripts view, the script containing that function will be
automatically selected for editing.

Chapter 10: Working with Client-side Scripts
Tip - If you are not sure which in-line script or function a
particular script in the list of Client-Side Script Tags represents,
select the script for editing and switch back to the Normal view
of the editor. The script you have selected will be the currently
selected object.
Browsing the object model
Client-Side DOM Objects represent objects in the browser object model. The
Client-Side DOM Objects graph has two root level objects, window and
navigator. The window object represents the Web browser window or a frame
within a window. All page-scope variables belong to this object. The document
object, contained in the window object, represents the document associated
with the window. By traversing the hierarchy, you can see the objects, events,
properties, and methods that define the object model.
The following types of items appear in the DOM Objects panel:
icon item
objects - the forms, buttons, text boxes, or even the document
arrays - items of the same type (e.g., scripts, forms, frames, images)
properties - object attributes
functions - object functions
events - event handler scripts can be associated with these events
In addition to icons representing the type of item, you will notice that some
items have a browser indicator on the icon. These additional indicators mark
items that are only defined in Navigator 4.x or IE 4.x, or both. The browser
indicator may appear on icons for objects, properties, functions, and events.
No browser symbol on the item indicates that the feature is supported by all
of the browsers (or at least the third generation browsers.)
icon Browsers supported
Most browsers support these objects, properties, functions, or events.
Navigator 4.x only
241

Chapter 10: Working with Client-side Scripts
icon Browsers supported
242
IE 4.x only
Navigator 4.x and IE 4.x only (not supported in earlier versions of the
browsers)
Note - When you’re browsing the DOM Object panel, the
script currently being edited may not always be visible.
Remember that the icon for the script being edited in the
editing window is indicated by a red highlight box.
Configuring the Client Scripts view
The DOM Objects window of the Client Scripts view of the editor can be
configured to display as much or as little information as you would like to see.
Instead of displaying all of the objects supported by all of the browsers, you
can display just the objects supported by specific browsers.
To configure the DOM Objects panel
1 From the main toolbar, select Tools > Options....
The Options dialog appears.
2 Click on the Client Scripts panel of the Options dialog.
3 Configure the panel to display the information you wish to see.

Field Description
Display Properties and
Methods
Default Client Script
LANGUAGE
Display Objects for
Browsers
4 Click OK.
Chapter 10: Working with Client-side Scripts
Note - Selecting a particular browser’s object model to be
displayed in the Client Scripts view does not prevent you from
writing scripts that are incompatible with the browser. This
selection only affects the object model that is shown. There is
no testing for browser compatibility in the editor.
Writing in-line scripts
You can add scripts in-line on a page while you’re in the Normal view. These
scripts will be visible in the HTML editor, but will not be visible on the page
when viewed by a browser. Script statements and functions are executed in
order as they are read from the page by the browser.
To insert script statements into a page
1 With the page open in the Normal view, place the cursor at the location at
which you want to enter the script.
2 Type in the script statements.
If checked, show the events, properties, and
functions associated with each object. If not checked,
only show the events associated with an object.
Select the scripting language from the drop-down
menu. New event handlers or scripts that you add
will use this value.
Select the browser for which to show the object
model from the drop-down menu. displays all
objects and object features supported by any browser
in this list. Selecting a browser from this list filters
the object model so that only objects and features
supported by that browser appear in the DOM
Objects panel.
Note - The IDE/IP does not check for errors in any scripts.
Errors in scripts will not be seen until the page is displayed in
a browser, so it is a good idea to test your pages thoroughly.
243

Chapter 10: Working with Client-side Scripts
3 Select the script statements.
4 Click the Client-side script button on the Character Styles toolbar.
244
The script appears in a special font and color.
The figure below shows a simple JavaScript example that conditionally
displays information in the Web page based on the month.
When a browser receives this page, it interprets the JavaScript code and, based
on the current month, replaces the JavaScript code with the appropriate HTML
output.
Tip - If you want to hide in-line scripts, select View > Code As
Icon from the main toolbar. The scripts on the page will be
replaced with the client-side script icon .
Once you’ve created an in-line script in the Normal view, you can edit it in the
Client Scripts view of the HTML editor. Editing scripts in the Client Scripts
view gives you access to the object model displayed on the DOM Objects tab
in the Projects window.
Writing script functions
You use the Client Scripts view of the HTML editor to create script functions
with page scope. Functions are subroutines that can be called either by in-line
script statements on the page or from event-handler scripts. The visibility or
scope of a function is determined by its position on a page. A function is
visible to any script statement that occurs after the function definition on the
page. A function has page scope if it is visible to statements anywhere on the
page. The HTML editor defines a General script for each page containing
functions that have page scope.

Chapter 10: Working with Client-side Scripts
A common practice is to place code that is called from multiple places on a
page into a function. Functions may also be used to keep the number of in-line
statements inserted into a page small. This will make the page more readable.
To insert a script function into a page
1 Open the page and select View > Client Scripts from the main toolbar.
Shortcut - Use the buttons on the Change Active View toolbar
to switch between views in the HTML editor.
2 Click on the script icon to select the first script in the Client-Side Script
Tags list.
A script for page scope functions appears in the editing window. If the
page has scripts in the tag, this is the first script that appears in the
tag. A page can have multiple scripts in the tag. Each script
appears as a separate icon under the scripts folder. If the tag does
not contain any scripts, a General script is generated. The first line in the
General script initially contains the comment line:
// General SCRIPT tag in HEAD tag. Put page scope client script
// functions here.
3 Type in script functions and variables definitions that require page scope.
To try this out, create the print_todays_date function shown below:
function print_todays_date()
{
var d = new Date();
document.write(d.toLocaleString);
}
4 Switch back to Normal view and insert a call to the function on the page
where you want the date to appear.
print_todays_date();
5 Select the line containing the function call and click on the Client-side
script button.
245

Chapter 10: Working with Client-side Scripts
246
When you browse the page, the date will appear in place of the function
call.
You can also insert functions in-line in a page. These functions will only be
visible to scripts occurring after the function definition on the page. These
functions will be visible in the Normal view and also in the DOM Objects
window in the Client Scripts view of the HTML editor.
If a function is used by multiple pages, you might prefer to keep the function
in a separate file in the project and include it in each script that uses the
function. A function that pops up a dialog to ask “Are you sure?” might be
used on several different pages. If a script includes this function, it only has to
be changed in one place if you what to change this popup.
Shortcut - While editing the page in Normal view,
drag-and-drop the script file from the Project window onto the
page. This will insert a reference to the script file as a
page-scope function.
HTML tags for client-side scripts
The HTML editor generates the HTML tags that contain the scripts
in the page. If you look at the page in HTML Tags view, you will see individual
script tags for each in-line function and set of statements on your page. When
script statements or functions are inserted in-line using the Normal view, the
tags are generated to include the statements at the location in the
body of the HTML where the code appears. Page scope functions, including
references to script files containing functions, are inserted in the tag.
These scripts are placed in the tag so that the functions are defined

Chapter 10: Working with Client-side Scripts
before any other scripts on the page. Event-handler scripts are inserted in the
tag for the object associated with the event.
Although the HTML editor provides a very flexible way to insert client-side
scripts into a HTML page, there may be occasions where you will need to edit
the HTML tags for the scripts directly. The HTML Tags view of the HTML editor
provides a convenient way to do this.
About event handlers
Most browsers in use today have defined a set of objects that represent the
browser and the page that it displays. These objects are commonly referred to
as the Document Object Model or DOM. (The browser object model is
discussed more fully in “The browser object model” on page 250.) The user
interacts with these browser objects by performing actions such as moving a
cursor over a link, pressing a button in a form, clicking in a frame, or loading
a document in a window. These actions are called events. By creating scripts
that run when one of these events occur, you can enable user interaction with
the page and control some browser behavior.
An event handler is a script that the browser invokes when a particular event,
such as a mouseover, occurs. For instance, you could write a script that
displays a different picture when the mouse is held over a picture. The HTML
editor provides an easy way to generate these scripts by allowing you to browse
a hierarchical representation of all of the available objects and their associated
events, select an event to bind to a script, and create the script for that event.
A powerful feature of the HTML editor is the encapsulation of the object
models for all of the commonly used browsers. By selecting the browser(s) that
you want to support in your scripts, you can view the objects and their
associated methods, properties, and events. You can even use drag-and-drop
to insert the code for accessing the object model into your scripts.
Scripting event handlers
Using the browser’s object model, as presented in the DOM Objects window
of the Client Scripts view, you can identify the event that you want to associate
with an event-handler script. “Browsing the object model” on page 241
explains how the objects are organized in the DOM Objects window. While
creating the script, you can also use the DOM Objects view to locate and insert
the code to access properties and functions of any object that is available on
the page. Complete documentation of the object models is outside the scope
247

Chapter 10: Working with Client-side Scripts
of this document. Up-to-date documentation of the object model is available
online from the Web browser vendors. There are also many reference books
with extensive coverage of the use of the object models.
To write an event handler script
1 In the Client Scripts view of the HTML editor, click on the icon of the
event to be associated with the script.
248
The icon for the event will be highlighted with a red box. The editing
window now contains the script currently associated with this event. If
there is no script currently associated with this event, the editing window
will be empty.
Shortcut - In the Normal view of the HTML editor, select the
object with which the script should be associated. Switch to
the Client Scripts view. The DOM Objects panel now indicates
that the currently selected item is an event associated with this
object. The HTML editor maintains focus on selected objects
and events when switching between views.
2 In the edit window, enter the script code for the event. The browser will
execute this code when the event occurs.
3 To insert the code to reference a property or method from the object
model into the script, drag-and-drop the icon for the property or method
from the DOM Objects panel into the editing panel.
Note - Event handling scripts do not appear in the Normal
view of the HTML editor.

Browser compatibility issues
Chapter 10: Working with Client-side Scripts
Perhaps the most difficult part of developing Web content is dealing with
browser compatibility issues. This is especially true when developing
client-side scripts. Aside from differences in features, you must consider which
browsers and platforms the viewers of the Web page will be using. When
writing client-side scripts you need to be aware of:
the scripting language and version (JavaScript or VBScript)
the browser type and version (Navigator, IE, others)
the OS platform and version (Windows, Mac or UNIX)
JavaScript is the predominate scripting language used today. Different
browsers support different versions of JavaScript. The table below shows the
language level support of the two major browsers.
Script Language Navigator Internet Explorer
VBScript IE
JavaScript 1.0 Navigator 2.x IE 3.x
JavaScript 1.1 Navigator 3.x
JavaScript 1.2 Navigator 4.x 1
1. Not fully compliant
IE 4.x
If you specify JavaScript in the Client Scripts tab of the Options dialog, any
browser that supports JavaScript1.0 or later versions will be able to run your
scripts. The IDE/IP generates JavaScript code that will only be executed by
browsers that understand the script tag and that have script capabilities turned
on.
The different versions of JavaScript reflect changes in the core language, such
as support for arrays, strings, and Java scripting. The objects in the DOM
Objects window of the Client Scripts view are not part of the JavaScript
language and are not determined by the version of JavaScript used, but by the
browser’s object model.
The greatest difference in browser compatibility is in the Document Object
Model or DOM, and support for Dynamic HTML. The DOM continues to
evolve with each version of the browsers. In Navigator 4.x and IE 4.x, there
was a significant divergence in the DOM. As a result, there has been a push for
a common DOM standard that may result in a common base for writing
249

Chapter 10: Working with Client-side Scripts
client-side scripts in the future. Currently, you have to make some strategic
decisions about which browsers and feature sets to support.
The browser object model
Both Navigator and IE have defined object models that provide a
programming interface to control the content and behavior of the displayed
Web pages. These object models are sometimes referred to as the Document
Object Model, or DOM. Two very important objects in the DOM are the
window object and the document object.
The window object is a root-level object that represents the window that the
browser uses to display a Web page. Some of the objects that can be accessed
from the window object are:
250
frames contained in the window
a document (or Web page) loaded into the window
colors used in drawing items in the window
the URL for the document
The document object, which is subordinate to the window object, represents
the HTML page. Some of the objects accessible from the document include:
images and applets displayed on the page
forms and elements in the forms (text boxes, buttons, radio buttons, etc.)
links and anchors in the page
cookies
Objects have properties or attributes that can be queried and sometimes set by
scripts. Many objects also have functions, which are methods that scripts can
invoke to cause the object to take some action. Many objects also have events
triggered by the browser as the user interacts with the page. Events are
particularly useful for enabling user interaction. When an event occurs, such
as the user clicking on a button, the browser invokes the event handler script
associated with that event.
Strategies for handling browser incompatibilities
The HTML editor gives you the ability to filter out objects, properties, and
events in the graph of objects in the Client Scripts view. You can choose to
browse through all of the possible features, or display a subset of the DOM
containing only those objects, properties, and methods supported by a specific
browser version. In addition, if you right-click on an object in the DOM and

Chapter 10: Working with Client-side Scripts
select Properties..., a Document Object Properties dialog lists the browsers that
support that object.
Here are a few strategies for addressing browser compatibility:
least common denominator. If you use only the language features and
DOM supported by Navigator 2.x, your scripts will run on all of the
browsers currently in use. The level of sophistication possible at this level
is fairly low. The only dynamic content supported is forms, form fields,
and links. By moving the bar up to Navigator 3.x, you still retain a
majority of the browsers in use and gain some additional capabilities,
such as dynamic images and the ability to script Java applets.
conditional coding. Write your scripts to determine the browser at
runtime, and run scripts that have been written for that browser version.
You may choose to interleave browser specific code in the page.
Supporting multiple browsers is a lot of work, but it lets you present the
best appearance possible to all viewers.
ignore the problem. Maybe you do not have to write scripts that can be
viewed by everyone. If so, write for the browser version of your choice
and fail gracefully on the rest. Consider yourself very lucky.
Platform specific compatibilities are difficult to anticipate. The basic premise
is that the scripting languages and browser support allow Web content
including scripts to be platform independent. In practice, implementations
are not perfect and there are incompatibilities and as well as bugs that may
cause users to experience difficulty viewing your page. Internet sources such
as user groups and FAQs are your best source for this type of information.
The following example JavaScript code takes advantage of a feature that is only
present in IE 4.x.
var browser = navigator.appName;
var version = parseInt(navigator.appVersion);
var bIsIE4 = (browser.indexOf("MicroSoft") != -1) &&
(version == 4);
// if this is running on IE 4, scroll the form to the top of the
// window
if ( bIsIE4 ) {
document.Form2.scrollIntoView();
}
Although the LANGUAGE attribute of the tag could be used to prevent
browsers from running scripts that include features of later versions of the
language than the browser supports, it is preferable to query the
251

Chapter 10: Working with Client-side Scripts
Window.navigator object to conditionally execute code targeted for specific
browsers.
About Dynamic HTML
Navigator 4.x and IE 4.x introduced greatly enhanced support for Dynamic
HTML (DHTML). In addition to a richer DOM, DHTML has an extended event
model and support for absolute positioning though cascading style sheets
(CSS). Unfortunately, the DOM’s properties used by the fourth generation of
Navigator and IE to position elements are very different. To access the object
properties, you have to use browser sensing. The next generation of browsers
may become more compatible as the standards for a common DOM are
adopted.
In spite of the current difficulties, DHTML offers the option of creating truly
interactive, dynamic Web pages. The HTML editor enables you to develop
DHTML for both Navigator and IE browsers by providing the complete DOM
for both browsers and the ability to drag-and-drop code for object references
as well as an intuitive interface for binding scripts to events. Dynamic
positioning of elements is done through layers in Navigator and CSS
properties in IE. Both of these methods are supported in the HTML editor as
part of the object model for the browser.
Moving objects using DTHML
Here’s a simple example that illustrates how to use DHTML in HAHTsite to
animate objects. Say that you want a picture to change its location in a
window when the user clicks a button. This example shows how client scripts
can detect browser types, and move an object using CSS positioning for IE 4.x
browsers and Netscape Layers for Navigator 4.x browsers.
252

This example involves the following steps:
Chapter 10: Working with Client-side Scripts
1 Insert a picture and a set of buttons to control the movement of the
picture on a page.
2 Create a Netscape Layer. This task is described in “To create a Netscape
Layer from a SPAN” on page 253.
3 Add client scripts to the buttons that move the object, using browser
specific mechanisms for positioning the objects.
Why use Netscape Layers for positioning?
In IE 4.x browsers, CSS positioning can be used to position any object in the
document. Navigator 4.x does not support CSS positioning directly for all
document objects. In Navigator 4.x positioning of objects is enabled by
embedding the objects in Netscape Layers, which can be moved through
positioning. Before an object like a picture can be moved, the picture needs to
be inserted into a tag which can be turned into a layer. Only container
objects like and can be treated as layers.
To create a Netscape Layer from a SPAN
1 In the Normal view of the HTML editor, select the object(s) to be inserted
into a layer. For example, to insert a picture, click on the picture.
2 From the main toolbar, select Insert > Span....
The Insert SPAN dialog appears.
253

Chapter 10: Working with Client-side Scripts
3 Click on the Properties... button to set the Style property.
254
The Style Properties Page Editor appears. For more information about
setting these properties, see Chapter 12, “Cascading Style Sheets,” in the
HAHTsite IDE and IP User’s Guide.
4 Select the Positioning tab of the Style Properties editor.
5 Set the Position to relative. Setting the Position attribute of the Style
Properties to relative or absolute makes the SPAN into a Netscape Layer.
6 Click OK.
7 Type a value for the SPAN tag into the ID field of the Insert Span dialog.
8 Click OK.

Chapter 10: Working with Client-side Scripts
JavaScript example for browser-independent DHTML
As a result of creating a Netscape layer from the SPAN object, there are two
representations of the SPAN object, depending on which browser DOM you
are using:
The IE 4.x DOM represents the SPAN object as
window.document.all.SPAN1.
The Navigator 4.x DOM represents the SPAN object as
window.document.layers.SPAN1.
The DOM Objects window shows the different representations of the SPAN
object.
To reference these objects in client-side scripts, you must use syntax specific to
the object model. The following script is a JavaScript script that is bound to
the onClick event of the button labeled Up in the example. When the user
clicks on the ‘Up’ button, the image will move up 10 pixels.
JavaScript attached to the Up button
if (bIsNS4) {
moveElement(document.SPAN1, 0, -10);
}
else if (bIsIE4) {
moveElement(document.all["SPAN1"], 0, -10);
}
255

Chapter 10: Working with Client-side Scripts
This example script uses two JavaScript code pages, BrowserVersion.js and
MoveObject.js. The first file, BrowserVersion.js, sets the page scope
variables bIsNS4 (browser is Navigator4) and bIsIE4 (browser is IE4), which
are used to determine which DOM will be used. The second file,
MoveObject.js, contains the function moveElement() that moves the object
on the page.
BrowserVersion.js
var sAgent = navigator.userAgent;
var bIs95NT = sAgent.indexOf("Windows 95") > -1 || sAgent.indexOf(
"Windows NT") > -1 || sAgent.indexOf("Win32") > -1;
var bIsIE4 = sAgent.indexOf("IE 4") != -1;
var appVer = navigator.appVersion;
var bIsNS = (navigator.appName == 'Netscape');
var bIsNS4 = bIsNS && (appVer.indexOf('4') != -1);
256

MoveObject.js
Chapter 10: Working with Client-side Scripts
function moveElement( element, x, y, animate ) {
if ( bIsNS4 ) {
if ( element )
element.moveBy( x, y );
else
alert( "MoveObject error: element is not a layer. Make
sure STYLE=\"position:relative\" is set." );
}
}
else if ( bIsIE4 ) {
if ( element.style.position == "" )
element.style.position = "relative";
sLeft = element.style.left.substr( 0, element.style.left.
indexOf( ‘px’ ));
if ( isNaN( parseInt( sLeft )))
sLeft = "0";
element.style.left = parseInt( sLeft ) + x;
sTop = element.style.top.substr( 0, element.style.top.
indexOf( ‘px’ ));
if ( isNaN( parseInt( sTop )))
sTop = "0";
element.style.top = parseInt( sTop ) + y;
}
return;
These functions could be included as project files that are referenced as page
functions or as script functions that are part of the HTML page. See “Writing
script functions” on page 244 for more information on how to include page
scope functions in your page.
Scripts with server-side expressions
You can use information from your application on the server in your
client-side scripts by using embedded server-side expressions. In a HAHTtalk
257

Chapter 10: Working with Client-side Scripts
project, HAHTtalk Basic expressions can be embedded in client-side scripts. In
a similar manner, Java projects allow server-side Java expressions to be
embedded in client-side scripts.
Inserting server-side expressions into a page causes that page to become a
dynamic page. When a page containing scripts with embedded server-side
expressions is requested by a browser, the Application Server executes the
HAHTtalk or Java code and places evaluated expressions into the script before
sending the page to the user’s browser. The server-side expressions are
evaluated by the Application Server each time the page is requested by a
browser.
Embedded server-side expressions are marked using the following a
begin-and-end syntax:
258
/*== marks the beginning of a server-side expression
*/ marks the end of a server-side expression
For example, the following code initializes the JavaScript variables
pagesVisited and userName to values stored in the HAHTtalk Basic variables
PagesVisited and LoginUser:
var pagesVisited = /*== PagesVisited */;
var userName = '/*== LoginUser */';
When the page containing this code is requested, the Application Server
evaluates the HAHTtalk Basic expressions and sends the following script to the
browser:
var pagesVisited = 10;
var userName = 'Zachary';
Note the single quotes around /*== LoginUser */. These quotes are required
because LoginUser is a string variable. When string variables are evaluated,
they need to be in quotes.
The server-side Java expression equivalent to the above HAHTtalk Basic
example would be:
var pagesVisited = /*== com.haht.project.PagesVisited */;
var userName = '/*== com.haht.project.Session.getUserName()*/':

Using HtmlOut
Routines or the
HtmlOut Class
11
Creating HTML at runtime...........................................................................260
The HAHTtalk Basic HtmlOut library ..........................................................260
Using the HAHTtalk Basic HtmlOut library ...........................................261
HAHTtalk Basic example .........................................................................262
The HtmlOut Java class ................................................................................264
Java example ............................................................................................265
259

Chapter 11: Using HtmlOut Routines or the HtmlOut Class
Creating HTML at runtime
You may have situations in your applications where you want to build HTML
tags “on-the-fly” (at runtime). For example, dynamic pages often contain
information that has been retrieved from a database system or from another
software system. Both HAHTtalk Basic and Java provide database access using
ODBC and support ActiveX, OLE automation, DLL calls, and other
mechanisms for communicating with other software systems.
Once you receive information from one of these systems, you must format the
data and display it on a dynamic page. For example, you may want to retrieve
the records from a database and display the data in an HTML table. To
accomplish this, you need to generate HTML table tags at runtime. In most
cases, you’ll use HAHTsite’s wizards and widgets to display the database data.
However, there may be cases where you want to format data in special ways
not supported by a wizard or widget.
You can generate HTML tags with HAHTtalk Basic print statements or with
Java calls to out.print() or out.println(). For example, the following
HAHTtalk Basic print statement displays the value of the “LastName” variable
in the cell of an HTML table:
Print "" & LastName & ""
You certainly wouldn’t want to write print statements each time that you want
to create some dynamic HTML. Fortunately, HAHTsite includes both a library
of HAHTtalk Basic HTML routines and a Java class, both called HtmlOut.
The HAHTtalk Basic HtmlOut library
The routines and their arguments are documented in the HtmlOut.hbs file,
which is installed in HAHTsiteInstallDir\scripts (where
HAHTsiteInstallDir is the directory into which HAHTsite was installed;
C:\HAHTSITE, for example). In addition to this source file, the
HAHTsiteInstallDir\include directory contains the file HtmlOutDecl.hbh,
an include file that contains the declarations for the HtmlOut routines.
The HtmlOut library contains general-purpose routines that generate HTML
tags. For example, you would use the htmlTableDataText routine to print the
value of LastName in a cell of an HTML table:
htmlTableDataText LastName,0,0,0
260

Chapter 11: Using HtmlOut Routines or the HtmlOut Class
The 0,0,0 arguments represent additional HTML parameters (alignment,
column spanning, and row spanning) that aren’t used in this example.
The HtmlOut routines include support for:
line, paragraph, indenting, and ruler tags
character formatting
lists and numbered bullets
links and bookmarks
images
forms and form fields
tables
frames
headers
Using the HAHTtalk Basic HtmlOut library
To use HAHTtalk Basic HtmlOut routines in your project you have the option
of including the library either globally (for all files in your project), or at the
page level.
Including the HAHTtalk Basic HtmlOut library at the page level
1 Create in the project a code page and copy to it the contents of the
HtmlOut.hbs file.
For example:
Create a code page named HtmlOutInclude.hbs.
Copy the contents of the HAHTsiteInstallDir\Scripts\HtmlOut.hbs
file into your project’s HtmlOutInclude.hbs page.
2 Include the HtmlOut declarations file (HtmlOutDecl.hbh) in each page
that uses the HtmlOut routines or in each page of the project.
3 If you are using the HtmlOut routines in only a few pages, you can include
the declarations file in the pages. To do that:
With the page that will use the HtmlOut routines open in the HTML
editor, select View > Server-Side Code to display the page in server-side
code view.
Scroll to the top of the page to find the “Imports and includes”
section.
261

Chapter 11: Using HtmlOut Routines or the HtmlOut Class
4 Type the following #include directive into the “Imports and includes”
area.
#Include
262
You can now call the HtmlOut subroutines from this page.
Including the HAHTtalk Basic HtmlOut library for all pages in your project
1 If you don’t already have a Globals.hbs page in your project, create one.
2 In the Globals.hbs page, place the directive:
#Include
3 Call the HtmlOut subroutines from your project’s Web pages.
HAHTtalk Basic example
This example is provided as a way to demonstrate the features of some
HAHTtalk Basic HtmlOut routines. Typically, you would build a table, like the
one shown in this example, with the Report Wizard.
Below is sample code that uses HtmlOut routines to create dynamically the
rows of a table, based on how many records are in the Data Set “DataSet1.” The
code displays a three-column table showing a record count, an employee’s first
name, and last name.

HAHTtalk Basic
Here is what the table looks like in a browser.
Chapter 11: Using HtmlOut Routines or the HtmlOut Class
Dim NumFound As Integer, I As Integer
Dim MatchingRec As String
' Get the number of records in the Data Set.
NumFound = DataSet1_RecordSet.DynaSet.RecordCount
' Print the number of matching records.
MatchingRec = " matching records."
If NumFound = 1 Then
MatchingRec = " matching record."
End If
Print "Found " & NumFound & MatchingRec
' Start the table. 1=1-pixel border
htmlTableStart 1,0,true,0,true,0,0
' Start a row for the column headers. 0=left aligned row.
htmlTableRowStart 0
' Print the three column headers. 2=centered.
htmlTableHeadingText "Record#",2,0,0
htmlTableHeadingText "First Name",2,0,0
htmlTableHeadingText "Last Name",2,0,0
htmlTableRowEnd
' Go through the Data Set and get records. Create a row for each
' record and print the data for the three columns.
For I = 1 to NumFound
htmlTableRowStart 0
htmlTableDataText format$(i),0,0,0
htmlTableDataText
DataSet1_RecordSet.DynaSet.fields("FirstName").value,0,0,0
htmlTableDataText
DataSet1_RecordSet.DynaSet.fields("LastName").value,0,0,0
DataSet1_RecordSet.DynaSet.MoveNext
htmlTableRowEnd
Next I
' End the table.
htmlTableEnd
263

Chapter 11: Using HtmlOut Routines or the HtmlOut Class
The HtmlOut Java class
The static member variables of the HtmlOut class are used to generate HTML.
In the simplest case, you can use them directly (for example, the Bold and
HorizontalRule members can be used to generate text between two
horizontal rules and surrounded by boldface tags).
HtmlOut.HorizontalRule.renderAsHtml();
HtmlOut.Bold.text("Hello");
264

HtmlOut.HorizontalRule.renderAsHtml();
or, equivalently:
HtmlOut.HorizontalRule.renderAsHtml();
HtmlOut.Bold.start();
// somehow emit the string "Hello"
HtmlOut.Bold.end();
HtmlOut.HorizontalRule.renderAsHtml();
Chapter 11: Using HtmlOut Routines or the HtmlOut Class
HtmlOut class members can also be used as the starting point for more
elaborate formatting control (e.g., the FontUp1 member variable creates the
HTML tag that increases the font size by one step). Red text in this font
size can be also be produced as follows:
PairedTag myFont = HtmlOut.FontUp1.clone();
myFont.setAttribute( "COLOR", "RED" );
myFont.Text("Hello");
HtmlOut also contains static member functions for creating the HTML tag
objects for tables, forms, and other more complex HTML entities. Thus, the
example above could also be coded as follows:
PairedTag myFont = HtmlOut.makeFont( "", "+1", "RED" );
myFont.text("Hello");
Here, the call to makeFont creates a font object using the default font face, a
font size one step larger, and with the color "RED".
Certain arguments of the static member functions are specified as being
optional. An optional String argument may be null or the empty string; an
optional integer argument may be a negative number. These values cause the
attribute in question not to be specified in the HTML, so that the browser will
supply its default behavior as shown in the following sample lines of code:
PairedTag myFont = HtmlOut.makeFont( "", "", "RED" );
myFont.Text( "Hello" );
causes the string “Hello” to be printed in red in the current font, while
PairedTag myFont = HtmlOut.makeFont( "Arial", "1", "RED" );
myFont.Text( "Hello" );
causes the string “Hello” to be printed in red in Arial font.
Java example
The following is a simple example using the Java HtmlOut class to build and
populate a simple HTML table.
265

Chapter 11: Using HtmlOut Routines or the HtmlOut Class
Java
Here is what the table looks like in a browser.
266
PairedTag myTable = HtmlOut.makeTable(true, 6, 216, false, 99,
true, 0, 0,"");
PairedTag myTableHeader =
HtmlOut.makeTableData("CENTER",1,1,"lightblue");
myTable.start();
HtmlOut.TableRow.start();
myTableHeader.text("Delete Item");
myTableHeader.text("Material Number");
myTableHeader.text("Material Description");
myTableHeader.text("Quantity");
myTableHeader.text("Net Value");
myTableHeader.text("Delivery Date");
HtmlOut.TableRow.end();
for(int i=1; i

Chapter 11: Using HtmlOut Routines or the HtmlOut Class
267

Chapter 11: Using HtmlOut Routines or the HtmlOut Class
268

Access Control
12
What is access control? ................................................................................270
Granting privileges: the basics .....................................................................271
Controlling access to a page ...................................................................271
Controlling access to part of a page .......................................................274
Displaying a custom error page ..............................................................275
Granting privileges to logged-in users .........................................................276
Authenticating users with the Login widget ..........................................277
Authenticating users with the Authentication interface........................286
Letting the Web server authenticate users..............................................288
Granting privileges on a user-name basis....................................................289
Using a Login widget and a database privilege repository ....................290
Using a Login widget and a nondatabase privilege repository..............291
Using the Server Object Model ...............................................................293
Server Object Model methods ......................................................................296
269

Chapter 12: Access Control
What is access control?
HAHTsite includes a security feature called access control that enables you to
restrict a user’s access to any pages of your application served by the
Application Server. That is, you can protect all dynamic and secure-static
pages.
270
Note - Secure-static pages are static pages that you’ve chosen
to publish to a HAHTsite Application Server — either for
security reasons or to preserve a state ID.
For additional security, you can place your Application Server behind a
firewall.
The access-control mechanism is based on the concept of privileges.
Associated with each dynamic and secure-static page is a set of zero or more
required privileges, which are strings that you define. In addition, each user
session has associated with it a set of zero or more session privileges. At runtime,
the HAHTsite Application Server determines whether a particular user session
can access a page by comparing the required page privileges with the session
privileges. If all of the page’s required privileges are in the session’s set of
privileges, the Application Server grants the session access to the page.
In the figure below, the Application Server will serve the page because the
page’s required privileges are contained in the user’s session privileges.
This access-control mechanism is very flexible and has many uses, but here is
a simple example of how you could use it. Say that your Web site is a
sports-news service, and that some articles are available for free, but others
require that users subscribe to your service. You can protect the
subscriber-only pages by assigning them the required privilege “Subscribed”
and by initially giving each user session no session privileges. If a user later fills

Chapter 12: Access Control
out a subscription form and submits it, you can assign the user’s session the
session privilege “Subscribed.” The user will then be able to read all of the
articles on your site.
For additional information on implementing this type of security, see
“Granting privileges: the basics” on page 271. This chapter also discusses
increasingly complex uses of access control, including:
how to have users log in to an application
how to assign a set of privileges to users who successfully log in
how to assign a user-specific set of privileges to each user who logs in
The chapter concludes with some reference material concerning which classes
and interfaces in the Server Object Model are useful for implementing access
control.
Granting privileges: the basics
This section explains how to protect a page, or part of a page, from
unauthorized access by:
assigning a required privilege to a page (or checking for a privilege before
displaying a page element)
explicitly assigning (or not assigning) one or more session privileges to a
user session, using the Session object’s addPrivilege or addPrivileges
method
The section also discusses how to display a custom error page when a user
attempts to access a page that the he or she does not have the privileges to
access.
Controlling access to a page
This chapter’s introduction (“What is access control?”) discussed in general
terms how a sports-news Web site could control user access to a set of
subscriber-only articles. This fictitious site allows general access to some
articles, but only subscribers (who have a special session privilege) can access
other pages.
271

Chapter 12: Access Control
How do you initially prevent a user from accessing the subscriber-only
articles? And how can you later grant a user session the privilege it needs to
access these articles? The following sections answer these questions.
To prevent a user from accessing a page
1 Configure the HAHTsite Application Server to enable access control, if
necessary. By default, access control is enabled.
272
For detailed instructions on how to perform this task, see Chapter 3,
“Performing administrative tasks,” in the HAHTsite Application Server
Administration Guide. Basically, all you need to do, however, is to check an
Enable Access Control check box.
2 Add one or more privileges to your HAHTsite project. These become the
privileges that you can assign to pages to limit access to them.
You add these privileges to a project from the Privileges tab of the Project
Properties dialog. For complete instructions on adding privileges to a
project, see Chapter 3, “Managing Projects,” in the HAHTsite IDE and IP
User’s Guide.
The sports-news project has a single project privilege: “Subscribed.”

3 Assign one or more required privileges to each protected page.
Chapter 12: Access Control
You assign a privilege to a page using the Privileges tab of the Page
Properties dialog. For detailed information about assigning a privilege to a
page (or other project element), see Chapter 3, “Managing Projects,” in
the HAHTsite IDE and IP User’s Guide.
In the sports-news project, the subscriber-only pages have been assigned
the required privilege “Subscribed.”
Once you’ve performed these steps, a protected page is inaccessible to a user
who doesn’t have the “Subscribed” session privilege. If such a user clicks a link
to a subscriber-only article at the sports-news Web site, the user’s browser will
display an error page indicating that access to the article has been denied.
For information on how to have your application display a more user-friendly
error page, see “Displaying a custom error page” on page 275.
To assign a session privilege to a session
Have your application call the Session object’s addPrivilege or
addPrivileges method.
Here’s how the sports-news Web site assigns the “Subscribed” privilege to a
session:
1 The application’s initial page prompt’s the user to follow a link if the user
wants to subscribe to the sports-news service. If the user selects this link,
the user is taken to a subscription-form page.
2 The user fills out the form and clicks a Submit button. The action
associated with the form is to call a subroutine — a Java method or a
HAHTtalk Basic subroutine.
273

Chapter 12: Access Control
3 The subroutine checks the data submitted and, if the data is OK, assigns
the “Subscribed” privilege to the user’s session.
274
The code used to assign this privilege is shown below:
Java
Haht.getSession().addPrivilege("Subscribed");
HAHTtalk Basic
HahtSession.addPrivilege "Subscribed"
4 The subroutine also runs the application’s initial page.
The user can now follow a link to any article.
Controlling access to part of a page
From the IDE, you can set the required privileges for a page, or for a higher
level object such as a folder. However, you might also want to limit access to
just one or more elements on a page.
As an example, the figures below show two versions of a page requested by a
user of the sports-news Web site. The first figure illustrates what a user whose
session does not have the “Subscribed” privilege would see:
The figure below shows what a user whose session does have the “Subscribed”
privilege would see:

Chapter 12: Access Control
The conditional elements on a page are controlled by an if statement that
determines whether the user’s session has a required privilege.
Java
if (Haht.getSession().hasPrivilege("Subscribed")) {
// Conditional elements go here
}
HAHTtalk Basic
If (HahtSession.hasPrivilege("Subscribed")) Then
' Conditional elements go here
End If
Displaying a custom error page
You can create a custom error page for the Application Server to display when
a user tries to access a page for which he or she does not have the necessary
session privileges. The figure below shows a simple access-denied page.
275

Chapter 12: Access Control
To create such a page, you:
276
copy a set of error-page templates (supplied with the Application Server)
to a directory of your choosing
edit the template named HS_access.html so that it contains the content
you want to display
set the Application Server’s Error Page Directory (on the Logging Options
page) to the name of the directory that contains the copied templates
stop and restart your server group
Once you’ve performed these steps, the Application Server will display the
new error page the next time an access violation occurs.
This subject is explained in more detail in Appendix A of the HAHTsite
Application Server Administration Guide.
Granting privileges to logged-in users
“Granting privileges: the basics” on page 271 explained how to handle the
situation where you give a user the privilege to access a protected page when
the user visits another page. In particular, that section looked at an application
that gives a user a privilege when the user fills out a subscription form.
The first time the user visits such a site, the user gets a session privilege by
submitting a form, but what about subsequent visits to the site? If the user is
assigned a user name and password during the first visit, the site would likely
require the user to log in to the application to get his or her privilege on a
second or subsequent visit. This section explains how HAHTsite supports
assigning users privileges when they log in to an application.
There are several ways to handle this situation in HAHTsite:

Chapter 12: Access Control
One way is to use the HAHTsite’s Login widget in your application. When
a user loads a page containing this widget, the widget displays a page
containing a login form, which generally contains user-name, password,
and (optionally) Windows NT domain text boxes. When the user fills out
and submits this form, the widget attempts to authenticate the user using
authentication information maintained by the operating system or in a
user-defined location. If the user is authenticated, the widget assigns the
user one or more session privileges and calls a success page. If the user is
not authenticated, the user does not receive any privileges, and the
widget calls a failure page.
The Login widget is implemented using calls to Server Object Model
methods; therefore, it’s possible for you to authenticate users and assign
privileges to them by calling these same methods directly.
If you want a Web server to authenticate users, you can simply configure
your Web server’s authentication mechanism appropriately. If a user logs
in successfully, your application can assign the user privileges using the
Session class’s addPrivilege or addPrivileges method.
Authenticating users with the Login widget
When you use the Login widget in your application, you can authenticate
users against authentication information maintained:
by the operating system
in another (“user-defined”) location, such as an LDAP directory or a
database
The procedures for the two types of applications are very similar. The only
difference is that HAHTsite includes a Java class that performs
operating-system authentication. To authenticate users against information
stored elsewhere, you must write the Java class that performs this
authentication. You’ll find more information on this subject in “To perform
user-defined authentication” on page 285.
To illustrate how to assign a privilege to a user when the user successfully logs
in to an application, this section shows how an application that uses this
strategy was put together. The example is a variation on the sports-news Web
site discussed earlier. In this version of the example, when a subscriber goes to
the site, the user does not have the privileges to read feature articles. The user
must elect to log in to the application against information maintained by the
operating system. If the user logs in successfully, the application grants the
user the privilege “Subscribed,” which enables the user to read protected
pages.
277

Chapter 12: Access Control
The main steps involved in adding the authentication feature to the
application are:
278
adding to your project a login page — which contains a form that
requests login information — and success and failure pages
adding the Login widget to the application
In addition, it may be necessary to change the configuration of the
Application Server.
You will find detailed information about how these steps were performed in
the following sections.
To add the pages required by the Login widget
1 Add to your project a page that will be used by the Login widget to present
a login form to the user.
The easiest way to perform this task is to use the application-login-page
template supplied with HAHTsite. To use this template:
From the File menu, select New > Page....
From the list of templates in the New Page dialog, choose the User
Login Page template, and click the OK button. The page shown below
is opened.
Customize the login page if you want to.
Give the page a name, and save the page.
From the Publish tab of the Page Properties dialog, promote the page
to dynamic or secure static so that the page will be published to the
Application Server.

Chapter 12: Access Control
Of course, you can also create your login form by hand. The form should
include a User Name text box, a Password text box, a Domain text box (if
appropriate), and a Submit button.
Note - The form can also be placed on the page that contains
the Login widget.
The table below shows how you should name the text fields in the form to
minimize the number of attributes you will need to customize in the
Login widget itself.
Text box label Text field name
User Name txtUserName
Password txtUserPassword
Domain txtUserDomain
The action you associate with this form should have the following
attributes:
Type: Project Item
Path: None. (Leave this field blank.)
If you supply these values, submitting the form will cause the application
to load the previous page. In the present case, the application will load the
page containing the Login widget.
One last point. Make sure that the login page is dynamic or secure static so
that it will be published to the Application Server.
2 Create a success page. This page will be loaded if the user successfully logs
in.
Note - The success (or failure) page can also be the same as the
page that contains the Login widget.
Set this page’s properties to make the page dynamic or secure static.
3 Create a failure page. This page will be loaded if the user login is
unsuccessful.
Set this page’s properties to make the page dynamic or secure static.
To add the Login widget
1 Create a blank page to hold the Login widget.
279

Chapter 12: Access Control
280
When the application calls the page containing the Login widget, the
widget will cause the login page (the page containing the login form) to be
displayed.
2 Drag a Login widget from the Project window to the page.
3 Set the widget’s properties.
The following four tables explain what information you need to supply on
the four tabs of the Login Properties dialog.
The first tab of the dialog, labeled General, enables you supply a name for
the widget and to specify some general characteristics of the widget’s
behavior.
Form field Description
Name Type the name of the Login widget here.
Reset session privileges on
successful login check box
When a user’s session loads a page
containing a Login widget, the user may
already have some session privileges. If this
check box is checked, the user’s current
privileges are taken away, and the user is
assigned the privileges indicated on the
Privileges tab of the Login Properties dialog.
If the check box is not checked, the user
receives the privileges indicated on the
Privileges tab in addition to any current
privileges.

Form field Description
Remember successful login
check box
Only one login per session
check box
Chapter 12: Access Control
This option enables you to specify whether
the user must log in each time the user goes
to the page containing the Login widget
(unchecked) or whether the user must log in
only the first time the user goes to that page
(checked).
An application may contain more than one
Login widget. If this check box is checked,
the user will be prompted to log in only
once per session.
The Navigation tab of the Login Properties dialog enables you to indicate
the pages the Login widget should call:
to display a login form
if the login succeeds
if the login fails
Form field Description
Login page: Page containing
widget
Select this radio button if the page
containing the Login widget also contains
the login form the user fills out to log in.
281

Chapter 12: Access Control
282
Form field Description
Login page: Another page Select this radio button if the page
containing the Login widget and the page
containing the login form are different
pages. In the example project, this is the
case.
Success page: Page containing
widget
Select this radio button if the page
containing the Login widget is also your
success page.
Success page: Another page Select this radio button if the page
containing the Login widget and your
success page are different pages. In the
example project, this is the case.
Failure page: Page containing
widget
Select this radio button if the page
containing the Login widget is also your
failure page.
Failure page: Another page Select this radio button if the page
containing the Login widget and your failure
page are different pages. In the example
project, this is the case.
The Login tab of the Login Properties dialog enables you to indicate the
names of the text boxes in which the Login widget will look for login
information:

Form field Description
Chapter 12: Access Control
User Name The name of the text box in the login form
in which the user enters a user name.
User Password The name of the text box in the login form
in which the user enters a password.
User Domain The name of the text box in the login form
in which the user enters a Windows NT
domain name. This information is only used
if the user is logging on against
authentication information maintained by
Windows NT.
Note - If you create your login page as described in “To add the
pages required by the Login widget” on page 278, you won’t
have to modify the Login tab of the dialog.
On the Privileges tab of the Login Properties dialog, you indicate whether
a logged-in user should receive a predefined set of privileges or whether
the Login widget should look up the user’s privileges in a privilege
repository. The current example is using the former option: a user receives
the “Subscribed” privilege upon logging in. For information on looking up
privileges in a privilege repository, see “Granting privileges on a user-name
basis” on page 289.
283

Chapter 12: Access Control
To configure the Application Server
284
Form field Description
Use privilege repository radio
button
Grant privileges on login radio
button
Select this button to indicate that the widget
should read the user’s privileges from a
database or some other repository.
Select this button to indicate that a user who
successfully logs in should receive the
privileges shown in the list. You can add
privileges to and remove privileges from the
list by using the Add... and Remove buttons.
Set the access-control properties of your Application Server so that the
Authentication Type is either Operating System or User Defined. (By
default, this property is set to Operating System.) For specific instructions
on how to configure this property, see Chapter 3, “Performing
administrative tasks,” in the HAHTsite Application Server Administration
Guide.
If you select Operating System authentication, the Login widget will use a
Java class called OSAuthentication to authenticate users. This is the
scenario in the sample project.
The OSAuthentication class, which implements the Authentication
interface, uses the operating system’s login mechanism to authenticate
user logins. This authentication is performed on the HAHTsite Background
Host on which the HAHTsite session is running. Before you use the
OSAuthentication class with HAHTsite, you should be aware of the
following platform-specific requirements:
Windows NT requires that a process hold a Windows NT privilege
named “Act as a part of the Operating System” in order to validate a
user login. The HAHTsite Background Service that performs this
validation runs as the System Account by default. This account has
the required privilege. Therefore, you should not change the user
account for the HAHTsite Background Service if you want to use
operating-system authentication.
The Developer’s Edition of the HAHTsite Application Server cannot
actually perform operating-system authentication because it runs as a
desktop application. Consequently, when you’re running the
Developer’s Edition, the method used to authenticate users always
returns true unless the user name is “InvalidUser,” the password is
“InvalidPassword,” or the domain value is “InvalidDomain.” This

Chapter 12: Access Control
arrangement enables you to test success cases with different user
names without knowing the corresponding passwords, and to test
failure cases with the Developer’s Edition.
For HAHTsite Background Hosts running on UNIX, you can use
OSAuthentication only if a root installation of the Application Server
has been performed.
If you select User Defined authentication, you must write and add to your
project a Java class that performs the authentication. You must also write
code that will set a variable of your application’s Application object at
runtime. This variable must contain the name of the authentication class
you’ve written. For further information about implementing a custom
authentication class, see “To perform user-defined authentication” below.
To perform user-defined authentication
1 In your project’s Packages folder, create a Java source file and write your
authentication class. This class must implement the Authentication
interface and, thus, must define a method named authorizeUser:
boolean authorizeUser(String aUserID, String aPassword, String
aDomain)
This method should return true if the user is authenticated, and false
otherwise. Appendix C, “Code Examples,” presents a sample
authentication class that authenticates users against information stored in
a database.
2 Add to your project the code that will enable your application to
determine at runtime which Java class it should use for user-defined
authentication. This task differs somewhat between Java and HAHTtalk
Basic projects.
Java projects. Modify your project’s HahtApplication class by editing the
source file HahtApplication.java. Add to the class’s onStart method
code to identify your custom authentication class. You do this by calling
the method setAuthenticationClassByName.
Java
public void onStart(com.haht.project.ApplicationEvent anEvent)
{
this.setAuthenticationClassByName("CustomAuthentication");
}
285

Chapter 12: Access Control
286
HAHTtalk Basic projects. Add a code page to your project, and in this file
define a public function called HahtSessionOnStart. This function should
call the Application object’s setAuthenticationClassByName method to
identify the name of the user-defined class that will perform the
authentication.
HAHTtalk Basic
Public function HahtSessionOnStart As Boolean
Dim AuthSuccess As Boolean
AuthSuccess = _
HahtApplication.setAuthenticationClassByName _
("CustomAuthentication")
HahtSessionOnStart = AuthSuccess
End Function
Caution - In a Java project, a publish operation does
not place your custom authentication class in the
!
Application Server’s default Java Class Directory or
in a default directory on the System Java Class Path.
Before running your application, either move your class file to
a directory where the Application Server can find it, or change
your System Java Class Path to include the directory where
your class file resides.
Tip - While debugging a custom authentication class, turn on
the project property “Run each app instance in separate
process.” This setting will cause the Application Server to
reload your authentication class each time you run your
application.
Authenticating users with the Authentication interface
The Login widget authenticates users by calling:
the authorizeUser method of a class that implements the
Authentication interface
the Session class’s addPrivilege or addPrivileges method
Since you also have access to these methods, you can call the methods directly,
instead of using the Login widget.

Chapter 12: Access Control
For example, assume that you wanted to modify the sports-news project so
that it did not use the Login widget. You could have users who want to log in
go not to a page containing a Login widget, but directly to the page containing
the login form. You could then change the action of the form so that the form
calls one of the subroutines shown below.
Java
package AccessCtrlJava1;
import com.haht.*;
import com.haht.project.*;
class AuthenticateUser {
public void run(Request aRequest, Response aResponse) {
/* Authenticate the user and assign the user
the privilege Subscribed if the authentication
is successful. */
String userName = aRequest.getURLField("txtUserName");
String password = aRequest.getURLField("txtUserPassword");
String domain = aRequest.getURLField("txtUserDomain");
boolean authenticated = Haht.getSession().
getAuthentication().
authorizeUser(userName, password, domain);
if (authenticated == true) {
Haht.getSession().addPrivilege("Subscribed");
HAHTPage successPage = Haht.getSession().
returnHAHTPageObject("AccessCtrlJava1.HsSuccess");
successPage.run(aRequest, aResponse);
}
else {
HAHTPage failurePage = Haht.getSession().
returnHAHTPageObject("AccessCtrlJava1.HsFailure");
failurePage.run(aRequest, aResponse);
}
}
}
287

Chapter 12: Access Control
HAHTtalk Basic
Sub AuthenticateUser
Dim aRequest As Object
Dim userName As String
Dim password As String
Dim domain As String
Dim authenticated As Boolean
Set aRequest = Haht.getRequest()
userName = aRequest.getURLField("txtUserName")
password = aRequest.getURLField("txtUserPassword")
domain = aRequest.getURLField("txtUserDomain")
authenticated = HahtSession.getAuthentication(). _
authorizeUser(userName, password, domain)
If (authenticated = True) Then
HahtSession.addPrivilege "Subscribed"
HS_Success
Else
HS_Failure
End If
End Sub
Generally, it’s preferable to use the Login widget in your application because
this approach requires less coding and gives you more features. But
occasionally you may need to authenticate users using the Server Object
Model methods.
Letting the Web server authenticate users
In addition to authenticating users against information maintained by the
operating system or information in a user-defined location, you may want to
authenticate users against information maintained by your Web server. In this
case, you don’t use the Login widget or methods defined in the Server Object
Model. You just configure your Web server so that URLs requesting dynamic
or secure-static pages from a HAHTsite Application Server cause the Web server
to send an authentication request to the browser.
To use your Web server’s authentication mechanism
1 Configure your Web server to authenticate a user who requests a dynamic
or secure-static page.
288

Chapter 12: Access Control
2 After the user is authenticated, assign the user one or more privileges using
the Session class’s addPrivilege or addPrivileges method.
3 Configure your Application Server’s access-control properties so that its
Authentication Type is None.
Note - If you need a user’s user name for any reason — for
example, you may want to look up a user’s privileges in a
database — you can get it by calling the Request class’s
getServerVariable method to obtain the value of the
environment variable REMOTE_USER. For information about
looking up user privileges in a privilege repository, see
“Granting privileges on a user-name basis” on page 289.
Granting privileges on a user-name basis
The preceding section explained how to require a user to log in to an
application and to grant a user a set of privileges upon a successful login. In
this arrangement, everyone who logs in to the application gets the same
privileges. This approach may work fine for the sports-news project, but other
applications may require that different users get different privileges. For
example, consider any application that accesses a database. Some users should
not be able to access the database at all (no privileges), some people should
have read-only access to the database (“User” privilege), and some people
should be able to read from and write to the database (“User” and “Admin”
privileges). Building on the information presented in earlier sections, this
section explains how to grant privileges on a user-by-user basis.
For this type of scheme to work, you must first create a privilege repository. This
repository can be a database table, but need not be. It could also be an LDAP
directory or a regular file. The only hard-and-fast rule is that the privilege
repository must specify the privileges to be given to a user with a particular
user name.
Once you’ve decided how to implement your privilege repository, there are
several scenarios to consider:
Your application uses a Login widget, and your privilege repository is a
database table.
Your application uses a Login widget, and your privilege repository is not
a database table.
Your application does not use a Login widget.
289

Chapter 12: Access Control
The upcoming sections explain how to handle each of these situations.
Using a Login widget and a database privilege
repository
If you have an application — like the sports-news project described in
“Granting privileges to logged-in users” on page 276 — that assigns all users
who log in the same set of privileges, there are three tasks you’ll have to
perform to have the application assign each user a custom set of privileges read
from a database:
290
Create a database table that contains information about each user’s
privileges.
Configure the Login widget to look up a user’s privileges in a privilege
repository.
Configure the Application Server to look for a user’s privileges in your
database.
The following sections explain in detail how to perform these tasks.
To create the database privilege repository
1 Create a database table named hsSecurityPrivileges.
2 In this table, create the fields shown in the table below.
Field name Description Data type
hsUserid The user’s user ID. This ID does not have
to be unique.
hsPrivilege The name of a privilege belonging to
the user.
Each row in the table specifies one privilege belonging to a user. The Login
widget reads the entire table to obtain a list of a user’s privileges.
3 Enter user names and privileges in the table, one user name and privilege
per row.
If a user has three privileges, you should add three rows to the table for
that user.
To configure the Login widget
1 Open the Login Properties dialog for the Login widget.
String
String

2 Go to the Privileges tab.
3 Select the radio button labeled “Use privilege repository.”
Chapter 12: Access Control
When you choose this setting, the Login widget behaves as follows: After
authenticating a user, the widget opens a connection to a database known
to the Application Server (the database containing the table
hsSecurityPrivileges) and reads the user’s privileges from the appropriate
table using a method of the DBUserProfile class. It then assigns those
privileges to the user’s session.
To configure the Application Server
1 Change your Application Server’s access-control properties so that the
Privilege Repository Type is Database.
2 Supply a DB Privilege Repository Connect String.
If you’re not sure how to write the connection string, you might want to
use the IDE to create an ADO connection to the privilege database. When
you create this connection, if you use the IDE’s Connection Browser to
point to your database, the IDE will create a connection string for you.
You can copy this connection string and paste in into the DB Privilege
Repository Connect String text box.
Using a Login widget and a nondatabase privilege
repository
It’s also possible to use the Login widget with a nondatabase version of the
privilege repository to assign privileges to users. However, to make this work,
you must write a Java class that contains a method that takes a user name as
an argument and returns a set of privileges. This subject is discussed in more
detail in “To create a Java class and make it known to your application” on
page 292.
There are three basic tasks you must perform to have your application assign
each user a custom set of privileges read from a user-defined location:
Configure the Login widget to look up a user’s privileges in a privilege
repository.
Configure the Application Server to look for a user’s privileges in a
user-defined location.
Write a custom user-profile class containing a lookupPrivileges method
that returns a list of privileges for a particular user. And make this class
known to your application.
291

Chapter 12: Access Control
The following sections explain in detail how to perform these tasks.
To configure the Login widget
1 Open the Login Properties dialog for the Login widget.
2 Go to the Privileges tab.
3 Select the radio button labeled “Use privilege repository.”
292
When you choose this setting, the Login widget behaves as follows: After
authenticating a user, the widget checks an Application Server property to
determine whether your privilege repository is in a database or elsewhere.
When it determines that your repository is not in a database, the widget
calls the lookupPrivileges method of a class you’ve written and made
known to your application. (You must write this method since you’re the
only one who knows where and in what format your privileges data is
stored.) Finally, the widget assigns the privileges it retrieves to the user’s
session.
To configure the Application Server
Change your Application Server’s access-control properties so that the
Privilege Repository Type is User Defined.
To create a Java class and make it known to your application
1 In your project’s Package folder, create a Java source file and write your
custom user-profile class. This class must implement the UserProfile
interface and, thus, must define a method lookupPrivileges:
Privileges lookupPrivileges(String aUserID)
The Privileges object returned by this method is a container for a set of
privileges. For more information about the Privileges class, see
“Privileges class” on page 298.
2 Add to your project the code that will enable your application to
determine at runtime which Java class it should use for user-defined
privilege lookup. This task differs to a degree between Java and HAHTtalk
Basic projects.
Java projects. Modify your project’s HahtApplication class by editing the
source file HahtApplication.java. Add to the class’s onStart method
code to identify your custom privilege-lookup class. You do this by calling
the method setUserProfileClassByName.

Java
Chapter 12: Access Control
public void onStart(com.haht.project.ApplicationEvent anEvent)
{
this.setUserProfileClassByName("CustomUserProfile");
}
HAHTtalk Basic projects. Add a code page to your project, and in this file
define a public function called HahtSessionOnStart. This function should
call the Application object’s setUserProfileClassByName method to
identify the name of the user-defined class that will perform the privilege
lookup.
HAHTtalk Basic
Public function HahtSessionOnStart As Boolean
Dim ProfSuccess As Boolean
ProfSuccess = HahtApplication.setUserProfileClassByName _
("CustomUserProfile")
HahtSessionOnStart = ProfSuccess
End Function
Using the Server Object Model
You don’t have to use HAHTsite’s Login widget to look up a user’s privileges in
a privilege repository and assign them to the user’s session. Your application
can call the lookupPrivileges method (of a class that implements the
UserProfile interface) and the Session class’s addPrivileges method
directly to accomplish the very same thing. This would be a useful approach
to take if you were using your Web server to perform user authentication, for
example.
The list of steps you must perform to look up and assign privileges in this way
is as follows:
1 Create your privilege repository.
If you want to store information about users and their privileges in a
database table, follow the directions in “To create the database privilege
repository” on page 290. If you choose to store the information elsewhere,
just remember that the Java method that looks up privileges takes a user
name as its argument and returns an object of type Privileges, which
contains a list of privileges. Since you must implement this method
293

Chapter 12: Access Control
294
yourself (if your privilege repository is not a database table), you can store
the data in any format you choose.
2 Configure your Application Server’s Privilege Repository Type and supply
a database connection string, if necessary.
If your privilege repository is a database table, choose a Privilege
Repository Type of Database, and enter the connection string the
Application Server will need to establish a connection with your database.
If your privilege repository is not a database, choose a Privilege Repository
Type of User Defined.
3 If your privilege repository is not a database, implement a custom
user-profile class, and modify your project so that it will know about your
user-profile class at runtime.
See “To create a Java class and make it known to your application” on page
292 for more information about how to perform this step.
4 Add to your application code that calls the lookupPrivileges and
addPrivileges methods.
The example below shows how your application might make these calls.
The example assumes that the user fills in a login form and that the form’s
action is to call a subroutine that authenticates the user and looks up his
or her privileges. The lines highlighted in the subroutine are the ones that
have to do specifically with looking up privileges and assigning them to a
user session.

Java
package AccessCtrlJava1;
import com.haht.*;
import com.haht.project.*;
import com.haht.access.*;
Chapter 12: Access Control
class AuthenticateUser {
public void run(Request aRequest, Response aResponse) {
String userName = aRequest.getURLField("txtUserName");
String password = aRequest.getURLField
("txtUserPassword");
String domain = aRequest.getURLField("txtUserDomain");
Privileges privs = new Privileges();
Session sess = Haht.getSession();
boolean authenticated = sess.getAuthentication().
authorizeUser(userName, password, domain);
if (authenticated == true) {
UserProfile prof = sess.getUserProfile();
try {
privs = prof.lookupPrivileges(userName);
}
catch (com.haht.HahtException except) {
}
String privStrings[] = privs.getStringArray();
sess.addPrivileges(privStrings);
HAHTPage successPage = Haht.getSession().
returnHAHTPageObject("AccessCtrlJava1.HsSuccess");
successPage.run(aRequest, aResponse);
}
else {
HAHTPage failurePage = Haht.getSession().
returnHAHTPageObject("AccessCtrlJava1.HsFailure");
failurePage.run(aRequest, aResponse);
}
}
}
295

Chapter 12: Access Control
Server Object Model methods
HAHTsite’s Server Object Model contains a number of classes that define
methods relating to access control: Session, Privileges, and Application.
The model also defines two interfaces — Authentication and UserProfile —
that you make use of when implementing user-defined authentication or
user-defined privilege lookup. The following pages list the relevant methods
of these classes and interfaces.
296
HAHTtalk Basic
Sub AuthenticateUser
Dim aRequest As Object
Dim prof As Object
Dim privs As Object
Dim sessionPrivs As Object
Dim userName As String
Dim password As String
Dim domain As String
Dim authenticated As Boolean
Set aRequest = Haht.getRequest()
userName = aRequest.getURLField("txtUserName")
password = aRequest.getURLField("txtUserPassword")
domain = aRequest.getURLField("txtUserDomain")
authenticated = HahtSession.getAuthentication(). _
authorizeUser(userName, password, domain)
If (authenticated = True) Then
Set prof = HahtSession.getUserProfile()
Set privs = prof.lookupPrivileges(userName)
Set sessionPrivs = HahtSession.getPrivileges()
If (sessionPrivs.merge(privs)) Then
' Check for error here.
End If
HS_Success
Else
HS_Failure
End If
End Sub

Session class
Chapter 12: Access Control
A Session object keeps track of information related to the state of an
application with respect to a single user. The methods of the Session class that
relate to access control are listed below.
Method Description
addPrivilege adds a single privilege to a user’s session
addPrivileges adds a set of privileges to a user’s session.
Available in Java projects only.
getAuthentication gets a reference to the session’s
authentication object. This object may have
been instantiated from the
OSAuthentication class or from a
user-defined authentication class.
getAuthenticationType returns a constant indicating the type of
the session's authentication object: OS
authentication, user-defined
authentication, or none
getPrivileges returns the set of privileges that have been
granted to the current session
getUserProfile gets a reference to the session’s user-profile
object. This object may have been
instantiated from the DBUserProfile class
of from a user-defined class.
hasPrivilege returns true if the user’s session has a
specific privilege
hasPrivilegesForItem returns true if a session has all of the
privileges required to access a particular
project item
removePrivilege removes a privilege from the set of
privileges held by the user’s session
removePrivileges removes some or all of the privileges
associated with the user’s session. Available
in Java projects only.
297

Chapter 12: Access Control
Privileges class
A Privileges object is a container for a set of privileges. The methods listed
below make up the interface to objects of this type.
Method Description
add adds a privilege to a list of privileges
clear removes from a Privileges object all the
privileges it contains at the time of the call
getStringArray returns the privileges contained in a
Privileges object as an array of strings.
Available in Java projects only.
hasAll returns true if the Privileges object
being used to access this method includes
all of the privileges contained in another
Privileges object
hasOne returns true if the Privileges object
being used to access this method includes
any one of the privileges contained in
another Privileges object
has returns true if the Privileges object
being used to access this method contains a
specific privilege
merge merges the contents of two Privileges
objects
remove removes a privilege from a Privileges
object
setStringArray adds to a Privileges object all of the
privileges contained in an array of strings.
Available in Java projects only.
Application class
The Application class provides methods that enable you to set or read the
name of:
298
a user-defined authentication class
a user-defined privilege lookup class

Method Description
Authentication interface
Chapter 12: Access Control
setAuthenticationClassByName enables you to specify the name of the
user-defined authentication class to be
used by the application
setUserProfileClassByName enables you to specify the name of the
user-defined privilege lookup class to be
used by the application
An object instantiated from a class that implements the Authentication
interface is responsible for authenticating a user who is attempting to log in to
an application. The object takes a user ID, a password, and possibly a Windows
NT domain name as input and compares that information with the
information in a user name/password repository. The interface to this object
is shown below.
Method Description
authorizeUser authenticates a user by comparing the user’s
login information with information in a
user name/password repository
UserProfile interface
An object instantiated from a class that implements the UserProfile interface
holds information about the session privileges associated with a particular
user. It gets its information from a database table or a user-defined repository.
The interface to this type of object is shown below.
Method Description
lookupPrivileges reads a repository to determine what
session privileges are to be granted to a
particular user and returns those privileges
as an object of type Privileges
299

Chapter 12: Access Control
300

Connecting to COM
Objects
13
Introduction..................................................................................................302
Calling DLLs .................................................................................................302
Declaring a DLL in HAHTtalk Basic........................................................302
Example DLL declarations.......................................................................303
Mapping HAHTtalk Basic types to DLL data types ................................304
Using COM objects with HAHTtalk Basic ...................................................305
The CreateObject function......................................................................305
A COM Server example ................................................................................306
Background ..............................................................................................307
HAHTMem methods................................................................................307
301

Chapter 13: Connecting to COM Objects
Introduction
If your Web server is running on a Windows NT machine, you can extend the
functionality of your HAHTsite applications by connecting the applications to
DLLs and COM objects. (A DLL is a dynamic link library. COM stands for
Component Object Model.) In a HAHTsite application, DLLs and COM servers
run as server-side objects (in contrast to client-side objects such as JavaScript
and VBScript).
This chapter explains how to call DLLs and connect to COM/DCOM objects
in a HAHTsite Basic project. You can accomplish the same thing in a Java
project using native methods; consult the documentation for your Java
compiler or the HAHTsite knowledge base at www.haht.com.
Calling DLLs
The method for calling a DLL from a HAHTtalk Basic application is the same
as calling a DLL from a Visual Basic application:
1 Obtain, from the author of the DLL, the number of DLL functions and
parameters.
2 Use the HAHTtalk Basic Declare statement to declare, typically in the
application’s globals.hbs file or in an include file, the DLL as a HAHTtalk
Basic function or subroutine. In many cases, the DLL’s author will provide
a Basic file with the DLL’s functions and subroutines already declared in
the Basic syntax.
3 Call the function or subroutine from a HAHTtalk Basic code page or HTML
page.
Declaring a DLL in HAHTtalk Basic
The syntax for the HAHTtalk Basic Declare statement is described completely
in the HAHTsite on-line help. Here is a summary:
Declare {Sub | Function} name[TypeChar] [CDecl | Pascal ] _
[Lib "LibName$" [Alias "AliasName$"]] _
[([ParameterList])] [As Type]
302

Item Description
Chapter 13: Connecting to COM Objects
Sub | Function If the DLL function is void (the function returns no value),
use “Sub.” If the DLL function returns a value, use
“Function.”
name The name of the DLL function. If the function is called
CalcSalesTax in C/C++, use the same name in the HAHTtalk
Basic declaration.
Cdecl | Pascal Order in which parameters are passed between the calling
program and the DLL. The default ordering is Pascal, which
passes parameters starting from the first parameter. If the
DLL function explicitly uses the Cdecl keyword in its
definition, use the Cdecl keyword in your declaration.
Lib "LibName" “Lib” specifies that the DLL is external to the calling
program.
“LibName” is the name of the DLL (in quotes). “LibName”
can include a path and need not include the .DLL extension.
Alias
"AliasName"
Note - HAHTtalk Basic does not support DLL functions that
return the following data types: Currency, Variant, fixedlength
strings, user-defined types, or COM objects. For more
information, see the Declare topic in HAHTsite’s on-line help.
Example DLL declarations
Use an alias when the name of an external routine conflicts
with the name of a HAHTtalk Basic internal routine or when
the external routine name contains invalid characters. The
AliasName parameter must appear within quotes.
ParameterList Any parameters, and their types, sent to the DLL. See
“Mapping HAHTtalk Basic types to DLL data types” on page
304.
As Type If the DLL is void (returns no value) and is declared as a Sub,
do not include this item. If the DLL is declared as a
Function, include the type. The valid return types are:
Integer, Long, String, Single, Double, Date, Boolean, and data
objects.
Here is a the API of a sample DLL written in C, followed by the HAHTtalk Basic
declaration for the DLL.
float __declspec(dllexport) CalcSalesTax(float SaleAmount, _
303

Chapter 13: Connecting to COM Objects
304
float TaxAmount)
Declare Function CalcSalesTax Cdecl Lib "SalesTax" _
(ByVal SaleAmount As Single, _
ByVal TaxAmount as Single) As Single
Here are other examples of HAHTtalk Basic DLL declarations. These DLL calls
are used in the XtremeCatalog module of the Xtreme_Demo in the HAHTsite
introduction project.
Declare Function LogonUser Lib "advapi32" _
Alias "LogonUserA" (ByVal lpszUsername As String, _
ByVal lpszDomain As String, ByVal lpszPassword As String, _
ByVal dwLogonType As Long, ByVal dwLogonProvider As Long, _
phToken As Long) As Long
Declare Function CloseHandle Lib "kernel32" _
Alias "CloseHandle" (ByVal hObject As Long _
As Long
Mapping HAHTtalk Basic types to DLL data types
Many DLLs are written in C or C++. The next table shows the relationship
between C/C++ data types and HAHTtalk Basic data types.
C Data Type HAHTtalk Basic Data Type
short (16-bit integer) ByVal Integer
long (32-bit integer) ByVal Long
short * (ptr to 16-bit integer) ByRef Integer
long * (ptr to 32-bit integer) ByRef Long
float ByVal single
double ByVal double

C Data Type HAHTtalk Basic Data Type
Chapter 13: Connecting to COM Objects
char * ByVal string
If the DLL is writing to the string, you must preallocate
the string space in HAHTtalk Basic. One
way to do this is:
TheStr = String$(TheMaximumLen,0)
Where TheStr is the string you are passing and
TheMaximumLen is the maximum length to
which the string could be populated.
The String$ function populates the string with
null bytes, which is compatible with the C
language convention for string termination.
structure * ByRef structure_type
Each element in the HAHTtalk Basic structure
must be explicitly defined, for example
TheStr As String*20
Additionally, the DLL must have been built on
single-byte alignment.
Using COM objects with HAHTtalk Basic
You create a COM object (an instance of a COM Server) with the HAHTtalk
Basic function CreateObject function. You can then access the object’s
methods and properties from your HAHTtalk Basic code
Once you have a COM object in a HAHTtalk Basic variable of type Object, you
access the object’s properties and methods using the "." syntax.
The CreateObject function
Syntax
Function CreateObject(COMObjectName) As Object
Description
Creates an instance of the COM Server specified in the COMObjectName
parameter. The supplier of the COM Server is responsible for providing
you with the methods and properties of the server.
305

Chapter 13: Connecting to COM Objects
You must register the COM Server with the Windows Regsvr32 utility, or with
a similar facility such as HAHTtalk Basic’s DLLRegisterServer function.
HAHTsite locates ActiveX/COM objects by looking in the registry on the
HAHTsite Application Server’s machine. For example, if you use the function
CreateObject("Excel.Application"), HAHTsite looks up
Excel.Application in the system registry to find the binary file for that
object.
Parameters
Parameter Type Description
COMObjectName String Registered COM object name
Example
The following subroutine creates a COM Server object called cObj from the
COM Server HAHTMem.
Sub DemoHAHTMem()
Dim cObj As Object
306
' Create an instance of the COM server
Print "Creating An Instance to the HAHTMem Server...";""
Set cObj = CreateObject("HAHTMem.cMemMgr")
'
' Code to use the COM Server.
'
End Sub
A COM Server example
This section describes a simple example of connecting HAHTsite to a COM
Server called HAHTMem. The HAHTMem COM Server provides for shared-memory
workspaces among multiple instances of a HAHTsite application running on
the same Windows machine.
Note - A project that contains the HAHTMem COM Server is
available online in the HAHT Software knowledge base
(www.haht.com).

Background
Chapter 13: Connecting to COM Objects
One of the features of the HAHTsite Application Server is its ability to maintain
state. At a conceptual level, there are different kinds of state you might want
to maintain:
state that is "per-instance" of a HAHTsite application. This is the kind of
state you get when you declare a global HAHTtalk Basic variable. Each
StateId (i.e., user) gets his or her own per-instance state. Any global
variables (defined in globals.hbs) are part of that user’s per-instance state.
A change that “User A” makes to his global variable “MyVariable” does
not affect what “User B” gets when she accesses her “MyVariable” global
variable.
state that is shared across all instances of the same application running
on the same machine. For example, information kept in a database table
to which the application attaches falls into this category. However
getting and setting cross-instance values in a database carries the
overhead of accessing the database.
Another approach to sharing state across instances of an application is to
allocate memory that can be accessed by all instances of the application.
In the simplest case, you might simply keep a count of the number of copies
of the application that were active— the number application instances. Or,
you could keep more sophisticated usage statistics.
Another example might be a “chat room” or “bulletin board” application in
which you need to keep a list of currently active users so that all users could
see what other users were logged in. This is what the HAHTMem COM Server
provides—each instance of an application can attach to the COM Server and
get access to a common shared memory area.
HAHTMem methods
Here is a description of the methods provided by the HAHTMem COM Server.
OpenWorkspace — HATHMem manages named workspaces that contain
one or more variables. If an OpenWorkspace command uses a workspace
name that doesn’t exist, the workspace is created. If the workspace
already exists, the in-use count for that workspace is incremented.
OpenWorkspace returns to the caller an ID which is used by the caller for
all subsequent operations against the workspace.
CloseWorkspace — detaches the caller from the workspace. The
workspace's in-use count is decremented by 1. If the workspace in-use
count reaches 0, the workspace is deleted.
307

Chapter 13: Connecting to COM Objects
308
OpenVar — opens a variable in an existing workspace. All variables are
referred to in the syntax of Workspace:Variable, where Workspace is the
workspace name and Variable is the variable name (for example,
FileLocks.MainLogFile). All workspace variables are stored as HAHTtalk
Basic Variant data types in the HAHTMem COM Server.
CloseVar — closes a variable in a workspace.
WriteVar —writes a value to a variable in a workspace.
ReadVar — reads the value of a variable in a workspace.
LockVar — locks access to a workspace variable to the current caller.
Returns True or False depending whether the lock request was successful.
If the lock request returns False, another application currently has the
variable locked, the application should perform an OS Sleep() and then
try again to lock the variable.
UnlockVar — unlocks exclusive access to a workspace variable.
LockWorkspace — locks a workspace for exclusive access by the current
application. Returns True or False depending if Lock request was
successful.
UnlockWorkspace — unlocks a workspace for exclusive access by the
current application.

HAHTsite CORBA
Capabilities
14
Overview .......................................................................................................310
Using CORBA with the HAHTsite IDE .........................................................311
HAHTsite as a CORBA client ........................................................................315
HAHTsite as a traditional CORBA server .....................................................318
CORBA and the HAHTsite Server Object Model .........................................321
Other Information ........................................................................................328
References......................................................................................................330
309

Chapter 14: HAHTsite CORBA Capabilities
Overview
HAHTsite gives you the ability to integrate Web applications with objects
created using CORBA, the Common Object Request Broker Architecture.
Among other things, this flexible mechanism can be used to:
310
integrate HAHTsite Web applications with large-scale and legacy systems
provide a direct connection between a client and the Application Server,
bypassing the Web server
allow external programmatic control over the operation of the
Application Server, including the initiation of HAHTsite application
sessions
While HAHTsite can be used to create sophisticated Web applications, many
customers already have complex computing environments built over many
years. Often, a major reason for providing Web capabilities is the exposure of
parts of these systems to the external world via the Internet, or access by the
enterprise through an intranet. Integration with CORBA allows HAHTsite to
connect new Web applications with a wide variety of existing enterprise
systems.
What is CORBA?
This chapter assumes familiarity with CORBA programming. CORBA (the
Common Object Request Broker Architecture) is the leading method for
building large-scale, distributed objects and applications. It is defined by the
Object Management Group, a consortium of over 800 companies. More
information is available from the OMG Web site: http://www.omg.org.
What does HAHTsite/CORBA interoperation mean?
The software bundled with HAHTsite includes Inprise (formerly Visigenic)
VisiBroker for Java. HAHTsite applications written using the HAHTsite Server
Object Model can incorporate calls to the VisiBroker interfaces and thereby act
as standard CORBA objects. Using CORBA’s built-in capabilities, they can
communicate with and become part of an enterprise built of distributed
CORBA objects.
Information from remote CORBA systems, such as mainframes, can be
obtained by these CORBA-enhanced HAHTsite applications. This data can
then be used in any manner within the HAHTsite application, providing a
flexible, complete method to present enterprise information on the Web.

Chapter 14: HAHTsite CORBA Capabilities
In addition to this peaceful coexistence, there are several extensions to the
HAHTsite Server Object Model that provide CORBA interfaces, allowing
CORBA systems to operate directly on some HAHTsite server objects. This level
of integration allows an external, non-HAHTsite application to connect as a
CORBA client to a CORBA-enabled HAHTsite application acting as a CORBA
server. Such a client can initiate and control a HAHTsite session, making use
of session capabilities such as automatic timeout.
CORBA can also provide a Java applet running in a browser the ability to
communicate with a HAHTsite application without the overhead of the HTTP
protocol. For applets requiring substantial or very dynamic data from the
server, this can be very beneficial.
Outside the support in HAHTsite for writing CORBA-enabled applications,
HAHTsite is not built on and does not directly depend on CORBA. If you have
no need to develop CORBA-based applications, you need not install VisiBroker
for Java.
Using CORBA with the HAHTsite IDE
The HAHTsite IDE can be used to build VisiBroker-enhanced HAHTsite
applications, handling the details of compilation of Java and CORBA code,
and putting the compiled classes in the proper location for use. In order to
accomplish this, the IDE provides a number of configuration points.
Handling CORBA projects
If the Application and Session objects are to be exposed as CORBA objects,
the check box “Expose Session and Application Objects to CORBA” must be
selected from the project’s Edit > Properties dialog box. Setting this check box
causes the IDE to generate CORBA-enabled HahtApplication and
HahtSession classes when the project is built, using the VisiBroker TIE
mechanism. This is not required if the application represents a CORBA client
or a straightforward CORBA server that creates its own objects.
You add an IDL file to the project in the same way that you add other file types.
File > New > IDL will create a new IDL file that can be added to the project, or
you can import an existing IDL file from the main File menu or by
right-clicking in the Project view.
When you publish a CORBA-enabled project, the IDL compiler produces a
number of Java files in the staging directory. These files are compiled, and the
311

Chapter 14: HAHTsite CORBA Capabilities
resulting classes are stored on the Web server or Application Server, depending
on how the IDE is configured. As with other file types, individual IDL files may
be selected and compiled by using the IDL > Build menu.
312
Note - The Visibroker IDL compiler is not included with
HAHTsite.
Setting options for CORBA
The addition of CORBA capabilities adds several dialogs to the IDE
configuration. A new Java file type is created for CORBA projects. The IDE
distinguishes Java code that is to be run on the Application Server from code
that is to be run elsewhere, and different Java compilers may be specified for
the two types of Java files. Under the Tools > Options... > Java > Add dialog, a
Java compiler may be added for Java files that are part of CORBA projects. The
setup of the default Java compiler profile for CORBA-generated Java files sets
up the proper Java compiler switches and places the necessary Visigenic JAR
files (vbjapp.jar and vbjorb.jar) in the compiler’s Class Path argument.
There is a new dialog under Tools > Options... > CORBA that allows IDL
compilers to be configured. Different IDL compilers may be specified
depending on whether the output code is to be run on the Application Server
or elsewhere. As with the Java compilers, different compiler options may be set
on an IDL compiler using the Add or Modify buttons. A typical use might be
to instruct the IDL compiler to produce ORB-independent code if the
application stubs and skeletons are to be compiled with compilers from more
than one ORB vendor.

Chapter 14: HAHTsite CORBA Capabilities
Note - For detailed instructions on how to add or modify an
IDL compiler profile, see Chapter 2, “Using the IDE/IP’s
Windows and Toolbars,” in the HAHTsite IDE and IP User’s
Guide.
For an individual project, the Edit > Properties > CORBA Compilers dialog
allows you to override the IDL compiler defaults just described. By choosing
an IDL compiler (the default one is the IDL-to-Java Visibroker compiler) and
clicking Modify, you can change which compiler is used to translate IDL files
to Java. You can also modify the settings used for the IDL compilation process,
such as the root directory and options to the compiler
313

Chapter 14: HAHTsite CORBA Capabilities
.
By default, the VisiBroker IDL compiler generates several Java files for each
CORBA interface, placing them in the staging directory. The following class
files are generated when these files are compiled with the CORBA Java
compiler.
File Name File Type
module_name\interface_name.class Both
module_name\_st_interface_name.class Stub
module_name\_tie_interface_name.class Both
module_name\interface_nameImplBase.class Skeleton
module_name\interface_nameHelper.class Stub
module_name\interface_nameHolder.class Skeleton
module_name\interface_nameOperations.class Skeleton
module_name\_example_interface_name Skeleton
Not all classes are necessarily generated for each IDL interface, depending on
the settings of the IDL compiler options.
For each IDL file, properties may be set to determine where the compiled Java
classes will be placed. Right-click on the IDL file and choose Properties to bring
up the IDL Properties dialog. By default, all classes are placed in the
Application Server’s staging directory. The interface may be used to specify
314

Chapter 14: HAHTsite CORBA Capabilities
whether the stub classes (those required for a CORBA client) are compiled to
the Application Server, the Web server, or both. The same choices are available
for the skeleton classes (those required for a CORBA server).
HAHTsite as a CORBA client
HAHTsite allows you to build CORBA clients in the IDE and to run those
clients in the Application Server. The CORBA IDL files for a particular project
may be imported or created using the HAHTsite IDE editor. IDL files are
recognized by the IDE. When the project is published, the IDL compiler is
invoked to produce the Java client stubs and server skeletons. HAHTsite places
the compiled stub classes in their appropriate location in the HAHTsite
directory hierarchy.
A common, straightforward use of CORBA within HAHTsite applications is to
provide a Web “front-end” for data from enterprise CORBA applications. Such
data might be a customer’s order information, normally residing on a
mainframe. In this case, the HAHTsite Application Server runs code that acts
as a CORBA client, connecting to a CORBA server object outside of HAHTsite.
315

Chapter 14: HAHTsite CORBA Capabilities
Example: Building a HAHTsite CORBA client
Imagine a legacy system containing a database with customer names and
addresses, with access keyed to an account number. Typically, if the system is
wrapped using CORBA, an IDL file will already exist describing the interfaces
exposed by the system. In our simple example, the IDL file might look like
this:
Java
module CustomerDB {
interface Customer {
attribute string last_name;
attribute string first_name;
attribute string address1;
attribute string address2;
};
interface DB {
Customer getCustomerFromAcct(in string account);
string getInfoBanner();
};
};
In practice, the IDL file would be much larger than the one defined here, but
somewhere in it would be fields like the name and address for a customer, and
a method to get the customer object from the database.
Imagine a simple HAHTsite project containing a single Web page that allows
the user to type in the account number and have the customer name and
address displayed on the page.
316

Chapter 14: HAHTsite CORBA Capabilities
Initialization of the CORBA ORB in the client can occur at any time; a
convenient place to put the CORBA code is in Application.onSessionStart.
All you have to do at this point is to bind to the server object. The Java
application might contain code similar to this:
Java
// Make customer_database available through Application
CustomerDB.DB customer_database;
public void onSessionStart(com.haht.project.SessionEvent anEvent)
{
try {
// Initialize the ORB
org.omg.CORBA.ORB orb = org.omg.CORBA.ORB.init();
// Create the DB object - Example1 is the name of the
// database server
customer_database = CustomerDB.DBHelper.bind("Example1");
}
catch(org.omg.CORBA.SystemException e) {
System.err.println(e);
}
}
Normally, one would probably obtain the customer account number as an
input on the Web page — this can be done via JavaScript or from an applet. In
this example, you might simply generate a random account number from a list
of available ones. The code to do this is in the application as well.
Java
public java.lang.String getRandomAcct() {
java.lang.String account_numbers[] =
{"A09133F6", "B72553Z9", "C29943I7", "D28473W2",
"E27723E6", "F23884K8", "G23847B2", "H23847O6",
"I23984O2", "J29348W9", "K84724Z3", "L99283F9",
"M73624G6", "N22731A1", "O88247Y2", "P83472P1",
"Q24257Z0", "R82634D1", "S23523S9", "T23487U6"};
Random random = new Random();
int randval = random.nextInt();
if (randval < 0) randval = -randval;
randval = randval % account_numbers.length;
return account_numbers[randval];
}
317

Chapter 14: HAHTsite CORBA Capabilities
In order to get the information on the page, you place a server-side statement
in the page.
Java
Assuming the HAHTsite Application Server is running, and that the example
CORBA server and Smart Agent are running, the first read of the page in this
project will cause the session to be initiated, calling the CORBA client
initialization code. Each read of the page will use the reference to the customer
database to get the customer information, placing the information into the
page.
HAHTsite as a traditional CORBA server
HAHTsite applications can also act as CORBA servers. Using CORBA,
server-side applications can make callbacks into client applets, or send events
that clients are registered to receive so that clients can be notified of changes
in application status without requiring any action by the user or the overhead
of polling by the applet.
There are two basic methods that may be used to initiate a CORBA server
within the HAHTsite Application Server. The traditional method — discussed
in this section — follows the standard CORBA paradigm where the CORBA
server is started by the HAHTsite application, initializing its objects. CORBA
clients bind to objects in this server using a well-known name via the Naming
Service or Smart Agent. The other method, in which the CORBA server uses
the capabilities of a HAHTsite session, is discussed in “CORBA and the
HAHTsite Server Object Model” on page 321.
318
// First, print out today’s banner from the database server
Application app = com.haht.Haht.getApplication();
out.println(app.customer_database.getBanner()+"");
out.println(app.getRandomAcct());
out.println(app.customer_database.getName());
out.println(app.customer_database.getAddress1());
out.println(app.customer_database.getAddress2()+"");

Chapter 14: HAHTsite CORBA Capabilities
CORBA servers written in this traditional fashion are identical to everyday
CORBA servers, with a few exceptions:
The CORBA server doesn’t have a main method, since it’s started in the
HAHTsite application in the Session.onStart method.
You can use the HAHTsite IDE to build and publish the server.
Server control is handled via the HAHTsite Application Server
administration.
The CORBA server inherits automatic restart and failover capabilities
by running as part of the HAHTsite application.
Like most simple CORBA systems, many clients bind to a single server object.
Clients can be applets, CORBA client applications, or any CORBA-enabled
HAHTsite applications.
Example: Using CORBA to hold HAHTsite global state
A simple use for a CORBA server running in HAHTsite is the storage of
information to be shared between multiple invocations of the HAHTsite
application. Such a server might store long-term user information, or
cross-project data, acting as a “service object.” Here, both the CORBA server
and client are running as applications in the HAHTsite Application Server.
Because of CORBA, whether the client and server are located on the same
Application Server is not important. This client looks essentially like the one
in the previous example.
Here, the server simply acts as a time accumulator for storing numbers of
minutes on a per-customer basis. The IDL file is shown below.
319

Chapter 14: HAHTsite CORBA Capabilities
Java
module ServerStats {
interface TimeRecord {
void addMinutes(in string user, in long minutes);
void resetMinutes(in string user);
long getMinutes(in string user);
};
};
When you implement this interface in the server, you must follow certain
naming conventions and put your source files in the correct folder. First, create
a subfolder in the Packages folder and give it the name of your module. Then
put your source files in this subfolder, and give them names of the form
interfaceNameImpl.java. For example, the source code for the
TimeRecordImpl class should be placed in TimeRecordImpl.java.
The client code also looks similar that shown in the last example.
Java
public void onSessionStart(com.haht.project.SessionEvent anEvent)
{
// Initialize the ORB
org.omg.CORBA.ORB orb = org.omg.CORBA.ORB.init();
// Bind to the Superglobal time record
ServerStats.TimeRecord record =
ServerStats.TimeRecord.bind(orb, "Example2");
// Get the number of minutes of usage for this user from the
// user
long minutes = record.getMinutes(user_id);
// Get the customer information from the Database
}
Put the CORBA server part in the application’s onSessionStart routine, and
create the new TimeRecord class that implements the IDL interface:
320

Java
Chapter 14: HAHTsite CORBA Capabilities
public void onSessionStart(com.haht.project.SessionEvent anEvent)
{
orb = org.omg.CORBA.ORB.init();
boa = orb.BOA_init();
timeRecord = new TimeRecordImpl("Example2");
boa.obj_is_ready(timeRecord);
}
To start this CORBA server, you should configure the Applications Server to
run the CORBA server as a service when a particular Server Group is started.
For information on performing this configuration, see Chapter 3 in the
HAHTsite Application Server Administration Guide.
Note - You should not run the CORBA server and a HAHTsite
application that is a client of that server in the same server
process. A simple way to prevent this from happening is to
establish a Server Group dedicated running to CORBA-server
services.
One other point. By default, a CORBA service can time out. You can prevent
this from happening by setting the server’s timeout value to -1.
CORBA and the HAHTsite Server Object
Model
In addition to the simple CORBA clients and server discussed so far, it’s
possible to create CORBA servers that provide clients with access to HAHTsite
Server Object Model objects and clients that take advantage of those services.
The following subsections discuss this type of client and server further.
Using the HAHTsite Server Object Model in a HAHTsite
CORBA server
“HAHTsite as a traditional CORBA server” on page 318 discussed one type of
CORBA server. A second type of CORBA server may be written by using the
capabilities of the HAHTsite session. Such a “session-oriented” CORBA server
differs from the type described earlier in that it is initiated as part of a
321

Chapter 14: HAHTsite CORBA Capabilities
HAHTsite session. Since each session has its own private set of objects, each
CORBA server created in this manner has an independent set of objects as well.
A CORBA server constructed in this fashion may be started in two ways. The
initial HTTP reference to a page representing this session will cause the session
to be invoked via the standard hsrun mechanism. The second method allows
a CORBA client to initiate the session through use of a predefined
ServerGroup object.
You must include an IDL file describing the CORBA interface for each Java
class you wish to expose via CORBA. If the session is to be accessible from
CORBA, the project property must be set to indicate that the Session object is
to be exposed as a CORBA object whenever a session of the application is
initiated.
When a method in a Java class in a HAHTsite application is invoked via
CORBA, it is not running a HAHTsite dynamic page, and therefore does not
have access to the HAHTsite Page, Request, and Response objects. However, it
could have access to the Application and Session objects if they were passed
to the object as arguments of a method.
The methods of the Session class shown below enable you to register a server
object as a visible CORBA object and to deactivate a CORBA object.
Method Description
Corba_obj_is_ready Call this instead of obj_is_ready on the BOA,
and the session will manage the object,
deactivating it when the session is done. It
makes calls to initialize the ORB and BOA the
first time it is called within an application.
Corba_deactivate_obj This method removes the object from control of
the session.
Accessing the HAHTsite Server Object Model from a
CORBA client
A CORBA client of any type can reference the HAHTsite Application, Session,
and ServerGroup classes of a HAHTsite CORBA server as CORBA objects. The
set of methods available to perform on these objects from a CORBA
application is defined in terms of CORBA IDL. It can be compiled into
applications in any CORBA-supported language.
The IDL describing the methods and classes available to CORBA programs
resides in the file IDEInstallDir\scripts\HSCorbaInterface.idl.
322

HSCorbaInterface.idl
module com
{
module haht
{
module corba
{
interface Application
{
string getName();
void writeLog (
in string aMessage);
Object getCORBAObject(
in string varName);
string getString(
in string varName);
void putString(
in string varName,
in string varValue);
void remove(
in string varName);
void lock();
void unlock();
};
interface Session
{
string getStateId();
string getServerGroupName();
string getHostName();
string createPageURL(
in string aURL,
in string aSubSiteName);
string createMapURL(
in string aURL,
in string aSubSiteName);
string createFileURL(
in string aURL,
in string aSubSiteName);
Chapter 14: HAHTsite CORBA Capabilities
323

Chapter 14: HAHTsite CORBA Capabilities
HSCorbaInterface.idl
};
324
};
};
};
string createStaticURL(
in string aURL,
in string aSubSiteName);
string getURL(
in string projectId,
in string defaultStr,
in string queryStr);
string getStaticURL();
boolean hasPrivilege(
in string aPrivilege);
Object getCORBAObject(
in string varName);
string getString(
in string varName);
void putString(
in string varName,
in string varValue);
void remove(
in string varName);
void lock();
void unlock();
void setUsername(
in string aUsername);
string getUsername();
void keepAlive();
void setTimeout(
in long Timeout);
long getTimeout();
Application getCORBAApplication();
interface ServerGroup
{
Session createApplicationSession(in string
ApplicationPath);
};

Chapter 14: HAHTsite CORBA Capabilities
These interfaces contain a subset of the methods available in the analogous
classes in the Server Object Model. The behavior of the methods described in
the interfaces is identical to their counterparts in the com.haht.project
package.
Client/server communication
The com.haht.project.Session and com.haht.project.Application classes
define a few additional CORBA-related methods. These methods facilitate
client/server communication.
Method Description
getCORBAApplication returns the Application object that has been
exposed to CORBA. This convenience function
allows a CORBA client to get a reference to the
Application object from the Session
reference.
getCORBAObject returns a handle to a CORBA object. Can be
called in the client to obtain a reference to a
CORBA server object (posted with the put
command) without having to bind the object in
the server.
put posts an arbitrary Java object (in this case, a
CORBA object) associated with a name. This
object can be retrieved from the client side.
putString posts a Java String associated with a name
getString returns a string posted with the putString
command
By using these interfaces, CORBA applications can pass CORBA objects
between the client and server without having to contact the Naming Service
or SmartAgent. CORBA must be enabled in the project for these routines to
work properly.
Example: Using CORBA in a session initiated via HTTP
CORBA can be used as a convenient way to set up a non-HTTP connection
between the Web client and the Application Server. See the figure below.
325

Chapter 14: HAHTsite CORBA Capabilities
Once the HAHTsite application is initiated, a Java applet on the dynamic page
can be connected back to the Session object via CORBA by performing the
following steps:
1 The dynamic HTML page should use the Session.getStateId method to
obtain the session’s State ID.
2 JavaScript on the page can pass the state ID as an argument to a method of
an applet on the page.
3 The applet can make the CORBA calls to initialize the ORB and bind to the
Session object on the server. This returns an object reference to the
application’s session object.
The code for the applet method would look something like:
Java
public void connectToSession(String StateId) {
// Initialize the ORB
org.omg.CORBA.ORB orb = org.omg.CORBA.ORB.init(this, null);
// Bind to the Session
Session session =
com.haht.corba.SessionHelper.bind(orb,StateId);
// Retrieve a CORBA object for use in the applet
MyCorbaObject my_corba_object =
(MyCorbaObject)session.getCorbaObject("my_corba_object");
// Get another object using the bind() technique
MyOtherCorbaObject my_other_corba_object =
MyOtherCorbaObjectHelper.bind
(orb,"my_other_corba_object");
...
326

Chapter 14: HAHTsite CORBA Capabilities
Example: Initiating a HAHTsite application session with
CORBA
A HAHTsite application session can also be initiated by a CORBA client. See the
figure below.
In order to accomplish this, the client must follow the steps:
1 Initialize the CORBA ORB and bind to the ServerGroup object. This
requires you to know the name of the ServerGroup object. Usually, the
name is generated during the HAHTsite installation process. It should be
available from the HAHTsite system administrator.
2 Invoke the createApplicationSession method on the ServerGroup
object. This starts a session of the specified application and returns a
CORBA reference to the new application Session object.
The code for such a CORBA client might contain something like:
327

Chapter 14: HAHTsite CORBA Capabilities
Java
public void createSession() {
// Initialize the ORB
org.omg. CORBA.ORB orb = org.omg.CORBA.ORB.init(args, null);
// Bind to the HAHTsite ServerGroup object
com.haht.corba.ServerGroup servergroup =
com.haht.corba.ServerGroupHelper.bind(orb, "webapps");
// Create the appliation session and get a reference to it
Project1.HAHTSession session =
servergroup.createApplicationSession
("Project1/Project1.html");
...
}
328
Note - In order for this method to work, the HAHTsite system
administrator must enable application sessions to be started
using CORBA. By default, this capability is disabled,
preventing a session from being initiated.
Other Information
This section presents some miscellaneous information about HAHTsite’s
CORBA capabilities. It discusses:
using the VisiBroker ORB with other ORBs
using CORBA in HAHTtalk Basic projects
installing and configuring VisiBroker
VisiBroker’s SmartAgent and the CORBA Naming Service
VisiBroker’s GateKeeper software
Interoperability with other ORBS
HAHTsite applications built using VisiBroker can connect to and exchange
data with applications built using any CORBA 2.0 ORB. The communication
protocol used to connect the ORBS (Internet Inter-Object Protocol - IIOP) is
standardized and allows interworking between different vendors’ ORBs. The
VisiBroker IDL compiler idl2java must be run with the -strict

Chapter 14: HAHTsite CORBA Capabilities
command-line option in order to generate stubs that will work with other
ORBs.
Using CORBA with HAHTtalk Basic
Although CORBA services are not directly available from HAHTtalk BASIC, it
is still possible to link with CORBA-enabled systems from these applications.
Using the CreateJavaObject call in HAHTtalk, you can create a Java class that
can in turn make CORBA calls exactly as described above. Using this
technique, it is possible to make CORBA clients and servers in HAHTtalk Basic
applications.
VisiBroker installation and configuration
The setup for the Application Server allows you to install VisiBroker for Java as
a custom installation option.
In order for HAHTsite applications to act as CORBA clients, VisiBroker for Java
must be installed on the Background Host. In a distributed configuration, it
must be installed on each Background Host, although the osagent (if used)
need only run on one Background Host. If HAHTsite applications are to be
started as CORBA servers by external CORBA clients, VisiBroker for Java must
also be installed on each of the Foreground Hosts.
By default, the VisiBroker runtime .jar files are included on the System Java
Classpath for the Server Group. They are required for CORBA operation and
should not be removed from the classpath.
VisiBroker SmartAgent and the CORBA Naming Service
The VisiBroker for Java software includes the Inprise implementation of the
standard CORBA Naming Service. It also includes a simple object registry
called osagent or SmartAgent. Licenses for both are included with HAHTsite.
The HAHTsite Application Server allows the use of either Naming Service or
SmartAgent, but the HAHTsite Server Object Model objects such as
Application and Session are only available to the programmer through the
SmartAgent.
VisiBroker GateKeeper
The Java “sandbox” security model allows an unsigned Java applet to connect
only to the server from which it was invoked. The VisiBroker GateKeeper
software permits applets to connect to other servers. If your HAHTsite system
is configured with separate Foreground and Background Hosts, you will need
329

Chapter 14: HAHTsite CORBA Capabilities
to employ the VisiBroker GateKeeper to allow CORBA connection between
CORBA-enabled applets and the HAHTsite servers. This is true even if no
firewall exists between the applets and application. The VisiBroker GateKeeper
software and license are included with HAHTsite.
References
These two documents are available with the VisiBroker software and are also
available for download from the Inprise Web page:
330
VisiBroker for Java Programmer’s Guide
VisiBroker for Java Reference Manual

Debugging
Server-side Code
15
Introduction..................................................................................................332
Requirements for debugging ........................................................................332
Starting a debugging session ........................................................................333
To start a debugging session....................................................................333
To begin debugging at a static page........................................................334
To stop a debugging session....................................................................335
Debugging a code page.................................................................................336
Executing code in the debugger..............................................................336
Single-stepping.........................................................................................337
Procedure-stepping ..................................................................................338
Using breakpoints....................................................................................338
The debug windows......................................................................................340
Debug output panel.................................................................................341
Variable window ......................................................................................341
Watch window.........................................................................................343
Call Stack window ...................................................................................344
Threads window ......................................................................................345
331

Chapter 15: Debugging Server-side Code
Introduction
This chapter explains how to use the IDE/IP debugger to find errors in
HAHTsite server-side code. Debugging of both Java and HAHTtalk Basic
projects is supported. In addition to debugging locally, in the development
environment, HAHTsite supports remote debugging of dynamic Web pages,
allowing you to debug dynamically created Web pages in the deployed
environment.
Requirements for debugging
You can debug a project’s dynamic code pages (server-side code) running in
the HAHTsite Application Server from any Internet-connected client, using
the IDE/IP. Projects can also be debugged locally in the Application Server:
Developer Edition. The following requirements must be met:
332
The pages to be debugged must have been published.
The Application Server (or the Application Server: Developer Edition)
must be running.
The Application Server must have at least one debug process enabled.
In the Application Server, accounts and privileges must be set up to
permit debugging and to control the number of active debug sessions
allowed. You must have an account and debugging privileges on the
server machine to start a debug session. When you are debugging using
the Application Server: Developer Edition, account privileges are not
required.
For information on enabling debug processes and administering accounts
and privileges, refer to the HAHTsite Application Server Administration Guide,
Chapter 3, “Performing Administrative Tasks.”
Java projects must have been built in debug mode.
Note - Debugging is not supported for server-side Java code in
a HAHTtalk Basic project. The debugger treats invocations of
Java methods as a single HAHTtalk Basic statement.

Chapter 15: Debugging Server-side Code
A special case: debugging HAHTtalk Basic stand-alone
programs
A HAHTtalk Basic code page with a main subroutine can be debugged without
being published. This type of code page does not represent a dynamic HTML
page, but is a stand-alone program.
Starting a debugging session
Debugging sessions may be run against a local site, using the Application
Server: Developer Edition during project development. Debugging sessions
may also be run against a remote site, using the Application Server. This
configuration allows debugging in a deployment situation.
To start a debugging session
1 Open the project that you want to debug.
2 Select Project > Debug From Site, or select the Start button from the
Code and Scripts Tools toolbar. The Debug From Site dialog appears.
333

Chapter 15: Debugging Server-side Code
3 Enter your user name, domain and password. If the Application Server is
installed on a UNIX system, leave the domain field blank. If “Allow
Anonymous Debug” is set on the Application Server, or you are using the
Application Server: Developer Edition, you can leave all three fields blank.
The Application Server: Developer Edition does not support
authentication.
4 Specify an unused IP port on your system. The debugger uses two
consecutive ports (7000 and 7001 are the defaults.) If you are accessing the
Application Server through a firewall, be sure to specify a port that is
configured to route back to your system.
5 Select the page to use as a starting point for the debug session. You can
select any page in the project.
6 Click OK.
334
As the IDE establishes a connection with the server, status messages are
displayed in the Output window.
To begin debugging at a static page
1 If you select a static page as the start page, the browser displays a page that
prompts you to start the debugging process. The URL of the page indicates
the page is being run by a debug process of the Application Server.

Chapter 15: Debugging Server-side Code
2 Click the link labeled Click Here to Debug to start the debugging session.
Clicking on this link notifies the Application Server to start the debugger
when a dynamic page is executed.
The static page selected as the starting point for the debug session will be
displayed in the browser.
3 Navigate through the Web site to the dynamic page that you want to
debug.
When a dynamic page is requested by the browser, the execution of the
Application Server program is paused immediately before the first
statement of the code page.
To stop a debugging session
While in a debug session, click the End button on the Code and
Scripts Tools toolbar.
Tip - If the End button is activated, you are in a debug session.
If the End button is not activated, you are not in a debug
session. When the buttons to single-step and procedure-step
are active, you are in a debugging session and program
execution is paused. If you are in a debug session and the
single-step and procedure-step buttons are not activated, the
program is running.
335

Chapter 15: Debugging Server-side Code
Debugging a code page
The Server-side Code view of the HTML editor displays the code used to
generate the HTML page. In a debugging session, you can run the application
until a breakpoint is encountered as well as step through the code as it is
executed. When you step through a code page, the HTML editor displays a
yellow arrow to the left of the next line of code that will be executed.The
debugger allows you to step through code pages using single-step, using
procedure-step and by setting breakpoints.
The debug commands are available in the Debug menu on the main toolbar.
The Debug menu is visible only when the HTML editor is in the Server-side
Code view, when you’re viewing a code page, and when a debug session is
active. Each of the commands in the Debug menu is also represented by a
button on the Code and Scripts Tools toolbar. .
Executing code in the debugger
When a debugging session is started, (see “Starting a debugging session” on
page 333) the execution of the Application Server program is paused
immediately before the first statement of the code page of the first dynamic
page is executed. The Debug > Start command will cause the application to
continue executing statements until one of the following conditions occurs:
336
a statement having a breakpoint is encountered,
the code page is completed and sent to the browser, or
a run-time error in the code is encountered.
If the page is completed, the page will be visible in the browser. The debugging
session will be continued when another dynamic page is requested by the

Chapter 15: Debugging Server-side Code
browser. If any of the other conditions occur, the application execution pauses
and the debug windows will contain updated information about the state of
the application.
Note - The debugger will not automatically pause the
application at the beginning of each dynamic page it
encounters. Only the first dynamic page encountered in the
session will be paused, and only for the first time through that
page. To cause the debugger to pause the application at the
beginning of a dynamic page, set a breakpoint at the
beginning of that page.
To start code execution
While in a debug session, click the Start button on the Code and
Script Tools toolbar.
Single-stepping
Single-stepping is the process of executing one statement at a time. You can
see the effect of each statement by looking at the browser window, the Serverside
Code window, and the Variable, Watch, Call Stack and Threads windows.
When a method or subroutine is encountered in a statement, the single-step
command steps into the method or subroutine, following the execution path
of the program.
Note - The debugger does not step into code whose source
code is not part of the published project. For instance, the
source code for the Application Server and language libraries
are not accessible by the debugger.
To single-step through code
While in a debug session, click the Single-step button on the Code and
Script Tools toolbar.
To step out of a method or subroutine
1 In the Call Stack window, double-click on the previous call level. This will
be the line immediately below the top line.
2 Set a breakpoint on the statement following the current statement in the
calling method or subroutine, as indicated by a yellow arrow.
3 Click the Start button.
The program execution will continue through the method or subroutine
and stop at the statement after the method or subroutine has returned.
337

Chapter 15: Debugging Server-side Code
Procedure-stepping
Procedure-stepping is like single-stepping, except that you step over methods
or subroutines. The Procedure-step command executes a statement containing
a method or subroutine as a unit, then steps to the next statement in the
current method or subroutine.
To use procedure-stepping
338
While in a debug session, click the Procedure-step button on the Code
and Script Tools toolbar.
Using breakpoints
Breakpoints pause an application before the line of code that the breakpoint is
set on is executed. Variables and the call stack can be examined when the
application is paused. Threads can also be monitored in Java projects. After
pausing at a breakpoint, you can continue program execution by clicking on
the start button, or you can step through and monitor critical sections of the
code.
When you are in a debugging session, you can set or remove breakpoints on
any published dynamic page or code page in the project. Breakpoints can be
set when the execution is paused in a dynamic page or when the Application
Server is waiting for browser input between dynamic pages.
When you are not in a debugging session, you can set or remove breakpoints
at any location in the server-side code. Breakpoints which are set while not in
a debugging session will not take effect in the next debugging session. Pages
do not need to be re-published for breakpoints to take effect.
Breakpoints are stored in the project and are remembered between IDE/IP
sessions.
To set or remove breakpoints
1 In the Server-side Code view of the HTML editor, position the cursor on a
statement to set or remove a breakpoint.
2 From the main toolbar, select Debug > Toggle Break Point, or click the
Toggle Breakpoint button on the Code toolbar.
When a line has a breakpoint, a red circle is displayed next to the line.
The following example shows a subroutine that has one breakpoint, indicated
by a (red) circle to the left of the statement. The (yellow) arrow indicates the
next line of code to be executed.

Chapter 15: Debugging Server-side Code
Once breakpoints are set in the code, select Debug > Start, or click the Start
button on the Code and Scripts toolbar to cause the program to continue
execution until it reaches a statement containing a breakpoint.
Note - In a debugging session, you can edit the source code
using the Server-side Code view of the HTML editor, and save
your changes. You must stop the current debug session, then
build and publish the pages containing the changes before
your edits will take effect.
As a convenient way to manage multiple breakpoints, the Breakpoint Manager
allows you to remove selected breakpoints, and remove, enable and disable all
breakpoints in a single operation.
To use the Breakpoint Manager
From the main toolbar, select Edit > Breakpoints... The Breakpoint
Manager dialog appears.
339

Chapter 15: Debugging Server-side Code
The Breakpoint Manager dialog displays a list of all breakpoints in the
project.Check marks in the checkboxes next to the breakpoints indicate
enabled breakpoints.
.
Button Action
Remove Removes the breakpoints that have been selected. Selected
breakpoints are highlighted.
RemoveAll Removes all breakpoints.
EnableAll Turns all breakpoints on. Check marks in the checkboxes
indicate enabled breakpoints.
DisableAll Turns all breakpoints off. The breakpoints will still exist, but will
not cause the program to pause at that point.
340
Shortcut - You can also remove all breakpoints by selecting
Debug > Clear All Break Points from the main toolbar.
The debug windows
When the Application Server encounters a dynamic page during a debug
session, the HTML editor switches to the Server-side Code view and displays
the code for that page.
Several other windows provide debug information and control during a debug
session.
Output window, Debug panel
Variable window
Watch window
Threads window
The visibility of these windows is controlled through the View menu on the
main tool bar during the debug session. If the windows are visible, the IDE/IP
switches to the Debug panel of the Output window and opens the Watch, Call
Stack, Variable and Threads windows. The Threads window is only used in
debugging Java projects. These windows are updated each time the program
execution is paused.

Debug output panel
Chapter 15: Debugging Server-side Code
The Debug panel of the Output window displays a trace of the server requests
and responses during the debug session. Click on the plus signs (+) to expand
the messages. Information displayed for each HTTP request includes the
environment variable settings and the HTTP response stream created for the
page. This window is updated each time the program is paused after hitting a
breakpoint.
Note - Informational messages from the debugger are sent to
the Output panel of this window during the debug session.
Variable window
The Locals panel of the Variables window displays all local variables and their
values. This window is updated each time the program execution is paused at
a breakpoint. The values of these variables can be modified at runtime by
changing the data in the value field of this variable. Variable arrays, structures
and Java objects in this window can be expanded by clicking on the (+) next
to the name. Individual values of the fields can be viewed and/or modified.
341

Chapter 15: Debugging Server-side Code
In Java projects, this panel of the Variable window is used to display the class
instance that contains the current statement. When you’re debugging Java
projects, the Variable window shows the superclass hierarchy of all objects and
displays the member variables for the class and the superclasses. The values in
the panel can be modified in the same manner as the local variables.
342
Note - The value of certain variables, such as pointers, cannot
be modified.
To modify a local variable
1 Click on a variable name in the Locals panel of the Variable window. The
Modify Variable dialog appears.
2 Type the new value of the variable in the Value field.
3 Optionally, you can check the box labeled Add to watch window. If this
option is selected, the variable will be added to the list of watched
variables in the watch window.

4 Click the OK button.
Chapter 15: Debugging Server-side Code
Shortcut - Variable values can also be changed by simply
clicking on the value in the Variable window and typing in the
new value.
Watch window
The Watch window allows you to select variables that you want to monitor
during a debug session. The Watch window displays the name and value of all
of the variables you are currently watching. In HAHTtalk Basic projects, the
watch window displays the value of the variable’s scope. The value of watched
variables can also be changed from the watch window (see “To modify a local
variable” on page 342.)
To add a watch variable
1 From the main toolbar, select Debug > Add Watch, or click the Add Watch
button on the Code and Scripts Tools toolbar. The Add Watch dialog
appears.
2 Type the name of the variable into the Variable Name field.
Shortcut - You can drag-and-drop variables into the watch
window from the Server-side Code view of the HTML editor.
343

Chapter 15: Debugging Server-side Code
In addition, you can substitute a different variable in the watch list by
selecting Debug > Edit Watch, and you can change the value of a watched
variable by selecting Debug > Modify Watch.
To remove a watched variable
344
Select the variable from the list in the Watch window and press Delete.
In Basic projects, the Watch window has a context field. The context field
controls the context or scope used to determine the value of the variable. The
‘any’ context in the Basic project watches follows the Basic scoping rules.
Selecting another context displays variables using that context.
Watches on Java variables always follow the scoping rules of Java.
Watches remain set between debugging sessions, but do not persist across
invocations of the IDE/IP.
Call Stack window
The Call Stack window is used to trace the execution of a page as it enters and
returns from methods or subroutines. The Call Stack window displays a list of
all of the methods or subroutines that the application has entered but not
returned to the invoking method or subroutine. The window displays the
earliest active subroutine at the bottom of the list and adds subsequent calls to
the top of the list. You can double-click any entry in the Call Stack window to
change the context of the other windows to the display values at that call
level. The selected call level is indicated in the Call Stack window by a yellow
triangle.
The variables in the Watch and Variable window reflect their state at the
selected call level. The Server-side Code editor marks the corresponding
execution point at the selected call level with a yellow arrow.
Shortcut - To make the Call Stack Window visible, click the
Call Stack button .

Threads window
Chapter 15: Debugging Server-side Code
The Threads window is only used when debugging a Java project. When a
HAHTsite Basic project is being debugged, this window is not available. When
a program is paused, the Threads window contains the list of active threads,
their names, and the class and method the thread is in at the current execution
point. The Threads window controls display context like the Call Stack
window. When you click on a thread, the Server-side Code window displays
the source code for the location in that thread. All windows are updated to
contain information in the context of the call stack for the selected thread. If
you click on a thread that has no available source code to display, the Thread
window indicates that the current line number is zero and all the windows are
updated, except for the code window.
345

Chapter 15: Debugging Server-side Code
346

HAHTsite 3.x WebApp
Methods and
Properties
A
Introduction..................................................................................................348
WebApp properties .......................................................................................348
WebApp methods .........................................................................................350
Pseudo-methods.......................................................................................352
347

Appendix A: HAHTsite 3.x WebApp Methods and Properties
Introduction
This appendix lists the WebApp properties and methods (from HAHTsite 3.x)
and their equivalent functionality in the HAHTsite Server Object Model. The
WebApp properties and methods are still supported for legacy code and can be
intermixed with Server Object Model classes and methods. However, for new
projects it is highly recommended that you use only the HAHTsite Server
Object Model.
WebApp properties
This table lists the WebApp properties from HAHTsite 3.x and the equivalent
methods in the HAHTsite Server Object Model.
WebApp Server Object Model
Property Definition Class Method
DirName The directory
containing the
HAHTtalk Basic
executable program.
The ‘root’ of this path
is the configured
application root
directory, so this path
does not typically
represent a real
operating system path.
DynamicURL The URL of the Web
server’s CGI-BIN
directory.
HAHTMapPrefix The URL prefix-string
for references to
dynamic image maps
on the default subsite.
HAHTPagePrefix The URL prefix-string
for references to
dynamic pages on the
default subsite.
348
Application getDirName
Application getAppData (index,
"DynamicURL")
Session createMapURL("")
Session createPageURL
(pagename,
subsitename)

Hostname The hostname of the
current machine
HTXName The simple name
(without a suffix) of
the executable file.
InHeaders Whether or not the
page being generated
is still in the HTTP
headers section.
NewApp Whether or not this is
a new instance of the
application.
PageName The entry-point name
of the currently
executing dynamic
page.
Appendix A: HAHTsite 3.x WebApp Methods and Properties
WebApp Server Object Model
Property Definition Class Method
PathName The combination of
DirName and
HTXName.
ServerName The name of the
server group serving
the application.
Session getHostName
Application getName
Response inHeaders
Session isNewApp
Page getName
Application getPathName
Session getServerGroupName
StateId The StateId value. Session getStateId
StaticROOT Operating systemdependent
path to the
Web server’s staticpage
directory on the
default subsite.
StaticURL URL to the Web
server’s static-page
directory on the
default subsite.
Timeout The application
timeout value in
seconds.
Application getStaticRoot
and
getAppData(index,
"StaticROOT")
Session getStaticURL
and
getAppData(index,
"StaticURL")
Session getTimeout
349

Appendix A: HAHTsite 3.x WebApp Methods and Properties
WebApp methods
This table lists the methods of the WebApp object and the corresponding
method in the HAHTsite Server Object Model.
.
WebApp Server Object Model
Property Definition Class Method
UserROOT Operating-system
dependent path to the
Web server’s initial
working directory on
the default subsite.
UsingCookies Whether or not the
application was
published to place the
StateId into cookies.
350
Application getUserRoot
and
getAppData(index,
"UserROOT")
Application isUsingCookies
WebApp Server Object Model
Method Definition Class Method
EndHeaders Writes the End-of-
Headers mark and sets
InHeaders to False.
Environ$ Returns the value of an
environment variable.
GetAppData Returns information
about the application.
GetMapPrefix$ Returns the URL for an
image map
GetPagePrefix$ Returns the URL for a
dynamic page
GetStaticURL$ Returns the URL of the
Web server’s static-page
directory
GetSubSiteCount Returns the number of
subsites defined for the
application.
Response endHeaders
Request getServerVariable
Application getAppData
Session createMapURL
Session createPageURL
Session createStaticURL
Application getSubSiteCount

Appendix A: HAHTsite 3.x WebApp Methods and Properties
WebApp Server Object Model
Method Definition Class Method
GetSubSite$ Returns the name of
the subsite associated
with the value of the
(zero-based) Index
argument.
GetURL$ Locates a project item
by its unique ProjectID
and returns a string
with either a full or
relative URL for that
item.
HeaderField Writes the string as a
partial header line.
HeaderLine Writes the string as a
complete header line,
supplying the
terminating
pair.
HeaderMark Writes the
line mark after a series
of HeaderField calls.
URLAttachment$ Returns the name of
the temporary file used
for the attachment
associated with the URL
field name String.
URLAttachmentCount Returns the total
number of attachments.
URLAttachmentExists Returns True or False,
indicating whether an
attachment exists for
the URL field name
String.
URLAttachmentType$ Returns the Content-
Type of the attachment
associated with the URL
field name "String."
Application getSubSite
Session getURL
n.a.
Response addHeaderLine
n.a.
Request getURLAttachment
Request getURLAttachmentCount
Request getURLAttachmentExist
s
Request getURLAttachmentType
351

Appendix A: HAHTsite 3.x WebApp Methods and Properties
URLField$ Returns the value of a
field on the URL or in a
form.
Pseudo-methods
Pseudo-methods are place-holders that you can override with a function or
subroutine. This table summarizes the WebApp pseudo-methods and lists the
corresponding methods in HAHTsite’s Server Object Model. If a project calls
both the "old" Webapp pseudo-method and the new Server Object Model
pseudo-method, the newer method will run first. (Note that these pseudomethods
apply only to HAHTtalk projects. Java projects should use the
Session class’s onStart and onEnd methods.)
HahtSessionOnStart should be declared as a function returning a boolean
value (for success or failure). HahtSessionOnEnd should be declared as a
subroutine. Neither routine takes any arguments.
352
WebApp Server Object Model
Method Definition Class Method
URLFieldCount Returns the total
number of URL fields.
URLFieldExists Tests whether the
named field is in the
URL.
WhoAmI$ Returns the name of
the current page or
HAHTtalk Basic
subroutine.
WhoCalledMe$ Returns the name of
the page or HAHTtalk
Basic subroutine that
called the object on
which the method is
located (“me").
WriteLog Writes a string to the
Application Server’s log
file.
Request getURLField
Request getURLFieldCount
Request getURLFieldExists
Session whoAmI
Session whoCalledMe
Application writeLog

Appendix A: HAHTsite 3.x WebApp Methods and Properties
WebApp WebApp Server Object Model
Pseudo-method Definition Pseudo-method
Initiate
(WebApp_Initiate)
TimeUp
(WebApp_TimeUp)
Terminate
(WebApp_Terminate)
The session was just
initiated.
The Timeout value has
elapsed.
The session is about to
be terminated.
HahtSessionOnStart
No equivalent. Do not use.
HahtSessionOnEnd
353

Appendix A: HAHTsite 3.x WebApp Methods and Properties
354

HAHTsite 3.x Data
Management
B
Introduction..................................................................................................356
DataSets and data agents..............................................................................356
Accessing and changing DataSet properties at runtime.........................356
DataSet control functions........................................................................357
Writing user-defined DataSet functions..................................................358
Accessing and changing form-control properties at runtime .....................358
Connection-manager functions ...................................................................359
355

Appendix B: HAHTsite 3.x Data Management
Introduction
This appendix summarizes the ways in which programming database
applications differs between HAHTsite 3.x and HAHTsite 4.0. In general, the
objects with which you interacted in HAHTsite 3.x—DataSets, form controls,
and the connection manager—are now represented by classes in the Server
Object Model (or by ActiveX Data Object classes). The correspondence
between a 3.x object and a Server Object Model object is not always
one-to-one, and the 4.0 methods may behave differently than their 3.x
counterparts. Note, too, that the HAHTsite 4.0 release offers much greater
functionality than is represented in this appendix.
The 3.x properties and functions will continue to be supported in legacy
projects, but any new projects should be developed using the Server Object
Model. You can mix both models within the same project, but not on the same
page.
DataSets and data agents
DataSets in HAHTsite 3.x have been replaced by data agents. These objects are
similar; however, data agents are only responsible for populating form fields
on a page with data read from an ADO recordset. Separate command handlers
perform the actions associated with form buttons.
The sections below explain how the DataSet programming tasks covered in the
3.x documentation are handled in HAHTsite 4.0.
Accessing and changing DataSet properties at runtime
HAHTsite 3.x maintained several DataSet record structures — DataSet_Widget,
DataSet_RecordSet, and DataSet_BoundWidget — and enabled you to set
properties of these structures. These record structures are not used in HAHTsite
4.0. The table below guides you to the Server Object Model classes that contain
data similar to that stored in the 3.x record structures.
Record structure Server Object Model classes
DataSet_Widget
The properties of this structure enabled
you set such attributes as the DataSet’s
name, filter, and default action.
356
DataAgent
This class has member variables that
give you access to similar data.

DataSet_RecordSet
The DynaSet property enabled you to
read or write the name of the DataSet’s
dynaset.
DataSet_BoundWidget
The properties of this structure enabled
you to read or change attributes of
form controls bound to the DataSet.
DataSet control functions
Appendix B: HAHTsite 3.x Data Management
Record structure Server Object Model classes
DataAgent
You can get or set a data agent’s
recordset using the methods
getRecordset and setRecordset.
(To work with a recordset, you use
methods of the ADO Recordset class.)
FormField and its subclasses
In HAHTsite 4.0, form fields are
represented by subclasses of the SOM
class FormField. You set form-field
attributes using methods of these
subclasses. (Note that some of the
bound-widget properties you could
read or set in 3.x are no longer
applicable.)
HAHTsite 3.x provided a small set of DataSet-control functions. These
functions and their 4.0 counterparts are listed in the table below.
DataSet-control function Server Object Model classes
DataSet_GetBoundWidgetIndex This function does not have a
counterpart in 4.0.
DataSet_GetBoundWidgetValue Subclasses of FormField
You get the value of a form field using
the method getValue, which is
inherited from FormField.
DataSet_SetBoundWidgetValue Subclasses of FormField
You set the value of a form field using
the method setValue.
DataSet_Close DataAgent
The close method closes all of a data
agent’s open resources.
357

Appendix B: HAHTsite 3.x Data Management
Writing user-defined DataSet functions
In HAHTsite 3.x, DataSets perform standard HAHTsite database actions (such
as Insert) on behalf of a form button, and you have the option of overriding a
standard event. In HAHTsite 4.0, the actions are performed by command
handlers that are generated by HAHTsite. You have the option of modifying
these command handlers by adding event handlers to the generated code.
Accessing and changing form-control
properties at runtime
In HAHTsite 3.x, you could read and set properties of the following form
controls:
358
Text boxes
Text areas
Check boxes
Radio buttons
Combo boxes
List boxes
Static text
HAHTsite maintained a set of record structures for each form control —
ControlName_Widget, ControlName_BoundWidget, ControlName_ExtAttr, and
in some cases ControlName_List — and you changed a form control’s
attributes using properties of these structures. In HAHTsite 4.0, form fields are
represented by Server Object Model classes, and you modify the attributes of
a form field using get and set methods.
The table below shows the correspondence between the types of form fields
and the relevant Server Object Model classes.
Note - The FormField class is relevant in each case because
FormField is the superclass of all the specific form-field classes,
and all of these classes inherit methods from FormField.
Form control Server Object Model class
Text box Textbox

Form control Server Object Model class
Text area TextArea
Check box Checkbox
Radio button Radiobutton
Combo box Combobox
List box Listbox
Static text StaticText
Appendix B: HAHTsite 3.x Data Management
The Server Object Model also includes classes for form buttons (Button) and
File Upload fields (FileUpload).
Connection-manager functions
HAHTsite 3.x provided a set of functions for working with the Connection
Manager. In HAHTsite 4.0, the counterpart of the Connection Manager is an
instance of the Server Object Model’s DMConnectionManager class. The table
maps the 3.x open- and close-connection functions to the appropriate
methods of the DMConnectionManager class.
Connection Manager functions DMConnectionManager methods
GetConnection getSharedConnectionByID
getSharedConnectionByName
openConnection
openPrivateConnectionByID
openPrivateConnectionByName
CloseConnection closeAllConnections
closePrivateConnection
359

Appendix B: HAHTsite 3.x Data Management
360

Code Examples
C
Calling a subroutine as a form action .........................................................362
Modifying a command handler ...................................................................370
Writing a custom authentication class ........................................................373
361

Appendix C: Code Examples
Calling a subroutine as a form action
“Calling a subroutine from a form” on page 134 explains how to have your
application invoke a Java method or HAHTtalk Basic subroutine when a form
is submitted. The example presented in that section assumes that the user of
the application enters the path to an image in a file-upload field. Then, when
the form is submitted, a subroutine reads the filename from a URL and writes
the contents of the file to a field in a database.
The subroutine is shown below in both its Java and HAHTtalk Basic flavors.
Java
package FileUploadJava;
import com.haht.*;
import com.haht.project.*;
import com.haht.ado.Abstract.*;
import java.io.*;
class StuffAPictureInAccess extends Object
implements HAHTPage
{
static final int BUFSIZE = 1024;
362
public void run (Request aRequest, Response aResponse)
{
// For success, failure
HsMessage_Page myMsgPage = new HsMessage_Page();
// Check to see if they've sent the data
//
if (aRequest.getURLFieldExists("txtName")
&& aRequest.getURLAttachmentExists("uplPicture"))
{
// Get shared connection, open NameAndPict table
// to get recordset
Connection myConn;
try
{

Java
Appendix C: Code Examples
myConn = Haht.getSession().getConnectionManager().
getSharedConnectionByName("NameAndPict");
}
catch (com.haht.HahtException e)
{
myMsgPage.setErrorMessage
("Unable to open connection: " +
e.toString());
myMsgPage.run (aRequest, aResponse);
return;
}
Recordset myRS =
new com.haht.ado.Recordset();
if (myRS == null)
{
myMsgPage.setErrorMessage
("Unable to create recordset");
myMsgPage.run (aRequest, aResponse);
return;
}
myRS.setActiveConnection(myConn);
// So we can Insert/Update/Delete
myRS.setCursorType
(com.haht.ado.CursorTypeEnum.adOpenKeyset);
myRS.setLockType
(com.haht.ado.LockTypeEnum.adLockOptimistic);
try
{
myRS.open("NameAndPict");
}
catch (java.lang.Exception e)
{
myMsgPage.setErrorMessage
("Opening NameAndPict table failed");
myMsgPage.run (aRequest, aResponse);
return;
}
363

Appendix C: Code Examples
Java
364
// Get filename of uploaded image, open it, and
// prepare to appendChunk it into the recordset
// field.
java.io.File pictureFile = new java.io.File
(Haht.getApplication().getUserRoot() +
'/' + aRequest.getURLAttachment("uplPicture"));
FileInputStream pictureStream;
Field pictureFld;
try
{
pictureStream = new FileInputStream
(pictureFile);
}
catch (java.io.FileNotFoundException e)
{
myMsgPage.setErrorMessage
("Unable to open uploaded file");
myRS.close();
myMsgPage.run (aRequest, aResponse);
return;
}
// Add new record to recordset to put picture in,
// assign name to it, and get picture field to
// append data to.
myRS.addNew ();
myRS.getField("Name").setString
(aRequest.getURLField("txtName"));
pictureFld = myRS.getField("Picture");
// Allocate a buffer and read until we're done
//
byte [] pictureBuf = new byte[BUFSIZE];
int nBytesRead;
int nBytesTotal = 0;

Java
Appendix C: Code Examples
do
{
try
{
nBytesRead = pictureStream.read(pictureBuf);
nBytesTotal += nBytesRead;
if (nBytesRead > 0)
{
pictureFld.appendChunk
(pictureBuf, nBytesRead);
}
}
catch (java.io.IOException e)
{
myMsgPage.setErrorMessage
("Error while reading file");
myRS.close();
myMsgPage.run (aRequest, aResponse);
try
{
pictureStream.close();
}
catch (java.io.IOException e2)
{
}
return;
}
}
while (nBytesRead > 0);
// Finish inserting the record by updating the
// recordset
myRS.update();
365

Appendix C: Code Examples
Java
}
366
}
// Close up shop, call Results page
try
{
pictureStream.close();
}
catch (java.io.IOException e)
{
}
myRS.close();
myMsgPage.setMessage ("Copied " +
String.valueOf(nBytesTotal) +
" bytes to record for " +
aRequest.getURLField("txtName"));
myMsgPage.run (aRequest, aResponse);
}
else
{
myMsgPage.setErrorMessage
("Picture name or file missing");
myMsgPage.run (aRequest, aResponse);
}

HAHTtalk Basic
#include
#include
Const BLKSIZE = 1024
Appendix C: Code Examples
Public Sub StuffAPictureInAccess
Dim myConnMgr As Object, mySession As Object
Dim sPictureFileName As String
Dim aRequest As Object
Dim pictureFld As ADODB.Field, nameFld As ADODB.Field
Dim fRead As Long
Dim fLen As Long
Dim nBlkSize As Long, nBytesTotal As Long
Dim sBuf As String
Dim nullObj As Object
Dim myRS As New ADODB.Recordset
Dim myConn As ADODB.Connection
'
' Check to see if they've sent the data
'
Set aRequest = Haht.getRequest()
Set nullObj = Nothing
If (aRequest.getURLFieldExists("txtName") _
And aRequest.getURLAttachmentExists("uplPicture")) Then
'
' Get shared connection, open NameAndPict table to
' get recordset
'
Set myConn = getSharedConnectionByName _
("NameAndPicture")
set myRS.ActiveConnection = myConn
myRS.CursorType = adOpenKeyset
myRS.LockType = adLockOptimistic
myRS.open "NameAndPict"
367

Appendix C: Code Examples
HAHTtalk Basic
368
'
' Get filename of uploaded image, open file, and prepare
' to appendChunk image into the recordset field
'
sPictureFileName = HahtApplication.getUserRoot() & "/" & _
& aRequest.getURLAttachment("uplPicture")
Set pictureFld = myRS.Fields("Picture")
Set nameFld = myRS.Fields("Name")
fRead = FreeFile()
Open sPictureFileName for Binary Access Read As #fRead
'
' Add new record to Recordset to put picture in, add
' data to it
'
myRS.addNew
nameFld.Value = aRequest.getURLField("txtName")
fLen = FileLen(sPictureFileName)
nBlkSize = IIF(fLen < BLKSIZE, fLen, BLKSIZE)
sBuf = String$(nBlkSize, 0)
nBytesTotal = 0
While fLen > 0
Get #fRead,,sBuf
nBytesTotal = nBytesTotal + nBlkSize
pictureFld.AppendChunk sBuf
fLen = fLen - nBlkSize
If ( fLen < nBlkSize ) AND ( fLen > 0 ) Then
nBlkSize = fLen
sBuf = String$(nBlkSize,0)
End If
Wend
'
' Close file, continue
'
Close #fRead
myRS.update

HAHTtalk Basic
Appendix C: Code Examples
'
' Close up shop, call Results page
'
myRS.close
Set myRS = Nothing
Set myConn = Nothing
Set myConnMgr = Nothing
gMessageText = "Copied " & CStr(nBytesTotal) & _
" to record for " & aRequest.getURLField("txtName")
Set aRequest = Nothing
goto StuffAPictureInAccess_Exit
Else
gMessageText ="Picture name or file missing"
goto StuffAPictureInAccess_Exit
End If
StuffAPictureInAccess_Exit:
HS_Message_Page
Exit Sub
StuffAPictureInAccess_Errors:
' Dump any errors we want to here
gMessageText = "Error " & Str$(Err) & " - " & Error & _
" occurred processing picture"
Resume StuffAPictureInAccess_Exit
End Sub
369

Appendix C: Code Examples
Modifying a command handler
This section presents an example of how you might customize a command
handler’s prebind method. Suppose that you have a form that contains a File
Upload form field. When a user runs your application, he or she will enter the
path to an image file in the File Upload text field. When the user clicks the
Insert button, you want to take this pathname, open the image file, and write
the contents of the file to a BLOB field in your database. (The record
containing the image will also contain a picture name that you can use to
identify the image.)
Since HAHTsite doesn’t generate code for inserting a large binary object into a
database, you must add code similar to the following to a command handler
to insert this object in your database.
HAHTtalk Basic
370
'
' Get the filename of an uploaded image, open the file,
' and copy its contents into a record field that holds
' binary data.
'
Dim aRequest As Object
Dim sPictureFileName As String
Dim pictureFld As Object, nameFld As Object
Dim fRead As Long
Dim fLen As Long
Dim nBlkSize As Long
Dim sBuf As String
On Error GoTo onBind_ErrorHandler
Set aRequest = Haht.getRequest()
sPictureFileName = HahtApplication.getUserRoot() & "/" _
& aRequest.getURLAttachment("upload1")

HAHTtalk Basic
Appendix C: Code Examples
'
' The command handler has already added a new record to
' the recordset, so we can get references to the Name
' and Picture fields in that record. Write the name
' me to the Name field.
'
Set pictureFld = daNameAndPict.getRecordset(). _
getField("Picture")
Set nameFld = daNameAndPict.getRecordset().getField("Name")
nameFld.setString aRequest.getURLField("txtName")
'
' Open the image file, read chunks of data into a buffer,
' and copy the data to the record's Picture field.
'
fRead = FreeFile()
Open sPictureFileName for Binary Access Read As #fRead
fLen = FileLen(sPictureFileName)
nBlkSize = IIF(fLen < BLKSIZE, fLen, BLKSIZE)
sBuf = String$(nBlkSize, 0)
While fLen > 0
Get #fRead,,sBuf
pictureFld.AppendChunk sBuf
fLen = fLen - nBlkSize
If ( fLen < nBlkSize ) AND ( fLen > 0 ) Then
nBlkSize = fLen
sBuf = String$(nBlkSize, 0)
End If
Wend
'
' Close the file.
'
Close #fRead
onBind_ExitHandler:
Exit Sub
371

Appendix C: Code Examples
HAHTtalk Basic
onbind_ErrorHandler:
'
' Dump any errors we want to here
'
aHandlerInfo.setProceedAction _
DMConstants_PROCEED_DO_FAILURE_PAGE
Resume onBind_ExitHandler
372

Appendix C: Code Examples
Writing a custom authentication class
This section presents the implementation of a Java class that authenticates
users against information stored in an Access database. The table used for
authentication contains two columns: UserName and Password.
Java
import com.haht.ado.Abstract.*;
import com.haht.access.*;
public class CustomAuthentication implements Authentication
{
public boolean authorizeUser(String aUserName,
String aPassword, String aDomain)
{
Connection conn = new com.haht.ado.Connection();
Recordset rs = new com.haht.ado.Recordset();
// Open a connection to the database.
try
{
conn.open("Provider=HSODBC;DSN=Authentication;" +
"DBQ=C:\\Stan\\Authentication.mdb;" +
"DriverId=25;FIL=MS Access;MaxBufferSize=512;" +
"PageTimeout=5;");
}
catch(java.lang.Exception e) {}
// Get the record containing the user name and password.
rs.setActiveConnection(conn);
String commandText = "SELECT Password FROM Authentication"
+ " WHERE UserName = '" + aUserName + "'";
try
{
rs.open(commandText);
}
catch (java.lang.Exception e) {}
373

Appendix C: Code Examples
Java
}
374
}
// Determine whether user should be authenticated.
if (!(rs.getBOF() == true && rs.getEOF() == true))
{
Field fld = rs.getField("Password");
if (fld.getString().equals(aPassword))
{
rs.close();
conn.close();
return true;
}
rs.close();
conn.close();
return false;
}
rs.close();
conn.close();
return false;

ADO Primer
D
What’s in this appendix ...............................................................................376
Connections..................................................................................................376
Opening a connection.............................................................................376
Executing a command against a connection .........................................378
Closing a connection...............................................................................379
Recordsets......................................................................................................380
Creating a recordset.................................................................................380
Iterating through the records in a recordset ..........................................381
Finding a specific record in a recordset ..................................................382
Reading a record ......................................................................................382
Updating a record....................................................................................383
Inserting a record.....................................................................................383
Deleting a record .....................................................................................384
Closing a recordset ..................................................................................385
375

Appendix D: ADO Primer
What’s in this appendix
This appendix provides a very brief introduction to ADO programming by
presenting short examples of how to perform common ADO operations in
HAHTsite applications. For example, the appendix illustrates how to:
376
open a connection
create a recordset
add a record to a recordset
Each example is shown using both Java and HAHTtalk Basic syntax.
A note for Java programmers: The Java ADO classes you use are not in the
package com.ms.wfc.data (as they would be in a Microsoft ADO program), but
are in the package com.haht.ado or com.haht.ado.Abstract. You use the
abstract classes in com.haht.ado.Abstract when you declare a variable that
will hold a reference to an ADO object. And you use the classes in
com.haht.ado — or in a package of user-defined ADO classes — when you
instantiate an ADO object. Generally, HAHTsite Java projects import
com.haht.ado.Abstract.* and fully qualify the names of classes in the
package com.haht.ado or in a user-defined package.
Connections
An ADO Connection object represents a connection to a data source — usually
a relational database. For information on how to perform common operations
using a Connection object, see the following sections:
“Opening a connection” on page 376
“Executing a command against a connection” on page 378
“Closing a connection” on page 379
Opening a connection
In a HAHTsite project, you can open a connection in one of two ways:
by calling a Connection object’s open method
by calling a Java method or HAHTtalk Basic function that returns a
Connection.
Both ways of opening a connection are illustrated below.

Using an ADO method
Appendix D: ADO Primer
The code below shows how to open a connection by instantiating a
Connection object and calling that object’s open method. This open method is
an overloaded method and may take zero or more of the following parameters:
Parameter Data type Description
A connection string String A data source name or a connection
string containing a series of name/value
pairs.
A user name String The user name to be used for a database
login.
A password String The corresponding password.
These examples use a connection string that specifies a provider and a data
source.
Java
import com.haht.ado.Abstract.*;
...
myConn = new com.haht.ado.Connection();
myConn.open("provider=hsodbc;dsn=Employees");
HAHTtalk Basic
Dim myConn As new ADODB.Connection
myConn.open "provider=hsodbc;dsn=Employees"
Note that the Java example creates a connection object of type
com.haht.ado.Connection and that the HAHTtalk Basic example creates one
of type ADODB.Connection.
Using a HAHTsite method or function
HAHTsite includes a set of Java methods and HAHTtalk Basic functions that
you can use to open, or get a reference to, a connection. For detailed
information about these methods and functions, see Chapter 9,
“Programming with the Connection Manager.”
The Java methods are methods of the DMConnectionManager class:
377

Appendix D: ADO Primer
378
getSharedConnectionByID
getSharedConnectionByName
openPrivateConnectionByID
openPrivateConnectionByName
There are four HAHTtalk Basic functions of the same names. The Java methods
return objects of type com.haht.ado.Connection, and the HAHTtalk Basic
functions return objects of type ADODB.Connection.
Calling a method or function that creates a private connection is comparable
to calling a Connection object’s open method. A new connection is created.
The shared-connection methods and functions enable you to create a
connection that can be used on a number of pages in an application. You can
also share such a connection with HAHTsite data agents.
The following examples get a reference to a shared connection by calling
getSharedConnectionByName. The one argument to this method/function is
the name of an ADO connection that you’ve created using the IDE.
Java
import com.haht.*;
import com.haht.ado.Abstract.*;
...
Connection myconn;
try
{
myConn = Haht.getSession().getConnectionManager().
getSharedConnectionByName("EmployeesConn");
}
catch(HahtException e) {}
HAHTtalk Basic
Dim myConn As ADODB.Connection
Set myConn = getSharedConnectionByName("EmployeesConn")
Executing a command against a connection
Once you’ve opened a connection (or obtained a reference to an open
connection), you can execute a command against that connection using the
Connection object’s execute or executeUpdate (Java only) method. The first
— and sometimes only — argument to this method is a string representing the

Appendix D: ADO Primer
command to execute against the connection. This command can be a SQL
statement, the name of a table, or the name of a stored procedure.
In the example below, the command is a SQL statement that inserts a record
into a database table.
Java
String insertCmd;
int recordsAffected;
...
insertCmd =
"INSERT INTO NAMES (FirstName, LastName)
VALUES ('Jane', 'Doe')";
recordsAffected = myConn.executeUpdate(insertCmd);
HAHTtalk Basic
Dim myRS As ADODB.Recordset
Dim insertCmd As String
...
insertCmd = _
"INSERT INTO NAMES (FirstName, LastName) VALUES ('Jane', 'Doe')"
Set myRS = myConn.execute(insertCmd)
Closing a connection
A connection is closed automatically when the object representing it goes out
of scope; however, it’s a good idea to close connections explicitly. You close a
connection using the Connection object’s close method.
Java
myConn.close();
myConn = null;
HAHTtalk Basic
myConn.close
Set myConn = Nothing
379

Appendix D: ADO Primer
Recordsets
The ADO Recordset object is a container for a group of records returned as the
result of a query. For information about common actions performed against
recordsets, see the following sections:
380
“Creating a recordset” on page 380
“Iterating through the records in a recordset” on page 381
“Finding a specific record in a recordset” on page 382
“Reading a record” on page 382
“Updating a record” on page 383
“Inserting a record” on page 383
“Deleting a record” on page 384
“Closing a recordset” on page 385
Creating a recordset
You can create a recordset in a number of ways. For example, both the
Connection and Command objects have execute methods that can return a
recordset. The example below, however, creates a recordset containing data by
instantiating a Recordset object and calling that object’s open method. The
first argument to this method specifies the source of the data; in this case, the
data will be read from a database table called Names. This first argument can
be a SQL statement, a table name, or the name of a stored procedure. The
second argument is the name of a previously established Connection.
Notice that the Java code returns an object of type com.haht.ado.Recordset,
while the HAHTtalk Basic code returns an object of type ADODB.Recordset.
Java
import com.haht.ado.Abstract.*;
...
Recordset myRS = new com.haht.ado.Recordset();
...
myRS.open("SELECT * FROM Names", myConn);

HAHTtalk Basic
Dim myRS As New ADODB.Recordset
...
myRS.open "SELECT * FROM Names", myConn
Iterating through the records in a recordset
Appendix D: ADO Primer
Once you’ve created a recordset, you’ll need to be able to navigate it. One
common requirement is to be able to look at each record in order. The
following examples show you how to do this (assuming you opened your
recordset using the default cursor type, forward-only).
When you open the recordset (using the default cursor type), the current
record is the first record in the recordset. The while statement checks to make
sure that the current record pointer is not pointing beyond the last record in
the recordset. As long as this condition is true, you want to process the record
and then move to the next record.
Java
while (!myRS.getEOF())
{
...
myRS.moveNext();
}
HAHTtalk Basic
while (not myRS.EOF)
...
myRS.moveNext
wend
Note - If you opened your recordset using a cursor type other
than the default — that is, using a static cursor or a dynamic
cursor — you should call the recordset’s moveFirst method to
move the current record pointer to the first record of the
recordset before you begin iterating through the records.
381

Appendix D: ADO Primer
Finding a specific record in a recordset
In addition to iterating through the records in a recordset, you’ll often want
to find a particular record in a recordset. You can find a record that meets a
specific criterion using the Recordset’s find method. This method takes three
arguments. The first is a string that specifies the criterion that must be met.
This criterion has the form fieldName operator value. The second argument
is a Boolean value indicating whether the find operation should skip the
current record. The third argument is a constant that dictates the direction of
the search: forward or backward.
Java
myRS.find("FirstName = 'Jane'", 0,
AdoEnums.SearchDirection.FORWARD);
HAHTtalk Basic
myRS.find "FirstName = 'Jane'", 0, adSearchForward
Reading a record
Each record in a recordset has associated with it a Fields collection, which
contains the individual fields that make up the record. You read a record by
making it the current record and then reading the individual fields in the
record. You can access a field either by its name or by its position in the record.
Java
String firstName;
String lastName;
...
firstName = myRS.getField("FirstName").getString();
lastName = myRS.getField("LastName").getString();
382

HAHTtalk Basic
Dim firstName As String
Dim lastName As String
...
firstName = myRS.Fields(0)
lastName = myRS.Fields(1)
Updating a record
Appendix D: ADO Primer
To update a record, you write data to one or more of the record’s fields and
then call the Recordset’s update method. If you forget to update the record
before you move the recordset’s record pointer, your changes will be lost.
Java
myRS.open("SELECT * FROM Names", myConn,
AdoEnums.CursorType.KEYSET, AdoEnums.LockType.OPTIMISTIC);
...
myRS.getField("LastName").setString("Smith");
myRS.update();
HAHTtalk Basic
myRS.open "SELECT * FROM Names", myConn, adOpenKeyset, _
adLockOptimistic
...
myRS.Fields("LastName") = "Smith"
myRS.Update
Inserting a record
To insert a new record in a recordset, you perform the following steps:
1 Add a new record to the recordset by calling the Recordset’s addNew
method.
2 Write data to the new record.
3 Update the recordset.
383

Appendix D: ADO Primer
Java
myRS.open("SELECT * FROM Names", myConn,
AdoEnums.CursorType.KEYSET, AdoEnums.LockType.OPTIMISTIC);
myRS.addNew();
myRS.getField("FirstName").setString("John");
myRS.getField("LastName").setString("Smith");
myRS.update();
HAHTtalk Basic
myRS.open "SELECT * FROM Names", myConn, adOpenKeyset, _
adLockOptimistic
myRS.AddNew
myRS.Fields("FirstName") = "John"
myRS.Fields("LastName") = "Smith"
myRS.Update
Deleting a record
Deleting a record is simple. You just position the current record pointer
appropriately and call the Recordset’s delete method.
Java
myRS.open("SELECT * FROM Names", myConn,
AdoEnums.CursorType.KEYSET, AdoEnums.LockType.OPTIMISTIC);
myRS.find("FirstName = 'Jane'", 0,
AdoEnums.SearchDirection.FORWARD);
myRS.delete();
HAHTtalk Basic
myRS.open "SELECT * FROM Names", myConn, adOpenKeyset, _
adLockOptimistic
myRS.find "FirstName = 'Jane'", 0, adSearchForward
myRS.Delete
384

Closing a recordset
A recordset is closed if:
Appendix D: ADO Primer
you allow the variable being used to address it to go out of scope
you call the Recordset’s close method
The examples below illustrate how to call the close method.
Java
myRS.close();
myRS = null;
HAHTtalk Basic
myRS.Close
Set myRS = Nothing
385

Appendix D: ADO Primer
386

ADO Extensions
E
What’s in this appendix ...............................................................................388
Extensions to the Java interface...................................................................388
ADO tracing in Java projects...................................................................388
Additional appendChunk methods ........................................................390
The Variant data type ..............................................................................390
Extensions to the HAHTtalk Basic interface ................................................391
ADO tracing in HAHTtalk Basic projects................................................391
Functions for managing connections .....................................................391
387

Appendix E: ADO Extensions
What’s in this appendix
HAHTsite’s ADO interface matches the Microsoft interface almost exactly.
However, a few extensions have been introduced to make debugging ADO
code easier, to make sure that Java and HAHTtalk Basic projects have the same
capabilities, and just to make programming easier.
This appendix contains two mains sections: one on extensions to the Java
interface and one on extensions to the Basic interface. See the appropriate
subsection below:
388
“Extensions to the Java interface” on page 388
“Extensions to the HAHTtalk Basic interface” on page 391
Extensions to the Java interface
The main extensions to the Java interface are the addition of an ADO tracing
facility, additional appendChunk methods, and the definition of a HAHTsite
Variant class.
For information on these extensions, see the sections listed below:
“ADO tracing in Java projects” on page 388
“Additional appendChunk methods” on page 390
“The Variant data type” on page 390
ADO tracing in Java projects
To help you debug your ADO code, HAHTsite adds an ADO-tracing feature. If
you turn tracing on in your program, information about ADO operations is
written to a log file. A sample trace file is shown below.

ADO tracing in a Java project
Appendix E: ADO Extensions
[17:15:07.848, 00173, 00162] setTracing (1)
[17:15:07.858, 00173, 00162] com.haht.ado.Abstract.Connection
conn1
[17:15:07.858, 00173, 00162] conn1 = new com.haht.ado.Connection
()
[17:15:07.858, 00173, 00162] conn1.setProvider ("HSODBC")
[17:15:07.858, 00173, 00162] conn1.open ("Provider=HSODBC;
DSN=Employees;DBQ=C:\Stan\Employees.mdb;DriverId=25;FIL=MS
Access;MaxBufferSize=512;PageTimeout=5;")
[17:15:08.369, 00173, 00162] rs2.open ("SELECT * FROM Names",
conn1, CursorTypeEnum.adOpenKeyset, LockTypeEnum.adLock
Optimistic)
[17:15:08.399, 00173, 00162] rs2.find ("FirstName = 'Jane'", 0,
SearchDirectionEnum.adSearchForward)
[17:15:08.429, 00173, 00162] rs2.update ()
This trace file is written to the root directory of the drive on which the
Application Server is installed (Windows NT) or /tmp (UNIX systems). The file
is given a name of the form trace_ado_stateID.log.
To turn ADO tracing on in a Java project
Call the static method com.haht.ado.Constants.setTracing.
The single argument to this method is a constant — or the bitwise OR of
two or more constants — that indicates the type of tracing you are
requesting. The constants you can use are listed in the table below.
Note - The constants are static variables of the Constants
class, so you should prepend com.haht.ado.Constants. to
each constant.
Constant Meaning
adGeneralTracing logs many (but not all) of the ADO calls and
their arguments. This type of tracing uses
relatively little overhead and should not affect
performance severely, unlike ODBC tracing.
adTimingTracing adds End trace entries so that you can see how
long some ADO calls took to complete
389

Appendix E: ADO Extensions
To turn ADO tracing off in a Java project
390
Constant Meaning
adColTimingTracing times calls to Field.finalize,
Field.getString, and Field.isNull
adGetValTracing traces getDataType operations for Field
objects
adSetValTracing traces setDataType operations for Field
objects
Call setTracing with an argument of 0.
Additional appendChunk methods
Four appendChunk methods have been added for writing binary or textual data
to fields and parameters.
Class Methods
Field public void appendChunk(byte[] bytes, int nBytes)
public void appendChunk(char[] chars, int nChars)
Parameter public void appendChunk(byte[] bytes, int nBytes)
public void appendChunk(char[] chars, int nChars)
Often the last chunk of data you need to append to a field or parameter does
not fill the byte or character array you’re using as a buffer. These methods let
you specify exactly how many bytes or characters you want to append with
your final call to appendChunk.
The Variant data type
HAHTsite ADO methods that take a Variant as an argument, or return a
Variant, use objects of the class com.haht.com.Variant, instead of
com.ms.com.Variant.

Appendix E: ADO Extensions
Extensions to the HAHTtalk Basic interface
The principal extensions to the HAHTtalk Basic interface are the addition of
an ADO-tracing feature and the inclusion of Basic functions/methods for
working with private and shared connections.
For further information on these subjects, see the sections listed below:
“ADO tracing in HAHTtalk Basic projects” on page 391
“Functions for managing connections” on page 391
ADO tracing in HAHTtalk Basic projects
The ADO-tracing feature discussed in “ADO tracing in Java projects” on page
388 is also available in HAHTtalk Basic projects. To turn tracing on, you call
the function setADOTracing, which requires one argument: a constant
indicating the type of tracing you’re requesting. The constants you can use are
the same as the constants you use in Java projects.
Note - The argument to setADOTracing can also be the bitwise
OR of two or more constants.
Functions for managing connections
In Java projects, you can use methods of the DMConnectionManager class to:
open a private connection
get a reference to a shared connection
close a private connection
These method return, or take as an argument, an object of type
com.haht.ado.Abstract.Connection. In HAHTtalk Basic projects, you’re
usually working with objects of type ADODB.Connection. HAHTsite provides
the following functions/methods to provide a comparable interface in
HAHTtalk Basic projects. The four functions listed below return an object of
type ADODB.Connection:
getSharedConnectionByID
getSharedConnectionByName
getPrivateConnectionByID
getPrivateConnectionByName
In addition, the class ADODB.Connection defines a closePrivateConnection
method that you can use to close private connections.
391

Appendix E: ADO Extensions
For further information about private and shared connections, see Chapter 9,
“Programming with the Connection Manager.”
392

Index
A
access control 270
enabling 272
access package (Java) 5
Active Server Pages 3
ActiveX Data Objects (ADO) 6
closing connections 379
closing recordsets 385
creating recordsets 380
deleting records 384
executing commands against
connections 378
finding records in recordsets 382
HAHTsite extensions to 387
inserting records 383
navigating recordsets 381
opening connections 376
primer 375
reading records 382
updating records 383
addPrivilege (Session class) 274
Application class 298
editing (Java projects) 25
application directories
for HAHTtalk Basic projects 70
for Java projects 39
Application object 97
method summary 102
retrieving properties 100
variables 98
application root directory 71
approot 40, 71
array datatypes 72
attachments
retrieving 122
authenticating users
using a Web server 288
using the Login widget 277
using the Server Object Model 286
authentication class
OSAuthentication 284
user-defined 285
Authentication interface 284, 285, 299
authorizeUser (Authentication
interface) 286
B
Breakpoint Manager 339
breakpoints 338
browser compatibility issues 249
built-in objects 90
getting references 91
Button class 165
button form fields 165
associating user code with 183
C
CAB files 28
Call Stack window 344
Cascading Style Sheets 252
check box form fields 167
Checkbox class 167
class declaration (Java projects) 19
class files 28
Client Scripts view 238, 240, 248
client-side scripts
See scripts
closePrivateConnection
(DMConnectionManager class) 232
code editor
HAHTtalk Basic projects 67
Java projects 37
code examples
calling a subroutine from a form 362
custom authentication class 373
modifying a command handler 370
code pages
adding to a project 60
saving
HAHTtalk Basic projects 61
COM objects
using with HAHTtalk Basic 305
combo box form fields 168
Combo class 168
command handlers 189
changing the flow of control in 225
customizing 216
examples of customized handlers 217
structure of 212
common files (Java) 27
393

Index
Common Object Request Broker
Architecture (CORBA) 9, 310
building clients 315
building servers 318
in HAHTtalk Basic projects 329
Naming Service 329
compiler
HAHTtalk Basic 69
finding compile-time errors 69
Java 38
debug option 39
finding compile-time errors 39
Connection class (ADO) 376
connections
closing 379
executing commands against 378
opening 230, 376
constructor (Java projects) 19
cookies
cookie collections 121, 128
multiple cookies with the same
name 122
retrieving cookie values 121
setting 127
corba package (Java) 5
createFileURL (Session class) 111
createMapURL (Session class) 111
createPageURL (Session class) 111
createStaticURL (Session class) 113
custom Form Handler widgets 145
creating 152
writing the form-handler
function 145
D
data agents 188
enabling tracing 210
filtering records 205
getting a reference to a data agent’s
connection 198
getting a reference to a data agent’s
recordset 200
getting parameters to stored
procedures 202
getting the values of data-agent
fields 196
handling errors 210
limiting the maximum number of
records 199
making a recordset read only 199
performing an action 192
394
refreshing data 203
setting a data agent’s command 190
setting the values of data-agent
fields 196
sorting records 204
data types
C/C++and HAHTtalk Basic 304
datamanager package (Java) 4
datatypes
arrays 72
scalars 72
debugger windows 340
Call Stack window 344
Output window, Debug tab 341
Threads window 345
Variable window 341
Watch window 343
debugging 10, 332
compiling with debug option 39
executing code 336
procedure stepping 338
requirements for 332
single stepping 337
starting a session 333
using breakpoints 338
directives, precompiler (HAHTtalk Basic
projects) 64
directories
static root 70
distributed-object applications 310
DLLs
datatype mapping 304
DMConnectionManager class 230
document object models 237, 250
browsing 241
Dynamic HTML 252
dynamic pages
calling from HAHTtalk Basic 65
calling from Java 30
E
enabling access control 272
endHeaders (Response class) 126
environment variables
retrieving 122
error handler
HAHTtalk Basic projects 60
event handling
in Java projects 31
exception handler
Java projects 23

exit handler
HAHTtalk Basic projects 59
expressions
HAHTtalk Basic 49
formatting 50
in dialog boxes 50
Java projects
formatting 15
in dialog boxes 15
F
File Upload class 168
File Upload form fields 140, 168
adding to a page 141
files
submitting with forms 140
form
method 117
form fields 163
buttons 165
check boxes 167
combo boxes 168
File Upload 140, 168
list boxes 169
radio buttons 175
setting properties of 156
text areas 178
text boxes 178
form handler
HAHTtalk Basic projects 56
Java projects 23
Form Handler widgets
custom 145
creating 152
writing the form-handler
function 145
form handlers 212
form package (Java) 4
FormField class 163
forms
calling subroutines from 134
submitting files with 140
G
GateKeeper 329
GET and POST methods 117
getAppData (Application class) 100
getBOF (Recordset class) 159
getCookie (Request class) 121
getDirName (Application class) 40, 71
Index
getEOF (Recordset class) 159
getError (DataAgent class) 210
getErrorCount (DataAgent class) 210
getRecordset (DataAgent class) 200
getServerVariable (Request class) 122
getServerVariableCount (Request
class) 122
getSharedConnectionByName
(DMConnectionManager class) 231
getStaticRoot (Application class) 40, 70
getStaticURL (Session class) 40, 70
getURL (Session class) 109
getURLAttachment (Request class) 144
getURLAttachmentCount (Request
class) 122
getURLAttachmentExists (Request
class) 122, 143
getURLAttachmentType (Request
class) 122
getURLField (Request class) 119
getURLFieldCount (Request class) 119
getURLFieldExists (Request class) 119
getUserRoot (Application class) 40, 71
getValue (FormField class) 182
getWriter (Response class) 129
Globals.hbs 63, 64
H
HahtApplication.java 25
HahtSession.java 25
HAHTsite Server Object Model, See
Server Object Model 89
HAHTtalk Basic 2
compared to Visual Basic 72
compiling 69
data types 72
editing code 67
error handling 73
file I/O 73
help for keywords 69
naming conventions 72
subroutines and functions 73
syntax checking 69
using COM objects 305
variable scope 72
HAHTtalk Basic projects
adding code pages to a project 60
and server-side code view 52
calling dynamic pages 65
calling external logic 47
code editor 67
395

Index
error handler 60
event handling 66
exit handler 59
generated code for a page 53
Globals.hbs 63
include files 53, 63
in-line code 48
naming conventions 62
page entry point 57
precompiler directives 64
server-side code 46
working with 46
headers
adding content information 127
testing for "in headers" 127
writing 126
hsSecurityPrivileges database table 290
HTML
writing 129
HTML Tags view 246
HtmlOut 260
HAHTtalk Basic example 262
HAHTtalk Basic include files 260
HAHTtalk Basic routines 261
Java class 264
Java example 265
HtmlWriter 129
I
IDL compiler 311
IDL files 311
import statements (Java projects) 19
include files
and HAHTtalk Basic projects 53
external includes (HAHTtalk Basic
projects) 63
in HAHTtalk Basic projects 63
project includes (HAHTtalk Basic
projects) 63
inHeaders (Response class) 127
in-line code
expressions
Java projects 14
in HAHTtalk Basic projects 48
statements
Java projects 15
insertElementAt (Listbox class) 172
Internet Explorer 249
isMultiple (Listbox class) 172
isNewApp (Session class) 113
396
J
JAR files 28
Java
class files 28
code editor 37
compiling 38
file types 27
files
adding to a project 26
JAR files 28
Java class directory 71
Java projects
application directories 39
event handling 31
exception handler 23
form handler 23
in-line code 13
naming conventions 30
page, generated code for 18
server-side code 12
server-side code view 17
writing HTML output 23
javaroot 71
JavaScript 237, 238, 249
L
layers (Netscape) 252
list box form fields 169
adding elements to a list 171
finding an item in a list 173
getting and setting properties 173
selecting an element in a list 172
list elements
creating 169
getting and setting properties 171
Listbox class 169
ListElement class 169
logging in to an application 276
Login widget 277, 279
lookupPrivileges (UserProfile
interface) 292
M
methods
calling from dialog boxes
Java projects 17
WebApp object 350

N
naming conventions
Java 30
Naming Service 329
Netscape Layers 252
Netscapte Navigator 249
O
onEnd (Application class) 31
onEnd (Session class) 31
onSessionEnd (Application class) 31
example 33
onSessionStart (Application class) 31
example 33
onStart (Application class) 31
onStart (Session class) 31
openPrivateConnectionByName
(DMConnectionManager class) 232
out.print statement 129
P
package statement (Java projects) 19
Packages folder (Java projects) 26
page
run method (Java projects) 20
page structure
HAHTtalk Basic projects 53
Java projects 20
performAction (DataAgent class) 193
precompiler directives (HAHTtalk Basic
projects) 64
print 129
printing
Java projects 23
private connections 230
closing 232
opening 232
privilege repository 289
privilege-lookup class
DBUserProfile 291
user-defined 292
privileges 270
adding to a project 272
assigning to a page 273
assigning to a session 273
granting to users who log in to an
application 276
looking up in a database 290
looking up in a nondatabase
repository 291
looking up using the Server Object
Model 293
required 270
session 270
Privileges class 5, 298
project package (Java) 3
pseudo methods, for WebApp
object 352
PUBLISH_OS 64
PUBLISH_SERVERGROUP 64
PUBLISH_SITENAME 64
PUBLISH_WEBSERVER 64
R
radio button form fields 175
Radiobutton class 175
Recordset class (ADO) 380
recordsets
closing 385
creating 380
deleting records 384
finding records in 382
getting references to 200
getting the values of fields in a
record 196, 382
inserting records 383
limiting the maximum number of
records 199
making read only 199
navigating 381
performing actions against 192
refreshing the data in 203
setting the values of fields in a
record 196
sorting records 204
updating records 383
referred projects 93
Request object 117
attachments 122
environment variables 122
field values, retrieving 117
method summary 123
references to
in HAHTtalk Basic projects 59
in Java projects 22
retrieving cookie values 121
required privileges 270
Response object 126
cookies 127
headers 126
method summary 130
Index
397

Index
references to
in HAHTtalk Basic projects 59
in Java projects 22
writing HTML output 129
Retrieving 117
run method (Java projects) 20
arguments 20
S
scalar datatypes 72
script functions 238, 244
scripts 8, 236
choosing a language 238
event handlers 238
in-line 238, 243
page-scope functions 238, 244
with server-side expressions 257
secure-static pages 270
security 270
Server Object Model 3, 89
Application object 97
built-in objects 90
Request object 117
Response object 126
Session object 107
server-side code view 52, 217
Java projects
17
server-side Java
called from HAHTtalk Basic 76
case sensitvity 80
CreateJavaObject function 77, 78
CreateTypedJavaNull function 78
differences between HAHTtalk Basic
and Java 79
GetJavaClass function 78
locating objects 80
mapping data types 83
mapping parameter types 81
runtime errors 84
Session class 297
editing (Java projects) 25
Session object 107
creating a static URL 113
creating a URL 109, 111
method summary 114
state 107
timeout 108
variables 107
session privileges 270
398
session state 107
session timeout 108
setAuthenticationClassByName
(Application class) 285
setCommand (DataAgent class) 190
setCommandType (DataAgent class) 191
setContentType (Response class) 127
setCookie (Response class) 127
setDisplayText (StaticText class) 176
setInitialAction (DataAgent class) 195
setLabel (FormField class) 160
setMaxRecords (DataAgent class) 199
setMultiple (Listbox class) 172
setPictureURL (Button class) 166
setPostSort (DataAgent class) 204
setPreFilter (DataAgent class) 208
setPreSort (DataAgent class) 204
setReadOnly (DataAgent class) 199
setStyle (Button class) 166
setTracing (DataAgent class) 211
setUserProfileClassByName (Application
class) 292
setValue (FormField class) 160, 182
setVisible (FormField class) 159
setWriter (Response class) 129
shared connections 230
opening or getting a reference to 231
SmartAgent 329
state 107
statements
HAHTtalk Basic 49
static root directory 40, 70
static URL 70
StaticText class 176
stored procedures
getting the values of output
parameters 202
subroutines
and dialog boxes 51
as form actions 134
T
text area form fields 178
text box form fields 178
TextArea class 178
Textbox class 178
Threads window 345
timeout 108
tracing, enabling 210

U
URL
creating 109, 111
user code
associating with a button 183
User Login Page template 278
UserProfile interface 292, 299
userroot 40, 71
V
Variable window 341
variables 107
and multiple processes 99
Application object 98
global (HAHTtalk Basic projects) 64
locking 99
VBScript 237, 238, 249
VisiBroker for Java 310
GateKeeper 329
installing 329
interoperability with other ORBs 328
SmartAgent 329
W
Watch window 343
watched variables
adding 343
removing 344
WebApp object
methods 350
pseudo methods 352
whoAmI (Session class) 114
whoCalledMe (Session class) 114
writeBinary (Response class) 129
Z
ZIP files 28
Index
399

Index
400